version 1.174, 2011/01/04 23:32:21 |
version 1.183, 2011/04/01 19:47:33 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
Line 52 Other lines are interpreted within the current state. |
|
Line 52 Other lines are interpreted within the current state. |
|
.Nm |
.Nm |
documents may contain only graphable 7-bit ASCII characters, the space |
documents may contain only graphable 7-bit ASCII characters, the space |
character, and, in certain circumstances, the tab character. |
character, and, in certain circumstances, the tab character. |
All manuals must have |
.Pp |
.Ux |
If the first character of a line is a space, that line is printed |
line terminators. |
with a leading newline. |
.Ss Comments |
.Ss Comments |
Text following a |
Text following a |
.Sq \e\*q , |
.Sq \e\*q , |
Line 65 A macro line with only a control character and comment |
|
Line 65 A macro line with only a control character and comment |
|
is also ignored. |
is also ignored. |
Macro lines with only a control character and optional whitespace are |
Macro lines with only a control character and optional whitespace are |
stripped from input. |
stripped from input. |
.Ss Reserved Characters |
.Ss Reserved Terms |
Within a macro line, the following characters are reserved: |
Within a macro line, the following terms are reserved: |
.Pp |
.Pp |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It \&. |
.It \&. |
.Pq period |
.Pq period |
|
.It \e. |
|
.Pq escaped period |
.It \&, |
.It \&, |
.Pq comma |
.Pq comma |
.It \&: |
.It \&: |
Line 91 Within a macro line, the following characters are rese |
|
Line 93 Within a macro line, the following characters are rese |
|
.Pq exclamation |
.Pq exclamation |
.It \&| |
.It \&| |
.Pq vertical bar |
.Pq vertical bar |
|
.It \e*(Ba |
|
.Pq reserved-word vertical bar |
.El |
.El |
.Pp |
.Pp |
Use of reserved characters is described in |
Use of reserved terms is described in |
.Sx MACRO SYNTAX . |
.Sx MACRO SYNTAX . |
For general use in macro lines, these characters can either be escaped |
For general use in macro lines, these can be escaped with a non-breaking |
with a non-breaking space |
space |
.Pq Sq \e& |
.Pq Sq \e& . |
or, if applicable, an appropriate escape sequence can be used. |
|
.Ss Special Characters |
.Ss Special Characters |
Special characters may occur in both macro and free-form lines. |
Special characters may occur in both macro and free-form lines. |
Sequences begin with the escape character |
Sequences begin with the escape character |
Line 197 Thus, the following produces |
|
Line 200 Thus, the following produces |
|
.Ed |
.Ed |
.Pp |
.Pp |
In free-form mode, quotes are regarded as opaque text. |
In free-form mode, quotes are regarded as opaque text. |
.Ss Dates |
|
There are several macros in |
|
.Nm |
|
that require a date argument. |
|
The canonical form for dates is the American format: |
|
.Pp |
|
.D1 Cm Month Day , Year |
|
.Pp |
|
The |
|
.Cm Day |
|
value is an optionally zero-padded numeral. |
|
The |
|
.Cm Month |
|
value is the full month name. |
|
The |
|
.Cm Year |
|
value is the full four-digit year. |
|
.Pp |
|
Reduced form dates are broken-down canonical form dates: |
|
.Pp |
|
.D1 Cm Month , Year |
|
.D1 Cm Year |
|
.Pp |
|
Some examples of valid dates follow: |
|
.Pp |
|
.D1 "May, 2009" Pq reduced form |
|
.D1 "2009" Pq reduced form |
|
.D1 "May 20, 2009" Pq canonical form |
|
.Ss Scaling Widths |
.Ss Scaling Widths |
Many macros support scaled widths for their arguments, such as |
Many macros support scaled widths for their arguments, such as |
stipulating a two-inch list indentation with the following: |
stipulating a two-inch list indentation with the following: |
|
|
By doing so, front-ends will be able to apply the proper amount of |
By doing so, front-ends will be able to apply the proper amount of |
spacing after the end of sentence (unescaped) period, exclamation mark, |
spacing after the end of sentence (unescaped) period, exclamation mark, |
or question mark followed by zero or more non-sentence closing |
or question mark followed by zero or more non-sentence closing |
delimiters ( |
delimiters |
.Ns Sq \&) , |
.Po |
|
.Sq \&) , |
.Sq \&] , |
.Sq \&] , |
.Sq \&' , |
.Sq \&' , |
.Sq \&" ) . |
.Sq \&" |
|
.Pc . |
.Pp |
.Pp |
The proper spacing is also intelligently preserved if a sentence ends at |
The proper spacing is also intelligently preserved if a sentence ends at |
the boundary of a macro line. |
the boundary of a macro line. |
|
|
.El |
.El |
.Ss Block partial-implicit |
.Ss Block partial-implicit |
Like block full-implicit, but with single-line scope closed by |
Like block full-implicit, but with single-line scope closed by |
.Sx Reserved Characters |
.Sx Reserved Terms |
or end of line. |
or end of line. |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB |
Line 765 section line, else it is |
|
Line 742 section line, else it is |
|
.Sx In-line . |
.Sx In-line . |
.Ss In-line |
.Ss In-line |
Closed by |
Closed by |
.Sx Reserved Characters , |
.Sx Reserved Terms , |
end of line, fixed argument lengths, and/or subsequent macros. |
end of line, fixed argument lengths, and/or subsequent macros. |
In-line macros have only text children. |
In-line macros have only text children. |
If a number (or inequality) of arguments is |
If a number (or inequality) of arguments is |
Line 795 then the macro accepts an arbitrary number of argument |
|
Line 772 then the macro accepts an arbitrary number of argument |
|
.It Sx \&%T Ta \&No Ta \&No Ta >0 |
.It Sx \&%T Ta \&No Ta \&No Ta >0 |
.It Sx \&%U Ta \&No Ta \&No Ta >0 |
.It Sx \&%U Ta \&No Ta \&No Ta >0 |
.It Sx \&%V Ta \&No Ta \&No Ta >0 |
.It Sx \&%V Ta \&No Ta \&No Ta >0 |
.It Sx \&Ad Ta Yes Ta Yes Ta n |
.It Sx \&Ad Ta Yes Ta Yes Ta >0 |
.It Sx \&An Ta Yes Ta Yes Ta n |
.It Sx \&An Ta Yes Ta Yes Ta >0 |
.It Sx \&Ap Ta Yes Ta Yes Ta 0 |
.It Sx \&Ap Ta Yes Ta Yes Ta 0 |
.It Sx \&Ar Ta Yes Ta Yes Ta n |
.It Sx \&Ar Ta Yes Ta Yes Ta n |
.It Sx \&At Ta Yes Ta Yes Ta 1 |
.It Sx \&At Ta Yes Ta Yes Ta 1 |
Line 804 then the macro accepts an arbitrary number of argument |
|
Line 781 then the macro accepts an arbitrary number of argument |
|
.It Sx \&Bt Ta \&No Ta \&No Ta 0 |
.It Sx \&Bt Ta \&No Ta \&No Ta 0 |
.It Sx \&Bx Ta Yes Ta Yes Ta n |
.It Sx \&Bx Ta Yes Ta Yes Ta n |
.It Sx \&Cd Ta Yes Ta Yes Ta >0 |
.It Sx \&Cd Ta Yes Ta Yes Ta >0 |
.It Sx \&Cm Ta Yes Ta Yes Ta n |
.It Sx \&Cm Ta Yes Ta Yes Ta >0 |
.It Sx \&Db Ta \&No Ta \&No Ta 1 |
.It Sx \&Db Ta \&No Ta \&No Ta 1 |
.It Sx \&Dd Ta \&No Ta \&No Ta n |
.It Sx \&Dd Ta \&No Ta \&No Ta n |
.It Sx \&Dt Ta \&No Ta \&No Ta n |
.It Sx \&Dt Ta \&No Ta \&No Ta n |
.It Sx \&Dv Ta Yes Ta Yes Ta n |
.It Sx \&Dv Ta Yes Ta Yes Ta >0 |
.It Sx \&Dx Ta Yes Ta Yes Ta n |
.It Sx \&Dx Ta Yes Ta Yes Ta n |
.It Sx \&Em Ta Yes Ta Yes Ta >0 |
.It Sx \&Em Ta Yes Ta Yes Ta >0 |
.It Sx \&En Ta \&No Ta \&No Ta 0 |
.It Sx \&En Ta \&No Ta \&No Ta 0 |
.It Sx \&Er Ta Yes Ta Yes Ta >0 |
.It Sx \&Er Ta Yes Ta Yes Ta >0 |
.It Sx \&Es Ta \&No Ta \&No Ta 0 |
.It Sx \&Es Ta \&No Ta \&No Ta 0 |
.It Sx \&Ev Ta Yes Ta Yes Ta n |
.It Sx \&Ev Ta Yes Ta Yes Ta >0 |
.It Sx \&Ex Ta \&No Ta \&No Ta n |
.It Sx \&Ex Ta \&No Ta \&No Ta n |
.It Sx \&Fa Ta Yes Ta Yes Ta n |
.It Sx \&Fa Ta Yes Ta Yes Ta >0 |
.It Sx \&Fd Ta \&No Ta \&No Ta >0 |
.It Sx \&Fd Ta \&No Ta \&No Ta >0 |
.It Sx \&Fl Ta Yes Ta Yes Ta n |
.It Sx \&Fl Ta Yes Ta Yes Ta n |
.It Sx \&Fn Ta Yes Ta Yes Ta >0 |
.It Sx \&Fn Ta Yes Ta Yes Ta >0 |
.It Sx \&Fr Ta \&No Ta \&No Ta n |
.It Sx \&Fr Ta \&No Ta \&No Ta n |
.It Sx \&Ft Ta Yes Ta Yes Ta n |
.It Sx \&Ft Ta Yes Ta Yes Ta >0 |
.It Sx \&Fx Ta Yes Ta Yes Ta n |
.It Sx \&Fx Ta Yes Ta Yes Ta n |
.It Sx \&Hf Ta \&No Ta \&No Ta n |
.It Sx \&Hf Ta \&No Ta \&No Ta n |
.It Sx \&Ic Ta Yes Ta Yes Ta >0 |
.It Sx \&Ic Ta Yes Ta Yes Ta >0 |
.It Sx \&In Ta \&No Ta \&No Ta n |
.It Sx \&In Ta \&No Ta \&No Ta n |
.It Sx \&Lb Ta \&No Ta \&No Ta 1 |
.It Sx \&Lb Ta \&No Ta \&No Ta 1 |
.It Sx \&Li Ta Yes Ta Yes Ta n |
.It Sx \&Li Ta Yes Ta Yes Ta >0 |
.It Sx \&Lk Ta Yes Ta Yes Ta n |
.It Sx \&Lk Ta Yes Ta Yes Ta >0 |
.It Sx \&Lp Ta \&No Ta \&No Ta 0 |
.It Sx \&Lp Ta \&No Ta \&No Ta 0 |
.It Sx \&Ms Ta Yes Ta Yes Ta >0 |
.It Sx \&Ms Ta Yes Ta Yes Ta >0 |
.It Sx \&Mt Ta Yes Ta Yes Ta >0 |
.It Sx \&Mt Ta Yes Ta Yes Ta >0 |
|
|
Publication date of an |
Publication date of an |
.Sx \&Rs |
.Sx \&Rs |
block. |
block. |
This should follow the reduced or canonical form syntax described in |
Recommended formats of arguments are |
.Sx Dates . |
.Ar month day , year |
|
or just |
|
.Ar year . |
.Ss \&%I |
.Ss \&%I |
Publisher or issuer name of an |
Publisher or issuer name of an |
.Sx \&Rs |
.Sx \&Rs |
Line 1467 This is the mandatory first macro of any |
|
Line 1446 This is the mandatory first macro of any |
|
manual. |
manual. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&Dd Op Ar date |
.D1 Pf \. Sx \&Dd Ar month day , year |
.Pp |
.Pp |
The |
The |
.Ar date |
.Ar month |
may be either |
is the full English month name, the |
.Ar $\&Mdocdate$ , |
.Ar day |
which signifies the current manual revision date dictated by |
is an optionally zero-padded numeral, and the |
|
.Ar year |
|
is the full four-digit year. |
|
.Pp |
|
Other arguments are not portable; the |
|
.Xr mandoc 1 |
|
utility handles them as follows: |
|
.Bl -dash -offset 3n -compact |
|
.It |
|
To have the date automatically filled in by the |
|
.Ox |
|
version of |
.Xr cvs 1 , |
.Xr cvs 1 , |
or instead a valid canonical date as specified by |
the special string |
.Sx Dates . |
.Dq $\&Mdocdate$ |
If a date does not conform or is empty, the current date is used. |
can be given as an argument. |
|
.It |
|
A few alternative date formats are accepted as well |
|
and converted to the standard form. |
|
.It |
|
If a date string cannot be parsed, it is used verbatim. |
|
.It |
|
If no date string is given, the current date is used. |
|
.El |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Dd $\&Mdocdate$ |
.Dl \&.Dd $\&Mdocdate$ |
Line 1863 are delimited by commas. |
|
Line 1861 are delimited by commas. |
|
If no arguments are specified, blank parenthesis are output. |
If no arguments are specified, blank parenthesis are output. |
.Pp |
.Pp |
Examples: |
Examples: |
.Dl \&.Fn "int funcname" "int arg0" "int arg1" |
.Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q |
.Dl \&.Fn funcname "int arg0" |
.Dl \&.Fn funcname \*qint arg0\*q |
.Dl \&.Fn funcname arg0 |
.Dl \&.Fn funcname arg0 |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
\&.Ft functype |
\&.Ft functype |
Line 1894 Invocations usually occur in the following context: |
|
Line 1892 Invocations usually occur in the following context: |
|
.br |
.br |
.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname |
.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname |
.br |
.br |
\.\.\. |
\&.\.\. |
.br |
.br |
.Pf \. Sx \&Fc |
.Pf \. Sx \&Fc |
.Ed |
.Ed |
Line 2203 Suppress a space. |
|
Line 2201 Suppress a space. |
|
Following invocation, text is interpreted as free-form text until a |
Following invocation, text is interpreted as free-form text until a |
macro is encountered. |
macro is encountered. |
.Pp |
.Pp |
|
This has no effect when invoked at the start of a macro line. |
|
.Pp |
Examples: |
Examples: |
.Dl \&.Fl o \&Ns \&Ar output |
.Dl \&.Fl o \&Ns \&Ar output |
.Pp |
.Pp |
Line 2767 does not start a new line. |
|
Line 2767 does not start a new line. |
|
\*[hist] |
\*[hist] |
.It |
.It |
.Sx \&Dd |
.Sx \&Dd |
without an argument prints |
with non-standard arguments behaves very strangely. |
.Dq Epoch . |
When there are three arguments, they are printed verbatim. |
In mandoc, it resolves to the current date. |
Any other number of arguments is replaced by the current date, |
|
but without any arguments the string |
|
.Dq Epoch |
|
is printed. |
.It |
.It |
.Sx \&Fl |
.Sx \&Fl |
does not print a dash for an empty argument. |
does not print a dash for an empty argument. |
Line 2903 This is not supported by mandoc. |
|
Line 2906 This is not supported by mandoc. |
|
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr man 1 , |
.Xr man 1 , |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
|
.Xr eqn 7 , |
.Xr man 7 , |
.Xr man 7 , |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
.Xr roff 7 , |
.Xr roff 7 , |