[ http://issues.apache.org/jira/browse/DERBY-1223?page=comments#action_12433265 ] Andrew McIntyre commented on DERBY-1223: ----------------------------------------
Wow, this is already a great improvement. Some further comments: cgsinstallingderby: "You will also find information on accessing the active source distributions for Derby." should probably be "You will also find information on how to use Subversion to access the Derby source code currently in development.". tgssetupjavaenvir: 1. "Set the DERBY_HOME environment variable." should maybe be "Set the DERBY_HOME environment variable to the location where you extracted the bin distribution." The second sentence is confusing and maybe should be removed, since it looks like it actually belongs in number 3. Third sentence needs a space before DERBY_HOME. 3. Unix example should be export PATH="$DERBY_HOME/bin:$PATH" Remove #4. cgsusingtoolsutils: now that i can see the edited page, I think the title could stay as is if we include a reference to where the 'utilities' are documented. For example, if the first paragraph ended with this sentence: "Instructions on how to use these system procedures are included in the Derby Tools and Utilities Guide and the Derby Reference Manual" I think import/export is something that even new, novice users will probably be interested in and so it might be good to point them to where import/export is documented. I think the following paragraph is confusing and should be removed along with the note about the Unix chmod business: "The scripts have descriptive names such as sysinfo or ij. Like the classpath scripts, these scripts end with different extensions depending on your environment. Windows scripts have a .bat extension. You might need to modify these scripts for the tools and utilities to run properly on Windows and UNIX operating systems." This can be replaced with something simple like "The DERBY_HOME/bin directory contains scripts to help you start the Derby tools and to help you set up your classpath. " Organizationally, maybe it then makes sense to make tgs26250 change from "Manually setting the classpath" to "Setting your classpath" or "Using the classpath-setting scripts" and be a subsection of this topic, since that page does talk about using the classpath setting scripts? tgs26250: I think this page needs to be refocused around the classpath setting scripts. Everything starting with the Tip section until the end of the page can be removed, since it's confusing and the idea is getting people off the ground and explaining to them what the scripts do, not to have them jumping through hoops with their environment. :-) I think the first sentence can be removed, and then the first two paragraphs combined. "a CLASSPATH environment variable" should be "the CLASSPATH environment variable." " In most development environments, it is best to temporarily set the CLASSPATH environment variable for the operating system." I think "for the operating system" should be something like "in the command-line shell where you are entering commands". "provides some scripts" should be "provides three scripts". think what would be more useful instead is a description of what the three classpath scripts do: "* setEmbeddedCP adds derby.jar and derbytools.jar to the classpath, for using the database engine in embedded mode. * setNetworkServerCP adds derby.jar and derbynet.jar to the classpath, so that you can start the network server. * setNetworkClientCP adds derbyclient.jar and derbytools.jar to the classpath, so that you can access databases using the network client. To see the classpath that the script sets, issue the command "echo $CLASSPATH" (Unix) or "echo %CLASSPATH%" (Windows) after running the script" As a general note, it would probably be a good idea to mention derbyrun.jar in here somewhere, maybe the sysinfo and ij pages should include an example of invoking each tool using derbyrun.jar. It would also be useful to talk about using the scripts to start and stop the network server. Both of those are outside of the scope of this issue, so I'll add them to the Getting Started doc review wiki page. > 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 > Fix For: 10.2.1.0 > > Attachments: derby1223.diff, derby1223_2.diff, Derby1223_html.zip, > derby1223_html2.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
