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

[mandoc.git] / man.7

diff --git a/man.7 b/man.7
index c893f2f06b04dfdd71e01ca6d5e44836e56c6929..a0ece476109978f83aa123dd6a0c15b911f9ee7b 100644 (file)
--- a/man.7
+++ b/man.7
@@ -1,4 +1,4 @@
-.\"    $Id: man.7,v 1.68 2010/05/12 16:52:33 kristaps Exp $
+.\"    $Id: man.7,v 1.77 2010/07/19 10:48:36 kristaps Exp $
 .\"
 .\" 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.
 .\"
-.Dd $Mdocdate: May 12 2010 $
+.Dd $Mdocdate: July 19 2010 $
 .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
-.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,
-.Sq \&.\e" ,
+.Sq \&.\e\*q ,
 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
-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
-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
@@ -212,6 +189,17 @@ this differs from
 .Xr mdoc 7 ,
 which, if a unit is not provided, will instead interpret the string as
 literal text.
+.Ss Sentence Spacing
+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 mark,
+or question mark followed by zero or more non-sentence closing
+delimiters (
+.Ns Sq \&) ,
+.Sq \&] ,
+.Sq \&' ,
+.Sq \&" ) .
 .Sh MANUAL STRUCTURE
 Each
 .Nm
@@ -227,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
-\&.
 \&.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 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
@@ -423,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
+.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    \&
@@ -437,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 \&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
@@ -445,7 +430,7 @@ The syntax is as follows:
 .It Sx \&nf  Ta    0         Ta    current   Ta    compat
 .It Sx \&r   Ta    0         Ta    current   Ta    compat
 .It Sx \&sp  Ta    1         Ta    current   Ta    compat
-.\" .It Sx \&Sp  Ta    0         Ta    current   Ta    compat
+.\" .It Sx \&Sp  Ta    <1        Ta    current   Ta    compat
 .\" .It Sx \&Vb  Ta    <1        Ta    current   Ta    compat
 .\" .It Sx \&Ve  Ta    0         Ta    current   Ta    compat
 .El
@@ -518,6 +503,11 @@ This section is a canonical reference to all macros, arranged
 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
@@ -792,8 +782,9 @@ arguments must be provided.
 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.
@@ -836,8 +827,10 @@ and
 .\" 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.
@@ -917,6 +910,9 @@ language.
 .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.