
Um – Create your own man pages so you can remember how to do stuff - quickthrower2
https://github.com/sinclairtarget/um
======
pjungwir
um is a brilliant name.

If you don't want to install anything new, you can also write your own man
pages with a personal "man section". Just do something like this in your
shell:

    
    
        export MANPATH="$MANPATH:$HOME/man"
        export MANSECT="1:n:l:8:3:2:3posix:3pm:3perl:5:4:9:6:7:pj"
    

Here I've added the "pj" section (my initials).

Then I have files like ~/man/manpj/postgres.pj or ~/man/manpj/ssl.pj. I can
say `man pj postgres` to see my own notes. My own collection goes back to 2001
or so. I feel lucky that early on I started putting notes into something so
portable. It's one of the few things that has always moved with me to new
machines. It is here:
[https://github.com/pjungwir/manpj/](https://github.com/pjungwir/manpj/)

You don't even need to use proper man formatting if you don't want to. I find
that a plain text file comes out pretty well. And when you want to start
adding sections/etc, there are only a handful of formatting codes to learn (or
copy/paste). I got started from a tiny chapter in O'Reilly's Unix in a
Nutshell. You're welcome to steal from my own repo above. (I'm sure the
formatting is nowhere close to best practice, but it's good enough for
personal use.)

~~~
teddyh
In fact, man pages were _made_ to be extensible in this way. It was assumed
that every site installation should have their local manual pages, and every
individual user too. It pains me to see so many useless projects like “um”
created just because people are assuming that the usual tool for something is
restricted to exactly what they are using it for.

~~~
toyg
_> just because people are assuming that the usual tool for something is
restricted_

To be fair, sometimes it's just because the usual tool is unfriendly. I've
just spent 30 mins to extend my manpath as parent suggested (on osx), and it's
not working. I have my variables, I have my directories, I have my text files,
and still man can't find them. For a tool as old as man, there is precious
little debugging information available. It shouldn't be this hard.

~~~
pjungwir
Ugh, I'm very sorry to have wasted your time! I mostly work on Linux, but I
tried it out on OS X and got the same results as you.

It looks to me like OS X will only search for sections named 1-9 (and maybe
"n" too). The MANSECT variable doesn't override this behavior. (I guess it
just changes the priority then?)

 _But_ you can have a custom suffix after a number. So if you have
~/man/man7/postgres.7pj (note just a 7 for the folder, but 7pj for the file
extension), you can open that file by saying `man 7pj postgres`. This is how
other programs with a lot of man pages work, e.g. `man 3perl open`. It's not
as nice to type a 7 too, but it's the best I can find that works. So I guess
on OS X you'd still set MANPATH but can leave MANSECT alone. (You could also
probably usurp section 9 or something, and omit your initials entirely.)

Or maybe you could compile a better `man` and put it in ~/bin. :-/

. . . In fact, I find that if I have ~/man/man7/postgres.7pj, I can even type
`man xpj postgres` to get my page. Maybe OS X man is just buggy?

~~~
toyg
Thanks, your help led me to a good solution: Apple man will accept section 0,
even though OSX doesn't ship it - so I can squat there. By appending :0 to
MANSECT I don't even need the section.

This could be the one time I actually find a good way to note down examples
for later reuse. Thanks!

------
dvh
One thing I hate about man pages is that there are not enough examples.
Sometimes feature is explained on five pages while simple one line example
would explained it instantly. And at the end there should be 2-3 pages of
examples at least, maybe even more.

~~~
philbarr
Those who can, do

Those who can't, teach

Those who can't teach, write

Those who can't write, write man pages

~~~
simplify
This is a pet peeve of mine. Teachers _are not_ somehow inferior to those who
do. It's a completely different skill set that actually helps you "do" better.

~~~
JoeAltmaier
Exactly. In sport we respect coaches for their particular skills. But somehow
teachers get joked about.

~~~
dcole2929
Sure we respect coaches, but we also still in every sport pay them
significantly less than the pros they ostensibly lead. I personally value both
coaches and teachers but it's very clear that we as a people have decided that
ability to do is more valuable than the ability to teach others.

------
thaumaturgy
Installing this on Linux is straightforward.

1\. You need Pandoc. On Debian, Ubuntu, etc. this is: `sudo apt-get install
pandoc`. I'm sure there's a similar incantation for Arch and so forth, but I
can't be arsed. If you don't already have Ruby installed in your system,
you'll need that too.

2\. cd into your favorite personal toolbox directory and `git clone
[https://github.com/sinclairtarget/um.git`](https://github.com/sinclairtarget/um.git`)

3\. Add a symlink to um in /usr/local/bin: `sudo ln -s /your/path/to/um/bin/um
/usr/local/bin/um`. Make sure you're symlinking to the um script, not the um
directory.

That's it. Enjoy.

Nice little widget. I like it.

~~~
enedil
Well, better modify $PATH than changing some system directories.

~~~
thaumaturgy
/usr/local/bin is a good place for things like that. See also
[http://man.openbsd.org/OpenBSD-
current/man7/hier.7](http://man.openbsd.org/OpenBSD-current/man7/hier.7) or
just `ls` your own system's /usr/local/bin directory.

------
x0
Just an aside, the repo complains about the length of curl's manpage, but
that's what I love about it. Fond memories of sitting on the train home from
uni, and browsing big long manpages looking for interesting new options to try
out.

------
hx2a
> Say you've just reminded yourself how grep works for the third time this
> month.

Hahaha, exactly. There are some commands that I just don't use enough for them
to properly stick in my mind. Awk is another one. This utility would be
helpful for me. Thanks!

~~~
mehrdadn
It would come in handy in this situation:
[https://xkcd.com/1168/](https://xkcd.com/1168/)

~~~
fengb
tar actually makes sense with a little mnemonic:

    
    
      tar xzf $file
      - xtract
      - ze (actually gzip but fake-accent "the" is more memorable)
      - file

~~~
mehrdadn
The most confusing thing about it for me now (after I eventually decided to
learn it and figured out what you mentioned) is the missing dash. Somehow it
works both with and without, which makes no sense considering how *nix tools
work. Why is it made to be like that?

~~~
cyphar
> Why is it made to be like that?

The history of tar is quite long, but the short version is that it was first
released as part of 7th edition Unix. It was a successor to tp[1] which was
introduced in 4th edition Unix, which was a successor to tap[2] which was
released in 1st edition Unix. In 1st edition Unix (as far as I could tell from
looking through the man pages), no command had '-abc'-style flag support at
all (so tap's semantics made sense). I imagine that quite a few users did
something like 'alias tap=tp' and 'alias tp=tar' when upgrading, and so CLI
backwards compatibility was required. As a result, everyone learned to use tar
that way and it stuck.

[1]: [http://man.cat-v.org/unix-6th/1/tp](http://man.cat-v.org/unix-6th/1/tp)
[2]:
[http://man.cat-v.org/unix-1st/1/tap](http://man.cat-v.org/unix-1st/1/tap)

~~~
oblio
And the (funny?) thing is that now the whole world has to suffer, probably
millions of developers, because at one point tar had an installed user base of
about 500 people. Yay for backwards compatibility :)

Make is another famous victim of this:

> Why the tab in column 1? Yacc was new, Lex was brand new. I hadn't tried
> either, so I figured this would be a good excuse to learn. After getting
> myself snarled up with my first stab at Lex, I just did something simple
> with the pattern newline-tab. It worked, it stayed. And then a few weeks
> later I had a user population of about a dozen, most of them friends, and I
> didn't want to screw up my embedded base. The rest, sadly, is history.

~~~
teddyh
> _now the whole world has to suffer_

Bad example, since tar still works with a dash:

    
    
      tar -ztvf foo.tar.gz
    

> _Make is another famous victim of this:_

Now that is a much better example.

------
Sreyanth
While this is interesting, I will probably find this too much of work to type
in all the stuff again with examples. Throwing a not-so-random extension idea
- may be a tool to go through the weird commands in my bash history and
suggest me to explain the commands which I just used?

Right now, I usually grep the man pages to search for things relevant to
specific context. Something like,

    
    
        man find | grep -i --color=always -C10 "file name"
    

Worked well in most cases. So, for figuring out how to send a POST request, I
would try

    
    
        man curl | grep -C10 --color=always POST
    

If that bombs, I would then immediately try

    
    
        curl --help | grep --color=always POST
    

If I end up using certain set of flags frequently, I will set up a bash
command like most others. Or, make a weird joke out of the flags, for example,

    
    
        ls -lionshit

~~~
banku_brougham
How could it check that the command from bash history successfully ran? I
often iterate about 10 times to get the right command, so that's 9 errors in
the history.

~~~
Sreyanth
May be extend a bit further to check if the return value is 0? Can be accessed
via `$?` in most non-Windows systems.

------
tigrezno
For me, it would be better if the tool actually did something like this:

\- open a real manpage `um grep`.

\- add a custom field to it, like "personal notes", at the beginning or at the
end, whatever.

\- save the new manpage in my home directory, so each time I do `man grep`
that custom manpage is used and I see my own notes.

------
neLrivVK
I just use my bash history with a very large HISTSIZE. Not as nice, but
doesn't require any effort. Effort I never want to put in at the time I'm
using the complicated command, I have other issues at that time :)

~~~
zach43
How do you deal with input from multiple concurrent bash sessions?

Usually I’ll have two or three konsole windows open at the same time, and I’ve
noticed that only one of them appears in the bash history...is there an easy
way to have it store all the history from all the windows?

~~~
phs2501
Use zsh.

[https://askubuntu.com/questions/23630/how-do-you-share-
histo...](https://askubuntu.com/questions/23630/how-do-you-share-history-
between-terminals-in-zsh)

It is possible to get similar effects by kludging around with bash, but it's a
built-in feature in zsh.

------
Annatar
“Writing man pages using roff today is not very fun or intuitive.”

Depends on who you ask: for me the best part of delivering software which I
wrote is writing the manual pages in straight nroff in vi, with lots of
examples. Seeing the engine typeset my documentation exactly the way I want is
always an awesome feeling.

It looks like to me that “um” is a reactionary effort because of the
notoriously poor quality of GNU/Linux manual pages which often lack examples;
if so, then the solution is to switch to a higher quality operating system
like FreeBSD or SmartOS / illumos.

------
shakna
If you are actually generating manpages, by using pandoc to generate roff
layouts... Why the extra view command? Why not register them with mandb?

~~~
ByThyGrace
Is it possible to register alternative manpages in such a way that they serve
as bullet-point cheatsheets?

~~~
shakna
Depends what you mean by 'alternative'.

You are always free to install manpages, however only one manpage per name
IIRC.

In this case, I'd just namespace it so you avoid any conflicts.

i.e.

    
    
        man git
    

And

    
    
        man um.git
    

So both are preserved.

~~~
nathell
The manpage namespaces are called sections. I think it would make a lot of
sense to put these pages in section 1u ('u' for 'um').

------
movedx
"Ha! What a great idea. That might be useful. Ah and it's a command line
utility too. Well this shou-oh it's written in Ruby never mind." \- Me.

(Because I can't be bothered installing Ruby or dealing with it at all. I've
never had a good experience. Sorry if that upsets you.)

~~~
enedil
If you have Mac or Linux, you probably already have Ruby.

------
kichuku
I have used asciinema for this purpose. Do you think it will be useful to link
asciinema recordings with this?

~~~
arendtio
:D I never thought about it, but now that you say it:

Why are there no scriptreplay/asciinema 'videos' available within normal man
pages? I mean yes, just a few more basic examples would certainly help more,
but for some more complicated commands a video might help too.

------
girishso
While not exactly same. But I find
[https://github.com/chubin/cheat.sh](https://github.com/chubin/cheat.sh) very
useful for finding usage.

------
statictype
Currently using dnote for this but this looks interesting as well.

I can see myself running `um git` literally before every invocation.

~~~
majewsky
> `um git`

This needs integration with voice assistants.

------
ams6110
Not taking anything away from this effort, but I just keep a "howto" section
in an org-mode file, where I keep all kinds of reminders and notes about stuff
I do.

------
wruza
Pure man(3) solution proposed here is very nice, but I usually just:

    
    
      vim ~/doc/nginx-snippets.txt # edit
      vim ~/doc/nginx-snippets.txt # consult
    

I actually have more files, config samples and source code templates, so it’s
not just ~/doc/.txt, but having them all in man registry would require yet
another better apropos(3) replacement. I also have my own vim colors format
that is much better looking to me than md^. I know that my argument may turn
similar to ‘dropbox is easy via ftp mount’, but I can’t see any need for a
tool even for my relatively big snippet-base. Moreover, with vim I can gf,
grep -r, _edit_ :w, etc. And with just files it is subject to svn/sh/make,
unleashing the full power of unix. --

^ just two levels of section headers, and :tags, all readable without color.
Based on dead-simple regexps, so in theory I could |sed them into terminal
escapes in five minutes.

------
tptacek
Does it show the man page after the user hints? It should show the actual man
page too, so I can replace “man” with it.

~~~
jwilk
It doesn't.

------
jamesrom
um is a great name for this tool

~~~
rodorgas
What’s the meaning of such name?

~~~
jerkstate
just a guess, but "unofficial manpage"

~~~
genezeta
Since they are "your own manpages", I would've guessed they are "user
manpages"?

------
guu
Some similarly helpful projects:

CLI tool to show simple examples instead of a full man page
[http://tldr.sh](http://tldr.sh)

View programming language and library documentation offline and in a single
place [http://devdocs.io](http://devdocs.io)

Cheat sheets for command line tools, programming languages, and libraries
[https://devhints.io](https://devhints.io)

------
NVRM
For anyone looking to do it «by hand», it's fairly doable:
[https://stackoverflow.com/a/50436684/2494754](https://stackoverflow.com/a/50436684/2494754)

~~~
Annatar
Bravo! And this should help as well:

[http://heirloom.sourceforge.net/doctools/troff.pdf](http://heirloom.sourceforge.net/doctools/troff.pdf)

[https://www.oreilly.com/openbook/utp/](https://www.oreilly.com/openbook/utp/)

------
lowleveldesign
Thanks, this tool looks great. I am eagerly awaiting a version for Linux.

~~~
jetti
Does anybody know why this can't run on linux now? I haven't touched Ruby in a
very long time and I didn't fully read over all the code but from my brief
look it seems like it is only because of the convenience of being able to use
Homebrew to ensure that pandoc is already installed when installing Um. Am I
missing something?

------
reacweb
Chapter 2 concern system calls. IMHO, this should be maintained by kernel
developpers and updated each time I update the kernel so that it is always in
sync. I would like to understand what is the contract the developper has
implemented. The limitations of a system call are the developpers regrets and
their plans for future evolutiond. I do not care if the style is not good.
What I care is how it should be used.

------
sharken
On Windows i find that using OneNote covers everything i need, mostly due to
excellent search via Ctrl+E. Being able to add pictures also helps.

------
bap
As someone who runs terminal obsessed engineering organizations I can see a
wider implication for team docs. Would love a distributed version of this. I
suppose we could do something with git, etc but the sync cycle would
inevitably kill forward momentum of usage. Bonus points for a web server for
those who aren't terminal obsessed.

------
lyngford
I started blogging to keep records on how to do certain things and it
eventually turned into teaching others how to do it.

------
alanbernstein
My personal solution to this problem:
[https://github.com/alanbernstein/quickref](https://github.com/alanbernstein/quickref)

------
Quequau
Interesting project but I do wonder if you're going to go through this amount
of effort if that idea of Literate-Devops with Org.Mode might not be a better
path.

------
scandox
I'd like this function except it would add a section to the existing man page.
That way my knowledge and the canonical information would be in the same
place.

------
exabrial
I use a Gollum wiki to do this exact thing. The nice part is it's backed by
git so it's easy to sync and backup to a gitlab private repo.

------
nautilus12
I hate how man pages are typically organized so I feel like if I built this
tool I would try to rethink how man pages are used at the same time.

------
amelius
Is it possible to host the manpages somewhere, so I can access them on all
machines I use?

(Perhaps using a git repository, and GitLab?)

~~~
rus64
You could put your pages on cloud storage?

------
throw7
One helpful option to add is an "apropos" as I do grep through my personal
stuff occasionally.

------
jiggunjer
I print 'cheat sheets' (e.g. regex, emmet & alt codes) and pin them next to my
monitor.

------
zombieprocess
I wish this was for life with a checklist like functionality. Like um edit
morningRoutine

------
dbnoch
I love the idea of this utility (I use TLDR myself) and wonder if there is a
way that tldr could be integrated with your tooling [https://github.com/tldr-
pages/tldr](https://github.com/tldr-pages/tldr).

I can see that there may be instances where you/your company would like to
have internal docs that should not be public and this utility would would work
for it

------
javajosh
I use nvalt for this.

------
nodofox
Started using it already! I love it :)

------
MrEfficiency
Let me say thanks for vocalizing the problems you were running into. Googling
axios for the third time this week...

------
a-b
There are couple alternatives like
[http://bropages.org/](http://bropages.org/) and
[https://tldr.sh/](https://tldr.sh/) How UM is different?

------
nichochar
I love tldr for similar-ish problem. [https://tldr.sh/](https://tldr.sh/)

------
moelf
prettyy sure [https://tldr.sh/](https://tldr.sh/) is enough.

------
susam
Interesting project. I believe these two shell functions in the shell's
initialization file (~/.profile, ~/.bashrc, etc.) can serve as a poor man's
um:

    
    
        umedit() { mkdir -p ~/notes; vim ~/notes/"$1.txt"; }
        um() { less ~/notes/"$1.txt"; }

~~~
gunnihinn
Make pandoc convert the txt/md/whatever to roff and pipe it to man, and you're
pretty much there. It would also work on more than OSX, unlike um itself.

~~~
danieldk
Something like:

    
    
        umedit() { mkdir -p ~/notes; vim ~/notes/"$1.md" }
        um() { pandoc -s -t man ~/notes/"$1.md" | tbl | groff -Wall -mtty-char -man -Tascii -c | less -R }
    

Not sure if pandoc creates tbl tables ;).

~~~
zhann_dc
I went for:

    
    
        function mdless() {
          pandoc -s -f markdown -t man $1 | groff -T utf8 -man | less
        }
        umedit() { mkdir -p ~/.notes; vim ~/.notes/$1; }
        um() { mdless ~/.notes/"$1"; }
        umls() { ls ~/.notes }
    

This way I can write the notes in markdown and view them as such in `less`.

~~~
v_lisivka
But how to share these man pages and how to search for man pages written by
others?

I can share my man pages with git/github, but nobody will notice them, nobody
will fix my spelling errors or contribute additional information.

Is there something like wiki, but for man pages?

~~~
masukomi
> Is there something like wiki, but for man pages?

yes. it's the source repo for whatever app you want improved man pages on.
Everyone can submit changes to it. All the good ones get merged in. It's
effectively a wiki curated by the most knowledgeable people on the subject.

um solves a different problem though. It's not trying to make a _common_ man
page. It's trying to make a man page that works _for you_. What _you_ need to
be highlighted is likely different from what _I_ need to be highlighted.

Personally I don't _want_ a generic wiki man page for stuff. I like the man
pages written by the creators of the code (because i know they're correct),
combined with my notes highlighting what's important to me.

------
sissyFuss
To be quite honest, I resist ever reading man pages simply out of purest spite
for that one well-known acronym.

I’ve never found actual help at the command line, delving any deeper beyond
the _\--help_ switch.

~~~
jwilk
What acronym?

~~~
gerdesj
RTFM (probably)

