Review request: auto-index tool
I'm not sure if we're doing reviews of tools - we haven't in the past - but I thought it would be good to get feedback anyway... Auto-index is a tool for semi-automating the task of adding an index to quickbook/boostbook/doxygen/docbook documentation. Auto-index acts at the docbook level to scan for terms in a concordance script-file, but can also scan headers for classes, typedefs, functions and macros to index and a lot more besides. Auto-index supports multiple indexes (for example class, function, macro and typedef indexes out of the box), and can either delegate the actual index formatting to the XSL stylesheets, or produce the index itself (faster, also better looking for HTML indexes). Code is in the sandbox under tools/auto_index, documentation can be viewed online at: http://svn.boost.org/svn/boost/sandbox/tools/auto_index/doc/html/index.html Currently the math, type_traits and spirit libraries are using this tool in trunk to produce indexes - take a look at those libraries to see the sort of indexes produced. Cheers, John.
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 :) Hey John. As one of the users of this tool, I'd be happy to do an (informal) review of this. - -- Bryce Lelbach aka wash boost-spirit.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAk05f5oACgkQ9cB/V3/s9Ewa3ACggRbLOaHLW+6hTQitJfRWDAZK eWcAnj4IquGeAY4nI8GTHQW25jnjO0Cx =7QDz -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 John, please find attached a patch plus a short summary of notes. More extensive comments: Jamfile - ------- While auto-index is still not a part of boost, I think you should check for the environmental variable BOOST_ROOT so that users can checkout auto-index and use it outside of their boost-trunk source tree. I see that you had: local boost = [ modules.peek : BOOST ] ; I've never seen the above done before to locate boost. I usually use: import os ; local BOOST_ROOT = [ os.environ BOOST_ROOT ] ; I'm sure volodya could tell us which is more portable. Other problems with the Jamfile; the targets for rgeex, filesystem and system are bad for GCC and clang (copious linker errors). Instead of: $(boost)/libs/regex/build//boost_regex $(boost)/libs/filesystem/build//boost_filesystem $(boost)/libs/system/build//boost_system you should have: $(boost)//regex $(boost)//filesystem $(boost)//system This leads to a successful build for me with gcc and clang. This is how the wave tool specifies libraries to be linked, so I'm assuming this will work fine on MSVC, etc. Source Code - ----------- The long initializer for the 257-element boost::array<> at line 168 in auto_index.cpp is painful to look at, and raises warnings with clang. I suggest reformatting it. A few other places in the code have painfully long lines (see: attached patch). Why aren't you using program_options for the command line argument parsing? Is there a particular rationale here, or is this something you didn't consider? All in all, the code does what it's supposed to (we've experienced no bugs/problems with this tool in the Spirit docs yet that I know of). However, I do have reservations about the design of the tool, though I suspect these reservations may be entirely stylistic. I have similiar reservations about other Boost tools, so perhaps I am biased. I feel like this code, while usable, is not particularly extensible. It feels like (no offense) a typical C application; copious use of source-file local global-namespaced functions and globals instead of tying said functions and globals together into classes which could be reused and hard-coded defaults preferred to more generic, configurable code. This is intended as a tool, and not a library, so this is understandable, moreso because the tool does exactly what it's supposed to do. On the other hand, I'd rather see a tool that is a library. An excellent example of this design model is the Clang project. Clang is a C language compiler, and at first glance it would appear to be "application" software. However, it is, in fact, "library" software; Clang is, first and foremost, a set of libraries which are designed to be reusable and extensible. The Clang driver (aka the "tool") is just an application that makes use of the Clang libraries. Finally, as a Spirit developer, I feel the need to make a shameless plug for my library :x. I wonder if some of the regex code used in auto_index (in particular, the stuff in file_scanning.cpp) wouldn't be better implemented with Spirit or Xpressive. I see a lot of regexs hard coded in strings, which implies a runtime cost to parse those strings... that cost could be possibly be avoided by rewriting that code as expression templates with Spirit or Xpressive. OTOH, that's probably more trouble than it's worth. Finally, another optimization thing - I've noticed for the Spirit docs (193 terms), indexing can take a while. Nothing too excessive, but certainly a noticable amount of time. As auto-index seems to currently work as intended, and there appear to be no bugs in it, perhaps investigating some optimizations to increase the speed of indexing would be prudent? I hope this feedback is helpful John. This is a great tool, and it has excellent and extensive documentation. I would hope that it would ship with Boost 1.47. Sincerely, - -- Bryce Lelbach aka wash boost-spirit.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAk05kcMACgkQ9cB/V3/s9ExzNgCghvdSB9TGbREtPqPf8Dldv/xp 8OoAn0ok5u76QHhiSVyO6H4TDvHrlz8l =gBBq -----END PGP SIGNATURE-----
At Fri, 21 Jan 2011 09:01:39 -0500, Bryce Lelbach wrote:
While auto-index is still not a part of boost, I think you should check for the environmental variable BOOST_ROOT so that users can checkout auto-index and use it outside of their boost-trunk source tree. I see that you had:
local boost = [ modules.peek : BOOST ] ;
I've never seen the above done before to locate boost. I usually use:
import os ; local BOOST_ROOT = [ os.environ BOOST_ROOT ] ;
I'm sure volodya could tell us which is more portable.
Either one can work, but John's way is better. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
On 21 January 2011 16:45, Dave Abrahams <dave@boostpro.com> wrote:
At Fri, 21 Jan 2011 09:01:39 -0500, Bryce Lelbach wrote:
While auto-index is still not a part of boost, I think you should check for the environmental variable BOOST_ROOT so that users can checkout auto-index and use it outside of their boost-trunk source tree. I see that you had:
local boost = [ modules.peek : BOOST ] ;
I've never seen the above done before to locate boost. I usually use:
import os ; local BOOST_ROOT = [ os.environ BOOST_ROOT ] ;
I'm sure volodya could tell us which is more portable.
Either one can work, but John's way is better.
We could be more consistent about environment variables - sometimes it's BOOST, sometimes it's BOOST_ROOT. Daniel
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Friday, January 21, 2011 10:14 PM To: boost@lists.boost.org Cc: John Maddock Subject: Re: [boost] Review request: auto-index tool
We could be more consistent about environment variables - sometimes it's BOOST, sometimes it's BOOST_ROOT.
We *SHOULD* be a lot more consistent about lots of things like this! The confusion is causes the non-cognoscenti is often terminal. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Bryce Lelbach Sent: Friday, January 21, 2011 12:44 PM To: boost@lists.boost.org Subject: Re: [boost] Review request: auto-index tool
:) Hey John. As one of the users of this tool, I'd be happy to do an (informal) review of this.
I'm also a user of auto-index and I'd like to hear your impressions. (I'd especially like to hear if you have used it to index the *text* of a Quickbook file (rather than functions, class etc...) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Bryce Lelbach Sent: Friday, January 21, 2011 12:44 PM To: boost@lists.boost.org Subject: Re: [boost] Review request: auto-index tool
:) Hey John. As one of the users of this tool, I'd be happy to do an (informal) review of this.
I'm also a user of John's Auto-index and I'd like to indulge in a few thoughts on indexing, and indeed Boost documentation in general. Boost documentation has improved markedly since Quickbook came into use, and was further improved when Doxygen was added. PDF versions are very conveniently self-contained and include all the invaluable hyperlinking that the html version has. (PDF versions are Quickbook's killer advantage?). (Aside - I note how few documents from government and corporate sites provide decent internal hyperlinking. Quickbook helps us do much better.) These two tools are especially useful for documenting big and/or complex libraries, of which there are an increasing number. But I think we still have some way to go, especially in the ease (or indeed possibility) of *finding* what one seeks to know. (As I've observed before, I still suspect we are *not* using Google to full advantage because the full documentation set (or even the partial PDF documentation set) is not being indexed (because it isn't visible except as a zip on Sourceforge?). I have struggled to find things I know are there somewhere. However this is a separate issue.) I've used and/or produced auto-indexes for Boost.Math, Boost.Units and the GSOC SVG_plot utility, and have recently converted the Boost.Pool docs from plain html to Quickbook with Doxygen and finally added auto-indexes. These are all big libraries and my brain isn't big enough to remember all the details - like Homer Simpson, my brain is full and if anything new comes in, some of the old stuff has to go! ;-) So I've also become a frequent *user* of the indexing as well as an author (with the advantage that I can remember that a piece of info exists, but can't remember where it is - and quickly get cross when I can't find it!). Doxygen Indexes well enough (some templated code can get it confused, and it is a bit picky about the position of the Doxygen comments). I prefer Doxygen's Standalone module layout, but then you don't get the nice structure and mark-up features for the text part that Quickbook provides. There are few libraries where simply feeding the uncommented header files provides effective documentation - despite what some authors hopefully imagine. With a Quickbook/Doxygen "reference" section, one can find the syntax of a specific named function. John Maddock's auto-index makes it very easy to find *named* things. But the *major unsolved need* is when trying to find something to which *you do not know the (function/class...) name*. Few functions have an obvious function, an obvious name or an obvious result. So just showing the structure of the classes etc. isn't much help deducing what functions do. My experience is that using the PDF version and searching with likely terms is often the only way to find things. But with the 500 + page documents we are now producing, the search takes some time, so an index of the *text* would still be useful. And while the syntax is useful, when you come to finding the pre-conditions, post conditions, and what does it do, our docs prove much less effective. This most valuable information for the user *can* come from the additional information provided as Doxygen comments. The disadvantage of doing this it that it clutters the code, often badly (though the use of syntax colouring allows even my brain to filter out easily. <aside> I *really, really, hate* the current syntax color for comments. We must to be able to let users choose easily. <\aside>). It also documents well for maintainers - a need that can only increase as more original authors get other lives. But I am convinced that Doxygen comments is the most effective next step. I've followed this for the SVG_plot package (a good example as it has zillions of functions, so many that I definitely can't remember them, even though I wrote many of them!). I've also added Doxygen comments to the classes and functions during conversion to Quickbook of the Boost.Pool library. This helps a lot IMO (and would much even better if someone more expert could expand these additions and correct my misunderstandings). Doxygen can even tell you which things you haven't yet provided a comment for, so we can ensure complete 'comment coverage'. (I have trusted that adding comments retrospectively should be a low-risk operation because any bad changes should be picked up by re-running the existing tests. I hope I'm not wrong about this!) Adding Doxygen-style comments is a laborious job, especially tedious as an after-thought activity, and requires a pretty details understanding of the workings of the code. So it is best done as the code is first written - new authors note! Finally I feel all the documentation still needs a conventional word index of the text part. I'm trying to (ab-)use John Maddock's auto-indexing for this. It won't be fully automatic - but doing it by hand is inconceivable. 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. (I don't feel I am alone in finding that it's pretty hard going getting setting up all the tools in place, jamfiles, correct links to tools and headers. Moving the code messes some 'would-be' relative address in jamfiles. Getting locations of images users graphs, equations, logos, admonitions, navigations, png versus svg images etc have caused me grief. The requirement to use only relative addressing means that there are loads of copies of image files bloating the file system. And to produce a packable html requires installing images and style sheet(s)). Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
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.
(I don't feel I am alone in finding that it's pretty hard going getting setting up all the tools in place, jamfiles, correct links to tools and headers. Moving the code messes some 'would-be' relative address in jamfiles. Getting locations of images users graphs, equations, logos, admonitions, navigations, png versus svg images etc have caused me grief. The requirement to use only relative addressing means that there are loads of copies of image files bloating the file system. And to produce a packable html requires installing images and style sheet(s)).
What a wonderful email. I would volunteer to put Doxygen comments in C++ code for someone. 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. Patrick
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Patrick Horgan Sent: Monday, January 24, 2011 6:03 PM To: boost@lists.boost.org Subject: Re: [boost] Review request: auto-index tool
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.
(I don't feel I am alone in finding that it's pretty hard going getting setting up all the tools in place, jamfiles, correct links to tools and headers. Moving the code messes some 'would-be' relative address in jamfiles. Getting locations of images users graphs, equations, logos, admonitions, navigations, png versus svg images etc have caused me grief. The requirement to use only relative addressing means that there are loads of copies of image files bloating the file system. And to produce a packable html requires installing images and style sheet(s)).
What a wonderful email.
:-)
I would volunteer to put Doxygen comments in C++ code for someone.
The structure that John Maddock has set up for Boost.Pool seems OK (except that I fear we will have some glitches when moving back to trunk, and any updates to trunk will need to be applied to the 'Guild' version too of course). A /Guild folder in boost-sandbox has folders for working copies, for example guild/pool with usual sub-folder structure (an exact copy of trunk). If any authors would like to offer their 'baby' to get the Doxygen and auto-index treatment? (Raw html-only libraries are more serious work, despite a conversion aid). 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!) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
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
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Barend Gehrels Sent: Monday, January 24, 2011 11:17 PM To: boost@lists.boost.org; boost-docs@lists.boost.org Subject: Re: [boost] Review request: auto-index tool
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.
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
+1 - at least !
We struggled too with generating the docs.
Reassured to hear that ;-)
This produces things as in: http://bit.ly/gJSmaa
But the results are worth it :-) However you haven't commented on the conventional word-in-the-text index ? Do you note feel a need for this? Did you try John's auto-index and reject it? Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
On 25/01/11 10:12, Paul A. Bristow wrote:
Barend Gehrels wrote:
This produces things as in: http://bit.ly/gJSmaa
But the results are worth it :-)
However you haven't commented on the conventional word-in-the-text index ?
Do you note feel a need for this?
I can't speak for Barend, but I feel there is a need for this. IMO, index is necessary in any technical writing.
Did you try John's auto-index and reject it?
I haven't myself yet. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org Member of ACCU, http://accu.org
hi Paul,
But the results are worth it :-)
;-)
However you haven't commented on the conventional word-in-the-text index ?
Do you note feel a need for this?
Yes, I think it is a good idea, and there is a need. But I didn't have the time yet for a close view.
Did you try John's auto-index and reject it?
Not yet. I'm curious how it will work, also in combination with our generated docs. Regards, Barend
On 1/24/2011 5:02 AM, Paul A. Bristow wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Bryce Lelbach Sent: Friday, January 21, 2011 12:44 PM To: boost@lists.boost.org Subject: Re: [boost] Review request: auto-index tool
:) Hey John. As one of the users of this tool, I'd be happy to do an (informal) review of this.
I'm also a user of John's Auto-index and I'd like to indulge in a few thoughts on indexing, and indeed Boost documentation in general.
snipped...
So I feel we need to encourage library authors to produce:
1 PDF version as well as HTML (and so use Quickbook?).
Is there some simple doc on how to produce PDF from 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?).
If by "Doxygen comments" you mean comments in the implementation portion of the code, I do not see the value of this to the end-user. OTOH perhaps you mean the normal Doxygen documentation which generates the Doxygen reference section.
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.
This would be very nice. In order to produce the docs for my sandbox libraries I borrowed from you and others but there really does not seem to be an official Quickbook template to use.
(I don't feel I am alone in finding that it's pretty hard going getting setting up all the tools in place, jamfiles, correct links to tools and headers. Moving the code messes some 'would-be' relative address in jamfiles. Getting locations of images users graphs, equations, logos, admonitions, navigations, png versus svg images etc have caused me grief. The requirement to use only relative addressing means that there are loads of copies of image files bloating the file system. And to produce a packable html requires installing images and style sheet(s)).
1 PDF version as well as HTML (and so use Quickbook?).
Is there some simple doc on how to produce PDF from Quickbook ?
It's just a: bjam pdf You do need an FO processor installed, see the setup instructions here: https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted You may also (purely for your own convenience) add an install rule to your Jamfile to copy the generated PDF somewhere accessible rather than the usual unmentionable directory it gets put in. Otherwise see for example the Boost.Math docs for some more Jamfile options. HTH, John.
On 1/21/2011 7:13 AM, John Maddock wrote:
I'm not sure if we're doing reviews of tools - we haven't in the past - but I thought it would be good to get feedback anyway...
Auto-index is a tool for semi-automating the task of adding an index to quickbook/boostbook/doxygen/docbook documentation. Auto-index acts at the docbook level to scan for terms in a concordance script-file, but can also scan headers for classes, typedefs, functions and macros to index and a lot more besides. Auto-index supports multiple indexes (for example class, function, macro and typedef indexes out of the box), and can either delegate the actual index formatting to the XSL stylesheets, or produce the index itself (faster, also better looking for HTML indexes).
Code is in the sandbox under tools/auto_index, documentation can be viewed online at: http://svn.boost.org/svn/boost/sandbox/tools/auto_index/doc/html/index.html
Currently the math, type_traits and spirit libraries are using this tool in trunk to produce indexes - take a look at those libraries to see the sort of indexes produced.
I am for this review also. I would like to use indexing in my libraries in the sandbox but have not done it because it would require the end-user to download your library in order to regenerate the docs. If auto-index were part of Boost it would be easier for potential Boost libraries in the sandbox to use it.
On 1/21/2011 7:13 AM, John Maddock wrote:
I'm not sure if we're doing reviews of tools - we haven't in the past - but I thought it would be good to get feedback anyway...
Auto-index is a tool for semi-automating the task of adding an index to quickbook/boostbook/doxygen/docbook documentation. Auto-index acts at the docbook level to scan for terms in a concordance script-file, but can also scan headers for classes, typedefs, functions and macros to index and a lot more besides. Auto-index supports multiple indexes (for example class, function, macro and typedef indexes out of the box), and can either delegate the actual index formatting to the XSL stylesheets, or produce the index itself (faster, also better looking for HTML indexes).
Code is in the sandbox under tools/auto_index, documentation can be viewed online at: http://svn.boost.org/svn/boost/sandbox/tools/auto_index/doc/html/index .html
Currently the math, type_traits and spirit libraries are using this tool in trunk to produce indexes - take a look at those libraries to see the sort of indexes produced.
I am for this review also. I would like to use indexing in my libraries in the sandbox but have not done it because it would require the end-user to download your library in order to regenerate the docs. If auto-index were part of Boost it would be easier for potential Boost libraries in the sandbox to use it.
Your users don't need to have auto_index installed. You can have a jamfile which looks at the command line options bjam was invoked with and use auto_index only if explicitly requested (i.e. bjam --enable-index). See the spirit docs how it can be solved. Regards Hartmut --------------- http://boost-spirit.com
I am for this review also. I would like to use indexing in my libraries in the sandbox but have not done it because it would require the end-user to download your library in order to regenerate the docs. If auto-index were part of Boost it would be easier for potential Boost libraries in the sandbox to use it.
FYI the code in Trunk for math/type_traits/spirit makes auto-index use entirely optional: if you build with "bjam --enable-index" then you need to have built and installed auto-index, otherwise the indexes just get completely ignored and don't appear in the output. HTH, John.
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Fri, 21 Jan 2011 16:35:08 -0000 John Maddock <boost.regex@virgin.net> wrote:
FYI the code in Trunk for math/type_traits/spirit makes auto-index use entirely optional: if you build with "bjam --enable-index" then you need to have built and installed auto-index, otherwise the indexes just get completely ignored and don't appear in the output.
John, docs for ^, if you want 'em: Index: auto_index.qbk =================================================================== - --- auto_index.qbk (revision 68353) +++ auto_index.qbk (working copy) @@ -183,6 +183,19 @@ defaults to "section", but could equally be "appendix" or "chapter" or some other block level element that has a formal title.]] ] +It is possible to make the use of auto-index optional in Boost.Build, to allow +users who do not have auto-index installed to build your documentation. One +method of setting up optional auto-index support is to place all auto-index +configuration in a the body of a bjam if statement: + + if --enable-index in [ modules.peek : ARGV ] + { + using auto-index ; + project : requirements + <auto-index>on + <auto-index-script>index.idx + ; + } [h4 Step 3: Add indexes to your documentation] - -- Bryce Lelbach aka wash boost-spirit.com -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAk05yl8ACgkQ9cB/V3/s9EwfXQCgqfDURZ09Bo7oUt4IsBZAoBEz X3EAnjq1z591SmBFAsIVFBm3spdRSseL =KBvH -----END PGP SIGNATURE-----
On 1/21/2011 11:35 AM, John Maddock wrote:
I am for this review also. I would like to use indexing in my libraries in the sandbox but have not done it because it would require the end-user to download your library in order to regenerate the docs. If auto-index were part of Boost it would be easier for potential Boost libraries in the sandbox to use it.
FYI the code in Trunk for math/type_traits/spirit makes auto-index use entirely optional: if you build with "bjam --enable-index" then you need to have built and installed auto-index, otherwise the indexes just get completely ignored and don't appear in the output.
Thanks, I will look at that and set my own jamfiles accordingly.
On 21 January 2011 12:13, John Maddock <boost.regex@virgin.net> wrote:
I'm not sure if we're doing reviews of tools - we haven't in the past - but I thought it would be good to get feedback anyway...
It's some time since I tried using it so this isn't a proper review. I think it will be a valuable addition to the documentation toolset and should be ushered in without delay. The results that I've seen work very well, from what I recall it wasn't too hard to use. It's based on the docbook standard so it should integrate well with external tools. The official docbook standard and implementation does seem a bit underdeveloped, but that can't be helped and, as far as I can tell, is unlikely to cause any real problems. A lot of the focus seems to be on indexing doxygen based documentation but it's also useful for indexing other boostbook and quickbook based documentation. It's quite easy to extend quickbook with templates, although when this is more established it might be worth building support into the language. I'm also wondering if there any improvements that could be made to boostbook, but that's something for the future. It would be nice to link to some more detailed documentation about the docbook tags. The official documentation isn't great but at least it fills in some information for anyone who wants to know more. I don't understand why you don't xml encode '&', '<' and '>', it's pretty simple to implement. Daniel
participants (10)
-
Barend Gehrels -
Bryce Lelbach -
Daniel James -
Dave Abrahams -
Edward Diener -
Hartmut Kaiser -
John Maddock -
Mateusz Loskot -
Patrick Horgan -
Paul A. Bristow