-.\" $Id: mdoc.7,v 1.261 2017/02/05 22:30:29 schwarze Exp $
+.\" $Id: mdoc.7,v 1.271 2018/07/28 18:34:15 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2013-2018 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: February 5 2017 $
+.Dd $Mdocdate: July 28 2018 $
.Dt MDOC 7
.Os
.Sh NAME
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
.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
.El
-.Ss Semantic markup for command line utilities:
+.Ss Semantic markup for command line utilities
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
.It Sx \&Fl Ta command line options (flags) (>=0 arguments)
.It Sx \&Ev Ta environmental variable (>0 arguments)
.It Sx \&Pa Ta file system path (>=0 arguments)
.El
-.Ss Semantic markup for function libraries:
+.Ss Semantic markup for function libraries
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Lb Ta function library (one argument)
.It Sx \&In Ta include file (one argument)
.It Sx \&Er Ta error constant (>0 arguments)
.It Sx \&Ev Ta environmental variable (>0 arguments)
.El
-.Ss Various semantic markup:
+.Ss Various semantic markup
.Bl -column "Brq, Bro, Brc" description
.It Sx \&An Ta author name (>0 arguments)
.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
.Ss \&Ao
Begin a block enclosed by angle brackets.
Does not have any head arguments.
-.Pp
-Examples:
-.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
-.Pp
-See also
-.Sx \&Aq .
+This macro is almost never useful.
+See
+.Sx \&Aq
+for more details.
.Ss \&Ap
Inserts an apostrophe without any surrounding whitespace.
This is generally used as a grammatical device when referring to the verb
.Dl \&.Fn execve \&Ap d
.Ss \&Aq
Encloses its arguments in angle brackets.
+The only important use case is for email addresses.
+See
+.Sx \&Mt
+for an example.
.Pp
-Examples:
-.Dl \&.Fl -key= \&Ns \&Aq \&Ar val
+Occasionally, it is used for names of characters and keys, for example:
+.Bd -literal -offset indent
+Press the
+\&.Aq escape
+key to ...
+.Ed
.Pp
-.Em Remarks :
-this macro is often abused for rendering URIs, which should instead use
+For URIs, use
.Sx \&Lk
+instead, and
+.Sx \&In
+for
+.Dq #include
+directives.
+Never wrap
+.Sx \&Ar
+in
+.Sx \&Aq .
+.Pp
+Since
+.Sx \&Aq
+usually renders with non-ASCII characters in non-ASCII output modes,
+do not use it where the ASCII characters
+.Sq <
+and
+.Sq >
+are required as syntax elements.
+Instead, use these characters directly in such cases, combining them
+with the macros
+.Sx \&Pf ,
+.Sx \&Ns ,
or
-.Sx \&Mt ,
-or to note pre-processor
-.Dq Li #include
-statements, which should use
-.Sx \&In .
+.Sx \&Eo
+as needed.
.Pp
See also
.Sx \&Ao .
.At .
.It Cm III
.At III .
-.It Cm V[.[1-4]]?
+.It Cm V | V.[1-4]
A version of
.At V .
.El
A columnated list.
The
.Fl width
-argument has no effect; instead, each argument specifies the width
-of one column, using either the scaling width syntax described in
-.Xr roff 7
-or the string length of the argument.
+argument has no effect; instead, the string length of each argument
+specifies the width of one column.
If the first line of the body of a
.Fl column
list is not an
.Ar month
is the full English month name, the
.Ar day
-is an optionally zero-padded numeral, and the
+is an integer number, and the
.Ar year
is the full four-digit year.
.Pp
.Pp
Examples:
.Dl \&.Dd $\&Mdocdate$
-.Dl \&.Dd $\&Mdocdate: July 21 2007$
-.Dl \&.Dd July 21, 2007
+.Dl \&.Dd $\&Mdocdate: July 2 2018$
+.Dl \&.Dd July 2, 2018
.Pp
See also
.Sx \&Dt
.Sx \&It
line itself; on following lines, only the
.Sx \&Ta
-macro can be used to delimit cells, and
+macro can be used to delimit cells, and portability requires that
.Sx \&Ta
-is only recognised as a macro when called by other macros,
-not as the first macro on a line.
+is called by other macros: some parsers do not recognize it when
+it appears as the first macro on a line.
.Pp
Note that quoted strings may span tab-delimited cells on an
.Sx \&It
.br
This standard is also called
X/Open Portability Guide version 7.
-.Pp
-.It \-p1003.1-2013
-.St -p1003.1-2013
-.br
-This is the first Technical Corrigendum.
.El
.It Other standards
.Pp
.Dl \&.Xr mandoc 1
.Dl \&.Xr mandoc 1 \&;
.Dl \&.Xr mandoc 1 \&Ns s behaviour
-.Ss \&br
-Emits a line-break.
-This macro should not be used; it is implemented for compatibility with
-historical manuals.
-.Pp
-Consider using
-.Sx \&Pp
-in the event of natural paragraph breaks.
-.Ss \&sp
-Emits vertical space.
-This macro should not be used; it is implemented for compatibility with
-historical manuals.
-Its syntax is as follows:
-.Pp
-.D1 Pf \. Sx \&sp Op Ar height
-.Pp
-The
-.Ar height
-argument is a scaling width as described in
-.Xr roff 7 .
-If unspecified,
-.Sx \&sp
-asserts a single vertical space.
.Sh MACRO SYNTAX
The syntax of a macro depends on its classification.
In this section,
.It Sx \&Va Ta Yes Ta Yes Ta n
.It Sx \&Vt Ta Yes Ta Yes Ta >0
.It Sx \&Xr Ta Yes Ta Yes Ta 2
-.It Sx \&br Ta \&No Ta \&No Ta 0
-.It Sx \&sp Ta \&No Ta \&No Ta 1
.El
.Ss Delimiters
When a macro argument consists of one single input character
.Xr tbl 7
.Pp
The web page
-.Lk http://mdocml.bsd.lv/mdoc/ "extended documentation for the mdoc language"
+.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
provides a few tutorial-style pages for beginners, an extensive style
guide for advanced authors, and an alphabetic index helping to choose
the best macros for various kinds of content.
git.ckatri.com / mandoc.git / blobdiff