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

[Valentin Sawadski]

Hello,

On Sat, 2007-11-24 at 14:25 -0500, Jonathan Pryor wrote:
> 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.

That's great if that can be done so easily :-)

> 
> > >  >  - 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.

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.

> >  - 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.

Sorry that's been a typo I originally wanted to write monodocer.

>   (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).

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.

> 
> >  - 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.

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.

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.
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.

> 
> 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.

SQLite was just an example data format. In general I was thinking of
some database back-end and forgot that changing the database was not
possible since this would require root access in most cases. Because
that was the point that would bring us most advantages, all changes
would be contained in one generic database (where generic means that it
would contain the documentation of several assemblies and more) which
could easily be filled with data from different sources and yes I was
thinking of keeping the revision control within the database so that
users could view older revisions of the documentation while browsing
(just like in a wiki).

All in all I now do think that...
 - the fact that the database could not be changed as well will kill the
   biggest benefit I saw in it.
 - most issues I addressed really don't require rewriting the format 
   from scratch
 - and I should have slept this over one night before posing it to the
   list.... >_>

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

Kind Regards,
Valentin S.