-.\" $Id: man.7,v 1.79 2010/07/22 23:03:15 kristaps Exp $
+.\" $Id: man.7,v 1.88 2010/09/04 17:22:41 kristaps Exp $
.\"
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: July 22 2010 $
+.Dd $Mdocdate: September 4 2010 $
.Dt MAN 7
.Os
.Sh NAME
attribute is forgotten when entering or exiting a macro block.
.Ss Whitespace
Whitespace consists of the space character.
-In free-form lines, whitespace is preserved within a line; un-escaped
+In free-form lines, whitespace is preserved within a line; unescaped
trailing spaces are stripped from input (unless in a literal context).
Blank free-form lines, which may include spaces, are permitted and
rendered as an empty line.
which, if a unit is not provided, will instead interpret the string as
literal text.
.Ss Sentence Spacing
-When composing a manual, make sure that your sentences end at the end of
+When composing a manual, make sure that sentences end at the end of
a line.
By doing so, front-ends will be able to apply the proper amount of
spacing after the end of sentence (unescaped) period, exclamation mark,
or question mark followed by zero or more non-sentence closing
-delimiters (
-.Ns Sq \&) ,
+delimiters
+.Po
+.Sq \&) ,
.Sq \&] ,
.Sq \&' ,
-.Sq \&" ) .
+.Sq \&"
+.Pc .
.Sh MANUAL STRUCTURE
Each
.Nm
-document must contain contains at least the
+document must contain the
.Sx \&TH
macro describing the document's section and title.
-It may occur anywhere in the document, although conventionally, it
+It may occur anywhere in the document, although conventionally it
appears as the first macro.
.Pp
Beyond
\&.TH FOO 1 2009-10-10
\&.SH NAME
\efBfoo\efR \e(en a description goes here
-\&.\e\*q The next is for sections 2 & 3 only.
\&.\e\*q .SH LIBRARY
+\&.\e\*q For sections 2 & 3 only.
+\&.\e\*q Not used in OpenBSD.
\&.SH SYNOPSIS
\efBfoo\efR [\efB\e-options\efR] arguments...
\&.SH DESCRIPTION
The \efBfoo\efR utility processes files...
\&.\e\*q .SH IMPLEMENTATION NOTES
-\&.\e\*q The next is for sections 2, 3, & 9 only.
\&.\e\*q .SH RETURN VALUES
-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.
\&.\e\*q .SH ENVIRONMENT
+\&.\e\*q For sections 1, 6, 7, & 8 only.
\&.\e\*q .SH FILES
-\&.\e\*q The next is for sections 1 & 8 only.
\&.\e\*q .SH EXIT STATUS
+\&.\e\*q For sections 1, 6 & 8 only.
\&.\e\*q .SH EXAMPLES
-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
\&.\e\*q .SH DIAGNOSTICS
-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q For sections 1, 4, 6, 7, & 8 only.
\&.\e\*q .SH ERRORS
+\&.\e\*q For sections 2, 3, & 9 only.
\&.\e\*q .SH SEE ALSO
\&.\e\*q .BR foo ( 1 )
\&.\e\*q .SH STANDARDS
\&.\e\*q .SH CAVEATS
\&.\e\*q .SH BUGS
\&.\e\*q .SH SECURITY CONSIDERATIONS
+\&.\e\*q Not used in OpenBSD.
.Ed
.Pp
The sections in a
This is useful when implementing standard functions that may have side
effects or notable algorithmic implications.
.It Em RETURN VALUES
-This section is the dual of
-.Em EXIT STATUS ,
-which is used for commands.
-It documents the return values of functions in sections 2, 3, and 9.
+This section documents the return values of functions in sections 2, 3, and 9.
.It Em ENVIRONMENT
Documents any usages of environment variables, e.g.,
.Xr environ 7 .
It's helpful to document both the file name and a short description of how
the file is used (created, modified, etc.).
.It Em EXIT STATUS
-Command exit status for section 1, 6, and 8 manuals.
-This section is the dual of
-.Em RETURN VALUES ,
-which is used for functions.
+This section documents the command exit status for
+section 1, 6, and 8 utilities.
Historically, this information was described in
.Em DIAGNOSTICS ,
a practise that is now discouraged.
Example usages.
This often contains snippets of well-formed,
well-tested invocations.
-Make doubly sure that your examples work properly!
+Make sure that examples work properly!
.It Em DIAGNOSTICS
Documents error conditions.
This is most useful in section 4 manuals.
.Em HISTORY
section should be used.
.It Em HISTORY
-The history of any manual without a
-.Em STANDARDS
-section should be described in this section.
+A brief history of the subject, including where support first appeared.
.It Em AUTHORS
-Credits to authors, if applicable, should appear in this section.
+Credits to the person or persons who wrote the code and/or documentation.
Authors should generally be noted by both name and email address.
.It Em CAVEATS
Common misuses and misunderstandings should be explained
in this section.
.It Em BUGS
-Known bugs, limitations and work-arounds should be described
+Known bugs, limitations, and work-arounds should be described
in this section.
.It Em SECURITY CONSIDERATIONS
Documents any security precautions that operators should consider.
.El
.Sh MACRO SYNTAX
-Macros are one to three three characters in length and begin with a
+Macros are one to three characters in length and begin with a
control character,
.Sq \&. ,
at the beginning of the line.
.Nm
manuals.
.Ss Block Macros
-Block macros are comprised of a head and body.
-Like for in-line macros, the head is scoped to the current line and, in
+Block macros comprise a head and body.
+As with in-line macros, the head is scoped to the current line and, in
one circumstance, the next line (the next-line stipulations as in
.Sx Line Macros
apply here as well).
and
.Sx \&r .
.Ss \&IB
-Text is rendered alternately in italics and bold face. Whitespace
-between arguments is omitted in output.
+Text is rendered alternately in italics and bold face.
+Whitespace between arguments is omitted in output.
.Pp
See
.Sx \&BI
The
.Cm width
argument defines the width of the left margin and is defined by
-.Sx Scaling Widths ,
+.Sx Scaling Widths .
It's saved for later paragraph left-margins; if unspecified, the saved or
default width is used.
.Pp
.Pp
.Bl -dash -compact
.It
-The \es (font size), \em (font colour), and \eM (font filling colour)
-font decoration escapes are all discarded in mandoc.
-.It
In quoted literals, GNU troff allowed pair-wise double-quotes to produce
a standalone double-quote in formatted output.
It is not known whether this behaviour is exhibited by other formatters.
.It
+troff suppresses a newline before
+.Sq \(aq
+macro output; in mandoc, it is an alias for the standard
+.Sq \&.
+control character.
+.It
+The
+.Sq \eh
+.Pq horizontal position ,
+.Sq \ev
+.Pq vertical position ,
+.Sq \em
+.Pq text colour ,
+.Sq \eM
+.Pq text filling colour ,
+.Sq \ez
+.Pq zero-length character ,
+.Sq \ew
+.Pq string length ,
+.Sq \ek
+.Pq horizontal position marker ,
+.Sq \eo
+.Pq text overstrike ,
+and
+.Sq \es
+.Pq text size
+escape sequences are all discarded in mandoc.
+.It
+The
+.Sq \ef
+scaling unit is accepted by mandoc, but rendered as the default unit.
+.It
The
.Sx \&sp
macro does not accept negative values in mandoc.
In GNU troff, this would result in strange behaviour.
-.It
-The
-.Sq \(aq
-macro control character, in GNU troff (and prior troffs) suppresses a
-newline before macro output; in mandoc, it is an alias for the standard
-.Sq \&.
-control character.
.El
.Sh SEE ALSO
.Xr mandoc 1 ,
The stand-alone implementation that is part of the
.Xr mandoc 1
utility written by Kristaps Dzonsons appeared in
-.Ox 4.6.
+.Ox 4.6 .
.Sh AUTHORS
This
.Nm
git.ckatri.com / mandoc.git / blobdiff