-.\" $Id: mdoc.7,v 1.185 2011/04/06 11:39:25 kristaps Exp $
+.\" $Id: mdoc.7,v 1.191 2011/07/18 10:23:02 kristaps Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 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: April 6 2011 $
+.Dd $Mdocdate: July 18 2011 $
.Dt MDOC 7
.Os
.Sh NAME
.Pq reserved-word vertical bar
.El
.Pp
-Use of reserved terms is described in
-.Sx MACRO SYNTAX .
For general use in macro lines, these can be escaped with a non-breaking
space
.Pq Sq \e& .
.Pp
The following is a well-formed skeleton
.Nm
-file:
+file for a utility
+.Qq progname :
.Bd -literal -offset indent
\&.Dd $\&Mdocdate$
-\&.Dt mdoc 7
+\&.Dt PROGNAME section
\&.Os
\&.Sh NAME
-\&.Nm foo
+\&.Nm progname
\&.Nd a description goes here
\&.\e\*q .Sh LIBRARY
\&.\e\*q For sections 2, 3, & 9 only.
\&.\e\*q Not used in OpenBSD.
\&.Sh SYNOPSIS
-\&.Nm foo
+\&.Nm progname
\&.Op Fl options
\&.Ar
\&.Sh DESCRIPTION
.Em SYNOPSIS
section line, else it is
.Sx In-line .
+.Ss Special block macro
+The
+.Sx \&Ta
+macro can only be used below
+.Sx \&It
+in
+.Sx \&Bl Fl column
+lists.
+It delimits blocks representing table cells;
+these blocks have bodies, but no heads.
+.Pp
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
+.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
+.El
.Ss In-line
Closed by
.Sx Reserved Terms ,
and
.Sx \&Sy .
.Ss \&Bk
-Keep the output generated from each macro input line together
-on one single output line.
+For each macro, keep its output together on the same output line,
+until the end of the macro or the end of the input line is reached,
+whichever comes first.
Line breaks in text lines are unaffected.
The syntax is as follows:
.Pp
and
.Sx \&Os .
.Ss \&Dv
-Defined variables such as preprocessor constants.
+Defined variables such as preprocessor constants, constant symbols,
+enumeration values, and so on.
.Pp
Examples:
+.Dl \&.Dv NULL
.Dl \&.Dv BUFSIZ
.Dl \&.Dv STDOUT_FILENO
.Pp
See also
-.Sx \&Er .
+.Sx \&Er
+and
+.Sx \&Ev
+for special-purpose constants and
+.Sx \&Va
+for variable symbols.
.Ss \&Dx
Format the DragonFly BSD version provided as an argument, or a default
value if no argument is provided.
will emulate
.Sx \&Do .
.Ss \&Er
-Display error constants.
+Error constants for definitions of the
+.Va errno
+libc global variable.
.Pp
Examples:
.Dl \&.Er EPERM
.Dl \&.Er ENOENT
.Pp
See also
-.Sx \&Dv .
+.Sx \&Dv
+for general constants.
.Ss \&Es
This macro is obsolete and not implemented.
.Ss \&Ev
Examples:
.Dl \&.Ev DISPLAY
.Dl \&.Ev PATH
+.Pp
+See also
+.Sx \&Dv
+for general constants.
.Ss \&Ex
-Insert a standard sentence regarding exit values.
+Insert a standard sentence regarding command exit values of 0 on success
+and >0 on failure.
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&Ex Fl std Op Ar utility
+.D1 Pf \. Sx \&Ex Fl std Op Ar utility...
.Pp
-When
+If
.Ar utility
is not specified, the document's name set by
.Sx \&Nm
is used.
+Multiple
+.Ar utility
+arguments are treated as separate utilities.
.Pp
See also
.Sx \&Rv .
.Sx \&Fc ,
and
.Sx \&Ft .
+.Ss \&Fr
+This macro is obsolete and not implemented.
.Ss \&Ft
A function type.
Its syntax is as follows:
list is the most complicated.
Its syntax is as follows:
.Pp
-.D1 Pf \. Sx \&It Op Cm args
+.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
+.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
.Pp
-The
-.Cm args
-are phrases, a mix of macros and text corresponding to a line column,
-delimited by tabs or the special
-.Sq \&Ta
-pseudo-macro.
-Lines subsequent the
+The arguments consist of one or more lines of text and macros
+representing a complete table line.
+Cells within the line are delimited by tabs or by the special
+.Sx \&Ta
+block macro.
+The tab cell delimiter may only be used within the
.Sx \&It
-are interpreted within the scope of the last phrase.
-Calling the pseudo-macro
-.Sq \&Ta
-will open a new phrase scope (this must occur on a macro line to be
-interpreted as a macro).
-Note that the tab phrase delimiter may only be used within the
+line itself; on following lines, only the
+.Sx \&Ta
+macro can be used to delimit cells, and
+.Sx \&Ta
+is only recognized as a macro when called by other macros,
+not as the first macro on a line.
+.Pp
+Note that quoted strings may span tab-delimited cells on an
.Sx \&It
-line itself.
-Subsequent this, only the
-.Sq \&Ta
-pseudo-macro may be used to delimit phrases.
-Furthermore, note that quoted sections propagate over tab-delimited
-phrases on an
-.Sx \&It ,
-for example,
+line.
+For example,
.Pp
.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
.Pp
before the rendered output, else the block continues on the current
line.
.Ss \&Rv
-Inserts text regarding a function call's return value.
-This macro must consist of the
-.Fl std
-argument followed by an optional
-.Ar function .
+Insert a standard sentence regarding a system call's return value of 0
+on success and \-1 on error, with the
+.Va errno
+libc global variable set on error.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&Rv Fl std Op Ar function...
+.Pp
If
.Ar function
-is not provided, the document's name as stipulated by the first
+is not specified, the document's name set by
.Sx \&Nm
-is provided.
+is used.
+Multiple
+.Ar function
+arguments are treated as separate functions.
.Pp
See also
.Sx \&Ex .
.Sx \&Li ,
and
.Sx \&Em .
+.Ss \&Ta
+Table cell separator in
+.Sx \&Bl Fl column
+lists; can only be used below
+.Sx \&It .
.Ss \&Tn
Format a tradename.
.Pp
.Qq AT&T UNIX
and the arguments.
.It
-.Sx \&Bd Fl column
+.Sx \&Bl Fl column
does not recognize trailing punctuation characters when they immediately
precede tabulator characters, but treats them as normal text and
outputs a space before them.
git.ckatri.com / mandoc.git / blobdiff