[Doc-SIG] reStructuredText: Revised Structured Text Specification

[Ken Manheimer]

On Mon, 27 Nov 2000, David Goodger wrote:

> on 2000-11-27 13:52, Ken Manheimer (klm@digicool.com) wrote:
> >  However, i much prefer reading text with
> > indentation to indicate section structure!  The cost of a 14 or 16
> > character right margin for level *7* sections seems not so bad, and i
> > would be dubious of extensive level 7 sections, besides.
> 
> Granted, this may be a personal preference issue. My 'wasted space' argument
> is minor, compared to the ambiguity and difficulty of using indentation for
> section structure. It would be painful to write up indented text using
> SimpleText or NotePad. I think requiring the use of Emacs or VI (or

I think that neither the ambiguity nor the difficulty are clear-cut cases
in either direction.

Indentation is a nearly ideal cue for local sectional relationships - it
makes it abundantly clear which sections are deeper than which.  In fact,
i usually *prefer* the raw structured text content to the html-rendered
version, because i find the indentation to be a way more self-evident cue
than the section header font sizes.  (For some more personal-preference
territory, i also find it clearer than your underline styles, and i find
the underlines clutterful.)

Conversely, indentation is harder to compare across large distances in a
document, unless you can line up the columns and compare, or your editor
has a ruler (i think wordpad does, not sure about notepad).  

Of course, if the issue at hand is docstrings, you don't have to worry
about such large bodies of text.

As far as difficulty, i don't quite see it.  I often use structured-text
style organization in email messages (for memos and such), and edit using
pico - which doesn't do fancy indented-block flows like emacs or vim.  I
spend some time getting things to line up, but not a lot - and for text
that's going to be processed, you don't need to worry about the left
margin, the text is going to be flowed by, eg, html, anyway!

I don't mean to dismiss either of these things, i realize they can be real
drawbacks in some situations (large documents and deficient tools).  
However, when it comes to python docstrings, people are already going to
have to be dealing with indenting the python code - if they can deal with
that, they can probably deal with indenting paragraphs.

> equivalent) would decimate the potential user base of this format. Even with
> Emacs, I would code my own extension rather than use indentation where
> indentation isn't warranted. As for ambiguity, what do we do if the 'parent'
> paragraph is 2 lines long, and the 'child' is indented, ie::
> 
>     This is the parent
>     paragraph.
> 
>         Here is the child.
> 
> StructuredText allows for 1-line parents as titles. Would the above example
> become a block quote? If so, how would one code a block quote with a 1-liner
> parent paragraph?

I may be missing something here. Punctuation at the end of the line, quite
suitably, disqualifies it as a header.  And i didn't think that structured
text presents anything as a blockquote!  It's not a bad idea, but probably
should be constrained (to avoid the problem you're sketching), maybe to an
indented block that begins and ends with '"' double quotes.

> Again, personal preference is probably the overriding factor.

But keep in mind that there are fine lines here - structured text
embodies some difficult-to-attain economies, pretty successfully, and i
think it's easier at this point to disrupt those economies than it is to
improve them.  I don't mean to say there's not room for improvement, by
any means - but consider your above example, where structured text was
doing the right thing for good reasons, even when you didn't expect it to
do so.  There's some cruft in it (footnotes and tables come immediately to
mind), but it's generally not easy to twiddle it to advantage.

> > I also don't like use of '\' for quoting.
> 
> I indented '\' for *escaping* only, vehemently *not* for quoting. An

Whoops - i meant escaping, not quoting.  Inline code blocks are *supposed*
to inhibit other processing, and example:: blocks should do so also - with
the one side effect that they turn the text to fixed-width fonts.

> escaping mechanism is needed, as has been discussed ad nauseum on this
> mailing list and elsewhere, including
> http://www.zope.org/Members/jim/StructuredTextWiki/NGEscaping. Escaping the
> markup will be only rarely needed, but without it certain tasks (like
> documenting Structured Text!) become very difficult. For most cases, code
> blocks are better, I agree. But *something* is needed, and I see no better
> alternative.
>
> Single-quotes for inline code markup prevents us from using them for their
> natural purpose. It is a wart that should be removed. Ever compared a novel
> published in the US to one published in the UK? Notice the quotes around
> dialog. 

I guess at this point the most valuable thing would be to see some
motivating examples - reasonable things people want to do where inline
code markup and example:: blocks won't suffice.  I don't mean to question
the need, but think that being specific will probably help identify
exactly what the need is - the requirements.

> This must have been a recent addition; didn't see it last time I visited the
> site. Yes, it's quite similar. It lacks the use of '+' at intersections,
> though; '+'s make parsing the table simple, and allow '|' within cell text.
> Jim's suggestion is slightly easier to type.

According to the change history (not yet exposed to non-manage accounts,
should be soon, when i get done w/WikiForNow), nov 17, just 10 days ago...

> > Overall, i'm really glad to see you paying careful attention to this,
> > and i'm hoping you and tony and whoever else is interested can pool
> > your efforts, make it work...
> 
> Thank you. I hope so too!

Cool.

Ken
klm@digicool.com