From 6916a873c2ead8bd3e0bfa6fa3757ea8a4fb89ec Mon Sep 17 00:00:00 2001
From: Martijn Dekker <martijn@inlv.org>
Date: Mon, 15 Jun 2020 16:56:11 +0200
Subject: [PATCH] optget: display --help and --man in terse usage messages

The fact that every ksh builtin command self-documents with the
options --help and --man (and others, see 'getopts --man'; but
these are the essential ones) is poorly known; the information is
buried somewhere deep in the sh.1 manual page, and is incomplete at
that. None of the terse usage messages displayed on error point the
user to these options. So let's fix that.

src/lib/libast/misc/optget.c:
- Change generic 'options' placeholder, used in all terse usage
  messages, to 'options | --help | --man'.

src/cmd/ksh93/sh.1:
- Edit documentation of --man/-?, adding documentation on --help
  which was completely undocumented. Refer to 'getopts --man' for
  more advanced info.
- Separate these from the (important) documentation on special
  builtins using a paragraph break.
---
 NEWS                         |  3 +++
 src/cmd/ksh93/sh.1           | 23 ++++++++++++++---------
 src/lib/libast/misc/optget.c |  2 +-
 3 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/NEWS b/NEWS
index fa5a5b99c..dc91415c1 100644
--- a/NEWS
+++ b/NEWS
@@ -10,6 +10,9 @@ Any uppercase BUG_* names are modernish shell bug IDs.
 - Functions that set variables in a virtual subshell will no longer affect
   variables of the same name outside of the virtual subshell's environment.
 
+- Terse usage messages written by builtin commands now point the user to
+  the --help and --man options for more information.
+
 2020-06-14:
 
 - 'read -S' is now able to correctly handle strings with double quotes
diff --git a/src/cmd/ksh93/sh.1 b/src/cmd/ksh93/sh.1
index 261ba8239..e43904495 100644
--- a/src/cmd/ksh93/sh.1
+++ b/src/cmd/ksh93/sh.1
@@ -5471,16 +5471,21 @@ all built-in commands accept
 to indicate end of options.
 They also interpret the option
 .B \-\-man
-as a request to display the man page onto
-standard error and
+as a request to display that command's own manual page,
+.B \-\-help
+as a request to display the
+.I OPTIONS
+section from their manual page, and
 .B \-?
-as a help request which prints a
-.I usage\^
-message
-on standard error.
-Commands that are preceded by one or two \(dg symbols
-are special built-in commands and
-are treated specially in the following ways:
+as a request to print a brief usage message.
+All these are printed on standard error.
+There are advanced output options as well; see
+.B getopts --man
+for more information.
+.PP
+Commands that are preceded by one or two \(dg symbols below are
+.I special\ built-in\ commands
+and are treated specially in the following ways:
 .PD 0
 .TP
 1.
diff --git a/src/lib/libast/misc/optget.c b/src/lib/libast/misc/optget.c
index af5559b15..6c5fcab37 100644
--- a/src/lib/libast/misc/optget.c
+++ b/src/lib/libast/misc/optget.c
@@ -1627,7 +1627,7 @@ args(register Sfio_t* sp, register char* p, register int n, int flags, int style
 	else
 	{
 		sep = ' ';
-		o = T(NiL, ID, "options");
+		o = T(NiL, ID, "options | --help | --man");
 		b = style == STYLE_nroff ? "\\ " : " ";
 		for (;;)
 		{