[Doc-SIG] reStructuredText: Revised Structured Text Specification

[David Goodger]

Hi Bob,

I think a lot of people are in the same situation as we are, and have the
same frustrations. 

> Just as an example of my problems, I find the current table layout mechanism
> interesting, but too limited. I had an idea that if I could add just a small
> wart to the layout, that I might be able to introduce the following:
> 
> <table class="events">

This is exactly the kind of thing that extensions to the spec are for.
Either subclassing the 'table' class for an implementation-specific quick
fix, or implementing a general extension along with a directive, like::

    .. table-class:: events

or::

    .. table:: class="events"

The latter could be a useful general way of adding attributes to arbitrary
structures.

The point is that the core syntax should be kept as minimal as possible.
Everyone will have specific extensions they need; an extension-enabling
mechanism is the key to making everyone happy.

Until now, the proposals have been of the 'all or nothing' variety. Person A
will say, "let's add feature X to StructuredText". People who see this as
cluttering up the syntax will never agree, Person A gets discouraged, and in
the end nobody gets to use feature X.

I see a future where there's the core Structured Text, plus a 'menu' of
optional add-ons. So we order up a 'Structured Text with table extensions on
the side'. (And hope the implementation doesn't ask, 'You want fries with
that?' :-)

> A second problem I have is that simple itemized lists are set as complete
> paragraphs.  In HTML this is a terrible waste of vertical space.

A simple matter of tweaking the HTML output model for layout efficiency.
From a document architecture point of view, having list items containing
paragraphs (and other lists, code blocks, etc.) is a much cleaner model. But
there's no reason that the HTML module couldn't be smart enough to make its
output layout-friendly.

> In any event, I need to get something done soon, so I am curious as too how
> much of this you have coded. Are you still trying to get the spec complete?

Yes, it's in the design/conceptual phase now, finalizing the spec, and
thinking about the implementation. I made an aborted attempt to write
something (many months ago) based on ST-TOS. At this point, I see two
possibilities:

1. Jim Fulton at Digital Creations sees my proposal, thinks it's great, and
   decides to rewrite ST-NG based on it (or some subset). Of course, I would
   be happy to help out.

2. A new, from-scratch version is started my myself and anyone else who's
   interested.

> Do you think it is worth doing even if the Doc-SIG doesn't jump on-board at
> first?  (If you build it, will they come?)

Yes, we'll go the distance! People are always skeptical of proposals without
code to back them up. I'm hoping to get feedback (of both the 'how about
this?' and 'that sucks!' varieties) to firm up the spec so that an
implementation will have a better chance of being accepted.

> If this has a chance of becoming usable in a short while (at least in a
> development version) then I would consider it a useful use of my time to help
> since it will get me to my more important goal sooner.

A chance? Sure. How much of a chance? You'll have to stay tuned (and
continue to contribute, I hope!).

Thanks for your input.

BTW, would it be OK if I shared your original message and this reply with
Doc-SIG?

Just had an idea. One of the Python-specific extensions that's obvious is to
mark up a block of text that begins with '>>> ' as a code block (and splice
in Tim Peters' doctest too). Looking at this message, an email extension
that marks up blocks of text where each line begins with '>'+ as block
quotes would also be obvious. Oh, the possibilities!

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