Um – Create your own man pages so you can remember how to do stuff | Hacker News Reader

Um – Create your own man pages so you can remember how to do stuff

github.com

647 pointsquickthrower2165 comments

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/

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.)

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.

> 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.

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?

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!

The Unix tools in macOS are old and bad. What else is new?

The problem with this approach is that you then have to maintain that variable. On OSX, my /etc/man.conf includes this for MANSECT:

1:1p:8:2:3:3p:4:5:6:7:9:0p:tcl:n:l:p:o

I guess one should really have a script that first greps out that default value, and then appends your custom section before exporting the variable.

EDIT: something like:

export MANSECT=$(pcregrep -o1 MANSECT\\s\{2,\}$.*$ /etc/man.conf):pj

>um is a brilliant name.

Literally so, if you consider that "ум" in Russian means "mind / intelligence", and "um" is the transliteration of that into Latin alphabet, making it a bilingual pun.

"Just use your Um!"

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"; }

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.

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 ;).

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`.

Great, thank you! I rewrote them for fish shell syntax and added the '-c' flag for `less` so it starts writing from the top of the window instead that from the bottom, I'm more confortable with it (still I don't know why it doesn't fit the terminal width like man does, but it wraps text every 80 characters - I guess it's not a problem anyway).

function mdless pandoc -s -f markdown -t man $argv[1] | groff -T utf8 -man | less -c end function umedit mkdir -p ~/.notes; nvim ~/.notes/$argv[1]; end function um mdless ~/.notes/"$argv[1]" end function umls ls ~/.notes/ end

(reminder, to make them permanent just: `funcsave mdless umedit um umls`)

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?

> 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.

umedit with templating:

    function umedit() {
        mkdir -p ~/.notes
        if [ ! -f ~/.notes/$1.md ]; then
            echo "% $(echo $1 | tr '[:lower:]' '[:upper:]')(shell) Um Pages | Um Page" >> ~/.notes/$1.md
            echo "\n# NAME\n$1 - $(whatis $1 2> /dev/null | cut -d '-' -f 2 | awk '{$1=$1};1')\n\n# COMMANDS" >> ~/.notes/$1.md
        fi
        vim ~/.notes/$1.md
    }

I love how immediately customizable this makes everything. Thank you. I'm imagining somebody tweaking this just a bit so that a robotic arm throws "Linux in a Nutshell" at them from across the room.

If you write these in .rst, you can generate actual manpages with Sphinx: http://www.sphinx-doc.org/en/master/usage/configuration.html...

sphinx.builders.manpage: http://www.sphinx-doc.org/en/master/_modules/sphinx/builders...

Nice!

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.

I find that this is something openBSD gets /really/ right. In general the man pages in BSD are phenomenal.

What happened to ‘info’ pages. I hated it, but wasn’t that supposed to address these kinds of issues with examples?

Info pages are still there.

    $ info grep

Info is much better than man, but keep in mind it's only covering gnu coreutils (which isn't a bad thing!)

Huh? grep is not part of coreutils.

I know this is late but you are right. For some reason I thought info was only fore coreutils, but it seems I was wrong. I only ever used it for coreutils, but hey, thats good news to me!

Why is info better than man?

Better search and better organization of the document (TOC, index search, etc.). And reading/searching Info manuals is a lot more convenient in Emacs Info-mode.

The man page for gcc goes on and on. Try it.

The info for gcc is a printed book, which is also accessible in the shell as hypertext (which predates html).

If you’re using a GNU system now you might be surprised by the quality of the BSD man pages, and documentation in general. Concise but still comprehensive, and plenty of examples. The tools (like man) aren’t really the problem here, the documentation itself is. (But it helps that the BSD folks show a bit more restraint wrt adding command line options.)

I have just compared the man pages for Linux and FreeBSD, but the result is not really clear:

Example provided on the FreeBSD man page of cut.

Examples provided on the Linux man page of xargs.

More examples provided on the Linux man page of find.

I find the cut man page (looking at the OpenBSD one) very clear. It's just 62 lines (fits on a screen), has only 5 flags and the 2 examples clearly show how the tool is used.

The xargs man page is ought to have some examples, I agree.

The find manual is lengthy (as it has a bunch of options) but not excessively so and it also has a good bunch of examples.

Edit: it also helps to be familiar with the pager, like using the search feature (hit / , n, n, Shift+n, ...) and the jump keys (G and g).

tldr tries to fix that: https://tldr.sh

Ever since I have discovered tldr i've been using man pages less and less.

When viewing man pages, you are using less by default.

lrf, guvf vf n cha

Also a big fan of tldr :) But love the idea of writing my own.

Not enough examples is only in GNU/Linux; the BSD’s and illumos-based operating systems have plenty of examples. Especially illumos, since they enforce a rule that no component may be integrated without a comprehensive manual page and since they come from Solaris, most of the documentation was written by a dedicated department of professional technical writers working with the engineers to document their work in a systematic fashion.

perldoc begins with examples by convention. No need to /EXA

See e.g. https://metacpan.org/pod/release/PHRED/Archive-Zip-1.62/lib/...

Those who can, do

Those who can't, teach

Those who can't teach, write

Those who can't write, write man pages

And those who believe in this aphorism have never did, taught or written :)

honestly, not having a man page would be better than half of the man pages out there

Having benefited tremendously from manpages I believe they're absolutely worth existing, whatever manpage seemed insufficient to you.

Those who can, do. Those who can't, become product managers.

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.

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

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.

H.L. Mencken had a strong antipathy to teachers, and maths specifically.

Rather a disappointment.

Man pages are a community project. Send patches!

While this is laudable, how many GNU projects, especially, don't use an archaic development/contribution process? I don't want to have to register on a mailing list and prepare patches.

This is an honest question. Friction and barriers to entry reduce contributions.

I second this, there's so much wasted work, and because that old contribution process there's no guarantee that even an absolutely fantastic patch, like a better man page for example. Will ever see the light of day.

I've tried in the past, it doesn't work out (not man pages, but I was fixing a bug and yeah, three, four submissions was enough for me to quit trying)

More importantly, many (most?) GNU projects don't care about man pages:

https://www.gnu.org/prep/standards/html_node/Man-Pages.html

This encapsulates one of my biggest gripes with Linux. A lack of appreciation for adequate/good documentation.

> The time you spend on the man page is time taken away from more useful work.

Making sure your users know how your program works, how to use it and what it's capable of seems incredibly important and useful to me.

If it weren't for Arch Linux's fantastic focus on documenting everything to do with Linux, I wouldn't be using Linux at all.

That page is specific to man pages, not to documentation in general.

See https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...

GNU deprecates man pages in favor of texinfo, not no documentation at all.

https://www.gnu.org/prep/standards/html_node/Documentation.h...

It's not hard, just suck it up and register for the ML, and prepare the patches. People are irrationally scared of this process. There are plentiful guides.

It's not always that it's hard, rather it can be demoralizing to have the same experience that @S-E-P did [a sibling comment to yours] where you _do_ expend the energy and then patches sit unactioned for months or years

Your patches are your responsibility. Bump them, reach out to maintainers directly, etc. Manual improvements are easy to review once you can get someone to.

Or I could just do what 99% of devs do, not give a crap and try StackOverflow/blogs to find an answer... That was my whole point, higher friction => much fewer contributions.

Higher friction => higher quality contributions.

But also fewer contributions, I reckon. If someone wants to contribute something big, they'll jump through all the hoops. But if all one wants is to contribute another example to a man page, I'd wager they're more easily discouraged by an arcane setup process. GitHub solves a lot of this friction by having:

  1. One account for manifesting your chosen identity, which you likely already have.
  2. One common way of getting the source code and sending diffs/patches (read: PRs).

The workflow is quite similar, in the abstract. But GitHub and friends solve important pain points.

1. One account for manifesting your chosen identity, which you likely already have.

You also have an email address, so. You need an email address to get a GitHub account, so technically it's harder to set up GitHub.

2. One common way of getting the source code and sending diffs/patches (read: PRs).

This is built into git. Don't need GitHub for either.

It looks like you think that older approaches to open-source collaboration (like many of the GNU projects are using) are more or less as user-friendly as GitHub. I don't have the data to prove that they aren't, just an intuition.

Perhaps the last argument I have is that I've heard a number of times about moving a project to GitHub (for example: the Go language or Vim the editor), but decidedly less often one hears of projects moving away from GitHub towards older forms (such as the wonderfully documented https://gcc.gnu.org/contribute.html). Despite the great documentation, I'm somehow not drawn to hacking on it to fix a small glitch, due to the overhead that entails. Mind, some of that overhead would be incurred just once, as it is general to the mailing list approach to collaboration. That, I believe, is another advantage of a project being on GitHub: for almost all projects there's a standard way of sending your patch: make a pull request.

About your counterpoints:

1. True. I was thinking of the bug trackers many mailing-list oriented projects have, which often require creating accounts just to file a bug. 2. I was more referring to things like (1) where to find the clone URL and (2) how to send a patch (the make a PR button is always the same).

Removing friction (even small frictions) will enable fishing for the long tail of small fixes. On the other side, I do not believe large contributions are greatly affected by the differences between these systems.

I don’t think being afraid of the process is the problem. It’s more about how unnecessarily manual the process is paired with the possibility of your patch’s email thread getting buried never to be seen again or worse, its reviewer abandoning it halfway through the review process with no easy way for someone else to pick it up.

That’s not to say that Github pull requests and the like are perfect (far from it) but it’s undeniable that they smooth the process quite considerably and make contribution far more accessible.

People are busy. If you want your patch considered, you should be bumping it and reaching out to people who can merge it. Man page improvements are generally a shoe-in, just get someone to pay attention to it for a few minutes and it'll get in.

The process you're describing in this comment is exactly the outdated approach people are saying they don't want to do.

It's not like this isn't a problem for GitHub, either. Pull requests go ignored, too.

Sounds like you want bro pages

http://bropages.org/

I don't think the use case is the same. um is for saving and viewing personal notes about usage, bropages is a common set of examples submitted by the wider community.

This other response says it better: https://news.ycombinator.com/item?id=17801788

that's what bro does by default; you only push an example to the community explicitly.

Attempting to read nix man pages, always felt like I was alone in learning best from examples. Documentation in any form without examples is always difficult for me to sort through.

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`

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.

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

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

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.

> 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!

It would come in handy in this situation: https://xkcd.com/1168/

tar actually makes sense with a little mnemonic:

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

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?

Because it comes from an era before POSIX, when tapes were prevalent and bytes were costly.

> 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 [2]: http://man.cat-v.org/unix-1st/1/tap

Wow, thanks!

And all of this because originally, the Imperial Roman had no punctuation.

The same history applies to ps [1] which was introduced in 3rd Edition Unix.

[1] http://man.cat-v.org/unix-6th/1/ps

Though from what I've seen, most people I talk to use the POSIX forms (such as 'ps -ef') and aren't aware that there is a BSD form (such as 'ps aux'). I've always used the BSD form, even though I came to Linux much much later, but I guess which form you use comes from where you learned basic *nix commands.

I guess the lack of '-' with tar is more apparent because POSIX didn't create a different syntax, and so most people omit the '-' for terseness -- while with ps it would require learning a different syntax.

> I've always used the BSD form, even though I came to Linux much much later, but I guess which form you use comes from where you learned basic *nix commands.

I too use the BSD form but came from the Linux world. Probably it is just a matter of taste (a common answer to everything!).

> I guess the lack of '-' with tar is more apparent because POSIX didn't create a different syntax, and so most people omit the '-' for terseness -- while with ps it would require learning a different syntax.

I argue the ps situation is worse than tar exactly because of that reason. There are three different classes of options in ps, often with slightly different meanings and sometimes with two different long-form options only distinguished by their cases...

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.

> 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.

Sometimes I dream of a nirvana in which:

- all unix commands support both short and long options

- option letters/names are, at least to a much greater extent than currently, common across different commands

No need for the ‘z’ :)

Yeah, tar is actually pretty simple these days. (At least GNU tar, don't know about other tars.) In 99.9% of cases you only need to know the following:

  tar caf $archive $file...      to create
  tar xf $archive                to extract

"x" will automatically recognize the compression format, and "ca" will automatically infer the desired compression format from the extension in $archive, e.g.

  tar caf backup.tar.xz /home/user

makes an xz-compressed tarball.

tar has trained us so well: "... tar is actually pretty simple these days"

I still prefer to pipe through a compression program on principle. tar has no good reason to messing around with compression, per the Unix single-function philosophy.

to people who grew up with archive programs, "making all of this into a single file" and "compressing all of this" is the same thing; requiring two commands is counterintuitive

You need it if you're processing stdin (curl ...file.tgz | tar xz)

For some reason, I think it would be more funny if the fourth frame was an exact copy of the third (with no text). I think it would be a simpler and less obvious route to the same "punchline".

Tar is one example of a command with dubious usage syntax. But how about cp?

    cp a.txt b/c/d

Will this create a new file "b/c/d/a.txt", or will it create a new file "b/c/d"? It's not clear, and depends on the circumstances (if a directory b/c/d exists). There's a flag to control the behavior, but nobody uses it often, so nobody remembers that flag. The best way to assert that "d" is a directory is by adding a trailing slash, but there's no similar way to assert that "d" should be a file. I suspect that there are many bash scripts that are essentially broken because of this problem.

Rsync has a similar problem.

For cp you can use -nv. I discovered it two days ago. It displays what will happen without doing it.

> tar -h

bomb disarmed

https://archive.org/download/pdfy-MgN0H1joIoDVoIC7/The_AWK_P...

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

A good joke consists of an introduction, which establishes the story to be told and gracefully segues into the punchline. Your post here demostrate that very well sir.

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.

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

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.

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 :)

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?

Use zsh.

https://askubuntu.com/questions/23630/how-do-you-share-histo...

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

    shopt -s histappend

In your .bashrc. Note that history is only saved when the shell exits, so new shells will only see history from other shells that have already exited.

“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.

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

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

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.

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').

Further, why not just use vim templates as the way to create the base man boilerplate and just customize. So issue 'vi mygrep.man' and quickly edit.

"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.)

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

I too choose what software to use based strictly on the language in which it's written.

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

: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.

While not exactly same. But I find https://github.com/chubin/cheat.sh very useful for finding usage.

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

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

> `um git`

This needs integration with voice assistants.

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.

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.

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.

It doesn't.

um is a great name for this tool

What’s the meaning of such name?

It's a thing you say when you don't know what you are doing or can't remember a thing.

just a guess, but "unofficial manpage"

This isn't a bad guess! I don't know why it was downvoted.

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

“um” is an expression of confusion or a space filler in conversation like “uh”.

“Um, how do I use this tool again?”

one in portuguese

Some similarly helpful projects:

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

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

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

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

Bravo! And this should help as well:

http://heirloom.sourceforge.net/doctools/troff.pdf

https://www.oreilly.com/openbook/utp/

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

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?

See thaumaturgy's comment.

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.

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.

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.

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

My personal solution to this problem: https://github.com/alanbernstein/quickref

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.

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.

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.

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.

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?)

You could put your pages on cloud storage?

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

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

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

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.

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

I use nvalt for this.

Started using it already! I love it :)

There are couple alternatives like http://bropages.org/ and https://tldr.sh/ How UM is different?

I love tldr for similar-ish problem. https://tldr.sh/

prettyy sure https://tldr.sh/ is enough.

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

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.

Man pages have a certain style, reading them is a skill and takes practice. I'd encourage you to embrace them but like all skills, it takes practice!

What acronym?

RTFM (probably)

Reply on news.ycombinator.com