libmdoc.h no longer needs mdoc.h

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 0d167e406fc028e9228c29fcfb012e4ac332b3cd..5c07434cd80e6d5baa70db10cd176977b27ec862 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,7 +1,7 @@
-.\"    $Id: mdoc.7,v 1.265 2017/06/10 16:32:27 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) 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
 .\"
 .\" 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.
 .\"
 .\" 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 10 2017 $
+.Dd $Mdocdate: July 28 2018 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -477,7 +477,7 @@ in the alphabetical
 .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
 .It Sx \&Bk , \&Ek Ta keep block: Fl words
 .El
 .It Sx \&Sm Ta switch horizontal spacing mode: Op Cm on | off
 .It Sx \&Bk , \&Ek Ta keep block: Fl words
 .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)


@@ -488,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)


@@ -509,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


@@ -674,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


@@ -689,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 .


@@ -1210,7 +1234,7 @@ The
 .Ar month
 is the full English month name, the
 .Ar day
 .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
 .Ar year
 is the full four-digit year.
 .Pp


@@ -1240,8 +1264,8 @@ If no date string is given, the current date is used.
 .Pp
 Examples:
 .Dl \&.Dd $\&Mdocdate$
 .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
 .Pp
 See also
 .Sx \&Dt


@@ -1850,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


@@ -2575,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


@@ -3203,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.