=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.193 retrieving revision 1.195 diff -u -p -r1.193 -r1.195 --- mandoc/mdoc.7 2011/07/31 17:42:50 1.193 +++ mandoc/mdoc.7 2011/08/02 01:07:26 1.195 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.193 2011/07/31 17:42:50 schwarze Exp $ +.\" $Id: mdoc.7,v 1.195 2011/08/02 01:07:26 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 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: July 31 2011 $ +.Dd $Mdocdate: August 2 2011 $ .Dt MDOC 7 .Os .Sh NAME @@ -65,42 +65,6 @@ A macro line with only a control character and comment is also ignored. Macro lines with only a control character and optional whitespace are stripped from input. -.Ss Reserved Terms -Within a macro line, the following terms are reserved: -.Pp -.Bl -tag -width Ds -offset indent -compact -.It \&. -.Pq period -.It \e. -.Pq escaped period -.It \&, -.Pq comma -.It \&: -.Pq colon -.It \&; -.Pq semicolon -.It \&( -.Pq left-parenthesis -.It \&) -.Pq right-parenthesis -.It \&[ -.Pq left-bracket -.It \&] -.Pq right-bracket -.It \&? -.Pq question -.It \&! -.Pq exclamation -.It \&| -.Pq vertical bar -.It \e*(Ba -.Pq reserved-word vertical bar -.El -.Pp -For general use in macro lines, these can be escaped with a non-breaking -space -.Pq Sq \e& . -In text lines, these may be used as normal punctuation. .Ss Special Characters Special characters may occur in both macro and text lines. Sequences begin with the escape character @@ -178,15 +142,38 @@ trailing spaces are stripped from input (unless in a l Blank text lines, which may include whitespace, are only permitted within literal contexts. .Pp +In general, trailing whitespace on input lines is discouraged +for reasons of clarity and portability. +In the rare case that a blank character is needed at the end of an +input line, it may be forced by +.Sq \e\ \e& . +.Pp In macro lines, whitespace delimits arguments and is discarded. -If arguments are quoted, whitespace within the quotes is retained. .Ss Quotation -Macro arguments may be quoted with double-quotes to group -space-delimited terms or to retain blocks of whitespace. +Macro arguments may be quoted with double-quotes; in this case, +whitespace within the quotes is retained as part of the argument. +For example, +.Pp +.D1 Pf \. \&Fn strlen "\(dqconst char *s\(dq" +.Pp +renders as +.Sq Fn strlen "const char *s" , +while +.Pp +.D1 Pf \. \&Fn strlen "const char *s" +.Pp +would produce +.Sq Fn strlen const char *s . +.Pp A quoted argument begins with a double-quote preceded by whitespace. The next double-quote not pairwise adjacent to another double-quote terminates the literal, regardless of surrounding whitespace. .Pp +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. +.Pp Note that any quoted text, even if it would cause a macro invocation when unquoted, is considered literal text. Thus, the following produces @@ -304,7 +291,7 @@ file for a utility \&.Os \&.Sh NAME \&.Nm progname -\&.Nd a description goes here +\&.Nd one line about what it does \&.\e\*q .Sh LIBRARY \&.\e\*q For sections 2, 3, & 9 only. \&.\e\*q Not used in OpenBSD. @@ -600,6 +587,17 @@ The .Em Callable column indicates that the macro may also be called by passing its name as an argument to another macro. +For example, +.Sq \&.Op \&Fl O \&Ar file +produces +.Sq Op Fl O Ar file . +To prevent a macro call and render the macro name literally, +escape it by prepending a zero-width space, +.Sq \e& . +For example, +.Sq \&Op \e&Fl O +produces +.Sq Op \&Fl O . If a macro is not callable but its name appears as an argument to another macro, it is interpreted as opaque text. For example, @@ -728,9 +726,8 @@ and/or tail .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc .El .Ss Block partial-implicit -Like block full-implicit, but with single-line scope closed by -.Sx Reserved Terms -or end of line. +Like block full-implicit, but with single-line scope closed by the +end of the line. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB .Ed @@ -776,9 +773,8 @@ these blocks have bodies, but no heads. .It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It .El .Ss In-line -Closed by -.Sx Reserved Terms , -end of line, fixed argument lengths, and/or subsequent macros. +Closed by the end of the line, fixed argument lengths, +and/or subsequent macros. In-line macros have only text children. If a number (or inequality) of arguments is .Pq n , @@ -868,6 +864,90 @@ then the macro accepts an arbitrary number of argument .It Sx \&br Ta \&No Ta \&No Ta 0 .It Sx \&sp Ta \&No Ta \&No Ta 1 .El +.Ss Delimiters +When a macro argument consists of one single input character +considered as a delimiter, the argument gets special handling. +This does not apply when delimiters appear in arguments containing +more than one character. +Consequently, to prevent special handling and just handle it +like any other argument, a delimiter can be escaped by prepending +a zero-width space +.Pq Sq \e& . +In text lines, delimiters never need escaping, but may be used +as normal punctuation. +.Pp +For many macros, when the leading arguments are opening delimiters, +these delimiters are put before the macro scope, +and when the trailing arguments are closing delimiters, +these delimiters are put after the macro scope. +For example, +.Pp +.D1 Pf \. \&Aq "( [ word ] ) ." +.Pp +renders as: +.Pp +.D1 Aq ( [ word ] ) . +.Pp +Opening delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&( +left parenthesis +.It \&[ +left bracket +.El +.Pp +Closing delimiters are: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&. +period +.It \&, +comma +.It \&: +colon +.It \&; +semicolon +.It \&) +right parenthesis +.It \&] +right bracket +.It \&? +question mark +.It \&! +exclamation mark +.El +.Pp +Note that even a period preceded by a backslash +.Pq Sq \e.\& +gets this special handling; use +.Sq \e&. +to prevent that. +.Pp +Many in-line macros interrupt their scope when they encounter +delimiters, and resume their scope when more arguments follow that +are not delimiters. +For example, +.Pp +.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" +.Pp +renders as: +.Pp +.D1 Fl a ( b | c \*(Ba d ) e +.Pp +This applies to both opening and closing delimiters, +and also to the middle delimiter: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It \&| +vertical bar +.El +.Pp +As a special case, the predefined string \e*(Ba is handled and rendered +in the same way as a plain +.Sq \&| +character. +Using this predefined string is not recommended in new manuals. .Sh REFERENCE This section is a canonical reference of all macros, arranged alphabetically. @@ -2883,7 +2963,7 @@ In new groff and mandoc, any list may be nested by def lists will restart the sequence only for the sub-list. .It .Sx \&Li -followed by a reserved character is incorrectly used in some manuals +followed by a delimiter is incorrectly used in some manuals instead of properly quoting that character, which sometimes works with historic groff. .It