Hack38.Usable Documentation for the Inherently Lazy

Hack 38. Usable Documentation for the Inherently Lazy

Web-based documentation is great, but it's not very accessible from the command line. However, manpages can be with you always.

I know very few administrators who are big fans of creating and maintaining documentation. It's just not fun. Not only that, but there's nothing heroic about doing it. Fellow administrators aren't going to pat you on the back and congratulate you on your wicked cool documentation. What's more, it's tough to see how end users get any benefit when you document stuff that's used only by administrators, and if you're an administrator writing documentation, it's likely that everyone in your group already knows the stuff you're documenting!

Well, this is one way to look at it. However, the fact is that turnover exists, and so does growth. It's possible that new admins will come on board due to growth or turnover in your group, and they'll have to be taught about all of the customized tools, scripts, processes, procedures, and hacks that are specific to your site. This learning process is also a part of any new admin's enculturation into the group, and it should be made as easy as possible for everyone's benefit, including your own.

In my travels, I've found that the last thing system administrators want to do is write documentation. The only thing that might fall below writing documentation on their lists of things they're dying to do is writing web-based documentation. I've tried to introduce in-browser WYSIWYG HTML editors, but they won't have it. Unix administrators are quite happy using Unix tools to do their work. "Give me Vim or give me death!"

Another thing administrators typically don't want to do is learn how to use tools like LaTeX, SGML, or groff to create formal documentation. They're happiest with plain text that is easily typed and easily understood by anyone who comes across the raw file. Well, I've found a tool that enables administrators to create manpages from simple text files, and it's cool. It's called txt2man.

Of course, it comes with a manpage, which is more than enough documentation to use the tool effectively. It's a simple shell script that you pass your text file to, along with any options you want to pass for a more polished end result, and it spits out a perfectly usable manpage. Here's how it works.

I have a script called cleangroup that I wrote to help clean up after people who have departed from our department (see "Clean Up NIS After Users Depart" [Hack #77]). It goes through our NIS map and gets rid of any references made to users who no longer exist in the NIS password map. It's a useful script, but because I created it myself there's really no reason that our two new full-time administrators would know it exists or what it does. So I created a new manpage directory, and I started working on my manpages for all the tools written locally that new admins would need to know about. Here is the actual text I typed to create the manpage:

 NAME   cleangroup - remove users from any groups if the account doesn't exist SYNOPSIS   /usr/local/adm/bin/cleangroup groupfile DESCRIPTION   cleangroup is a perl script used to check each uid found in the group file   against the YP password map. If the user doesn't exist there, the user is   removed from the group.   The only argument to the file is groupfile, which is required. ENVIRONMENT LOGNAME You need to be root on the YP master to run this script successfully. BUGS   Yes. Most certainly. AUTHOR   Brian Jones [e-mail] 

The headings in all caps will be familiar to anyone who has read his fair share of manpages. I saved this file as cleangroup.txt. Next, I ran the following command to create a manpage called cleangroup.man:

 $ txt2man -t cleangroup -s 8 cleangroup.txt > cleangroup.man 

When you open this manpage using the man command, the upper-left and right corners will display the title and section specified on the command line with the -t and -s flags, respectively. Here's the finished output:

 cleangroup(8) cleangroup(8) NAME cleangroup-remove users from any groups if the account doesn't exist SYNOPSIS /var/local/adm/bin/beta/cleangroup groupfile DESCRIPTION cleangroup is a perl script used to check each uid found in the group file against the YP password map. If the user doesn't exist there, the user is removed from the group. The only argument to the file is groupfile, which is required. ENVIRONMENT LOGNAME  You need to be root on nexus to run this script successfully. BUGS Yes. Most certainly. AUTHOR Brian Jones [e-mail] 

For anyone not enlightened as to why I chose section 8 of the manpages, you should know that the manpage sections are not completely arbitrary. Different man sections are for different classes of commands. Here's a quick overview of the section breakdown:

Table 4-1.

1	User-level commands such as ls and man
2	System calls such as gethostname and setgid
3	Library calls such as isupper and getchar
4	Special files such as fd and fifo
5	Configuration files such as ldap.conf and nsswitch.conf
6	Games and demonstrations
7	Miscellaneous
8	Commands normally run by the root user, such as MAKEDEV and pvscan

Some systems have a section 9 for kernel documentation. If you're planning on making your own manpage section, try to pick an existing one that isn't being used, or just work your manpages into one of the existing sections. Currently, man only traverses manX directories (where X is a single digit), so man42 is not a valid manpage section.

Though the resulting manpage isn't much different from the text file, it has the advantage that you can actually use a standard utility to read it, and everyone will know what you mean when you say "check out man 8 cleangroup." That's a whole lot easier than saying "go to our intranet, click on Documentation, go to Systems, then Linux/Unix, then User Accounts, and click to open the PDF."

If you think that txt2man can handle only the simplest of manpages, it has a handy built-in help that you can send to itself; the resulting manpage is a pretty good sample of what txt2man can do with just simple text. Run this command (straight from the txt2man manpage) to check it out:

 $ txt2man -h 2>&1 | txt2man -T 

This sends the help output for the command back to txt2man, and the -T flag will preview the output for you using more or whatever you've set your PAGER environment variable to. This flag is also a quick way to preview manpages you're working on to make sure all of your formatting is correct instead of having to create a manpage, open it up, realize it's hosed in some way, close it, and open it up again in your editor. Give it a try!