不要な空白がドキュメントの文章内に頻出している

[r7kamura]

概要

オプションサマリには出てきません

のような文章が表示されることを期待している箇所で、

オプションサマリには 出てきません

のように不要な空白が配置されている、という事例がドキュメント内で多く見受けられ、これは意図されたものではないだろうと思い Issue を立てました。

例

例えば https://docs.ruby-lang.org/ja/latest/class/OptionParser.html を例にすると、以下の画像内で矢印を付けている箇所のことを指しています。

推測した理由

なぜこうなっているのか調べたところ、ソースコード中に含まれている改行がそのまま HTML 内に出力されているため、Web ブラウザには空白のテキストノードとして扱われており、結果としてユーザには空白が見えているのではないかと考えました。

この部分の HTML は、以下のソースコードを元にして生成されたものだと思います。

doctree/refm/api/src/optparse/OptionParser

Lines 23 to 24 in 5afe4dc

	以下はデフォルトで利用可能なオプションです。オプションサマリには
	出てきません。

思いつく解決策

この Issue を立てた時点で思いついた解決策を二つ挙げてみます。

個人的には案2は難しいと思っています。 (案1も結局機械的に変換するなら同じくらいの難易度ですね)

案1

ソースコード内から、(日本語の単位としての) 行の中には改行を含めないように少しずつ変更していく。

案2

パーサの挙動を変更し、単一の改行を無視する (\n\n のように連続する改行だけ改行と見なす) ようにした上で、これによっておかしくなってしまった箇所を修正する。

[r7kamura]

• 「そうですね、直していきましょう」
• 「些細なことだし優先度は低いと思うので、今のところは無視していきましょう」
• 「その空白は意図的に置いています」

みたいな意見が欲しいなと思っています。

[scivola]

重要なご指摘と思います。
私もコレ，嫌です。

ちなみに，CSS Text Module Level 3 — Editor’s Draft, 28 October 2018 の 4.1.2. Segment Break Transformation Rules によれば，ご指摘の箇所の改行はスペース（U+0020）にせず取り除かなくてはなりません。

つまり，現状で空白に見えるのはブラウザーの実装がこの仕様に従っていない，ということなんですね。
まあまだ Editor’s Draft の段階ですし。

ちなみに Firefox 63 の表示はこうです。

あれっ？　いつのまに直ってた（笑）
Firefox も以前は空白になってた記憶があるのですが。
WebKit, Blink はよ。

案 1 は，人的資源の面と，ほぼ全ファイルにわたる大量の修正が発生するという点から，ちょっと難しい気がします。
また，現状でソースがブチブチに改行されているのは恐らく編集上の理由があるのだろうと推測しています。

[r7kamura]

理想的にどうするべきかという話をすると、

1. どんなソースコードが書かれるべきか
2. どんな HTML が出力されるべきか

という二つの論点がありそうですね。その上で、1 についての課題を解決しようとすると、2 についての課題もある程度解決していきそうな気がしています。

---

案1について、たしかに完璧にやるのは大変だろうと思うので、完璧ではないけれど楽に対応できる方策を考えたいと思っています。

例えば以下のような感じで、機械的な修正を試みるというのはどうでしょうか。

require 'pathname'

Pathname.glob('{faq,refm}/**/*').each do |pathname|
  next unless pathname.file?
  content = pathname.read
  replacement = content.gsub(/(\P{ascii})\n([^\p{ascii}\n])/m, '\1\2')
  pathname.write(replacement)
end

要するに、

...<非ASCII文字列>\n<非ASCII文字列(改行は除く)>...

というように文字列が並んでいる部分については、機械的に改行を取り除いても良いのではないか、という話です (編集上の理由がこれを許せばですが...)。るりまで使われる文法規則が、制御文字 (--- や = や * みたいなやつ) としてマルチバイト文字列を利用していない、という性質を利用しています。

試しに手元で実行してみた結果の差分を Gist に貼っておきます。

https://gist.github.com/r7kamura/eea84464aa71e921755d1e006251e48d

[sho-h]

案1、2のどちらかであれば、個人的にはやるなら案2が嬉しいですね。bitclustを修正して今のデータでそれが可能なら僕は賛成です。一時的に解決しても文章の追加の際に改行が入ると元の木阿弥とまではいかずとも根絶できないためですね。diffが読みづらくなって作業するのがしんどくなるので案1はなるべくやりたくないです。

ただ、原文を直に修正するのではなくて、整形時に前処理として修正するフェーズを取り込むなら今のところ特に不都合を感じる要素は思いついていません。この場合は以下のどちらかが対象になると思います。(仮にこれを案3とします)

1. HTML整形直前のメモリ上のテキスト
2. bitclust updateした時に更新されるDB上のファイル、及び1.

案2だとASCII文字で終わる文章とASCII文字で始まる文章を自動で連結なりする時がやっぱり要注意ですかねぇ。lib/bitclust/rdcompiler.rbかな？(追記: rrdparser.rbだったかも)と思うのですが、基本1行1行でしか処理しなかったと思いますので、何らかのフラグが必要になって確かにちょっと大変かも？とだけ思いましたが、思い違いかもしれません。

案3(仮)だとコメントいただいたreplacementのgsub相当を lib/bitclust/preprocessor.rb ですればいいのかな？と思いました。

しかし、どちらも改行を故意にいれたい場合が問題になるかもしれませんね...

[sho-h]

1. どんなソースコードが書かれるべきか
   2.どんな HTML が出力されるべきか

そんな訳で個人的には1.は改行を含めれると嬉しいです(編集の都合で今のままに近いものがよい)
2.は「推測した理由」で書いていただいてる内容が原因で合ってるかと思いますのでHTML上は非ASCIIの範囲では連結すれば見た目上の問題は解決しそうですね。

[scivola]

案 1〜3 なら 3 がよさそうです。編集作業に影響しませんし。
私はブラウザーの不具合をカバーするための処置という捉え方をしています。

改行を取り除くロジックですが，

gsub(/(\P{ascii})\n([^\p{ascii}\n])/m, '\1\2')

で，\n と m は不要なので（\n は ASCII だし，m オプションは . の意味を変えるだけなので）以下のようになるかと思います。

gsub(/(\P{ascii})\n(\P{ascii})/, '\1\2')

ただ，「非 ASCII」という括りでよいかは疑問というか若干不安です。
非 ASCII の欧文がありうるからです。

もっとも，ざっと調べたところ，行頭・行末に非 ASCII の欧文が来ている例は無いようなので，編集マニュアルで注意を促せば済む話かもしれません。

[sho-h]

僕も案3(の2.で挙げた方)に一票というところです。
出てきてる事を含みますが以下のような感想ですね。

• 案3の1.は筋悪っぽい
  • 出しておいてなんですけど、このタイミングでデータ変更をやると問題があった時の調査にハマりそうなので、案2のパーサ直すのがずっとよさそう
  • 案3の1.のメリットは1.8など更新を止めてしまったファイル群のケアが簡単にできる事だけどEOLなバージョンに手間をかける事もない(今のままでいい)
• 案3の2.は最もデグレが起きにくそう
  • ステータスの管理(今 #@if の中にいるかなど)をしなくていいものであれば、分業がしやすくルールが定まれば取り込みやすそう
  • 分業=整形方法だけ検討いただき、取り込む行の修正はbitclustに権限のある誰かなど
    • 注意するポイントは案2と同じかもしれないけど、自由度が高い
  • なお、preprocessor.rb(バージョンの分岐を先に解釈した各バージョン向けのソースを吐く処理)の修正の件は案3の2.の方
• 案2は心配事が多い
  • コードが集約できそうだけど継続行が同じタイプのテキスト(例: 同じ引数の説明である)でかつ空行でないみたいな判断が必要だと思われるため構造から変えないといけないかが心配で、デグレも心配なので、そこまでして導入する事かはなんともという所

[r7kamura]

bitclust の実装にまだあまり詳しくないので、案3の内でどちらが良いかという意見は出せないんですが、

• ソースコードには改行を挿れられるほうが編集しやすい
• 不完全な Web ブラウザのための対応である

ということで、自分も案3に賛成です。

[r7kamura]

この Issue の件に関して、rurema/bitclust#61 に Pull Request を出してみました。

[znz]

refe2 のように HTML 以外で参照することもあるので、そういう用途でも見やすいように改行が入っているのかと思っていました。

[okkez]

💭 BlinkやWebKitでの対応状況ってどうなんだろう？ 🤔

[sho-h]

refe2 のように HTML 以外で参照することもあるので、そういう用途でも見やすいように改行が入っているのかと思っていました。

ターミナルの横幅次第かと思うのですが、たとえばrefe2が環境変数COLUMNS見ているならそちらも含めて見やすくなりそうに思いました(検索しただけですが以下でしょうか？

• https://github.com/rurema/bitclust/blob/83998a1e2f5e2d644ee046fbec24b09d85c79950/lib/bitclust/searcher.rb#L421

[sho-h]

COLUMNS見てるのは本文ではなくて、メソッド一覧みたいですね。本文も同じでいいのではないかと思ったりしますけど、過去のMLをみる範囲だと特にそういう議論はないようですね。

[r7kamura]

rurema/bitclust#61 がmergeされて問題が解決されたので、Closeしておきます。
ありがとうございました 👍

---