docutils-users — General discussions, questions, help requests.

[Docutils-users] rst2latex and (un)numbered sections

[Martin K. <m...@ef...>]

In LaTeX, one may write \section{...} for a numbered section and
\section*{...} for an unnumbered section. This seems impossible with rST.
Is this correct?

I have a large document which I'm translating into LaTeX using rst2latex
and (because of specific styling needs) I would like to have both numbered
and unnumbered sections. Does anyone know a hack to do this?

I wanted to implement the following: for a normal section, just write

Section
=======

but for an unnumbered section, write

STARRED Section
===================

and then in LaTeX redefine the \section command with ifthen to give
\section*{Section} (gobble "STARRED ") if the title begun with the special
string and to give \section{Section} if it did not start with that special
string. But this also seems quite hard to do.

Happy to hear your advice,
Martin

Re: [Docutils-users] replacement directive and formatting tables (in vim)

[Saša J. <sja...@gm...>]

On Tue, 5 Nov 2019 16:33:30 -0600
David Goodger <go...@py...> wrote:

> I use it on my personal machine (Ubuntu Linux, where it's an input
> system configuration option) and at work (Windows, via WinCompose). I
> can easily type any àçċéñţëđ characters, and I can add custom compose
> key combinations for any Unicode characters I like, e.g.
> ◀▶⇒∞Σ♡∀×✖★∅⚠⎄ (all typed with my standard keyboard, e.g.
> [compose]+[=]+[>] gives ⇒). It works with any software.

Yeah, I'm using GNOME and it would work, but not sure how it
practical it would be when I've > 20 symbols which I regularly have
to use...


Sincerely,
Gour

-- 
As a blazing fire turns firewood to ashes, O Arjuna, so does the
fire of knowledge burn to ashes all reactions to material activities.

Re: [Docutils-users] replacement directive and formatting tables (in vim)

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

Another option is direct Unicode text entry via the Compose Key system:
https://en.wikipedia.org/wiki/Compose_key

I use it on my personal machine (Ubuntu Linux, where it's an input system
configuration option) and at work (Windows, via WinCompose). I can easily
type any àçċéñţëđ characters, and I can add custom compose key combinations
for any Unicode characters I like, e.g. ◀▶⇒∞Σ♡∀×✖★∅⚠⎄ (all typed with my
standard keyboard, e.g. [compose]+[=]+[>] gives ⇒). It works with any
software.

David Goodger
<https://david.goodger.org>


On Tue, 5 Nov 2019 at 05:57, Saša Janiška <sja...@gm...> wrote:

> On Mon, 4 Nov 2019 10:58:43 -0000 (UTC)
> Guenter Milde via Docutils-users <doc...@li...>
> wrote:
>
> > Unfortunately, there is no simple way to use a different syntax for
> > replacements.
>
> OK.
>
> > You may use `simple tables`__ without |, but maybe these cannot be
> > formatted by your editor.
>
> Correct.
>
> > You could also try to teach the table formatter the difference
> > between a table column separator (with whitespace around, regexp "(^|
> > )[|]( |$)") and the replacement syntax (no inner whitespace).
>
> Yeah, that is one possibility.
>
> > Finally, it may be simpler to use the Unicode characters directly via
> > drag-and drop
>
> Well, I use many symbols...
>
> > or group-replacing a placeholder in the editor.
>
> ..will think about it.
>
> Thank you for your input.
>
>
> Sincerely,
> Saša
>
> --
> The working senses are superior to dull matter; mind is higher
> than the senses; intelligence is still higher than the mind;
> and he [the soul] is even higher than the intelligence.
>
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-users] reStructuredText and Localization of Documents, Scaling to Lots of Content, Managed Over Time

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

On 2019-10-31, Kent Borg wrote:
> I am wondering about tools and techniques to help manage translating and 
> localizing documents. Particularly when scaled up and used over time.

Did you have a look at the translating extension for Sphinx?
(I know it exists, but don't know a URL or details.)

> Some considerations:

> - Say a commercial service produces a translated rST document, how might 
> we easily know that it is structurally the same (that the RST didn't 
> accidentally get edited)?

It would be possible code a transform that strips all Text
nodes when exporting. Alternatively, you may use XSLT processing of the
Docutils XML output...

But you may also think about different order of marked-up words or links due
to different grammatical rules in the respective languages...


> - As documents change over time, sometimes there will only be small 
> changes. We don't want to waste time and money redoing the entire 
> document, but the translator should be able to see the whole document, 
> to see the context, but only translate the changed part. (Alternatively, 
> maybe in the only-one-change example, the translator needs to change in 
> a different part of the document because of a change in terminology that 
> should correspond.)

You may split the document source in a master and several child documents.
Pass the relevant child rST and an export of the complete document to the
translating service...


> Some of the things I am wondering about slide into content management 
> questions and don't have any language-specific aspects and are just 
> worrying about managing rST documents over time, maybe with shared 
> components that are used via include directives, etc.

Being text based, rST documents are well suited for version management via
Git or similar.


As a Python package, Docutils can be used as module of a wider system.
Limits are your imagination and coding ressources.

> I note that the Wikipedia has a page on content management systems, and 
> another page on translation management systems. I'm wondering about rST 
> considerations...


Günter

Re: [Docutils-users] replacement directive and formatting tables (in vim)

[Saša J. <sja...@gm...>]

On Mon, 4 Nov 2019 10:58:43 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> Unfortunately, there is no simple way to use a different syntax for
> replacements.

OK.

> You may use `simple tables`__ without |, but maybe these cannot be
> formatted by your editor.

Correct.

> You could also try to teach the table formatter the difference
> between a table column separator (with whitespace around, regexp "(^|
> )[|]( |$)") and the replacement syntax (no inner whitespace).

Yeah, that is one possibility.

> Finally, it may be simpler to use the Unicode characters directly via
> drag-and drop 

Well, I use many symbols...

> or group-replacing a placeholder in the editor.

..will think about it.

Thank you for your input.


Sincerely,
Saša

-- 
The working senses are superior to dull matter; mind is higher
than the senses; intelligence is still higher than the mind;
and he [the soul] is even higher than the intelligence.

Re: [Docutils-users] replacement directive and formatting tables (in vim)

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

On 2019-11-03, Saša Janiška wrote:
> Hello,

> in my content I have a need to use many replacement directives, e.g. for
> entering Unicode characters for planets, so I have things like:

> .. |Jupiter| replace:: ♃

> However, since rst uses '|' as table's cell separator, when I use the
> above-like replacement directives, they clash with the code used to
> reformat tables in vim (using https://github.com/gu-fan/riv.vim)
> package, so I wonder if someone can provide some workaround to be able
> to stay with rst **and** using vim editor?

Unfortunately, there is no simple way to use a different syntax for
replacements.

You may use `simple tables`__ without |, but maybe these cannot be formatted
by your editor.

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables

You could also try to teach the table formatter the difference between a
table column separator (with whitespace around, regexp "(^| )[|]( |$)")
and the replacement syntax (no inner whitespace).

Finally, it may be simpler to use the Unicode characters directly via
drag-and drop or group-replacing a placeholder in the editor.

Ahoj,

Günter

[Docutils-users] replacement directive and formatting tables (in vim)

[Saša J. <sja...@gm...>]

Hello,

in my content I have a need to use many replacement directives, e.g. for
entering Unicode characters for planets, so I have things like:

.. |Jupiter| replace:: ♃

However, since rst uses '|' as table's cell separator, when I use the
above-like replacement directives, they clash with the code used to
reformat tables in vim (using https://github.com/gu-fan/riv.vim)
package, so I wonder if someone can provide some workaround to be able
to stay with rst **and** using vim editor?


Sincerely,
Saša

-- 
Before giving up this present body, if one is able to tolerate
the urges of the material senses and check the force of desire and
anger, he is well situated and is happy in this world.

[Docutils-users] reStructuredText and Localization of Documents, Scaling to Lots of Content, Managed Over Time

[Kent B. <ken...@bo...>]

I am wondering about tools and techniques to help manage translating and 
localizing documents. Particularly when scaled up and used over time.

Some considerations:

- Say a commercial service produces a translated rST document, how might 
we easily know that it is structurally the same (that the RST didn't 
accidentally get edited)?

- As documents change over time, sometimes there will only be small 
changes. We don't want to waste time and money redoing the entire 
document, but the translator should be able to see the whole document, 
to see the context, but only translate the changed part. (Alternatively, 
maybe in the only-one-change example, the translator needs to change in 
a different part of the document because of a change in terminology that 
should correspond.)

Some of the things I am wondering about slide into content management 
questions and don't have any language-specific aspects and are just 
worrying about managing rST documents over time, maybe with shared 
components that are used via include directives, etc.

I note that the Wikipedia has a page on content management systems, and 
another page on translation management systems. I'm wondering about rST 
considerations...

Thanks,

-kb

Re: [Docutils-users] Inline, verbatim anchors?

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

On 2019-10-28, Matthew Woehlke wrote:
> On 28/10/2019 12.11, Guenter Milde via Docutils-users wrote:
>> On 2019-10-08, Guenter Milde via Docutils-users wrote:
>>> On 2019-10-07, Matthew Woehlke wrote:
>>>> On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:

>>>>> You may be looking for `inline internal targets`__.

>>>>> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

>>>> Huh. Okay, that *sort of* works, but is there any way to style the text?

>>> Unfortunately, inline markup nesting is not supported.
>>> This is a long standing feature request.
>>> http://docutils.sourceforge.net/docs/dev/todo.html#nested-inline-markup

>> Another option would be to extend `custom interpreted text roles`_ to roles
>> based on hyperlink targets and hyperlink references.

>> __ http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles

>> Concept: 
>>   Two special roles :hyperlink-reference: and :hyperlink-target: are
>>   defined (similar to the `:raw:`__ role).

>>   __ http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw

>>   Then, the rSText::

>>     .. role:: emph-link(hyperlink-target)

>>     :emph-link:`here`

>>   would create a target with class argument::

>>         <target ids="target" names="target" classes="emph-link">
>>             target

>>   that could be styled accordingly.

> Yes, something like that could possibly work, especially as user roles
> can also have custom classes added. The problem currently is, as you
> note, there is no way to create a user role that also turns its text
> into an anchor. Your suggested :hyperlink-target: would fix that.

> Do you think a patch along those lines would be considered?

Yes, a patch would be welcome.

> (BTW, what *is* the patch process? I came across a "move to github"
> thread that talked about doing so as a way of making it easier to
> submit patches...)

This is explained in the Docutils Policies 
http://docutils.sourceforge.net/docs/dev/policies.html#how-to-get-a-new-feature-into-docutils

Patches against a git mirror are accepted, too.

>> Maybe we could also allow a combination of hyperlink syntax and role syntax
>> like::

>>   This is an _`important target`:emphasis: and a very :strong:`bold link`_.

> While that looks technically plausible, I suspect the implementation
> would be much more difficult. (I have some experience with sphinx
> hacking, so I'm not entirely unfamiliar with the internals. I feel
> confident I could bash out a patch along the lines of your first idea
> pretty quickly. The second...?)

Actually, I prefer the first approach.

> BTW, I wonder why nested markup is such an issue? I've implemented that
> before for my own custom extensions, and it wasn't hard.

As you told in the follow up, the devil is in the details. The issue is not
pressing for main developers and there are many points to consider to get it
right. We would need a volunteer with long-term commitment.

Thanks,
Günter

Re: [Docutils-users] Set Debug Mode?

[Kent B. <ken...@bo...>]

On 10/19/19 5:11 PM, Guenter Milde via Docutils-users wrote:
> parts = docutils.core.publish_parts(...
>    	  			      settings_overrides={debug: True})

And it works!

Belated thanks,

-kb

Re: [Docutils-users] Inline, verbatim anchors?

[Matthew W. <mwo...@gm...>]

On 28/10/2019 16.56, Matthew Woehlke wrote:
> On 2019-10-08, Guenter Milde via Docutils-users wrote:
>> Unfortunately, inline markup nesting is not supported.
>> This is a long standing feature request.
>> http://docutils.sourceforge.net/docs/dev/todo.html#nested-inline-markup
> 
> BTW, I wonder why nested markup is such an issue? I've implemented that
> before for my own custom extensions, and it wasn't hard. (IIRC,
> something mutter something about creating an extra paragraph node, but I
> think I solved that by stripping out the interior node from
> nested_parse. At least, I had something that was working for my use
> case, and I don't think it would have worked with an extra paragraph
> node, which suggests I was able to deal with it somehow.)

Okay, I'm *not* using nested_parse. Here is my code (note: old, may not
work with latest version):


  def make_parsed_text_role(class_names=[], node_class=nodes.inline):
      def parsed_text_role(name, rawtext, text, lineno, inliner,
                           options={}, content=[]):
        # Prepare context for nested parsing
        memo = Struct(document=inliner.document,
                      reporter=inliner.reporter,
                      language=inliner.language)

        # Create parent node
        options['classes'] = class_names
        parent = node_class(rawtext, '', **options)

        # Parse role text for markup and add to parent
        processed, messages = inliner.parse(text, lineno, memo, parent)
        parent += processed

        # Return parent node, and any messages from nested parsing
        return [parent], messages

      return parsed_text_role

As you'll note, this isn't a role in and of itself; it is actually a
function to *create* a role. My project creates a bunch of these with
different 'stock' classes; for example:

  app.add_role('t', make_parsed_text_role(class_names=['title-drop']))
  app.add_role('i', make_parsed_text_role(node_class=nodes.emphasis))

...which lets you write stuff like:

  I read :t:`The *Very* Long Evening` last night.

OTOH I don't think this supports nested *roles*, and we won't even talk
about backwards compatibility, but for my purposes, using emphasis and
substitutions inside of interpreted text was sufficient.

-- 
Matthew

Re: [Docutils-users] Inline, verbatim anchors?

[Matthew W. <mwo...@gm...>]

On 28/10/2019 12.11, Guenter Milde via Docutils-users wrote:
> On 2019-10-08, Guenter Milde via Docutils-users wrote:
>> On 2019-10-07, Matthew Woehlke wrote:
>>> On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:
>>>> You may be looking for `inline internal targets`__.
>>>>
>>>> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets
>>> 
>>> Huh. Okay, that *sort of* works, but is there any way to style the text?
>> 
>> Unfortunately, inline markup nesting is not supported.
>> This is a long standing feature request.
>> http://docutils.sourceforge.net/docs/dev/todo.html#nested-inline-markup
> 
> Another option would be to extend `custom interpreted text roles`_ to roles
> based on hyperlink targets and hyperlink references.
> 
> __ http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
> 
> Concept: 
>   Two special roles :hyperlink-reference: and :hyperlink-target: are
>   defined (similar to the `:raw:`__ role).
> 
>   __ http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw
> 	 
>   Then, the rSText::
> 	 
>     .. role:: emph-link(hyperlink-target)
>     
>     :emph-link:`here`
>     
>   would create a target with class argument::
>   
>         <target ids="target" names="target" classes="emph-link">
>             target
> 
>   that could be styled accordingly.

Yes, something like that could possibly work, especially as user roles
can also have custom classes added. The problem currently is, as you
note, there is no way to create a user role that also turns its text
into an anchor. Your suggested :hyperlink-target: would fix that.

Do you think a patch along those lines would be considered? (BTW, what
*is* the patch process? I came across a "move to github" thread that
talked about doing so as a way of making it easier to submit patches...)

> Maybe we could also allow a combination of hyperlink syntax and role syntax
> like::
> 
>   This is an _`important target`:emphasis: and a very :strong:`bold link`_.

While that looks technically plausible, I suspect the implementation
would be much more difficult. (I have some experience with sphinx
hacking, so I'm not entirely unfamiliar with the internals. I feel
confident I could bash out a patch along the lines of your first idea
pretty quickly. The second...?)

BTW, I wonder why nested markup is such an issue? I've implemented that
before for my own custom extensions, and it wasn't hard. (IIRC,
something mutter something about creating an extra paragraph node, but I
think I solved that by stripping out the interior node from
nested_parse. At least, I had something that was working for my use
case, and I don't think it would have worked with an extra paragraph
node, which suggests I was able to deal with it somehow.)

-- 
Matthew

Re: [Docutils-users] Inline, verbatim anchors?

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

On 2019-10-08, Guenter Milde via Docutils-users wrote:
> On 2019-10-07, Matthew Woehlke wrote:
>> On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:
>>> On 2019-10-07, Matthew Woehlke wrote:

>>>> What I want, ideally, is a role that takes its text and generates an
>>>> anchor from its text (i.e. sets the 'id' on its node to its contents),
>>>> *and also emits the text*.

>>> You may be looking for `inline internal targets`__.

>>> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

>> Huh. Okay, that *sort of* works, but is there any way to style the text?

> Unfortunately, inline markup nesting is not supported.
> This is a long standing feature request.
> http://docutils.sourceforge.net/docs/dev/todo.html#nested-inline-markup


Another option would be to extend `custom interpreted text roles`_ to roles
based on hyperlink targets and hyperlink references.

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles

Concept: 
  Two special roles :hyperlink-reference: and :hyperlink-target: are
  defined (similar to the `:raw:`__ role).

  __ http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw
	 
  Then, the rSText::
	 
    .. role:: emph-link(hyperlink-target)
    
    :emph-link:`here`
    
  would create a target with class argument::
  
        <target ids="target" names="target" classes="emph-link">
            target

  that could be styled accordingly.


Maybe we could also allow a combination of hyperlink syntax and role syntax
like::

  This is an _`important target`:emphasis: and a very :strong:`bold link`_.
  
This makes use of the fact that the `interpreted text`__ role can be
specified on either side.

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text


Günter



Günter

Re: [Docutils-users] Set Debug Mode?

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

On 2019-10-08, Kent Borg wrote:
> I have discovered that setting debug=True in the 
> statemachine.StateMachine.__init__() call can be *very* useful. But I'm 
> not calling directly. Tracing my call stack is seems to be 
> reader/__init__.py Reader.parse() that would be the place to pass it 
> down that doesn't.

> Is there a way to set that programmaticly? I can edit statemachine.py to 
> force it, but that's both ugly and obscure. Is there a better way that I 
> missed?

"debug" is one of the many configuration settings
http://docutils.sourceforge.net/docs/user/config.html#debug

You can either set it in a local configuration file, or via the
`settings_overrides` argument to the `core.publish_*()` functions, e.g.

  parts = docutils.core.publish_parts(...
  	  			      settings_overrides={debug: True})

See the Docutils test suite for code examples and
http://docutils.sourceforge.net/docs/api/publisher.html
for general documentation on use of Docutils as a library.

Günter

[Docutils-users] Set Debug Mode?

[Kent B. <ken...@bo...>]

I have discovered that setting debug=True in the 
statemachine.StateMachine.__init__() call can be *very* useful. But I'm 
not calling directly. Tracing my call stack is seems to be 
reader/__init__.py Reader.parse() that would be the place to pass it 
down that doesn't.

Is there a way to set that programmaticly? I can edit statemachine.py to 
force it, but that's both ugly and obscure. Is there a better way that I 
missed?

Thanks,

-kb

Re: [Docutils-users] Inline, verbatim anchors?

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

On 2019-10-07, Matthew Woehlke wrote:
> On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:
>> On 2019-10-07, Matthew Woehlke wrote:

>>> What I want, ideally, is a role that takes its text and generates an
>>> anchor from its text (i.e. sets the 'id' on its node to its contents),
>>> *and also emits the text*.

>> You may be looking for `inline internal targets`__.

>> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

> Huh. Okay, that *sort of* works, but is there any way to style the text?

Unfortunately, inline markup nesting is not supported.
This is a long standing feature request.
http://docutils.sourceforge.net/docs/dev/todo.html#nested-inline-markup

> Also, the replacement of '.' with '-' is undesired and doesn't seem to
> be necessary...

The replacement is done in the ID, but not in the text or the "name" used
for references to this target from other places in the rST document:

   This is the _`inline.target`
   
   I can link to it with `inline.target`_ in the rST source document.
   
   Other documents link to it as ``file:foo.html#inline-target``
   

The rationale was to make the ID compatible with both, HTML4.1 and CSS1
identifiers:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#rationale

There is a feature request to lift these limitations
https://sourceforge.net/p/docutils/feature-requests/66/
but we have to think about backwards compatibility
(it would be a bad thing if re-compiling a document would break external
links to it adapted to the current transformation without advance warning)
and other output formats (LaTeX, manpage, ODT).

Günter

Re: [Docutils-users] Inline, verbatim anchors?

[Matthew W. <mwo...@gm...>]

On 07/10/2019 14.11, Guenter Milde via Docutils-users wrote:
> On 2019-10-07, Matthew Woehlke wrote:
> 
>> What I want, ideally, is a role that takes its text and generates an
>> anchor from its text (i.e. sets the 'id' on its node to its contents),
>> *and also emits the text*.
> 
> You may be looking for `inline internal targets`__.
> 
> __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

Huh. Okay, that *sort of* works, but is there any way to style the text?
Also, the replacement of '.' with '-' is undesired and doesn't seem to
be necessary...

-- 
Matthew

Re: [Docutils-users] Inline, verbatim anchors?

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

On 2019-10-07, Matthew Woehlke wrote:

> What I want, ideally, is a role that takes its text and generates an
> anchor from its text (i.e. sets the 'id' on its node to its contents),
> *and also emits the text*.

You may be looking for `inline internal targets`__.

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-internal-targets

Günter

[Docutils-users] Inline, verbatim anchors?

[Matthew W. <mwo...@gm...>]

I have a document that is structured roughly like the C++ standard, e.g.:


  Some Heading [foo]
  ------------------

  [foo.dog] This is a paragraph with some text.

  [foo.cat] This is another paragraph.

I want to be able to link to specific paragraphs, i.e.
https://example.com/docs/foo.html#foo.bar.

Is there any way to accomplish this? Would a patch to add a feature like
this be accepted?

What I want, ideally, is a role that takes its text and generates an
anchor from its text (i.e. sets the 'id' on its node to its contents),
*and also emits the text*. I don't want to repeat__ the section
identifiers, i.e. not this:

  .. _foo.dog

  [foo.dog] Text goes here

I also want to be able to use this "anywhere", not just before
paragraphs. (In particular, much of my document is structured as lists...)

__ https://en.wikipedia.org/wiki/Don%27t_repeat_yourself

-- 
Matthew

Re: [Docutils-users] Question About Section Levels

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

The way I would go about something like this is to write a new directive,
"insert" or "subdoc", which spawns a new parser, parses the external
subdocument file into a separate document tree, and grafts this doctree
onto the master document tree. That would allow independent section
structure in the subdocument. There are issues to consider here, like how
much context is to be copied over between the master document's parser and
the subparser (e.g. the section title adornments should not be copied over;
but what about reference names, substitution definitions, etc.?).

There are lots of notes on this (and many other topics) in the Docutils To
Do List:
http://docutils.sourceforge.net/docs/dev/todo.html#large-documents
Note: many items in there may be stale, as it hasn't been updated/pruned in
a while.

David Goodger
<https://david.goodger.org>

Re: [Docutils-users] Question About Section Levels

[Kent B. <ken...@bo...>]

On 10/2/19 4:02 PM, Guenter Milde via Docutils-users wrote:
> implementation sketch:
> * a new option to "include"::
>
>     :relative-section-levels: <offset>
>
> * push the current level and adornment-style--level mapping,
>
> * read the to-be-included file into a list and append an "end marker",
>
> * start a new adornment-style--level mapping
>
> * section_level = parent_level + offset + child_level
>
> * when hitting "end marker": pop section level and adornment-style--level
>    mapping

I don't know the code well, but that seems familiar from what I do know.

Though it seems it would be much harder to do as a custom 
directive--that is, not forking sources, not moving to a new library 
version, etc.

It turns out we have a good (AKA, really unpleasant but we have to do it 
anyway) "workaround": being compatible with some old code means we are 
chopping up content into small enough pieces that we can mostly not have 
our includes do any sections, so we can do them all in a top-level 
document that we can create on-the-fly.

A related question: What are prospects for writing a custom directive 
that does a single section, at an offset-from-current? Or, put another 
way, is there a way from the perspective of a custom directive's 
parse-time code to learn the current section level? If I knew the 
current level I could do a fake include of the right ASCII to indicate 
the section I want to create.

Thanks,

-kb, the Kent who is a big fan of fake includes to do all kinds of things.

Re: [Docutils-users] Question About Section Levels

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

Dear Kent,

On 2019-10-02, Kent Borg wrote:
> On 10/2/19 7:20 AM, Guenter Milde via Docutils-users wrote:

>> However, the mapping "adornment style" -> `section_level` is done "on the
>> go", i.e.  the first style encountered will be level 1, the second style
>> will be level 2, the third will be level 3, and so on.

>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

> Ah, yes, I think I noticed that without realizing it. Interesting. And 
> for a moment I thought it might help me here, but I think not.

>> "this level":
>>    use the style of the previous section title.

>> "one deeper than the current level":
>>    use the style "established" for one level deepter by previous use.
>>    If there  is no "established" style yet, use a new style.

>> "X number of levels shallower than the current level"
>>    ! not allowed in rST !

> I think I am misunderstanding.
...

> This section I popped up 2 levels, I could have used "=" to pop up three, "`" to pop up one.

> That is what I meant by "X number of levels shallower".

Sorry, I did not read carefully.
You can go up several levels but down only one level. 


>>> Is there some option to include that will make contents relative to
>>> the depth at which the include directive appeared?
>> No. (It would be a nice thing but is non-trivial to implement.)

> Yes, I was tracing through docutils code yesterday, I agree it would be 
> non-trivial...

implementation sketch:

* a new option to "include"::

   :relative-section-levels: <offset>

* push the current level and adornment-style--level mapping,

* read the to-be-included file into a list and append an "end marker",

* start a new adornment-style--level mapping

* section_level = parent_level + offset + child_level

* when hitting "end marker": pop section level and adornment-style--level
  mapping


Günter

Re: [Docutils-users] Question About Section Levels

[Kent B. <ken...@bo...>]

On 10/2/19 7:20 AM, Guenter Milde via Docutils-users wrote:
> However, the mapping "adornment style" -> `section_level` is done "on the
> go", i.e.  the first style encountered will be level 1, the second style
> will be level 2, the third will be level 3, and so on.
>
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections

Ah, yes, I think I noticed that without realizing it. Interesting. And 
for a moment I thought it might help me here, but I think not.

> "this level":
>    use the style of the previous section title.
>
> "one deeper than the current level":
>    use the style "established" for one level deepter by previous use.
>    If there  is no "established" style yet, use a new style.
>
> "X number of levels shallower than the current level"
>    ! not allowed in rST !

I think I am misunderstanding. I can do:

Section 1
=========

Paragraph One

Section 2
---------

Paragraph Two is a level deeper.

Section 3
`````````

Paragraph Three is deeper still.

Section 4
'''''''''

Paragraph 4 is the deepest I'll go in this example.


Section 5
---------

This section I popped up 2 levels, I could have used "=" to pop up three, "`" to pop up one.

That is what I meant by "X number of levels shallower".


>> Is there some option to include that will make contents relative to
>> the depth at which the include directive appeared?
> No. (It would be a nice thing but is non-trivial to implement.)

Yes, I was tracing through docutils code yesterday, I agree it would be 
non-trivial...


This is part of the dynamic content inside RST project I mentioned a few 
weeks ago. This specific question is prompted by needed to be backwards 
compatible with a previous design. It looks like our workaround will be 
rST include files in smaller chunks. Not as nice for maintaining our 
content, but it will work.


Now I need to go make changes to one of the custom directives I wrote: 
add a section depth parameter so it can be used from any nesting depth...


Thanks,

-kb

Re: [Docutils-users] Question About Section Levels

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

On 2019-10-01, Kent Borg wrote:
> As I understand it reStructuredText section levels are absolute, not
> relative. 
> That is, at any point one can do another section at the
> current level, do a section one level deeper, or do a section
> shallower. But in each case it must be an explicit level indicated
> by an explicit underlining character.

However, the mapping "adornment style" -> `section_level` is done "on the
go", i.e.  the first style encountered will be level 1, the second style
will be level 2, the third will be level 3, and so on.

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections


> Is there a way to do a section that is merely "this level" or "one
> deeper than the current level" or "X number of levels shallower than
> the current level"? That's all reStructuredText wants to know, there
> must be a way to say that...

"this level": 
  use the style of the previous section title.

"one deeper than the current level":
  use the style "established" for one level deepter by previous use.
  If there  is no "established" style yet, use a new style.

"X number of levels shallower than the current level"
  ! not allowed in rST !
  

> The use-case is to make include files useful at different
> levels. Imagine a long document with lots of detail sitting in
> different include files, and imagine an executive summary document
> that has less detail, but wants to include a specific section to
> highlight something notable, using an include file that is also used
> by the long document. Cool, no problem...but what if the section
> level in the executive summary will be shallower than in the
> detailed document?

Then, you must change the section title adornment style in one of the
documents. Unfortunately, this means advance planning of section styles
(or lookup and editing later on). A good editor__ may help (e.g. by
producing an outline showing the adornments used in a document).

__ http://docutils.sourceforge.net/docs/user/links.html#editors


> Is there some option to include that will make contents relative to
> the depth at which the include directive appeared?

No. (It would be a nice thing but is non-trivial to implement.)

> Is there some way I might make a custom directive that can do
> relative sections?

This would be tricky, because currently, the included file is
included as source replacing the "include" directive and then parsing
continues (i.e. the result is the same as if the file content were
inserted into the master file before calling Docutils).


Thanks,

Günter

[Docutils-users] Question About Section Levels

[Kent B. <ken...@bo...>]

As I understand it reStructuredText section levels are absolute, not
relative. That is, at any point one can do another section at the
current level, do a section one level deeper, or do a section
shallower. But in each case it must be an explicit level indicated
by an explicit underlining character.

Is there a way to do a section that is merely "this level" or "one
deeper than the current level" or "X number of levels shallower than
the current level"? That's all reStructuredText wants to know, there
must be a way to say that...

The use-case is to make include files useful at different
levels. Imagine a long document with lots of detail sitting in
different include files, and imagine an executive summary document
that has less detail, but wants to include a specific section to
highlight something notable, using an include file that is also used
by the long document. Cool, no problem...but what if the section
level in the executive summary will be shallower than in the
detailed document?

Is there some option to include that will make contents relative to
the depth at which the include directive appeared?

Is there some way I might make a custom directive that can do
relative sections?

Thanks,

-kb