[Doc-SIG] Markup of identifiers (was: Cross-reference proposal)

[Tony J Ibbs (Tibs)]

Peter Funk wrote, on 10 February 2000 13:14
> Several possibilities to markup (tag) identifiers in doc strings:
>
> 1. #identifier#
> 2. [ident identifier]
> 3. *identifier*
> 4. 'identifier'
> 5. "identifier"
> 6. `identifier'
> 7. ^identifier

I've omitted the comments.

1 is Eddy's idea - I've commented elsewhere - it works but I don't like the
look either (but it might still be the best solution).

2 is too verbose (where one of the sister threads to this started!). The
simpler [identifier] variant was proposed in the earlier round of talks, and
is my favourite, but suffers from the "Eddy objection" - that "[" and "]"
are too valuable/used too much in Python to be reserved for this purpose (I
*think* that's the problem).

3 can't be used because it already is (emphasis) - firstly someone might
want to emphasise a cross reference (for example, me), and secondly you
can't actually *distinguish* a cross reference from plain text automatically
anyway (see the other thread)

4 and 5 both use quotes, which must suffer the "Eddy objection" (see 2), but
also I don't think you can force people to choose quote styles in doc
strings.

6 won't fly because "`" (that first quote char) is not in ISO 646 (or ASCII
if you prefer) and I don't think it's a good idea to *require* non-646 text
in doc strings (also, it's paired with "'", which is a valid character for
other purposes, so that doesn't work well - yu'd get confusion over what the
"'" was doing, I think).

7 would need a terminator, and can suffer the "Eddy problem".

Personally I like [reference], but I'm comfortably expecting this to be
solved by someone else in the implementation we eventually see (which I'm
not writing, you note) and I'll use their choice...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.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.)