[Doc-SIG] Re: reStructuredText Markup Specification

[Edward Welbourne]

Indentation is *the* pythonic way to express structure.

I already know which depth of indentation is shallower/deeper of two.
I shall have to learn which (over- and) under-line style means what.
I cannot forget which depth of indentation is which.
I shall forget which of ====, ----, ...., ____ etc is shallower/deeper.
I shall forget which of them go before-and-after the title, which only after.

I can indent some more if I need to, no matter how indented I already am.
How many line-styles shall we define ?

Indentation is natural.  Folk use it in e-mails without any agreed
format, and use it in consistently intelligible ways.  All my
doc-strings use indentation already; and in my web pages I use
BlockQuote to indent asides, proofs and other subordinate material
relative to the main text; not just for aesthetic purposes, but equally
for the structural purpose of indicating its status as a subordinate
text.

When I wrote, for our testing engineer, a specification of what HTTP
content negotiation does, I was writing a singularly complex logical
proposition (when the functionality is enabled and the resource
requested is absent, if there are resources whose names differ therefrom
only in the addition of suffixes to which ...) so guess what - I
expressed its structure (on a whiteboard) by using: indentation.
That made it easier for Philip to keep track of its structure.

I do not believe one can draw any kind of a crisp boundary between
aesthetic and practical values in documentation: if the text does not
guide the eye to the information, it fails in its function; giving such
guidance to the eye is aesthetics.  Since not only programs but also
folk read code, I apply the same reasoning to code.

Putting a marker under or over a text looks ugly to me: albeit largely
because vertical space is precious to me and such a marker squanders a
whole line (or two).

Indentation stands out at least as clearly as such a line: and makes it
easy for me to see the structural truth - I can see, directly, where the
indented chunk starts and ends.  With line-styles, I have to not only
know precedence order of line-styles but also scan through the text
looking for lines of `a given style or shallower'; this is an
error-prone activity.  When a section's title tells me enough that I'm
going to skip the section - and all its subsections - I don't want to
have to scan that section, all the same, in search of the header line
which will end it - I want my eye lead rapidly and unambiguously to the
section's end, with as little risk as possible of missing the next
section.

If I (over- and) under-line a heading with the style two levels deeper
than the most recent heading, it's `wrong'.  If I indent by twice as
much as usual, it has aesthetic effect in the source; but is logically
one step deeper.

Wolfgang's points about moving a chunk of structure are good.
I find his case compelling.

How could a pythoneer not ?

	Eddy.