===================================================================
RCS file: /cvs/mandoc/man.7,v
retrieving revision 1.93
retrieving revision 1.104
diff -u -p -r1.93 -r1.104
--- mandoc/man.7	2010/12/29 16:18:13	1.93
+++ mandoc/man.7	2011/08/17 22:20:14	1.104
@@ -1,4 +1,4 @@
-.\"	$Id: man.7,v 1.93 2010/12/29 16:18:13 kristaps Exp $
+.\"	$Id: man.7,v 1.104 2011/08/17 22:20:14 kristaps Exp $
 .\"
 .\" Copyright (c) 2009, 2010 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: December 29 2010 $
+.Dd $Mdocdate: August 17 2011 $
 .Dt MAN 7
 .Os
 .Sh NAME
@@ -49,28 +49,41 @@ prior macros:
 \&.SH Macro lines change control state.
 Other lines are interpreted within the current state.
 .Ed
-.Sh INPUT ENCODING
+.Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the
 space character, and the tab character.
-All manuals must have
-.Ux
-line termination.
-.Pp
-Blank lines are acceptable; where found, the output will assert a
-vertical space.
+The back-space character
+.Sq \e
+indicates the start of an escape sequence for
+.Sx Comments ,
+.Sx Predefined Strings ,
+and
+.Sx Special Characters .
 .Ss Comments
-Text following a
+Text following an escaped double-quote
 .Sq \e\*q ,
-whether in a macro or free-form text line, is ignored to the end of
+whether in a macro or text line, is ignored to the end of
 line.
-A macro line with only a control character and comment escape,
-.Sq \&.\e\*q ,
+A macro line beginning with a control character and comment escape
+.Sq \&.\e\*q
 is also ignored.
-Macro lines with only a control character and optionally whitespace are
+Furthermore,
+macro lines with only a control character and optional trailing
+whitespace are
 stripped from input.
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+\&.\e\*q This is a comment line.
+\&.\e\*q The next line is ignored:
+\&.
+\&.Em Emphasis \e\*q This is also a comment.
+.Ed
 .Ss Special Characters
-Special characters may occur in both macro and free-form lines.
+Special characters are used to encode special glyphs and are rendered
+differently across output media.
+They may occur in both macro and text lines.
 Sequences begin with the escape character
 .Sq \e
 followed by either an open-parenthesis
@@ -79,25 +92,25 @@ for two-character sequences; an open-bracket
 .Sq \&[
 for n-character sequences (terminated at a close-bracket
 .Sq \&] ) ;
-or a single one-character sequence.
+or a single one character sequence.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \e(em
+em dash
+.It \ee
+backslash
+.El
+.Pp
 See
 .Xr mandoc_char 7
 for a complete list.
-Examples include
-.Sq \e(em
-.Pq em-dash
-and
-.Sq \ee
-.Pq back-slash .
 .Ss Text Decoration
 Terms may be text-decorated using the
 .Sq \ef
-escape followed by an indicator: B (bold), I (italic), R (Roman), or P
+escape followed by an indicator: B (bold), I (italic), R (regular), or P
 (revert to previous mode):
-.Pp
-.D1 \efBbold\efR \efIitalic\efP
-.Pp
-A numerical representation 3, 2, or 1 (bold, italic, and Roman,
+A numerical representation 3, 2, or 1 (bold, italic, and regular,
 respectively) may be used instead.
 A text decoration is only valid, if specified in free-form text, until
 the next macro invocation; if specified within a macro, it's only valid
@@ -109,35 +122,80 @@ open and close a font scope with each argument.
 The
 .Sq \ef
 attribute is forgotten when entering or exiting a macro block.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \efBbold\efR
+write in bold, then switch to regular
+.It \efIitalic\efP
+write in italic, then return to previous
+.El
+.Ss Predefined Strings
+Predefined strings, like
+.Sx Special Characters ,
+mark special output glyphs.
+Predefined strings are escaped with the slash-asterisk,
+.Sq \e* :
+single-character
+.Sq \e*X ,
+two-character
+.Sq \e*(XX ,
+and N-character
+.Sq \e*[N] .
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \e*(Am
+ampersand
+.It \e*(Ba
+vertical bar
+.El
+.Pp
+These strings are set using
+.Xr roff 7 ,
+although
+.Nm
+consists of several pre-set escapes listed in
+.Xr mandoc_char 7 .
 .Ss Whitespace
 Whitespace consists of the space character.
-In free-form lines, whitespace is preserved within a line; unescaped
-trailing spaces are stripped from input (unless in a literal context).
-Blank free-form lines, which may include spaces, are permitted and
-rendered as an empty line.
-.Pp
+In text lines, whitespace is preserved within a line.
 In macro lines, whitespace delimits arguments and is discarded.
-If arguments are quoted, whitespace within the quotes is retained.
-.Ss Dates
-The
-.Sx \&TH
-macro is the only
-.Nm
-macro that requires a date.
-The form for this date is the ISO-8601
-standard
-.Cm YYYY-MM-DD .
-.Ss Scaling Widths
-Many macros support scaled widths for their arguments, such as
-stipulating a two-inch paragraph indentation with the following:
-.Bd -literal -offset indent
-\&.HP 2i
-.Ed
 .Pp
-The syntax for scaled widths is
-.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? ,
+Unescaped trailing spaces are stripped from text line input unless in a
+literal context.
+In general, trailing whitespace on any input line is discouraged for
+reasons of portability.
+In the rare case that a blank character is needed at the end of an
+input line, it may be forced by
+.Sq \e\ \e& .
+.Pp
+If the first character of a text line is a space, that line is printed
+with a leading newline.
+.Ss Quotation
+Macro arguments may be quoted with double-quotes; in this case,
+whitespace within the quotes is retained as part of the argument.
+.Pp
+A quoted argument begins with a double-quote preceded by whitespace.
+The next double-quote not pairwise adjacent to another double-quote
+terminates the literal, regardless of surrounding whitespace.
+.Pp
+In unquoted arguments, space characters can alternatively be included
+by preceding them with a backslash
+.Pq Sq \e\~ ,
+but quoting is usually better for clarity.
+.Pp
+Note that any quoted text, even if it would cause a macro invocation
+when unquoted, is considered literal text.
+.Pp
+In text lines, quotes are regarded as opaque text.
+.Ss Scaling Widths
+Many macros support scaled widths for their arguments.
+The syntax for a scaled width is
+.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
 where a decimal must be preceded or proceeded by at least one digit.
 Negative numbers, while accepted, are truncated to zero.
+.Pp
 The following scaling units are accepted:
 .Pp
 .Bl -tag -width Ds -offset indent -compact
@@ -177,6 +235,8 @@ Using anything other than
 or
 .Sq v
 is necessarily non-portable across output media.
+See
+.Sx COMPATIBILITY .
 .Pp
 If a scaling unit is not provided, the numerical value is interpreted
 under the default rules of
@@ -184,15 +244,19 @@ under the default rules of
 for vertical spaces and
 .Sq u
 for horizontal ones.
-.Em Note :
-this differs from
-.Xr mdoc 7 ,
-which, if a unit is not provided, will instead interpret the string as
-literal text.
+.Pp
+Examples:
+.Bl -tag -width Ds -offset indent -compact
+.It \&.HP 2i
+two-inch tagged list indentation
+.Pq see Sx \&HP
+.It \&.sp 2v
+two vertical spaces
+.Pq see Sx \&sp
+.El
 .Ss Sentence Spacing
-When composing a manual, make sure that sentences end at the end of
-a line.
-By doing so, front-ends will be able to apply the proper amount of
+Sentences should terminate at the end of an input line.
+By doing this, a formatter 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
@@ -202,6 +266,13 @@ delimiters
 .Sq \&' ,
 .Sq \&"
 .Pc .
+.Pp
+Examples:
+.Bd -literal -offset indent -compact
+Do not end sentences mid-line like this.  Instead,
+end a sentence like this.
+A new sentence gets a new line.
+.Ed
 .Sh MANUAL STRUCTURE
 Each
 .Nm
@@ -214,16 +285,20 @@ appears as the first macro.
 Beyond
 .Sx \&TH ,
 at least one macro or text node must appear in the document.
-Documents are generally structured as follows:
+.Pp
+The following is a well-formed skeleton
+.Nm
+file for a utility
+.Qq progname :
 .Bd -literal -offset indent
-\&.TH FOO 1 2009-10-10
+\&.TH PROGNAME 1 2009-10-10
 \&.SH NAME
-\efBfoo\efR \e(en a description goes here
+\efBprogname\efR \e(en a description goes here
 \&.\e\*q .SH LIBRARY
 \&.\e\*q For sections 2 & 3 only.
 \&.\e\*q Not used in OpenBSD.
 \&.SH SYNOPSIS
-\efBfoo\efR [\efB\e-options\efR] arguments...
+\efBprogname\efR [\efB\e-options\efR] arguments...
 \&.SH DESCRIPTION
 The \efBfoo\efR utility processes files...
 \&.\e\*q .SH IMPLEMENTATION NOTES
@@ -370,6 +445,13 @@ Thus, the following are equivalent:
 \&.\ \ \ PP
 .Ed
 .Pp
+To include space characters in macro arguments, arguments may be quoted;
+see the
+.Sq MACRO SYNTAX
+section in the
+.Xr roff 7
+manual for details.
+.Pp
 The
 .Nm
 macros are classified by scope: line scope or block scope.
@@ -705,6 +787,9 @@ and
 .Ss \&RE
 Explicitly close out the scope of a prior
 .Sx \&RS .
+The default left margin is restored to the state of the original
+.Sx \&RS
+invocation.
 .Ss \&RI
 Text is rendered alternately in roman (the default font) and italics.
 Whitespace between arguments is omitted in output.
@@ -721,13 +806,10 @@ See also
 and
 .Sx \&IR .
 .Ss \&RS
-Begin a part setting the left margin.
-The left margin controls the offset, following an initial indentation,
-to un-indented text such as that of
-.Sx \&PP .
+Temporarily reset the default left margin.
 This has the following syntax:
 .Bd -filled -offset indent
-.Pf \. Sx \&Rs
+.Pf \. Sx \&RS
 .Op Cm width
 .Ed
 .Pp
@@ -736,6 +818,9 @@ The
 argument must conform to
 .Sx Scaling Widths .
 If not specified, the saved or default width is used.
+.Pp
+See also
+.Sx \&RE .
 .Ss \&SB
 Text is rendered in small size (one point smaller than the default font)
 bold face.
@@ -756,26 +841,27 @@ The paragraph left-margin width is reset to the defaul
 Sets the title of the manual page with the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&TH
-.Cm title section
-.Op Cm date Op Cm source Op Cm volume
+.Ar title section date
+.Op Ar source Op Ar volume
 .Ed
 .Pp
-At least the upper-case document
-.Cm title
-and the manual
-.Cm section
-arguments must be provided.
-The
-.Cm date
-argument should be formatted as described in
-.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
+Conventionally, the document
+.Ar title
+is given in all caps.
+The recommended
+.Ar date
+format is
+.Sy YYYY-MM-DD
+as specified in the ISO-8601 standard;
+if the argument does not conform, it is printed verbatim.
+If the
+.Ar date
+is empty or not specified, the current date is used.
+The optional
+.Ar source
 string specifies the organisation providing the utility.
 The
-.Cm volume
+.Ar volume
 string replaces the default rendered volume, which is dictated by the
 manual section.
 .Pp
@@ -842,6 +928,10 @@ Begin literal mode: all subsequent free-form lines hav
 line boundaries preserved.
 May be ended by
 .Sx \&fi .
+Literal mode is implicitly ended by
+.Sx \&SH
+or
+.Sx \&SS .
 .Ss \&sp
 Insert vertical spaces into output with the following syntax:
 .Bd -filled -offset indent
@@ -912,8 +1002,11 @@ In GNU troff, this would result in strange behaviour.
 .Sh SEE ALSO
 .Xr man 1 ,
 .Xr mandoc 1 ,
+.Xr eqn 7 ,
 .Xr mandoc_char 7 ,
-.Xr mdoc 7
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 7
 .Sh HISTORY
 The
 .Nm