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