[Mono-docs-list] State of Mono Documentation

[Mike Kestner]

On Fri, 2008-01-11 at 05:51 -0500, Jonathan Pryor wrote:

> I must apologize for this (being the one to make this change).

You weren't the first to add "whitespace" diffs to monodocer.  You won't
be the last.  To be honest, I've seen more whitespace coming from
System.Xml changes than from monodocer changes.  We could probably solve
most of these issues by exposing a stable monodoc XMLWriter so that
every tool that touches a monodoc file can use it.  

My larger goal is to only touch a monodoc file when there's a real
documentation change going in, as opposed to all the on-disk stubbing we
are doing now.

> My own personal plan at the moment is to write an umbrella command-line
> program 'mdoc' to better associate the current programs.
> 
> For example:
>   Old:                  New:
>   ---                   ---
>   mdassembler           mdoc assemble
>   monodocs2html	        mdoc export-html

The monodoc script already does many of these:

  monodoc --assemble
  monodoc --validate
  etc...

> I also want to update the command-line arguments of these apps to
> increase consistency, e.g. -o vs. -dest or -path, etc.

Consistency is good, but obviously I'm focused on the non-xterm using
community.  My suspicion is that the majority of potential documentation
contributors would prefer to not know what an xterm is.

> So my fear is that your integrated WYSIWYG editor would obsolete this
> idea.

>From a platform stability standpoint, I don't think we could remove the
scripts even if I wanted to, which I don't.  Any functionality which is
needed from the base scripts would be extracted into a library assembly
that could be used by the editor as well as the scripts.

-- 
Mike Kestner <mkestner at novell.com>