RE: [boost] Reference documentation: one approach

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-10-31 08:29:26

> Front/back is a little weird here: The system's front-ends parse C++
> code (and code for other languages) as input. The back-ends generate
> output. So as I understand it, the front-end capture the comments and
> the AST, while the back-ends process the comments to extract the
> appropriate information.

Thx.
 
> OK. I wouldn't debate much anyway, since I'd be arguing with little or
> no data. I tried Doxygen once a few years ago and gave up quickly.

Right.  My feeling is you gave up too easily...
 
> > I'm back to my original view that we should ignore doc generation.
> 
> I'm certainly not going to ignore it, but I guess people may decide
> not to discuss it. Even if I only get really good implementation docs
> out of Synopsis, I'll be highly satisfied.

I'm very happy that you have time the time and energy to help
bootstrap Synopsis as an alternative.   

> > That is, I agree with Doug what we really need is a standard form
> > that generators can create or can be created by hand and then
> > massaged appropriately for output into html, pdf, etc.
> 
> I find the question of intermediate format uninteresting. Anything
> sufficiently rich will do, as long as I don't have to edit it

I disagree.  Is it Docbook, custom XML tags, Latex? I think it is 
critically important to nail this down b/c no one can reasonably 
write style sheets, generation tool customizations, or anything
else without this definition.  

> > Whatever. I could care less about the details of the syntax.  
> 
> I guess that's where our fundamental differences lie. I think that
> unless the syntax for the programmer is easy, accessible, and
> attractive, programmers won't use it at all.

I and many other programmers I find the doxygen syntax easy, 
accessible, and just fine.  You find it unattractive, but that 
is purely a mostly of taste. 

Jeff