From: Matt Birkholz Date: Mon, 13 Mar 2017 23:29:13 +0000 (-0700) Subject: user manual: Add section Proposed Changes to chapter Changes. X-Git-Tag: mit-scheme-pucked-9.2.12~174 X-Git-Url: https://birchwood-abbey.net/git?a=commitdiff_plain;h=f1157201b932ad965df677e534b132606c76dbd0;p=mit-scheme.git user manual: Add section Proposed Changes to chapter Changes. --- diff --git a/doc/user-manual/user.texinfo b/doc/user-manual/user.texinfo index 0dbab918f..2ba71d526 100644 --- 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