===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.78
retrieving revision 1.97
diff -u -p -r1.78 -r1.97
--- mandoc/man.7	2010/07/19 23:21:39	1.78
+++ mandoc/man.7	2011/01/25 00:40:14	1.97
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.78 2010/07/19 23:21:39 schwarze Exp $
+.\"	$Id: man.7,v 1.97 2011/01/25 00:40:14 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 19 2010 $
+.Dd $Mdocdate: January 25 2011 $
 .Dt MAN 7
 .Os
 .Sh NAME
@@ -53,12 +53,12 @@ Other lines are interpreted within the current state.
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the
 space character, and the tab character.
-All manuals must have
-.Ux
-line termination.
 .Pp
 Blank lines are acceptable; where found, the output will assert a
 vertical space.
+.Pp
+If the first character of a line is a space, that line is printed
+with a leading newline.
 .Ss Comments
 Text following a
 .Sq \e\*q ,
@@ -111,7 +111,7 @@ The
 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.
@@ -190,23 +190,25 @@ this differs from
 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
@@ -217,25 +219,27 @@ Documents are generally structured as follows:
 \&.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 Not used in OpenBSD.
 \&.\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
@@ -244,6 +248,7 @@ The \efBfoo\efR utility processes files...
 \&.\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
@@ -291,10 +296,7 @@ Implementation-specific notes should be kept here.
 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 .
@@ -303,10 +305,8 @@ Documents files used.
 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.
@@ -314,7 +314,7 @@ 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.
@@ -341,23 +341,21 @@ If not adhering to any standards, the
 .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.
@@ -372,6 +370,13 @@ Thus, the following are equivalent:
 \&.\ \ \ PP
 .Ed
 .Pp
+To include space characters in macro arguments, arguments may be quoted;
+see the
+.Sq MACRO SYNTAX
+section in the
+.Xr roff 7
+manual for details.
+.Pp
 The
 .Nm
 macros are classified by scope: line scope or block scope.
@@ -416,7 +421,6 @@ The syntax is as follows:
 .It Sx \&I   Ta    n         Ta    next-line Ta    \&
 .It Sx \&IB  Ta    n         Ta    current   Ta    \&
 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
-.\" .It Sx \&PD  Ta    n         Ta    current   Ta    compat
 .It Sx \&R   Ta    n         Ta    next-line Ta    \&
 .It Sx \&RB  Ta    n         Ta    current   Ta    \&
 .It Sx \&RI  Ta    n         Ta    current   Ta    \&
@@ -426,14 +430,11 @@ The syntax is as follows:
 .It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
 .It Sx \&br  Ta    0         Ta    current   Ta    compat
 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
-.It Sx \&i   Ta    n         Ta    current   Ta    compat
+.It Sx \&ft  Ta    1         Ta    current   Ta    compat
+.It Sx \&in  Ta    1         Ta    current   Ta    compat
 .It Sx \&na  Ta    0         Ta    current   Ta    compat
 .It Sx \&nf  Ta    0         Ta    current   Ta    compat
-.It Sx \&r   Ta    0         Ta    current   Ta    compat
 .It Sx \&sp  Ta    1         Ta    current   Ta    compat
-.\" .It Sx \&Sp  Ta    <1        Ta    current   Ta    compat
-.\" .It Sx \&Vb  Ta    <1        Ta    current   Ta    compat
-.\" .It Sx \&Ve  Ta    0         Ta    current   Ta    compat
 .El
 .Pp
 Macros marked as
@@ -444,8 +445,8 @@ These macros should not be used for portable
 .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).
@@ -513,12 +514,9 @@ The optional arguments specify which release it is fro
 Text is rendered in bold face.
 .Pp
 See also
-.Sx \&I ,
-.Sx \&R ,
-.Sx \&b ,
-.Sx \&i ,
+.Sx \&I
 and
-.Sx \&r .
+.Sx \&R .
 .Ss \&BI
 Text is rendered alternately in bold face and italic.
 Thus,
@@ -536,7 +534,7 @@ Whitespace between arguments is omitted in output.
 .Pp
 Examples:
 .Pp
-.D1 \&.BI bold italic bold italic
+.Dl \&.BI bold italic bold italic
 .Pp
 The output of this example will be emboldened
 .Dq bold
@@ -595,15 +593,12 @@ and
 Text is rendered in italics.
 .Pp
 See also
-.Sx \&B ,
-.Sx \&R ,
-.Sx \&b ,
-.Sx \&i ,
+.Sx \&B
 and
-.Sx \&r .
+.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
@@ -626,7 +621,7 @@ Begin an indented paragraph with the following syntax:
 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
@@ -696,12 +691,9 @@ and
 Text is rendered in roman (the default font).
 .Pp
 See also
-.Sx \&I ,
-.Sx \&B ,
-.Sx \&b ,
-.Sx \&i ,
+.Sx \&I
 and
-.Sx \&r .
+.Sx \&B .
 .Ss \&RB
 Text is rendered alternately in roman (the default font) and bold face.
 Whitespace between arguments is omitted in output.
@@ -796,7 +788,7 @@ manual section.
 .Pp
 Examples:
 .Pp
-.D1 \&.TH CVS 5 "1992-02-12" GNU
+.Dl \&.TH CVS 5 "1992-02-12" GNU
 .Ss \&TP
 Begin a paragraph where the head, if exceeding the indentation width, is
 followed by a newline; if not, the body follows on the same line after a
@@ -822,12 +814,6 @@ See also
 .Sx \&P ,
 and
 .Sx \&PP .
-.\" .
-.\" .
-.\" .Ss \&PD
-.\" Has no effect.  Included for compatibility.
-.\" .
-.\" .
 .Ss \&UC
 Sets the volume for the footer for compatibility with man pages from
 BSD releases.
@@ -841,18 +827,21 @@ See also
 .Ss \&fi
 End literal mode begun by
 .Sx \&nf .
-.Ss \&i
-Italicise arguments.
-Synonym for
-.Sx \&I .
+.Ss \&ft
+Change the current font mode.
+See
+.Sx Text Decoration
+for a listing of available font modes.
+.Ss \&in
+Indent relative to the current indentation:
 .Pp
-See also
-.Sx \&B ,
-.Sx \&I ,
-.Sx \&R .
-.Sx \&b ,
-and
-.Sx \&r .
+.D1 Pf \. Sx \&in Op Cm width
+.Pp
+If
+.Cm width
+is signed, the new offset is relative.
+Otherwise, it is absolute.
+This value is reset upon the next paragraph, section, or sub-section.
 .Ss \&na
 Don't align to the right margin.
 .Ss \&nf
@@ -860,16 +849,6 @@ Begin literal mode: all subsequent free-form lines hav
 line boundaries preserved.
 May be ended by
 .Sx \&fi .
-.Ss \&r
-Fonts and styles (bold face, italics) reset to roman (default font).
-.Pp
-See also
-.Sx \&B ,
-.Sx \&I ,
-.Sx \&R ,
-.Sx \&b ,
-and
-.Sx \&i .
 .Ss \&sp
 Insert vertical spaces into output with the following syntax:
 .Bd -filled -offset indent
@@ -888,21 +867,6 @@ Defaults to 1, if unspecified.
 .Pp
 See also
 .Sx \&br .
-.\" .Ss \&Sp
-.\" A synonym for
-.\" .Sx \&sp
-.\" .Cm 0.5v .
-.\" .
-.\" .Ss \&Vb
-.\" A synonym for
-.\" .Sx \&nf .
-.\" Accepts an argument (the height of the formatted space) which is
-.\" disregarded.
-.\" .
-.\" .Ss \&Ve
-.\" A synonym for
-.\" .Sx \&fi .
-.\" .
 .Sh COMPATIBILITY
 This section documents areas of questionable portability between
 implementations of the
@@ -911,28 +875,54 @@ language.
 .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 man 1 ,
 .Xr mandoc 1 ,
-.Xr mandoc_char 7
+.Xr mandoc_char 7 ,
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 7
 .Sh HISTORY
 The
 .Nm
@@ -943,7 +933,7 @@ It was later rewritten by James Clark as a macro packa
 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