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.
> 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!
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.
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`)
> 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.
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.)
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).
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.
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.
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.
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.
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!
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.
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)
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.
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.
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.
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.
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.
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!
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.
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?
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.
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.
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...
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.
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
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".
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.
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?
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.
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.
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 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
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.)