mirror of
https://github.com/LCTT/TranslateProject.git
synced 2025-01-13 22:30:37 +08:00
Merge pull request #10702 from way-ww/master
20181009 How To Create And Maintain Your Own Man Pages.md
This commit is contained in:
Xingyu.Wang
GitHub
commit
4b08228c4a
@ -1,199 +0,0 @@
|
||||
Translating by way-ww
|
||||
How To Create And Maintain Your Own Man Pages
|
||||
======
|
||||
|
||||
|
||||
|
||||
We already have discussed about a few [**good alternatives to Man pages**][1]. Those alternatives are mainly used for learning concise Linux command examples without having to go through the comprehensive man pages. If you’re looking for a quick and dirty way to easily and quickly learn a Linux command, those alternatives are worth trying. Now, you might be thinking – how can I create my own man-like help pages for a Linux command? This is where **“Um”** comes in handy. Um is a command line utility, used to easily create and maintain your own Man pages that contains only what you’ve learned about a command so far.
|
||||
|
||||
By creating your own alternative to man pages, you can avoid lots of unnecessary, comprehensive details in a man page and include only what is necessary to keep in mind. If you ever wanted to created your own set of man-like pages, Um will definitely help. In this brief tutorial, we will see how to install “Um” command line utility and how to create our own man pages.
|
||||
|
||||
### Installing Um
|
||||
|
||||
Um is available for Linux and Mac OS. At present, it can only be installed using **Linuxbrew** package manager in Linux systems. Refer the following link if you haven’t installed Linuxbrew yet.
|
||||
|
||||
Once Linuxbrew installed, run the following command to install Um utility.
|
||||
|
||||
```
|
||||
$ brew install sinclairtarget/wst/um
|
||||
|
||||
```
|
||||
|
||||
If you will see an output something like below, congratulations! Um has been installed and ready to use.
|
||||
|
||||
```
|
||||
[...]
|
||||
==> 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
|
||||
|
||||
```
|
||||
|
||||
Before going to use to make your man pages, you need to enable bash completion for Um.
|
||||
|
||||
To do so, open your **~/.bash_profile** file:
|
||||
|
||||
```
|
||||
$ nano ~/.bash_profile
|
||||
|
||||
```
|
||||
|
||||
And, add the following lines in it:
|
||||
|
||||
```
|
||||
if [ -f $(brew --prefix)/etc/bash_completion.d/um-completion.sh ]; then
|
||||
. $(brew --prefix)/etc/bash_completion.d/um-completion.sh
|
||||
fi
|
||||
|
||||
```
|
||||
|
||||
Save and close the file. Run the following commands to update the changes.
|
||||
|
||||
```
|
||||
$ source ~/.bash_profile
|
||||
|
||||
```
|
||||
|
||||
All done. let us go ahead and create our first man page.
|
||||
|
||||
### Create And Maintain Your Own Man Pages
|
||||
|
||||
Let us say, you want to create your own man page for “dpkg” command. To do so, run:
|
||||
|
||||
```
|
||||
$ um edit dpkg
|
||||
|
||||
```
|
||||
|
||||
The above command will open a markdown template in your default editor:
|
||||
|
||||
|
||||
|
||||
My default editor is Vi, so the above commands open it in the Vi editor. Now, start adding everything you want to remember about “dpkg” command in this template.
|
||||
|
||||
Here is a sample:
|
||||
|
||||
|
||||
|
||||
As you see in the above output, I have added Synopsis, description and two options for dpkg command. You can add as many as sections you want in the man pages. Make sure you have given proper and easily-understandable titles for each section. Once done, save and quit the file (If you use Vi editor, Press **ESC** key and type **:wq** ).
|
||||
|
||||
Finally, view your newly created man page using command:
|
||||
|
||||
```
|
||||
$ um dpkg
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
As you can see, the the dpkg man page looks exactly like the official man pages. If you want to edit and/or add more details in a man page, again run the same command and add the details.
|
||||
|
||||
```
|
||||
$ um edit dpkg
|
||||
|
||||
```
|
||||
|
||||
To view the list of newly created man pages using Um, run:
|
||||
|
||||
```
|
||||
$ um list
|
||||
|
||||
```
|
||||
|
||||
All man pages will be saved under a directory named**`.um`**in your home directory
|
||||
|
||||
Just in case, if you don’t want a particular page, simply delete it as shown below.
|
||||
|
||||
```
|
||||
$ um rm dpkg
|
||||
|
||||
```
|
||||
|
||||
To view the help section and all available general options, run:
|
||||
|
||||
```
|
||||
$ 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.
|
||||
|
||||
```
|
||||
|
||||
### Configure Um
|
||||
|
||||
To view the current configuration, run:
|
||||
|
||||
```
|
||||
$ 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
|
||||
|
||||
```
|
||||
|
||||
In this file, you can edit and change the values for **pager** , **editor** , **default_topic** , **pages_directory** , and **pages_ext** options as you wish. Say for example, if you want to save the newly created Um pages in your **[Dropbox][2]** folder, simply change the value of **pages_directory** directive and point it to the Dropbox folder in **~/.um/umconfig** file.
|
||||
|
||||
```
|
||||
pages_directory = /Users/myusername/Dropbox/um
|
||||
|
||||
```
|
||||
|
||||
And, that’s all for now. Hope this was useful. More good stuffs to come. Stay tuned!
|
||||
|
||||
Cheers!
|
||||
|
||||
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://www.ostechnix.com/how-to-create-and-maintain-your-own-man-pages/
|
||||
|
||||
作者：[SK][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[译者ID](https://github.com/译者ID)
|
||||
校对：[校对者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/
|
||||
@ -0,0 +1,199 @@
|
||||
如何创建和维护你的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/
|
||||
Loading…
Reference in New Issue
Block a user