Re: [Docutils-develop] Writing directives

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

Aahz wrote:
> It appears that simply declaring something Inline doesn't do
> anything;

Correct.  It's just for classification purposes, so that later
transforms can query a node with isinstance().

> I'm assuming I need to run a transform in the writer?

No.  By the time the document gets to the Writer, it should be in
final form.  The Writer's job is simply (and only) to translate from
the Docutils doctree structure to the target format.  Some small
transforms may be required, but they should be local and
format-specific.  The "index_entry" node class is not format-specific
and should become a standard Docutils node/element (i.e. part of
nodes.py and docutils.dtd).  We can figure out its syntax (attributes
& content model) later.

> Or should the directive find its parent/predecessor-sibling during
> parsing?

I think so.  Given::

    Here's a paragraph.

    .. index:: paragraph

The directive should produce something like this XML::

    <paragraph>
    <index_entry text="paragraph"/>
    Here's a paragraph.
    </paragraph>

Thus the "nodes.Inline" base class; it's an inline element.  This kind
of content model would also allow true inline index-entries::

    Here's a `paragraph`:index:.

If the "index" role were the default for the application, it could be
dropped::

    Here's a `paragraph`.

Both of these would result in this XML::

    <paragraph>
    Here's a <index_entry>paragraph</index_entry>.
    </paragraph>

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