如何創建和維護你自己的 man 手冊

我們已經討論了一些 man 手冊的替代方案。 這些替代方案主要用於學習簡潔的 Linux 命令示例，而無需通過全面而過於詳細的手冊頁。 如果你正在尋找一種快速而簡單的方法來輕鬆快速地學習 Linux 命令，那麼這些替代方案值得嘗試。 現在，你可能正在考慮 —— 如何為 Linux 命令創建自己的 man 式的幫助頁面？ 這時 「Um」 就派上用場了。 Um 是一個命令行實用程序，可以用於輕鬆創建和維護包含你到目前為止所了解的所有命令的 man 頁面。

通過創建自己的手冊頁，你可以在手冊頁中避免大量不必要的細節，並且只包含你需要記住的內容。 如果你想創建自己的一套 man 式的頁面，「Um」 也能為你提供幫助。 在這個簡短的教程中，我們將學習如何安裝 「Um」 命令以及如何創建自己的 man 手冊頁。

安裝 Um

Um 適用於 Linux 和Mac OS。 目前，它只能在 Linux 系統中使用 Linuxbrew 軟體包管理器來進行安裝。 如果你尚未安裝 Linuxbrew，請參考以下鏈接：

• Linuxbrew：一個用於 Linux 和 MacOS 的通用包管理器

安裝 Linuxbrew 後，運行以下命令安裝 Um 實用程序。

$ brew install sinclairtarget/wst/um

如果你會看到類似下面的輸出，恭喜你！ Um 已經安裝好並且可以使用了。

[...]
==> Installing sinclairtarget/wst/um
==> Downloading https://github.com/sinclairtarget/um/archive/4.0.0.tar.gz
==> Downloading from https://codeload.github.com/sinclairtarget/um/tar.gz/4.0.0
-=#=# # #
==> Downloading https://rubygems.org/gems/kramdown-1.17.0.gem
######################################################################## 100.0%
==> gem install /home/sk/.cache/Homebrew/downloads/d0a5d978120a791d9c5965fc103866815189a4e3939
==> Caveats
Bash completion has been installed to:
/home/linuxbrew/.linuxbrew/etc/bash_completion.d
==> Summary
[] /home/linuxbrew/.linuxbrew/Cellar/um/4.0.0: 714 files, 1.3MB, built in 35 seconds
==> Caveats
==> openssl
A CA file has been bootstrapped using certificates from the SystemRoots
keychain. To add additional certificates (e.g. the certificates added in
the System keychain), place .pem files in
/home/linuxbrew/.linuxbrew/etc/openssl/certs

and run
/home/linuxbrew/.linuxbrew/opt/openssl/bin/c_rehash
==> ruby
Emacs Lisp files have been installed to:
/home/linuxbrew/.linuxbrew/share/emacs/site-lisp/ruby
==> um
Bash completion has been installed to:
/home/linuxbrew/.linuxbrew/etc/bash_completion.d

在製作你的 man 手冊頁之前，你需要為 Um 啟用 bash 補全。

要開啟 bash 補全，首先你需要打開 ~/.bash_profile 文件:

$ nano ~/.bash_profile

並在其中添加以下內容：

if [ -f $(brew --prefix)/etc/bash_completion.d/um-completion.sh ]; then
 . $(brew --prefix)/etc/bash_completion.d/um-completion.sh
fi

保存並關閉文件。運行以下命令以更新更改。

$ source ~/.bash_profile

準備工作全部完成。讓我們繼續創建我們的第一個 man 手冊頁。

創建並維護自己的man手冊

如果你想為 dpkg 命令創建自己的 man 手冊。請運行:

$ um edit dpkg

上面的命令將在默認編輯器中打開 markdown 模板：

我的默認編輯器是 Vi，因此上面的命令會在 Vi 編輯器中打開它。現在，開始在此模板中添加有關 dpkg 命令的所有內容。

下面是一個示例：

正如你在上圖的輸出中看到的，我為 dpkg 命令添加了概要，描述和兩個參數選項。 你可以在 man 手冊中添加你所需要的所有部分。不過你也要確保為每個部分提供了適當且易於理解的標題。 完成後，保存並退出文件（如果使用 Vi 編輯器，請按 ESC 鍵並鍵入:wq）。

最後，使用以下命令查看新創建的 man 手冊頁：

$ um dpkg

如你所見，dpkg 的 man 手冊頁看起來與官方手冊頁完全相同。 如果要在手冊頁中編輯和/或添加更多詳細信息，請再次運行相同的命令並添加更多詳細信息。

$ um edit dpkg

要使用 Um 查看新創建的 man 手冊頁列表，請運行：

$ um list

所有手冊頁將保存在主目錄中名為 .um 的目錄下

以防萬一，如果你不想要某個特定頁面，只需刪除它，如下所示。

$ um rm dpkg

要查看幫助部分和所有可用的常規選項，請運行：

$ um --help
usage: um <page name>
 um <sub-command> [ARGS...]

The first form is equivalent to `um read <page name>`.

Subcommands:
 um (l)ist List the available pages for the current topic.
 um (r)ead <page name> Read the given page under the current topic.
 um (e)dit <page name> Create or edit the given page under the current topic.
 um rm <page name> Remove the given page.
 um (t)opic [topic] Get or set the current topic.
 um topics List all topics.
 um (c)onfig [config key] Display configuration environment.
 um (h)elp [sub-command] Display this help message, or the help message for a sub-command.

配置 Um

要查看當前配置，請運行：

$ um config
Options prefixed by '*' are set in /home/sk/.um/umconfig.
editor = vi
pager = less
pages_directory = /home/sk/.um/pages
default_topic = shell
pages_ext = .md

在此文件中，你可以根據需要編輯和更改 pager、editor、default_topic、pages_directory 和 pages_ext 選項的值。 比如說，如果你想在 Dropbox 文件夾中保存新創建的 Um 頁面，只需更改 ~/.um/umconfig 文件中 pages_directory 的值並將其更改為 Dropbox 文件夾即可。

pages_directory = /Users/myusername/Dropbox/um

這就是全部內容，希望這些能對你有用，更多好的內容敬請關注！

乾杯！

via: https://www.ostechnix.com/how-to-create-and-maintain-your-own-man-pages/

作者：SK 選題：lujun9972 譯者：way-ww 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive