Finishing doc for file-enable-sql-reader-syntax, adding warnings to docs on other...

diff --git a/doc/ref-syntax.xml b/doc/ref-syntax.xml
index dd0dd0ef4f6d732328695eca2472ad5d72fdf060..e0364fabd825483540f4d323de1c210d69a019dc 100644 (file)
--- a/doc/ref-syntax.xml
+++ b/doc/ref-syntax.xml
@@ -16,6 +16,12 @@
       utilities for enabling and disabling the square bracket reader
       syntax and for constructing symbolic SQL expressions.
     </para>
+    <tip>
+      <title>Tip: just want it on</title>
+      <simpara>
+       <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> at the top of each file is easiest.
+      </simpara>
+    </tip>
   </partintro>  
 
   <refentry id="enable-sql-reader-syntax">
@@ -57,6 +63,12 @@
       <para> 
         Modifies the default readtable.
       </para>
+      <warning>
+       <para>
+       &clsql; tries to keep track of whether the syntax has already been enabled. This can be problematic if the syntax is somehow disabled externally to &clsql; as future attempts to enable the syntax will do nothing--the system thinks it is already enabled. This may happen if there is an enable, but no disable, in a file that is processed with load or compile-file as the lisp implementation will restore the readtable on completion. Or, even if there is a disable but a compiler-error is encountered before running the disable. If you encounter this try running <link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link> a couple times in the REPL.
+       </para>
+       <para>See <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> for an alternative.</para>
+      </warning>
     </refsect1>
     <refsect1>
       <title>Affected by</title>
@@ -77,6 +89,7 @@
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -151,6 +164,7 @@
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -172,7 +186,7 @@
     </refmeta>
     <refnamediv>
       <refname>LOCALLY-ENABLE-SQL-READER-SYNTAX</refname>
-      <refpurpose>Globally enable square bracket reader syntax.</refpurpose>
+      <refpurpose>Locally enable square bracket reader syntax.</refpurpose>
       <refclass>Macro</refclass>
     </refnamediv>
     <refsect1>
@@ -210,6 +224,12 @@
       <para>
         Modifies the default readtable.
       </para>
+      <warning>
+       <para>
+       &clsql; tries to keep track of whether the syntax has already been enabled. This can be problematic if the syntax is somehow disabled externally to &clsql; as future attempts to enable the syntax will do nothing--the system thinks it is already enabled. This may happen if there is an enable, but no disable, in a file that is processed with load or compile-file as the lisp implementation will restore the readtable on completion. Or, even if there is a disable but a compiler-error is encountered before running the disable. If you encounter this try running <link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link> a couple times in the REPL.
+       </para>
+       <para>See <link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link> for an alternative.</para>
+      </warning>
     </refsect1>
     <refsect1>
       <title>Affected by</title>
@@ -228,6 +248,7 @@
         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -310,6 +331,7 @@
         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -394,6 +416,7 @@
         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
+       <member><link linkend="file-enable-sql-reader-syntax"><function>file-enable-sql-reader-syntax</function></link></member>
       </simplelist>
     </refsect1>
     <refsect1>
@@ -438,7 +461,7 @@
       <function>disable-sql-reader-syntax</function></link> which try to keep track of whether
        the syntax has been enabled or disabled and keep track of the old read-table for restoration this function just enables it unconditionally.
       </para>
-      <para>Once enabled this way there is no corresponding disable function but instead relies on being used in a file context. The spec for <ulink url="http://www.lispworks.com/documentation/lw51/CLHS/Body/f_load.htm">load</ulink> and <ulink url="http://www.lispworks.com/documentation/lw51/CLHS/Body/f_cmp_fi.htm">compile-file</ulink> states that the *readtable* will be restored after processing the file.
+      <para>Once enabled this way there is no corresponding disable function but instead relies on being used in a file context. The spec for <ulink url="http://www.lispworks.com/documentation/lw51/CLHS/Body/f_load.htm">load</ulink> and <ulink url="http://www.lispworks.com/documentation/lw51/CLHS/Body/f_cmp_fi.htm">compile-file</ulink> states that the *readtable* will be restored after processing the file.</para>
     </refsect1>
     <refsect1>
       <title>Examples</title>
@@ -453,7 +476,7 @@
     <refsect1>
       <title>Side Effects</title>
       <para>
-        Modifies the readtable.
+        Modifies the readtable for #\[ and #\]
       </para> 
     </refsect1>
     <refsect1>