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

[David Goodger]

on 2001-08-03 6:02 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote:
> Problems with StructuredText version 1.32 of 2001/07/20
> =======================================================
> 
> prob:`Formal Specification`_
> 
>     "preceed" should be "precede".

How embarrassing.

> prob:`Character escaping mechanism`_
> 
>     After the paragraph starting "The best choice for this...", maybe
>     add a note along the lines of:

Added:

    (On 2001-03-29 on the Doc-SIG mailing list, GvR endorsed backslash
    escapes, saying, "'nuff said.  Backslash it is." Although neither
    legally binding nor irrevocable nor any kind of guarantee of
    anything, it is a good sign.)

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

Deleted from problems.txt, but I've left it in rst-notes.txt.

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

Perhaps it's better to think of "::" as pure markup, which disappears
from the processed output as would the asterisks in *emphasis*. As a
special case, if the "::" ends a paragraph preceded by non-whitespace,
we keep one ":" in place.

Is that less naff? :-)

> prob:`Tables`_
> 
>    This is good. Does the Emacs mode support "====" lines?

No, not yet. Unfortunately, the table.el code is hard-coded to '-'
now, and I haven't had time to brush up my elisp to tackle the
modification. Any elispers out there who'd like to take this one on?

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

No, honest! :-) Every time I read a novel published or printed in the
UK, dialogue is single-quoted.

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

No, I meant "downplay" or "minimize". When you stick a URI in the
middle of a sentence, it tends to interrupt the flow. Putting it in
paretheses alleviates that a little.

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

The "Problems" document was really my working notes for the
development of the reStructuredText syntax. I missed a few
alternatives. I'm wondering whether I should let "Problems"
stand, or maintain it as a record of further ideas and rejected
alternatives.

>     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 never really thought of it that way. You make it sound so
important! :-)

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

I sort-of do. From introduction.txt, first paragraph:

    reStructuredText_ is a proposed revision and reinterpretation of
    the StructuredText_ and Setext_ lightweight markup systems.

And the paragraph before the "Author's Note" in the "Goals" section:

    Also, it is not the goal of reStructuredText to maintain
    compatibility with StructuredText_ or Setext_. reStructuredText
    shamelessly steals their great ideas and ignores the not-so-great.

Do you think this should be combined and/or reiterated somewhere?

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

True. Your comments elsewhere have been duly noted and are being
pondered in my subconscious as you read this. (Kinda creepy, huh? Like
a trans-Atlantic mental remote procedure call.)

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net