Added news item for new version.

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 6372968ad52aea9602b9c9ff5f903658487672f4..ce0a001aa440690fc03a3775f9f90f24a6a0f9ef 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.72 2009/11/02 06:22:45 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.84 2010/02/17 19:22:50 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"


@@ -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.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: November 2 2009 $
+.Dd $Mdocdate: February 17 2010 $

 .Dt MDOC 7
 .Os
 .
 .Dt MDOC 7
 .Os
 .


@@ -131,18 +131,58 @@ and
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
 .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 ,
 .Nm ,

-which encourages semantic, not presentation, annotation.
+which encourages semantic annotation.

 .
 .
 .Ss Predefined Strings
 .
 .
 .Ss Predefined Strings

-Historically, 
+Historically,

 .Xr groff 1
 .Xr groff 1

-also defined a set of package-specific 
+also defined a set of package-specific

 .Dq predefined strings ,
 .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,
 .Sx Special Characters ,
 demark special output characters and strings by way of input codes.
 Predefined strings are escaped with the slash-asterisk,


@@ -303,7 +343,7 @@ and
 .Sx \&Os
 macros, is required for every document.
 .Pp
 .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
 .Sx \&Sh )
 must be the NAME section, consisting of at least one
 .Sx \&Nm


@@ -363,38 +403,199 @@ The sections in a
 .Nm
 document are conventionally ordered as they appear above.  Sections
 should be composed as follows:
 .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
 .Sx \&Nm

-followed by
+macro(s) must precede the
+.Sx \&Nd
+macro.
+.Pp
+See
+.Sx \&Nm
+and

 .Sx \&Nd .
 .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
 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
 .
 .
 .El
 .
 .


@@ -482,7 +683,7 @@ All macros have bodies; some
 don't have heads; only one
 .Po
 .Sx \&It Fl column
 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
 has multiple heads.
 .Bd -literal -offset indent
 \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB


@@ -569,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 \&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
 .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
 .
 .
 .Ss In-line


@@ -662,10 +872,10 @@ then the macro accepts an arbitrary number of arguments.
 .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 \&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
 .It Sx \&br  Ta    \&No     Ta    \&No     Ta    0
 .It Sx \&sp  Ta    \&No     Ta    \&No     Ta    1

-.El   
+.El

 .
 .
 .Sh REFERENCE
 .
 .
 .Sh REFERENCE


@@ -825,7 +1035,7 @@ a function:
 .Ed
 .
 .Ss \&Aq
 .Ed
 .
 .Ss \&Aq

-Encloses its arguments in angled brackets.  
+Encloses its arguments in angled brackets.

 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent


@@ -872,7 +1082,7 @@ Note that these parameters do not begin with a hyphen.
 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent

-\&.At 
+\&.At

 \&.At V.1
 .Ed
 .Pp
 \&.At V.1
 .Ed
 .Pp


@@ -973,7 +1183,60 @@ and
 .Ss \&Bf
 .Ss \&Bk
 .Ss \&Bl
 .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.
 .Ss \&Bo
 Begins a block enclosed by square brackets.  Does not have any head
 arguments.


@@ -988,7 +1251,7 @@ See also
 .Sx \&Bq .
 .
 .Ss \&Bq
 .Sx \&Bq .
 .
 .Ss \&Bq

-Encloses its arguments in square brackets.  
+Encloses its arguments in square brackets.

 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent


@@ -1135,7 +1398,7 @@ manual.  Its calling syntax is as follows:
 .Pp
 .D1 \. Ns Sx \&Dd Cm date
 .Pp
 .Pp
 .D1 \. Ns Sx \&Dd Cm date
 .Pp

-The 
+The

 .Cm date
 field may be either
 .Ar $\&Mdocdate$ ,
 .Cm date
 field may be either
 .Ar $\&Mdocdate$ ,


@@ -1184,7 +1447,7 @@ See also
 .Sx \&Dq .
 .
 .Ss \&Dq
 .Sx \&Dq .
 .
 .Ss \&Dq

-Encloses its arguments in double quotes.  
+Encloses its arguments in double quotes.

 .Pp
 Examples:
 .Bd -literal -offset indent
 .Pp
 Examples:
 .Bd -literal -offset indent


@@ -1409,6 +1672,22 @@ is provided.
 .Ss \&Fc
 .Ss \&Fd
 .Ss \&Fl
 .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
 .Ss \&Fn
 .Ss \&Fo
 .Ss \&Fr


@@ -1622,9 +1901,58 @@ and
 .
 .Ss \&Va
 .Ss \&Vt
 .
 .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
 .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
 .
 .Ss \&br
 .Ss \&sp
 .


@@ -1643,9 +1971,33 @@ file re-write
 .Pp
 .Bl -dash -compact
 .It
 .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
 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.
 Furthermore, the
 .Sq f
 scaling unit, while accepted, is rendered as the default unit.


@@ -1655,7 +2007,8 @@ standalone double-quote in formatted output.  This idiosyncratic
 behaviour is no longer applicable.
 .It
 Display types
 behaviour is no longer applicable.
 .It
 Display types

-.Sx \&Bd Fl center
+.Sx \&Bd
+.Fl center

 and
 .Fl right
 are aliases for
 and
 .Fl right
 are aliases for


@@ -1685,7 +2038,8 @@ made historic groff
 .Qq go orbital
 but is a proper delimiter in this implementation.
 .It
 .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
 is assumed for all lists (it wasn't in historic groff): any list may be
 nested and
 .Fl enum