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

[Mirco Bauer]

On Sun, 19 Oct 2008 10:20:14 -0400
Jonathan Pryor <jonpryor at vt.edu> wrote:

> On Sat, 2008-10-18 at 13:10 +0200, Mirco Bauer wrote:
> > Debian and thus Ubuntu ship the web-frontend of monodoc:
> > http://packages.debian.org/search?keywords=monodoc-http
> > 
> > And according to popcon 108 installs of it are counted:
> > http://qa.debian.org/popcon.php?package=monodoc
> 
> Wow, it is being used.  Incredible.

Yes! And I like it! :)

> 
> So, there are three solutions:
> 
> 1. Move the ASP.NET web-frontend into mcs/tools as well.
> 2. Keep it in monodoc, and have it be the _only_ thing packaged from
> it. 3. Move it to a new svn module.
> 
> I'm leaning toward (1)...

hm the gtk-frontend lives in mono-tools... maybe put it there?

> So overall I think this is an improvement -- building monodoc used to
> require parallel mcs & mono directories (to find mcs/errors and
> mono/man for documentation inclusion), and by moving these into mcs
> it seems we simplify packaging as well (no such silly requirements,
> except that mcs & mono be checked out at the same time, which has
> been a requirement since the beginning...)

For downstream packaging is not an issue anyhow, the monodoc ->
mono/mcs merge, except that the mono (downstream) source package will
become even more complex :-P

> 
> > 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? :-)

We tried to identify the issue first, and like the wiki shows there is
an upstream solution path but wasn't followed yet.

> 
> The easy, flippant answer for monodoc integration is that all "3rd
> party" documentation should be placed under the "Various" node, and
> then you don't need to worry about anything, as monodoc.xml doesn't
> need modification, etc.

That's we do, we put all libs under Various, but monodoc-browser didnt
show them.

> 
> Though I will admit that isn't an ideal solution, it's just an easy
> one.
> 
> Reading the MonodocIntegration wiki, one potential problem with the
> *.installmonodoc format is the [PARENT] entry -- what should happen if
> the specified parent node isn't present (because the PARENT node is
> from an uninstalled *.installmonodoc file)?  

We planned to make PARENT actually a defined list of supported/allowed
nodes...

> 
> 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, and then we should need to patch the generator-tool
instead of all source packages using monodoc.

> 
> But why have a *.installmonodoc file and $libdir/monodoc/manuals.d at
> all?  Why not have the current requirements -- that all files must be
> placed in $libdir/monodoc/sources -- and instead extend the
> *.source /monodoc/source/@path attribute semantics so that instead of
> referring to nodes "by name" it can instead hold a labeled path (as
> suggested above for PARENT).  The semantic choice between node-name
> and Labeled path could be based on whether @path starts with a '/'.

Well I am all for a solution that doesn't require any additional
handling besides putting the docs in the right place! :) But he had no
such solution so we tried to address the short comings of what he have
now...

> 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!

Just testing is IMHO unneeded as testing is either a tool or a library
(depending which part).

> 
> 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.

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

> 
> And if someone wants/needs a new node to insert themselves under, then
> they can bring it up on mono-docs-list and we can discuss the
> appropriate place to insert themselves or create a new node for them.

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

> 
>  - Jon
> 
> 


-- 
Regards,

Mirco 'meebey' Bauer

PGP-Key ID: 0xEEF946C8

FOSS Developer    meebey at meebey.net  http://www.meebey.net/
PEAR Developer    meebey at php.net     http://pear.php.net/
Debian Developer  meebey at debian.org  http://www.debian.org/