[Mono-docs-list] mdoc: Introduction and RFC
jit at occams.info
Mon Feb 25 16:21:32 EST 2008
Jonathan Pryor wrote:
> 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
Oh those don't count! :) If you're going to update something, you can
update your other projects at the same time.
Seriously, I think when major cruft-removal is in order, and a 2.0 Mono
release is approaching, it's fair to break things like documentation
> Furthermore, mdoc isn't a shell script, it is a C# .exe.
Ahha! That's neat.
But it's all good. I'm always happy to see your improvements.
- Josh Tauberer
"Yields falsehood when preceded by its quotation! Yields
falsehood when preceded by its quotation!" Achilles to
Tortoise (in "Godel, Escher, Bach" by Douglas Hofstadter)
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
More information about the Mono-docs-list