From: Austin Ziegler <austin@...>
Date: 2003-09-04T10:41:31+09:00
Subject: Re: RDoc: how to turn off automatic linking for a word?

On Thu, 4 Sep 2003 07:28:05 +0900, Dave Thomas wrote:
> On Wednesday, September 3, 2003, at 03:30 PM, Austin Ziegler wrote:
>> For the general case, why not reverse the model (or at least make it
>> possible to reverse the model)? Make it so that there is no automatic
>> linking? That is:
>> # Class ::CGI handles requests in a CGI context.
> That might work. Before I get too deep in to this, though, could someone
> post links to examples where this is a problem (so I can get a feel for
> the issue).

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. Immediately below that is "Simple object transaction" 
-- and "Simple" is linked. Again, this one doesn't necessarily make sense, 
but would not work under the "::<name>" rule because it's not a top-level 
match. Frankly, I don't really want to see ::Transaction::Simple to make 
this work, because it's just plain ugly.

The case that fits the described possible solution is the subtitle "Named 
Transaction Usage" where Transaction is a link.

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 isn't entirely necessary, but it would be nice.

-austin
--
austin ziegler    * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.09.03
                                         * 21.28.54