[Doc-SIG] Comments on the "problems with structured text"

[Tony J Ibbs (Tibs)]

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