-.\" $Id: man.7,v 1.50 2009/11/12 05:50:12 kristaps Exp $
+.\" $Id: man.7,v 1.58 2010/03/25 07:28:16 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 12 2009 $
+.Dd $Mdocdate: March 25 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
Terms may be text-decorated using the
.Sq \ef
escape followed by an indicator: B (bold), I, (italic), R (Roman), or P
-(revert to previous mode):
+(revert to previous mode):
.Pp
.D1 \efBbold\efR \efIitalic\efP
.Pp
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
.Sq \es
and
.Sq \ef
-attributes are forgotten when exiting a subsequent (or current) macro
-invocation.
+attributes are forgotten when entering or exiting a macro block.
.
.
.Ss Whitespace
.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
.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 SEE ALSO
References other manuals with related topics. This section should exist
-for most manuals.
+for most manuals.
.Pp
.D1 \&.BR bar \&( 1 \&),
.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
.Pp
is equivalent to
.Sq \&.I foo .
-If next-line macros are invoked consecutively, only the last is used; in
-other words, if a next-line macro is preceded by a block macro, it is
-ignored.
+If next-line macros are invoked consecutively, only the last is used.
+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 ,
+.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
.
.
.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
.Cm width
argument must conform to
.Sx Scaling Widths .
-If not specified, the saved or default width is used.
+If not specified, the saved or default width is used.
.
.
.Ss \&SB
.Sx \&P ,
and
.Sx \&PP .
-.
-.
-.Ss \&PD
-Has no effect. Included for compatibility.
-.
-.
-.Ss \&UC
-Has no effect. Included for compatibility.
+.\" .
+.\" .
+.\" .Ss \&PD
+.\" Has no effect. Included for compatibility.
+.\" .
+.\" .
+.\" .Ss \&UC
+.\" Has no effect. Included for compatibility.
.
.
.Ss \&br
.
.
.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 ,
.Op Cm height
.Ed
.Pp
-Insert
+Insert
.Cm height
spaces, which must conform to
.Sx Scaling Widths .
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
-The
-.Sq sp
-macro does not accept negative numbers.
+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
-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
+.Sx \&sp
+macro does not accept negative values in mandoc. In GNU troff, this
+would result in strange behaviour.
.El
.
.
git.ckatri.com / mandoc.git / blobdiff