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

From: David Abrahams (dave_at_[hidden])
Date: 2002-11-02 15:20:08

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

> Doug,
> 
> A very nice graph (I am not as good at ASCII graphing...)!
> 
> I agree with your CPPXML layer. 

I assume by CPPXML you mean what Doug has labeled "C++ XML"? It's
important to keep our terminology straight or we'll all get confused.

> For cross-referencing, though, it would be beneficial to then
> operate on that CPPXML level, since we there have the semantics
> preserved (i.e, a template is still a template, and a specialization
> a specialization). That way we could list all specializations for a
> template, for instance.

Sounds reasonable.

> I do believe that this CPPXML of yours should be a proper extension
> of DocBook, in the sense of super-language, so all DocBook documents
> are valid CPPXML documents. This to enable developers writing the
> high-level specifications, which cannot/should not be extractable
> from the source code in DocBook, and use the CPPXML extensions to
> express C++-specific constructions and still use the same
> transformer XSL (the arch between your "C++ XML" and "DocBook XML"
> nodes) as the generated documentation.

I don't get it. Firstly, I am not sure I agree that "high-level
specifications cannot/should not be extractable from source code". It
may just depend on the quality of comments in the source and the power
of source transformation directives made available by the extraction
tools... though I'm not at all sure of this. Secondly, I can't parse
the final phrase: "and still use the same transformer XSL as the
generated documentation".  

The subject of the sentence is "developers". You are saying you want
them to be able to use the same XSL as the generated documentation
does? I can't understand the idea of "developers" and "documentation"
both using an XSL in the same kind of way. Or you're saying that you
want them to be able to utilize the XSL as generated docs? That
doesn't make any sense to me either.

> So, we should extend DocBook, *but* with your preprocessing XSLs, so we
> can still enjoy the DocBook stylesheets and tools from the next node.

As someone with little experience in this area, I have to say I have
no clue what you're driving at. Could you clarify?

-- 
                    David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com