From: Dave Thomas <Dave@...>
Date: 2003-09-04T21:39:36+09:00
Subject: Re: RDoc: how to turn off automatic linking for a word?


On Wednesday, September 3, 2003, at 08:41 PM, Austin Ziegler wrote:

> http://www.halostatue.ca/ruby/Transaction__Simple_doc/index.html
>
> Note that this doesn't solve every case. On the main page for that 
> one, I
> have the title "Transaction::Simple for Ruby". Transaction::Simple is,
> naturally, linked. It doesn't make sense, though, because the main 
> page *is*
> Transaction::Simple.

Except it _would_ make sense to link to yourself if it's a ways down 
the page, and you want to get back to the top (for example under 
'Contraindications'.

> I think that there are a couple of things we could suggest:
> 1. If a potential link is in a heading, then it should not become a 
> link.
>    This would prevent the page title problem noted.
> 2. Bare class constant references should not be linked. That is, in my 
> case,
>    Simple would not become a link. Only Transaction::Simple would 
> become a
>    link.
> 3. To compensate for #2, the ::Name rule could be adopted.
>

(1) is perhaps OK (although I can see cases where the current behavior 
useful). I'm still not sure about 2/3. Using ::Name is very unnatural, 
and wouldn't look right in comment blocks:

    # See the documentation in ::Simple for details

or

    # Class ::Simple is used as a proxy....

I'm still thinking about this one.


Cheers


Dave