[Mono-docs-list] doctools: fork in the road?

[Joe Betz]

> Hello All,
> 
> Here is the deal.  I have been working diligently on all of the tools
and
> am
> ready to commit something to cvs.  I've also recently taken a look at
NDoc
> (GPL'd ndoc.sourceforge.net) as John Barnette has suggested and this
has
> led
> to an impending decision of sorts.  The NDoc stuff is very impressive,
> they
> have been coding for quite sometime and far along.  With that said,
here
> are
> the choices I see for the road ahead:
> 
> 1.  Continue building docstub, docgen, docconv, and monodoc.  -- The
Pro's
> for this are: We generate our own DTD/Schema for the xml which is
simpler
> and
> it makes it easier to code the docgen tool (combining reflection
metadata
> xml
> and extern documentation).  The NDoc stuff is written to combine the
/doc
> compiler option output of Microsoft's csc compiler with information
> generated
> via reflection metadata.  Mono's mcs does not have this feature, so a
> great
> amount of information would be lost to us, if we just went with NDoc.
The
> Cons:  Well, just that NDoc is farther along and it seems beneficial
to
> combine efforts wherever we can, which means we could also...

Yeah, I think in the long run we will want the most complete DTD/Schema
available.

> 2.  Use NDoc as our documentation tool.  This would imply that we
build
> /doc
> compiler output into mcs.  The Pro's for this are:  We get to
piggyback on
> all of the work that has gone on before.  The Cons are:  Not sure how
> trivial this would be, and I personally, don't like the look of
> NDocs/Microsoft's DTD/Schema.  I haven't been able to find a spec for
it
> and
> IMHO it looks like another convoluted Microsoft document format.  Of
> course

Are you referring to the MSDN output feature and related xslt's?  I
don't see much use for them in the mono project either since it requires
that Microsoft help browser, but that still leaves the xml and JavaDoc
output.

> we could just ask the nice folks at NDoc for more information, which
leads
> to
> ...
> 
> 3.  We could choose to adapt/extend NDoc to combine with our external
> documentation.  The Pro's:  Well, this way we don't have to worry
about
> mcs
> and the /doc output.  The Cons:  Once again, I think this would be a
> nightmare because of the convoluted DTD/Schema of NDoc/Microsoft.
Also, I
> haven't been able ot get NDoc built either with wine or on Windows...
They
> only use nmake and there stuff is already heavily tied to
Windows.Forms.

I don't know enough about mono (yet) to know exactly what would be
required to get NDoc working with mono but it looks like the console
interface could be used to get NDoc working until a new GUI could be
built for stuff like Qt.  That leaves nmake...  Unfortunately, I don't
know much about what this will require either.

> That is another plus for continuing on our own, command line tools,
which
> leads me to this...
> 
> Regardless the decision, if we decide to continue on our own, then I
will
> be
> adapting DocStub to use NDoc's backend for generating reflection
metadata.
> They already have this stuff figured out and it is quite frankly a lot
> better
> than my ad hoc backend.  Work on this has already begun and it is
fairly
> straightforward.

I haven't seen your doc tools yet but I am also quite impressed with
NDoc.  It looks like a really good place to build from.  IMHO NDoc
should be adapted to mono by fixing it to run in console form on mono
and adding support for external documentation, however external
documentation will work...

> I am itching to get back to work on the Qt Bindings so I'd like to get
> this
> all sorted out and done.  Well let me know what you all think and i'll
> commit
> to cvs as soon as I get some feedback.

Sounds good.

Cheers,
Joe