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

Subject: Re: [boost] [review][autoindex] AutoIndex review extended
From: John Maddock (boost.regex_at_[hidden])
Date: 2011-05-15 11:07:58

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

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

John.