diff options
Diffstat (limited to 'usr/src/man/man5/mandoc_roff.5')
| -rw-r--r-- | usr/src/man/man5/mandoc_roff.5 | 2342 |
1 files changed, 0 insertions, 2342 deletions
diff --git a/usr/src/man/man5/mandoc_roff.5 b/usr/src/man/man5/mandoc_roff.5 deleted file mode 100644 index 17e9d2e09c..0000000000 --- a/usr/src/man/man5/mandoc_roff.5 +++ /dev/null @@ -1,2342 +0,0 @@ -.\" $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 5 -.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 5 -and -.Xr man 5 -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 5 -or -.Xr man 5 -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 5 -for a complete list. -.Ss Font Selection -In -.Xr mdoc 5 -and -.Xr man 5 -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 5 -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 5 -.It Li \&.HP 2i -two-inch tagged list indentation in -.Xr man 5 -.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 5 -and -.Xr man 5 -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 5 -or -.Xr mdoc 5 -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 5 -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 5 -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 5 -.Ic \&Sh -macro and by the -.Xr man 5 -.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 5 . -Ignored in -.Xr mdoc 5 . -.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 5 -.Ic \&Bd Fl unfilled -and -.Ic \&Bd Fl literal -macros and by the -.Xr man 5 -.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 5 -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 5 -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 5 -and -.Xr man 5 -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 5 -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 5 -and -.Xr man 5 -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 5 . -.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 5 , -and the -.Dq MACRO SYNTAX -and -.Dq Delimiters -sections in -.Xr mdoc 5 . -.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 5 . -.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 5 . -.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 5 -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 5 . -.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 -Print -.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 5 -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 5 -implementations. -.Sh SEE ALSO -.Xr mandoc 1 , -.Xr eqn 5 , -.Xr man 5 , -.Xr mandoc_char 5 , -.Xr mdoc 5 , -.Xr tbl 5 -.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 . |