Thread: [Docutils-develop] Relax the 4-character minimum on section title underlines?

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

I am considering relaxing the 4-character minimum requirement for
reStructuredText section title underlines, and would like to determine
the best course of action.  The spec states:

    An underline/overline is a single repeated punctuation character
    that begins in column 1 and forms a line extending at least as far
    as the right edge of the title text. ...  An underline/overline
    must be at least 4 characters long (to avoid mistaking ellipses
    ["..."] for overlines).

    (http://docutils.sf.net/spec/rst/reStructuredText.html#sections)

The 4-character minimum on transition markers will remain, regardless.

Sometimes a title is less than 4 characters long, and it's natural to
want to use an underline of exactly the same length.  I've noticed
such cases in others' documents, and in my own.  In my own document, I
used a 3-character underline; the title was parsed as an ordinary
paragraph and it took some time to discover the problem and fix it,
because the parser produced no warning.

Here's the current entry in the "Bugs" section of the "To Do" list:

    Section headers must have underlines at least 4 characters long.
    But when the section title is only 3 characters long, it's natural
    to underline with "===" (I just did).  The parser should produce a
    warning in such cases.

    Or should the parser simply recognize such short underlines?  A
    zero-tolerance policy might work: over/underlines of 3 or fewer
    characters which are shorter than the "title" text are not
    recognized as titles, and should generate an "info" message.

There has also been a bug report submitted on the issue (by Jeremy
Hylton):
http://sf.net/tracker/?func=detail&atid=422030&aid=608108&group_id=38414

There's no problem with the typical case, where the over/underlines
are at least as long as the title text::

    ABC
    ===

    ---
    DEF
    ---

But what to do when the over/underline is too short?  Ellipsis ("...")
and m-dash (commonly written "---") both use 3 repeated punctuation
characters; this ambiguity is what the 4-character minimum avoided.  For
example::

    Is This Supposed To Be A Title?
    ---

    This, surely, is not
    ...

In these cases, I'm thinking of inserting INFO (level 1) system
messages that say, "Possible title underline, too short for the title
text.  Treating it as ordinary text because it's so short."  INFO
system messages are not normally visible (shown only if the
-v/--verbose option is used).  In other words, short underlines (<= 3
characters) are recognized as title adornments if they're long enough
for the title text, but if they're too short they're just wrapped text
plus a normally-invisible system message.  I think this is the right
balance of precision (unambiguous, unsurprising) and "do what I say"
(intuitive).

How about these cases, of overlines?  Unless stated otherwise, the
short overlines would each be treated as ordinary text and an INFO
system message inserted::

    ...
    This is not a title; perhaps an excerpt from a quote.

    ..
    This is interpreted as a comment start immediately followed by a
    paragraph.  Triggers a "no blank line; unexpected unindent"
    warning.

    ==
    These lines would not be interpreted as a title.
    ==

    ---
    The three dashes above might represent an m-dash.

    ==
      Would this become a definition list?

    ==
      And what about this?  A definition list item followed by a
      paragraph and a "no blank line; unexpected unindent" warning.
    ==

And when section titles are not expected/allowed::

    Ordinary paragraph.

        This title should trigger a SEVERE error (sections not allowed
        inside block quotes), as currently happens with longer titles:

        ABC
        ===

        This title should trigger an INFO message and be treated as an
        ordinary paragraph, since the underline is too short for the
        title:

        ABC
        ==

Does all of this seem reasonable?  Any gotchas I'm missing?

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Thread: [Docutils-develop] Relax the 4-character minimum on section title underlines?

docutils-develop