├── .gitignore ├── Gemfile ├── LICENSE ├── README.md ├── Rakefile ├── UPGRADE.md ├── bin └── um ├── doc ├── man1 │ ├── um-config.1 │ ├── um-edit.1 │ ├── um-help.1 │ ├── um-list.1 │ ├── um-read.1 │ ├── um-rm.1 │ ├── um-topic.1 │ ├── um-topics.1 │ └── um.1 ├── um-config.md ├── um-edit.md ├── um-help.md ├── um-list.md ├── um-read.md ├── um-rm.md ├── um-topic.md ├── um-topics.md └── um.md ├── lib ├── um.rb └── um │ ├── commands.rb │ ├── options.rb │ ├── preprocessor.rb │ ├── topic.rb │ └── umconfig.rb ├── libexec ├── um-config.rb ├── um-edit.rb ├── um-help.rb ├── um-list.rb ├── um-read.rb ├── um-rm.rb ├── um-topic.rb └── um-topics.rb ├── templates ├── template.md └── template.txt ├── um-completion.sh ├── um-completion.zsh ├── um.gemspec └── version.txt /.gitignore: -------------------------------------------------------------------------------- 1 | notes.txt 2 | man_examples 3 | Gemfile.lock 4 | -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | 3 | gemspec 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 Sinclair Target 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # um 2 | `um` is a command-line utility for creating and maintaining your own set of 3 | `man`-like help pages. It is available for MacOS (via 4 | [Homebrew](https://brew.sh/)) and Linux (via AUR in Arch, otherwise via 5 | Homebrew, which is [now on Linux](https://docs.brew.sh/Homebrew-on-Linux)). 6 | 7 | ### Why? 8 | Have you seen how long `curl`'s man page is? How many times have you gone 9 | through it trying to figure out how to make a POST request? 10 | 11 | Man pages are written to be comprehensive, but what humans really need are the 12 | bullet points. Use `um` to write your own `man`-like help pages that reflect 13 | what you've learned about a command so far. That way you have an easy 14 | reference for the things you already know are useful. 15 | 16 | ### An Example 17 | Say you've just reminded yourself how `grep` works for the third time this 18 | month. You'd like to hold on to that precious knowledge so you don't have to go 19 | digging through the `grep` man page again. You can do that with `um`: 20 | ``` 21 | $ um edit grep 22 | ``` 23 | This will open your text editor, allowing you to record everything you want to 24 | remember about `grep`. Once you've saved what you've written, you can pull it 25 | up again as easily as you would any man page: 26 | 27 | ``` 28 | $ um grep 29 | ``` 30 | This will open your pager with whatever you might have for `grep`, say: 31 | ``` 32 | GREP(shell) GREP(shell) 33 | 34 | 35 | NAME 36 | grep -- Print lines matching a pattern 37 | 38 | SYNOPSIS 39 | grep [OPTIONS...] pattern [FILE...] 40 | 41 | REGEX SYNTAX 42 | . Matches any character. 43 | 44 | ^ Anchors pattern to beginning of line. 45 | 46 | $ Anchors pattern to end of line. 47 | 48 | [] Character set. ^ for negation, - for range. 49 | 50 | OPTIONS 51 | -r Recursively search listed directories. 52 | 53 | -E Force grep to behave as egrep, accepting extended REGEXes. 54 | 55 | 56 | 57 | Um Pages September 26, 2017 GREP(shell) 58 | ``` 59 | 60 | `um` supports several additional sub-commands. Among them are: 61 | * `um list`, which lists all the um pages you already have. 62 | * `um rm`, which removes an existing um page. 63 | * `um topic`, which switches between topic namespaces for your pages, allowing 64 | you to keep a separate set of um pages for css properties, for example. 65 | 66 | ### Um Page Format 67 | Man pages were [historically typeset using the `roff` typesetting 68 | system](http://twobithistory.org/2017/09/28/the-lineage-of-man.html). `roff` 69 | was basically an early LaTeX. Writing man pages using `roff` today is not very 70 | fun or intuitive. 71 | 72 | Happily, the Kramdown library can be used to convert Markdown documents to 73 | `roff`-like man pages. (Previously, `um` used Pandoc. See 74 | [UPGRADE.md](/UPGRADE.md) if the switch to Kramdown has broken your um pages.) 75 | By default, `um` expects you to write your um pages in Markdown so that it can 76 | convert them and pass them to the `man` program to view. You can, however, 77 | elect to just write your um pages as `.txt` files and view them without going 78 | through the `man` program. 79 | 80 | Below is the Markdown source that produced the `grep` listing above. Except for 81 | the Kramdown-specific attribute syntax (all the fiddly curly brace bits), it's 82 | all just Markdown: 83 | ```markdown 84 | # grep -- Print lines matching a pattern 85 | {:data-section="shell"} 86 | {:data-date="September 26, 2017"} 87 | {:data-extra="Um Pages"} 88 | {::comment} 89 | ^ The Kramdown "attribute list" which provides metadata for the page. 90 | The first heading must include the name of the command and a summary. 91 | {:/} 92 | 93 | ## SYNOPSIS 94 | {::comment}Top level Markdown headings become man section headings.{:/} 95 | **grep** [OPTIONS...] *pattern* [FILE...] 96 | 97 | ## REGEX SYNTAX 98 | {::comment}Here we're using a "definition list" to get that man page look.{:/} 99 | 100 | `.` 101 | : Matches any character. 102 | 103 | `^` 104 | : Anchors pattern to beginning of line. 105 | 106 | `$` 107 | : Anchors pattern to end of line. 108 | 109 | `[]` 110 | : Character set. ^ for negation, - for range. 111 | 112 | ## OPTIONS 113 | `-r` 114 | : Recursively search listed directories. 115 | 116 | `-E` 117 | : Force grep to behave as egrep, accepting extended REGEXes. 118 | ``` 119 | 120 | See [Configuration](#config) below for more information on changing the default 121 | um page format. See the [Kramdown Man Converter 122 | Documentation](https://kramdown.gettalong.org/converter/man.html) for more 123 | information about Kramdown's flavor of Markdown and the formatting options 124 | available to you when you are writing a man page. 125 | 126 | `um`'s own [man pages](/doc) are written in Markdown and converted using 127 | Kramdown, so they could also make a good reference. 128 | 129 | ## Installation 130 | 131 | 132 | Packaging status 133 | 134 | 135 | * **MacOS/Linux:** `um` is available via [Homebrew](http://brew.sh/): 136 | ``` 137 | $ brew install um 138 | ``` 139 | * **Arch Linux:** `um` is available via the AUR in two versions: the release version [`um`](https://aur.archlinux.org/packages/um/) and the latest master [`um-git`](https://aur.archlinux.org/packages/um-git/) 140 | 141 | ### Post-Installation 142 | A bash completion script for `um` is installed to 143 | `/usr/local/etc/bash_completion.d`, assuming you're using the default `brew` 144 | prefix. You may need to add the following lines to your `~/.bash_profile` to 145 | enable the completion: 146 | ``` 147 | if [ -f $(brew --prefix)/etc/bash_completion.d/um-completion.sh ]; then 148 | . $(brew --prefix)/etc/bash_completion.d/um-completion.sh 149 | fi 150 | ``` 151 | 152 | ## Help 153 | Refer to `um help` for comprehensive documentation of the sub-commands and 154 | options available for `um`. Man pages are also available. 155 | 156 | 157 | ## Configuration 158 | You can configure `um` using a file called `umconfig` placed in a folder called 159 | `.um` in your home directory. The syntax for setting an option is as follows: 160 | ``` 161 |