Return to mdoc.7 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.129, 2010/07/02 13:07:46 | version 1.137, 2010/07/19 10:48:36 | ||
---|---|---|---|
|
|
||
.\" $Id$ | .\" $Id$ | ||
.\" | .\" | ||
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv> | .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> | ||
.\" 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 | ||
.\" purpose with or without fee is hereby granted, provided that the above | .\" purpose with or without fee is hereby granted, provided that the above | ||
|
|
||
line terminators. | line terminators. | ||
.Ss Comments | .Ss Comments | ||
Text following a | Text following a | ||
.Sq \e" , | .Sq \e\*q , | ||
whether in a macro or free-form text line, is ignored to the end of | whether in a macro or free-form text line, is ignored to the end of | ||
line. A macro line with only a control character and comment escape, | line. A macro line with only a control character and comment escape, | ||
.Sq \&.\e" , | .Sq \&.\e\*q , | ||
is also ignored. Macro lines with only a control character and optionally | is also ignored. Macro lines with only a control character and optionally | ||
whitespace are stripped from input. | whitespace are stripped from input. | ||
.Ss Reserved Characters | .Ss Reserved Characters | ||
|
|
||
is specified outside of any font scope, such as in unenclosed, free-form | is specified outside of any font scope, such as in unenclosed, free-form | ||
text, it will affect the remainder of the document. | text, it will affect the remainder of the document. | ||
.Pp | .Pp | ||
Text may also be sized with the | Note this form is | ||
.Sq \es | |||
escape, whose syntax is one of | |||
.Sq \es+-n | |||
for one-digit numerals; | |||
.Sq \es(+-nn | |||
or | |||
.Sq \es+-(nn | |||
for two-digit numerals; and | |||
.Sq \es[+-N] , | |||
.Sq \es+-[N] , | |||
.Sq \es'+-N' , | |||
or | |||
.Sq \es+-'N' | |||
for arbitrary-digit numerals: | |||
.Pp | |||
.D1 \es+1bigger\es-1 | |||
.D1 \es[+10]much bigger\es[-10] | |||
.D1 \es+(10much bigger\es-(10 | |||
.D1 \es+'100'much much bigger\es-'100' | |||
.Pp | |||
Note these forms are | |||
.Em not | .Em not | ||
recommended for | recommended for | ||
.Nm , | .Nm , | ||
|
|
||
block. Does not have any tail arguments. | block. Does not have any tail arguments. | ||
.Ss \&Bd | .Ss \&Bd | ||
Begins a display block. | Begins a display block. | ||
Its syntax is as follows: | |||
.Bd -ragged -offset indent | |||
.Pf \. Sx \&Bd | |||
.Fl type | |||
.Op Fl offset Ar width | |||
.Op Fl compact | |||
.Ed | |||
.Pp | |||
A display is collection of macros or text which may be collectively | A display is collection of macros or text which may be collectively | ||
offset or justified in a manner different from that | offset or justified in a manner different from that | ||
of the enclosing context. | of the enclosing context. | ||
|
|
||
The type must be provided first. | The type must be provided first. | ||
Secondary arguments are as follows: | Secondary arguments are as follows: | ||
.Bl -tag -width 12n -offset indent | .Bl -tag -width 12n -offset indent | ||
.It Fl offset Ar width | .It Fl offset Ar val | ||
Offset by the value of | Offset by the value of | ||
.Ar width , | .Ar val , | ||
which is interpreted as one of the following, specified in order: | which is interpreted as one of the following, specified in order: | ||
.Bl -item | .Bl -item | ||
.It | .It | ||
|
|
||
twice | twice | ||
.Ar indent ; | .Ar indent ; | ||
.Ar left , | .Ar left , | ||
which has no effect ; | which has no effect; | ||
.Ar right , | .Ar right , | ||
which justifies to the right margin; and | which justifies to the right margin; and | ||
.Ar center , | .Ar center , | ||
|
|
||
If not provided an argument, it will be ignored. | If not provided an argument, it will be ignored. | ||
.It Fl compact | .It Fl compact | ||
Do not assert a vertical space before the block. | Do not assert a vertical space before the block. | ||
.It Fl file Ar file | |||
Prepend the file | |||
.Ar file | |||
before any text or macros within the block. | |||
.El | .El | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
|
|
||
and | and | ||
.Sx \&Sy . | .Sx \&Sy . | ||
.Ss \&Bk | .Ss \&Bk | ||
Begins a keep block, containing a collection of macros or text | Begins a collection of macros or text not breaking the line. | ||
to be kept together in the output. | Its syntax is as follows: | ||
One argument is required; additional arguments are ignored. | |||
Currently, the only argument implemented is | |||
.Fl words , | |||
requesting to keep together all words of the contained text | |||
on the same output line. | |||
A | |||
.Fl lines | |||
argument to keep together all lines of the contained text | |||
on the same page has been desired for a long time, | |||
but has never been implemented. | |||
.Pp | .Pp | ||
Examples: | .D1 Pf \. Sx \&Bk Fl words | ||
.Pp | |||
Subsequent arguments are ignored. | |||
The | |||
.Fl words | |||
argument is required. | |||
.Pp | |||
Each line within a keep block is kept intact, so the following example | |||
will not break within each | |||
.Sx \&Op | |||
macro line: | |||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Bk \-words | \&.Bk \-words | ||
\&.Op o Ar output_file | \&.Op Fl f Ar flags | ||
\&.Op Fl o Ar output | |||
\&.Ek | \&.Ek | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
See also | Be careful in using over-long lines within a keep block! | ||
.Sx \&Ek . | Doing so will clobber the right margin. | ||
.Ss \&Bl | .Ss \&Bl | ||
Begins a list composed of one or more list entries. | Begins a list composed of one or more list entries. | ||
Its syntax is as follows: | |||
.Bd -ragged -offset indent | |||
.Pf \. Sx \&Bl | |||
.Fl type | |||
.Op Fl width Ar val | |||
.Op Fl offset Ar val | |||
.Op Fl compact | |||
.Op HEAD ... | |||
.Ed | |||
.Pp | |||
A list is associated with a type, which is a required argument. | A list is associated with a type, which is a required argument. | ||
Other arguments are | Other arguments are | ||
.Fl width , | .Fl width , | ||
|
|
||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Ec | .Ss \&Ec | ||
Close a scope started by | |||
.Sx \&Eo . | |||
Its syntax is as follows: | |||
.Pp | |||
.D1 Pf \. Sx \&Ec Op Cm TERM | |||
.Pp | |||
The | |||
.Cm TERM | |||
argument is used as the enclosure tail, for example, specifying \e(rq | |||
will emulate | |||
.Sx \&Dc . | |||
.Ss \&Ed | .Ss \&Ed | ||
End a display context started by | |||
.Sx \&Bd . | |||
.Ss \&Ef | .Ss \&Ef | ||
Ends a font mode context started by | Ends a font mode context started by | ||
.Sx \&Bf . | .Sx \&Bf . | ||
|
|
||
.D1 \&.Em Warnings! | .D1 \&.Em Warnings! | ||
.D1 \&.Em Remarks : | .D1 \&.Em Remarks : | ||
.Ss \&En | .Ss \&En | ||
This macro is obsolete and not implemented. | |||
.Ss \&Eo | .Ss \&Eo | ||
An arbitrary enclosure. | |||
Its syntax is as follows: | |||
.Pp | |||
.D1 Pf \. Sx \&Eo Op Cm TERM | |||
.Pp | |||
The | |||
.Cm TERM | |||
argument is used as the enclosure head, for example, specifying \e(lq | |||
will emulate | |||
.Sx \&Do . | |||
.Ss \&Er | .Ss \&Er | ||
Display error constants. | Display error constants. | ||
.Pp | .Pp | ||
|
|
||
See also | See also | ||
.Sx \&Dv . | .Sx \&Dv . | ||
.Ss \&Es | .Ss \&Es | ||
This macro is obsolete and not implemented. | |||
.Ss \&Ev | .Ss \&Ev | ||
Environmental variables such as those specified in | Environmental variables such as those specified in | ||
.Xr environ 7 . | .Xr environ 7 . | ||
|
|
||
See also | See also | ||
.Sx \&Fo . | .Sx \&Fo . | ||
.Ss \&Fc | .Ss \&Fc | ||
Ends a function context started by | |||
.Sx \&Fo . | |||
.Ss \&Fd | .Ss \&Fd | ||
Historically used to document include files. | Historically used to document include files. | ||
This usage has been deprecated in favour of | This usage has been deprecated in favour of | ||
|
|
||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Hf | .Ss \&Hf | ||
This macro is obsolete and not implemented. | |||
.Ss \&Ic | .Ss \&Ic | ||
Designate an internal or interactive command. | |||
This is similar to | |||
.Sx \&Cm | |||
but used for instructions rather than values. | |||
.Pp | |||
Examples: | |||
.D1 \&.Ic hash | |||
.D1 \&.Ic alias | |||
.Pp | |||
Note that using | |||
.Sx \&Bd No Fl literal | |||
or | |||
.Sx \&D1 | |||
is preferred for displaying code; the | |||
.Sx \&Ic | |||
macro is used when referring to specific instructions. | |||
.Ss \&In | .Ss \&In | ||
An | An | ||
.Qq include | .Qq include | ||
|
|
||
.D1 \&.Lb libz | .D1 \&.Lb libz | ||
.D1 \&.Lb mdoc | .D1 \&.Lb mdoc | ||
.Ss \&Li | .Ss \&Li | ||
Denotes text that should be in a literal font mode. | |||
Note that this is a presentation term and should not be used for | |||
stylistically decorating technical terms. | |||
.Ss \&Lk | .Ss \&Lk | ||
Format a hyperlink. | Format a hyperlink. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
|
|
||
See also | See also | ||
.Sx \&Mt . | .Sx \&Mt . | ||
.Ss \&Lp | .Ss \&Lp | ||
Synonym for | |||
.Sx \&Pp . | |||
.Ss \&Ms | .Ss \&Ms | ||
.Ss \&Mt | .Ss \&Mt | ||
Format a | Format a | ||
|
|
||
Examples: | Examples: | ||
.D1 \&.Mt discuss@manpages.bsd.lv | .D1 \&.Mt discuss@manpages.bsd.lv | ||
.Ss \&Nd | .Ss \&Nd | ||
A one-line description of the manual's content. | |||
This may only be invoked in the | |||
.Em SYNOPSIS | |||
section subsequent the | |||
.Sx \&Nm | |||
macro. | |||
.Pp | |||
Examples: | |||
.D1 \&.Sx \&Nd mdoc language reference | |||
.D1 \&.Sx \&Nd format and display UNIX manuals | |||
.Pp | |||
The | |||
.Sx \&Nd | |||
macro technically accepts child macros and terminates with a subsequent | |||
.Sx \&Sh | |||
invocation. | |||
Do not assume this behaviour: some | |||
.Xr whatis 1 | |||
database generators are not smart enough to parse more than the line | |||
arguments and will display macros verbatim. | |||
.Pp | |||
See also | |||
.Sx \&Nm . | |||
.Ss \&Nm | .Ss \&Nm | ||
The name of the manual page, or \(em in particular in section 1, 6, | The name of the manual page, or \(em in particular in section 1, 6, | ||
and 8 pages \(em of an additional command or feature documented in | and 8 pages \(em of an additional command or feature documented in | ||
|
|
||
.Sx \&Nm | .Sx \&Nm | ||
to mark up the name of the manual page. | to mark up the name of the manual page. | ||
.Ss \&No | .Ss \&No | ||
A | |||
.Qq noop | |||
macro used to terminate prior macro contexts. | |||
.Pp | |||
Examples: | |||
.D1 \&.Sx \&Fl ab \&No cd \&Fl ef | |||
.Ss \&Ns | .Ss \&Ns | ||
.Ss \&Nx | .Ss \&Nx | ||
Format the NetBSD version provided as an argument, or a default value if | Format the NetBSD version provided as an argument, or a default value if | ||
|
|
||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Oc | .Ss \&Oc | ||
Closes multi-line | |||
.Sx \&Oo | |||
context. | |||
.Ss \&Oo | .Ss \&Oo | ||
Multi-line version of | |||
.Sx \&Op . | |||
.Pp | |||
Examples: | |||
.Bd -literal -offset indent | |||
\&.Oo | |||
\&.Op Fl flag Ns Ar value | |||
\&.Oc | |||
.Ed | |||
.Ss \&Op | .Ss \&Op | ||
Command-line option. | |||
Used when listing options to command-line utilities. | |||
Prints the argument(s) in brackets. | |||
.Pp | |||
Examples: | |||
.D1 \&.Op \&Fl a \&Ar b | |||
.D1 \&.Op \&Ar a | b | |||
.Pp | |||
See also | |||
.Sx \&Oo . | |||
.Ss \&Os | .Ss \&Os | ||
Document operating system version. | Document operating system version. | ||
This is the mandatory third macro of | This is the mandatory third macro of | ||
|
|
||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Pa | .Ss \&Pa | ||
A file-system path. | |||
.Pp | |||
Examples: | |||
.D1 \&.Pa /usr/bin/mandoc | |||
.D1 \&.Pa /usr/share/man/man7/mdoc.7 | |||
.Pp | |||
See also | |||
.Sx \&Lk . | |||
.Ss \&Pc | .Ss \&Pc | ||
Close parenthesised context opened by | |||
.Sx \&Po . | |||
.Ss \&Pf | .Ss \&Pf | ||
Removes the space | |||
.Pq Qq prefix | |||
between its arguments. | |||
Its syntax is as follows: | |||
.Pp | |||
.D1 Pf \. \&Pf Cm prefix suffix | |||
.Pp | |||
The | |||
.Cm suffix | |||
argument may be a macro. | |||
.Pp | |||
Examples: | |||
.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix | |||
.Ss \&Po | .Ss \&Po | ||
Multi-line version of | |||
.Sx \&Pq . | |||
.Ss \&Pp | .Ss \&Pp | ||
Break a paragraph. | |||
This will assert vertical space between prior and subsequent macros | |||
and/or text. | |||
.Ss \&Pq | .Ss \&Pq | ||
Parenthesised enclosure. | |||
.Pp | |||
See also | |||
.Sx \&Po . | |||
.Ss \&Qc | .Ss \&Qc | ||
.Ss \&Ql | .Ss \&Ql | ||
.Ss \&Qo | .Ss \&Qo | ||
|
|
||
.Ss \&Sc | .Ss \&Sc | ||
.Ss \&Sh | .Ss \&Sh | ||
.Ss \&Sm | .Ss \&Sm | ||
Switches the spacing mode for output generated from macros. | |||
Its syntax is as follows: | |||
.Pp | |||
.D1 Pf \. Sx \&Sm Cm on | off | |||
.Pp | |||
By default, spacing is | |||
.Cm on . | |||
When switched | |||
.Cm off , | |||
no white space is inserted between macro arguments and between the | |||
output generated from adjacent macros, but free-form text lines | |||
still get normal spacing between words and sentences. | |||
.Ss \&So | .Ss \&So | ||
.Ss \&Sq | .Ss \&Sq | ||
.Ss \&Ss | .Ss \&Ss | ||
|
|
||
and | and | ||
.Sx \&Ox . | .Sx \&Ox . | ||
.Ss \&Va | .Ss \&Va | ||
A variable name. | |||
.Pp | |||
Examples: | |||
.D1 \&.Va foo | |||
.D1 \&.Va const char *bar ; | |||
.Ss \&Vt | .Ss \&Vt | ||
A variable type. | A variable type. | ||
This is also used for indicating global variables in the | This is also used for indicating global variables in the | ||
|
|
||
.Pp | .Pp | ||
.Bl -dash -compact | .Bl -dash -compact | ||
.It | .It | ||
The \es (font size), \em (font colour), and \eM (font filling colour) | |||
font decoration escapes are all discarded in mandoc. | |||
.It | |||
Old groff fails to assert a newline before | Old groff fails to assert a newline before | ||
.Sx \&Bd Fl ragged compact . | .Sx \&Bd Fl ragged compact . | ||
.It | .It | ||
|
|
||
mandoc does. | mandoc does. | ||
.It | .It | ||
The comment syntax | The comment syntax | ||
.Sq \e." | .Sq \e\." | ||
is no longer accepted. | is no longer accepted. | ||
.It | .It | ||
In groff, the | In groff, the | ||
|
|
||
and | and | ||
.Fl offset Ar right | .Fl offset Ar right | ||
are disregarded in mandoc. | are disregarded in mandoc. | ||
Furthermore, the | Furthermore, troff specifies a | ||
.Fl file Ar file | .Fl file Ar file | ||
argument is not supported in mandoc. | argument that is not supported in mandoc. | ||
Lastly, since text is not right-justified in mandoc (or even groff), | Lastly, since text is not right-justified in mandoc (or even groff), | ||
.Fl ragged | .Fl ragged | ||
and | and |