Note discarding of \m, \M, and \s in COMPATIBILITY sections.

[mandoc.git] / man.7

diff --git a/man.7 b/man.7
index c8dbd900641f2e1bd1425e7840ce3b2ec7dc713a..a0ece476109978f83aa123dd6a0c15b911f9ee7b 100644 (file)
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"    $Id: man.7,v 1.70 2010/05/14 16:19:26 kristaps Exp $
+.\"    $Id: man.7,v 1.77 2010/07/19 10:48:36 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"


@@ -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: May 14 2010 $
+.Dd $Mdocdate: July 19 2010 $

 .Dt MAN 7
 .Os
 .Sh NAME
 .Dt MAN 7
 .Os
 .Sh NAME


@@ -61,11 +61,11 @@ Blank lines are acceptable; where found, the output will assert a
 vertical space.
 .Ss Comments
 Text following a
 vertical space.
 .Ss Comments
 Text following a

-.Sq \e\*" ,
+.Sq \e\*q ,

 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,
 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" ,
+.Sq \&.\e\*q ,

 is also ignored.
 Macro lines with only a control character and optionally whitespace are
 stripped from input.
 is also ignored.
 Macro lines with only a control character and optionally whitespace are
 stripped from input.


@@ -106,32 +106,9 @@ Note that macros like
 .Sx \&BR
 open and close a font scope with each argument.
 .Pp
 .Sx \&BR
 open and close a font scope with each argument.
 .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
-Both
-.Sq \es
-and
+The

 .Sq \ef
 .Sq \ef

-attributes are forgotten when entering or exiting a macro block.
+attribute is forgotten when entering or exiting a macro block.

 .Ss Whitespace
 Whitespace consists of the space character.
 In free-form lines, whitespace is preserved within a line; un-escaped
 .Ss Whitespace
 Whitespace consists of the space character.
 In free-form lines, whitespace is preserved within a line; un-escaped


@@ -216,8 +193,13 @@ literal text.
 When composing a manual, make sure that your sentences end at the end of
 a line.
 By doing so, front-ends will be able to apply the proper amount of
 When composing a manual, make sure that your sentences end at the end of
 a line.
 By doing so, front-ends will be able to apply the proper amount of

-spacing after the end of sentence (unescaped) period, exclamation, or question
-mark.
+spacing after the end of sentence (unescaped) period, exclamation mark,
+or question mark followed by zero or more non-sentence closing
+delimiters (
+.Ns Sq \&) ,
+.Sq \&] ,
+.Sq \&' ,
+.Sq \&" ) .

 .Sh MANUAL STRUCTURE
 Each
 .Nm
 .Sh MANUAL STRUCTURE
 Each
 .Nm


@@ -233,18 +215,14 @@ at least one macro or text node must appear in the document.
 Documents are generally structured as follows:
 .Bd -literal -offset indent
 \&.TH FOO 1 2009-10-10
 Documents are generally structured as follows:
 .Bd -literal -offset indent
 \&.TH FOO 1 2009-10-10

-\&.

 \&.SH NAME
 \efBfoo\efR \e(en a description goes here
 \&.\e\*q The next is for sections 2 & 3 only.
 \&.\e\*q .SH LIBRARY
 \&.SH NAME
 \efBfoo\efR \e(en a description goes here
 \&.\e\*q The next is for sections 2 & 3 only.
 \&.\e\*q .SH LIBRARY

-\&.

 \&.SH SYNOPSIS
 \efBfoo\efR [\efB\e-options\efR] arguments...
 \&.SH SYNOPSIS
 \efBfoo\efR [\efB\e-options\efR] arguments...

-\&.

 \&.SH DESCRIPTION
 The \efBfoo\efR utility processes files...
 \&.SH DESCRIPTION
 The \efBfoo\efR utility processes files...

-\&.

 \&.\e\*q .SH IMPLEMENTATION NOTES
 \&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .SH RETURN VALUES
 \&.\e\*q .SH IMPLEMENTATION NOTES
 \&.\e\*q The next is for sections 2, 3, & 9 only.
 \&.\e\*q .SH RETURN VALUES


@@ -429,6 +407,7 @@ The syntax is as follows:
 .Pp
 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"
 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes
 .Pp
 .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX"
 .It Em Macro Ta Em Arguments Ta Em Scope     Ta Em Notes

+.It Sx \&AT  Ta    <=1       Ta    current   Ta    \&

 .It Sx \&B   Ta    n         Ta    next-line Ta    \&
 .It Sx \&BI  Ta    n         Ta    current   Ta    \&
 .It Sx \&BR  Ta    n         Ta    current   Ta    \&
 .It Sx \&B   Ta    n         Ta    next-line Ta    \&
 .It Sx \&BI  Ta    n         Ta    current   Ta    \&
 .It Sx \&BR  Ta    n         Ta    current   Ta    \&


@@ -443,7 +422,7 @@ The syntax is as follows:
 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
 .It Sx \&SB  Ta    n         Ta    next-line Ta    \&
 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&

-.\" .It Sx \&UC  Ta    n         Ta    current   Ta    compat
+.It Sx \&UC  Ta    <=1       Ta    current   Ta    \&

 .It Sx \&br  Ta    0         Ta    current   Ta    compat
 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
 .It Sx \&i   Ta    n         Ta    current   Ta    compat
 .It Sx \&br  Ta    0         Ta    current   Ta    compat
 .It Sx \&fi  Ta    0         Ta    current   Ta    compat
 .It Sx \&i   Ta    n         Ta    current   Ta    compat


@@ -524,6 +503,11 @@ This section is a canonical reference to all macros, arranged
 alphabetically.
 For the scoping of individual macros, see
 .Sx MACRO SYNTAX .
 alphabetically.
 For the scoping of individual macros, see
 .Sx MACRO SYNTAX .

+.Ss \&AT
+Sets the volume for the footer for compatibility with man pages from
+.Tn AT&T UNIX
+releases.
+The optional arguments specify which release it is from.

 .Ss \&B
 Text is rendered in bold face.
 .Pp
 .Ss \&B
 Text is rendered in bold face.
 .Pp


@@ -798,8 +782,9 @@ arguments must be provided.
 The
 .Cm date
 argument should be formatted as described in
 The
 .Cm date
 argument should be formatted as described in

-.Sx Dates :
-if it does not conform, the current date is used instead.
+.Sx Dates ,
+but will be printed verbatim if it is not.
+If the date is not specified, the current date is used.

 The
 .Cm source
 string specifies the organisation providing the utility.
 The
 .Cm source
 string specifies the organisation providing the utility.


@@ -842,8 +827,10 @@ and
 .\" Has no effect.  Included for compatibility.
 .\" .
 .\" .
 .\" Has no effect.  Included for compatibility.
 .\" .
 .\" .

-.\" .Ss \&UC
-.\" Has no effect.  Included for compatibility.
+.Ss \&UC
+Sets the volume for the footer for compatibility with man pages from
+BSD releases.
+The optional first argument specifies which release it is from.

 .Ss \&br
 Breaks the current line.
 Consecutive invocations have no further effect.
 .Ss \&br
 Breaks the current line.
 Consecutive invocations have no further effect.


@@ -923,6 +910,9 @@ language.
 .Pp
 .Bl -dash -compact
 .It
 .Pp
 .Bl -dash -compact
 .It

+The \es (font size), \em (font colour), and \eM (font filling colour)
+font decoration escapes are all discarded in mandoc.
+.It

 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
 a standalone double-quote in formatted output.
 It is not known whether this behaviour is exhibited by other formatters.
 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
 a standalone double-quote in formatted output.
 It is not known whether this behaviour is exhibited by other formatters.