mdoc.samples.7

早期freebsd实现

.\" Copyright (c) 1990, 1993
.\"	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	8.2 (Berkeley) 12/30/93
.\"
.\" This tutorial sampler invokes every macro in the package several
.\" times and is guaranteed to give a worst case performance
.\" for an already extremely slow package.
.\"
.Dd December 30, 1993
.Os
.Dt MDOC.SAMPLES 7
.Sh NAME
.Nm mdoc.samples
.Nd tutorial sampler for writing
.Bx
manuals with
.Nm \-mdoc
.Sh SYNOPSIS
.Nm man mdoc.samples
.Sh DESCRIPTION
A tutorial sampler for writing
.Bx
manual pages with the
.Nm \-mdoc
macro package, a
.Em content Ns \-based
and
.Em domain Ns \-based
formatting
package for
.Xr troff 1 .
Its predecessor, the
.Xr \-man 7
package,
addressed page layout leaving the
manipulation of fonts and other
typesetting details to the individual author.
In
.Nm \-mdoc ,
page layout macros
make up the
.Em "page structure domain"
which consists of macros for titles, section headers, displays
and lists. Essentially items which affect the physical position
of text on a formatted page.
In addition to the page structure domain, there are two more domains,
the manual domain and the general text domain.
The general text domain is defined as macros which
perform tasks such as quoting or emphasizing pieces of text.
The manual domain is defined as macros that are a subset of the
day to day informal language used to describe commands, routines
and related
.Bx
files.
Macros in the manual domain handle
command names, command line arguments and options, function names,
function parameters, pathnames, variables, cross
references to other manual pages, and so on.
These domain
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
Throughout the
.Ux
manual pages, a manual entry
is simply referred
to as a man page, regardless of actual length and without
sexist intention.
.Sh GETTING STARTED
Since a tutorial document is normally read when a person
desires to use the material immediately, the assumption has
been made that the user of this document may be impatient.
The material presented in the remained of this document is
outlined as follows:
.Bl -enum -offset indent
.It
.Tn "TROFF IDIOSYNCRASIES"
.Bl -tag -width flag -compact -offset indent
.It "Macro Usage" .
.It "Passing Space Characters in an Argument" .
.It "Trailing Blank Space Characters (a warning)" .
.It "Escaping Special Characters" .
.El
.It
.Tn "THE ANATOMY OF A MAN PAGE"
.Bl -tag -width flag -compact -offset indent
.It "A manual page template" .
.El
.It
.Tn "INTRODUCTION OF TITLE MACROS" .
.It
.Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" .
.Bl -tag -width flag -compact -offset indent
.It "What's in a name..." .
.It "General Syntax" .
.El
.It
.Tn "MANUAL DOMAIN"
.Bl -tag -width flag -compact -offset indent
.It "Addresses" .
.It "Arguments" .
.It "Configuration Declarations (section four only)" .
.It "Command Modifier .
.It "Defined Variables" .
.It "Errno's (Section two only)" .
.It "Environment Variables" .
.It "Function Argument" .
.It "Function Declaration" .
.It "Flags" .
.It "Functions (library routines)" .
.It "Function Types" .
.\" .It "Header File (including source code)" .
.It "Interactive Commands" .
.It "Literals" .
.It "Names" .
.It "Options" .
.It "Pathnames" .
.It "Variables" .
.It "Cross References" .
.El
.It
.Tn "GENERAL TEXT DOMAIN"
.Bl -tag -width flag -compact -offset indent
.It "AT&T Macro" .
.It "BSD Macro" .
.It "UNIX Macro" .
.It "Emphasis Macro" .
.It "Enclosure/Quoting Macros"
.Bl -tag -width flag -compact -offset indent
.It "Angle Bracket Quote/Enclosure" .
.It "Bracket Quotes/Enclosure" .
.It "Double Quote macro/Enclosure" .
.It "Parenthesis Quote/Enclosure" .
.It "Single Quotes/Enclosure" .
.It "Prefix Macro" .
.El
.It "Extended  Arguments" .
.It "No\-Op or Normal Text Macro" .
.It "No Space Macro" .
.It "Section Cross References" .
.It "Symbolic Macro" .
.It "References and Citations" .
.It "Trade Names (Acronyms and Type Names)" .
.El
.It
.Tn "PAGE STRUCTURE DOMAIN"
.Bl -tag -width flag -compact -offset indent
.It "Section Headers" .
.It "Paragraphs and Line Spacing" .
.It "Keeps" .
.It "Displays" .
.It "Lists and Columns" .
.El
.It
.Tn "PREDEFINED STRINGS"
.It
.Tn "DIAGNOSTICS"
.It
.Tn "FORMATTING WITH GROFF, TROFF AND NROFF"
.It
.Tn "BUGS"
.El
.ne 7
.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 invocation, precede the
.Ql \&\.
(dot) with the
.Ql \e&
escape sequence.
The
.Ql \e&
translates literally to a zero width space, and is never displayed in the
output.
.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 ) .
A few macros handle quoted arguments (see
.Sx Passing Space Characters in an Argument
below).
.Pp
Most of the
.Nm \-mdoc
general text domain and manual domain macros are special
in that their argument lists are
.Em parsed
for callable macro names.
This means an argument on the argument list which matches
a general text or manual domain macro name and is determined
to be callable will be executed
or called when it is processed.
In this case
the argument, although the name of a macro,
is not preceded by a
.Ql \&\.
(dot).
It is in this manner that many 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:
.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 "\&.Op \&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
Here the strings
.Ql \&Fl
and
.Ql \&Ar
are not interpreted as macros.
Macros whose argument lists are parsed for callable arguments
are referred to
as parsed and macros which may be called from an argument
list are referred to as callable
throughout this document and in the companion quick reference
manual
.Xr mdoc 7 .
This is a technical
.Em faux pas
as almost all of the macros in 
.Nm \-mdoc
are parsed, but as it was cumbersome to constantly refer to macros
as being callable and being able to call other macros,
the term parsed has been used.
.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 .
.Pp
There are two possible ways to pass an argument which contains
an embedded space.
.Em Implementation note :
Unfortunately, the most convenient way
of passing spaces in between quotes by reassigning individual
arguments before parsing was fairly expensive speed wise
and space wise to implement in all the macros for
.Tn AT&T
.Xr troff .
It is not expensive for
.Xr groff
but for the sake of portability, has been limited
to the following macros which need
it the most:
.Pp
.Bl -tag -width 4n -offset indent -compact
.It Li \&Cd
Configuration declaration (section 4
.Sx 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 preceded 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.
.Ss Trailing Blank Space Characters
.Xr Troff
can be confused by blank space characters at the end of a line.
It
is a wise preventive 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
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.template:
\&.\e" The following six lines are required.
\&.Dd Month day, year
\&.Os OPERATING_SYSTEM [version/release]
\&.Dt DOCUMENT_TITLE [section number] [volume]
\&.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 \&.Dd , \&.Os , \&.Dt ;
the document date,
the operating system the man page or subject source is developed
or modified for,
and the man page title
.Pq Em in upper case
along with the section of the manual the page
belongs in.
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
.Sx NAME ,
.Sx SYNOPSIS
and
.Sx DESCRIPTION
are mandatory.
The
headers are
discussed in
.Sx PAGE STRUCTURE DOMAIN ,
after
presentation of
.Sx MANUAL DOMAIN .
Several content macros are used to demonstrate page layout macros;
reading about content macros before page layout macros is
recommended.
.Sh TITLE MACROS
The title macros are the first portion of the page structure
domain, but are presented first and separate for someone who
wishes to start writing a man page yesterday.
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
.Tn 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 Programmer's Supplementary Documents
.Pp
.Bl -column SMM -offset indent -compact
.It Li AMD	UNIX Ancestral Manual Documents
.It Li SMM	UNIX System Manager's Manual
.It Li URM	UNIX Reference Manual
.It Li PRM	UNIX Programmer's Manual
.El
.Pp
The default volume labeling is
.Li URM
for sections 1, 6, and 7;
.Li SMM
for section 8;
.Li PRM
for sections 2, 3, 4, and 5.
.\" .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.
.Tn BSD
or
.Tn 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, a typical footer might be: