Merge OpenBSD mdoc.7 rev. 1.56 and 1.57:

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 12ff50fdeaa32c38453f87c48b8e65f871375c09..329bedbb3a29905ac899094c55f29a4b1d40d58f 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.152 2010/08/24 12:18:49 kristaps Exp $
+.\"    $OpenBSD: mdoc.7,v 1.56 2010/11/28 15:45:26 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 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: August 24 2010 $
+.Dd $Mdocdate: November 30 2010 $

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


@@ -331,8 +331,9 @@ file:
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here

-\&.\e\*q The next is for sections 2, 3, & 9 only.

 \&.\e\*q .Sh LIBRARY
 \&.\e\*q .Sh LIBRARY

+\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.

 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options


@@ -342,18 +343,19 @@ The
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES

-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.

 \&.\e\*q .Sh RETURN VALUES
 \&.\e\*q .Sh RETURN VALUES

-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.

 \&.\e\*q .Sh ENVIRONMENT
 \&.\e\*q .Sh ENVIRONMENT

+\&.\e\*q For sections 1, 6, 7, & 8 only.

 \&.\e\*q .Sh FILES
 \&.\e\*q .Sh FILES

-\&.\e\*q The next is for sections 1 & 8 only.

 \&.\e\*q .Sh EXIT STATUS
 \&.\e\*q .Sh EXIT STATUS

+\&.\e\*q For sections 1, 6, & 8 only.

 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q .Sh EXAMPLES

-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.

 \&.\e\*q .Sh DIAGNOSTICS
 \&.\e\*q .Sh DIAGNOSTICS

-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q For sections 1, 4, 6, 7, & 8 only.

 \&.\e\*q .Sh ERRORS
 \&.\e\*q .Sh ERRORS

+\&.\e\*q For sections 2, 3, & 9 only.

 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS
 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS


@@ -362,6 +364,7 @@ utility processes files ...
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS

+\&.\e\*q Not used in OpenBSD.

 .Ed
 .Pp
 The sections in an
 .Ed
 .Pp
 The sections in an


@@ -601,20 +604,21 @@ closes it out.
 .Pp
 The
 .Em Callable
 .Pp
 The
 .Em Callable

-column indicates that the macro may be called subsequent to the initial
-line-macro.
-If a macro is not callable, then its invocation after the initial line
-macro is interpreted as opaque text, such that
+column indicates that the macro may also be called by passing its name
+as an argument to another macro.
+If a macro is not callable but its name appears as an argument
+to another macro, it is interpreted as opaque text.
+For example,

 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
 .Pp
 The
 .Em Parsed
 .Sq \&.Fl \&Sh
 produces
 .Sq Fl \&Sh .
 .Pp
 The
 .Em Parsed

-column indicates whether the macro may be followed by further
-(ostensibly callable) macros.
-If a macro is not parsed, subsequent macro invocations on the line
-will be interpreted as opaque text.
+column indicates whether the macro may call other macros by receiving
+their names as arguments.
+If a macro is not parsed but the name of another macro appears
+as an argument, it is interpreted as opaque text.

 .Pp
 The
 .Em Scope
 .Pp
 The
 .Em Scope


@@ -1073,7 +1077,8 @@ implementations render it poorly.
 Left- and right-justify the block.
 .It Fl literal
 Do not justify the block at all.
 Left- and right-justify the block.
 .It Fl literal
 Do not justify the block at all.

-Preserve white space as it appears in the input.
+Preserve white space and newlines as they appear in the input, including
+if it follows a macro.

 .It Fl ragged
 Only left-justify the block.
 .It Fl unfilled
 .It Fl ragged
 Only left-justify the block.
 .It Fl unfilled


@@ -1643,6 +1648,7 @@ It must be one of
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,
 .Ar luna88k ,
 .Ar mac68k ,
 .Ar macppc ,

+.Ar mips64 ,

 .Ar mvme68k ,
 .Ar mvme88k ,
 .Ar mvmeppc ,
 .Ar mvme68k ,
 .Ar mvme88k ,
 .Ar mvmeppc ,


@@ -1866,6 +1872,9 @@ Examples:
 \&.Fn funcname
 .Ed
 .Pp
 \&.Fn funcname
 .Ed
 .Pp

+When referring to a function documented in another manual page, use
+.Sx \&Xr
+instead.

 See also
 .Sx MANUAL STRUCTURE
 and
 See also
 .Sx MANUAL STRUCTURE
 and


@@ -2116,6 +2125,9 @@ Examples:
 Format a
 .Dq mailto:
 hyperlink.
 Format a
 .Dq mailto:
 hyperlink.

+If an argument is not provided, the string
+.Dq \(ti
+is used as a default.

 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Mt Cm address
 Its syntax is as follows:
 .Pp
 .D1 Pf \. Sx \&Mt Cm address


@@ -2297,6 +2309,9 @@ and
 .Sx \&Ux .
 .Ss \&Pa
 A file-system path.
 .Sx \&Ux .
 .Ss \&Pa
 A file-system path.

+If an argument is not provided, the string
+.Dq \(ti
+is used as a default.

 .Pp
 Examples:
 .D1 \&.Pa /usr/bin/mandoc
 .Pp
 Examples:
 .D1 \&.Pa /usr/bin/mandoc


@@ -2651,9 +2666,13 @@ and
 Close a scope opened by
 .Sx \&Xo .
 .Ss \&Xo
 Close a scope opened by
 .Sx \&Xo .
 .Ss \&Xo

-Open an extension scope.
-This macro originally existed to extend the 9-argument limit of troff;
-since this limit has been lifted, the macro has been deprecated.
+Extend the header of an
+.Sx \&It
+macro or the body of a partial-implicit block macro
+beyond the end of the input line.
+This macro originally existed to work around the 9-argument limit
+of historic
+.Xr roff 7 .

 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .
 .Ss \&Xr
 Link to another manual
 .Pq Qq cross-reference .


@@ -2707,10 +2726,10 @@ troff implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term
 .Qq historic groff
 .Pq Qq groff .
 The term
 .Qq historic groff

-refers to groff versions before the
+refers to groff versions before 1.17,
+which featured a significant update of the

 .Pa doc.tmac
 .Pa doc.tmac

-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+file.

 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.


@@ -2801,6 +2820,11 @@ can only be called by other macros, but not at the beginning of a line.
 .Sx \&%C
 is not implemented.
 .It
 .Sx \&%C
 is not implemented.
 .It

+Historic groff only allows up to eight or nine arguments per macro input
+line, depending on the exact situation.
+Providing more arguments causes garbled output.
+The number of arguments on one input line is not limited with mandoc.
+.It

 Historic groff has many un-callable macros.
 Most of these (excluding some block-level macros) are callable
 in new groff and mandoc.
 Historic groff has many un-callable macros.
 Most of these (excluding some block-level macros) are callable
 in new groff and mandoc.


@@ -2846,11 +2870,16 @@ The
 .Pq text filling colour ,
 .Sq \ez
 .Pq zero-length character ,
 .Pq text filling colour ,
 .Sq \ez
 .Pq zero-length character ,

+.Sq \ew
+.Pq string length ,
+.Sq \ek
+.Pq horizontal position marker ,
+.Sq \eo
+.Pq text overstrike ,

 and
 .Sq \es
 .Pq text size
 and
 .Sq \es
 .Pq text size

-.Sx Text Decoration
-escapes are all discarded in mandoc.
+escape sequences are all discarded in mandoc.

 .It
 The
 .Sq \ef
 .It
 The
 .Sq \ef


@@ -2861,6 +2890,7 @@ standalone double-quote in formatted output.
 This is not supported by mandoc.
 .El
 .Sh SEE ALSO
 This is not supported by mandoc.
 .El
 .Sh SEE ALSO

+.Xr man 1 ,

 .Xr mandoc 1 ,
 .Xr mandoc_char 7
 .Sh HISTORY
 .Xr mandoc 1 ,
 .Xr mandoc_char 7
 .Sh HISTORY


@@ -2869,7 +2899,7 @@ The
 language first appeared as a troff macro package in
 .Bx 4.4 .
 It was later significantly updated by Werner Lemberg and Ruslan Ermilov
 language first appeared as a troff macro package in
 .Bx 4.4 .
 It was later significantly updated by Werner Lemberg and Ruslan Ermilov

-in groff-1.20.1.
+in groff-1.17.

 The standalone implementation that is part of the
 .Xr mandoc 1
 utility written by Kristaps Dzonsons appeared in
 The standalone implementation that is part of the
 .Xr mandoc 1
 utility written by Kristaps Dzonsons appeared in