この記事では、manコマンドの実行で出てくるようなフォーマットのマニュアル、すなわちmanページについてのみ挙げる。あとコマンド以外(ヘッダファイルや関数とか)はキリがないので取り上げない。本記事の最終更新はそこらへんに書いてある。あとネット以外を調べないと見つからないマニュアルとか、正直知ったこっちゃないと言いたい。
この記事を作成したくなったきっかけ
Linux JM ProjectとFreeBSD jpman Projectでそれぞれ「説明」と「解説」をDESCRIPTIONの訳語に当てているのが気になって。
あとそこまで訳し方が多数あればGNUにもBSDにも寄っていないソフトウェアのマニュアルの作成はどうすべきか、的なことになるのと、方針はどうすべきか、ということも悩みそうで。
OS全体用
JM Project
JM プロジェクトは、主に Linux 関連のマニュアルページの日本語ページを翻訳・公開しています。
- プロジェクトガイドがある。
- 本記事初版執筆時点での最後の更新は2022-06-24と、活発。
- パッケージで分かれてる。
- GNU infoやPerlのPODもやってる。
- 多数ある。多数閲覧できる。
統一的な章立てについては正直よくわからない。
- LDP man-pagesについては次の順で章立てがなされる：名前、書式、説明、オプション、終了ステータス、環境変数、ファイル、準拠、注意、バグ、例、関連項目、この文書について
- 「Linux専用」のパッケージは、色々な人々により作成されているので原文の方のマニュアルの書き方も様々である。LDP man-pagesでの章立てと比べてざっくりしていたり、「オプション」を「説明」に入れたり、「作者」「入手方法」などとあったりと。どうまとめろと。
- GNUのパッケージ向けのマニュアルは、GNU info優先となってきている。そのためマニュアルには「の完全なドキュメントは Texinfo マニュアルとしてメンテナンスされています。」と見受けられるものが多数。即ち「manページは知ったこっちゃない」。また、GNUにはhelp2manというものがあってこれでマニュアルを簡易的に生成することができる。
- 「Unix 汎用」パッケージは色々。FreeBSDユーザから寄贈されたものとかあったりとか。正直まとめるのしんどい。
ていうかman(7)形式で書かれたマニュアルで、日付をアメリカ式で表示しているものと日本語で表示しているものがあったんだけどどこに見逃がしたんだろ。
FreeBSD 用の日本語マニュアルを作るプロジェクト(jpman プロジェクト)
- 2004年1月20日の更新で止まってる。
- そして翻訳予約のページが動かない。
- かつてはGNU由来のパッケージを流用していたこともあってJM Project由来っぽいマニュアルも混ざってるっぽい(例：FreeBSD 5.2-RELEASE 用のgrep(1)のマニュアル)
- FreeBSD 5.2-RELASE 用のマニュアルにおける使用マクロ体系はman(7)ではなくmdoc(7)になってた。
- こちらのオンライン検索は最早動作せず。オンライン検索は次の個人サイトのものを使うしかない。
- あるいはtarballをダウンロードするしかない。
FreeBSD 5.2-RELEASE用のマニュアルを見るとLinux JM Project由来のものも入り混ざっていた(csh(1),CC(1),as(1)など)。そんな中でFreeBSD側独自のもの(例：ed(1),pax(1))については次の章立てがなされていた。
- pax(1):名称、書式、解説、オペランド、オプション、使用例、規格、関連項目、歴史、作者、診断
- ed(1):名称、書式、解説、オプション、行指定、正規表現、コマンド、関連ファイル、関連項目、制限、診断、歴史
- ls(1):名称、書式、解説、使用例、診断、環境変数、互換性、関連項目、規格、歴史、バグ
- cat(1):名称、書式、解説、診断、使用例、関連項目、標準、歴史、バグ
章立てにおける用語や順番がバラバラなものもあった。オプションやオペランドが「解説」に入っていることもあった。
FreeBSD 日本語マニュアル検索 (jman/japropos/jwhatis)
- 上述のフォークっぽい。
- そして最も古いのがFreeBSD 8.4-RELEASE-K用のもの。
- 現在も更新やってるっぽい。その証拠としてGNU grepのマニュアルとFreeBSD自前のgrepのが見受けられたりと。
- ダウンロード可能なtarballが用意されている。それも4.11からのものから。
章立てについては省略。
SunOS リファレンスマニュアル (1) : ユーザーコマンド
ex(1)の章立ては：名前、形式、機能説明、オプション、オペランド、使用法、環境、終了ステータス、ファイル、属性、関連項目、作者、注意事項
ls(1)では使用法の次に使用例がある。
IBM DocumentationにあるAIXのコマンドのマニュアル
- AIXのバージョンごとにある。
- 日本語版も提供されている。少なくとも7.3は機械翻訳で。それより前は人手の翻訳っぽい。
- オンラインで見る場合、マニュアルにセクション番号というものはなさげ。でも本物のAIXではセクション番号ごとにマニュアルを用意。
- manページっぽいドキュメントとmanページじゃないっぽいドキュメントが用意されてる。
ex コマンドを例にする。章立ては：目的、構文、説明、フラグ、終了状況、ファイル
ls コマンドの章立てでは終了状況の次にセキュリティー、例が続く。環境変数の話については説明で触れられていた。
個別のソフトウェアの方
Tukubaiオンラインコマンドマニュアル - Open usp Tukubaiコマンドマニュアル
- 日本語のしかないよ。
- "DESCRIPTION"に当たる節が「【解説】」となっていることからFreeBSDの日本語マニュアル寄り。
-
マニュアルの配布もある。その形式がPDFとHTMLとプレーンテキストの3つ。
- troffが不便だったんじゃねえの？とでも推測したい。もともとはhtmlで書いてたんだろうか？
2022年10月28日版のテキスト版のマニュアルについて、全83ユーティリティ(と全6のファイルフォーマット)のマニュアルをざっくり見てみた。マニュアルの章立ては次の通りだった：名前、書式、説明、オプション、注意、例１、例２、…、ワンポイント、注意、関連項目、コラム。ただし「注意」の出現が自由だったり、オプション節を省いていたりと。あと節名を【】で囲んでいたりと。
変更履歴っぽいもの
2023-02-28でひとまずLinux JM Project, FreeBSD jpman Project, SunOSのもの、AIXのもの、Open Usp Tukubaiのマニュアルについてをまとめた。
今後これ以上増やすか？増やさなくてもよくね？