+.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
+.Sx \&Bf
+and
+.Pq optionally
+.Sx \&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 Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
+.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
+.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
+.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
+.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
+.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
+.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
+.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&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
+.Sx \&It Fl bullet ,
+.Fl hyphen ,
+.Fl dash ,
+.Fl enum ,
+.Fl item
+.Pc
+don't have heads; only one
+.Po
+.Sx \&It
+in
+.Sx \&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 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 \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
+.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
+.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
+.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
+Like block full-explicit, but also with single-line scope.
+Each has at least a body and, in limited circumstances, a head
+.Po
+.Sx \&Fo ,
+.Sx \&Eo
+.Pc
+and/or tail
+.Pq Sx \&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 Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
+.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
+.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
+.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
+.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
+.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
+.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
+.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
+.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
+.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
+.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
+.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
+.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
+.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
+.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
+.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
+.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
+.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
+.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
+.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
+.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
+.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
+.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
+.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&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 Sx \&Aq Ta Yes Ta Yes
+.It Sx \&Bq Ta Yes Ta Yes
+.It Sx \&Brq Ta Yes Ta Yes
+.It Sx \&D1 Ta \&No Ta \&Yes
+.It Sx \&Dl Ta \&No Ta Yes
+.It Sx \&Dq Ta Yes Ta Yes
+.It Sx \&En Ta Yes Ta Yes
+.It Sx \&Op Ta Yes Ta Yes
+.It Sx \&Pq Ta Yes Ta Yes
+.It Sx \&Ql Ta Yes Ta Yes
+.It Sx \&Qq Ta Yes Ta Yes
+.It Sx \&Sq Ta Yes Ta Yes
+.It Sx \&Vt Ta Yes Ta Yes
+.El
+.Pp
+Note that the
+.Sx \&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
+.Sx \&Ta
+macro can only be used below
+.Sx \&It
+in
+.Sx \&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 Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&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 Sx \&%A Ta \&No Ta \&No Ta >0
+.It Sx \&%B Ta \&No Ta \&No Ta >0
+.It Sx \&%C Ta \&No Ta \&No Ta >0
+.It Sx \&%D Ta \&No Ta \&No Ta >0
+.It Sx \&%I Ta \&No Ta \&No Ta >0
+.It Sx \&%J Ta \&No Ta \&No Ta >0
+.It Sx \&%N Ta \&No Ta \&No Ta >0
+.It Sx \&%O Ta \&No Ta \&No Ta >0
+.It Sx \&%P Ta \&No Ta \&No Ta >0
+.It Sx \&%Q Ta \&No Ta \&No Ta >0
+.It Sx \&%R Ta \&No Ta \&No Ta >0
+.It Sx \&%T Ta \&No Ta \&No Ta >0
+.It Sx \&%U Ta \&No Ta \&No Ta >0
+.It Sx \&%V Ta \&No Ta \&No Ta >0
+.It Sx \&Ad Ta Yes Ta Yes Ta >0
+.It Sx \&An Ta Yes Ta Yes Ta >0
+.It Sx \&Ap Ta Yes Ta Yes Ta 0
+.It Sx \&Ar Ta Yes Ta Yes Ta n
+.It Sx \&At Ta Yes Ta Yes Ta 1
+.It Sx \&Bsx Ta Yes Ta Yes Ta n
+.It Sx \&Bt Ta \&No Ta \&No Ta 0
+.It Sx \&Bx Ta Yes Ta Yes Ta n
+.It Sx \&Cd Ta Yes Ta Yes Ta >0
+.It Sx \&Cm Ta Yes Ta Yes Ta >0
+.It Sx \&Db Ta \&No Ta \&No Ta 1
+.It Sx \&Dd Ta \&No Ta \&No Ta n
+.It Sx \&Dt Ta \&No Ta \&No Ta n
+.It Sx \&Dv Ta Yes Ta Yes Ta >0
+.It Sx \&Dx Ta Yes Ta Yes Ta n
+.It Sx \&Em Ta Yes Ta Yes Ta >0
+.It Sx \&Er Ta Yes Ta Yes Ta >0
+.It Sx \&Es Ta Yes Ta Yes Ta 2
+.It Sx \&Ev Ta Yes Ta Yes Ta >0
+.It Sx \&Ex Ta \&No Ta \&No Ta n
+.It Sx \&Fa Ta Yes Ta Yes Ta >0
+.It Sx \&Fd Ta \&No Ta \&No Ta >0
+.It Sx \&Fl Ta Yes Ta Yes Ta n
+.It Sx \&Fn Ta Yes Ta Yes Ta >0
+.It Sx \&Fr Ta Yes Ta Yes Ta >0
+.It Sx \&Ft Ta Yes Ta Yes Ta >0
+.It Sx \&Fx Ta Yes Ta Yes Ta n
+.It Sx \&Hf Ta \&No Ta \&No Ta n
+.It Sx \&Ic Ta Yes Ta Yes Ta >0
+.It Sx \&In Ta \&No Ta \&No Ta 1
+.It Sx \&Lb Ta \&No Ta \&No Ta 1
+.It Sx \&Li Ta Yes Ta Yes Ta >0
+.It Sx \&Lk Ta Yes Ta Yes Ta >0
+.It Sx \&Lp Ta \&No Ta \&No Ta 0
+.It Sx \&Ms Ta Yes Ta Yes Ta >0
+.It Sx \&Mt Ta Yes Ta Yes Ta >0
+.It Sx \&Nm Ta Yes Ta Yes Ta n
+.It Sx \&No Ta Yes Ta Yes Ta 0
+.It Sx \&Ns Ta Yes Ta Yes Ta 0
+.It Sx \&Nx Ta Yes Ta Yes Ta n
+.It Sx \&Os Ta \&No Ta \&No Ta n
+.It Sx \&Ot Ta Yes Ta Yes Ta >0
+.It Sx \&Ox Ta Yes Ta Yes Ta n
+.It Sx \&Pa Ta Yes Ta Yes Ta n
+.It Sx \&Pf Ta Yes Ta Yes Ta 1
+.It Sx \&Pp Ta \&No Ta \&No Ta 0
+.It Sx \&Rv Ta \&No Ta \&No Ta n
+.It Sx \&Sm Ta \&No Ta \&No Ta <2
+.It Sx \&St Ta \&No Ta Yes Ta 1
+.It Sx \&Sx Ta Yes Ta Yes Ta >0
+.It Sx \&Sy Ta Yes Ta Yes Ta >0
+.It Sx \&Tn Ta Yes Ta Yes Ta >0
+.It Sx \&Ud Ta \&No Ta \&No Ta 0
+.It Sx \&Ux Ta Yes Ta Yes Ta n
+.It Sx \&Va Ta Yes Ta Yes Ta n
+.It Sx \&Vt Ta Yes Ta Yes Ta >0
+.It Sx \&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