[ http://issues.apache.org/jira/browse/DERBY-1223?page=comments#action_12429910 ] Andrew McIntyre commented on DERBY-1223: ----------------------------------------
cgsinstallingderby.html: There is also a lib-debug package with jars built with line number tables to aid in debugging and reporting problems. I'm not sure how to best incorporate this information into the page as it is. A description of what the different packages contain may be in order. e.g.: "The bin distribution contains scripts, demonstration programs, documentation and the optimized jars available in the lib distribution. The lib distribution contains an optimized, small footprint set of the Derby jars for deployment. The lib-debug distribution contains a larger footprint set of the Derby jars that are useful for debugging or reporting issues The src distribution contains the source files used to create the other distributions mentioned above." But maybe that is too much information for this page? cgsusingtoolsutils.html: I'm not sure that this is still relevant: "Derby utilities include the import, export and database class utilities." Perhaps this should read: "Some Derby utilities exist as system procedures, including the import and export of external files. These system procedures can be called through ij." And maybe include a reference to the import/export system procedures in the reference manual. I think "database class utilities" refers to functionality that no longer exists, so it should probably be removed. "The /bin directory contains scripts for running some of the Derby tools and utilities in embedded mode. You can find similar scripts for running tools and utilities for the Network Server in the NetworkServer/bin directory. " should read: "The scripts in DERBY_HOME/bin directory default to using the embedded mode. To run these tools against the Network Server, use: * sysinfo - run 'NetworkServerControl sysinfo' * ij - set DERBY_OPTS=-Dij.protocol=jdbc:derby://localhost/ and then execute 'ij' * dblook - call the script with the -d option and the full URL to the Network Server database. For example: dblook -d 'jdbc:derby://localhost/myDB;user=usr;' rgslib27507.html: There needs to be an entry for bin/setNetworkServerCP, which "puts the libraries needed to start the Derby Network Server into the classpath." tgs26250.html: setNetworkServeCp should be setNetworkServerCP These three paragraphs: "The names of the scripts that help with setting the CLASSPATH are: setEmbeddedCP, setNetworkServeCP, and setNetworkClientCP. You can set the CLASSPATH environment variable in the operating system either temporarily, permanently, or at run time when you start your Java application and the JVM. If you set the environment variable temporarily, you must set it each time that you open a new command window. In most development environments, it is best to set the operating system's CLASSPATH environment variable temporarily. Derby provides some scripts to help you set your classpath quickly. These scripts are located in the bin directory or the NetworkServer/bin directory. To set the class path temporarily, run a script every time you open a new command window." should be combined to something like: "You can set the CLASSPATH environment variable in the operating system either temporarily, permanently, or at run time when you start your Java application and the JVM. If you set the environment variable temporarily, you must set it each time that you open a new command window. In most development environments, it is best to set the operating system's CLASSPATH environment variable temporarily. Derby provides some scripts in the DERBY_HOME/bin directory to help you set your classpath quickly. These scripts are named: setEmbeddedCP, setNetworkServerCP, and setNetworkClientCP. To set the class path temporarily, run one of these scripts every time you open a new command window." As for the bullet points, I think the first one should be unbulleted, and made to read "To set your CLASSPATH so that it includes the derby.jar and derbytools.jar files, you can use the setEmbeddedCP script, or set the CLASSPATH variable manually as follows:" Then the next bullet points follow underneath this heading to demonstrate how to run sysinfo or ij without the scripts. The last bullet point should probably be unbulleted as a demonstration of how to specify the classpath directly on the command line. tgssetupjavaenvir.html: "You need to set the environment variables so that the JVM and Java applications run correctly" should be "You need to set some environment variables so that the scripts included with the Derby bin distribution run correctly." Remove the next line about PATH. The rest of this page should be structured as follows: * set DERBY_HOME - include the content formerly from tgs36360 mentioned by Kim. * set JAVA_HOME - keep the first two sentences and the first set of examples. The third sentence should move elsewhere. The text after the first set of examples is incorrect and should be removed. * I don't think bullet 3 needs to be here. Adding JAVA_HOME/bin to the path should probably move to the page about setting the classpath manually, since having the java executable on the path is important in that regard, but not for running the scripts. * need to add a section about adding DERBY_HOME/bin to the path so that the scripts can be executed from any directory. * bullet 4 is correct if the above section is added. The scripts need to have the DERBY_HOME and JAVA_HOME properly set, and DERBY_HOME/bin added to the path, if the user wants to be able to execute the scripts from any location on their system from their current shell environment. ... I'm sure I've missed something or made something more unclear than it already was. Please don't hesitate to ask for clarification about any of these comments. This review has made it clear that the Getting Started guide was in really bad shape. Thank you for helping to make it better. > Update Getting Started to include instructions on setting JAVA_HOME variable. > ----------------------------------------------------------------------------- > > Key: DERBY-1223 > URL: http://issues.apache.org/jira/browse/DERBY-1223 > Project: Derby > Issue Type: Improvement > Components: Documentation > Affects Versions: 10.2.1.0 > Reporter: Andrew McIntyre > Assigned To: Laura Stewart > Priority: Minor > Attachments: derby1223.diff, Derby1223_html.zip, > Derby1223_ProposedChanges.txt > > > As of the fix for DERBY-1082, the scripts were made consistent to require > setting DERBY_HOME (or DERBY_INSTALL) and JAVA_HOME. The documentation on > setting up your environment in the Getting Started guide should be updated to > reflect that these variables should be set. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
