[DOC] Fixes for link fragments (#7981)

2 files changed, 20 insertions, 17 deletions

diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md
index 907d935de9..ccfc7be294 100644
--- a/doc/contributing/documentation_guide.md
+++ b/doc/contributing/documentation_guide.md
@@ -41,16 +41,17 @@ Use your judgment about what the user needs to know.
 - Write short declarative or imperative sentences.
 - Group sentences into (ideally short) paragraphs,
   each covering a single topic.
-- Organize material with [headers](rdoc-ref:RDoc::Markup@Headers).
+- Organize material with
+  [headings](rdoc-ref:RDoc::MarkupReference@Headings).
 - Refer to authoritative and relevant sources using
-  [links](rdoc-ref:RDoc::Markup@Links).
+  [links](rdoc-ref:RDoc::MarkupReference@Links).
 - Use simple verb tenses: simple present, simple past, simple future.
 - Use simple sentence structure, not compound or complex structure.
 - Avoid:
     - Excessive comma-separated phrases;
-      consider a [list](rdoc-ref:RDoc::Markup@Simple+Lists).
+      consider a [list](rdoc-ref:RDoc::MarkupReference@Lists).
     - Idioms and culture-specific references.
-    - Overuse of headers.
+    - Overuse of headings.
     - Using US-ASCII-incompatible characters in C source files;
       see [Characters](#label-Characters) below.
 
@@ -124,16 +125,16 @@ a.shuffle!    #=> [2, 3, 1]
 a             #=> [2, 3, 1]
 ```
 
-### Headers
+### Headings
 
-Organize a long discussion with [headers](rdoc-ref:RDoc::Markup@Headers).
+Organize a long discussion with [headings](rdoc-ref:RDoc::MarkupReference@Headings).
 
 ### Blank Lines
 
 A blank line begins a new paragraph.
 
-A [code block](rdoc-ref:RDoc::Markup@Paragraphs+and+Verbatim)
-or [list](rdoc-ref:RDoc::Markup@Simple+Lists)
+A [code block](rdoc-ref:RDoc::MarkupReference@Code+Blocks)
+or [list](rdoc-ref:RDoc::MarkupReference@Lists)
 should be preceded by and followed by a blank line.
 This is unnecessary for the HTML output, but helps in the `ri` output.
 
@@ -214,7 +215,7 @@ Guidelines:
 
 - The section title is `What's Here`.
 - Consider listing the parent class and any included modules; consider
-  [links](rdoc-ref:RDoc::Markup@Links)
+  [links](rdoc-ref:RDoc::MarkupReference@Links)
   to their "What's Here" sections if those exist.
 - List methods as a bullet list:
 
@@ -224,9 +225,9 @@ Guidelines:
       (and do not list the aliases separately).
     - Check the rendered documentation to determine whether \RDoc has recognized
       the method and linked to it;  if not, manually insert a
-      [link](rdoc-ref:RDoc::Markup@Links).
+      [link](rdoc-ref:RDoc::MarkupReference@Links).
 
-- If there are numerous entries, consider grouping them into subsections with headers.
+- If there are numerous entries, consider grouping them into subsections with headings.
 - If there are more than a few such subsections,
   consider adding a table of contents just below the main section title.
 
@@ -249,7 +250,7 @@ For methods written in Ruby, \RDoc documents the calling sequence automatically.
 
 For methods written in C, \RDoc cannot determine what arguments
 the method accepts, so those need to be documented using \RDoc directive
-[`call-seq:`](rdoc-ref:RDoc::Markup@Method+arguments).
+[`call-seq:`](rdoc-ref:RDoc::MarkupReference@Directives+for+Method+Documentation).
 
 For a singleton method, use the form:
 
@@ -388,7 +389,7 @@ argument passed if it is not obvious, not explicitly mentioned in the
 details, and not implicitly shown in the examples.
 
 If there is more than one argument or block argument, use a
-[labeled list](rdoc-ref:RDoc::Markup@Labeled+Lists).
+[labeled list](rdoc-ref:RDoc::MarkupReference@Labeled+Lists).
 
 ### Corner Cases and Exceptions
 
diff --git a/doc/encodings.rdoc b/doc/encodings.rdoc
index 1f3c54d740..3d09b298c9 100644
--- a/doc/encodings.rdoc
+++ b/doc/encodings.rdoc
@@ -137,15 +137,16 @@ returns the \Encoding of the concatenated string, or +nil+ if incompatible:
 A Ruby String object has an encoding that is an instance of class \Encoding.
 The encoding may be retrieved by method String#encoding.
 
-The default encoding for a string literal is the script encoding
-(see Encoding@Script+encoding):
+The default encoding for a string literal is the script encoding;
+see (Script Encoding)[rdoc-ref:encodings.rdoc@Script+Encoding].
 
   's'.encoding # => #<Encoding:UTF-8>
 
 The default encoding for a string created with method String.new is:
 
 - For a \String object argument, the encoding of that string.
-- For a string literal, the script encoding (see Encoding@Script+encoding).
+- For a string literal, the script encoding;
+  see {Script Encoding}[https://docs.ruby-lang.org/en/master/encodings_rdoc.html#label-Script+Encoding].
 
 In either case, any encoding may be specified:
 
@@ -190,7 +191,8 @@ the encoding may be retrieved by method Symbol#encoding or Regexp#encoding.
 The default encoding for these, however, is:
 
 - US-ASCII, if all characters are US-ASCII.
-- The script encoding, otherwise (see Encoding@Script+encoding).
+- The script encoding, otherwise;
+  see (Script Encoding)[rdoc-ref:encodings.rdoc@Script+Encoding].
 
 === Filesystem \Encoding