[Mono-docs-list] mdoc: Introduction and RFC

[Jonathan Pryor]

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

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
mdoc sub-commands.

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

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

 - Jon