LeavaTailの日記

LeavaTailの日記

Linuxエンジニアを目指した技術者の備忘録

help2man でmanページを自動生成する

はじめに

Linuxではmanコマンドによる利用者にオンラインマニュアルを提供する機構が設けられている。

ソフトウェアパッケージの開発者は、そのソフトウェアの使い方を記したmanページを含めて配布することが望ましい。
しかし、manページはの作成は更新する頻度も多く手間がかかる。

help2manは、ソフトウェアの実行結果から標準的manページを自動生成するツールである。 www.gnu.org

またhelp2manとautomakeを併用することで、configureファイルの生成からmanページの生成までの手順を自動化することができる。

そこで、本記事ではautomakeを使ってhelp2manでmanページを生成する手順を紹介する。

f:id:LeavaTail:20200808171034p:plain
help2manの出力結果

準備

下記のリポジトリを例にhelp2manを使ってmanページを生成する手順と、automakeによりmanページを自動生成する手順をまとめる。

github.com

dumpexfatは、FAT/exFATファイルシステムイメージから情報を取得することができるプログラムである。
このプログラムは複数のオプションの指定を許しており、以下のオプションをサポートしている。

オプション (long option) 概要
-c (--cluster=index) indexで指定したクラスタ番号のデータを出力する
-f (--force) 未確保のクラスタでも出力を許す
-o (--output) 結果を指定したファイルに出力する
-s (--sector=index) indexで指定したセクタ番号のデータを出力する
-v (--verbose) メッセージを冗長に出力する

help2man とは

公式サイトに詳細な説明があるので、詳しくはそちらを参照。

www.gnu.org

help2manはプログラムの--helpオプションと--versionオプションから簡単なmanページを作成するツールである。

f:id:LeavaTail:20200802184937p:plain
help2manの概略図

このとき、--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ページは必要最低限度の情報が記述されているはずなので、とりあえずプロジェクトに組み込むとよいだろう。

*1:cpコマンドを参考にするとよい