=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.44 retrieving revision 1.48 diff -u -p -r1.44 -r1.48 --- mandoc/mdoc.7 2009/07/17 12:08:08 1.44 +++ mandoc/mdoc.7 2009/07/18 23:31:04 1.48 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.44 2009/07/17 12:08:08 kristaps Exp $ +.\" $Id: mdoc.7,v 1.48 2009/07/18 23:31:04 kristaps Exp $ .\" .\" Copyright (c) 2009 Kristaps Dzonsons .\" @@ -14,7 +14,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 17 2009 $ +.Dd $Mdocdate: July 18 2009 $ .Dt MDOC 7 .Os .\" SECTION--------------------------------------------- @@ -49,13 +49,13 @@ prior macros: Other lines are interpreted within the current state. .Ed .\" SECTION--------------------------------------------- -.Sh INPUT ENCODING +.Sh LANGUAGE SYNTAX .Nm documents may contain only graphable 7-bit ASCII characters, the space character, and, in certain circumstances, the tab character. All manuals must have .Ux -line termination. +line terminators. .\" SUB-SECTION---------------------- .Ss Comments Text following a @@ -133,22 +133,49 @@ escape followed by an indicator: B (bold), I, (italic) (Roman, or reset). This form is not recommended. .\" SUB-SECTION---------------------- .Ss Whitespace -In general, consecutive blocks of whitespace are pruned from input. -These are later re-added, when applicable, by -.Xr mandoc 1 . +In non-literal free-form lines, consecutive blocks of whitespace are +pruned from input and added later in the output filter, if applicable: +.Bd -literal -offset indent +These spaces are pruned from input. +\&.Bd \-literal +These are not. +\&.Ed +.Ed .\" PARAGRAPH------------ .Pp -Blank lines are permitted within -.Sq \&Bd \-literal -or -.Sq \&Bd \-unfilled -contexts. Tab characters are only acceptable when delimiting +In macro lines, whitespace delimits arguments and is discarded. If +arguments are quoted, whitespace within the quotes is retained. +.\" PARAGRAPH------------ +.Pp +Blank lines are only permitted within literal contexts, as are lines +containing only whitespace. Tab characters are only acceptable when +delimiting .Sq \&Bl \-column -and in -.Sq \&Bd \-literal -or -.Sq \&Bd \-unfilled -contexts. +or when in a literal context. +.\" SUB-SECTION---------------------- +.Ss Quotation +Macro arguments may be quoted with a double-quote to group +space-delimited terms or to retain blocks of whitespace. A quoted +argument begins with a double-quote preceded by whitespace. The next +double-quote not pair-wise adjacent to another double-quote terminates +the literal, regardless of surrounding whitespace. +.\" PARAGRAPH------------ +.Pp +This produces tokens +.Sq a" , +.Sq b c , +.Sq de , +and +.Sq fg" . +Note that any quoted term, be it argument or macro, is indiscriminately +considered literal text. Thus, the following produces +.Sq \&Em a : +.Bd -literal -offset indent +\&.Em "Em a" +.Ed +.\" PARAGRAPH------------ +.Pp +In free-form mode, quotes are regarded as opaque text. .\" SECTION--------------------------------------------- .Sh MANUAL STRUCTURE Each @@ -157,8 +184,11 @@ document must begin with a document prologue, containi .Sq \&Dd , .Sq \&Dt , and -.Sq \&Os -(using this manual as an example): +.Sq \&Os , +then the NAME section containing at least one +.Sq \&Nm +followed by +.Sq \&Nd : .Bd -literal -offset indent \&.Dd $\&Mdocdate$ \&.Dt mdoc 7 @@ -167,12 +197,6 @@ and \&.Nm mdoc \&.Nd mdoc language reference .Ed -.Pp -Following these, the document body must begin with the NAME section -containing at least one -.Sq \&Nm -followed by -.Sq \&Nd . .\" PARAGRAPH------------ .Pp Subsequent SYNOPSIS and DESCRIPTION sections are strongly encouraged, @@ -181,10 +205,10 @@ but non-compulsory. .Sh MACRO SYNTAX Every line beginning with the control character .Sq \. -is processed for macros, two- or three-character semantic annotations. +is processed for macros, two- or three-character sequences. .\" PARAGRAPH------------ .Pp -The syntax of macro depends on its classification. In this section, +The syntax of a macro depends on its classification. In this section, .Sq \-arg refers to macro arguments, which may be followed by zero or more .Sq parm @@ -199,7 +223,7 @@ The .Em Callable column indicates that the macro may be called subsequent to the initial line-macro. The -.Qq Parsable +.Em Parsable column indicates whether the macro may be followed by further (ostensibly callable) macros. The .Em Scope @@ -414,6 +438,7 @@ then the macro accepts an arbitrary number of argument .It \&Vt Ta Yes Ta Yes Ta >0 .It \&Xr Ta Yes Ta Yes Ta >0, <3 .It \&br Ta \&No Ta \&No Ta 0 +.It \&sp Ta \&No Ta \&No Ta 1 .El .\" SECTION--------------------------------------------- .Sh COMPATIBILITY @@ -431,6 +456,16 @@ file re-write .Bl -dash -compact .\" LIST-ITEM .It +In quoted literals, groff allowed pair-wise double-quotes to produce a +standalone double-quote in formatted output. This idiosyncratic +behaviour is no longer applicable. +.\" LIST-ITEM +.It +The +.Sq \&sp +macro does not accept negative numbers. +.\" LIST-ITEM +.It Some character sequences in groff are not handled depending on escape style, e.g., .Sq \e(ba @@ -457,25 +492,25 @@ made historic groff but is a proper delimiter in this implementation. .\" LIST-ITEM .It -.Sq \&.It \-nested +.Sq \&It \-nested is assumed for all lists (it wasn't in historic groff): any list may be nested and .Sq \-enum lists will restart the sequence only for the sub-list. .\" LIST-ITEM .It -.Sq \&.It \-column +.Sq \&It \-column syntax where column widths may be preceded by other arguments (instead of proceeded) is not supported. .\" LIST-ITEM .It The -.Sq \&.At +.Sq \&At macro only accepts a single parameter. .\" LIST-ITEM .It Some manuals use -.Sq \&.Li +.Sq \&Li incorrectly by following it with a reserved character and expecting the delimiter to render. This is not supported. .\" LIST-ITEM @@ -487,7 +522,7 @@ versions of groff seem to dither on this. .\" LIST-ITEM .It In groff, the -.Sq \&.Fo +.Sq \&Fo macro only produces the first parameter. This is no longer the case. .El .\" SECTION--------------------------------------------- @@ -498,7 +533,7 @@ macro only produces the first parameter. This is no l .Sh AUTHORS The .Nm -utility was written by +reference was written by .An Kristaps Dzonsons Aq kristaps@kth.se . .\" SECTION--------------------------------------------- .Sh CAVEATS @@ -508,69 +543,69 @@ There are many ambiguous parts of mdoc. .Bl -dash -compact .\" LIST-ITEM .It -.Sq \&.Fa +.Sq \&Fa should be -.Sq \&.Va +.Sq \&Va as function arguments are variables. .\" LIST-ITEM .It -.Sq \&.Ft +.Sq \&Ft should be -.Sq \&.Vt +.Sq \&Vt as function return types are still types. Furthermore, the -.Sq \&.Ft +.Sq \&Ft should be removed and -.Sq \&.Fo , +.Sq \&Fo , which ostensibly follows it, should follow the same convention as -.Sq \&.Va . +.Sq \&Va . .\" LIST-ITEM .It -.Sq \&.Va +.Sq \&Va should formalise that only one or two arguments are acceptable: a variable name and optional, preceding type. .\" LIST-ITEM .It -.Sq \&.Fd +.Sq \&Fd is ambiguous. It's commonly used to indicate an include file in the synopsis section. -.Sq \&.In +.Sq \&In should be used, instead. .\" LIST-ITEM .It Only the .Sq \-literal argument to -.Sq \&.Bd +.Sq \&Bd makes sense. The remaining ones should be removed. .\" LIST-ITEM .It The -.Sq \&.Xo +.Sq \&Xo and -.Sq \&.Xc +.Sq \&Xc macros should be deprecated. .\" LIST-ITEM .It The -.Sq \&.Dt +.Sq \&Dt macro lacks clarity. It should be absolutely clear which title will render when formatting the manual page. .\" LIST-ITEM .It A -.Sq \&.Lx +.Sq \&Lx should be provided for Linux (\(`a la -.Sq \&.Ox , -.Sq \&.Nx +.Sq \&Ox , +.Sq \&Nx etc.). .\" LIST-ITEM .It There's no way to refer to references in -.Sq \&.Rs/.Re +.Sq \&Rs/Re blocks. .\" LIST-ITEM .It The \-split and \-nosplit arguments to -.Sq \&.An +.Sq \&An are inane. .El