[Doc-SIG] using the same delimiter on the left and right..

[Tony J Ibbs (Tibs)]

46 (!!!) messages on Doc-SIG to process this morning - aagh (but heh,
it's a healthy sign, I hope)

Goodger, David (?) wrote:
> Just a little reminder here, guys.

and he points out his previous documents (which for anyone who had
downloaded early versions of docutils, you already have therein...)

>   - A Plan for Structured Text
>     http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
>
>   - Problems With StructuredText
>     http://mail.python.org/pipermail/doc-sig/2000-November/001240.html
>
>   - reStructuredText: Revised Structured Text Specification
>     http://mail.python.org/pipermail/doc-sig/2000-November/001241.html

Strangely enough, I planned to
a. mention them this morning as "if we're reworking stuff radically, we
should look at what David had to say", and
b. read them this weekend (assuming Joan's flu doesn't get me - in which
case, what with child's birthday party and flu, I might be out of
commission for a while...)

> Specifically, backticks ("`") are good for inline literals.

I'm increasingly coming to like them for that - it also solves the
"hard space" problem in plain` `text.

> Hash marks ("#") are unbearably ugly.

Hmm. I've come to like them, rather a lot - partly because they're ugly
enough to stand out, which to me is good.

> in an agile (new P.C. term for "lightweight";
> see http://www.agilealliance.org) markup scheme, we don't
> need all four of (inline, block) x (alien text, Python code);
> I think that's up to the tool to deal with.

Of course, I disagree rather strongly (I would, wouldn't I!). Also, I
don't like the un-emphasis on documentation on that page - if I develop
software, documentation is for *me*  - it's a vital communications media
both to me-of-the-future, and also to customers who have to *use* the
bloody stuff (I've worked long enough in the industry to go from no
documentation and no up-front design towards some of each that I don't
want to lose either, if you see what I mean. Anyway, that's another
argument - docstrings are for *me*, for use in *my* code).

NB: it's *not* "Python code" blocks - it's "doctest" blocks - i.e., if
I'm going to use doctest, I don't see why my presentation tools
shouldn't highlight the doctest fragments neatly for me!

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