On Thu, 10 Feb 2000, Tony J Ibbs (Tibs) wrote:
Paul Prescod wrote, on 09 February 2000 16:34:
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?
Mmm. Okay. Well, first of all, let's carefully define and reduce the issue. Here is the list of kinds of auto-referencing again: 1. dotted.references to classes or functions in other modules 2. dotted.references to class methods or attributes 3. references() to class methods or functions 4. references to class names in the local module The question to ask, then, is: Of these cases, for which are there likely to exist situations where the cross-reference is misleading? So, first, i posit that #1, #2, and #3 are unambiguous enough not to bother anyone. That is, i hypothesize that no one would write <identifier>.<identifier> that happens to match the name of a module member or class method and *not* be referring to that thing. Does anyone have a problem with that much? #4 might be considered a little dangerous; more dangerous is 5. references to argument names in function and method docstrings since these are likely to be just ordinary unmarked words. It's #4 and #5 that concern you, right? Well, there is a spectrum of comfort zones for this kind of automatic interpretation. I think i have placed these categories in order, from #1 which i think is very solid, to #5 which i think is the most shaky. And #5 i would agree is approaching the limit of my comfort level. I didn't think that #4 would be too unreasonable to propose. Does it make you uncomfortable? (survey for all, not just Tony)
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!").
Right, well at least i don't think there ought to be a situation where the reader doesn't know whether it will be worth following a reference -- because i think it is a basic requirement that it always be transparently obvious what the reference will lead to. And i think that for #1 through #4 above this is true. (Even in cases where the introduced reference is spurious, it would still be quite obvious where the hyperlink will take you.)
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.
Yup. This is an entirely justified reason even if it may sound emotionally driven at first blush. I don't want anyone messing up *my* text either. :)
[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...
I'm glad that you broke it down into specific reasons. Thanks. -- ?!ng "Je n'aime pas les stupides gar�ons, m�me quand ils sont intelligents." -- Roople Unia