um
is a command-line utility for creating and maintaining your own set of
man
-like help pages.
Have you seen how long curl
's man page is? How many times have you gone
through it trying to figure out how to make a POST request?
Man pages are written to be comprehensive, but what humans really need are the
bullet points. Use um
to write your own man
-like help pages that reflect
what you've learned about a command so far. That way you have an easy
reference for the things you already know are useful.
Say you've just reminded yourself how grep
works for the third time this
month. You'd like to hold on to that precious knowledge so you don't have to go
digging through the grep
man page again. You can do that with um
:
$ um edit grep
This will open your text editor, allowing you to record everything you want to
remember about grep
. Once you've saved what you've written, you can pull it
up again as easily as you would any man page:
$ um grep
This will open your pager with whatever you might have for grep
, say:
GREP(shell) Um Pages GREP(shell)
NAME
grep -- Print lines matching a pattern
SYNOPSIS
grep [options ...] [file ...]
REGEX SYNTAX
. Matches any character.
^ Anchors pattern to beginning of line.
$ Anchors pattern to end of line.
[] Character set. ^ for negation, - for range.
OPTIONS
-r Recursively search listed directories.
-E Force grep to behave as egrep, accepting extended REGEXes.
Um Pages September 26, 2017 GREP(shell)
um
supports several additional sub-commands. Among them are:
um list
, which lists all the um pages you already have.um rm
, which removes an existing um page.um topic
, which switches between topic namespaces for your pages, allowing you to keep a separate set of um pages for css properties, for example.
Man pages were historically typeset using the roff
typesetting
system. roff
was basically an early LaTeX. Writing man pages using roff
today is not very
fun or intuitive.
Happily, pandoc
can be used to convert Markdown documents to roff
-like man
pages. By default, um
expects you to write your um pages in Markdown so that
it can convert them and pass them to the man
program to view. You can,
however, elect to just write your um pages as .txt
files and view them
without going through the man
program.
Below is the Markdown source that produced the grep
listing above. Except for
the first three lines, it's all just Markdown:
% GREP(shell) Um Pages | Um Pages
%
% September 26, 2017
<!-- ^ The Pandoc "title block" which provides metadata about the page. -->
# NAME <!-- Top-level Markdown headings become man section headings. -->
grep -- Print lines matching a pattern
# SYNOPSIS
**grep** [options ...] <pattern> [file ...]
# REGEX SYNTAX
<!-- Here we're using a "definition list" to get that man page look. -->
.
: Matches any character.
^
: Anchors pattern to beginning of line.
$
: Anchors pattern to end of line.
[]
: Character set. ^ for negation, - for range.
# OPTIONS
-r
: Recursively search listed directories.
-E
: Force grep to behave as egrep, accepting extended REGEXes.
See Configuration below for more information on changing the default um page format. See the Pandoc Manual for more information about Pandoc's flavor of Markdown and the formatting options available to you when you are writing a man page in Markdown.
um
's own man pages are written in Markdown and converted using
Pandoc, so they could also make a good reference.
um
is currently available only for MacOS.
You can install um
via Homebrew:
$ brew install sinclairtarget/wst/um
A bash completion script for um
is installed to
/usr/local/etc/bash_completion.d
, assuming you're using the default brew
prefix. You may need to add the following lines to your ~/.bash_profile
to
enable the completion:
if [ -f $(brew --prefix)/etc/bash_completion.d/um-completion.sh ]; then
. $(brew --prefix)/etc/bash_completion.d/um-completion.sh
fi
Refer to um help
for comprehensive documentation of the sub-commands and
options available for um
. Man pages are also available.
You can configure um
using a file called umconfig
placed in a folder called
.um
in your home directory. The syntax for setting an option is as follows:
<option> = <value>
e.g.
pager = less
You can set values for pager
, editor
, default_topic
, pages_directory
,
and pages_ext
. The defaults for these options are less
, vi
, shell
,
~/.um
, and .md
respectively. Before falling back to the defaults, um
will
attempt to read the values for pager
and editor
from the shell environment
(i.e. the PAGER
and EDITOR
environment variables) if they are not
specified in umconfig
.
Option | Default | Meaning |
---|---|---|
pager |
less |
"Use this pager to view um pages." |
editor |
vi |
"Use this editor to edit um pages." |
default_topic |
shell |
Current topic if none is set. |
pages_directory |
~/.um |
Where to store um pages. |
pages_ext |
.md |
Unless .md , just the extension for your um pages. |
The pager
configuration option is only used when pages_ext
is not .md
(the default). When pages_ext
is .md
, then um
runs the pages through
pandoc
before passing them to man
. The pager used by man
is determined by
the PAGER
and MANPAGER
environment variables. See the man page for man
for more information.
So, if you wanted to store your um pages in your Dropbox folder, and you prefer emacs to vim, your config file might look like the following:
editor = emacs
pages_directory = /Users/myusername/Dropbox/um
You can print the current configuration using um config
.
If you place a file called template.md
in ~/.um
, that file will serve as
the basis for any new um pages you create (when pages_ext
is set to .md
).
If you have pages_ext
set to something else, perhaps .txt
, then you should
create a template file called template.txt
.
The template file is preprocessed so that the following variables are replaced before the file is used to create a new um page:
Variable | Substitution |
---|---|
$name |
The name of the page, which you specify when you call um edit <page name> . |
$NAME |
The same as above, but uppercase. |
$topic |
The name of the current topic. |
$time |
The current time in RFC2822 format. |
$date |
The current date as Month Day, Year. |
If you do not have an appropriate template in your ~/.um
directory, um
falls back to using its default templates. um
ships with a default template
for .md
um pages and .txt
um pages.
If you want to reset the topic to its default whenever you start a new shell,
you can place the following line in your .bash_profile
or .bashrc
:
um topic -d
You must have pandoc
installed to convert the Markdown man pages (for um
itself, that is) to the roff
format readable by man
. See
Rakefile.