generic.mex

操作系统SunOS 4.1.3版本的源码

.\" @(#)generic.mex 1.1 92/07/30 SMI;
.PL RIGHT
.H C "Generic Format \(em Sections 1, 6, 7 and 8"
.H 2 \s-1ORDERING\s0
.LP
.IX ordering
.IX "man pages" ordering
Here is a list of the of section
headings in their proper order.
All of the sections follow this order,
but where a heading is not needed,
it is not used.
For example,
if there are no bugs to report for a command,
there is no need for a
.SM BUGS
Section.
.RS
.\" CHECK THIS IF ERROR
.RS
.IP
.nf
.SM NAME
\s-1CONFIGURATION\s+1 (\fISection 4 only\fP)
.SM SYNOPSIS
.SM "SYSTEM V SYNOPSIS"
\s-1PROTOCOL\s+1 (\fISection 3R only\fP)
.SM AVAILABILITY
.SM DESCRIPTION
.SM "SYSTEM V DESCRIPTION"
\s-1IOCTLS\s+1 (\fISection 4 only\fP)
.SM OPTIONS
.SM "SYSTEM V OPTIONS"
\s-1RETURN VALUE\s+1 (\fISections 2 and 3 only\fP)
\s-1ERRORS\s+1 (\fISections 2, 3, and 4 only\fP)
.SM USAGE
.sp .5
.RS
.nf
Commands
Modifiers
Variables
Expressions
Input Grammar
.RE
.sp .5
.nf
.SM EXAMPLE(S)
.SM ENVIRONMENT
.SM FILES
.SM "SEE ALSO"
.SM DIAGNOSTICS
.SM WARNINGS
.SM NOTES
.SM BUGS
.fi
.RE
.RE
.LP
.I Note :
the
.SM USAGE
heading frequently contains subsections (listed with
.L \&.SS ).
.LP
.IX "introduction to manual pages" "" "" "" PAGE END
The specifications in these headings vary slightly from section
to section; the differences are
covered in the section descriptions below.
.LP
These sections of the man pages
describe general utility commmands
(Section 1), Games and Demos
(Section 6),
.SM TROFF
Macros and Miscellaneous Tables (Section 7),
and Maintenance Commands (Section 8).
Pages are listed in alphabetic order
within each section.
.LP
Sections 1 and 8 contain the following subsections:
.LP
Section 1
.IP 1 7
.PD 0
Standard SunOS Commands.
.IP 1C
Commands for communication with other systems.
.IP 1G
Commands used primarily for graphics and computer-aided design.
.IP 1V
Commands that behave differently under the System V environment.
.IP 1W
Commands for window\-related pages.
.PD
.LP
Section 8
.IP 8 7
.PD 0
General maintenance commands.
.IP 8C
Maintenance commands for communication with other systems.
.IP 8S
Standalone and diagnostic commands
.IP 8V
Maintenance commands for use with the System V environment.
.PD
.br
.H 2 \s-1HEADING\s0
.PD
.LP
The following section headings can appear
in the man pages for Sections 1, 6, 7 and 8:
.RS
.RS
.IP
.nf
.SM NAME
.SM SYNOPSIS
.SM "SYSTEM V SYNOPSIS"
.SM AVAILABILITY
.SM DESCRIPTION
.SM "SYSTEM V DESCRIPTION"
.SM OPTIONS
.SM "SYSTEM V OPTIONS"
.SM USAGE
.sp .5
.RS
.nf
Commands
Modifiers
Variables
Expressions
Input Grammar
.RE
.sp .5
.nf
.SM EXAMPLE(S)
.SM ENVIRONMENT
.SM FILES
.SM "SEE ALSO"
.SM DIAGNOSTICS
.SM WARNINGS
.SM NOTES
.SM BUGS
.fi
.RE
.RE
.LP
Enter these headings with .SH, as in the following examples:
.L
.RS
.nf
\&.SH SYNOPSIS
\fRor\fL
\&.SH "SEE ALSO"
.R
.RE
.LP
Label machine-dependent differences, or separate differences
related to more than one command on the page, with the .SS
macro:
.L
.RS
.nf
\&.SH OPTIONS
\&.SS egrep
\&...
\&.SS fgrep
\&...
.RE
.R
.LP
The following are specifications for Sections 1, 6, 7 and 8
of the man pages.  Remember, use only the headings required.
.H 2 "\s-1PAGE HEADING\s0"
.LP
The first line of each man page begins with the
.L \&.TH
macro, followed by the man page title.
This macro creates the page heading.
The following is an example for the first line of the
.L open(2V)
title page.
.sp .5
.RS
.RS
.L "\&.TH OPEN 2V \"20 November 1987\""
.RE
.RE
.sp .5
.H 2 "\s-1NAME\s0"
.LP
.IP \*(SQ 2
List the command, followed by
a brief summary of what it does.
.IP \*(SQ 2
Name of page (command or game) in all lower-case Roman,
separated from the summary by
.L \e- ' `
(en-dash).
When one page describes more than one command,
put all commands in a comma-separated
list preceding the
.L \e- '. `
Include all commands documented in the
.SM SYNOPSIS
section in a list.
.IP \*(SQ 2
Do not include
.SM RETURN
characters.
.IP \*(SQ 2
Do not include font or point size changes.
.IP \*(SQ 2
Make the Summary a brief statement,
.I not
a sentence, containing the minimal number of words:
.PD
.IP
.RS
.RS
echo \- echo argument to the standard output
.RE
.RE
.IP \*(SQ 2
.PD 0
Because
.L pix
(an indexing script) marks the words on this line
to generate index entries, unnecessary words here
generate unnecessary index entries.
.H 2 \s-1SYNOPSIS\s0
.LP
.PD 0
.IP \*(SQ 2
Show a listing of the command or game with
commands, options, and variables
shown exactly as they are to be entered.
.IP \*(SQ 2
Put literal characters (commands, options,
etc.) in Bold font, exactly as they should
be entered.
.IP \*(SQ 2
Put variables (arguments, parameters, and
substitution characters) in Italic font.
Use a descriptive term,
such as
.IR filename ,
.IR directory ,
or
.I string
to represent the variable.
.IP \*(SQ 2
Place ellipses (...) after variables that
can be repeated.
.IP \*(SQ 2
Place optional arguments in
\(lq[\|]\(rq (brackets).
.IP \*(SQ 2
Separate mutually exclusive arguments,
mandatory or optional, with a `|' (pipe).
The following example shows a Synopsis line for a
command with mutually exclusive optional arguments:
.PD
.IP
.RS
.RS
.BR mesg " [" n | y ]
.RE
.RE
.IP \*(SQ 2
List mutually exclusive synopses
alphabetically, and separate with
.L \&.br :
.PD
.IP
.RS
.RS
.B "cpio \-i"
[
.I options
]
.br
.B "cpio \-p"
[
.I options
]
.I directory
.RE
.RE
.IP \*(SQ 2
When one page lists more than one command,
separate the synopses with
.L \&.LP :
.IP
.RS
.RS
.B "at \-l"
[
.I jobs
\|.\|.\|. ]
.br
.B "at \-r"
.I jobs
\|.\|.\|.
.br
.B at
[
.B \-csm
]
.I time
[
.I date
]
[ +
.I increment
]
[
.I script
]
.IP
.B batch
[
.B \-csm
]
[
.I script
]
.RE
.RE
.br
.ne 30
.H 3 Ordering
.IP \*(SQ 2
.PD 0
Required, literal arguments are listed first,
either single letters, numbers, or
complete words.
.IP \*(SQ 2
List literal, single letter options (no arguments) next.
List them alphabetically, followed by options that are
complete words (again, no arguments).
.IP \*(SQ 2
Options with arguments then follow, single letters first,
then complete words
.IP \*(SQ 2
Variable options are then followed by required variable
arguments.
.PD
.IP
.RS
.RS
.B "command \-d"
|
.B \-e
[
.B \-bfs
]
[
.B \-k
.I key
]
[
.B \-dryrun
]
.I filename
.RE
.RE
.IP
where
.B command
is the command,
either
.B \-d
or
.B \-e
is required,
[
.B \-bfs
]
and
.br
.\" The above .br is a micro-adjustment.  If it becomes annoying, destroy it.
[
.B \-dryrun
]
are options.
.IP
.RS
.RS
.br
.ne 7
.I "Note" :
.B \-bfs
is a
list of single-character options;
.B \-b ,
.B \-f,
and
.B \-s
can be used separately or together.  In contrast,
options which take the form of a
.I "mnemonic word" ,
such as
[
.B \-dryrun
]
must be in a separate set of brackets.
.sp
.RE
.RE
[
.B \-k
.I key
]
is an option with an argument.
.br
.I filename
is a required variable argument.
.IP \*(SQ 2
Always maintain the original spacing between
options and arguments
.IP
.RS
.RS
input:
.RS
.ftL
[
.br
\&.BI \e\-f
" filename"
.br
]
.ftP
.RE
output:
.RS
.IP
[
.BI \-f " filename"
]
.sp
.RE
.I Note:
If a space is needed between arguments, put it
.I within
the double quotes which separate those arguments
(as shown
above).
.RE
.RE
.br
.ne 8
.H 2 \s-1AVAILABILITY\s0
.IP \*(SQ 2
Any limitations on the availability of the command are
listed here in concise, complete
sentences.
.H 2 "\s-1DESCRIPTION\s0"
.LP
.H 3 "\s-1[SYSTEM V DESCRIPTION]\s0"
.LP
.PD 0
.IP \*(SQ 2
Describe concisely what the command
.I does .
.IP \*(SQ 2
Do not discuss
.SM OPTIONS ,
cite
.SM EXAMPLES ,
or explain why or how the command works.
.IP \*(SQ 2
Always use complete grammatical sentences.
.IP \*(SQ 2
Always use
.I active
voice.  The command
doesn't "cause to do,"
it
.I does .
.IP \*(SQ 2
Use the third person to describe the
action using the command as the subject.
.PD
.IP
.RS
.RS
.B file
performs a series of tests on each
.I filename,
in an attempt to determine what it contains.
.RE
.RE
.IP \*(SQ 2
Interactive commands, subcommands, requests, macros,
functions, etc., are described under
.SM USAGE.
.br
.ne 10v
.H 2 "\s-1OPTIONS\s0"
.LP
.H 3 "\s-1[SYSTEM V OPTIONS]\s0"
.LP
.PD 0
.IP \*(SQ 2
List the command's options with a concise summary of what
each does.
.IP \*(SQ 2
List alphabetically using
.L \.TP
unless the command requires that options
and argumments not be in alphabetical order.
Arrange options as they appear on the
.SM SYNOPSIS
line.
.IP \*(SQ 2
Show options literally, that is,
with a
.L \- ' `
if one is required, or with a
non-literal argument (even if the argument is
optional)
.PD
.TS
lB l.
\-b     literal option
\-c [ \fIstring\fP ]    T{
literal option with argument
T}
\-k [ \fIkey\fP ]       T{
literal option with optional argument
T}
.TE
.IP \*(SQ 2
Option descriptions must be in complete
grammatical sentences in the imperative voice.
The first sentence may be a mnemonic,
but subsequent sentences should be complete:
.IP
.RS
.RS
.B \-v "       \fRVerbose.  Display detailed progress reports.\fP"
.RE
.RE
.H 2 \s-1USAGE\s0
.LP
.PD 0
.IP \*(SQ 2
This section lists special rules, features, and
commands that require in-depth explanations (and
are thereby excluded from the
.SM DESCRIPTION
section)
.IP \*(SQ 2
The
following are listed as sub-sections
and are used to explain built-in functionality.
.PD
.IP
.DS
Commands
Modifiers
Variables
Expressions
Input Grammar
.DE
.H 2 \s-1EXAMPLE(S)\s0
.LP
.PD 0
.IP \*(SQ 2
Give examples of how to use the command or function.
.IP \*(SQ 2
Always introduce an example, especially
when it is referred to elsewhere
on the page.
.IP \*(SQ 2
Always show a
.I complete
example, where possible.
Include command line entry, machine
response (even if only a returned prompt), and,
where necessary, a return code.
.IP \*(SQ 2
When a prompt is shown, use
.B example% .
.IP \*(SQ 2
Follow examples with any necessary explanations,
or variable substitution rules, or returned values.
.IP \*(SQ 2
Use this section to illustrate concepts from the
.SM SYNOPSIS ,
.SM DESCRIPTION ,
.SM OPTIONS
and
.SM USAGE
sections.
Do not introduce new information here.
.PD
.H 2 \s-1ENVIRONMENT\s0
.LP
.PD 0
.IP \*(SQ 2
List any environment variables that the command or function affects,
followed by a brief description of the effect.
.IP \*(SQ 2
List environment variables with
.L .SB ,
separated by
.L .TP .
.PD
.H 2 \s-1FILES\s0
.LP
.H 3 "\s-1[SYSTEM V FILES]\s0"
.LP
.PD 0
.IP \*(SQ 2
List of all the
files mentioned on page (except those
mentioned in
.SM EXAMPLES\s0).
.IP \*(SQ 2
A brief explanation may be included.
.br
.ne 8
.IP \*(SQ 2
Use the following format:
.sp .5
.RS
.RS
.nf
.ft L
\&.PD 0
\&.TP 20
\&.B \fIfilename\fP
.IR "file description" " (" "summary, not sentence" !)
.L \&.TP
.L \&.PD
.ft
.fi
.RE
.RE
.sp .5
If the filename extends beyond the indentation,
increase by 5s, within reason.
.IP \*(SQ 2
.L /usr/bin5
are System V files
.PD
.H 2 "\s-1SEE ALSO\s0"
.LP
.H 3 "Man Pages"
.LP
.PD 0
.IP \*(SQ 2
Use a comma\-separated list to show the pages referenced
along with others that are relevant
(excluding those in EXAMPLES).
.IP \*(SQ 2
Alphabetize commands according to sections
(ignoring subsection suffixes \(em C,V, etc.).
All suffixes are capitalized.
.IP \*(SQ 2
List man page in Bold font, section number in Roman font.
.IP \*(SQ 2
Do not end with a
.L . ' `
(period).
.PD
.H 3 "Sun Manuals"
.LP
.PD 0
.IP \*(SQ 2
Separate from man pages with
.L \&.LP .
.IP \*(SQ 2
Separate from other books/articles with
.L \&.br .
.IP \*(SQ 2
List in-house documentation by title.
Since chapter titles frequently change, reference them by supplying
arguments to the
.SM .TX
macro.
Titles and abbreviations are listed in Appendix D
of this document.
.PD
.IP
.br
.ne 10
.RS
.RS
.RS
.IP input:
.L ".TX SVBG"
.IP output:
.TX SVBG
.RE
.RE
.RE
.H 3 "Other Publications"
.IP \*(SQ 2
List outside publications by author (Roman), title
(Italics, no quotes), holder (Roman) and
publisher (Roman).
.PD
.IP
.ft R
Sollins, K.R., (\fIThe TFTP Protocol Revision 2\fR), RFC 783, Network Information
Center, SRI International, Menlo Park, Calif., June 1981.
.ft
.H 2 \s-1DIAGNOSTICS\s0
.LP
.PD 0
.IP \*(SQ 2
This section contains additional information which may be helpful.
.IP \*(SQ 2
List diagnostic messages as they would appear,
in Bold font with Italic font variables, separated
by
.L \&.TP .
.IP \*(SQ 2
Explain diagnostic in complete sentences.
.IP \*(SQ 2
Combine with
.SM WARNINGS
where appropriate.
.PD
.RE
.H 2 \s-1WARNINGS\s0
.LP
.PD 0
.IP \*(SQ 2
A list of warnings about special conditions,
not a list of
.SM DIAGNOSTICS.
.IP \*(SQ 2
The section header,
.SM CAVEATS
should be changed to
.SM WARNINGS.
.PD
.RE
.br
.ne 8
.H 2 \s-1NOTES\s0
.PD 0
.IP \*(SQ 2
List information of interest that does not belong
anywhere else.
.IP \*(SQ 2
This section should take the form of an `aside' to the user,
covering points of special interest.
Critical information should
.I not
be given here; it should be noted in the
.SM SYNOPSIS
or
.SM DESCRIPTION
sections depending on its form.
.IP \*(SQ 2
Notes are separated by
.L .LP .
.H 2 \s-1BUGS\s0
.PD 0
.IP \*(SQ 2
List all known bugs.
If there is a known workaround,
suggest it here.
.IP \*(SQ 2
Separate bugs with
.L .LP .
.IP \*(SQ 2
Be descriptive.
.IP \*(SQ 2
Do not editorialize!
.IP \*(SQ 2
Do not use slang.