[Doc-SIG] Re: reStructuredText Markup Specification

[Wolfgang Lipp]

>
>It's just as easy to make an indentation error::
>
>    Title of Section 1
>
>        Text of section 1.
>
>        Title of Section 2
>
>            Text of section 2.
>
>      Title of Section 3
>
>          Text of section 3.
>
>If the beginning of sections 1 and 2 are not visible when viewing the
>beginning of section 3, it's very easy to make a mistake like the above.
>
>I have a big problem with the structure as expressed by the sections above
>(even without the error). The titles are indistinguishable from the text!
>
>Python also has classes, methods, and functions to describe program
>structure. These are not applicable to prose either. Apples and oranges.
>

All of the above is true: (1) it is possible to make errors, even (almost) 
invisible ones (mixing spaces w/ tabs, using different tabsizes etc.). 
(2) In principle, nothing tells you the difference between a heading and
a text -- in fact, a heading is text with a special function (and, yes, 
perhaps title case plus no dot at the end -- but how about questions as 
headlines?) (3) (Most) (prose) texts do not have classes, functions etc. 

(1) applies to other schemes as well, it is a very subjective factor.
(2) I do suggest there be some 'unusual', 'clear', 'salient' additional
markup to distinguish headlines from other blocks of text. I am not
happy with relying on missing punction, or on headlines having to 
be one-liners. (3) True, but, we have end-of-being and radiation fallout, 
plus we have * headlines, * codeblocks, * block quotes, * tables, 
*illustrations(?), elements structured in themselves to appear in a text
structured as * documents with * sections and perhaps *appendices. 
This is a potentially much richer structure than Python scripts typically
have. Different though they are, prose and program structures still seem 
related. Functions are much like the subsections of a written law, or a 
term definition. Literature and programming are not so different to me...
a good story or a play, like a program...



-Wolf