Re: [boost] [review][autoindex] AutoIndex review extended

Subject: Re: [boost] [review][autoindex] AutoIndex review extended
From: Barend Gehrels (barend_at_[hidden])
Date: 2011-05-15 11:41:11

On 15-5-2011 17:07, John Maddock wrote:
>>> 2) I also want to exclude all examples (nearly every page in 
>>> Boost.Geometry will have one; these examples of course also include 
>>> other "terms"; which should not be indexed on that page). Is there a 
>>> way to mark a qbk-block to be excluded from being indexed?
>>>
>>> Not at present no.... I'm not really sure how one would even do 
>>> that, there would have to be some kind of docbook XML container that 
>>> was used to represent "don't index this block".
>>
>>
>> A bit of hacking could enable this.
>>
>> If I add literal docbook-entries in QuickBook, like this:
>>
>> '''
>> <para role="auto-index-skip-begin" />
>> '''
>>
>> [heading Example]
>> [box_view]
>> [box_view_output]
>>
>> '''
>> <para role="auto-index-skip-end" />
>> '''
>>
>>
>> The para entries are included in my final docbook XML, on the right 
>> places, like this:
>> <para><para role="auto-index-skip-begin"/></para>
>>
>> They are empty and have no visual effects. So they could be used  for 
>> skipping. Of course, it is not really beautiful but it would work. I 
>> tried several other things (begin para, end para, or an invisible 
>> section) but that does not work. Using some other entries (I tried 
>> "markup" the same way) will work.
>>
>> So with this, we could create non-indexable parts in quickbook, for 
>> examples or otherwise.
>>
>> Using QuickBook I could create a section with an id 
>> "box_view_example_skip_autoindex" and that would work either, but 
>> that show up in the page differently, because the section will have 
>> an entry in the hierarchy. I don't know of there are other containers 
>> available.
>
> If I go this route, I'd rather use docbook processing instructions: 
> http://www.sagehill.net/docbookxsl/ProcessingInstructions.html
>
> I guess these could be arbitrarily complex, but I'd prefer to keep it 
> simple if possible, something like:
>
> <?boost.ai exclude-enclosing ?>
>
> To exclude the enclosing XML container from indexing.

I don't get this, how would that container would be marked? The whole 
section? That is the only XML container there currently is... The sample 
is not contained in any container right now.

>
> I guess we could have start/stop instructions as well, but you can 
> imagine the trouble they could cause if mis-matched or at different 
> levels in the XML - I guess we'd have to say that they apply only 
> until the enclosing XML scope is exited.

The markers I gave were in a closed <para />, so different levels in XML 
is no problem. Besides that, there is also [section] [endsect] which 
should match as well. If auto-index is commonplace, QuickBook could be 
extended by something like [exclude_from_ai]  ... [end_exclude_from_ai]

>
> I think these are neater than abusing the XML structure, but would 
> likely require modification to the Boostbook stylesheets (to pass them 
> through unchanged), and also to the XML parser which I think currently 
> ignores these...

I agree that it is not neat, it is a hack, and abusing. So if processing 
instructions work, I would like that being included.

Regards, Barend