mdoc.samples.7

早期freebsd实现

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
.Sx SYNOPSIS
section.
It may be used
anywhere else in the man page without problems, but its main purpose
is to present the function type in kernel normal form for the
.Sx 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
.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 , unsetenvxx" -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 is parsed 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 parsed and is callable.
.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
.Sx NAME
section, and with
.Ql \&.Fn
in the
.Sx 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 \e-mdoc
.Nm \-mdoc .
.It Li \&.Nm foo\ )\ )\ ,
.Nm foo ) ) ,
.It Li \&.Nm
.Nm
.El
.Pp
The
.Ql \&.Nm
macro is parsed and is callable.
.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 parsed and are callable.
.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 parsed and is callable.
.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 parsed and is callable.
.Ss Manual Page 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 man_page [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 parsed and is callable.
It is an error to call
.Ql \&.Xr
without
any arguments.
.Sh GENERAL TEXT DOMAIN
.Ss AT&T Macro
.Bd -literal -offset indent -compact
Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \*(Pu
.Ed
.Bl -tag -width ".At v6 ) ," -compact -offset 14n
.It Li ".At"
.At
.It Li ".At v6 ."
.At v6 .
.El
.Pp
The
.Ql \&.At
macro is
.Em not
parsed and
.Em not
callable. It accepts at most two arguments.
.Ss BSD Macro
.Dl Usage: .Bx [Version/release] ... \*(Pu
.Bl -tag -width ".Bx 4.3 ) ," -compact -offset 14n
.It Li ".Bx"
.Bx
.It Li ".Bx 4.3 ."
.Bx 4.3 .
.El
.Pp
The
.Ql \&.Bx
macro is parsed and is callable.
.Ss UNIX Macro
.Dl Usage: .Ux ... \*(Pu
.Bl -tag -width ".Ux 4.3 ) ," -compact -offset 14n
.It Li ".Ux"
.Ux
.El
.Pp
The
.Ql \&.Ux
macro is parsed and is callable.
.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 STRUCTURE DOMAIN .
.\" .Pp
.\" .Bf -emphasis
.\" We are certain the reason most people desire a Harvard MBA
.\" so they can become to be successful philanthropists.  Only
.\" mathematicians and physicists go to graduate school strictly
.\" to acquire infinite wealthy and fame. Its that inifinity
.\" word that does it to them. Ruins them.
.\" .Ef
.Pp
The
.Ql \&.Em
macro is parsed and is callable.
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 being to enclose one or more strings between
a pair of characters like quotes or parentheses.
The terms quoting and enclosure are used
interchangeably throughout this document.
Most of the
one line enclosure macros end
in small letter
.Ql q
to give a hint of quoting, but there are a few irregularities.
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 have nesting limitations, the one line quote macros
can be used inside
of them.
.Pp
.ne 5
.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
\&.Pq	.Pc	.Po	Parenthesis Enclosure	(string)
\&.Ql			Quoted Literal	`st' or string
\&.Qq	.Qc	.Qo	Straight Double Quote	"string"
\&.Sq	.Sc	.So	Single Quote	`string'
.El
.Ed
.Pp
Except for the irregular macros noted below, all
of the quoting macros are parsed and callable.
All handle punctuation properly, as long as it
is presented one character at a time and separated by spaces.
The quoting macros examine opening and closing punctuation
to determine whether it comes before or after the
enclosing string. This makes some nesting possible.
.Bl -tag -width xxx,xxxx
.It Li \&.Ec , \&.Eo
These macros expect the first argument to be the
opening and closing strings respectively.
.It Li \&.Ql
The quoted literal macro behaves differently for
.Xr troff
than
.Xr nroff .
If formatted with
.Xr nroff ,
a quoted literal is always quoted. If formatted with
troff, an item is only quoted if the width
of the item is less than three constant width characters.
This is to make short strings more visible where the font change
to literal (constant width) is less noticeable.
.It Li \&.Pf
The prefix macro is not callable, but it is parsed:
.Bl -tag -width "(namexx" -offset indent
.It Li ".Pf ( Fa name2"
becomes
.Pf ( Fa name2 .
.El
.Pp
The
.Ql \&.Ns
(no space) macro performs the analogous suffix function.
.El
.Pp
.ne 4
Examples of quoting:
.Bl -tag -width ".Aq Pa ctype.h ) ,xxxxxxxx" -compact -offset indent
.It Li \&.Aq
.Aq
.It Li \&.Aq \&Ar ctype.h\ )\ ,
.Aq Ar ctype.h ) ,
.It Li \&.Bq
.Bq
.It Li \&.Bq \&Em Greek \&, French \&.
.Bq Em Greek , French .
.It Li \&.Dq
.Dq
.It Li ".Dq string abc ."
.Dq string abc .
.It Li ".Dq \'^[A-Z]\'"
.Dq \'^[A-Z]\'
.It Li "\&.Ql man mdoc"
.Ql man mdoc
.It Li \&.Qq
.Qq
.It Li "\&.Qq string ) ,"
.Qq string ) ,
.It Li "\&.Qq string Ns ),"
.Qq string Ns ),
.It Li \&.Sq
.Sq
.It Li "\&.Sq string
.Sq string
.El
.Pp
For a good example of nested enclosure macros, see the
.Ql \&.Op
option macro.
It was created from the same
underlying enclosure macros as those presented in the list
above.
The
.Ql \&.Xo
and
.Ql \&.Xc
extended argument list macros
were also built from the same underlying routines and are a good
example of
.Nm \-mdoc
macro usage at its worst.
.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 directoryxx" -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 parsed and is callable.
.Ss Section Cross References
The
.Ql \&.Sx
macro designates a reference to a section header
within the same document.
It is parsed and is callable.
.Pp
.Bl -tag -width "Li \&.Sx FILES" -offset 14n
.It Li \&.Sx FILES
.Sx FILES
.El
.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 Noticex" -compact -offset 14n
.It Li \&.Sy Important Notice
.Sy Important Notice
.El
.Pp
The
.Ql \&.Sy
macro is parsed and is callable.
Arguments to
.Ql \&.Sy
may be quoted.
.Ss References and Citations
The following macros make a modest attempt to handle references.
At best, the macros make it convenient 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 ".\&%C"
City/place.
.It Li ".\&%D"
Date.
.It Li ".%J"
Journal name.
.It Li ".%N"
Issue number.
.It Li ".%O"
Optional information.
.It Li ".%P"
Page number.
.It Li ".%R"
Report name.
.It Li ".%T"
Title of article.
.It Li ".%V"
Volume(s).
.El
.Pp
The macros beginning with
.Ql %
are not callable, and are parsed only for the trade name macro which
returns to its caller.
(And not very predictably at the moment either.)
The purpose is to allow trade names
to be pretty printed in
.Xr troff Ns / Ns Xr ditroff
output.
.Ss Trade Names (or Acronyms and Type Names)
The trade name macro is generally a small caps macro for
all upper case words longer than two characters.
.Pp
.Dl Usage: .Tn symbol ... \*(Pu
.Bl -tag -width ".Tn ASCII" -compact -offset 14n
.It Li \&.Tn DEC
.Tn DEC