roff.7 (63448B)
- .\" $Id: roff.7,v 1.116 2021/09/18 12:23:06 schwarze Exp $
- .\"
- .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
- .\" Copyright (c) 2010-2019 Ingo Schwarze <schwarze@openbsd.org>
- .\"
- .\" Permission to use, copy, modify, and distribute this software for any
- .\" purpose with or without fee is hereby granted, provided that the above
- .\" copyright notice and this permission notice appear in all copies.
- .\"
- .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- .\"
- .Dd $Mdocdate: September 18 2021 $
- .Dt ROFF 7
- .Os
- .Sh NAME
- .Nm roff
- .Nd roff language reference for mandoc
- .Sh DESCRIPTION
- The
- .Nm roff
- language is a general purpose text formatting language.
- Since traditional implementations of the
- .Xr mdoc 7
- and
- .Xr man 7
- manual formatting languages are based on it,
- many real-world manuals use small numbers of
- .Nm
- requests and escape sequences intermixed with their
- .Xr mdoc 7
- or
- .Xr man 7
- code.
- To properly format such manuals, the
- .Xr mandoc 1
- utility supports a subset of
- .Nm
- requests and escapes.
- Even though this manual page lists all
- .Nm
- requests and escape sequences, it only contains partial information
- about requests not supported by
- .Xr mandoc 1
- and about language features that do not matter for manual pages.
- For complete
- .Nm
- manuals, consult the
- .Sx SEE ALSO
- section.
- .Pp
- Input lines beginning with the control character
- .Sq \&.
- are parsed for requests and macros.
- Such lines are called
- .Dq request lines
- or
- .Dq macro lines ,
- respectively.
- Requests change the processing state and manipulate the formatting;
- some macros also define the document structure and produce formatted
- output.
- The single quote
- .Pq Qq \(aq
- is accepted as an alternative control character,
- treated by
- .Xr mandoc 1
- just like
- .Ql \&.
- .Pp
- Lines not beginning with control characters are called
- .Dq text lines .
- They provide free-form text to be printed; the formatting of the text
- depends on the respective processing context.
- .Sh LANGUAGE SYNTAX
- .Nm
- documents may contain only graphable 7-bit ASCII characters, the space
- character, and, in certain circumstances, the tab character.
- The backslash character
- .Sq \e
- indicates the start of an escape sequence, used for example for
- .Sx Comments
- and
- .Sx Special Characters .
- For a complete listing of escape sequences, consult the
- .Sx ESCAPE SEQUENCE REFERENCE
- below.
- .Ss Comments
- Text following an escaped double-quote
- .Sq \e\(dq ,
- whether in a request, macro, or text line, is ignored to the end of the line.
- A request line beginning with a control character and comment escape
- .Sq \&.\e\(dq
- is also ignored.
- Furthermore, request lines with only a control character and optional
- trailing whitespace are stripped from input.
- .Pp
- Examples:
- .Bd -literal -offset indent -compact
- \&.\e\(dq This is a comment line.
- \&.\e\(dq The next line is ignored:
- \&.
- \&.Sh EXAMPLES \e\(dq This is a comment, too.
- \&example text \e\(dq And so is this.
- .Ed
- .Ss Special Characters
- Special characters are used to encode special glyphs and are rendered
- differently across output media.
- They may occur in request, macro, and text lines.
- Sequences begin with the escape character
- .Sq \e
- followed by either an open-parenthesis
- .Sq \&(
- for two-character sequences; an open-bracket
- .Sq \&[
- for n-character sequences (terminated at a close-bracket
- .Sq \&] ) ;
- or a single one character sequence.
- .Pp
- Examples:
- .Bl -tag -width Ds -offset indent -compact
- .It Li \e(em
- Two-letter em dash escape.
- .It Li \ee
- One-letter backslash escape.
- .El
- .Pp
- See
- .Xr mandoc_char 7
- for a complete list.
- .Ss Font Selection
- In
- .Xr mdoc 7
- and
- .Xr man 7
- documents, fonts are usually selected with macros.
- The
- .Ic \ef
- escape sequence and the
- .Ic \&ft
- request can be used to manually change the font,
- but this is not recommended in
- .Xr mdoc 7
- documents.
- Such manual font changes are overridden by many subsequent macros.
- .Pp
- The following fonts are supported:
- .Pp
- .Bl -tag -width CW -offset indent -compact
- .It Cm B
- Bold font.
- .It Cm BI
- A font that is both bold and italic.
- .It Cm CB
- Bold constant width font.
- Same as
- .Cm B
- in terminal output.
- .It Cm CI
- Italic constant width font.
- Same as
- .Cm I
- in terminal output.
- .It Cm CR
- Regular constant width font.
- Same as
- .Cm R
- in terminal output.
- .It Cm CW
- An alias for
- .Cm CR .
- .It Cm I
- Italic font.
- .It Cm P
- Return to the previous font.
- If a macro caused a font change since the last
- .Ic \ef
- eascape sequence or
- .Ic \&ft
- request, this returns to the font before the last font change in
- the macro rather than to the font before the last manual font change.
- .It Cm R
- Roman font.
- This is the default font.
- .It Cm 1
- An alias for
- .Cm R .
- .It Cm 2
- An alias for
- .Cm I .
- .It Cm 3
- An alias for
- .Cm B .
- .It Cm 4
- An alias for
- .Cm BI .
- .El
- .Pp
- Examples:
- .Bl -tag -width Ds -offset indent -compact
- .It Li \efBbold\efR
- Write in \fBbold\fP, then switch to regular font mode.
- .It Li \efIitalic\efP
- Write in \fIitalic\fP, then return to previous font mode.
- .It Li \ef(BIbold italic\efP
- Write in \f(BIbold italic\fP, then return to previous font mode.
- .El
- .Ss Whitespace
- Whitespace consists of the space character.
- In text lines, whitespace is preserved within a line.
- In request and macro lines, whitespace delimits arguments and is discarded.
- .Pp
- Unescaped trailing spaces are stripped from text line input unless in a
- literal context.
- In general, trailing whitespace on any input line is discouraged for
- reasons of portability.
- In the rare case that a space character is needed at the end of an
- input line, it may be forced by
- .Sq \e\ \e& .
- .Pp
- Literal space characters can be produced in the output
- using escape sequences.
- In macro lines, they can also be included in arguments using quotation; see
- .Sx MACRO SYNTAX
- for details.
- .Pp
- Blank text lines, which may include whitespace, are only permitted
- within literal contexts.
- If the first character of a text line is a space, that line is printed
- with a leading newline.
- .Ss Scaling Widths
- Many requests and macros support scaled widths for their arguments.
- The syntax for a scaled width is
- .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
- where a decimal must be preceded or followed by at least one digit.
- .Pp
- The following scaling units are accepted:
- .Pp
- .Bl -tag -width Ds -offset indent -compact
- .It c
- centimetre
- .It i
- inch
- .It P
- pica (1/6 inch)
- .It p
- point (1/72 inch)
- .It f
- scale
- .Sq u
- by 65536
- .It v
- default vertical span
- .It m
- width of rendered
- .Sq m
- .Pq em
- character
- .It n
- width of rendered
- .Sq n
- .Pq en
- character
- .It u
- default horizontal span for the terminal
- .It M
- mini-em (1/100 em)
- .El
- .Pp
- Using anything other than
- .Sq m ,
- .Sq n ,
- or
- .Sq v
- is necessarily non-portable across output media.
- See
- .Sx COMPATIBILITY .
- .Pp
- If a scaling unit is not provided, the numerical value is interpreted
- under the default rules of
- .Sq v
- for vertical spaces and
- .Sq u
- for horizontal ones.
- .Pp
- Examples:
- .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
- .It Li \&.Bl -tag -width 2i
- two-inch tagged list indentation in
- .Xr mdoc 7
- .It Li \&.HP 2i
- two-inch tagged list indentation in
- .Xr man 7
- .It Li \&.sp 2v
- two vertical spaces
- .El
- .Ss Sentence Spacing
- Each sentence should terminate at the end of an input line.
- By doing this, a formatter will be able to apply the proper amount of
- spacing after the end of sentence (unescaped) period, exclamation mark,
- or question mark followed by zero or more non-sentence closing
- delimiters
- .Po
- .Sq \&) ,
- .Sq \&] ,
- .Sq \&' ,
- .Sq \&"
- .Pc .
- .Pp
- The proper spacing is also intelligently preserved if a sentence ends at
- the boundary of a macro line.
- .Pp
- If an input line happens to end with a period, exclamation or question
- mark that isn't the end of a sentence, append a zero-width space
- .Pq Sq \e& .
- .Pp
- Examples:
- .Bd -literal -offset indent -compact
- Do not end sentences mid-line like this. Instead,
- end a sentence like this.
- A macro would end like this:
- \&.Xr mandoc 1 \&.
- An abbreviation at the end of an input line needs escaping, e.g.\e&
- like this.
- .Ed
- .Sh REQUEST SYNTAX
- A request or macro line consists of:
- .Pp
- .Bl -enum -compact
- .It
- the control character
- .Sq \&.
- or
- .Sq \(aq
- at the beginning of the line,
- .It
- optionally an arbitrary amount of whitespace,
- .It
- the name of the request or the macro, which is one word of arbitrary
- length, terminated by whitespace,
- .It
- and zero or more arguments delimited by whitespace.
- .El
- .Pp
- Thus, the following request lines are all equivalent:
- .Bd -literal -offset indent
- \&.ig end
- \&.ig end
- \&. ig end
- .Ed
- .Sh MACRO SYNTAX
- Macros are provided by the
- .Xr mdoc 7
- and
- .Xr man 7
- languages and can be defined by the
- .Ic \&de
- request.
- When called, they follow the same syntax as requests, except that
- macro arguments may optionally be quoted by enclosing them
- in double quote characters
- .Pq Sq \(dq .
- Quoted text, even if it contains whitespace or would cause
- a macro invocation when unquoted, is always considered literal text.
- Inside quoted text, pairs of double quote characters
- .Pq Sq Qq
- resolve to single double quote characters.
- .Pp
- To be recognised as the beginning of a quoted argument, the opening
- quote character must be preceded by a space character.
- A quoted argument extends to the next double quote character that is not
- part of a pair, or to the end of the input line, whichever comes earlier.
- Leaving out the terminating double quote character at the end of the line
- is discouraged.
- For clarity, if more arguments follow on the same input line,
- it is recommended to follow the terminating double quote character
- by a space character; in case the next character after the terminating
- double quote character is anything else, it is regarded as the beginning
- of the next, unquoted argument.
- .Pp
- Both in quoted and unquoted arguments, pairs of backslashes
- .Pq Sq \e\e
- resolve to single backslashes.
- In unquoted arguments, space characters can alternatively be included
- by preceding them with a backslash
- .Pq Sq \e\~ ,
- but quoting is usually better for clarity.
- .Pp
- Examples:
- .Bl -tag -width Ds -offset indent -compact
- .It Li .Fn strlen \(dqconst char *s\(dq
- Group arguments
- .Qq const char *s
- into one function argument.
- If unspecified,
- .Qq const ,
- .Qq char ,
- and
- .Qq *s
- would be considered separate arguments.
- .It Li .Op \(dqFl a\(dq
- Consider
- .Qq \&Fl a
- as literal text instead of a flag macro.
- .El
- .Sh REQUEST REFERENCE
- The
- .Xr mandoc 1
- .Nm
- parser recognises the following requests.
- For requests marked as "ignored" or "unsupported", any arguments are
- ignored, and the number of arguments is not checked.
- .Bl -tag -width Ds
- .It Ic \&ab Op Ar message
- Abort processing.
- Currently unsupported.
- .It Ic \&ad Op Cm b | c | l | n | r
- Set line adjustment mode for subsequent text.
- Currently ignored.
- .It Ic \&af Ar registername format
- Assign an output format to a number register.
- Currently ignored.
- .It Ic \&aln Ar newname oldname
- Create an alias for a number register.
- Currently unsupported.
- .It Ic \&als Ar newname oldname
- Create an alias for a request, string, macro, or diversion.
- .It Ic \&am Ar macroname Op Ar endmacro
- Append to a macro definition.
- The syntax of this request is the same as that of
- .Ic \&de .
- .It Ic \&am1 Ar macroname Op Ar endmacro
- Append to a macro definition, switching roff compatibility mode off
- during macro execution (groff extension).
- The syntax of this request is the same as that of
- .Ic \&de1 .
- Since
- .Xr mandoc 1
- does not implement
- .Nm
- compatibility mode at all, it handles this request as an alias for
- .Ic \&am .
- .It Ic \&ami Ar macrostring Op Ar endstring
- Append to a macro definition, specifying the macro name indirectly
- (groff extension).
- The syntax of this request is the same as that of
- .Ic \&dei .
- .It Ic \&ami1 Ar macrostring Op Ar endstring
- Append to a macro definition, specifying the macro name indirectly
- and switching roff compatibility mode off during macro execution
- (groff extension).
- The syntax of this request is the same as that of
- .Ic \&dei1 .
- Since
- .Xr mandoc 1
- does not implement
- .Nm
- compatibility mode at all, it handles this request as an alias for
- .Ic \&ami .
- .It Ic \&as Ar stringname Op Ar string
- Append to a user-defined string.
- The syntax of this request is the same as that of
- .Ic \&ds .
- If a user-defined string with the specified name does not yet exist,
- it is set to the empty string before appending.
- .It Ic \&as1 Ar stringname Op Ar string
- Append to a user-defined string, switching roff compatibility mode off
- during macro execution (groff extension).
- The syntax of this request is the same as that of
- .Ic \&ds1 .
- Since
- .Xr mandoc 1
- does not implement
- .Nm
- compatibility mode at all, it handles this request as an alias for
- .Ic \&as .
- .It Ic \&asciify Ar divname
- Fully unformat a diversion.
- Currently unsupported.
- .It Ic \&backtrace
- Print a backtrace of the input stack.
- This is a groff extension and currently ignored.
- .It Ic \&bd Ar font Oo Ar curfont Oc Op Ar offset
- Artificially embolden by repeated printing with small shifts.
- Currently ignored.
- .It Ic \&bleedat Ar left top width height
- Set the BleedBox page parameter for PDF generation.
- This is a Heirloom extension and currently ignored.
- .It Ic \&blm Ar macroname
- Set a blank line trap.
- Currently unsupported.
- .It Ic \&box Ar divname
- Begin a diversion without including a partially filled line.
- Currently unsupported.
- .It Ic \&boxa Ar divname
- Add to a diversion without including a partially filled line.
- Currently unsupported.
- .It Ic \&bp Oo Cm + Ns | Ns Cm - Oc Ns Ar pagenumber
- Begin a new page.
- Currently ignored.
- .It Ic \&BP Ar source height width position offset flags label
- Define a frame and place a picture in it.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&br
- Break the output line.
- .It Ic \&break
- Break out of the innermost
- .Ic \&while
- loop.
- .It Ic \&breakchar Ar char ...
- Optional line break characters.
- This is a Heirloom extension and currently ignored.
- .It Ic \&brnl Ar N
- Break output line after the next
- .Ar N
- input lines.
- This is a Heirloom extension and currently ignored.
- .It Ic \&brp
- Break and spread output line.
- Currently, this is implemented as an alias for
- .Ic \&br .
- .It Ic \&brpnl Ar N
- Break and spread output line after the next
- .Ar N
- input lines.
- This is a Heirloom extension and currently ignored.
- .It Ic \&c2 Op Ar char
- Change the no-break control character.
- Currently unsupported.
- .It Ic \&cc Op Ar char
- Change the control character.
- If
- .Ar char
- is not specified, the control character is reset to
- .Sq \&. .
- Trailing characters are ignored.
- .It Ic \&ce Op Ar N
- Center the next
- .Ar N
- input lines without filling.
- .Ar N
- defaults to 1.
- An argument of 0 or less ends centering.
- Currently, high level macros abort centering.
- .It Ic \&cf Ar filename
- Output the contents of a file.
- Ignored because insecure.
- .It Ic \&cflags Ar flags char ...
- Set character flags.
- This is a groff extension and currently ignored.
- .It Ic \&ch Ar macroname Op Ar dist
- Change a trap location.
- Currently ignored.
- .It Ic \&char Ar glyph Op Ar string
- Define or redefine the ASCII character or character escape sequence
- .Ar glyph
- to be rendered as
- .Ar string ,
- which can be empty.
- Only partially supported in
- .Xr mandoc 1 ;
- may interact incorrectly with
- .Ic \&tr .
- .It Ic \&chop Ar stringname
- Remove the last character from a macro, string, or diversion.
- Currently unsupported.
- .It Ic \&class Ar classname char ...
- Define a character class.
- This is a groff extension and currently ignored.
- .It Ic \&close Ar streamname
- Close an open file.
- Ignored because insecure.
- .It Ic \&CL Ar color text
- Print text in color.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&color Op Cm 1 | 0
- Activate or deactivate colors.
- This is a groff extension and currently ignored.
- .It Ic \&composite Ar from to
- Define a name component for composite glyph names.
- This is a groff extension and currently unsupported.
- .It Ic \&continue
- Immediately start the next iteration of a
- .Ic \&while
- loop.
- Currently unsupported.
- .It Ic \&cp Op Cm 1 | 0
- Switch
- .Nm
- compatibility mode on or off.
- Currently ignored.
- .It Ic \&cropat Ar left top width height
- Set the CropBox page parameter for PDF generation.
- This is a Heirloom extension and currently ignored.
- .It Ic \&cs Ar font Op Ar width Op Ar emsize
- Constant character spacing mode.
- Currently ignored.
- .It Ic \&cu Op Ar N
- Underline next
- .Ar N
- input lines including whitespace.
- Currently ignored.
- .It Ic \&da Ar divname
- Append to a diversion.
- Currently unsupported.
- .It Ic \&dch Ar macroname Op Ar dist
- Change a trap location in the current diversion.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&de Ar macroname Op Ar endmacro
- Define a
- .Nm
- macro.
- Its syntax can be either
- .Bd -literal -offset indent
- .Pf . Ic \&de Ar macroname
- .Ar definition
- \&..
- .Ed
- .Pp
- or
- .Bd -literal -offset indent
- .Pf . Ic \&de Ar macroname endmacro
- .Ar definition
- .Pf . Ar endmacro
- .Ed
- .Pp
- Both forms define or redefine the macro
- .Ar macroname
- to represent the
- .Ar definition ,
- which may consist of one or more input lines, including the newline
- characters terminating each line, optionally containing calls to
- .Nm
- requests,
- .Nm
- macros or high-level macros like
- .Xr man 7
- or
- .Xr mdoc 7
- macros, whichever applies to the document in question.
- .Pp
- Specifying a custom
- .Ar endmacro
- works in the same way as for
- .Ic \&ig ;
- namely, the call to
- .Sq Pf . Ar endmacro
- first ends the
- .Ar definition ,
- and after that, it is also evaluated as a
- .Nm
- request or
- .Nm
- macro, but not as a high-level macro.
- .Pp
- The macro can be invoked later using the syntax
- .Pp
- .D1 Pf . Ar macroname Op Ar argument Op Ar argument ...
- .Pp
- Regarding argument parsing, see
- .Sx MACRO SYNTAX
- above.
- .Pp
- The line invoking the macro will be replaced
- in the input stream by the
- .Ar definition ,
- replacing all occurrences of
- .No \e\e$ Ns Ar N ,
- where
- .Ar N
- is a digit, by the
- .Ar N Ns th Ar argument .
- For example,
- .Bd -literal -offset indent
- \&.de ZN
- \efI\e^\e\e$1\e^\efP\e\e$2
- \&..
- \&.ZN XtFree .
- .Ed
- .Pp
- produces
- .Pp
- .D1 \efI\e^XtFree\e^\efP.
- .Pp
- in the input stream, and thus in the output: \fI\^XtFree\^\fP.
- Each occurrence of \e\e$* is replaced with all the arguments,
- joined together with single space characters.
- The variant \e\e$@ is similar, except that each argument is
- individually quoted.
- .Pp
- Since macros and user-defined strings share a common string table,
- defining a macro
- .Ar macroname
- clobbers the user-defined string
- .Ar macroname ,
- and the
- .Ar definition
- can also be printed using the
- .Sq \e*
- string interpolation syntax described below
- .Ic ds ,
- but this is rarely useful because every macro definition contains at least
- one explicit newline character.
- .Pp
- In order to prevent endless recursion, both groff and
- .Xr mandoc 1
- limit the stack depth for expanding macros and strings
- to a large, but finite number, and
- .Xr mandoc 1
- also limits the length of the expanded input line.
- Do not rely on the exact values of these limits.
- .It Ic \&de1 Ar macroname Op Ar endmacro
- Define a
- .Nm
- macro that will be executed with
- .Nm
- compatibility mode switched off during macro execution.
- This is a groff extension.
- Since
- .Xr mandoc 1
- does not implement
- .Nm
- compatibility mode at all, it handles this request as an alias for
- .Ic \&de .
- .It Ic \&defcolor Ar newname scheme component ...
- Define a color name.
- This is a groff extension and currently ignored.
- .It Ic \&dei Ar macrostring Op Ar endstring
- Define a
- .Nm
- macro, specifying the macro name indirectly (groff extension).
- The syntax of this request is the same as that of
- .Ic \&de .
- The effect is the same as:
- .Pp
- .D1 Pf . Cm \&de No \e* Ns Bo Ar macrostring Bc Op \e* Ns Bq Ar endstring
- .It Ic \&dei1 Ar macrostring Op Ar endstring
- Define a
- .Nm
- macro that will be executed with
- .Nm
- compatibility mode switched off during macro execution,
- specifying the macro name indirectly (groff extension).
- Since
- .Xr mandoc 1
- does not implement
- .Nm
- compatibility mode at all, it handles this request as an alias for
- .Ic \&dei .
- .It Ic \&device Ar string ...
- .It Ic \&devicem Ar stringname
- These two requests only make sense with the groff-specific intermediate
- output format and are unsupported.
- .It Ic \&di Ar divname
- Begin a diversion.
- Currently unsupported.
- .It Ic \&do Ar command Op Ar argument ...
- Execute
- .Nm
- request or macro line with compatibility mode disabled.
- Currently unsupported.
- .It Ic \&ds Ar stringname Op Oo \(dq Oc Ns Ar string
- Define a user-defined string.
- The
- .Ar stringname
- and
- .Ar string
- arguments are space-separated.
- If the
- .Ar string
- begins with a double-quote character, that character will not be part
- of the string.
- All remaining characters on the input line form the
- .Ar string ,
- including whitespace and double-quote characters, even trailing ones.
- .Pp
- The
- .Ar string
- can be interpolated into subsequent text by using
- .No \e* Ns Bq Ar stringname
- for a
- .Ar stringname
- of arbitrary length, or \e*(NN or \e*N if the length of
- .Ar stringname
- is two or one characters, respectively.
- Interpolation can be prevented by escaping the leading backslash;
- that is, an asterisk preceded by an even number of backslashes
- does not trigger string interpolation.
- .Pp
- Since user-defined strings and macros share a common string table,
- defining a string
- .Ar stringname
- clobbers the macro
- .Ar stringname ,
- and the
- .Ar stringname
- used for defining a string can also be invoked as a macro,
- in which case the following input line will be appended to the
- .Ar string ,
- forming a new input line passed to the
- .Nm
- parser.
- For example,
- .Bd -literal -offset indent
- \&.ds badidea .S
- \&.badidea
- H SYNOPSIS
- .Ed
- .Pp
- invokes the
- .Ic SH
- macro when used in a
- .Xr man 7
- document.
- Such abuse is of course strongly discouraged.
- .It Ic \&ds1 Ar stringname Op Oo \(dq Oc Ns Ar string
- Define a user-defined string that will be expanded with
- .Nm
- compatibility mode switched off during string expansion.
- This is a groff extension.
- Since
- .Xr mandoc 1
- does not implement
- .Nm
- compatibility mode at all, it handles this request as an alias for
- .Ic \&ds .
- .It Ic \&dwh Ar dist macroname
- Set a location trap in the current diversion.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&dt Op Ar dist macroname
- Set a trap within a diversion.
- Currently unsupported.
- .It Ic \&ec Op Ar char
- Enable the escape mechanism and change the escape character.
- The
- .Ar char
- argument defaults to the backslash
- .Pq Sq \e .
- .It Ic \&ecr
- Restore the escape character.
- Currently unsupported.
- .It Ic \&ecs
- Save the escape character.
- Currently unsupported.
- .It Ic \&el Ar body
- The
- .Dq else
- half of an if/else conditional.
- Pops a result off the stack of conditional evaluations pushed by
- .Ic \&ie
- and uses it as its conditional.
- If no stack entries are present (e.g., due to no prior
- .Ic \&ie
- calls)
- then false is assumed.
- The syntax of this request is similar to
- .Ic \&if
- except that the conditional is missing.
- .It Ic \&em Ar macroname
- Set a trap at the end of input.
- Currently unsupported.
- .It Ic \&EN
- End an equation block.
- See
- .Ic \&EQ .
- .It Ic \&eo
- Disable the escape mechanism completely.
- .It Ic \&EP
- End a picture started by
- .Ic \&BP .
- This is a Heirloom extension and currently unsupported.
- .It Ic \&EQ
- Begin an equation block.
- See
- .Xr eqn 7
- for a description of the equation language.
- .It Ic \&errprint Ar message
- Print a string like an error message.
- This is a Heirloom extension and currently ignored.
- .It Ic \&ev Op Ar envname
- Switch to another environment.
- Currently unsupported.
- .It Ic \&evc Op Ar envname
- Copy an environment into the current environment.
- Currently unsupported.
- .It Ic \&ex
- Abort processing and exit.
- Currently unsupported.
- .It Ic \&fallback Ar curfont font ...
- Select the fallback sequence for a font.
- This is a Heirloom extension and currently ignored.
- .It Ic \&fam Op Ar familyname
- Change the font family.
- This is a groff extension and currently ignored.
- .It Ic \&fc Op Ar delimchar Op Ar padchar
- Define a delimiting and a padding character for fields.
- Currently unsupported.
- .It Ic \&fchar Ar glyphname Op Ar string
- Define a fallback glyph.
- Currently unsupported.
- .It Ic \&fcolor Ar colorname
- Set the fill color for \eD objects.
- This is a groff extension and currently ignored.
- .It Ic \&fdeferlig Ar font string ...
- Defer ligature building.
- This is a Heirloom extension and currently ignored.
- .It Ic \&feature Cm + Ns | Ns Cm - Ns Ar name
- Enable or disable an OpenType feature.
- This is a Heirloom extension and currently ignored.
- .It Ic \&fi
- Break the output line and switch to fill mode,
- which is active by default but can be ended with the
- .Ic \&nf
- request.
- In fill mode, input from subsequent input lines is added to
- the same output line until the next word no longer fits,
- at which point the output line is broken.
- This request is implied by the
- .Xr mdoc 7
- .Ic \&Sh
- macro and by the
- .Xr man 7
- .Ic \&SH ,
- .Ic \&SS ,
- and
- .Ic \&EE
- macros.
- .It Ic \&fkern Ar font minkern
- Control the use of kerning tables for a font.
- This is a Heirloom extension and currently ignored.
- .It Ic \&fl
- Flush output.
- Currently ignored.
- .It Ic \&flig Ar font string char ...
- Define ligatures.
- This is a Heirloom extension and currently ignored.
- .It Ic \&fp Ar position font Op Ar filename
- Assign font position.
- Currently ignored.
- .It Ic \&fps Ar mapname ...
- Mount a font with a special character map.
- This is a Heirloom extension and currently ignored.
- .It Ic \&fschar Ar font glyphname Op Ar string
- Define a font-specific fallback glyph.
- This is a groff extension and currently unsupported.
- .It Ic \&fspacewidth Ar font Op Ar afmunits
- Set a font-specific width for the space character.
- This is a Heirloom extension and currently ignored.
- .It Ic \&fspecial Ar curfont Op Ar font ...
- Conditionally define a special font.
- This is a groff extension and currently ignored.
- .It Ic \&ft Op Ar font
- Change the font; see
- .Sx Font Selection .
- The
- .Ar font
- argument defaults to
- .Cm P .
- .It Ic \&ftr Ar newname Op Ar oldname
- Translate font name.
- This is a groff extension and currently ignored.
- .It Ic \&fzoom Ar font Op Ar permille
- Zoom font size.
- Currently ignored.
- .It Ic \&gcolor Op Ar colorname
- Set glyph color.
- This is a groff extension and currently ignored.
- .It Ic \&hc Op Ar char
- Set the hyphenation character.
- Currently ignored.
- .It Ic \&hcode Ar char code ...
- Set hyphenation codes of characters.
- Currently ignored.
- .It Ic \&hidechar Ar font char ...
- Hide characters in a font.
- This is a Heirloom extension and currently ignored.
- .It Ic \&hla Ar language
- Set hyphenation language.
- This is a groff extension and currently ignored.
- .It Ic \&hlm Op Ar number
- Set maximum number of consecutive hyphenated lines.
- Currently ignored.
- .It Ic \&hpf Ar filename
- Load hyphenation pattern file.
- This is a groff extension and currently ignored.
- .It Ic \&hpfa Ar filename
- Load hyphenation pattern file, appending to the current patterns.
- This is a groff extension and currently ignored.
- .It Ic \&hpfcode Ar code code ...
- Define mapping values for character codes in hyphenation patterns.
- This is a groff extension and currently ignored.
- .It Ic \&hw Ar word ...
- Specify hyphenation points in words.
- Currently ignored.
- .It Ic \&hy Op Ar mode
- Set automatic hyphenation mode.
- Currently ignored.
- .It Ic \&hylang Ar language
- Set hyphenation language.
- This is a Heirloom extension and currently ignored.
- .It Ic \&hylen Ar nchar
- Minimum word length for hyphenation.
- This is a Heirloom extension and currently ignored.
- .It Ic \&hym Op Ar length
- Set hyphenation margin.
- This is a groff extension and currently ignored.
- .It Ic \&hypp Ar penalty ...
- Define hyphenation penalties.
- This is a Heirloom extension and currently ignored.
- .It Ic \&hys Op Ar length
- Set hyphenation space.
- This is a groff extension and currently ignored.
- .It Ic \&ie Ar condition body
- The
- .Dq if
- half of an if/else conditional.
- The result of the conditional is pushed into a stack used by subsequent
- invocations of
- .Ic \&el ,
- which may be separated by any intervening input (or not exist at all).
- Its syntax is equivalent to
- .Ic \&if .
- .It Ic \&if Ar condition body
- Begin a conditional.
- This request can also be written as follows:
- .Bd -unfilled -offset indent
- .Pf . Ic \&if Ar condition No \e{ Ns Ar body
- .Ar body ... Ns \e}
- .Ed
- .Bd -unfilled -offset indent
- .Pf . Ic \&if Ar condition No \e{\e
- .Ar body ...
- .Pf . No \e}
- .Ed
- .Pp
- The
- .Ar condition
- is a boolean expression.
- Currently,
- .Xr mandoc 1
- supports the following subset of roff conditionals:
- .Bl -bullet
- .It
- If
- .Sq \&!
- is prefixed to
- .Ar condition ,
- it is logically inverted.
- .It
- If the first character of
- .Ar condition
- is
- .Sq n
- .Pq nroff mode
- or
- .Sq o
- .Pq odd page ,
- it evaluates to true, and the
- .Ar body
- starts with the next character.
- .It
- If the first character of
- .Ar condition
- is
- .Sq e
- .Pq even page ,
- .Sq t
- .Pq troff mode ,
- or
- .Sq v
- .Pq vroff mode ,
- it evaluates to false, and the
- .Ar body
- starts with the next character.
- .It
- If the first character of
- .Ar condition
- is
- .Sq c
- .Pq character available ,
- it evaluates to true if the following character is an ASCII character
- or a valid character escape sequence, or to false otherwise.
- The
- .Ar body
- starts with the character following that next character.
- .It
- If the first character of
- .Ar condition
- is
- .Sq d ,
- it evaluates to true if the rest of
- .Ar condition
- is the name of an existing user defined macro or string;
- otherwise, it evaluates to false.
- .It
- If the first character of
- .Ar condition
- is
- .Sq r ,
- it evaluates to true if the rest of
- .Ar condition
- is the name of an existing number register;
- otherwise, it evaluates to false.
- .It
- If the
- .Ar condition
- starts with a parenthesis or with an optionally signed
- integer number, it is evaluated according to the rules of
- .Sx Numerical expressions
- explained below.
- It evaluates to true if the result is positive,
- or to false if the result is zero or negative.
- .It
- Otherwise, the first character of
- .Ar condition
- is regarded as a delimiter and it evaluates to true if the string
- extending from its first to its second occurrence is equal to the
- string extending from its second to its third occurrence.
- .It
- If
- .Ar condition
- cannot be parsed, it evaluates to false.
- .El
- .Pp
- If a conditional is false, its children are not processed, but are
- syntactically interpreted to preserve the integrity of the input
- document.
- Thus,
- .Pp
- .D1 \&.if t .ig
- .Pp
- will discard the
- .Sq \&.ig ,
- which may lead to interesting results, but
- .Pp
- .D1 \&.if t .if t \e{\e
- .Pp
- will continue to syntactically interpret to the block close of the final
- conditional.
- Sub-conditionals, in this case, obviously inherit the truth value of
- the parent.
- .Pp
- If the
- .Ar body
- section is begun by an escaped brace
- .Sq \e{ ,
- scope continues until the end of the input line containing the
- matching closing-brace escape sequence
- .Sq \e} .
- If the
- .Ar body
- is not enclosed in braces, scope continues until the end of the line.
- If the
- .Ar condition
- is followed by a
- .Ar body
- on the same line, whether after a brace or not, then requests and macros
- .Em must
- begin with a control character.
- It is generally more intuitive, in this case, to write
- .Bd -unfilled -offset indent
- .Pf . Ic \&if Ar condition No \e{\e
- .Pf . Ar request
- .Pf . No \e}
- .Ed
- .Pp
- than having the request or macro follow as
- .Pp
- .D1 Pf . Ic \&if Ar condition Pf \e{. Ar request
- .Pp
- The scope of a conditional is always parsed, but only executed if the
- conditional evaluates to true.
- .Pp
- Note that the
- .Sq \e}
- is converted into a zero-width escape sequence if not passed as a
- standalone macro
- .Sq \&.\e} .
- For example,
- .Pp
- .D1 \&.Fl a \e} b
- .Pp
- will result in
- .Sq \e}
- being considered an argument of the
- .Sq \&Fl
- macro.
- .It Ic \&ig Op Ar endmacro
- Ignore input.
- Its syntax can be either
- .Bd -literal -offset indent
- .Pf . Cm \&ig
- .Ar ignored text
- \&..
- .Ed
- .Pp
- or
- .Bd -literal -offset indent
- .Pf . Cm \&ig Ar endmacro
- .Ar ignored text
- .Pf . Ar endmacro
- .Ed
- .Pp
- In the first case, input is ignored until a
- .Sq \&..
- request is encountered on its own line.
- In the second case, input is ignored until the specified
- .Sq Pf . Ar endmacro
- is encountered.
- Do not use the escape character
- .Sq \e
- anywhere in the definition of
- .Ar endmacro ;
- it would cause very strange behaviour.
- .Pp
- When the
- .Ar endmacro
- is a roff request or a roff macro, like in
- .Pp
- .D1 \&.ig if
- .Pp
- the subsequent invocation of
- .Ic \&if
- will first terminate the
- .Ar ignored text ,
- then be invoked as usual.
- Otherwise, it only terminates the
- .Ar ignored text ,
- and arguments following it or the
- .Sq \&..
- request are discarded.
- .It Ic \&in Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
- Change indentation.
- See
- .Xr man 7 .
- Ignored in
- .Xr mdoc 7 .
- .It Ic \&index Ar register stringname substring
- Find a substring in a string.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&it Ar expression macro
- Set an input line trap.
- The named
- .Ar macro
- will be invoked after processing the number of input text lines
- specified by the numerical
- .Ar expression .
- While evaluating the
- .Ar expression ,
- the unit suffixes described below
- .Sx Scaling Widths
- are ignored.
- .It Ic \&itc Ar expression macro
- Set an input line trap, not counting lines ending with \ec.
- Currently unsupported.
- .It Ic \&IX Ar class keystring
- To support the generation of a table of contents,
- .Xr pod2man 1
- emits this user-defined macro, usually without defining it.
- To avoid reporting large numbers of spurious errors,
- .Xr mandoc 1
- ignores it.
- .It Ic \&kern Op Cm 1 | 0
- Switch kerning on or off.
- Currently ignored.
- .It Ic \&kernafter Ar font char ... afmunits ...
- Increase kerning after some characters.
- This is a Heirloom extension and currently ignored.
- .It Ic \&kernbefore Ar font char ... afmunits ...
- Increase kerning before some characters.
- This is a Heirloom extension and currently ignored.
- .It Ic \&kernpair Ar font char ... font char ... afmunits
- Add a kerning pair to the kerning table.
- This is a Heirloom extension and currently ignored.
- .It Ic \&lc Op Ar glyph
- Define a leader repetition character.
- Currently unsupported.
- .It Ic \&lc_ctype Ar localename
- Set the
- .Dv LC_CTYPE
- locale.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&lds Ar macroname string
- Define a local string.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&length Ar register string
- Count the number of input characters in a string.
- Currently unsupported.
- .It Ic \&letadj Ar lspmin lshmin letss lspmax lshmax
- Dynamic letter spacing and reshaping.
- This is a Heirloom extension and currently ignored.
- .It Ic \&lf Ar lineno Op Ar filename
- Change the line number for error messages.
- Ignored because insecure.
- .It Ic \&lg Op Cm 1 | 0
- Switch the ligature mechanism on or off.
- Currently ignored.
- .It Ic \&lhang Ar font char ... afmunits
- Hang characters at left margin.
- This is a Heirloom extension and currently ignored.
- .It Ic \&linetabs Op Cm 1 | 0
- Enable or disable line-tabs mode.
- This is a groff extension and currently unsupported.
- .It Ic \&ll Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
- Change the output line length.
- If the
- .Ar width
- argument is omitted, the line length is reset to its previous value.
- The default setting for terminal output is 78n.
- If a sign is given, the line length is added to or subtracted from;
- otherwise, it is set to the provided value.
- Using this request in new manuals is discouraged for several reasons,
- among others because it overrides the
- .Xr mandoc 1
- .Fl O Cm width
- command line option.
- .It Ic \&lnr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment
- Set local number register.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&lnrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar value Op Ar increment
- Set local floating-point register.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&lpfx Ar string
- Set a line prefix.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&ls Op Ar factor
- Set line spacing.
- It takes one integer argument specifying the vertical distance of
- subsequent output text lines measured in v units.
- Currently ignored.
- .It Ic \&lsm Ar macroname
- Set a leading spaces trap.
- This is a groff extension and currently unsupported.
- .It Ic \< Op Oo Cm + Ns | Ns Cm - Oc Ns Ar width
- Set title line length.
- Currently ignored.
- .It Ic \&mc Ar glyph Op Ar dist
- Print margin character in the right margin.
- The
- .Ar dist
- is currently ignored; instead, 1n is used.
- .It Ic \&mediasize Ar media
- Set the device media size.
- This is a Heirloom extension and currently ignored.
- .It Ic \&minss Ar width
- Set minimum word space.
- This is a Heirloom extension and currently ignored.
- .It Ic \&mk Op Ar register
- Mark vertical position.
- Currently ignored.
- .It Ic \&mso Ar filename
- Load a macro file using the search path.
- Ignored because insecure.
- .It Ic \&na
- Disable adjusting without changing the adjustment mode.
- Currently ignored.
- .It Ic \&ne Op Ar height
- Declare the need for the specified minimum vertical space
- before the next trap or the bottom of the page.
- Currently ignored.
- .It Ic \&nf
- Break the output line and switch to no-fill mode.
- Subsequent input lines are kept together on the same output line
- even when exceeding the right margin,
- and line breaks in subsequent input cause output line breaks.
- This request is implied by the
- .Xr mdoc 7
- .Ic \&Bd Fl unfilled
- and
- .Ic \&Bd Fl literal
- macros and by the
- .Xr man 7
- .Ic \&EX
- macro.
- The
- .Ic \&fi
- request switches back to the default fill mode.
- .It Ic \&nh
- Turn off automatic hyphenation mode.
- Currently ignored.
- .It Ic \&nhychar Ar char ...
- Define hyphenation-inhibiting characters.
- This is a Heirloom extension and currently ignored.
- .It Ic \&nm Op Ar start Op Ar inc Op Ar space Op Ar indent
- Print line numbers.
- Currently unsupported.
- .It Ic \&nn Op Ar number
- Temporarily turn off line numbering.
- Currently unsupported.
- .It Ic \&nop Ar body
- Execute the rest of the input line as a request, macro, or text line,
- skipping the
- .Ic \&nop
- request and any space characters immediately following it.
- This is mostly used to indent text lines inside macro definitions.
- .It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize
- Define or change a register.
- A register is an arbitrary string value that defines some sort of state,
- which influences parsing and/or formatting.
- For the syntax of
- .Ar expression ,
- see
- .Sx Numerical expressions
- below.
- If it is prefixed by a sign, the register will be
- incremented or decremented instead of assigned to.
- .Pp
- The
- .Ar stepsize
- is used by the
- .Ic \en+
- auto-increment feature.
- It remains unchanged when omitted while changing an existing register,
- and it defaults to 0 when defining a new register.
- .Pp
- The following
- .Ar register
- is handled specially:
- .Bl -tag -width Ds
- .It Cm nS
- If set to a positive integer value, certain
- .Xr mdoc 7
- macros will behave in the same way as in the
- .Em SYNOPSIS
- section.
- If set to 0, these macros will behave in the same way as outside the
- .Em SYNOPSIS
- section, even when called within the
- .Em SYNOPSIS
- section itself.
- Note that starting a new
- .Xr mdoc 7
- section with the
- .Ic \&Sh
- macro will reset this register.
- .El
- .It Xo
- .Ic \&nrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression
- .Op Ar increment
- .Xc
- Define or change a floating-point register.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&nroff
- Force nroff mode.
- This is a groff extension and currently ignored.
- .It Ic \&ns
- Turn on no-space mode.
- Currently ignored.
- .It Ic \&nx Op Ar filename
- Abort processing of the current input file and process another one.
- Ignored because insecure.
- .It Ic \&open Ar stream file
- Open a file for writing.
- Ignored because insecure.
- .It Ic \&opena Ar stream file
- Open a file for appending.
- Ignored because insecure.
- .It Ic \&os
- Output saved vertical space.
- Currently ignored.
- .It Ic \&output Ar string
- Output directly to intermediate output.
- Not supported.
- .It Ic \&padj Op Cm 1 | 0
- Globally control paragraph-at-once adjustment.
- This is a Heirloom extension and currently ignored.
- .It Ic \&papersize Ar media
- Set the paper size.
- This is a Heirloom extension and currently ignored.
- .It Ic \&pc Op Ar char
- Change the page number character.
- Currently ignored.
- .It Ic \&pev
- Print environments.
- This is a groff extension and currently ignored.
- .It Ic \&pi Ar command
- Pipe output to a shell command.
- Ignored because insecure.
- .It Ic \&PI
- Low-level request used by
- .Ic \&BP .
- This is a Heirloom extension and currently unsupported.
- .It Ic \&pl Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
- Change page length.
- Currently ignored.
- .It Ic \&pm
- Print names and sizes of macros, strings, and diversions
- to standard error output.
- Currently ignored.
- .It Ic \&pn Oo Cm + Ns | Ns Cm - Oc Ns Ar number
- Change the page number of the next page.
- Currently ignored.
- .It Ic \&pnr
- Print all number registers on standard error output.
- Currently ignored.
- .It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset
- Set a horizontal page offset.
- If no argument is specified, the page offset is reverted to its
- previous value.
- If a sign is specified, the new page offset is calculated relative
- to the current one; otherwise, it is absolute.
- The argument follows the syntax of
- .Sx Scaling Widths
- and the default scaling unit is
- .Cm m .
- .It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size
- Change point size.
- Currently ignored.
- .It Ic \&psbb Ar filename
- Retrieve the bounding box of a PostScript file.
- Currently unsupported.
- .It Ic \&pshape Ar indent length ...
- Set a special shape for the current paragraph.
- This is a Heirloom extension and currently unsupported.
- .It Ic \&pso Ar command
- Include output of a shell command.
- Ignored because insecure.
- .It Ic \&ptr
- Print the names and positions of all traps on standard error output.
- This is a groff extension and currently ignored.
- .It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
- Change post-vertical spacing.
- This is a groff extension and currently ignored.
- .It Ic \&rchar Ar glyph ...
- Remove glyph definitions.
- Currently unsupported.
- .It Ic \&rd Op Ar prompt Op Ar argument ...
- Read from standard input.
- Currently ignored.
- .It Ic \&recursionlimit Ar maxrec maxtail
- Set the maximum stack depth for recursive macros.
- This is a Heirloom extension and currently ignored.
- .It Ic \&return Op Ar twice
- Exit the presently executed macro and return to the caller.
- The argument is currently ignored.
- .It Ic \&rfschar Ar font glyph ...
- Remove font-specific fallback glyph definitions.
- Currently unsupported.
- .It Ic \&rhang Ar font char ... afmunits
- Hang characters at right margin.
- This is a Heirloom extension and currently ignored.
- .It Ic \&rj Op Ar N
- Justify the next
- .Ar N
- input lines to the right margin without filling.
- .Ar N
- defaults to 1.
- An argument of 0 or less ends right adjustment.
- .It Ic \&rm Ar macroname
- Remove a request, macro or string.
- .It Ic \&rn Ar oldname newname
- Rename a request, macro, diversion, or string.
- In
- .Xr mandoc 1 ,
- user-defined macros,
- .Xr mdoc 7
- and
- .Xr man 7
- macros, and user-defined strings can be renamed, but renaming of
- predefined strings and of
- .Nm
- requests is not supported, and diversions are not implemented at all.
- .It Ic \&rnn Ar oldname newname
- Rename a number register.
- Currently unsupported.
- .It Ic \&rr Ar register
- Remove a register.
- .It Ic \&rs
- End no-space mode.
- Currently ignored.
- .It Ic \&rt Op Ar dist
- Return to marked vertical position.
- Currently ignored.
- .It Ic \&schar Ar glyph Op Ar string
- Define global fallback glyph.
- This is a groff extension and currently unsupported.
- .It Ic \&sentchar Ar char ...
- Define sentence-ending characters.
- This is a Heirloom extension and currently ignored.
- .It Ic \&shc Op Ar glyph
- Change the soft hyphen character.
- Currently ignored.
- .It Ic \&shift Op Ar number
- Shift macro arguments
- .Ar number
- times, by default once: \e\e$i becomes what \e\e$i+number was.
- Also decrement \en(.$ by
- .Ar number .
- .It Ic \&sizes Ar size ...
- Define permissible point sizes.
- This is a groff extension and currently ignored.
- .It Ic \&so Ar filename
- Include a source file.
- The file is read and its contents processed as input in place of the
- .Ic \&so
- request line.
- To avoid inadvertent inclusion of unrelated files,
- .Xr mandoc 1
- only accepts relative paths not containing the strings
- .Qq ../
- and
- .Qq /.. .
- .Pp
- This request requires
- .Xr man 1
- to change to the right directory before calling
- .Xr mandoc 1 ,
- per convention to the root of the manual tree.
- Typical usage looks like:
- .Pp
- .Dl \&.so man3/Xcursor.3
- .Pp
- As the whole concept is rather fragile, the use of
- .Ic \&so
- is discouraged.
- Use
- .Xr ln 1
- instead.
- .It Ic \&sp Op Ar height
- Break the output line and emit vertical space.
- The argument follows the syntax of
- .Sx Scaling Widths
- and defaults to one blank line
- .Pq Li 1v .
- .It Ic \&spacewidth Op Cm 1 | 0
- Set the space width from the font metrics file.
- This is a Heirloom extension and currently ignored.
- .It Ic \&special Op Ar font ...
- Define a special font.
- This is a groff extension and currently ignored.
- .It Ic \&spreadwarn Op Ar width
- Warn about wide spacing between words.
- Currently ignored.
- .It Ic \&ss Ar wordspace Op Ar sentencespace
- Set space character size.
- Currently ignored.
- .It Ic \&sty Ar position style
- Associate style with a font position.
- This is a groff extension and currently ignored.
- .It Ic \&substring Ar stringname startpos Op Ar endpos
- Replace a user-defined string with a substring.
- Currently unsupported.
- .It Ic \&sv Op Ar height
- Save vertical space.
- Currently ignored.
- .It Ic \&sy Ar command
- Execute shell command.
- Ignored because insecure.
- .It Ic \&T&
- Re-start a table layout, retaining the options of the prior table
- invocation.
- See
- .Ic \&TS .
- .It Ic \&ta Op Ar width ... Op Cm T Ar width ...
- Set tab stops.
- Each
- .Ar width
- argument follows the syntax of
- .Sx Scaling Widths .
- If prefixed by a plus sign, it is relative to the previous tab stop.
- The arguments after the
- .Cm T
- marker are used repeatedly as often as needed; for each reuse,
- they are taken relative to the last previously established tab stop.
- When
- .Ic \&ta
- is called without arguments, all tab stops are cleared.
- .It Ic \&tc Op Ar glyph
- Change tab repetition character.
- Currently unsupported.
- .It Ic \&TE
- End a table context.
- See
- .Ic \&TS .
- .It Ic \&ti Oo Cm + Ns | Ns Cm - Oc Ns Ar width
- Break the output line and indent the next output line by
- .Ar width .
- If a sign is specified, the temporary indentation is calculated
- relative to the current indentation; otherwise, it is absolute.
- The argument follows the syntax of
- .Sx Scaling Widths
- and the default scaling unit is
- .Cm m .
- .It Ic \&tkf Ar font minps width1 maxps width2
- Enable track kerning for a font.
- Currently ignored.
- .It Ic \&tl No \& Ap Ar left Ap Ar center Ap Ar right Ap
- Print a title line.
- Currently unsupported.
- .It Ic \&tm Ar string
- Print to standard error output.
- Currently ignored.
- .It Ic \&tm1 Ar string
- Print to standard error output, allowing leading blanks.
- This is a groff extension and currently ignored.
- .It Ic \&tmc Ar string
- Print to standard error output without a trailing newline.
- This is a groff extension and currently ignored.
- .It Ic \&tr Ar glyph glyph ...
- Output character translation.
- The first glyph in each pair is replaced by the second one.
- Character escapes can be used; for example,
- .Pp
- .Dl tr \e(xx\e(yy
- .Pp
- replaces all invocations of \e(xx with \e(yy.
- .It Ic \&track Ar font minps width1 maxps width2
- Static letter space tracking.
- This is a Heirloom extension and currently ignored.
- .It Ic \&transchar Ar char ...
- Define transparent characters for sentence-ending.
- This is a Heirloom extension and currently ignored.
- .It Ic \&trf Ar filename
- Output the contents of a file, disallowing invalid characters.
- This is a groff extension and ignored because insecure.
- .It Ic \&trimat Ar left top width height
- Set the TrimBox page parameter for PDF generation.
- This is a Heirloom extension and currently ignored.
- .It Ic \&trin Ar glyph glyph ...
- Output character translation, ignored by
- .Ic \&asciify .
- Currently unsupported.
- .It Ic \&trnt Ar glyph glyph ...
- Output character translation, ignored by \e!.
- Currently unsupported.
- .It Ic \&troff
- Force troff mode.
- This is a groff extension and currently ignored.
- .It Ic \&TS
- Begin a table, which formats input in aligned rows and columns.
- See
- .Xr tbl 7
- for a description of the tbl language.
- .It Ic \&uf Ar font
- Globally set the underline font.
- Currently ignored.
- .It Ic \&ul Op Ar N
- Underline next
- .Ar N
- input lines.
- Currently ignored.
- .It Ic \&unformat Ar divname
- Unformat spaces and tabs in a diversion.
- Currently unsupported.
- .It Ic \&unwatch Ar macroname
- Disable notification for string or macro.
- This is a Heirloom extension and currently ignored.
- .It Ic \&unwatchn Ar register
- Disable notification for register.
- This is a Heirloom extension and currently ignored.
- .It Ic \&vpt Op Cm 1 | 0
- Enable or disable vertical position traps.
- This is a groff extension and currently ignored.
- .It Ic \&vs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
- Change vertical spacing.
- Currently ignored.
- .It Ic \&warn Ar flags
- Set warning level.
- Currently ignored.
- .It Ic \&warnscale Ar si
- Set the scaling indicator used in warnings.
- This is a groff extension and currently ignored.
- .It Ic \&watch Ar macroname
- Notify on change of string or macro.
- This is a Heirloom extension and currently ignored.
- .It Ic \&watchlength Ar maxlength
- On change, report the contents of macros and strings
- up to the specified length.
- This is a Heirloom extension and currently ignored.
- .It Ic \&watchn Ar register
- Notify on change of register.
- This is a Heirloom extension and currently ignored.
- .It Ic \&wh Ar dist Op Ar macroname
- Set a page location trap.
- Currently unsupported.
- .It Ic \&while Ar condition body
- Repeated execution while a
- .Ar condition
- is true, with syntax similar to
- .Ic \&if .
- Currently implemented with two restrictions: cannot nest,
- and each loop must start and end in the same scope.
- .It Ic \&write Oo \(dq Oc Ns Ar string
- Write to an open file.
- Ignored because insecure.
- .It Ic \&writec Oo \(dq Oc Ns Ar string
- Write to an open file without appending a newline.
- Ignored because insecure.
- .It Ic \&writem Ar macroname
- Write macro or string to an open file.
- Ignored because insecure.
- .It Ic \&xflag Ar level
- Set the extension level.
- This is a Heirloom extension and currently ignored.
- .El
- .Ss Numerical expressions
- The
- .Ic \&nr ,
- .Ic \&if ,
- and
- .Ic \&ie
- requests accept integer numerical expressions as arguments.
- These are always evaluated using the C
- .Vt int
- type; integer overflow works the same way as in the C language.
- Numbers consist of an arbitrary number of digits
- .Sq 0
- to
- .Sq 9
- prefixed by an optional sign
- .Sq +
- or
- .Sq - .
- Each number may be followed by one optional scaling unit described below
- .Sx Scaling Widths .
- The following equations hold:
- .Bd -literal -offset indent
- 1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240
- 254c = 100i = 24000u = 24000
- 1f = 65536u = 65536
- .Ed
- .Pp
- The following binary operators are implemented.
- Unless otherwise stated, they behave as in the C language:
- .Pp
- .Bl -tag -width 2n -compact
- .It Ic +
- addition
- .It Ic -
- subtraction
- .It Ic *
- multiplication
- .It Ic /
- division
- .It Ic %
- remainder of division
- .It Ic <
- less than
- .It Ic >
- greater than
- .It Ic ==
- equal to
- .It Ic =
- equal to, same effect as
- .Ic ==
- (this differs from C)
- .It Ic <=
- less than or equal to
- .It Ic >=
- greater than or equal to
- .It Ic <>
- not equal to (corresponds to C
- .Ic != ;
- this one is of limited portability, it is supported by Heirloom roff,
- but not by groff)
- .It Ic &
- logical and (corresponds to C
- .Ic && )
- .It Ic \&:
- logical or (corresponds to C
- .Ic || )
- .It Ic <?
- minimum (not available in C)
- .It Ic >?
- maximum (not available in C)
- .El
- .Pp
- There is no concept of precedence; evaluation proceeds from left to right,
- except when subexpressions are enclosed in parentheses.
- Inside parentheses, whitespace is ignored.
- .Sh ESCAPE SEQUENCE REFERENCE
- The
- .Xr mandoc 1
- .Nm
- parser recognises the following escape sequences.
- In
- .Xr mdoc 7
- and
- .Xr man 7
- documents, using escape sequences is discouraged except for those
- described in the
- .Sx LANGUAGE SYNTAX
- section above.
- .Pp
- A backslash followed by any character not listed here
- simply prints that character itself.
- .Bl -tag -width Ds
- .It Ic \e<newline>
- A backslash at the end of an input line can be used to continue the
- logical input line on the next physical input line, joining the text
- on both lines together as if it were on a single input line.
- .It Ic \e<space>
- The escape sequence backslash-space
- .Pq Sq \e\ \&
- is an unpaddable space-sized non-breaking space character; see
- .Sx Whitespace
- and
- .Xr mandoc_char 7 .
- .It Ic \e!
- Embed text up to and including the end of the input line into the
- current diversion or into intermediate output without interpreting
- requests, macros, and escapes.
- Currently unsupported.
- .It Ic \e\(dq
- The rest of the input line is treated as
- .Sx Comments .
- .It Ic \e#
- Line continuation with comment.
- Discard the rest of the physical input line and continue the logical
- input line on the next physical input line, joining the text on
- both lines together as if it were on a single input line.
- This is a groff extension.
- .It Ic \e$ Ns Ar arg
- Macro argument expansion, see
- .Ic \&de .
- .It Ic \e%
- Hyphenation allowed at this point of the word; ignored by
- .Xr mandoc 1 .
- .It Ic \e&
- Non-printing zero-width character,
- often used for various kinds of escaping; see
- .Sx Whitespace ,
- .Xr mandoc_char 7 ,
- and the
- .Dq MACRO SYNTAX
- and
- .Dq Delimiters
- sections in
- .Xr mdoc 7 .
- .It Ic \e\(aq
- Acute accent special character; use
- .Ic \e(aa
- instead.
- .It Ic \e( Ns Ar cc
- .Sx Special Characters
- with two-letter names, see
- .Xr mandoc_char 7 .
- .It Ic \e)
- Zero-width space transparent to end-of-sentence detection;
- ignored by
- .Xr mandoc 1 .
- .It Ic \e*[ Ns Ar name Ns Ic \&]
- Interpolate the string with the
- .Ar name .
- For short names, there are variants
- .Ic \e* Ns Ar c
- and
- .Ic \e*( Ns Ar cc .
- .Pp
- One string is predefined on the
- .Nm
- language level:
- .Ic \e*(.T
- expands to the name of the output device,
- for example ascii, utf8, ps, pdf, html, or markdown.
- .Pp
- Macro sets traditionally predefine additional strings which are not
- portable and differ across implementations.
- Those supported by
- .Xr mandoc 1
- are listed in
- .Xr mandoc_char 7 .
- .Pp
- Strings can be defined, changed, and deleted with the
- .Ic \&ds ,
- .Ic \&as ,
- and
- .Ic \&rm
- requests.
- .It Ic \e,
- Left italic correction (groff extension); ignored by
- .Xr mandoc 1 .
- .It Ic \e-
- Special character
- .Dq mathematical minus sign ;
- see
- .Xr mandoc_char 7
- for details.
- .It Ic \e/
- Right italic correction (groff extension); ignored by
- .Xr mandoc 1 .
- .It Ic \e:
- Breaking the line is allowed at this point of the word
- without inserting a hyphen.
- .It Ic \e?
- Embed the text up to the next
- .Ic \e?
- into the current diversion without interpreting requests, macros,
- and escapes.
- This is a groff extension and currently unsupported.
- .It Ic \e[ Ns Ar name Ns Ic \&]
- .Sx Special Characters
- with names of arbitrary length, see
- .Xr mandoc_char 7 .
- .It Ic \e^
- One-twelfth em half-narrow space character, effectively zero-width in
- .Xr mandoc 1 .
- .It Ic \e_
- Underline special character; use
- .Ic \e(ul
- instead.
- .It Ic \e`
- Grave accent special character; use
- .Ic \e(ga
- instead.
- .It Ic \e{
- Begin conditional input; see
- .Ic \&if .
- .It Ic \e\(ba
- One-sixth em narrow space character, effectively zero-width in
- .Xr mandoc 1 .
- .It Ic \e}
- End conditional input; see
- .Ic \&if .
- .It Ic \e~
- Paddable non-breaking space character.
- .It Ic \e0
- Digit width space character.
- .It Ic \eA\(aq Ns Ar string Ns Ic \(aq
- Anchor definition; ignored by
- .Xr mandoc 1 .
- .It Ic \ea
- Leader character; ignored by
- .Xr mandoc 1 .
- .It Ic \eB\(aq Ns Ar string Ns Ic \(aq
- Interpolate
- .Sq 1
- if
- .Ar string
- conforms to the syntax of
- .Sx Numerical expressions
- explained above or
- .Sq 0
- otherwise.
- .It Ic \eb\(aq Ns Ar string Ns Ic \(aq
- Bracket building function; ignored by
- .Xr mandoc 1 .
- .It Ic \eC\(aq Ns Ar name Ns Ic \(aq
- .Sx Special Characters
- with names of arbitrary length.
- .It Ic \ec
- When encountered at the end of an input text line,
- the next input text line is considered to continue that line,
- even if there are request or macro lines in between.
- No whitespace is inserted.
- .It Ic \eD\(aq Ns Ar string Ns Ic \(aq
- Draw graphics function; ignored by
- .Xr mandoc 1 .
- .It Ic \ed
- Move down by half a line; ignored by
- .Xr mandoc 1 .
- .It Ic \eE
- Escape character intended to not be interpreted in copy mode.
- In
- .Xr mandoc 1 ,
- it currently does the same as
- .Ic \e
- itself.
- .It Ic \ee
- Backslash special character.
- .It Ic \eF[ Ns Ar name Ns Ic \&]
- Switch font family (groff extension); ignored by
- .Xr mandoc 1 .
- For short names, there are variants
- .Ic \eF Ns Ar c
- and
- .Ic \eF( Ns Ar cc .
- .It Ic \ef[ Ns Ar name Ns Ic \&]
- Switch to the font
- .Ar name ,
- see
- .Sx Font Selection .
- For short names, there are variants
- .Ic \ef Ns Ar c
- and
- .Ic \ef( Ns Ar cc .
- An empty name
- .Ic \ef[]
- defaults to
- .Ic \efP .
- .It Ic \eg[ Ns Ar name Ns Ic \&]
- Interpolate the format of a number register; ignored by
- .Xr mandoc 1 .
- For short names, there are variants
- .Ic \eg Ns Ar c
- and
- .Ic \eg( Ns Ar cc .
- .It Ic \eH\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq
- Set the height of the current font; ignored by
- .Xr mandoc 1 .
- .It Ic \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns Ic \(aq
- Horizontal motion.
- If the vertical bar is given, the motion is relative to the current
- indentation.
- Otherwise, it is relative to the current position.
- The default scaling unit is
- .Cm m .
- .It Ic \ek[ Ns Ar name Ns Ic \&]
- Mark horizontal input place in register; ignored by
- .Xr mandoc 1 .
- For short names, there are variants
- .Ic \ek Ns Ar c
- and
- .Ic \ek( Ns Ar cc .
- .It Ic \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns Ic \(aq
- Vertical line drawing function; ignored by
- .Xr mandoc 1 .
- .It Ic \el\(aq Ns Ar width Ns Oo Ar c Oc Ns Ic \(aq
- Draw a horizontal line of
- .Ar width
- using the glyph
- .Ar c .
- .It Ic \eM[ Ns Ar name Ns Ic \&]
- Set fill (background) color (groff extension); ignored by
- .Xr mandoc 1 .
- For short names, there are variants
- .Ic \eM Ns Ar c
- and
- .Ic \eM( Ns Ar cc .
- .It Ic \em[ Ns Ar name Ns Ic \&]
- Set glyph drawing color (groff extension); ignored by
- .Xr mandoc 1 .
- For short names, there are variants
- .Ic \em Ns Ar c
- and
- .Ic \em( Ns Ar cc .
- .It Ic \eN\(aq Ns Ar number Ns Ic \(aq
- Character
- .Ar number
- on the current font.
- .It Ic \en Ns Oo +|- Oc Ns Ic \&[ Ns Ar name Ns Ic \&]
- Interpolate the number register
- .Ar name .
- For short names, there are variants
- .Ic \en Ns Ar c
- and
- .Ic \en( Ns Ar cc .
- If the optional sign is specified,
- the register is first incremented or decremented by the
- .Ar stepsize
- that was specified in the relevant
- .Ic \&nr
- request, and the changed value is interpolated.
- .It Ic \eO Ns Ar digit , Ic \eO[5 Ns arguments Ns Ic \&]
- Suppress output.
- This is a groff extension and currently unsupported.
- With an argument of
- .Ic 1 , 2 , 3 ,
- or
- .Ic 4 ,
- it is ignored.
- .It Ic \eo\(aq Ns Ar string Ns Ic \(aq
- Overstrike, writing all the characters contained in the
- .Ar string
- to the same output position.
- In terminal and HTML output modes,
- only the last one of the characters is visible.
- .It Ic \ep
- Break the output line at the end of the current word.
- .It Ic \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns Ic \(aq
- Set number register; ignored by
- .Xr mandoc 1 .
- .It Ic \er
- Move up by one line; ignored by
- .Xr mandoc 1 .
- .It Ic \eS\(aq Ns Ar number Ns Ic \(aq
- Slant output; ignored by
- .Xr mandoc 1 .
- .It Ic \es\(aq Ns Oo +|- Oc Ns Ar number Ns Ic \(aq
- Change point size; ignored by
- .Xr mandoc 1 .
- Alternative forms
- .Ic \es Ns Oo +|- Oc Ns Ar n ,
- .Ic \es Ns Oo +|- Oc Ns Ic \(aq Ns Ar number Ns Ic \(aq ,
- .Ic \es[ Ns Oo +|- Oc Ns Ar number Ns Ic \&] ,
- and
- .Ic \es Ns Oo +|- Oc Ns Ic \&[ Ns Ar number Ns Ic \&]
- are also parsed and ignored.
- .It Ic \et
- Horizontal tab; ignored by
- .Xr mandoc 1 .
- .It Ic \eu
- Move up by half a line; ignored by
- .Xr mandoc 1 .
- .It Ic \eV[ Ns Ar name Ns Ic \&]
- Interpolate an environment variable; ignored by
- .Xr mandoc 1 .
- For short names, there are variants
- .Ic \eV Ns Ar c
- and
- .Ic \eV( Ns Ar cc .
- .It Ic \ev\(aq Ns Ar number Ns Ic \(aq
- Vertical motion; ignored by
- .Xr mandoc 1 .
- .It Ic \ew\(aq Ns Ar string Ns Ic \(aq
- Interpolate the width of the
- .Ar string .
- The
- .Xr mandoc 1
- implementation assumes that after expansion of user-defined strings, the
- .Ar string
- only contains normal characters, no escape sequences, and that each
- character has a width of 24 basic units.
- .It Ic \eX\(aq Ns Ar string Ns Ic \(aq
- Output
- .Ar string
- as device control function; ignored in nroff mode and by
- .Xr mandoc 1 .
- .It Ic \ex\(aq Ns Ar number Ns Ic \(aq
- Extra line space function; ignored by
- .Xr mandoc 1 .
- .It Ic \eY[ Ns Ar name Ns Ic \&]
- Output a string as a device control function; ignored in nroff mode and by
- .Xr mandoc 1 .
- For short names, there are variants
- .Ic \eY Ns Ar c
- and
- .Ic \eY( Ns Ar cc .
- .It Ic \eZ\(aq Ns Ar string Ns Ic \(aq
- .Ar string
- with zero width and height; ignored by
- .Xr mandoc 1 .
- .It Ic \ez
- Output the next character without advancing the cursor position.
- .El
- .Sh COMPATIBILITY
- The
- .Xr mandoc 1
- implementation of the
- .Nm
- language is incomplete.
- Major unimplemented features include:
- .Pp
- .Bl -dash -compact
- .It
- For security reasons,
- .Xr mandoc 1
- never reads or writes external files except via
- .Ic \&so
- requests with safe relative paths.
- .It
- There is no automatic hyphenation, no adjustment to the right margin,
- and very limited support for centering; the output is always set flush-left.
- .It
- Support for setting tabulator and leader characters is missing,
- and support for manually changing indentation is limited.
- .It
- The
- .Sq u
- scaling unit is the default terminal unit.
- In traditional troff systems, this unit changes depending on the
- output media.
- .It
- Width measurements are implemented in a crude way
- and often yield wrong results.
- Support for explicit movement requests and escapes is limited.
- .It
- There is no concept of output pages, no support for floats,
- graphics drawing, and picture inclusion;
- terminal output is always continuous.
- .It
- Requests regarding color, font families, font sizes,
- and glyph manipulation are ignored.
- Font support is very limited.
- Kerning is not implemented, and no ligatures are produced.
- .It
- The
- .Qq \(aq
- macro control character does not suppress output line breaks.
- .It
- Diversions and environments are not implemented,
- and support for traps is very incomplete.
- .It
- Use of macros is not supported inside
- .Xr tbl 7
- code.
- .El
- .Pp
- The special semantics of the
- .Cm nS
- number register is an idiosyncrasy of
- .Ox
- manuals and not supported by other
- .Xr mdoc 7
- implementations.
- .Sh SEE ALSO
- .Xr mandoc 1 ,
- .Xr eqn 7 ,
- .Xr man 7 ,
- .Xr mandoc_char 7 ,
- .Xr mdoc 7 ,
- .Xr tbl 7
- .Rs
- .%A Joseph F. Ossanna
- .%A Brian W. Kernighan
- .%I AT&T Bell Laboratories
- .%T Troff User's Manual
- .%R Computing Science Technical Report
- .%N 54
- .%C Murray Hill, New Jersey
- .%D 1976 and 1992
- .%U http://www.kohala.com/start/troff/cstr54.ps
- .Re
- .Rs
- .%A Joseph F. Ossanna
- .%A Brian W. Kernighan
- .%A Gunnar Ritter
- .%T Heirloom Documentation Tools Nroff/Troff User's Manual
- .%D September 17, 2007
- .%U http://heirloom.sourceforge.net/doctools/troff.pdf
- .Re
- .Sh HISTORY
- The RUNOFF typesetting system, whose input forms the basis for
- .Nm ,
- was written in MAD and FAP for the CTSS operating system by Jerome E.
- Saltzer in 1964.
- Doug McIlroy rewrote it in BCPL in 1969, renaming it
- .Nm .
- Dennis M. Ritchie rewrote McIlroy's
- .Nm
- in PDP-11 assembly for
- .At v1 ,
- Joseph F. Ossanna improved roff and renamed it nroff
- for
- .At v2 ,
- then ported nroff to C as troff, which Brian W. Kernighan released with
- .At v7 .
- In 1989, James Clark re-implemented troff in C++, naming it groff.
- .Sh AUTHORS
- .An -nosplit
- This
- .Nm
- reference was written by
- .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
- and
- .An Ingo Schwarze Aq Mt schwarze@openbsd.org .