[Doc-SIG] Cross-reference proposal

[Tony J Ibbs (Tibs)]

Peter Funk wrote, on 10 February 2000 12:55:
> Question: What is difference between a "marked up" docstring and a doc
> string, which is not "marked up"?  This must be easy to detect.

"must"? hmm...

Answer 1: A marked up doc string is one which contains markup.

This is the easy answer, but see:

Answer 2: You can't tell, because you can't distinguish a doc string that
*required* no markup (or so the writer decided) from one which (for
instance) predates the markup scheme.

In fact, I don't think it's a problem in practise.

Some person decides to run the appropriate tool over a particular Python
file, and I think it is reasonable to assume (for our purposes) that either
all of a file (maybe even a module) shall be marked up, or none of it shall
be (note the careful ISO-speak there). In that case, the person can make the
decision.

If Ka-Ping Yee wants to be *really* nice (and I don't regard this as a
requirement!) then he could have his script warn the user that there
actually *is* something that looks like markup in the text, and even (maybe)
attempt to use it - but that's a whole other discussion about trade-offs
(e.g., what if it *looked* like our markup but wasn't?,
and should the user be able to aver "ignore any characters that look like
markup"?). Etc.

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.)