You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Stan Bradbury (JIRA)" <de...@db.apache.org> on 2006/01/27 00:20:32 UTC
[jira] Created: (DERBY-879) The Getting Started Guide is incomplete
(section: Installing and working with Derby) and so not helpful to new
users
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
[jira] Commented: (DERBY-879) The Getting Started Guide is
incomplete (section: Installing and working with Derby) and so not helpful
to new users
Posted by "Stan Bradbury (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-879?page=comments#action_12364156 ]
Stan Bradbury commented on DERBY-879:
-------------------------------------
A basic rewrtie of section: " Manually setting environment variables and paths":
-- hope you find this useful.
Change title to: Setting up the Derby Environment
DERBY_INSTALL
During the installation the files and directories containing the Derby system were placed in a directory on the harddisk of your computer. In order to locate the files discussed in the documentation it is important that you know the location of this directory. In the Derby documents the full path to Derby installation directory is symbolically referred to as DERBY_INSTALL. Please make a note of the Derby installation directory before continuing.
Set the DERBY_INSTALL variable
DERBY_INSTALL is also used as an environment variable in scripts provided to assist with the use of Derby as well as many command examples. If your operating system supports it, create the environment variable DERBY_INSTALL. Set the value of this variable to the path of the Derby installation directory. Examples for setting the variable in a Windows and a Unix environment are provided below:
UNIX (Korn shell): if you installed the product in /opt/derby , set DERBY_INSTALL like this: $ export DERBY_INSTALL=/opt/derby
WINDOWS: if you installed the product in C:\Programs\derby , set DERBY_INSTALL like this: set DERBY_INSTALL=C:\Programs\derby
Set the CLASSPATH variable
The Java JVM needs to know the location of every class file and jarfile needed by your application. The CLASSPATH variable contains a list of the directories and files available to the Java JVM and other Java applications. Set your CLASSPATH to include the needed Derby libraries. The Derby libraries are found in the lib directory of DERBY_INSTALL. Examples for manually setting the variable in a Windows and a Unix environment are provided below. The CLASSPATH shown in these examples will allow the use of Derby and the Derby tools. The examples assume the DERBY_INSTALL variable discussed above is set properly:
UNIX (Korn shell, note that a colon separates the files): export
CLASSPATH=$DERBY_INSTALL/lib/derby.jar:$DERBY_INSTALL/lib/derbytools.jar:.
WINDOWS (note that a semi-colon separates the files): set CLASSPATH=%DERBY_INSTALL%\lib\derby.jar;%DERBY_INSTALL%\lib\derbytools.jar;.
[NOTE: a section on validating the variable setting would be good to add here - no time to include it in this draft but there is a good a good example of validating the environment at:
http://db.apache.org/derby/papers/DerbyTut/install_software.html#derby_verify ]
> 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
[jira] Updated: (DERBY-879) The Getting Started Guide is incomplete
(section: Installing and working with Derby) and so not helpful to new
users
Posted by "Stan Bradbury (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-879?page=all ]
Stan Bradbury updated DERBY-879:
--------------------------------
Comment: was deleted
> 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
Re: [jira] Commented: (DERBY-879) The Getting Started Guide is incomplete (section: Installing and working with Derby) and so not helpful to new users
Posted by Andrew McIntyre <mc...@gmail.com>.
On 1/27/06, Daniel John Debrunner <dj...@apache.org> wrote:
>
> One way to start solving these types of issues is to see what other
> Apache projects do.
I looked around not long ago at what other projects do for installers.
Most of the Java projects just have zips and tars. Some of the C
projects produce packages (rpm, Solaris pkg).
Tomcat, Maven and Lenya use NSIS, the Nullsoft Installer:
http://nsis.sourceforge.net/Main_Page
It has a non-standard but unrestrictive license.
And looking again at httpd, they have an InstallShield installer now,
which is news to me. I'm curious if InstallShield donated free
licenses to the httpd community, or if an httpd developer happens to
have a commercial license and produces the installers for the
community.
andrew
Re: [jira] Commented: (DERBY-879) The Getting Started Guide is incomplete
(section: Installing and working with Derby) and so not helpful to new users
Posted by scott hutinger <S-...@wiu.edu>.
Daniel John Debrunner wrote:
> scott hutinger (JIRA) wrote:
>
>
>> [ 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...
>>
>
> One way to start solving these types of issues is to see what other
> Apache projects do. Typically such problems have already been faced by
> other projects, that's part of the purpose of Derby being here, to take
> gain synergy from existing work.
>
> For example I think I remember Tomcat had some GUI installer.
>
> Dan.
>
>
Hmmm, you make it sound too easy :-). But yes, this is a very good
idea, too bad I couldn't think of it...
I'll take a look around and see what everyone else is doing....
thanks,
scott
Re: [jira] Commented: (DERBY-879) The Getting Started Guide is incomplete
(section: Installing and working with Derby) and so not helpful to new users
Posted by Daniel John Debrunner <dj...@apache.org>.
scott hutinger (JIRA) wrote:
> [ 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...
One way to start solving these types of issues is to see what other
Apache projects do. Typically such problems have already been faced by
other projects, that's part of the purpose of Derby being here, to take
gain synergy from existing work.
For example I think I remember Tomcat had some GUI installer.
Dan.
[jira] Commented: (DERBY-879) The Getting Started Guide is
incomplete (section: Installing and working with Derby) and so not helpful
to new users
Posted by "scott hutinger (JIRA)" <de...@db.apache.org>.
[ 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
Re: [jira] Commented: (DERBY-879) The Getting Started Guide is incomplete (section: Installing and working with Derby) and so not helpful to new users
Posted by Andrew McIntyre <mc...@gmail.com>.
On 1/26/06, Bryan Pendleton <bp...@amberpoint.com> wrote:
>
> - improve the bundled scripts to be easier to use
> - re-arrange the directory structure to be more obvious (I was
> certainly confused by the concept of a "framework" when I first
> started with Derby).
> - issue better error messages for misconfiguration problems.
These are all excellent ideas. I had a few ideas to improve the scripts as well:
- change the name of the framework directory to bin and collapse the
directory structure.
- change DERBY_INSTALL to DERBY_HOME to make it similar to other
projects' use of a HOME variable
- use the DERBY_HOME variable to self-configure as much as possible.
- improve the scripts to detect whether you are in a client/server or
embedded environment and do the right thing for the tools that work
differently in the two environments.
I'm sure other people have ideas on ways to improve the scripts to get
people up and running faster. Because some of them are fairly
straightforward, although I believe there's an impact on the docs
particularly with the DERBY_INSTALL -> DERBY_HOME change.
Lance Andersen also mentioned he would prefer an alternative to
scripts altogether, such as Ant based task files.
If no one objects to the changes above, though, I can file JIRA
entries for them and start looking into doing them.
andrew
Re: [jira] Commented: (DERBY-879) The Getting Started Guide is incomplete
(section: Installing and working with Derby) and so not helpful to new users
Posted by scott hutinger <S-...@wiu.edu>.
Hi Bryan,
I do agree that some type of installer/install scripts etc should
exist. Any good idea's about what path to take :-)
scott
Bryan Pendleton wrote:
> Stan Bradbury (JIRA) wrote:
>> The following email prompted the filing of this JIRA entry:
>> ===== Feedback on the initial Derby experience ====
>
> That is a very interesting set of experiences. It's not obvious
> to me that all of these are necessarily best fixed via documentation.
> In some cases, it might be possible to also do things like:
> - improve the bundled scripts to be easier to use
> - re-arrange the directory structure to be more obvious (I was
> certainly confused by the concept of a "framework" when I first
> started with Derby).
> - issue better error messages for misconfiguration problems.
>
> I think it's wonderful that you're working on improving the
> documentation; I'm just observing that as you do so, it would
> be great if you could also keep an eye out for the possibility of
> improvements we could make to things like scripts, installer, etc.
> at the same time.
>
> thanks,
>
> bryan
>
>
>
Re: [jira] Commented: (DERBY-879) The Getting Started Guide is incomplete
(section: Installing and working with Derby) and so not helpful to new users
Posted by Bryan Pendleton <bp...@amberpoint.com>.
Stan Bradbury (JIRA) wrote:
> The following email prompted the filing of this JIRA entry:
> ===== Feedback on the initial Derby experience ====
That is a very interesting set of experiences. It's not obvious
to me that all of these are necessarily best fixed via documentation.
In some cases, it might be possible to also do things like:
- improve the bundled scripts to be easier to use
- re-arrange the directory structure to be more obvious (I was
certainly confused by the concept of a "framework" when I first
started with Derby).
- issue better error messages for misconfiguration problems.
I think it's wonderful that you're working on improving the
documentation; I'm just observing that as you do so, it would
be great if you could also keep an eye out for the possibility of
improvements we could make to things like scripts, installer, etc.
at the same time.
thanks,
bryan
[jira] Commented: (DERBY-879) The Getting Started Guide is
incomplete (section: Installing and working with Derby) and so not helpful
to new users
Posted by "Stan Bradbury (JIRA)" <de...@db.apache.org>.
[ http://issues.apache.org/jira/browse/DERBY-879?page=comments#action_12364154 ]
Stan Bradbury commented on DERBY-879:
-------------------------------------
The following email prompted the filing of this JIRA entry:
===== Feedback on the initial Derby experience ====
Here are my UCD [User Centered Design] comments on getting started with Cloudscape 10.1.
My Cloudscape 10.1 installation experience
I downloaded the .exe install program for Windows, ran it, read the release notes, and even read the installation instructions on the download page. So as far as I know, Cloudscape is installed successfully on my machine.
Now what? The installation instructions from the download page say that "You should also review Getting Started with Cloudscape in the user documentation. This information is especially important in helping you use Cloudscape 10.1"
But they don't point me anywhere specifically. So I'm stalled with nothing to read, and nothing to run.
I don't think that I should need to do research to use Cloudscape. The instructions should flow linearly until I'm creating tables, inserting data, and running queries. I know what relational databases can do, so how do I do those things with Cloudscape? Don't know.
So with enough searching on the web, I found the Getting Started guide. The first thing it wants me to is to see if the Java executable is in my path. It's not. It wants me to update the path, but isn't telling me how. I can never remember this sort of thing so more research required ... thank goodness for Google.
OK, my path is now set and the java -version test works correctly.
The documentation wants me to run sysinfo. It also says that I need the /bin directory in my path. I had just included the JVM's bin directory in my path, but the command fails anyway:
'sysinfo' is not recognized as an internal or external command,
so it must mean some other /bin directory. But it doesn't say which one, so time to start guessing...
Hey, look at that. I found a bin directory - and a sysinfo.bat file - way down in the subdirectory:
C:\Program Files\IBM\Cloudscape_10.1\frameworks\NetworkServer\bin
I don't know what a "framework" or a "NetworkServer" is, but I'll guess that this is the right directory. (Since I took the default location during installation, it might have been helpful if the docs suggested a location. Or even a relative location.)
So I'll add another directory to my path - it's getting long - and then try it again.
Well, something changed. When I run sysinfo now, it says:
Could not connect to Derby Network Server on host localhost, port 1527.
and appears to hang. Oh, it just returned to the prompt. Hmm, back to the Getting Started guide...
Let's try the "ij" command instead. Whoah, it didn't like that. I got a twenty line error message from that one. I'll skip the rest of this "ij" section and scroll down in the Guide.
Scrolling down farther, I find the section on manually setting environment variables and paths. The previous automatic (?) method didn't work for me, so I'll try manual.
The book says that a base directory was created during install, for example "Derby_10". Nope, no such directory on my computer. There is a directory "Cloudscape_10.1" on my computer. That must be it.
Wait a minute. It says I should do the following
set DERBY_INSTALL=c:\Derby_10
Should I set DERBY_INSTALL to the Cloudscape_10.1 directory or should I create CLOUDSCAPE_INSTALL instead? I'll split the difference, and set DERBY_INSTALL to the Cloudscape directory. There's nothing to test, so I'll go onto the next section.
OK, the Set the Classpath section is confusing. It suggests I use scripts - and gives me a directory location - but it doesn't actually say which scripts. Then it immediately shows me how to do it manually. So which should I do? Since I don't know what the script files are named, I'll try the manual command:
C:\>set CLASSPATH=%DERBY_INSTALL%\lib\derby.jar;%DERBY_INSTALL%\lib\derbytools.jar;%CLASSPATH%
What does my CLASSPATH look like?
C:\>echo %classpath%
"C:\Program Files\IBM\Cloudscape_10.1"\lib\derby.jar;"C:\Program Files\IBM\Cloudscape_10.1"\lib\derbytools.jar;%CLASSPATH%
That's odd. I've got a trailing %CLASSPATH% string in my classpath definition. I'll ignore it.
Now let's try sysinfo again:
C:\>java org.apache.derby.tools.sysinfo
OK, a whole bunch of output. I'll declare success and move on to the "ij" command.
The documentation is telling me to run the following command:
ij> connect 'jdbc:derby:<dbname>;create=true';
where <dbname> is "the name of the database you are connecting to". Huh? What database? Cloudscape? I thought that I was using Cloudscape. And what does it mean by "connecting to"? I'm afraid to run this command. Who cares anyway, this command apparently doesn't do anything useful.
ij> exit
hey, it's just hanging there. Oh, forgot the semi-colon.
ij> exit
;
now it exited.
I still want to create some tables, insert some data, and run a couple of queries. But as I read the rest of the book, I don't find any instructions on how to do that. I can only find instructions on how to use JDBC. Pity, I'd have hoped that Cloudscape would have allowed me to issue interactive SQL commands. Guess it doesn't have that capability.
OK, it's the next day, and I'm rereading the Getting Started guide again. I found the description of what you can do with "ij" in terms of creating databases and executing SQL statements. Yea! So I'm going to try that:
java org.apache.derby.tools.ij
ij> connect 'jdbc:derby:rollerdb;create=true';
And that's as far as the Getting Started guide takes me.
I have a long script file, and I need to see which SQL statements in the script fail. The manual says that I can redirect output to a file. Good.
By redirecting output to a file:
java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver
org.apache.derby.tools.ij <myscript.sql> <myoutput.txt>
So I'll do the command
C:\Roller data>java -Djdbc.drivers=org.apache.derby.jdbc.EmbeddedDriver org.apache.derby.tools.ij createderbydb.sql output.txt
Usage: java org.apache.derby.tools.ij [-p propertyfile] [-ca connectionAttribute
PropertyFile] [inputfile]
Bummer, didn't work. According to the error message, I can't have an output file?
I did finally get to the point where I could execute SQL statements and even run a script file. But considering that I came into this already knowing SQL, I'd argue that it took me longer than it should have. Very possibly due to my lack of Java or other skills, but that will still impact Cloudscape/Derby adoption.
> 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
[jira] Closed: (DERBY-879) The Getting Started Guide is incomplete
(section: Installing and working with Derby) and so not helpful to new
users
Posted by "Stan Bradbury (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-879?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Stan Bradbury closed DERBY-879.
-------------------------------
Resolution: Fixed
Fix Version/s: 10.3.1.4
The rewrite of the Getting Started Guide done for version 10.3 has taken care of these issues. No need to keep this open.
> The Getting Started Guide is incomplete (section: Installing and working with Derby) and so not helpful to new users
> --------------------------------------------------------------------------------------------------------------------
>
> Key: DERBY-879
> URL: https://issues.apache.org/jira/browse/DERBY-879
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Reporter: Stan Bradbury
> Fix For: 10.3.1.4
>
>
> 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.
-
You can reply to this email to add a comment to the issue online.