歡迎光臨
每天分享高質量文章

如何創建和維護你自己的 man 手冊 | Linux 中國

Um 是一個命令列實用程式,可以用於輕鬆創建和維護包含你到目前為止所瞭解的所有命令的 man 頁面。
— Sk


致謝
編譯自 | 
https://www.ostechnix.com/how-to-create-and-maintain-your-own-man-pages/
 
 作者 | Sk
 譯者 | way-ww ??共計翻譯:3.0 篇 貢獻時間:23 天

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

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

安裝 Um

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

◈ Linuxbrew:一個用於 Linux 和 MacOS 的通用包管理器[2]

安裝 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. ==> Downloading from 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 in 35 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. Emacs Lisp 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 `.

  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> Create or edit the given page under the current topic.

  9. um rm <page name> Remove the given page.

  10. um (t)opic [topic] Get or set the current topic.

  11. um topics List all topics.

  12. um (c)onfig [config key] Display configuration environment.

  13. um (h)elp [sub-command] Display this help message, or the help message for a sub-command.

配置 Um

要查看當前配置,請運行:

  1. $ um config

  2. Options prefixed by '*' are set in /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

在此檔案中,你可以根據需要編輯和更改 pagereditordefault_topicpages_directory 和 pages_ext 選項的值。 比如說,如果你想在 Dropbox[3] 檔案夾中儲存新創建的 Um 頁面,只需更改 ~/.um/umconfig 檔案中 pages_directory的值並將其更改為 Dropbox 檔案夾即可。

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

這就是全部內容,希望這些能對你有用,更多好的內容敬請關註!

乾杯!


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

作者:SK[5] 選題:lujun9972 譯者:way-ww 校對:wxy

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

赞(0)

分享創造快樂

© 2021 知識星球   网站地图