With the current architecture, we can't support inline equations

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index ef2203dd32e620ebb878b94af3259d4130ddd4c7..cdc4c41ce7d14b7cfa25fdd67a03ba9247616dcc 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.233 2014/08/08 01:52:40 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.239 2014/10/20 17:59:20 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: August 8 2014 $
+.Dd $Mdocdate: October 20 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


@@ -1245,7 +1245,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.


@@ -1467,16 +1467,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 ,


@@ -1557,7 +1570,7 @@ 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


@@ -2335,7 +2348,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 .


@@ -2344,6 +2357,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 .


@@ -2492,10 +2510,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


@@ -2588,8 +2608,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


@@ -2632,10 +2654,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 ,


@@ -2668,8 +2704,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.


@@ -2684,18 +2729,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 .


@@ -3022,7 +3070,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