[2022 年度 Ruby アソシエーション開発助成](https://www.ruby.or.jp/ja/news/20221027)でやっている「Ruby リファレンスマニュアル改善計画 2022」の進捗の報告と、Ruby リファレンスマニュアルの改善に参加してくれる人の募集をしたいと思っています。
Ruby リファレンスマニュアル改善計画2022 進捗報告Kazuhiro NISHIYAMA株式会社Ruby開発第90回 Ruby関西 勉強会2023-03-25Powered by Rabbit 3.0.1
View Slide
self.introduction西山 和広Ruby のコミッターtwitter, github など: @znz株式会社Ruby開発 www.ruby-dev.jp1/29
agendaるりまについてRuby リファレンスマニュアル改善計画 2022 について歴史目標2/29
What is rurema (るりま)?Japanese Ruby reference manualRubyリファレンスマニュアル刷新計画https://github.com/ruremarurema/doctreeドキュメントrurema/bitclust独自のドキュメントシステム3/29
るりま != るびまRubyist Magazinehttps://magazine.rubyist.net/https://github.com/rubima似ているけど無関係FAQよりQ. るびま、って「ネギま!」のぱくりですか?A. 違います。多分。「るびま」を考えた人たちは「ネギま!」を知りませんでした (または、言われるまで気付かなかった)。4/29
Ruby リファレンスマニュアル改善計画2022 とは?Ruby リファレンスマニュアル を Markdown 記法に対応させる計画5/29
現状の予定bitclust に Markdown 対応を追加doctree でいくつかのドキュメントを Markdown で書いてみる(現状は上2点の途中)問題点をみつけて直しつつ、既存のドキュメントも移行していくRD のドキュメントを削除して bitclust からも RD 対応を削除して移行完了6/29
Markdown 変換の進捗簡単なサンプルを作成して実現可能性を検証kramdown-parser-gfm でほぼ RD と同じように変換可能分割処理を RD から流用→ code block の中のコメントを見出しと誤認識する問題発生実現可能性の検証用実装を捨てて Kramdown のパース結果を利用するように作り直し中7/29
歴史なぜこういう状況なのかという歴史の話8/29
るりまより前Ruby 1.4.6 以前https://ftp.ruby-lang.org/pub/ruby/doc/ドキュメントは RD で書かれていたEnglish: ruby-man-1.4.6.tar.gzJapanese: ruby-man-1.4.6-jp.tar.gz(中の HTML ファイルは iso-2022-jp なので文字化けに注意)Ruby 1.6 から 1.8 の時代RWiki で編集・公開RWiki はいくつかの拡張機能つきの RD を使った Wiki9/29
るりまが始まった頃Ruby 1.8 時代Rubyリファレンスマニュアル刷新計画が開始bitclust という RD ベースの独自記法のシステムbitclust は RDtool (https://rubygems.org/gems/rdtool) を使っていないRWiki で編集していたドキュメントを取り込んだ10/29
ドキュメントのライセンスRWiki の編集フォームにライセンスの変更手順を書いておいた(freeml の rubyist ML での合意で変更可能とした)Creative Commons — Attribution 3.0 Unported に変更https://github.com/rurema/doctree/blob/master/refm/doc/license.rd11/29
bitclust 時代になってからの改善点EUC-JP から UTF-8 にコードの色付け (#@samplecode)#@ で始まる行はプリプロセッサchm, ePub に出力可能あまり使われていないので動かない可能性ありデフォルトは静的HTML (docs.ruby-lang.orgもこれ)12/29
るりまプロジェクトの現状ドキュメント改善のサブプロジェクトRubyの新しいバージョン対応https://rurema-review.connpass.com/13/29
ドキュメント改善ノサブプロジェクトhttps://github.com/rurema/doctree/issues/433コピペ可能なサンプルコードを整備するサンプルコードの色付け→ ほとんど完了したからか現在はほぼ停止中14/29
Rubyの新しいバージョン対応そこそこ対応メソッドの変更 (追加、引数や機能の変更、削除)ほとんど対応できていない文法の変更 (パターンマッチ, &., …)どこに書けばいいのかはっきりしていない15/29
rurema-reviewhttps://rurema-review.connpass.com/毎週火曜の夜るりまレビュー会 → るりまもくもく会鹿児島Ruby会議01をきっかけに開始たくさんの pull request をマージ→ 現在は活動できている人がいない16/29
協力者募集こういう状況なので協力者を増やしたいGitHub issues や ruby-jp slack の #ruremahttps://github.com/rurema/doctree/issueshttps://ruby-jp.github.io/17/29
目標短期目標中期目標長期目標18/29
RD ベース → Markdown ベース最重要短期目標RD より Markdown の方が馴染みがある人が多い貢献してくれる人が増えるはずRuby リファレンスマニュアル改善計画 2022 で作業開始19/29
現在の記法#@ はプリプロセッサ要の行--- は RD の MethodList#@since 3.1--- intersect?(other) -> boolother と共通の要素が少なくとも1個あれば true を、なければ false を返します。#@samplecode 例a = [ 1, 2, 3 ]b = [ 3, 4, 5 ]c = [ 5, 6, 7 ]a.intersect?(b) # => truea.intersect?(c) # => false#@end#@end20/29
プリプロセッサの移行バージョン分岐や include などエディタや GitHub.com でのサポートも気にしたい→ Jekyll でも使われている Liquid を採用21/29
MethodListMethodList の代用案現在の記法は def m(args) ベースブロックの書き方は揺れがある{|x| ... }, {|x| block }, &block返り値は書いてあるが有効活用はあまりされていない22/29
MethodList の移行### def m(args) -> nil 形式最初は単純に既存の記法を Markdown にするだけ将来は RBS 形式もサポート予定23/29
他の記法#@samplecode → code blockリンク[[c:String]] → [c:String]Markdown の記法に合わせて [] が1段減る細かい問題は臨機応変に対応予定24/29
他の短期目標と問題使われていないファイルや古いファイルの削除ChangeLog, setup.rb, …tools のファイルがまだ使えるかどうかはっきりしない使い方のドキュメント不足これが最重要の課題再現可能なビルドcontainer? devcontainer?25/29
中期目標(他のツールとの連携)RBS連携例: signatures の連携IRB連携rdoc の代わりに rurema を表示したい26/29
中期目標(ドキュメント)WASMでサンプルコードを実行可能にしたいhanachin さんが試したものがある https://github.com/hanachin/bitclust/commit/1ae60bfabd09c0d241e6966a6800e27a797ce175 https://github.com/rurema/doctree/issues/2730標準添付から外れたライブラリや古いドキュメントの整理いくつかは https://github.com/rurema/historical-documents に移動済27/29
長期目標I18n 対応rdoc と ruerema は記法だけに限らず、ドキュメントの書き方が違いすぎて統一しにくいgettext か何かを使う?英語ベースの方が良さそうなので遠い将来の夢になりそう28/29
endRD から Markdown への移行開始中進捗があれば github や slack で報告予定ご協力よろしくお願いします29/29Powered by Rabbit 3.0.1