Export mdoc XML to Microsoft Documentation with mdoc-export-msxdoc

You will finish with a Microsoft XML Documentation file, the format produced by the C# compiler's /doc option, from one or more Mono mdoc documentation directories. This guide uses mdoc-export-msxdoc from monodoc-base version 6.8.0.105+dfsg-3.6ubuntu2, as installed on this machine.

Allow about fifteen minutes. You need a shell, the monodoc-base package, and a directory containing valid mdoc XML. The examples read documentation and write a new file in the current directory. They do not install anything, edit the source XML, or require elevated privileges.

1. Check the installed command

Confirm which executable will run and record the package version. These are ordinary, read-only commands:

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

Checkpoint: the command must be available and the package version should be recorded alongside generated documentation. Distribution updates can change diagnostics or the exact XML formatting, even when the documented options remain the same.

2. Check the input layout

The exporter expects a directory in the Mono documentation format, not a single type XML file. At its root, a normal input has index.xml, namespace files named ns-*.xml, and directories containing type files:

$ find /path/to/mdoc -maxdepth 2 -type f -print
/path/to/mdoc/index.xml
/path/to/mdoc/ns-Example.xml
/path/to/mdoc/Example/Widget.xml

index.xml records assemblies, namespaces and types. A type file contains the type metadata and its Docs elements. The exporter reads those files and turns documented types and members into Microsoft member identifiers such as T:Example.Widget and C:Example.Widget.

Do not point the command at a random directory containing unrelated XML. If the directory is missing index.xml, the command exits with status 1 and reports that it could not find that file. Fix the input path or generate the mdoc tree first; adding sudo will not repair an incomplete input.

3. Export to one named file

Use -o or --out with a destination path when a build or review step needs one predictable file:

$ mkdir -p /path/to/build
$ mdoc-export-msxdoc --out=/path/to/build/Example.xml /path/to/mdoc

The command's logging can vary by package version. The useful checks are the exit status and the existence of the output file:

$ test -s /path/to/build/Example.xml && echo 'export created a non-empty file'
export created a non-empty file
$ sed -n '1,24p' /path/to/build/Example.xml
<doc>
    <assembly>
        <name>Example</name>
    </assembly>
    <members>
        <member name="T:Example.Widget">

Because shell redirection and build scripts often replace files, choose a new destination while testing. The exporter does not provide an undo operation. If you deliberately need to replace an existing result, copy it to a dated backup first, then regenerate and compare the new file before removing the backup.

4. Send the result to standard output

Use -o - when another command should consume the XML, or when you want to inspect the conversion without creating a file:

$ mdoc-export-msxdoc -o - /path/to/mdoc > /tmp/Example.xml
$ test -s /tmp/Example.xml && echo 'standard-output export captured'
standard-output export captured

The hyphen is significant. It tells the exporter to write XML to standard output. The shell redirection creates or truncates /tmp/Example.xml before the exporter runs, so do not use a valuable existing path in a blind command. If the export fails, check the command status before treating the redirected file as usable:

$ mdoc-export-msxdoc -o - /path/to/mdoc > /tmp/Example.xml
$ status=$?
$ printf 'export status: %s\n' "$status"
export status: 0

5. Let the exporter create per-assembly files

Omit -o when the input contains assemblies that should become separate files. The command writes into the current working directory, using the values in //AssemblyInfo/AssemblyName from the documentation and also creating namespace summaries:

$ mkdir -p /path/to/exported
$ cd /path/to/exported
$ mdoc-export-msxdoc /path/to/mdoc-one /path/to/mdoc-two
Example.xml
Other.xml
NamespaceSummaries.xml
$ find . -maxdepth 1 -type f -printf '%f\n'
Example.xml
Other.xml
NamespaceSummaries.xml

This mode is convenient for a collection of assemblies, but the current directory matters. Make a dedicated output directory first so an export cannot mix with unrelated build artefacts. If two inputs produce the same assembly name, resolve that collision before exporting into a shared directory. A name collision can make it unclear which result is authoritative.

6. Inspect and diagnose the result

Microsoft XML Documentation normally has a doc root, an assembly name and a members collection. Inspect the structure with an XML-aware tool if one is installed, or use a small read-only check:

$ grep -E '<(doc|assembly|members|member)( |>)' /path/to/build/Example.xml
<doc>
    <assembly>
    <members>
        <member name="T:Example.Widget">
        <member name="C:Example.Widget">

An empty or missing member list usually means the input tree did not contain the documentation you expected, rather than that the exporter needs a special flag. Recheck index.xml, the namespace and type paths, and the Docs elements. If a source file is malformed, validate or repair the mdoc tree with the Mono documentation tools before exporting again.

The installed help also lists -q for reduced console logging. The installed manual documents -o, help options, and the positional directories, so keep automation based on the documented interface and treat logging as non-essential. The XML file and the process exit status are the reliable outputs to test.