[Mono-docs-list] [mono-packagers] monodoc & mcs/mono module merging

[Jonathan Pryor]

On Sun, 2008-10-19 at 10:20 -0400, Jonathan Pryor wrote:
> > Apropros monodoc, in debian we are working on a better way (packaging
> > wise) to integrate documentation from non-Mono projects in monodoc:
> > http://wiki.debian.org/Teams/DebianMonoGroup/MonodocIntegration
> 
> Why not discuss this on mono-docs-list? :-)

Continuing with this logic...

I've done a little more thinking about this.

First thought: what do other documentation tools do?

Alas, I only know of devhelp (anyone know what the Qt equivalent is?).

What's devhelp do?

Documentation is in e.g. /usr/share/gtk-doc, and each directory found
under there becomes a toplevel node in the devhelp treenode.

This works, but I don't think it will scale well.  For example, on my
(anemic) machine, devhelp has 7 libraries installed (i.e. 7 nodes in the
tree view by default), while monodoc has 12, and that's with some stuff
"collapsed" that would otherwise be toplevel nodes in devhelp (e.g.
"Mono Libraries/Cairo" would likely be a toplevel in devhelp, as would
"Various/NUnit Libraries" and everything else under Various).

So I don't really like the devhelp solution, as it's solution to
"structure" is to provide nearly no structure at all.

> Which brings us to the final question: is allowing external
> documentation teams to specify their documentation location (within the
> GUI tree) a good idea at all?  The possible problem is that there won't
> be any "structure" to the documentation, as docs could be placed
> anywhere/everywhere within the tree view, potentially making it more
> difficult to find things.
...
> So perhaps instead of making the tree uber-extensible, we should instead
> rethink the treeview so that we can keep things as they are --
> monodoc.xml is the sole source of the toplevel nodes in the treeview --
> but 3rd party docs have "sensible" places to insert themselves without
> inviting a "tragedy of the commons" scenario, in which the resulting
> tree view is effectively unstructured as every project decides that
> they're important enough to be toplevel nodes...
> 
> So perhaps this structure would be a good start:
> 
>   - Libraries
>     - Base Class Library
>       - [Namespace List -- System, etc.]
>     - Gnome Libraries
>     - Mono Libraries
>     - Mozilla Libraries
>     - ...
>   - Languages
>     - C#
>       - C# Language Specification
>       - C# Error Reference
>     - [ Nemerle, Boo, etc. ]
>   - Testing
>     - NUnit
>     - [ MbUnit, etc. ]
>   - Programs [ or Tools? ]
>     - MonoDevelop IDE
>     - Mono Utilities
>       - [man pages]
> 
> The point being that if we can make the toplevel nodes sufficiently high
> level, we (hopefully) won't need 3rd parties to be able to place nodes
> "anywhere", as there is already a well-designed place for them to insert
> themselves.

And the problem with this is the current implementation -- *.source
files specify their *parent* node, which (1) obviously must exist, and
(2) is the _parent_ node.  So if we changed e.g.
$prefix/lib/monodoc/sources/Mono.source to contain:

        <source provider="ecma" basefile="Mono" path="classlib"/>

(1) is satisfied ("classlib" exists as the Libraries node), but because
of (2) all of the Mono.* namespaces will show up as direct children of
Libraries, intermixed with all the children of System.*, Novell.*,
Cairo.*, and everything else.

So much for structure.  We'd get something worse than devhelp!

What I think is necessary is an extension to the *.source format: in
addition to /monodoc/source, we could permit a /monodoc/node element
(with the same semantics as in monodoc.xml), with the following changes:

1. /monodoc/node element (i.e. toplevel //node element) would require a
@parent attribute, which would be the parent node of the specified node.
If no @parent is provided, it would be ignored.

2. All //node elements from $libdir/monodoc/sources/*.sources would be
"merged" with the //node elements within $libdir/monodoc/monodoc.xml at
runtime.  Two nodes with the same //node/@name attribute value would be
the same node.  //node/@label is not used for equality purposes.

If no node matching the /monodoc/source/@path value is found, it would
be inserted underneath a default Various node.

This would allow a $libdir/monodoc/monodoc.xml file of:

        <?xml version="1.0"?>
        <node label="Mono Documentation" name="root:">
          <node label="Libraries" name="classlib"/>
          <node label="Languages" name="languages"/>
          <node label="Testing" name="testing"/>
          <node label="Tools" name="tools"/>
          <node label="Various" name="various" />
        </node>

$libdir/monodoc/sources/Mono.source would become:

        <?xml version="1.0"?>
        <monodoc>
          <node label="Mono Libraries" name="classlib-mono"
            parent="classlib" />
          <source provider="ecma" basefile="Mono" path="classlib-mono"/>
        </monodoc>

And more "complicated" nesting could be done to support multiple levels
of nesting, e.g. cs-errors.source:

        <?xml version="1.0"?>
        <monodoc>
          <node label="C#" name="lang-c#" parent="languages">
            <node label="C# Compiler Error Reference" name="cs-errors"/>
          </node>
          <source provider="error" basefile="cs-errors"
        path="cs-errors"/>
        </monodoc>

and ecma334.source:

        <?xml version="1.0"?>
        <monodoc>
          <node label="C#" name="lang-c#" parent="languages">
            <node label="C# Language Specification" name="ecmaspec"/>
          </node>
          <source provider="ecmaspec" basefile="ecma334"
        path="ecmaspec"/>
        </monodoc>

Which would generate the /Languages/C#/C# Language Spec etc. nodes from
the quotation above.

This would allow a basic level of structure to be provided (Libraries,
Testing, Tools, etc.), while allowing each .source file to provide
additional structure in a reasonable manner, while the entire treeview
is built at runtime.

New toplevel nodes could even be added by using "root:" as the @parent
node (though this should be discouraged).

Now, I haven't actually written any code to do this, just trying to
think/feel things out here, but does this sound sane/reasonable?  Would
this clear up the packaging issues that were originally eluded to?  Is
anything missing?

Thanks,
 - Jon