[Doc-SIG] backslashing

[Tony J Ibbs (Tibs)]

Edward Welbourne wrote:
> OK, two orthogonal questions about a verbatim fragment:
>    * inline or block
>    * python code or `alien text'
> giving us four kinds of `verbatim' fragment in doc-strings.
>
> As I've been understanding you, '...' is an inline alien and
> #...# is an inline python expression.

Correct.

There are (module spanish inquisition) reasons for having the two forms:
1. Python literals commonly include a single quote, but rarely include
comments
(this was the whole basis of your suggesting this notation, Eddy!).
Trying to use single quotes to indicate Python literals would be a right
pain.
2. I suspect that it *may* be useful to regard all Python code fragments
that contain a single Python entity (be it name or function call) as
potential "local links" - i.e., generate a reference from them. I know
that I didn't like Ka-Ping Yee's approach of aggressively looking for
all *potential* links in unmarked-up text, but once someone has
indicated that something is, indeed, Python code, I feel this is a risk
I'm more prepared to take.

> I've been presuming that there are also
> mechanisms for including (and distinguishing between) blocks whose
> contents are python or alien in like manner; however, I grant
> that I've only seen the '::' marker (unless >>> on each line is
> the markup for python, which I won't like, given that it's on each
> line)  used in such a
> role, and don't know whether you meant the block it introduces to be
> read as alien or python.  If you don't provide for this
> distinction, I'm
> worried.

No.

'::' introduces a literal "block", whose contents are not parsed. The
contents may include blank lines.

'>>>' at the start of a paragraph indicates that *that paragraph* is
Python code. Such a paragraph ends at the next blank line (or end of
file!). This is intended to allow the visual distinction of text that
will be specially handled by doctest (which is now a formal part of the
Python package, and whose use is To Be Encouraged (my opinion)).

They are thus serving a different purpose.

> [Further: I want to type
> your fictional
> example as::
>     If the user types::
>         x'
...etc...
> without the blank lines you inserted in it; the '::' on the
> end of each
> text line, and the return to its indentation at the next,
> should suffice
> to enable parsers to know what I meant.

The whole issue of *when* we start new paragraphs is likely to be a
major research issue after docutils 1.0, I suspect - we already know how
easy it is to boobytrap ourselves.

I'll leave the rest - I have a feeling that:
a. You're arguing towards agreement (indeed, you may already agree)
b. I'm not going to introduce any form of quoting in STpy alpha1
c. Probably not in STpy 1.0, either

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)