=================================================================== RCS file: /cvs/mandoc/mdoc.7,v retrieving revision 1.71 retrieving revision 1.85 diff -u -p -r1.71 -r1.85 --- mandoc/mdoc.7 2009/10/31 06:50:25 1.71 +++ mandoc/mdoc.7 2010/03/21 18:16:41 1.85 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.71 2009/10/31 06:50:25 kristaps Exp $ +.\" $Id: mdoc.7,v 1.85 2010/03/21 18:16:41 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: October 31 2009 $ +.Dd $Mdocdate: March 21 2010 $ .Dt MDOC 7 .Os . @@ -131,18 +131,58 @@ and .Ss Text Decoration Terms may be text-decorated using the .Sq \ef -escape followed by an indicator: B (bold), I, (italic), or P and R -(Roman, or reset). This form is not recommended for +escape followed by an indicator: B (bold), I, (italic), R (Roman), or P +(revert to previous mode): +.Pp +.D1 \efBbold\efR \efIitalic\efP +.Pp +A numerical representation 3, 2, or 1 (bold, italic, and Roman, +respectively) may be used instead. A text decoration is valid within +the current font scope only: if a macro opens a font scope alongside +its own scope, such as +.Sx \&Bf +.Cm \&Sy , +in-scope invocations of +.Sq \ef +are only valid within the font scope of the macro. If +.Sq \ef +is specified outside of any font scope, such as in unenclosed, free-form +text, it will affect the remainder of the document. +.Pp +Text may also be sized with the +.Sq \es +escape, whose syntax is one of +.Sq \es+-n +for one-digit numerals; +.Sq \es(+-nn +or +.Sq \es+-(nn +for two-digit numerals; and +.Sq \es[+-N] , +.Sq \es+-[N] , +.Sq \es'+-N' , +or +.Sq \es+-'N' +for arbitrary-digit numerals: +.Pp +.D1 \es+1bigger\es-1 +.D1 \es[+10]much bigger\es[-10] +.D1 \es+(10much bigger\es-(10 +.D1 \es+'100'much much bigger\es-'100' +.Pp +Note these forms are +.Em not +recommended for .Nm , -which encourages semantic, not presentation, annotation. +which encourages semantic annotation. . . .Ss Predefined Strings -Historically, +Historically, .Xr groff 1 -also defined a set of package-specific +also defined a set of package-specific .Dq predefined strings , -which, like +which, like .Sx Special Characters , demark special output characters and strings by way of input codes. Predefined strings are escaped with the slash-asterisk, @@ -212,9 +252,8 @@ In free-form mode, quotes are regarded as opaque text. .Ss Dates There are several macros in .Nm -that require a date argument. The -.Em canonical form -for dates is the American format: +that require a date argument. The canonical form for dates is the +American format: .Pp .D1 Cm Month Day , Year .Pp @@ -226,26 +265,16 @@ value is the full month name. The .Cm Year value is the full four-digit year. .Pp -The -.Em non-canonical form -is the same as the canonical form, but without the comma between the -.Cm Day -and -.Cm Year -field. +Reduced form dates are broken-down canonical form dates: .Pp -Lastly, -.Em reduced form -dates range from only a -.Cm Year -to the full canonical or non-canonical form. +.D1 Cm Month , Year +.D1 Cm Year .Pp Some examples of valid dates follow: .Pp .D1 "May, 2009" Pq reduced form .D1 "2009" Pq reduced form .D1 "May 20, 2009" Pq canonical form -.D1 "May 20 2009" Pq non-canonical form . .Ss Scaling Widths Many macros support scaled widths for their arguments, such as @@ -314,7 +343,7 @@ and .Sx \&Os macros, is required for every document. .Pp -The first section (sections are denoted by +The first section (sections are denoted by .Sx \&Sh ) must be the NAME section, consisting of at least one .Sx \&Nm @@ -374,38 +403,199 @@ The sections in a .Nm document are conventionally ordered as they appear above. Sections should be composed as follows: -.Bl -tag -width Ds -offset Ds -.It NAME -Must contain at least one +.Bl -ohang -offset Ds +.It Em NAME +The name(s) and a short description of the documented material. The +syntax for this as follows: +.Bd -literal -offset indent +\&.Nm name0 +\&.Nm name1 +\&.Nm name2 +\&.Nd a short description +.Ed +.Pp +The .Sx \&Nm -followed by +macro(s) must precede the +.Sx \&Nd +macro. +.Pp +See +.Sx \&Nm +and .Sx \&Nd . -The name needs re-stating since one -.Nm -documents can be used for more than one utility or function, such as -.Xr grep 1 -also being referenced as -.Xr egrep 1 +. +.It Em LIBRARY +The name of the library containing the documented material, which is +assumed to be a function in a section 2 or 3 manual. The syntax for +this is as follows: +.Bd -literal -offset indent +\&.Lb libarm +.Ed +.Pp +See +.Sx \&Lb . +. +.It Em SYNOPSIS +Documents the utility invocation syntax, function call syntax, or device +configuration. +.Pp +For the first, utilities (sections 1, 6, and 8), this is +generally structured as follows: +.Bd -literal -offset indent +\&.Nm foo +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +\&.Nm bar +\&.Op Fl v +\&.Op Fl o Ar file +\&.Op Ar +.Ed +.Pp +For the second, function calls (sections 2, 3, 9): +.Bd -literal -offset indent +\&.Vt extern const char *global; +\&.In header.h +\&.Ft "char *" +\&.Fn foo "const char *src" +\&.Ft "char *" +\&.Fn bar "const char *src" +.Ed +.Pp +And for the third, configurations (section 4): +.Bd -literal -offset indent +\&.Cd \*qit* at isa? port 0x2e\*q +\&.Cd \*qit* at isa? port 0x4e\*q +.Ed +.Pp +Manuals not in these sections generally don't need a +.Em SYNOPSIS . +.Pp +See +.Sx \&Op , +.Sx \&Cd , +.Sx \&Fn , +.Sx \&Ft , and -.Xr fgrep 1 . -.It LIBRARY -.It SYNOPSIS -.It DESCRIPTION -.It IMPLEMENTATION NOTES -.It EXIT STATUS -.It RETURN VALUES -.It ENVIRONMENT -.It FILES -.It EXAMPLES -.It DIAGNOSTICS -.It ERRORS -.It SEE ALSO -.It STANDARDS -.It HISTORY -.It AUTHORS -.It CAVEATS -.It BUGS -.It SECURITY CONSIDERATIONS +.Sx \&Vt . +. +.It Em DESCRIPTION +This expands upon the brief, one-line description in +.Em NAME . +It usually contains a break-down of the options (if documenting a +command), such as: +.Bd -literal -offset indent +The arguments are as follows: +\&.Bl \-tag \-width Ds +\&.It Fl v +Print verbose information. +\&.El +.Ed +.Pp +Manuals not documenting a command won't include the above fragment. +. +.It Em IMPLEMENTATION NOTES +Implementation-specific notes should be kept here. This is useful when +implementing standard functions that may have side effects or notable +algorithmic implications. +. +.It Em EXIT STATUS +Command exit status for section 1, 6, and 8 manuals. This section is +the dual of +.Em RETURN VALUES , +which is used for functions. Historically, this information was +described in +.Em DIAGNOSTICS , +a practise that is now discouraged. +.Pp +See +.Sx \&Ex . +. +.It Em RETURN VALUES +This section is the dual of +.Em EXIT STATUS , +which is used for commands. It documents the return values of functions +in sections 2, 3, and 9. +.Pp +See +.Sx \&Rv . +. +.It Em ENVIRONMENT +Documents any usages of environment variables, e.g., +.Xr environ 7 . +.Pp +See +.Sx \&Ev . +. +.It Em FILES +Documents files used. It's helpful to document both the file and a +short description of how the file is used (created, modified, etc.). +.Pp +See +.Sx \&Pa . +. +.It Em EXAMPLES +Example usages. This often contains snippets of well-formed, +well-tested invocations. Make doubly sure that your examples work +properly! +. +.It Em DIAGNOSTICS +Documents error conditions. This is most useful in section 4 manuals. +Historically, this section was used in place of +.Em EXIT STATUS +for manuals in sections 1, 6, and 8; however, this practise is +discouraged. +.Pp +See +.Sx \&Bl +.Fl diag . +. +.It Em ERRORS +Documents error handling in sections 2, 3, and 9. +.Pp +See +.Sx \&Er . +. +.It Em SEE ALSO +References other manuals with related topics. This section should exist +for most manuals. Cross-references should conventionally be ordered +first by section, then alphabetically. +.Pp +See +.Sx \&Xr . +. +.It Em STANDARDS +References any standards implemented or used. If not adhering to any +standards, the +.Em HISTORY +section should be used instead. +.Pp +See +.Sx \&St . +. +.It Em HISTORY +The history of any manual without a +.Em STANDARDS +section should be described in this section. +. +.It Em AUTHORS +Credits to authors, if applicable, should appear in this section. +Authors should generally be noted by both name and an e-mail address. +.Pp +See +.Sx \&An . +. +.It Em CAVEATS +Explanations of common misuses and misunderstandings should be explained +in this section. +. +.It Em BUGS +Extant bugs should be described in this section. +. +.It Em SECURITY CONSIDERATIONS +Documents any security precautions that operators should consider. +. .El . . @@ -493,7 +683,7 @@ All macros have bodies; some don't have heads; only one .Po .Sx \&It Fl column -.Pc +.Pc has multiple heads. .Bd -literal -offset indent \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB @@ -580,7 +770,16 @@ or end of line. .It Sx \&Ql Ta Yes Ta Yes .It Sx \&Qq Ta Yes Ta Yes .It Sx \&Sq Ta Yes Ta Yes +.It Sx \&Vt Ta Yes Ta Yes .El +.Pp +Note that the +.Sx \&Vt +macro is a +.Sx Block partial-implicit +only when invoked as the first macro +in a SYNOPSIS section line, else it is +.Sx In-line . . . .Ss In-line @@ -673,10 +872,10 @@ then the macro accepts an arbitrary number of argument .It Sx \&Ux Ta Yes Ta Yes Ta n .It Sx \&Va Ta Yes Ta Yes Ta n .It Sx \&Vt Ta Yes Ta Yes Ta >0 -.It Sx \&Xr Ta Yes Ta Yes Ta >0, <3 +.It Sx \&Xr Ta Yes Ta Yes Ta >0 .It Sx \&br Ta \&No Ta \&No Ta 0 .It Sx \&sp Ta \&No Ta \&No Ta 1 -.El +.El . . .Sh REFERENCE @@ -710,10 +909,9 @@ this macro is not implemented in .Ss \&%D Publication date of an .Sx \&Rs -block. This should follow the reduced syntax for +block. This should follow the reduced or canonical form syntax +described in .Sx Dates . -Canonical or non-canonical form is not necessary since publications are -often referenced only by year, or month and year. . .Ss \&%I Publisher or issuer name of an @@ -837,7 +1035,7 @@ a function: .Ed . .Ss \&Aq -Encloses its arguments in angled brackets. +Encloses its arguments in angled brackets. .Pp Examples: .Bd -literal -offset indent @@ -884,7 +1082,7 @@ Note that these parameters do not begin with a hyphen. .Pp Examples: .Bd -literal -offset indent -\&.At +\&.At \&.At V.1 .Ed .Pp @@ -985,7 +1183,60 @@ and .Ss \&Bf .Ss \&Bk .Ss \&Bl -. +.\" Begins a list composed of one or more list entries. A list entry is +.\" specified by the +.\" .Sx \&It +.\" macro, which consists of a head and optional body. By default, a list +.\" is preceded by a blank line. A list must specify one of the following +.\" list types: +.\" .Bl -tag -width 12n +.\" .It Fl bullet +.\" A list offset by a bullet. The head of list entries must be empty. +.\" List entry bodies are justified after the bullet. +.\" .It Fl column +.\" A columnated list. The number of columns is specified as arguments to +.\" the +.\" .Sx \&Bl +.\" macro (the deprecated form of following the invocation of +.\" .Fl column +.\" is also accepted). Arguments dictate the width of columns specified in +.\" list entries. List entry bodies must be left empty. Columns specified +.\" in the list entry head are justified to their position in the sequence +.\" of columns. +.\" .It Fl dash +.\" A list offset by a dash (hyphen). The head of list entries must be +.\" empty. List entry bodies are justified past the dash. +.\" .It Fl diag +.\" Like +.\" .Fl inset +.\" lists, but with additional formatting to the head. +.\" .It Fl enum +.\" A list offset by a number indicating list entry position. The head of +.\" list entries must be empty. List entry bodies are justified past the +.\" enumeration. +.\" .It Fl hang +.\" Like +.\" .Fl tag , +.\" but instead of list bodies justifying to the head on the first line, +.\" they trail the head text. +.\" .It Fl hyphen +.\" Synonym for +.\" .Fl dash . +.\" .It Fl inset +.\" Like +.\" .Fl tag , +.\" but list entry bodies aren't justified. +.\" .It Fl item +.\" An un-justified list. This produces blocks of text. +.\" .It Fl ohang +.\" List bodies are placed on the line following the head. +.\" .It Fl tag +.\" A list offset by list entry heads. List entry bodies are justified +.\" after the head. +.\" .El +.\" .Pp +.\" More... +.\" . .Ss \&Bo Begins a block enclosed by square brackets. Does not have any head arguments. @@ -1000,7 +1251,7 @@ See also .Sx \&Bq . . .Ss \&Bq -Encloses its arguments in square brackets. +Encloses its arguments in square brackets. .Pp Examples: .Bd -literal -offset indent @@ -1147,14 +1398,15 @@ manual. Its calling syntax is as follows: .Pp .D1 \. Ns Sx \&Dd Cm date .Pp -The +The .Cm date field may be either .Ar $\&Mdocdate$ , which signifies the current manual revision date dictated by -.Xr cvs 1 +.Xr cvs 1 , or instead a valid canonical date as specified by .Sx Dates . +If a date does not conform, the current date is used instead. .Pp Examples: .Bd -literal -offset indent @@ -1195,7 +1447,7 @@ See also .Sx \&Dq . . .Ss \&Dq -Encloses its arguments in double quotes. +Encloses its arguments in double quotes. .Pp Examples: .Bd -literal -offset indent @@ -1301,6 +1553,7 @@ subsequent that. It, too, is optional. It must be on .Ar hppa64 , .Ar i386 , .Ar landisk , +.Ar longsoon , .Ar luna88k , .Ar mac68k , .Ar macppc , @@ -1420,6 +1673,22 @@ is provided. .Ss \&Fc .Ss \&Fd .Ss \&Fl +Command-line flag. Used when listing arguments to command-line +utilities. Prints a fixed-width hyphen +.Sq \- +before each delimited argument. If no arguments are provided, a hyphen +is still printed. +.Pp +Examples: +.Bd -literal -offset indent +\&.Fl a b c +\&.Fl +\&.Op Fl o Ns Ar file +.Ed +.Pp +See also +.Sx \&Cm . +. .Ss \&Fn .Ss \&Fo .Ss \&Fr @@ -1633,9 +1902,58 @@ and . .Ss \&Va .Ss \&Vt +A variable type. This is also used for indicating global variables in the +SYNOPSIS section, in which case a variable name is also specified. Note that +it accepts +.Sx Block partial-implicit +syntax when invoked as the first macro in the SYNOPSIS section, else it +accepts ordinary +.Sx In-line +syntax. +.Pp +Note that this should not be confused with +.Sx \&Ft , +which is used for function return types. +.Pp +Examples: +.Bd -literal -offset indent +\&.Vt unsigned char +\&.Vt extern const char * const sys_signame[] ; +.Ed +.Pp +See also +.Sx \&Ft +and +.Sx \&Va . +. .Ss \&Xc .Ss \&Xo .Ss \&Xr +Link to another manual +.Pq Qq cross-reference . +Its calling syntax is +.Pp +.D1 \. Ns Sx \&Xr Cm name section +.Pp +The +.Cm name +and +.Cm section +are the name and section of the linked manual. If +.Cm section +is followed by non-punctuation, an +.Sx \&Ns +is inserted into the token stream. This behaviour is for compatibility +with +.Xr groff 1 . +.Pp +Examples: +.Bd -literal -offset indent +\&.Xr mandoc 1 +\&.Xr mandoc 1 ; +\&.Xr mandoc 1 s behaviour +.Ed +. .Ss \&br .Ss \&sp . @@ -1654,9 +1972,33 @@ file re-write .Pp .Bl -dash -compact .It +The comment syntax +.Sq \e." +is no longer accepted. +.It +In +.Xr groff 1 , +the +.Sx \&Pa +macro does not format its arguments when used in the FILES section under +certain list types. This irregular behaviour has been discontinued. +.It +Historic +.Xr groff 1 +does not print a dash for empty +.Sx \&Fl +arguments. This behaviour has been discontinued. +.It +.Xr groff 1 +behaves strangely (even between versions) when specifying +.Sq \ef +escapes within line-macro scopes. These aberrations have been +normalised. +.It Negative scaling units are now truncated to zero instead of creating interesting conditions, such as with -.Sq \&sp -1i . +.Sx \&sp +.Fl 1i . Furthermore, the .Sq f scaling unit, while accepted, is rendered as the default unit. @@ -1666,7 +2008,8 @@ standalone double-quote in formatted output. This idi behaviour is no longer applicable. .It Display types -.Sx \&Bd Fl center +.Sx \&Bd +.Fl center and .Fl right are aliases for @@ -1696,7 +2039,8 @@ made historic groff .Qq go orbital but is a proper delimiter in this implementation. .It -.Sx \&It Fl nested +.Sx \&It +.Fl nested is assumed for all lists (it wasn't in historic groff): any list may be nested and .Fl enum