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:
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.
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.
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"; }
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.
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.
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.
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.)
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.
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.
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.
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.
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!
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,
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.
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.
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?
“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.
: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.
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.
[+] [-] pjungwir|7 years ago|reply
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:
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.)
[+] [-] teddyh|7 years ago|reply
[+] [-] romwell|7 years ago|reply
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!"
[+] [-] toyg|7 years ago|reply
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
[+] [-] susam|7 years ago|reply
[+] [-] westurner|7 years ago|reply
sphinx.builders.manpage: http://www.sphinx-doc.org/en/master/_modules/sphinx/builders...
[+] [-] themodelplumber|7 years ago|reply
[+] [-] gunnihinn|7 years ago|reply
[+] [-] v01d4lph4|7 years ago|reply
[+] [-] dvh|7 years ago|reply
[+] [-] sjmulder|7 years ago|reply
[+] [-] Annatar|7 years ago|reply
[+] [-] philbarr|7 years ago|reply
Those who can't, teach
Those who can't teach, write
Those who can't write, write man pages
[+] [-] dijit|7 years ago|reply
What happened to ‘info’ pages. I hated it, but wasn’t that supposed to address these kinds of issues with examples?
[+] [-] ptman|7 years ago|reply
See e.g. https://metacpan.org/pod/release/PHRED/Archive-Zip-1.62/lib/...
[+] [-] swebs|7 years ago|reply
http://bropages.org/
[+] [-] ddevault|7 years ago|reply
[+] [-] overcast|7 years ago|reply
[+] [-] zuppy|7 years ago|reply
[+] [-] thaumaturgy|7 years ago|reply
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.
[+] [-] x0|7 years ago|reply
[+] [-] hx2a|7 years ago|reply
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!
[+] [-] dataflow|7 years ago|reply
[+] [-] Annatar|7 years ago|reply
[+] [-] Sreyanth|7 years ago|reply
Right now, I usually grep the man pages to search for things relevant to specific context. Something like,
Worked well in most cases. So, for figuring out how to send a POST request, I would try If that bombs, I would then immediately try 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,[+] [-] seealso|7 years ago|reply
[+] [-] banku_brougham|7 years ago|reply
[+] [-] nazri1|7 years ago|reply
[+] [-] tigrezno|7 years ago|reply
- 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|7 years ago|reply
[+] [-] zach43|7 years ago|reply
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?
[+] [-] Annatar|7 years ago|reply
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|7 years ago|reply
[+] [-] movedx|7 years ago|reply
(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|7 years ago|reply
[+] [-] pc86|7 years ago|reply
[+] [-] kichuku|7 years ago|reply
[+] [-] arendtio|7 years ago|reply
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|7 years ago|reply
[+] [-] statictype|7 years ago|reply
I can see myself running `um git` literally before every invocation.
[+] [-] majewsky|7 years ago|reply
This needs integration with voice assistants.
[+] [-] ams6110|7 years ago|reply
[+] [-] wruza|7 years ago|reply
^ 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|7 years ago|reply
[+] [-] jamesrom|7 years ago|reply
[+] [-] rodorgas|7 years ago|reply
[+] [-] guu|7 years ago|reply
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