=================================================================== RCS file: /cvs/mandoc/roff.7,v retrieving revision 1.21 retrieving revision 1.30 diff -u -p -r1.21 -r1.30 --- mandoc/roff.7 2011/01/04 12:06:21 1.21 +++ mandoc/roff.7 2011/07/28 14:17:11 1.30 @@ -1,4 +1,4 @@ -.\" $Id: roff.7,v 1.21 2011/01/04 12:06:21 kristaps Exp $ +.\" $Id: roff.7,v 1.30 2011/07/28 14:17:11 kristaps Exp $ .\" .\" Copyright (c) 2010 Kristaps Dzonsons .\" Copyright (c) 2010 Ingo Schwarze @@ -15,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: January 4 2011 $ +.Dd $Mdocdate: July 28 2011 $ .Dt ROFF 7 .Os .Sh NAME @@ -57,10 +57,6 @@ To produce other characters in the output, use the esc documented in the .Xr mandoc_char 7 manual. -.Pp -All manuals must have -.Ux -line terminators. .Sh REQUEST SYNTAX A request or macro line consists of: .Pp @@ -86,6 +82,38 @@ Thus, the following request lines are all equivalent: \&.ig end \&. ig end .Ed +.Sh MACRO SYNTAX +Macros 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 . +To be recognized as the beginning of a quoted argument, the opening +quote character must be preceded by a space character. +.Pp +A quoted argument may contain whitespace, and pairs of double quote +characters +.Pq Sq Qq +resolve to single double quote characters. +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. .Sh REQUEST REFERENCE The .Xr mandoc 1 @@ -174,12 +202,9 @@ The 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. +Regarding argument parsing, see +.Sx MACRO SYNTAX +above. .Pp The line invoking the macro will be replaced in the input stream by the @@ -319,6 +344,15 @@ then false is assumed. The syntax of this request is similar to .Sx \&if except that the conditional is missing. +.Ss \&EN +End an equation block. +See +.Sx \&EQ . +.Ss \&EQ +Begin an equation block. +See +.Xr eqn 7 +for a description of the equation language. .Ss \&hy Set automatic hyphenation mode. This line-scoped request is currently ignored. @@ -414,15 +448,20 @@ than having the request or macro follow as The scope of a conditional is always parsed, but only executed if the conditional evaluates to true. .Pp -Note that text following an -.Sq \&.\e} -escape sequence 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 request, not only the text preceding the close, with the +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} -collapsing into a zero-width space. +being considered an argument of the +.Sq \&Fl +macro. .Ss \&ig Ignore input. Its syntax can be either @@ -512,6 +551,16 @@ section with the .Cm \&Sh macro will reset this register. .El +.Ss \&ns +Turn on no-space mode. +This line-scoped request is intended to take no arguments. +Currently, it is ignored including its arguments, +and the number of arguments is not checked. +.Ss \&ps +Change point size. +This line-scoped request is intended to take one numerical argument. +Currently, it is ignored including its arguments, +and the number of arguments is not checked. .Ss \&so Include a source file. Its syntax is as follows: @@ -523,18 +572,33 @@ The will be read and its contents processed as input in place of the .Sq \&.so request line. -To avoid inadvertant inclusion of unrelated files, +To avoid inadvertent inclusion of unrelated files, .Xr mandoc 1 only accepts relative paths not containing the strings .Qq ../ and .Qq /.. . +.Ss \&ta +Set tab stops. +This line-scoped request can take an arbitrary number of arguments. +Currently, it is ignored including its arguments. .Ss \&tr Output character translation. -This request 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. +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 \&T& Re-start a table layout, retaining the options of the prior table invocation. @@ -546,196 +610,9 @@ See .Sx \&TS . .Ss \&TS Begin a table, which formats input in aligned rows and columns. -A table consists of an optional single line of table options terminated -by a semicolon, followed by one or more lines of layout specification -terminated by a period, then table data. -A table block may also include -.Nm , -.Xr mdoc 7 , -or -.Xr man 7 -macros. -Example: -.Bd -literal -offset indent -\&.TS -box tab(:); \e" Table-wide options. -c | c \e" Layout for first line. -| c | c. \e" Layout for all subsequent lines. -1:2 \e" Data... -3:4 -\&.TE -.Ed -.Pp -Table data is -.Em pre-processed , -that is, data rows are parsed then inserted into the underlying stream -of input data. -This allows data rows to be interspersed by arbitrary macros, such as -.Bd -literal -offset indent -\&.TS -tab(:); -c c c. -1:2:3 -\&.Ao -3:2:1 -\&.Ac -\&.TE -.Ed -.Pp -in the case of -.Xr mdoc 7 -or -.Bd -literal -offset indent -\&.TS -tab(:); -c c c. -\&.ds ab 2 -1:\e*(ab:3 -\&.I -3:2:1 -\&.TE -.Ed -.Pp -in the case of -.Xr man 7 . -.Pp -The first line of a table consists of its options, which consists of -space-separated keys and modifiers terminated by a semicolon. -If the first line does not have a terminating semicolon, it is assumed -that no options are specified and instead a layout is processed. -Some options accept arguments enclosed by paranthesis. -The following case-insensitive options are available: -.Bl -tag -width Ds -.It Cm center -This option is not supported by -.Xr mandoc 1 . -This may also be invoked with -.Cm centre . -.It Cm delim -Accepts a two-character argument. -This option is not supported by -.Xr mandoc 1 . -.It Cm expand -This option is not supported by -.Xr mandoc 1 . -.It Cm box -Draw a single-line box around the table. -This may also be invoked with -.Cm frame . -.It Cm doublebox -Draw a double-line box around the table. -This may also be invoked with -.Cm doubleframe . -.It Cm allbox -This option is not supported by -.Xr mandoc 1 . -.It Cm tab -Accepts a single-character argument. -This character is used a delimiter between data cells, which otherwise -defaults to the tab character. -.It Cm linesize -Accepts a natural number (all digits). -This option is not supported by -.Xr mandoc 1 . -.It Cm nokeep -This option is not supported by -.Xr mandoc 1 . -.It Cm decimalpoint -Accepts a single-character argument. -This character will be used as the decimal point with the -.Cm n -layout key. -This option is not supported by -.Xr mandoc 1 . -.It Cm nospaces -This option is not supported by -.Xr mandoc 1 . -.El -.Pp -The table layout follows table options, except in the case of -.Sx \&T& , -where it immediately procedes invocation. -Layout specifies how data rows are displayed on output. -Each layout line corresponds to a line of data; the last layout line -applies to all remaining data lines. -Layout lines may also be separated by a comma. -Each layout cell consists of one of the following case-insensitive keys: -.Bl -tag -width Ds -.It Cm c -Centre a literal string within its column. -.It Cm r -Right-justify a literal string within its column. -.It Cm l -Left-justify a literal string within its column. -.It Cm n -Justify a number around its decimal point. -If the decimal point is not found on the number, it's assumed to trail -the number. -.It Cm s -This option is not supported by -.Xr mandoc 1 . -.It Cm a -This option is not supported by -.Xr mandoc 1 . -.It Cm ^ -This option is not supported by -.Xr mandoc 1 . -.It Cm \- -Replace the data cell (its contents will be lost) with a single -horizontal line. -This may also be invoked with -.Cm _ . -.It Cm = -Replace the data cell (its contents will be lost) with a double -horizontal line. -.It Cm \(ba -Emit a vertical bar instead of data. -.It Cm \(ba\(ba -Emit a double-vertical bar instead of data. -.El -.Pp -For example, following layout specifies a centre-justified column of -minimum width 10, followed by vertical bar, followed by a left-justified -column of minimum width 10, another vertical bar, then a column -justified about the decimal point in numbers: -.Pp -.Dl c10 | l10 | n -.Pp -Keys may be followed by a set of modifiers. -A modifier is either a modifier key or a natural number for specifying -spacing. -The following case-insensitive modifier keys are available: -.Cm z , -.Cm u , -.Cm e , -.Cm t , -.Cm d , -.Cm f , -.Cm b , -.Cm i , -.Cm b , -and -.Cm i . -All of these are ignored by -.Xr mandoc 1 . -.Pp -The data section follows the last layout row. -By default, cells in a data section are delimited by a tab. -This behaviour may be changed with the -.Cm tab -option. -If -.Cm _ -or -.Cm = -is specified, a single or double line, respectively, is drawn across the -data field. -If -.Cm \e- -or -.Cm \e= -is specified, a line is drawn within the data field (i.e., terminating -within the cell and not draw to the border). +See +.Xr tbl 7 +for a description of the tbl language. .Sh COMPATIBILITY This section documents compatibility between mandoc and other other .Nm @@ -747,6 +624,19 @@ refers to groff version 1.15. .Pp .Bl -dash -compact .It +In mandoc, the +.Sx \&EQ , +.Sx \&TE , +.Sx \&TS , +and +.Sx \&T& , +macros are considered regular macros. +In all other +.Nm +implementations, these are special macros that must be specified without +spacing between the control character (which must be a period) and the +macro name. +.It The .Cm nS register is only compatible with OpenBSD's groff-1.15. @@ -764,15 +654,11 @@ using the next-line syntax. .El .Sh SEE ALSO .Xr mandoc 1 , +.Xr eqn 7 , .Xr man 7 , .Xr mandoc_char 7 , -.Xr mdoc 7 -.Rs -.%A M. E. Lesk -.%T Tbl\(emA Program to Format Tables -.%D June 11, 1976 -.%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps -.Re +.Xr mdoc 7 , +.Xr tbl 7 .Rs .%A Joseph F. Ossanna .%A Brian W. Kernighan