概要
automakeから、help2manによるmanページを生成する手順を確認した。
はじめに
Linuxではmanコマンドによる利用者にオンラインマニュアルを提供する機構が設けられている。
ソフトウェアパッケージの開発者は、そのソフトウェアの使い方を記したmanページを含めて配布することが望ましい。
しかし、manページはの作成は更新する頻度も多く手間がかかる。
help2manは、ソフトウェアの実行結果から標準的manページを自動生成するツールである。 www.gnu.org
また、help2manとautomakeを併用することで、configureファイルの生成からmanページの生成までの手順を自動化することができる。
そこで、本記事ではautomakeを使ってhelp2manでmanページを生成する手順を紹介する。
準備
下記のリポジトリを例にhelp2manを使ってmanページを生成する手順と、automakeによりmanページを自動生成する手順をまとめる。
dumpexfatは、FAT/exFATのファイルシステムイメージから情報を取得することができるプログラムである。
このプログラムは複数のオプションの指定を許しており、以下のオプションをサポートしている。
| オプション (long option) | 概要 |
|---|---|
| -c (--cluster=index) | indexで指定したクラスタ番号のデータを出力する |
| -f (--force) | 未確保のクラスタでも出力を許す |
| -o (--output) | 結果を指定したファイルに出力する |
| -s (--sector=index) | indexで指定したセクタ番号のデータを出力する |
| -v (--verbose) | メッセージを冗長に出力する |
help2man とは
公式サイトに詳細な説明があるので、詳しくはそちらを参照。
help2manはプログラムの--helpオプションと--versionオプションから簡単なmanページを作成するツールである。
このとき、--helpと--versionは、仕様に基づいた形式*1で記述することで精度の高いmanページを生成することができる。
一般的なmanページを作るときに必要となる--helpを下記に示す。
Usage: <コマンド名> <コマンド書式> ★ SYNOPSIS に出力される
<コマンド概要> ★ NAMEに出力される
<コマンド説明> ★ DESCRIPTIONに出力される
Options: ★ OPTIONSに出力される
<オプション> <オプション概要>
Examples: ★ EXAMPLEに出力される
<例> ＜実行例の説明＞
Report bugs to: <mailing-address> ★ REPORTING BUGSに出力される
<>で記述したものに関しては、開発者がそのプログラムにあったものに修正する必要となる。
また、その他にmanページのセクションを追加したい場合は、<セクション名>: で追加することができる。
一般的なmanページを作るときに必要となる--versionを下記に示す。
<command> <version>
<著作権表示> ★ COPYRIGHTに出力される
Written by <作者> ★ AUTHORに出力される
manページを生成する
help2manの書式に則って、--helpと--versionを作成する。
$ dumpexfat --help
Usage: dumpexfat [OPTION]... FILE
dump FAT/exFAT filesystem information.
-c, --cluster=index dump the cluster index after dump filesystem information.
-f, --force dump the cluster forcibly in spite of the non-allocated.
-o, --output=file send output to file rather than stdout.
-s, --sector=index dump the sector index after dump filesystem information.
-v, --verbose Version mode.
--help display this help and exit.
--version output version information and exit.
Examples:
dumpexfat /dev/sda dump FAT/exFAT filesystem information.
dumpexfat -c 2 /dev/sda dump FAT/exFAT filesystem information and cluster #2.
$ dumpexfat --version
dumpexfat 0.1
Written by LeavaTail.
manページの作成に必要なものはこれで完了したので、help2manを実行する。
$ help2man --no-discard-stderr -N -o dumpexfat.1 dumpexfat
今回は下記のオプションに指定した。
--no-discard-stderr: stderrに出力された内容も使用する-N: manページの末尾にTexinfoの情報を載せないようにする-o: 出力先のファイルを指定する
automakeにhelp2manを組み込む
help2manの更新でも記述されているが、automakeと連携させる場合には、manページの依存関係にソースコードを指定することが望ましい。
そこで、このプロジェクトではMakefile.amに下記のターゲットを追加した。
dumpexfat.1: dumpexfat$(EXEEXT)
help2man --no-discard-stderr -N -o dumpexfat.1 ./dumpexfat
これで、automakeを実行することでhelp2manコマンドからmanページを生成できるようなMakefileが生成できるようになった。
おわりに
本記事は、automakeを使ってhelp2manでmanページを生成する手順を書き留めた。
help2manによって生成されたmanページは必要最低限度の情報が記述されているはずなので、とりあえずプロジェクトに組み込むとよいだろう。
変更履歴
- 2020/08/10: 記事公開
*1:cpコマンドを参考にするとよい
