[Mono-docs-list] Best way to contribute Mono documentation?

[Jonathan Pryor]

On Tue, 2010-01-19 at 21:32 -0500, John Feminella wrote:
> * Are these source and not generated files?

Yes (these are source) and No (they are ALSO generated).

>  That is, it was my
> understanding is that things in a path matching **/Documentation/**
> are generated by an external documentation-generation tool. If someone
> later updated the source, wouldn't that cause problems with the
> resulting generated files? Is this a mistaken view?

Behold the power of XML!  Or something.

Both humans and mdoc process the *same* XML files.  mdoc will add and
remove <Type/> and <Member/> elements from the XML (as types and members
are added and removed from the assembly), and a whole host of other
things.

The *only* elements that should be edited by hand are the //Docs
elements, and mdoc is written to not change the contents of these nested
elements [0].

In general, it seems to work.

> So, to me it sounds like the take-away conclusion to draw from your
> earlier e-mail are:
> 
> * Don't use `monodoc --edit`.

Yes.

> * Do use `mdoc update` + documentation stubs.

Yes.

> * Maybe use inline XML + `mdoc update -i MyType.xml`.

Maybe; depends on the project, and which you want to use as the
"canonical source" -- which should people edit, the inline XML or the
mdoc repository XML?  Having both be "canonical" is a recipe for
confusion.  (Not to say that this should NEVER be done, but just be
careful about it [1].)

Mono wants the canonical source to be the **/Documentation/en/* files;
other projects may want the canonical source to be inline XML.  This
will vary by project.

> * Chug out docs by filling out the stubs mdoc generates. You can use
> `mdoc export-html` to see how it all looks once you're making
> progress.

You can also use 'monodoc --edit' to *view* the documentation.  It works
quite well for that, and should be faster as well.  I just suggest not
using 'monodoc --edit' to *edit* documentation.

> * Find an assembly or two (or perhaps even an ancillary project like
> Cadenza) and just jump right on it, mailing relevant patches to the
> appropriate committers as needed.
> 
> Is that about the gist of it?

Pretty much. :-)

 - Jon

[0] This doesn't always work quite as well as I'd like.  Part of the
issue is that mdoc uses System.Xml to load the XML documents (of
course!), and System.Xml occasionally has "interesting" definitions of
significant whitespace vs. insignificant whitespace (which I'm sure is
standard compliant, it just doesn't match *my* desires for whitespace
handling).

This means that, while you won't _lose_ your changes to the XML files,
the nesting of XML tags may *change* when mdoc processes the files next.
Again, you WILL NOT LOSE anything, but e.g. diff(1) MAY show
differences.

I generally find that this happens most frequently with <list/>, where I
would write:

        <list type="bullet">
          <item><term>
            This is a bulleted item!
          </term></item>
        </list>

and when mdoc next processes the file it will be turned into:

        <list type="bullet">
          <item>
            <term>
            This is a bulleted item!
          </term>
          </item>
        </list>

Nothing lost, and (as far as XML is concerned) not a semantic change,
but it is "uglier" to me.

[1] For instance, Cadenza tries to keep all the canonical documentation
within the mdoc repository, EXCEPT for machine-generated types like
Tuple<...>, Either<...>, Delegate extension methods, etc.  This allows
the generator to ALSO generate the documentation, so there is still the
expectation that humans shouldn't change the inline XML, BUT for these
generated types the "canonical" source is the inline XML.