Writing Man Pages for the Command Line – Part 2

MAN PAGES

Man is a command line tool that delivers a manual page for whatever command line executable you type in the next argument.

man <command>

That’s not all they provide manuals for. There are also man pages for programming libraries, configuration files (file formats), system calls, games, and miscellaneous items. Man pages are broken down into eight categories:

1 general commands
2 system calls
3 library functions
4 devices and drivers
5 file formats, like configuration files
6 games and screensavers
7 miscellaneous
8 sysadmin commands and daemons

Do me a favor and read that last word at the end of 8. Daemons. Huh. How do you suppose that’s pronounced (and just what is a daemon, anyway)? Let me tell you, padawan. The word “daemon” is pronounced exactly like the word “demon.” Some people pronounce it as “day-mun.” They are wrong. But don’t try to correct them, as they will tell you that it doesn’t matter, but they are lying because if they really thought it didn’t matter, they’d just pronounce it correctly when corrected and be done with it. Alas, they only grow more stubborn about pronouncing it “day-mun.” “The fuck?” you ask. Well, it’s because they are contrarians who revel in sticking it to the prescriptivist authoritarians that live in their heads. That, or they come from religious families and are afraid of the notion that there might be demons possessing their computers, and emphasizing the ‘a’ gives them a (false) sense of security (because they most certainly do get possessed by chieftains of The Dark Lord).

3676953

But that is neither here nor there.

So, typing anything into a Terminal Window only works if the commands you type…

1) are built-in to the shell you’re using (there are several shells out there, Macs and most Linux distributions come with BASH as the default shell)

cd

2) are available at the root of a directory that’s in the “search path.”

cp

3) are in the form of the absolute or relative path to an executable.

/usr/libexec/airportd

Let’s look at number 2 above. A search path is a list of directories, or folders, inside of which your shell has been configured to look for whatever it is you’re typing. Typically, this is at least /bin, /sbin, /usr/bin and /usr/sbin.

Go into one of those folders and list it’s contents.

cd /bin
ls -l

You’ll see thirty-something executables. If you know anything about getting around, you’ll recognize many of them. The basic commands are here, like mv, cp, date, df, echo, hostname, etc. Well, when you open Terminal and type “mv ~/Desktop/Porn ~/.Trash/.” (again, hopefully for the last time this time), the shell knows what you want it to do because mv is in /bin, which is in the list of directories specified by the search path.

That list can be expanded upon by authoring your own simple text file with a return-delimited list of paths, dropping it into the folder at /etc/paths.d/, and giving it the correct permissions. Mac OS X has some behind-the-scenes processes that load the specified directory paths from your file into the PATH variable of your shell environment when you open a new window in Terminal.

Alright. You’re thinking, “Hey, Matthew. What does this have to do with man pages?” Well, man pages are files that, like executables, live in a path at a couple of different locations. When you type “man,” the next argument you give your command will be searched for in several different directories.

Now, finding what directories these are can be a bit more complicated than how we found the directories assigned to the PATH environmental variable in your Terminal’s shell. There is a MANPATH environmental variable that you can specify, but it isn’t set by default. There’s a file at /private/etc/man.conf that allows you to configure man for where it will search, and there’s also a file at /private/etc/manpaths containing a carriage return delimited list of directories to search for man pages and a folder at /private/etc/manpaths.d/ where you can drop files set up in the same format as the aforementioned. Just like /private/etc/man.d/. There’s more on how man hunts down it’s man page directories on your computer. Just type the following command:

man man

And look for the section titled, “SEARCH PATH FOR MANUAL PAGES.”

One more thing about these directories. They are filled with one more level of directories before we see the man page files. These are to help organize the man pages into their proper category. Do this to find your list of paths for man:

manpath

You’ll get a list, just like the one you saw with echo $PATH. Go into one of those directories. Let’s do this one:

cd /usr/share/man

And now list the contents:

ls -l

What do we see?

drwxr-xr-x   1632 root  wheel   55488    Jul 12 16:22  man1
drwxr-xr-x      3 root  wheel     102    Oct 23  2013  man3
drwxr-xr-x     39 root  wheel    1326    Oct 23  2013  man4
drwxr-xr-x    199 root  wheel    6766    May 24 19:47  man5
drwxr-xr-x      3 root  wheel     102    Aug 24  2013  man6
drwxr-xr-x     51 root  wheel    1734    Oct 23  2013  man7
drwxr-xr-x    481 root  wheel   16354    May 24 19:47  man8
drwxr-xr-x     23 root  wheel     782    Sep 20  2013  man9
drwxr-xr-x    680 root  wheel   23120    Oct 23  2013  mann
-rw-r--r--      1 root  wheel  149346    Jul 27 23:24  whatis

We have man folders with numbers on their ends! What are those numbers for? Well, for man page authors to dump their man pages, of course. And according to what key? The above list from 1 to 8 (from general commands to sysadmin and daemon commands)! But what is this folder, “mann?” It’s for client libraries or something like that. Whatever. Lots of files in that folder. What is the “whatis” file (this question makes me laugh)? It’s a database created by your periodic daily scripts. It’s there to help the whatis executable find results relevant to your search.

Go into the man1 directory. Every file in there is a man page, but they all end with a “.1,” as the man page files in the man8 directory all end with a “.8,” etc. Each type of man file ends with an extension of “1-8” or “n.” And then we drop it into the appropriate directory, based on that extension.

So, let’s say you make a shell script that anyone can use. It’s a general tool. Maybe it asks you what your first pet’s name was and then what the name of the street you grew up on was. Hit return and it spits out, “Your porn star name is Chris Crocus.” No sysadmin privileges are required there. Let’s call it, “urpornstarname.” You made a man page for it called “urpornstarname.1.” Where to put it?

If you answered /usr/local/man/man1/urpornstarname.1, you’re thinking right. But you could make things really organized and slick. Since we’re professionals, let’s do it that way!

To be continued…

Leave a Comment

Your email address will not be published. Required fields are marked *