docutils-users

[Docutils-users] Nested, titled sections

[Jeffrey C. J. <dar...@ti...>]

Is there a way to nest a titled section.  For instance, say we have text::

All About Dogs
~~~~~~~~~~~~~~

Aren't Dogs great?  Let's talk about a breed.

   Poodle
   ------

   Poodles are the smartest dog.  They come in full and toy sizes.

So let's talk about a different dog.

   Beagle
   ------

   Beagles are noisy.  Snoopy was a beagle.

And how about another Dog.

In this example, I've incorrectly indented the headings for the 
subsections to make it clear where each subsection ends but this isn't 
valid RST.  What's the right way to specify a limited-scope subsection?

Jeffrey.

Re: [Docutils-users] Nested, titled sections

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

On Tue, Apr 14, 2015 at 1:54 PM, Jeffrey C. Jacobs
<dar...@ti...> wrote:
> Is there a way to nest a titled section.

In the strictest sense, only in the normal way, via the normal
hierarchy of sections and subsections etc. But that doesn't do what
you want.

> For instance, say we have text::
>
> All About Dogs
> ~~~~~~~~~~~~~~
>
> Aren't Dogs great?  Let's talk about a breed.
>
>    Poodle
>    ------
>
>    Poodles are the smartest dog.  They come in full and toy sizes.
>
> So let's talk about a different dog.
>
>    Beagle
>    ------
>
>    Beagles are noisy.  Snoopy was a beagle.
>
> And how about another Dog.
>
> In this example, I've incorrectly indented the headings for the
> subsections to make it clear where each subsection ends but this isn't
> valid RST.

Exactly. There is no way apart from some mechanism like this. And the
output should also format such segments in a distinctive way,
otherwise the document will not make sense to the reader.

> 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

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

Re: [Docutils-users] Nested, titled sections

[Jeffrey C. J. <dar...@ti...>]

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.

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

Currently::

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

Proposal with topics::

.. topic:: Character

   .. admonition:: parenthetical

      (action)

   Dialog

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

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.  So thanks again for your help but 
if you have more suggestions on how to resolve this issue I'd greatly 
appreciate it.

Jeffrey.

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>

Re: [Docutils-users] Nested, titled sections

[Jeffrey C. J. <dar...@ti...>]

On Tue, Apr 14, 2015 at 5:19 PM, David Goodger <go...@py...> wrote:
> 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.

Thanks for drilling down into a more specific use case than dogs,
David.  I know the original question doesn't seem like its related but
I was trying to make a query in the most general case possible.  In
that sense, I think your title suggestion does make some sense as long
as it's rendered inline and not separate from the document which I
think was my main concern, how the writer would handle it.

I think the line-blocks are an interesting idea and I'll definitely
consider it as a way to spell how it should be rendered.  As you saw
in the developer's thread, I'm trying to look at all of Docutils for
rendering, which will likely mean modifying the doctree through a
custom transform before it hits the writer and then use the existing
writer with a custom stylesheet to render it properly.  I just wonder
if custom doctree transforms can be added to any of the publish
functions as I worry that styling may not be able to smooth over all
the bumps of the default generated document elements without a little
massaging beforehand.  A simple visitor transform could accomplish
this (seeing adding an XSLT parser is a bit much for such a thing).
But as transforms are more a developer issue, I'll move that
discussion there.

Thanks again!

Jeffrey.

[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

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

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

On Apr 19, 2015 3:22 PM, "Guenter Milde" <mi...@us...> wrote:
>
> 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

That does work. But I'd recommend a less verbose option.

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

Yes, but I believe there should not be any blank lines between sections of
dialog and parentheticals (in the output). Of course, a transform could do
that too.

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

Probably better to require the parentheses in the source text, for the sake
of WYSIWYG (input matching output).

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

Unfortunately that won't work, because such parentheticals can occur in
arbitrary positions (not just at the beginning of dialog, but in the middle
or at the end), and there can be multiple instances. The pattern doesn't
match definition list classifiers at all.

DG

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

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

On 2015-04-19, David Goodger wrote:
> On Apr 19, 2015 3:22 PM, "Guenter Milde" <mi...@us...> wrote:
>> 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:

...

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

> That does work. But I'd recommend a less verbose option.

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

>>     Character
>>           `action`

>>           Dialog

> Yes, but I believe there should not be any blank lines between sections of
> dialog and parentheticals (in the output). Of course, a transform could do
> that too.

A custom paragraph style for "parenthetical" paragraphs should suffice.
(Most printed documents use indendation instead of vertical space as
paragraph separator anyway.)


>> Another, [...] option would be to (ab)use the
>> "classifier" of a definition list term ...
...

> Unfortunately that won't work, because such parentheticals can occur in
> arbitrary positions (not just at the beginning of dialog, but in the middle
> or at the end), and there can be multiple instances. The pattern doesn't
> match definition list classifiers at all.

OK. Then it is up to role (inline element) vs. directive (block element).

It should even be possible to transform all "parenthetical" role nodes to
block elements (paragraphs with class value "parenthetical", say) in a
transform. 

+1 less verbose markup (no need for blank lines)
-1 the role can be used at places where no block level markup is allowed --
   requires test and error mechanism that comes "for free" if you use a
   directive.
   
Günter