Drop explicit, constant style=margin-left attribute on .Bf blocks.

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 00ed53ed5b044ef4112d5d79f245296ad908d55d..1efd8cf0d6804b312f225ba18f75cdaa70b6d42a 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $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>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013-2017 Ingo Schwarze <schwarze@openbsd.org>


@@ -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.
 .\"
 .\" 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
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -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 \&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
 .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)
 .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
 .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)
 .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
 .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
 .Bl -column "Brq, Bro, Brc" description
 .It Sx \&An Ta author name (>0 arguments)
 .It Sx \&Lk Ta hyperlink: Ar uri Op Ar name


@@ -675,12 +674,10 @@ Examples:
 .Ss \&Ao
 Begin a block enclosed by angle brackets.
 Does not have any head arguments.
 .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
 .Ss \&Ap
 Inserts an apostrophe without any surrounding whitespace.
 This is generally used as a grammatical device when referring to the verb


@@ -690,19 +687,45 @@ Examples:
 .Dl \&.Fn execve \&Ap d
 .Ss \&Aq
 Encloses its arguments in angle brackets.
 .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
 .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
 .Pp

-.Em Remarks :
-this macro is often abused for rendering URIs, which should instead use
+For URIs, use

 .Sx \&Lk
 .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
 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 .
 .Pp
 See also
 .Sx \&Ao .


@@ -736,7 +759,7 @@ A version of
 .At .
 .It Cm III
 .At III .
 .At .
 .It Cm III
 .At III .

-.It Cm V[.[1-4]]?
+.It Cm V | V.[1-4]

 A version of
 .At V .
 .El
 A version of
 .At V .
 .El


@@ -1851,10 +1874,10 @@ The tab cell delimiter may only be used within the
 .Sx \&It
 line itself; on following lines, only the
 .Sx \&Ta
 .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
 .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
 .Pp
 Note that quoted strings may span tab-delimited cells on an
 .Sx \&It


@@ -2576,11 +2599,6 @@ The second and last Technical Corrigendum.
 .br
 This standard is also called
 X/Open Portability Guide version 7.
 .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
 .El
 .It Other standards
 .Pp


@@ -2735,21 +2753,6 @@ Examples:
 .Dl \&.Xr mandoc 1
 .Dl \&.Xr mandoc 1 \&;
 .Dl \&.Xr mandoc 1 \&Ns s behaviour
 .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,
 .Sh MACRO SYNTAX
 The syntax of a macro depends on its classification.
 In this section,


@@ -3034,7 +3037,6 @@ then the macro accepts an arbitrary number of arguments.
 .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 \&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
 .El
 .Ss Delimiters
 When a macro argument consists of one single input character


@@ -3220,7 +3222,7 @@ but produces large indentations.
 .Xr tbl 7
 .Pp
 The web page
 .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.
 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.