誤 mention 問題残件

[znz]

プリプロセッサの #@since などで誤mention問題が残っているので、(Markdown 移行をアナウンスしてしまった後だが、) #@ 以外の良い prefix があれば変更したいです。

[znz]

#@since x.y
#@else
#@since x.z
#@else
#@end
#@end

のように else since のような途中のバージョン範囲を分岐したい組み合わせは頻出しています。

manual/doc/index.md のように途中は略記の since を使わず if にする方法もありますが、prefix を変更するなら、ついでにこのパターンにも専用の省略記法を導入したいです。

#@since 4.1
- 開発版対応リファレンス
#@end
#@if("4.0" <= version and version < "4.1")
- version 4.0 対応リファレンス
#@end
#@if("3.4" <= version and version < "4.0")
- version 3.4 対応リファレンス
#@end
#@if("3.3" <= version and version < "3.4")
- version 3.3 対応リファレンス
#@end
#@if("3.2" <= version and version < "3.3")
- version 3.2 対応リファレンス
#@end
#@if("3.1" <= version and version < "3.2")
- version 3.1 対応リファレンス
#@end
#@until 3.1
- version 3.0 対応リファレンス
#@end

[znz]

考慮したい点:

• GitHub のプレビューで表示されてほしいかどうか。表示されなくても良いなら HTML のコメント <!-- since x.y --> や PI (Processing Instruction) <?rurema since="x.y"?> という案がありそうだが、今の行ごとのプリプロセッサという見た目ではなくなりそう。
• #! や #= や #< や #. などは既存のドキュメント中に存在するので避ける方が良さそう。
• #if などの # 直後にすぐに英字は C 言語のソースを書いている部分もあるので衝突しそう。#数字 も irb.md や tracer.md の中にあるので衝突しそう。
• #: は rbs-inline と衝突するので避けた方が良さそう。

[znz]

誤 mention 問題と prefix 変更について、現状のデータを集めて検討しました。長くなるので要点を先に:

• 誤 mention するのは #@ の直後が英字のディレクティブ(#@since/#@until/#@if/#@else/#@end/#@include/#@todo)で、manual/ に 合計 2078 行。#@#(コメント、3884 行)は @ の直後が #(非単語文字)なので mention 化しません。
• prefix を変えるなら、既存文書・Ruby コード例・GitHub mention のいずれとも衝突しない記号を選ぶ必要があり、候補は絞れます。
• else-since のネストは実際に頻出(12 ファイル・31 箇所、最大 2 段)なので、専用の版範囲記法を入れる価値はありそうです。

1. 問題の範囲(manual/ の実測)

ディレクティブ	件数	mention 化
#@#(コメント)	3884	しない(@ の次が #)
#@todo	728	する
#@end	515	する
#@since	397	する
#@else	204	する
#@include	116	する
#@if	67	する
#@until	51	する

#@ 行は全体で 5965 行(518/1273 ファイル)。mention 化する #@英字 が 2078 行です。

補足: #@ は Ruby の式展開の省略記法 #@ivar(#{@ivar} の短縮)とも衝突します。実際に manual/api/observer.md の Ruby サンプル中に #@limit が 2 件あり、これはディレクティブではなく正当な Ruby です。新 prefix は #@ / #$ / #{(いずれも式展開の頭)を避けるのが安全です。

2. prefix 変更で手を入れる箇所(規模感)

• bitclust: #@ をハードコードした実装が 15 ファイル。正典は preprocessor.rb、次いで rrd_to_markdown.rb(57)・markdown_to_rrd.rb(34)・include_graph.rb・markdown_bridge.rb・entity_splitter.rb・whole_file_gate.rb ほか。
• doctree: 独立実装が 2 本(tools/fold_version_branches.rb・tools/method-versions/tools/parse_doctree.rb)、Rakefile の lint 2 箇所(check_indent_in_samplecode / check_blank_lines)、VSCode 拡張の TextMate 文法(ディレクティブ別に 10 正規表現)+ その README。
• 本文(manual/ 5965 行)は機械置換(sed)で一括変換可能。旧 refm/ にも #@samplecode 中心に 17527 行ありますが、これは削除予定の旧 RD ツリーなので移行対象外にできます。

つまり「本文の一括 sed + コード ~20 ファイルの正規表現/文字列の差し替え + VSCode 文法」という規模で、機械的ではあるものの一度で通す必要があります。

3. prefix の候補(衝突チェック済み)

manual/ の行頭 ^\s*#記号 の出現数で衝突を見ました。

• 除外(衝突大): #=(454・# => 出力表記)・#<(44・inspect 表記)・#!(22・shebang)・#+英字(22・C ソース #define 等)・#+数字(16・irb/tracer)・#.(12)。#: は現状 0 ですが rbs-inline と衝突するので回避。
• 衝突なし(0 件): #% / #| / #* / #~ / #^ / #; / #& / #@@。#+ / #- は RDoc 記法(#++/#--)を解説する引用例 1 組のみ。

これらはいずれも行頭が # なので Ruby のコード例に紛れても「コメント」のままで、コード例の構文を壊しません(現在の #@ と同じ利点)。

mention 化について: 確実なのは「@ を含まない」候補(#%/#|/#*/#~/#^/#;/#&)です。#@@since は見た目の変化が最小(#@ 継続)ですが、@@since の内側の @since を GitHub がなお mention 化しないかは要確認で、確実性では @ なしに劣ります。

個人的な推し: 読みやすさと「ディレクティブらしさ」で #%(例 #%since 3.4 / #%if(...) / #%end / #%# コメント)が無難かなと思います。#* も候補です。ここは好みの領域なので、方針だけ決めていただければと。

HTML コメント <!-- since x.y --> / PI <?rurema ...?> 案: mention は確実に消えますが、(1)現状の MDCompiler は raw HTML コメント/PI を透過する実装になっておらず(地の文を広く escape している)、通すには実装が要る (2)行ごとに 1 記号だけ、という今の見た目ではなくなる、という難点があります。専用実装を足す覚悟があれば選択肢ですが、prefix 変更より重いです。

4. else-since / 版範囲の省略記法(#285 の追加要望)

実測では、version 範囲の分岐は確かに頻出でした:

• #@else 使用: 73 ファイル・206 件。
• ネスト(深さ 2): 12 ファイル・31 箇所(最大 2 段、3 段以上なし)。例 RubyVM__YJIT.md は #@since 3.3 の内側で #@if("4.0" <= version) / #@if("3.4"<=version and version<"4.0") / #@if(version<"3.4") の 3 連分岐。
• 連続 #@if チェーンによる 3 分岐以上(singleton.md 型): 10 ファイル以上(singleton.md・Socket.md・TCPSocket.md・did_you_mean.md 等、いずれも 3.3/3.4/4.0 境界のシグネチャ差)。

これらは今 #@if("3.3" <= version and version < "3.4") と冗長に書いているので、prefix 変更のついでに 半開区間の省略記法を入れると効果が大きそうです。たとえば(新 prefix を #% と仮定):

#%version 4.1..       開発版(4.1 以上)
#%version 4.0..4.1    4.0 以上 4.1 未満
#%version 3.4..4.0    3.4 以上 4.0 未満
#%version ..3.1       3.1 未満
#%end

#%since/#%until はそれぞれ #%version X.. / #%version ..X の別名、という整理にもできます。導入する場合は preprocessor.rb(と各派生実装)に version A..B を A <= version and version < B に展開するパースを足す形になります。

まとめ・進め方の提案

1. prefix を @ を含まない記号(#% 推し、#* 等も可)に決める。
2. manual/ を機械置換 + コード ~20 ファイル + VSCode 文法を 1 つの変更で通す(preprocessor.rb を最初に変え、verify_preprocessor_output.rb で描画不変を確認)。
3. ついでに #%version A..B の半開区間記法を追加し、既存の #@if("A" <= version ...) を順次置換(必須ではなく段階的で可)。

prefix の最終決定(と HTML コメント案を採るか)だけ方針をいただければ、preprocessor の変更 → 本文一括置換 → 描画不変確認、の手順で PR を用意できます。

🤖 Generated with Claude Code