[ http://issues.apache.org/jira/browse/DERBY-879?page=comments#action_12364221 ]
scott hutinger commented on DERBY-879: -------------------------------------- I think this it's important to get a reality check on the useability of the docs. I think most unix people take the windows docs (although this shouldn't be the case) and translate to whatever shell they like, because this is what we do without thinking about it. I can get my wife to try installing derby in windows (wow, that does scare me), but I would agree with someone else that possibly an installer should be created for setting up all the 'crud' that should be set. I would prefer to get an installer, but http://www.izforge.com/izpack/ is GPL, I guess one would have to find some possibly simpler method to install (mainly on windows). Although at least a script, in a couple different shells should at least be setup for unix/linux/ etc. One could argue that most people that use the 'non-norm' know how to setup the system, but I don't think this is always the case. Any good ideas about fixing this problem? It would be nice to have an installer that isn't GPL and would fit within the Apache license, but I haven't done the research on this... > The Getting Started Guide is incomplete (section: Installing and working with > Derby) and so not helpful to new users > -------------------------------------------------------------------------------------------------------------------- > > Key: DERBY-879 > URL: http://issues.apache.org/jira/browse/DERBY-879 > Project: Derby > Type: Bug > Components: Documentation > Reporter: Stan Bradbury > > The "Installing and working with Derby" chapter of the Getting Started Guide > is incomplete and so not useful to a new Derby user (see user feedback > attached in the comments). This entry contains documents for each section > (html page) of this Chapter what needs to be changed (marked PROBLEM) and > things that would be helpful to add (ENHANCEMENT). The items marked PROBLEM > should be addressed ASAP. > Chapter "Installing and working with Derby" - First page > >> http://db.apache.org/derby/docs/dev/getstart/cgsinsta.html > Describes the sections in the Chapter. Update as necessary to reflect > changes in section titles and order. > SECTION: Installing Derby > >> http://db.apache.org/derby/docs/dev/getstart/cgsinstallingderby.html > No major problems > ENHANCEMENT: example showing the naming convention of a bin archive is needed. > SECTION: Setting up your Java environment > >> http://db.apache.org/derby/docs/dev/getstart/tgssetupjavaenvir.html > OK if java is setup properly in the PATH. > PROBLEM: Command examples need to be added to Item 2 to resolve problems with > the PATH. > PROBLEM: The problem of not having a JDK installed is not covered. > PROBLEM: Under Related Topics - remove the link to: "Manually setting > environment variables and paths" > SECTION:Using the tools and startup utilities > >> http://db.apache.org/derby/docs/dev/getstart/cgsusingtoolsutils.html > This is not a Getting Started subject. Reduce the scope of this to IJ and > SYSINFO > PROBLEM: Title is not accurate > PROBLEM: dblook, export/import, database class utilities are not Getting > Started Topics - remove references > PROBLEM: the scripts listed require DERBY_INSTALL be set in order to work as > shown in the following sections > PROBLEM: /frameworks/embedded/bin is not a valid directory (need > DERBY_INSTALL) > PROBLEM: Only setting PATH for UNIX is identified - this is required for > WINDOWS in order for the scripts to work as shown in the following sections > PROBLEM: the /bin directory does not exist, be explicit > (DERBY_INSTAALL/frameworks/embedded/bin) > SECTION: Using sysinfo > >> http://db.apache.org/derby/docs/dev/getstart/cgsusingsysinfo.html > PROBLEM: In the standard distribution of Derby (the 'bin' distribution) the > script DOES NOT set the appropriate environment as stated on this page. > ENHANCEMENT: An example and explanation of the output is needed. > SECTION: Running ij > >> http://db.apache.org/derby/docs/dev/getstart/tgsrunningij.html > PROBLEM: In the standard distribution of Derby (the 'bin' distribution) the > script DOES NOT set the appropriate environment as stated on this page. > PROBLEM: Incorrect statement: "You must include the /bin directory in your > PATH environment variable to run ij." This refers to running the IJ script. > ENHANCEMENT: An example of a simple select is needed. > ENHANCEMENT: State that the command will not execute until a semicolon is > typed. > SECTION: Manually setting environment variables and paths > >> http://db.apache.org/derby/docs/dev/getstart/cgsmanuallysetting.html > PROBLEM: DERBY_INSTALL and CLASSPATH are key variables and should be > discussed before SYSINFO and IJ. > PROBLEM: This statement is very confusing: "This document assumes that > directory is named Derby_10" . Also it is not good to use a version number > here, what about the next release? > PROBLEM: This is incorrect: "The classpath is a list of the class libraries > needed by the JVM " reword as something like 'libraries available to' or > 'known to' or something. > ENHANCEMENT: Introduce NoClassDefFoundError exception here > ENHANCEMENT: Better title needed > SECTION: Set the DERBY_INSTALL environment variable > >> http://db.apache.org/derby/docs/dev/getstart/tgs36360.html > PROBLEM: /frameworks/embedded/bin does not exist (need DERBY_INSTALL). > PROBLEM: Unix command example not provided to set variable > ENHANCEMENT: use full path names for directories (e.g. C:\Derby_10) > SECTION: Set the classpath > >> http://db.apache.org/derby/docs/dev/getstart/tgs26250.html > PROBLEM: This is incorrect: "The classpath is a list of the class libraries > needed by the JVM " reword as something like 'libraries available to' or > 'known to' or something. > PROBLEM: /frameworks/embedded/bin directory and /frameworks/NetworkServer/bin > do not exist (need DERBY_INSTALL). > PROBLEM: Unix command example not provided to set variable > PROBLEM: Though nice, the bullets about manually running SYSINFO and IJ are > not tied into the topic of CLASSPATH. -- 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
