[Mono-docs-list] mdoc: Introduction and RFC
jonpryor at vt.edu
Thu Feb 21 07:24:25 EST 2008
On Thu, 2008-02-21 at 06:58 -0500, Joshua Tauberer wrote:
> Why not just merge all of the tools into a mdoc.exe (with the new
> options parsing library to boot), rather than wrapping them all with a
Because that would imply removing the older tools, which would break any
number of existing projects; I know that removing monodocer and
monodocs2html would break Mono.Fuse and NDesk.Options, and probably
Gtk#. These tools will need to remain for the foreseeable future, and
potentially may never be removed. New tools can be restricted to just
Furthermore, mdoc isn't a shell script, it is a C# .exe. As such, I can
do such wonderful things as -r:monodocer.exe and invoke the monodocer
Main() function directly from mdoc. Alas, this means that everything is
transferred between mdoc and the subcommands via a string, but this
allows simpler maintenance and code re-use.
> But otherwise I think it's a good idea.
> > - `mdoc update' has *far* fewer options than monodocer, mostly because
> > I can't see the need for some monodocer options such as
> > -ignore_extra_docs (it should die now), -pretty (when don't you want
> > nicely formatted XML?), -name, -since, etc.
> I think I added -pretty because reformatting XML causes problems with
> version control.
I found that without -pretty, all "unnecessary" whitespace was removed,
which resulted in *huge* diffs after minor updates (lack of newlines,
etc.). Also (monodocer bug?), the initial monodocer output was usually
pretty-printed, even if -pretty wasn't provided, which resulted in
further executions *removing* the whitespace (thus contributing to the
What I have observed is that monodocer occasionally goes schizo and
removes whitespace from e.g. <list/> elements. I have no idea why, nor
have I fixed this yet.
> And I don't even recall what -name does.
Allows you to provide the project name. :-)
Also missing is -type, -namespace, -updateto....
And -overrides is enabled by default under `mdoc update`.
More information about the Mono-docs-list