Changed the module warning: Recommend the use of scheme-with-scsh.

doc/scsh-manual/running.tex

@@ -146,40 +146,35 @@ all, we recommend taking the time to learn and use it.
 The effort will pay off in the construction of modular, factorable programs.
 
 \subsubsection{Module warning}
-Programmers who open both the \ex{scheme} and \ex{scsh} structures in their
-own packages should make sure to always put the \ex{scsh} reference first.
-\begin{center}
-\begin{tabular}{l@{\qquad}l}
-Do this: & Not this: \strut \\
-\quad{\begin{codebox}[b]
-(define-structure web-server
-  (open scsh
-        scheme
-        net-hax
-        \vdots)
-  (file web))\end{codebox}}
-&
-\quad{\begin{codebox}[b]
-(define-structure web-server
-  (open scheme
-        scsh
-        net-hax
-        \vdots)
-  (file web))\end{codebox}}\\
-%
-Open \ex{scsh} before \ex{scheme}. &
-Not \ex{scsh} after \ex{scheme}.
-\end{tabular}
-\end{center}
-Ordering the two packages like this is necessary because scsh overrides
-some of the standard R4RS Scheme definitions exported by the \ex{scheme}
-package with its own definitions.
-For example, scsh's versions of the R4RS I/O functions such as \ex{display}
-and \ex{write} take integer file descriptors as arguments, as well as Scheme
-ports.
-If you open the \ex{scheme} structure before the \ex{scsh} structure,
-you'll get the standard {\scm} definitions, which is not what you want.
+Most scsh programs will need to import from the \ex{scheme} structure
+as well as from the \ex{scsh} structure. However, putting both of
+these structures in the same \texttt{open} clause is a bad idea
+because the structures \ex{scheme} and \ex{scsh} export some names of
+I/O functions in common but with different definitions.  The current
+implementation of the module system does not recognize this as an
+error but silently overwrites the exports of one structure with the
+exports of the other.  If the \ex{scheme} structure overwrites the
+exports of the \ex{scsh} structures the program will access the
+R$^5$RS definitions of the I/O functions which is not what you want.
 
+Previous versions of this manual suggested to list \ex{scheme} and
+\ex{scsh} in a specific order in the \texttt{open} clause of a
+structure to ensure that the definitions from \ex{scsh} overwrite the
+ones from \ex{scheme}. This approach is error-prone and fragile: A
+simple change in the implementation of the module system will render
+thousands of programs useless.  Starting with release 0.6.3 scsh
+provides a better means to deal with this problem: the structure
+\ex{scheme-with-scsh} provides all the exports of the modules
+\ex{scheme} and \ex{scsh} but exports the right denotations for the
+I/O functions in question. To make a long story short:
+\begin{center}
+  Scsh programs should open the structure \ex{scheme-with-scsh} if
+  they need access to the exports of \ex{scheme} and \ex{scsh}.
+\end{center}
+
+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{Switches}
 \label{sec:scsh-switches}