mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-23 21:20:42 +08:00
200 lines
6.6 KiB
Markdown
200 lines
6.6 KiB
Markdown
|
如何创建和维护你的Man手册
|
|||
|
|
======
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
我们已经讨论了一些[Man手册的替代方案] [1]。 这些替代方案主要用于学习简洁的Linux命令示例，而无需通过全面过于详细的手册页。 如果你正在寻找一种快速而简单的方法来轻松快速地学习Linux命令，那么这些替代方案值得尝试。 现在，你可能正在考虑 - 如何为Linux命令创建自己的man-like帮助页面？ 这时**“Um”**就派上用场了。 Um是一个命令行实用程序，用于轻松创建和维护包含你到目前为止所了解的所有命令的Man页面。
|
|||
|
|
|
|||
|
|
通过创建自己的手册页，你可以在手册页中避免大量不必要的细节，并且只包含你需要记住的内容。 如果你想创建自己的一套man-like页面，“Um”也能为你提供帮助。 在这个简短的教程中，我们将学习如何安装“Um”命令以及如何创建自己的man手册页。
|
|||
|
|
|
|||
|
|
### 安装 Um
|
|||
|
|
|
|||
|
|
Um适用于Linux和Mac OS。 目前，它只能在Linux系统中使用** Linuxbrew **软件包管理器来进行安装。 如果你尚未安装Linuxbrew，请参考以下链接。
|
|||
|
|
|
|||
|
|
安装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] [2] **文件夹中保存新创建的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][a]
|
|||
|
|
选题：[lujun9972][b]
|
|||
|
|
译者：[way-ww](https://github.com/way-ww)
|
|||
|
|
校对：[校对者ID](https://github.com/校对者ID)
|
|||
|
|
|
|||
|
|
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
|||
|
|
|
|||
|
|
[a]: https://www.ostechnix.com/author/sk/
|
|||
|
|
[b]: https://github.com/lujun9972
|
|||
|
|
[1]: https://www.ostechnix.com/3-good-alternatives-man-pages-every-linux-user-know/
|
|||
|
|
[2]: https://www.ostechnix.com/install-dropbox-in-ubuntu-18-04-lts-desktop/
|