[Docutils-develop] index

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

Aahz wrote:
> Now, how do I add a new directive?  (For index tags.)

Take a look at docutils/parsers/rst/directives/images.py for relevant
examples.  If you could show us some concrete examples of what you want, it
would be easier to advise.

Were I writing a book with an index, I guess I'd need two different kinds of
index tags: inline/implicit and out-of-line/explicit.  For example::

    In this `paragraph`:index:, several words are being
    `marked`:index: inline as implicit `index`:index:
    entries.

    .. index:: markup
    .. index:: syntax

    The explicit index directives above would refer to
    this paragraph.

The words "paragraph", "marked", and "index" would become index entries
pointing at the words in the first paragraph.  The index entries appear
verbatim in the text.  (Don't worry about the ugly ":index:" part; if
indexing is the only application of interpreted text in your documents, it
can be implicit and omitted.)  The two directives provide manual indexing,
where the index entry words ("markup" and "syntax") do not appear in the
main text.  We could combine the two directives into one::

    .. index:: markup; syntax

Semicolons instead of commas because commas could *be* part of the index
entry, like::

    .. index:: van Rossum, Guido

Sometimes index entries have multiple levels.  Given::

    .. index:: statement syntax: expression statements

In the index, combined with other entries, it might look like this::

    statement syntax
        expression statements ..... 56
        assignment ................ 57
        simple statements ......... 58
        compound statements ....... 60

How does all that sound?  These are just my initial ideas.  Nothing's been
implemented yet, so tell us your requirements to get them incorporated.
Last time around, you mentioned "see / see also" index entries; I'm
unfamiliar with the semantics of these.  I guess I'll be reading more of the
DocBook docs, a great reference for this type of thing (although the DocBook
implementation is not always ideal).

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