db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Stan Bradbury (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby and Getting Started Guide
Date Thu, 14 Jun 2007 22:40:26 GMT

    [ 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.


Mime
View raw message