-.\" $Id: mdoc.7,v 1.263 2017/05/05 02:31:35 schwarze Exp $
+.\" $Id: mdoc.7,v 1.270 2017/10/23 13:54:41 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010, 2011, 2013-2017 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: May 5 2017 $
+.Dd $Mdocdate: October 23 2017 $
.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 \&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
.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 \&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 \&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