RE: [boost] Re: Reference documentation: one approach

From: David Bergman (davidb_at_[hidden])
Date: 2002-11-01 19:49:57

Dave,

There seems to be only two viable choices, if we indeed want a
"tag-and-structure" extracting tool: Synopsis and Doxygen. This choice
is probably independent on whether we want to use DocBook or TeX as the
format for the entry point of developers. [even though the route to
DocBook is easier for Synopsis and the route to TeX easier for Doxygen]

And, unless someone (Jeff et al.) can come up with some new, positive,
information regarding Doxygen's handling of templates, this choice will
not be too hard...

I will test the CVS head of Synopsis, as I used the (presumably old)
0.4.1.

Thanks,

David

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of David Abrahams
Sent: Friday, November 01, 2002 6:53 PM
To: Boost mailing list
Subject: Re: [boost] Re: Reference documentation: one approach

"David Bergman" <davidb_at_[hidden]> writes:

> Dave,
> 
> Did you have such a "patched" version of Synpsis somewhere?

Did I? Yes, I did. All of my patches have been in the Synopsis CVS for
some time now, though.

> I could not get Synposis to work "out-of-the-box".

You need a few other libraries to get going, e.g. graphviz.

> I used Doxygen to produce HTML (directly) and PDF (through pdftex) 
> documentation of the 1.29 version of Boost.Python. It was not a very 
> interesting document... Doxygen seems to not acknowledge templates as 
> "compounds", so one basically get a list of the files involved in the 
> project. Not very useful for Boost, in other words. I used it in 
> non-template libraries, and with other languages, and it is quite 
> good, with inlined code, keeping the links.

That corresponds roughly to my experience of several years ago.

> It is a pitty that the Doxygen group has not put much effort in 
> handling templates, since Doxygen is a more supported tool than 
> Synopsis. I think the Boost group has to more or less adopt Synopsis 
> to make it viable as a documentation generator...

Maybe so. I think it might be worth it.

-- 
                    David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost