[mono-packagers] monodoc & mcs/mono module merging
jonpryor at vt.edu
Mon Oct 20 23:18:11 EDT 2008
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. ]
- Mono Libraries
- Namespaces [ Mono.Posix, etc. ]
- NUnit Libraries
- Namespaces [ NUnit.Framework, etc. ]
- Mono Development Tools
- Man pages
- MonoDevelop IDE
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
> 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).
More information about the mono-packagers-list