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 "Kim Haase (JIRA)" <ji...@apache.org> on 2007/05/24 20:11:16 UTC
[jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby and
Getting Started Guide
[ https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12498750 ]
Kim Haase commented on DERBY-2390:
----------------------------------
This is a terrific job, Laura -- I think you've done a great job merging the manuals. These comments are on the individual sections. I don't think these answer every question you had, though. Let me see -- question 5 -- I think it would be good to update the output to 10.3 if possible, but getting the svn version right is probably not possible since code hasn't frozen. Question 7 -- I believe both "mode" and "environment" are used but in slightly different situations -- it might be worth adding the mention of "mode" to the Terminology section? I think "configuration" is used only in "Deployment options" -- not sure.
Introduction to Derby
Nice synthesis.
Last sentence -- you might reverse the order of "system requirements and deployment options" to make it the same order as the sections that follow.
Deployment options
Here, probably, is where "Network Server" needs to be defined. But even the Admin Guide doesn't seem to define it exactly. It talks about what it *does* but doesn't say what it *is*. I don't know the answer to that question.
System requirements
I think for 10.3 the JDK version is 1.4 or higher? Maybe you were figuring on dealing with this stuff later.
Product documentation for Derby
Glad you changed this from "library" -- that's a confusing term in software!
Getting Started introduces dblook as well as sysinfo and ij, I think -- at least briefly?
The last paragraph mentions "Version 10.2" -- is that from one of the conrefs that need to be changed for the next release?
Installing Derby
I like the reordering here.
Setting up your environment
In step 2, the common usage is "Set the environment variables", not "Set up".
Choosing a method to run the Derby tools and startup utilities
A table works really well here!
First row, middle column: second sentence repeats content of first column so may be removable.
Third row, first column: should be "the java command", I think.
Third column: in both the second and third rows, the last paragraph is in bigger type than the other(s) in the PDF. Any idea why? I see this happens in other tables; it may just be a quirk of the DITA tools...
Also, in the third row, shouldn't CLASSPATH be included in the list of environment variables to set?
Syntax for the derbyrun.jar file
I'm wondering if this section shouldn't come after the next one (Setting the environment variables). The information is less basic.
Also, I think the first sentence should be more general because we're not talking just about the CLASSPATH here. Maybe "If you use the derbyrun.jar file, you do not need to remember which jar file to use for a particular purpose (as described in Libraries provided by Derby)."
Setting the environment variables
Second sentence: The common usage is that you set an environment variable, not set it up.
Step 1: I wonder why DERBY_10 is in code font in the second occurrence in the sentence but not in the first?
Step 2: Is there some reason why one command looks in the bin directory and the other just in the main DERBY_HOME directory? It is less distracting if they are the same.
Step 3: I think you need a "the" in the Windows entry ("add the JAVA_HOME environment variable").
Also you might use a more recent version of the 1.4.2 SDK -- the current version is j2sdk1.4.2_14. (By default it installs as j2sdk, not j2se.) Or even (gasp!) 1.5, the current version of which is jdk1.5.0_11. (They changed the naming convention for 1.5.) We previously used the version one up from the minimum -- we might continue that. Not necessary if it's too much work.
The Note here is a bit confusing. The thing is, if you have a Java executable in your path, that almost invariably means that you have set JAVA_HOME previously (and then set your PATH to include $JAVA_HOME/bin). So the note is in effect saying, "If you have already set JAVA_HOME, you don't need to set JAVA_HOME", which pretty much goes without saying. People who have JAVA_HOME set will know that and will skip the step anyway. So you could remove the note, I think.
Possibly what really needs to be here is something about adding $JAVA_HOME/bin to your PATH and using java -version to verify that it's set correctly. (See discussion later about "Verifying the Derby system configuration".)
Step 4: In the sentence about the control panel, there should not be a semicolon after "bin".
Step 5: I don't think you need the second "the" (before JAVA_HOME).
I think in the Note "very" should be "verify"?
In the second paragraph after that, "follow" should be "following".
Using the Derby tools and startup utilities
I think it is not quite accurate to say that "These scripts also help you set up your CLASSPATH environment variable." The scripts that start the Derby tools set the CLASSPATH variable while they are being run, but they don't leave it set. It would be better to leave out the sentence, I think.
There are additional scripts in the bin directory that can be used to set the classpath (setEmbeddedCP, etc.). I think they all work fine if DERBY_HOME is set. I don't know if they need to be mentioned at this point.
Running sysinfo, etc.
I notice the language on running the commands is not exactly parallel in all three sections (sysinfo, ij, dblook) -- you might look closely at these and sync them up.
I notice the first sentence in the second table row about sysinfo actually mentions dblook -- cut/paste error apparently.
I'm glad you added dblook to this -- it was missing before, for some reason.
There is a bullet under "Running sysinfo", after "To run the sysinfo script" -- but there is only one bullet item, so maybe the two sentences should be merged into "Choose the method for running the sysinfo script that you want to use", or something like that. Similarly, there is a "1." in front of a sentence under dblook, but this is the only item in the numbered list -- so it should probably be a plain paragraph, similar to whatever you use for sysinfo. (With ij there are actually three bullet items so there is no problem there.)
In the sentence above that there is a minor parallel-structure glitch -- should be either
"to either a console or a file"
or
"either to a console or to a file"
Manually setting the CLASSPATH environment variable
See what Stan says about this, but we might want to de-emphasize these scripts. Using derbyrun.jar simplifies matters considerably -- not only do you not need to figure out which classpath script to run, you don't need to set the classpath at all.
Verifying the Derby system configuration
Another JDK 1.3 mention.
Hm, there's a mention of using java -version back under System Requirements, but that was before all the info about setting JAVA_HOME -- I wondered about that. But I think most of the material in this current section is redundant at this point? The "echo DERBY_HOME" material is under "Setting the environment variables". In order for "java -version" to work, $JAVA_HOME/bin has to be in your PATH, just as $DERBY_HOME/bin has to be in your path in order for the standalone commands to work. So maybe that should be in the earlier section about setting environment variables.
You do have at least one xref to this section that would need changing...
Self-study tutorial for users new to Derby
Under "Tutorial skills and software requirements," you might want to change "run" to "use" in the second sentence. (You run commands, but you don't run syntax.)
Another JDK 1.3 mention (and Derby 10.2).
Under "Problems and feedback on the tutorial activities" maybe "even more useful" should be changed to "more useful" -- seems a bit presumptuous otherwise. I missed this one before.
Activity 1
The way you reorganized this is excellent.
Creating a directory and copying scripts into the directory
Step 1: I would suggest that you should NOT change to the directory where you installed Derby. It's not a great idea to add stuff to a Derby installation. The DERBYTUTOR directory should be in your home directory or some other place where you do your work.
Step 4: Period missing after second sentence.
Remove the sentence "In the following examples, substitute the correct path for the DERBY_HOME variable:". In fact, if you have the DERBY_HOME variable set, you can use exactly the commands shown, and it saves typing. (No need to put DERBY_HOME in italics.)
Also, at the end of this step I would recommend adding the "Important" note from Step 1 of Activity 3, since it applies here as well.
Creating a Derby database and running SQL statements
Step 7a: Missing period at end.
Activity 2: Run SQL using the client driver
Step 2: We should use derbyrun.jar here, I think. Replace
derbynet.jar start
with
derbyrun.jar server start
Step 4: "java" could be in code font in the third sentence.
Step 11: Replace
derbynet.jar shutdown
with
derbyrun.jar server shutdown
Activity 4
Steps 2 and 4 -- replace derbynet.jar with derbyrun.jar as in Activity 2.
Step 3: I think you can replace derbyclient.jar with derbyrun.jar -- but check with Stan on this.
For the Activity notes at the end, you might want to check with Rick Hillegas to see if this needs any updating to reflect the security changes for this release.
Database connection URL
There's some inconsistency in how the syntax is specified -- server and port are in angle brackets, but databaseName and URLAttributes are in italics. Since they are all meant to be replaceable items, they should all be in the same format (italics, I think) -- unless there's something I'm not understanding.
Typographical conventions
Were we going to try to update these so that people would use the correct conventions going forward? You have used our proposed doc conventions for this book, at least. Or is this an item for later when we have time to actually make corresponding changes to the other docs? (Maybe we could update one item at a time, say starting with fixed width for file and directory names.)
Libraries provided by Derby
First sentence: I think "their functions" would be more correct.
The format of this table seems confusing but I am not sure how to fix it; maybe it needs to be a 3-column table, "Library", "Library file name(s)", "Use"?
Libraries not provided by Derby
Looks like this can be cut now, since it relates to JDK 1.3.
Scripts included with Derby
The sentence introducing the list should be changed from
The complete list of scripts that are included with Derby are:
to
The complete list of scripts that are included with Derby is:
> 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
> Assigned To: 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.
Review - second installment: (DERBY-2390) DOCS - Merge Working with
Derby and Getting Started Guide
Posted by Stanley Bradbury <St...@gmail.com>.
Hi -
This is the second installment of my review of the new Getting Started
Guide. Again 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.
Background and General recommendations:
Thanks to Andrew's improvements of the scripts (.bat and .sh:
Derby-1032, v 10.2.1) the scripts no longer require that JAVA_HOME be
set and, though the scripts will now figure out the proper setting for
DERBY_HOME (assuming the scripts have not been moved from
DERBY_HOME\bin) I recommend we still document that DERBY_HOME be set for
ALL methods of execution. With regard to the scripts; having DERBY_HOME
set allows the discussion of adding the scripts directory to the PATH
environment variable can reference DERBY_HOME\bin. In addition the
changes I suggest below count on java being in the system/user PATH.
All the examples shown require the 'java.exe' be in the system/user PATH
and this should be clearly stated and a check added to replace that of
JAVA_HOME. I recommend something like this:
====== Related Text substitutions ======
>> Section: To check the Derby system configuration
Change item 1
... Replace:
1. Verify that the JAVA_HOME environment variable is set and points to a
JDK version 1.3 or higher.
Open a command window and run the command java -version
[ SYSTEM SYNTAX TABLE: Unix and Windows]
... With:
1. Verify that the java executable, version 1.4.2 or, higher is in your
command execution PATH by opening a command window and running the
command <CODE> java -version </code>
[NOTE TO AUTHOR: this command is the same on all platforms so the SYSTEM
SYNTAX TABLE can be removed. The example of output presented is fine,
just change the reference to 1.3 (and all other references) which
follows, as mentioned previously.
>> Section: Setting the environment variables
... Replace:
item: 3. Set the JAVA_HOME environment ...
... With:
3. Be sure the java executable is in your command execution PATH
OR .. just remove item #3 altogether...
>> NOTES TO AUTHOR:
Be sure to search for and REMOVE other reference to setting/checking
JAVA_HOME in the document.
The first table in the document, 'Choosing a method to run the Derby
tools and startup utilities' is key to the information presented later.
Since many of my suggestions (both first and second installments) change
or augment the information presented in the table, I thought I would
provide a rough rewrite for it. Of course, I am not the author nor a
good wordsmith so please use this as a guide and clean things up:
====== BEGIN of TABLE Suggestion =========
++ COLUMN 1: Method
ROW 1
Run the tools using the shell scripts provided
ROW 2
Run the tools using the derbyrun.jar archive
ROW 3
Run the tools using complete java command syntax or use Derby in a Java
program
++ COLUMN 2: When to Use
ROW 1
When you want to execute the tools with the least amount of typing and
have a full Derby 'bin' software distribution available.
ROW 2
When you only have the derby jarfile set available or you do not want to
use the scripts provided.
ROW 3
When you do not have the scripts and derbyrun.jar archive available or
when you are interested in learning the full syntax of each command and
understanding the details of setting up the execution environment.
Also, anyone who will be programming with Derby will need to meet the
requirements listed for this method.
++ COLUMN 3: Requirements
ROW 1
To use the examples in this book, the DERBY_HOME environment variable
must be set and both the java executable and the Derby scripts directory
(DERBY_HOME\bin) must be in your command execution PATH.
ROW 2
To use the examples in this book, the DERBY_HOME environment variable
must be set and the java executable must be in your command execution
PATH. The derbyrun.jar file must be in the same folder as the other
Derby jarfiles.
For more information see the syntax for the derbyrun.jar file.
ROW 3
To use the examples in this book, the DERBY_HOME environment variable
must be set and the java executable must be in your command execution
PATH. You will need to know the full package name for the java class
supporting the tool and the CLASSPATH environment variable must be set
to include the required jarfiles.
For details on setting the CLASSPATH, see Manually setting the
CLASSPATH environment variable.
============= END OF TABLE =========================
- - - - END: Related Text substitutions - - - -
INCORRECT INFORMATION [note: derbyrun.jar does NOT need to be in CLASSPATH]:
>> SECTION:Syntax for the derbyrun.jar file
.. Replace:
Adding the derbyrun.jar file to your CLASSPATH is equivalent to adding
all of the
Derby jar files to your CLASSPATH
.. With:
The derbyrun.jar file is a special jarfile archive that greatly
simplifies invoking the Derby tools and Network Server. It allows these
programs to be executing using shortened names and without having to set
the java CLASSAPATH environment variable. To use derbyrun.jar the file
must be in the same folder as the other Derby jarfiles.
NOTE TO AUTHOR: It would be appropriate to add "Manually setting the
CLASSPATH environment variable" to this section as it is an environment
variable. It seems odd that it is in the section: 'Using the Derby
tools and startup utilities'. My suggestions below include CLASSPATH
and so will need tweaking if you do not want to cover CLASSPATH here.
>> SECTION: Setting the environment variables
.. Replace:
If you set several environment variables, the scripts that are included
with the Derby bin distribution will be easier to run.
.. With:
This section shows how to setup the environment variables required to
support the execution method you select for using the Derby tools. As
stated in the table "Choosing a method to run the Derby tools and
startup utilities", the environment variable DERBY_HOME needs to be set
to use the command examples presented in this manual. In addition
adding the Derby scripts directory to your execution path makes the
scripts easier to use and is also required to use the script examples
presented. The CLASSPATH environment variable must be set if you will
be using Derby in a Java program or executing the tools using the java
command.
NOTE TO AUTHOR: I think with the above lead in you can remove this
sentence that only talks about the scripts. Or maybe incorporate some
of it in the above??
... Seems not to be needed
The Derby scripts run the Derby tools and utilities. If you decide not
to setup the
environment variables, you will need to run the Derby tools manually.
NOTE TO AUTHOR: The following two notes appear in the document and
should either be removed or clarifying text added. New windows need to
be opened only after making changes using the Control Panel. Control
Panel changes only effect windows opened after the edits have been
saved. If the variables are set manually in a window then they are in
effect ONLY in that window - you will NOT be able to check settings done
this way in another window.
.. Note: You will need to open a new command window to verify that the
DERBY_HOME environment variable is set.
.. Note: On Windows, you will need to open a new command window to
very the
settings for these environment variables.
Re: [jira] Commented: (DERBY-2390) DOCS - Merge Working with Derby
and Getting Started Guide
Posted by Stanley Bradbury <St...@gmail.com>.
Kim Haase (JIRA) wrote:
> [ https://issues.apache.org/jira/browse/DERBY-2390?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12498750 ]
>
> Kim Haase commented on DERBY-2390:
> ----------------------------------
>
> This is a terrific job, Laura -- I think you've done a great job merging the manuals. These comments are on the individual sections. I don't think these answer every question you had, though. Let me see -- question 5 -- I think it would be good to update the output to 10.3 if possible, but getting the svn version right is probably not possible since code hasn't frozen. Question 7 -- I believe both "mode" and "environment" are used but in slightly different situations -- it might be worth adding the mention of "mode" to the Terminology section? I think "configuration" is used only in "Deployment options" -- not sure.
>
= = = = SNIP === Stan's comments:
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
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.