Paul A Bristow wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: 04 November 2008 10:10 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs?
Paul A Bristow wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Eric Niebler Sent: 03 November 2008 19:19 To: boost@lists.boost.org Subject: Re: [boost] location for PDF docs? Since we don't have an automatic indexing system for Quickbook (or other) documentation (A GSoC project?),
Boostbook docs have automatic indexing system, for some definition of 'automatic'. Please see
http://www.boost.org/boost-build2/doc/html/ix01.html
Each index entry must be explicitly provided in the source (where the index term is defined). However, collection of all index entries at a single page is done by some magic.
This *looks* nice - but
1 I don't see where to define the index entries. Can you point me to the instructions for this.
In docbook, you put something like: <indexterm> <primary>main target</primary> <secondary>declaration syntax</secondary> </indexterm> Docbook documentation has the details.
2 It will be hard work for a 500 page document :-(
(We already have a several libraries that are this big - and it is for big documents that indexing is most useful).
Of course. I'm not claiming searchability of PDF is useless -- in fact, I think PDFs have a number of advantages, including searchablility, printability, and presence of annotation tools -- and it's deplorable that we don't officially provide PDF for everything. It may be a problem with fop, or some other issue, I don't know.
3 Would it be more practical if the author had a list of all possible index terms from the document and could then generate a subset by *excluding* ones that are not considered worth an entry. Could Quickbook or some other tool output this list? Once generated, this 'exclusion list' could be re-used?
Will that work. Say, in Boost.Build case, "main target" is used everywhere, so adding all locations to the index won't work very well. Often, the phrase to appear in the index is not exactly the phrase present in the text. And while usually, a term should be defined on the first use, it could be that the first definition is brief, and the accurate definition is present later. Boost.Build index is bit lean presently, and I'd love to have some automated tool, but I'm not sure how they could work. - Volodya