Hi,
On 01/24/2011 02:02 AM, Paul A. Bristow wrote:
... elision by patrick... So I feel we need to encourage library authors to produce:
1 PDF version as well as HTML (and so use Quickbook?).
2 Quickbook and Doxygen reference section.
2 Doxygen comments in C++ code about everything. (Perhaps GSoC or Boost.Guild people could volunteer to do this?).
3 Auto-indexing of functions.,classes ... as standard. (So we need to get auto-index into next Boost release package).
4 Conventional word index - Indexing of words in the text.
5 A user-friendly Quickbook template so new authors can get going quickly.
Perhaps others will volunteer to tackle the docs (you have to have a reasonable grasp of the library - I found I didn't have enough for Boost.Pool and would like some experts to correct and amplify my efforts.
It seems like we not only need a user-friendly Quickbook template, but a good tutorial document from someone that's fought through this and has found success. I'm working on it :-)
(but listing all the many, many pits on can fall into (been there, done that) with inscrutable diagnostics is quite a job!)
To the useful list of Paul I would suggest that there should be many more examples within the boost docs. So: 6: Enough clear examples We struggled too with generating the docs. But I feel now we have something useful combining Doxygen and Quickbook. I realize there are some other approaches, some of them translating to boostbook, some to quickbook, but that process (xslt) was hard. So in short how now Boost.Geometry doc's are generated: 1) C++ is commented the Doxygen way 2) Samples are created, the Quickbook way (compilable, might go back to quickbook, callouts, etc. are possible) 3) Doxygen is called, producing XML (the configuration file has an alias, \qbk) 4) A specifically developed (work in progress) tool *doxygen_xml2qbk* is called, converting the doxygen XML to quickbook 5) quickbook is called the normal way (using bjam, go to boostbook,docbook,html) This produces things as in: http://bit.ly/gJSmaa (follow the area link, or e.g. reference matrix - point) (note it is work in progress) I've added a sort of minimal sample showing the process, to that doxygen_xml2qbk tool, (currently) here: http://bit.ly/eGYBf5 The essence is that: 1) quickbook is created, not boostbook 2) the quickbook is created as good as possible (using xsl this seems to be quite hard (at least for me)), showing all that Doxygen shows 3) quickbook can be intermingled within Doxygen comments, and those quickbook pieces can (partly to do) go anywhere in the generated quickbook, e.g.: /*! \brief A useful function \qbk{[heading Example] } \qbk{[apple] [apple_output] } */ the \qbk alias (defined in Doxygen configuration) gives also the possibility to use e.g. the quickbook [include ...] clause (to avoid many lines of qbk here), and/or can span different lines (as done in the sample in the trunk) To define the place, the first argument of the alias(macro) might be a place-marker (e.g. before.synopsis) 4) the result is pure quickbook code based on doxygen comments and manually written quickbook markup. Regards, Barend