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

@@ -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

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.

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 (;;)
 		{