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

[Jonathan Pryor]

On Sat, 2008-10-18 at 13:10 +0200, Mirco Bauer wrote:
> On Fri, 17 Oct 2008 21:10:38 -0400
> Jonathan Pryor <jonpryor at vt.edu> wrote:
> 
> > > Unanswered Questions:
> > 
> > What should be done about monodoc/engine/web, the ASP.NET frontend to
> > monodoc documentation?  I don't believe that it's actually packaged,
> > nor do I know of anyone using it except for http://go-mono.com/docs,
> 
> 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.

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

> I see the point moving the documentation files to mcs, but why the
> tools too? IMHO the monodoc tarball should provide only the
> documentation framework, and mono (mcs) would then ship the actual
> documentation... Most library packages in debian ship monodoc manual
> packages:
> http://packages.debian.org/search?searchon=names&keywords=monodoc+manual
> 
> But of course a circular dependency must be prevented between mono,
> xsp and monodoc... one of the reasons the gtk# frontend was moved to
> mono-tools and gtk# docs to gtk-sharp-2.0...

Exactly.  It doesn't make a whole lot of sense to include documentation
within mcs, but provide the tools to update that documentation in
monodoc -- mcs would then depend upon monodoc for doc update and
assembling purposes.

This is doubly problematic for packaging: if we kept the tools in
monodoc, then to build the monodoc package you would *require* a
parallel mcs checkout.  (Technically this is already necessary so that
monodoc can use the mcs/errors directory for error examples, but iirc
this isn't an ideal situation, and I don't think anyone wants to make it
"worse" by also depending upon mcs/class/*/Documentation in addition to
mcs/errors...)

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

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

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.

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

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

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

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.

Arguably we're there already -- why do we need Mono Libraries, Gnome
Libraries, and Novell Libraries as toplevel nodes?  And who is going to
think to look under Various for the NUnit docs?

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

 - Jon