|
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
|
|
