[Docutils-users] screenplay markup (was Re: Nested, titled sections)

[Guenter M. <mi...@us...>]

Dear Jeffrey and David,

On 2015-04-14, David Goodger wrote:
> On Tue, Apr 14, 2015 at 3:13 PM, Jeffrey C. Jacobs
><dar...@ti...> wrote:
>> David Goodger <goodger <at> python.org> writes:

>> Currently::

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

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

...

>> Proposal with Definition Lists::

...

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

The idea was to use a block element instead of a role. This could be a
generic admonition, an (ab)used pre-defined admonition (note, hint, ...) or
a custom directive (whether the parentheses are added by the directive or
required in the source is up to the implementation)::

  Character
    .. parenthetical:: action
 
    Dialog

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

In addition, definition lists look more similar to a dialogue and are easier
to type also in the rST source.

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

Or you could simply put the `action` in a separate paragraph:

    Character
          `action`
           
          Dialog

Again, the parentheses might be added by the "parenthetical" role.

Another, not very clean but concise option would be to (ab)use the
"classifier" of a definition list term::

    Character : action
       Dialogue
       
A custom transform could replace the classifier node in the definition
term with a leading paragraph with class "parenthetical" in the defintion.


Günter