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

[Joshua Tauberer]

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

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

> 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

http://razor.occams.info

"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
> 
>