RDoc: how to turn off automatic linking for a word?

[Yuri Leikind]

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

[Dave Thomas]

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 _).
>

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

[Hugh Sasse Staff Elec Eng]

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 ??

>
> Cheers
>
> Dave
>

Hugh

>
>

[Dave Thomas]

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]

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.

This case could be handled as:

# Class CGI handles requests in a CGI<Common Gateway Interface> context.

In this way, we'd be able to potentially generate acronyms (e.g., <acronym
title="Common Gateway Interface">CGI</acronym>) 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
--
austin ziegler * [email]austin@halostatue.ca[/email] * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.09.03
* 16.24.56

[Hugh Sasse Staff Elec Eng]

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.

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

[Dave Thomas]

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).

Thanks

Dave

[Austin Ziegler]

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).

[url]http://www.halostatue.ca/ruby/Transaction__Simple_doc/index.html[/url]

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 * [email]austin@halostatue.ca[/email] * Toronto, ON, Canada
software designer * pragmatic programmer * 2003.09.03
* 21.28.54

[Dave Thomas]

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

> [url]http://www.halostatue.ca/ruby/Transaction__Simple_doc/index.html[/url]
>
> 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

[William Webber]

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

[Dave Thomas]

> 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