Writing man Pages Using groff
In order to format this man page and view it on your screen, you can use the command:
$ groff -Tascii -man coffee.man | more
The -Tascii option tells groff to produce plain-ASCII output; -man tells groff to use the man page macro set. If all goes well, the man page should be displayed as shown in Figure 1.
COFFEE(1) COFFEE(1) NAME coffee - Control remote coffee machine SYNOPSIS coffee [ -h | -b ] [ -t type ] amount DESCRIPTION coffee queues a request to the remote coffee machine at the device /dev/cf0. The required amount argument speci- fies the number of cups, generally between 0 and 12 on ISO standard coffee machines. Options -h Brew hot coffee. Cold is the default. -b Burn coffee. Especially useful when executing cof- fee on behalf of your boss. -t type Specify the type of coffee to brew, where type is one of columbian, regular, or decaf. FILES /dev/cf0 The remote coffee machine device SEE ALSO milk(5), sugar(5) BUGS May require human intervention if coffee supply is exhausted.
Figure 1. Formatted man Page
As mentioned before, groff is capable of producing other types of output. Using the -Tps option in place of -Tascii will produce PostScript output that you can save to a file, view with GhostView, or print on a PostScript printer. -Tdvi will produce device-independent .dvi output similar to that produced by TeX.
If you wish to make the man page available for others to view on your system, you need to install the groff source in a directory that is present in other users' MANPATH. The location for standard man pages is /usr/man. The source for section 1 man pages should therefore go in /usr/man/man1. Therefore, the command:
$ cp coffee.man /usr/man/man1/coffee.1
will install this man page in /usr/man for all to use (note the use of the .1 file name extension, instead of .man). When man coffee is subsequently invoked, the man page will be automatically reformatted, and the viewable text saved in /usr/man/cat1/coffee.1.Z.
If you can't copy man page sources directly to /usr/man (say, because you're not the system administrator), you can create your own man page directory tree and add it to your MANPATH. The MANPATH environment variable is of the same format as PATH; for example, to add the directory /home/mdw/man to MANPATH just use:
$ export MANPATH=/home/mdw/man:$MANPATH
There are many other options and formatting commands available for groff and the man page macros. The best way to find out about these is to look at the files in /usr/lib/groff; the tmac directory contains the macro files themselves, which often contain some documentation on the commands they provide. To use a particular macro set with groff, just use the -mmacro option. For example, to use the mgs macros, use:
groff -Tascii -mgs files...
The man pages for groff describe this option in more detail.
Unfortunately, the macro sets provided with groff are not well-documented. There are section 7 man pages for some of them; for example, man 7 groff_mm will tell you about the mm macro set. However, this documentation usually only covers the differences and new features in the groff implementation, which assumes you have access to the man pages for the original nroff/troff macro sets (known as DWB—the Documentor's Work Bench). The best source of information may be a book on using nroff/troff which covers these classic macro sets in detail. For more about writing man pages, you can always look at the man page sources (in /usr/man) and determine what they do by comparing the formatted output with the source.
This article is adapted from Running Linux, by Matt Welsh and Lar Kaufman, published by O'Reilly and Associates (ISBN 1-56592-100-3). Among other things, this book includes tutorials of various text-formatting systems used under Linux. Information in this issue of Linux Journal as well as Running Linux should provide a good head-start on using the many text tools available for the system.
Good luck, and happy documenting!
Matt Welsh (firstname.lastname@example.org) is a student and systems programmer at Cornell University, working with the Robotics and Vision Laboratory on projects dealing with real-time machine vision.
Practical Task Scheduling Deployment
July 20, 2016 12:00 pm CDT
One of the best things about the UNIX environment (aside from being stable and efficient) is the vast array of software tools available to help you do your job. Traditionally, a UNIX tool does only one thing, but does that one thing very well. For example, grep is very easy to use and can search vast amounts of data quickly. The find tool can find a particular file or files based on all kinds of criteria. It's pretty easy to string these tools together to build even more powerful tools, such as a tool that finds all of the .log files in the /home directory and searches each one for a particular entry. This erector-set mentality allows UNIX system administrators to seem to always have the right tool for the job.
Cron traditionally has been considered another such a tool for job scheduling, but is it enough? This webinar considers that very question. The first part builds on a previous Geek Guide, Beyond Cron, and briefly describes how to know when it might be time to consider upgrading your job scheduling infrastructure. The second part presents an actual planning and implementation framework.
Join Linux Journal's Mike Diehl and Pat Cameron of Help Systems.
Free to Linux Journal readers.Register Now!
- SUSE LLC's SUSE Manager
- Murat Yener and Onur Dundar's Expert Android Studio (Wrox)
- My +1 Sword of Productivity
- Managing Linux Using Puppet
- Non-Linux FOSS: Caffeine!
- Doing for User Space What We Did for Kernel Space
- SuperTuxKart 0.9.2 Released
- Google's SwiftShader Released
- Parsing an RSS News Feed with a Bash Script
- Rogue Wave Software's Zend Server
With all the industry talk about the benefits of Linux on Power and all the performance advantages offered by its open architecture, you may be considering a move in that direction. If you are thinking about analytics, big data and cloud computing, you would be right to evaluate Power. The idea of using commodity x86 hardware and replacing it every three years is an outdated cost model. It doesn’t consider the total cost of ownership, and it doesn’t consider the advantage of real processing power, high-availability and multithreading like a demon.
This ebook takes a look at some of the practical applications of the Linux on Power platform and ways you might bring all the performance power of this open architecture to bear for your organization. There are no smoke and mirrors here—just hard, cold, empirical evidence provided by independent sources. I also consider some innovative ways Linux on Power will be used in the future.Get the Guide