Re: Mailutils new competitor

[Sam Roberts]

Quoting Alain Magloire <address@hidden>, who wrote:
> > 
> > On Tue, Feb 13, 2001 at 11:20:36AM -0500, Alain Magloire wrote:
> > I've been thinking that I may write a 'javadoc' for C and C++ code.  This 
> > could be a nice way to learn bison. =)  Comments? 

There's two already, doxygen and doc++. Both generate html and latex,
and other formats as well, and understand and extend the javadoc syntax.

I don't think either generate docbook/sgml, unfortuneately, since
that can be translated easily into good quality html/ps/info/rtf/pdf.
I'm not sure about that though, its been over a year since I've
looked at them.

> But IMHO, they don't provide quality documentation in the tutorial sense.
> If someone has the time to change the framework for this, I will
> follow the rule.

Well, doc++ would generate a document base on a kind of 'main' that
could include latex docs and the docs generated from the code. So
the chapter-like introductory stuff could be written and then
generated into a final form that included the more manual-like
stuff.

The thing that frustrated me at the time was that both of them
wanted to be the formatting engine, so instead of generating
ONE output format in some kind of reasonably standard format
like docbook, or texinfo, or even some kind of xml, you had
to hack the src to get formatting control. If they just
generated texinfo, then you could use all the existing tools
to convert to info format (my favorite docs, after postscript),
ps, html, etc.

I think some of the gnome-related projects were
generating docbook from src comments.

I'm a huge docbook fan, we converted all of our docs at the
last company I worked at into it (though not auto-generated)
and we could produce great ps,html,QNX helpviewer, and pdf,
which pretty much dwarfed the capabilities of 10,000 dollar
toolkits being used by all kinds of huge companies. Very
satisifying. My only gripe was the lack of .info format, and
then just before I left I found a reference to somebody
have written some kind of processor to generate that, but
I never got a chance to give it a try.

I confess to getting a fair way on a C/C++ yacc grammer
for a doc generator, after looking at the doc++ src code
and seeing some of the kind of C++ that convinces people
C++ is a bad thing, and it being unsupported, and under
a weird set of copyrights, etc. That said, doxygen
is GPL (I think) and is being maintained and developed,
and I'd take a look at it before redoing it, I know
the guy who maintains the debian package, and he's
a huge sgml fan, so who knows whats coming down the pipe.

Ciao,
Sam

-- 
Sam Roberts <address@hidden> (http://www.emyr.net/Sam)