Revert doc changes to see if it compiles

doc/.vuepress/config.js

@@ -147,17 +147,6 @@ module.exports = {
                         ]
                       },
 
-                      { title: "Support for the Unix Command Line Interface",
-                        path: "/reference/std/cli/",
-                        children: [
-                            "cli/",
-                            "cli/getopt",
-                            "cli/shell",
-                            "cli/print-exit",
-                            "cli/multicall",
-                        ]
-                      },
-
                       { title: "Miscellaneous Libraries",
 		                path: '/reference/std/misc/',
 		                children: [

doc/reference/std/errors.md

@@ -426,23 +426,7 @@ displaying the exception with `display-exception`).
 ```
 
 Invokes `thunk` with an exception handler that dumps the exception
-stack trace with `dump-stack-trace!`
-if `(dump-stack-trace?)` is true (the default).
-
-### dump-stack-trace?
-```scheme
-(define dump-stack-trace? (make-parameter #t))
-```
-A parameter that controls whether `with-exception-stack-trace`
-will actually dump a stack trace to standard error.
-
-You can `(dump-stack-trace? #f)`
-or locally `(parameterize ((dump-stack-trace? #f)) ...)`
-to disable this stack trace dump,
-in case you are building a program for end-users rather than for developers,
-and want to control what limited error output they see.
-Or you can re-enable them based on a debug flag at the CLI
-in cases you want them to provide you with extra debugging information.
+stack trace with `dump-stack-trace!`.
 
 ### dump-stack-trace!
 ```scheme
@@ -451,38 +435,3 @@ in cases you want them to provide you with extra debugging information.
 
 Displays the exception `exn`, dumping the stack trace of continuation
 `cont` if there is no stack trace information in the exception itself.
-
-### exit-with-error
-```scheme
-(exit-with-error exception) => [exit]
-```
-Display the `exception` to current error port and exit with error code 2.
-
-### exit-on-error?
-```scheme
-(def exit-on-error? (make-parameter #t))
-```
-This parameter controls whether `call-with-exit-on-error`, `with-exit-on-error`,
-`call-with-getopt`, and any function that indirectly uses them,
-will exit if an error is caught, rather than pass on the error
-and return to the REPL (or let a more fundamental function exit).
-
-### call-with-exit-on-error
-```scheme
-(call-with-exit-on-error thunk)
-```
-Calls the `thunk` in an environment wherein if an error is caught and
-`(exit-on-error)` is true, `exit-with-error` will be called,
-causing an error message to be printed and the process to exit with exit code 2.
-If `(exit-on-error)` is false, the error will simply be raised again.
-
-This mechanism enables users to modify the parameter
-(e.g. via a flag passed at the Unix CLI or a change made at the Scheme REPL)
-and control whether to exit with an error (e.g. for end-users)
-or enter a debugger REPL (e.g. for developers).
-
-### with-exit-on-error
-```scheme
-(with-exit-on-error body ...)
-```
-Evaluates the `body` as in a `thunk` passed to `call-with-exit-on-error`.

doc/reference/std/getopt.md

@@ -1,15 +1,188 @@
 # Command Line Argument Parsing
 
-This is the old name of the `:std/cli/getopt` module,
-that provides facilities for command line argument parsing.
-
-As of Gerbil v0.19 this name is deprecated and
-you should be using the new library instead,
-but the old name remains available for now
-for the sake of backward compatibility.
+The `:std/getopt` library provides facilities for command line argument parsing.
 
 ::: tip usage
-(import :std/cli/getopt)
+(import :std/getopt)
 :::
 
-See [:std/cli/getopt](cli/getopt.md) for the module documentation.
+## Interface
+
+### getopt
+```scheme
+(getopt <specifier> ...)
+=> <parser>
+
+specifier:
+ (command id [help: text] <cmd-specifier>)
+ <cmd-specifier> ...
+
+cmd-specifier:
+ (flag id short [long])
+ (option id short [long] [help: text] [value: proc] [default: value])
+ (argument id [help: text] [value: proc])
+ (optional-argument id [help: text] [value: proc] [default: value])
+ (rest-arguments id [help: text] [value: proc])
+
+```
+
+`getopt` creates a command line parser, which can be used to parse arguments
+with `getopt-parse`.
+
+### getopt-parse
+```scheme
+(getopt-parse <parser> args)
+=> (values cmd-id options)
+   options
+```
+
+`getopt-parse` accepts a parser and a list of string arguments and parses
+according to the parser specification. If it is parsing a specification with
+subcommands, it returns two values, the command id and a hash table with the
+parsed options. Otherwise it just returns the hash table with the parsed options.
+An exception is raised if parsing the arguments fails.
+
+### getopt-error?
+```scheme
+(getopt-error? obj)
+=> boolean
+```
+
+If parsing fails, then a `getopt-error` is raised, which can be guarded with
+`getopt-error?`.
+
+### getopt-display-help
+```scheme
+(getopt-display-help <tip> program-name [port = (current-output-port)])
+
+
+tip:
+ <getopt-error>
+ <parser>
+ <command>
+```
+
+The procedure `getopt-display-help` can be used to display
+a help message for a getopt error according to the argument specification.
+
+### getopt-display-help-topic
+```scheme
+(getopt-display-help-topic <parser> topic program-name [port = (current-output-port)])
+```
+
+The procedure `getopt-display-help-topic` can be used to display a help page
+for a subcommand.
+
+### getopt?
+```scheme
+(getopt? obj)
+=> boolean
+```
+
+Returns true if the object is a getopt parser
+
+### getopt-object?
+```scheme
+(getopt-object? obj)
+=> boolean
+```
+
+Returns true if the object is a getopt command or command specifier.
+
+### call-with-getopt
+```scheme
+(call-with-getopt proc args
+                  program: program
+                  help: (help #f)
+                  exit-on-error: (exit-on-error? #t)
+                  . gopts)
+```
+
+This shim around getopt parsing eliminates all the repetitive
+boilerplate around argument parsing with getopt.
+
+It creates a getopt parser that parses with options `gopts`, automatically
+including a help option or command accordingly.
+
+It then uses the parser to pare `args`, handling the exceptions and
+displayin help accordingly; if `exit-on-error` is true (the default),
+then parsing errors will exit the program.
+
+If the parse succeeds it invokes `proc` with the output of the parse.
+
+## Example
+
+For an example, here the a command line parser for the `gxpkg` program:
+```scheme
+(def (main . args)
+  (def install-cmd
+    (command 'install help: "install one or more packages"
+             (rest-arguments 'pkg help: "package to install")))
+  (def uninstall-cmd
+    (command 'uninstall help: "uninstall one or more packages"
+             (flag 'force "-f" help: "force uninstall even if there are orphaned dependencies")
+             (rest-arguments 'pkg help: "package to uninstall")))
+  (def update-cmd
+    (command 'update help: "update one or more packages"
+             (rest-arguments 'pkg help: "package to update; all for all packages")))
+  (def link-cmd
+    (command 'link help: "link a local development package"
+             (argument 'pkg help: "package to link")
+             (argument 'src help: "path to package source directory")))
+  (def unlink-cmd
+    (command 'unlink help: "unlink one or more local development packages"
+             (flag 'force "-f" help: "force unlink even if there are orphaned dependencies")
+             (rest-arguments 'pkg help: "package to unlink")))
+  (def build-cmd
+    (command 'build help: "rebuild one or more packages and their dependents"
+             (rest-arguments 'pkg help: "package to build; all for all packages")))
+  (def clean-cmd
+    (command 'clean help: "clean compilation artefacts from one or more packages"
+             (rest-arguments 'pkg help: "package to clean")))
+  (def list-cmd
+    (command 'list help: "list installed packages"))
+  (def retag-cmd
+    (command 'retag help: "retag installed packages"))
+  (def search-cmd
+    (command 'search help: "search the package directory"
+             (rest-arguments 'keywords help: "keywords to search for")))
+
+  (call-with-getopt gxpkg-main args
+    program: "gxpkg"
+    help: "The Gerbil Package Manager"
+    install-cmd
+    uninstall-cmd
+    update-cmd
+    link-cmd
+    unlink-cmd
+    build-cmd
+    clean-cmd
+    list-cmd
+    retag-cmd
+    search-cmd))
+
+(def (gxpkg-main cmd opt)
+  (let-hash opt
+    (case cmd
+      ((install)
+       (install-pkgs .pkg))
+      ((uninstall)
+       (uninstall-pkgs .pkg .?force))
+      ((update)
+       (update-pkgs .pkg))
+      ((link)
+       (link-pkg .pkg .src))
+      ((unlink)
+       (unlink-pkgs .pkg .?force))
+      ((build)
+       (build-pkgs .pkg))
+      ((clean)
+       (clean-pkgs .pkg))
+      ((list)
+       (list-pkgs))
+      ((retag)
+       (retag-pkgs))
+      ((search)
+       (search-pkgs .keywords)))))
+
+```