Re: [boost] location for PDF docs?

Subject: Re: [boost] location for PDF docs?
From: Vladimir Prus (vladimir_at_[hidden])
Date: 2008-11-05 05:06:51

Paul A Bristow wrote:

>  
> 
>>-----Original Message-----
>>From: boost-bounces_at_[hidden]
>>[mailto:boost-bounces_at_[hidden]] On Behalf Of Vladimir Prus
>>Sent: 04 November 2008 10:10
>>To: boost_at_[hidden]
>>Subject: Re: [boost] location for PDF docs?
>>
>>Paul A Bristow wrote:
>>
>>>>-----Original Message-----
>>>>From: boost-bounces_at_[hidden]
>>>>[mailto:boost-bounces_at_[hidden]] On Behalf Of Eric Niebler
>>>>Sent: 03 November 2008 19:19
>>>>To: boost_at_[hidden]
>>>>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