From ChangeLog:

: 2001-08-14  Ruslan Ermilov  <ru@FreeBSD.org>
:
: 	* tmac/doc.tmac (Ex): New implementation.
: 	* tmac/doc-common, tmac/groff_tmac.man: Updated.

This adds a new macro, .Ex (Exit Status), for use in the
DIAGNOSTICS section of section 1, 6 and 8 manpages.

Prodded by:	dd

3 files changed, 100 insertions, 3 deletions

diff --git a/contrib/groff/tmac/doc-common b/contrib/groff/tmac/doc-common
index d19a795..9e1a81a 100644
--- a/contrib/groff/tmac/doc-common
+++ b/contrib/groff/tmac/doc-common
@@ -89,6 +89,7 @@
 .nr Er 17n
 .nr Es 12n
 .nr Ev 15n
+.nr Ex 1
 .nr Fa 12n
 .nr Fc 3
 .nr Fd 12n\" ?
diff --git a/contrib/groff/tmac/doc.tmac b/contrib/groff/tmac/doc.tmac
index db8029f..8e72e56 100644
--- a/contrib/groff/tmac/doc.tmac
+++ b/contrib/groff/tmac/doc.tmac
@@ -6195,6 +6195,67 @@
 ..
 .
 .
+.\" NS Ex user macro
+.\" NS   exit status
+.\" NS
+.\" NS width register `Ex' set in doc-common
+.\" NS
+.\" NS local variables:
+.\" NS   doc-str-Ex-std-prefix
+.\" NS   doc-str-Ex-std-suffix
+.
+.ds doc-str-Ex-std-prefix "The
+.ds doc-str-Ex-std-suffix "utility exits\~0 on success,
+.as doc-str-Ex-std-suffix " and\~>0 if an error occurs.
+.
+.ds doc-str-Ex-stds-prefix "The
+.als doc-str-Ex-stds-and doc-str-Rv-stds-and
+.ds doc-str-Ex-stds-suffix "utilities exit\~0 on success,
+.as doc-str-Ex-stds-suffix " and\~>0 if an error occurs.
+.
+.de Ex
+.
+.\" XXX: what does this function without `-std'?
+.
+.  if \n[doc-arg-limit] \{\
+.    tm Usage: .Ex not callable by other macros (#\n[.c])
+.    doc-reset-args
+.    return
+.  \}
+.
+.  if !\n[.$] \{\
+.    tm Usage: .Ex [-std] [<utility> ...] (#\n[.c])
+.    return
+.  \}
+.
+.  if "\$1"-std" \{\
+.    nr doc-reg-Ex \*[doc-section]
+.    if !((\n[doc-reg-Ex] == 1) : (\n[doc-reg-Ex] == 6) : (\n[doc-reg-Ex] == 8)) \
+.      tm Usage: .Ex -std in sections 1, 6 and 8 only (#\n[.c])
+.    br
+.    shift
+.    ie (\n[.$] > 1) \{\
+.      nop \)\*[doc-str-Ex-stds-prefix]
+.      nr doc-reg-Ex 1
+.      while (\n[doc-reg-Ex] < \n[.$]) \{\
+.        ie (\n[.$] > 2) \
+.          Nm \$\n[doc-reg-Ex] ,
+.        el \
+.          Nm \$\n[doc-reg-Ex]
+.        nr doc-reg-Ex +1
+.      \}
+.      nop \)\*[doc-str-Ex-stds-and]
+.      Nm \$\n[.$]
+.      nop \)\*[doc-str-Ex-stds-suffix]
+.    \}
+.    el \{\
+.      nop \)\*[doc-str-Ex-std-prefix]
+.      Nm \$1
+.      nop \)\*[doc-str-Ex-std-suffix]
+.  \}\}
+..
+.
+.
 .\" NS Mt user macro
 .\" NS   mailto (for conversion to HTML)
 .
@@ -6259,9 +6320,6 @@
 .
 .als Ds doc-defunct-macro
 .
-.als Ex doc-defunct-macro
-.ds doc-Ex-usage use .D1
-.
 .als Or doc-defunct-macro
 .ds doc-Or-usage use `|'
 .
diff --git a/contrib/groff/tmac/groff_mdoc.man b/contrib/groff/tmac/groff_mdoc.man
index 17ef3d6..534c516 100644
--- a/contrib/groff/tmac/groff_mdoc.man
+++ b/contrib/groff/tmac/groff_mdoc.man
@@ -163,6 +163,7 @@ as follows:
 .    It "Functions (Library Routines)"
 .    It "Function Arguments"
 .    It "Return Values"
+.    It "Exit Status"
 .    \" .It "Header File (including source code)"
 .    It "Interactive Commands"
 .    It "Library Names"
@@ -1537,6 +1538,36 @@ Currently, this macro does nothing if used without the
 .Fl std
 flag.
 .
+.Ss "Exit Status"
+.
+The
+.Ql .Ex
+macro generates text for use in the
+.Sx DIAGNOSTICS
+section.
+.Pp
+.Dl Usage: .Ex Oo -std Oc Op Ao utility Ac ...
+.Pp
+For example,
+.Ql ".Ex -std cat"
+produces:
+.
+.Bd -ragged -offset -indent
+\# a small hack to suppress a warning message
+.ds section-old "\*[section]
+.ds section 1
+.Ex -std cat
+.ds section "\*[section-old]
+.Ed
+.Pp
+.
+The
+.Fl std
+option is valid only for manual page sections 1, 6 and\~8.
+Currently, this macro does nothing if used without the
+.Fl std
+flag.
+.
 .Ss "Interactive Commands"
 .
 The
@@ -2709,6 +2740,13 @@ section below for details.
 .
 .It Li ".Sh DIAGNOSTICS"
 Diagnostic messages from a command should be placed in this section.
+The
+.Ql .Ex
+macro may be used to generate text for use in the
+.Sx DIAGNOSTICS
+section for most section 1, 6 and\~8 commands;
+see
+.Sx "Exit Status" .
 .
 .It Li ".Sh COMPATIBILITY"
 Known compatibility issues (e.g. deprecated options or parameters)