=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.57 retrieving revision 1.63 diff -u -p -r1.57 -r1.63 --- mandoc/mdoc.7 2009/08/20 12:08:40 1.57 +++ mandoc/mdoc.7 2009/10/19 07:34:43 1.63 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.57 2009/08/20 12:08:40 kristaps Exp $ +.\" $Id: mdoc.7,v 1.63 2009/10/19 07:34:43 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: August 20 2009 $ +.Dd $Mdocdate: October 19 2009 $ .Dt MDOC 7 .Os . @@ -67,11 +67,13 @@ Text following a whether in a macro or free-form text line, is ignored to the end of line. A macro line with only a control character and comment escape, .Sq \&.\e" , -is also ignored. +is also ignored. Macro lines with only a control charater and optionally +whitespace are stripped from input. . . .Ss Reserved Characters Within a macro line, the following characters are reserved: +.Pp .Bl -tag -width Ds -offset indent -compact .It \&. .Pq period @@ -207,7 +209,63 @@ considered literal text. Thus, the following produces .Pp In free-form mode, quotes are regarded as opaque text. . +.Ss Dates +TODO. . +.Ss Scaling Widths +Many macros support scaled widths for their arguments, such as +stipulating a two-inch list indentation with the following: +.Bd -literal -offset indent +\&.Bl -tag -width 2i +.Ed +. +.Pp +The syntax for scaled widths is +.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , +where a decimal must be preceded or proceeded by at least one digit. +Negative numbers, while accepted, are truncated to zero. The following +scaling units are accepted: +.Pp +.Bl -tag -width Ds -offset indent -compact +.It c +centimetre +.It i +inch +.It P +pica (~1/6 inch) +.It p +point (~1/72 inch) +.It f +synonym for +.Sq u +.It v +default vertical span +.It m +width of rendered +.Sq m +.Pq em +character +.It n +width of rendered +.Sq n +.Pq en +character +.It u +default horizontal span +.It M +mini-em (~1/100 em) +.El +.Pp +Using anything other than +.Sq m , +.Sq n , +.Sq u , +or +.Sq v +is necessarily non-portable across output media. See +.Sx COMPATIBILITY . +. +. .Sh MANUAL STRUCTURE Each .Nm @@ -224,9 +282,43 @@ followed by \&.Dd $\&Mdocdate$ \&.Dt mdoc 7 \&.Os +\&. \&.Sh NAME -\&.Nm mdoc -\&.Nd mdoc language reference +\&.Nm foo +\&.Nd a description goes here +\&.\e\*q The next is for sections 2 & 3 only. +\&.\e\*q .Sh LIBRARY +\&. +\&.Sh SYNOPSIS +\&.Nm foo +\&.Op Fl options +\&.Ar +\&. +\&.Sh DESCRIPTION +The +\&.Nm +utility processes files ... +\&.\e\*q .Sh IMPLEMENTATION NOTES +\&.\e\*q The next is for sections 1 & 8 only. +\&.\e\*q .Sh EXIT STATUS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .Sh RETURN VALUES +\&.\e\*q The next is for sections 1, 6, 7, & 8 only. +\&.\e\*q .Sh ENVIRONMENT +\&.\e\*q .Sh FILES +\&.\e\*q .Sh EXAMPLES +\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. +\&.\e\*q .Sh DIAGNOSTICS +\&.\e\*q The next is for sections 2, 3, & 9 only. +\&.\e\*q .Sh ERRORS +\&.\e\*q .Sh SEE ALSO +\&.\e\*q .Xr foobar 1 +\&.\e\*q .Sh STANDARDS +\&.\e\*q .Sh HISTORY +\&.\e\*q .Sh AUTHORS +\&.\e\*q .Sh CAVEATS +\&.\e\*q .Sh BUGS +\&.\e\*q .Sh SECURITY CONSIDERATIONS .Ed . .Pp @@ -262,9 +354,9 @@ The column indicates that the macro may be called subsequent to the initial line-macro. If a macro is not callable, then its invocation after the initial line macro is interpreted as opaque text, such that -.Sq \&.Fl Sh +.Sq \&.Fl \&Sh produces -.Sq Fl Sh . +.Sq Fl \&Sh . . .Pp The @@ -350,8 +442,8 @@ and/or tail .Pp .Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope -.It \&Ac Ta Yes Ta Yes Ta opened by \&Ao -.It \&Ao Ta Yes Ta Yes Ta closed by \&Ac +.It \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao +.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac .It \&Bc Ta Yes Ta Yes Ta closed by \&Bo .It \&Bo Ta Yes Ta Yes Ta opened by \&Bc .It \&Brc Ta Yes Ta Yes Ta opened by \&Bro @@ -368,8 +460,8 @@ and/or tail .It \&Po Ta Yes Ta Yes Ta opened by \&Pc .It \&Qc Ta Yes Ta Yes Ta opened by \&Oo .It \&Qo Ta Yes Ta Yes Ta closed by \&Oc -.It \&Re Ta \&No Ta \&No Ta opened by \&Rs -.It \&Rs Ta \&No Ta \&No Ta closed by \&Re +.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs +.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re .It \&Sc Ta Yes Ta Yes Ta opened by \&So .It \&So Ta Yes Ta Yes Ta closed by \&Sc .It \&Xc Ta Yes Ta Yes Ta opened by \&Xo @@ -421,18 +513,18 @@ then the macro accepts an arbitrary number of argument .Pp .Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments -.It \&%A Ta \&No Ta \&No Ta >0 -.It \&%B Ta \&No Ta \&No Ta >0 -.It \&%C Ta \&No Ta \&No Ta >0 -.It \&%D Ta \&No Ta \&No Ta >0 -.It \&%I Ta \&No Ta \&No Ta >0 -.It \&%J Ta \&No Ta \&No Ta >0 -.It \&%N Ta \&No Ta \&No Ta >0 -.It \&%O Ta \&No Ta \&No Ta >0 -.It \&%P Ta \&No Ta \&No Ta >0 -.It \&%R Ta \&No Ta \&No Ta >0 -.It \&%T Ta \&No Ta \&No Ta >0 -.It \&%V Ta \&No Ta \&No Ta >0 +.It Sx \&%A Ta \&No Ta \&No Ta >0 +.It Sx \&%B Ta \&No Ta \&No Ta >0 +.It Sx \&%C Ta \&No Ta \&No Ta >0 +.It Sx \&%D Ta \&No Ta \&No Ta >0 +.It Sx \&%I Ta \&No Ta \&No Ta >0 +.It Sx \&%J Ta \&No Ta \&No Ta >0 +.It Sx \&%N Ta \&No Ta \&No Ta >0 +.It Sx \&%O Ta \&No Ta \&No Ta >0 +.It Sx \&%P Ta \&No Ta \&No Ta >0 +.It Sx \&%R Ta \&No Ta \&No Ta >0 +.It Sx \&%T Ta \&No Ta \&No Ta >0 +.It Sx \&%V Ta \&No Ta \&No Ta >0 .It \&Ad Ta Yes Ta Yes Ta n .It \&An Ta Yes Ta Yes Ta n .It \&Ap Ta Yes Ta Yes Ta 0 @@ -453,7 +545,7 @@ then the macro accepts an arbitrary number of argument .It \&Er Ta Yes Ta Yes Ta >0 .It \&Es Ta \&No Ta \&No Ta 0 .It \&Ev Ta Yes Ta Yes Ta n -.It \&Ex Ta \&No Ta \&No Ta 0 +.It \&Ex Ta \&No Ta \&No Ta n .It \&Fa Ta Yes Ta Yes Ta n .It \&Fd Ta \&No Ta \&No Ta >0 .It \&Fl Ta Yes Ta Yes Ta n @@ -480,7 +572,7 @@ then the macro accepts an arbitrary number of argument .It \&Pa Ta Yes Ta Yes Ta n .It \&Pf Ta \&No Ta Yes Ta 1 .It \&Pp Ta \&No Ta \&No Ta 0 -.It \&Rv Ta \&No Ta \&No Ta 0 +.It \&Rv Ta \&No Ta \&No Ta n .It \&Sm Ta \&No Ta \&No Ta 1 .It \&St Ta \&No Ta Yes Ta 1 .It \&Sx Ta Yes Ta Yes Ta >0 @@ -496,6 +588,250 @@ then the macro accepts an arbitrary number of argument .El . . +.Sh REFERENCE +This section is a canonical reference of all macros, arranged +alphabetically. For the scoping of individual macros, see +.Sx MACRO SYNTAX . +. +.Ss \&%A +Author name of an +.Sx \&Rs +block. Multiple authors should each be accorded their own +.Sq \%%A +line. +.Pp +Author names should be ordered with full or abbreviated forename(s) +first, then full surname. +.Ss \&%B +Book title of an +.Sx \&Rs +block. This macro may also be used in a non-bibliographic context when +referring to book titles. +.Ss \&%C +Publication city or location of an +.Sx \&Rs +block. +.Pp +.Em Compatibility remark : +this macro is not implemented in +.Xr groff 1 . +.Ss \&%D +Publication date of an +.Sx \&Rs +block. This should follow the canonical syntax for +.Sx Dates . +.Ss \&%I +Publisher or issuer name of an +.Sx \&Rs +block. +.Ss \&%J +Journal name of an +.Sx \&Rs +block. +.Ss \&%N +Issue number (usually for journals) of an +.Sx \&Rs +block. +.Ss \&%O +Optional information of an +.Sx \&Rs +block. +.Ss \&%P +Book or journal page number of an +.Sx \&Rs +block. +.Ss \&%Q +Institutional author (school, government, etc.) of an +.Sx \&Rs +block. Multiple institutional authors should each be accorded their own +.Sq \&%Q +line. +.Ss \&%R +Technical report name of an +.Sx \&Rs +block. +.Ss \&%T +Article title of an +.Sx \&Rs +block. This macro may also be used in a non-bibliographical context +when referring to article titles. +.Ss \&%V +Volume number of an +.Sx \&Rs +block. +.Ss \&Ac +Closes an +.Sx \&Ao +block. Does not have any tail arguments. +.Ss \&Ad +Address construct: usually in the context of an computational address in +memory, not a physical (post) address. +.Pp +Example: +.Bd -literal -offset indent +\&.Ad [0,$] +\&.Ad 0x00000000 +.Ed +.Ss \&An +.Ss \&Ao +Begins a block enclosed by angled brackets. Does not have any head +arguments. +.Pp +Example: +.Bd -literal -offset indent +\&.Fl -key= Ns Ao Ar val Ac +.Ed +.Pp +Note that, although this is overwhelmingly used to note URIs, the +.Sx \&Lk +and +.Sx \&Mt +macros are better suited for this purpose. +.Ss \&Ap +.Ss \&Aq +.Ss \&Ar +.Ss \&At +.Ss \&Bc +.Ss \&Bd +.Ss \&Bf +.Ss \&Bk +.Ss \&Bl +.Ss \&Bo +.Ss \&Bq +.Ss \&Brc +.Ss \&Bro +.Ss \&Brq +.Ss \&Bsx +.Ss \&Bt +.Ss \&Bx +.Ss \&Cd +.Ss \&Cm +.Ss \&D1 +.Ss \&Db +.Ss \&Dc +.Ss \&Dd +.Ss \&Dl +.Ss \&Do +.Ss \&Dq +.Ss \&Dt +.Ss \&Dv +.Ss \&Dx +.Ss \&Ec +.Ss \&Ed +.Ss \&Ef +.Ss \&Ek +.Ss \&El +.Ss \&Em +.Ss \&En +.Ss \&Eo +.Ss \&Er +.Ss \&Es +.Ss \&Ev +.Ss \&Ex +.Ss \&Fa +.Ss \&Fc +.Ss \&Fd +.Ss \&Fl +.Ss \&Fn +.Ss \&Fo +.Ss \&Fr +.Ss \&Ft +.Ss \&Fx +.Ss \&Hf +.Ss \&Ic +.Ss \&In +.Ss \&It +.Ss \&Lb +.Ss \&Li +.Ss \&Lk +.Ss \&Lp +.Ss \&Ms +.Ss \&Mt +.Ss \&Nd +.Ss \&Nm +.Ss \&No +.Ss \&Ns +.Ss \&Nx +.Ss \&Oc +.Ss \&Oo +.Ss \&Op +.Ss \&Os +.Ss \&Ot +.Ss \&Ox +.Ss \&Pa +.Ss \&Pc +.Ss \&Pf +.Ss \&Po +.Ss \&Pp +.Ss \&Pq +.Ss \&Qc +.Ss \&Ql +.Ss \&Qo +.Ss \&Qq +.Ss \&Re +Closes a +.Sx \&Rs +block. Does not have any tail arguments. +.Ss \&Rs +Begins a bibliographic +.Pq Dq reference +block. Does not have any head arguments. The block macro and may only +contain +.Sx \&%A , +.Sx \&%B , +.Sx \&%C , +.Sx \&%D , +.Sx \&%I , +.Sx \&%J , +.Sx \&%N , +.Sx \&%O , +.Sx \&%P , +.Sx \&%Q , +.Sx \&%R , +.Sx \&%T , +and +.Sx \&%V +child macros (at least one must be specified). +.Pp +Example: +.Bd -literal -offset indent +\&.Rs +\&.%A J. E. Hopcroft +\&.%A J. D. Ullman +\&.%B Introduction to Automata Theory, Languages, and Computation +\&.%I Addison-Wesley +\&.%C Reading, Massachusettes +\&.%D 1979 +\&.Re +.Ed +.Pp +If an +.Sx \&Rs +block is used within a SEE ALSO section, a vertical space is asserted +before the rendered output, else the block continues on the current +line. +.Ss \&Rv +.Ss \&Sc +.Ss \&Sh +.Ss \&Sm +.Ss \&So +.Ss \&Sq +.Ss \&Ss +.Ss \&St +.Ss \&Sx +.Ss \&Sy +.Ss \&Tn +.Ss \&Ud +.Ss \&Ux +.Ss \&Va +.Ss \&Vt +.Ss \&Xc +.Ss \&Xo +.Ss \&Xr +.Ss \&br +.Ss \&sp +. +. .Sh COMPATIBILITY This section documents compatibility with other roff implementations, at this time limited to @@ -509,6 +845,13 @@ file re-write . .Pp .Bl -dash -compact +.It +Negative scaling units are now truncated to zero instead of creating +interesting conditions, such as with +.Sq \&sp -1i . +Furthermore, the +.Sq f +scaling unit, while accepted, is rendered as the default unit. .It The .Sq \-split