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

From: David Bergman (davidb_at_[hidden])
Date: 2002-11-02 00:58:27

Jeff,

We could use both, as long as they would produce the exact same DocBook
in the end AND use the exact same tags.

It is important to know (1) what tags to use (i.e., the syntax (Qt,
Javadoc etc.) and recommendation what to document) and (2) what output
it should produce. I am not sure whether Doug's proposal deals with
these two issues.

As said, I like Doxygen, and will give it a try alongside Synopsis on
some other libraries...

I just have to get the Synopisis installation working, since we do not
have that EXE/RPM/ installer for that tool yet ;-) 

/David

-----Original Message-----
From: boost-bounces_at_[hidden]
[mailto:boost-bounces_at_[hidden]] On Behalf Of Jeff Garland
Sent: Friday, November 01, 2002 9:51 PM
To: Boost mailing list
Subject: RE: [boost] Re: Reference documentation: one approach

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

As I said before, we don't really need to choose one extraction tool or
another.  We can use one or both.  I think the point that is being
missed here is that Doug has a proposal on the table, but to my eye 
it looks like mostly an extension of DocBook.  What I see in Doug's
stuff looks like solid XML, but I don't understand how DocBook 
extends so I'm just a little worried that the standard DocBook 
tools will be less useful than we think...

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

For my purposes, Doxygen will work fine so I'm not planning on 
giving it up now.  (And I have plenty of template code -- not 
meta code, just regular templates see:
http://www.crystalclearsoftware.com/libraries/gdtl/gdtl_ref_guide/classb
oost_1_1date__time_1_1date.html for example)

And please, if you find bugs with the template handling in a recent 
release of Doxygen be sure to report them.  The developer of Doxygen 
is very responsive and helpful in fixing issues. There are regular
weekly releases for bug fixes and enhancements.  And, I'm certainly 
willing to try Synopsis.  Let me know when I can download an RPM for 
Linux and an exe installer for windows.  

Jeff   
_______________________________________________
Unsubscribe & other changes:
http://lists.boost.org/mailman/listinfo.cgi/boost