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

[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 <[e-mail]>
Reply-To: ruby/ruby 
<[e-mail]>
To: ruby/ruby <[e-mail]>
CC: Subscribed <[e-mail]>

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



Unsubscribe: <mailto:[e-mail]?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>