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

[Adam Treat]

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

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

Cheers,

Adam