=================================================================== RCS file: /cvs/mandoc/roff.7,v retrieving revision 1.20 retrieving revision 1.24 diff -u -p -r1.20 -r1.24 --- mandoc/roff.7 2011/01/03 16:04:41 1.20 +++ mandoc/roff.7 2011/01/24 23:17:19 1.24 @@ -1,4 +1,4 @@ -.\" $Id: roff.7,v 1.20 2011/01/03 16:04:41 kristaps Exp $ +.\" $Id: roff.7,v 1.24 2011/01/24 23:17:19 schwarze 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 3 2011 $ +.Dd $Mdocdate: January 24 2011 $ .Dt ROFF 7 .Os .Sh NAME @@ -86,6 +86,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 +206,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 @@ -546,169 +575,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 \- -This may also be invoked with -.Cm _ . -.It Cm = -.It Cm \(ba -Emit a vertical bar instead of data. -.It Cm \(ba\(ba -Emit a double-vertical bar instead of data. -.El -.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: -.Bl -tag -width Ds -.It Cm z -.It Cm u -.It Cm e -.It Cm t -.It Cm d -.It Cm f -Must be followed by a case-insensitive font style: -.Cm b -for bold or -.Cm i -for italic. -.It Cm b -.It Cm i -.El +See +.Xr tbl 7 +for a description of the tbl language. .Sh COMPATIBILITY This section documents compatibility between mandoc and other other .Nm @@ -739,13 +608,8 @@ using the next-line syntax. .Xr mandoc 1 , .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