getopts: break up help into three functions.

* lisplib.c (getopts_set_entries): Autoload for
opthelp-conventions and opthelp-types.

* stdlib/getopts.tl (opthelp): Remove incnotes parameter.
Entirely trim out the code for notes about conventions and use
of types.
(opthel-conventions, opthelp-types): New functions.
(option-base opthelp-conventions, option-base opthelp-types):
New methods.

* txr.1: Documented.

* stdlib/doc-syms.tl: Updated.

4 files changed, 143 insertions, 92 deletions

diff --git a/lisplib.c b/lisplib.c
index f841f4c7..0f48b82e 100644
--- a/lisplib.c
+++ b/lisplib.c
@@ -483,7 +483,8 @@ static val getopts_set_entries(val dlt, val fun)
 {
   val name[] = {
     lit("opt-desc"), lit("opts"),
-    lit("opt"), lit("getopts"), lit("opthelp"), lit("define-option-struct"),
+    lit("opt"), lit("getopts"), lit("opthelp"), lit("opthelp-conventions"),
+    lit("opthelp-types"), lit("define-option-struct"),
     nil
   };
   val name_noload[] = {
diff --git a/stdlib/doc-syms.tl b/stdlib/doc-syms.tl
index 71302389..a296a126 100644
--- a/stdlib/doc-syms.tl
+++ b/stdlib/doc-syms.tl
@@ -1397,7 +1397,9 @@
       ("opost" "N-03BD477F")
       ("opt" "N-0047F5AB")
       ("opt-desc" "N-03FC5092")
-      ("opthelp" "N-016C6171")
+      ("opthelp" "N-010286EC")
+      ("opthelp-conventions" "N-010286EC")
+      ("opthelp-types" "N-010286EC")
       ("opts" "N-01D911E8")
       ("or" "D-001A")
       ("orec" "N-0003ED2C")
diff --git a/stdlib/getopts.tl b/stdlib/getopts.tl
index 65b6e4dc..70413902 100644
--- a/stdlib/getopts.tl
+++ b/stdlib/getopts.tl
@@ -269,7 +269,7 @@
          (opr (new sys:opt-processor od-list opt-desc-list opts opts)))
     opr.(parse-opts args)))
 
-(defun opthelp (opt-desc-list : (stream *stdout*) (incnotes t))
+(defun opthelp (opt-desc-list : (stream *stdout*))
   (let ((sorted [nsort (copy-list (remove-if (op null @1.helptext)
                                              opt-desc-list)) :
                        (do if @1.long @1.long @1.short)])
@@ -306,74 +306,78 @@
                                    (flatten (mappend (op list @1.short @1.long)
                                                      undocumented))] ", "}`))
         (each ((line (sys:wdwrap undoc-str 75)))
-          (put-line `    @line` stream)))
-      (put-line : stream))
-    (when incnotes
-      (put-line "Notes:\n" stream)
-      (let* ((have-short (some sorted (usl short)))
-             (have-long (some sorted (usl long)))
-             (have-arg-p (some sorted (usl arg-p)))
-             (have-bool (some sorted (op eq @1.type :bool)))
-             (texts (list (if have-short
-                            "Short options can be invoked with long syntax: \ \
-                             for example, --a can be used when -a exists.\ \
-                             Short no-argument options can be clumped into\ \
-                             one argument as exemplified by -xyz.")
-                          (if have-bool
-                            (if have-arg-p
-                              "Options that take no argument are Boolean:"
-                              (if undocumented
-                                "All documented options are Boolean:"
-                                "All options are Boolean:")))
-                          (if have-bool
-                            "they are true when present, false when absent.")
-                          (if (and have-bool have-arg-p)
-                            "The --no- prefix can explicitly specify \ \
-                             Boolean options as false: if a Boolean option\ \
-                             X exists,\ \
-                             --no-X specifies it as false. This is useful\ \
-                             for making false those options which default\ \
-                             to true. "
-                            "The --no- prefix can explicitly specify \ \
-                             options as false: if an X option exists,\ \
-                             --no-X specifies it as false. This is useful\ \
-                             for making false those options which default\ \
-                             to true. ")
-                          (if (not have-long)
-                            "Note the double dash on --no.")
-                          (if (and have-short have-long)
-                            "The --no- prefix can be applied to a short\ \
-                             or long option name.")
+          (put-line `    @line` stream))))))
+
+(defun opthelp-conventions (opt-desc-list : (stream *stdout*))
+  (let ((documented (remove-if (op null @1.helptext) opt-desc-list))
+        (undocumented (keep-if (op null @1.helptext) opt-desc-list)))
+    (put-line "Option Conventions:\n" stream)
+    (let* ((have-short (some documented (usl short)))
+           (have-long (some documented (usl long)))
+           (have-arg-p (some documented (usl arg-p)))
+           (have-bool (some documented (op eq @1.type :bool)))
+           (texts (list (if have-short
+                          "Short options can be invoked with long syntax: \ \
+                           for example, --a can be used when -a exists.\ \
+                           Short no-argument options can be clumped into\ \
+                           one argument as exemplified by -xyz.")
+                        (if have-bool
                           (if have-arg-p
-                            "The argument to a long option can be given in one\ \
-                             argument as --option=arg or as a separate\ \
-                             argument using --option arg.")
-                          "The special argument -- can be used where an option\ \
-                           may appear. It means \"end of options\": the\ \
-                           arguments which follow are not treated as options\ \
-                           even if they look like options.")))
-        (mapdo (do put-line `  @1` stream)
-               (sys:wdwrap `@{(flatten texts)}` 77)))
-      (put-line : stream)
-      (whenlet ((types (keep-if [andf keywordp (op neq :bool)]
-                (uniq (mapcar (usl type) sorted)))))
-        (put-line "Type legend:\n" stream)
-        (each ((ty types))
-          (iflet ((ln (caseql ty
-                        (:dec   "  DEC    - Decimal integer: -123, 0, 5, +73")
-                        (:hex   "  HEX    - Hexadecimal integer -EF, 2D0, +9A")
-                        (:oct   "  OCT    - Octal integer: -773, 5677, +326")
-                        (:cint  "  CINT   - C-style integer: leading 0 octal,\
-                                \ leading 0x hex, else decimal;\n\
-                                \           leading sign allowed: -0777, 0xFDC, +123")
-                        (:float "  FLOAT  - Floating-point: -1.3e+03, +5, 3.3,\
-                                \ 3., .5, .12e9, 53.e-3, 3e-015")
-                        (:str   "  STR    - String with embedded escapes, valid\
-                                \ as TXR Lisp string literals\n\
-                                \           syntax: foo, foo\\tbar, abc\\nxyz")
-                        (:text  "  TEXT   - Unprocessed text"))))
-            (put-line ln stream)))
-        (put-line : stream)))))
+                            "Options that take no argument are Boolean:"
+                            (if undocumented
+                              "All documented options are Boolean:"
+                              "All options are Boolean:")))
+                        (if have-bool
+                          "they are true when present, false when absent.")
+                        (if (and have-bool have-arg-p)
+                          "The --no- prefix can explicitly specify \ \
+                           Boolean options as false: if a Boolean option\ \
+                           X exists,\ \
+                           --no-X specifies it as false. This is useful\ \
+                           for making false those options which default\ \
+                           to true. "
+                          "The --no- prefix can explicitly specify \ \
+                           options as false: if an X option exists,\ \
+                           --no-X specifies it as false. This is useful\ \
+                           for making false those options which default\ \
+                           to true. ")
+                        (if (not have-long)
+                          "Note the double dash on --no.")
+                        (if (and have-short have-long)
+                          "The --no- prefix can be applied to a short\ \
+                           or long option name.")
+                        (if have-arg-p
+                          "The argument to a long option can be given in one\ \
+                           argument as --option=arg or as a separate\ \
+                           argument using --option arg.")
+                        "The special argument -- can be used where an option\ \
+                         may appear. It means \"end of options\": the\ \
+                         arguments which follow are not treated as options\ \
+                         even if they look like options.")))
+      (mapdo (do put-line `  @1` stream)
+             (sys:wdwrap `@{(flatten texts)}` 77)))))
+
+(defun opthelp-types (opt-desc-list : (stream *stdout*))
+  (let ((documented (remove-if (op null @1.helptext) opt-desc-list)))
+    (whenlet ((types (keep-if [andf keywordp (op neq :bool)]
+                              (uniq (mapcar (usl type) documented)))))
+      (put-line "Type legend:\n" stream)
+      (each ((ty types))
+        (iflet ((ln (caseql ty
+                      (:dec   "  DEC    - Decimal integer: -123, 0, 5, +73")
+                      (:hex   "  HEX    - Hexadecimal integer -EF, 2D0, +9A")
+                      (:oct   "  OCT    - Octal integer: -773, 5677, +326")
+                      (:cint  "  CINT   - C-style integer: leading 0 octal,\
+                              \ leading 0x hex, else decimal;\n\
+                              \           leading sign allowed: -0777, 0xFDC, +123")
+                      (:float "  FLOAT  - Floating-point: -1.3e+03, +5, 3.3,\
+                              \ 3., .5, .12e9, 53.e-3, 3e-015")
+                      (:str   "  STR    - String with embedded escapes, valid\
+                              \ as TXR Lisp string literals\n\
+                              \           syntax: foo, foo\\tbar, abc\\nxyz")
+                      (:text  "  TEXT   - Unprocessed text"))))
+          (put-line ln stream)))
+      (put-line : stream))))
 
 (defstruct sys:option-base nil
   in-args
@@ -390,8 +394,12 @@
     (set me.in-args args me.out-args args)
     (let ((opr (new sys:opt-processor od-list me.opt-desc-list opts me)))
       opr.(parse-opts args)))
-  (:method opthelp (me : (stream *stdout*) (incnotes t))
-    (opthelp me.opt-desc-list stream incnotes)))
+  (:method opthelp (me : (stream *stdout*))
+    (opthelp me.opt-desc-list stream))
+  (:method opthelp-conventions (me : (stream *stdout*))
+    (opthelp-conventions me.opt-desc-list stream))
+  (:method opthelp-types (me : (stream *stdout*))
+    (opthelp-types me.opt-desc-list stream)))
 
 (defmacro define-option-struct (name super-spec . opts)
   (let* ((slots (mapcar (tb ((short long . rest))
diff --git a/txr.1 b/txr.1
index 611f032d..78e05fe3 100644
--- a/txr.1
+++ b/txr.1
@@ -68160,12 +68160,22 @@ arguments.
 
 The
 .code opthelp
-function takes a list of option descriptors, an output stream, and an arg
-indicating whether to print extra notes on command line conventions.
-It then generates help text on that stream. A program supporting a
+function takes a list of option descriptors and an output stream,
+and generates help text on that stream. A program supporting a
 .code --help
 option can use this to generate that portion of its help text which
-describes the available options, as well as the conventions that they use.
+describes the available options. Also provided are functions
+.code opthelp-conventions
+and
+.codn opthelp-types ,
+which have the same interface as
+.code opthelp
+and print additional information. These may be used together with
+.code opthelp
+to provide more detailed help under a single
+.code --help
+option, or under separate options like
+.codn --extra-help .
 
 The
 .code define-option-struct
@@ -68285,6 +68295,9 @@ macro:
                  "Verbosity level. Higher values produce more chatter.")
     (nil help    :bool
                  "List this help text.")
+    (nil extra-help
+                 :bool
+                 "List help text with more detailed information.")
     (x   nil     :hex
                  "The X factor: a number with a mysterious\e \e
                   interpretation, affecting the program\e \e
@@ -68308,10 +68321,15 @@ macro:
 
   (let ((o (new prog-opts)))
     o.(getopts *args*)
-    (when o.help
+    (when (or o.help o.extrahelp)
       (put-line "Usage:\en")
       (put-line `  @{prog-name} [options] arg*`)
       o.(opthelp)
+      (when o.extrahelp
+        (put-line)
+        o.(opthelp-types)
+        (put-line)
+        o.(opthelp-conventions))
       (exit -1))
     (put-line `args after opts are: @{o.out-args ", "}`))
 .brev
@@ -68652,9 +68670,11 @@ returns an instance of the
 structure describing the parsed options and listing the non-option
 arguments.
 
-.coNP Function @ opthelp
+.coNP Functions @, opthelp @ opthelp-types and @ opthelp-conventions
 .synb
-.mets (opthelp < opt-desc-list <> [ stream ] <> [ inchelp ])
+.mets (opthelp < opt-desc-list <> [ stream ])
+.mets (opthelp-types < opt-desc-list <> [ stream ])
+.mets (opthelp-conventions < opt-desc-list <> [ stream ])
 .syne
 .desc
 The
@@ -68663,12 +68683,10 @@ function processes the list of
 .code opt-desc
 structures
 .meta opt-desc-list
-and compiles a customized body of help text describing all of the
-options. If
-.meta inchelp
-is non-nil then a general description of the command-line option
-conventions will also be printed to guide the user in in the correct
-use of command line options.
+and compiles a customized body of help describing all of the
+options which have help text. These are presented in alphabetical
+order. Options which do not have help text, if any, are simply
+listed together under a heading which indicates their undocumented status.
 
 The text is formatted to fit within 79 columns, and begins and ends with a
 blank line. Its format consists of headings which begin in the first column,
@@ -68687,6 +68705,24 @@ itself, then an exception of type
 .code error
 is thrown.
 
+The
+.code opthelp-types
+supplementary help function processes the
+.metn opt-desc-list ,
+considering only those options which are documented. If any of them have typed
+arguments, then a legend is printed explaining the types. The legend includes
+only information about those option argument types which appear in
+.metn opt-desc-list .
+
+The
+.code opthelp-conventions
+supplementary help function processes
+.metn opt-desc-list ,
+considering only those options which are documented. It prints a guide
+to the use of options, which includes information only about the kinds
+of options actually present in
+.metn opt-desc-list .
+
 .coNP Macro @ define-option-struct
 .synb
 .mets (define-option-struct < name < super << opt-specifier *)
@@ -68732,10 +68768,12 @@ shall exist in the structure.
 
 The struct type defined by
 .code define-option-struct
-has two methods:
-.code getopts
+has four methods:
+.codn getopts ,
+.codn opthelp ,
+.code opthelp-types
 and
-.codn opthelp .
+.codn opthelp-conventions .
 It also has two slots:
 .code in-args
 and
@@ -68751,9 +68789,11 @@ method takes a single argument: the argument list to be processed.
 When the argument list is successfully processed.
 
 The
-.code opthelp
-method takes an optional stream argument, and an argument to indicate whether
-or not to include general notes on command line conventions.
+.codn opthelp ,
+.code opthelp-types
+and
+.code opthelp-conventions
+methods takes an optional stream argument.
 
 Note: to encode the option names
 .str "t"
@@ -68763,7 +68803,7 @@ or option names which clash with the slot names
 .code in-args
 and
 .code out-args
-or the methods
+or the method names such as
 .code getopts
 or
 .codn opthelp ,