[JEDI.NET discuss] Documentation

[Marcel B. <ma...@ze...>]

All,

    I've been looking at the documentation issue. At first I was going for Doc-O-Matic because, well, I know that one and they
have donated free licenses to Project JEDI and it was good enough for JCL, JVCL, Jedi MATH, and Indy (yes Indy uses Doc-O-Matic to
deliver the rtf files to Borland). However, I've been having difficulty in getting the output the way I want to (which is much the
same as the .NET Framework SDK Documentation). So I started looking for other solutions and came across NDoc (http://ndoc.sf.net;
yes, it is Open Source). It generates the output exactly they way I want to, except for one, tiny little detail: it doesn't
generate Delphi syntax.

    Seeing this is OSS, I figured I might take a stab at adding Delphi language support to it. Now, my C# is not the greatest, but
it is much better than XSL Transformations, and the generation of the html pages is done with these translations. Soooo, if any of
you on this list things he's good enough to add that in: please do. When getting the sources of NDoc, you need to look in the
ndoc/src/Documenter/NativeHtmlHelp2/xslt for the XSL transformations (BTW, the other Html-based documentation outputs also use
XSLT files, hint, hint).

    While on the subject of documentation: I wanted to use .uex includes
(http://www.hanselman.com/blog/PermaLink.aspx?guid=e5aebe9b-2bec-493c-bab1-3cbf88f459c1) directly from the source files.
Unfortunately, Delphi XML generation is not following the standard set by MS, in other words: it doesn't matter if I use '///
<include...>' or '/// <summary>' in the source, the resulting XML is just not usable with NDoc (for one thing, Delphi generates a
completely different schema, where it changes the '<summary>' tags into '&lt;summary&gt;' and secondly it generates an XML file
per namespace, instead of one for the entire assembly).

    I see two options: write a tool to generate/update the xml templates by reflecting an assembly or write a tool to combine the
various XML files, translate them and generate the single new XML file. Or does someone know of such a tool (either one of them'll
do).

--
Marcel Bestebroer (Team JEDI) http://delphi-jedi.org
Project JEDI Help coordinator
JEDI.NET team coordinator