[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::

    ABC
    ===

    ---
    DEF
    ---

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::

    ..
    Hi
    ..

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

    ...
    Hi
    ...

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

    Hi
    ..

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:

    http://docutils.sf.net/docutils-snapshot.tgz

-- 
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/