mdoc.samples.7

早期freebsd实现

.It Li \&.Tn ASCII
.Tn ASCII
.El
.Pp
The
.Ql \&.Tn
macro
is parsed and is callable by other macros.
.Ss Extended  Arguments
The
.Li \&.Xo
and
.Li \&.Xc
macros 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 .
.Pp
Here is an example of
.Ql \&.Xo
using the space mode macro to turn spacing off:
.Bd -literal -offset indent
\&.Sm off
\&.It Xo Sy I Ar operation
\&.No \een Ar count No \een
\&.Xc
\&.Sm on
.Ed
.Pp
Produces
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.Sm off
.It Xo Sy I Ar operation
.No \en Ar count No \en
.Xc
.Sm on
.El
.Ed
.Pp
Another one:
.Bd -literal -offset indent
\&.Sm off
\&.It Cm S No \&/ Ar old_pattern Xo
\&.No \&/ Ar new_pattern
\&.No \&/ Op Cm g
\&.Xc
\&.Sm on
.Ed
.Pp
Produces
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.Sm off
.It Cm S No \&/ Ar old_pattern Xo
.No \&/ Ar new_pattern
.No \&/ Op Cm g
.Xc
.Sm on
.El
.Ed
.Pp
Another example of
.Ql \&.Xo
and using enclosure macros:
Test the value of an variable.
.Bd -literal -offset indent
\&.It Xo
\&.Ic .ifndef
\&.Oo \e&! Oc Ns Ar variable
\&.Op Ar operator variable ...
\&.Xc
.Ed
.Pp
Produces
.Bd -filled -offset indent
.Bl -tag -width flag -compact
.It Xo
.Ic .ifndef
.Oo \&! Oc Ns Ar variable
.Op Ar operator variable ...
.Xc
.El
.Ed
.Pp
All of the above examples have used the
.Ql \&.Xo
macro on the argument list of the
.Ql \&.It
(list-item)
macro.
The extend macros are not used very often, and when they are
it is usually to extend the list-item argument list.
Unfortunately, this is also where the extend macros are the
most finicky.
In the first two examples, spacing was turned off;
in the third, spacing was desired in part of the output but
not all of it.
To make these macros work in this situation make sure
the
.Ql \&.Xo
and
.Ql \&.Xc
macros are placed as shown in the third example.
If the
.Ql \&.Xo
macro is not alone on the
.Ql \&.It
argument list, spacing will be unpredictable.
The
.Ql \&.Ns
(no space macro)
must not occur as the first or last macro on a line
in this situation.
Out of 900 manual pages (about 1500 actual pages)
currently released with
.Bx
only fifteen use the
.Ql \&.Xo
macro.
.Sh PAGE STRUCTURE DOMAIN
.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 discretion of the author
writing the manual page.
The
.Ql \&.Sh
macro can take up to nine arguments.
It is parsed and but is not callable.
.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
.Sx 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
.Sx SYNOPSIS
section describes the typical usage of the
subject of a man page.
The  macros required
are either
.Ql ".Nm" ,
.Ql ".Cd" ,
.Ql ".Fn" ,
(and possibly
.Ql ".Fo" ,
.Ql ".Fc" ,
.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
.Pp
.Sy Note :
The macros
.Ql \&.Op ,
.Ql \&.Fl ,
and
.Ql \&.Ar
recognize the pipe bar character
.Ql \*(Ba ,
so a command line such as:
.Pp
.Dl ".Op Fl a | Fl b"
.Pp
will not go orbital.
.Xr Troff
normally interprets a \*(Ba as a special operator.
See
.Sx PREDEFINED STRINGS
for a usable \*(Ba
character in other situations.
.It \&.Sh DESCRIPTION
In most cases the first text in the
.Sx 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
.Sx ENVIRONMENT
section should reveal any related
environment
variables and clues to their behavior and/or usage.
.It \&.Sh EXAMPLES
There are several ways to create examples.
See
the
.Sx 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
.Sx 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
.Sx 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
.St -p1003.2
or
.St -ansiC
this should be noted here.
If the
command does not adhere to any standard, its history
should be noted in the
.Sx 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
.\" This worked with version one, need to redo for version three
.\" .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 Keeps
The only keep that is implemented at this time is for words.
The macros are
.Ql \&.Bk
(begin-keep)
and
.Ql \&.Ek
(end-keep).
The only option that
.Ql \&.Bl
accepts is
.Fl words
and is useful for preventing line breaks in the middle of options.
In the example for the make command line arguments (see
.Sx What's in a name ) ,
the keep prevented
.Xr nroff
from placing up the
flag and the argument
on separate lines.
(Actually, the option macro used to prevent this from occurring,
but was dropped when the decision (religious) was made to force
right justified margins in
.Xr troff
as options in general look atrocious when spread across a sparse
line.
More work needs to be done with the keep macros, a
.Fl line
option needs to be added.)
.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 ,
and 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 \&.Dlxx
.It Li \&.D1
(D-one) Display one line of indented text.
This macro is parsed, but it is not callable.
.Pp
.Dl Fl ldghfstru
.Pp
The above was produced by:
.Li \&.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
it is parsed and will recognized other macros.
It is not callable however.
.Pp
.Dl % ls -ldg /usr/local/bin
.Pp
The above was produced by
.Li \&.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] [-compact]"
.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 "file file_name  " -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 unjustified).
.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.