FW: [Doc-SIG] reStructuredText: Revised Structured Text Specification

[David Goodger]

----------
From: Bob Tolbert <bob@tolbert.org>
Reply-To: bob@tolbert.org
Date: Sat, 25 Nov 2000 09:19:38 -0500
To: David Goodger <dgoodger@bigfoot.com>
Subject: Re: [Doc-SIG] reStructuredText: Revised Structured Text
Specification

On Friday 24 November 2000 23:15, you wrote:
> =========================================================
>  reStructuredText: Revised Structured Text Specification
> =========================================================
> David Goodger (mailto:dgoodger@bigfoot.com)
> 2000-11-24


David,

Looks like you given this a bit of thought. I too happened upon the Doc-SIG
'war' while trying to find a decent method to document code. Specifically, I
am working on documenting all of wxPython, a monumental task, and I don't
want to do it twice.  I have been impressed with the concept of ST, but
unimpressed with the implementation.  I am very happy to write LaTeX, so I
find ST just too limited in it's current implementation and it is impossible
to comprehend in order to modify.

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

and then be able to get around the stylistic limitations by using CSS in the
HTML output.

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.

For example:

I might type HTML like:

<OL>
<LI>  one
<LI>  two
<LI>  three
</OL>

but in ST if I use the bullet layout, I would get:

<OL>
<LI><P>one</P>
<LI><P>two</P>
<LI><P>three</P>
</OL>


I clearly haven't thought about this as much as you, because I have a rather
narrow goal for what I want to document.

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

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.


Thanks for the thoughtful discussion,


Bob Tolbert