docutils-develop

[Docutils-develop] Interleaved elements

[Aahz <aa...@py...>]

I'm finally starting to buckle down to the work of emitting OpenOffice
output from my reST files (so far, I've been just writing -- haven't even
checked syntax for correctness).  I'm going to do some tests myself, but
I might as well ask for advice in parallel.  What I'm trying to figure
out is how to handle the case where two different blocks both get
attached to a preceding paragraph::

    The three execution scopes are *function local* (hereafter referred
    to as local), *module global* (hereafter referred to as global), and
    builtin scope.  Local scope exists any time Python's instruction
    pointer is inside a function/method.  Global scope refers to the
    currently executing module; functions defined in another module still
    consider that module their global scope even if imported into the
    current module's namespace::

        import M
        M.f()               # f()'s global scope is the module M
        from M import f
        f()                 # f()'s global scope is still M

    .. index::
        local
        function local
        global
        module global
        builtin

Should the order of the code block and index directive be swapped?  Does
it make any difference?  Do I need to do something special to handle
this?  (The index terms should be attached to the paragraph, not the
code block.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Re: [Docutils-develop] Interleaved elements

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

Aahz wrote:
> What I'm trying to figure out is how to handle the case where two different
> blocks both get attached to a preceding paragraph::

The literal block isn't "attached" to the paragraph at all.  One merely
follows the other.  Perhaps the "::" being at the end of the paragraph gives
the illusion of attachment, but it's only a convenience; no relationship is
implied.

> Should the order of the code block and index directive be swapped?  Does
> it make any difference?  Do I need to do something special to handle
> this?  (The index terms should be attached to the paragraph, not the
> code block.)

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.

Do you actually have an "index" directive, or is it just a placeholder?
Have you thought further on details of indexing that we discussed some time
ago?

On an editorial note, shouldn't it be "built-in scope"?  "builtin" may be a
Python identifier, but it's not a word.

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

Re: [Docutils-develop] Interleaved elements

[Aahz <aa...@py...>]

On Mon, Oct 07, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> What I'm trying to figure out is how to handle the case where two different
>> blocks both get attached to a preceding paragraph::
> 
> The literal block isn't "attached" to the paragraph at all.  One
> merely follows the other.  Perhaps the "::" being at the end of
> the paragraph gives the illusion of attachment, but it's only a
> convenience; no relationship is implied.

That's true for the DOM, but my perception is different WRT the reST
syntax itself.  And conceptually, the code block *is* attached to the
preceding paragraph (generally, if the paragraph gets moved, the code
block goes with it).

>> Should the order of the code block and index directive be swapped?  Does
>> it make any difference?  Do I need to do something special to handle
>> this?  (The index terms should be attached to the paragraph, not the
>> code block.)
> 
> 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.

<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.  I may
just create a "code" directive (if one doesn't already exist), so the
order becomes paragraph, index directive, code directive.

> Do you actually have an "index" directive, or is it just a
> placeholder?  Have you thought further on details of indexing that we
> discussed some time ago?

I'm currently planning to use "index" as a directive, with the block
following the directive containing one index entry per line.  It turns
out that OpenOffice doesn't support "see" and "see also" entries AFAICT,
so while there will be some annoyance, my formatting code can also be
less complex.  

I haven't actually started coding it yet; I'll probably finally do some
code this week, but I'm not sure where I'm going to start first -- most
likely just hacking together some skeletal writer.  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].

> On an editorial note, shouldn't it be "built-in scope"? "builtin" may
> be a Python identifier, but it's not a word.

I'll let my real editors complain if they don't like it.  ;-)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

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/

Re: [Docutils-develop] Interleaved elements

[Aahz <aa...@py...>]

On Tue, Oct 08, 2002, David Goodger wrote:
>
> The "::" attached to the end of a paragraph is merely a convenience.

Yeah, I learned that ten minutes ago.  ;-)

Okay, I'll start the next issue in another message.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/