[Doc-SIG] Cross-reference proposal

[Tony J Ibbs (Tibs)]

<awkward>
Ka-Ping Yee wrote, on 08 February 2000 11:51:
> Note that simple bare words are never interpreted as references.

Urm - but...

> To refer to something, an identifier must be capitalized and match
> a class name,

that sure sounds to me like it could be a "simple bare word" - if I have a
class called London that handles data relating to the city of London, then
I'll certainly use the noun and the class name in the same text.

> or be followed with an open-parenthesis and match a
> function or method name,

The company I work for have a customer who are the Ordnance Survey for Great
Britain (as opposed to the Ordnance Survey for Northern Ireland, who are
*not* the same people). This is commonly abbreviated OS(GB) (strangely
enough, OSNI is not OS(NI)). It is not inconceivable that code written to
handle OS(GB) data might have a function somewhere called OS()... (and I
would not be prepared NOT to write such code just to make the documentation
processing easier!).

> or be preceded by "self."

OK - I find it harder to come up with an awkward example for this one, *but
I bet I could given enough time to think* (heh, I've been *paid* to be a
pedant on occasion!).
</awkward>

The point? I think that we MUST require some delimitation for words/phrases
that are to become links into the code, because *in practice* it is not
possible to guess often enough (and I don't regard my awkward examples of
the guessing failing as "odd" cases at all, thank you very much).

The alternative suggestion (flag the awkward cases to say "don't guess wrong
here") seem to me truly horrid.

(I've used a documentation preprocessing system which, whilst dumber - it
doesn't discriminate *nearly* as well as your algorithm - still illustrates
the sheer frustration of typing perfectly normal english text and having odd
words highlighted when one doesn't want them to be.)

despite-this-the-output-of-your-algorithm-is-very-pretty,guv
	Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.co.uk/
.. "equal" really means "in some sense the same, but maybe not
.. the sense you were hoping for", or, more succinctly, "is
.. confused with". (Gordon McMillan, Python list, Apr 1998)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)