From ac75b2ab7d692fca5b4d4daeea3dbee9963d82d3 Mon Sep 17 00:00:00 2001
From: emarsden <emarsden>
Date: Mon, 28 Jun 2004 16:40:45 +0000
Subject: [PATCH] Minor improvements to the CMUCL User's Manual:

   - document the new EXT:LOAD-FOREIGN behaviour
   - minimal information about simple streams
   - change formatting of section titles
---
 docs/cmu-user/aliens.tex         | 49 ++++++++++++++++++--------------
 docs/cmu-user/cmu-user.tex       |  3 +-
 docs/cmu-user/extensions.tex     | 10 +++----
 docs/cmu-user/macros.tex         | 14 ++++++---
 docs/cmu-user/simple-streams.tex | 17 ++++++++++-
 5 files changed, 60 insertions(+), 33 deletions(-)

diff --git a/docs/cmu-user/aliens.tex b/docs/cmu-user/aliens.tex
index 2bdc7900c..09b04d181 100644
--- a/docs/cmu-user/aliens.tex
+++ b/docs/cmu-user/aliens.tex
@@ -543,35 +543,40 @@ which can be made be manipulated in Lisp like this:
 
 \section{Loading Unix Object Files}
 
-Foreign object files are loaded into the running Lisp process by
-\code{load-foreign}.  First, it runs the linker on the files and
-libraries, creating an absolute Unix object file.  This object file is
-then loaded into into the currently running Lisp.  The external
-symbols defining routines and variables are made available for future
-external references (e.g.  by \code{extern-alien}.)
-\code{load-foreign} must be run before any of the defined symbols are
-referenced.
+\cmucl{} is able to load foreign object files at runtime, using the
+function \code{load-foreign}. This function is able to load shared
+libraries (that are typically named \verb|.so|) via the dlopen
+mechanism. It can also load \verb|.a| or \verb|.o| object files by
+calling the linker on the files and libraries to create a loadable
+object file. Once loaded, the external symbols that define routines
+and variables are made available for future external references (e.g.
+by \code{extern-alien}.) \code{load-foreign} must be run before any of
+the defined symbols are referenced.
 
 Note that if a Lisp core image is saved (using \funref{save-lisp}), all
-loaded foreign code is lost when the image is restarted.
+loaded foreign code is lost when the image is restarted. 
+
 
 \begin{defun}{ext:}{load-foreign}{%
     \args{\var{files} \keys{\kwd{libraries} \kwd{base-file} \kwd{env}}}}
   
   \var{files} is a \code{simple-string} or list of
-  \code{simple-string}s specifying the names of the object files.
-  \var{libraries} is a list of \code{simple-string}s specifying
-  libraries in a format that \code{ld}, the Unix linker, expects.  The
-  default value for \var{libraries} is \code{("-lc")} (i.e., the
-  standard C library).  \var{base-file} is the file to use for the
-  initial symbol table information.  The default is the Lisp start up
-  code: \file{path:lisp}.  \var{env} should be a list of simple
-  strings in the format of Unix environment variables (i.e.,
-  \code{\var{A}=\var{B}}, where \var{A} is an environment variable and
-  \var{B} is its value).  The default value for \var{env} is the
-  environment information available at the time Lisp was invoked.
-  Unless you are certain that you want to change this, you should just
-  use the default.
+  \code{simple-string}s specifying the names of the object files. If
+  \var{files} is a simple-string, the file that it designates is
+  loaded using the platform's dlopen mechanism. If it is a list of
+  strings, the platform linker \code{ld} is invoked to transform the
+  object files into a loadable object file. \var{libraries} is a list
+  of \code{simple-string}s specifying libraries in a format that the
+  platform linker expects. The default value for \var{libraries} is
+  \code{("-lc")} (i.e., the standard C library). \var{base-file} is
+  the file to use for the initial symbol table information. The
+  default is the Lisp start up code: \file{path:lisp}. \var{env}
+  should be a list of simple strings in the format of Unix environment
+  variables (i.e., \code{\var{A}=\var{B}}, where \var{A} is an
+  environment variable and \var{B} is its value). The default value
+  for \var{env} is the environment information available at the time
+  Lisp was invoked. Unless you are certain that you want to change
+  this, you should just use the default.
 \end{defun}
 
 
diff --git a/docs/cmu-user/cmu-user.tex b/docs/cmu-user/cmu-user.tex
index a44238d9f..0ea0a8dc3 100644
--- a/docs/cmu-user/cmu-user.tex
+++ b/docs/cmu-user/cmu-user.tex
@@ -1,4 +1,4 @@
-%% cmucl-user.tex --- CMUCL User's Manual
+%% cmu-user.tex --- CMUCL User's Manual
 %%
 %% 2001-04-05  Eric Marsden
 %% Modifications to work with hevea and pdflatex. 
@@ -34,6 +34,7 @@
 \usepackage{index}
 \usepackage{ifthen}
 \usepackage{calc}
+\usepackage{sectsty}
 \usepackage[hyperindex=false,colorlinks=false,urlcolor=blue]{hyperref}
 \usepackage{html}
 \usepackage{varioref}
diff --git a/docs/cmu-user/extensions.tex b/docs/cmu-user/extensions.tex
index ae5d2042c..5c8654b55 100644
--- a/docs/cmu-user/extensions.tex
+++ b/docs/cmu-user/extensions.tex
@@ -562,7 +562,7 @@ platform, both the stop-and-copy GC and the generational GC are
 available, but the stop-and-copy GC is deprecated in favor of the
 generational GC.  
 
-The generational GC is available if \code{*features*} contains
+The generational GC is available if \var{*features*} contains
 \code{:gencgc}.
 
 %% The stop-and-copy GC compacts the items in dynamic space every time it
@@ -2535,17 +2535,17 @@ innermost fwrapper.
   unfortunately disabled by default.  It is known to cause some issues
   with CLX and Hemlock.  The cause is not known, but causes random
   errors and brokeness.  Enable at your own risk.  However, it is safe
-  enough for build all of CMUCL without problems.}
+  enough to build all of CMUCL without problems.}
 
 On x86 and sparc, \cmucl{} can exploit \code{dynamic-extent}
 declarations by allocating objects on the stack instead of the heap.
 
 You can tell \cmucl{} to trust or not trust \code{dynamic-extent}
 declarations by setting the variable
-\code{*trust-dynamic-extent-declarations*}.
+\var{*trust-dynamic-extent-declarations*}.
 
-\begin{defvar}{ext:}{*trust-dynamic-extent-declarations*}
-  If the value of \code{*trust-dynamic-extent-declarations*} is 
+\begin{defvar}{ext:}{trust-dynamic-extent-declarations}
+  If the value of \var{*trust-dynamic-extent-declarations*} is 
   \code{NIL}, \code{dynamic-extent} declarations are effectively
   ignored.
 
diff --git a/docs/cmu-user/macros.tex b/docs/cmu-user/macros.tex
index dfe4049c1..87c2a44df 100644
--- a/docs/cmu-user/macros.tex
+++ b/docs/cmu-user/macros.tex
@@ -282,7 +282,13 @@
 %% boxes.
 \setlength{\emergencystretch}{5pt}
 
-% These are for latex2html, which isn't really supported anymore.
-%\begin{htmlonly}
-%\input{latex2html}
-%\end{htmlonly}
+%% requires the sectsty package
+\allsectionsfont{\bfseries\sffamily}
+\chapterfont{\fontfamily{pag}\selectfont}
+
+%% section numbers in the left margin
+\makeatletter
+\def\@seccntformat#1{\protect\makebox[0pt][r]{\csname
+    the#1\endcsname\quad}}
+\makeatother
+
diff --git a/docs/cmu-user/simple-streams.tex b/docs/cmu-user/simple-streams.tex
index 323c44b1d..205faabcb 100644
--- a/docs/cmu-user/simple-streams.tex
+++ b/docs/cmu-user/simple-streams.tex
@@ -2,4 +2,19 @@
 \cindex{simple-streams}
 \label{simple-streams}
 
-[TBD]
+\cmucl{} includes a partial implementation of \emph{Simple Streams}, a
+protocol that allows user-extensible streams. The protocol was
+proposed by Franz, Inc. and is intended to replace the \emph{Gray
+Streams} method of extending streams. Simple streams are distributed
+as a \cmucl{} subsystem, that can be loaded into the image by saying
+
+\begin{lisp}
+   (require :simple-streams)
+\end{lisp}
+
+Note that CMUCL's implementation of simple streams is incomplete, and
+in particular is currently missing support for the functions
+\code{read-sequence} and \code{write-sequence}. Please consult the
+\textit{Allegro Common Lisp} documentation for more information on
+simple streams.
+
-- 
GitLab