Linuxでマニュアルページを作成する方法
公開: 2022-01-29
新しいLinuxプログラムをプロフェッショナルに見せたいですか？ manページを提供します。 最も簡単で最速の方法を紹介します。
マニュアルページ
古いUnixのジョークには、「知っておく必要のあるコマンドはmanだけです」という真実の核心があります。 manページには豊富な知識が含まれており、コマンドについて学びたいときに最初に参照する場所である必要があります。
作成したユーティリティまたはコマンドのmanページを提供すると、便利なコードから完全な形式のLinuxパッケージに昇格します。 人々は、Linux用に書かれたプログラムのmanページが提供されることを期待しています。 Linuxをネイティブにサポートしている場合、プログラムを真剣に受け止めたいのであれば、 manページは必須です。
歴史的に、 manページは一連のフォーマットマクロを使用して書かれてきました。 manにページを開くように要求すると、 groffが呼び出されてファイルが読み取られ、ファイル内のマクロに従ってフォーマットされた出力が生成されます。 出力はlessにパイプされ、表示されます。
manページを頻繁に作成しない限り、マニュアルページを作成して手動でマクロを挿入するのは大変な作業です。 正しく解析され、正しく表示されるmanページを作成するという行為は、コマンドの簡潔でありながら完全な説明を提供するという目的を超える可能性があります。
あいまいなマクロのセットと戦うのではなく、コンテンツに集中する必要があります。
関連： Linuxのmanコマンドの使用方法：隠された秘密と基本
レスキューへのパンドック
pandocプログラムは、マークダウンファイルを読み取り、 manページを含む約40の異なるマークアップ言語とドキュメント形式で新しいファイルを生成します。 manページの作成プロセスを完全に変換するため、象形文字と格闘する必要はありません。
開始するには、次のコマンドを使用してUbuntuにpandocをインストールできます。
sudo apt-get install pandoc
Fedoraでは、必要なコマンドは次のとおりです。
sudo dnf install pandoc
Manjaroで、次のように入力します。
sudo pacman -Syu pandoc
関連： Linuxコマンドラインでpandocを使用してファイルを変換する方法
マニュアルページのセクション
manページには、標準の命名規則に従ったセクションが含まれています。 manページに必要なセクションは、説明しているコマンドの洗練度によって決まります。
少なくとも、ほとんどのマニュアルページには次のセクションが含まれています。
- 名前：コマンドの名前と、その機能を説明する簡潔なワンライナー。
- 概要：誰かがプログラムを起動するために使用できる呼び出しの簡潔な説明。 これらは、受け入れられるコマンドラインパラメータのタイプを示しています。
- 説明：コマンドまたは機能の説明。
- オプション：コマンドラインオプションのリストとその機能。
- 例：一般的な使用法のいくつかの例。
- 終了値：可能な戻りコードとその意味。
- バグ：既知のバグと癖のリスト。 プロジェクトの課題追跡システムへのリンクが追加される（または置き換えられる）場合があります。
- 作成者：コマンドを作成した人。
- 著作権：あなたの著作権メッセージ。 これらには通常、プログラムがリリースされるライセンスの種類も含まれます。
より複雑なmanページのいくつかを見ると、他にも多くのセクションがあることがわかります。 たとえば、 man manを試してください。 ただし、それらすべてを含める必要はありません。本当に必要なものだけを含める必要があります。 manページは言葉遣いの場所ではありません。
かなり頻繁に表示されるその他のセクションは次のとおりです。
- 関連項目：主題に関連する他のコマンドは、有用または関連性があると思われるものもあります。
- ファイル：パッケージに含まれているファイルのリスト。
- 警告：知っておくべき、または注意すべきその他のポイント。
- 履歴：コマンドの変更履歴。
マニュアルのセクション
Linuxマニュアルは、すべてのmanページで構成されており、次の番号のセクションに分割されています。
- 実行可能プログラム：または、シェルコマンド。
- システムコール：カーネルによって提供される関数。
- ライブラリ呼び出し：プログラムライブラリ内の関数。
- 特別なファイル。
- ファイル形式と規則：たとえば、「/ etc / passwd」。
- ゲーム。
- その他：
groffなどのマクロパッケージと規則。 - システム管理コマンド：通常はroot用に予約されています。
- カーネルルーチン：通常、デフォルトではインストールされません。
すべてmanページは、それがどのセクションに属しているかを示す必要があります。また、後で説明するように、そのセクションの適切な場所に保存する必要があります。 コマンドとユーティリティのmanページはセクション1に属しています。
マニュアルページのフォーマット
groffマクロ形式は、視覚的に解析するのは簡単ではありません。 対照的に、値下げは簡単です。
以下はgroffのmanページです。
同じページが下のマークダウンに表示されます。
フロントの問題
最初の3行は、フロントマターと呼ばれるものを形成します。 これらはすべてパーセント記号（ % ）で始まり、先頭にスペースはなく、その後に1つ続く必要があります。
- 最初の行：コマンドの名前が含まれ、その後に括弧で囲まれた手動セクションが続きます。スペースは含まれません。 名前は、
manページヘッダーの左右のセクションになります。 慣例により、コマンド名は大文字ですが、そうでないものもたくさんあります。 コマンド名と手動セクション番号に続くものはすべて、フッターの左側のセクションになります。 ソフトウェアのバージョン番号に使用すると便利です。 - 2行目：作成者の名前。 これらは、
manページの自動生成された作成者セクションに表示されます。 「作成者」セクションを追加する必要はありません。ここに少なくとも1つの名前を含めるだけです。 - 3行目：フッターの中央部分にもなる日付。
名前
セクションは、マークダウンのヘッダーを示すマークアップである番号記号（ # ）で始まる行で示されます。 番号記号（ #)は、行の最初の文字であり、その後にスペースが続く必要があります。
nameセクションには、コマンドの名前、スペース、ハイフン（ - ）、スペース、およびコマンドの機能の非常に短い説明を含む、わかりやすい1行のライナーが含まれています。
あらすじ
概要には、コマンドラインで使用できるさまざまな形式が含まれています。 このコマンドは、検索パターンまたはコマンドラインオプションを受け入れることができます。 コマンド名の両側にある2つのアスタリスク（ ** ）は、名前がmanページに太字で表示されることを意味します。 一部のテキストの両側にある単一のアスタリスク（ * ）により、 manページに下線が引かれます。
デフォルトでは、改行の後に空白行が続きます。 空白行なしでハードブレークを強制するには、末尾の円記号（ \ ）を使用できます。
説明
説明は、コマンドまたはプログラムの機能を説明しています。 重要な詳細を簡潔にカバーする必要があります。 ユーザーガイドを書いているのではないことを忘れないでください。
行の先頭に2つの数字記号（ ## ）を使用すると、レベル2の見出しが作成されます。 これらを使用して、説明を小さなチャンクに分割できます。
オプション
オプションセクションには、コマンドで使用できるコマンドラインオプションの説明が含まれています。 慣例により、これらは太字で表示されるため、前後に2つのアスタリスク（ ** ）を含めます。 次の行にオプションのテキスト説明を含め、コロン（ :で開始し、その後にスペースを続けます。
説明が十分に短い場合、 manはコマンドラインオプションと同じ行にそれを表示します。 長すぎる場合は、コマンドラインオプションの下の行から始まるインデントされた段落として表示されます。
例
例のセクションには、さまざまなコマンドライン形式の選択が含まれています。 オプションセクションと同じように、説明行はコロン（ :で始まることに注意してください。
終了値
このセクションには、コマンドが呼び出し元のプロセスに送り返す戻り値が一覧表示されます。 これは、コマンドラインから呼び出した場合はシェルである可能性があり、シェルスクリプトから起動した場合はスクリプトである可能性があります。 このセクションでも、説明行をコロン（ :で始めます。
バグ
バグのセクションには、人々が知っておく必要のある既知のバグ、落とし穴、または癖がリストされています。 オープンソースプロジェクトの場合、バグのステータスを確認したり、新しいバグを報告したりするために、プロジェクトの課題追跡システムへのリンクをここに含めるのが一般的です。
著作権
著作権セクションには、著作権表示と、通常、ソフトウェアがリリースされるライセンスの種類の説明が含まれています。
効率的なワークフロー
お気に入りのエディタでmanページを編集できます。 構文の強調表示をサポートするほとんどの場合、マークダウンを認識し、見出しを強調表示するためにテキストに色を付け、太字と下線を付けます。 それはそれに関しては素晴らしいことですが、あなたはレンダリングされたmanページを見ていません。これはプリンの本当の証拠です。
マークダウンファイルが含まれているディレクトリでターミナルウィンドウを開きます。 エディターで開いた状態で、定期的にファイルをハードドライブに保存します。 実行するたびに、ターミナルウィンドウで次のコマンドを実行できます。
pandoc ms.1.md -s -t man | / usr / bin / man-l-
このコマンドを使用したら、上矢印を押してそれを繰り返し、Enterキーを押すことができます。
このコマンドは、マークダウンファイル（ここでは「ms.1.md」と呼ばれます）でpandocも呼び出します。
-
-s（スタンドアロン）オプションは、man形式のテキストだけでなく、上から下への完全なmanページを生成します。 - 「man」演算子を指定した
-t（出力タイプ）オプションは、pandocにman形式で出力を生成するように指示します。pandocに出力をファイルに送信するように指示していないため、stdoutに送信されます。
また、 -l （ローカルファイル）オプションを使用して、その出力をmanにパイプします。 これは、 manページを探してmanデータベースを検索しないようにmanに指示します。 代わりに、指定されたファイルを開く必要があります。 ファイル名が-の場合、 manはstdinから入力を取得します。
つまり、エディターから保存し、ターミナルウィンドウで実行されている場合は、Qキーを押してmanを閉じることができます。 次に、上矢印を押してからEnterキーを押すと、 manページのレンダリングされたバージョンがmanのすぐ内側に表示されます。
関連： Linuxのstdin、stdout、およびstderrとは何ですか？
マニュアルページの作成
manページが完成したら、その最終バージョンを作成して、システムにインストールする必要があります。 次のコマンドは、 pandocに「ms.1」というmanページを生成するように指示します。
pandoc ms.1.md -s -t man -o ms.1
これは、 manページに記述されているコマンドにちなんで名前を付け、ファイル拡張子であるかのように手動セクション番号を追加するという規則に従います。
これにより、新しいmanページである「ms.1」ファイルが作成されます。 どこに置くの？ このコマンドは、 man manを検索する場所を教えてくれます。
マンパス
結果から、次の情報が得られます。
- / usr / share / man：
manページの標準ライブラリの場所。 このライブラリにはページを追加しません。 - / usr / local / share / man：このシンボリックリンクは「/ usr / local / man」を指します。
- / usr / local / man：これは、新しい
manページを配置する必要がある場所です。
さまざまな手動セクションが、man1、man2、man3などの独自のディレクトリに含まれていることに注意してください。 セクションのディレクトリが存在しない場合は、作成する必要があります。
これを行うには、次のように入力します。
sudo mkdir / usr / local / man / man1
次に、「ms.1」ファイルを正しいディレクトリにコピーします。
sudo cp ms.1 / usr / local / man / man1
manはmanページが圧縮されることを期待しているので、 gzipを使用して圧縮します。
sudo gzip /usr/local/man/man1/ms.1
manに新しいファイルをデータベースに追加させるには、次のように入力します。
sudo mandb
それでおしまい！ 次のように入力することで、新しいmanページを他のページと同じように呼び出すことができます。
男ms
新しいmanページが見つかり、表示されます。
他のmanページと同じように見えますが、適切な場所に太字、下線付き、インデントされたテキストがあります。
説明するオプションの横に収まる説明の行は、同じ行に表示されます。 長すぎて収まらない線は、説明されているオプションの下に表示されます。
また、「作成者」セクションも自動的に生成されました。 フッターには、前書きで定義されているように、ソフトウェアのバージョン番号、日付、およびコマンド名も含まれています。
あなたがしたい場合は 。 。 。
pandocがmanページを作成したら、ファイルをmanページディレクトリに移動する前に、 groffマクロ形式でファイルを直接編集してgzipで圧縮することもできます。