Autolink directive

[nobu]

To control cross-reference linking.
Fix #1254.

[kou]

Suggested change

	@autolink = flag
	flag

[nobu]

Updated!

[st0012]

Can you add more examples in the description on how this would be used?

I think it'd be like this?

class MyClass # Mentioning MyClass in plain text won't be linked by default
  # :autolink: false
end

For not linking to specific words, like Ruby, Set....etc., they have a global effect in the project. And with that in mind, I think a centralized config like #1259 will be easier to maintain and understand.

Using directives for it could have a few downsides:

• It's easier to create unexpected side-effects that are hard to debug.
  • For example, RDoc used to use :main: in its doc and it unexpectedly changed ruby/ruby's main page too, which was why Restore options after option parsing #426 workaround was needed later.
  • If any default gem added :autolink: to, say Kernel, for its own documentation, then ruby/ruby would suddenly stopped linking to Kernel too once the code was synced.
• It's harder for developers to understand why a class/module isn't linked as they need to know that this directive exists. They'll eventually find it for sure after going through RDoc's docs, but a config in .rdoc_options should be easier to find in most cases.

So for ease of maintenance and understanding, I still prefer #1259 as the solution to #1254

[nobu]

• If any default gem added :autolink: to, say Kernel, for its own documentation, then ruby/ruby would suddenly stopped linking to Kernel too once the code was synced.

The inverse can be true.
A gem, for instance set defines a class Set, and suddenly all word Set begins linking.

• It's harder for developers to understand why a class/module isn't linked as they need to know that this directive exists. They'll eventually find it for sure after going through RDoc's docs, but a config in .rdoc_options should be easier to find in most cases.

There is unexpected linking risk, too.

In general, WiKi style autolinking is a sweet trap, for Ruby that capitalized words have the special meaning at least, I think.
We should encourage the use of explicit code linking, +Kernel+ etc, and should stop autolinking in plain text part in the future.

[kou]

Can we simplify this?

Suggested change

	autolink = @metadata["autolink"]
	if autolink
	RDoc::Options.boolean(autolink, "autolink")
	else
	true
	end
	RDoc::Options.boolean(@metadata["autolink"] || true, "autolink")

[nobu]

fetch may be better?

Suggested change

	autolink = @metadata["autolink"]
	if autolink
	RDoc::Options.boolean(autolink, "autolink")
	else
	true
	end
	RDoc::Options.boolean(@metadata.fetch("autolink", true), "autolink")

[kou]

Yes.

[st0012]

In general, WiKi style autolinking is a sweet trap, for Ruby that capitalized words have the special meaning at least, I think.
We should encourage the use of explicit code linking, +Kernel+ etc, and should stop autolinking in plain text part in the future.

I agree that this will be a better long-term direction 👍 But given this could be a breaking change, can you open an issue to expand this idea and we can discuss about the steps needed to get there?

[nobu]

What I don't like is we have to manage excluded words, like #1266, to add to each ".rdoc_options" file.