[Doc-SIG] Re: Relax the 4-character minimum on section title underlines?

David Goodger goodger@users.sourceforge.net
Thu, 19 Sep 2002 23:24:34 -0400

I have removed the 4-character minimum requirement for section title
underlines and overlines.  The following section titles will now
process as expected::



The original reason for the minimum was to avoid misinterpretation of
common punctuation constructs, such as ellipsis ("...") and m-dash
("---").  The parser now allows for such constructs where they may
otherwise be misinterpreted as title adornments.  For example, all of
the following will parse as ordinary paragraphs::

    This is not a title

    nor is this

    Or this

Level-1/INFO system messages are inserted wherever there's any
question.  Normally, level-1/INFO messages are not visible; to see
them, use the --verbose, -v, or --report-level=info options.

There is still one limitaton.  A two-period overlined title is not
possible, because it will be parsed as a comment start.  The text
immediately following will generate a warning because there's no
intervening blank line::


Extending the over/underlines to 3 characters makes it work::


A two-period *underline* has no problem though::


In other recent news:

* A subtle bug that introduced unwanted empty rows in some "simple"
  tables has been fixed.

* The locale-setting code in front ends has been made fault-tolerant.

* The definition of "simple reference names" has been altered
  slightly: internal hyphens, periods, and underscores may only occur
  one at a time, not two or more adjacent.  This prevents text like
  "object.__method__" from being parsed as a reference (because of the
  trailing underscores).  If any such text *does* exist, it can always
  be quoted like this::

    reference to `object.__method__`_

The CVS snapshot is always up to date and available at:


David Goodger  <goodger@users.sourceforge.net>  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/