monodoc & mcs/mono module merging

[Jonathan Pryor]

This is a heads-up that the monodoc & mcs modules are merging for the
Mono 2.2 release.

Why?

The largest reason is so that documentation is closer to the source, in
the hopes that someone other than me will actually update the
documentation stubs and write documentation for the class libraries.
(This may be in vain, but I can hope, can't I?)

Another reason is that some class library source I've seen makes use of
C#'s XML documentation features, and having the documentation in the
same module as the source code should simplify importing this
documentation.

(I would enable XML documentation importing now, but for mscorlib.dll it
drops a fair bit of the existing docs...)


How?

Files and directories from the monodoc svn module were `svn copy`d into
the mcs and mono modules, so full file history should be preserved.
This includes:

      * monodoc/class/ASSEMBLY -> mcs/class/ASSEMBLY/Documentation.
      * monodoc/ecma334        -> mcs/docs/ecma334
      * monodoc/engine         -> mcs/tools/monodoc
      * monodoc/man            -> mono/man
      * monodoc/scripts        -> mono/scripts
      * monodoc/tools/*        -> mcs/tools/mdoc.

The monodoc module hasn't gone (though we may remove it; no ETA), so it
can still be referred to.

The mcs Makefiles have gained a new `doc-update` target, which when run
will update the documentation stubs within the Documentation/en
directory using mdoc.  Running `doc-update` at the mcs toplevel will
update the documentation stubs for all libraries within mcs (where
"library" is defined as "anything including library.make" in Makefile).

The doc-update target is NOT currently run automatically by the build
system.  It is up to those wishing to update the documentation to run
this target.  (This decision may be revisited in the future; I just
didn't think it a good idea to have several files changed whenever a
library was built, increasing the amount of "noise" developers need to
sort through before committing...)

The mcs/docs directory assembles the Documentation directories
into .tree and .zip files for use by monodoc, and installs them into the
same location these files have always been: $prefix/lib/monodoc/sources.

mcs now contains and will build and install the documentation-related
tools that were in the monodoc module, such as mdoc, monodoc.dll, mod,
etc.

In terms of packaging, I *hope* that very little will change,
big-picture wise.  For example, mono-core.spec already creates 18
packages, so it should be possible to create a new %package which
contains the same files as the previous monodoc package...[0]


Related issues:

Many of the monodoc/tools and monodoc/engine programs, which used to be
separate, have been bundled together into the mdoc program.  (mdoc was
introduced in Mono 2.0, but it was just a wrapper for the other apps.)
To maintain compatibility, I'll be writing shell scripts which convert
the previous command-lines to mdoc command lines.  This will impact the
commands: mdassembler, mdvalidater, monodocer, monodocs2html,
monodocs2slashdoc.

I would like to remove the commands mdcs2ecma and mdnormalizer, as
mdcs2ecma hasn't been maintained in eons (and monodocer/mdoc already has
Microsoft XML documentation import support), and mdnormalizer seems
~pointless (xmllint, anyone?).


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, but if
we want to remove the monodoc module we'll need to move it _somewhere_
(standalone svn module?).


 - Jon

[0] Famous Last Words (TM)


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

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


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Jonathan Pryor]

On Sun, 2008-10-19 at 10:20 -0400, Jonathan Pryor wrote:
> > 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? :-)

Continuing with this logic...

I've done a little more thinking about this.

First thought: what do other documentation tools do?

Alas, I only know of devhelp (anyone know what the Qt equivalent is?).

What's devhelp do?

Documentation is in e.g. /usr/share/gtk-doc, and each directory found
under there becomes a toplevel node in the devhelp treenode.

This works, but I don't think it will scale well.  For example, on my
(anemic) machine, devhelp has 7 libraries installed (i.e. 7 nodes in the
tree view by default), while monodoc has 12, and that's with some stuff
"collapsed" that would otherwise be toplevel nodes in devhelp (e.g.
"Mono Libraries/Cairo" would likely be a toplevel in devhelp, as would
"Various/NUnit Libraries" and everything else under Various).

So I don't really like the devhelp solution, as it's solution to
"structure" is to provide nearly no structure at all.

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

> 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 the problem with this is the current implementation -- *.source
files specify their *parent* node, which (1) obviously must exist, and
(2) is the _parent_ node.  So if we changed e.g.
$prefix/lib/monodoc/sources/Mono.source to contain:

        <source provider="ecma" basefile="Mono" path="classlib"/>

(1) is satisfied ("classlib" exists as the Libraries node), but because
of (2) all of the Mono.* namespaces will show up as direct children of
Libraries, intermixed with all the children of System.*, Novell.*,
Cairo.*, and everything else.

So much for structure.  We'd get something worse than devhelp!

What I think is necessary is an extension to the *.source format: in
addition to /monodoc/source, we could permit a /monodoc/node element
(with the same semantics as in monodoc.xml), with the following changes:

1. /monodoc/node element (i.e. toplevel //node element) would require a
@parent attribute, which would be the parent node of the specified node.
If no @parent is provided, it would be ignored.

2. All //node elements from $libdir/monodoc/sources/*.sources would be
"merged" with the //node elements within $libdir/monodoc/monodoc.xml at
runtime.  Two nodes with the same //node/@name attribute value would be
the same node.  //node/@label is not used for equality purposes.

If no node matching the /monodoc/source/@path value is found, it would
be inserted underneath a default Various node.

This would allow a $libdir/monodoc/monodoc.xml file of:

        <?xml version="1.0"?>
        <node label="Mono Documentation" name="root:">
          <node label="Libraries" name="classlib"/>
          <node label="Languages" name="languages"/>
          <node label="Testing" name="testing"/>
          <node label="Tools" name="tools"/>
          <node label="Various" name="various" />
        </node>

$libdir/monodoc/sources/Mono.source would become:

        <?xml version="1.0"?>
        <monodoc>
          <node label="Mono Libraries" name="classlib-mono"
            parent="classlib" />
          <source provider="ecma" basefile="Mono" path="classlib-mono"/>
        </monodoc>

And more "complicated" nesting could be done to support multiple levels
of nesting, e.g. cs-errors.source:

        <?xml version="1.0"?>
        <monodoc>
          <node label="C#" name="lang-c#" parent="languages">
            <node label="C# Compiler Error Reference" name="cs-errors"/>
          </node>
          <source provider="error" basefile="cs-errors"
        path="cs-errors"/>
        </monodoc>

and ecma334.source:

        <?xml version="1.0"?>
        <monodoc>
          <node label="C#" name="lang-c#" parent="languages">
            <node label="C# Language Specification" name="ecmaspec"/>
          </node>
          <source provider="ecmaspec" basefile="ecma334"
        path="ecmaspec"/>
        </monodoc>

Which would generate the /Languages/C#/C# Language Spec etc. nodes from
the quotation above.

This would allow a basic level of structure to be provided (Libraries,
Testing, Tools, etc.), while allowing each .source file to provide
additional structure in a reasonable manner, while the entire treeview
is built at runtime.

New toplevel nodes could even be added by using "root:" as the @parent
node (though this should be discouraged).

Now, I haven't actually written any code to do this, just trying to
think/feel things out here, but does this sound sane/reasonable?  Would
this clear up the packaging issues that were originally eluded to?  Is
anything missing?

Thanks,
 - Jon


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Mirco Bauer-4]

On Sun, 19 Oct 2008 10:20:14 -0400
Jonathan Pryor <jonpryor@...> 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@...  http://www.meebey.net/
PEAR Developer    meebey@...     http://pear.php.net/
Debian Developer  meebey@...  http://www.debian.org/
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

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


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[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


[parent.patch]

---

Index: Monodoc/provider.cs
===================================================================
--- Monodoc/provider.cs (revision 116332)
+++ Monodoc/provider.cs (working copy)
@@ -339,7 +339,8 @@
 
  public void Sort ()
  {
- nodes.Sort ();
+ if (nodes != null)
+ nodes.Sort ();
  }
 
  public string URL {
@@ -364,7 +365,15 @@
 
  int IComparable.CompareTo (object obj)
  {
- Node other = (Node) obj;
+ Node other = obj as Node;
+ if (other == null)
+ return -1;
+
+ if (position < 0)
+ LoadNode ();
+ if (other.position < 0)
+ other.LoadNode ();
+
  return String.CompareOrdinal(caption, other.caption);
  }
 }
@@ -851,6 +860,7 @@
  foreach (Node n in hs.Tree.Nodes){
  parent.AddNode (n);
  }
+ parent.Sort ();
  }
  }
 
@@ -869,6 +879,9 @@
  // Clean the tree
  PurgeNode(root);
 
+ // Sort the top 3 levels of the tree
+ root.Sort ();
+
  return root;
  }
 
@@ -949,7 +962,14 @@
  void Populate (Node parent, XmlNodeList xml_node_list)
  {
  foreach (XmlNode xml_node in xml_node_list){
- XmlAttribute e = xml_node.Attributes ["label"];
+ XmlAttribute e = xml_node.Attributes ["parent"];
+ if (e != null && name_to_node.ContainsKey (e.InnerText)) {
+ Node p = (Node) name_to_node [e.InnerText];
+ xml_node.Attributes.Remove (e);
+ Populate (p, xml_node.SelectNodes ("."));
+ continue;
+ }
+ e = xml_node.Attributes ["label"];
  if (e == null){
  Console.Error.WriteLine ("`label' attribute missing in <node>");
  continue;

---

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Néstor Salceda]

El mar, 21-10-2008 a las 00:59 -0400, Jonathan Pryor escribió:
> 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...

        Yes, that's true.  I could do it adding a <source> tag in the .source
files, but then I have several Gendarme.Rules ... nodes without a
relationship among them, under Various, and I will prefer group those
nodes under a Rules node (because perhaps a Framework node should be
added too).  I had thought about send a patch to monodoc.xml, but I
prefered wait until this stuff is finished :)

        Personally, I like the solution you have thought, nesting in
the .source files.

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

        Nice, if I can help you with something; I'll be glad to do it.

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

        Well, as it allows defining "complicated" nesting I like it.

Néstor.

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Jonathan Pryor]

On Tue, 2008-10-21 at 00:59 -0400, Jonathan Pryor wrote:
> 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).

Attached is an updated patch to mcs/tools/monodoc & mcs/docs to put this
all into perspective -- monodoc.dll changes, monodoc.xml, and *.source
changes.

This version supports the following non-Library top-level nodes:

  - File Formats
    - [ Mono File Formats - mdoc.5, mono-config.5 ]
  - Languages
    - [ C#, etc. ]
  - Tools
    - [ Mono Development Tools, etc. ]
  - Various
    - [ Anything that has an invalid //source/@path value

Library nodes ("Base Class Library", "Mono Libraries", etc.) are also
top-level nodes, and all top-level nodes are sorted by name.

A screenshot of the currrent tree also attached (which doesn't
necessarily show all those nodes, as nodes with no children are hidden).

 - Jon


[monodoc.patch]

---

Index: ChangeLog
===================================================================
--- ChangeLog (revision 116516)
+++ ChangeLog (working copy)
@@ -1,3 +1,26 @@
[phone]  Jonathan Pryor  <jpryor@...>
+
+ * docs (svn:ignore): Ignore generated files.
+ * docs/lang-csharp.source: Added; combined .source file for the C#
+  language specification and error reference.
+ * docs/Makefile: Support lang-csharp.source, mono-file-formats.*, etc.
+ * *.tree/*.zip should be rebuilt when Makefile is changed.
+ * docs/mono-file-formats.config, docs/mono-file-formats.source: Added;
+  moving file format documentation out from mono-tools.* so that it's
+  easier to find.
+ * docs/mono-tools.config: Move mdoc(5), mono-config(5) to
+  mono-file-formats.config.
+ * docs/mono-tools.source, docs/Mono.source, docs/netdocs.source,
+  docs/Novell.source, docs/nunit-docs.source: Add /monodoc/node
+  information so that the documentation is inserted into the correct
+  location.
+ * docs/monodoc.xml: Vastly simplify the default monodoc.xml as
+  structure can be/has been pushed out into the .source files.  This
+  should help simplify the life of downstream packagers who wish to
+  add additional documentation to monodoc.
+ * docs/ecma334.source, docs/cs-errors.source: Remove (replaced with
+  lang-csharp.source).
+
 2008-10-20  Jonathan Pryor  <jpryor@...>
 
  * docs/Makefile (MONO_DIRS): Add Mono.Data.SqliteClient docs.

Property changes on: docs
___________________________________________________________________
Modified: svn:ignore
   - semantic.cache

   + semantic.cache
*.tree
*.zip


Index: docs/nunit-docs.source
===================================================================
--- docs/nunit-docs.source (revision 116355)
+++ docs/nunit-docs.source (working copy)
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
 <monodoc>
+  <node label="NUnit Libraries" name="classlib-nunit" parent="libraries" />
   <source provider="ecma" basefile="nunit-docs" path="classlib-nunit"/>
 </monodoc>
Index: docs/mono-file-formats.source
===================================================================
--- docs/mono-file-formats.source (revision 0)
+++ docs/mono-file-formats.source (revision 0)
@@ -0,0 +1,5 @@
+<?xml version="1.0"?>
+<monodoc>
+  <node label="Mono File Formats" name="mono-formats" parent="formats" />
+  <source provider="man" basefile="mono-file-formats" path="mono-formats"/>
+</monodoc>
Index: docs/monodoc.xml
===================================================================
--- docs/monodoc.xml (revision 116355)
+++ docs/monodoc.xml (working copy)
@@ -1,24 +1,7 @@
 <?xml version="1.0"?>
-<node label="Mono Documentation" name="root:">
-  <node label="Class Library" name="classlib"/>
-  <node label="Mono Libraries" name="classlib-mono"/>
-  <node label="Gnome Libraries" name="classlib-gnome"/>
-  <node label="Mozilla Libraries" name="classlib-gecko"/>
-  <node label="Novell Libraries" name="classlib-novell"/>
-  <node label="MonoDevelop IDE" name="md">
-    <node label="API Reference" name="monodevelop" />
-    <node label="Extension Point Reference" name="monodevelop-extension-guide" />
-  </node>
-  <node label="Moonlight/Silverlight" name="moonlight"/>
-  <node label="C# Language Specification" name="ecmaspec" />
-  <node label="C# Compiler Error Reference" name="cs-errors" />
-  <node label="Mono Development Tools" name="dev-tools">
-    <node label="Mono Debugger" name="debugger"/>
-  </node>
-  <node label="Mono Embedding" name="embed"/>
-  <node label="Various" name="various">
-    <node label="DiaCanvas Libraries" name="classlib-diacanvas"/>
-    <node label="NUnit Libraries" name="classlib-nunit"/>
-    <node label="Tao" name="tao"/>
-  </node>
+<node label="Mono Documentation" name="libraries">
+  <node label="File Formats" name="formats" />
+  <node label="Languages" name="languages" />
+  <node label="Tools" name="tools" />
+  <node label="Various" name="various" />
 </node>
Index: docs/lang-csharp.source
===================================================================
--- docs/lang-csharp.source (revision 0)
+++ docs/lang-csharp.source (revision 0)
@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<monodoc>
+  <node label="C#" name="lang-c#" parent="languages">
+    <node label="C# Compiler Error Reference" name="cs-errors"/>
+    <node label="C# Language Specification" name="ecmaspec"/>
+  </node>
+  <source provider="error" basefile="cs-errors" path="cs-errors"/>
+  <source provider="ecmaspec" basefile="ecma334" path="ecmaspec"/>
+</monodoc>
Index: docs/Novell.source
===================================================================
--- docs/Novell.source (revision 116355)
+++ docs/Novell.source (working copy)
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
 <monodoc>
+  <node label="Novell Libraries" name="classlib-novell" parent="libraries" />
   <source provider="ecma" basefile="Novell" path="classlib-novell"/>
 </monodoc>
Index: docs/netdocs.source
===================================================================
--- docs/netdocs.source (revision 116355)
+++ docs/netdocs.source (working copy)
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
 <monodoc>
+  <node label="Base Class Library" name="classlib" parent="libraries" />
   <source provider="ecma" basefile="netdocs" path="classlib"/>
 </monodoc>
Index: docs/ecma334.source
===================================================================
--- docs/ecma334.source (revision 116355)
+++ docs/ecma334.source (working copy)
@@ -1,4 +0,0 @@
-<?xml version="1.0"?>
-<monodoc>
-  <source provider="ecmaspec" basefile="ecma334" path="ecmaspec"/>
-</monodoc>
Index: docs/mono-file-formats.config
===================================================================
--- docs/mono-file-formats.config (revision 0)
+++ docs/mono-file-formats.config (revision 0)
@@ -0,0 +1,5 @@
+<?xml version="1.0"?>
+<manpages>
+  <manpage name="mdoc(5)"               page="../../mono/man/mdoc.5" />
+  <manpage name="mono-config(5)"        page="../../mono/man/mono-config.5" />
+</manpages>
Index: docs/mono-tools.source
===================================================================
--- docs/mono-tools.source (revision 116355)
+++ docs/mono-tools.source (working copy)
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
 <monodoc>
+  <node label="Mono Development Tools" name="dev-tools" parent="tools" />
   <source provider="man" basefile="mono-tools" path="dev-tools"/>
 </monodoc>
Index: docs/Mono.source
===================================================================
--- docs/Mono.source (revision 116355)
+++ docs/Mono.source (working copy)
@@ -1,4 +1,5 @@
 <?xml version="1.0"?>
 <monodoc>
+  <node label="Mono Libraries" name="classlib-mono" parent="libraries" />
   <source provider="ecma" basefile="Mono" path="classlib-mono"/>
 </monodoc>
Index: docs/mono-tools.config
===================================================================
--- docs/mono-tools.config (revision 116355)
+++ docs/mono-tools.config (working copy)
@@ -20,7 +20,6 @@
   <manpage name="mdcs2ecma(1)"          page="../../mono/man/mdcs2ecma.1" />
   <manpage name="mdnormalizer(1)"       page="../../mono/man/mdnormalizer.1" />
   <manpage name="mdoc(1)"               page="../../mono/man/mdoc.1" />
-  <manpage name="mdoc(5)"               page="../../mono/man/mdoc.5" />
   <manpage name="mdoc-assemble(1)"      page="../../mono/man/mdoc-assemble.1" />
   <manpage name="mdoc-export-html(1)"   page="../../mono/man/mdoc-export-html.1" />
   <manpage name="mdoc-export-msxdoc(1)" page="../../mono/man/mdoc-export-msxdoc.1" />
@@ -29,7 +28,6 @@
   <manpage name="mdvalidator(1)"        page="../../mono/man/mdvalidator.1" />
   <manpage name="mkbundle(1)"           page="../../mono/man/mkbundle.1" />
   <manpage name="mono(1)"               page="../../mono/man/mono.1" />
-  <manpage name="mono-config(5)"        page="../../mono/man/mono-config.5" />
   <manpage name="mono-service(1)"       page="../../mono/man/mono-service.1" />
   <manpage name="mono-shlib-cop(1)"     page="../../mono/man/mono-shlib-cop.1" />
   <manpage name="monodocer(1)"          page="../../mono/man/monodocer.1" />
Index: docs/Makefile
===================================================================
--- docs/Makefile (revision 116516)
+++ docs/Makefile (working copy)
@@ -15,9 +15,9 @@
  $(wildcard ecma334/*.xml)
 
 DOC_SOURCE_FILES = \
- cs-errors.source            \
- ecma334.source              \
+ lang-csharp.source          \
  mono-tools.source           \
+ mono-file-formats.source    \
  Mono.source                 \
  netdocs.source              \
  Novell.source               \
@@ -27,6 +27,7 @@
  cs-errors.tree cs-errors.zip      \
  ecma334.tree ecma334.zip          \
  mono-tools.tree mono-tools.zip    \
+ mono-file-formats.tree mono-file-formats.zip    \
  Mono.tree Mono.zip                \
  netdocs.tree netdocs.zip          \
  Novell.tree Novell.zip            \
@@ -96,24 +97,27 @@
 
 build-documentation: $(ASSEMBLED_DOCS)
 
-netdocs.tree netdocs.zip:
+netdocs.tree netdocs.zip: Makefile
  $(MDOC) assemble -o netdocs $(NETDOCS_DIRS)
 
-Mono.tree Mono.zip:
+Mono.tree Mono.zip: Makefile
  $(MDOC) assemble -o Mono $(MONO_DIRS)
 
-Novell.tree Novell.zip:
+Novell.tree Novell.zip: Makefile
  $(MDOC) assemble -o Novell $(NOVELL_DIRS)
 
-nunit-docs.tree nunit-docs.zip:
+nunit-docs.tree nunit-docs.zip: Makefile
  $(MDOC) assemble -o nunit-docs $(NUNIT_DIRS)
 
-cs-errors.tree cs-errors.zip:
- $(MDOC) assemble -o cs-errors -f error cs-errors.config
+cs-errors.tree cs-errors.zip: cs-errors.config Makefile
+ $(MDOC) assemble -o cs-errors -f error $<
 
-ecma334.tree ecma334.zip:
+ecma334.tree ecma334.zip: Makefile
  $(MDOC) assemble -o ecma334 -f ecmaspec ecma334
 
-mono-tools.tree mono-tools.zip: mono-tools.config
- $(MDOC) assemble -o mono-tools -f man mono-tools.config
+mono-tools.tree mono-tools.zip: mono-tools.config Makefile
+ $(MDOC) assemble -o mono-tools -f man $<
 
+mono-file-formats.tree mono-file-formats.zip: mono-file-formats.config Makefile
+ $(MDOC) assemble -o mono-file-formats -f man $<
+
Index: docs/cs-errors.source
===================================================================
--- docs/cs-errors.source (revision 116355)
+++ docs/cs-errors.source (working copy)
@@ -1,4 +0,0 @@
-<?xml version="1.0"?>
-<monodoc>
-  <source provider="error" basefile="cs-errors" path="cs-errors"/>
-</monodoc>
Index: tools/monodoc/ChangeLog
===================================================================
--- tools/monodoc/ChangeLog (revision 116393)
+++ tools/monodoc/ChangeLog (working copy)
@@ -1,3 +1,26 @@
[phone]  Jonathan Pryor  <jonpryor@...>
+
+ * Monodoc/provider.cs:
+  - Fix Node.Sort() so that it doesn't NRE if nodes == null.
+  - Fix Node.CompareTo() so that it can sort Nodes that haven't been
+    loaded yet.
+  - Add "libraries" as an alias for "root", so that .source files can
+    refer to the parent "libraries" (which would allow us to change
+    the location of "libraries" in the future, should we want to).
+  - If a /monodoc/source/@path refers to a nonexistant node, then
+    insert the contents under Various instead of ignoring it.
+  - Sort the top-level nodes.
+  - Sort the `parent` node after inserting children under it.  This
+    allows multiple different .source files to insert nodes under the
+    same parent node and still have the child nodes sorted as most
+    mortals would expect.
+  - Support a //node/@parent attribute, which allows for creating
+    nodes underneath the specified parent node.  This allows multiple
+    different .source files to contribute to the tree and depend upon
+    each other.  Thus, instead of having a single monodoc.xml file
+    that needs to know the entire tree in advance, the entire tree can
+    be spread across multiple .source files and filled at runtime.
+
 2008-10-18  Jonathan Pryor  <jonpryor@...>
 
  * Makefile $(LIBRARY_PACKAGE): Set to `monodoc`, as we historically
Index: tools/monodoc/Monodoc/provider.cs
===================================================================
--- tools/monodoc/Monodoc/provider.cs (revision 116332)
+++ tools/monodoc/Monodoc/provider.cs (working copy)
@@ -339,7 +339,8 @@
 
  public void Sort ()
  {
- nodes.Sort ();
+ if (nodes != null)
+ nodes.Sort ();
  }
 
  public string URL {
@@ -364,7 +365,15 @@
 
  int IComparable.CompareTo (object obj)
  {
- Node other = (Node) obj;
+ Node other = obj as Node;
+ if (other == null)
+ return -1;
+
+ if (position < 0)
+ LoadNode ();
+ if (other.position < 0)
+ other.LoadNode ();
+
  return String.CompareOrdinal(caption, other.caption);
  }
 }
@@ -779,6 +788,7 @@
  XmlNodeList nodes = doc.SelectNodes ("/node/node");
 
  root.name_to_node ["root"] = root;
+ root.name_to_node ["libraries"] = root;
  root.Populate (root, nodes);
 
  Node third_party = root.LookupEntryPoint ("various");
@@ -845,12 +855,13 @@
  Node parent = root.LookupEntryPoint (path);
  if (parent == null){
  Console.Error.WriteLine ("node `{0}' is not defined on the documentation map", path);
- continue;
+ parent = third_party;
  }
 
  foreach (Node n in hs.Tree.Nodes){
  parent.AddNode (n);
  }
+ parent.Sort ();
  }
  }
 
@@ -869,6 +880,8 @@
  // Clean the tree
  PurgeNode(root);
 
+ root.Sort ();
+
  return root;
  }
 
@@ -949,7 +962,14 @@
  void Populate (Node parent, XmlNodeList xml_node_list)
  {
  foreach (XmlNode xml_node in xml_node_list){
- XmlAttribute e = xml_node.Attributes ["label"];
+ XmlAttribute e = xml_node.Attributes ["parent"];
+ if (e != null && name_to_node.ContainsKey (e.InnerText)) {
+ Node p = (Node) name_to_node [e.InnerText];
+ xml_node.Attributes.Remove (e);
+ Populate (p, xml_node.SelectNodes ("."));
+ continue;
+ }
+ e = xml_node.Attributes ["label"];
  if (e == null){
  Console.Error.WriteLine ("`label' attribute missing in <node>");
  continue;

---

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Miguel de Icaza-4]

Hello,

    I love this!   lets get it in.

> On Tue, 2008-10-21 at 00:59 -0400, Jonathan Pryor wrote:
> > 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).
>
> Attached is an updated patch to mcs/tools/monodoc & mcs/docs to put this
> all into perspective -- monodoc.dll changes, monodoc.xml, and *.source
> changes.
>
> This version supports the following non-Library top-level nodes:
>
>   - File Formats
>     - [ Mono File Formats - mdoc.5, mono-config.5 ]
>   - Languages
>     - [ C#, etc. ]
>   - Tools
>     - [ Mono Development Tools, etc. ]
>   - Various
>     - [ Anything that has an invalid //source/@path value
>
> Library nodes ("Base Class Library", "Mono Libraries", etc.) are also
> top-level nodes, and all top-level nodes are sorted by name.
>
> A screenshot of the currrent tree also attached (which doesn't
> necessarily show all those nodes, as nodes with no children are hidden).
>
>  - Jon
>

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list