[Doc-SIG] Proposal for indented sections in reStructuredText

[Guido van Rossum]

> Guido van Rossum <guido@digicool.com> wrote:
> >I reject the argument that using indentation is Pythonic: text is not
> >code, and different traditions and conventions hold.  People have been
> >presenting text for readability for over 30 centuries.  Let's not
> >innovate needlessly.
> >
> >I think allowing indented sections because it's popular is unpythonic:
> >there should be only one way to do it.  Existing ST should be run
> >through a converter.
> 
> Guido, isn't indentation in Python a needless invention, too? 
> Programmers had gotten used to it as a redundant and semantically
> insignificant, potentially even misleading device. The real thing,
> for well over 3 decades, had been all curly and other braces, and 
> 'begin'/'end' blocks. It would have been logical to come up with a 
> language (or return to such languages) where indentation is considered 
> ungrammatical. Instead, curly braces and 'begin's and 'end's for blocks 
> fell prey to an innovative re-interpretation. Indentation has since 
> lost its misleading character and proven to be a valid, readable and 
> low-redundancy way to express structure in code text. 

Very funny, but not a reasonable argument.  Presenting program source
code has a history of about 50 years, and indentation has been part of
the presentation tradition for about 40 of those.  Plain text however,
has been around for, oh, 30 centuries, and I am as skeptical of this
"innovation" as I am of many other "improvements" to text presentation
that have been proposed by computer geeks.

Arguing the same point from the other direction, code has a much
higher structure-to-text ration than text (even if that text is
documentation for code), so the cost-benefits analysis comes out the
other way.  For text, the length of sections (often more than a page)
mean that the human reader isn't very good at keeping track of
indentation levels.  I bet you've been confused once or twice in your
life by a book where a significant indent coincided by a page break.
So we scan for the section headers to discern the section structure.

Given the way our brain works, indendation is best used for *small*
structure, which abounds in code, and indeed it is used for small
structure in text.

My conclusion: using indentation to discern section structure in text
would be as much giving in to the computer (which has no problem
keeping track of indents over many pages) as is using braces to
discern block structure in code.

> Others have extended this concept to replace markups in prose text. No
> fully grammatical implementation has been worked out so far. Indented 
> text is still in its inceptive stage with a, consequently, small user
> community. 
> 
> I understand from the second paragraph that indentation stands a chance
> only in so far as it is more popular than other devices to structure 
> text. I agree. If a majority turns out to be in favour of a more liberal 
> solution that allows more than one way, would that beat TSBOOWTDI, or is 
> TSBOOWTDI even above that?
> 
> -Wolf

Sure, but I would doubt a majority of votes in this forum, where geeks
are overrepresented.

--Guido van Rossum (home page: http://www.python.org/~guido/)