git clone sinclairtarget-um_-_2018-08-20_17-05-52.bundle -b master
Create and maintain your own man pages so you can remember how to do stuff
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 gonethrough it trying to figure out how to make a POST request?
Man pages are written to be comprehensive, but what humans really need are thebullet points. Use
um to write your own
man-like help pages that reflectwhat you've learned about a command so far. That way you have an easyreference for the things you already know are useful.
Say you've just reminded yourself how
grep works for the third time thismonth. You'd like to hold on to that precious knowledge so you don't have to godigging through the
grep man page again. You can do that with
$ um edit grepThis will open your text editor, allowing you to record everything you want toremember about
grep. Once you've saved what you've written, you can pull itup again as easily as you would any man page:
$ um grepThis will open your pager with whatever you might have for
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.
Um Page Format
Man pages were historically typeset using the
roffwas basically an early LaTeX. Writing man pages using
roff today is not veryfun or intuitive.
pandoc can be used to convert Markdown documents to
roff-like manpages. By default,
um expects you to write your um pages in Markdown so thatit 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 themwithout going through the
Below is the Markdown source that produced the
grep listing above. Except forthe first three lines, it's all just Markdown:```markdown% GREP(shell) Um Pages | Um Pages%% September 26, 2017
grep -- Print lines matching a pattern
grep [options ...] [file ...]
.: Matches any character.
^: Anchors pattern to beginning of line.
$: Anchors pattern to end of line.
: Character set. ^ for negation, - for range.
-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 umpage format. See the PandocManual for more informationabout Pandoc's flavor of Markdown and the formatting options available to youwhen you are writing a man page in Markdown.
um's own man pages are written in Markdown and converted usingPandoc, 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
brewprefix. You may need to add the following lines to your
~/.bash_profile toenable the completion:
if [ -f $(brew --prefix)/etc/bash_completion.d/um-completion.sh ]; then . $(brew --prefix)/etc/bash_completion.d/um-completion.shfi
um help for comprehensive documentation of the sub-commands andoptions 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:
= e.g.pager = less
You can set values for
pages_ext. The defaults for these options are
.md respectively. Before falling back to the defaults,
um willattempt to read the values for
editor from the shell environment(i.e. the
EDITOR environment variables) if they are notspecified in
Option | Default | Meaning--- | --- | ---
less | "Use this pager to view um pages."
vi | "Use this editor to edit um pages."
shell | Current topic if none is set.
~/.um | Where to store um pages.
.md | Unless
.md, just the extension for your um pages.
pager configuration option is only used when
pages_ext is not
.md(the default). When
um runs the pages through
pandoc before passing them to
man. The pager used by
man is determined bythe
MANPAGER environment variables. See the man page for
manfor more information.
So, if you wanted to store your um pages in your Dropbox folder, and you preferemacs to vim, your config file might look like the following:
editor = emacspages_directory = /Users/myusername/Dropbox/um
You can print the current configuration using
If you place a file called
~/.um, that file will serve asthe 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 shouldcreate a template file called
The template file is preprocessed so that the following variables are replacedbefore 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 .
$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
umfalls back to using its default templates.
um ships with a default templatefor
.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
um topic -d
You must have
pandoc installed to convert the Markdown man pages (for
umitself, that is) to the
roff format readable by
Upload date: 2015-12-26
- 2018-08-20 17:05:52
- Internet Archive Python library 1.7.7
- iagitup - v1.0