Validate Mono ECMA Documentation with mdvalidater

This guide validates a directory of Mono ECMA documentation with the legacy mdvalidater command. It then shows the equivalent switch to mdoc, without touching the documentation tree at all. Allow about ten minutes if the documentation is already generated and you only need a validation pass. The examples read files and report validation status; they do not edit, load or publish documentation.

This guide covers the mdvalidater shipped by monodoc-base 6.8.0.105+dfsg-3.6ubuntu2. The local manual describes it as obsolete and points to mdoc-validate. That matters when writing new scripts: use the old command to support an existing workflow, but prefer the replacement for new work.

1. Check the installed command

First confirm which executable your shell will run and record the package version. These are ordinary, read-only commands and do not need elevated privileges:

$ command -v mdvalidater
/usr/bin/mdvalidater
$ dpkg-query -W -f='${Package} ${Version}\n' monodoc-base
monodoc-base 6.8.0.105+dfsg-3.6ubuntu2

2. Identify the documentation tree

mdvalidater takes a provider name followed by one or more paths. The only provider listed by its manual is ecma. The path can be a directory, which lets the validator inspect documentation below it recursively, or a single file.

$ DOCS='/path/to/ecma/docs'
$ test -d "$DOCS" && echo "documentation tree found"
documentation tree found
$ find "$DOCS" -type f -name '*.xml' | head

Replace /path/to/ecma/docs with the directory produced by your documentation workflow. Do not guess a directory from a package name: confirm it contains XML files and that your account can read them. The ECMA format includes the index.xml and namespace XML files generated by MonoDoc tools.

3. Run the legacy validation command

Pass the provider first, then the directory. This is an unprivileged check:

$ mdvalidater ecma "$DOCS"
$ status=$?
$ printf 'validator exit status: %s\n' "$status"
validator exit status: 0

• A status of 0 means this invocation completed successfully.
• A non-zero status means validation did not complete successfully: preserve the diagnostic text and inspect the path, provider and XML before changing anything. Output wording is version-specific and may go to standard error.

4. Use the replacement command for new scripts

The old executable is a compatibility wrapper. On this installation, /usr/bin/mdvalidater invokes mdoc validate --format and passes your provider and paths after it. The direct replacement is therefore:

$ mdoc validate --format ecma "$DOCS"
$ status=$?
$ printf 'validator exit status: %s\n' "$status"
validator exit status: 0

The installed mdoc-validate(1) manual also documents the shorter form, because its default format is ECMA:

$ mdoc validate "$DOCS"
$ printf 'validator exit status: %s\n' "$?"
validator exit status: 0

5. Keep validation separate from repair

Validation is a read-only inspection. It does not generate missing XML, repair malformed elements or change a MonoDoc output directory. If the check fails, keep the original tree and capture the complete command output:

$ mdoc validate --format ecma "$DOCS" >validation.out 2>&1
$ status=$?
$ sed -n '1,120p' validation.out
$ printf 'validator exit status: %s\n' "$status"
validator exit status: 1

The displayed status is an example of the failure path, not a promise about the exact number returned for every malformed document. If you later decide to regenerate the documentation, write it to a separate output directory first and rerun validation there. Do not overwrite the only copy of a documentation tree while investigating a schema error.

Common traps

• Do not omit ecma when using mdvalidater. It is the provider argument, not an optional label.
• Quote the documentation path. This stops spaces or shell metacharacters in a directory name from changing the command.
• Do not pass --help to mdvalidater as if it were a modern option. The wrapper expects a provider in that position, and the old tool is obsolete.
• Do not run the validator as root to hide a permissions problem. Fix ownership or read access deliberately, then rerun as the account that will consume the documentation.
• Do not confuse a zero status on an accidental empty or wrong path with proof that the intended documentation was checked. Verify the path and count its XML files before the validation step.