version 1.127, 2010/06/27 13:30:51 |
version 1.131, 2010/07/05 13:12:32 |
|
|
.\" $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 478 they are separated by a vertical space, unless in the |
|
Line 479 they are separated by a vertical space, unless in the |
|
and |
and |
.Sx \&Ft , |
.Sx \&Ft , |
which are always separated by vertical space. |
which are always separated by vertical space. |
|
.Pp |
|
When text and macros following an |
|
.Sx \&Nm |
|
macro starting an input line span multiple output lines, |
|
all output lines but the first will be indented to align |
|
with the text immediately following the |
|
.Sx \&Nm |
|
macro, up to the next |
|
.Sx \&Nm , |
|
.Sx \&Sx , |
|
or |
|
.Sx \&Ss |
|
macro or the end of an enclosing block, whichever comes first. |
.It Em DESCRIPTION |
.It Em DESCRIPTION |
This expands upon the brief, one-line description in |
This expands upon the brief, one-line description in |
.Em NAME . |
.Em NAME . |
Line 672 has multiple heads. |
|
Line 686 has multiple heads. |
|
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope |
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope |
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El |
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El |
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh |
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh |
|
.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss |
.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh |
.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh |
.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss |
.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss |
.El |
.El |
|
.Pp |
|
Note that the |
|
.Sx \&Nm |
|
macro is a |
|
.Sx Block full-implicit |
|
macro only when invoked as the first macro |
|
in a |
|
.Em SYNOPSIS |
|
section line, else it is |
|
.Sx In-line . |
.Ss Block partial-explicit |
.Ss Block partial-explicit |
Like block full-explicit, but also with single-line scope. |
Like block full-explicit, but also with single-line scope. |
Each has at least a body and, in limited circumstances, a head |
Each has at least a body and, in limited circumstances, a head |
|
|
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. |
Line 1063 Centre-justify each line. |
|
Line 1096 Centre-justify each line. |
|
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 |
Line 1076 the width of standard indentation; |
|
Line 1109 the width of standard indentation; |
|
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 , |
Line 1097 As the calculated string length of the opaque string. |
|
Line 1130 As the calculated string length of the opaque string. |
|
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 \&Dl . |
.Sx \&Dl . |
.Ss \&Bf |
.Ss \&Bf |
|
Change the font mode for a scoped block of text. |
|
Its syntax is as follows: |
|
.Bd -ragged -offset indent |
|
.Pf \. Sx \&Bf |
|
.Oo |
|
.Fl emphasis | literal | symbolic | |
|
.Cm \&Em | \&Li | \&Sy |
|
.Oc |
|
.Ed |
|
.Pp |
|
The |
|
.Fl emphasis |
|
and |
|
.Cm \&Em |
|
argument are equivalent, as are |
|
.Fl symbolic |
|
and |
|
.Cm \&Sy, |
|
and |
|
.Fl literal |
|
and |
|
.Cm \&Li . |
|
Without an argument, this macro does nothing. |
|
The font mode continues until broken by a new font mode in a nested |
|
scope or |
|
.Sx \&Ef |
|
is encountered. |
|
.Pp |
|
See also |
|
.Sx \&Li , |
|
.Sx \&Ef , |
|
and |
|
.Sx \&Sy . |
.Ss \&Bk |
.Ss \&Bk |
Begins a keep block, containing a collection of macros or text |
Begins a keep block, containing a collection of macros or text |
to be kept together in the output. |
to be kept together in the output. |
One argument is required; additional arguments are ignored. |
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Sx \&Bk Fl words |
|
.Pp |
Currently, the only argument implemented is |
Currently, the only argument implemented is |
.Fl words , |
.Fl words , |
requesting to keep together all words of the contained text |
requesting to keep together all words of the contained text |
on the same output line. |
on the same output line. |
A |
Subsequent arguments are ignored. |
.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: |
Examples: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
|
|
\&.Op o Ar output_file |
\&.Op o Ar output_file |
\&.Ek |
\&.Ek |
.Ed |
.Ed |
|
.Pp |
|
See also |
|
.Sx \&Ek . |
.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 |
|
.Sx \&Bf . |
.Ss \&Ek |
.Ss \&Ek |
Ends a keep context started by |
Ends a keep context started by |
.Sx \&Bk . |
.Sx \&Bk . |
|
|
.D1 \&.Em Remarks : |
.D1 \&.Em Remarks : |
.Ss \&En |
.Ss \&En |
.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 \&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 |
|
|
.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: |
|
|
.D1 \&.Mt discuss@manpages.bsd.lv |
.D1 \&.Mt discuss@manpages.bsd.lv |
.Ss \&Nd |
.Ss \&Nd |
.Ss \&Nm |
.Ss \&Nm |
|
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 |
|
the manual page. |
|
When first invoked, the |
|
.Sx \&Nm |
|
macro expects a single argument, the name of the manual page. |
|
Usually, the first invocation happens in the |
|
.Em NAME |
|
section of the page. |
|
The specified name will be remembered and used whenever the macro is |
|
called again without arguments later in the page. |
|
The |
|
.Sx \&Nm |
|
macro uses |
|
.Sx Block full-implicit |
|
semantics when invoked as the first macro on an input line in the |
|
.Em SYNOPSIS |
|
section; otherwise, it uses ordinary |
|
.Sx In-line |
|
semantics. |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent |
|
\&.Sh SYNOPSIS |
|
\&.Nm cat |
|
\&.Op Fl benstuv |
|
\&.Op Ar |
|
.Ed |
|
.Pp |
|
In the |
|
.Em SYNOPSIS |
|
of section 2, 3 and 9 manual pages, use the |
|
.Sx \&Fn |
|
macro rather than |
|
.Sx \&Nm |
|
to mark up the name of the manual page. |
.Ss \&No |
.Ss \&No |
.Ss \&Ns |
.Ss \&Ns |
.Ss \&Nx |
.Ss \&Nx |
Line 2270 Display offsets |
|
Line 2410 Display offsets |
|
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 |