[Doc-SIG] Re: reStructuredText Markup Specification

[castor@snafu.de]

>You make some good points (perhaps a little heavy on the hyperbole? ;-). I'd
>like to take some time to consider your position and compose my reply.

Admittedly there's some hyperbole to it... but then... It's just that
I do think indention is a Good Thing, that's it. The underline stuff
is in fact more readable *locally* (did I omit that in my posting?), 
that is, when you have one heading plus a few lines and then some. 
Globally, however, and when more than two heading levels come into play, 
I think indention is more readable (and more reliable) (and theoretically
more pleasing, at that).


>Let me assure you though that I don't intend to abolish indentation.
>Challenge it, propose and implement an alternative, yes. The whole point of
>the DPS is that there doesn't have to be one and only one way. The result of
>competition could be the survival of the fittest, or amicable coexistence,
>or cross-pollination, I don't know. But it would be good to have
>competition.

A day later, perhaps the main point on my side is 
about procedure, and that means to me that we should build a 
down-to-earth format, something "like python", that might even 
look clumsy to some people, something with a boring, but steadfast syntax.

That done, let's talk about "situations" or "textual constellations", 
in one and in two dimensions, about character classes and so forth.

Then, alternative interpretations of situations can be used as 
shortcut to features, replacing "eloquent" markup with a more 
"symbolic" or "iconic" one. Such shortcuts would be configurable
at least to the extent that a developer can clearly delineate what
is markup and what is core, perhaps to the extent that a user can choose
among several "formats" or write their own (even if for the special 
purpose of docstrings, one or a few specific "format" definitions
will have to be prescribed). The shortcuts could always be discarded,
backing up to the "eloquent" markup would be possible. This way, we
can make features available before we actually decide on a specific
"iconic" notation for it. Then, I can test e.g. hyperlinks, references
and annotations with (inventing a syntax)

   Please $$a{$$href{http://xy.com}click here}. As discussed 
   in $$ref{BLOCH}, gnus have four legs.$$note{most of the time, at least.}

and so on, and perhaps if someone comes up with nice iconic 
replacements for some of these thingies, sometime later
the same would be expressable as (again blindly inventing something)

   Please ***http://xy.com click here***. As discussed 
   in [[BLOCH]], gnus have four legs.$$note{most of the time, at least.}

In the above, some features have been shortcut, and they 
happily co-exist with eloquent markup for those cases that
have perhaps not yet received an alternative representation, or not
ones that the author happens to like. On a slightly bigger
scale, such a mechanism could even alow for the coexistence 
of under/overlining style and indention style for section 
heading.


-wolf