Update docs

* NEWS: Document changes.
* doc/gdbm.texi: Document new variables.

2 files changed, 99 insertions, 15 deletions

diff --git a/NEWS b/NEWS
index 1f267d0..76b3c79 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-GNU dbm NEWS -- history of user-visible changes. 2021-08-09
+GNU dbm NEWS -- history of user-visible changes. 2021-08-12
 Copyright (C) 1990-2021 Free Software Foundation, Inc.
 See the end of file for copying conditions.
 
@@ -15,11 +15,62 @@ recover the database state corresponding to the most recent
 successful gdbm_sync() call before the crash.  See the chapter 16
 "Crash Tolerance" in the GDBM manual.
 
-* gdbmtool: Fix string output in non-ASCII encodings
+* New database file format: numsync
+
+To support crash tolerance, the "numsync" database format is
+introduced.  To create a database in numsync format, the gdbm_open 
+(or gdbm_fd_open) function must be given the GDBM_NEWDB|GDBM_NUMSYNC
+flags.  The GDBM_NUMSYNC flag also takes effect when used together
+with GDBM_WRCREAT, provided that the new file is created.
+
+New function gdbm_convert() is provided for converting the databases
+from standard GDBM format to numsync and vice versa.
+
+The gdbmtool tool can also be used for converting databases between
+these two formats.
+
+* Changes in gdbmtool
+
+** Fix string output in non-ASCII encodings
 
 Printable multi-byte sequences are correctly represented on output.
 This also fixes octal representation of unprintable characters.
 
+** The filename variable
+
+This variable supplies the name of database file for use in "open"
+command, if the latter is called without arguments.  If "open" is
+called with the file name argument, the "filename" variable is
+initialized to this value.
+
+** The fd variable
+
+If set, its value must be an open file descriptor referring to a
+GDBM database file.  The "open" command will use gdbm_fd_open
+function to use this file.   Upon closing the database, this
+descriptor will be closed and the variable will be unset.
+
+The file descriptor to use can also be supplied using the
+-d (--db-descriptor) command line option.
+
+** The format variable
+
+Defines the format in which new databases will be created.  Allowed
+values are: "standard" (default) and numsync.
+
+** New commands: upgrade and downgrade
+
+The "upgrade" command converts current database to the numsync
+(extended) format.  The "downgrade" command converts current database
+to the standard format.
+
+** New command: snapshot
+
+The "snapshot" command is part of the new crash tolerance support.
+Given the names of two snapshot files, it analyzes them and selects
+the one to be used for database recovery.  See the GDBM manual,
+section 17.5 "Manual crash recovery" for a detailed discussion of its
+use.
 
 Version 1.20, 2021-06-17
 
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
index 9c54f74..037baea 100644
--- a/doc/gdbm.texi
+++ b/doc/gdbm.texi
@@ -3205,7 +3205,34 @@ Sets the block size.  @xref{Open, block_size}.  Unset by default.
 
 @deftypevr {gdbmtool variable} numeric cachesize
 Sets the cache size.  @xref{Options, GDBM_SETCACHESIZE}.
-By default this variable is not set.
+
+This variable affects the currently opened database immediately.  It
+is also used by @command{open} command.
+
+To enable automatic cache size selection, unset this variable.  This
+is the default.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} string filename
+Name of the database file.  If the @code{open} command is called
+without argument (e.g. called implicitly), this variable names the
+database file to open.  If @code{open} is called with file name
+argument, upon successful opening of the database the @code{filename}
+variable is initialized with its file name.
+
+This variable cannot be unset.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} number fd
+File descriptor of the database file to open.  If this variable is
+set, its value must be an open file descriptor referring to a
+@command{GDBM} database file.  The @code{open} command will use
+@code{gdbm_fd_open} function to use this file (@pxref{gdbm_fd_open}).
+When this database is closed, the descriptor will be closed as well
+and the @code{fd} variable will be unset.
+
+See also the @option{-d} (@option{--db-descriptor}) command line
+option in @ref{invocation}.
 @end deftypevr
 
 @anchor{format variable}
@@ -3288,16 +3315,16 @@ effective memory management at the cost of slight increase in
 execution time when calling @code{gdbm_delete}. @xref{Options,
 GDBM_SETCOALESCEBLKS}.
 
-This variable affects the @command{open} command and should be set
-before invoking it.
+This variable affects the currently opened database immediately and
+will be used by @command{open} command, when it is invoked.
 @end deftypevr
 
 @deftypevr {gdbmtool variable} bool centfree
 Set to @code{true}, enables the use of central free block pool in
 newly opened databases. @xref{Options, GDBM_SETCENTFREE}.
 
-This variable affects the @command{open} command and should be set
-before invoking it.
+This variable affects the currently opened database immediately and
+will be used by @command{open} command, when it is invoked.
 @end deftypevr
 
 The following commands are used to list or modify the variables:
@@ -3315,19 +3342,25 @@ For example:
 
 @example
 @group
-ps1="%p>%_"
-ps2="%_>%_"
+# blocksize is unset
+# cachesize is unset
+nocentfree
+nocoalesce
+confirm
 delim1=","
 delim2=","
-confirm
-# cachesize is unset
-# blocksize is unset
-open="wrcreat"
+# fd is unset
+filemode=644
+filename="junk.gdbm"
+format="standard"
 lock
 mmap
-nosync
+open="wrcreat"
 pager="less"
+ps1="%p>%_"
+ps2="%_>%_"
 # quiet is unset
+nosync
 @end group
 @end example
 
@@ -3506,7 +3539,7 @@ Name of the database to open, if no argument is given.
 File descriptor to use.  If set, this must be an open file descriptor
 referring to a valid database file.  The database will be opened using
 @code{gdbm_fd_open} (@pxref{gdbm_fd_open}).  The file descriptor will
-be closed upon closing the database.
+be closed and the variable unset upon closing the database.
 
 @item filemode
 Specifies the permissions to use in case a new file is created.