Re: [Docutils-users] Nested, titled sections

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

On Tue, Apr 14, 2015 at 3:13 PM, Jeffrey C. Jacobs
<dar...@ti...> wrote:
> David Goodger <goodger <at> python.org> writes:
>> > What's the right way to specify a limited-scope subsection?
>>
>> Use "topic" or "sidebar" directives. Probably topic:
>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic
>
> Thank you David.  I looked over the documentation for topic and sidebar
> and I think maybe this way of specifying isn't ideal as these would be
> normal text elements in the flow.  It goes back to the formal definition
> of how one writes a screenplay using RST.

First off, I was answering your question about the dog essay. I'd
never suggest topics or sidebars for use in screenplays. If you want
to know about screenplays, don't ask about dog essays; ask about
screenplays, as you did in the other thread. Please don't bait &
switch.

Next, I have no idea what you mean by "normal text elements in the
flow". A document is nothing more than a series of text elements, no
matter what type (document, or elements).

> Right now I'm using Field Lists but that won't allow embedded
> admonitions so I'm looking for a better way.

Uh... yes they would. You can put admonitions inside field lists, no
problem. Try it. Not sure why you'd want to though. I don't see how
admonitions apply to screenplays.

> Currently::
>
> :Character:
>    `(action)`:parenthetical:
>    Dialog

This seems perfectly reasonable to me. See below for my suggestions.

> Proposal with topics::
>
> .. topic:: Character
>
>    .. admonition:: parenthetical
>
>       (action)
>
>    Dialog

Far too wordy and complex. In "An Introduction to reStructuredText", I
described reST as "an easy-to-read, what-you-see-is-what-you-get
plaintext markup syntax". The above is neither. You'll never get
perfect WYSIWYG, but you can get much closer.

> Proposal with Definition Lists::
>
> Character
>
>   .. admonition:: parenthetical
>
>      (action)
>
>   Dialog

While definition lists are a viable alternative to field lists for
screenplay dialog, the above is not a valid definition list item. This
would be:

Character
  .. admonition:: parenthetical

     (action)

  Dialog

> I'm not sure if I'm able to embed adminitions in a topic or a definition
> list

You can. At the block level, reST is completely orthogonal. Anywhere
that you can put a paragraph or a bullet list, you can also put any
other block-level element, including admonitions. With reST, you can
put a table inside an admonition inside a table cell inside... as
deeply as you like.

However, I don't think admonitions are the right thing for your purposes here.

> but as suggested in the developers list an admonition is a better
> document type than a role since parenthetical is typically on a line by
> itself.

That should be "element", not "document". A document is a much bigger
thing, with a title, section structure, multiple block-level elements,
etc.

"On a line by itself". Hmmm. Sounds like line blocks might be just the thing:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks

> I do worry though about how wordy the admonitions are relative to how
> concise the current specification is, but I think processing of the
> generated doctree would be incorrect.

Correctness is a wonderful goal, but practicality beats purity.
Looking at screenplays, I see a set of conventions accumulated
organically over the years. In other words: evolved, not designed.
Evolution is messy, and I wouldn't expect screenplays to fit neatly
into any document model. Neither Docutils' document model nor reST's
set of constructs were designed with screenplays in mind, so you'll
have to shoehorn those conventions in as best you can.

> So thanks again for your help but
> if you have more suggestions on how to resolve this issue I'd greatly
> appreciate it.

I suspect that definition lists would be your best bet for dialog.
Field lists could work too, but they are typically formatted
side-by-side (e.g., by the current html4css1 writer) while definition
lists are often formatted term-on-top, definition-below. So it would
be easier to reconfigure a stylesheet to make definition lists look
like screenplay dialog.

Your "parentheticals" (AKA "personal direction" or "wrylies") may be
common enough to deserve their own special syntax. Lucky for you, reST
offers one customizable inline syntax mechanism: the default
interpreted text role:

    .. role:: parenthetical
    .. default-role:: parenthetical

After that, you can drop the text ":parenthetical:" from your markup:

    Character
        `(action)`
        Dialog

At this point, the only real issue is that the "(action)" text above
has to be on its own line. You could either process your document to
treat the "parenthetical" role specially, or you could use line
blocks:

    Character
        | Dialog
        | `(action)`
        | More dialog, that might
          wrap around. Note that
          the vertical bars aren't
          necessary on wrapped lines.

-- 
David Goodger <http://python.net/~goodger>