From 79408cfc9244082264666a812e40fa61386a80ea Mon Sep 17 00:00:00 2001 From: Matt Birkholz Date: Sun, 30 Dec 2018 01:16:59 -0700 Subject: [PATCH] Update user manual and manpage for 10.1.7. --- doc/mit-scheme-pucked.1 | 4 +- doc/user-manual/user.texinfo | 196 ++++++++--------------------------- 2 files changed, 45 insertions(+), 155 deletions(-) diff --git a/doc/mit-scheme-pucked.1 b/doc/mit-scheme-pucked.1 index fd386962c..1df6ac1ad 100644 --- a/doc/mit-scheme-pucked.1 +++ b/doc/mit-scheme-pucked.1 @@ -15,9 +15,7 @@ integrated Emacs-like editor, and a large runtime library. MIT/GNU Scheme is best suited to programming large applications with a rapid development cycle. .LP -Friar Puck's MIT/GNU Scheme is a testbed for new plugins. It does not -have microcode modules, relying on plugins to provide the same -functionality. +Friar Puck's MIT/GNU Scheme is a testbed for new plugins. .SH "OPTIONS" .LP These are some of the more common command-line options. For full diff --git a/doc/user-manual/user.texinfo b/doc/user-manual/user.texinfo index d9a3bfe0e..b22f17db0 100644 --- a/doc/user-manual/user.texinfo +++ b/doc/user-manual/user.texinfo @@ -169,13 +169,13 @@ and Scheme will load and print something like this: MIT/GNU Scheme Pucked running under GNU/Linux Type `^C' (control-C) followed by `H' to obtain information about interrupts. -Copyright (C) 2017 Matthew Birkholz -Copyright (C) 2017 Massachusetts Institute of Technology +Copyright (C) 2018 Matthew Birkholz +Copyright (C) 2018 Massachusetts Institute of Technology This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -Image saved on Sunday March 12, 2017 at 10:15:09 AM - Release 9.2.7 || Microcode 15.3 || Runtime 15.7 || SF 4.41 +Image saved on Saturday December 29, 2018 at 10:54:40 AM + Release 10.1.7 || Microcode 15.8 || Runtime 15.8 || SF 4.41 LIAR/x86-64 4.118 @end smallexample @@ -3835,90 +3835,15 @@ state that prevents Edwin from running. This experimental version of MIT/GNU Scheme got a new project name, MIT/GNU Scheme Pucked, and a new command name, @code{mit-scheme-pucked}, so that it can be installed alongside the -stable release. While it comes with an assortment of plugins and a -strange name, the core of the system is largely unchanged. - -@section Proposed Changes - -The core of MIT/GNU Scheme Pucked is the @emph{bleeding edge core}. -The head of the MIT/GNU Scheme project's development branch on -Savannah is merged in frequently, so this version includes changes -proposed for the next stable release of MIT/GNU Scheme. - -@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 -(fluid-let ((*parser-radix* 16)) - ...) -@end example - -@noindent -you should parameterize @code{param:parser-radix} - -@example -(parameterize ((param:parser-radix 16)) - ...) -@end example - -@item -CREF now supports deprecated bindings. It will list references to -them in your packaging construction reports (@file{.crf} files). - -@item -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 -deprecated. - -@item -The microcode no longer has ``modules''. Systems like @code{(runtime -crypto)} now autoload ``plugins'' that are much like the microcode -modules except they use the C/FFI and can be built outside the -microcode source tree. - -@item -The @code{(runtime blowfish)}, @code{(runtime gdbm)} and -@code{(runtime x-graphics)} packages now autoload plugins and are -deprecated. Work-alike replacements @code{(blowfish)}, @code{(gdbm)} -and @code{(x11 graphics)} should be used instead. Thus @code{(runtime -blowfish)} should be replaced with @code{(blowfish)} in package -descriptions, and a @code{(global-definitions blowfish/)} expression -added. - -@item -The @code{(runtime crypto)} package is similarly deprecated. Its -bindings are unassigned until the corresponding plugin is loaded. -When a band is restored these bindings are unassigned again. Thus a -restored thread using them will quickly signal an error and can be -aborted or restarted as appropriate. An @code{mcrypt-available?} -binding is assigned a procedure that autoloads the mcrypt option. A -restarted thread is assumed to begin again with a call to -@code{mcrypt-available?} (or @code{load-option}). -@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 incrementally. - -@section Experimental Changes +stable release. While it comes with experimental plugins and a +strange name, the core of the system is largely unchanged. Note that +this is a @emph{bleeding edge} core. The head of the MIT/GNU Scheme +project's development branch on Savannah is merged in frequently. The experimental code in this ``pucked'' version is almost entirely -contained in the plugins. The core was changed only to hook the Gtk -screen into Edwin. This change should not be apparent to the casual -user. - -If your code does not hack Edwin and you previously said +contained in the new plugins. The core was changed only to hook the +Gtk screen into Edwin, and this change should not be apparent to the +casual user. If your code does not hack Edwin and you previously said @example mit-scheme --load my-code @@ -4072,7 +3997,7 @@ be @emph{three} packages named @code{mit-scheme-pucked} with the When you upgrade to a new version of Ubuntu you should first remove the @code{mit-scheme-pucked} package (which will remove all of its plugins), then re-install them after changing the source URL (e.g. to -@url{http://birchwood-abbey.net/ubuntu/18.04/}). +@url{http://birchwood-abbey.net/ubuntu/18.10/}). @example sudo apt-get remove mit-scheme-pucked @@ -4085,8 +4010,7 @@ sudo apt-get install mit-scheme-pucked-x11-screen @end example You can also download the package files and install them by hand. -Links to the available package files are listed on the project home -page. +Links to the files can be found on the project home page. @example @uref{https://birchwood-abbey.net/~puck/Scheme/} @@ -4117,16 +4041,16 @@ gpg --import ~/Downloads/codemaster.txt Then verify the signature on the @file{.changes} file like this: @example -gpg --verify ~/Downloads/mit-scheme-pucked_9.2.7-1_amd64.changes +gpg --verify ~/Downloads/mit-scheme-pucked_10.1.7-1_amd64.changes @end example And compare the checksum in the @file{.changes} file to one computed from your downloaded file. @example -grep mit-scheme-pucked_9.2.7-1_amd64.deb \ - mit-scheme-pucked_9.2.7-1_amd64.changes -sha256sum mit-scheme-pucked_9.2.7-1_amd64.deb +grep mit-scheme-pucked_10.1.7-1_amd64.deb \ + mit-scheme-pucked_10.1.7-1_amd64.changes +sha256sum mit-scheme-pucked_10.1.7-1_amd64.deb @end example After you have downloaded and verified all of the required files, you @@ -4135,7 +4059,7 @@ can install them, required packages first, e.g.@: starting with @code{mit-scheme-pucked-x11-screen}. @verbatim P=~/Downloads/mit-scheme-pucked -sudo dpkg --install ${P}_9.2.7-1_amd64.deb +sudo dpkg --install ${P}_10.1.7-1_amd64.deb sudo dpkg --install ${P}-gdbm_0.2.1-1_amd64.deb sudo dpkg --install ${P}-blowfish_0.2.1-1_amd64.deb sudo dpkg --install ${P}-edwin_3.116.1-1_amd64.deb @@ -4154,14 +4078,24 @@ new Ubuntu. MIT/GNU Scheme Pucked can be built and installed on a wide variety of Unix-like operating systems using a ``binary distribution'' and developer tools like those in the GNU tool chain: a bourne-like shell, -a @code{make} command, a C compiler and linker. The Scheme -interpreter is built from C code and installed much like any other GNU -C program. +a @code{make} command, a C compiler and linker, and a ``curses'' +library. For example, here are the packages that must be installed on +some popular systems: -These are @emph{binary} distributions because they contain pre-compiled -Scheme code in binary files. This code cannot be compiled during the -install because there is no Scheme compiler to do the work until -@emph{after} Scheme is installed. +@itemize @bullet +@item +Debian-like systems: @code{gcc} @code{make} @code{libncurses-dev} +@item +CentOS-like systems: @code{gcc} @code{make} @code{ncurses-devel} +@item +macOS systems: @code{Xcode} +@end itemize + +The Scheme interpreter is built from C code and installed much like +any other GNU C program. The @emph{binary} files in the distribution +contain pre-compiled Scheme code. This code cannot be compiled during +the install because there is no Scheme compiler to do the work until +@emph{after} the install. First download the appropriate binary distribution. To do this you will need to know the name of your Scheme architecture. If your @@ -4175,26 +4109,26 @@ slower than the native machine. Click on the name of your Scheme machine architecture in the list of binaries for the core system. Save the file, which should be named -something like @file{mit-scheme-pucked-9.2.7-i386.tar.gz}. +something like @file{mit-scheme-pucked-10.1.7-i386.tar.gz}. Compile the Scheme interpreter using the following steps: @enumerate @item Unpack the archive to create your build directory, e.g.@: -@file{mit-scheme-pucked-9.2.7}. For example, +@file{mit-scheme-pucked-10.1.7}. For example, @example -tar xzf mit-scheme-pucked-9.2.7-i386.tar.gz +tar xzf mit-scheme-pucked-10.1.7-i386.tar.gz @end example -will create a new directory @file{mit-scheme-pucked-9.2.7}. +will create a new directory @file{mit-scheme-pucked-10.1.7}. @item Move into the @file{src} subdirectory of the new directory: @example -cd mit-scheme-pucked-9.2.7/src +cd mit-scheme-pucked-10.1.7/src @end example @item @@ -4224,7 +4158,7 @@ command @code{./configure --help}. Build the software: @example -make compile-microcode +make @end example @item @@ -4254,52 +4188,10 @@ are: blowfish, edwin, gdbm, imail, mcrypt, x11, and x11-screen. The plugins are not distributed in binary form (except as Ubuntu packages). With the core Scheme system installed, their Scheme code -can be compiled along with their C code. - -The plugins are all built by scripts and makefiles created by GNU -automake (and autoconf). Thus make targets like @code{dist} and -@code{install-html} and @code{uninstall} are defined. - -Installation is per the GNU custom, not unlike the core -installation. For the Gtk+ plugin: - -@example -tar xzf mit-scheme-pucked-gtk-0.5-i386.tar.gz -cd mit-scheme-pucked-gtk-0.5 -./configure -make -make check -make install -@end example - -The @code{install} target attempts to create a subdirectory in the -first directory on the host Scheme's library path. If that directory -is not writable by you, super-user privileges may be required. - -You can put a writable directory at the front of your host Scheme's -library path by setting the @code{MITSCHEME_LIBRARY_PATH} environment -variable - -@example -export MITSCHEME_LIBRARY_PATH=~/pucked:/opt/lib/mit-scheme-pucked -@end example - -@noindent -or including the @code{--prepend-library} option on the command line. - -@example -mit-scheme-pucked --prepend-library ~/pucked -@end example - -The build will fail if the required plugins (Cairo, Pango and GLib) -are not installed first (and in the reverse order). It will also fail -if the plugin is a wrapper for a C library that is not installed. The -build needs the library header files. Often this means ``developer's -packages'' must be installed. See the @file{README} file in each -plugin's source archive for help in finding these files or packages. +can be compiled along with their C code. See the @file{README} file +in each plugin's source distribution for more information. -@c A full @node spec is needed here to avoid a bogus warning. -@node GNU Free Documentation License, Environment-variable Index, Installation, Top +@node GNU Free Documentation License @appendix GNU Free Documentation License @cindex FDL, GNU Free Documentation License -- 2.25.1