クロスリファレンスの適正化

[matsuand]

現状の git-scm.com 日本語版の「クロスリファレンス」およびそれによるハイパーリンクが、(1) リンク先非存在によりエラー、となり (2) リンク先表記が適正な日本語表記になっていない、という問題があります。(1)についてはまだよくわかっていないのですが、(2)に関して、あるいは (2)そのものではないかもしれませんが、一つ提案があります。（この提案が上述の (1)、(2) の解決になるかどうかが、まだわかっていません。git-scm.com に準拠した処理を実践してみないとよくわかりません。）

セクションタイトルに対して、現状は明示的な ID づけが為されていないため、たとえば「バージョン管理に関して」という章立てタイトル箇所に対して、（HTMLの） ID は "_バージョン管理に関して" という日本語を含む ID となっています。これは改善の余地があり、英語表記、正確には英語版とまったく同じ ID を採用すべきと思います。その方法は後述します。

改善理由としては以下です。

1. 訳出編集観点から。そのセクションタイトルが原文変更となった場合、原文ではタイトル変更と同時に ID 参照箇所も変更をかけるはずです。その際に日本語版でも当然、セクションタイトルの訳変更が発生する可能性が大いにあり、であると ID 参照箇所も変更しなければなりません。しかし ID を英語版どおりに揃えておけば、セクションタイトルの訳変更をするだけで済み、ID 参照の変更が必要な個所を探し出してそれをすべて変更するという手間が省けます。
2. ユーザー利用観点から。ID が日本語化されていると、当然、英語版の本来との ID との紐づけは一切失われます。逆に英語版の ID と同一にしておけば紐づけが維持されます。例えば日本語版での「progit.html#_about_version_control」という ID つきの URL は、英語版の対応 ID が即座に識別できるという利便性があります。

セクションタイトルの ID づけを明示的に行う方法は、Asciidoctor のリファレンス により以下のようにできます。たとえばセクション「バージョン管理に関して」の場合

[#_about_version_control]
=== バージョン管理について

つまりセクション開始行において、カスタムID [#_cross_reference_id] を付与するというものです。この際に付与すべき ID は、英語版を見ればわかります。おおざっぱに言えば単語をすべて小文字化して、単語間をアンダースコアで繋げるものです。

いかがでしょうか。