Noted non-accepted comment syntax (thanks Joerg Sonnenberger).

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index c7e6f92438065a338dcfca51de857aa9281cb5b0..84dad13e71782f72c5975cdd853916060ecc2eed 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.73 2009/11/02 11:39:40 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.81 2010/01/01 16:52:00 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: January 1 2010 $

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


@@ -131,10 +131,50 @@ 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


@@ -379,6 +419,11 @@ The
 macro(s) must precede the
 .Sx \&Nd
 macro.
 macro(s) must precede the
 .Sx \&Nd
 macro.

+.Pp
+See 
+.Sx \&Nm
+and
+.Sx \&Nd .

 .
 .It Em LIBRARY
 The name of the library containing the documented material, which is
 .
 .It Em LIBRARY
 The name of the library containing the documented material, which is


@@ -389,8 +434,7 @@ this is as follows:
 .Ed
 .Pp
 See
 .Ed
 .Pp
 See

-.Sx \&Lb
-for details.
+.Sx \&Lb .

 .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
 .
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device


@@ -427,6 +471,14 @@ And for the third, configurations (section 4):
 .Pp
 Manuals not in these sections generally don't need a 
 .Em SYNOPSIS .
 .Pp
 Manuals not in these sections generally don't need a 
 .Em SYNOPSIS .

+.Pp
+See 
+.Sx \&Op ,
+.Sx \&Cd ,
+.Sx \&Fn ,
+.Sx \&Ft ,
+and
+.Sx \&Vt .

 .
 .It Em DESCRIPTION
 This expands upon the brief, one-line description in 
 .
 .It Em DESCRIPTION
 This expands upon the brief, one-line description in 


@@ -440,6 +492,7 @@ The arguments are as follows:
 Print verbose information.
 \&.El
 .Ed
 Print verbose information.
 \&.El
 .Ed

+.Pp

 Manuals not documenting a command won't include the above fragment.
 .
 .It Em IMPLEMENTATION NOTES
 Manuals not documenting a command won't include the above fragment.
 .
 .It Em IMPLEMENTATION NOTES


@@ -495,7 +548,8 @@ for manuals in sections 1, 6, and 8; however, this practise is
 discouraged.
 .Pp
 See
 discouraged.
 .Pp
 See

-.Sx \&Bl No \-diag .
+.Sx \&Bl
+.Fl diag .

 .
 .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.
 .
 .It Em ERRORS
 Documents error handling in sections 2, 3, and 9.


@@ -1120,7 +1174,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.


@@ -1556,6 +1663,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


@@ -1790,9 +1913,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.


@@ -1802,7 +1949,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


@@ -1832,7 +1980,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