=================================================================== RCS file: /cvs/mandoc/roff.7,v retrieving revision 1.19 retrieving revision 1.24 diff -u -p -r1.19 -r1.24 --- mandoc/roff.7 2010/12/29 15:21:34 1.19 +++ mandoc/roff.7 2011/01/24 23:17:19 1.24 @@ -1,4 +1,4 @@ -.\" $Id: roff.7,v 1.19 2010/12/29 15:21:34 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: December 29 2010 $ +.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 @@ -535,132 +564,20 @@ 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. -.\" .Ss \&T& -.\" Re-start a table layout, retaining the options of the prior table -.\" invocation. -.\" See -.\" .Sx \&TS . -.\" .Ss \&TE -.\" End a table context. -.\" 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. -.\" .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 -.\" 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 -.\" 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 may also be invoked with -.\" .Cm centre . -.\" .It Cm delim -.\" Accepts a two-character argument. -.\" This option is ignored. -.\" .It Cm expand -.\" .It Cm box -.\" This may also be invoked with -.\" .Cm frame . -.\" .It Cm doublebox -.\" This may also be invoked with -.\" .Cm doubleframe . -.\" .It Cm allbox -.\" .It Cm tab -.\" Accepts a single character argument used as the delimiter for cells in -.\" data rows. -.\" .It Cm linesize -.\" Accepts a natural number (all digits) used as the line width for drawing -.\" boxes. -.\" .It Cm nokeep -.\" .It Cm decimalpoint -.\" .It Cm nospaces -.\" .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 -.\" .It Cm r -.\" .It Cm l -.\" .It Cm n -.\" .It Cm s -.\" .It Cm a -.\" .It Cm ^ -.\" .It Cm \- -.\" This may also be invoked with -.\" .Cm _ . -.\" .It Cm = -.\" .It Cm \(ba -.\" .It Cm \(ba\(ba -.\" .El -.\" 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 +.Ss \&T& +Re-start a table layout, retaining the options of the prior table +invocation. +See +.Sx \&TS . +.Ss \&TE +End a table context. +See +.Sx \&TS . +.Ss \&TS +Begin a table, which formats input in aligned rows and columns. +See +.Xr tbl 7 +for a description of the tbl language. .Sh COMPATIBILITY This section documents compatibility between mandoc and other other .Nm @@ -691,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