Split mlinks_undupe() out of mpages_merge()

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 4c1f92227d40f6c22032068872cb080aa2c74528..165c76b950013ca361336d6c2fb7f0d8d4449240 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,7 +1,7 @@
-.\"    $Id: mdoc.7,v 1.215 2012/06/20 22:06:30 schwarze Exp $
+.\"    $Id: mdoc.7,v 1.223 2013/12/25 14:09:32 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 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2013 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 20 2012 $
+.Dd $Mdocdate: December 25 2013 $

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


@@ -477,6 +477,7 @@ in the alphabetical
 .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)

+.It Sx \&Fd Ta other preprocessor directive (>0 arguments)

 .It Sx \&Ft Ta function type (>0 arguments)
 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
 .It Sx \&Fn Ta function name:
 .It Sx \&Ft Ta function type (>0 arguments)
 .It Sx \&Fo , \&Fc Ta function block: Ar funcname
 .It Sx \&Fn Ta function name:


@@ -657,7 +658,7 @@ for all other author listings.
 .Pp
 Examples:
 .Dl \&.An -nosplit
 .Pp
 Examples:
 .Dl \&.An -nosplit

-.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv

 .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.


@@ -711,7 +712,9 @@ for fixed strings to be passed verbatim as arguments, use
 or
 .Sx \&Cm .
 .Ss \&At
 or
 .Sx \&Cm .
 .Ss \&At

-Formats an AT&T version.
+Formats an
+.At
+version.

 Accepts one optional argument:
 .Pp
 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
 Accepts one optional argument:
 .Pp
 .Bl -tag -width "v[1-7] | 32vX" -offset indent -compact


@@ -1089,7 +1092,9 @@ Examples:
 See also
 .Sx \&Bro .
 .Ss \&Bsx
 See also
 .Sx \&Bro .
 .Ss \&Bsx

-Format the BSD/OS version provided as an argument, or a default value if
+Format the
+.Bsx
+version provided as an argument, or a default value if

 no argument is provided.
 .Pp
 Examples:
 no argument is provided.
 .Pp
 Examples:


@@ -1109,7 +1114,9 @@ and
 Prints
 .Dq is currently in beta test.
 .Ss \&Bx
 Prints
 .Dq is currently in beta test.
 .Ss \&Bx

-Format the BSD version provided as an argument, or a default value if no
+Format the
+.Bx
+version provided as an argument, or a default value if no

 argument is provided.
 .Pp
 Examples:
 argument is provided.
 .Pp
 Examples:


@@ -1401,11 +1408,16 @@ See also
 .Sx \&Er
 and
 .Sx \&Ev
 .Sx \&Er
 and
 .Sx \&Ev

-for special-purpose constants and
+for special-purpose constants,

 .Sx \&Va
 .Sx \&Va

-for variable symbols.
+for variable symbols, and
+.Sx \&Fd
+for listing preprocessor variable definitions in the
+.Em SYNOPSIS .

 .Ss \&Dx
 .Ss \&Dx

-Format the DragonFly BSD version provided as an argument, or a default
+Format the
+.Dx
+version provided as an argument, or a default

 value if no argument is provided.
 .Pp
 Examples:
 value if no argument is provided.
 .Pp
 Examples:


@@ -1562,15 +1574,32 @@ See also
 End a function context started by
 .Sx \&Fo .
 .Ss \&Fd
 End a function context started by
 .Sx \&Fo .
 .Ss \&Fd

-Historically used to document include files.
-This usage has been deprecated in favour of
+Preprocessor directive, in particular for listing it in the
+.Em SYNOPSIS .
+Historically, it was also used to document include files.
+The latter usage has been deprecated in favour of

 .Sx \&In .
 .Sx \&In .

-Do not use this macro.
+.Pp
+Its syntax is as follows:
+.Bd -ragged -offset indent
+.Pf \. Sx \&Fd
+.Li # Ns Ar directive
+.Op Ar argument ...
+.Ed
+.Pp
+Examples:
+.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler
+.Dl \&.Fd #define SIO_MAXNFDS
+.Dl \&.Fd #ifdef FS_DEBUG
+.Dl \&.Ft void
+.Dl \&.Fn dbg_open \(dqconst char *\(dq
+.Dl \&.Fd #endif

 .Pp
 See also
 .Pp
 See also

-.Sx MANUAL STRUCTURE
+.Sx MANUAL STRUCTURE ,
+.Sx \&In ,

 and
 and

-.Sx \&In .
+.Sx \&Dv .

 .Ss \&Fl
 Command-line flag or option.
 Used when listing arguments to command-line utilities.
 .Ss \&Fl
 Command-line flag or option.
 Used when listing arguments to command-line utilities.


@@ -1851,7 +1880,7 @@ section as described in
 .Pp
 Examples:
 .Dl \&.Lb libz
 .Pp
 Examples:
 .Dl \&.Lb libz

-.Dl \&.Lb mdoc
+.Dl \&.Lb libmandoc

 .Ss \&Li
 Denotes text that should be in a
 .Li literal
 .Ss \&Li
 Denotes text that should be in a
 .Li literal


@@ -1902,6 +1931,7 @@ Its syntax is as follows:
 .Pp
 Examples:
 .Dl \&.Mt discuss@manpages.bsd.lv
 .Pp
 Examples:
 .Dl \&.Mt discuss@manpages.bsd.lv

+.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv

 .Ss \&Nd
 A one line description of the manual's content.
 This may only be invoked in the
 .Ss \&Nd
 A one line description of the manual's content.
 This may only be invoked in the


@@ -2083,7 +2113,7 @@ This macro is obsolete and not implemented in
 .Xr mandoc 1 .
 .Pp
 Historical
 .Xr mandoc 1 .
 .Pp
 Historical

-.Xr mdoc 7
+.Nm

 packages described it as
 .Dq "old function type (FORTRAN)" .
 .Ss \&Ox
 packages described it as
 .Dq "old function type (FORTRAN)" .
 .Ss \&Ox


@@ -2347,20 +2377,26 @@ The following standards are recognised:
 .St -p1003.1b-93
 .It \-p1003.1c-95
 .St -p1003.1c-95
 .St -p1003.1b-93
 .It \-p1003.1c-95
 .St -p1003.1c-95

+.It \-p1003.1d-99
+.St -p1003.1d-99

 .It \-p1003.1g-2000
 .St -p1003.1g-2000
 .It \-p1003.1i-95
 .St -p1003.1i-95
 .It \-p1003.1g-2000
 .St -p1003.1g-2000
 .It \-p1003.1i-95
 .St -p1003.1i-95

+.It \-p1003.1j-2000
+.St -p1003.1j-2000
+.It \-p1003.1q-2000
+.St -p1003.1q-2000
+.It \-p1003.2
+.St -p1003.2

 .It \-p1003.2-92
 .St -p1003.2-92
 .It \-p1003.2a-92
 .St -p1003.2a-92
 .It \-p1003.2-92
 .St -p1003.2-92
 .It \-p1003.2a-92
 .St -p1003.2a-92

-.It \-p1387.2-95
-.St -p1387.2-95
-.It \-p1003.2
-.St -p1003.2

 .It \-p1387.2
 .St -p1387.2
 .It \-p1387.2
 .St -p1387.2

+.It \-p1387.2-95
+.St -p1387.2-95

 .It \-isoC
 .St -isoC
 .It \-isoC-90
 .It \-isoC
 .St -isoC
 .It \-isoC-90


@@ -2407,6 +2443,8 @@ The following standards are recognised:
 .St -xbd5
 .It \-xcu5
 .St -xcu5
 .St -xbd5
 .It \-xcu5
 .St -xcu5

+.It \-xsh4.2
+.St -xsh4.2

 .It \-xsh5
 .St -xsh5
 .It \-xns5
 .It \-xsh5
 .St -xsh5
 .It \-xns5


@@ -2467,7 +2505,9 @@ Examples:
 Prints out
 .Dq currently under development.
 .Ss \&Ux
 Prints out
 .Dq currently under development.
 .Ss \&Ux

-Format the UNIX name.
+Format the
+.Ux
+name.

 Accepts no argument.
 .Pp
 Examples:
 Accepts no argument.
 .Pp
 Examples:


@@ -2532,20 +2572,14 @@ Link to another manual
 .Pq Qq cross-reference .
 Its syntax is as follows:
 .Pp
 .Pq Qq cross-reference .
 Its syntax is as follows:
 .Pp

-.D1 Pf \. Sx \&Xr Ar name section
+.D1 Pf \. Sx \&Xr Ar name Op section

 .Pp
 .Pp

-The
+Cross reference the

 .Ar name
 and
 .Ar section
 .Ar name
 and
 .Ar section

-are the name and section of the linked manual.
-If
-.Ar section
-is followed by non-punctuation, an
-.Sx \&Ns
-is inserted into the token stream.
-This behaviour is for compatibility with
-GNU troff.
+number of another man page;
+omitting the section number is rarely useful.

 .Pp
 Examples:
 .Dl \&.Xr mandoc 1
 .Pp
 Examples:
 .Dl \&.Xr mandoc 1


@@ -2964,7 +2998,7 @@ Manually switching the font using the
 .Ql \ef
 font escape sequences is never required.
 .Sh COMPATIBILITY
 .Ql \ef
 font escape sequences is never required.
 .Sh COMPATIBILITY

-This section documents compatibility between mandoc and other other
+This section documents compatibility between mandoc and other

 troff implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term
 troff implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term


@@ -3168,5 +3202,4 @@ utility written by Kristaps Dzonsons appeared in
 The
 .Nm
 reference was written by
 The
 .Nm
 reference was written by

-.An Kristaps Dzonsons ,
-.Mt kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .