[Doc-SIG] Re: reStructuredText Markup Specification
Wolfgang Lipp
lipp@epost.de
Thu, 14 Jun 2001 21:39:49 +0900 (Tokyo Standard Time)
Discarding some lines I had already written, I think it is
more constructive to answer/continue on the lines of
thoughts expressed by David (<dgoodger@bigfoot.com>, Wed,
13 Jun 2001 00:26:52 -0400) and Peter (<pf@artcom-gmbh.de>,
Wed, 13 Jun 2001 08:21:16 +0200 (MEST)). David examines
four alternatives, differing in character markup
(underlines) and indentation.
Currently, I'd much prefer the style discussed by David as
number three (Peter, thanks for pointing out the demerits
of the other variants ;-) -- but with a slight variation
(the lines indicate the 'paper'):
+---------------------------------
| (1)
Documents may start right away at zero
indention; no document title is required.
*** Top level heading ***
All text and headings of the same logical
level receive the same amount of indent.
*** Second level heading ***
All text and headings of the same
logical level receive the same amount
of indent.
*** Title of Section 3 ***
All text and headings of the same logical
level receive the same amount of indent.
|
+---------------------------------
(1) is structure-by-indentation style; it has
an indentation-free alternative:
+---------------------------------
| (2)
Documents may start right away at zero
indention; no document title is required.
*** Top level heading ***
All text and headings of the same logical
level receive the same amount of indent.
+++ Second level heading +++
All text and headings of the same
logical level receive the same amount
of indent.
*** Title of Section 3 ***
All text and headings of the same logical
level receive the same amount of indent.
|
+---------------------------------
Since this is a liberal proposal, I would like to allow
the mixed form as well:
+---------------------------------
| (3)
Documents may start right away at zero
indention; no document title is required.
*** Top level heading ***
All text and headings of the same logical
level receive the same amount of indent.
+++ Second level heading +++
All text and headings of the same
logical level receive the same amount
of indent.
*** Title of Section 3 ***
All text and headings of the same logical
level receive the same amount of indent.
|
+---------------------------------
and suggest to derive levels in the intermediate form from
indentations and discard differences in the character
markups (though strict-minded people would perhaps be right
in suggesting that in such a case, indentations and
character markups must be coherent within a document).
The two styles do not conflict with each other. It
might be wise to disallow mixing styles in a single
docstring. The style is determined by comparing the
first heading in the text with the closest heading
that differs from the first in either character markup
or indentation.
Please compare all of the above with the readability
of underlined headings, with identical text and spacing:
+---------------------------------
| (4)
Documents may start right away at zero
indention; no document title is required.
Top level heading
*****************
All text and headings of the same logical
level receive the same amount of indent.
Second level heading
++++++++++++++++++++
All text and headings of the same
logical level receive the same amount
of indent.
Title of Section 3
******************
All text and headings of the same logical
level receive the same amount of indent.
|
+---------------------------------
Given that -- in all of the above examples -- heading/body
ratios are hardly naturalistic, and judicious use of
intervening white lines could help clarify things, I think
variants (1) and (3) are clearest, most readable, while (4)
compares somewhat better on this than (2). More than three
characters for the markups in (1), (2), and (3) would be
helpful.
(1), (2) and (3) all have the advantage that a change in
heading length does not entail a change in the markup
(separation of form and content). Moreover, copying is
safer and easier. Authors can switch freely between styles
(but not within one document), without there being
interpretational ambiguity.
The proposed markup also resembles traditional markups for
*bold* and such -- in fact, this is logical, since headings
in printed materials prefer big, bold type.
A reasonable set of constraints would look like this:
* the set of markup characters to choose from
is [*+~#-= ...]
* the markup that starts a heading must be identical
to the one that ends that heading
* the markup that starts and the one that ends a
heading must consist of exactly / at least three
identical characters from the above set
* intervening whitespace between the markups and the
text of the headline is discarded [and optional]
* in one docstring, either indentation-free indication of
levels or indication of structure by indentation is
allowed
* a mixed style is possible [, but must be coherently
applied (same level ==> same markup)]
* the style is determined by comparing the first
heading in the text with the closest heading that
differs from the first in either character markup
or indentation
* (in order to prevent ambiguities,) the mixed style
is considered a variant of structure by indentation
* headings may extend over more than one line
Being intended as 'more than a compromise', I propose the
described scheme as a way to allow authors freedom of
choice between indented and indention-free styles of
structural markup.
Some details of this plan -- indentation, headings by
enclosement within punctuation -- have enjoyed a certain
degree of popularity in 'typewriter-like', constrained
editing environments for the purpose of hassle-free, yet
clear indication of headings. Other details -- such as
using character markups for headlines at all, the omission
of extra indentation, the free and yet consistent use of
character markups for the indication of logical levels --
are ideas proposed recently in the group.
-Wolf