[Doc-SIG] Re: reStructuredText Markup Specification

[David Goodger]

on 2001-06-14 8:39 AM, Wolfgang Lipp (wolfgang.lipp@epost.de) wrote:
> (Peter, thanks for pointing out the demerits
> of the other variants ;-)

I must have missed something... Did Peter point out more than "they suck"?
:-) (But seriously, did he?)

> *** Top level heading ***
...
>  *** Second level heading ***
...
> *** Title of Section 3 ***

Maybe your emailer condensed the whitespace, but I had to look long and hard
to see the 1-space indent of the second level heading.

> *** Top level heading ***
...
> +++ Second level heading +++
...
> *** Title of Section 3 ***

Are you serious about the '*** title ***' syntax? If so, the difference
between '***' and '+++' is *very* hard to see.

> Please compare all of the above with the readability
> of underlined headings, with identical text and spacing:

I've got to say I don't see '*** title ***' as being any more readable than
underlining. Less, I'd say: it's non-obvious to me and conflicts with inline
markup (*emphasis* etc.).

> (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).

Perhaps, but this seems a weak argument. reStructuredText specifically
allows underlines to be *longer* than the title text; there's no reason not
to have 75-character-long underlines to allow for future editing.

> Moreover, copying is safer and easier.

Why, 1 line versus 2?

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

Too similar, methinks. (And you can put *emphasis* or **strong** in
reStructuredText titles if you want to.)

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

Do you mean "the *level* is determined..."? I don't follow the rest of the
sentence either.

> *    headings may extend over more than one line

I was thinking of allowing that in reStructuredText also, like::

    This is a Very Very Very Very Very Very
    Very Very Very Very Long Title
    =======================================

Comments anyone?

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

I don't see how the proposed syntax aids in giving "freedom of choice." Care
to elaborate?

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

Could you provide any pointers to examples?

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net