Writing GNUstep man-pages with groff

This tries to be the documentation on how to write man-pages for the GNUstep project. If you adhere to this standard all GNUstep related man-pages will have an identical structure, which makes them easier to read.

If you installed GNUstep in the default /usr/GNUstep directory you should add to /etc/manpath.config the following entries: 

MANDATORY_MANPATH           /usr/GNUstep/System/Library/Documentation/man
MANDATORY_MANPATH           /usr/GNUstep/Local/Library/Documentation/man

MANPATH_MAP  /usr/GNUstep/System/Tools  /usr/GNUstep/System/Library/Documentation/man
MANPATH_MAP  /usr/GNUstep/Local/Tools  /usr/GNUstep/Local/Library/Documentation/man

MANDB_MAP       /usr/GNUstep/System/Library/Documentation/man   /var/cache/man
MANDB_MAP       /usr/GNUstep/Local/Library/Documentation/man   /var/cache/man

Then you have to rebuild the mandb with: 

/usr/bin/mandb --no-purge

Testing your man-pages

To make sure the man-pages can be used on as much platforms as possible, they should be tested. The tools that should be available for testing are: 

  1. groff -man -Tascii gpbs.1
  2. groff -man -Tps ./page.1 > page.ps
    to make sure the conversion to PostScript is correct.
  3. Test your newly created man-page in man to see if the rendering is what you expected it to be.
  4. Test by converting your page to HTML with rman. Use 
    rman -fHTML ./page.1 > page.html
    and make sure the HTML page is viewable in a couple of browsers (lynx, Mozilla firefox) and that there are are no serious problems reported by the rman command.
  5. lexgrog ./page.1
    to check it the whatis data is filtered out correctly.

About man-pages

Chapters

Man-pages are stored in a structured fashion below the man/ directory, which are called chapters. The man/ directory contains 9 chapters named man1 to man9. These directories contain the actual man-pages, where the unzipped postfix is the number of the section the man-page belongs to. openapp.1 is thus stored in man/man1/

Below follows a description of the different chapters:
1 Executable programs or shell commands
2 System calls (functions provided by the kernel)
3 Library calls (functions within program libraries)
4 Special files (usually found in /dev)
5 File formats and conventions eg /etc/passwd
6 Games
7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8 System administration commands (usually only for root)
9 Kernel routines [Non standard]

Writing pages

Man-pages are devided in sections. There are several sections that can be used and you can name them as you like, however to stay consistent with other manual pages (and make it easier on the reader) it is best to stick with some common named sections.

The first section has to be NAME since this is the one used by whatis and apropos. All other sections are not defined, but if you compare existing man-pages there seems to be an unwritten law of the order. This chapter is devided in sections that represent the order of appearence in a man-page.

For those entirely new to writing man-pages there is a list of all the macros that can be used in man-pages and their function at the end of this document.

Remarks and convenions

It is good practice to start off the page with some remarks that describe how the page should be rendered. Such a section could look like this: 

.\" Process this file with
.\" groff -man -Tascii openapp.1

The .\" macro is the start of a remark. The information provided to the next end of line will not appear in the man-page, but is only used as meta-information.

Bold The subject of the man-page
Environment variables
options to commands and functions
Italics arguments to options
files
directories

The heading

A required section

The name in the .TH macro is in caps used for the command. Meaning if the command is in small caps the name is. This is to be able to also document commands and functions with alternating caps.

Example

.TH openapp 1 "08/12/2007" gnustep-gui "GNUstep System Manual"
can be opened with: 
man ./openapp.1
and outputs: 
openapp(1)                   GNUstep System Manual                  openapp(1)

gnustep-gui                       08/12/2007                        openapp(1)

NAME

A required section

The first section in the man-page is the NAME section. This section has a standardized format consisting of a comma-separated list of program or function names, followed by a dash, followed by a short (usually one line) description of the functionality the program (or function, or file) is supposed to provide. By means of mandb(8), the name sections make it into the whatis database files. mandb is the reason the name section must exist, and why it must adhere to the format described.

.SH NAME
foo \- foo description
The \- is of importance here. The backslash is needed to make the dash distinct from a hyphenation dash that may appear in either the command name or the one line description.

Example

.SH NAME
openapp \- Command line tool for starting applications
is formatted as: 
NAME
       openapp - Command line tool for starting applications

To test that you didn't make a mistake and that whatis is able to parse the information correctly do the following: 

lexgrog ./openapp.1
./openapp.1: "openapp - Command line tool for starting applications"

SYNOPSIS

A required section for functions and programs

The synopsis gives a short overview on the syntaxis of a program or function. For functions this sections lists corresponding include files and the prototype so the programmer knows the type and number of arguments as well as the return type.

Example: 

.SH SYNOPSIS
.B openapp
.RB [ --find ]
.RB [ --debug " [" --gdb=\fI...\fR ]]
.RB [ --library-combo=\fI...\fR ]
.I application
.RI [ arguments... ]
Looks like: 
SYNOPSIS
       openapp [ --find ] [--debug [--gdb=...]] [--library-combo=...] application [arguments...]

DESCRIPTION

A required section

An as complete description as possible. This section should spell out what the program or function does. Without the need of going into details about the different options.

OPTIONS

A required section for functions, programs and configuration files

It is based around a list of .TP macros. Where the option is set in bold and the description in a normal font.

Example: 

.SH OPTIONS
.TP
.BI --find " application"
will print out the full path of the application executable which
would be executed, without actually executing it. It will also
list all paths that are attempted.
Is rendered as: 
OPTIONS
	--find application
		will print out the full path of the application executable which
		would be executed, without actually executing it. It will also
		list all paths that are attempted.

RETURN VALUE

A required section for functions and programs

DIAGNOSTICS

Optional

EXAMPLES

A required section for functions and programs

ENVIRONMENT

A required section for shell scripts

FILES

An optional section

Lists all the files used by the program or function. For example, log files, configuration files, and startup files. It is often best to use the full path name to the file.

BUGS

An optional section

Bugs in the program or function known to the author of the man-page should be mentioned here.

SEE ALSO

A required section

A list of related man pages in alphabetical order.

HISTORY

A required section

This section describes the project, program or function history.

AUTHORS

A required section

Mentions the names and e-mail addresses of the authors that worked on the man-page, so they can be contacted about errors, omissions or to send compliments.

The person who started the page should be mentioned on top, with every later editor below that one in chronological order, so the last person who editer the page is listed at the bottom.

CREDITS

An optional section

Thank you's and the like go in the section.

COPYRIGHT

Required section

Copyright statement concerning the man-page, all GNUstep man-pages should comply with the GNU man-page copyrights: 

.SH COPYRIGHT
Copyright (C) YEAR Free Software Foundation, Inc.
.PP
Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and
this notice are preserved.

Man-page macros

Fonts and font layout

The default font is Roman, 10 points.

Do not use structures like \fB \fR within your man-pages, but only use the below mentioned macro's.

.B
Bold font. Mainly used to highlight the command name or function name in the manual. Example: 
This manual page for
.B openapp
describes its function
Which is rendered as: 
This manual page for openapp describes its function
.I
Italic font, rendered as underlined with the man command. Mainly used to highlight the filenames, and arguments to programs and functions in the manual. Example: 
The log file
.I syslog
logs system logs
Which is rendered as: 
The log file syslog logs system logs
.R
Roman font. Hardly used since the default font is roman.
.BR
alternate bold and roman font. Example: 
.BR this " is a " test
Which is rendered as: 
this is a test
.RB
alternate roman and bold font. Example: 
.RB this " is a " test
Which is rendered as: 
this is a test
.IR
alternate italic and roman font. Example: 
.IR this " is a " test"
Which is rendered as: 
this is a test
.RI
alternate roman and italic font. Example: 
.RI this " is a " test"
Which is rendered as: 
this is a test
.BI
alternate bold and italic font. Example: 
.BI this " is a " test"
Which is rendered as: 
this is a test
.BI
alternate italic and bold font. Example: 
.BI this " is a " test"
Which is rendered as: 
this is a test
.SM
Small (scaled 9/10 of the regular size). Acronyms look best when typeset in small type face. Example: 
.SM ASCII
.SB
Small bold (not small alternating with bold).

Headers, sections an paragraphs

.TH
A man-page starts with the .TH macro, which looks like this: 
.TH [name of program] [section number] [center footer] [left footer] [center header]
As you can see there is only a small part defined the rest is only header and footer information. For GNUstep we use the following convention:
[name of program]
The program or function name
[section number]
Just the number of the man-page chapter
[center footer]
The date the man-page was last changed, in a format of DD/MM/YYYY
[left footer]
The source package the function or program belongs to
[center header]
The overall system the command belongs to, e.g. GNUstep System Manual for everything installed from the GNUstep core, and GORM Manual for everything belonging to GORM.
.SH
Start a new section
.SS
Start a new sub-section (secondary section)
.P
Start a new paragraph, creates an empty line between two pieces of text.
.LP
See .P
.PP
See .P

Lists

.IP [designator] [nnn]
Set up an indented paragraph, using DESIGNATOR as a tag to mark its beginning. The indentation is set to NNN if that argument is supplied (default unit is `n'), otherwise the default indentation value is used. To start an indented paragraph with a particular indentation but without a designator, use `""' (two double quotes) as the first argument of IP. Example: 
.IP \(bu
item1
.IP \(bu
item2
When using man the bullets will not be shown, there will only be a idnented list.
.HP [nnn]
Set up a paragraph with hanging left indentation. The indentation is set to NNN if that argument is supplied (default unit is `n'), otherwise the default indentation value is used.
.TP [nnn]
Set up an indented paragraph with label. The indentation is set to NNN if that argument is supplied (the default unit is `n' if omitted), otherwise it is set to the default indentation value. The first line following the TP is the label. Example: 
.TP
.BI --debug " application"
starts the application in the debugger. By default gdb, but this can be
changed with the --gdb= argument or through the GDB shell variable.
Which is rendered as: 
       --debug application
                    starts the application in the debugger. By default gdb, but this
		    can be changed with the --gdb= argument or through the GDB shell
		    variable.

Tips and Tricks

Preformatted text
Preformatted text like code snippets can be included like this: 
.PP
.RS 0
foo bar '{
.RS 0
            Name = "My Application";
.RS 0
	    Author = "Just me and \"my other half\"";
.RS 0
	    Modules = (
.RS 0
	                Main,
.RS 0
			"''Input output''",
.RS 0
			Computation
.RS 0
			);
.RS 0
	    Checksum = <01014b5b 123a8b20>
.RS 0
}'
Which is then rendered as: 
foo bar '{
            Name = "My Application";
	    Author = "Just me and \"my other half\"";
	    Modules = (
	                Main,
			"''Input output''",
			Computation
			);
	    Checksum = <01014b5b 123a8b20>
}'