首頁 > 軟體

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

2020-06-16 16:43:32

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

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

安裝 Um

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

安裝 Linuxbrew 後，執行以下命令安裝 Um 實用程式。

  1. $ brew install sinclairtarget/wst/um

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

  1. [...]
  2. ==>Installing sinclairtarget/wst/um
  3. ==>Downloading https://github.com/sinclairtarget/um/archive/4.0.0.tar.gz
  4. ==>Downloadingfrom https://codeload.github.com/sinclairtarget/um/tar.gz/4.0.0
  5. -=#=###
  6. ==>Downloading https://rubygems.org/gems/kramdown-1.17.0.gem
  7. ######################################################################## 100.0%
  8. ==> gem install /home/sk/.cache/Homebrew/downloads/d0a5d978120a791d9c5965fc103866815189a4e3939
  9. ==>Caveats
  10. Bash completion has been installed to:
  11. /home/linuxbrew/.linuxbrew/etc/bash_completion.d
  12. ==>Summary
  13. []/home/linuxbrew/.linuxbrew/Cellar/um/4.0.0:714 files,1.3MB, built in35 seconds
  14. ==>Caveats
  15. ==> openssl
  16. A CA file has been bootstrapped using certificates from the SystemRoots
  17. keychain.To add additional certificates (e.g. the certificates added in
  18. the System keychain), place .pem files in
  19. /home/linuxbrew/.linuxbrew/etc/openssl/certs
  20. and run
  21. /home/linuxbrew/.linuxbrew/opt/openssl/bin/c_rehash
  22. ==> ruby
  23. EmacsLisp files have been installed to:
  24. /home/linuxbrew/.linuxbrew/share/emacs/site-lisp/ruby
  25. ==> um
  26. Bash completion has been installed to:
  27. /home/linuxbrew/.linuxbrew/etc/bash_completion.d

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

要開啟 bash 補全，首先你需要開啟 ~/.bash_profile 檔案:

  1. $ nano~/.bash_profile

並在其中新增以下內容：

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

儲存並關閉檔案。執行以下命令以更新更改。

  1. $ source ~/.bash_profile

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

建立並維護自己的man手冊

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

  1. $ um edit dpkg

上面的命令將在預設編輯器中開啟 markdown 模板：

我的預設編輯器是 Vi，因此上面的命令會在 Vi 編輯器中開啟它。現在，開始在此模板中新增有關 dpkg 命令的所有內容。

下面是一個範例：

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

最後，使用以下命令檢視新建立的 man 手冊頁：

  1. $ um dpkg

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

  1. $ um edit dpkg

要使用 Um 檢視新建立的 man 手冊頁列表，請執行：

  1. $ um list

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

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

  1. $ um rm dpkg

要檢視幫助部分和所有可用的常規選項，請執行：

  1. $ um --help
  2. usage: um <page name>
  3. um <sub-command>[ARGS...]
  4. The first form is equivalent to `um read <page name>`.
  5. Subcommands:
  6. um (l)ist List the available pages for the current topic.
  7. um (r)ead <page name>Read the given page under the current topic.
  8. um (e)dit <page name>Createor edit the given page under the current topic.
  9. um rm<page name>Remove the given page.
  10. um (t)opic [topic]Getorset the current topic.
  11. um topics List all topics.
  12. um (c)onfig [config key]Display configuration environment.
  13. um (h)elp [sub-command]Displaythis help message,or the help message for a sub-command.

設定 Um

要檢視當前設定，請執行：

  1. $ um config
  2. Options prefixed by '*' are setin/home/sk/.um/umconfig.
  3. editor =vi
  4. pager =less
  5. pages_directory =/home/sk/.um/pages
  6. default_topic = shell
  7. pages_ext =.md

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

  1. pages_directory =/Users/myusername/Dropbox/um

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

乾杯！


相關文章

IT145.com E-mail:sddin#qq.com