[Docutils-develop] Re: index

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

Aahz wrote:
> After a quick skim of images.py: So, in other words, in order to add a
> new directive, I'm going to have to understand how the state machine
> works?

I wouldn't go that far.  You'll need some knowledge of the inner workings,
yes; there's no free lunch.  The directive API is summarized in
docutils/parsers/rst/directives/__init__.py, except for details about the
return value, which I've just added:

    Directive functions return a tuple of two values:
    
    - a list of nodes which will be inserted into the document tree at
      the point where the directive was encountered (can be an empty
      list), and
    - a boolean, true iff the directive block finished on a blank line.

You'll need some services from the state machine, to get the line(s)
following the directive, usually an indented block, and to determine the
"blank_finish" state.  The "image" directive does everything you'd need
yours to do, I think, so it should be possible to hack something up.

To use the directive, it has to be registered in the directives/__init__.py
module.  You'll also need a new node class to instantiate, perhaps
"index_target" or "index_term".  Node classes usually live in
docutils/nodes.py, but directives can make their own if they're specialized;
see directives/html.py, class "meta" (inside class "MetaBody").

> Note that currently I don't care about reST generating the actual index;
> I'm only interested in emitting index tags for OpenOffice.

Understood.  I was just giving an example to illustrate semantics.

> (Yes, I'm ignoring your questions about requirements for now; I'm more
> interested in hacking up something which gives minimal results.)

If you get stuck, let us know what you need, and you may get some help.
Until then, happy hacking!

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