[Doc-SIG] Cross-reference proposal

[Ka-Ping Yee]

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