|
|||||||||||
![]() |
To help you somewhat in this daunting task, I've created this "instructions
guide". It describes the necessary steps to roll your own man pages with
ease. In addition it shows some nice macros to make life more easy.
You need the nroff/troff formatting package either from your hardware's vendor or from the GNU foundation. GNU's troff variant is called gtroff and comes together with a front-end to gtroff and other preprocessors like gtbl (for setting tables). In the following I'll refer to groff only but using nroff or troff instead should be straightforward. The man command often uses preformatted man pages as created by troff/groff. Depending on your platform's configuration man can also display unformatted (raw) man pages by processing them first with troff/groff. The raw man page is simply a plain ASCII file with interspearsed commands for the formatting package. Thus you can use whatever editor you want to create the source file from which groff creates the man page - even vi (although emacs is even more cryptic). With groff, to ease writing you can define new macros. In fact, the whole process relies heavily on macro packages which already come with troff/groff. You can specify the necessary macro package(s) when invoking groff. Such packages are then read in by troff before processing of your man page file begins. Running groff is a simple task: $ groff -t -man -Tascii MyFile > MyManPageMyFile is the name of the file containing the raw man page. MyManPage is a name suitable to be used with man on your platform. On some platforms you have to run pack or gzip on the resulting man page file. With some systems you have to add the section number to MyManPage. The option -t first runs gtbl, a preprocessor for setting tables. With man pages, you will often need to do this. The next option -man load the appropiate macro package for authoring man pages. And finaly -Tascii prepares output for use with man. But now some examples to clearify this. In every case I assume that you have your own private man page directories. If not, you can easily create them. The following shell commands (assuming the bourne shell) will do the job (for preformatted man pages): $ cd $ mkdir man $ mkdir man/cat3 $ MANPATH=`pwd`/man:$MANPATH $ export MANPATHBut now the examples:
$ groff -t -man -Tascii XmComboBox.groff > XmComboBox $ pack -f XmComboBox $ cp XmComboBox.z ~/man/cat3/XmComboBox.z $ groff -t -man -Tascii XmComboBox.groff > XmComboBox.3X $ gzip -f XmComboBox.3X $ cp XmComboBox.3X.gz ~/man/cat3/XmComboBox.3X.gz
The first macro command I'll introduce is called .TH. With groff documents a macro's name must always be given on the first column of a line. If you put by error a space in the first column, groff will not notice the command and put the command's name verbatim into the resulting man page. The .TH macro expects up to five parameters: .TH name chapter comment left center
.TH XmComboBox 3Xm "19 October 1994" "Version 1.30" \ "Harry's Motif Tools"
When browsing through the man pages you may have already noticed different section names like SYNOPSIS, DESCRIPTION, and SEE ALSO. The section names are printed to the left of the page whereas the text following the section's title is indented to the right. To create a section title, use the .SH macro. The text following .SH on the same line will be printed in another type face (often bold on ttys). Other text from the next line on gets indented to the right and is typed with a Roman font. The first section has always to be entitled NAME. The text following in this section should only span across a single line and contain no text manipulation like changing the font. This is for the permuted index generator (for use with apropos) who gets confused if there is anything in the line other than plain text. .SH NAME bogous \- a special compiler for use with bogous source filesNote the "\-" in this example. groff regards a simple "-" as a hyphen. But we actually want an en-dash here, that's why you have to use "\-" instead of "-". It's completely up to you how to name the remaining sections. If you need more examples, I advise you to look at all the man pages comming with your U**X operating system. The sceletton of a man page would look like this: .\" This is a comment line. .TH Bogous 42X "1 Apr 2001" "V0.99zeta" "Bogous Software Group" .SH NAME bogous \- a special compiler for use with bogous source files .SH SYNOPSIS Some text... .SH DESCRIPTION At least a rough description... .SH BUGS To numerous to count...
There are several predefined ways to lay out text in paragraphs. Most common you'll use either the .LP or .PP command. These commands simply achive the same result: they begin a fresh paragraph and indent it 0.5 inch to the right (measured relative to the page's left border). The same indent is set automatically by the .SH command for the first paragraph following a section. Neither .LP nor .PP takes any parameter, thus you have to type the text of the following paragraph starting with a fresh line. .SH DESCRIPTION This is the first paragraph of the description. It spans over several lines and just takes up space. It simply makes no sense. .LP This is the second paragraph.results in:
This is the second paragraph. .SH DESCRIPTION My first paragraph (indent = 0.5 inch). .RS This is the second paragraph (indented 1 inch to the right). .RE Third paragraph.
Using plain ASCII isn't always just enough. In your man page you surely need to emphasize some words or sentences. The man page macro package provides for this:
.I This text is printed with a .B bold font . Now this is printed using a normal font.produces:
This text is printed with a .BR "bold font" . Now this is printed using a normal font..BR means: "first print bold text, then switch back to the roman font." This macro accepts up to six arguments, printing the first one with a bold font, the second one using a roman font, then printing bold text again, and so on. Remember to enclose text in quotation marks if it contains spaces. Notice the point beeing the second argument to .BR, thus seperated by an space from the text "bold font". Other combinations are also possible:
Thanks to this "turbo introduction" to groff, you should now be able to write your own man pages ;-). But life can be so much easier using macros for the every day's work.
In addition, macros help to keep a certain style throughout your document
or a set of documents.
![]() Contents: Harald Albrecht (albrecht@igpm.rwth-aachen.de) Layout: Harald Albrecht Last Change: 97/08/10 (ab) |