https://www.amazon.co.jp/gp/product/B012WL4QMW/

最近 FireTV Stick を買った。動機は Amazon Prime Video を市販のテレビにキャストしたかったのだ(*1)。

これは電源をUSBケーブルから取る仕様なのだが、付属のケーブルは 長さが1.5m と短く、自分の環境では短過ぎた。だが、長いものを買おうにも、市販のケーブルで相性がいいものがなかなかなくて困った。

いろいろ試した結果、以下の Anker のものに行き着いた。3m でよければ、これで十分だ。Anker は USBケーブル周りでかなり評判が良いようなので買ってみたが、評判通りだったと言えよう(*´～｀)

(*1) PC から Google Chrome 経由で Amazon Prime Video をキャストさせたり、スマホ画面をキャストさせたりすれば見れるのは承知しているが、リモコンがあった方が家族には優しい

このエントリは、以下の Pull Request がマージされるまでの記録である。
https://github.com/svarshavchik/courier-libs/pull/13

3行まとめ

1) Courier Mail Server (以下 Courier) という古いメールサーバに patch を書いてマージしてもらった
2) いろいろ苦労しながら、やり遂げた記録
3) 青臭いソフトウェアエンジニアも、成長するものだと思う

なぜこの patch を書いたか

始まりは、Let's Encrypt を手元のサーバに導入しようとして、 Courier IMAP にも適用しようとしたことだった。だが、一筋縄では行かなかった。どうしても TLS の通信に失敗するのだ。いろいろググった結果、Courier では、「TLS の秘密鍵と証明書は同一のファイルに入っていなければいけない」ことがわかった。

多くのサーバソフトウェアでは、TLS の秘密鍵と証明書のファイルパスは別々に設定できる。メールサーバで言えば Postfix でもそうだ。このことから、自分にとっては Courier のこの動きは直感に反する仕様であった。しかもこれに関するドキュメントが 一切書かれていない ことにカッとなった。

だから、issueを立てて、秘密鍵と証明書を分離することを提案した ところ、メンテナ的にはデフォルトの動きに fallback 出来るなら問題ないよ、とのことだったので、patch を書いた。このエントリは、それがマージされたことの記録である。

当初はヤクの毛刈りに奔走

patch を書くのは一筋縄では行かなかった。当初はヤクの毛刈りに奔走させられた。当初は git のソースをまともにビルドすらできなかったので、ビルドをキックするスクリプトを修正することから始まり、メンテナと自分の開発するディストリビューションが異なる (*1) ことが原因の libtool まわりの修正から、ドキュメントの修正まで、送った patch は 6つに及んだ。

メンテナにしてみれば、自分以外の環境で patch を書く人がいるとは思ってもいなかったのだろう。

a) Courier 本体側で 送った patchたち
b) Courier Library 側で送った patch たち

(*1) メンテナは Fedora で、自分は Ubuntu だった。

OpenSSL + GnuTLS の両方に対応

一通りコードを書く環境が整い、途中まで patch を書いてみると、Courier は TLS 通信に OpenSSL だけでなく、 GnuTLS も並行してサポートしていることに気がついた。また、SNI(Server Name Indication) や IPアドレスベースのバーチャルホストもサポートしていたので、それらもこれら両方のライブラリでサポートするように書かなければならなかった。

さらに、これら2つのライブラリのコードは、実装されている機能がそれぞれに微妙に異なっていたので、どこまで実装するかを判断するために全コードを見る必要があり、対応は難航した。方針は以下に纏めた通りだが、正直 GnuTLS 側のコードは、よく [読めた|書けた] ものだと今振り返ってみて思う。

c) couriertls の TLS_PRIVATE_KEY 対応方針

モチベーション

何故ここまで続いたのかは、正直わからない。本職で C++ を書くようになり、この手のソフトウェアの深追いには慣れていたことが割と大きかったように思う。あとは、少しずつでも、ゴールに近づいている感覚が確実にあったからだろうか。また、義務感なしに、気が向いた時に作業できたのも大きい。

メンテナについて

Courier のメンテナは、 Sam Varshavchik というロシア人だ。コードが良ければ黙ってマージしてくれるし、提案にもちゃんと真摯に返事を返してくれる人だった。コード自体は正直綺麗だとは思わないが、OSS ではコードを全面的に書き直すのでもない限り、相手の流儀に徹底的に合わせるのが基本なので、メンテナの流儀を踏襲する方向で動いた。

その他

Courier 自体は 1990年代末からある古いソフトウェアである。自分は 自宅サーバを立て始めたのが2004年で、その時は他の人が書いた手順を見よう見まねで自分の環境にいろいろ適用しては試行錯誤を繰り返していた。 スラッシュドットの日記 にも、当時の青臭い記録が残っている。そんな糞エンジニアな自分が、こうして、patch を書くことなど思いもよらなかった。

当時から、少しは成長したんだなあ、と思う。

http://mumumu.github.io/blog/2013/06/29/php-manual-generate-howto/

このエントリは、5年前に書かれた上記エントリの更新版である。
PHP のバージョンを 5.x 系から 7.x 系にあげたのだが、やり方は何も変わっていない。ただ、PhD のバグが fix されているので、chm のビルド手順が単純になっている。

特に更新する必要はないかとも考えたが、最新バージョンでの手順を示すのも意義があると考え、脚注を少し足した上で、このエントリを記す。

PHPのマニュアルは、DocBook と呼ばれるフォーマットで記述されており、PhD という PHPマニュアル のためのツール によってその DocBook から HTML や CHM、PDF などの複数の形式にビルドできる。

この記事では、2018年6月時点で実際にPHPのマニュアルをリポジトリから取ってきてビルドする方法を紹介する。PhD は PDF や manpage形式、epub 等多様な形式がビルドできるが、ここでは HTML および chm のみについて触れる。

a) ビルドするときに使うPHPについて

まず、PHP をインストールしなければはじまらない。
2018年6月現在、PHP 7.2.6 が最新版である。このバージョンで問題なく HTML 版も chm もビルドできる。

PHP をインストールするときも、PhD のために DOM, libXML2, XMLReader and SQLite3 は有効にしていなければならない。ただ、これらは デフォルトで有効になっているので、無効にしないよう注意しよう。

b) 必要なツールをインストール

subversion と PEAR を予めインストール(*1)しておいて、PhD と PhD_PHP をpearコマンド経由でインストール(*2)する。
PhD_PHP は chm をビルドするのに必要だ。

$ pear version
PEAR Version: 1.10.5
PHP Version: 7.2.6
Zend Engine Version: 3.2.0
Running on: Linux 4.15.0-23-generic #25-Ubuntu SMP Wed May 23 18:02:16 UTC 2018 x86_64
$ pear install doc.php.net/PhD doc.php.net/PhD_PHP
WARNING: channel "doc.php.net" has updated its protocols, use "pear channel-update doc.php.net" to update
Did not download optional dependencies: phpdocs/PhD_PEAR, phpdocs/PhD_IDE, use --alldeps to download automatically
phpdocs/PhD can optionally use package "phpdocs/PhD_PEAR"
phpdocs/PhD can optionally use package "phpdocs/PhD_IDE"
phpdocs/PhD can optionally use PHP extension "haru"
phpdocs/PhD_PHP can optionally use PHP extension "haru"
phpdocs/PhD_Generic can optionally use PHP extension "haru"
downloading PhD-1.1.10.tgz ...
Starting to download PhD-1.1.10.tgz (47,401 bytes)
............done: 47,401 bytes
downloading PhD_PHP-1.1.10.tgz ...
Starting to download PhD_PHP-1.1.10.tgz (26,240 bytes)
...done: 26,240 bytes
downloading PhD_Generic-1.1.10.tgz ...
Starting to download PhD_Generic-1.1.10.tgz (29,362 bytes)
...done: 29,362 bytes
install ok: channel://doc.php.net/PhD-1.1.10
install ok: channel://doc.php.net/PhD_PHP-1.1.10
install ok: channel://doc.php.net/PhD_Generic-1.1.10

(*1) Unix/Linux/BSD だと、 ./configure で --without-pear とかしない限りデフォルトで入るが、Windows や Mac だと go-pear.phar が必要。詳しくは PEAR Manual を参照
(*2) PhD は composer にも対応しているが、依存ライブラリとして何かをすることはないので、PEAR 経由でのインストールが良い

c) リポジトリからの取得

次にマニュアルのソースをリポジトリから取ってくる。作業用のディレクトリを作って、リポジトリをsvnからチェックアウトする。

下記のURL には、 doc-base, en, ja への外部項目が設定されているので、以下のコマンド一つで3つのリポジトリが一気にチェックアウトできる。

$ mkdir phpdoc-ja
$ cd phpdoc-ja
$ svn co http://svn.php.net/repository/phpdoc/modules/doc-ja .

d) HTML版の PHPマニュアルをビルドする

--enable-xml-details は、XMLに万が一文法エラーがあったときに細かい情報を出力するためのモノだ。また、phd は結構メモリを使うので、memory_limit の値を大きめにしておいた方がよいかもしれない。

$ php doc-base/configure.php --with-lang=ja --enable-xml-details
$ phd -d doc-base/.manual.xml

成功すれば、 output ディレクトリ以下にマニュアルが生成される。

e) chm 版の PHPマニュアルをビルドする

PHP 7.2.6 では、以下のコマンドで何も考えなくても chm 版をビルドできる。--enable-chm は、chm特有のコンテンツを生成物に含めるために必要だ。 また、--with-lang や -L オプションで言語の指定も忘れずに。

まあ、--enable-chm がなくても、chm特有のヘルプコンテンツが入らないだけで、皆が見たいメインのコンテンツは欠落しないので、問題はないのだけれども。

$ php doc-base/configure.php --enable-chm --with-lang=ja
$ phd -f chm -P PHP -L ja -d doc-base/.manual.xml

成功すると、output/php-chm 以下に chm のコンテンツが生成される。

$ ls output/php-chm/
php_manual_ja.hhc  php_manual_ja.hhk  php_manual_ja.hhp  res

chm 形式のファイルは LZX 形式で圧縮されており、Linux や Mac では chm 形式は生成できないので、以下、Windows 上で chm ファイルをコンパイルする必要がある。

ここからは Windows での作業だ(*1) 。まず、HTML Help Workshop をインストールし、output/php-chm/php_manual_ja.hhp を File -> Open で開く。すると、以下のような画面になるはずだ。

この状態で、File -> Compile を 選択し、php_manual_ja.hhp を以下のようなダイアログで選び、OK を押すと php_manual_ja.hhp がある フォルダに php_manual_ja.chm が生成されるはずだ(*2)。

(*1) Windows 10 および、Windows Server 2016 で確認している
(*2) 実は、この手順で chm を生成すると、chm の検索が機能しない。きちんと機能させるためには、DBCSFix.exe というアジア系言語のためのバッチを適用し、適切なロケールで HTML Help Compiler を起動して生成する必要がある。これらをWindowsのビルド環境で手当するのは少し大変なので、そこまで手当した生成物が欲しい場合は、php.net から取得 したほうが良い。詳細を知りたい場合は、バッチプログラムのソースコード を読んでみよう

https://www3.lenovo.com/jp/ja/deals/sbiz/sbiz-accessory/KEYBOARD-Japanese/p/0B47181

最近、上のような形で3画面の環境にした。うん、良い。

だが、ノートPC (ASUS Zenbook Pro UX550VD) のキーボードがあまりにもアレだった(*注1)。リターンキーの右側に PgUp や PgDown 等のキーが存在してて、邪魔。使いにくいことこの上ない。

自分のような糞エンジニアでも生産性に影響するレベルだったため、ThinkPad Keyboard (Bluetooth版) を買った。

こういう動機で買ったものの、上のような環境だと首を横に向ければ壁によっかかる形で作業できるので、非常に良い。これまではノートパソコンを寝ながら使いたいという動機から ゴロ寝デスクの類を使ってきた が、ちょっと体勢を変えたいとか思った時も、デスクと違い、体の移動とかを考えなくても良い。

もともと ThinkPad ユーザー (*注2) だったため、このキータッチには慣れているし、何より軽いので非常に楽に使える。あと、ノートPC と違い、筐体が熱くならないのも何気にポイント高い。唯一の欠点といえば、一番左下が Fn キーで、ソフトウェア的に他の Keymap の割当が不可能なことだが、慣れの問題と言い切れるので、自分は気にならない(*注3)。

自分が本当に欲しかった環境って、「寝ながら使いたい」じゃなくて、「軽くて体がいろいろ動かしやすい」ことだったってことに今更気付いたのだった。。

なので、ゴロ寝デスクはもう使わない... 多分。

(*注1) じゃあなんで買ったし、というツッコミは尤もなんですが、急いでたので魔が差したというか...
(*注2) 社会人なりたての時に、ThinkPad T40 とか使ってたし、ThinkPad が好きな社長の会社で働いていた時は、業務用のPCも ThinkPad だった。
(*注3) 多分これが原因で Bluetooth 版を選んでない人相当いるんじゃないかと推測

http://cweb.canon.jp/drv-upd/ij-sfp/linux-pd-ip7230-380.html

Linux のドライバが動く、という理由で Canon IP7230 を5年前だかに導入した記憶がある。当時は Ubuntu にもドライバが出ていたのだが、現在は... ? ということで試してみたら、ネットワークに繋いだら DNS-SD 経由で自動で発見してくれ、ドライバも CUPS が持っているエントリから見つけることができた。

いい時代になったものだ。