From 9d6a3f20bf88381c4a9d7374b178714434563fe1 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Sat, 27 Nov 2010 21:57:24 +0000 Subject: Move our partial roff language manual to the right place, such that, after some more improvements, we will eventually be able to install it. jmc@ agrees with the plan. --- share/man/man7/roff.7 | 532 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 532 insertions(+) create mode 100644 share/man/man7/roff.7 (limited to 'share') diff --git a/share/man/man7/roff.7 b/share/man/man7/roff.7 new file mode 100644 index 00000000000..b3492b97b16 --- /dev/null +++ b/share/man/man7/roff.7 @@ -0,0 +1,532 @@ +.\" $Id: roff.7,v 1.1 2010/11/27 21:57:23 schwarze Exp $ +.\" +.\" Copyright (c) 2010 Kristaps Dzonsons +.\" Copyright (c) 2010 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 +.\" 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 . -- cgit v1.2.3