From c15045478fb9e0dc849aa165dbbeb8ca987fab5f Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <fare@tunes.org>
Date: Sun, 5 Nov 2023 00:53:03 +0000
Subject: [PATCH] doc update
---
doc/reference/gerbil/expander/README.md | 2 +-
doc/reference/gerbil/runtime/MOP.md | 4 ++--
doc/reference/gerbil/runtime/hash-tables.md | 16 ++++++++--------
doc/reference/gerbil/runtime/misc-procedures.md | 4 ++--
doc/reference/gerbil/runtime/strings.md | 6 +++---
doc/reference/gerbil/runtime/symbols.md | 4 ++--
doc/reference/std/cli/README.md | 4 ++--
doc/reference/std/cli/getopt.md | 4 ++--
doc/reference/std/cli/shell.md | 2 +-
doc/reference/std/getopt.md | 12 +++++-------
doc/reference/std/misc/alist.md | 2 +-
doc/reference/std/misc/list.md | 4 ++--
doc/reference/std/misc/plist.md | 2 +-
doc/reference/std/text/base64.md | 8 ++++----
14 files changed, 36 insertions(+), 38 deletions(-)
diff --git a/doc/reference/gerbil/expander/README.md b/doc/reference/gerbil/expander/README.md
index 414092659..f6717bea6 100644
--- a/doc/reference/gerbil/expander/README.md
+++ b/doc/reference/gerbil/expander/README.md
@@ -681,7 +681,7 @@ Please document me!
Please document me!
-### core-module-export->import
+### core-module-export->import
```
(core-module-export->import ...)
```
diff --git a/doc/reference/gerbil/runtime/MOP.md b/doc/reference/gerbil/runtime/MOP.md
index d4494885d..4ea4381d4 100644
--- a/doc/reference/gerbil/runtime/MOP.md
+++ b/doc/reference/gerbil/runtime/MOP.md
@@ -294,7 +294,7 @@ Accesses *obj*'s field with absolute offset *off*; there is no type check.
Mutates *obj*'s field with absolute offset *off* to *val*; there is no type check.
-## struct->list
+## struct->list
``` scheme
(struct->list obj) -> list
@@ -482,7 +482,7 @@ Returns the value associated with slot *slot* in *obj*, without any checks.
Sets the value associated with slot *slot* in *obj* to *val*, without any checks.
-## class->list
+## class->list
``` scheme
(class->list obj)
diff --git a/doc/reference/gerbil/runtime/hash-tables.md b/doc/reference/gerbil/runtime/hash-tables.md
index 909a589ba..da5cac861 100644
--- a/doc/reference/gerbil/runtime/hash-tables.md
+++ b/doc/reference/gerbil/runtime/hash-tables.md
@@ -240,7 +240,7 @@ Merges *more* hash tables into *hash*. Entries in hash tables on the left take p
((a . 1) (z . 6) (b . 2) (c . 3))
```
-## hash->list
+## hash->list
``` scheme
(hash->list hash) -> list
@@ -249,7 +249,7 @@ Merges *more* hash tables into *hash*. Entries in hash tables on the left take p
Returns the bindings of *hash* as an alist.
-## list->hash-table
+## list->hash-table
``` scheme
(list->hash-table lst . options) -> hash table
@@ -258,7 +258,7 @@ Returns the bindings of *hash* as an alist.
Creates a hash table from an alist *lst*.
-## list->hash-table-eq
+## list->hash-table-eq
``` scheme
(list->hash-table-eq lst . options) -> hash table
@@ -267,7 +267,7 @@ Creates a hash table from an alist *lst*.
Same as `list->hash-table`, but using `eq?` as the test function for the table.
-## list->hash-table-eqv
+## list->hash-table-eqv
``` scheme
(list->hash-table-eqv lst . options) -> hash table
@@ -276,7 +276,7 @@ Same as `list->hash-table`, but using `eq?` as the test function for the table.
Same as `list->hash-table`, but using `eqv?` as the test function for the table.
-## hash->plist
+## hash->plist
``` scheme
(hash->plist hash) -> list
@@ -285,7 +285,7 @@ Same as `list->hash-table`, but using `eqv?` as the test function for the table.
Returns the bindings of *hash* as a plist.
-## plist->hash-table
+## plist->hash-table
``` scheme
(plist->hash-table lst) -> hash table
@@ -294,7 +294,7 @@ Returns the bindings of *hash* as a plist.
Creates a hash table from a plist *lst*.
-## plist->hash-table-eq
+## plist->hash-table-eq
``` scheme
(plist->hash-table-eq lst) -> hash table
@@ -303,7 +303,7 @@ Creates a hash table from a plist *lst*.
Same as `plist->hash-table`, but using `eq?` as the test function for the table.
-## plist->hash-table-eqv
+## plist->hash-table-eqv
``` scheme
(plist->hash-table-eqv lst) -> hash table
diff --git a/doc/reference/gerbil/runtime/misc-procedures.md b/doc/reference/gerbil/runtime/misc-procedures.md
index 09c015f8c..247995f28 100644
--- a/doc/reference/gerbil/runtime/misc-procedures.md
+++ b/doc/reference/gerbil/runtime/misc-procedures.md
@@ -20,7 +20,7 @@ it is considered a single value.
Returns the *n*th value in the object *obj*. If the object is not multiple `values`,
it returns the object itself.
-### values->list
+### values->list
``` scheme
(values->list obj) -> list
@@ -30,7 +30,7 @@ it returns the object itself.
Converts multiple `values` to a list. If the object *obj* is not multiple `values`,
it returns a list containing the object.
-### subvector->list
+### subvector->list
``` scheme
(subvector->list obj [start = 0]) -> list
diff --git a/doc/reference/gerbil/runtime/strings.md b/doc/reference/gerbil/runtime/strings.md
index 1b7881f6a..5b20bc3c5 100644
--- a/doc/reference/gerbil/runtime/strings.md
+++ b/doc/reference/gerbil/runtime/strings.md
@@ -1,6 +1,6 @@
# Strings
-## bytes->string
+## bytes->string
```
(bytes->string bstr [encoding = 'UTF-8]) -> string
@@ -12,7 +12,7 @@ Decodes a byte vector *bstr* to a string.
Note: if you are decoding UTF-8, then you should consider using `string->utf8`
from `:std/text/utf8` which is considerably faster.
-## string->bytes
+## string->bytes
``` scheme
(string->bytes str [encoding = 'UTF-8]) -> u8vector
@@ -25,7 +25,7 @@ Note: if you are encoding UTF-8, then you should consider using `utf8->string`
from `:std/text/utf8` which is considerably faster.
-## substring->bytes
+## substring->bytes
``` scheme
(substring->bytes str start end [encoding = 'UTF-8]) -> u8vector
diff --git a/doc/reference/gerbil/runtime/symbols.md b/doc/reference/gerbil/runtime/symbols.md
index ca94278fe..a0fa5e2b0 100644
--- a/doc/reference/gerbil/runtime/symbols.md
+++ b/doc/reference/gerbil/runtime/symbols.md
@@ -32,7 +32,7 @@ Returns true if the object *obj* is an interned symbol.
Returns true if the object *obj* is an interned keyword.
-## symbol->keyword
+## symbol->keyword
``` scheme
(symbol->keyword sym) -> keyword
@@ -41,7 +41,7 @@ Returns true if the object *obj* is an interned keyword.
Converts a symbol *sym* to a keyword.
-## keyword->symbol
+## keyword->symbol
``` scheme
(keyword->symbol kw) -> symbol
diff --git a/doc/reference/std/cli/README.md b/doc/reference/std/cli/README.md
index 5105e4a4d..809a8d63d 100644
--- a/doc/reference/std/cli/README.md
+++ b/doc/reference/std/cli/README.md
@@ -1,6 +1,6 @@
-# Unix Command Line Interface
+# Command Line Interface
-The following libraries are provided to support the Unix Command Line Interface (CLI):
+The following libraries are provided to support the Command Line Interface (CLI):
- [:std/cli/getopt](getopt.md)
- [:std/cli/shell](shell.md)
- [:std/cli/print-exit](print-exit.md)
diff --git a/doc/reference/std/cli/getopt.md b/doc/reference/std/cli/getopt.md
index f37565f8f..0036d1c2c 100644
--- a/doc/reference/std/cli/getopt.md
+++ b/doc/reference/std/cli/getopt.md
@@ -189,7 +189,7 @@ For an example, here the a command line parser for the `gxpkg` program:
(search-pkgs .keywords)))))
```
-### getopt-parse->function-arguments
+### getopt-parse->function-arguments
```scheme
(getopt-parse->function-arguments getopt h) => list-of-arguments
```
@@ -250,7 +250,7 @@ e.g. with prototype objects like `gerbil-poo`.
TODO: add examples, discuss abort-on-error behavior,
lack of automatic help, etc.
-### ->getopt-spec
+### ->getopt-spec
```scheme
(->getopt-spec arg) => list-of-getopt-arguments
```
diff --git a/doc/reference/std/cli/shell.md b/doc/reference/std/cli/shell.md
index b3b61f296..808c51f8e 100644
--- a/doc/reference/std/cli/shell.md
+++ b/doc/reference/std/cli/shell.md
@@ -70,7 +70,7 @@ when included in a Unix shell command, will expand into the input `string`.
```
:::
-### ->envvar
+### ->envvar
```scheme
(->envvar . str) => environment-variable-name
```
diff --git a/doc/reference/std/getopt.md b/doc/reference/std/getopt.md
index aa84b9183..0d31ee37c 100644
--- a/doc/reference/std/getopt.md
+++ b/doc/reference/std/getopt.md
@@ -1,17 +1,15 @@
# Command Line Argument Parsing
-This is the old name of the `:std/cli/getopt` module,
+This is the old name of the [`:std/cli/getopt`](cli/getopt.md) 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.
+Up to Gerbil v0.18, `:std/getopt` was the only name for this module.
+As of Gerbil v0.19, both names are supported.
+However, we recommend you use the new name `:std/cli/getopt` from now on,
+as we may deprecate the old name in the future.
::: tip usage
```scheme
(import :std/cli/getopt)
```
:::
-
-<!-- See [:std/cli/getopt](cli/getopt.md) for the module documentation. -->
diff --git a/doc/reference/std/misc/alist.md b/doc/reference/std/misc/alist.md
index 7c867a38d..070d4d8c5 100644
--- a/doc/reference/std/misc/alist.md
+++ b/doc/reference/std/misc/alist.md
@@ -40,7 +40,7 @@ A proper association list is a list of pairs and may be of the following forms:
```
:::
-## plist->alist
+## plist->alist
``` scheme
(plist->alist plist) -> alist | error
diff --git a/doc/reference/std/misc/list.md b/doc/reference/std/misc/list.md
index 355e3a76e..afd3b509a 100644
--- a/doc/reference/std/misc/list.md
+++ b/doc/reference/std/misc/list.md
@@ -6,7 +6,7 @@
```
:::
-## length=?, length<? ... length>=? ##
+## length=?, length<? ... length>=? ##
```scheme
(length=? lst1 lst2) -> boolean
@@ -53,7 +53,7 @@ Also, either of these two lists is allowed to be circular, but not both.
```
:::
-## length=n?, length<n? ... length>=n? ##
+## length=n?, length<n? ... length>=n? ##
```scheme
(length=n? lst n) -> boolean | error
diff --git a/doc/reference/std/misc/plist.md b/doc/reference/std/misc/plist.md
index f6bf60482..19e1833d3 100644
--- a/doc/reference/std/misc/plist.md
+++ b/doc/reference/std/misc/plist.md
@@ -42,7 +42,7 @@ form: `((key1 value1 key2 value2 ...))`
```
:::
-## alist->plist
+## alist->plist
``` scheme
(alist->plist alist) -> plist | error
diff --git a/doc/reference/std/text/base64.md b/doc/reference/std/text/base64.md
index 83639790c..25e33a829 100644
--- a/doc/reference/std/text/base64.md
+++ b/doc/reference/std/text/base64.md
@@ -36,7 +36,7 @@ For some more references see:
```
:::
-## base64-string->u8vector
+## base64-string->u8vector
``` scheme
(base64-string->u8vector str [nopadding-ok?: #t] [urlsafe?: #f]) -> u8vector
@@ -50,7 +50,7 @@ control how the conversion is done. If *nopadding-ok?* is #t (default) the value
is converted. If *urlsafe?* is #t, the result is URL encoded as specified in RFC 4648.
...
-## base64-substring->u8vector
+## base64-substring->u8vector
``` scheme
(base64-substring->u8vector str start end [nopadding-ok?: #t] [urlsafe?: #f]) ->
u8vector
@@ -65,7 +65,7 @@ u8vector
Returns a newly allocated u8vector containing Base64 encoded value of *str* from
*start* to *end* like `base64-string->u8vector`.
-## u8vector->base64-string
+## u8vector->base64-string
``` scheme
(u8vector->base64-string u8vect [width: 0] [padding?: #t] [urlsafe?: #f]) -> string
@@ -77,7 +77,7 @@ Returns a newly allocated u8vector containing Base64 encoded value of *str* from
Returns a newly allocated Base64 string with bytes of *u8vect* in left-to-right order to Base64 encoded string.
-## subu8vector->base64-string
+## subu8vector->base64-string
``` scheme
(subu8vector->base64-string u8vect start end [width: 0] [padding?: #t] [urlsafe?: #f]) -> string