DOCBOOK: Re: Extra Spaces Caused by <indexterm>s

[Jeffrey Oldham <oldham at codesourcery dot com>]

Thanks for the explanation.  The answer may be obvious to someone who
understands the implementation, but it is not obvious to me.  TeX
would merge a series of spaces and newline characters into one
whitespace.  It seems that an indexterm's actual contents are not
rendered, but it has some tricky type of spaciness that uncareful
users can reveal.  In contrast, if I construct a DocBook file with a
lot of blank lines, they are compressed into a single space.

For what other DocBook tags should I be careful about this type of
spaciness?

On Tue, Mar 05, 2002 at 04:52:19PM +0000, Norman Walsh wrote:
> [ Dave, FAQ? ]
> 
> / Jeffrey Oldham <oldham@codesourcery.com> was heard to say:
> | Processing expectations for <indexterm> include:
> |
> |     IndexTerms are suppressed in the primary text flow, although they
> |     contribute to the population of an index and serve as anchors for
> |     cross references. Under no circumstances is the actual content of
> |     IndexTerm rendered in the primary flow.
> |
> | The DVI/PostScript file produced from the attached DocBook/XML file
> | has one erroneous space for each indexterm in the source.  Which tool
> | (or me?) is responsible for these erroneous spaces and how do we fix
> | it?
> 
> Consider your source:
> 
> <para>Why does adding indexterms cause spaces to appear here:
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>      <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
>     <indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>
> ending here?</para>
> 
> For clarity, let's replace spaces by '+' characters:
> 
> <para>Why+does+adding+indexterms+cause+spaces+to+appear+here:
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> +++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ++++<indexterm>
> +++++<primary>data-parallel+operation</primary>
> ++++</indexterm>
> ending+here?</para>
> 
> Now, unless you've taken special care, multiple adjacent spaces are
> generally treated as a single space, so we can reduce this to:
> 
> <para>Why+does+adding+indexterms+cause+spaces+to+appear+here:
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> +<indexterm>
> +<primary>data-parallel+operation</primary>
> +</indexterm>
> ending+here?</para>
> 
> Now, remove the index terms and what's left?
> 
> <para>Why+does+adding+indexterms+cause+spaces+to+appear+here:
> +
> +
> +
> +
> +
> +
> +
> +
> +
> ending+here?</para>
> 
> Those spaces are not "adjacent" unfortunately, so each one is produced
> in the output. That's the source of the extra spaces.
> 
> Unfortunately, the only way to avoid this problem is either to put the
> indexterms between paragraphs (which is logically wrong) or to make
> sure that you don't introduce extra spaces with your index terms:
> 
> <para>Why does adding indexterms cause spaces to appear here:<indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm><indexterm>
>      <primary>data-parallel operation</primary>
>     </indexterm>ending here?</para>
> 
>                                         Be seeing you,
>                                           norm
> 
> -- 
> Norman Walsh <ndw@nwalsh.com>      | No man is more than another if he
> http://www.oasis-open.org/docbook/ | does no more than
> Chair, DocBook Technical Committee | another.--Cervantes

Thanks,
Jeffrey D. Oldham
oldham@codesourcery.com