TokyoMercurial #9
TokyoMercurial の第9回に参加してきた。
運営の id:troter 氏ならびに参加者の皆様、お疲れ様でした。
今回の個人的な黙々目標は、月末の 2.8 版リリースに向けて、コードフリーズ期間に投函するドキュメント周りの修正パッチの作成作業。
基本的には、オンラインヘルプ中の記述に関する細かい修正がメインなのだけれど、オンラインヘルプのHTML生成に関して、実装の修正が必要なものが1点ある。
例えば、コマンドラインでの hg help archive の出力には:
オプション:
--no-decode デコード処理を回避
-p --prefix 接頭辞 アーカイブファイルのディレクトリ接頭辞
-r --rev リビジョン アーカイブ対象リビジョン
-t --type 種別 アーカイブ種別
-S --subrepos サブリポジトリへの再帰的適用
-I --include パターン [+] パターンに合致したファイルを処理対象に追加
-X --exclude パターン [+] パターンに合致したファイルを処理対象から除外
--mq パッチ管理リポジトリへの操作
[+] 印付きのオプションは複数回指定可能です
上記のように、各オプション毎に『値指定の要否』と『複数指定の可否』が表示される。
ところが、オンラインヘルプから HTML ページを生成した場合、単なるオプションと説明が列挙されるだけの表示になってしまう。
オプション:
--no-decode デコード処理を回避
-p --prefix アーカイブファイルのディレクトリ接頭辞
-r --rev アーカイブ対象リビジョン
-t --type アーカイブ種別
-S --subrepos サブリポジトリへの再帰的適用
-I --include パターンに合致したファイルを処理対象に追加
-X --exclude パターンに合致したファイルを処理対象から除外
--mq パッチ管理リポジトリへの操作
これだと、各オプションに対して、値が指定できるのかとか、複数回の指定が有効なのかとかがわからなくなってしまう。
まぁ、現状のコマンドラインでのオンラインヘルプ表示が、散々駄目出しを食らった上で取り込まれた、自分のパッチで実現されるようになったものなので、HTML側が片手落ちなのが我慢できない、ってのも大きいかも（笑）。
以下、作業の上で手間取った点に関して、備忘録代わりにメモしておく。
Python の docutils ライブラリを使った ReST テキストの整形だと:
-o --option ARGUMENT オプションの説明
上記のような記述での ARGUMENT 部分に指定可能な文字列は、『半角英字で始まる文字列』という条件を満たす正規表現との合致が必要なため、非英字で始まる翻訳済みの文字列だと、解析処理の段階で形式不正扱いされてしまう。
ありがたいことに、一応回避方法も用意されていて、『<文字列>』という形式であれば、任意の文字列を記述することも可能な模様。
上記の対処により、引数の詳細情報を追加することには成功したのだけれど、生成した HTML ページでは、以下のように、引数詳細が記述されたオプションで、行の折り返しが発生してしまう状況に。
--no-decode デコード処理を回避
-p --prefix <接頭辞>
アーカイブファイルのディレクトリ接頭辞
引数詳細 (上記例での『接頭辞』部分) が記述された全ての行で、行折り返しが発生しているのかと思ったが、実際には、『オプション列挙部分が一定文字数を超えた』場合限定で行折り返しをしている、との情報が:
何文字なら妥当かは場合によりけりで、何らかの数値を指定したとしても、『私にとっては妥当に思われる』以外には殊更根拠があるわけでは無いのだから、option_limit オプションを明示的に指定するようなパッチは、Matt が受け取ってくれないだろうなぁ……
多分、option_limit オプションは明示しないパッチを送ることになりそう。
これ以外にも、code freeze 期間向け修正パッチをいくつか作成できたので、自分の課題の消化に関しては、今回は比較的進んだ方かな？
追記:
結局、ドキュメント周りのパッチは取り込まれたけれど、HTMLページ生成に関するパッチは、2.8版のコードフリーズ明けに再度投函することに。
