svn commit: r904693 - /db/derby/docs/trunk/src/getstart/tgs26250.dita

[bp...@apache.org]

Author: bpendleton
Date: Sat Jan 30 00:25:39 2010
New Revision: 904693

URL: http://svn.apache.org/viewvc?rev=904693&view=rev
Log:
DERBY-4501: Improve description of classpath-setting scripts

This change enhances the documentation of the CLASSPATH-setting scripts
to clarify their behavior on UNIX systems. Since the purpose of these
scripts is to set a shell variable in the calling shell, it is
important that the scripts be run using the "dot" or "source" command;
otherwise the variable is set only for the subshell, and the calling
shell's variables are not affected.

Modified:
    db/derby/docs/trunk/src/getstart/tgs26250.dita

Modified: db/derby/docs/trunk/src/getstart/tgs26250.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/getstart/tgs26250.dita?rev=904693&r1=904692&r2=904693&view=diff
==============================================================================
--- db/derby/docs/trunk/src/getstart/tgs26250.dita (original)
+++ db/derby/docs/trunk/src/getstart/tgs26250.dita Sat Jan 30 00:25:39 2010
@@ -58,11 +58,67 @@
 to the classpath. </dd>
 </dlentry></dl></p><p>To set the classpath temporarily, run the script that
 is appropriate for your environment every time that you open a new command
-window.</p><p>To see the classpath that the script sets, issue the following
-command after you run the script: <ul>
-<li>On UNIX, use <codeph>echo $CLASSPATH</codeph></li>
-<li>On Windows, use <codeph>echo %CLASSPATH%</codeph></li>
-</ul></p></context>
+window.</p>
+<p>
+    Note that these scripts behave slightly differently on UNIX systems
+    and on Windows systems. On Windows systems, running the script in your
+    command shell will set the environment variables for your shell.
+</p>
+<p>On UNIX systems, you need to use the "dot" or "source"
+    command to ensure that the script
+    is run in the calling shell's environment. Otherwise, when a script
+    is run, it launches a new shell for that script.
+    The CLASSPATH is set within that shell.
+    Once the script is complete, that
+    shell exits and you are returned to your shell.
+    The CLASSPATH is changed only for the shell that the script was
+    running in.
+    The CLASSPATH in your shell is unchanged. 
+</p>
+<p>
+    The UNIX shell scripts are known to run successfully in the Bash shell,
+    and you may need to modify them slightly if you are using a
+    different UNIX shell.
+</p>
+<p>
+    Here are examples of running the scripts, then displaying
+    the classpath that the script sets:
+    <ul>
+        <li>On UNIX, using the "dot" command to invoke the script,
+            a sample session might be as follows:
+            <codeblock>
+sh-2.05b$ echo $CLASSPATH
+sh-2.05b$ DERBY_HOME=/derby/db-derby-10.X.Y.0-bin
+sh-2.05b$ . $DERBY_HOME/bin/setEmbeddedCP
+sh-2.05b$ echo $CLASSPATH
+/derby/db-derby-10.X.Y.0-bin/lib/derby.jar:/derby/db-derby-10.X.Y.0-bin/lib/derbytools.jar:
+sh-2.05b$ java org.apache.derby.tools.ij
+ij version 10.X
+ij> quit;
+                </codeblock>
+        </li>
+        <li>On UNIX, using the "source" command to invoke the script,
+            a sample session might be as follows:
+            <codeblock>
+-bash-2.05b$ echo $CLASSPATH
+-bash-2.05b$ export DERBY_HOME=/derby/db-derby-10.X.Y.0-bin
+-bash-2.05b$ source $DERBY_HOME/bin/setEmbeddedCP
+                </codeblock>
+        </li>
+        <li>On Windows, a sample session might be as follows:
+            <codeblock>
+C:\derby\db-derby-10.X.Y.0-bin\bin>echo %CLASSPATH%
+%CLASSPATH%
+C:\derby\db-derby-10.X.Y.0-bin\bin>set DERBY_HOME=C:\derby\db-derby-10.X.Y.0-bin
+C:\derby\db-derby-10.X.Y.0-bin\bin>setEmbeddedCP.bat
+C:\derby\db-derby-10.X.Y.0-bin\bin>echo %CLASSPATH%
+C:\derby\DB-DERBY-10.X.Y.0-bin\lib\derby.jar;C:\derby\DB-DERBY-10.X.Y.0-bin\lib\derbytools.jar;
+C:\derby\db-derby-10.X.Y.0-bin\bin>java org.apache.derby.tools.ij
+ij version 10.X
+ij> quit;
+        </codeblock></li>
+</ul>
+</p></context>
 <postreq>For more information on running the <codeph>ij</codeph> and <codeph>sysinfo</codeph> utilities,
 see the <cite><ph conref="../conrefs.dita#pub/citutilities"></ph></cite></postreq>
 </taskbody>