<commit_before># um
`um` is a command-line utility for creating and maintaining your own set of
`man`-like help pages.

### Why?
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.

### An Example
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.

### Um Page Format
Man pages were historically typeset using the `troff` typesetting system.
`troff` was basically an early LaTeX. Writing man pages using `troff` today is
not very fun or intuitive.

Happily, `pandoc` can be used to convert Markdown documents to `troff`-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 throught the `man` program.

Below is the Markdown source that produced the `grep` listing above:
```markdown
% GREP(shell) Um Pages | Um Pages
%
% September 26, 2017
<!-- ^ The Pandoc "title block" which provides metadata about the page. -->
<!-- If you use the default templates, this will be filled in for you. -->

# NAME <!-- Top-level Markdown headings become man section headings. -->
grep -- Print lines matching a pattern
<commit_msg>Fix spelling error in README.md<commit_after># um
`um` is a command-line utility for creating and maintaining your own set of
`man`-like help pages.

### Why?
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.

### An Example
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.

### Um Page Format
Man pages were historically typeset using the `troff` typesetting system.
`troff` was basically an early LaTeX. Writing man pages using `troff` today is
not very fun or intuitive.

Happily, `pandoc` can be used to convert Markdown documents to `troff`-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:
```markdown
% GREP(shell) Um Pages | Um Pages
%
% September 26, 2017
<!-- ^ The Pandoc "title block" which provides metadata about the page. -->
<!-- If you use the default templates, this will be filled in for you. -->

# NAME <!-- Top-level Markdown headings become man section headings. -->
grep -- Print lines matching a pattern

{'fraction_non_alphanumeric': 0.07115607895173329, 'fraction_numerical': 0.003980759661635429, 'mean_word_length': 3.02, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1609608', 'n_tokens_mistral': 1724, 'n_tokens_neox': 1584, 'n_words': 918}