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

[Jonathan Pryor]

On Sat, 2007-11-24 at 16:16 +0100, Valentin Sawadski wrote:
> On Sat, 2007-11-24 at 08:14 -0500, Joshua Tauberer wrote:
> > I think you're making it too complicated:
> > 
> >  >  - Insufficient support for "Multi-Version" files (e.g. Class-Libs
> >  >    from .NET 1.1 and 2.0) because the current "Since Version X.Y" does
> >  >    not work if a member is only available in 1.1 and not in 2.0.
> > 
> > This just requires the addition of more tags to the documentation, one 
> > that says when a member was removed.
> 
> 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.  This should be trivial to do -- monodocer would just
insert the current assembly version into this element if it's found, and
if the member _isn't_ within the current assembly monodocer would ensure
that the <AssemblyInfo/> element is NOT present for the current assembly
version.

Monodoc display could now be:

	Requirements:
	  Namespace: ...
	  Culture: ...
	  Assemblies:
	    mscorlib 1.0.500.0
	    mscorlib 2.0.0.0
	    mscorlib 2.1.0.0

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.

> >  >  - Automated user-contributions do not work properly (I don't know if a
> >  >    contribution has ever made it into the documentation).
> > 
> > The current system isn't bad fundamentally. I think there's just some 
> > personal overhead involved in Miguel taking the contributions and 
> > applying them.
> 
> 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.

> >  >  - Documentation work-cycle is pretty complicated. It is very unhandy to
> >  >    run many tools to do one simple task. (monodoc, browser, mdassembler)
> > 
> > Maybe....
> 
> Compared to the MS world it is really more complicated on mono. A simple
> "/doc" compiler flag and running nDoc would suffice on windows.

Mono isn't much more complicated, if that's what you want:

	gmcs /doc /t:lib YourAssembly.cs
	monodocer -importslashdoc:YourAssembly.xml -assembly:DocTest.dll
	mdassembler --ecma en -o YourAssembly-docs
	monodocs2html -source:en -dest:/path/to/html/docs

You only need one of the latter two commands; mdassembler is to view the
docs in monodoc, and monodocs2html is for static HTML output.  If you
want to use an ASP.NET server (as http://www.go-mono.com/docs does), you
don't need either of these commands.

The problem typically isn't the _format_ of Mono's documentation, the
problem is _writing_ the documentation in the first place.  Saying "use
the /doc compiler flag" isn't a solution, as you still need to _write_
the documentation within your source files, which doesn't permit WYSIWIG
editing of the documentation.

Afaik, NDoc doesn't support that either, which is why monodoc is nice --
it *is* a WYSIWIG editor for Mono-formatted documentation:

	monodoc --edit path/to/monodoc-format/docs

> > My two cents if you really want to address some of these things would be 
> > to start on the UI side and make something that works "properly" with a 
> > plain ZIP file of the XML documentation files, and no changes on the 
> > server or mdassembler side. Once that works, if you need to cache some 
> > indexes or whatever to be able to get to pages quickly, or if you need 
> > changes to the XML documentation format, then look into that. A 
> > documentation browser should be a simple program at its core.
> 
> Yes you are right the documentation browser should be as slim as
> possible. However I still do think that the current xml-only approach
> does not work sufficiently because of the limitations mentioned in my
> first mail. A small database back-end could provide a lot more
> opportunities for the creation and maintenance of documentation.

I'm still not convinced.  Your original list:

>  - Insufficient support for "Multi-Version" files (e.g. Class-Libs
>    from .NET 1.1 and 2.0) 

Above is a potential solution for this.  I just need to implement it.

>  - Generic Types and Members are not fully supported in the
>    documentation browser.

That's not a documentation format limitation, that's a browser
limitation.  The browser just needs to be updated.

>  - Automated user-contributions do not work properly (I don't know if a
>    contribution has ever made it into the documentation).

Again, this isn't a problem with the format, but of the infrastructure.

>  - Even if documentation has been updated the updates won't make it back
>    to the user before a new version of mono has been released. (With
>    other words, there is no way to update offline-documentation)

Also not a problem with the format.  Monodoc largely reads ZIP files
containing the documentation, so if you want updated docs you just need
to update the ZIP files.  It should be trivial to implement support into
Monodoc to download & use updated ZIP files; the problem is one of Unix
permissions (distro-provided files will be owned by root, and thus can't
be updated by normal users).  Regardless, it's solvable w/o a format
change.

>  - Documentation work-cycle is pretty complicated. It is very unhandy to
>    run many tools to do one simple task. (monodoc, browser, mdassembler)

I think you're confusing things.  monodoc *is* the browser, and is NOT
needed for the editing process.  (It's nice to have, as it's a WYSIWIG
editor, but it's not necessary -- I regularly use gvim to edit the raw
XML.  It would be nice to improve it's WYSIWIG capabilities; it displays
the formatting, but it doesn't permit adding new sections, such as the
<exception/> elements, etc.)

So if you don't care about editing -- you earlier mentioned 'CSC /doc'
as being superior, and that has NO WYSIWIG editor -- you don't need
monodoc.  Just monodocer and monodocs2html (for HTML output), xsp (for
ASPX output), or mdassembler (to browse docs within monodoc).

>  - No Revision control (this is not a big turn-off however it would be
>    quite handy when user-contributions will finally work) and no user
>    comments (again not very important but nice to have)

It's XML.  It's inherently compatible with revision control, as it's
text. :-)

I've been improving the revision control question over time as well,
such as by sorting documentation members so that smaller patch files are
generated when committing the updates to svn.

All this is to say that I don't see any need to change the format --
extend, yes, but not completely change -- nor do I see what advantages a
local SQL database would provide.  A local database would have ALL the
same problems as current monodoc wrt updating contents (normal users
can't update root-owned files, and all files installed by the package
manager are owned by root).  A database also complicates the revision
control question, as far as I'm concerned -- how do you *easily*
integrate e.g. SQLite with Subversion or git?  (Storing the entire
revision history within SQLite is NOT a "revision control" solution, as
far as I'm concerned.)

Furthermore, monodoc *already* supports 3rd party assemblies -- this is
how Gtk# and Mono.Fuse documentation, among other assemblies, is
integrated into monodoc.

So aside from entailing lots of work to re-find the same problems we
currently have (a WYSIWIG editor which still needs improvement, solving
the update problem), what does changing the format buy us?  What does
SQLite permit that XML doesn't?

Please enlighten me.

Thanks,
 - Jon