Reworked description of the library directories.

doc/scsh-manual/running.tex

@@ -176,9 +176,111 @@ For programs which should run in versions of scsh prior to release
 0.6.3, programmers should make sure to always put the \ex{scsh}
 reference first.
 
+\subsection{Library directories search facility}
+\label{sec:lib-dirs}
+
+Scsh's command line switches allow loading of code not present in the
+script file or the heap image at startup. To relief the user from
+specifying full path names and to improve flexibility, scsh offers the
+library directories path list. This list contains directories in which
+scsh searches automatically for a file name argument of the
+\texttt{-ll} or \texttt{-le} switch.
+
+This section describes the programmatic interface to the library
+directories search facility. In addition, various command line
+switches for scsh modify the library directories path list. Section
+\ref{sec:scsh-switches} describes these switches and the switches to
+actually load files.
+
+Another way to change the library directories path list is the
+environment variable \texttt{\$SCSH\_LIB\_DIRS}. If this variable is
+set, scsh uses it to set library directories path list. The value of
+this environment variable is treated as a sequence of s-expressions,
+which are ``read'' from the string:
+    
+\begin{itemize}
+\item A string is treated as a directory,
+\item \sharpf{} is replaced with the default list of directories.
+\end{itemize}
+
+A \texttt{\$SCSH\_LIB\_DIRS} assignment of this form
+\begin{small}
+\begin{verbatim}
+SCSH_LIB_DIRS='"." "/usr/contrib/lib/scsh/" #f "/home/shivers/lib/scsh"'
+\end{verbatim}
+\end{small}
+would produce this list of strings for the
+\textit{library-directories} list:
+%
+\begin{verbatim}
+          ("." "/usr/contrib/lib/scsh/" 
+          "/usr/local/lib/scsh/modules/" 
+          "/home/shivers/lib/scsh")
+\end{verbatim}
+%
+It is a startup error if reading the \texttt{\$SCSH\_LIB\_DIRS}
+environment variable causes a read error, or produces a value that
+isn't a list of strings or \sharpf.
+
+\defvar{default-lib-dirs}{string list}
+
+\begin{desc}
+  The default list of \textit{library directories}. The original value
+of this variable is \verb+("$prefix/lib/scsh/modules/")+. %$ but
+starting with version 0.6.5 the option \verb+--with-lib-dirs-list+ of
+the \texttt{configure} script changes for a new installation.
+\end{desc}    
+
+\defun{find-library-file}{file lib-dirs script-file}{\undefined}
+\begin{desc}
+  Searches the list of library directories \var{lib-dirs} for
+  \var{file} and returns the full path. The variable \var{script-file}
+  is used to resolve references to the directory of the current
+  script. 
+  
+  When searching for a directory containing a given library module,
+  nonexistent or read-protected directories are silently ignored; it
+  is not an error to have them in the \textit{library-directories}
+  list.
+    
+  Directory search can be recursive. A directory name that ends with a
+  slash is recursively searched.
+\end{desc}
+
+\defun{lib-dirs}{}{string list}
+\begin{desc}
+  Returns the current library directories path list.
+\end{desc}
+
+\defun{lib-dirs-prepend-script-dir!}{}{\undefined}
+\defunx{lib-dirs-append-script-dir!}{}{\undefined}
+\begin{desc}
+  Add the directory of the current script file to the beginning or end
+  of the \textit{library-directories} path list, respectively.
+\end{desc}
+
+\defun{lib-dirs-append!}{dir}{\undefined}
+\defunx{lib-dirs-prepend!}{dir}{\undefined}
+\begin{desc}
+  Add directory \var{lib-dir} to the beginning or end of the
+  \textit{library-directories} path list, respectively.
+\end{desc}
+
+\defun{clear-lib-dirs!}{}{\undefined}
+\begin{desc}
+  Set the \textit{library-directories} path list to the empty list.
+\end{desc}
+
+\defun{reset-lib-dirs!}{}{\undefined}
+\begin{desc}
+  Set the \textit{library-directories} path list to system default,
+  i.e. to the value of \var{default-lib-dirs}.
+\end{desc}
+
 \subsection{Switches}
 \label{sec:scsh-switches}
-The scsh top-level takes command-line switches in the following format:
+The scsh top-level takes command-line switches in the following
+format:
 %
 \codex{scsh [\var{meta-arg}] [\vari{switch}i {\ldots}] 
             [\var{end-option} \vari{arg}1 {\ldots} \vari{arg}n]}
@@ -408,54 +510,17 @@ The following switches and end options are defined:
     {\scm} exec language.
 
 \Item{-ll \var{module-file-name}}
+
     Load library module into config package.
     This is just like the \ex{-lm} switch, except that it searches the
-    library-directory path list for the file to load.
+    library-directory path list (see Section \ref{sec:lib-dirs}) 
+    for the file to load.
     
     Specifically, it means: search through the
     \textit{library-directories} list of directories looking for a
-    module file of the given name, and load it in.
+    module file of the given name, and load it in. Scsh uses the
-    
+    procedure \var{find-library-file} from Section \ref{sec:lib-dirs}
-    The \textit{library-directories} list defaults to
+    to perform the search.
-    \verb+("$prefix/lib/scsh/modules/")+. Starting with version
-    0.6.5 the option \verb+--with-lib-dirs-list+ of the
-    \texttt{configure} script changes this default value.
-    
-    If the environment variable \texttt{\$SCSH\_LIB\_DIRS} is set, it is
-    used to determine the library search path. The value of this
-    environment variable is treated as a sequence of s-expressions, which
-    are ``read'' from the string:
-    
-    \begin{itemize}
-      \item  A string is treated as a directory,
-      \item \sharpf{} is replaced with the default list of directories.
-    \end{itemize}
-
-    A \texttt{\$SCSH\_LIB\_DIRS} assignment of this form
-    \begin{small}
-\begin{verbatim}
-SCSH_LIB_DIRS='"." "/usr/contrib/lib/scsh/" #f "/home/shivers/lib/scsh"'
-\end{verbatim}
-    \end{small}
-    would produce this list of strings for the
-    \textit{library-directories} list:
-    \begin{verbatim}
-          ("." "/usr/contrib/lib/scsh/" 
-          "/usr/local/lib/scsh/modules/" 
-          "/home/shivers/lib/scsh")
-    \end{verbatim}
-    
-    When searching for a directory containing a given library module,
-    nonexistent or read-protected directories are silently ignored; it
-    is not an error to have them in the \textit{library-directories}
-    list.
-    
-    It is a startup error if reading the \texttt{\$SCSH\_LIB\_DIRS}
-    environment variable causes a read error, or produces a value that
-    isn't a list of strings or \sharpf.
-
-    Directory search can be recursive. A directory name that ends
-    with a slash is recursively searched.
 
 \Item{-lel \var{exec-file-name}}
     As above, but load the specified file into scsh's exec package.
@@ -467,17 +532,28 @@ SCSH_LIB_DIRS='"." "/usr/contrib/lib/scsh/" #f "/home/shivers/lib/scsh"'
     \textit{library-directories} path list, respectively.
     
     \var{lib-dir} is a single directory. It is not split at colons or
-    otherwise processed.
+    otherwise processed. These switches correspond to the procedures
+    \var{lib-dirs-prepend!} and \var{lib-dirs-append!} from Section
+    \ref{sec:lib-dirs}.
 
 \Item{+lpe, lpe+}
     As above, except that \~ home-directory syntax and environment
     variables are expanded out.
      
+\Item{+lpsd,lpsd+} 
+    Add script-file's directory to the beginning or end of the
+    \textit{library-directories} path list, respectively. These switches 
+    correspond to the procedures
+    \var{lib-dirs-prepend-script-dir!} and \var{lib-dirs-append-script-dir!} from Section
+    \ref{sec:lib-dirs}.
+
 \Item{-lp-clear, -lp-default}
     Set the \textit{library-directories} path list to the empty list and
-    the system default, respectively.
+    the system default, respectively. These switches correspond to
+    the procedures \var{clear-lib-dirs!} and \var{reset-lib-dirs!} from Section
+    \ref{sec:lib-dirs}.
         
-    These two switches are useful if you would like to protect your
+    The two switches are useful if you would like to protect your
     script from influence by the \texttt{\$SCSH\_LIB\_DIRS} variable.
 
     In these cases, the \texttt{\$SCSH\_LIB\_DIRS} environment variable is never