+.Em Scope
+column, if applicable, describes closure rules.
+.Ss Block full-explicit
+Multi-line scope closed by an explicit closing macro.
+All macros contains bodies; only
+.Ic \s&Bf
+and
+.Pq optionally
+.Ic \&Bl
+contain a head.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
+\(lBbody...\(rB
+\&.Yc
+.Ed
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
+.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed
+.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef
+.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek
+.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El
+.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd
+.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf
+.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk
+.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl
+.El
+.Ss Block full-implicit
+Multi-line scope closed by end-of-file or implicitly by another macro.
+All macros have bodies; some
+.Po
+.Ic \&It Fl bullet ,
+.Fl hyphen ,
+.Fl dash ,
+.Fl enum ,
+.Fl item
+.Pc
+don't have heads; only one
+.Po
+.Ic \&It
+in
+.Ic \&Bl Fl column
+.Pc
+has multiple heads.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
+\(lBbody...\(rB
+.Ed
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
+.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El
+.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh
+.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss
+.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh
+.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss
+.El
+.Pp
+Note that the
+.Ic \&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
+Like block full-explicit, but also with single-line scope.
+Each has at least a body and, in limited circumstances, a head
+.Po
+.Ic \&Fo ,
+.Ic \&Eo
+.Pc
+and/or tail
+.Pq Ic \&Ec .
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
+\(lBbody...\(rB
+\&.Yc \(lBtail...\(rB
+
+\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
+\(lBbody...\(rB \&Yc \(lBtail...\(rB
+.Ed
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
+.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao
+.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac
+.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo
+.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc
+.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro
+.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc
+.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do
+.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc
+.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo
+.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec
+.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo
+.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc
+.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo
+.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc
+.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po
+.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc
+.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo
+.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc
+.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs
+.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re
+.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So
+.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc
+.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo
+.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc
+.El
+.Ss Block partial-implicit
+Like block full-implicit, but with single-line scope closed by the
+end of the line.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
+.Ed
+.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed
+.It Ic \&Aq Ta Yes Ta Yes
+.It Ic \&Bq Ta Yes Ta Yes
+.It Ic \&Brq Ta Yes Ta Yes
+.It Ic \&D1 Ta \&No Ta \&Yes
+.It Ic \&Dl Ta \&No Ta Yes
+.It Ic \&Dq Ta Yes Ta Yes
+.It Ic \&En Ta Yes Ta Yes
+.It Ic \&Op Ta Yes Ta Yes
+.It Ic \&Pq Ta Yes Ta Yes
+.It Ic \&Ql Ta Yes Ta Yes
+.It Ic \&Qq Ta Yes Ta Yes
+.It Ic \&Sq Ta Yes Ta Yes
+.It Ic \&Vt Ta Yes Ta Yes
+.El
+.Pp
+Note that the
+.Ic \&Vt
+macro is a
+.Sx Block partial-implicit
+only when invoked as the first macro
+in a
+.Em SYNOPSIS
+section line, else it is
+.Sx In-line .
+.Ss Special block macro
+The
+.Ic \&Ta
+macro can only be used below
+.Ic \&It
+in
+.Ic \&Bl Fl column
+lists.
+It delimits blocks representing table cells;
+these blocks have bodies, but no heads.
+.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
+.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It
+.El
+.Ss In-line
+Closed by the end of the line, fixed argument lengths,
+and/or subsequent macros.
+In-line macros have only text children.
+If a number (or inequality) of arguments is
+.Pq n ,
+then the macro accepts an arbitrary number of arguments.
+.Bd -literal -offset indent
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
+
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
+
+\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
+.Ed
+.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
+.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
+.It Ic \&%A Ta \&No Ta \&No Ta >0
+.It Ic \&%B Ta \&No Ta \&No Ta >0
+.It Ic \&%C Ta \&No Ta \&No Ta >0
+.It Ic \&%D Ta \&No Ta \&No Ta >0
+.It Ic \&%I Ta \&No Ta \&No Ta >0
+.It Ic \&%J Ta \&No Ta \&No Ta >0
+.It Ic \&%N Ta \&No Ta \&No Ta >0
+.It Ic \&%O Ta \&No Ta \&No Ta >0
+.It Ic \&%P Ta \&No Ta \&No Ta >0
+.It Ic \&%Q Ta \&No Ta \&No Ta >0
+.It Ic \&%R Ta \&No Ta \&No Ta >0
+.It Ic \&%T Ta \&No Ta \&No Ta >0
+.It Ic \&%U Ta \&No Ta \&No Ta >0
+.It Ic \&%V Ta \&No Ta \&No Ta >0
+.It Ic \&Ad Ta Yes Ta Yes Ta >0
+.It Ic \&An Ta Yes Ta Yes Ta >0
+.It Ic \&Ap Ta Yes Ta Yes Ta 0
+.It Ic \&Ar Ta Yes Ta Yes Ta n
+.It Ic \&At Ta Yes Ta Yes Ta 1
+.It Ic \&Bsx Ta Yes Ta Yes Ta n
+.It Ic \&Bt Ta \&No Ta \&No Ta 0
+.It Ic \&Bx Ta Yes Ta Yes Ta n
+.It Ic \&Cd Ta Yes Ta Yes Ta >0
+.It Ic \&Cm Ta Yes Ta Yes Ta >0
+.It Ic \&Db Ta \&No Ta \&No Ta 1
+.It Ic \&Dd Ta \&No Ta \&No Ta n
+.It Ic \&Dt Ta \&No Ta \&No Ta n
+.It Ic \&Dv Ta Yes Ta Yes Ta >0
+.It Ic \&Dx Ta Yes Ta Yes Ta n
+.It Ic \&Em Ta Yes Ta Yes Ta >0
+.It Ic \&Er Ta Yes Ta Yes Ta >0
+.It Ic \&Es Ta Yes Ta Yes Ta 2
+.It Ic \&Ev Ta Yes Ta Yes Ta >0
+.It Ic \&Ex Ta \&No Ta \&No Ta n
+.It Ic \&Fa Ta Yes Ta Yes Ta >0
+.It Ic \&Fd Ta \&No Ta \&No Ta >0
+.It Ic \&Fl Ta Yes Ta Yes Ta n
+.It Ic \&Fn Ta Yes Ta Yes Ta >0
+.It Ic \&Fr Ta Yes Ta Yes Ta >0
+.It Ic \&Ft Ta Yes Ta Yes Ta >0
+.It Ic \&Fx Ta Yes Ta Yes Ta n
+.It Ic \&Hf Ta \&No Ta \&No Ta n
+.It Ic \&Ic Ta Yes Ta Yes Ta >0
+.It Ic \&In Ta \&No Ta \&No Ta 1
+.It Ic \&Lb Ta \&No Ta \&No Ta 1
+.It Ic \&Li Ta Yes Ta Yes Ta >0
+.It Ic \&Lk Ta Yes Ta Yes Ta >0
+.It Ic \&Lp Ta \&No Ta \&No Ta 0
+.It Ic \&Ms Ta Yes Ta Yes Ta >0
+.It Ic \&Mt Ta Yes Ta Yes Ta >0
+.It Ic \&Nm Ta Yes Ta Yes Ta n
+.It Ic \&No Ta Yes Ta Yes Ta 0
+.It Ic \&Ns Ta Yes Ta Yes Ta 0
+.It Ic \&Nx Ta Yes Ta Yes Ta n
+.It Ic \&Os Ta \&No Ta \&No Ta n
+.It Ic \&Ot Ta Yes Ta Yes Ta >0
+.It Ic \&Ox Ta Yes Ta Yes Ta n
+.It Ic \&Pa Ta Yes Ta Yes Ta n
+.It Ic \&Pf Ta Yes Ta Yes Ta 1
+.It Ic \&Pp Ta \&No Ta \&No Ta 0
+.It Ic \&Rv Ta \&No Ta \&No Ta n
+.It Ic \&Sm Ta \&No Ta \&No Ta <2
+.It Ic \&St Ta \&No Ta Yes Ta 1
+.It Ic \&Sx Ta Yes Ta Yes Ta >0
+.It Ic \&Sy Ta Yes Ta Yes Ta >0
+.It Ic \&Tn Ta Yes Ta Yes Ta >0
+.It Ic \&Ud Ta \&No Ta \&No Ta 0
+.It Ic \&Ux Ta Yes Ta Yes Ta n
+.It Ic \&Va Ta Yes Ta Yes Ta n
+.It Ic \&Vt Ta Yes Ta Yes Ta >0
+.It Ic \&Xr Ta Yes Ta Yes Ta 2
+.El
+.Ss Delimiters
+When a macro argument consists of one single input character
+considered as a delimiter, the argument gets special handling.
+This does not apply when delimiters appear in arguments containing
+more than one character.
+Consequently, to prevent special handling and just handle it
+like any other argument, a delimiter can be escaped by prepending
+a zero-width space
+.Pq Sq \e& .
+In text lines, delimiters never need escaping, but may be used
+as normal punctuation.
+.Pp
+For many macros, when the leading arguments are opening delimiters,
+these delimiters are put before the macro scope,
+and when the trailing arguments are closing delimiters,
+these delimiters are put after the macro scope.
+Spacing is suppressed after opening delimiters
+and before closing delimiters.
+For example,
+.Pp
+.D1 Pf \. \&Aq "( [ word ] ) ."
+.Pp
+renders as:
+.Pp
+.D1 Aq ( [ word ] ) .
+.Pp
+Opening delimiters are:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&(
+left parenthesis
+.It \&[
+left bracket
+.El
+.Pp
+Closing delimiters are:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&.
+period
+.It \&,
+comma
+.It \&:
+colon
+.It \&;
+semicolon
+.It \&)
+right parenthesis
+.It \&]
+right bracket
+.It \&?
+question mark
+.It \&!
+exclamation mark
+.El
+.Pp
+Note that even a period preceded by a backslash
+.Pq Sq \e.\&
+gets this special handling; use
+.Sq \e&.
+to prevent that.
+.Pp
+Many in-line macros interrupt their scope when they encounter
+delimiters, and resume their scope when more arguments follow that
+are not delimiters.
+For example,
+.Pp
+.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
+.Pp
+renders as:
+.Pp
+.D1 Fl a ( b | c \*(Ba d ) e
+.Pp
+This applies to both opening and closing delimiters,
+and also to the middle delimiter, which does not suppress spacing:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It \&|
+vertical bar
+.El
+.Pp
+As a special case, the predefined string \e*(Ba is handled and rendered
+in the same way as a plain
+.Sq \&|
+character.
+Using this predefined string is not recommended in new manuals.
+.Ss Font handling
+In
+.Nm
+documents, usage of semantic markup is recommended in order to have
+proper fonts automatically selected; only when no fitting semantic markup
+is available, consider falling back to
+.Sx Physical markup
+macros.
+Whenever any
+.Nm
+macro switches the
+.Xr roff 7
+font mode, it will automatically restore the previous font when exiting
+its scope.
+Manually switching the font using the
+.Xr roff 7
+.Ql \ef
+font escape sequences is never required.
git.ckatri.com / mandoc.git / blobdiff