From 0cc57cadc11e369eab39f1e540f3c05673e3cabd Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <fare@tunes.org>
Date: Fri, 27 Oct 2023 06:46:50 +0000
Subject: [PATCH] More docs

---
 doc/reference/std/cli/getopt.md | 53 ++++++++++++++++++++++++++++-----
 doc/reference/std/cli/shell.md  |  1 -
 2 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/doc/reference/std/cli/getopt.md b/doc/reference/std/cli/getopt.md
index 599e1ee9c..d4930f79a 100644
--- a/doc/reference/std/cli/getopt.md
+++ b/doc/reference/std/cli/getopt.md
@@ -199,16 +199,53 @@ resulting from calling `getopt-parse`, and returns a list of argument
 with which to call a Scheme function that has an analogous call convention:
   - supplied positional arguments are passed in order
   - they are followed by all the rest arguments
-  - they are followed by the remaining specified keyword arguments;
-    those who were omitted by the user but provided defaults in their
-    `(option ...)` specification will be included with the default value,
-    which should hopefully be the same as the default value from the function
-    being called, or there will be a semantic discrepancy between the CLI
-    interface and the Scheme API.
+  - they are followed by the remaining specified keyword arguments.
 
-The table `h` will be modified in place, removing positional and rest arguments.
-Omitted option arguments will be omitted;
+Omitted option arguments without default will be omitted.
+Omitted option arguments with a default will be included with the default value;
+the programmer must ensure that this default value is the same as
+the default value from the Scheme function being called, or there will be
+a semantic discrepancy between the CLI interface and the underlying Scheme function.
+
+NB: `h` will be modified in place, removing positional and rest arguments.
+Make sure to use `hash-copy` if you want to preserve the original data.
+
+TODO: add examples
 
 ### call-with-getopt-parse
+```scheme
+(call-with-getopt-parse gopt hash fun) => results-of-fun
+```
+
+Given a getopt specification `gopt`, the `hash` resulting from calling
+`getopt-parse` on some provided command-line arguments, and a function `fun`
+that has a calling convention analogous to that specified by `gopt`,
+call the function with arguments that correspond to those provided by `hash`,
+as per `getopt-parse->function-arguments`.
+
+TODO: add examples, discuss abort-on-error behavior,
+lack of automatic help, etc.
 
 ### call-with-processed-command-line
+```scheme
+(call-with-processed-command-line processor command-line function) => results-of-function
+```
+
+Generic function of three arguments:
+  - a `processor` that describes a `getopt` specification,
+  - a `command-line`, list of strings as provided by the invoking process, and
+  - a `function` to be called with the results of processing the command-line.
+
+The function is generic in the first argument.
+The default method recognizes a `getopt` specification as first argument,
+and appropriately calls `getopt-parse` and `call-with-getopt-parse`
+to process the command-line. It also recognizes a list as being arguments
+to which to apply `getopt` to obtain a specification,
+with which to proceed as above.
+
+You may define more methods, to work with your own variant of `getopt`,
+or with innovative ways to incrementally compose `getopt` specifications
+e.g. with prototype objects like `gerbil-poo`.
+
+TODO: add examples, discuss abort-on-error behavior,
+lack of automatic help, etc.
diff --git a/doc/reference/std/cli/shell.md b/doc/reference/std/cli/shell.md
index bf720e5d6..93acc5c9e 100644
--- a/doc/reference/std/cli/shell.md
+++ b/doc/reference/std/cli/shell.md
@@ -20,4 +20,3 @@ in gerbil-utils.
 ### escape-shell-tokens
 
 ### ->envvar
-