Re: [boost] location for PDF docs?

Subject: Re: [boost] location for PDF docs?
From: Paul A Bristow (pbristow_at_[hidden])
Date: 2008-11-05 05:31:19

>-----Original Message-----
>From: boost-bounces_at_[hidden] 
>[mailto:boost-bounces_at_[hidden]] On Behalf Of Vladimir Prus
>Sent: 05 November 2008 10:07
>To: boost_at_[hidden]
>Subject: Re: [boost] location for PDF docs?
>

>>>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.

OK thanks - I aw looking at BoostBook :-(

http://www.sagehill.net/docbookxsl/GenerateIndex.html#Indexterms

gives 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.

It's mainly getting the long toolchain working.  John Maddock, for one, has got it cracked - and with his help I'm also
re-generating the Math Toolkit library into html and pdf with no hassle.
 
>> 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.

Yup - it's never going to produce a really good index without some human intervention.

Even a way of marking a word as an index entry in the Quickbook source would be a major help.

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow_at_[hidden]