[
https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12504045
]
Laura Stewart commented on DERBY-2390:
--------------------------------------
Comments made by Stan Bradbury on derby-dev 5/30/2007
Hi Laura -
I'm posting these comments to the email thread but NOT adding a comment to the
JIRA issue. You can add this message to DERBY-2390 if you like or simply
summarize relevant points based on your decisions about the suggestions. The
document looks good but I think it would be clearer to novice users to provide
the following information / clarifications (in not particular order):
1) It looks like Kim has flagged the references to JDK 1.3 which is no longer
supported in this release. The info from the WIKI states:
10.3 Platforms : Minimum JDK support will change to JDK 1.4.2 for J2SE &
CDC/Foundation 1.1 for J2ME. (Removes support for JDK 1.3 and
J2ME/CDC/Foundation 1.0) -> DERBY-1982
o) Laura is correct raising issue 6: "I don't think that we do a good job of
describing what the Network Server is." And I agree with Kim's suggestion:
"Deployment options - Here, probably, is where "Network Server" needs to be
defined." IMHO the Deployment options section of the Getting Started Guide
has never been right. The GS should only introduce the two basic options:
Embedded and Server / Network Server. Any more gets you into the deep weeds
really quickly. Here's a basic 'Getting Started' replacement for this section:
==== Begin of Replacement ===============
Before you install Derby, you should understand the system requirements and two
basic
frameworks provided.
Basic Frameworks Provided
The Derby software distribution provides two basic frameworks (also referred to
as 'deployment options'). The simple embedded framework and the Derby Network
Server framework.
o Embedded is used to refer to Derby being started by a simple single-user
Java application. In this framework Derby runs in the same Java virtual
machine (JVM) as the application. Derby can be almost invisible to the end
user because it is started and stopped by the application and often requires no
administration.
o Server (or Server based) is used to refer to Derby being started by an
application that provides multi-user connectivity to Derby across a network.
In this framework Derby runs in the Java virtual machine (JVM) that hosts the
Server and applications connect to the Server from different JVMs in order to
access the database(s). The Derby Network Server is part of the Derby software
distribution and provides this type of framework for Derby. Derby also works
well with other, independently developed Server applications.
========== END =============
o) The document would benefit from clarifying the three different 'command
styles' shown in the 'Using the Derby tools and setup utilities'. Adding
information to the 'Choose a method to run the Derby tools and startup
utilities' seems like where this is needed. Also, for clarity and use the text
provided below you will need to perform the following global changes on two of
the three 'Method' columns in each table:
Replace Method:
Run the tools as standalone commands
with:
Run the tools using the command scripts
Replace Method:
Run the tools using the jar files that are located in the directory where the
tools reside.
with:
Run the tools using the derbyrun.jar archive
Intro Replacement suggestion [NOTE: you could instead add the three
'People/Programmers ... interested/have' sentences below to the 'When to Use'
section of the table]
There are several ways that you can run the Derby tools and startup utilities.
with:
This section discusses how to setup the system environment variables needed to
run the Derby tools and utilities presented in the next section. Three ways to
run each tools and utilities are shown. Choose the method that best fits your
own personal needs and interests. Java programmers will probably be interested
in learning the full command syntax show by the methods: '...using java
command'. People who have a full Derby 'bin' distribution available, want to
do a minimal amount of typing when running the tools and don't mind setting up
a few environment variables upfront will like using the method '...shell
scripts provided'. People interested in performing the minimum amount of
environment setup and being able to run the tools when only the derby jarfiles
are available will want to use the method: '...using the derbyrun.jar archive'.
Replace:
Choose the method that you want to use:Choose the method that you want to use:
with:
Use the following table to identify the setting required for the method which
is right for you.
In the first table itself, the second row (derbyrun) remove the following:
Col 2: • Do not run the tools often - (this is not a good recommendation,
see text above)
Col 3: JAVA_HOME - ( with JAVA in your PATH there is no reason to have
JAVA_HOME set)
--- I hope you find this helpful. I think these changes, though somewhat
longish, will provide the intro needed to guide new users through the rest of
the document. I will provide additional input tomorrow but I think this is the
bulk of it.
> 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, 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.
