[Doc-SIG] reStructuredText: Revised Structured Text Specification

[David Goodger]

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

Again, personal preference is probably the overriding factor.

> I also don't like use of '\' for quoting.

I indented '\' for *escaping* only, vehemently *not* for quoting. An
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. 

> As i see it, the goal is not to provide for
> every reasonable convention, but rather to provide a reasonable set of
> acceptible conventions that people can adopt as the common basis.)

This statement reinforces my rejection of single quotes for anything but
their ordinary language purposes.

> About tables ... Jim has a proposal for a
> much more comprehensive provision, which looks fairly similar to the
> one you sketch out:
> 
> http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextTables

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.

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

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - The Go Tools Project: http://gotools.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net (soon)