mdoc: Introduction and RFC

[Jonathan Pryor]

I think the monodoc tools need an "umbrella" program, in the spirit of
svn or git, where instead of doing "monodocer ARGS" we could instead do
"mdoc update ARGS".

The reasons for this are threefold:

1. Many moons ago, I wrote man pages for many of the monodoc tools, and
was somewhat annoyed because there was no "umbrella" term/program to use
for the collection of apps.  In particular, monodocer, monodocs2html,
and monodocs2slashdoc (among others) should be able to reference the XML
schema used, but currently only monodocer does.  Certainly,
monodocs2html and monodocs2slashdoc could reference the monodocer man
page, but this doesn't seem "clean" to me; at minimum, the XML schema
docs should be in section 5, not section 1 (as is currently done), but a
`monodocer(5)' section just seems wrong.

2. I foresee adding additional programs, and don't want to pollute $PATH
with additional programs.

3. I (personally) find it annoying when related apps don't have a common
prefix.  Now, we have mdassembler, mdvalidator, monodocer,
monodocs2html...  The only common prefix is "m", which doesn't create
any association between them when using bash tab completion...

Consequently, I've written a `mdoc' front-end to most of these programs,
which has a _different_ set of command-line arguments than the
underlying programs.  The primary reason for the change is for
consistency, so that all of the mdoc sub-programs are similar.

Attached are two files:

  - mdoc.txt is the `mdoc help' output, listing all of the sub-commands.
  - mdoc.commands.txt is the `mdoc help COMMAND' output for each of the
    sub-commands.

Some changes I'd like to highlight:

  - `mdoc assemble' uses the same format for all directories, while
    `mdassembler' allows you to specify a different format for each
    directory; to compare/contrast:

        mdoc assemble -o netdocs --format=ecma corlib/en System/en ...
        mdassembler -o netdocs --ecma corlib/en --ecma System/en ...

    The added flexibility of mdassembler might be useful...if anything
    actually used it; monodoc/class does not.  By requiring only one
    format for all directories listed, this improves consistency with
    the other apps, as all of them take a trailing list of
    files/directories for various purposes (usually input files).

    This is also consistent with things like mdvalidator, which use a
    single provider for all remaining options.

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

Is there interest in this (or am I wasting my time)?  Any feedback on
the command names and the argument lists?

Thanks,
 - Jon


usage: mdoc COMMAND [OPTIONS]
Use `mdoc help COMMAND' for help on a specific command.

Available commands:

   assemble
   create
   export-html
   export-slashdoc
   help
   import-ecma
   import-slashdoc
   normalize
   update
   validate

mdoc is a tool for documentation management.
For additional information, see http://www.mono-project.com/

usage: mdoc assemble [OPTIONS]+ DIRECTORIES
Assemble documentation within DIRECTORIES for use within the monodoc browser.

Available Options:
  -f, --format=FORMAT        The documentation FORMAT used in DIRECTORIES.  
                               Valid formats include:
                                 ecma
                                 ecmaspec
                                 error
                                 hb
                                 man
                                 simple
                                 xhtml
  -o, --out=PREFIX           Provides the output file prefix; the files
                               PREFIX.zip and PREFIX.tree will be created.
                               If not specified, `tree' is the default PREFIX.
  -h, -?, --help             Show this message and exit.

usage: mdoc create [OPTIONS]+ ASSEMBLIES
Create or update documentation from ASSEMBLIES.

Available Options:
  -i, --import=FORMAT:FILE   Import documentation from FILE in the specified
                               FORMAT.  Supported formats include:
                                 ecma
                                 slashdoc
      --delete               Delete removed members from the XML files.
  -o, --out=DIRECTORY        Root DIRECTORY to generate/update documentation.
  -h, -?, --help             Show this message and exit.

usage: mdoc export-html [OPTIONS]+ DIRECTORIES
Export mdoc documentation within DIRECTORIES to HTML.

Available Options:
      --ext=EXTENSION        The file EXTENSION to use for created files.  
                               This defaults to "html".
      --template=FILE        An XSLT FILE to use to generate the created
                               files.  If not specified, uses the template
                               generated by --dump-template.
      --default-template     Writes the default XSLT to stdout.
  -o, --out=DIRECTORY        The DIRECTORY to place the generated files and
                               directories.
  -h, -?, --help             Show this message and exit.

usage: mdoc export-slashdoc [OPTIONS]+ DIRECTORIES
Export mdoc documentation within DIRECTORIES into /doc XML files.

The file created is based on DIRECTORY/index.xml, in the
(XPath) /Overview/Assemblies/Assembly/@Name attribute.

Available Options:
  -h, -?, --help             Show this message and exit.

usage: mdoc import-ecma [OPTIONS]+ ASSEMBLIES
Create or update documentation from ASSEMBLIES.

Available Options:
  -i, --import-from=FILE     Import documentation from FILE.
  -o, --out=DIRECTORY        Root DIRECTORY to generate/update documentation.
  -h, -?, --help             Show this message and exit.

usage: mdoc import-slashdoc [OPTIONS]+ ASSEMBLIES
Create or update documentation from ASSEMBLIES.

Available Options:
  -i, --import-from=FILE     Import documentation from FILE.
  -o, --out=DIRECTORY        Root DIRECTORY to generate/update documentation.
  -h, -?, --help             Show this message and exit.

usage: mdoc normalize FILES
Normalize XML documents.

Available Options:
  -h, -?, --help             Show this message and exit.

usage: mdoc update [OPTIONS]+ ASSEMBLIES
Create or update documentation from ASSEMBLIES.

Available Options:
  -i, --import=FORMAT:FILE   Import documentation from FILE in the specified
                               FORMAT.  Supported formats include:
                                 ecma
                                 slashdoc
      --delete               Delete removed members from the XML files.
  -o, --out=DIRECTORY        Root DIRECTORY to generate/update documentation.
  -h, -?, --help             Show this message and exit.

usage: mdoc validate [OPTIONS]+ PATHS
Validate PATHS against the specified format schema.

Available Options:
  -f, --format=FORMAT        The documentation FORMAT used within PATHS.  
                               Valid formats include:
                                 ecma
                               If no format provided, `ecma' is used.
  -h, -?, --help             Show this message and exit.

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Joshua Tauberer-4]

Hey, Jon.

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?

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. And I don't even recall what -name does.

Josh
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Mario Sopena Novales-2]

Hi,

   I also think it is a good Idea. Go ahead.

On 21/02/2008, Joshua Tauberer <jit@...> wrote:

Hey, Jon.

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?

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. And I don't even recall what -name does.

Josh
_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[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


_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list

[Joshua Tauberer-4]

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

_______________________________________________
Mono-docs-list maillist  -  Mono-docs-list@...
http://lists.ximian.com/mailman/listinfo/mono-docs-list