mdoc.samples.7

早期freebsd实现

.Pp
.Dl \&.Os BSD 4.3
.Pp
or for a locally produced set
.Pp
.Dl \&.Os CS Department
.Pp
The Berkeley default,
.Ql \&.Os
without an argument, has been defined as
.Tn BSD
Experimental in the
site specific file
.Pa /usr/src/share/tmac/doc-common .
It really should default to
.Tn LOCAL .
Note, if the
.Ql \&.Os
macro is not present, the bottom left corner of the page
will be ugly.
.It Li \&.Dd month day, year
The date should be written formally:
.Pp
.ne 5
.Dl January 25, 1989
.El
.Sh MANUAL DOMAIN
.Ss What's in a name...
The manual domain 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 of 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
.Sx SYNOPSIS
command line might be displayed as:
.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:
.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 referred to as
.Em operands
or
.Em file arguments .
Some command line argument lists are quite long:
.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
.Bk -words
.Op Fl I Ar directory
.Ek
.Op Fl j Ar max_jobs
.Op Ar variable=value
.Bk -words
.Op Ar target ...
.Ek
.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 .
The make command line was produced from:
.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
\&.Bk -words
\&.Op Ar target ...
\&.Ek
.Ed
.Pp
The
.Ql \&.Bk
and
.Ql \&.Ek
macros are explained in
.Sx Keeps .
.Ss General Syntax
The manual domain and general text domain 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
.Ql \&.Op
and
.Ql \&.Fn
macros
have nesting limitations.
All content macros
are capable of recognizing and properly handling punctuation,
provided each punctuation character is separated by a leading space.
If an request is given:
.Pp
.Dl \&.Li sptr, ptr),
.Pp
The result is:
.Pp
.Dl Li sptr, ptr),
.Pp
The punctuation is not recognized and all is output in the
literal font. If the punctuation is separated by a leading
white space:
.Pp
.Dl \&.Li "sptr , ptr ) ,"
.Pp
The result is:
.Pp
.Dl Li sptr , ptr ) ,
.Pp
The punctuation is now recognized and is output in the
default font distinguishing it from the strings in literal font.
.Pp
To remove the special meaning from a punctuation character
escape it with
.Ql \e& .
.Xr Troff
is limited as a macro language, and has difficulty
when presented with a string containing
a member of the mathematical, logical or
quotation set:
.Bd -literal -offset indent-two
\&{+,\-,/,*,\&%,<,>,<=,>=,=,==,&,`,',"}
.Ed
.Pp
The problem is that
.Xr troff
may assume it is supposed to actually perform the operation
or evaluation suggested by the characters.  To prevent
the accidental evaluation of these characters,
escape them with
.Ql \e& .
Typical syntax is shown in the first content macro displayed
below,
.Ql \&.Ad .
.Ss Address Macro
The address macro identifies an address construct
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 is parsed.
.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 is parsed and is callable.
.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 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
is parsed and is callable.
.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
general text domain 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 parsed and is callable.
.Ss Environment Variables
The
.Ql \&.Ev
macro specifies an 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 parsed and is callable.
.Ss Function Argument
The
.Ql \&.Fa
macro is used to refer to function arguments (parameters)
outside of the
.Sx SYNOPSIS
section of the manual or inside
the
.Sx 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 parsed and is callable.
.Ss Function Declaration
The
.Ql \&.Fd
macro is used in the
.Sx 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
.Sx 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 without 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 parsed and is callable.
.Ss Functions (library routines)
The .Fn macro is modeled on ANSI C conventions.
.Bd -literal
Usage: .Fn [type] function [[type] parameters ... \*(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 parsed and is callable,
note that any call to another macro signals the end of
the
.Ql \&.Fn
call (it will close-parenthesis at that point).
.Pp
For functions that have more than eight parameters (and this
is rare), the
macros
.Ql \&.Fo
(function open)
and
.Ql \&.Fc
(function close)
may be used with
.Ql \&.Fa
(function argument)
to get around the limitation. For example:
.Bd -literal -offset indent
\&.Fo "int res_mkquery"
\&.Fa "int op"
\&.Fa "char *dname"
\&.Fa "int class"
\&.Fa "int type"
\&.Fa "char *data"
\&.Fa "int datalen"
\&.Fa "struct rrec *newrr"
\&.Fa "char *buf"
\&.Fa "int buflen"
\&.Fc
.Ed
.Pp
Produces:
.Bd -filled -offset indent
.Fo "int res_mkquery"
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc
.Ed
.Pp
The
.Ql \&.Fo
and
.Ql \&.Fc
macros are parsed and are callable.
In the
.Sx SYNOPSIS
section, the function will always begin at
the beginning of line.
If there is more than one function
presented in the
.Sx SYNOPSIS
section and a function type has not been