Re: [Docutils-users] alternative heading syntax

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

On 2020-12-03, Danil Shkodin wrote:

> Hello.

> Do you mind telling please if there is a way to alternate the way headings
> are marked up?

Actually, reStructuredText does not include a markup alternative for
"one-line section headings" and there is no plan to indroduce them.

The development version 0.17b.dev in the repository has experimental
support for Markdown sources, where they are part of the format
specification.

> My biggest issues with the current style are that
> It is uncomfortable to text search for all heading lines since the syntax
> makes them at least 2 lines
> and I have to change the size of underline when I change the text.

Some text editors__ will help you with this task.
I use the "JED programmers editor" with rst mode and Search>List_Routines
presents me with an "Outline" window showing the document structure as well as
functions to go to the next or previous section heading.


__ https://docutils.sourceforge.io/docs/user/links.html#editors

> Would be nice if I could just use some substitution or a directive or a
> role.
> But I do not seem to find anything sufficient in the documentation.
> And I do not want to modify or extend docutils.

> Apart from that the specification suits my ideas of beauty and simplicity.

You may also consider writing your own function to recognize headings,
something along::

   % Check whether the point is in a line underlining a section title.
   % (underline is equal or longer than previous line and previous line is
   % no adornment line and non-blank).
   % Leave point at bol of underline.
   define is_heading_underline()
   {
      !if (up(1)) % already on first line 
         return 0;
      % Get length of heading
      variable heading_len = get_line_len();
      if (not(re_looking_at(".*[a-zA-Z0-9]")))
          heading_len = 0;
      go_down_1();
      !if (heading_len) % blank line, no heading
         return 0;
      % Compare to length of adornment
      return get_line_len() >= heading_len;
   }  

(This is the S-Lang__ code used in the "jed" editor).

__ http://www.jedsoft.org/slang/

Günter