=================================================================== RCS file: /cvs/mandoc/roff.7,v retrieving revision 1.10 retrieving revision 1.16 diff -u -p -r1.10 -r1.16 --- mandoc/roff.7 2010/06/26 15:22:19 1.10 +++ mandoc/roff.7 2010/12/10 20:58:56 1.16 @@ -1,6 +1,7 @@ -.\" $Id: roff.7,v 1.10 2010/06/26 15:22:19 kristaps Exp $ +.\" $Id: roff.7,v 1.16 2010/12/10 20:58:56 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 @@ -14,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 26 2010 $ +.Dd $Mdocdate: December 10 2010 $ .Dt ROFF 7 .Os .Sh NAME @@ -36,7 +37,8 @@ characters .Sq \. or .Sq \(aq -are parsed for macros. Other lines are interpreted within the scope of +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. @@ -50,57 +52,235 @@ manuals must have .Ux line terminators. .Sh MACRO SYNTAX -Macros are arbitrary in length and begin with a control character , +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 macro name. +and the request or macro name. Thus, the following are equivalent: .Bd -literal -offset indent \&.if \&.\ \ \ \&if .Ed -.Sh REFERENCE -This section is a canonical reference of all macros, arranged -alphabetically. +.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 \&ad +Set line adjustment mode. +This line-scoped request is intended to have one argument to select +normal, left, right, or center adjustment for subsequent text. +Currently, it is ignored including its arguments, +and the number of arguments is not checked. .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. +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 -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, 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 -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. +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 -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 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. +.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. +Do not rely on the exact value of this limit. .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 \&ig , -except that a leading argument must be specified. -It is ignored, as are its children. -.Ss \&ds -Define a string. -This macro is intended to have two arguments, -the name of the string to define and its content. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. +.Sx \&de . +It is currently ignored by +.Xr mandoc 1 , +as are its children. .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 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 @@ -115,6 +295,9 @@ then false is assumed. The syntax of this macro is similar to .Sx \&if except that the conditional is missing. +.Ss \&hy +Set automatic hyphenation mode. +This line-scoped request is currently ignored. .Ss \&ie The .Qq if @@ -223,48 +406,58 @@ scope of the prior macro, not only the text preceding collapsing into a zero-width space. .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 +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 \&.. +macro are discarded. +.Ss \&ne +Declare the need for the specified minimum vertical space +before the next trap or the bottom of the page. +This line-scoped request is currently ignored. +.Ss \&nh +Turn off automatic hyphenation mode. +This line-scoped request is currently ignored. .Ss \&rm Remove a request, macro or string. -This macro is intended to have one argument, +This request 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. @@ -274,28 +467,48 @@ A register is an arbitrary string value that defines s which influences parsing and/or formatting. Its syntax is as follows: .Pp -.D1 Pf \. Sx \&nr Cm name value +.D1 Pf \. Cm \&nr Ar name Ar value .Pp The -.Cm value +.Ar value may, at the moment, only be an integer. The -.Cm name +.Ar name is defined up to the next whitespace. -The following register -.Cm name -requests are recognised: +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 are defined in the +macros will behave as if they were defined in the .Em SYNOPSIS -section to a manual. +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, @@ -332,7 +545,10 @@ and family would print funny white-spaces with histori depending on next-line syntax. .El .Sh AUTHORS -The +.An -nosplit +This partial .Nm reference was written by -.An Kristaps Dzonsons Aq kristaps@bsd.lv . +.An Kristaps Dzonsons Aq kristaps@bsd.lv +and +.An Ingo Schwarze Aq schwarze@openbsd.org .