Skip to content

manual/: Markdown ソースツリーの追加とビルドの切り替え#3035

Merged
znz merged 13 commits into
rurema:masterfrom
znz:markdown/add-manual-tree
Jul 8, 2026
Merged

manual/: Markdown ソースツリーの追加とビルドの切り替え#3035
znz merged 13 commits into
rurema:masterfrom
znz:markdown/add-manual-tree

Conversation

@znz

@znz znz commented Jul 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

概要

ドキュメントソースを RD ベースの独自記法（RRD）から GFM ベースの Markdown へ
移行するため、refm/ から変換した Markdown ツリー manual/{api,doc,capi}
（api 1161 + doc 68 + capi 16 = 1245 ファイル）を追加し、ビルドを manual/
ベースに切り替えます。

  • 記法の提案・仕様は bitclust 側の文書を参照:
    • 提案書: doc/markdown-proposal.md
    • 紹介文書: doc/markdown-announcement.md
    • 記法仕様: doc/markdown-samples/MARKUP_SPEC.md
  • クロスファイル情報（ライブラリ所属・include/extend/alias・バージョンゲート）は
    YAML front matter に集約。#@since/#@until/#@include 等の指令はそのまま維持
  • 公開 URL はエンティティ名由来のため変わりません

変更内容

  • manual/ の追加: bin/rrd2md（bitclust 側）による refm/ 全3ツリーの変換結果
  • ビルド切替: rake generate / rake statichtml が
    bitclust update --markdowntree=manual/api（および --capi update --markdowntree=manual/capi）で manual/ から直接ビルド。
    bitclust はネイティブに Markdown をパース・描画し、編集リンクは
    manual/**.md を指します
  • refm/ の正規化 12 ファイル: ラウンドトリップ検証で見つかった描画等価な
    表記ゆれ（ゲート付き include 前の空行、---name スペース欠落、行末スペース、
    dlist term の二重スペース等）を正規形へ
  • refm/ は凍結して共存: 移行ウィンドウ中は残し、以後の編集は manual/ の
    Markdown に対して行います

検証

  • ラウンドトリップ: rd → md → rd がバイト一致 1245/1245（100%）
  • データベース等価: 新旧両経路でフルビルドして全比較 —
    368 ライブラリ・1436 クラス・9281 メソッドエントリ・66 doc ページ・
    814 C 関数が一致
  • 描画等価: 全 10,655 エントリで RDCompiler と MDCompiler の HTML が一致
  • 静的 HTML: 旧経路とネイティブ経路の全 13,535 ページを比較し、残差は
    既知の無害差分 1 箇所のみ（JSON::State#generate の meta description 内の
    改行 1 個。旧経路の #@include 後空行漏れ由来で、md 経路の方がクリーン。
    bitclust doc/markdown-operations.md §4 に記録）
  • GFM による意図した表示改善: インラインコード → <code>、GFM テーブル、
    パラメータ名のコード表示など

依存関係

  • bitclust の feature/markdown-conversion ブランチが必要です
    （MDParser / MDCompiler / --markdowntree を含む）。
    bitclust 側 PR とセットでレビュー・マージしてください

レビューの観点

  • manual/ の記法・読みやすさ（サンプル: manual/api/_builtin/Comparable.md 等）
  • front matter への関係集約と 1 ファイル 1 エンティティ分割の方針
  • refm/ 凍結・共存という移行手順、切替タイミング

🤖 Generated with Claude Code

znz and others added 7 commits July 6, 2026 00:04
@znz @claude
Add manual/: Markdown source tree converted from refm/
dee7495 
manual/{api,doc,capi} is the Markdown edition of the reference manual
source, generated from refm/ with bitclust's bin/rrd2md (branch
feature/markdown-conversion):

  ruby bin/rrd2md --graph refm/api/src  manual/api   # 1161 files
  ruby bin/rrd2md --doc   refm/doc      manual/doc   #   68 files
  ruby bin/rrd2md --capi  refm/capi/src manual/capi  #   16 files

Notation is specified in bitclust's doc/markdown-samples/MARKUP_SPEC.md.
Key properties:

- api: front matter carries library membership, include/extend/alias
  relations and structural since/until gates (computed from the
  LIBRARIES include graph); entity-grouping #@include lines and the
  LIBRARIES manifest are replaced by glob + front matter discovery.
  Entities that carry relations live in their own file; relation-free
  bundles (Errno, response-code families) stay together.
- doc: prose pages keep their H1 title, no front matter. Unreferenced
  stray files (news/1.8.0.rd-2 etc.) are not converted.
- capi: '--- signature' entries become keyword-less '### signature'.

Equivalence with the refm/ build has been verified at every level:
byte-exact roundtrip (1161/1161, 70/70, 16/16), parser structure for
every library at 3.0/3.4/4.1, full database comparison (9281 method
entries, 66 docs, 814 C functions - all identical), and statichtml
output (13540 HTML files, one benign attribute-whitespace diff).

refm/ stays frozen during the transition window; builds switch to
manual/ via bitclust update --markdowntree (see bitclust's
doc/markdown-operations.md).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Build databases from manual/ (Markdown) instead of refm/
0f460ea 
generate_database now feeds bitclust from the Markdown tree:

  bitclust update --markdowntree=manual/api          # api + doc
  bitclust --capi update --markdowntree=manual/capi  # C API

Set BITCLUST_SOURCE=refm to build from the frozen refm/ tree during
the transition window (output equivalence between the two paths is
verified in bitclust; see doc/markdown-operations.md there).

check_indent_in_samplecode now lints manual/ as well as refm/.

Verified locally with the path-referenced bitclust
(feature/markdown-conversion): rake generate:3.4 builds the 59MB
database in ~18s, rake statichtml:3.4 renders 13540 pages whose edit
links point at manual/**/*.md, and the check_format greps find no
UNKNOWN_META_INFO or compileerror output.

Note: requires a bitclust release that supports --markdowntree;
until then CI must either pin bitclust to the feature branch or set
BITCLUST_SOURCE=refm.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Regenerate manual/api with #@# metadata comments in front matter
49830f3 
Converter update (bitclust feature/markdown-conversion): #@# comments
inside library metadata areas now land in front matter instead of
aborting metadata collection. irb.md, irb/completion.md and
irb/workspace.md gain proper front matter (library metadata was
previously left in their body), completing the api tree - all 1161
files now roundtrip byte-exact with no exceptions, and the built
database remains equivalent to the refm/ build.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Regenerate manual/ with renderer-faithful converters (MDCompiler M1)
2bebef0 
bitclust 側のネイティブ MD 描画（MDCompiler）の HTML 等価検証で
見つかった変換器の統一ルールを反映して全3ツリーを再生成
（api 828/828・doc 68/68・capi 16/16）。主な変化:

- dd 説明のインデント段落と emlist の交互列を1つの説明として保持
- インデントコードの複数空行跨ぎを1つのフェンスに融合
- 「---name」（スペース無しシグネチャ）を正規形「--- name」で変換
- dlist 継続の「:term」（スペース無し）を「: term」に正規化
- ===== 見出しを ##### に（従来は素通し）
- (N) リスト項目の折り返し継続行をリスト継続として保持
  （従来は後続がインデントコード扱いになっていた）
- 行頭 **N.** 離散番号・@see・@undef などの扱いを描画等価に統一

検証: roundtrip api 1161/1161・tree-check 要対応警告0・
bridge-check 368/368 @3.4・DATABASES EQUIVALENT
（末尾空白のみ25件+シグネチャスペースのみ8件）・
FUNCTION DATABASES EQUIVALENT・
MDCompiler HTML 等価 10655/10655（method/doc/lib/function 全件）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Regenerate manual/ with GFM-faithful inline markup (M2)
93c1aaa 
bitclust M2（a3b06b5）の変換規則を反映して全3ツリーを再生成
（api 828/828・doc 68/68・capi 16/16、49ファイル変化）:

- GNU 風引用 `token' → インラインコードスパン `token`
  （getoptlong・pathname・debug 等の `-'、`--version' など）
- それ以外の生バッククォートは \` にエスケープ
  （GitHub 上での偶発コードスパンによる表示崩れも直る）
- 参照ターゲット内の __WORD__ の誤スパン化を修正
  （[m:Delegator#__getobj__] 等）
- アンカー付き見出し内のバッククォートをエスケープ
  （spec/pattern_matching の `未定義`、symref の `）

検証: roundtrip 1161/1161・tree-check 要対応0・bridge 368/368・
DATABASES EQUIVALENT（既知差 25+8）・FUNCTION DATABASES EQUIVALENT・
MDCompiler M1 等価 10655/10655・GFM 整合 10655/10655。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Normalize whitespace/spacing anomalies for byte-exact roundtrip
77b3f79 
md 変換のラウンドトリップ検証（rd → md → rd バイト一致）で見つかった
描画等価な表記ゆれ12ファイルを正規形へ:

- ゲート付き include/alias 前の空行を除去（Integer, Monitor,
  RDoc__CodeObject, RDoc__Context__Section。remove-blank-before-include
  正規化のゲート付き取りこぼし）
- include 行の行末スペース除去（SSL__SSLServer）
- 「---name」（スペース無しシグネチャ）→「--- name」
  （X509__Extension 全9件, X509__StoreContext）
- dlist term「:  term」（二重スペース）→「: term」
  （safelevel, symref）
- 「//} 」「#@SampleCode 」の行末スペース除去
  （pattern_matching, variables）
- アンカー見出しの二重スペース除去（regexp19）

いずれも RDCompiler の描画は不変（dt/シグネチャ/前処理が空白を
正規化するため）。検証: bitclust f6086cd で roundtrip 1245/1245。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Regenerate manual/ with gate-family converter fixes (M3)
365329e 
bitclust f6086cd の変換器修正を反映して全3ツリーを再生成
（api 828/828・doc 68/68・capi 16/16、19ファイル変化）:

- dd 内 #@SampleCode 後の継続段落がフェンス化されていたのを
  インデント段落へ（pack-template の w、printf-format 等）
- ゲート分岐した @param の #@EnD 直後の継続行がフェンス化されて
  いたのをインデント継続へ（fileutils, scanf, pstore 等）
- リスト項目直後のカラム0 #@SampleCode を ```ruby フェンスへ
  （素通しで本体の #=> 行が \# エスケープされていた。news/2_5_0,
  news/2_7_0, glossary, spec/eval 等）
- refm 正規化（77b3f797b）の反映（symref, safelevel, regexp18 等）

検証: roundtrip 1245/1245（--inject）、statichtml 旧経路比較で
GFM 正規化後の残差は既知1件のみ（JSON::State#generate、
bitclust doc/markdown-operations.md §4）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz znz mentioned this pull request Jul 7, 2026
Merged
znz and others added 3 commits July 7, 2026 22:03
@znz @claude
Address findings rurema#4/rurema#6/rurema#9: dlist spacing, empty @raise
6102f55 
, old-style quote

bitclust doc/markdown-findings.md のフォローアップのうち doctree 記述3件:

- rurema#4: spec/operator.rd の「:再定義できない演算子」にスペースを追加
  （dlist 開始/継続の非対称に依存しない正規形へ。描画は不変）
- rurema#6: 説明なし・末尾スペースの @raise を整備
  - openssl/Random の egd/egd_bytes に「EGD からのエントロピー取得に
    失敗した場合に発生します。」を追記
  - 孤立した重複 @raise 2行（egd_bytes 直後・load_random_file の2つ目）を削除
  - rubygems/remote_fetcher.rd の download に「Gem の取得に失敗した場合に
    発生します。」を追記
- rurema#9: platform/DOSISH-support.rd の GNU 風引用 `\' を「\」に書き換え

manual/ は同変更を再生成で反映（3ファイル）。
検証: roundtrip 1245/1245、rake generate 3.0〜4.1 全7版成功、
statichtml 全7版で UNKNOWN_META_INFO 0・compileerror 0、
check_indent_in_samplecode green。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Temporarily pin bitclust to znz fork for CI
8f3747e 
--markdowntree オプションは rurema/bitclust#189（feature/markdown-conversion、
レビュー中）にのみ存在するため、Gemfile の git フォールバックと
Gemfile.lock を znz フォークの同ブランチ（7b32aeb）へ一時ピンする。
これで PR のレビュー中も CI が通る。

**rurema/bitclust#189 のマージ後に revert して rurema/bitclust.git へ
戻すこと**（Gemfile 内 TODO コメント参照）。

検証: BITCLUST_PATH=/nonexistent（= CI と同じ git ソース解決）で
bundle install → bitclust update --help に --markdowntree が存在、
rake generate:3.4 成功（source_format=markdown）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Bump pinned bitclust to 4ec941b (Windows CI fix)
b93636b 
doc エントリの source_location を相対のまま格納し、Location の
file:line 分割を最後のコロンで行う修正（znz/bitclust 4ec941b）を
取り込む。rake (windows-latest, head) の
「wrong number of arguments (given 3, expected 2)」の対処。

検証: BITCLUST_PATH=/nonexistent（CI と同じ git ソース解決）で
bundle install → rake generate:3.4 成功、
doc/help の source_location が manual/doc/help.md:1（相対）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
znz added a commit to rurema/generated-documents that referenced this pull request Jul 8, 2026
@znz @claude
Build databases from doctree manual/ (Markdown) tree
0501f97 
doctree の Markdown 移行 (rurema/bitclust#189, rurema/doctree#3035) に伴い、
DB 構築のソースを refm/ から manual/ へ切り替える (doctree の Rakefile の
切り替えと同じコマンド形)。refm/ は移行ウィンドウ中の凍結ソース。

rurema/bitclust#189 と rurema/doctree#3035 の両方が master に入るまで
マージしないこと (generate.sh は両リポジトリの master を clone するため)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz znz mentioned this pull request Jul 8, 2026
Merged
znz and others added 3 commits July 8, 2026 13:55
@znz @claude
大文字小文字のみが異なるファイル名を解消する
0b0847b 
macOS/Windows の case-insensitive ファイルシステムでは
manual/api/fiddle/2.0/{Fiddle,fiddle}.md のような大文字小文字のみが
異なるファイル名が同居するディレクトリをチェックアウトできない。
旧ツリーは拡張子の非対称（Fiddle と fiddle.rd）で衝突しなかったが、
md 化で全ファイルが .md になり2箇所で衝突していた。

- refm/api/src/fiddle/{1.9,2.0}/fiddle.rd → fiddle.lib.rd にリネーム
  （include 参照も更新。断片なので旧ビルド経路にも影響しない）
- manual/ を再生成: 上記断片は fiddle.lib.md に、rdoc/rdoc.md は
  RDoc.md との衝突を避けて rdoc/rdoc.lib.md + front matter name: rdoc/rdoc に
  （bitclust 側の衝突回避 emit。それ以外のファイルは変更なし）
- Rakefile に check_filename_case_conflicts を追加し default タスクに組み込み
  （manual/ と refm/ の再発防止）

検証: roundtrip 1245/1245 byte-exact、tree-check parity 370/370・要対応警告0、
bridge-check 368/368、3.4 DB 構築で rdoc/rdoc の名前・fiddle の断片透過を確認、
旧経路（--stdlibtree）ビルドも green。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Bump pinned bitclust to 3668809 (case-collision avoidance)
21e2557 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz @claude
Revert temporary bitclust pin, use rurema/bitclust master
99f7439 
--markdowntree が rurema/bitclust master に入った（rurema#189 マージ、
c7500e5e2）ので、CI 用の znz フォーク一時ピン（8f3747e61）を戻す。
lock の解決は BITCLUST_PATH=/nonexistent bundle install で検証済み
（git 解決で --markdowntree の存在も確認）。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@znz znz merged commit 49edbf8 into rurema:master Jul 8, 2026
9 checks passed
This was referenced Jul 9, 2026
Merged
Merged
@znz znz deleted the markdown/add-manual-tree branch July 9, 2026 05:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@znz