[Mono-docs-list] 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

-------------- next part --------------
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/
-------------- next part --------------
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.