[Doc-SIG] Cross-reference proposal

[Tony J Ibbs (Tibs)]

Paul Prescod wrote, on 09 February 2000 16:34:
> "Tony J Ibbs (Tibs)" wrote:
> > 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.
>
> Okay, but what is the real cost of the mis-identification?

Erm - it's wrong?[1]

But seriously, if I'm reading a document and come across a cross reference,
is it *really* too much to ask that it be relevant? I know I'm a pedant
(well, of some sort), but this is text that's meant to be *helpful* to
people, and if it consistently contains (or may contain) misleading cross
references, then that engenders distrust of the text - one never knows
whether it will be worth *following* a reference (I can hear it now - "drat,
that *!@X&! has cocked up their referencing again - I thought I'd find
something *useful* there!").

Also, it's pride - if I'm writing documentation in a doc string, then it's
MY text, and I don't want it to be mucked up by an (otherwise) useful tool.
Putting in *misleading* references would be such mucking up.

As for misleadingness - there *are* words in the english language that can
have entirely opposite, and certainly antagonistic, meanings in different
contexts. If the misreference in such a circumstance, life could get truly
confusing.

Tibs

[1] The pedant in me wants to leave it at that, on the grounds that the rest
is trivially derived from this, but since Paul asked I guess it *does* need
explanation...

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.co.uk/
.. Haskell is the most Pythonic of all the languages that are entirely
.. unlike Python <0.9 wink> (Tim Peters)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)