From: William Webber <william@...>
Date: 2003-09-05T12:28:39+09:00
Subject: Re: RDoc: how to turn off automatic linking for a word?

On Thu, 04 Sep 2003 05:30:47 +0900, 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.
> 
> ::CGI would be recognised as a top-level constant and turned into a link, 
> just like #foo would be.

I vote for this.  However, it does mean that in the situation of a class
that is not top-level (for instance, is within a module namespace), we
have to use the fully-qualified name.  Take, for instance, drb/drb.rb:


module DRb

  class DRbServer

  end

end

We'd have to talk about DRb::DRbServer rather than just DRbServer
(::DRbServer would be bad and misleading Ruby).

Actually, having rdoc'd several complex stdlib files now, I'd much prefer
rdoc to be pickier about, or at least to recognise, proper identifier
scoping.  At present, rdoc recognises the last definition of foo() in 
a file as the only definition of foo(), even if there are a dozen classes
that all define foo(), and links all references to foo() to that foo(),
and there is no way to get it to do otherwise (that I am aware of).  This
is particularly confusing with new().

William