-.\" $Id: mdoc.7,v 1.150 2010/08/22 14:54:29 kristaps Exp $
+.\" $Id: mdoc.7,v 1.167 2010/11/30 21:44:59 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\" 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 22 2010 $
+.Dd $Mdocdate: November 30 2010 $
.Dt MDOC 7
.Os
.Sh NAME
\&.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 For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.
\&.Sh SYNOPSIS
\&.Nm foo
\&.Op Fl options
\&.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 The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.
\&.\e\*q .Sh ENVIRONMENT
+\&.\e\*q For sections 1, 6, 7, & 8 only.
\&.\e\*q .Sh FILES
-\&.\e\*q The next is for sections 1 & 8 only.
\&.\e\*q .Sh EXIT STATUS
+\&.\e\*q For sections 1, 6, & 8 only.
\&.\e\*q .Sh EXAMPLES
-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.
\&.\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 For sections 2, 3, & 9 only.
\&.\e\*q .Sh SEE ALSO
\&.\e\*q .Xr foobar 1
\&.\e\*q .Sh STANDARDS
\&.\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
.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
-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
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
.Ar luna88k ,
.Ar mac68k ,
.Ar macppc ,
+.Ar mips64 ,
.Ar mvme68k ,
.Ar mvme88k ,
.Ar mvmeppc ,
\&.Fn funcname
.Ed
.Pp
+When referring to a function documented in another manual page, use
+.Sx \&Xr
+instead.
See also
.Sx MANUAL STRUCTURE
and
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
.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
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 .
.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
-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.
.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.
.Pq text colour ,
.Sq \eM
.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
-.Sx Text Decoration
-escapes are all discarded in mandoc.
+escape sequences are all discarded in mandoc.
.It
The
.Sq \ef
This is not supported by mandoc.
.El
.Sh SEE ALSO
+.Xr man 1 ,
.Xr mandoc 1 ,
.Xr mandoc_char 7
+.Sh HISTORY
+The
+.Nm
+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.17.
+The standalone implementation that is part of the
+.Xr mandoc 1
+utility written by Kristaps Dzonsons appeared in
+.Ox 4.6 .
.Sh AUTHORS
The
.Nm
git.ckatri.com / mandoc.git / blobdiff