=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.233 retrieving revision 1.239 diff -u -p -r1.233 -r1.239 --- mandoc/mdoc.7 2014/08/08 01:52:40 1.233 +++ mandoc/mdoc.7 2014/10/20 17:59:20 1.239 @@ -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 .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze @@ -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. .\" -.Dd $Mdocdate: August 8 2014 $ +.Dd $Mdocdate: October 20 2014 $ .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 -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 @@ -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 \&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 @@ -1245,7 +1245,7 @@ See also 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. @@ -1467,16 +1467,29 @@ See also 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: -.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 , @@ -1557,7 +1570,7 @@ arguments are treated as separate utilities. See also .Sx \&Rv . .Ss \&Fa -Function argument. +Function argument or parameter. 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 -.D1 Pf \. Sx \&Sm Cm on | off +.D1 Pf \. Sx \&Sm Op Cm on | off .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. +.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 . @@ -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 \-susv1 +.St -susv1 .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 @@ -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 +.It \-susv4 +.St -susv4 .br -This standard is also called SUSv4 and +This standard is also called X/Open Portability Guide version 7. .Pp .It \-p1003.1-2013 @@ -2632,11 +2654,25 @@ See also 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 , .Sx \&Em , @@ -2668,8 +2704,17 @@ A variable name. 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. +.Pp 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 lin 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 +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 -.Sx MANUAL STRUCTURE -and -.Sx \&Va . +.Sx MANUAL STRUCTURE . .Ss \&Xc Close a scope opened by .Sx \&Xo . @@ -3022,7 +3070,7 @@ then the macro accepts an arbitrary number of argument .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