|
V.0.1
If there are any questions or comments, please direct them to
walt@erudition.net. The newest copy of this How-To can always be retrieved
from www.freebsd-howto.com. All rights for the reproduction of this
document are reserved.
Summary.
This Howto will make a quick overview of manpage formatting
and creation in FreeBSD 2.2.x, 3.x and 4.x. It is geared to those
interested in a quick introduction to man page creation and editing.
Outline.
1.Introduction
2. Man Page Location & Types
3. Man Page Macros
3.1. Page Structure Macros
3.2. Manual & General Text Macros
4.References
1. Introduction
Man pages are formatted by the UNIX utility nroff(1) with the
batch package historically called man(7). nroff/troff/groff are powerful
formatting utilities which can use special batch packages for defining
special macros for a given purpose. The man(7) batch package defines
macros for use with creating man pages. To display a particular man page
source manually wih nroff, the following commands can be issued at the
prompt:
nroff -man <man page file> | more
This will display the man page source file with the man batch
package, and pipe it to more(1) for easy scrolling display. This is
exactly what the man(1) command does. At first glance, man page source
files will appear extremely cryptic, and to those used to using WYSIWYG
word processors, they will seem archaic. However, the formatting tools
nroff/troff/groff offer powerful formatting tools for precise layout. The
man batch package for nroff defines specific macros that need to be filled
out in the source file which allows for stong control over how man pages
will look. This is important as it allows a relatively uniform look for
man pages; yet, the batch package allows for enough flexibility to allow
one to document everything from system libraries and header files to
configuration files.
In BSD systems, the man(7) batch packages, although available, has
been deprecated and the more powerful mdoc(7) batch package is used
instead; so, the follow line will work to display man pages as well:
nroff -mdoc <man page file> | more
2.Man Page Location & Types
To take a glance at a man page source file, go to /usr/local/man/,
choose the man directory of your choice, and select the man page source
file you wish to view. You will need to copy it to a temporary directory,
gunzip it, and open it with your favourite text editor. Man pages are
usually compressed to save space. Each man directory under /usr/local/man
corresponds to special groups of man pages. For instance, basic system
utilities and commands are under /usr/local/man/man1, and system call
documentation is under /usr/local/man2. The MANPATH environment variable
defines all of the paths which should be checked for man1, man2, man3, and
so on, and is usually set in one's shell init files. Here is the complete
list of man page numbers and what types of man pages they correspond to:
TypeDescription
Number-----------
------
1General Command
2System Calls
3Library Functions
4Kernel Interfaces
5File Formats
6Games
7Miscellaneous Information
8System Manager's Manuals
9Kernel Developer's Manual
3.Man Page Macros
Man page macros are divided into two major groups: Page Structure
Macros and Manual & General Text Macros. The first outline the general
sections that each man pages has (you may recall some as "NAME" and
"SYNOPSIS." For a quick refresher, look at the man page of any command you
can think of, for instance, ls(1) or inetd.conf(5). You will see general
section divisions; each of them are defined by Page Structure Macros. Page
Structure Macros also define the title for each man page, which contains
the name of the man page, type of man page, and so on. General Text Macros
define all of the formatting for the remaining bold, underlined, indented
text, etc.
3.1.Page Structure Macros
The Page Structure Macros are further subdivided into two parts:
Title Macros and Page Layout Macros. The former define the title and the
latter define the layout of the man page sections. The first Macros that
must be used in any man page source file are the Title Macros; they number
three:
MacroDescription
----------------
.DdDocument date
.DtTitle, in upper case
.OsOperating System (FreeBSD)
The .Dd macro's syntax is: '[month] [day], [year]', the .Dt
syntax is '[document title] [section] [volume]', and the .Os syntax is
'[operating system] [version/release]'. For example, a man page source
file for a utility named "magicbin" may begin thusly:
.Dd June 6, 2000
.Dt MAGICBIN 1 URM
.Os FreeBSD 4.0
The volume type "URM" is one of four possible volume types, and is
optional. The four possible volumes types are:
AMD UNIX Ancestral Manual Documents
SMM UNIX System Manager's Manual
URM UNIX Reference Manual
PRM UNIX Programmer's Manual
After the Title Macros, come the the Page Layout Macros with their
corresponding General Text Macros. The first section of each man page is
the NAME section which shows the name of the utility in bold followed by a
quick description of what it does. So, following the Title Macros in the
source file, the beginning of the NAME section must be specified with an
.Sh macro, after which would follow a few short Manual & General Text
Macros defining the quick summary. In the following example we will use
the .Nm and .Nd General Text Macros macros and explain their usage more
clearly later.
.Sh NAME
.Nm magicbin
.Nd this utility does some special operations on your system
If you would like to see how this looks so far, save the previous
Title Macros and the above Page Layout and Manual & General Text Macros in
a file and call it with:
nroff -mdoc <file> | more
You will notice the man page is neatly formatted, with a date on
the bottom, the page type in the top middle, and so on. You may be slowly
seeing the power of nroff in formatting documents.
The next section we will specify is the SYNOPSIS, which outlines
the syntax for our utility:
.Sh SYNOPSIS
.Nm magicbin
.Op Fl cxz Ar time Ar number
Here we define the utility "magicbin" as having three options,
'c,' 'x,' 'z' and two parameters, 'time' and 'number.'
The remainder of the sections and how they are started off in the
man page source is as follows:
.Sh DESCRIPTION
.Sh IMPLEMENTATION NOTES
.Sh RETURN VALUES
.Sh ENVIRONMENT
.Sh FILES
.Sh EXAMPLES
.Sh DIAGNOSTICS
.Sh COMPATIBILITY
.Sh ERRORS
.Sh SEE ALSO
.Sh STANDARDS
.Sh HISTORY
.Sh AUTHORS
.Sh BUGS
These are the three main sections that may be used, and obviously,
all do not need to be used in a man page. One can also define custom
sections with the .Sh macro. In addition, one may define sub-sections with
the .Ss macro.
To create paragraph breaks, use the .Pp on a line by itself. To
display a line literally, that is, with all of its tabs and spaces
literally as outlined in the source file, use the .Dl macro, followed by
the text. To create blocks of indented text, either as literal text (as
described above) or not, use two macros: .Bd and .Ed. The former macro
defines the beginning of the display block and the latter macro defines
the end of the display block. Various options can be passed to the display
block to specify special formatting. These options must be specified on
the .Bd line. For example, to define a display-block literally as
formatted with spaces and tabs in the source file, one would do the
follow:
.Bd -literal
some test here with tabsand more tabs
on this line too and maybe some spaces like this.
.Ed
Other options that can be passed to the display-block macros are:
-raggedUnjustified text
-filledJustified text
-file <name>Read in named <file> and display
-offset<parameters>Offset the display with parameter
specified with the <string> option.
Some -offset options are:
"left"Align block on left
"center"Center the text
"indent"A Tab indent
"indent-two"Two Tab indent
"right"Align block on right
In addition to defining display-blocks, one can define display
lists with the .Bl and .El macros. Items in dislay-lists must use the .It
macro, for instance:
.Bl
.It
First Item
.It
Second Item
.El
This will make a list with no <return>s after each list item. To
number the items on separate lines, pass the "-num" parameter on the .Bl
macro line, for instance:
.Bl -enum
.It
First Item
.It
Second Item
.El
To list the items with bullets, use the -bullet parameter to the
.Bl macro line instead. Altogether there are 11 parameters that can be
sent to the .Bl macro:
-bullet Bullet Item List
-item Unlabeled List
-enum Enumerated List
-tag Tag Labeled List
-diag Diagnostic List
-hang Hanging Labeled List
-ohang Overhanging Labeled List
-inset Inset or Run-on Labeled List
-offset (All lists.) See `.Bd' begin-display above.
-width (-tag and -hang lists only.) See `.Bd'.
-compact (All lists.) Suppresses blank lines.
3.2.Manual & General Text Macros
You have already seen some Manual & General Text macros in our
above examples, namely .Nm, .Fl, .Ar, and .Op. The .Nm macro is used to
display commands in bold. In our case, the command was "magicbin." .Fl is
used to define command parameters, .Ar is used to define command
arguments, and .Op is a special macro that is used to combine multiple
callable macros for easy formatting. For instance, in our original example
we had:
.Op Fl cxz Ar time Ar number
Here, the .Op macro operated on the text "Fl cxz Ar time Ar
number". The callable Fl macro worked on its following text, the "cxz" and
prefixed them with a hyphen and made them bold. The callable macros Ar
took their subsequent text, underlined it, and all the .Ar macros were
bracketted. For a clear illustration of this, use our earlier examples and
display them with nroff(1). Not all .Op macros are callable and the full
list of Manual & General Text macros, with the callable and non-callable
ones indicated, can be found in the mdoc(7) man page.
Other often-used macros are:
.Xr <reference> <number> Underline system man page reference
.An <author> Man page Author
.Aq <text> Block off given text in angle quotes
.Fx OS version
When formatting macro parameters with punctuation, one must put a
space between the text and the commas and periods for the commas and
periods to be placed properly, for instance, to display "FreeBSD
4.0." the followed must be put in the source file:
.Fx 4.0 .
When typing regular text for display, one needn't preceed
punctuation with spaces. For instance:
.Sh DESCRIPTION
This man page, among other things, displays some interesting stuff
and then explains some cool things, such as how the command
.Nm magicbin ,
is used and all of its parameters.
When indicating path names to files, use the .Pa macro, when
indicating variable names, use the .Va macro, and when trying to display
literal text use the .Li macro. The full list of macros found in the
mdoc(7) man page numbers far more than those quickly referred to here, and
it is strongly suggested that one reads over them to be aware of all
macros that one can use to format their man pages.
For an full example of a man page, one should look over the three
documents in /usr/share/examples/mdoc. The three documents in there are
samples for three different types of man pages, specifically, 1, 3, and
4. In addition, mdoc.samples(7) offers many sample macros and snippets of
man page layouts. It is an extremely powerful reference and should be used
by anyone who requires advanced mdoc(7) functionality.
4. References
mdoc(7)
mdoc.samples(7)
man(1)
man(7)
/usr/share/examples/mdoc/
/usr/share/tmac/mdoc/
Lasker
|
|
