[Doc-SIG] Cross-reference proposal

[Tony J Ibbs (Tibs)]

Ka-Ping Yee wrote, on 08 February 2000 21:45:
> Let me ask a radical question: if you had a class named London in
> your module, and you happened to mention the city of London in
> your docstring somewhere -- what would be so wrong with linking
> that mention to the class named London?
>
> Or if you have an argument named "capitalise" and somewhere in the
> documentation you use the word "capitalise" -- is it really a
> problem that that word is interpreted as referring to the argument?
>
> Surely if you "just happen" to use exactly the name of a class
> in your module documentation somewhere, it's somehow related... ?

My immediate (and thus emotional) response to that is "NO!". This seems to
be for two reasons:

1. I don't want spurious extra references that I don't intend (this is
important to me, but I can see from the above you might not care).

2. It's quite possible to use common words in ways which are *not*
applicable for the cross-reference.

Hmm - thinks a bit... OK, here we go with an example:

def BLOCKS(text,delimiter):
	"""Given text and a paragraph delimiter, return paragraph BLOCKS.

	burble burble burble on a flowline model burble. burble think of it as
pieces
	of text flowing along a pipeline burble if something goes wrong such that
the
	pipeline BLOCKS up burble burble.
	"""

Not a *very* contrived example. I've "highlighted" the word "blocks" as best
I can in email. Note that the second usage of the word in the doc string is
*not* a candidate for cross referencing. Given the nature of the english
language (I can't speak for others) such multiple binding of meaning for a
single word is common.

trying-to-give-constructive-criticism,honest-guv
Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.co.uk/
'Tim happens. Get used to it'. (David Ascher, on the Doc-SIG)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)