[Mono-docs-list] Proposing a new documentation subsystem

[Jonathan Pryor]

On Sun, 2007-11-25 at 13:56 +0100, Valentin Sawadski wrote:
> On Sat, 2007-11-24 at 14:25 -0500, Jonathan Pryor wrote:
> > On Sat, 2007-11-24 at 16:16 +0100, Valentin Sawadski wrote:
> > > I don't like that idea because this might introduce some since x,
> > > removed in y, reintroduced in z.... patterns (Yes I know it is unlikely
> > > but still possible)
> > 
> > I've been doing some (minor) thinking about this.  What it primarily
> > would entail is duplicating the /Type/AssemblyInfo element to be a
> > per-member element as well, listing each and every version that the
> > element is within.
<snip/>
> > etc.  This perfectly handles the "introduce some since x, removed in y,
> > reintroduced in z" pattern, as it would only list the assembly versions
> > that the member was present within, i.e. x and z, but not y.
> 
> That's great if that can be done so easily :-)

The monodocer part should be a fairly minor change, probably < 100 LOC.
(Probably < 20.)  The browser part will be somewhat more involved,
mostly as it deals with XSLT, but I don't think it will be terribly
difficult either.

Sadly, I'm not sure when I'll get a chance to work on this.  Hopefully
before year-end.

> > > Is he still the only one in charge of the documentation approval?
> > 
> > Yes, afaik.  The reason for Miguel as a bottleneck is for copyright
> > concerns -- we don't want someone copy+pasting MSDN documentation into
> > monodoc w/o any form of validation before it's committed to svn.
> > Perhaps we just need a better automated validation system...but this
> > will be a concern no matter what format/architecture we have.
> 
> I know and maybe I should have expressed myself clearer because the
> point was that I was thinking this could be fixed as well in the new
> system.

It would be nice to fix this -- perhaps with some Bayesian comparison
function and a set of "editors" to approve the changes? -- but
regardless, I doubt that such an improved process would require a format
change. :-)

> I personally prefer it over the mono approach of documentation. However
> since /doc is used nowhere in the mono sources this is not an option for
> documenting mono.

/doc isn't used for a variety of reasons -- many of them listed in the
monodocer man page -- including ease of translation (/doc doesn't scale
to having multiple languages), and that *good* documentation is *very*
verbose (examples, etc.).  I find that it's not uncommon for the
documentation on a member to be longer than the member itself.  Do you
*really* want all that documentation within the sources?

Furthermore, if you have a web-based documentation editing system, I'd
*really* not want that ANYWHERE near my sources, as a bug in the doc
system could cause the software to stop compiling...

> > Furthermore, monodoc *already* supports 3rd party assemblies -- this is
> > how Gtk# and Mono.Fuse documentation, among other assemblies, is
> > integrated into monodoc.
> 
> I know that monodoc already supports 3rd party assemblies but I was
> thinking of measures that would enable 3rd party developers also to
> benefit from the documentation contribution.
> 
> Which means some that the documentation might contain some kind of url
> where contributions can be sent to. Apart from the current mono-only
> contribution.

This sounds easy enough -- extend the .source XML format to include a
URL to send edits to.  Then the problem "merely" becomes one of
documenting the transport format/protocol so that others can write
servers to integrate with monodoc.  I believe the current protocol is
SOAP based, so that may need to change....

> Another point of which I have been thinking would be to add 3rd party
> documentation without having to rebuild the browser and all the sources.

That's already possible.  Just add your (.source, .tree, .zip) set of
files to your $lib/monodoc/sources directory, and restart monodoc.
You're done.  Again, see how Gtk# and Mono.Fuse do things.

> Someway that users only have to open http://3rdparty.com/docs in the
> documentation browser and the browser downloads all the documentation
> and integrates them into the database backend.

This is a slightly different problem.  It should also be solvable by
having the concept of a "local" sources directory in addition to the
system sources directory, e.g. ~/.local/share/monodoc/sources/, nd have
the local directory read before the system directory.  Again, solvable
(though I don't know how difficult this would be).

> Still thanks for the fruit-full conversation. :-)

No problem.  I'd love to dedicate more time to to monodocer/etc., but
sadly I lack the time.  Hopefully I can dedicate some time later this
month, but I also have a 2nd baby due soon, so any potential free time
is likely going to disappear...

 - Jon