-.\" $Id: man.7,v 1.43 2009/11/02 06:22:45 kristaps Exp $
+.\" $Id: man.7,v 1.61 2010/04/05 07:25:23 kristaps Exp $
.\"
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
.\"
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: November 2 2009 $
+.Dd $Mdocdate: April 5 2010 $
.Dt MAN 7
.Os
.
Blank lines are acceptable; where found, the output will assert a
vertical space.
.
-.Pp
-The
-.Sq \ec
-escape is common in historical
-.Nm
-documents; if encountered at the end of a word, it ensures that the
-subsequent word isn't off-set by whitespace.
-.
.
.Ss Comments
Text following a
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,
.Sq \&.\e" ,
-is also ignored. Macro lines with only a control charater and
+is also ignored. Macro lines with only a control character and
optionally whitespace are stripped from input.
.
.
.Ss Text Decoration
Terms may be text-decorated using the
.Sq \ef
-escape followed by an indicator: B (bold), I, (italic), or P and R
-(Roman, or reset).
+escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
+(revert to previous mode):
+.Pp
+.D1 \efBbold\efR \efIitalic\efP
+.Pp
+A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+respectively) may be used instead. A text decoration is only valid, if
+specified in free-form text, until the next macro invocation; if
+specified within a macro, it's only valid until the macro closes scope.
+Note that macros like
+.Sx \&BR
+open and close a font scope with each argument.
+.Pp
+Text may also be sized with the
+.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
+Both
+.Sq \es
+and
+.Sq \ef
+attributes are forgotten when entering or exiting a macro block.
.
.
.Ss Whitespace
utility such as
.Xr mandoc 1 .
.
+.
.Ss Dates
The
.Sx \&TH
standard
.Cm YYYY-MM-DD .
.
-.Ss Scaling Widths
-Many macros support scaled widths for their arguments, such as
-stipulating a two-inch list indentation with the following:
-.Bd -literal -offset indent
-\&.Bl -tag -width 2i
-.Ed
-.
.
.Ss Scaling Widths
Many macros support scaled widths for their arguments, such as
.Sq u ,
or
.Sq v
-is necessarily non-portable across output media. See
-.Sx COMPATIBILITY .
+is necessarily non-portable across output media.
.
.Pp
If a scaling unit is not provided, the numerical value is interpreted
.D1 Standard C Library (libc, -lc)
.It Em SYNOPSIS
Documents the utility invocation syntax, function call syntax, or device
-configuration.
+configuration.
.Pp
For the first, utilities (sections 1, 6, and 8), this is
generally structured as follows:
.Pp
For the second, function calls (sections 2, 3, 9):
.Pp
-.D1 \. Ns Sx \&B No char *name(char *\efIarg\efR);
+.D1 \&.B char *name(char *\efIarg\efR);
.Pp
And for the third, configurations (section 4):
.Pp
-.D1 \. Ns Sx \&B No name* at cardbus ? function ?
+.D1 \&.B name* at cardbus ? function ?
.Pp
-Manuals not in these sections generally don't need a
+Manuals not in these sections generally don't need a
.Em SYNOPSIS .
.It Em DESCRIPTION
-This expands upon the brief, one-line description in
+This expands upon the brief, one-line description in
.Em NAME .
It usually contains a break-down of the options (if documenting a
command).
.It Em EXAMPLES
Example usages. This often contains snippets of well-formed,
well-tested invocations. Make doubly sure that your examples work
-properly! Assume that users will skip to this section and use your
-example verbatim.
+properly!
.
.It Em DIAGNOSTICS
Documents error conditions. This is most useful in section 4 manuals.
.
.It Em SEE ALSO
References other manuals with related topics. This section should exist
-for most manuals. Cross-references should conventionally be ordered
-first by section, then alphabetically.
+for most manuals.
+.Pp
+.D1 \&.BR bar \&( 1 \&),
.Pp
-.D1 \. Ns Sx \&BR No bar \&( 1 \&),
-.D1 \. Ns Sx \&BR No foo \&( 1 \&),
-.D1 \. Ns Sx \&BR No baz \&( 2 \&).
+Cross-references should conventionally be ordered
+first by section, then alphabetically.
.
.It Em STANDARDS
References any standards implemented or used, such as
Macros are one to three three characters in length and begin with a
control character ,
.Sq \&. ,
-at the beginning of the line. An arbitrary amount of whitespace may
-sit between the control character and the macro name. Thus, the
-following are equivalent:
+at the beginning of the line. The
+.Sq \(aq
+macro control character is also accepted. An arbitrary amount of
+whitespace (spaces or tabs) may sit between the control character and
+the macro name. Thus, the following are equivalent:
.Bd -literal -offset indent
\&.PP
\&.\ \ \ PP
.Ss Line Macros
Line macros are generally scoped to the current line, with the body
consisting of zero or more arguments. If a macro is scoped to the next
-line and the line arguments are empty, the next line is used instead,
-else the general syntax is used. Thus:
+line and the line arguments are empty, the next line, which must be
+text, is used instead. Thus:
.Bd -literal -offset indent
\&.I
foo
is equivalent to
.Sq \&.I foo .
If next-line macros are invoked consecutively, only the last is used.
-If a next-line macro is proceded by a block macro, it is ignored.
+If a next-line macro is followed by a non-next-line macro, an error is
+raised (unless in the case of
+.Sx \&br ,
+.Sx \&sp ,
+or
+.Sx \&na ) .
+.Pp
+The syntax is as follows:
.Bd -literal -offset indent
\&.YO \(lBbody...\(rB
\(lBbody...\(rB
.Ed
.
.Pp
-.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
-.It Em Macro Ta Em Arguments Ta Em Scope
-.It Sx \&B Ta n Ta next-line
-.It Sx \&BI Ta n Ta current
-.It Sx \&BR Ta n Ta current
-.It Sx \&DT Ta 0 Ta current
-.It Sx \&I Ta n Ta next-line
-.It Sx \&IB Ta n Ta current
-.It Sx \&IR Ta n Ta current
-.It Sx \&PD Ta n Ta current
-.It Sx \&R Ta n Ta next-line
-.It Sx \&RB Ta n Ta current
-.It Sx \&RI Ta n Ta current
-.It Sx \&SB Ta n Ta next-line
-.It Sx \&SM Ta n Ta next-line
-.It Sx \&TH Ta >1, <6 Ta current
-.It Sx \&UC Ta n Ta current
-.It Sx \&br Ta 0 Ta current
-.It Sx \&fi Ta 0 Ta current
-.It Sx \&i Ta n Ta current
-.It Sx \&na Ta 0 Ta current
-.It Sx \&nf Ta 0 Ta current
-.It Sx \&r Ta 0 Ta current
-.It Sx \&sp Ta 1 Ta current
+.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"
+.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
+.It Sx \&B Ta n Ta next-line Ta \&
+.It Sx \&BI Ta n Ta current Ta \&
+.It Sx \&BR Ta n Ta current Ta \&
+.It Sx \&DT Ta 0 Ta current Ta \&
+.It Sx \&I Ta n Ta next-line Ta \&
+.It Sx \&IB Ta n Ta current Ta \&
+.It Sx \&IR Ta n Ta current Ta \&
+.\" .It Sx \&PD Ta n Ta current Ta compat
+.It Sx \&R Ta n Ta next-line Ta \&
+.It Sx \&RB Ta n Ta current Ta \&
+.It Sx \&RI Ta n Ta current Ta \&
+.It Sx \&SB Ta n Ta next-line Ta \&
+.It Sx \&SM Ta n Ta next-line Ta \&
+.It Sx \&TH Ta >1, <6 Ta current Ta \&
+.\" .It Sx \&UC Ta n Ta current Ta compat
+.It Sx \&br Ta 0 Ta current Ta compat
+.It Sx \&fi Ta 0 Ta current Ta compat
+.It Sx \&i Ta n Ta current Ta compat
+.It Sx \&na Ta 0 Ta current Ta compat
+.It Sx \&nf Ta 0 Ta current Ta compat
+.It Sx \&r Ta 0 Ta current Ta compat
+.It Sx \&sp Ta 1 Ta current Ta compat
+.\" .It Sx \&Sp Ta 0 Ta current Ta compat
+.\" .It Sx \&Vb Ta <1 Ta current Ta compat
+.\" .It Sx \&Ve Ta 0 Ta current Ta compat
.El
.
.Pp
-The
-.Sx \&PD ,
-.Sx \&RS ,
-.Sx \&RE ,
-.Sx \&UC ,
-.Sx \&br ,
-.Sx \&fi ,
-.Sx \&i ,
-.Sx \&na ,
-.Sx \&nf ,
-.Sx \&r ,
-and
-.Sx \&sp
-macros should not be used. They're included for compatibility.
+Macros marked as
+.Qq compat
+are included for compatibility with the significant corpus of existing
+manuals that mix dialects of roff. These macros should not be used for
+portable
+.Nm
+manuals.
.
.
.Ss Block Macros
Block macros are comprised of a head and body. Like for in-line macros,
the head is scoped to the current line and, in one circumstance, the
-next line; the body is scoped to subsequent lines and is closed out by a
-subsequent block macro invocation.
+next line (the next-line stipulations as in
+.Sx Line Macros
+apply here as well).
+.Pp
+The syntax is as follows:
.Bd -literal -offset indent
\&.YO \(lBhead...\(rB
\(lBhead...\(rB
.Sx \&SS ;
part, closed by a section, sub-section, or
.Sx \&RE ;
-or paragraph, closed by a section, sub-section, part,
+or paragraph, closed by a section, sub-section, part,
.Sx \&HP ,
.Sx \&IP ,
.Sx \&LP ,
No closure refers to an explicit block closing macro.
.
.Pp
-.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" -compact -offset indent
-.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope
-.It Sx \&HP Ta <2 Ta current Ta paragraph
-.It Sx \&IP Ta <3 Ta current Ta paragraph
-.It Sx \&LP Ta 0 Ta current Ta paragraph
-.It Sx \&P Ta 0 Ta current Ta paragraph
-.It Sx \&PP Ta 0 Ta current Ta paragraph
-.It Sx \&RE Ta 0 Ta current Ta none
-.It Sx \&RS Ta 1 Ta current Ta part
-.It Sx \&SH Ta >0 Ta next-line Ta section
-.It Sx \&SS Ta >0 Ta next-line Ta sub-section
-.It Sx \&TP Ta n Ta next-line Ta paragraph
+As a rule, block macros may not be nested; thus, calling a block macro
+while another block macro scope is open, and the open scope is not
+implicitly closed, is syntactically incorrect.
+.
+.Pp
+.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX"
+.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
+.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
+.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
+.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
+.It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
+.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
+.It Sx \&RE Ta 0 Ta current Ta none Ta compat
+.It Sx \&RS Ta 1 Ta current Ta part Ta compat
+.It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
+.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
+.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
.El
+.Pp
+.
+Macros marked
+.Qq compat
+are as mentioned in
+.Sx Line Macros .
.
.Pp
If a block macro is next-line scoped, it may only be followed by in-line
-macros (excluding
-.Sx \&DT ,
-.Sx \&PD ,
-.Sx \&TH ,
-.Sx \&UC ,
-.Sx \&br ,
-.Sx \&na ,
-.Sx \&sp ,
-.Sx \&nf ,
-and
-.Sx \&fi ) .
+macros for decorating text.
.
.
.Sh REFERENCE
alphabetically. For the scoping of individual macros, see
.Sx MACRO SYNTAX .
.
+.
.Ss \&B
Text is rendered in bold face.
+.Pp
+See also
+.Sx \&I ,
+.Sx \&R ,
+.Sx \&b ,
+.Sx \&i ,
+and
+.Sx \&r .
+.
+.
.Ss \&BI
-Text is rendered alternately in bold face and italic. Thus,
+Text is rendered alternately in bold face and italic. Thus,
.Sq .BI this word and that
causes
.Sq this
and
.Sq and
-to render in bold face, while
+to render in bold face, while
.Sq word
and
.Sq that
render in italics. Whitespace between arguments is omitted in output.
+.Pp
+Examples:
+.Pp
+.D1 \&.BI bold italic bold italic
+.Pp
+The output of this example will be emboldened
+.Dq bold
+and italicised
+.Dq italic ,
+with spaces stripped between arguments.
+.Pp
+See also
+.Sx \&IB ,
+.Sx \&BR ,
+.Sx \&RB ,
+.Sx \&RI ,
+and
+.Sx \&IR .
+.
+.
.Ss \&BR
Text is rendered alternately in bold face and roman (the default font).
Whitespace between arguments is omitted in output.
+.Pp
+See
+.Sx \&BI
+for an equivalent example.
+.Pp
+See also
+.Sx \&BI ,
+.Sx \&IB ,
+.Sx \&RB ,
+.Sx \&RI ,
+and
+.Sx \&IR .
+.
+.
.Ss \&DT
Has no effect. Included for compatibility.
+.
+.
.Ss \&HP
Begin a paragraph whose initial output line is left-justified, but
subsequent output lines are indented, with the following syntax:
-.Bd -literal -offset indent
-\&.HP [width]
+.Bd -filled -offset indent
+.Pf \. Sx \&HP
+.Op Cm width
.Ed
-.
.Pp
-If scaling width
-.Va width
-is specified, it's saved for later paragraph left-margins; if
-unspecified, the saved or default width is used.
+The
+.Cm width
+argument must conform to
+.Sx Scaling Widths .
+If specified, it's saved for later paragraph left-margins; if unspecified, the
+saved or default width is used.
+.Pp
+See also
+.Sx \&IP ,
+.Sx \&LP ,
+.Sx \&P ,
+.Sx \&PP ,
+and
+.Sx \&TP .
+.
+.
.Ss \&I
Text is rendered in italics.
+.Pp
+See also
+.Sx \&B ,
+.Sx \&R ,
+.Sx \&b ,
+.Sx \&i ,
+and
+.Sx \&r .
+.
+.
.Ss \&IB
Text is rendered alternately in italics and bold face. Whitespace
between arguments is omitted in output.
+.Pp
+See
+.Sx \&BI
+for an equivalent example.
+.Pp
+See also
+.Sx \&BI ,
+.Sx \&BR ,
+.Sx \&RB ,
+.Sx \&RI ,
+and
+.Sx \&IR .
+.
+.
.Ss \&IP
-Begin a paragraph with the following syntax:
-.Bd -literal -offset indent
-\&.IP [head [width]]
+Begin an indented paragraph with the following syntax:
+.Bd -filled -offset indent
+.Pf \. Sx \&IP
+.Op Cm head Op Cm width
.Ed
-.
.Pp
-This follows the behaviour of the
-.Sx \&TP
-except for the macro syntax (all arguments on the line, instead of
-having next-line scope). If
-.Va width
-is specified, it's saved for later paragraph left-margins; if
-unspecified, the saved or default width is used.
+The
+.Cm width
+argument defines the width of the left margin and is defined by
+.Sx Scaling Widths ,
+It's saved for later paragraph left-margins; if unspecified, the saved or
+default width is used.
+.Pp
+The
+.Cm head
+argument is used as a leading term, flushed to the left margin. This is
+useful for bulleted paragraphs and so on.
+.Pp
+See also
+.Sx \&HP ,
+.Sx \&LP ,
+.Sx \&P ,
+.Sx \&PP ,
+and
+.Sx \&TP .
+.
+.
.Ss \&IR
Text is rendered alternately in italics and roman (the default font).
Whitespace between arguments is omitted in output.
+.Pp
+See
+.Sx \&BI
+for an equivalent example.
+.Pp
+See also
+.Sx \&BI ,
+.Sx \&IB ,
+.Sx \&BR ,
+.Sx \&RB ,
+and
+.Sx \&RI .
+.
+.
.Ss \&LP
Begin an undecorated paragraph. The scope of a paragraph is closed by a
subsequent paragraph, sub-section, section, or end of file. The saved
paragraph left-margin width is re-set to the default.
+.Pp
+See also
+.Sx \&HP ,
+.Sx \&IP ,
+.Sx \&P ,
+.Sx \&PP ,
+and
+.Sx \&TP .
+.
+.
.Ss \&P
Synonym for
.Sx \&LP .
+.Pp
+See also
+.Sx \&HP ,
+.Sx \&IP ,
+.Sx \&LP ,
+.Sx \&PP ,
+and
+.Sx \&TP .
+.
+.
.Ss \&PP
Synonym for
.Sx \&LP .
+.Pp
+See also
+.Sx \&HP ,
+.Sx \&IP ,
+.Sx \&LP ,
+.Sx \&P ,
+and
+.Sx \&TP .
+.
+.
.Ss \&R
Text is rendered in roman (the default font).
+.Pp
+See also
+.Sx \&I ,
+.Sx \&B ,
+.Sx \&b ,
+.Sx \&i ,
+and
+.Sx \&r .
+.
+.
.Ss \&RB
Text is rendered alternately in roman (the default font) and bold face.
Whitespace between arguments is omitted in output.
+.Pp
+See
+.Sx \&BI
+for an equivalent example.
+.Pp
+See also
+.Sx \&BI ,
+.Sx \&IB ,
+.Sx \&BR ,
+.Sx \&RI ,
+and
+.Sx \&IR .
+.
+.
.Ss \&RE
Explicitly close out the scope of a prior
.Sx \&RS .
+.
+.
.Ss \&RI
Text is rendered alternately in roman (the default font) and italics.
Whitespace between arguments is omitted in output.
+.Pp
+See
+.Sx \&BI
+for an equivalent example.
+.Pp
+See also
+.Sx \&BI ,
+.Sx \&IB ,
+.Sx \&BR ,
+.Sx \&RB ,
+and
+.Sx \&IR .
+.
+.
.Ss \&RS
Begin a part setting the left margin. The left margin controls the
offset, following an initial indentation, to un-indented text such as
that of
.Sx \&PP .
-A scaling width may be specified as following:
-.Bd -literal -offset indent
-\&.RS [width]
+This has the following syntax:
+.Bd -filled -offset indent
+.Pf \. Sx \&Rs
+.Op Cm width
.Ed
-.
.Pp
-If
-.Va width
-is not specified, the saved or default width is used.
+The
+.Cm width
+argument must conform to
+.Sx Scaling Widths .
+If not specified, the saved or default width is used.
+.
+.
.Ss \&SB
Text is rendered in small size (one point smaller than the default font)
bold face.
+.
+.
.Ss \&SH
Begin a section. The scope of a section is only closed by another
section or the end of file. The paragraph left-margin width is re-set
to the default.
+.
+.
.Ss \&SM
Text is rendered in small size (one point smaller than the default
font).
+.
+.
.Ss \&SS
Begin a sub-section. The scope of a sub-section is closed by a
subsequent sub-section, section, or end of file. The paragraph
left-margin width is re-set to the default.
+.
+.
.Ss \&TH
Sets the title of the manual page with the following syntax:
-.Pp
-.D1 \. Ns Sx \&TH No Cm title msec Op Cm date Op Cm src Op Cm vol
+.Bd -filled -offset indent
+.Pf \. Sx \&TH
+.Cm title section
+.Op Cm date Op Cm source Op Cm volume
+.Ed
.Pp
At least the upper-case document title
.Cm title
and numeric manual section
-.Cm msec
+.Cm section
arguments must be provided. The
.Cm date
argument should be formatted as described in
.Sx Dates :
if it does not conform, the current date is used instead. The
-.Cm src
+.Cm source
string specifies the organisation providing the utility. The
-.Cm vol
+.Cm volume
string replaces the default rendered volume, which is dictated by the
manual section.
.Pp
Examples:
-.Bd -literal -offset indent
-\&.TH CVS 5 "1992-02-12" GNU
-.Ed
+.Pp
+.D1 \&.TH CVS 5 "1992-02-12" GNU
+.
.
.Ss \&TP
Begin a paragraph where the head, if exceeding the indentation width, is
followed by a newline; if not, the body follows on the same line after a
buffer to the indentation width. Subsequent output lines are indented.
-.
-.Pp
-The indentation scaling width may be set as follows:
-.Bd -literal -offset indent
-\&.TP [width]
+The syntax is as follows:
+.Bd -filled -offset indent
+.Pf \. Sx \&TP
+.Op Cm width
.Ed
-.
.Pp
-If
-.Va width
-is specified, it's saved for later paragraph left-margins; if
+The
+.Cm width
+argument must conform to
+.Sx Scaling Widths .
+If specified, it's saved for later paragraph left-margins; if
unspecified, the saved or default width is used.
-.Ss \&PD
-Has no effect. Included for compatibility.
-.Ss \&UC
-Has no effect. Included for compatibility.
+.Pp
+See also
+.Sx \&HP ,
+.Sx \&IP ,
+.Sx \&LP ,
+.Sx \&P ,
+and
+.Sx \&PP .
+.\" .
+.\" .
+.\" .Ss \&PD
+.\" Has no effect. Included for compatibility.
+.\" .
+.\" .
+.\" .Ss \&UC
+.\" Has no effect. Included for compatibility.
+.
+.
.Ss \&br
Breaks the current line. Consecutive invocations have no further effect.
+.Pp
+See also
+.Sx \&sp .
+.
+.
.Ss \&fi
End literal mode begun by
.Sx \&nf .
+.
+.
.Ss \&i
-Italicise arguments. If no arguments are specified, all subsequent text
-is italicised.
+Italicise arguments. Synonym for
+.Sx \&I .
+.Pp
+See also
+.Sx \&B ,
+.Sx \&I ,
+.Sx \&R .
+.Sx \&b ,
+and
+.Sx \&r .
+.
+.
.Ss \&na
Don't align to the right margin.
+.
+.
.Ss \&nf
Begin literal mode: all subsequent free-form lines have their end of
line boundaries preserved. May be ended by
.Sx \&fi .
+.
+.
.Ss \&r
Fonts and styles (bold face, italics) reset to roman (default font).
+.Pp
+See also
+.Sx \&B ,
+.Sx \&I ,
+.Sx \&R ,
+.Sx \&b ,
+and
+.Sx \&i .
+.
+.
.Ss \&sp
-Insert n spaces, where n is the macro's positive numeric argument. If
-0, this is equivalent to the
+Insert vertical spaces into output with the following syntax:
+.Bd -filled -offset indent
+.Pf \. Sx \&sp
+.Op Cm height
+.Ed
+.Pp
+Insert
+.Cm height
+spaces, which must conform to
+.Sx Scaling Widths .
+If 0, this is equivalent to the
.Sx \&br
-macro.
-.
+macro. Defaults to 1, if unspecified.
+.Pp
+See also
+.Sx \&br .
+.
+.\" .Ss \&Sp
+.\" A synonym for
+.\" .Sx \&sp
+.\" .Cm 0.5v .
+.\" .
+.\" .Ss \&Vb
+.\" A synonym for
+.\" .Sx \&nf .
+.\" Accepts an argument (the height of the formatted space) which is
+.\" disregarded.
+.\" .
+.\" .Ss \&Ve
+.\" A synonym for
+.\" .Sx \&fi .
+.\" .
.
.Sh COMPATIBILITY
-This section documents compatibility with other roff implementations, at
-this time limited to
-.Xr groff 1 .
-.Bl -hyphen
+This section documents areas of questionable portability between
+implementations of the
+.Nm
+language.
+.
+.Pp
+.Bl -dash -compact
.It
-In quoted literals, groff allowed pair-wise double-quotes to produce a
-standalone double-quote in formatted output. This idiosyncratic
-behaviour is no longer applicable.
+In quoted literals, GNU troff allowed pair-wise double-quotes to produce
+a standalone double-quote in formatted output. It is not known whether
+this behaviour is exhibited by other formatters.
+.
+.It
+Blocks of whitespace are stripped from macro and free-form text lines
+(except when in literal mode) in mandoc. This is not the case for GNU
+troff: for maximum portability, whitespace sensitive blocks should be
+enclosed in literal contexts.
+.
.It
The
-.Sq sp
-macro does not accept negative numbers.
+.Sx \&sp
+macro does not accept negative values in mandoc. In GNU troff, this
+would result in strange behaviour.
+.
.It
-Blocks of whitespace are stripped from both macro and free-form text
-lines (except when in literal mode), while groff would retain whitespace
-in free-form text lines.
+The
+.Sq \(aq
+macro control character, in GNU troff (and prior troffs) suppresses a
+newline before macro output; in mandoc, it is an alias for the standard
+.Sq \&.
+control character.
.El
.
.
git.ckatri.com / mandoc.git / blobdiff