From: David Bergman (davidb_at_[hidden])
Date: 2002-11-03 13:44:45
> 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
> 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
> 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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk