Validate Mono ECMA Documentation with mdvalidater

You will validate a directory of Mono ECMA documentation with the command installed on this machine, then switch the same check to mdoc without changing the documentation tree. 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

Checkpoint: if command -v prints nothing, stop and install or repair the MonoDoc package through your normal package-management process. Do not use sudo merely to validate documentation that your account can already read.

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 file path.

$ 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 the name of a package: confirm that 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

The command's useful result is its exit status. A status of 0 means this invocation completed successfully. A non-zero status means the validation did not complete successfully, so preserve the diagnostic text and inspect the path, provider and XML before changing anything. Output wording is version-specific and may be written to standard error.

Checkpoint: do not treat the existence of XML files as proof that they conform to the schema. The validation command must finish with a zero status against the actual tree you intend to ship.

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

Keep --format ecma in automation when the format is part of the contract. It makes a future review clearer and avoids relying on a default that may be unfamiliar to the person maintaining the script.

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.

6. Avoid the common command-line traps

• Do not omit ecma when using mdvalidater. It is the provider argument, not an optional label.
• Quote the documentation path. This prevents 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.