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

[Jonathan Pryor]

Background: we'd the treeview to be generated at runtime, so that
distros don't need to patch monodoc.xml to add additional documentation
(without placing all additional documentation under the Various node).

This is doubly useful when we have projects like Gendarme looking to
integrate their documentation (see the gendarme google group), but the
patches I've seen for that _also_ involve monodoc.xml changes, so the
current monodoc.xml architecture hostile toward 3rd parties...

With luck, we can get this finished for Mono 2.2...

On Mon, 2008-10-20 at 23:18 -0400, Jonathan Pryor wrote:
> Consequently, I'm thinking of a slightly different track: drop Testing
> and Libraries as top-level nodes (leaving Languages, Programs/Tools, and
> Various), and make all libraries top-level nodes:
> 
>   - Base Class Library
>     - Namespaces [ System, etc. ]
>   - Gnome Libraries
>     - Namespaces [ Gtk, Gnome, etc. ]
>   - Languages
>     - C#
>       - ...
>   - Mono Libraries
>     - Namespaces [ Mono.Posix, etc. ]
>   - NUnit Libraries
>     - Namespaces [ NUnit.Framework, etc. ]
>   - ...
>   - Tools
>     - Mono Development Tools
>       - Man pages
>     - MonoDevelop IDE
>     - ...
>   - Various
> 
> Every layer should be alphabetized (otherwise you can't find anything).
> This is slightly less structured, but should still be ~straightforward
> to implement with the previously suggested /monodoc/node/@parent
> attribute.

Attached is a monodoc.dll patch and sample files to drive the treeview.

parent.patch adds support for the //node/@parent attribute, which allows
a //node element to specify the parent node to use "by name."

With that patch applied, you can use the new monodoc.xml (attached),
which is significantly smaller than before.  *.source files can now
provide additional structure to the tree view.

netdocs.source is a minimal example of adding a root "Base Class
Library" node, under which the normal "classlib" documentation is
displayed.

cs-errors.source creates a "C# / C# Compiler Error Reference" node under
the Languages node, while ecma334.source creates a "C# / C# Language
Specification" node under the Languages node.  Since cs-errors.source &
ecma334.source refer to intermediate nodes with the same name, they get
the same parent at runtime.

The result of patch + these new .source files is the default tree:

  - Base Class Library
  - Languages
    - C#
      - C# Compiler Error Reference
      - C# Language Specification

It's ~fully dynamic, so if any additional structure is desired by a 3rd
party, they can ~trivially add it.

Thoughts?

 - Jon

-------------- next part --------------
A non-text attachment was scrubbed...
Name: parent.patch
Type: text/x-patch
Size: 1499 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20081021/4f98cfee/attachment.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: monodoc.xml
Type: application/xml
Size: 244 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20081021/4f98cfee/attachment.rdf 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: cs-errors.source
Type: application/xml
Size: 239 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20081021/4f98cfee/attachment-0001.rdf 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ecma334.source
Type: application/xml
Size: 236 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20081021/4f98cfee/attachment-0002.rdf 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: netdocs.source
Type: application/xml
Size: 174 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20081021/4f98cfee/attachment-0003.rdf