===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.122
retrieving revision 1.139
diff -u -p -r1.122 -r1.139
--- mandoc/man.7	2014/01/06 00:53:33	1.122
+++ mandoc/man.7	2018/08/18 02:08:27	1.139
@@ -1,7 +1,8 @@
-.\"	$Id: man.7,v 1.122 2014/01/06 00:53:33 schwarze Exp $
+.\"	$Id: man.7,v 1.139 2018/08/18 02:08:27 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2011, 2012, 2013 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2011-2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
 .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -16,7 +17,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: January 6 2014 $
+.Dd $Mdocdate: August 18 2018 $
 .Dt MAN 7
 .Os
 .Sh NAME
@@ -98,30 +99,32 @@ file for a utility
 .Bd -literal -offset indent
 \&.TH PROGNAME 1 2009-10-10
 \&.SH NAME
-\efBprogname\efR \e(en a description goes here
+\efBprogname\efR \e(en one line about what it does
 \&.\e\(dq .SH LIBRARY
-\&.\e\(dq For sections 2 & 3 only.
+\&.\e\(dq For sections 2, 3, and 9 only.
 \&.\e\(dq Not used in OpenBSD.
 \&.SH SYNOPSIS
-\efBprogname\efR [\efB\e-options\efR] arguments...
+\efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR
 \&.SH DESCRIPTION
-The \efBfoo\efR utility processes files...
+The \efBfoo\efR utility processes files ...
+\&.\e\(dq .Sh CONTEXT
+\&.\e\(dq For section 9 functions only.
 \&.\e\(dq .SH IMPLEMENTATION NOTES
 \&.\e\(dq Not used in OpenBSD.
 \&.\e\(dq .SH RETURN VALUES
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, and 9 function return values only.
 \&.\e\(dq .SH ENVIRONMENT
-\&.\e\(dq For sections 1, 6, 7, & 8 only.
+\&.\e\(dq For sections 1, 6, 7, and 8 only.
 \&.\e\(dq .SH FILES
 \&.\e\(dq .SH EXIT STATUS
-\&.\e\(dq For sections 1, 6, & 8 only.
+\&.\e\(dq For sections 1, 6, and 8 only.
 \&.\e\(dq .SH EXAMPLES
 \&.\e\(dq .SH DIAGNOSTICS
-\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
+\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
 \&.\e\(dq .SH ERRORS
-\&.\e\(dq For sections 2, 3, & 9 only.
+\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
 \&.\e\(dq .SH SEE ALSO
-\&.\e\(dq .BR foo ( 1 )
+\&.\e\(dq .BR foobar ( 1 )
 \&.\e\(dq .SH STANDARDS
 \&.\e\(dq .SH HISTORY
 \&.\e\(dq .SH AUTHORS
@@ -171,6 +174,9 @@ This expands upon the brief, one-line description in
 .Em NAME .
 It usually contains a break-down of the options (if documenting a
 command).
+.It Em CONTEXT
+This section lists the contexts in which functions can be called in section 9.
+The contexts are autoconf, process, or interrupt.
 .It Em IMPLEMENTATION NOTES
 Implementation-specific notes should be kept here.
 This is useful when implementing standard functions that may have side
@@ -197,13 +203,19 @@ well-tested invocations.
 Make sure that examples work properly!
 .It Em DIAGNOSTICS
 Documents error conditions.
-This is most useful in section 4 manuals.
+In section 4 and 9 manuals, these are usually messages
+printed by the kernel to the console and to the kernel log.
+In section 1, 6, 7, and 8, these are usually messages
+printed by userland programs to the standard error output.
+.Pp
 Historically, this section was used in place of
 .Em EXIT STATUS
 for manuals in sections 1, 6, and 8; however, this practise is
 discouraged.
 .It Em ERRORS
-Documents error handling in sections 2, 3, and 9.
+Documents
+.Xr errno 2
+settings in sections 2, 3, 4, and 9.
 .It Em SEE ALSO
 References other manuals with related topics.
 This section should exist for most manuals.
@@ -255,8 +267,6 @@ in the alphabetical reference below.
 .It Sx TP Ta tagged paragraph: Op Ar width
 .It Sx HP Ta hanged paragraph: Op Ar width
 .It Sx PD Ta set vertical paragraph distance: Op Ar height
-.It Sx \&br Ta force output line break in text mode (no arguments)
-.It Sx \&sp Ta force vertical space: Op Ar height
 .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
 .It Sx in Ta additional indent: Op Ar width
 .El
@@ -264,7 +274,6 @@ in the alphabetical reference below.
 .Bl -column "PP, LP, P" description
 .It Sx B Ta boldface font
 .It Sx I Ta italic font
-.It Sx R Ta roman (default) font
 .It Sx SB Ta small boldface font
 .It Sx SM Ta small roman font
 .It Sx BI Ta alternate between boldface and italic fonts
@@ -281,16 +290,14 @@ For the scoping of individual macros, see
 .Sx MACRO SYNTAX .
 .Ss \&AT
 Sets the volume for the footer for compatibility with man pages from
-.Tn AT&T UNIX
+.At
 releases.
 The optional arguments specify which release it is from.
 .Ss \&B
 Text is rendered in bold face.
 .Pp
 See also
-.Sx \&I
-and
-.Sx \&R .
+.Sx \&I .
 .Ss \&BI
 Text is rendered alternately in bold face and italic.
 Thus,
@@ -339,8 +346,12 @@ See also
 and
 .Sx \&IR .
 .Ss \&DT
-Has no effect.
-Included for compatibility.
+Restore the default tabulator positions.
+They are at intervals of 0.5 inches.
+This has no effect unless the tabulator positions were changed with the
+.Xr roff 7
+.Ic \&ta
+request.
 .Ss \&EE
 This is a non-standard GNU extension, included only for compatibility.
 In
@@ -358,11 +369,11 @@ Begin a paragraph whose initial output line is left-ju
 subsequent output lines are indented, with the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&HP
-.Op Cm width
+.Op Ar width
 .Ed
 .Pp
 The
-.Cm width
+.Ar width
 argument is a
 .Xr roff 7
 scaling width.
@@ -380,9 +391,7 @@ and
 Text is rendered in italics.
 .Pp
 See also
-.Sx \&B
-and
-.Sx \&R .
+.Sx \&B .
 .Ss \&IB
 Text is rendered alternately in italics and bold face.
 Whitespace between arguments is omitted in output.
@@ -402,11 +411,11 @@ and
 Begin an indented paragraph with the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&IP
-.Op Cm head Op Cm width
+.Op Ar head Op Ar width
 .Ed
 .Pp
 The
-.Cm width
+.Ar width
 argument is a
 .Xr roff 7
 scaling width defining the left margin.
@@ -414,7 +423,7 @@ It's saved for later paragraph left-margins; if unspec
 default width is used.
 .Pp
 The
-.Cm head
+.Ar head
 argument is used as a leading term, flushed to the left margin.
 This is useful for bulleted paragraphs and so on.
 .Pp
@@ -453,19 +462,33 @@ See also
 .Sx \&PP ,
 and
 .Sx \&TP .
+.Ss \&ME
+End a mailto block.
+This is a non-standard GNU extension, included only for compatibility.
+See
+.Sx \&MT .
+.Ss \&MT
+Begin a mailto block.
+This is a non-standard GNU extension, included only for compatibility.
+It has the following syntax:
+.Bd -literal -offset indent
+.Pf \. Sx \&MT Ar address
+link description to be shown
+.Pf \. Sx ME
+.Ed
 .Ss \&OP
 Optional command-line argument.
 This is a non-standard GNU extension, included only for compatibility.
 It has the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&OP
-.Cm key Op Cm value
+.Ar key Op Ar value
 .Ed
 .Pp
 The
-.Cm key
+.Ar key
 is usually a command-line flag and
-.Cm value
+.Ar value
 its argument.
 .Ss \&P
 Synonym for
@@ -484,11 +507,11 @@ Specify the vertical space to be inserted before each 
 The syntax is as follows:
 .Bd -filled -offset indent
 .Pf \. Sx \&PD
-.Op Cm height
+.Op Ar height
 .Ed
 .Pp
 The
-.Cm height
+.Ar height
 argument is a
 .Xr roff 7
 scaling width.
@@ -519,13 +542,6 @@ See also
 .Sx \&P ,
 and
 .Sx \&TP .
-.Ss \&R
-Text is rendered in roman (the default font).
-.Pp
-See also
-.Sx \&I
-and
-.Sx \&B .
 .Ss \&RB
 Text is rendered alternately in roman (the default font) and bold face.
 Whitespace between arguments is omitted in output.
@@ -544,9 +560,29 @@ and
 .Ss \&RE
 Explicitly close out the scope of a prior
 .Sx \&RS .
-The default left margin is restored to the state of the original
+The default left margin is restored to the state before that
 .Sx \&RS
 invocation.
+.Pp
+The syntax is as follows:
+.Bd -filled -offset indent
+.Pf \. Sx \&RE
+.Op Ar level
+.Ed
+.Pp
+Without an argument, the most recent
+.Sx \&RS
+block is closed out.
+If
+.Ar level
+is 1, all open
+.Sx \&RS
+blocks are closed out.
+Otherwise,
+.Ar level No \(mi 1
+nested
+.Sx \&RS
+blocks remain open.
 .Ss \&RI
 Text is rendered alternately in roman (the default font) and italics.
 Whitespace between arguments is omitted in output.
@@ -567,11 +603,11 @@ Temporarily reset the default left margin.
 This has the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&RS
-.Op Cm width
+.Op Ar width
 .Ed
 .Pp
 The
-.Cm width
+.Ar width
 argument is a
 .Xr roff 7
 scaling width.
@@ -595,8 +631,21 @@ Begin a sub-section.
 The scope of a sub-section is closed by a subsequent sub-section,
 section, or end of file.
 The paragraph left-margin width is reset to the default.
+.Ss \&SY
+Begin a synopsis block with the following syntax:
+.Bd -unfilled -offset indent
+.Pf \. Sx \&SY Ar command
+.Ar arguments
+.Pf \. Sx \&YS
+.Ed
+.Pp
+This is a non-standard GNU extension
+and very rarely used even in GNU manual pages.
+Formatting is similar to
+.Sx \&IP .
 .Ss \&TH
-Sets the title of the manual page with the following syntax:
+Sets the title of the manual page for use in the page header
+and footer with the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&TH
 .Ar title section date
@@ -618,6 +667,11 @@ is empty or not specified, the current date is used.
 The optional
 .Ar source
 string specifies the organisation providing the utility.
+When unspecified,
+.Xr mandoc 1
+uses its
+.Fl Ios
+argument.
 The
 .Ar volume
 string replaces the default rendered volume, which is dictated by the
@@ -634,11 +688,11 @@ Subsequent output lines are indented.
 The syntax is as follows:
 .Bd -filled -offset indent
 .Pf \. Sx \&TP
-.Op Cm width
+.Op Ar width
 .Ed
 .Pp
 The
-.Cm width
+.Ar width
 argument is a
 .Xr roff 7
 scaling width.
@@ -652,6 +706,12 @@ See also
 .Sx \&P ,
 and
 .Sx \&PP .
+.Ss \&TQ
+Like
+.Sx \&TP ,
+except that no vertical spacing is inserted before the paragraph.
+This is a non-standard GNU extension and rarely used even by GNU
+manual pages.
 .Ss \&UC
 Sets the volume for the footer for compatibility with man pages from
 .Bx
@@ -671,32 +731,23 @@ It has the following syntax:
 link description to be shown
 .Pf \. Sx UE
 .Ed
-.Ss \&br
-Breaks the current line.
-Consecutive invocations have no further effect.
-.Pp
-See also
-.Sx \&sp .
+.Ss \&YS
+End a synopsis block started by
+.Pf \. Sx SY .
+This is a non-standard GNU extension.
 .Ss \&fi
 End literal mode begun by
 .Sx \&nf .
-.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
-.D1 Pf \. Sx \&in Op Cm width
+.D1 Pf \. Sx \&in Op Ar width
 .Pp
 If
-.Cm width
+.Ar 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
 Begin literal mode: all subsequent free-form lines have their end of
 line boundaries preserved.
@@ -706,24 +757,6 @@ Literal mode is implicitly ended by
 .Sx \&SH
 or
 .Sx \&SS .
-.Ss \&sp
-Insert vertical spaces into output with the following syntax:
-.Bd -filled -offset indent
-.Pf \. Sx \&sp
-.Op Cm height
-.Ed
-.Pp
-The
-.Cm height
-argument is a scaling width as described in
-.Xr roff 7 .
-If 0, this is equivalent to the
-.Sx \&br
-macro.
-Defaults to 1, if unspecified.
-.Pp
-See also
-.Sx \&br .
 .Sh MACRO SYNTAX
 The
 .Nm
@@ -747,11 +780,7 @@ is equivalent to
 .Sq \&.I foo .
 If next-line macros are invoked consecutively, only the last is used.
 If a next-line macro is followed by a non-next-line macro, an error is
-raised, except for
-.Sx \&br ,
-.Sx \&sp ,
-and
-.Sx \&na .
+raised.
 .Pp
 The syntax is as follows:
 .Bd -literal -offset indent
@@ -772,20 +801,15 @@ The syntax is as follows:
 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
 .It Sx \&OP  Ta    0, 1      Ta    current   Ta    compat
 .It Sx \&PD  Ta    1         Ta    current   Ta    \&
-.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    \&
 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
 .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 \&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 \&sp  Ta    1         Ta    current   Ta    compat
 .El
 .Pp
 Macros marked as
@@ -867,82 +891,6 @@ until the end of the macro scope.
 Note that macros like
 .Sx \&BR
 open and close a font scope for each argument.
-.Sh COMPATIBILITY
-This section documents areas of questionable portability between
-implementations of the
-.Nm
-language.
-.Pp
-.Bl -dash -compact
-.It
-Do not depend on
-.Sx \&SH
-or
-.Sx \&SS
-to close out a literal context opened with
-.Sx \&nf .
-This behaviour may not be portable.
-.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
-In page header lines, GNU troff versions up to and including 1.21
-only print
-.Ar volume
-names explicitly specified in the
-.Sx \&TH
-macro; mandoc and newer groff print the default volume name
-corresponding to the
-.Ar section
-number when no
-.Ar volume
-is given, like in
-.Xr mdoc 7 .
-.El
-.Pp
-The
-.Sx OP
-macro is part of the extended
-.Nm
-macro set, and may not be portable to non-GNU troff implementations.
 .Sh SEE ALSO
 .Xr man 1 ,
 .Xr mandoc 1 ,