blowfish: Document the undocumented.

- read-blowfish-file-header
- write-blowfish-file-header
- blowfish-file?
- import-blowfish

Mention the pivotal role of the deprecated blowfish-available?
procedure too.

diff --git a/src/blowfish/README b/src/blowfish/README
index 6641ac33debfd18d75c920e7b343caa787ddf9d1..1ad004724b7e9c89148ac25f35bf06afb1b556c9 100644 (file)
--- a/src/blowfish/README
+++ b/src/blowfish/README
@@ -25,26 +25,6 @@ creating a short optiondb file.
        ~/.mit-scheme-x86-64:/usr/local/lib/mit-scheme-x86-64
     make install
 
-To use:
-
-    (load-option 'blowfish)
-    (import-blowfish)
-
-Import-blowfish will modify the REPL's current environment by adding
-bindings linked to the plugin's exports.  They are not exported to the
-global environment because they would conflict with the deprecated
-exports from (runtime blowfish).
-
-To import into a CREF package set, add this to your .pkg file:
-
-    (global-definitions blowfish/)
-
-    (define-package (your package name)
-      (parent (your package parent))
-      (import (blowfish)
-              blowfish-set-key
-              ...))
-
 Please see the manual for API details.  An Info version should have
 been installed along with the plugin.  If you have a texlive or
 similar TeX environment installed, then HTML and PDF versions of the

diff --git a/src/blowfish/blowfish.texi b/src/blowfish/blowfish.texi
index f1d607aed0bab1edf76be83a6975323d41c9a798..a0c908501b3e20305427e690971aa00e88db9cc4 100644 (file)
--- a/src/blowfish/blowfish.texi
+++ b/src/blowfish/blowfish.texi
@@ -78,16 +78,50 @@ Documentation License.''
 @chapter Introduction
 
 This plugin is a dynamically loadable implementation of the Blowfish
-block cipher.
-
-The Blowfish block cipher is totally obsolete and you should never use
-it for new data.
-It is provided only for compatibility with existing ciphertext.
-
-The plugin includes a Scheme procedure to feed bytes from a binary
-input port to the library, and write the encrypted bytes to a binary
+block cipher.  The Blowfish block cipher is totally obsolete and you
+should never use it for new data.  It is provided only for
+compatibility with existing ciphertext.
+
+The plugin creates its bindings in the @code{(blowfish)} package.
+These can be imported into @code{(your package)} by adding a
+@code{global-definitions} declaration to your @file{.pkg} file, as
+shown below.
+
+@example
+    (global-definitions blowfish/)
+
+    (define-package (your package)
+      (parent (your package parent))
+      (import (blowfish)
+              blowfish-set-key
+              ...))
+@end example
+
+For interactive use, enter:
+
+@example
+    (load-option 'blowfish)
+    (import-blowfish)
+@end example
+
+The @code{import-blowfish} procedure will modify the current REPL's
+environment, adding bindings linked to the plugin's.  (The plugin's
+``exported'' bindings are not linked to the deprecated bindings in the
+global environment.)
+
+The @code{blowfish-encrypt-port} procedure is the plugin's top-level
+entry point, reading bytes from a binary input port, encrypting or
+decrypting them with a supplied key, and writing them to a binary
 output port.
 
+The plugin implements the same API as that exported from the
+@code{(runtime blowfish)} package, and is in fact the same code in a
+new wrapper.  The plugin is automatically loaded when the deprecated
+@code{blowfish-available?} procedure is called.  Until then the other
+deprecated bindings in @code{(runtime blowfish)} (and @code{()}) are
+unassigned.  After the plugin is loaded, the bindings can be used as
+before.
+
 @node Procedures
 @chapter Procedures
 
@@ -173,7 +207,26 @@ Apply Blowfish in Output Feed-Back mode.
 The returned value is the new value of Num.
 @end deffn
 
-Two convenience procedures are also provided.
+@deffn Procedure compute-blowfish-init-vector
+Returns a uniform random initialization vector
+@end deffn
+
+@deffn Procedure read-blowfish-file-header port
+Returns the init vector in the file header read from @var{port} (or
+signals an error).
+@end deffn
+
+@deffn Procedure write-blowfish-file-header port
+Generates an init vector (with @code{compute-blowfish-init-vector})
+and writes it to @var{port} in a version 2 file header.
+@end deffn
+
+A few convenience procedures are also provided.
+
+@deffn Procedure blowfish-file? pathname
+Opens and reads a few bytes from the file at @var{pathname}.  Returns
+@code{#f} unless it finds the standard file header.
+@end deffn
 
 @deffn Procedure blowfish-encrypt-port input output key init encrypt?
 Reads bytes from @var{input}, which should be in blocking mode, until
@@ -185,8 +238,9 @@ the latter).
 (when @code{#f}).
 @end deffn
 
-@deffn Procedure compute-blowfish-init-vector
-Returns a uniform random initialization vector
+@deffn Procedure import-blowfish
+Define the ``exported'' names in the current REPL environment for
+interactive use.
 @end deffn
 
 The Blowfish cipher was invented and described by Counterpane (see