Home Command line utilities How To Create And Maintain Your Own Man Pages
Um - Create And Maintain Your Own Man Pages

How To Create And Maintain Your Own Man Pages

By sk
33 Views

We already have discussed about a few good alternatives to Man pages. 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 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:

Create dpkg man page

Create a new man page

My default editor is Vi, so the above command open it in the Vi editor. Now, start adding everything you want to remember about "dpkg" command in this template.

Here is a sample:

Edit dpkg man page

Add contents in dpkg man page

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
View dpkg man page

View dpkg man page

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.umin your home directory

If you don't want a particular man 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 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

Hope this helps.

Resource:

Thanks for stopping by!

Help us to help you:

Have a Good day!!

You May Also Like

Leave a Comment

* By using this form you agree with the storage and handling of your data by this website.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish. Accept Read More