Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Gems from the man page trenches (2016)

saminiir.com

Post reply on HN
Print view View original

1–10 of 28 posts

Re: Gems from the man page trenches (2016)

#3

Post by mixedmath »

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.

Re: Gems from the man page trenches (2016)

#4

Post by somat »

My favorite man page is 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.

Re: Gems from the man page trenches (2016)

#5

Post by [deleted] »

mixedmath wrote: post #3

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 m…

[deleted]

Re: Gems from the man page trenches (2016)

#7

Post by smcameron »

somat wrote: post #4

My favorite man page is 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.

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.

Re: Gems from the man page trenches (2016)

#9

Post by yuubi »

smcameron wrote: post #7
somat wrote: post #4

My favorite man page is 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.

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 o…

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)
Post reply on HN