[Doc-SIG] Re: Proposal for indented sections in reStructuredText

[Ken Manheimer]

I'm a little frustrated by the intensity of the rhetoric in the
pro-indentation camp.  While i'm one of those that **like** using
indentation to indicate sectional structure, i've also heard enough
people express valid reservations that i realize that it's a mixed
bag.  I think it's misguided to argue as if there's some natural law
that makes it fundamentally "right".  (I particularly cringe when i
hear it called "pythonic" - or "unpythonic", for that matter.  I
suspect either term is purely unsubstantial in this context.)

On Wed, 13 Jun 2001 David Goodger <dgoodger@bigfoot.com> wrote:

> The vehement feedback from Wolfgang Lipp and Edward Welbourne, as well as
> the notes of regret from Ken Manheimer and Doug Hellmann, caused me to
> reflect on the real reasons why I reject how StructuredText uses indentation
> for sections. I then came up with a form of indented sections that I can
> live with, and I hope everyone else can too. The rejection rationale and
> proposed solution follow. Please let me know what you think.

To clarify, my note of regret was about the *need* for leaving it behind,
not doubts about the judgment that it may be necessary.  While david's
compromise proposal - allow both - appeals to me, i suspect we'd be better
off going with just not using indentation for sectional structure.  (As
with many of the ideas in the proposal, though, i think there's good
insight in putting the section header at the same indentation level as the
paragraphs!)

Here's what's crucial to me.  While i think it's easier to _read_ the
structure with section indentation, i also realize it's a genuine
nuisance for many people to have to _write_ that way.

It's a different thing to demand indentation for program text.
Program text has elaborate structure *expressed* through indentation -
most conventional programming languages (not just python!) require
exquisite indentation so people can easily read them.  The same is
*not* true of prose text!

The problem with the compromise comes in when someone edits someone
else's document.  If the first person has the tools and inclination to
do section indentation, then the next person may be obliged to do so
also, even if they lack the support and/or inclination.  (I'm not sure
whether the proposal allows them to be intermixed - but i also doubt
that would be a good thing.)

> (I would miss indentation as the cue for section depth nesting when
> _reading_ stx source - i find it more clear even than in the formatted
> presentation - but i guess for most people it's an unacceptable burden
> to _write_ by that rule.  So be it.)

In general, the more i think about the specifics of david's main
proposal, the more i like them.  I'm not sure the compromise improves
it.  I'm willing to accept it either way.

(BTW, i'd vote to we keep both the *<em>* and **<b>** styles of
emphasis.  I use them both, and find the implication so natural as to
not substantially add "cognitive burden".  Also, i really like the
idea of having the alternative heading styles to some degree up to the
author, depending just on their consistency rather than some memorized
canon.)

Ken
klm@digicool.com