[Mono-docs-list] 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)