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

From: David Bergman (davidb_at_[hidden])
Date: 2002-11-03 13:44:45

Dave,

I wrote:

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

You wrote:

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

I now reply:

Regarding your "CPPXML" comment: I tend to avoid "+" and other such
signs when naming XML Applications. Sorry about that. I will use the
"C++ XML" name.

Regarding your first comment, I actually meant "high-level
specifications that" instead of "high-level specifications, which". In
other words, I agree that even high-level specifications can be
extracted when using good comments. *but*, for those cases where we need
to have supplemental specification parts tailored outside the commented
code, the author should be able to insert his document somewhere in the
chain. I hope you agree that any standardization should support
documentation *not* extracted from commented source.

Regarding your second comment, my phrase was not grammatically correct
and is thus not parsable, using a low-level English parser. One has to
switch to a higher-level, more heuristic parser ;-) Sorry about that,
but I will fill in the blanks: I want the author/developer, in those
(rare or not) cases where the structures and comments in the code need
to be supplemented by manual documentation, to (1) use "C++ XML" and (2)
to apply the "C++ XML --> DocBook" XSLT of Doug.

Then there is the question of merging and cross-referencing (XPath...)
of the manually produced documents and the
(Doxygen/Synposis/ReStructuredText-)generated documentaton. I think it
would be better to have the merge taking place at the "C++ XML" level...

I hope this clarified my take on this.

/David