Re: [ndoc-devel] Custom documentation topics with NDoc and MsdnDocumenter

[Atanas I. <ata...@gm...>]

First of all, many thanks for the comoprehensive reply :)

I agree with your point, but if I understood it correctly, it assumes that
the custom topics are already present in a ready-to-read form (html) - the
problem I'm trying to solve is in the previous stage of the documentation
process.

The reason for the decision to use NDoc for something like this, is the ide=
a
that we should apply for the custom topics the same principle which lies
behind C# xml comments:

DEVELOPMENT->ARTIFACTS->TRANSFORM->USABLE OUTPUT

where artifacts are par ex. code and docs - both in a well-defined, but
"raw" format like c# for the first and xml for the latter. In step #3, code
is transformed by the compiler and docs by tools like NDoc.

It seems logical to create custom topics in xml and then transform them
(with xslt) to html, so they can be merged with the code-related content.
However, XML docs->xslt->html is exactly what NDoc does...

So, if we want to start with xml and end with html which is in the
same style as
the code comment pages, all the xslt files should be copied from the NDoc's
sources and used by another tool which will contain the same logic as NDoc
(because it will have to perform the same transform of xml into html). This
was the first approach used (which I personally tried). However, I decided
to abandon it, because I didn't like the idea to write a tool which has as
functionality a subset of something already existing.

The "upgrade" to NDoc costed (yes, it is already completed) less than 2
days of the time of a single developer, which in all cases is less than the
effort which would be needed for the creation of a custom tool with the
capabilities required.

I consider NDoc and the different help compilers (and formats) as pieces
which from most of the puzzle named "automated documentation process", but
have the feeling that something is still missing. Maybe a solution with a
freely extensible and customizable transform pipeline which would be able
to handle virtually any kind of (xml) input and produce any kind of
documentation?

Best Regards,
Atanas Ilchev


2005/12/29, Heath Stewart <clu...@ho...>:
>
>  You don't need NDoc to do this job. If you're compiling CHMs you can
> decompile them using the HTML Help Workshop available from
> msdn.microsoft.com (this can even be automated) change the TOC (it's an
> HTML file - maybe even well-formed enough to be XML...I don't remember of=
f
> hand) and add in your other HTML pieces. If you're using the Msdn2
> documentor you can create your own HxS and HxI files and integrate them p=
er
> instructions for HTML Help2. The Visual Studio Combined Collection, for
> example, merges many TOCs and content files for VS itself, and the MSDN
> Library merge itself into the VSCC. Third parties can also do this.
>
> HTML Help (CHM) can do this with the proper application. Old MSDN Library
> used to do this.
>
> My point is don't make NDoc do something for which it's not intended when
> ways of doing this already exist. The tools exist and can be called via
> automation (like a batch script) to do what you need. This also allows yo=
u
> to decouple your other, non-API documentation from your API documentation
> which will, of course, change over time (though your other content may
> not...at least as much).
>
> My recommendation is to use HTML Help 2 if you can. Currently this does
> require either the .NET Framework SDK 1.0+, VS 7.0+, or recent (i.e., the
> last several years) MSDN Library (a couple other apps may come with
> it...don't remember off hand) but if you're developing a third-party cont=
rol
> for VS or .NET it's likely you can depend on Document Explorer being ther=
e.
>
> Sorry, but I'm not aware of any plans to yet release Document Explorer as
> a third-party redist (like HTML Help 1.x).
>
> ---
> *Heath Stewart
> *Software Design Engineer
> Developer Division Customer Product-Lifecycle Experience
> Microsoft Corporation
> http://blogs.msdn.com/heaths
>
> ------------------------------
> From: *Atanas Ilchev <ata...@gm...>*
> To: *ndo...@li...*
> Subject: *[ndoc-devel] Custom documentation topics with NDoc and
> MsdnDocumenter*
> Date: *Thu, 29 Dec 2005 15:03:34 +0200*
>
> Hi All,
>
> I'm responsible for a small team, which works on another open source
> project (http://sourceforge.net/projects/cybercore). However, as we all
> know, the whole effort is of a little value without a proper
> documentation...
>
> When it comes to documentation, NDoc is the tool which will play the
> central role (no surprises here). The problem is that currently NDoc can =
be
> used for only what I call "API refernce", which is far away from what I
> consider to be the necessary minimum.
>
> So I've assigned to one of the developers the task to "upgrade" the msdn
> documenter in such a way, which will permit us to create custom topic tre=
es
> in the TOC - they will lead to not-directly-code-related info (but with
> possible liks to the API reference). Here is the place to say, that she
> started to show some quite serious pregress...
>
> Regarding all this, I would like to ask 2 questions:
> - Is there something like this already realized? I do not like the
> possibility to come out with a re-invented wheel at the end...
> - Because this "enchancement" seems like a very serious candidate for
> contribution, is there such planned feature (i.e. - is there a need for
> such a contribution)?
>
>