[
https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12504953
]
Stan Bradbury commented on DERBY-2390:
--------------------------------------
Comments / suggests based on review of the recent Alpha Gettting Started upto
the Tutorial section:
>>> Clarification (minor) - Section: System requirements
SAYS:
You must have a Java Development Kit (JDK) version 1.4 or higher installed on
your computer. To check that the correct version of Java is installed, issue
the java
-version command.
ISSUE:
It is true that you need a JDK to perform the exercises in the tutorial. You
should add this qualification or state something like: You must have JAVA
version 1.4 or higher installed on your computer. Java Development Kit (JDK)
is required to perform the activities in the tutorial. To check that the
correct version of Java is installed, issue the java -version command.
[NOTE TO AUTHOR: JAVA comes packaged two ways, a JRE (runs JAVA programs like
Derby, IJ, etc.: almost everyone has this) and a JDK (needed to compile JAVA
programs like those in the tutorial)]
>>> SECTION: Product documentation for Derby
The doc list section for: Derby Tools and Utilities Guide
SAYS:
Describes how to use the Derby tools such as ij, more advanced utilities such as
import and export, and the database class loader
BETTER would be:
Describes how to use the Derby tools such as ij, sysinfo, dblook and use of the
system procedures to import and export data and to store java code in the
database.
[NOTE TO AUTHOR: references to 'the database classloader' should be replace
throughout the document set with: System procedures to store java code in the
database.]
>>> I think the reference to 'optimized jar files' is wrong and have asked
for confirmation on the list. Either both distribution contain 'optimized jar
files' or neither does.
The distributions are:
• The bin distribution contains scripts, demonstration programs, and
documentation.
The optimized jar files are available in the lib distribution.
• The lib distribution contains an optimized, small footprint set of the
Derby jar files for deployment.
>>> In Table1 - row 2 , column 2 (derbyrun):
SAYS:
• You have only the derbyrun.jar file available, and do not have the full bin
distribution of Derby
BETTER IS:
• You have only the derby jar files available (see: "Libraries provided by
Derby") and do not have the full bin distribution of Derby.
[NOTE TO AUTHOR: 'only the derbyrun.jar file' is wrong As mentioned in column 3
you need the other jar files - derbyrun needs to find them for anything to run.]
>>> This seems clearer to me - it references back to the Column 3 in the
table:
SAYS:
2. Based on the method that you chose to run the tools, follow the instructions
to set
the environment variables.
BETTER:
2. Based on the requirements of the method that you chose to run the tools,
follow the instructions to set
the environment variables.
>>> TYPO in Section: Setting the environment variables
command execution PATH makes the scripts ?are? easier to use and enables you to
use
>>> I find this paragraph confusing. Think it can be removed:
If you decide not to set the environment variables, you will need to run the
Derby tools
manually.
>>> The numbered list titled: To set the environment variables:
2b and the related table can be removed. JAVA_HOME is NOT needed anymore.
AND also - The numbered list titled: To check the Derby system configuration:
1a and the related table can be removed.
>>> Recommend putting advanced topics (e.g. Network Server) and notes
(Additional Derby utilities) last (after the detail sections on the tools).
SUGGEST MOVE sections: 'Running the scripts with the Network Server' and
'Additional Derby utilities' to the end of 'Using the Derby tools and startup
utilities ' as a section on a par with the 'Running xxxx'.
>>> ALL the 'RUNNING xxx' TABLES.
Row 3, Col 3 - You DO need to set your CLASSPATH but derbyrun.jar is NOT needed
at all for this mode. It actually NEVER needs to be in the CLASSPATH. And 'in
the java command' sounds strange so I changed it to 'with the java command' -
would be good to get another opinion on this nuance
CURRENT TEXT:
You must set your CLASSPATH to include the derbyrun.jar file and then specify
the class name in the java command.
CORRECTION:
You must set your CLASSPATH as shown in the section 'Manually setting the
CLASSPATH environment variable' and then specify the class name with the java
command.
> DOCS - Merge Working with Derby and Getting Started Guide
> ---------------------------------------------------------
>
> Key: DERBY-2390
> URL: https://issues.apache.org/jira/browse/DERBY-2390
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Reporter: Laura Stewart
> Assignee: Laura Stewart
> Fix For: 10.3.0.0
>
> Attachments: cgsintro.html, derby2390_1.diff, getstartderby.pdf,
> rgsdocs17307.html
>
>
> The activities in the Working with Derby guide should be merged into the
> Getting Started Guide.
> Review Getting Started Guide for any reference info that should be either
> "shared" with another guide
> or moved to another guide. For example, the SQL Syntax section in the Getting
> Started Guide should
> be moved to the Reference Manual.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
