Monodoc internals and a little annoying fly

If anyone out there still does not know, Monodoc is the mono documentation system. It is the core that allows the mono documentation web and the mono documentation browser work. Well, it is also behind a handful of other nice tools like monodoc2html. Once the presentation are done let's move on...

Monodoc works with several different sources of documentation. It renders API documentation, but also C# compiler errors, the Ecma specification and, in the past, even the monkeyguide (which was obsolete and removed). The nice thing is that it keeps a uniform documentation tree no matter where the documentation comes from (API, man pages, error references, ...)

This tree is generated from a skeleton and feed with different documentation sources. This skeleton is defined in a file called monodoc.xml which is something like this:

<node label="Mono Documentation" name="root:">
    <node label="Class Library" name="classlib"/>
    <node label="Mono Libraries" name="classlib-mono"/>
... (more contents here)
    <node label="Various" name="various">
        <node label="DiaCanvas Libraries" name="classlib-diacanvas"/>
        <node label="NUnit Libraries" name="classlib-nunit"/>
        <node label="Tao" name="tao"/>
    </node>

</node>

Then, when monodoc starts, it looks for all the *.sources files it founds and feeds its contents to the nodes:



In the image above, the "Class Library" node is feed with the contents of netdocs.source, the "C# Compiler errors reference" with cs-errors.source and the "NUnit Libraries" with nothing, because that documentation is not currently installed on my system.

And that's it. That's how monodoc manages the documentation tree.

Well, there is this little annoying fly I'm sure everyone using monodoc has met at least once. What happens if you click on "NUnit Libraries" node which has no documentation:

---

Unhandled URL

Functionality to view the resource root:/classlib-nunit is not available on your system or has not yet been implemented.

---

That is the problem of having a static skeleton for documentation which is filled with the *.source files found. I know, the problem is not big, one possible solution is to purge those entries which does not have documentation (no *.source file was found), and that is exactly what is done as of r99894.