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