Hello all,
How do I turn off creating a link out of a word that looks like
the name of a class I have? Preceding the word with “” does not work,
looks like it handles explicit markup only.
Best regards,
Yuri Leikind
Unfortunately, there’s no way to do this that I am aware of,
short of mangling the name somehow (e.g. prepending a _).
William
···
On Wed, Sep 03, 2003 at 12:32:23AM +0900, Yuri Leikind wrote:
How do I turn off creating a link out of a word that looks like
the name of a class I have? Preceding the word with "" does not work,
looks like it handles explicit markup only.
Is the problem here that you want to mention the name of a class but
don’t want to link to it, or is it that you have a class whose name is
also a common word in your comments?
One of the things I’m keen on is to keep the source comments looking as
natural as possible, so I’m not too keen on having something like:
Class CGI handles requests in a \CGI environment.
However, if this is a major problem, I guess I’ll have to (unless folks
have a neater way of flagging the “don’t link” attribute).
Cheers
Dave
···
On Wednesday, September 3, 2003, at 03:15 AM, William Webber wrote:
On Wed, Sep 03, 2003 at 12:32:23AM +0900, Yuri Leikind wrote:
How do I turn off creating a link out of a word that looks like
the name of a class I have? Preceding the word with "" does not work,
looks like it handles explicit markup only.Unfortunately, there’s no way to do this that I am aware of,
short of mangling the name somehow (e.g. prepending a _).
have a neater way of flagging the “don’t link” attribute).
#–rdoc-no-link: this that the_other
on a per “paragraph” basis ??
Cheers
Dave
Hugh
···
On Wed, 3 Sep 2003, Dave Thomas wrote:
But that wouldn’t work on the example I gave:
Class CGI handles requests in a CGI context.
···
On Wednesday, September 3, 2003, at 12:30 PM, Hugh Sasse Staff Elec Eng wrote:
On Wed, 3 Sep 2003, Dave Thomas wrote:
have a neater way of flagging the “don’t link” attribute).
#–rdoc-no-link: this that the_other
on a per “paragraph” basis ??
This case could be handled as:
Class CGI handles requests in a CGI context.
In this way, we’d be able to potentially generate acronyms (e.g., CGI) that look okay in text and
good in HTML. The biggest potential problem is when the acronym expansion
spans a line end.
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.
-austin
···
On Thu, 4 Sep 2003 04:45:15 +0900, Dave Thomas wrote:
On Wednesday, September 3, 2003, at 12:30 PM, Hugh Sasse Staff Elec Eng > wrote:
On Wed, 3 Sep 2003, Dave Thomas wrote:
have a neater way of flagging the “don’t link” attribute).
#–rdoc-no-link: this that the_other
on a per “paragraph” basis ??
But that wouldn’t work on the example I gave:Class CGI handles requests in a CGI context.
–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.09.03
* 16.24.56
Oh, yes, caffeine underflow error. What about
on a per “paragraph” basis, unless explicitly preceeded by
/[cC]lass\s+|[mM]odule\s+/
Maybe this smells of Eau de Kludge? 
The main thrust was to move the control out into ‘#–’ style
comments, like you already have, with room for future expansion.
Hugh
···
On Thu, 4 Sep 2003, Dave Thomas wrote:
On Wednesday, September 3, 2003, at 12:30 PM, Hugh Sasse Staff Elec Eng > wrote:
On Wed, 3 Sep 2003, Dave Thomas wrote:
have a neater way of flagging the “don’t link” attribute).
#–rdoc-no-link: this that the_other
on a per “paragraph” basis ??
But that wouldn’t work on the example I gave:
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).
Thanks
Dave
···
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.
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
···
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.
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 “::” 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:
- If a potential link is in a heading, then it should not become a link.
This would prevent the page title problem noted. - 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. - To compensate for #2, the ::Name rule could be adopted.
#1 isn’t entirely necessary, but it would be nice.
-austin
···
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).
–
austin ziegler * austin@halostatue.ca * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.09.03
* 21.28.54
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.
It’s on the list of things to do.
Dave
You are in a maze of twisty little passages, all alike. // halo • statue
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:
- If a potential link is in a heading, then it should not become a
link.
This would prevent the page title problem noted.- 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.- 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
···
On Wednesday, September 3, 2003, at 08:41 PM, Austin Ziegler wrote: