diff options
Diffstat (limited to 'usr.bin')
| -rw-r--r-- | usr.bin/mandoc/roff.7 | 532 |
1 files changed, 0 insertions, 532 deletions
diff --git a/usr.bin/mandoc/roff.7 b/usr.bin/mandoc/roff.7 deleted file mode 100644 index 489e5ed53d5..00000000000 --- a/usr.bin/mandoc/roff.7 +++ /dev/null @@ -1,532 +0,0 @@ -.\" $Id: roff.7,v 1.10 2010/11/27 17:46:46 schwarze Exp $ -.\" -.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2010 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: November 27 2010 $ -.Dt ROFF 7 -.Os -.Sh NAME -.Nm roff -.Nd roff language reference -.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 -.Xr mandoc 1 -utility. It is a work in progress. -.Pp -An -.Nm -document follows simple rules: lines beginning with the control -characters -.Sq \. -or -.Sq \(aq -are parsed for requests and 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 -.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 -Requests and macros are arbitrary in length and begin with a control -character, -.Sq \. -or -.Sq \(aq , -at the beginning of the line. -An arbitrary amount of whitespace may sit between the control character -and the request or macro name. -Thus, the following are equivalent: -.Bd -literal -offset indent -\&.if -\&.\ \ \ \&if -.Ed -.Sh REQUEST REFERENCE -This section is a canonical reference of all requests recognized by the -.Xr mandoc 1 -.Nm -parser. -The -.Nm -language defines many more requests and macros not implemented in -.Xr mandoc 1 . -.Ss \&am -Append to a macro definition. -The syntax of this request is the same as that of -.Sx \&de . -It is currently ignored by -.Xr mandoc 1 , -as are its children. -.Ss \&ami -Append to a macro definition, specifying the macro name indirectly. -The syntax of this request is the same as that of -.Sx \&dei . -It is currently ignored by -.Xr mandoc 1 , -as are its children. -.Ss \&am1 -Append to a macro definition, switching roff compatibility mode off -during macro execution. -The syntax of this request is the same as that of -.Sx \&de1 . -It is currently ignored by -.Xr mandoc 1 , -as are its children. -.Ss \&de -Define a user-defined -.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 -A user-defined macro can be invoked later using the syntax -.Pp -.D1 Pf . Ar name Op Ar argument Op Ar argument ... -.Pp -Arguments are separated by blank characters and can be quoted -using double-quotes -.Pq Sq \(dq -to allow inclusion of blank characters into arguments. -To include the double-quote character into a quoted argument, -escape it from ending the argument by doubling it. -.Pp -The line invoking the user-defined 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. -.Pp -Since user-defined macros and 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. -.Ss \&dei -Define a user-defined -.Nm -macro, specifying the macro name indirectly. -The syntax of this macro is the same as that of -.Sx \&de . -It is currently ignored by -.Xr mandoc 1 , -as are its children. -.Ss \&de1 -Define a user-defined -.Nm -macro that will be executed with -.Nm -compatibility mode switched off during macro execution. -This is a GNU extension not available in traditional -.Nm -implementations and not even in older versions of groff. -Since -.Xr mandoc 1 -does not implement -.Nm -compatibility mode at all, it handles this macro as an alias for -.Sx \&de . -.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. -.Pp -Since user-defined strings and macros share a common string table, -defining a string -.Ar name -clobbers the user-defined 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 \&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 macro is similar to -.Sx \&if -except that the conditional is missing. -.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. -Right now, the conditional evaluates to true -if and only if it starts with the letter -.Sy n , -indicating processing in -.Xr nroff 1 -style as opposed to -.Xr troff 1 -style. -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 -.Pp -will discard the -.Sq \&.ig , -which may lead to interesting results, but -.Pp -.D1 \&.if t \e .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 statement. -roff allows for complicated conditionals; mandoc is much simpler. -At this time, mandoc supports only -.Sq n , -evaluating to true; -and -.Sq t , -.Sq e , -and -.Sq o , -evaluating to false. -All other invocations are read up to the next end of line or space and -evaluate as 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. -If the COND is followed by a BODY on the same line, whether after a -brace or not, then macros -.Em must -begin with a control character. -It is generally more intuitive, in this case, to write -.Bd -literal -offset indent -\&.if COND \e{\e -\&.foo -bar -\&.\e} -.Ed -.Pp -than having the 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 -.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, with the -.Sq \e} -collapsing into a zero-width space. -.Ss \&ig -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 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 the specified -.Sq Pf . Ar end -macro is encountered. -Do not use the escape character -.Sq \e -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 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 \&.. -macro are discarded. -.Ss \&rm -Remove a request, macro or string. -This macro is intended to have one argument, -the name of the request, macro or string to be undefined. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. -.Ss \&nr -Define 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 Ar value -.Pp -The -.Ar value -may, at the moment, only be an integer. -The -.Ar name -is defined up to the next whitespace. -So far, only the following register -.Ar name -is recognised: -.Bl -tag -width Ds -.It Cm nS -If set to a positive integer value, certain -.Xr mdoc 7 -macros will behave as if they were defined in the -.Em SYNOPSIS -section. -Otherwise, this behaviour is unset (even if called within the -.Em SYNOPSIS -section itself). -Note that invoking a new -.Xr mdoc 7 -section will unset this value. -.El -.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 inadvertant inclusion of unrelated files, -.Xr mandoc 1 -only accepts relative paths not containing the strings -.Qq ../ -and -.Qq /.. . -.Ss \&tr -Output character translation. -This macro is intended to have one argument, -consisting of an even number of characters. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. -.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 . -.Pp -.Bl -dash -compact -.It -The -.Cm nS -request to -.Sx \&nr -is only compatible with OpenBSD's groff. -.It -Historic groff did not accept white-space buffering the custom END tag -for the -.Sx \&ig -macro. -.It -The -.Sx \&if -and family would print funny white-spaces with historic groff when -depending on next-line syntax. -.El -.Sh AUTHORS -.An -nosplit -This partial -.Nm -reference was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv -and -.An Ingo Schwarze Aq schwarze@openbsd.org . |