user manual: Add section Proposed Changes to chapter Changes.

diff --git a/doc/user-manual/user.texinfo b/doc/user-manual/user.texinfo
index 0dbab918ff913238e289a09130d6bb0e1dbdfb2c..2ba71d526815f8d49eef9a91df19aafac37292bd 100644 (file)
--- a/doc/user-manual/user.texinfo
+++ b/doc/user-manual/user.texinfo
@@ -213,58 +213,82 @@ at least Unix-like system can be found in a following chapter.
 This experimental version of MIT/GNU Scheme was given a new project
 name, MIT/GNU Scheme Pucked, with a new command name,
 @code{mit-scheme-pucked}, so that it can be installed alongside the
-stable version.  The names of the plugin packages also changed, but
-not their option names in Scheme (arguments to @code{load-option}).
+official release.  While it comes with an assortment of plugins and a
+strange name, the core of the system is largely unchanged.  However
+the core is the @emph{bleeding edge core}.  The head of the project's
+development branch on Savannah is merged in frequently.  Thus it
+includes changes proposed for the next official release.
 
-The core system is largely unchanged by this accommodation of the new
-plugins.  If you previously said
+@section Proposed Changes
+
+@itemize @bullet
+@item
+Most of the bindings that we would fluid bind with @code{fluid-let},
+e.g. @code{*parser-radix*}, are deprecated.  Parameters, found in
+corresponding bindings (e.g. @code{param:parser-radix}), should be
+used instead.  @footnote{Parameters will be more easily implemented in
+SMPing (Symmetrically Multi-Processing) worlds.}  For example, rather
+than fluid binding @code{*parser-radix*} with @code{fluid-let}
 @example
-    $ mit-scheme --load my-shtick
+(fluid-let ((*parser-radix* 16))
+  ...)
 @end example
 @noindent
-you should be able to say
+you should parameterize @code{param:parser-radix}
 @example
-    $ mit-scheme-pucked --load my-shtick
+(parameterize ((param:parser-radix 16))
+  ...)
 @end example
-@noindent
-and be no worse off.
-
-@noindent
-Users may want to add the following to their shtick.
 
-@itemize @bullet
 @item
-Scheme's Debian packaging includes a @file{.menu} file in
-@url{freedesktop.org} format.  In the right place it makes this Scheme
-available through any @file{.menu} aware application launcher.  The
-lucky user can install the @code{x11-screen} package and find a launch
-button, a picture of a lambda holding a fountain pen.
+New unicode support means your old code can generate ``legacy
+strings'' suitable only for ``legacy ports''.  Most string operations
+can handle legacy @emph{or} Unicode strings, but new procedures may
+only handle Unicode strings, and several old procedures are marked as
+``deprecated.''
 
 @item
-The installation process includes HTML documentation by default.  In
-the right place these files are available in your web browser, whether
-online or offline, using a file URL like the following Ubuntu locator.
+CREF now supports deprecated bindings.  It will list references to
+them in your packaging construction reports (@file{.crf} files).
+@end itemize
+
+The proposed changes to the core system are intended to produce a new
+release compatible with the current release.  The new release will
+support both parameters and fluid bound bindings, both legacy and
+Unicode strings.  It should thus be possible to run mixtures of old
+and new code, allowing you to replace references to deprecated
+bindings in stages.
+@cindex cond-expand feature
+@cindex feature, cond-expand
+And you can use the @code{cond-expand} feature @code{pucked} to keep
+experimental replacements out of stable worlds.
+
+@section Experimental Changes
+
+The experimental code in this ``pucked'' version is almost entirely
+contained in the plugins.  The core was changed only to replace the
+microcode modules and hook the Gtk screen into Edwin.  Neither change
+should be apparent to the casual user.  And in this world Edwin is a
+plugin; its changes should not be counted as changes to the core.
+
+If your shtick does not hack Edwin and you previously said
 @example
-    @url{file:///usr/share/doc/mit-scheme-pucked/html/index.html}
+    $ mit-scheme --load my-shtick
 @end example
-HTML documentation for installed plugins is found in the same location.
-
-@item
-Lucky users can install a Planetarium package and see some fancy,
-Scheme-generated graphics.
-
-@item
-And users who are @emph{really} lucky can install the Gtk Screen
-package and try out a graphical Edwin.
-@end itemize
+@noindent
+you should be able to say
+@example
+    $ mit-scheme-pucked --load my-shtick
+@end example
+@noindent
+and be no worse off.
 
 @noindent
-Users may also need to make the following changes to their shtick.
+Users @emph{may} need to make the following changes to their shtick.
 
 @itemize @bullet
-
 @item
-The Edwin subsystem is now a plugin; it is no longer included in the
+The Edwin subsystem is a plugin; it is no longer included in the
 default band, @file{all.com}.  However that band still handles the
 @code{--edit} command line option and provides an @code{edit}
 procedure.  Either method of launching Edwin autoloads it with an
@@ -312,6 +336,35 @@ are transparent except that loading Edwin now loads SOS.
 
 @end itemize
 
+@noindent
+Users may also want to add the following to their shtick.
+
+@itemize @bullet
+@item
+Scheme's Debian packaging includes a @file{.menu} file in
+@url{freedesktop.org} format.  In the right place it makes this Scheme
+available through any @file{.menu} aware application launcher.  The
+lucky user can install the @code{x11-screen} package and find a launch
+button, a picture of a lambda holding a fountain pen.
+
+@item
+The installation process includes HTML documentation by default.  In
+the right place these files are available in your web browser, whether
+online or offline, using a file URL like the following Ubuntu locator.
+@example
+    @url{file:///usr/share/doc/mit-scheme-pucked/html/index.html}
+@end example
+HTML documentation for installed plugins is found in the same location.
+
+@item
+Lucky users can install a Planetarium package and see some simple
+Scheme-generated graphics.
+
+@item
+And users who are @emph{really} lucky can install the Gtk Screen
+package and try out a graphical Edwin.
+@end itemize
+
 @node Installation
 @chapter Installation
 
@@ -321,13 +374,13 @@ plugins and external libraries.  To get a system as much like the
 original MIT/GNU Scheme as possible, able to run IMAIL in a basic X11
 screen, you will want to install the
 @code{mit-scheme-pucked-x11-screen} and @code{mit-scheme-pucked-imail}
-packages.
+packages.  They will require other packages to be installed first.
 
 Until the Debian packages become available in a public package
-archive, you will need to download @file{.deb} files from the
-website and use the @code{dpkg} command to install them.  Instructions
-on the website should make plain what files you need.  Install each
-file, in order, with a command like this:
+archive, you will need to download @file{.deb} files from the website
+and use the @code{dpkg} command to install them.  Instructions on the
+website should make plain what files you need.  Install each in order
+with a command like this:
 @example
     sudo dpkg --install mit-scheme-pucked-9.2.7_1.deb
 @end example
@@ -335,45 +388,38 @@ file, in order, with a command like this:
 If you cannot install Debian packages, you can install binary tarballs
 on almost any Unix-like system.  Installation involves compiling some
 C code, so your system will need a C compiler and developer packages
-for the external libraries your chosen plugins will need.
-Installation of a plugin requires that Scheme be installed first, so
-you will begin by downloading and installing the binary for the core
-Scheme system.  Follow the instructions on the website to download the
-appropriate tarball.
-
-The distributed binary tarballs
-contain both source and binary files; the binary files are
-pre-compiled Scheme code for a particular computer architecture.  The
-@samp{x86-64} and @samp{i386}binaries contain native instructions for
-Intel@registeredsymbol{} 64 and IA-32 architecture machines.  On other
-architectures you can use @samp{svm1-32} or @samp{svm1-64} binaries;
-they contain instructions for a virtual machine included in the C code.
+for the libraries your plugins use.  Installing plugins requires
+Scheme to be installed first, so you must begin by downloading and
+installing the binary for the core Scheme system.
+
+Follow the instructions on the website to download the appropriate
+core binary tarball.  Its binary files contain Scheme code compiled
+for a particular computer architecture.  The @samp{x86-64} and
+@samp{i386} binaries contain native instructions for
+Intel@registeredsymbol{}64 and IA-32 architecture machines.  The
+@samp{svm1-32} and @samp{svm1-64} binaries contain Scheme Virtual
+Machine v1 opcodes.  Machines of @emph{any} architecture can use these
+binaries by running the included virtual machine, though the virtual
+machine is 3-4 times slower than the native machine.
 
 To compile the C code take the following steps:
-
 @enumerate
 @item
 Unpack the tar file, e.g.@:
 @file{mit-scheme-pucked-9.2.7-i386.tar.gz}, to create the build
 directory, e.g.@:
 @file{mit-scheme-pucked-9.2.7}.  For example,
-
 @example
 tar xzf mit-scheme-pucked-9.2.7-i386.tar.gz
 @end example
-
 will create a new directory @file{mit-scheme-pucked-9.2.7}.
-
 @item
 Move into the @file{src} subdirectory of the new directory:
-
 @example
 cd mit-scheme-pucked-9.2.7/src
 @end example
-
 @item
 Configure the software:
-
 @example
 ./configure
 @end example