[Docutils-develop] index entries (was Re: DocBook writer in sandbox)

[David G. <go...@us...>]

David Goodger wrote:
> If all of your index entries will appear verbatim in the text, this
> should be sufficient.  If not (e.g., if you want "Van Rossum, Guido"
> in the index but "Guido van Rossum" in the text), we'll have to
> figure out a supplemental mechanism, perhaps using substitutions.

I've thought a bit more on this, and I came up with two possibilities:

1. Using interpreted text, embed the index entry text within the
   interpreted text::

       ... by `Guido van Rossum [Van Rossum, Guido]` ...

   The problem with this is obvious: the text becomes cluttered and
   hard to read.  The processed output would drop the text in
   brackets, which goes against the spirit of interpreted text.

2. Use substitutions::

       ... by |Guido van Rossum| ...

       .. |Guido van Rossum| index:: Van Rossum, Guido

   A problem with this is that each substitution definition must have
   a unique name.  A subsequent ``.. |Guido van Rossum| index:: BDFL``
   would be illegal.  Some kind of anonymous substitution definition
   mechanism would be required, but I think that's going too far.

Both of these alternatives are flawed.  Any other ideas?

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/