=================================================================== RCS file: /cvs/mandoc/roff.7,v retrieving revision 1.3 retrieving revision 1.74 diff -u -p -r1.3 -r1.74 --- mandoc/roff.7 2010/05/17 00:37:26 1.3 +++ mandoc/roff.7 2015/08/29 22:40:05 1.74 @@ -1,6 +1,7 @@ -.\" $Id: roff.7,v 1.3 2010/05/17 00:37:26 kristaps Exp $ +.\" $Id: roff.7,v 1.74 2015/08/29 22:40:05 schwarze Exp $ .\" -.\" Copyright (c) 2010 Kristaps Dzonsons +.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons +.\" Copyright (c) 2010, 2011, 2013-2015 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,138 +15,1104 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: May 17 2010 $ +.Dd $Mdocdate: August 29 2015 $ .Dt ROFF 7 .Os .Sh NAME .Nm roff -.Nd roff language reference +.Nd roff language reference for mandoc .Sh DESCRIPTION The .Nm roff -language is a general-purpose text-formatting language. The purpose of -this document is to consistently describe those language constructs -accepted by the +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. It is a work in progress. -.Pp -An +utility supports a tiny subset of .Nm -document follows simple rules: lines beginning with the control -characters -.Sq \. +requests and escapes. +Only these requests and escapes supported by +.Xr mandoc 1 +are documented in the present manual, +together with the basic language syntax shared by +.Nm , +.Xr mdoc 7 , +and +.Xr man 7 . +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 -.Sq \(aq -are parsed for macros. Other lines are interpreted within the scope of -prior macros: -.Bd -literal -offset indent -\&.xx Macro lines change control state. -Other lines are interpreted within the current state. -.Ed +.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. All -manuals must have -.Ux -line terminators. -.Sh MACRO SYNTAX -Macros are arbitrary in length and begin with a control character , -.Sq \. +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 , +.Sx Special Characters , +.Sx Predefined Strings , +and +user-defined strings defined using the +.Sx ds +request. +For a 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 Text Decoration +Terms may be text-decorated using the +.Sq \ef +escape followed by an indicator: B (bold), I (italic), R (regular), or P +(revert to previous mode). +A numerical representation 3, 2, or 1 (bold, italic, and regular, +respectively) may be used instead. +The indicator or numerical representative may be preceded by C +(constant-width), which is ignored. +.Pp +The two-character indicator +.Sq BI +requests a font that is both bold and italic. +It may not be portable to old roff implementations. +.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 +.Pp +Text decoration is +.Em not +recommended for +.Xr mdoc 7 , +which encourages semantic annotation. +.Ss Predefined Strings +Predefined strings, like +.Sx Special Characters , +mark special output glyphs. +Predefined strings are escaped with the slash-asterisk, +.Sq \e* : +single-character +.Sq \e*X , +two-character +.Sq \e*(XX , +and N-character +.Sq \e*[N] . +.Pp +Examples: +.Bl -tag -width Ds -offset indent -compact +.It Li \e*(Am +Two-letter ampersand predefined string. +.It Li \e*q +One-letter double-quote predefined string. +.El +.Pp +Predefined strings are not recommended for use, +as they differ across implementations. +Those supported by +.Xr mandoc 1 +are listed in +.Xr mandoc_char 7 . +Manuals using these predefined strings are almost certainly not portable. +.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 blank 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. +Negative numbers, while accepted, are truncated to zero. +.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 \(aq , -at the beginning of the line. -An arbitrary amount of whitespace may sit between the control character -and the macro name. -Thus, the following are equivalent: +.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 +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 \&. +.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 -\&.if -\&.\ \ \ \&if +\&.ig end +\&.ig end +\&. ig end .Ed -.Sh REFERENCE -This section is a canonical reference of all macros, arranged -alphabetically. +.Sh MACRO SYNTAX +Macros are provided by the +.Xr mdoc 7 +and +.Xr man 7 +languages and can be defined by the +.Sx \&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. +.Ss \&ab +Abort processing. +Currently unsupported. +.Ss \&ad +Set line adjustment mode. +It takes one argument to select normal, left, right, +or center adjustment for subsequent text. +Currently ignored. +.Ss \&af +Assign an output format to a number register. +Currently ignored. +.Ss \&aln +Create an alias for a number register. +Currently unsupported. +.Ss \&als +Create an alias for a request, string, macro, or diversion. +Currently unsupported. .Ss \&am -The syntax of this macro is the same as that of -.Sx \&ig , -except that a leading argument must be specified. -It is ignored, as are its children. -.Ss \&ami -The syntax of this macro is the same as that of -.Sx \&ig , -except that a leading argument must be specified. -It is ignored, as are its children. +Append to a macro definition. +The syntax of this request is the same as that of +.Sx \&de . .Ss \&am1 -The syntax of this macro is the same as that of -.Sx \&ig , -except that a leading argument must be specified. -It is ignored, as are its children. +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 +.Sx \&de1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&am . +.Ss \&ami +Append to a macro definition, specifying the macro name indirectly +(groff extension). +The syntax of this request is the same as that of +.Sx \&dei . +.Ss \&ami1 +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 +.Sx \&dei1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&ami . +.Ss \&as +Append to a user-defined string. +The syntax of this request is the same as that of +.Sx \&ds . +If a user-defined string with the specified name does not yet exist, +it is set to the empty string before appending. +.Ss \&as1 +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 +.Sx \&ds1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&as . +.Ss \&asciify +Fully unformat a diversion. +Currently unsupported. +.Ss \&backtrace +Print a backtrace of the input stack. +This is a groff extension and currently ignored. +.Ss \&bd +Artificially embolden by repeated printing with small shifts. +Currently ignored. +.Ss \&bleedat +Set the BleedBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.Ss \&blm +Set a blank line trap. +Currently unsupported. +.Ss \&box +Begin a diversion without including a partially filled line. +Currently unsupported. +.Ss \&boxa +Add to a diversion without including a partially filled line. +Currently unsupported. +.Ss \&bp +Begin new page. +Currently ignored. +.Ss \&BP +Define a frame and place a picture in it. +This is a Heirloom extension and currently unsupported. +.Ss \&br +Break the output line. +See +.Xr man 7 +and +.Xr mdoc 7 . +.Ss \&break +Break out of a +.Sx \&while +loop. +Currently unsupported. +.Ss \&breakchar +Optional line break characters. +This is a Heirloom extension and currently ignored. +.Ss \&brnl +Break output line after next N input lines. +This is a Heirloom extension and currently ignored. +.Ss \&brp +Break and spread output line. +Currently, this is implemented as an alias for +.Sx \&br . +.Ss \&brpnl +Break and spread output line after next N input lines. +This is a Heirloom extension and currently ignored. +.Ss \&c2 +Change the no-break control character. +Currently unsupported. +.Ss \&cc +Change the control character. +Its syntax is as follows: +.Bd -literal -offset indent +.Pf . Cm \&cc Op Ar c +.Ed +.Pp +If +.Ar c +is not specified, the control character is reset to +.Sq \&. . +Trailing characters are ignored. +.Ss \&ce +Center some lines. +It takes one integer argument, specifying how many lines to center. +Currently ignored. +.Ss \&cf +Output the contents of a file. +Ignored because insecure. +.Ss \&cflags +Set character flags. +This is a groff extension and currently ignored. +.Ss \&ch +Change a trap location. +Currently ignored. +.Ss \&char +Define a new glyph. +Currently unsupported. +.Ss \&chop +Remove the last character from a macro, string, or diversion. +Currently unsupported. +.Ss \&class +Define a character class. +This is a groff extension and currently ignored. +.Ss \&close +Close an open file. +Ignored because insecure. +.Ss \&CL +Print text in color. +This is a Heirloom extension and currently unsupported. +.Ss \&color +Activate or deactivate colors. +This is a groff extension and currently ignored. +.Ss \&composite +Define a name component for composite glyph names. +This is a groff extension and currently unsupported. +.Ss \&continue +Immediately start the next iteration of a +.Sx \&while +loop. +Currently unsupported. +.Ss \&cp +Switch +.Nm +compatibility mode on or off. +Currently ignored. +.Ss \&cropat +Set the CropBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.Ss \&cs +Constant character spacing mode. +Currently ignored. +.Ss \&cu +Underline including whitespace. +Currently ignored. +.Ss \&da +Append to a diversion. +Currently unsupported. +.Ss \&dch +Change a trap location in the current diversion. +This is a Heirloom extension and currently unsupported. .Ss \&de -The syntax of this macro is the same as that of -.Sx \&ig , -except that a leading argument must be specified. -It is ignored, as are its children. -.Ss \&dei -The syntax of this macro is the same as that of -.Sx \&ig , -except that a leading argument must be specified. -It is ignored, as are its children. +Define a +.Nm +macro. +Its syntax can be either +.Bd -literal -offset indent +.Pf . Cm \&de Ar name +.Ar macro definition +\&.. +.Ed +.Pp +or +.Bd -literal -offset indent +.Pf . Cm \&de Ar name Ar end +.Ar macro definition +.Pf . Ar end +.Ed +.Pp +Both forms define or redefine the macro +.Ar name +to represent the +.Ar macro 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 end +macro works in the same way as for +.Sx \&ig ; +namely, the call to +.Sq Pf . Ar end +first ends the +.Ar macro 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 name 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 macro 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 blank characters. +.Pp +Since macros and user-defined strings share a common string table, +defining a macro +.Ar name +clobbers the user-defined string +.Ar name , +and the +.Ar macro definition +can also be printed using the +.Sq \e* +string interpolation syntax described below +.Sx 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. .Ss \&de1 -The syntax of this macro is the same as that of -.Sx \&ig , -except that a leading argument must be specified. -It is ignored, as are its children. +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 +.Sx \&de . +.Ss \&defcolor +Define a color name. +This is a groff extension and currently ignored. +.Ss \&dei +Define a +.Nm +macro, specifying the macro name indirectly (groff extension). +The syntax of this request is the same as that of +.Sx \&de . +The request +.Pp +.D1 Pf . Cm \&dei Ar name Op Ar end +.Pp +has the same effect as: +.Pp +.D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end +.Ss \&dei1 +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 +.Sx \&dei . +.Ss \&device +This request only makes sense with the groff-specific intermediate +output format and is unsupported. +.Ss \&devicem +This request only makes sense with the groff-specific intermediate +output format and is unsupported. +.Ss \&di +Begin a diversion. +Currently unsupported. +.Ss \&do +Execute +.Nm +request or macro line with compatibility mode disabled. +Currently unsupported. +.Ss \&ds +Define a user-defined string. +Its syntax is as follows: +.Pp +.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string +.Pp +The +.Ar name +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 name +for a +.Ar name +of arbitrary length, or \e*(NN or \e*N if the length of +.Ar name +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 name +clobbers the macro +.Ar name , +and the +.Ar name +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 +.Cm SH +macro when used in a +.Xr man 7 +document. +Such abuse is of course strongly discouraged. +.Ss \&ds1 +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 +.Sx \&ds . +.Ss \&dwh +Set a location trap in the current diversion. +This is a Heirloom extension and currently unsupported. +.Ss \&dt +Set a trap within a diversion. +Currently unsupported. +.Ss \&ec +Change the escape character. +Currently unsupported. +.Ss \&ecs +Restore the escape character. +Currently unsupported. +.Ss \&ecr +Save the escape character. +Currently unsupported. +.Ss \&el +The +.Qq else +half of an if/else conditional. +Pops a result off the stack of conditional evaluations pushed by +.Sx \&ie +and uses it as its conditional. +If no stack entries are present (e.g., due to no prior +.Sx \&ie +calls) +then false is assumed. +The syntax of this request is similar to +.Sx \&if +except that the conditional is missing. +.Ss \&em +Set a trap at the end of input. +Currently unsupported. +.Ss \&EN +End an equation block. +See +.Sx \&EQ . +.Ss \&eo +Disable the escape mechanism completely. +Currently unsupported. +.Ss \&EP +End a picture started by +.Sx \&BP . +This is a Heirloom extension and currently unsupported. +.Ss \&EQ +Begin an equation block. +See +.Xr eqn 7 +for a description of the equation language. +.Ss \&errprint +Print a string like an error message. +This is a Heirloom extension and currently ignored. +.Ss \&ev +Switch to another environment. +Currently unsupported. +.Ss \&evc +Copy an environment into the current environment. +Currently unsupported. +.Ss \&ex +Abort processing and exit. +Currently unsupported. +.Ss \&fallback +Select the fallback sequence for a font. +This is a Heirloom extension and currently ignored. +.Ss \&fam +Change the font family. +Takes one argument specifying the font family to be selected. +It is a groff extension and currently ignored. +.Ss \&fc +Define a delimiting and a padding character for fields. +Currently unsupported. +.Ss \&fchar +Define a fallback glyph. +Currently unsupported. +.Ss \&fcolor +Set the fill color for \eD objects. +This is a groff extension and currently ignored. +.Ss \&fdeferlig +Defer ligature building. +This is a Heirloom extension and currently ignored. +.Ss \&feature +Enable or disable an OpenType feature. +This is a Heirloom extension and currently ignored. +.Ss \&fi +Switch to fill mode. +See +.Xr man 7 . +Ignored in +.Xr mdoc 7 . +.Ss \&fkern +Control the use of kerning tables for a font. +This is a Heirloom extension and currently ignored. +.Ss \&fl +Flush output. +Currently ignored. +.Ss \&flig +Define ligatures. +This is a Heirloom extension and currently ignored. +.Ss \&fp +Assign font position. +Currently ignored. +.Ss \&fps +Mount a font with a special character map. +This is a Heirloom extension and currently ignored. +.Ss \&fschar +Define a font-specific fallback glyph. +This is a groff extension and currently unsupported. +.Ss \&fspacewidth +Set a font-specific width for the space character. +This is a Heirloom extension and currently ignored. +.Ss \&fspecial +Conditionally define a special font. +This is a groff extension and currently ignored. +.Ss \&ft +Change the font. +Its syntax is as follows: +.Pp +.D1 Pf . Cm \&ft Op Ar font +.Pp +The following +.Ar font +arguments are supported: +.Bl -tag -width 4n -offset indent +.It Cm B , BI , 3 , 4 +switches to +.Sy bold +font +.It Cm I , 2 +switches to +.Em underlined +font +.It Cm R , CW , 1 +switches to normal font +.It Cm P No "or no argument" +switches back to the previous font +.El +.Pp +This request takes effect only locally, may be overridden by macros +and escape sequences, and is only supported in +.Xr man 7 +for now. +.Ss \&ftr +Translate font name. +This is a groff extension and currently ignored. +.Ss \&fzoom +Zoom font size. +Currently ignored. +.Ss \&gcolor +Set glyph color. +This is a groff extension and currently ignored. +.Ss \&hc +Set the hyphenation character. +Currently ignored. +.Ss \&hcode +Set hyphenation codes of characters. +Currently ignored. +.Ss \&hidechar +Hide characters in a font. +This is a Heirloom extension and currently ignored. +.Ss \&hla +Set hyphenation language. +This is a groff extension and currently ignored. +.Ss \&hlm +Set maximum number of consecutive hyphenated lines. +Currently ignored. +.Ss \&hpf +Load hyphenation pattern file. +This is a groff extension and currently ignored. +.Ss \&hpfa +Load hyphenation pattern file, appending to the current patterns. +This is a groff extension and currently ignored. +.Ss \&hpfcode +Define mapping values for character codes in hyphenation patterns. +This is a groff extension and currently ignored. +.Ss \&hw +Specify hyphenation points in words. +Currently ignored. +.Ss \&hy +Set automatic hyphenation mode. +Currently ignored. +.Ss \&hylang +Set hyphenation language. +This is a Heirloom extension and currently ignored. +.Ss \&hylen +Minimum word length for hyphenation. +This is a Heirloom extension and currently ignored. +.Ss \&hym +Set hyphenation margin. +This is a groff extension and currently ignored. +.Ss \&hypp +Define hyphenation penalties. +This is a Heirloom extension and currently ignored. +.Ss \&hys +Set hyphenation space. +This is a groff extension and currently ignored. +.Ss \&ie +The +.Qq if +half of an if/else conditional. +The result of the conditional is pushed into a stack used by subsequent +invocations of +.Sx \&el , +which may be separated by any intervening input (or not exist at all). +Its syntax is equivalent to +.Sx \&if . .Ss \&if -Begins a conditional that always evaluates to false. +Begins a conditional. +This request has the following syntax: +.Bd -literal -offset indent +\&.if COND BODY +.Ed +.Bd -literal -offset indent +\&.if COND \e{BODY +BODY...\e} +.Ed +.Bd -literal -offset indent +\&.if COND \e{\e +BODY... +\&.\e} +.Ed +.Pp +COND is a conditional statement. +Currently, +.Xr mandoc 1 +supports the following subset of roff conditionals: +.Bl -bullet +.It +If +.Sq \&! +is prefixed to COND, the condition is logically inverted. +.It +If the first character of COND is +.Sq n +.Pq nroff mode +or +.Sq o +.Pq odd page , +COND evaluates to true. +.It +If the first character of COND is +.Sq c +.Pq character available , +.Sq d +.Pq string defined , +.Sq e +.Pq even page , +.Sq t +.Pq troff mode , +or +.Sq v +.Pq vroff mode , +COND evaluates to false. +.It +If the first character of COND is +.Sq r , +it evalutes to true if the rest of COND is the name of an existing +number register; otherwise, it evaluates to false. +.It +If COND 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 COND is regarded as a delimiter +and COND 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 COND 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 \e .ig +.D1 \&.if t .ig .Pp will discard the .Sq \&.ig , which may lead to interesting results, but .Pp -.D1 \&.if t \e .if t \e{\e +.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. -This macro has the following syntax: .Pp -.Bd -literal -offset indent -compact -\&.if COND \e{\e -BODY... -\&.\e} -.Ed -.Bd -literal -offset indent -compact -\&.if COND \e{ BODY -BODY... \e} -.Ed -.Bd -literal -offset indent -compact -\&.if COND \e{ BODY -BODY... -\&.\e} -.Ed -.Bd -literal -offset indent -compact -\&.if COND \e -BODY -.Ed -.Pp -COND is a conditional (for the time being, this always evaluates to -false). -.Pp If the BODY section is begun by an escaped brace .Sq \e{ , -scope continues until a closing-brace macro -.Sq \.\e} . -If the BODY is not enclosed in braces, scope continues until the next -macro or word. +scope continues until the end of the input line containing the +matching closing-brace escape sequence +.Sq \e} . +If the BODY is not enclosed in braces, scope continues until +the end of the line. If the COND is followed by a BODY on the same line, whether after a -brace or not, then macros +brace or not, then requests and macros .Em must begin with a control character. It is generally more intuitive, in this case, to write @@ -156,81 +1123,1032 @@ bar \&.\e} .Ed .Pp -than having the macro follow as +than having the request or macro follow as .Pp .D1 \&.if COND \e{ .foo .Pp The scope of a conditional is always parsed, but only executed if the conditional evaluates to true. .Pp -Note that text subsequent a -.Sq \&.\e} -macro is discarded. -Furthermore, if an explicit closing sequence +Note that the .Sq \e} -is specified in a free-form line, the entire line is accepted within the -scope of the prior macro, not only the text preceding the close. +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. .Ss \&ig Ignore input. -Accepts the following syntax: -.Pp -.Bd -literal -offset indent -compact -\&.ig -BODY... +Its syntax can be either +.Bd -literal -offset indent +.Pf . Cm \&ig +.Ar ignored text \&.. .Ed -.Bd -literal -offset indent -compact -\&.ig END -BODY... -\&.END +.Pp +or +.Bd -literal -offset indent +.Pf . Cm \&ig Ar end +.Ar ignored text +.Pf . Ar end .Ed .Pp In the first case, input is ignored until a .Sq \&.. -macro is encountered on its own line. -In the second case, input is ignored until a -.Sq \&.END -is encountered. -Text subsequent the -.Sq \&.END -or -.Sq \&.. -is discarded. -.Pp -Do not use the escape +request is encountered on its own line. +In the second case, input is ignored until the specified +.Sq Pf . Ar end +macro is encountered. +Do not use the escape character .Sq \e -anywhere in the definition of END. -It causes very strange behaviour. -Furthermore, if you redefine a -.Nm -macro, such as +anywhere in the definition of +.Ar end ; +it would cause very strange behaviour. .Pp +When the +.Ar end +macro is a roff request or a roff macro, like in +.Pp .D1 \&.ig if .Pp the subsequent invocation of .Sx \&if -will first signify the end of comment, then be invoked as a macro. -This behaviour really shouldn't be counted upon. +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. +.Ss \&in +Change indentation. +See +.Xr man 7 . +Ignored in +.Xr mdoc 7 . +.Ss \&index +Find a substring in a string. +This is a Heirloom extension and currently unsupported. +.Ss \&it +Set an input line trap. +Its syntax is as follows: +.Pp +.D1 Pf . Cm it Ar expression macro +.Pp +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. +.Ss \&itc +Set an input line trap, not counting lines ending with \ec. +Currently unsupported. +.Ss \&IX +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. +.Ss \&kern +Switch kerning on or off. +Currently ignored. +.Ss \&kernafter +Increase kerning after some characters. +This is a Heirloom extension and currently ignored. +.Ss \&kernbefore +Increase kerning before some characters. +This is a Heirloom extension and currently ignored. +.Ss \&kernpair +Add a kerning pair to the kerning table. +This is a Heirloom extension and currently ignored. +.Ss \&lc +Define a leader repetition character. +Currently unsupported. +.Ss \&lc_ctype +Set the +.Dv LC_CTYPE +locale. +This is a Heirloom extension and currently unsupported. +.Ss \&lds +Define a local string. +This is a Heirloom extension and currently unsupported. +.Ss \&length +Count the number of input characters in a user-defined string. +Currently unsupported. +.Ss \&letadj +Dynamic letter spacing and reshaping. +This is a Heirloom extension and currently ignored. +.Ss \&lf +Change the line number for error messages. +Ignored because insecure. +.Ss \&lg +Switch the ligature mechanism on or off. +Currently ignored. +.Ss \&lhang +Hang characters at left margin. +This is a Heirloom extension and currently ignored. +.Ss \&linetabs +Enable or disable line-tabs mode. +This is a groff extension and currently unsupported. +.Ss \&ll +Change the output line length. +Its syntax is as follows: +.Pp +.D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width +.Pp +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. +.Ss \&lnr +Set local number register. +This is a Heirloom extension and currently unsupported. +.Ss \&lnrf +Set local floating-point register. +This is a Heirloom extension and currently unsupported. +.Ss \&lpfx +Set a line prefix. +This is a Heirloom extension and currently unsupported. +.Ss \&ls +Set line spacing. +It takes one integer argument specifying the vertical distance of +subsequent output text lines measured in v units. +Currently ignored. +.Ss \&lsm +Set a leading spaces trap. +This is a groff extension and currently unsupported. +.Ss \< +Set title line length. +Currently ignored. +.Ss \&mc +Print margin character in the right margin. +Currently ignored. +.Ss \&mediasize +Set the device media size. +This is a Heirloom extension and currently ignored. +.Ss \&minss +Set minimum word space. +This is a Heirloom extension and currently ignored. +.Ss \&mk +Mark vertical position. +Currently ignored. +.Ss \&mso +Load a macro file. +Ignored because insecure. +.Ss \&na +Disable adjusting without changing the adjustment mode. +Currently ignored. +.Ss \&ne +Declare the need for the specified minimum vertical space +before the next trap or the bottom of the page. +Currently ignored. +.Ss \&nf +Switch to no-fill mode. +See +.Xr man 7 . +Ignored by +.Xr mdoc 7 . +.Ss \&nh +Turn off automatic hyphenation mode. +Currently ignored. +.Ss \&nhychar +Define hyphenation-inhibiting characters. +This is a Heirloom extension and currently ignored. +.Ss \&nm +Print line numbers. +Currently unsupported. +.Ss \&nn +Temporarily turn off line numbering. +Currently unsupported. +.Ss \&nop +Exexute the rest of the input line as a request or macro line. +Currently unsupported. +.Ss \&nr +Define or change a register. +A register is an arbitrary string value that defines some sort of state, +which influences parsing and/or formatting. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression +.Pp +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 following register +.Ar name +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 +.Cm \&Sh +macro will reset this register. +.El +.Ss \&nrf +Define or change a floating-point register. +This is a Heirloom extension and currently unsupported. +.Ss \&nroff +Force nroff mode. +This is a groff extension and currently ignored. +.Ss \&ns +Turn on no-space mode. +Currently ignored. +.Ss \&nx +Abort processing of the current input file and process another one. +Ignored because insecure. +.Ss \&open +Open a file for writing. +Ignored because insecure. +.Ss \&opena +Open a file for appending. +Ignored because insecure. +.Ss \&os +Output saved vertical space. +Currently ignored. +.Ss \&output +Output directly to intermediate output. +Not supported. +.Ss \&padj +Globally control paragraph-at-once adjustment. +This is a Heirloom extension and currently ignored. +.Ss \&papersize +Set the paper size. +This is a Heirloom extension and currently ignored. +.Ss \&pc +Change the page number character. +Currently ignored. +.Ss \&pev +Print environments. +This is a groff extension and currently ignored. +.Ss \&pi +Pipe output to a shell command. +Ignored because insecure. +.Ss \&PI +Low-level request used by +.Sx \&BP . +This is a Heirloom extension and currently unsupported. +.Ss \&pl +Change page length. +Takes one height argument. +Currently ignored. +.Ss \&pm +Print names and sizes of macros, strings, and diversions. +Currently ignored. +.Ss \&pn +Change page number of the next page. +Currently ignored. +.Ss \&pnr +Print all number registers. +Currently ignored. +.Ss \&po +Set horizontal page offset. +Currently ignored. +.Ss \&ps +Change point size. +Takes one numerical argument. +Currently ignored. +.Ss \&psbb +Retrieve the bounding box of a PostScript file. +Currently unsupported. +.Ss \&pshape +Set a special shape for the current paragraph. +This is a Heirloom extension and currently unsupported. +.Ss \&pso +Include output of a shell command. +Ignored because insecure. +.Ss \&ptr +Print the names and positions of all traps. +This is a groff extension and currently ignored. +.Ss \&pvs +Change post-vertical spacing. +This is a groff extension and currently ignored. +.Ss \&rchar +Remove glyph definitions. +Currently unsupported. +.Ss \&rd +Read from standard input. +Currently ignored. +.Ss \&recursionlimit +Set the maximum stack depth for recursive macros. +This is a Heirloom extension and currently ignored. +.Ss \&return +Exit a macro and return to the caller. +Currently unsupported. +.Ss \&rfschar +Remove font-specific fallback glyph definitions. +Currently unsupported. +.Ss \&rhang +Hang characters at right margin. +This is a Heirloom extension and currently ignored. +.Ss \&rj +Justify unfilled text to the right margin. +Currently ignored. +.Ss \&rm +Remove a request, macro or string. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&rm Ar name +.Ss \&rn +Rename a request, macro, diversion, or string. +Currently unsupported. +.Ss \&rnn +Rename a number register. +Currently unsupported. +.Ss \&rr +Remove a register. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&rr Ar name +.Ss \&rs +End no-space mode. +Currently ignored. +.Ss \&rt +Return to marked vertical position. +Currently ignored. +.Ss \&schar +Define global fallback glyph. +This is a groff extension and currently unsupported. +.Ss \&sentchar +Define sentence-ending characters. +This is a Heirloom extension and currently ignored. +.Ss \&shc +Change the soft hyphen character. +Currently ignored. +.Ss \&shift +Shift macro arguments. +Currently unsupported. +.Ss \&sizes +Define permissible point sizes. +This is a groff extension and currently ignored. +.Ss \&so +Include a source file. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&so Ar file +.Pp +The +.Ar file +will be read and its contents processed as input in place of the +.Sq \&.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 +.Sx \&so +is discouraged. +Use +.Xr ln 1 +instead. +.Ss \&spacewidth +Set the space width from the font metrics file. +This is a Heirloom extension and currently ignored. +.Ss \&special +Define a special font. +This is a groff extension and currently ignored. +.Ss \&spreadwarn +Warn about wide spacing between words. +Currently ignored. +.Ss \&ss +Set space character size. +Currently ignored. +.Ss \&sty +Associate style with a font position. +This is a groff extension and currently ignored. +.Ss \&substring +Replace a user-defined string with a substring. +Currently unsupported. +.Ss \&sv +Save vertical space. +Currently ignored. +.Ss \&sy +Execute shell command. +Ignored because insecure. +.Ss \&T& +Re-start a table layout, retaining the options of the prior table +invocation. +See +.Sx \&TS . +.Ss \&ta +Set tab stops. +Takes an arbitrary number of arguments. +Currently unsupported. +.Ss \&tc +Change tab repetion character. +Currently unsupported. +.Ss \&TE +End a table context. +See +.Sx \&TS . +.Ss \&ti +Temporary indent. +Currently unsupported. +.Ss \&tkf +Enable track kerning for a font. +Currently ignored. +.Ss \&tl +Print a title line. +Currently unsupported. +.Ss \&tm +Print to standard error output. +Currently ignored. +.Ss \&tm1 +Print to standard error output, allowing leading blanks. +This is a groff extension and currently ignored. +.Ss \&tmc +Print to standard error output without a trailing newline. +This is a groff extension and currently ignored. +.Ss \&tr +Output character translation. +Its syntax is as follows: +.Pp +.D1 Pf \. Cm \&tr Ar [ab]+ +.Pp +Pairs of +.Ar ab +characters are replaced +.Ar ( a +for +.Ar b ) . +Replacement (or origin) characters may also be character escapes; thus, +.Pp +.Dl tr \e(xx\e(yy +.Pp +replaces all invocations of \e(xx with \e(yy. +.Ss \&track +Static letter space tracking. +This is a Heirloom extension and currently ignored. +.Ss \&transchar +Define transparent characters for sentence-ending. +This is a Heirloom extension and currently ignored. +.Ss \&trf +Output the contents of a file, disallowing invalid characters. +This is a groff extension and ignored because insecure. +.Ss \&trimat +Set the TrimBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.Ss \&trin +Output character translation, ignored by +.Cm \&asciify . +Currently unsupported. +.Ss \&trnt +Output character translation, ignored by \e!. +Currently unsupported. +.Ss \&troff +Force troff mode. +This is a groff extension and currently ignored. +.Ss \&TS +Begin a table, which formats input in aligned rows and columns. +See +.Xr tbl 7 +for a description of the tbl language. +.Ss \&uf +Globally set the underline font. +Currently ignored. +.Ss \&ul +Underline. +Currently ignored. +.Ss \&unformat +Unformat spaces and tabs in a diversion. +Currently unsupported. +.Ss \&unwatch +Disable notification for string or macro. +This is a Heirloom extension and currently ignored. +.Ss \&unwatchn +Disable notification for register. +This is a Heirloom extension and currently ignored. +.Ss \&vpt +Enable or disable vertical position traps. +This is a groff extension and currently ignored. +.Ss \&vs +Change vertical spacing. +Currently ignored. +.Ss \&warn +Set warning level. +Currently ignored. +.Ss \&warnscale +Set the scaling indicator used in warnings. +This is a groff extension and currently ignored. +.Ss \&watch +Notify on change of string or macro. +This is a Heirloom extension and currently ignored. +.Ss \&watchlength +On change, report the contents of macros and strings +up to the sepcified length. +This is a Heirloom extension and currently ignored. +.Ss \&watchn +Notify on change of register. +This is a Heirloom extension and currently ignored. +.Ss \&wh +Set a page location trap. +Currently unsupported. +.Ss \&while +Repeated execution while a condition is true. +Currently unsupported. +.Ss \&write +Write to an open file. +Ignored because insecure. +.Ss \&writec +Write to an open file without appending a newline. +Ignored because insecure. +.Ss \&writem +Write macro or string to an open file. +Ignored because insecure. +.Ss \&xflag +Set the extension level. +This is a Heirloom extension and currently ignored. +.Ss Numerical expressions +The +.Sx \&nr , +.Sx \&if , +and +.Sx \&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 ? +maximum (not available in C) +.El +.Pp +There is no concept of precendence; evaluation proceeds from left to right, +except when subexpressions are enclosed in parantheses. +Inside parentheses, whitespace is ignored. +.Sh ESCAPE SEQUENCE REFERENCE +The +.Xr mandoc 1 +.Nm +parser recognises the following escape sequences. +Note that the +.Nm +language defines more escape sequences not implemented in +.Xr mandoc 1 . +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. +.Ss \e +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. +.Ss \e +The escape sequence backslash-space +.Pq Sq \e\ \& +is an unpaddable space-sized non-breaking space character; see +.Sx Whitespace . +.Ss \e\(dq +The rest of the input line is treated as +.Sx Comments . +.Ss \e% +Hyphenation allowed at this point of the word; ignored by +.Xr mandoc 1 . +.Ss \e& +Non-printing zero-width character; see +.Sx Whitespace . +.Ss \e\(aq +Acute accent special character; use +.Sq \e(aa +instead. +.Ss \e( Ns Ar cc +.Sx Special Characters +with two-letter names, see +.Xr mandoc_char 7 . +.Ss \e*[ Ns Ar name ] +Interpolate the string with the +.Ar name ; +see +.Sx Predefined Strings +and +.Sx ds . +For short names, there are variants +.No \e* Ns Ar c +and +.No \e*( Ns Ar cc . +.Ss \e, +Left italic correction (groff extension); ignored by +.Xr mandoc 1 . +.Ss \e- +Special character +.Dq mathematical minus sign . +.Ss \e/ +Right italic correction (groff extension); ignored by +.Xr mandoc 1 . +.Ss \e[ Ns Ar name ] +.Sx Special Characters +with names of arbitrary length, see +.Xr mandoc_char 7 . +.Ss \e^ +One-twelfth em half-narrow space character, effectively zero-width in +.Xr mandoc 1 . +.Ss \e` +Grave accent special character; use +.Sq \e(ga +instead. +.Ss \e{ +Begin conditional input; see +.Sx if . +.Ss \e\(ba +One-sixth em narrow space character, effectively zero-width in +.Xr mandoc 1 . +.Ss \e} +End conditional input; see +.Sx if . +.Ss \e~ +Paddable non-breaking space character. +.Ss \e0 +Digit width space character. +.Ss \eA\(aq Ns Ar string Ns \(aq +Anchor definition; ignored by +.Xr mandoc 1 . +.Ss \eB\(aq Ns Ar string Ns \(aq +Interpolate +.Sq 1 +if +.Ar string +conforms to the syntax of +.Sx Numerical expressions +explained above and +.Sq 0 +otherwise. +.Ss \eb\(aq Ns Ar string Ns \(aq +Bracket building function; ignored by +.Xr mandoc 1 . +.Ss \eC\(aq Ns Ar name Ns \(aq +.Sx Special Characters +with names of arbitrary length. +.Ss \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. +.Ss \eD\(aq Ns Ar string Ns \(aq +Draw graphics function; ignored by +.Xr mandoc 1 . +.Ss \ed +Move down by half a line; ignored by +.Xr mandoc 1 . +.Ss \ee +Backslash special character. +.Ss \eF[ Ns Ar name ] +Switch font family (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.No \eF Ns Ar c +and +.No \eF( Ns Ar cc . +.Ss \ef[ Ns Ar name ] +Switch to the font +.Ar name , +see +.Sx Text Decoration . +For short names, there are variants +.No \ef Ns Ar c +and +.No \ef( Ns Ar cc . +.Ss \eg[ Ns Ar name ] +Interpolate the format of a number register; ignored by +.Xr mandoc 1 . +For short names, there are variants +.No \eg Ns Ar c +and +.No \eg( Ns Ar cc . +.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq +Set the height of the current font; ignored by +.Xr mandoc 1 . +.Ss \eh\(aq Ns Ar number Ns \(aq +Horizontal motion; ignored by +.Xr mandoc 1 . +.Ss \ek[ Ns Ar name ] +Mark horizontal input place in register; ignored by +.Xr mandoc 1 . +For short names, there are variants +.No \ek Ns Ar c +and +.No \ek( Ns Ar cc . +.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq +Vertical line drawing function; ignored by +.Xr mandoc 1 . +.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq +Horizontal line drawing function; ignored by +.Xr mandoc 1 . +.Ss \eM[ Ns Ar name ] +Set fill (background) color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.No \eM Ns Ar c +and +.No \eM( Ns Ar cc . +.Ss \em[ Ns Ar name ] +Set glyph drawing color (groff extension); ignored by +.Xr mandoc 1 . +For short names, there are variants +.No \em Ns Ar c +and +.No \em( Ns Ar cc . +.Ss \eN\(aq Ns Ar number Ns \(aq +Character +.Ar number +on the current font. +.Ss \en[ Ns Ar name ] +Interpolate the number register +.Ar name . +For short names, there are variants +.No \en Ns Ar c +and +.No \en( Ns Ar cc . +.Ss \eo\(aq Ns Ar string Ns \(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. +.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq +Set number register; ignored by +.Xr mandoc 1 . +.Ss \eS\(aq Ns Ar number Ns \(aq +Slant output; ignored by +.Xr mandoc 1 . +.Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq +Change point size; ignored by +.Xr mandoc 1 . +Alternative forms +.No \es Ns Oo +|- Oc Ns Ar n , +.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq , +.No \es Ns [ Oo +|- Oc Ns Ar number ] , +and +.No \es Ns Oo +|- Oc Ns [ Ar number Ns ] +are also parsed and ignored. +.Ss \et +Horizontal tab; ignored by +.Xr mandoc 1 . +.Ss \eu +Move up by half a line; ignored by +.Xr mandoc 1 . +.Ss \eV[ Ns Ar name ] +Interpolate an environment variable; ignored by +.Xr mandoc 1 . +For short names, there are variants +.No \eV Ns Ar c +and +.No \eV( Ns Ar cc . +.Ss \ev\(aq Ns Ar number Ns \(aq +Vertical motion; ignored by +.Xr mandoc 1 . +.Ss \ew\(aq Ns Ar string Ns \(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. +.Ss \eX\(aq Ns Ar string Ns \(aq +Output +.Ar string +as device control function; ignored in nroff mode and by +.Xr mandoc 1 . +.Ss \ex\(aq Ns Ar number Ns \(aq +Extra line space function; ignored by +.Xr mandoc 1 . +.Ss \eY[ Ns Ar name ] +Output a string as a device control function; ignored in nroff mode and by +.Xr mandoc 1 . +For short names, there are variants +.No \eY Ns Ar c +and +.No \eY( Ns Ar cc . +.Ss \eZ\(aq Ns Ar string Ns \(aq +Print +.Ar string +with zero width and height; ignored by +.Xr mandoc 1 . +.Ss \ez +Output the next character without advancing the cursor position. .Sh COMPATIBILITY -This section documents compatibility between mandoc and other other -troff implementations, at this time limited to GNU troff -.Pq Qq groff . -The term -.Qq historic groff -refers to groff versions before the -.Pa doc.tmac -file re-write -.Pq somewhere between 1.15 and 1.19 . +The +.Xr mandoc 1 +implementation of the +.Nm +language is intentionally incomplete. +Unimplemented features include: .Pp .Bl -dash -compact .It -Historic groff did not accept white-space buffering the custom END tag -for the -.Sx \&ig -macro. +For security reasons, +.Xr mandoc 1 +never reads or writes external files except via +.Sx \&so +requests with safe relative paths. +.It +There is no automatic hyphenation, no adjustment to the right margin, +and no centering; the output is always set flush-left. +.It +Support for setting tabulator positions +and 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. +Explicit movement requests and escapes are ignored. +.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, 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 are not implemented, +and support for traps is very incomplete. +.It +While recursion is supported, +.Sx \&while +loops are not. .El +.Pp +The special semantics of the +.Cm nS +number register is an idiosyncracy 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 Clarke re-implemented troff in C++, naming it groff. .Sh AUTHORS -The +.An -nosplit +This .Nm reference was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and +.An Ingo Schwarze Aq Mt schwarze@openbsd.org .