More on auto-link #9907
More on auto-link #9907
Conversation
| - The reference is to the current class document | ||
| (e.g., _Array_ in the documentation for class `Array`). | ||
| - The same reference is repeated many times | ||
| (e.g., _RDoc_ on this page). | ||
| - The reference is to a class or module that users | ||
| usually don't deal with, including these: |
There was a problem hiding this comment.
I recommend removing the last bullet as well. It mentions Class, Module, and Method. First, I'm not sure users don't usually deal with them. Second, even if they don't usually deal with them, there is no problem auto-linking when referring to the Ruby class/entity.
I think the only time auto-linking should be supressed is if the usage does not refer to the Ruby class/entity. Maybe:
In general, \RDoc's auto-linking should not be suppressed.
For example, we should write `Array`, not `\Array`.
However, suppress when the word in question does not refer to the Ruby entity
(e.g., some uses of _Class_ or _English_).
I don't agree. Using monofont signals that it's code, but linking to the same page (except linking to a particular section) is pointless and distracts the user from which links are useful to click on. |
You'd be comfortable with code for page self-reference, and auto-links for others? Text adjusted. |
| For example, we should write `Array`, not `\Array`. | ||
| However, suppress when the word in question does not refer to a Ruby entity | ||
| (e.g., some uses of _Class_ or _English_). | ||
| For example, we should write `Array`, not `\Array` |
|
Once we have consensus/approval for the specific reviewers here, I'd like to leave this open for a few days for any others to comment. |
@nobu suggests that a reference to a class such as
IO(even the local one) should be+IO+(to force monofont), not\IO(plain text). In my view, if it's not plain text, it may as well be auto-linked (IO), since both forced monofont and auto-linking cause both the font and the background color to be changed.Therefore I propose allowing auto-linking in almost all cases.
This proposed change does not imply that current docs should be revised for this purpose, but only that additions or revisions should consider this.