[Doc-SIG] reStructuredText: Revised Structured Text Specification

[Ken Manheimer]

I like that you're nailing down your specs.  There are a couple of
things you're suggesing changing in structured text that i would like
to see changed - most prominent, allowing bullets without intervening
white space, etc.  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.

I also don't like use of '\' for quoting.  I don't see a hint of
intuitive motivation for it, except maybe for programmers familiar
with shell/C/programming-in-general quoting - which seems like a
different venue.  I'd like to stick with having people do literal
quoting by using code ('single-quote' bracketed) and "example::" -
these are self-evident in the raw form.

(If you're trying to cater to existing "natural" text, i doubt you'll
find use of '\' - and i think you're imposing an unfeasible
requirement, anyway.  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.)

About tables - *nobody* likes the current structured text abomination
for tables.  It betrays the principles (naturalness), and provides
woefully inadequate capability, as a bonus.-) 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

At cursory glance, they look extremely similar - jim's provides for
table header rows, which may be nice.  Both suffer from requiring a
lot of typing from the user for elaborate tables, and maybe some
complications in changing the table contents if it bursts the
boundaries of what you already have - but considering how hard it is
to create elaborate tables in html, maybe that kind of overhead is
inevitable.  Both are really nice in that they provide for arbitrary
(structured) text in the cells - i think this is proper.

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

Ken
klm@digicool.com