[ruby-core:101968] Fwd: [ruby/ruby] More on RDoc formatting (#4027)

[ruby-core:101968] Fwd: [ruby/ruby] More on RDoc formatting (#4027)

[Martin J. Dürst]

[Forwarding to ruby-core because I didn't find the text I want to 
comment on on Github anymore.]

If the links are too intrusive visually, we should change the styling 
(via CSS), not the markup.

Regards,   Martin.


-------- Forwarded Message --------
Subject: Re: [ruby/ruby] More on RDoc formatting (#4027)
Date: Wed, 06 Jan 2021 03:06:11 -0800
From: Burdette Lamar <notifications@github.com>
Reply-To: ruby/ruby 
<reply+AAGHDTN4SHG6SYQDKAD457F6AF5KHEVBNHHC45ATKU@reply.github.com>
To: ruby/ruby <ruby@noreply.github.com>
CC: Subscribed <subscribed@noreply.github.com>

@BurdetteLamar commented on this pull request.



> +Alignment may sometimes aid readability.
+
+=== Lists
+
+A list should be preceded and followed by a blank line.
+This is unnecessary for the HTML output, but helps in the ri output.
+
+=== Auto-Links
+
+Consider whether an auto-link (e.g., to +Array+)
+should be suppressed (<tt>\Array</tt>) or allowed (Array).
+
+It's usually best to suppress when local;
+that is, in the documentation for class \Array, suppress auto-links to 
the class itself.
+
+For an "off-class" reference, the decision to suppress or not may 
depend on context.

I'd like to hear more from others about this.  I find that the link 
(with its change of font and background color) to be intrusive, and so 
have generally suppressed.