mandoc: Massively reduce the amount of text, cutting it down to what is

mandoc: Massively reduce the amount of text, cutting it down to what is

[schwarze]

Log Message:
-----------
Massively reduce the amount of text, cutting it down to what is needed
to understand existing man(7) code and deleting parts that would only
be useful for writing new documents, which we strongly discourage:

* Delete the MANUAL STRUCTURE section which merely duplicates mdoc(7).
* Delete internal cross references only useful for writing new code.
* Delete many instances of "included only for compatibility" as the
  whole language is only provided for compatibility.
* Fix a few minor errors and omissions.

Modified Files:
--------------
    mandoc:
        man.7

Revision Data
-------------
Index: man.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man.7,v
retrieving revision 1.139
retrieving revision 1.140
diff -Lman.7 -Lman.7 -u -p -r1.139 -r1.140
--- man.7
+++ man.7
@@ -24,24 +24,13 @@
 .Nm man
 .Nd legacy formatting language for manual pages
 .Sh DESCRIPTION
-Traditionally, the
+The
 .Nm man
-language has been used to write
-.Ux
-manuals for the
-.Xr man 1
-utility.
-It supports limited control of presentational details like fonts,
-indentation and spacing.
-This reference document describes the structure of manual pages
-and the syntax and usage of the man language.
-.Pp
-.Bf -emphasis
-Do not use
-.Nm
-to write your manuals:
-.Ef
-It lacks support for semantic markup.
+language was the standard formatting language for
+.At
+manual pages from 1979 to 1989.
+Do not use it to write new manual pages: it is a purely presentational
+language and lacks support for semantic markup.
 Use the
 .Xr mdoc 7
 language, instead.
@@ -54,7 +43,7 @@ are called
 .Dq macro lines .
 The first word is the macro name.
 It usually consists of two capital letters.
-For a list of available macros, see
+For a list of portable macros, see
 .Sx MACRO OVERVIEW .
 The words following the macro name are arguments to the macro.
 .Pp
@@ -79,189 +68,35 @@ sections in the
 .Xr roff 7
 manual for details, in particular regarding
 comments, escape sequences, whitespace, and quoting.
-.Sh MANUAL STRUCTURE
+.Pp
 Each
 .Nm
-document must contain the
+document starts with the
 .Sx \&TH
-macro describing the document's section and title.
-It may occur anywhere in the document, although conventionally it
-appears as the first macro.
-.Pp
-Beyond
-.Sx \&TH ,
-at least one macro or text line must appear in the document.
-.Pp
-The following is a well-formed skeleton
-.Nm
-file for a utility
-.Qq progname :
+macro specifying the document's name and section, followed by the
+.Sx NAME
+section formatted as follows:
 .Bd -literal -offset indent
-\&.TH PROGNAME 1 2009-10-10
+\&.TH PROGNAME 1 1979-01-10
 \&.SH NAME
 \efBprogname\efR \e(en one line about what it does
-\&.\e\(dq .SH LIBRARY
-\&.\e\(dq For sections 2, 3, and 9 only.
-\&.\e\(dq Not used in OpenBSD.
-\&.SH SYNOPSIS
-\efBprogname\efR [\efB\e-options\efR] \efIfile ...\efR
-\&.SH DESCRIPTION
-The \efBfoo\efR utility processes files ...
-\&.\e\(dq .Sh CONTEXT
-\&.\e\(dq For section 9 functions only.
-\&.\e\(dq .SH IMPLEMENTATION NOTES
-\&.\e\(dq Not used in OpenBSD.
-\&.\e\(dq .SH RETURN VALUES
-\&.\e\(dq For sections 2, 3, and 9 function return values only.
-\&.\e\(dq .SH ENVIRONMENT
-\&.\e\(dq For sections 1, 6, 7, and 8 only.
-\&.\e\(dq .SH FILES
-\&.\e\(dq .SH EXIT STATUS
-\&.\e\(dq For sections 1, 6, and 8 only.
-\&.\e\(dq .SH EXAMPLES
-\&.\e\(dq .SH DIAGNOSTICS
-\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
-\&.\e\(dq .SH ERRORS
-\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only.
-\&.\e\(dq .SH SEE ALSO
-\&.\e\(dq .BR foobar ( 1 )
-\&.\e\(dq .SH STANDARDS
-\&.\e\(dq .SH HISTORY
-\&.\e\(dq .SH AUTHORS
-\&.\e\(dq .SH CAVEATS
-\&.\e\(dq .SH BUGS
-\&.\e\(dq .SH SECURITY CONSIDERATIONS
-\&.\e\(dq Not used in OpenBSD.
 .Ed
-.Pp
-The sections in a
-.Nm
-document are conventionally ordered as they appear above.
-Sections should be composed as follows:
-.Bl -ohang -offset indent
-.It Em NAME
-The name(s) and a short description of the documented material.
-The syntax for this is generally as follows:
-.Pp
-.D1 \efBname\efR \e(en description
-.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.
-For functions in the C library, this may be as follows:
-.Pp
-.D1 Standard C Library (libc, -lc)
-.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:
-.Pp
-.D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
-.Pp
-For the second, function calls (sections 2, 3, 9):
-.Pp
-.D1 \&.B char *name(char *\efIarg\efR);
-.Pp
-And for the third, configurations (section 4):
-.Pp
-.D1 \&.B name* at cardbus ? function ?
-.Pp
-Manuals not in these sections generally don't need a
-.Em SYNOPSIS .
-.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).
-.It Em CONTEXT
-This section lists the contexts in which functions can be called in section 9.
-The contexts are autoconf, process, or interrupt.
-.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 RETURN VALUES
-This section documents the return values of functions in sections 2, 3, and 9.
-.It Em ENVIRONMENT
-Documents any usages of environment variables, e.g.,
-.Xr environ 7 .
-.It Em FILES
-Documents files used.
-It's helpful to document both the file name and a short description of how
-the file is used (created, modified, etc.).
-.It Em EXIT STATUS
-This section documents the command exit status for
-section 1, 6, and 8 utilities.
-Historically, this information was described in
-.Em DIAGNOSTICS ,
-a practise that is now discouraged.
-.It Em EXAMPLES
-Example usages.
-This often contains snippets of well-formed,
-well-tested invocations.
-Make sure that examples work properly!
-.It Em DIAGNOSTICS
-Documents error conditions.
-In section 4 and 9 manuals, these are usually messages
-printed by the kernel to the console and to the kernel log.
-In section 1, 6, 7, and 8, these are usually messages
-printed by userland programs to the standard error output.
-.Pp
-Historically, this section was used in place of
-.Em EXIT STATUS
-for manuals in sections 1, 6, and 8; however, this practise is
-discouraged.
-.It Em ERRORS
-Documents
-.Xr errno 2
-settings in sections 2, 3, 4, and 9.
-.It Em SEE ALSO
-References other manuals with related topics.
-This section should exist for most manuals.
-.Pp
-.D1 \&.BR bar \&( 1 \&),
-.Pp
-Cross-references should conventionally be ordered
-first by section, then alphabetically.
-.It Em STANDARDS
-References any standards implemented or used, such as
-.Pp
-.D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
-.Pp
-If not adhering to any standards, the
-.Em HISTORY
-section should be used.
-.It Em HISTORY
-A brief history of the subject, including where support first appeared.
-.It Em AUTHORS
-Credits to the person or persons who wrote the code and/or documentation.
-Authors should generally be noted by both name and email address.
-.It Em CAVEATS
-Common misuses and misunderstandings should be explained
-in this section.
-.It Em BUGS
-Known bugs, limitations, and work-arounds should be described
-in this section.
-.It Em SECURITY CONSIDERATIONS
-Documents any security precautions that operators should consider.
-.El
 .Sh MACRO OVERVIEW
 This overview is sorted such that macros of similar purpose are listed
-together, to help find the best macro for any given purpose.
-Deprecated macros are not included in the overview, but can be found
-in the alphabetical reference below.
+together.
+Deprecated and non-portable macros are not included in the overview,
+but can be found in the alphabetical reference below.
 .Ss Page header and footer meta-data
-.Bl -column "PP, LP, P" description
-.It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
+.Bl -column "RS, RE" description
+.It Sx TH Ta set the title: Ar name section date Op Ar source Op Ar volume
 .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
 .It Sx UC Ta display BSD version in the page footer (<= 1 argument)
 .El
 .Ss Sections and paragraphs
-.Bl -column "PP, LP, P" description
+.Bl -column "RS, RE" description
 .It Sx SH Ta section header (one line)
 .It Sx SS Ta subsection header (one line)
-.It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
+.It Sx PP Ta start an undecorated paragraph (no arguments)
 .It Sx RS , RE Ta reset the left margin: Op Ar width
 .It Sx IP Ta indented paragraph: Op Ar head Op Ar width
 .It Sx TP Ta tagged paragraph: Op Ar width
@@ -271,7 +106,7 @@ in the alphabetical reference below.
 .It Sx in Ta additional indent: Op Ar width
 .El
 .Ss Physical markup
-.Bl -column "PP, LP, P" description
+.Bl -column "RS, RE" description
 .It Sx B Ta boldface font
 .It Sx I Ta italic font
 .It Sx SB Ta small boldface font
@@ -295,9 +130,6 @@ releases.
 The optional arguments specify which release it is from.
 .Ss \&B
 Text is rendered in bold face.
-.Pp
-See also
-.Sx \&I .
 .Ss \&BI
 Text is rendered alternately in bold face and italic.
 Thus,
@@ -313,38 +145,14 @@ and
 render in italics.
 Whitespace between arguments is omitted in output.
 .Pp
-Examples:
+Example:
 .Pp
 .Dl \&.BI bold italic bold italic
-.Pp
-The output of this example will be emboldened
-.Dq bold
-and italicised
-.Dq italic ,
-with spaces stripped between arguments.
-.Pp
-See also
-.Sx \&IB ,
-.Sx \&BR ,
-.Sx \&RB ,
-.Sx \&RI ,
-and
-.Sx \&IR .
 .Ss \&BR
 Text is rendered alternately in bold face and roman (the default font).
 Whitespace between arguments is omitted in output.
-.Pp
-See
-.Sx \&BI
-for an equivalent example.
-.Pp
 See also
-.Sx \&BI ,
-.Sx \&IB ,
-.Sx \&RB ,
-.Sx \&RI ,
-and
-.Sx \&IR .
+.Sx \&BI .
 .Ss \&DT
 Restore the default tabulator positions.
 They are at intervals of 0.5 inches.
@@ -353,13 +161,13 @@ This has no effect unless the tabulator 
 .Ic \&ta
 request.
 .Ss \&EE
-This is a non-standard GNU extension, included only for compatibility.
+This is a non-standard GNU extension.
 In
 .Xr mandoc 1 ,
 it does the same as
 .Sx \&fi .
 .Ss \&EX
-This is a non-standard GNU extension, included only for compatibility.
+This is a non-standard GNU extension.
 In
 .Xr mandoc 1 ,
 it does the same as
@@ -379,34 +187,13 @@ argument is a
 scaling width.
 If specified, it's saved for later paragraph left-margins; if unspecified, the
 saved or default width is used.
-.Pp
-See also
-.Sx \&IP ,
-.Sx \&LP ,
-.Sx \&P ,
-.Sx \&PP ,
-and
-.Sx \&TP .
 .Ss \&I
 Text is rendered in italics.
-.Pp
-See also
-.Sx \&B .
 .Ss \&IB
 Text is rendered alternately in italics and bold face.
 Whitespace between arguments is omitted in output.
-.Pp
-See
-.Sx \&BI
-for an equivalent example.
-.Pp
 See also
-.Sx \&BI ,
-.Sx \&BR ,
-.Sx \&RB ,
-.Sx \&RI ,
-and
-.Sx \&IR .
+.Sx \&BI .
 .Ss \&IP
 Begin an indented paragraph with the following syntax:
 .Bd -filled -offset indent
@@ -426,50 +213,21 @@ The
 .Ar head
 argument is used as a leading term, flushed to the left margin.
 This is useful for bulleted paragraphs and so on.
-.Pp
-See also
-.Sx \&HP ,
-.Sx \&LP ,
-.Sx \&P ,
-.Sx \&PP ,
-and
-.Sx \&TP .
 .Ss \&IR
 Text is rendered alternately in italics and roman (the default font).
 Whitespace between arguments is omitted in output.
-.Pp
-See
-.Sx \&BI
-for an equivalent example.
-.Pp
 See also
-.Sx \&BI ,
-.Sx \&IB ,
-.Sx \&BR ,
-.Sx \&RB ,
-and
-.Sx \&RI .
+.Sx \&BI .
 .Ss \&LP
-Begin an undecorated paragraph.
-The scope of a paragraph is closed by a subsequent paragraph,
-sub-section, section, or end of file.
-The saved paragraph left-margin width is reset to the default.
-.Pp
-See also
-.Sx \&HP ,
-.Sx \&IP ,
-.Sx \&P ,
-.Sx \&PP ,
-and
-.Sx \&TP .
+A synonym for
+.Sx \&PP .
 .Ss \&ME
-End a mailto block.
-This is a non-standard GNU extension, included only for compatibility.
-See
+End a mailto block started with
 .Sx \&MT .
+This is a non-standard GNU extension.
 .Ss \&MT
 Begin a mailto block.
-This is a non-standard GNU extension, included only for compatibility.
+This is a non-standard GNU extension.
 It has the following syntax:
 .Bd -literal -offset indent
 .Pf \. Sx \&MT Ar address
@@ -478,7 +236,7 @@ link description to be shown
 .Ed
 .Ss \&OP
 Optional command-line argument.
-This is a non-standard GNU extension, included only for compatibility.
+This is a non-standard GNU extension.
 It has the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&OP
@@ -491,16 +249,8 @@ is usually a command-line flag and
 .Ar value
 its argument.
 .Ss \&P
-Synonym for
-.Sx \&LP .
-.Pp
-See also
-.Sx \&HP ,
-.Sx \&IP ,
-.Sx \&LP ,
-.Sx \&PP ,
-and
-.Sx \&TP .
+A synonym for
+.Sx \&PP .
 .Ss \&PD
 Specify the vertical space to be inserted before each new paragraph.
 .br
@@ -529,34 +279,19 @@ This macro affects the spacing before an
 .Sx \&PP ,
 .Sx \&SH ,
 .Sx \&SS ,
+.Sx \&SY ,
 and
 .Sx \&TP .
 .Ss \&PP
-Synonym for
-.Sx \&LP .
-.Pp
-See also
-.Sx \&HP ,
-.Sx \&IP ,
-.Sx \&LP ,
-.Sx \&P ,
-and
-.Sx \&TP .
+Begin an undecorated paragraph.
+The scope of a paragraph is closed by a subsequent paragraph,
+sub-section, section, or end of file.
+The saved paragraph left-margin width is reset to the default.
 .Ss \&RB
 Text is rendered alternately in roman (the default font) and bold face.
 Whitespace between arguments is omitted in output.
-.Pp
-See
-.Sx \&BI
-for an equivalent example.
-.Pp
 See also
-.Sx \&BI ,
-.Sx \&IB ,
-.Sx \&BR ,
-.Sx \&RI ,
-and
-.Sx \&IR .
+.Sx \&BI .
 .Ss \&RE
 Explicitly close out the scope of a prior
 .Sx \&RS .
@@ -586,18 +321,8 @@ blocks remain open.
 .Ss \&RI
 Text is rendered alternately in roman (the default font) and italics.
 Whitespace between arguments is omitted in output.
-.Pp
-See
-.Sx \&BI
-for an equivalent example.
-.Pp
 See also
-.Sx \&BI ,
-.Sx \&IB ,
-.Sx \&BR ,
-.Sx \&RB ,
-and
-.Sx \&IR .
+.Sx \&BI .
 .Ss \&RS
 Temporarily reset the default left margin.
 This has the following syntax:
@@ -644,16 +369,16 @@ and very rarely used even in GNU manual 
 Formatting is similar to
 .Sx \&IP .
 .Ss \&TH
-Sets the title of the manual page for use in the page header
+Set the name of the manual page for use in the page header
 and footer with the following syntax:
 .Bd -filled -offset indent
 .Pf \. Sx \&TH
-.Ar title section date
+.Ar name section date
 .Op Ar source Op Ar volume
 .Ed
 .Pp
 Conventionally, the document
-.Ar title
+.Ar name
 is given in all caps.
 The recommended
 .Ar date
@@ -698,33 +423,24 @@ argument is a
 scaling width.
 If specified, it's saved for later paragraph left-margins; if
 unspecified, the saved or default width is used.
-.Pp
-See also
-.Sx \&HP ,
-.Sx \&IP ,
-.Sx \&LP ,
-.Sx \&P ,
-and
-.Sx \&PP .
 .Ss \&TQ
 Like
 .Sx \&TP ,
 except that no vertical spacing is inserted before the paragraph.
-This is a non-standard GNU extension and rarely used even by GNU
-manual pages.
+This is a non-standard GNU extension
+and very rarely used even in GNU manual pages.
 .Ss \&UC
 Sets the volume for the footer for compatibility with man pages from
 .Bx
 releases.
 The optional first argument specifies which release it is from.
 .Ss \&UE
-End a uniform resource identifier block.
-This is a non-standard GNU extension, included only for compatibility.
-See
-.Sx \&UE .
+End a uniform resource identifier block started with
+.Sx \&UR .
+This is a non-standard GNU extension.
 .Ss \&UR
 Begin a uniform resource identifier block.
-This is a non-standard GNU extension, included only for compatibility.
+This is a non-standard GNU extension.
 It has the following syntax:
 .Bd -literal -offset indent
 .Pf \. Sx \&UR Ar uri
@@ -732,11 +448,11 @@ link description to be shown
 .Pf \. Sx UE
 .Ed
 .Ss \&YS
-End a synopsis block started by
-.Pf \. Sx SY .
+End a synopsis block started with
+.Sx \&SY .
 This is a non-standard GNU extension.
 .Ss \&fi
-End literal mode begun by
+End literal mode started with
 .Sx \&nf .
 .Ss \&in
 Indent relative to the current indentation:
@@ -794,12 +510,12 @@ The syntax is as follows:
 .It Sx \&BI  Ta    n         Ta    current   Ta    \&
 .It Sx \&BR  Ta    n         Ta    current   Ta    \&
 .It Sx \&DT  Ta    0         Ta    current   Ta    \&
-.It Sx \&EE  Ta    0         Ta    current   Ta    compat
-.It Sx \&EX  Ta    0         Ta    current   Ta    compat
+.It Sx \&EE  Ta    0         Ta    current   Ta    GNU
+.It Sx \&EX  Ta    0         Ta    current   Ta    GNU
 .It Sx \&I   Ta    n         Ta    next-line Ta    \&
 .It Sx \&IB  Ta    n         Ta    current   Ta    \&
 .It Sx \&IR  Ta    n         Ta    current   Ta    \&
-.It Sx \&OP  Ta    0, 1      Ta    current   Ta    compat
+.It Sx \&OP  Ta    >=1       Ta    current   Ta    GNU
 .It Sx \&PD  Ta    1         Ta    current   Ta    \&
 .It Sx \&RB  Ta    n         Ta    current   Ta    \&
 .It Sx \&RI  Ta    n         Ta    current   Ta    \&
@@ -807,18 +523,10 @@ The syntax is as follows:
 .It Sx \&SM  Ta    n         Ta    next-line Ta    \&
 .It Sx \&TH  Ta    >1, <6    Ta    current   Ta    \&
 .It Sx \&UC  Ta    <=1       Ta    current   Ta    \&
-.It Sx \&fi  Ta    0         Ta    current   Ta    compat
-.It Sx \&in  Ta    1         Ta    current   Ta    compat
-.It Sx \&nf  Ta    0         Ta    current   Ta    compat
+.It Sx \&fi  Ta    0         Ta    current   Ta    Xr roff 7
+.It Sx \&in  Ta    1         Ta    current   Ta    Xr roff 7
+.It Sx \&nf  Ta    0         Ta    current   Ta    Xr roff 7
 .El
-.Pp
-Macros marked as
-.Qq compat
-are included for compatibility with the significant corpus of existing
-manuals that mix dialects of roff.
-These macros should not be used for portable
-.Nm
-manuals.
 .Ss Block Macros
 Block macros comprise a head and body.
 As with in-line macros, the head is scoped to the current line and, in
@@ -838,14 +546,14 @@ by
 .Sx \&SH ;
 sub-section, closed by a section or
 .Sx \&SS ;
-part, closed by a section, sub-section, or
-.Sx \&RE ;
-or paragraph, closed by a section, sub-section, part,
+or paragraph, closed by a section, sub-section,
 .Sx \&HP ,
 .Sx \&IP ,
 .Sx \&LP ,
 .Sx \&P ,
 .Sx \&PP ,
+.Sx \&RE ,
+.Sx \&SY ,
 or
 .Sx \&TP .
 No closure refers to an explicit block closing macro.
@@ -858,22 +566,22 @@ implicitly closed, is syntactically inco
 .It Sx \&HP  Ta    <2        Ta    current    Ta    paragraph   Ta    \&
 .It Sx \&IP  Ta    <3        Ta    current    Ta    paragraph   Ta    \&
 .It Sx \&LP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
+.It Sx \&ME  Ta    0         Ta    none       Ta    none        Ta    GNU
+.It Sx \&MT  Ta    1         Ta    current    Ta    to \&ME     Ta    GNU
 .It Sx \&P   Ta    0         Ta    current    Ta    paragraph   Ta    \&
 .It Sx \&PP  Ta    0         Ta    current    Ta    paragraph   Ta    \&
-.It Sx \&RE  Ta    0         Ta    current    Ta    none        Ta    compat
-.It Sx \&RS  Ta    1         Ta    current    Ta    part        Ta    compat
+.It Sx \&RE  Ta    <=1       Ta    current    Ta    none        Ta    \&
+.It Sx \&RS  Ta    1         Ta    current    Ta    to \&RE     Ta    \&
 .It Sx \&SH  Ta    >0        Ta    next-line  Ta    section     Ta    \&
 .It Sx \&SS  Ta    >0        Ta    next-line  Ta    sub-section Ta    \&
+.It Sx \&SY  Ta    1         Ta    current    Ta    to \&YS     Ta    GNU
 .It Sx \&TP  Ta    n         Ta    next-line  Ta    paragraph   Ta    \&
-.It Sx \&UE  Ta    0         Ta    current    Ta    none        Ta    compat
-.It Sx \&UR  Ta    1         Ta    current    Ta    part        Ta    compat
+.It Sx \&TQ  Ta    n         Ta    next-line  Ta    paragraph   Ta    GNU
+.It Sx \&UE  Ta    0         Ta    current    Ta    none        Ta    GNU
+.It Sx \&UR  Ta    1         Ta    current    Ta    part        Ta    GNU
+.It Sx \&YS  Ta    0         Ta    none       Ta    none        Ta    GNU
 .El
 .Pp
-Macros marked
-.Qq compat
-are as mentioned in
-.Sx Line Macros .
-.Pp
 If a block macro is next-line scoped, it may only be followed by in-line
 macros for decorating text.
 .Ss Font handling
@@ -918,8 +626,3 @@ This
 .Nm
 reference was written by
 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
-.Sh CAVEATS
-Do not use this language.
-Use
-.Xr mdoc 7 ,
-instead.
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv