FW: [Doc-SIG] reStructuredText: Revised Structured Text
Specification
David Goodger
dgoodger@bigfoot.com
Sat, 25 Nov 2000 14:16:51 -0500
----------
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