Re: [Docutils-develop] Interleaved elements

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

[David]
>> I'd suggest that your "index" directive *precede* the paragraph
>> they're targeting.  That makes more sense to me, and it's more in
>> keeping with the hyperlink target construct:
>>
>>     .. _name:
>>
>>     The "name" above targets this paragraph.

[Aahz]
> <grimace> That's what I was thinking, and for some reason it offends
> my sense of esthetics.  I think of index entries as being like
> footnote entries, and footnote contents generally follow their
> references.

Having the "index" directive follow the object it targets is not a
problem.  It seems like it's a matter of personal preference, and
either way would be fine.  Having "index" after the target could
actually make processing easier; the target object will already exist
when the directive is encountered, so processing won't have to be put
off.

> I may just create a "code" directive (if one doesn't already exist),
> so the order becomes paragraph, index directive, code directive.

In my first reading of this, I thought you meant to make a
special-purpose directive for the "paragraph followed by a literal
block followed by an index directive" case.  I hope that's not the
case.  I think you mean a directive to create a code block, correct?
It's not necessary.

The "::" attached to the end of a paragraph is merely a convenience.
"::" alone will also do the trick.  This paragraph and literal block::

    A paragraph::

        # A literal
        # block

is equivalent to this::

    A paragraph:

    ::

        # A literal
        # block

If you want to have your "index" directive follow the object it
targets, and that object is the paragraph, you can put the directive
in-between like this::

    A paragraph:

    .. index:
       one
       two
       three

    ::

        # A literal
        # block

> WRT to indexing in general, I'm not likely to think about it until I
> see how my needs work in the Real World [tm].

That's a good rule of thumb.

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