[Doc-SIG] Comments on the "problems with structured text"
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Fri, 3 Aug 2001 11:02:03 +0100
Problems with StructuredText version 1.32 of 2001/07/20
=======================================================
.. namespace:: prob is problems.txt
prob:`Formal Specification`_
"preceed" should be "precede".
prob:`Understanding and extending the code`_
Paragraph 1: I'm glad someone else thinks so!
Paragraph 2: last sentence: yes, good.
prob:`Section structure via indentation`_
Paragraph 1: agreed.
List - first item: yep.
List - third item: "is indistinguishable from..." - erm, no it isn't
(since the docstring will have been processed to sort this out
first, one would hope!). Oh - maybe that's not true in ST[NG].
(I thought it was OK in STNG?)
prob:`Character escaping mechanism`_
After the paragraph starting "The best choice for this...", maybe
add a note along the lines of:
The opinion of the BDFL that this is the way to go, whilst not
conclusive, should be taken strongly into account.
prob:`Bullet list markup`_
Dropping the "o" - sensible.
prob:`Enumerated list markup`_
Nested enumerated list without indentation - I'd say this is a bad
idea - it's more complex, more ambiguous, and doesn't seem to me
to give any realistic gain.
prob:`Definition list markup`_
I don't particularly expect to change this, but I want to discuss it
elsewhere. I find it interesting that the BDFL proposal sounds like
what *I* thought he described as a layout he didn't like, when he
was saying he didn't like descriptive lists. But I haven't checked
that, and my memory *is* unreliable.
prob:`Literal blocks`_
I still think the distinction of whether there's a space before the
"::" or not is a bit naff, but it does serve a useful purpose, and
David obviously likes it.
The "::" on a line by itself thing is also a bit naff (even though I
came up with it), but it is also useful, and it does "fall out
naturally" (sort of).
prob:`Tables`_
This is good. Does the Emacs mode support "====" lines?
(I agree that option 2 is not as useful, and should be ignored.)
prob:`Inline literals`_
"In the UK, single quotes are used for dialogue in published works."
Hmm - no more than double quotes, I'd say - you've been reading old
books on printing again, haven't you?
As to the argument as to what sort of quotes to use - I think the
argument for backquotes *is* compelling.
The "TeX" use of directed quotes never actually looks right in plain
text using normal fixed width fonts, so is not an option for that
reason alone.
prob:`Hyperlinks`_
In "Alternatives" item 2, you use the phrase "de-emphasize the URI",
which doesn't make any sense to me. Do you mean "stop it being
*recognised* as a URL"? (anyway, I do realise it's only commentary
describing an option not taken).
You don't mention the (rejected) option of enclosing URIs in "<" and
">" (cf. email, etc). One major objection to this was the BDFL's
note that it was important to be able to write XML/HTML/SGML in text
without needing to quote it, and use of such a convention would make
that impossible.
In the "Alternatives" section, option 3 makes it clear that you are
actually performing something of a Grand Unification of the ideas
and techniques from ST and setext (with some new ideas added, of
course). I actually think that you should maybe mention (boast
about?) this up-front in the description of reST (whilst, of course,
pointing out that you are not being bound by the previous
"standards" when it does not seem sensible).
Later on, the paragraph "The two-dots-and-a-space syntax was
generalized by Setext for comments," is useful history, but I think
not a justification for *retaining* `.. arbitrary text` as a
comment...
--
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)