[Doc-SIG] Re: reStructuredText Markup Specification

[David Goodger]

on 2001-06-07 15:04, Edward Welbourne (eddy@vortigen.demon.co.uk) wrote:
> Indentation is *the* pythonic way to express structure.

Indentation is *the* pythonic way to express *program* structure. But we're
discussing prose, not Python. Outlines use indentation, but prose text
rarely does.

> 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 ?

As many as the author likes. If you read the section on section structure
again, you'll see that the number, styles, and order of section titles is
taken from the document and not prescribed by the spec. All that is required
is that they be consistent.

> 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.

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!

> Wolfgang's points about moving a chunk of structure are good.
> I find his case compelling.
> 
> How could a pythoneer not ?

Python also has classes, methods, and functions to describe program
structure. These are not applicable to prose either. Apples and oranges.

But I'm just arguing for argument's sake. Before replying, please see my
proposal on indented sections (2 posts from now).

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net