===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.263
retrieving revision 1.273
diff -u -p -r1.263 -r1.273
--- mandoc/mdoc.7	2017/05/05 02:31:35	1.263
+++ mandoc/mdoc.7	2018/12/23 16:55:34	1.273
@@ -1,7 +1,7 @@
-.\"	$Id: mdoc.7,v 1.263 2017/05/05 02:31:35 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.273 2018/12/23 16:55:34 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
@@ -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: May 5 2017 $
+.Dd $Mdocdate: December 23 2018 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -449,7 +449,7 @@ in the alphabetical
 .It Sx \&Ss Ta subsection header (one line)
 .It Sx \&Sx Ta internal cross reference to a section or subsection
 .It Sx \&Xr Ta cross reference to another manual page: Ar name section
-.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
+.It Sx \&Pp Ta start a text paragraph (no arguments)
 .El
 .Ss Displays and lists
 .Bl -column "Brq, Bro, Brc" description
@@ -476,9 +476,8 @@ in the alphabetical
 .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)
@@ -489,7 +488,7 @@ in the alphabetical
 .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)
@@ -510,7 +509,7 @@ in the alphabetical
 .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
@@ -523,7 +522,6 @@ in the alphabetical
 .Bl -column "Brq, Bro, Brc" description
 .It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
 .It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
-.It Sx \&Li Ta typewriter font (literal) (>0 arguments)
 .It Sx \&No Ta return to roman font (normal) (no arguments)
 .It Sx \&Bf , \&Ef Ta font block:
 .Op Fl Ar type | Cm \&Em | \&Li | \&Sy
@@ -675,12 +673,10 @@ Examples:
 .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
@@ -690,19 +686,45 @@ Examples:
 .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 .
@@ -736,7 +758,7 @@ A version of
 .At .
 .It Cm III
 .At III .
-.It Cm V[.[1-4]]?
+.It Cm V | V.[1-4]
 A version of
 .At V .
 .El
@@ -1211,7 +1233,7 @@ The
 .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
@@ -1241,8 +1263,8 @@ If no date string is given, the current date is used.
 .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
@@ -1451,9 +1473,8 @@ to save the pattern space for subsequent retrieval.
 .Ed
 .Pp
 See also
-.Sx \&Bf ,
-.Sx \&Li ,
 .Sx \&No ,
+.Sx \&Ql ,
 and
 .Sx \&Sy .
 .Ss \&En
@@ -1753,12 +1774,13 @@ Examples:
 .Dl \&.Ic alias
 .Pp
 Note that using
-.Sx \&Bd Fl literal
+.Sx \&Ql ,
+.Sx \&Dl ,
 or
-.Sx \&D1
-is preferred for displaying code; the
+.Sx \&Bd Fl literal
+is preferred for displaying code samples; the
 .Sx \&Ic
-macro is used when referring to specific instructions.
+macro is used when referring to an individual command name.
 .Ss \&In
 The name of an include file.
 This macro is most often used in section 2, 3, and 9 manual pages.
@@ -1851,10 +1873,10 @@ The tab cell delimiter may only be used within the
 .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
@@ -1892,21 +1914,15 @@ Examples:
 .Dl \&.Lb libz
 .Dl \&.Lb libmandoc
 .Ss \&Li
-Denotes text that should be in a
-.Li literal
-font mode.
-Note that this is a presentation term and should not be used for
-stylistically decorating technical terms.
-.Pp
-On terminal output devices, this is often indistinguishable from
-normal text.
-.Pp
-See also
-.Sx \&Bf ,
-.Sx \&Em ,
-.Sx \&No ,
-and
-.Sx \&Sy .
+Request a typewriter (literal) font.
+Deprecated because on terminal output devices, this is usually
+indistinguishable from normal text.
+For literal displays, use
+.Sx \&Ql Pq in-line ,
+.Sx \&Dl Pq single line ,
+or
+.Sx \&Bd Fl literal Pq multi-line
+instead.
 .Ss \&Lk
 Format a hyperlink.
 Its syntax is as follows:
@@ -1920,7 +1936,7 @@ Examples:
 See also
 .Sx \&Mt .
 .Ss \&Lp
-Synonym for
+Deprecated synonym for
 .Sx \&Pp .
 .Ss \&Ms
 Display a mathematical symbol.
@@ -2023,7 +2039,7 @@ Examples:
 .Pp
 See also
 .Sx \&Em ,
-.Sx \&Li ,
+.Sx \&Ql ,
 and
 .Sx \&Sy .
 .Ss \&Ns
@@ -2221,14 +2237,8 @@ Close quoted context opened by
 .Sx \&Qo .
 .Ss \&Ql
 In-line literal display.
-This can for example be used for complete command invocations and
-for multi-word code fragments when more specific markup is not
-appropriate and an indented display is not desired.
-While
-.Xr mandoc 1
-always encloses the arguments in single quotes, other formatters
-usually omit the quotes on non-terminal output devices when the
-arguments have three or more characters.
+This can be used for complete command invocations and for multi-word
+code examples when an indented display is not desired.
 .Pp
 See also
 .Sx \&Dl
@@ -2576,11 +2586,6 @@ The second and last Technical Corrigendum.
 .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
@@ -2637,11 +2642,10 @@ program.
 .Ed
 .Pp
 See also
-.Sx \&Bf ,
 .Sx \&Em ,
-.Sx \&Li ,
+.Sx \&No ,
 and
-.Sx \&No .
+.Sx \&Ql .
 .Ss \&Ta
 Table cell separator in
 .Sx \&Bl Fl column
@@ -2735,21 +2739,6 @@ Examples:
 .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,
@@ -3034,7 +3023,6 @@ then the macro accepts an arbitrary number of argument
 .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
@@ -3220,7 +3208,7 @@ but produces large indentations.
 .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.