2269 lines
56 KiB
Groff
2269 lines
56 KiB
Groff
.\" Copyright (c) 1990 The Regents of the University of California.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)mdoc.samples.7 5.7 (Berkeley) 7/1/91
|
|
.\"
|
|
|
|
.\" This sampler invokes every macro in the package several
|
|
.\" times and is garanteed to give a worst case performance
|
|
.\" for an already extremely slow package.
|
|
|
|
.Dd July 1, 1991
|
|
.Os BSD 4.4
|
|
.Dt MDOC.SAMPLES 7
|
|
.Sh NAME
|
|
.Nm mdoc.sample
|
|
.Nd writing manual pages with
|
|
.Nm -mdoc
|
|
macro package
|
|
.Sh SYNOPSIS
|
|
.Nm man mdoc.sample
|
|
.Sh DESCRIPTION
|
|
A tutorial sampler for writing
|
|
.Bx
|
|
manual pages with the
|
|
.Nm \-mdoc
|
|
macro package, a
|
|
.Em content Ns \-based
|
|
formatting
|
|
package for
|
|
.Xr troff 1 .
|
|
Its predecessor, the
|
|
.Xr \-man 7
|
|
package,
|
|
addressed page structure leaving the
|
|
manipulation of fonts and other
|
|
typesetting details to the individual author.
|
|
The
|
|
.Nm \-mdoc
|
|
package
|
|
allows the author to ignore font considerations by
|
|
using macros to label
|
|
pieces of text according to content.
|
|
In the context of manual pages, examples of content
|
|
are a command name, a file pathname or a cross
|
|
reference to another manual page; these
|
|
items have value
|
|
for both the author and the future user of the manual page.
|
|
It is hoped the consistency gained
|
|
across the manual set will provide easier
|
|
translation to future documentation tools.
|
|
.Pp
|
|
Through out the
|
|
.Ux
|
|
manual pages, a manual entry
|
|
is simply referred
|
|
to as a man page, regardless of actual length and without
|
|
sexist intention.
|
|
.Sh TROFF IDIOSYNCRASIES
|
|
The
|
|
.Nm \-mdoc
|
|
package attempts to simplify the process of writing a man page.
|
|
Theoretically, one should not have to learn the dirty details of
|
|
.Xr troff 1
|
|
to use
|
|
.Nm \-mdoc ;
|
|
however, there are a few
|
|
limitations which are unavoidable and best gotten out
|
|
of the way. And, too, be forewarned, this package is
|
|
.Em not
|
|
fast.
|
|
.Ss Macro Usage
|
|
As in
|
|
.Xr troff 1 ,
|
|
a macro is called by placing a
|
|
.Ql \&\.
|
|
(dot character)
|
|
at the beginning of
|
|
a line followed by the two character name for the macro.
|
|
Arguments may follow the macro separated by spaces.
|
|
It is the dot character at the beginning of the line which causes
|
|
.Xr troff 1
|
|
to interpret the next two characters as a macro name.
|
|
To place a
|
|
.Ql \&\.
|
|
(dot character)
|
|
at the beginning of a line in some context other than
|
|
a macro macro, precede the
|
|
.Ql \&\.
|
|
(dot) with a
|
|
.Ql \e& .
|
|
.Pp
|
|
In general,
|
|
.Xr troff 1
|
|
macros accept up to nine arguments, any
|
|
extra arguments are ignored.
|
|
Most macros in
|
|
.Nm \-mdoc
|
|
accept nine arguments and,
|
|
in limited cases, arguments may be continued or extended
|
|
on the
|
|
next line (See
|
|
.Sx Extensions
|
|
\-
|
|
macro
|
|
.Ql \&.Xo
|
|
and
|
|
.Ql \&.Xc ) .
|
|
A few macros handle quoted aguments (see
|
|
.Sx Passing Space Characters in an Argument
|
|
below).
|
|
Many
|
|
.Nm \-mdoc
|
|
macros may be given the
|
|
name of another macro as an argument. In this case
|
|
the argument, although the name of a macro,
|
|
is not preceded by a
|
|
.Ql \&\.
|
|
(dot),
|
|
and is
|
|
.Em called
|
|
when the argument is processed.
|
|
It is in this manner that some macros are nested; for
|
|
example
|
|
the option macro,
|
|
.Ql \&.Op ,
|
|
may
|
|
.Em call
|
|
the flag and argument macros,
|
|
.Ql \&.Fl
|
|
and
|
|
.Ql \&.Ar ,
|
|
to specify an optional flag with an argument:
|
|
.nr D 1
|
|
.Bl -tag -width "\&.Op \&Fl s \&Ar bytes" -offset indent
|
|
.It Op Fl s Ar bytes
|
|
is produced by
|
|
.Li \&.Op \&Fl s \&Ar bytes
|
|
.El
|
|
.Pp
|
|
To prevent a two character
|
|
string from being interpreted as a macro name, precede
|
|
the string with the
|
|
escape sequence
|
|
.Ql \e& :
|
|
.Bl -tag -width "[\&Fl s \&Ar bytes]" -offset indent
|
|
.It Op \&Fl s \&Ar bytes
|
|
is produced by
|
|
.Li \&.Op \e&Fl s \e&Ar bytes
|
|
.El
|
|
.Pp
|
|
.nr D 0
|
|
Here the strings
|
|
.Ql \&Fl
|
|
and
|
|
.Ql \&Ar
|
|
were not interpreted as macros.
|
|
Details on callable macros are presented in the
|
|
sections
|
|
.Sx CONTENT MACROS
|
|
and
|
|
.Sx PAGE LAYOUT MACROS.
|
|
.Ss Passing Space Characters in an Argument
|
|
Sometimes it is desirable to give as one argument a string
|
|
containing one or more blank space characters. This may be necessary
|
|
to defeat the nine argument limit or to specify arguments to macros
|
|
which expect particular arrangement of items in the argument list.
|
|
For example,
|
|
the function macro
|
|
.Ql \&.Fn
|
|
expects the first argument to be the name of a function and any
|
|
remaining arguments to be function parameters. As
|
|
.Tn "ANSI C"
|
|
stipulates the declaration of function parameters in the
|
|
parenthesized parameter list, each parameter is guaranteed
|
|
to be at minimum a two word string. For example,
|
|
.Fa int foo .
|
|
There are two possible ways to pass an argument which contains
|
|
an imbedded space. Unfortunately, the most convient way
|
|
of passing such a space between quotes was too expensive to implement for
|
|
all the macros. It is however, implemented for the following macros which need
|
|
it the most:
|
|
.Pp
|
|
.Bl -tag -width 4n -offset indent -compact
|
|
.It Li \&Cd
|
|
Configuration declaration (section 4 SYNOPSIS)
|
|
.It Li \&Bl
|
|
Begin list (for the width specifier).
|
|
.It Li \&Em
|
|
Emphasized text.
|
|
.It Li \&Fn
|
|
Functions (sections two and four).
|
|
.It Li \&It
|
|
List items.
|
|
.It Li \&Li
|
|
Literal text.
|
|
.It Li \&Sy
|
|
Symbolic text.
|
|
.It Li \&%B
|
|
Book titles.
|
|
.It Li \&%J
|
|
Journal names.
|
|
.It Li \&%O
|
|
Optional notes for a reference.
|
|
.It Li \&%R
|
|
Report title (in a reference).
|
|
.It Li \&%T
|
|
Title of article in a book or journal.
|
|
.El
|
|
.Pp
|
|
One way of passing a string
|
|
containing blank spaces is to use the hard or unpaddable space character
|
|
.Ql \e\ ,
|
|
that is, a blank space preceeded by the escape character
|
|
.Ql \e .
|
|
This method may be used with any macro but has the side effect
|
|
of interfering with the adjustment of text
|
|
over the length of a line.
|
|
.Xr Troff
|
|
sees the hard space as if it were any other printable character and
|
|
cannot split the string into blank or newline separated pieces as one
|
|
would expect. The method is useful for strings which are not expected
|
|
to overlap a line boundary. For example:
|
|
.Bl -tag -width "fetch(char *str)" -offset indent
|
|
.It Fn fetch char\ *str
|
|
is created by
|
|
.Ql \&.Fn fetch char\e *str
|
|
.It Fn fetch "char *str"
|
|
can also be created by
|
|
.Ql \&.Fn fetch "\\*q*char *str\\*q"
|
|
.El
|
|
.Pp
|
|
If the
|
|
.Ql \e
|
|
or quotes
|
|
were omitted,
|
|
.Ql \&.Fn
|
|
would see three arguments and
|
|
the result would be:
|
|
.Pp
|
|
.Dl Fn fetch char *str
|
|
.Pp
|
|
For an example of what happens when the parameter list overlaps
|
|
a newline boundary, see the
|
|
.Sx BUGS
|
|
section.
|
|
.\" Note what happens if the parameter list overlaps a newline
|
|
.\" boundary. For example, the next two examples are repeated several times
|
|
.\" to make sure a line boundary is crossed:
|
|
.\" .Bd -literal
|
|
.\" \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
|
|
.\" .Ed
|
|
.\" .Pp
|
|
.\" produces, nudge nudge,
|
|
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
|
|
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
|
|
.\" nudge
|
|
.\" .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
|
|
.\" .Pp
|
|
.\" If double quotes are used, for example:
|
|
.\" .Bd -literal
|
|
.\" \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
|
|
.\" .Ed
|
|
.\" .Pp
|
|
.\" produces, nudge nudge,
|
|
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
|
|
.\" nudge
|
|
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
|
|
.\" nudge
|
|
.\" .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
|
|
.\" .Pp
|
|
.\" Not a pretty sight...
|
|
.\" In a paragraph, a long parameter containing unpaddable spaces as
|
|
.\" in the former example will cause
|
|
.\" .Xr troff
|
|
.\" to break the line and spread
|
|
.\" the remaining words out. The latter example will adjust nicely to
|
|
.\" justified margins, but may break in between an argument and its
|
|
.\" declaration. In
|
|
.\" .Xr nroff
|
|
.\" the right margin adjustment is normally ragged and the problem is
|
|
.\" not as severe.
|
|
.Ss Trailing Blank Space Characters
|
|
.Xr Troff
|
|
can be confused by blank space characters at the end of a line. It
|
|
is wise preventative measure to globally remove all blank spaces
|
|
from <blank-space><end-of-line> character sequences. Should the need
|
|
arise to force a blank character at the end of a line,
|
|
it may be forced with an unpaddable space and the
|
|
.Ql \e&
|
|
escape character.
|
|
For example,
|
|
.Ql string\e\ \e& .
|
|
.Ss Escaping Special Characters
|
|
Special characters
|
|
like the newline character
|
|
.Ql \en ,
|
|
are handled by replacing the
|
|
.Ql \e
|
|
with
|
|
.Ql \ee
|
|
(e.g.
|
|
.Ql \een )
|
|
to preserve
|
|
the backslash.
|
|
.Sh THE ANATOMY OF A MAN PAGE (Getting Started)
|
|
There are three basic groups of macros: specific header macros
|
|
called only once at the very beginning of
|
|
each manual page, page layout or structure macros
|
|
which may be called many times, and content macros which also
|
|
may be called many times.
|
|
The body of a man page is easily constructed from a basic
|
|
template found in the file:
|
|
.Bd -literal -offset indent
|
|
\&.\e" /usr/share/misc/man.tempate :
|
|
\&.\e" The following six lines are required.
|
|
\&.Dt DOCUMENT_TITLE [section number] [volume]
|
|
\&.Os OPERATING_SYSTEM [version/release]
|
|
\&.Dd Month day, year
|
|
\&.Sh NAME
|
|
\&.Sh SYNOPSIS
|
|
\&.Sh DESCRIPTION
|
|
\&.\e" The following requests should be uncommented and
|
|
\&.\e" used where appropriate. This next request is
|
|
\&.\e" for sections 2 and 3 function return values only.
|
|
\&.\e" .Sh RETURN VALUES
|
|
\&.\e" This next request is for sections 1, 6, 7 & 8 only
|
|
\&.\e" .Sh ENVIRONMENT
|
|
\&.\e" .Sh FILES
|
|
\&.\e" .Sh EXAMPLES
|
|
\&.\e" This next request is for sections 1, 6, 7 & 8 only
|
|
\&.\e" (command return values (to shell) and
|
|
\&.\e" fprintf/stderr type diagnostics)
|
|
\&.\e" .Sh DIAGNOSTICS
|
|
\&.\e" The next request is for sections 2 and 3 error
|
|
\&.\e" and signal handling only.
|
|
\&.\e" .Sh ERRORS
|
|
\&.\e" .Sh SEE ALSO
|
|
\&.\e" .Sh STANDARDS
|
|
\&.\e" .Sh HISTORY
|
|
\&.\e" .Sh AUTHORS
|
|
\&.\e" .Sh BUGS
|
|
.Ed
|
|
.Pp
|
|
The first items in the template are the macros
|
|
.Pq Li \&.Dt , \&.Dd , \&.Os ;
|
|
the document or man page title
|
|
.Pq Em in upper case ,
|
|
the section of the manual the page
|
|
belongs to, the (document) date,
|
|
and the operating system the man page is derived
|
|
from. These macros identify the page,
|
|
and are discussed below in
|
|
.Sx TITLE MACROS .
|
|
.Pp
|
|
The remaining items in the template are section headers
|
|
.Pq Li \&.Sh ;
|
|
of which NAME, SYNOPSIS and DESCRIPTION
|
|
are mandatory. The
|
|
headers are
|
|
discussed in
|
|
.Sx PAGE LAYOUT MACROS,
|
|
after
|
|
presentation of
|
|
.Sx CONTENT MACROS .
|
|
Several content macros are used to demonstrate page layout macros;
|
|
reading about content macros before page layout macros is
|
|
recommended.
|
|
.Sh TITLE MACROS
|
|
Three header macros designate the document title or manual page title,
|
|
the operating system,
|
|
and the date of authorship.
|
|
These macros are one called once at the very beginning of the document
|
|
and are used to construct the headers and footers only.
|
|
.Bl -tag -width 6n
|
|
.It Li \&.Dt DOCUMENT_TITLE section# [volume]
|
|
The document title is the
|
|
subject of the man page and must be in CAPITALS due to troff
|
|
limitations.
|
|
The section number may be 1,\ ...,\ 8,
|
|
and if it is specified,
|
|
the volume title may be omitted.
|
|
A volume title may be arbitrary or one of the following:
|
|
.\" .Cl
|
|
.\" USD UNIX User's Supplementary Documents
|
|
.\" .Cl
|
|
.\" PS1 UNIX Programmers's Supplementary Documents
|
|
.Pp
|
|
.Bl -column SMM -offset indent -compact
|
|
.It AMD UNIX Ancestral Manual Documents
|
|
.It SMM UNIX System Manager's Manual
|
|
.It URM UNIX Reference Manual
|
|
.It PRM UNIX Programmers's Manual
|
|
.El
|
|
.Pp
|
|
.\" .Cl
|
|
.\" MMI UNIX Manual Master Index
|
|
.\" .Cl
|
|
.\" CON UNIX Contributed Software Manual
|
|
.\" .Cl
|
|
.\" LOC UNIX Local Manual
|
|
.It Li \&.Os operating_system release#
|
|
The name of the operating system
|
|
should be the common acronym, e.g. BSD
|
|
or ATT. The release should be the standard release
|
|
nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3,
|
|
V.4. Unrecognized arguments are displayed as given in the page footer.
|
|
For instance, for the footer on this page, the 4.4 Berkeley Distribution
|
|
was produced by:
|
|
.Pp
|
|
.Dl \&.Os BSD 4.4
|
|
.It Li \&.Dd month day, year
|
|
The date should be written formally:
|
|
.Pp
|
|
.Dl January 25, 1989
|
|
.El
|
|
.Sh CONTENT MACROS
|
|
.Ss What's in a name...
|
|
Content macro names are derived from the day to day
|
|
informal language used to describe commands, subroutines and related
|
|
files. Slightly
|
|
different variations of this language are used to describe
|
|
the three different aspects of writing a man page.
|
|
First, there is the description of
|
|
.Nm \-mdoc
|
|
macro request usage.
|
|
Second is the description of a
|
|
.Ux
|
|
command
|
|
.Em with
|
|
.Nm \-mdoc
|
|
macros and third,
|
|
the
|
|
description a command to a user in the verbal sense;
|
|
that is, discussion of a command in the text of a man page.
|
|
.Pp
|
|
In the first case,
|
|
.Xr troff 1
|
|
macros are themselves a type of command;
|
|
the general syntax for a troff command is:
|
|
.Bd -filled -offset indent
|
|
\&.Va argument1 argument2 ... argument9
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Ql \&.Va
|
|
is a macro command or request, and anything following it is an argument to
|
|
be processed.
|
|
In the second case,
|
|
the description of a
|
|
.Ux
|
|
command using the content macros is a
|
|
bit more involved;
|
|
a typical SYNOPSIS command line might be displayed as:
|
|
.Pp
|
|
.Bd -filled -offset indent
|
|
.Nm filter
|
|
.Op Fl flag
|
|
.Ar infile outfile
|
|
.Ed
|
|
.Pp
|
|
Here,
|
|
.Nm filter
|
|
is the command name and the
|
|
bracketed string
|
|
.Fl flag
|
|
is a
|
|
.Em flag
|
|
argument designated as optional by the option brackets.
|
|
In
|
|
.Nm \-mdoc
|
|
terms,
|
|
.Ar infile
|
|
and
|
|
.Ar outfile
|
|
are
|
|
called
|
|
.Em arguments .
|
|
The macros which formatted the above example:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
\&.Nm filter
|
|
\&.Op \&Fl flag
|
|
\&.Ar infile outfile
|
|
.Ed
|
|
.Pp
|
|
In the third case, discussion of commands and command syntax
|
|
includes both examples above, but may add more detail. The
|
|
arguments
|
|
.Ar infile
|
|
and
|
|
.Ar outfile
|
|
from the example above might be refered to as
|
|
.Em operands
|
|
or
|
|
.Em file arguments .
|
|
Some command line argument lists are quite long:
|
|
.\" .Bl -tag -width make -offset indent
|
|
.Bl -tag -width make -offset indent
|
|
.It Nm make
|
|
.Op Fl eiknqrstv
|
|
.Op Fl D Ar variable
|
|
.Op Fl d Ar flags
|
|
.Op Fl f Ar makefile
|
|
.Op Fl I Ar directory
|
|
.Op Fl j Ar max_jobs
|
|
.Op Ar variable=value
|
|
.br
|
|
.Op Ar "target\ ..."
|
|
.El
|
|
.Pp
|
|
Here one might talk about the command
|
|
.Nm make
|
|
and qualify the argument
|
|
.Ar makefile ,
|
|
as an argument to the flag,
|
|
.Fl f ,
|
|
or discuss the optional
|
|
file
|
|
operand
|
|
.Ar target .
|
|
In the verbal context, such detail can prevent confusion,
|
|
however the
|
|
.Nm \-mdoc
|
|
package
|
|
does not have a macro for an argument
|
|
.Em to
|
|
a flag.
|
|
Instead the
|
|
.Ql \&Ar
|
|
argument macro is used for an operand or file argument like
|
|
.Ar target
|
|
as well as an argument to a flag like
|
|
.Ar variable :
|
|
.Bd -literal -offset indent
|
|
\&.Nm make
|
|
\&.Op Fl eiknqrstv
|
|
\&.Op Fl D Ar variable
|
|
\&.Op Fl d Ar flags
|
|
\&.Op Fl f Ar makefile
|
|
\&.Op Fl I Ar directory
|
|
\&.Op Fl j Ar max_jobs
|
|
\&.Op Ar variable=value
|
|
\&.Op Ar target ...
|
|
.Ed
|
|
.Ss General Syntax
|
|
All content macros share a similar
|
|
syntax with a few minor deviations:
|
|
.Ql \&.Ar ,
|
|
.Ql \&.Fl ,
|
|
.Ql \&.Nm ,
|
|
and
|
|
.Ql \&.Pa
|
|
differ only when called without arguments;
|
|
.Ql \&.Fn
|
|
and
|
|
.Ql \&.Xr
|
|
impose an order on their argument lists
|
|
and the
|
|
.Em enclosure
|
|
and
|
|
.Em quoting
|
|
macros
|
|
have nesting limitations. All content macros
|
|
are capable of handling punctuation.
|
|
Any argument which may be tested for punctuation
|
|
and contains a member of the mathematical, logical or
|
|
quotation set:
|
|
.Bd -literal -offset indent -compact
|
|
{+,\-,/,*,%,<,>,<=,>=,=,==,&,`,',"}
|
|
.Ed
|
|
should have
|
|
the character escaped with
|
|
.Ql \e& .
|
|
Typical syntax is shown in the first content macro displayed
|
|
below,
|
|
.Ql \&.Ad ,
|
|
and the syntax for enclosure/quoting macros is shown in
|
|
.Sx Enclosure and Quoting Macros .
|
|
.Ss Address Macro
|
|
The address macro constructs an address
|
|
of the form addr1[,addr2[,addr3]].
|
|
.Pp
|
|
.Dl Usage: .Ad address ... \*(Pu
|
|
.Bl -tag -width ".Ad f1 , f2 , f3 :" -compact -offset 14n
|
|
.It Li \&.Ad addr1
|
|
.Ad addr1
|
|
.It Li \&.Ad addr1\ .
|
|
.Ad addr1 .
|
|
.It Li \&.Ad addr1\ , file2
|
|
.Ad addr1 , file2
|
|
.It Li \&.Ad f1\ , f2\ , f3\ :
|
|
.Ad f1 , f2 , f3 :
|
|
.It Li \&.Ad addr\ )\ )\ ,
|
|
.Ad addr ) ) ,
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Li \&.Ad
|
|
without arguments.
|
|
.Li \&.Ad
|
|
is callable by other macros and may call other macros.
|
|
.Ss Argument Macro
|
|
The
|
|
.Li \&.Ar
|
|
argument macro may be used whenever
|
|
a command line argument is referenced.
|
|
.Pp
|
|
.Dl Usage: .Ar argument ... \*(Pu
|
|
.Bl -tag -width ".Ar file1 file2" -compact -offset 15n
|
|
.It Li \&.Ar
|
|
.Ar
|
|
.It Li \&.Ar file1
|
|
.Ar file1
|
|
.It Li \&.Ar file1\ .
|
|
.Ar file1 .
|
|
.It Li \&.Ar file1 file2
|
|
.Ar file1 file2
|
|
.It Li \&.Ar f1 f2 f3\ :
|
|
.Ar f1 f2 f3 :
|
|
.It Li \&.Ar file\ )\ )\ ,
|
|
.Ar file ) ) ,
|
|
.El
|
|
.Pp
|
|
If
|
|
.Li \&.Ar
|
|
is called without arguments
|
|
.Ql Ar
|
|
is assumed. The
|
|
.Li \&.Ar
|
|
macro may call other macros, and may be
|
|
called by other macros.
|
|
.Ss Angle Bracket Quote/Enclosure
|
|
Encloses a string or strings in between angle brackets. The macro
|
|
.Ql \&.Aq
|
|
encloses the remaining arguments on the macro command line, and the
|
|
.Ql \&.Ao
|
|
(angle open) and
|
|
.Ql \&.Ac
|
|
(angle close) macros may be used across one or more lines.
|
|
.Pp
|
|
.Dl Usage: .Aq string ... \*(Pu
|
|
.Bl -tag -width ".Aq Pa ctype.h ) ," -compact -offset 14n
|
|
.It Li \&.Aq
|
|
.Aq
|
|
.It Li \&.Aq string.
|
|
.Aq string.
|
|
.It Li \&.Aq string\ .
|
|
.Aq string .
|
|
.It Li \&.Aq stdio.h
|
|
.Aq stdio.h
|
|
.It Li \&.Aq \&Ar ctype.h\ )\ ,
|
|
.Aq Ar ctype.h ) ,
|
|
.El
|
|
.Pp
|
|
See
|
|
.Sx Enclosure Macros
|
|
for discussion and
|
|
.Sx Options
|
|
for examples of the open and close
|
|
macros
|
|
.Ql \&.Ac
|
|
and
|
|
.Ql \&.Ao .
|
|
.Ql \&.Aq
|
|
is callable by other macros and may call other macros.
|
|
.Ss Bracket Quotes/Enclosure
|
|
Bracket quotes should be used when the string being bracketed is
|
|
.Em not
|
|
an option string. The brackets for an option may be different
|
|
than the default brackets. The macro
|
|
.Ql \&.Bq
|
|
encloses the remaining arguments on a macro command line and the
|
|
macros
|
|
.Ql \&.Bo
|
|
and
|
|
.Ql \&.Bc
|
|
may be used across one or more lines.
|
|
.Pp
|
|
.Dl Usage: .Bq string ... \*(Pu
|
|
.Pp
|
|
The
|
|
.Li \&.Bq
|
|
macro exists for statements which use other macros:
|
|
.Bq Em Greek , French .
|
|
This was done with:
|
|
.Pp
|
|
.Dl Li \&.Bq \&Em Greek \&, French \&.
|
|
.Pp
|
|
It also could have been done using the prefix macro:
|
|
.Pp
|
|
.Dl Li ".Pf [ Em Greek , French ] ."
|
|
.Pp
|
|
See
|
|
.Sx Enclosure Macros
|
|
for discussion and
|
|
.Sx Options
|
|
for examples of the open and close
|
|
macros
|
|
.Ql \&.Bc
|
|
and
|
|
.Ql \&.Bo .
|
|
The
|
|
.Ql \&.Bq
|
|
macro
|
|
is callable and may call other macros.
|
|
.Ss Configuration Declaration (section four only)
|
|
The
|
|
.Ql \&.Cd
|
|
macro is used to demonstrate a
|
|
.Xr config 8
|
|
declaration for a device interface in a section four manual.
|
|
This macro accepts quoted arguments (double quotes only).
|
|
.Pp
|
|
.Bl -tag -width "device le0 at scode?" -offset indent
|
|
.It Cd "device le0 at scode?"
|
|
produced by:
|
|
.Ql ".Cd device le0 at scode?" .
|
|
.El
|
|
.Ss Command Modifier
|
|
The command modifier is identical to the
|
|
.Ql \&.Fl
|
|
(flag) command with the exception
|
|
the
|
|
.Ql \&.Cm
|
|
macro does not assert a dash
|
|
in front of every argument. Traditionally flags are marked by the
|
|
preceding dash, some commands or subsets of commands do not use them.
|
|
Command modifiers may also be specified in conjunction with interactive
|
|
commands such as editor commands.
|
|
See
|
|
.Sx Flags .
|
|
.Ss Double Quote macro/Enclosure
|
|
The
|
|
.Ql \&.Dq
|
|
double quote encloses
|
|
any remaining strings on the command line with double quotes.
|
|
Punctuation is
|
|
placed after the end quote.
|
|
The macros
|
|
.Ql \&.Do
|
|
and
|
|
.Ql \&.Dc
|
|
may be used across one or more lines.
|
|
.Pp
|
|
.Dl Usage: .Dq string ... \*(Pu
|
|
.Bl -tag -width ".Dq Ar patternx ) ) ," -compact -offset 14n
|
|
.It Li \&.Dq
|
|
.Dq
|
|
.It Li ".Dq string."
|
|
.Dq string.
|
|
.It Li ".Dq string abc ."
|
|
.Dq string abc .
|
|
.It Li ".Dq \'^[A-Z]\'"
|
|
.Dq \'^[A-Z]\'
|
|
.It Li \&.Dq \&Ar pattern\ )\ )\ ,
|
|
.Dq Ar pattern ) ) ,
|
|
.El
|
|
.Pp
|
|
If
|
|
.Ql \&.Dq
|
|
is called with no arguments
|
|
.Dq
|
|
is assumed. The
|
|
.Ql \&.Dq
|
|
macro may call or be called by
|
|
other macros.
|
|
See
|
|
.Sx Enclosure Macros
|
|
for discussion of
|
|
.Ql \&.Dc
|
|
and
|
|
.Ql \&.Do
|
|
macro types.
|
|
.Ss Defined Variables
|
|
A variable which is defined in an include file is specified
|
|
by the macro
|
|
.Ql \&.Dv .
|
|
.Pp
|
|
.Dl Usage: .Dv defined_variable ... \*(Pu
|
|
.Bl -tag -width ".Dv MAXHOSTNAMELEN" -compact -offset 14n
|
|
.It Li ".Dv MAXHOSTNAMELEN"
|
|
.Dv MAXHOSTNAMELEN
|
|
.It Li ".Dv TIOCGPGRP )"
|
|
.Dv TIOCGPGRP )
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Ql \&.Dv
|
|
without arguments.
|
|
.Ql \&.Dv
|
|
may call other macros and
|
|
may be called by other macros.
|
|
.Ss Emphasis Macro
|
|
Text may be stressed or emphasized with the
|
|
.Ql \&.Em
|
|
macro. The usual font for emphasis is italic.
|
|
.Pp
|
|
.Dl Usage: .Em argument ... \*(Pu
|
|
.Bl -tag -width ".Em vide infra ) ) ," -compact -offset 14n
|
|
.It Li ".Em does not"
|
|
.Em does not
|
|
.It Li ".Em exceed 1024 ."
|
|
.Em exceed 1024 .
|
|
.It Li ".Em vide infra ) ) ,"
|
|
.Em vide infra ) ) ,
|
|
.El
|
|
.Pp
|
|
The emphasis can be forced across several lines of text by using
|
|
the
|
|
.Ql \&.Bf
|
|
macro discussed in
|
|
.Sx Modes
|
|
under
|
|
.Sx PAGE LAYOUT .
|
|
.\" .Pp
|
|
.\" .Em
|
|
.\" I'm certain the reason so many people desire an MBA from Harvard
|
|
.\" is because they want to be successful philanthropists.
|
|
.\" .Em
|
|
.Pp
|
|
The
|
|
.Ql \&.Em
|
|
macro
|
|
is callable and may call other macros.
|
|
It is an error to call
|
|
.Ql \&.Em
|
|
without arguments.
|
|
.Ss Enclosure and Quoting Macros
|
|
The concept of enclosure is similar to quoting.
|
|
The object is to enclose a string or more between
|
|
a pair of characters like quotes or parentheses.
|
|
The terms quoting and enclosure are used
|
|
interchangeably throughout this document. Many of the
|
|
one line enclosure macros end
|
|
end in small letter
|
|
.Ql q
|
|
to give a hint of quoting, but there are a few exceptions
|
|
(the macros
|
|
.Ql \&.En ,
|
|
.Ql \&.Fn
|
|
and
|
|
.Ql \&.Op
|
|
are also enclosure macros).
|
|
For each enclosure macro
|
|
there is also a pair of open and close macros which end
|
|
in small letters
|
|
.Ql o
|
|
and
|
|
.Ql c
|
|
respectively. These can be used across one or more lines of text
|
|
and while they cannot be nested, the one line quote macros
|
|
can be used inside
|
|
of them.
|
|
For a good example of one these macros, see
|
|
.Sx Options .
|
|
.Pp
|
|
.Bd -filled -offset indent
|
|
.Bl -column "quote" "close" "open" "Enclose Stringx(in XX)" XXstringXX
|
|
.Em " quote close open function result"
|
|
\&.Aq, .Ac, .Ao Angle Bracket Enclosure <string>
|
|
\&.Bq, .Bc, .Bo Bracket Enclosure [string]
|
|
\&.Dq, .Dc, .Do Double Quote ``string''
|
|
.Ec, .Eo Enclose String (in XX) XXstringXX
|
|
\&.Fn, .Fc, .Fo Function Enclosure function(string)
|
|
\&.Op, .Oc, .Oo Option Enclosure [string]
|
|
\&.Pq, .Pc, .Po Parenthesis Enclosure (string)
|
|
\&.Qq, .Qc, .Qo Straight Double Quote "string"
|
|
\&.Sq, .Sc, .So Single Quote `string'
|
|
\& .Xc, .Xo Extend Argument \ \-\-
|
|
.El
|
|
.Ed
|
|
.Pp
|
|
The macros
|
|
.Ql \&.Eo
|
|
and
|
|
.Ql \&.Ec
|
|
allow a user to specify an open and close with the first argument as the
|
|
opening or closing string respectively.
|
|
.Ss Errno's (Section two only)
|
|
The
|
|
.Ql \&.Er
|
|
errno macro specifies the error return value
|
|
for section two library routines. The second example
|
|
below shows
|
|
.Ql \&.Er
|
|
used with the
|
|
.Ql \&.Bq
|
|
macro, as it would be used in
|
|
a section two manual page.
|
|
.Pp
|
|
.Dl Usage: .Er ERRNOTYPE ... \*(Pu
|
|
.Bl -tag -width ".Bq Er ENOTDIR" -compact -offset 14n
|
|
.It Li \&.Er ENOENT
|
|
.Er ENOENT
|
|
.It Li \&.Er ENOENT\ )\ ;
|
|
.Er ENOENT ) ;
|
|
.It Li \&.Bq \&Er ENOTDIR
|
|
.Bq Er ENOTDIR
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Ql \&.Er
|
|
without arguments.
|
|
The
|
|
.Ql \&.Er
|
|
macro
|
|
is callable and may call other macros.
|
|
.Ss Environment Variables
|
|
The
|
|
.Ql \&.Ev
|
|
macro specifies a environment variable.
|
|
.Pp
|
|
.Dl Usage: .Ev argument ... \*(Pu
|
|
.Bl -tag -width ".Ev PRINTER ) ) ," -compact -offset 14n
|
|
.It Li \&.Ev DISPLAY
|
|
.Ev DISPLAY
|
|
.It Li \&.Ev PATH\ .
|
|
.Ev PATH .
|
|
.It Li \&.Ev PRINTER\ )\ )\ ,
|
|
.Ev PRINTER ) ) ,
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Ql \&.Ev
|
|
without arguments.
|
|
The
|
|
.Ql \&.Ev
|
|
macro
|
|
is callable by other macros and may call other macros.
|
|
.Ss Function Argument
|
|
The
|
|
.Ql \&.Fa
|
|
macro is used to refer to function arguments (parameters)
|
|
outside of the SYNOPSIS section of the manual or inside
|
|
the SYNOPSIS section should a parameter list be too
|
|
long for the
|
|
.Ql \&.Fn
|
|
macro and the enclosure macros
|
|
.Ql \&.Fo
|
|
and
|
|
.Ql \&.Fc
|
|
must be used.
|
|
.Ql \&.Fa
|
|
may also be used to refer to structure members.
|
|
.Pp
|
|
.Dl Usage: .Fa function_argument ... \*(Pu
|
|
.Bl -tag -width ".Fa d_namlen\ )\ )\ ," -compact -offset 14n
|
|
.It Li \&.Fa d_namlen\ )\ )\ ,
|
|
.Fa d_namlen ) ) ,
|
|
.It Li \&.Fa iov_len
|
|
.Fa iov_len
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Ql \&.Fa
|
|
without arguments.
|
|
.Ql \&.Fa
|
|
is callable by other macros and may call other macros.
|
|
.Ss Function Declaration
|
|
The
|
|
.Ql \&.Fd
|
|
macro is used in the SYNOPSIS section with section two or three
|
|
functions. The
|
|
.Ql \&.Fd
|
|
macro does not call other macros and is not callable by other
|
|
macros.
|
|
.Pp
|
|
.Dl Usage: .Fd include_file (or defined variable)
|
|
.Pp
|
|
In the SYNOPSIS section a
|
|
.Ql \&.Fd
|
|
request causes a line break if a function has already been presented
|
|
and a break has not occurred. This leaves a nice vertical space
|
|
in between the previous function call and the declaration for the
|
|
next function.
|
|
.Ss Flags
|
|
The
|
|
.Ql \&.Fl
|
|
macro handles command line flags. It prepends
|
|
a dash,
|
|
.Ql \- ,
|
|
to the flag. For interactive command flags, which
|
|
are not prepended with a dash, the
|
|
.Ql \&.Cm
|
|
(command modifier)
|
|
macro is identical, but with out the dash.
|
|
.Pp
|
|
.Dl Usage: .Fl argument ... \*(Pu
|
|
.Bl -tag -width ".Fl \-s \-t \-v" -compact -offset 14n
|
|
.It Li \&.Fl
|
|
.Fl
|
|
.It Li \&.Fl cfv
|
|
.Fl cfv
|
|
.It Li \&.Fl cfv\ .
|
|
.Fl cfv .
|
|
.It Li \&.Fl s v t
|
|
.Fl s v t
|
|
.It Li \&.Fl -\ ,
|
|
.Fl - ,
|
|
.It Li \&.Fl xyz\ )\ ,
|
|
.Fl xyz ) ,
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Fl
|
|
macro without any arguments results
|
|
in a dash representing stdin/stdout.
|
|
Note that giving
|
|
.Ql \&.Fl
|
|
a single dash, will result in two dashes.
|
|
The
|
|
.Ql \&.Fl
|
|
macro
|
|
is callable and may call other macros.
|
|
.Ss Functions (library routines)
|
|
The .Fn macro is modeled on ANSI C conventions.
|
|
.Bd -literal
|
|
Usage: .Fn [type] function [[type] params ... \*(Pu]
|
|
.Ed
|
|
.Bl -tag -width ".Fn .int align. .const * char *sptrsxx" -compact
|
|
.It Li "\&.Fn getchar"
|
|
.Fn getchar
|
|
.It Li "\&.Fn strlen ) ,"
|
|
.Fn strlen ) ,
|
|
.It Li \&.Fn "\\*qint align\\*q" "\\*qconst * char *sptrs\\*q" ,
|
|
.Fn "int align" "const * char *sptrs" ,
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Ql \&.Fn
|
|
without any arguments.
|
|
The
|
|
.Ql \&.Fn
|
|
macro
|
|
is callable by other macros and may call other macros, but
|
|
note that any call to another macro signals the end of
|
|
the
|
|
.Ql \&.Fn
|
|
call (it will close-paren at that point).
|
|
.Pp
|
|
In the SYNOPSIS section, the function will always begin at
|
|
the beginning of line. If there is more than one function
|
|
presented in the SYNOPSIS section and a function type has not been
|
|
given, a line break will occur, leaving a nice vertical space
|
|
between the current function name and the one prior.
|
|
At the moment,
|
|
.Ql \&.Fn
|
|
does not check its word boundaries
|
|
against troff line lengths and may split across a newline
|
|
ungracefully. This will be fixed in the near future.
|
|
.Ss Function Type
|
|
This macro is intended for the SYNOPSIS section. It may be used
|
|
anywhere else in the manpage without problems, but its main purpose
|
|
is to present the function type in kernel normal form for the SYNOPSIS
|
|
of sections two and three
|
|
(it causes a page break allowing the function name to appear
|
|
on the next line).
|
|
.Pp
|
|
.Dl Usage: .Ft type ... \*(Pu
|
|
.Pp
|
|
.Bl -tag -width "\&.Ft struct stat" -offset 14n -compact
|
|
.It Li \&.Ft struct stat
|
|
.Ft struct stat
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Ft
|
|
request is not callable by other macros.
|
|
.Ss Interactive Commands
|
|
The
|
|
.Ql \&.Ic
|
|
macro designates an interactive or internal command.
|
|
.Pp
|
|
.Dl Usage: .Li argument ... \*(Pu
|
|
.Bl -tag -width ".Ic setenv , unsetenv" -compact -offset 14n
|
|
.It Li \&.Ic :wq
|
|
.Ic :wq
|
|
.It Li \&.Ic do while {...}
|
|
.Ic do while {...}
|
|
.It Li \&.Ic setenv\ , unsetenv
|
|
.Ic setenv , unsetenv
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Ql \&.Ic
|
|
without arguments.
|
|
The
|
|
.Ql \&.Ic
|
|
macro may call other macros and is callable.
|
|
.Ss Literals
|
|
The
|
|
.Ql \&.Li
|
|
literal macro may be used for special characters,
|
|
variable constants, anything which should be displayed as it
|
|
would be typed.
|
|
.Pp
|
|
.Dl Usage: .Li argument ... \*(Pu
|
|
.Bl -tag -width ".Li cntrl-D ) ," -compact -offset 14n
|
|
.It Li \&.Li \een
|
|
.Li \en
|
|
.It Li \&.Li M1 M2 M3\ ;
|
|
.Li M1 M2 M3 ;
|
|
.It Li \&.Li cntrl-D\ )\ ,
|
|
.Li cntrl-D ) ,
|
|
.It Li \&.Li 1024\ ...
|
|
.Li 1024 ...
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Li
|
|
macro
|
|
is callable by other macros and may call other macros.
|
|
.Ss Name Macro
|
|
The
|
|
.Ql \&.Nm
|
|
macro is used for the document title or subject name.
|
|
It has the peculiarity of remembering the first
|
|
argument it was called with, which should
|
|
always be the subject name of the page. When called without
|
|
arguments,
|
|
.Ql \&.Nm
|
|
regurgitates this initial name for the sole purpose
|
|
of making less work for the author.
|
|
Note:
|
|
a section two
|
|
or three document function name is addressed with the
|
|
.Ql \&.Nm
|
|
in the NAME section, and with
|
|
.Ql \&.Fn
|
|
in the SYNOPSIS
|
|
and remaining sections.
|
|
For interactive commands, such as the
|
|
.Ql while
|
|
command keyword in
|
|
.Xr csh 1 ,
|
|
the
|
|
.Ql \&.Ic
|
|
macro should be used.
|
|
While the
|
|
.Ql \&.Ic
|
|
is nearly identical
|
|
to
|
|
.Ql \&.Nm ,
|
|
it can not recall the first argument it was invoked with.
|
|
.Pp
|
|
.Dl Usage: .Nm argument ... \*(Pu
|
|
.Bl -tag -width ".Nm mdoc.sample" -compact -offset 14n
|
|
.It Li \&.Nm mdoc.sample
|
|
.Nm mdoc.sample
|
|
.It Li \&.Nm \-mdoc
|
|
.Nm \-mdoc .
|
|
.It Li \&.Nm foo\ )\ )\ ,
|
|
.Nm foo ) ) ,
|
|
.It Li \&.Nm
|
|
.Nm
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Nm
|
|
macro
|
|
is callable by other macros and may call other macros.
|
|
.Ss No\-Op or Normal Text Macro
|
|
The macro
|
|
.Li \&.No
|
|
is
|
|
a hack for words in a macro command line which should
|
|
.Em not
|
|
be formatted and follows the conventional syntax
|
|
for content macros.
|
|
.Ss No Space Macro
|
|
The
|
|
.Ql \&.Ns
|
|
macro eliminates unwanted spaces in between macro requests.
|
|
It is useful for old style argument lists where there is no space
|
|
between the flag and argument:
|
|
.Bl -tag -width ".Op Fl I Ns Ar directory" -offset indent
|
|
.It Li ".Op Fl I Ns Ar directory"
|
|
produces
|
|
.Op Fl I Ns Ar directory
|
|
.El
|
|
.Pp
|
|
Note: the
|
|
.Ql \&.Ns
|
|
macro always invokes the
|
|
.Ql \&.No
|
|
macro after eliminating the space unless another macro name
|
|
follows it.
|
|
The macro
|
|
.Ql \&.Ns
|
|
is callable and may call other macros.
|
|
.Ss Options
|
|
The
|
|
.Ql \&.Op
|
|
macro
|
|
places option brackets around the any remaining arguments on the command
|
|
line, and places any
|
|
trailing punctuation outside the brackets. The macros
|
|
.Ql \&.Oc
|
|
and
|
|
.Ql \&.Oo
|
|
may be used across one or more lines.
|
|
.Pp
|
|
.Dl Usage: .Op options ... \*(Pu
|
|
.Bl -tag -width ".Op Fl c Ar objfil Op Ar corfil ," -compact -offset indent
|
|
.It Li \&.Op
|
|
.Op
|
|
.It Li ".Op Fl k"
|
|
.Op Fl k
|
|
.It Li ".Op Fl k ) ."
|
|
.Op Fl k ) .
|
|
.It Li ".Op Fl k Ar kookfile"
|
|
.Op Fl k Ar kookfile
|
|
.It Li ".Op Fl k Ar kookfile ,"
|
|
.Op Fl k Ar kookfile ,
|
|
.It Li ".Op Ar objfil Op Ar corfil"
|
|
.Op Ar objfil Op Ar corfil
|
|
.It Li ".Op Fl c Ar objfil Op Ar corfil ,"
|
|
.Op Fl c Ar objfil Op Ar corfil ,
|
|
.It Li \&.Op word1 word2
|
|
.Op word1 word2
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Oc
|
|
and
|
|
.Ql \&.Oo
|
|
macros:
|
|
.Bd -literal -offset indent
|
|
\&.Oo
|
|
\&.Op \&Fl k \&Ar kilobytes
|
|
\&.Op \&Fl i \&Ar interval
|
|
\&.Op \&Fl c \&Ar count
|
|
\&.Oc
|
|
.Ed
|
|
.Pp
|
|
Produce:
|
|
.Oo
|
|
.Op Fl k Ar kilobytes
|
|
.Op Fl i Ar interval
|
|
.Op Fl c Ar count
|
|
.Oc
|
|
.Pp
|
|
The macros
|
|
.Ql \&.Op ,
|
|
.Ql \&.Oc
|
|
and
|
|
.Ql \&.Oo
|
|
are callable and may call other macros.
|
|
.Ss Parenthesis Quote/Enclosure
|
|
Macros
|
|
.Li \&.Pq , \&.Pc
|
|
and
|
|
.Li \&.Po
|
|
follow the conventions for a typical quoting macros,
|
|
see
|
|
.Sx Enclosure Macros
|
|
and
|
|
.Sx Options
|
|
above.
|
|
.Ss Pathnames
|
|
The
|
|
.Ql \&.Pa
|
|
macro formats path or file names.
|
|
.Pp
|
|
.Dl Usage: .Pa pathname \*(Pu
|
|
.Bl -tag -width ".Pa /tmp/fooXXXXX ) ." -compact -offset 14n
|
|
.It Li \&.Pa /usr/share
|
|
.Pa /usr/share
|
|
.It Li \&.Pa /tmp/fooXXXXX\ )\ .
|
|
.Pa /tmp/fooXXXXX ) .
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Pa
|
|
macro
|
|
is callable by other macros and may call other macros.
|
|
.Ss Single Quotes/Enclosure
|
|
See
|
|
.Sx Enclosure Macros .
|
|
See
|
|
.Sx Double Quote/Enclosure
|
|
above.
|
|
The single quoting macro
|
|
.Ql \&.Sq
|
|
works in the identical manner as
|
|
.Ql \&.Dq.
|
|
.Ss Prefix Macro
|
|
The
|
|
.Ql \&.Pf
|
|
macro
|
|
is a short cut for combining
|
|
two strings together, the first of which is
|
|
in the default font, and the second a content
|
|
specified string.
|
|
.Pp
|
|
.Bl -tag -width ".Pf ( Fa name2 " -offset 14n -compact
|
|
.It Li ".Pf ( Fa name2"
|
|
becomes
|
|
.Pf ( Fa name2
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Pf
|
|
macro is not callable, but may call other macros. The
|
|
.Ql \&.Ns
|
|
macro performs the analogus suffix function.
|
|
.Ss Section Cross References
|
|
The
|
|
.Ql \&.Sx
|
|
macro designates a reference to a section header
|
|
within the same document. It is callable by other macros and may
|
|
call other macros.
|
|
.Pp
|
|
.Bl -tag -width "Li \&.Sx FILES" -offset 14n
|
|
.It Li \&.Sx FILES
|
|
.Sx FILES
|
|
.El
|
|
.Ss References and Citations
|
|
The following macros make a modest attempt to handle references.
|
|
At best, the macros make it convientent to manually drop in a subset of
|
|
refer style references.
|
|
.Pp
|
|
.Bl -tag -width 6n -offset indent -compact
|
|
.It Li ".Rs"
|
|
Reference Start. Causes a line break and begins collection
|
|
of reference information until the
|
|
reference end macro is read.
|
|
.It Li ".Re"
|
|
Reference End. The reference is printed.
|
|
.It Li ".%A"
|
|
Reference author name, one name per invocation.
|
|
.It Li ".%B"
|
|
Book title.
|
|
.It Li ".%J"
|
|
Journal title.
|
|
.It Li ".%N"
|
|
Issue number.
|
|
.It Li ".%O"
|
|
Optional information.
|
|
.It Li ".%R"
|
|
Report name.
|
|
.It Li ".%T"
|
|
Title of article.
|
|
.It Li ".%V"
|
|
Volume(s).
|
|
.El
|
|
.Pp
|
|
The macros begining with
|
|
.Ql %
|
|
are not callable, but may call only the trade name macro which
|
|
returns to its caller. The purpose is to allow trade names
|
|
to be pretty printed in troff/ditroff output. WARNING: this
|
|
has very few trade names defined at the moment and will print unknown
|
|
trade names in the default font.
|
|
.Ss Symbolic
|
|
The symbolic emphasis macro is generally a boldface macro in
|
|
either the symbolic sense or the traditional English usage.
|
|
.Pp
|
|
.Dl Usage: .Sy symbol ... \*(Pu
|
|
.Bl -tag -width ".Sy Important Notice" -compact -offset 14n
|
|
.It Li \&.Sy Important Notice
|
|
.Sy Important Notice
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Sy
|
|
macro
|
|
is callable by other macros and may call other macros, except
|
|
in the second form. Arguments to
|
|
.Ql \&.Sy
|
|
may be quoted.
|
|
.Ss Variables
|
|
Generic variable reference:
|
|
.Pp
|
|
.Dl Usage: .Va variable ... \*(Pu
|
|
.Bl -tag -width ".Va char s ] ) ) ," -compact -offset 14n
|
|
.It Li \&.Va count
|
|
.Va count
|
|
.It Li \&.Va settimer ,
|
|
.Va settimer ,
|
|
.It Li \&.Va int\ *prt\ )\ :
|
|
.Va int\ *prt ) :
|
|
.It Li \&.Va char\ s\ ]\ )\ )\ ,
|
|
.Va char\ s ] ) ) ,
|
|
.El
|
|
.Pp
|
|
It is an error to call
|
|
.Ql \&.Va
|
|
without any arguments.
|
|
The
|
|
.Ql \&.Va
|
|
macro
|
|
is callable by other macros and may call other macros.
|
|
.Ss Cross References
|
|
The
|
|
.Ql \&.Xr
|
|
macro expects the first argument to be
|
|
a manual page name, and the second argument, if it exists,
|
|
to be either a section page number or punctuation. Any
|
|
remaining arguments are assumed to be punctuation.
|
|
.Pp
|
|
.Dl Usage: .Xr manpage [1,...,8] \*(Pu
|
|
.Bl -tag -width ".Xr mdoc 7 ) ) ," -compact -offset 14n
|
|
.It Li \&.Xr mdoc
|
|
.Xr mdoc
|
|
.It Li \&.Xr mdoc\ ,
|
|
.Xr mdoc ,
|
|
.It Li \&.Xr mdoc 7
|
|
.Xr mdoc 7
|
|
.It Li \&.Xr mdoc 7\ )\ )\ ,
|
|
.Xr mdoc 7 ) ) ,
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ql \&.Xr
|
|
macro
|
|
is callable by other macros and may call other macros.
|
|
It is an error to call
|
|
.Ql \&.Xr
|
|
without
|
|
any arguments.
|
|
.Ss Extended Arguments
|
|
The
|
|
.Li \&.Xo
|
|
and
|
|
.Li \&.Xc
|
|
maxros allow one to extend an argument list
|
|
on a macro boundary. Argument lists cannot
|
|
be extended within a macro
|
|
which expects all of its arguments on one line such
|
|
as
|
|
.Ql \&.Op .
|
|
.\" ---
|
|
.Sh PAGE LAYOUT MACROS
|
|
.Ss Section Headers
|
|
The first three
|
|
.Ql \&.Sh
|
|
section header macros
|
|
list below are required in every
|
|
man page. The remaining section headers
|
|
are recommended at the disgression of the author
|
|
writing the manual page. The
|
|
.Ql \&.Sh
|
|
macro can take up to nine arguments. It may call
|
|
other macros, but it may not be called by other macros.
|
|
.Bl -tag -width ".Sh SYNOPSIS"
|
|
.It \&.Sh NAME
|
|
The
|
|
.Ql \&.Sh NAME
|
|
macro is mandatory. If not specified,
|
|
the headers, footers and page layout defaults
|
|
will not be set and things will be rather unpleasant.
|
|
The NAME section consists of at least three items.
|
|
The first is the
|
|
.Ql \&.Nm
|
|
name macro naming the subject of the man page.
|
|
The second is the Name Description macro,
|
|
.Ql \&.Nd ,
|
|
which separates the subject
|
|
name from the third item, which is the description. The
|
|
description should be the most terse and lucid possible,
|
|
as the space available is small.
|
|
.It \&.Sh SYNOPSIS
|
|
The SYNOPSIS section describes the typical usage of the
|
|
subject of a man page. The macros required
|
|
are either
|
|
.Ql ".Nm" ,
|
|
.Ql ".Cd" ,
|
|
or
|
|
.Ql ".Fn"
|
|
(and possibly
|
|
.Ql ".Fd" ,
|
|
.Ql ".Ft"
|
|
macros).
|
|
The function name
|
|
macro
|
|
.Ql ".Fn"
|
|
is required
|
|
for manual page sections 2 and 3, the command and general
|
|
name macro
|
|
.Ql \&.Nm
|
|
is required for sections 1, 5, 6, 7, 8.
|
|
Section 4 manuals require a
|
|
.Ql ".Nm" , ".Fd"
|
|
or a
|
|
.Ql ".Cd"
|
|
configuration device usage macro.
|
|
Several other macros may be necessary to produce
|
|
the synopsis line as shown below:
|
|
.Pp
|
|
.Bd -filled -offset indent
|
|
.Nm cat
|
|
.Op Fl benstuv
|
|
.Op Fl
|
|
.Ar
|
|
.Ed
|
|
.Pp
|
|
The following macros were used:
|
|
.Pp
|
|
.Dl \&.Nm cat
|
|
.Dl \&.Op \&Fl benstuv
|
|
.Dl \&.Op \&Fl
|
|
.Dl \&.Ar
|
|
.It \&.Sh DESCRIPTION
|
|
In most cases the first text in the DESCRIPTION section
|
|
is a brief paragraph on the command, function or file,
|
|
followed by a lexical list of options and respective
|
|
explanations. To create such a list, the
|
|
.Ql \&.Bl
|
|
begin-list,
|
|
.Ql \&.It
|
|
list-item and
|
|
.Ql \&.El
|
|
end-list
|
|
macros are used (see
|
|
.Sx Lists and Columns
|
|
below).
|
|
.El
|
|
.Pp
|
|
The following
|
|
.Ql \&.Sh
|
|
section headers are part of the
|
|
preferred manual page layout and must be used appropriately
|
|
to maintain consistency. They are listed in the order
|
|
in which they would be used.
|
|
.Bl -tag -width SYNOPSIS
|
|
.It \&.Sh ENVIRONMENT
|
|
The ENVIRONMENT section should reveal any related
|
|
environment
|
|
variables and clues to their behaviour and/or usage.
|
|
.It \&.Sh EXAMPLES
|
|
There are several ways to create examples. See
|
|
the EXAMPLES section below
|
|
for details.
|
|
.It \&.Sh FILES
|
|
Files which are used or created by the man page subject
|
|
should be listed via the
|
|
.Ql \&.Pa
|
|
macro in the FILES section.
|
|
.It \&.Sh SEE ALSO
|
|
References to other material on the man page topic and
|
|
cross references to other relevant man pages should
|
|
be placed in the SEE ALSO section. Cross references
|
|
are specified using the
|
|
.Ql \&.Xr
|
|
macro. At this time
|
|
.Xr refer 1
|
|
style references are not accommodated.
|
|
.It \&.Sh STANDARDS
|
|
If the command, library function or file adheres to a
|
|
specific implementation such as POSIX 1003.1 or
|
|
ANSI C X3.159-1989 this should be noted here. If the
|
|
command does not adhere to any standard, its history
|
|
should be noted in the HISTORY section.
|
|
.It \&.Sh HISTORY
|
|
Any command which does not adhere to any specific standards
|
|
should be outlined historically in this section.
|
|
.It \&.Sh AUTHORS
|
|
Credits, if need be, should be placed here.
|
|
.It \&.Sh DIAGNOSTICS
|
|
Diagnostics from a command should be placed in this section.
|
|
.It \&.Sh ERRORS
|
|
Specific error handling, especially from library functions
|
|
(man page sections 2 and 3) should go here. The
|
|
.Ql \&.Er
|
|
macro is used to specify an errno.
|
|
.It \&.Sh BUGS
|
|
Blatant problems with the topic go here...
|
|
.El
|
|
.Pp
|
|
User specified
|
|
.Ql \&.Sh
|
|
sections may be added,
|
|
for example, this section was set with:
|
|
.Bd -literal -offset 14n
|
|
\&.Sh PAGE LAYOUT MACROS
|
|
.Ed
|
|
.Ss Paragraphs and Line Spacing.
|
|
.Bl -tag -width 6n
|
|
.It \&.Pp
|
|
The \&.Pp paragraph command may
|
|
be used to specify a line space where necessary.
|
|
The macro is not necessary after a
|
|
.Ql \&.Sh
|
|
or
|
|
.Ql \&.Ss
|
|
macro or before
|
|
a
|
|
.Ql \&.Bl
|
|
macro.
|
|
(The
|
|
.Ql \&.Bl
|
|
macro asserts a vertical distance unless the -compact flag is given).
|
|
.El
|
|
.\" .Pp
|
|
.\" .Ds I
|
|
.\" .Cw (ax+bx+c) \ is\ produced\ by\ \&
|
|
.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx\ (
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Va ax
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Sy \+
|
|
.\" .Cx
|
|
.\" .Cl Cx \&(\&
|
|
.\" .Va ax
|
|
.\" .Cx +
|
|
.\" .Va by
|
|
.\" .Cx +
|
|
.\" .Va c )
|
|
.\" .Cx \t
|
|
.\" .Em is produced by
|
|
.\" .Cx \t
|
|
.\" .Li \&.Va by
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Sy \+
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Va c )
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx
|
|
.\" .Cx
|
|
.\" .Cw
|
|
.\" .De
|
|
.\" .Pp
|
|
.\" This example shows the same equation in a different format. The spaces
|
|
.\" around the
|
|
.\" .Li \&+
|
|
.\" signs were forced with
|
|
.\" .Li \e :
|
|
.\" .Pp
|
|
.\" .Ds I
|
|
.\" .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
|
|
.\" .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx\ (
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Va a
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Sy x
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx \e\ +\e\ \e&
|
|
.\" .Cx
|
|
.\" .Cl Cx \&(\&
|
|
.\" .Va a
|
|
.\" .Sy x
|
|
.\" .Cx \ +\ \&
|
|
.\" .Va b
|
|
.\" .Sy y
|
|
.\" .Cx \ +\ \&
|
|
.\" .Va c )
|
|
.\" .Cx \t
|
|
.\" .Em is produced by
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Va b
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Sy y
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx \e\ +\e\ \e&
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Va c )
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx
|
|
.\" .Cx
|
|
.\" .Cw
|
|
.\" .De
|
|
.\" .Pp
|
|
.\" The incantation below was
|
|
.\" lifted from the
|
|
.\" .Xr adb 1
|
|
.\" manual page:
|
|
.\" .Pp
|
|
.\" .Ds I
|
|
.\" .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx Op Sy ?/
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Nm m
|
|
.\" .Cx
|
|
.\" .Cl Cx Op Sy ?/
|
|
.\" .Nm m
|
|
.\" .Ad \ b1 e1 f1
|
|
.\" .Op Sy ?/
|
|
.\" .Cx \t
|
|
.\" .Em is produced by
|
|
.\" .Cx \t
|
|
.\" .Li \&.Ar \e\ b1 e1 f1
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Op Sy ?/
|
|
.\" .Cx
|
|
.\" .Cl Cx \t\t
|
|
.\" .Li \&.Cx
|
|
.\" .Cx
|
|
.\" .Cw
|
|
.\" .De
|
|
.\" .Pp
|
|
.Ss Examples and Displays
|
|
There are five types of displays, a quickie one line indented display
|
|
.Ql \&.D1 ,
|
|
a quickie one line literal display
|
|
.Ql \&.Dl ,
|
|
a block literal, block filled and block ragged which use
|
|
the
|
|
.Ql \&.Bd
|
|
begin-display
|
|
and
|
|
.Ql \&.Ed
|
|
end-display macros.
|
|
.Pp
|
|
.Bl -tag -width \&.D1
|
|
.It Li \&.D1
|
|
(D-one) Display one line of indented text.
|
|
Arguments are checked to see if they are callable.
|
|
.Bd -ragged -offset indent
|
|
.Li \&.D1 \&Fl ldghfstru
|
|
.Ed
|
|
.Pp
|
|
produces:
|
|
.Pp
|
|
.Dl Fl ldghfstru
|
|
.It Li \&.Dl
|
|
(D-ell)
|
|
Display one line of indented
|
|
.Em literal
|
|
text. The
|
|
.Ql \&.Dl
|
|
example macro has been used throughout this
|
|
file. It allows
|
|
the indent (display) of one line of text.
|
|
Its default font is set to
|
|
constant width (literal) however
|
|
.Ql \&.Dl
|
|
does check arguments to see it they are callable.
|
|
Macros called from
|
|
.Li \&.Dl
|
|
should be content macros; calling macros from
|
|
the page layout section
|
|
is redundant and may cause unpredictable errors.
|
|
.Bd -ragged -offset indent
|
|
.Li \&.Dl % ls -ldg /usr/local/bin
|
|
.Ed
|
|
.Pp
|
|
produces:
|
|
.Pp
|
|
.Dl % ls -ldg /usr/local/bin
|
|
.It Li \&.Bd
|
|
Begin-display. The
|
|
.Ql \&.Bd
|
|
display must be ended with the
|
|
.Ql \&.Ed
|
|
macro. Displays may be nested within displays and
|
|
lists.
|
|
.Ql \&.Bd
|
|
has the following syntax:
|
|
.Pp
|
|
.Dl ".Bd display-type [offset offset_value]"
|
|
.Pp
|
|
The display-type must be one of the following four types and
|
|
may have an offset specifier for indentation:
|
|
.Ql \&.Bd .
|
|
.Pp
|
|
.Bl -tag -width "literalxx" -compact
|
|
.It Fl ragged
|
|
Display a block of text as typed,
|
|
right (and left) margin edges are left ragged.
|
|
.It Fl filled
|
|
Display a filled (formatted) block.
|
|
The block of text is formatted (the edges are filled \-
|
|
not left ragged).
|
|
.It Fl literal
|
|
Display a literal block, useful for source code or
|
|
simple tabbed or spaced text.
|
|
.It Fl file Ar file_name
|
|
The file name following the
|
|
.Fl file
|
|
flag is read and displayed. Literal mode is
|
|
asserted and tabs are set at 8 constant width character
|
|
intervals, however any
|
|
.Xr troff/ Ns Nm \-mdoc
|
|
commands in file will be processed.
|
|
.It Fl offset Ar string
|
|
If
|
|
.Fl offset
|
|
is specified with one of the following strings, the string
|
|
is interpreted to indicate the level of indentation for the
|
|
forthcoming block of text:
|
|
.Pp
|
|
.Bl -tag -width "indent" -compact
|
|
.It Ar left
|
|
Align block on the current left margin,
|
|
this is the default mode of
|
|
.Ql \&.Bd .
|
|
.It Ar center
|
|
Supposedly center the block. At this time
|
|
unfortunately, the block merely gets
|
|
left aligned about an imaginary center margin.
|
|
.It Ar indent
|
|
Indents by one default indent value or tab. The default
|
|
indent value is also used for the
|
|
.Ql \&.D1
|
|
display so one can be garanteed of the two types of displays
|
|
lining up. This indent is nornally set to 6n or about two
|
|
thirds of an inch (six constant width characters).
|
|
.It Ar indent-two
|
|
Indents two times the default indent value.
|
|
.It Ar right
|
|
This
|
|
.Em left
|
|
aligns the block about two inches from
|
|
the right side of the page. This macro also needs
|
|
work and perhaps may never be right in
|
|
.Xr troff .
|
|
.El
|
|
.El
|
|
.It ".Ed"
|
|
End-display.
|
|
.El
|
|
.Ss Tagged Lists and Columns
|
|
There are several types of lists which may be initiated with the
|
|
.Ql ".Bl"
|
|
begin-list macro. Items within the list
|
|
are specified with the
|
|
.Ql ".It"
|
|
item macro and
|
|
each list must end with the
|
|
.Ql ".El"
|
|
macro. Lists may be nested within themselves and within displays.
|
|
Columns may be used inside of lists, but lists are unproven
|
|
inside of columns.
|
|
.Pp
|
|
In addition, several list attributes may be specified such as
|
|
the width of a tag, the list offset, and compactness specified
|
|
(blank lines between items allowed or disallowed).
|
|
The following list types are accepted by
|
|
.Ql ".Bl":
|
|
.Pp
|
|
.Bl -ohang -compact
|
|
.It Fl bullet
|
|
.It Fl item
|
|
.It Fl enum
|
|
These three are the simplest types of lists. Once the
|
|
.Ql ".Bl"
|
|
macro has been given, items in the list are merely
|
|
indicated by a line consisting solely of the
|
|
.Ql ".It"
|
|
macro. For example, the source text for a simple enumerated list
|
|
would look like:
|
|
.Bd -literal -offset indent-two
|
|
\&.Bl -enum -compact
|
|
\&.It
|
|
\&Item one goes here.
|
|
\&.It
|
|
\&And item two here.
|
|
\&.It
|
|
\&Lastly item three goes here.
|
|
\&.El
|
|
.Ed
|
|
.Pp
|
|
The results:
|
|
.Pp
|
|
.Bl -enum -offset indent-two -compact
|
|
.It
|
|
Item one goes here.
|
|
.It
|
|
And item two here.
|
|
.It
|
|
Lastly item three goes here.
|
|
.El
|
|
.Pp
|
|
A simple bullet list construction:
|
|
.Bd -literal -offset indent-two
|
|
\&.Bl -bullet -compact
|
|
\&.It
|
|
\&Bullet one goes here.
|
|
\&.It
|
|
\&Bullet two here.
|
|
\&.El
|
|
.Ed
|
|
.Pp
|
|
Produces:
|
|
.Bl -bullet -offset indent-two -compact
|
|
.It
|
|
Bullet one goes here.
|
|
.It
|
|
Bullet two here.
|
|
.El
|
|
.Pp
|
|
.It Fl tag
|
|
.It Fl diag
|
|
.It Fl hang
|
|
.It Fl ohang
|
|
.It Fl inset
|
|
These list-types collect arguments specified with the
|
|
.Ql \&.It
|
|
macro and create a label which may be
|
|
.Em inset
|
|
into the forth coming text,
|
|
.Em hanged
|
|
(exdented) from the forth coming text,
|
|
.Em overhanged
|
|
set above the forth coming paragraph or
|
|
.Em tagged
|
|
(exdented and offset). This
|
|
list was constructed with the
|
|
.Ql Fl ohang
|
|
list-type. The
|
|
.Ql \&.It
|
|
macro may call any callable macros for the inset, hang
|
|
and tag list-types, but will not call macros for the
|
|
diag type.
|
|
Here is an example of inset labels:
|
|
.Bl -inset -offset indent
|
|
.It Em Tag
|
|
The tagged list (also called a tagged paragraph) is the
|
|
most common type of list used in the Berkeley manuals.
|
|
.It Em Diag
|
|
Diag lists create section four diagnostic lists
|
|
and are similar to inset lists except callable
|
|
macros are ignored.
|
|
.It Em Hang
|
|
Hanged labels are a matter of taste.
|
|
.It Em Ohang
|
|
Over hanging labels are nice when space is constrained.
|
|
.It Em Inset
|
|
Inset labels are useful for controlling blocks of
|
|
paragraphs and are valuable for converting
|
|
.Nm \-mdoc
|
|
manuals to other formats.
|
|
.El
|
|
.Pp
|
|
Here is the source text which produced the above example:
|
|
.Bd -literal -offset indent
|
|
\&.Bl -inset -offset indent
|
|
\&.It Em Tag
|
|
\&The tagged list (also called a tagged paragraph) is the
|
|
\&most common type of list used in the Berkeley manuals.
|
|
\&.It Em Diag
|
|
\&Diag lists create section four diagnostic lists
|
|
\&and are similar to inset lists except callable
|
|
\¯os are ignored.
|
|
\&.It Em Hang
|
|
\&Hanged labels are a matter of taste.
|
|
\&.It Em Ohang
|
|
\&Over hanging labels are nice when space is constrained.
|
|
\&.It Em Inset
|
|
\&Inset labels are useful for controlling blocks of
|
|
\¶graphs and are valuable for converting
|
|
\&.Nm \-mdoc
|
|
\&manuals to other formats.
|
|
\&.El
|
|
.Ed
|
|
.Pp
|
|
Here is a hanged list with just one item:
|
|
.Bl -hang -offset indent
|
|
.It Em Hanged
|
|
labels appear similar to tagged lists when the
|
|
label is smaller than the label width.
|
|
.It Em Longer hanged list labels
|
|
blend in to the paragraph unlike
|
|
tagged paragraph labels.
|
|
.El
|
|
.Pp
|
|
And the unfomatted text which created it:
|
|
.Bd -literal -offset indent
|
|
\&.Bl -hang -offset indent
|
|
\&.It Em Hanged
|
|
\&labels appear similar to tagged lists when the
|
|
\&label is smaller than the label width.
|
|
\&.It Em Longer hanged list labels
|
|
\&blend in to the paragraph unlike
|
|
\&tagged paragraph labels.
|
|
\&.El
|
|
.Ed
|
|
.Pp
|
|
The tagged list which follows uses an optional width specifier to controll
|
|
the width of the tag.
|
|
.Pp
|
|
.Bl -tag -width "PAGEIN 10" -compact -offset indent
|
|
.It SL 10
|
|
sleep time of the process (seconds blocked)
|
|
.It PAGEIN 10
|
|
number of disk i/o's resulting from references
|
|
by the process to pages not loaded in core.
|
|
.It UID 10
|
|
numerical user-id of process owner
|
|
.It PPID 10
|
|
numerical id of parent of process process priority
|
|
(non-positive when in non-interruptible wait)
|
|
.El
|
|
.Pp
|
|
The raw text:
|
|
.Bd -literal -offset indent
|
|
\&.Bl -tag -width "PAGEIN 10" -compact -offset indent
|
|
\&.It SL 10
|
|
\&sleep time of the process (seconds blocked)
|
|
\&.It PAGEIN 10
|
|
\&number of disk i/o's resulting from references
|
|
\&by the process to pages not loaded in core.
|
|
\&.It UID 10
|
|
\&numerical user-id of process owner
|
|
\&.It PPID 10
|
|
\&numerical id of parent of process process priority
|
|
\&(non-positive when in non-interruptible wait)
|
|
\&.El
|
|
.Ed
|
|
.Pp
|
|
Acceptable width specifiers:
|
|
.Bl -tag -width Ar -offset indent
|
|
.It Fl width Ar "\&Fl"
|
|
sets the width to the default width for a flag. All callable
|
|
macros have a default width value. The
|
|
.Ql \&.Fl ,
|
|
value is presently
|
|
set to ten constant width characters or about five sixth of
|
|
an inch.
|
|
.It Fl width Ar "24n"
|
|
sets the width to 24 constant width characters or about two
|
|
inches. The
|
|
.Ql n
|
|
is absolutely necessary for the scaling to work correctly.
|
|
.It Fl width Ar "ENAMETOOLONG"
|
|
sets width to the constant width length of the
|
|
string given.
|
|
.It Fl width Ar "\\*qint mkfifo\\*q"
|
|
again, the width is set to the constant width of the string
|
|
given.
|
|
.El
|
|
.Pp
|
|
If a width is not specified for the tag list type, the first
|
|
time
|
|
.Ql \&.It
|
|
is invoked, an attempt is made to determine an appropriate
|
|
width. If the first argument to
|
|
.Ql ".It"
|
|
is a callable macro, the default width for that macro will be used
|
|
as if the macro name had been supplied as the width. However,
|
|
if another item in the list is given with a different callable
|
|
macro name, a new and nested list is assumed. Here is an involved
|
|
example of a self nesting list:
|
|
.Sh DIAGNOSTICS
|
|
The debugging facilities for
|
|
.Nm \-mdoc
|
|
are limited, but can help detect subtle errors such
|
|
as the collision of an argument name with an internal
|
|
register or macro name. (A what?)
|
|
A register is an arithmetic storage class for
|
|
.Xr troff
|
|
with a one or two character name.
|
|
All registers internal to
|
|
.Nm \-mdoc
|
|
for
|
|
.Xr troff
|
|
and
|
|
.Xr ditroff
|
|
are two characters and
|
|
of the form <uppercase><lowercase> such as
|
|
.Ql \&Ar ,
|
|
<lowercase><uppercase> as
|
|
.Ql \&aR
|
|
or
|
|
<upper or lower letter><digit> as
|
|
.Ql \&C\&1 .
|
|
And adding to the muddle,
|
|
.Xr troff
|
|
has its own internal registers all of which are either
|
|
two lowercase characters or a dot plus a letter or meta-character
|
|
character.
|
|
In one of the introduction examples, it was shown how to
|
|
prevent the interpretation of a macro name with the escape sequence
|
|
.Ql \e& .
|
|
This is sufficient for the internal register names also.
|
|
.Pp
|
|
.\" Every callable macro name has a corresponding register
|
|
.\" of the same name (<Uppercase><lowercase>).
|
|
.\" There are also specific registers which have
|
|
.\" been used for stacks and arrays and are listed in the
|
|
.\" .Sx Appendix .
|
|
.\" .Bd -ragged -offset 4n
|
|
.\" [A-Z][a-z] registers corresponding to macro names (example ``Ar'')
|
|
.\" [a-z][A-Z] registers corresponding to macro names (example ``aR'')
|
|
.\" C[0-9] argument types (example C1)
|
|
.\" O[0-9] offset stack (displays)
|
|
.\" h[0-9] horizontal spacing stack (lists)
|
|
.\" o[0-9] offset (stack) (lists)
|
|
.\" t[0-9] tag stack (lists)
|
|
.\" v[0-9] vertical spacing stack (lists)
|
|
.\" w[0-9] width tag/label stack
|
|
.\" .Ed
|
|
.\" .Pp
|
|
If a non-escaped register name is given in the argument list of a request
|
|
unpredictable behaviour will occur. In general, anytime huge portions
|
|
of text do not appear where expected in the output, or small strings
|
|
such as list tags disappear, chances are there is a misunderstanding
|
|
about an argument type in the argument list.
|
|
Your mother never intended for you to remember this evil stuff - so here
|
|
is a way to find out whether or not your arguments are valid: The
|
|
.Ql \&.Db
|
|
(debug)
|
|
macro displays the interpretation of the argument list for most
|
|
macros. Macros such as the
|
|
.Ql \&.Pp
|
|
(paragraph)
|
|
macro do not contain debugging information. All of the callable macros do,
|
|
and it is strongly advised whenever in doubt,
|
|
turn on the
|
|
.Ql \&.Db
|
|
macro.
|
|
.Pp
|
|
.Dl Usage: \&.Db [on | off]
|
|
.Pp
|
|
An example of a portion of text with
|
|
the debug macro placed above and below an
|
|
artificially created problem (a flag argument
|
|
.Ql \&aC
|
|
which should be
|
|
.Ql \e&aC
|
|
in order to work):
|
|
.Bd -literal -offset indent
|
|
\&.Db on
|
|
\&.Op Fl aC Ar file )
|
|
\&.Db off
|
|
.Ed
|
|
.Pp
|
|
The resulting output:
|
|
.Bd -literal -offset indent
|
|
DEBUGGING ON
|
|
DEBUG(argv) MACRO: `.Op' Line #: 2
|
|
Argc: 1 Argv: `Fl' Length: 2
|
|
Space: `' Class: Executable
|
|
Argc: 2 Argv: `aC' Length: 2
|
|
Space: `' Class: Executable
|
|
Argc: 3 Argv: `Ar' Length: 2
|
|
Space: `' Class: Executable
|
|
Argc: 4 Argv: `file' Length: 4
|
|
Space: ` ' Class: String
|
|
Argc: 5 Argv: `)' Length: 1
|
|
Space: ` ' Class: Closing Punctuation or suffix
|
|
MACRO REQUEST: .Op Fl aC Ar file )
|
|
DEBUGGING OFF
|
|
.Ed
|
|
.Pp
|
|
The first line of information tells the name of the calling
|
|
macro, here
|
|
.Ql \&.Op ,
|
|
and the line number it appears on. If one or more files are involved
|
|
(especially if text from another file is included) the line number
|
|
may be bogus. If there is only one file, it should be accurate.
|
|
The second line gives the argument count, the argument
|
|
.Pq Ql \&Fl
|
|
and its length. If the length of an argument is two characters, the
|
|
argument is tested to see if it is executable (unfortunately, any
|
|
register which contains a non-zero value appears executable).
|
|
The third line gives the space allotted for a class, and the
|
|
class type. The problem here is the argument aC should not be
|
|
executable. The four types of classes are string, executable, closing
|
|
punctuation and opening punctuation. The last line shows the entire
|
|
argument list as it was read. In this next example, the offending
|
|
.Ql \&aC
|
|
is escaped:
|
|
.Bd -literal -offset indent
|
|
\&.Db on
|
|
\&.Em An escaped \e&aC
|
|
\&.Db off
|
|
.Ed
|
|
.Bd -literal -offset indent
|
|
DEBUGGING ON
|
|
DEBUG(fargv) MACRO: `.Em' Line #: 2
|
|
Argc: 1 Argv: `An' Length: 2
|
|
Space: ` ' Class: String
|
|
Argc: 2 Argv: `escaped' Length: 7
|
|
Space: ` ' Class: String
|
|
Argc: 3 Argv: `aC' Length: 2
|
|
Space: ` ' Class: String
|
|
MACRO REQUEST: .Em An escaped &aC
|
|
DEBUGGING OFF
|
|
.Ed
|
|
.Pp
|
|
The argument
|
|
.Ql \e&aC
|
|
shows up with the same length of 2 as the
|
|
.Ql \e&
|
|
sequence produces a zero width, but a register
|
|
named
|
|
.Ql \e&aC
|
|
was not found and the type classified as string.
|
|
.Pp
|
|
Other diagnostics consist of usage statements and are self explanatory.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/man0/template.doc -compact
|
|
.It Pa /usr/share/tmac/tmac.doc
|
|
manual macro package
|
|
.It Pa /usr/share/man0/template.doc
|
|
template for writing a man page
|
|
.El
|
|
.Sh HISTORY
|
|
4.4 BSD
|
|
.Sh SEE ALSO
|
|
.Xr mdoc 7 ,
|
|
.Xr man 1 ,
|
|
.Xr troff 1
|
|
.Sh BUGS
|
|
Undesirable hyphenation on the dash of a flag
|
|
argument is not yet resolved, and causes
|
|
occasional mishaps in the DESCRIPTION section.
|
|
(line break on the hyphen).
|
|
.Pp
|
|
Predefined strings are not declared in documentation.
|
|
.Pp
|
|
Section 3f has not been added to the header routines.
|
|
.Pp
|
|
.Ql \&.Nm
|
|
font should be changed in NAME section.
|
|
.Pp
|
|
.Ql \&.Fn
|
|
needs to have a check to prevent splitting up
|
|
if the line length is too short. Right now it
|
|
separates the last parenthesis, and sometimes
|
|
looks ridiculous if a line is in fill mode.
|
|
.Pp
|
|
The method used to prevent header and footer page
|
|
breaks (other than the initial header and footer) when using
|
|
nroff seems to be putting out a partially filled line
|
|
at the bottom of the page leaving an unsightly blank space.
|
|
.Pp
|
|
The list and display macros to not do any keeps
|
|
and certainly should be able to.
|