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@lists.ximian.com http://lists.ximian.com/mailman/listinfo/mono-docs-list