43 ms·

Gems from the man page trenches (2016)

62 points by LEARAX 4y ago

smcameron 4y ago
If you create and distribute an executable for linux/unix, and you don't create a man page for it, you are committing a crime against humanity.
- enriquto 4y ago
  > If you create and distribute an executable for linux/unix, and you don't create a man page for it, you are committing a crime against humanity. I agree. And it's so easy to do! As long as your program has a --help option, creating the manpage simply amounts to calling help2man. Just add this to your makefile: foo.1 : foo ; help2man -N foo > foo.1
- runlevel1 4y ago
  And pandoc makes it easy: https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-in-markdown-with-pandoc/ https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-i...
  - eichin 4y ago
    Huh, I wonder how close that is to what `ronn` does (also markdown to man, via a couple of paths, written in ruby.)
deleted 4y ago
[deleted]
mixedmath 4y ago
I love man pages. But it took me many years before I realized how easy it is to write man pages for tools that I write (and further, I write in markdown and pandoc happily translates them to troff for me). A few years ago I learned that one can also add a new section to man. I've added the `eg` section, which I fill with examples that I think will be useful to future me. For example, typing `man eg awk` opens up my man page of examples for awk, which is more pointed.
- deleted 4y ago
  [deleted]
somat 4y ago
My favorite man page is scan_ffs. http://man.openbsd.org/scan_ffs http://man.openbsd.org/scan_ffs The basic operation of this program is as follows: 1. Panic. You usually do so anyways, so you might as well get it over with. Just don't do anything stupid. Panic away from your machine. Then relax, and see if the steps below won't help you out.
- smcameron 4y ago
  Ha. I wasn't familiar with scan_ffs, so I googled it. Given what it does, or purports to do, yeah, a first step of "Panic" makes total sense. Reminds me of something which happened early in my career. An older, wiser coworker came by and said, "You won't believe what I almost did. I was installing a new disk on cyclops (our main NFS server), and I almost typed 'newfs /dev/sda' instead of 'newfs /dev/sdb'" (this was on SunOS 4, iirc). Then he went back to his office, hit return a couple times and... he had left "newfs /dev/sda_" sitting there on the command line. Panic ensued. We recovered from backup tapes.
  - yuubi 4y ago
    sunos4 disk devices were named like xy0a or xd2h or sd1b. the first 2 letters were the controller (xy/xd were different types of xylogics smd controllers, sd scsi), the number was the unit number, and the letter was the partition, with some fairly strong conventions (a=root, b=swap, c=whole disk, d..h=other)
  - sen_armstrong 4y ago
    > so I googled it uh... the man page? XD
  - teddyh 4y ago
    For those who are wondering: The Linux equivalent is “findsuper”, which is from the e2fsprogs package, but the “findsuper” command is not normally built and installed, so when you need it, you will have to download the e2fsprogs source and compile findsuper yourself. An unnecessary pain at the worst possible time, sadly.
mturmon 4y ago
The best pages are terse. My favorite snippet: Sharp and newline surround comments. I think from a old awk man page?
- enriquto 4y ago
  It seems to be from make(1) : http://man.cat-v.org/unix_7th/1/make http://man.cat-v.org/unix_7th/1/make
  - mturmon 4y ago
    Thank you!
danrl 4y ago
My fav: "You can tune a filesystem, but you can't tune a fish." --tunefs(8), 4.2BSD and later
- Sprocklem 4y ago
  I appreciate that this is listed as a bug.
thepostman0 4y ago
man has an Easter egg for anyone interested: https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=84bde8d8a9a357bd372793d25746ac6b49480525 https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=84bd...
- ollybee 4y ago
  Not any longer https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=b225d9e76fbb0a6a4539c0992fba88c83f0bd37e https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=b225...
yaccz 4y ago
POSIX_ME_HARDER
nagonago 4y ago
> They are almost without exception well-written and concise, and the intuition you gain for particular topics as you browse through the man pages is well worth the effort. In contrast, many developers shoot straight to googling the answer for the problem at hand. Maybe worth the effort if you want to learn about a program in detail, but in practice I often give up reading the manual and use google instead because I just want to know/remind myself the most common use cases. To be fair, there are some man pages that have a great USAGE or EXAMPLES section which meet this purpose.
euroderf 4y ago
Didn't GNU man pages use to have a lot more examples in the 90s ? At some point (IIRC) examples were purged. A great disservice.
- codeflo 4y ago
  Was there a rationale?
  - enriquto 4y ago
    "The GNU folks, in general, abhor man pages, and create info documents instead."
- Y_Y 4y ago
  I don't remember what exactly happened, but a lot of manpages moved over to `info` and `man` would just complain and send you there. These days I use `tldr` (via `tealdeer`) and that usually spits out a few nice example commands.
hyperman1 4y ago
I remember some old man page (su? sudo?) complaining quite bitterly about the wheel group not sharing its power or something, but can't seem to remember it.
crawl_soever 4y ago
My favorite is entering "extreme bounce zone"Just take a look at the stupid tricks sampler at the end of GNU man!

62 points by LEARAX 4y ago

If you create and distribute an executable for linux/unix, and you don't create a man page for it, you are committing a crime against humanity.

enriquto 4y ago
> If you create and distribute an executable for linux/unix, and you don't create a man page for it, you are committing a crime against humanity. I agree. And it's so easy to do! As long as your program has a --help option, creating the manpage simply amounts to calling help2man. Just add this to your makefile: foo.1 : foo ; help2man -N foo > foo.1
runlevel1 4y ago
And pandoc makes it easy: https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-in-markdown-with-pandoc/ https://eddieantonio.ca/blog/2015/12/18/authoring-manpages-i...
- eichin 4y ago
  Huh, I wonder how close that is to what `ronn` does (also markdown to man, via a couple of paths, written in ruby.)

deleted 4y ago

[deleted]

mixedmath 4y ago

I love man pages. But it took me many years before I realized how easy it is to write man pages for tools that I write (and further, I write in markdown and pandoc happily translates them to troff for me). A few years ago I learned that one can also add a new section to man. I've added the `eg` section, which I fill with examples that I think will be useful to future me. For example, typing `man eg awk` opens up my man page of examples for awk, which is more pointed.

deleted 4y ago
[deleted]

somat 4y ago

My favorite man page is scan_ffs. http://man.openbsd.org/scan_ffs http://man.openbsd.org/scan_ffs The basic operation of this program is as follows: 1. Panic. You usually do so anyways, so you might as well get it over with. Just don't do anything stupid. Panic away from your machine. Then relax, and see if the steps below won't help you out.

smcameron 4y ago
Ha. I wasn't familiar with scan_ffs, so I googled it. Given what it does, or purports to do, yeah, a first step of "Panic" makes total sense. Reminds me of something which happened early in my career. An older, wiser coworker came by and said, "You won't believe what I almost did. I was installing a new disk on cyclops (our main NFS server), and I almost typed 'newfs /dev/sda' instead of 'newfs /dev/sdb'" (this was on SunOS 4, iirc). Then he went back to his office, hit return a couple times and... he had left "newfs /dev/sda_" sitting there on the command line. Panic ensued. We recovered from backup tapes.
- yuubi 4y ago
  sunos4 disk devices were named like xy0a or xd2h or sd1b. the first 2 letters were the controller (xy/xd were different types of xylogics smd controllers, sd scsi), the number was the unit number, and the letter was the partition, with some fairly strong conventions (a=root, b=swap, c=whole disk, d..h=other)
- sen_armstrong 4y ago
  > so I googled it uh... the man page? XD
- teddyh 4y ago
  For those who are wondering: The Linux equivalent is “findsuper”, which is from the e2fsprogs package, but the “findsuper” command is not normally built and installed, so when you need it, you will have to download the e2fsprogs source and compile findsuper yourself. An unnecessary pain at the worst possible time, sadly.

mturmon 4y ago

The best pages are terse. My favorite snippet: Sharp and newline surround comments. I think from a old awk man page?

enriquto 4y ago
It seems to be from make(1) : http://man.cat-v.org/unix_7th/1/make http://man.cat-v.org/unix_7th/1/make
- mturmon 4y ago
  Thank you!

danrl 4y ago

My fav: "You can tune a filesystem, but you can't tune a fish." --tunefs(8), 4.2BSD and later

Sprocklem 4y ago
I appreciate that this is listed as a bug.

thepostman0 4y ago

man has an Easter egg for anyone interested: https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=84bde8d8a9a357bd372793d25746ac6b49480525 https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=84bd...

ollybee 4y ago
Not any longer https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=b225d9e76fbb0a6a4539c0992fba88c83f0bd37e https://git.savannah.gnu.org/cgit/man-db.git/commit/?id=b225...

yaccz 4y ago

POSIX_ME_HARDER

nagonago 4y ago

> They are almost without exception well-written and concise, and the intuition you gain for particular topics as you browse through the man pages is well worth the effort. In contrast, many developers shoot straight to googling the answer for the problem at hand. Maybe worth the effort if you want to learn about a program in detail, but in practice I often give up reading the manual and use google instead because I just want to know/remind myself the most common use cases. To be fair, there are some man pages that have a great USAGE or EXAMPLES section which meet this purpose.

euroderf 4y ago

Didn't GNU man pages use to have a lot more examples in the 90s ? At some point (IIRC) examples were purged. A great disservice.

codeflo 4y ago
Was there a rationale?
- enriquto 4y ago
  "The GNU folks, in general, abhor man pages, and create info documents instead."
Y_Y 4y ago
I don't remember what exactly happened, but a lot of manpages moved over to `info` and `man` would just complain and send you there. These days I use `tldr` (via `tealdeer`) and that usually spits out a few nice example commands.

hyperman1 4y ago

I remember some old man page (su? sudo?) complaining quite bitterly about the wheel group not sharing its power or something, but can't seem to remember it.

crawl_soever 4y ago

My favorite is entering "extreme bounce zone"Just take a look at the stupid tricks sampler at the end of GNU man!