[DOC] Correction for doc guide + TOC fix in File (#8505)

2 files changed, 14 insertions, 9 deletions

diff --git a/doc/contributing/documentation_guide.md b/doc/contributing/documentation_guide.md
index 6cb2b8d7dc..25a5fa1673 100644
--- a/doc/contributing/documentation_guide.md
+++ b/doc/contributing/documentation_guide.md
@@ -216,16 +216,21 @@ may not render them properly.
 In particular, avoid building tables with HTML tags
 (<tt><table></tt>, etc.).
 
-Alternatives are:
-
-- The GFM (GitHub Flavored Markdown) table extension,
-  which is enabled by default. See
-  {GFM tables extension}[https://github.github.com/gfm/#tables-extension-].
+Alternatives:
 
 - A {verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks],
-  using spaces and punctuation to format the text.
-  Note that {text markup}[rdoc-ref:RDoc::MarkupReference@Text+Markup]
-  will not be honored.
+  using spaces and punctuation to format the text;
+  note that {text markup}[rdoc-ref:RDoc::MarkupReference@Text+Markup]
+  will not be honored:
+
+    - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/file.c#L6570-L6596].
+    - Corresponding {output}[rdoc-ref:File@Read-2FWrite+Mode].
+
+- (Markdown format only): A {Github Flavored Markdown (GFM) table}[https://github.github.com/gfm/#tables-extension-],
+  using special formatting for the text:
+
+    - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/doc/contributing/glossary.md?plain=1].
+    - Corresponding {output}[https://docs.ruby-lang.org/en/master/contributing/glossary_md.html].
 
 ## Documenting Classes and Modules
 
diff --git a/file.c b/file.c
index 4a5c8a8f8a..6327b1cf94 100644
--- a/file.c
+++ b/file.c
@@ -6531,7 +6531,7 @@ const char ruby_null_device[] =
  *  \Class \File extends module FileTest, supporting such singleton methods
  *  as <tt>File.exist?</tt>.
  *
- *  === About the Examples
+ *  == About the Examples
  *
  *  Many examples here use these variables:
  *