Clarified EXIT STATUS sections. Discussed among schwarze@, Thomas, and

[mandoc.git] / mdoc.7

diff --git a/mdoc.7 b/mdoc.7
index 8b1d30ea66f34532229946950ca01bdb33aef0e8..1f94e32808fc67f38e2b667c60ee22827262f939 100644 (file)
--- a/mdoc.7
+++ b/mdoc.7
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.7,v 1.146 2010/08/07 10:18:36 kristaps Exp $
+.\"    $Id: mdoc.7,v 1.158 2010/09/04 17:22:41 kristaps Exp $

 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,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: August 7 2010 $
+.Dd $Mdocdate: September 4 2010 $

 .Dt MDOC 7
 .Os
 .Sh NAME
 .Dt MDOC 7
 .Os
 .Sh NAME


@@ -331,8 +331,9 @@ file:
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here
 \&.Sh NAME
 \&.Nm foo
 \&.Nd a description goes here

-\&.\e\*q The next is for sections 2, 3, & 9 only.

 \&.\e\*q .Sh LIBRARY
 \&.\e\*q .Sh LIBRARY

+\&.\e\*q For sections 2, 3, & 9 only.
+\&.\e\*q Not used in OpenBSD.

 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options
 \&.Sh SYNOPSIS
 \&.Nm foo
 \&.Op Fl options


@@ -342,18 +343,18 @@ The
 \&.Nm
 utility processes files ...
 \&.\e\*q .Sh IMPLEMENTATION NOTES
 \&.Nm
 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 RETURN VALUES

-\&.\e\*q The next is for sections 1, 6, 7, & 8 only.
+\&.\e\*q For sections 2, 3, & 9 only.

 \&.\e\*q .Sh ENVIRONMENT
 \&.\e\*q .Sh ENVIRONMENT

+\&.\e\*q For sections 1, 6, 7, & 8 only.

 \&.\e\*q .Sh FILES
 \&.\e\*q .Sh FILES

-\&.\e\*q The next is for sections 1 & 8 only.

 \&.\e\*q .Sh EXIT STATUS
 \&.\e\*q .Sh EXIT STATUS

+\&.\e\*q For sections 1, 6 & 8 only.

 \&.\e\*q .Sh EXAMPLES
 \&.\e\*q .Sh EXAMPLES

-\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only.

 \&.\e\*q .Sh DIAGNOSTICS
 \&.\e\*q .Sh DIAGNOSTICS

-\&.\e\*q The next is for sections 2, 3, & 9 only.
+\&.\e\*q For sections 1, 4, 6, 7, & 8 only.

 \&.\e\*q .Sh ERRORS
 \&.\e\*q .Sh ERRORS

+\&.\e\*q For sections 2, 3, & 9 only.

 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS
 \&.\e\*q .Sh SEE ALSO
 \&.\e\*q .Xr foobar 1
 \&.\e\*q .Sh STANDARDS


@@ -362,6 +363,7 @@ utility processes files ...
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS
 \&.\e\*q .Sh CAVEATS
 \&.\e\*q .Sh BUGS
 \&.\e\*q .Sh SECURITY CONSIDERATIONS

+\&.\e\*q Not used in OpenBSD.

 .Ed
 .Pp
 The sections in an
 .Ed
 .Pp
 The sections in an


@@ -570,7 +572,7 @@ See
 Common misuses and misunderstandings should be explained
 in this section.
 .It Em BUGS
 Common misuses and misunderstandings should be explained
 in this section.
 .It Em BUGS

-Known bugs, limitations and work-arounds should be described
+Known bugs, limitations, and work-arounds should be described

 in this section.
 .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.
 in this section.
 .It Em SECURITY CONSIDERATIONS
 Documents any security precautions that operators should consider.


@@ -876,10 +878,6 @@ referring to book titles.
 Publication city or location of an
 .Sx \&Rs
 block.
 Publication city or location of an
 .Sx \&Rs
 block.

-.Pp
-.Em Remarks :
-this macro is not implemented in
-.Xr groff 1 .

 .Ss \&%D
 Publication date of an
 .Sx \&Rs
 .Ss \&%D
 Publication date of an
 .Sx \&Rs


@@ -2099,7 +2097,7 @@ Its syntax is as follows:
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:
 .D1 Pf \. Sx \&Lk Cm uri Op Cm name
 .Pp
 Examples:

-.D1 \&.Lk http://bsd.lv "The BSD.lv Project"
+.D1 \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q

 .D1 \&.Lk http://bsd.lv
 .Pp
 See also
 .D1 \&.Lk http://bsd.lv
 .Pp
 See also


@@ -2676,7 +2674,7 @@ is followed by non-punctuation, an
 .Sx \&Ns
 is inserted into the token stream.
 This behaviour is for compatibility with
 .Sx \&Ns
 is inserted into the token stream.
 This behaviour is for compatibility with

-.Xr groff 1 .
+GNU troff.

 .Pp
 Examples:
 .D1 \&.Xr mandoc 1
 .Pp
 Examples:
 .D1 \&.Xr mandoc 1


@@ -2719,151 +2717,170 @@ file re-write
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
 .Pp
 Heirloom troff, the other significant troff implementation accepting
 \-mdoc, is similar to historic groff.
 .Pp

+The following problematic behaviour is found in groff:
+.ds hist (Historic groff only.)
+.Pp

 .Bl -dash -compact
 .It
 .Bl -dash -compact
 .It

-An empty
-.Sq \&Dd
-macro in groff prints
+.Sx \&At
+with unknown arguments produces no output at all.
+\*[hist]
+Newer groff and mandoc print
+.Qq AT&T UNIX
+and the arguments.
+.It
+.Sx \&Bd Fl column
+does not recognize trailing punctuation characters when they immediately
+precede tabulator characters, but treats them as normal text and
+outputs a space before them.
+.It
+.Sx \&Bd Fl ragged compact
+does not start a new line.
+\*[hist]
+.It
+.Sx \&Dd
+without an argument prints

 .Dq Epoch .
 In mandoc, it resolves to the current date.
 .It
 .Dq Epoch .
 In mandoc, it resolves to the current date.
 .It

-The \es (font size), \em (font colour), and \eM (font filling colour)
-font decoration escapes are all discarded in mandoc.
+.Sx \&Fl
+does not print a dash for an empty argument.
+\*[hist]

 .It
 .It

-Old groff fails to assert a newline before
-.Sx \&Bd Fl ragged compact .
+.Sx \&Fn
+does not start a new line unless invoked as the line macro in the
+.Em SYNOPSIS
+section.
+\*[hist]

 .It
 .It

-groff behaves inconsistently when encountering
-.Pf non- Sx \&Fa
-children of

 .Sx \&Fo
 .Sx \&Fo

-regarding spacing between arguments.
-In mandoc, this is not the case: each argument is consistently followed
-by a single space and the trailing
-.Sq \&)
-suppresses prior spacing.
+with
+.Pf non- Sx \&Fa
+children causes inconsistent spacing between arguments.
+In mandoc, a single space is always inserted between arguments.

 .It
 .It

-groff behaves inconsistently when encountering

 .Sx \&Ft
 .Sx \&Ft

-and
-.Sx \&Fn

 in the
 in the

-.Em SYNOPSIS :
-at times newline(s) are suppressed depending on whether a prior
+.Em SYNOPSIS
+causes inconsistent vertical spacing, depending on whether a prior

 .Sx \&Fn
 has been invoked.
 .Sx \&Fn
 has been invoked.

-In mandoc, this is not the case.

 See
 .Sx \&Ft
 and
 .Sx \&Fn
 See
 .Sx \&Ft
 and
 .Sx \&Fn

-for the normalised behaviour.
-.It
-Historic groff does not break before an
-.Sx \&Fn
-when not invoked as the line macro in the
-.Em SYNOPSIS
-section.
+for the normalised behaviour in mandoc.

 .It
 .It

-Historic groff formats the

 .Sx \&In
 .Sx \&In

-badly: trailing arguments are trashed and
-.Em SYNOPSIS
-is not specially treated.
+ignores additional arguments and is not treated specially in the
+.Em SYNOPSIS .
+\*[hist]

 .It
 .It

-groff does not accept the
-.Sq \&Ta
-pseudo-macro as a line macro.
-mandoc does.
+.Sx \&It
+sometimes requires a
+.Fl nested
+flag.
+\*[hist]
+In new groff and mandoc, any list may be nested by default and
+.Fl enum
+lists will restart the sequence only for the sub-list.
+.It
+.Sx \&Li
+followed by a reserved character is incorrectly used in some manuals
+instead of properly quoting that character, which sometimes works with
+historic groff.

 .It
 .It

-The comment syntax
-.Sq \e\."
-is no longer accepted.
+.Sx \&Lk
+only accepts a single link-name argument; the remainder is misformatted.

 .It
 .It

-In groff, the

 .Sx \&Pa
 .Sx \&Pa

-macro does not format its arguments when used in the FILES section under
+does not format its arguments when used in the FILES section under

 certain list types.
 certain list types.

-mandoc does.

 .It
 .It

-Historic groff does not print a dash for empty
-.Sx \&Fl
-arguments.
-mandoc and newer groff implementations do.
+.Sx \&Ta
+can only be called by other macros, but not at the beginning of a line.

 .It
 .It

-groff behaves irregularly when specifying
+.Sx \&%C
+is not implemented.
+.It
+Historic groff has many un-callable macros.
+Most of these (excluding some block-level macros) are callable
+in new groff and mandoc.
+.It
+.Sq \(ba
+(vertical bar) is not fully supported as a delimiter.
+\*[hist]
+.It
+.Sq \ef
+.Pq font face
+and

 .Sq \ef
 .Sq \ef

+.Pq font family face

 .Sx Text Decoration
 .Sx Text Decoration

-within line-macro scopes.
-mandoc follows a consistent system.
+escapes behave irregularly when specified within line-macro scopes.

 .It
 .It

-In mandoc, negative scaling units are truncated to zero; groff would
-move to prior lines.
-Furthermore, the
-.Sq f
-scaling unit, while accepted, is rendered as the default unit.
+Negative scaling units return to prior lines.
+Instead, mandoc truncates them to zero.
+.El
+.Pp
+The following features are unimplemented in mandoc:
+.Pp
+.Bl -dash -compact

 .It
 .It

-In quoted literals, groff allowed pairwise double-quotes to produce a
-standalone double-quote in formatted output.
-This idiosyncratic behaviour is not applicable in mandoc.
+.Sx \&Bd
+.Fl file Ar file .

 .It
 .It

-Display offsets

 .Sx \&Bd
 .Fl offset Ar center
 and
 .Sx \&Bd
 .Fl offset Ar center
 and

-.Fl offset Ar right
-are disregarded in mandoc.
-Furthermore, troff specifies a
-.Fl file Ar file
-argument that is not supported in mandoc.
-Lastly, since text is not right-justified in mandoc (or even groff),
-.Fl ragged
-and
-.Fl filled
-are aliases, as are
-.Fl literal
-and
-.Fl unfilled .
-.It
-Historic groff has many un-callable macros.
-Most of these (excluding some block-level macros) are now callable.
+.Fl offset Ar right .
+Groff does not implement centered and flush-right rendering either,
+but produces large indentations.

 .It
 .It

-The vertical bar
-.Sq \(ba
-made historic groff
-.Qq go orbital
-but has been a proper delimiter since then.
-.It
-.Sx \&It Fl nested
-is assumed for all lists (it wasn't in historic groff): any list may be
-nested and
-.Fl enum
-lists will restart the sequence only for the sub-list.
-.It
-Some manuals use
-.Sx \&Li
-incorrectly by following it with a reserved character and expecting the
-delimiter to render.
-This is not supported in mandoc.
-.It
-In groff, the
-.Sx \&Cd ,
-.Sx \&Er ,
-.Sx \&Ex ,
+The
+.Sq \eh
+.Pq horizontal position ,
+.Sq \ev
+.Pq vertical position ,
+.Sq \em
+.Pq text colour ,
+.Sq \eM
+.Pq text filling colour ,
+.Sq \ez
+.Pq zero-length character ,
+.Sq \ew
+.Pq string length ,
+.Sq \ek
+.Pq horizontal position marker ,
+.Sq \eo
+.Pq text overstrike ,

 and
 and

-.Sx \&Rv
-macros were stipulated only to occur in certain manual sections.
-mandoc does not have these restrictions.
+.Sq \es
+.Pq text size
+escape sequences are all discarded in mandoc.

 .It
 .It

-Newer groff and mandoc print
-.Qq AT&T UNIX
-prior to unknown arguments of
-.Sx \&At ;
-older groff did nothing.
+The
+.Sq \ef
+scaling unit is accepted by mandoc, but rendered as the default unit.
+.It
+In quoted literals, groff allows pairwise double-quotes to produce a
+standalone double-quote in formatted output.
+This is not supported by mandoc.

 .El
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr mandoc_char 7
 .El
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr mandoc_char 7

+.Sh HISTORY
+The
+.Nm
+language first appeared as a troff macro package in
+.Bx 4.4 .
+It was later significantly updated by Werner Lemberg and Ruslan Ermilov
+in groff-1.17.
+The standalone implementation that is part of the
+.Xr mandoc 1
+utility written by Kristaps Dzonsons appeared in
+.Ox 4.6 .

 .Sh AUTHORS
 The
 .Nm
 .Sh AUTHORS
 The
 .Nm