Export Monodoc XML to HTML with monodocs2html

monodocs2html looks like the old exporter but is actually a compatibility shim, so its own help text will send you chasing options that do nothing.

On this machine monodocs2html delegates to mdoc export-html. Allow about fifteen minutes for a first export.

1. Confirm the installed implementation

Check the command and package before relying on examples copied from an older Mono installation:

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

The local manual describes the historical interface, including -source:SOURCE_DIR and -dest:DEST_DIR. The installed wrapper translates those options to the newer mdoc export-html interface, so its -help output shows modern mdoc usage rather than the legacy option names.

2. Check the source tree

The source directory must be the base of a Monodoc documentation collection: an index.xml file, one XML file per namespace, and a directory per namespace containing the type XML files.

Inspect the tree without changing it. Replace the placeholder with the real path:

$ SOURCE_DIR='/path/to/monodoc-xml'
$ test -r "$SOURCE_DIR/index.xml" && echo 'index.xml: readable'
index.xml: readable
$ find "$SOURCE_DIR" -maxdepth 2 -type f -name '*.xml' -print | sort | head

An empty find result or a missing index is a source-layout problem, not a reason to add more exporter options. Stop and locate the directory that actually holds the collection root. If the files belong to another user or a package-managed location, ask for read access rather than making broad permission changes.

3. Export to a new destination

Choose a destination that does not contain an export you need to keep. The command creates HTML using the default html extension:

$ DEST_DIR="$PWD/monodoc-html"
$ test ! -e "$DEST_DIR" || { echo "Refusing existing destination: $DEST_DIR"; exit 1; }
$ monodocs2html -source:"$SOURCE_DIR" -dest:"$DEST_DIR"
$ find "$DEST_DIR" -type f -name '*.html' -print | head

The wrapper passes the source directory to mdoc export-html and maps the destination to --out. A non-zero exit status means the export was not a success, even if a few files appeared. Check the error, fix the source or destination, and use a fresh output directory for the next attempt.

Safety boundary: the example deliberately writes beside your working files. If you later export into a document root, a package-owned directory, or a live site, confirm the deployment procedure first. The exporter can replace files in an existing destination when source files are newer, and a web server may expose incomplete output while a batch is running.

4. Verify the generated files

Check that output exists, is non-empty, and has the extension you intended:

$ find "$DEST_DIR" -type f -name '*.html' -size +0c -print | head
$ test -s "$DEST_DIR/index.html" && echo 'index.html: non-empty'
index.html: non-empty

Open a representative file with a browser or check its first lines. Generated pages are documentation output, not a guarantee your site stylesheet matches the template, so look for the collection or page title and a link to the expected type or member before publishing the directory.

Tip: current mdoc export-html behaviour normally updates a generated file when its XML source is newer. The backend also has --force-update, but this legacy wrapper does not translate an equivalent option. If you need that, invoke mdoc export-html directly and test it in a separate destination first.

5. Change the file extension when needed

Pass -ext:EXTENSION if another extension is required by an existing documentation site:

$ ALT_DIR="$PWD/monodoc-xhtml"
$ monodocs2html -source:"$SOURCE_DIR" -dest:"$ALT_DIR" -ext:xhtml
$ find "$ALT_DIR" -type f -name '*.xhtml' -print | head

The extension value only names created files. It does not convert the document format by itself, and it does not update links in files already generated. Keep each extension in its own destination so an old HTML tree cannot be mistaken for the new export.

6. Inspect or supply an XSLT template

To see the built-in template, write it to a temporary file or standard output. This is read-only with respect to your source tree:

$ monodocs2html -dumptemplate > /tmp/monodocs2html-default.xsl
$ test -s /tmp/monodocs2html-default.xsl && echo 'template: non-empty'
template: non-empty

A custom template is an XSLT file passed with -template:FILE. The input page has fields such as CollectionTitle, PageTitle, Summary, Signature, Remarks, Members, and Copyright. The output also relies on CSS class names including PageTitle, MemberName, MembersListing, and TypesListing.

Copy the dumped template to a project-controlled file and make one small change first. Export to a new destination, then compare a representative page with the default export. Keep the original template until the new output has been checked: there is no automatic undo for files overwritten in a destination.

7. Recover from a failed or unwanted export

If an export failed in a newly created destination, leave the source tree alone and remove only that disposable destination, after checking its exact path:

$ test "$DEST_DIR" = "$PWD/monodoc-html" || exit 1
$ rm -rf -- "$DEST_DIR"
$ test ! -e "$DEST_DIR" && echo 'temporary export removed'

Warning: rm -rf is irreversible. Never run this recovery block against a source directory, a package directory, or a live document root. If you exported into a directory with files you value, restore it from backup or your deployment system instead of guessing which files belong to the exporter.

Done means