Let -h imply -c (that is, not use the pager).

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index a4aa1c70b0ab9e20945fecf756da55feda96a75b..c31a47b726533c43701a17a1da10b6165b500536 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.231 2014/07/02 03:48:07 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.240 2014/10/30 20:10:02 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" 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 2 2014 $
+.Dd $Mdocdate: October 30 2014 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -388,7 +388,7 @@ See
 References other manuals with related topics.
 This section should exist for most manuals.
 Cross-references should conventionally be ordered first by section, then
 References other manuals with related topics.
 This section should exist for most manuals.
 Cross-references should conventionally be ordered first by section, then

-alphabetically.
+alphabetically (ignoring case).

 .Pp
 References to other documentation concerning the topic of the manual page,
 for example authoritative books or journal articles, may also be
 .Pp
 References to other documentation concerning the topic of the manual page,
 for example authoritative books or journal articles, may also be


@@ -468,7 +468,7 @@ in the alphabetical
 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
 .It Sx \&Pf Ta prefix, no following horizontal space (one argument)
 .It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
 .It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)

-.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
+.It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off

 .It Sx \&Bk , \&Ek Ta keep block: Fl words
 .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 \&Bk , \&Ek Ta keep block: Fl words
 .It Sx \&br Ta force output line break in text mode (no arguments)
 .It Sx \&sp Ta force vertical space: Op Ar height


@@ -937,8 +937,11 @@ The
 .Fl width
 and
 .Fl offset
 .Fl width
 and
 .Fl offset

-arguments accept scaling widths as described in
-.Xr roff 7
+arguments accept macro names as described for
+.Sx \&Bd
+.Fl offset ,
+scaling widths as described in
+.Xr roff 7 ,

 or use the length of the given string.
 The
 .Fl offset
 or use the length of the given string.
 The
 .Fl offset


@@ -1195,7 +1198,7 @@ Close a
 block.
 Does not have any tail arguments.
 .Ss \&Dd
 block.
 Does not have any tail arguments.
 .Ss \&Dd

-Document date.
+Document date for display in the page footer.

 This is the mandatory first macro of any
 .Nm
 manual.
 This is the mandatory first macro of any
 .Nm
 manual.


@@ -1224,8 +1227,11 @@ the special string
 .Dq $\&Mdocdate$
 can be given as an argument.
 .It
 .Dq $\&Mdocdate$
 can be given as an argument.
 .It

-A few alternative date formats are accepted as well
-and converted to the standard form.
+The traditional, purely numeric
+.Xr man 7
+format
+.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day
+is accepted, too.

 .It
 If a date string cannot be parsed, it is used verbatim.
 .It
 .It
 If a date string cannot be parsed, it is used verbatim.
 .It


@@ -1242,7 +1248,7 @@ See also
 and
 .Sx \&Os .
 .Ss \&Dl
 and
 .Sx \&Os .
 .Ss \&Dl

-One-line intended display.
+One-line indented display.

 This is formatted as literal text and is useful for commands and
 invocations.
 It is followed by a newline.
 This is formatted as literal text and is useful for commands and
 invocations.
 It is followed by a newline.


@@ -1285,30 +1291,26 @@ See also
 and
 .Sx \&Do .
 .Ss \&Dt
 and
 .Sx \&Do .
 .Ss \&Dt

-Document title.
+Document title for display in the page header.

 This is the mandatory second macro of any
 .Nm
 file.
 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Dt
 This is the mandatory second macro of any
 .Nm
 file.
 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Dt

-.Oo
-.Ar title
-.Oo
+.Ar TITLE

 .Ar section
 .Ar section

-.Op Ar volume
-.Op Ar arch
-.Oc
-.Oc
+.Op Ar volume | arch

 .Ed
 .Pp
 Its arguments are as follows:
 .Ed
 .Pp
 Its arguments are as follows:

-.Bl -tag -width Ds -offset Ds
-.It Ar title
+.Bl -tag -width section -offset 2n
+.It Ar TITLE

 The document's title (name), defaulting to
 The document's title (name), defaulting to

-.Dq UNKNOWN
+.Dq UNTITLED

 if unspecified.
 if unspecified.

-It should be capitalised.
+To achieve a uniform appearance of page header lines,
+it should by convention be all caps.

 .It Ar section
 The manual section.
 This may be one of
 .It Ar section
 The manual section.
 This may be one of


@@ -1346,8 +1348,7 @@ or
 .Cm paper
 .Pq paper .
 It should correspond to the manual's filename suffix and defaults to
 .Cm paper
 .Pq paper .
 It should correspond to the manual's filename suffix and defaults to

-.Cm 1
-if unspecified.
+the empty string if unspecified.

 .It Ar volume
 This overrides the volume inferred from
 .Ar section .
 .It Ar volume
 This overrides the volume inferred from
 .Ar section .


@@ -1469,16 +1470,29 @@ See also
 and
 .Sx \&It .
 .Ss \&Em
 and
 .Sx \&It .
 .Ss \&Em

-Denotes text that should be
-.Em emphasised .
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
-Depending on the output device, this is usually represented
-using an italic font or underlined characters.
+Request an italic font.
+If the output device does not provide that, underline.
+.Pp
+This is most often used for stress emphasis (not to be confused with
+importance, see
+.Sx \&Sy ) .
+In the rare cases where none of the semantic markup macros fit,
+it can also be used for technical terms and placeholders, except
+that for syntax elements,
+.Sx \&Sy
+and
+.Sx \&Ar
+are preferred, respectively.

 .Pp
 Examples:
 .Pp
 Examples:

-.Dl \&.Em Warnings!
-.Dl \&.Em Remarks :
+.Bd -literal -compact -offset indent
+Selected lines are those
+\&.Em not
+matching any of the specified patterns.
+Some of the functions use a
+\&.Em hold space
+to save the pattern space for subsequent retrieval.
+.Ed

 .Pp
 See also
 .Sx \&Bf ,
 .Pp
 See also
 .Sx \&Bf ,


@@ -1559,23 +1573,35 @@ arguments are treated as separate utilities.
 See also
 .Sx \&Rv .
 .Ss \&Fa
 See also
 .Sx \&Rv .
 .Ss \&Fa

-Function argument.
+Function argument or parameter.

 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Fa
 Its syntax is as follows:
 .Bd -ragged -offset indent
 .Pf \. Sx \&Fa

-.Op Cm argtype
-.Cm argname
+.Qo
+.Op Ar argtype
+.Op Ar argname
+.Qc Ar \&...

 .Ed
 .Pp
 .Ed
 .Pp

-This may be invoked for names with or without the corresponding type.
-It is also used to specify the field name of a structure.
+Each argument may be a name and a type (recommended for the
+.Em SYNOPSIS
+section), a name alone (for function invocations),
+or a type alone (for function prototypes).
+If both a type and a name are given or if the type consists of multiple
+words, all words belonging to the same function argument have to be
+given in a single argument to the
+.Sx \&Fa
+macro.
+.Pp
+This macro is also used to specify the field name of a structure.
+.Pp

 Most often, the
 .Sx \&Fa
 macro is used in the
 .Em SYNOPSIS
 within
 .Sx \&Fo
 Most often, the
 .Sx \&Fa
 macro is used in the
 .Em SYNOPSIS
 within
 .Sx \&Fo

-section when documenting multi-line function prototypes.
+blocks when documenting multi-line function prototypes.

 If invoked with multiple arguments, the arguments are separated by a
 comma.
 Furthermore, if the following macro is another
 If invoked with multiple arguments, the arguments are separated by a
 comma.
 Furthermore, if the following macro is another


@@ -1585,7 +1611,7 @@ the last argument will also have a trailing comma.
 Examples:
 .Dl \&.Fa \(dqconst char *p\(dq
 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
 Examples:
 .Dl \&.Fa \(dqconst char *p\(dq
 .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq

-.Dl \&.Fa foo
+.Dl \&.Fa \(dqchar *\(dq size_t

 .Pp
 See also
 .Sx \&Fo .
 .Pp
 See also
 .Sx \&Fo .


@@ -1688,7 +1714,7 @@ Invocations usually occur in the following context:
 .br
 .Pf \. Sx \&Fo Ar funcname
 .br
 .br
 .Pf \. Sx \&Fo Ar funcname
 .br

-.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
+.Pf \. Sx \&Fa Qq Ar argtype Ar argname

 .br
 \&.\.\.
 .br
 .br
 \&.\.\.
 .br


@@ -2098,7 +2124,7 @@ Examples:
 See also
 .Sx \&Oo .
 .Ss \&Os
 See also
 .Sx \&Oo .
 .Ss \&Os

-Document operating system version.
+Operating system version for display in the page footer.

 This is the mandatory third macro of
 any
 .Nm
 This is the mandatory third macro of
 any
 .Nm


@@ -2325,7 +2351,7 @@ and
 Switches the spacing mode for output generated from macros.
 Its syntax is as follows:
 .Pp
 Switches the spacing mode for output generated from macros.
 Its syntax is as follows:
 .Pp

-.D1 Pf \. Sx \&Sm Cm on | off
+.D1 Pf \. Sx \&Sm Op Cm on | off

 .Pp
 By default, spacing is
 .Cm on .
 .Pp
 By default, spacing is
 .Cm on .


@@ -2334,6 +2360,11 @@ When switched
 no white space is inserted between macro arguments and between the
 output generated from adjacent macros, but text lines
 still get normal spacing between words and sentences.
 no white space is inserted between macro arguments and between the
 output generated from adjacent macros, but text lines
 still get normal spacing between words and sentences.

+.Pp
+When called without an argument, the
+.Sx \&Sm
+macro toggles the spacing mode.
+Using this is not recommended because it makes the code harder to read.

 .Ss \&So
 Multi-line version of
 .Sx \&Sq .
 .Ss \&So
 Multi-line version of
 .Sx \&Sq .


@@ -2482,10 +2513,12 @@ Based on POSIX.1 and POSIX.2, published in 1992.
 .It Single UNIX Specification version 1 and related standards
 .Pp
 .Bl -tag -width "-p1003.1g-2000" -compact
 .It Single UNIX Specification version 1 and related standards
 .Pp
 .Bl -tag -width "-p1003.1g-2000" -compact

+.It \-susv1
+.St -susv1

 .It \-xpg4.2
 .St -xpg4.2
 .br
 .It \-xpg4.2
 .St -xpg4.2
 .br

-This standard was published in 1994 and is also called SUSv1.
+This standard was published in 1994.

 It was used as the basis for UNIX 95 certification.
 The following three refer to parts of it.
 .Pp
 It was used as the basis for UNIX 95 certification.
 The following three refer to parts of it.
 .Pp


@@ -2578,8 +2611,10 @@ The second and last Technical Corrigendum.
 .Bl -tag -width "-p1003.1g-2000" -compact
 .It \-p1003.1-2008
 .St -p1003.1-2008
 .Bl -tag -width "-p1003.1g-2000" -compact
 .It \-p1003.1-2008
 .St -p1003.1-2008

+.It \-susv4
+.St -susv4

 .br
 .br

-This standard is also called SUSv4 and
+This standard is also called

 X/Open Portability Guide version 7.
 .Pp
 .It \-p1003.1-2013
 X/Open Portability Guide version 7.
 .Pp
 .It \-p1003.1-2013


@@ -2622,10 +2657,24 @@ See also
 and
 .Sx \&Ss .
 .Ss \&Sy
 and
 .Sx \&Ss .
 .Ss \&Sy

-Format enclosed arguments in symbolic
-.Pq Dq boldface .
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
+Request a boldface font.
+.Pp
+This is most often used to indicate importance or seriousness (not to be
+confused with stress emphasis, see
+.Sx \&Em ) .
+When none of the semantic macros fit, it is also adequate for syntax
+elements that have to be given or that appear verbatim.
+.Pp
+Examples:
+.Bd -literal -compact -offset indent
+\&.Sy Warning :
+If
+\&.Sy s
+appears in the owner permissions, set-user-ID mode is set.
+This utility replaces the former
+\&.Sy dumpdir
+program.
+.Ed

 .Pp
 See also
 .Sx \&Bf ,
 .Pp
 See also
 .Sx \&Bf ,


@@ -2658,8 +2707,17 @@ A variable name.
 Examples:
 .Dl \&.Va foo
 .Dl \&.Va const char *bar ;
 Examples:
 .Dl \&.Va foo
 .Dl \&.Va const char *bar ;

+.Pp
+For function arguments and parameters, use
+.Sx \&Fa
+instead.
+For declarations of global variables in the
+.Em SYNOPSIS
+section, use
+.Sx \&Vt .

 .Ss \&Vt
 A variable type.
 .Ss \&Vt
 A variable type.

+.Pp

 This is also used for indicating global variables in the
 .Em SYNOPSIS
 section, in which case a variable name is also specified.
 This is also used for indicating global variables in the
 .Em SYNOPSIS
 section, in which case a variable name is also specified.


@@ -2674,18 +2732,21 @@ In the former case, this macro starts a new output line,
 and a blank line is inserted in front if there is a preceding
 function definition or include directive.
 .Pp
 and a blank line is inserted in front if there is a preceding
 function definition or include directive.
 .Pp

-Note that this should not be confused with
-.Sx \&Ft ,
-which is used for function return types.
-.Pp

 Examples:
 .Dl \&.Vt unsigned char
 .Dl \&.Vt extern const char * const sys_signame[] \&;
 .Pp
 Examples:
 .Dl \&.Vt unsigned char
 .Dl \&.Vt extern const char * const sys_signame[] \&;
 .Pp

+For parameters in function prototypes, use
+.Sx \&Fa
+instead, for function return types
+.Sx \&Ft ,
+and for variable names outside the
+.Em SYNOPSIS
+section
+.Sx \&Va ,
+even when including a type with the name.

 See also
 See also

-.Sx MANUAL STRUCTURE
-and
-.Sx \&Va .
+.Sx MANUAL STRUCTURE .

 .Ss \&Xc
 Close a scope opened by
 .Sx \&Xo .
 .Ss \&Xc
 Close a scope opened by
 .Sx \&Xo .


@@ -3012,7 +3073,7 @@ then the macro accepts an arbitrary number of arguments.
 .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n
 .It Sx \&Pf  Ta    Yes      Ta    Yes      Ta    1
 .It Sx \&Pp  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&Rv  Ta    \&No     Ta    \&No     Ta    n

-.It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    1
+.It Sx \&Sm  Ta    \&No     Ta    \&No     Ta    <2

 .It Sx \&St  Ta    \&No     Ta    Yes      Ta    1
 .It Sx \&Sx  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Sy  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&St  Ta    \&No     Ta    Yes      Ta    1
 .It Sx \&Sx  Ta    Yes      Ta    Yes      Ta    >0
 .It Sx \&Sy  Ta    Yes      Ta    Yes      Ta    >0