Rubyリファレンスマニュアルと空白の話
るりまに Issue を立てた
昨日 doctree/rurema に Issue をつくった。doctree/rurema というのは、日本語で書かれた Ruby のリファレンスマニュアル (a.k.a. ドキュメントサイト) のソースコードが置かれているGitリポジトリ。内容は、Ruby リファレンスマニュアルの文章中にたまに空白が入っているように見えるけど、これどうにかならないの？というもの。意見のある人は、この機会にぜひコメントをば。
Issue を立てた背景
Ruby リファレンスマニュアルには普段からお世話になっており、事あるごとに標準ライブラリの機能などを調べさせてもらっていて、何かできることは無いかなと思って考えていた。とは言え Ruby リファレンスマニュアルがどう開発されているのかあまり知らないので、利用者として出来ることをしようと思い、普段からずっと気になっていた議題を Issue に挙げてみた、というのが今回 Issue を立てた背景。
CSS Text Module Level 3
結局 doctree/rurema での空白の扱い方はどうすべきかについて、自分の中でも明確な意見が出ていないので、しばらく考え続けている。 scivola さんがコメントしてくれたように、CSS Text Module Level 3 の 2018-10-28版 Editor's Draft では、今回のような全角文字の間に改行が配置されているような場合、その改行は半角スペースに置き換えられるべきではなく、単に取り除かれるべきだとされている。
CSS Text Module Level 3 というのは…、そもそも CSS 3 は「CSS 2 って一部の機能がボトルネックになって全体の仕様勧告までに9年も掛かっちゃったね。CSS 3 では幾つかのモジュールに分けて仕様策定を進めるようにしよう」という事になっていて、その1つに CSS Text Module Level 3 というモジュールがあって、空白文字類の表示に関する仕様はその中に含まれている。草案、勧告候補、勧告案、勧告というレベルがあって、CSS Text Module Level 3 はまだ草案段階。
あと Web ブラウザはこの仕様に従った実装を行わなくても別に良くて、実際 Google Chrome とか Firefox とかでも改行の扱いはこれに則った実装をしていなかった。だから空白が表示されて doctree/rurema に Issue が立てられちゃった訳なんだけど、最近の Firefox で見たら改行が正しく扱われて空白出なくなっとるやんけ、というのが scivola さんのコメントの話です。
改行規則の一貫性
Firefox では正しく実装されてることだし、ほっといたらそのうち Google Chrome でも対応してくれて問題なくなるんじゃね？というのが一番楽な解決方法だと思う。あれ、これで良くない？
いや、自分が Issue を立てた裏側には、過去に Pull Request を送るために doctree/rurema のドキュメントを編集したときに少し困ったことがあって、その困りがこの Issue を書くモチベーションの一つにもなっている。というのも、ソースコード内の文章が適当なところでぶちぶちと改行されているように見えて、既存の文章と一貫性を保ったまま文章を追加するには、一体どういう規則で改行を入れれば良いのやら…というのが当時 Pull Request をつくろうとしたときの悩みの種だった。なので、ソースコードの文章にも一貫性があった方が良いし、例えば改行全部取り除けば Web ブラウザで不要な空白も表示されなくなるんじゃないのか、と考えて立てた Issue だった。しかし、こういう感じでいかにも利用者として困っていますよ的な Issue タイトルで立てておきながら、開発者として困っていることを主張するのは邪悪な感じがするので、この点についてはあまり声高に主張しづらい。
もし自分がコメントで提案しているように改行を取り除いたら、編集上の手間はどうなるだろう。エディタの Soft wrap の支援が無いと、1行あたりの文字数が長めになってしまって、右方向にスクロールするのが大変だろうなあというのが容易に想像できる。一貫性が増すのでその点では書きやすくなるんだけども、別の点で書きにくくなってしまう…。
別のドキュメントサイトではどうなっているのだろう。もし Markdown を採用していれば、HARDBREAKS モード (ソースコードでの改行が br 要素に置き換えられる) を有効化していないならば、改行はそのまま p 要素などの中に改行として出力されることになるので、doctree/rurema と同じ状況になるはず。
論点の整理と雑感
とりあえず論点を整理すると、決まってると嬉しいのが以下の二点。
- Web ブラウザの CSS Text Module Level 3 への対応を期待して待つべきか
- ソースコード中の日本語文章の改行規則はどうあるべきか
そしてここまで長々と書いたけど、色々なことを鑑みた結果、"日本語の文章では出来る限り「。」か「、」の直後にしか改行を入れないようにしよう" ぐらいの緩い合意を取って Issue を Close するのが良いかもしれない。あるいは、可能であれば bitclust の HTML 出力時に整形する。
余談: 過去の Pull Request
前述した過去に doctree/rurema に送った Pull Request がこれで、いま docs.ruby-lang.org を見たらその内容がきちんと HTML に反映されていることが確認できた。
Ruby 書いてるとき Ruby リファレンスマニュアルほんとうによく利用するので、自分の書いたものが表示されているのはかなり嬉しい…。大学時代は電車で2時間ほど掛けて通学してたので、昔は Refe というツールでオフライン環境で Ruby リファレンスマニュアルを読めるようにして、古い電車のボックス席で小さくPCを開けてコードを読み書きしていたのが懐かしい。