[Doc-SIG] Re: reStructuredText Markup Specification

[castor@snafu.de]

On Fri, 15 Jun 2001 00:48:24 -0400, David Goodger <dgoodger@bigfoot.com> wrote:

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

I see a tab in my copy, and that's what I sent...

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

It's obviously not limited to that. Four characters
would be possible, too:

#### Very Important ####
==== Read this ====
---- Also important ----

I concede I might have the idea from 
some spam mail.

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

"Style" here refers to the choice between structure-
by-indentation or structure-by-character-markup. In
other words, if the first heading uses '####', and the
following heading has no indentation either, but 
uses, say '****', than all levels in the docstring 
are determined by character markup. 

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

Yeah, I know. No problems with that. They should be 
allowed.

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

Yes. This was not, as the rest of the text was not, aimed
against anything or anyone. (I guess I've been writing too
in-flamed recently, so people automatically expect I'm
attacking someone with every sentence.) This only serves
to re-state a suggestion made earlier by, I think, David,
and it is not unique to either "surrounding" or "underlining"
headings. In both cases, the freedom of choice is the freedom
to use either style: structure-by-indents vs. structure-by-
character-markups. 


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

I always delete my spam mail :-) When I tried out this
variant, it looked very familiar to me. Maybe it's primary
use is really for emphasis. Headings are emphasized portions
of the text. 

But I guess the case is pretty much settled in favour of 
(1) underlined, (2) non-indented headlines, if this forum were
to vote. 

-Wolf