-.\" $Id: mdoc.7,v 1.229 2014/06/22 17:07:06 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>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: June 22 2014 $
+.Dd $Mdocdate: October 30 2014 $
.Dt MDOC 7
.Os
.Sh NAME
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
.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 \&Cd Ta kernel configuration declaration (>0 arguments)
.It Sx \&Ad Ta memory address (>0 arguments)
.It Sx \&Ms Ta mathematical symbol (>0 arguments)
-.It Sx \&Tn Ta tradename (>0 arguments)
.El
.Ss Physical markup
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
.It Sx \&St Ta reference to a standards document (one argument)
-.It Sx \&Ux Ta Ux
.It Sx \&At Ta At
.It Sx \&Bx Ta Bx
.It Sx \&Bsx Ta Bsx
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Bc
Close a
.Sx \&Bo
.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
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Bt
+Supported only for compatibility, do not use this in new manuals.
Prints
.Dq is currently in beta test.
.Ss \&Bx
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Cd
Kernel configuration declaration.
This denotes strings accepted by
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.
.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
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.
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
-.Oo
-.Ar title
-.Oo
+.Ar TITLE
.Ar section
-.Op Ar volume
-.Op Ar arch
-.Oc
-.Oc
+.Op Ar volume | arch
.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
-.Dq UNKNOWN
+.Dq UNTITLED
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
.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 .
.Sx \&Bx ,
.Sx \&Fx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Ec
Close a scope started by
.Sx \&Eo .
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 ,
and
.Sx \&Sy .
.Ss \&En
-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
+This macro is obsolete.
+Use
+.Sx \&Eo
+or any of the other enclosure macros.
+.Pp
+It encloses its argument in the delimiters specified by the last
+.Sx \&Es
+macro.
.Ss \&Eo
An arbitrary enclosure.
Its syntax is as follows:
.Sx \&Dv
for general constants.
.Ss \&Es
-This macro is obsolete and not implemented.
+This macro is obsolete.
+Use
+.Sx \&Eo
+or any of the other enclosure macros.
+.Pp
+It takes two arguments, defining the delimiters to be used by subsequent
+.Sx \&En
+macros.
.Ss \&Ev
Environmental variables such as those specified in
.Xr environ 7 .
See also
.Sx \&Rv .
.Ss \&Fa
-Function argument.
+Function argument or parameter.
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
-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
-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
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 .
.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
and
.Sx \&Ft .
.Ss \&Fr
-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
-.Pp
-It was used to show function return values.
-The syntax was:
+This macro is obsolete.
+No replacement markup is needed.
.Pp
-.Dl Pf . Sx \&Fr Ar value
+It was used to show numerical function return values in an italic font.
.Ss \&Ft
A function type.
Its syntax is as follows:
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Nx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Hf
This macro is not implemented in
.Xr mandoc 1 .
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
-.Sx \&Ox ,
and
-.Sx \&Ux .
+.Sx \&Ox .
.Ss \&Oc
Close multi-line
.Sx \&Oo
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
and
.Sx \&Dt .
.Ss \&Ot
-This macro is obsolete and not implemented in
-.Xr mandoc 1 .
+This macro is obsolete.
+Use
+.Sx \&Ft
+instead; with
+.Xr mandoc 1 ,
+both have the same effect.
.Pp
Historical
.Nm
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
-.Sx \&Nx ,
and
-.Sx \&Ux .
+.Sx \&Nx .
.Ss \&Pa
An absolute or relative file system path, or a file or directory name.
If an argument is not provided, the character
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 .
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 .
.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
.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
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 ,
lists; can only be used below
.Sx \&It .
.Ss \&Tn
-Format a tradename.
-.Pp
-Since this macro is often implemented to use a small caps font,
-it has historically been used for acronyms (like ASCII) as well.
-Such usage is not recommended because it would use the same macro
-sometimes for semantical annotation, sometimes for physical formatting.
-.Pp
-Examples:
-.Dl \&.Tn IBM
+Supported only for compatibility, do not use this in new manuals.
+Even though the macro name
+.Pq Dq tradename
+suggests a semantic function, historic usage is inconsistent, mostly
+using it as a presentation-level macro to request a small caps font.
.Ss \&Ud
+Supported only for compatibility, do not use this in new manuals.
Prints out
.Dq currently under development.
.Ss \&Ux
-Format the
-.Ux
-name.
-Accepts no argument.
-.Pp
-Examples:
-.Dl \&.Ux
-.Pp
-See also
-.Sx \&At ,
-.Sx \&Bsx ,
-.Sx \&Bx ,
-.Sx \&Dx ,
-.Sx \&Fx ,
-.Sx \&Nx ,
-and
-.Sx \&Ox .
+Supported only for compatibility, do not use this in new manuals.
+Prints out
+.Dq Ux .
.Ss \&Va
A variable name.
.Pp
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.
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 .
.It Sx \&D1 Ta \&No Ta \&Yes
.It Sx \&Dl Ta \&No Ta Yes
.It Sx \&Dq Ta Yes Ta Yes
+.It Sx \&En Ta Yes Ta Yes
.It Sx \&Op Ta Yes Ta Yes
.It Sx \&Pq Ta Yes Ta Yes
.It Sx \&Ql Ta Yes Ta Yes
.It Sx \&Dv Ta Yes Ta Yes Ta >0
.It Sx \&Dx Ta Yes Ta Yes Ta n
.It Sx \&Em Ta Yes Ta Yes Ta >0
-.It Sx \&En Ta \&No Ta \&No Ta 0
.It Sx \&Er Ta Yes Ta Yes Ta >0
-.It Sx \&Es Ta \&No Ta \&No Ta 0
+.It Sx \&Es Ta Yes Ta Yes Ta 2
.It Sx \&Ev Ta Yes Ta Yes Ta >0
.It Sx \&Ex Ta \&No Ta \&No Ta n
.It Sx \&Fa Ta Yes Ta Yes Ta >0
.It Sx \&Fd Ta \&No Ta \&No Ta >0
.It Sx \&Fl Ta Yes Ta Yes Ta n
.It Sx \&Fn Ta Yes Ta Yes Ta >0
-.It Sx \&Fr Ta \&No Ta \&No Ta n
+.It Sx \&Fr Ta Yes Ta Yes Ta >0
.It Sx \&Ft Ta Yes Ta Yes Ta >0
.It Sx \&Fx Ta Yes Ta Yes Ta n
.It Sx \&Hf Ta \&No Ta \&No Ta n
.It Sx \&Ns Ta Yes Ta Yes Ta 0
.It Sx \&Nx Ta Yes Ta Yes Ta n
.It Sx \&Os Ta \&No Ta \&No Ta n
-.It Sx \&Ot Ta \&No Ta \&No Ta n
+.It Sx \&Ot Ta Yes Ta Yes Ta >0
.It Sx \&Ox Ta Yes Ta Yes Ta n
.It Sx \&Pa Ta Yes Ta Yes 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
git.ckatri.com / mandoc.git / blobdiff