From 14a0e19679c39e44b6fd002e2c5c184377e88547 Mon Sep 17 00:00:00 2001
From: Oskar Eichler <oskar@songstats.com>
Date: Sun, 30 Aug 2026 03:01:34 +0200
Subject: [PATCH 1/2] Hide embedded Racc runtime from generated docs

---
 Rakefile                     | 13 ++++++++++++-
 lib/rdoc/rd/block_parser.rb  |  2 ++
 lib/rdoc/rd/inline_parser.rb |  2 ++
 3 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/Rakefile b/Rakefile
index 988c01b80f..22f02b36bf 100644
--- a/Rakefile
+++ b/Rakefile
@@ -61,7 +61,18 @@ def generate_parser_file(parser_file)
   when '.ry' # need racc
     sh "bundle", "exec", "racc", "-l", "-E", "-o", parsed_file, parser_file
     File.open(parsed_file, 'r+') do |f|
-      newtext = "# frozen_string_literal: true\n#{f.read}"
+      generated = f.read
+      runtime_begin = "###### racc/parser.rb begin\n"
+      runtime_end = "###### racc/parser.rb end\n"
+
+      unless generated.include?(runtime_begin) && generated.include?(runtime_end)
+        raise "Racc runtime markers are missing from #{parsed_file}"
+      end
+
+      generated.sub!(runtime_begin, "# :stopdoc:\n#{runtime_begin}")
+      generated.sub!(runtime_end, "#{runtime_end}# :startdoc:\n")
+
+      newtext = "# frozen_string_literal: true\n#{generated}"
       f.rewind
       f.write newtext
     end
diff --git a/lib/rdoc/rd/block_parser.rb b/lib/rdoc/rd/block_parser.rb
index 256ba553e5..bbfd32ac9c 100644
--- a/lib/rdoc/rd/block_parser.rb
+++ b/lib/rdoc/rd/block_parser.rb
@@ -5,6 +5,7 @@
 # from Racc grammar file "block_parser.ry".
 #
 
+# :stopdoc:
 ###### racc/parser.rb begin
 unless $".find {|p| p.end_with?('/racc/parser.rb')}
 $".push "#{__dir__}/racc/parser.rb"
@@ -650,6 +651,7 @@ def token_to_str(t)
 
 end
 ###### racc/parser.rb end
+# :startdoc:
 
 class RDoc::RD
 
diff --git a/lib/rdoc/rd/inline_parser.rb b/lib/rdoc/rd/inline_parser.rb
index b6d521c6bd..5f008629a3 100644
--- a/lib/rdoc/rd/inline_parser.rb
+++ b/lib/rdoc/rd/inline_parser.rb
@@ -5,6 +5,7 @@
 # from Racc grammar file "inline_parser.ry".
 #
 
+# :stopdoc:
 ###### racc/parser.rb begin
 unless $".find {|p| p.end_with?('/racc/parser.rb')}
 $".push "#{__dir__}/racc/parser.rb"
@@ -650,6 +651,7 @@ def token_to_str(t)
 
 end
 ###### racc/parser.rb end
+# :startdoc:
 
 require 'strscan'
 

From 34957eebe39265c779b559883dc7442e2770dfb6 Mon Sep 17 00:00:00 2001
From: Oskar Eichler <oskar@songstats.com>
Date: Mon, 31 Aug 2026 16:45:06 +0700
Subject: [PATCH 2/2] Exclude generated RD parsers from documentation

---
 .rdoc_options                |  2 ++
 Rakefile                     | 13 +------------
 lib/rdoc/rd/block_parser.rb  |  2 --
 lib/rdoc/rd/inline_parser.rb |  2 --
 4 files changed, 3 insertions(+), 16 deletions(-)

diff --git a/.rdoc_options b/.rdoc_options
index be43dcd553..2e7b8a70a0 100644
--- a/.rdoc_options
+++ b/.rdoc_options
@@ -8,6 +8,8 @@ exclude:
 - AGENTS.md
 - CLAUDE.md
 - lib/rdoc/markdown.kpeg
+- lib/rdoc/rd/block_parser.rb
+- lib/rdoc/rd/inline_parser.rb
 
 footer_content:
   DOCUMENTATION:
diff --git a/Rakefile b/Rakefile
index 22f02b36bf..988c01b80f 100644
--- a/Rakefile
+++ b/Rakefile
@@ -61,18 +61,7 @@ def generate_parser_file(parser_file)
   when '.ry' # need racc
     sh "bundle", "exec", "racc", "-l", "-E", "-o", parsed_file, parser_file
     File.open(parsed_file, 'r+') do |f|
-      generated = f.read
-      runtime_begin = "###### racc/parser.rb begin\n"
-      runtime_end = "###### racc/parser.rb end\n"
-
-      unless generated.include?(runtime_begin) && generated.include?(runtime_end)
-        raise "Racc runtime markers are missing from #{parsed_file}"
-      end
-
-      generated.sub!(runtime_begin, "# :stopdoc:\n#{runtime_begin}")
-      generated.sub!(runtime_end, "#{runtime_end}# :startdoc:\n")
-
-      newtext = "# frozen_string_literal: true\n#{generated}"
+      newtext = "# frozen_string_literal: true\n#{f.read}"
       f.rewind
       f.write newtext
     end
diff --git a/lib/rdoc/rd/block_parser.rb b/lib/rdoc/rd/block_parser.rb
index bbfd32ac9c..256ba553e5 100644
--- a/lib/rdoc/rd/block_parser.rb
+++ b/lib/rdoc/rd/block_parser.rb
@@ -5,7 +5,6 @@
 # from Racc grammar file "block_parser.ry".
 #
 
-# :stopdoc:
 ###### racc/parser.rb begin
 unless $".find {|p| p.end_with?('/racc/parser.rb')}
 $".push "#{__dir__}/racc/parser.rb"
@@ -651,7 +650,6 @@ def token_to_str(t)
 
 end
 ###### racc/parser.rb end
-# :startdoc:
 
 class RDoc::RD
 
diff --git a/lib/rdoc/rd/inline_parser.rb b/lib/rdoc/rd/inline_parser.rb
index 5f008629a3..b6d521c6bd 100644
--- a/lib/rdoc/rd/inline_parser.rb
+++ b/lib/rdoc/rd/inline_parser.rb
@@ -5,7 +5,6 @@
 # from Racc grammar file "inline_parser.ry".
 #
 
-# :stopdoc:
 ###### racc/parser.rb begin
 unless $".find {|p| p.end_with?('/racc/parser.rb')}
 $".push "#{__dir__}/racc/parser.rb"
@@ -651,7 +650,6 @@ def token_to_str(t)
 
 end
 ###### racc/parser.rb end
-# :startdoc:
 
 require 'strscan'