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

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> >     "preceed" should be "precede".
>
> How embarrassing.

Hmm - bear in mind I'm the one who posted documents with tabs in them!
Spelling happens.

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

Not particularly - but I wasn't saying the description was naff, or that
it wasn't a good way of doing things - it's just that it's a little more
ad-hoc than one might wish in a perfect life (it's not "intuitive"). On
the other hand, it does give good return for little learning effort,
it's not likely to go wrong, and it ain't worth trying to iron out with
something more clever and less easy to use. So "naff" is relative.

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

It *might* be worth emailing the person who wrote/maintains the code to
see if they are interested (and, of course, it gives them egoboo since
we're using their module as a contributing reason for adopting this
format).

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

Gosh - I clearly don't notice, but then I read a mix of books (and most
SF/fantasy, for instance, is US-published).

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

I think that a "Historical background" document, containing the pros and
cons of past arguments, would be a good thing - partly for the same
reason we have "refused" PEPs, and partly just 'cos that sort of thing
*can* be neat. Of course, it's yet more work to saddle you with.

> > that you are actually performing something of a
> > Grand Unification of the ideas and techniques
> > from ST and setext
>
> I never really thought of it that way. You make it sound so
> important! :-)

Hmm - you haven't watched the Doc-SIG for as long as I have. I don't
particularly care *who* gets a product out (you, me, Edward) so long as
we get one, and preferably one I like. Managing to get *this* near is a
Good Thing, and being able to do it by pulling together the very first
two threads of the Doc-SIG on this matter (!) is clearly something Very
Clever to pull off.

> I sort-of do. From introduction.txt, first paragraph:
>
>     reStructuredText_ is a proposed revision and reinterpretation of
>     the StructuredText_ and Setext_ lightweight markup systems.

True - I'd forgotten that by the time I got to this document.

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

No - it's actually already OK. It just didn't stick in my mind.

> (Kinda creepy, huh? Like a trans-Atlantic mental remote
> procedure call.)

Hmm - maybe we shouldn't go there!

Tibs

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