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

[Jonathan Pryor]

On Mon, 2008-10-20 at 22:44 +0200, Mirco Bauer wrote:
> On Sun, 19 Oct 2008 10:20:14 -0400
> Jonathan Pryor <jonpryor at vt.edu> wrote:
> 
> > I think a better strategy would be to make PARENT a "node path"
> > instead, e.g. "/Various/NUnit Libraries", which would bypass the
> > whole "PARENT node doesn't exist" problem (as it could always be
> > created automatically from the path).
> 
> Hm we tried to keep actual structure stuff out, as it might change
> upstream one day

Yes, I see your point.  But some amount of structure needs to be
necessary so that we can move related things into separate files/nodes,
e.g. have cs-errors.zip in a /Languages/C#/Errors node and ecma334.zip
in a /Languages/C#/Specification node, without monodoc.xml needing to
care about anything below /Languages.

> > 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]
> 
> I really like this one!

Me too, and I managed to pass it by Miguel earlier today and he _didn't_
like it. :-(

His problem: the purpose to monodoc is to document Libraries, not these
other "things" (languages, programs), so it "buries" the purpose of
monodoc in his opinion.

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.

> Well but where would libfoo go then? in that "- ..." slot?

If libfoo is a library, then it could provide a /monodoc/node/@prefix
attribute with the value of "root" (to create a toplevel node), and
insert documentation under that node.

If it doesn't provide a /monodoc/node element, then the current
semantics apply (and the documentation may wind up underneath Various).

> Did you take a list of the monodoc manual packages we ship in debian?
> most of them have nothing in common....

No, but I have seen lists of man pages in general, which frequently have
~nothing in common.  Which is precisely why external documentation needs
to provide _some_ amount of structure, because there's no way monodoc
could automatically provide any reasonable amount of structure (nor
could any other app).

 - Jon