Derby
  1. Derby
  2. DERBY-2390

DOCS - Merge Working with Derby and Getting Started Guide

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.3.1.4
    • Component/s: Documentation
    • Labels:
      None

      Description

      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.

      1. cgsintro.html
        4 kB
        Laura Stewart
      2. derby2390_1.diff
        204 kB
        Laura Stewart
      3. derby2390_2.diff
        23 kB
        Laura Stewart
      4. derby2390_3.diff
        14 kB
        Laura Stewart
      5. derby2390_4.diff
        0.8 kB
        Laura Stewart
      6. derby2390_5.diff
        90 kB
        Laura Stewart
      7. getstartderby.pdf
        127 kB
        Laura Stewart
      8. getstartderby.pdf
        124 kB
        Laura Stewart
      9. rgsdocs17307.html
        6 kB
        Laura Stewart

        Activity

        Hide
        Laura Stewart added a comment -

        Here is a proposed outline for the merged Getting Started Guide and Working with Derby guide.

        I propose that we keep the title for the Getting Started Guide as is.

        Getting Started Guide
        Copyright
        License
        Introducing Derby
        Deployment options
        System requirements
        The Derby library
        Installing and working with Derby
        Installing Derby
        Setting up your environment
        Using the Derby tools and startup utilities
        Using the sysinfo tool
        Running ij
        Setting the classpath
        Self-study guide to get up and running with Derby
        Introduction and activity overview
        Activity 1: Run SQL using the embedded driver
        Creating the database and running SQL
        Activity 2: Run SQL using the client driver
        Activity 3: Run a JDBC program using the embedded driver
        The WwdEmbedded program
        Activity 4: Create and run a JDBC program using the client driver and Network Server
        What next with Derby?
        Quick start guide for experienced JDBC users
        Environments in which Derby can run
        Embedded environment
        Client/server environment
        Available drivers
        Database connection URL
        Documentation conventions
        Terminology
        SQL syntax
        Typographical conventions
        Derby libraries and scripts: complete reference
        Libraries provided by Derby
        Libraries not provided by Derby
        Scripts included with Derby
        Trademarks

        Show
        Laura Stewart added a comment - Here is a proposed outline for the merged Getting Started Guide and Working with Derby guide. I propose that we keep the title for the Getting Started Guide as is. Getting Started Guide Copyright License Introducing Derby Deployment options System requirements The Derby library Installing and working with Derby Installing Derby Setting up your environment Using the Derby tools and startup utilities Using the sysinfo tool Running ij Setting the classpath Self-study guide to get up and running with Derby Introduction and activity overview Activity 1: Run SQL using the embedded driver Creating the database and running SQL Activity 2: Run SQL using the client driver Activity 3: Run a JDBC program using the embedded driver The WwdEmbedded program Activity 4: Create and run a JDBC program using the client driver and Network Server What next with Derby? Quick start guide for experienced JDBC users Environments in which Derby can run Embedded environment Client/server environment Available drivers Database connection URL Documentation conventions Terminology SQL syntax Typographical conventions Derby libraries and scripts: complete reference Libraries provided by Derby Libraries not provided by Derby Scripts included with Derby Trademarks
        Hide
        Kim Haase added a comment -

        Thanks very much for doing this work, Laura! I think you've inserted the WWD material in the right place. I'm not sure that "self-study guide" is the right term, though, since it implies you're just reading – it's really a tutorial. Also, "up and running" might be a little colloquial. So I would suggest a title like "Tutorial: working with Derby" or maybe even just "Derby tutorial".

        I see that the "SQL Syntax" section is still included; were you going to file a separate issue to move it to the Reference Manual (maybe a subtask of this one)?

        Show
        Kim Haase added a comment - Thanks very much for doing this work, Laura! I think you've inserted the WWD material in the right place. I'm not sure that "self-study guide" is the right term, though, since it implies you're just reading – it's really a tutorial. Also, "up and running" might be a little colloquial. So I would suggest a title like "Tutorial: working with Derby" or maybe even just "Derby tutorial". I see that the "SQL Syntax" section is still included; were you going to file a separate issue to move it to the Reference Manual (maybe a subtask of this one)?
        Hide
        Jean T. Anderson added a comment -

        If you decide to name it "Derby tutorial", please just give me a heads up and I'll rename http://db.apache.org/derby/papers/DerbyTut/index.html to something suitable so the two don't get confused with each other.

        heh – I only just now noticed that none of the Derby books have "Apache" included in the title. I wonder if that should change moving forward.

        Show
        Jean T. Anderson added a comment - If you decide to name it "Derby tutorial", please just give me a heads up and I'll rename http://db.apache.org/derby/papers/DerbyTut/index.html to something suitable so the two don't get confused with each other. heh – I only just now noticed that none of the Derby books have "Apache" included in the title. I wonder if that should change moving forward.
        Hide
        Laura Stewart added a comment -

        There seems to be some overlap between the Getting Started info and
        the Derby Tutorial (install Derby, set classpath, etc). Also some
        overlap between the Working with Derby Guide and the Derby tutorial
        (embedded vs Network server).

        Is there a reason why there is this duplication?

        We should strive to have the info documented in one place, either the
        books or the Web, but typically not both. The main reason for this is
        maintenance. Writers like to single source the documentation so that
        it is easier to maintain. By having this info in 2 places (2 source
        files) we run the risk of one or the other being out of date.

        I do see some information that is not in the books, particularly the
        info on working with other products. There might be other examples as
        well...

        One way to avoid the duplication, is to point the reader to the main
        place for info. For example, instead of providing the installation
        info on the Web, indicate that installation is a step and point the
        reader to the Getting Started Guide, installation section.

        As for having "Apache" in the titles, that makes perfect sense to me.
        It should be there.


        Laura Stewart

        Show
        Laura Stewart added a comment - There seems to be some overlap between the Getting Started info and the Derby Tutorial (install Derby, set classpath, etc). Also some overlap between the Working with Derby Guide and the Derby tutorial (embedded vs Network server). Is there a reason why there is this duplication? We should strive to have the info documented in one place, either the books or the Web, but typically not both. The main reason for this is maintenance. Writers like to single source the documentation so that it is easier to maintain. By having this info in 2 places (2 source files) we run the risk of one or the other being out of date. I do see some information that is not in the books, particularly the info on working with other products. There might be other examples as well... One way to avoid the duplication, is to point the reader to the main place for info. For example, instead of providing the installation info on the Web, indicate that installation is a step and point the reader to the Getting Started Guide, installation section. As for having "Apache" in the titles, that makes perfect sense to me. It should be there. – Laura Stewart
        Hide
        Jean T. Anderson added a comment -

        The web-based tutorial now at http://db.apache.org/derby/papers/DerbyTut/index.html was originally developed for ApacheCon, not for the doc set.

        It's starting to become obsolete – for example, needs to be updated for 10.2.2.0 features (it uses the old scripts, doesn't say anything about derbyrun.jar). If your new effort can replace it, terrific. I'd be happy to remove it.

        Show
        Jean T. Anderson added a comment - The web-based tutorial now at http://db.apache.org/derby/papers/DerbyTut/index.html was originally developed for ApacheCon, not for the doc set. It's starting to become obsolete – for example, needs to be updated for 10.2.2.0 features (it uses the old scripts, doesn't say anything about derbyrun.jar). If your new effort can replace it, terrific. I'd be happy to remove it.
        Hide
        Kim Haase added a comment -

        Oops, obviously I forgot about the online Derby Tutorial (except possibly subconsciously!).

        The online one doesn't seem to have been kept up to date: it seems to apply to Derby 10.1.2.1, some of the pathnames (for example, that of the demo program in the Embedded Derby section) have changed, and it doesn't reflect other changes since that release (the introduction of derbyrun.jar, for example). This reinforces Laura's point about the difficulty of maintaining documentation in multiple places. I agree with her that it would be best to keep all the intro/tutorial material in one place.

        It would be great if the material that is in the Tutorial but not in Getting Started or Working With Derby (and that is still current) could be moved into the merged Getting Started.

        Show
        Kim Haase added a comment - Oops, obviously I forgot about the online Derby Tutorial (except possibly subconsciously!). The online one doesn't seem to have been kept up to date: it seems to apply to Derby 10.1.2.1, some of the pathnames (for example, that of the demo program in the Embedded Derby section) have changed, and it doesn't reflect other changes since that release (the introduction of derbyrun.jar, for example). This reinforces Laura's point about the difficulty of maintaining documentation in multiple places. I agree with her that it would be best to keep all the intro/tutorial material in one place. It would be great if the material that is in the Tutorial but not in Getting Started or Working With Derby (and that is still current) could be moved into the merged Getting Started.
        Hide
        Laura Stewart added a comment -

        file = cgsintro.html
        I merged some of the intro info into from the WWD into the GS Intro topic. Previously this topic only contained a short description. Also I changed the title of this topic to remove the gerund (which we only use for tasks).

        file = rgsdocs17307.html
        I changed the title of this topic so that it would not be confused with the library files that are discussed at the end of the GS guide. I added a lead in para before the definition list with a link to the product documentation. I added a description for the Getting Started with Derby guide (which was missing) and augmented the description for the API reference. Based on the outcome of the thread on derby-dev about linking to the javadoc, I will either change the link info to include both manuals and api or have a separate link.

        Show
        Laura Stewart added a comment - file = cgsintro.html I merged some of the intro info into from the WWD into the GS Intro topic. Previously this topic only contained a short description. Also I changed the title of this topic to remove the gerund (which we only use for tasks). file = rgsdocs17307.html I changed the title of this topic so that it would not be confused with the library files that are discussed at the end of the GS guide. I added a lead in para before the definition list with a link to the product documentation. I added a description for the Getting Started with Derby guide (which was missing) and augmented the description for the API reference. Based on the outcome of the thread on derby-dev about linking to the javadoc, I will either change the link info to include both manuals and api or have a separate link.
        Hide
        Kim Haase added a comment -

        Excellent start on this, Laura!

        cgsintro.html looks just fine. Good catch on the title issue.

        On rgsdocs17307.html – just a few things:

        I'm glad you caught the problem with the term "library. I don't think Derby is technically a product, which implies something that is sold; so maybe just "Derby documentation" would be a better title.

        The new description of the Getting Started guide might be split into two or more sentences – it's kind of a long list of topics. The Developer's Guide description might also be split into two sentences. The others are fine.

        "Javadoc," believe it or not, is actually a Sun trademarked term that applies to the tool used to generate API documentation. Derby doc isn't Sun doc, so it doesn't really have to obey the trademark requirements, and "javadoc" is in extremely common use as a noun. But it might be nice to use the term "API documentation" or "API reference" instead of "javadoc."

        Show
        Kim Haase added a comment - Excellent start on this, Laura! cgsintro.html looks just fine. Good catch on the title issue. On rgsdocs17307.html – just a few things: I'm glad you caught the problem with the term "library. I don't think Derby is technically a product, which implies something that is sold; so maybe just "Derby documentation" would be a better title. The new description of the Getting Started guide might be split into two or more sentences – it's kind of a long list of topics. The Developer's Guide description might also be split into two sentences. The others are fine. "Javadoc," believe it or not, is actually a Sun trademarked term that applies to the tool used to generate API documentation. Derby doc isn't Sun doc, so it doesn't really have to obey the trademark requirements, and "javadoc" is in extremely common use as a noun. But it might be nice to use the term "API documentation" or "API reference" instead of "javadoc."
        Hide
        Jean T. Anderson added a comment -

        Regarding this:
        >I'm glad you caught the problem with the term "library. I don't think Derby is technically a product, which implies something that is sold; so maybe just "Derby documentation" would be a better title.

        The ASF requires every project to include a NOTICE file with this text [1]:

        Apache [PRODUCT_NAME]
        Copyright [yyyy] The Apache Software Foundation

        This product includes software developed at
        The Apache Software Foundation (http://www.apache.org/).

        Using the word "product" is not a problem.

        [1] http://www.apache.org/legal/src-headers.html#notice

        Show
        Jean T. Anderson added a comment - Regarding this: >I'm glad you caught the problem with the term "library. I don't think Derby is technically a product, which implies something that is sold; so maybe just "Derby documentation" would be a better title. The ASF requires every project to include a NOTICE file with this text [1] : Apache [PRODUCT_NAME] Copyright [yyyy] The Apache Software Foundation This product includes software developed at The Apache Software Foundation ( http://www.apache.org/ ). Using the word "product" is not a problem. [1] http://www.apache.org/legal/src-headers.html#notice
        Hide
        Laura Stewart added a comment -

        Attached is an updated PDF of the Getting Started guide, which now includes the Acivities in the Working With Derby guide. The Acivities from WWD now form a "tutorial" for new users.

        Kim - if you want to see the dita source, I can zip it up and attach it as well.

        Because of this merger, many of the topics had to be updated in the sections prior to the Tutorial.
        What follows are some issues/questions and notes for you to keep in mind as you review the PDF.

        Issues/Questions:
        1. Pay particular attention to the environment variables discussion. If the user sets all of the variables, then what is needed in the Activities? Should the CLASSPATH environment variable be added to this section?
        2. The section on working with the tool scripts was originally designed to use the scripts to setup up the classpath (not really about running the tools). Because these topics weren't clear (to me) I restructured them. Now that we have the derbyrun.jar file, is this section still necessary for setting up the classpath? Should a new topic describing the derbyrun.jar file be added? The current section appears just after the environment variable section, and includes the manual way to set the CLASSPATH.
        3. Do we explain the CLASSPATH well enough? What is missing?
        4. Activities - Please check the steps very carefully. Because the environment variables (at least DERBY_HOME) should already be set up, I removed any reference to doing that task. I also removed the instructions to "change directory (cd) to the directory ..." that were in many of the activities because this should be a known command to the users... and it is shown explicitly in the first activity.
        5. Examples (system responses) - I updated the system responses in the Activities to reflect May instead of January. Should they also be updated to reflect 10.3 instead of 10.2.2? Do we need to specify a valid svn revision to use if we update the version, or is that overkill?
        6. I don't think that we do a good job of describing what the Network Server is. The term just shows up. Where should this be explained and how should it be described?
        7. Consistency re: embedded and client/server. In some places we say "embedded configuration" or "embedded mode" yet in both the "Quick start guide for experienced JDBC users" and the "Terminology" sections at the end of the Getting Started Guide, we use "embedded environment". There is the same problem with client/server.

        Notes:

        Other things that I changed:
        • In tables that show both UNIX and Windows commands, I moved UNIX before Windows. Several reasons for this. 1) I have the impression that most people are running Derby on UNIX. 2) UNIX comes before Windows alphabetically.
        • I broke up topics for several reasons. Mostly to help me, representing the novice user, to better understand the info. If I oversimplified the info, please let me know. Here are some of my reasons:
        o Simplify the content.
        o Organize the information more logically
        o Put task info into task topics (instead of concepts)
        • Many, but not all, choice tables were converted to simple tables. I did this for formatting reasons and as soon as I figure out how to change the formatting in the xsl files, I will change them back. But for the foreseeable future, the formatting is better with simple tables (which was a recommendation by Kim).

        I'd appreciate any comments that you have about this merger.

        Show
        Laura Stewart added a comment - Attached is an updated PDF of the Getting Started guide, which now includes the Acivities in the Working With Derby guide. The Acivities from WWD now form a "tutorial" for new users. Kim - if you want to see the dita source, I can zip it up and attach it as well. Because of this merger, many of the topics had to be updated in the sections prior to the Tutorial. What follows are some issues/questions and notes for you to keep in mind as you review the PDF. Issues/Questions: 1. Pay particular attention to the environment variables discussion. If the user sets all of the variables, then what is needed in the Activities? Should the CLASSPATH environment variable be added to this section? 2. The section on working with the tool scripts was originally designed to use the scripts to setup up the classpath (not really about running the tools). Because these topics weren't clear (to me) I restructured them. Now that we have the derbyrun.jar file, is this section still necessary for setting up the classpath? Should a new topic describing the derbyrun.jar file be added? The current section appears just after the environment variable section, and includes the manual way to set the CLASSPATH. 3. Do we explain the CLASSPATH well enough? What is missing? 4. Activities - Please check the steps very carefully. Because the environment variables (at least DERBY_HOME) should already be set up, I removed any reference to doing that task. I also removed the instructions to "change directory (cd) to the directory ..." that were in many of the activities because this should be a known command to the users... and it is shown explicitly in the first activity. 5. Examples (system responses) - I updated the system responses in the Activities to reflect May instead of January. Should they also be updated to reflect 10.3 instead of 10.2.2? Do we need to specify a valid svn revision to use if we update the version, or is that overkill? 6. I don't think that we do a good job of describing what the Network Server is. The term just shows up. Where should this be explained and how should it be described? 7. Consistency re: embedded and client/server. In some places we say "embedded configuration" or "embedded mode" yet in both the "Quick start guide for experienced JDBC users" and the "Terminology" sections at the end of the Getting Started Guide, we use "embedded environment". There is the same problem with client/server. Notes: Other things that I changed: • In tables that show both UNIX and Windows commands, I moved UNIX before Windows. Several reasons for this. 1) I have the impression that most people are running Derby on UNIX. 2) UNIX comes before Windows alphabetically. • I broke up topics for several reasons. Mostly to help me, representing the novice user, to better understand the info. If I oversimplified the info, please let me know. Here are some of my reasons: o Simplify the content. o Organize the information more logically o Put task info into task topics (instead of concepts) • Many, but not all, choice tables were converted to simple tables. I did this for formatting reasons and as soon as I figure out how to change the formatting in the xsl files, I will change them back. But for the foreseeable future, the formatting is better with simple tables (which was a recommendation by Kim). I'd appreciate any comments that you have about this merger.
        Hide
        Kim Haase added a comment -

        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:

        Show
        Kim Haase added a comment - 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:
        Hide
        Myrna van Lunteren added a comment -

        Laura, how is this issue progressing? There's input in a comment from Kim, and there was response on the list from Stan...

        Show
        Myrna van Lunteren added a comment - Laura, how is this issue progressing? There's input in a comment from Kim, and there was response on the list from Stan...
        Hide
        Laura Stewart added a comment -

        I am working through the comments. I expect the them all included and updated patches submitted by Monday, June 11.

        Show
        Laura Stewart added a comment - I am working through the comments. I expect the them all included and updated patches submitted by Monday, June 11.
        Hide
        John H. Embretsen added a comment - - edited

        While browsing the merged document (getstartderby.pdf) I noticed a couple of issues not directly related to this work, but that are present in each of the manuals that are part of this merger. I see a number of different ways to handle this, but I'm not sure which one is the best:

        a) Fix the issues as part of this JIRA-issue
        b) Create two new JIRA-issues, one for each of the current manuals ("Getting Started" and "Working with Derby")
        c) Wait until the two manuals have been merged and then create a new JIRA-issue for fixing the issues.

        I tend to think that option c) is the cleanest way to go, but let me know if anyone has other ideas.

        The issues are potentially factual errors in the manuals, but this may be subject to discussion. I do not consider it important to fix these issues by the time a release candidate for 10.3 is generated (we may not have enough time for that anyway). Issues are:

        1) Getting Started with Derby: Installing Derby: Confusing description of the bin-distribution, seems to say that jar files are not part of it.
        2) Working With Derby: Activity 3: The WwdEmbedded program:
        a) The "Shut down the database" shuts down the engine, not an individual database. It should make a point about the difference between these operations.
        b) The same section says that "The XJ015 error is the only exception thrown by Derby that indicates that an operation succeeded. All other exceptions indicate that an operation failed." What about '08006 - Database '<databaseName>' shutdown'?

        I found no issues with the merger itself that was not already commented by others - but I'll consider reading an updated version if I have enough cycles available when it is submitted.

        Show
        John H. Embretsen added a comment - - edited While browsing the merged document (getstartderby.pdf) I noticed a couple of issues not directly related to this work, but that are present in each of the manuals that are part of this merger. I see a number of different ways to handle this, but I'm not sure which one is the best: a) Fix the issues as part of this JIRA-issue b) Create two new JIRA-issues, one for each of the current manuals ("Getting Started" and "Working with Derby") c) Wait until the two manuals have been merged and then create a new JIRA-issue for fixing the issues. I tend to think that option c) is the cleanest way to go, but let me know if anyone has other ideas. The issues are potentially factual errors in the manuals, but this may be subject to discussion. I do not consider it important to fix these issues by the time a release candidate for 10.3 is generated (we may not have enough time for that anyway). Issues are: 1) Getting Started with Derby: Installing Derby: Confusing description of the bin-distribution, seems to say that jar files are not part of it. 2) Working With Derby: Activity 3: The WwdEmbedded program: a) The "Shut down the database" shuts down the engine, not an individual database. It should make a point about the difference between these operations. b) The same section says that "The XJ015 error is the only exception thrown by Derby that indicates that an operation succeeded. All other exceptions indicate that an operation failed." What about '08006 - Database '<databaseName>' shutdown'? I found no issues with the merger itself that was not already commented by others - but I'll consider reading an updated version if I have enough cycles available when it is submitted.
        Hide
        Laura Stewart added a comment -

        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.

        Show
        Laura Stewart added a comment - 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.
        Hide
        Laura Stewart added a comment -

        Comments made by Stan Bradbury on derby-dev 6/1/2007

        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.

        Show
        Laura Stewart added a comment - Comments made by Stan Bradbury on derby-dev 6/1/2007 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.
        Hide
        Laura Stewart added a comment -

        The comments from Stan and Kim were implemented.
        Committed revision 546665.

        If you have additional comments, please review the Alpha version of the Getting Started Guide tomorrow, when the
        guide is refreshed on the Web site:

        http://db.apache.org/derby/manuals/index.html

        Show
        Laura Stewart added a comment - The comments from Stan and Kim were implemented. Committed revision 546665. If you have additional comments, please review the Alpha version of the Getting Started Guide tomorrow, when the guide is refreshed on the Web site: http://db.apache.org/derby/manuals/index.html
        Hide
        Laura Stewart added a comment -

        Patch that contains the updated files based on comments from Kim and Stan.

        Show
        Laura Stewart added a comment - Patch that contains the updated files based on comments from Kim and Stan.
        Hide
        Laura Stewart added a comment -

        Hi John -

        Thanks for your comments. Although I have commited 1 patch for the comments from Kim and Stan, I anticipate more comments and intend to commit your comments later this week (before we post a release candidate for 10.3.

        Regarding the text in "Installing Derby" and reference to the JAR files.

        The current text is:

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

        This text leads me to believe that the optimized jar files (a different set of the Derby jar files) are only used for deployment. Is that correct or inaccurate? If inacurrate (meaning that the optimized jar files have several uses or are in several distributions), then we need
        more accurate descriptions of how the jar files are useful in each distribution.

        Show
        Laura Stewart added a comment - Hi John - Thanks for your comments. Although I have commited 1 patch for the comments from Kim and Stan, I anticipate more comments and intend to commit your comments later this week (before we post a release candidate for 10.3. Regarding the text in "Installing Derby" and reference to the JAR files. The current text is: 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. This text leads me to believe that the optimized jar files (a different set of the Derby jar files) are only used for deployment. Is that correct or inaccurate? If inacurrate (meaning that the optimized jar files have several uses or are in several distributions), then we need more accurate descriptions of how the jar files are useful in each distribution.
        Hide
        Laura Stewart added a comment -

        John - I believe that we have addressed your second issue (activity 4 shutting down the database).
        Please take a look at the Alpha version of the Getting Started Guide.

        Show
        Laura Stewart added a comment - John - I believe that we have addressed your second issue (activity 4 shutting down the database). Please take a look at the Alpha version of the Getting Started Guide.
        Hide
        Kim Haase added a comment -

        Congratulations, Laura – as I said, you've done a wonderful job with this.

        There are still a couple of little glitches:

        The file rgslib56653.dita is still part of the reltable in the ditamap, although it has been deleted. So there are some errors when I generate the output, though they don't actually prevent the output from being generated.

        The tables under Running sysinfo, Running ij, and Running dblook come out fine in both HTML versions: the first two columns are narrow and the third column is wide so the command lines fit. But in the PDF version, it is the middle column that is wide and the third column that is narrow, so the command lines run off the edge of the page. It seems that the relcolwidth attribute for sysinfo specifies a wide middle column, while the ones for the other two assume they are 2-column tables when they are actually 3-column tables.

        <simpletable relcolwidth="1* 2* 1*">
        <simpletable relcolwidth="1* 2*">

        I did some experimenting – I think if you change them to "1* 1* 2*" you will get better output.

        Hope this helps.

        Show
        Kim Haase added a comment - Congratulations, Laura – as I said, you've done a wonderful job with this. There are still a couple of little glitches: The file rgslib56653.dita is still part of the reltable in the ditamap, although it has been deleted. So there are some errors when I generate the output, though they don't actually prevent the output from being generated. The tables under Running sysinfo, Running ij, and Running dblook come out fine in both HTML versions: the first two columns are narrow and the third column is wide so the command lines fit. But in the PDF version, it is the middle column that is wide and the third column that is narrow, so the command lines run off the edge of the page. It seems that the relcolwidth attribute for sysinfo specifies a wide middle column, while the ones for the other two assume they are 2-column tables when they are actually 3-column tables. <simpletable relcolwidth="1* 2* 1*"> <simpletable relcolwidth="1* 2*"> I did some experimenting – I think if you change them to "1* 1* 2*" you will get better output. Hope this helps.
        Hide
        Laura Stewart added a comment -

        Hi Kim -

        Thanks I caught the problem with the spill over in the PDF and have already changed the relcolwidth as you recommeneded.
        I will remove file rgslib56653.dita from the reltable with my next updated/commit patch.

        Really appreciate all of your comments. I intend to submit the patch and commit tomorrow, so if you see anything else, please let me know!

        Show
        Laura Stewart added a comment - Hi Kim - Thanks I caught the problem with the spill over in the PDF and have already changed the relcolwidth as you recommeneded. I will remove file rgslib56653.dita from the reltable with my next updated/commit patch. Really appreciate all of your comments. I intend to submit the patch and commit tomorrow, so if you see anything else, please let me know!
        Hide
        John H. Embretsen added a comment -

        Laura, thanks for committing the new version of the getting started guide, great work

        Regarding the "Installing Derby" section and the description of the distributions/packages:

        I see now that this was added as part of DERBY-1223. It seems that the wording in the patch for that issue is slightly different from Andrew's original proposal - and different enough to change meaning:

        Original proposal: "The bin distribution contains scripts, demonstration programs, documentation and the optimized jars available in the lib distribution."
        Patch/committed wording: "The bin distribution contains scripts, demonstration programs, and documentation. The optimized jar files are available in the lib distribution. "

        The so-called optimized jars (i.e. the non-debug jars, without extra line number information) are part of both the lib and the bin distributions. The non-optimized (debug) jars are in the lib-debug distribution only. I've tried to make this more clear with the following wording for the bin distribution:

        "The bin distribution contains scripts, demonstration programs, documentation and the same set of jar files as the lib distribution."

        Would this work for everyone?

        Regarding my second issue, (Activity 3) shutting down the database, I cannot see that it has been addressed. I see the comments in Activity 4 about not shutting down the database from the client application, but my issue was regarding the application using the embedded driver, with a separate section with the title "Shut down the database" (under "The gsEmbedded program"), page number 29-30 in the pdf.

        The current manual says:

        "If an application starts the Derby engine, the application should shut down all databases before exiting. The attribute ;shutdown=true in the Derby connection URL performs the shutdown."

        Here I think it is important to include a sentence about the difference between shutting down the engine and a single database. This is described in the Developers guide (http://db.apache.org/derby/docs/dev/devguide/tdevdvlp40464.html), but I think saying something like this in the Getting started guide would be appropriate:

        "If an application starts the Derby engine, the application should shut it down before exiting. The attribute ;shutdown=true in the Derby connection URL performs the shutdown. When shutting down the Derby engine, all booted databases will automatically shut down. It is also possible to shut down individual databases without shutting down the engine, by including the database name in the connection URL."

        Alternatively we could possibly cut down on the text and rather refer to the Developers guide, but I think the sentences I added/modified above would be useful.

        Later, the manual says:

        "This section verifies that the embedded driver is being used, then issues the shutdown command and catches the shutdown exception to confirm that the database shut down cleanly."

        This is inaccurate, because the shutdown command shown in the example shuts down the Derby engine, not the individual database (although this happens as a side-effect). I suggest changing to:
        "This section verifies that the embedded driver is being used, then issues the shutdown command and catches the shutdown exception to confirm that the Derby engine shut down cleanly."

        After the code example, the manual says:

        "> Important: The XJ015 error is the only exception thrown by Derby that indicates that an operation succeeded. All other exceptions indicate that an operation failed."

        This is wrong, because if you shut down an individual database instead of the engine, you will get the 08006 - "Database '<databaseName>' shutdown" error message instead, i.e. another exception indicating that an operation succeeded. As far as I know there are no other exceptions indicating success, so perhaps something like this would suffice:

        "> Important: The XJ015 error (successful shutdown of the Derby engine) and the 08006 error (successful shutdown of a single database) are the only exceptions thrown by Derby that may indicate that an operation succeeded. All other exceptions indicate that an operation failed."

        I included "may indicate" because the 08006 error could also mean something else (see http://db.apache.org/derby/docs/dev/ref/rrefexcept71493.html), so the user would have to check the error message text to be sure (I think).

        Show
        John H. Embretsen added a comment - Laura, thanks for committing the new version of the getting started guide, great work Regarding the "Installing Derby" section and the description of the distributions/packages: I see now that this was added as part of DERBY-1223 . It seems that the wording in the patch for that issue is slightly different from Andrew's original proposal - and different enough to change meaning: Original proposal: "The bin distribution contains scripts, demonstration programs, documentation and the optimized jars available in the lib distribution." Patch/committed wording: "The bin distribution contains scripts, demonstration programs, and documentation. The optimized jar files are available in the lib distribution. " The so-called optimized jars (i.e. the non-debug jars, without extra line number information) are part of both the lib and the bin distributions. The non-optimized (debug) jars are in the lib-debug distribution only. I've tried to make this more clear with the following wording for the bin distribution: "The bin distribution contains scripts, demonstration programs, documentation and the same set of jar files as the lib distribution." Would this work for everyone? Regarding my second issue, (Activity 3) shutting down the database, I cannot see that it has been addressed. I see the comments in Activity 4 about not shutting down the database from the client application, but my issue was regarding the application using the embedded driver, with a separate section with the title "Shut down the database" (under "The gsEmbedded program"), page number 29-30 in the pdf. The current manual says: "If an application starts the Derby engine, the application should shut down all databases before exiting. The attribute ;shutdown=true in the Derby connection URL performs the shutdown." Here I think it is important to include a sentence about the difference between shutting down the engine and a single database. This is described in the Developers guide ( http://db.apache.org/derby/docs/dev/devguide/tdevdvlp40464.html ), but I think saying something like this in the Getting started guide would be appropriate: "If an application starts the Derby engine, the application should shut it down before exiting. The attribute ;shutdown=true in the Derby connection URL performs the shutdown. When shutting down the Derby engine, all booted databases will automatically shut down. It is also possible to shut down individual databases without shutting down the engine, by including the database name in the connection URL." Alternatively we could possibly cut down on the text and rather refer to the Developers guide, but I think the sentences I added/modified above would be useful. Later, the manual says: "This section verifies that the embedded driver is being used, then issues the shutdown command and catches the shutdown exception to confirm that the database shut down cleanly." This is inaccurate, because the shutdown command shown in the example shuts down the Derby engine, not the individual database (although this happens as a side-effect). I suggest changing to: "This section verifies that the embedded driver is being used, then issues the shutdown command and catches the shutdown exception to confirm that the Derby engine shut down cleanly." After the code example, the manual says: "> Important: The XJ015 error is the only exception thrown by Derby that indicates that an operation succeeded. All other exceptions indicate that an operation failed." This is wrong, because if you shut down an individual database instead of the engine, you will get the 08006 - "Database '<databaseName>' shutdown" error message instead, i.e. another exception indicating that an operation succeeded. As far as I know there are no other exceptions indicating success, so perhaps something like this would suffice: "> Important: The XJ015 error (successful shutdown of the Derby engine) and the 08006 error (successful shutdown of a single database) are the only exceptions thrown by Derby that may indicate that an operation succeeded. All other exceptions indicate that an operation failed." I included "may indicate" because the 08006 error could also mean something else (see http://db.apache.org/derby/docs/dev/ref/rrefexcept71493.html ), so the user would have to check the error message text to be sure (I think).
        Hide
        Laura Stewart added a comment -

        Thanks for your comments John. I wasn't able to get your last comments into the first patch, but I intend to commit another patch (or 2) today and will include them in those patches. I want to do that so we can all see the final version in the alpha docs tomorrow.

        I greatly appreciate the clarification about the bin and lib distributions. I see now where the meaning got changed. I would prefer to word it like this:

        "The bin distribution contains scripts, demonstration programs, documentation, and the optimized JAR files. These JAR files are the same set of JAR files that are in the lib distribution."

        Okay with you?

        Show
        Laura Stewart added a comment - Thanks for your comments John. I wasn't able to get your last comments into the first patch, but I intend to commit another patch (or 2) today and will include them in those patches. I want to do that so we can all see the final version in the alpha docs tomorrow. I greatly appreciate the clarification about the bin and lib distributions. I see now where the meaning got changed. I would prefer to word it like this: "The bin distribution contains scripts, demonstration programs, documentation, and the optimized JAR files. These JAR files are the same set of JAR files that are in the lib distribution." Okay with you?
        Hide
        John H. Embretsen added a comment -

        Laura: Absolutely, your suggested wording is okay with me. I just want to add that we might want to make the casing of the word "jar" consistent among at least the different distribution descriptions, so perhaps use "jar" (all lowercase) as it is currently?

        I haven't had time to go through the entire (new version of the) manual yet, but I'll let you know if I eventually find anything worth reporting.

        Show
        John H. Embretsen added a comment - Laura: Absolutely, your suggested wording is okay with me. I just want to add that we might want to make the casing of the word "jar" consistent among at least the different distribution descriptions, so perhaps use "jar" (all lowercase) as it is currently? I haven't had time to go through the entire (new version of the) manual yet, but I'll let you know if I eventually find anything worth reporting.
        Hide
        Stan Bradbury added a comment -

        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.

        Show
        Stan Bradbury added a comment - 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.
        Hide
        Laura Stewart added a comment -

        Attaching a patch (derby2390_2.diff) and an updated PDF file
        based on the latest comments from Kim, John, and Stan.

        Show
        Laura Stewart added a comment - Attaching a patch (derby2390_2.diff) and an updated PDF file based on the latest comments from Kim, John, and Stan.
        Hide
        Laura Stewart added a comment -

        Committed revision 547456.

        Show
        Laura Stewart added a comment - Committed revision 547456.
        Hide
        Laura Stewart added a comment -

        Found a minor problem and am attaching the updated
        patch derby2390_3.diff
        Committed revision 547457.

        Show
        Laura Stewart added a comment - Found a minor problem and am attaching the updated patch derby2390_3.diff Committed revision 547457.
        Hide
        Laura Stewart added a comment -

        Small change needed in the Tools Guide,
        Attached the updated patch derby2390_4.diff

        Committed revision 547462.

        Show
        Laura Stewart added a comment - Small change needed in the Tools Guide, Attached the updated patch derby2390_4.diff Committed revision 547462.
        Hide
        Laura Stewart added a comment -

        Need to remove the old Working with Derby guide files.

        Show
        Laura Stewart added a comment - Need to remove the old Working with Derby guide files.
        Hide
        Laura Stewart added a comment -

        Removed the files for the Working with derby guide, including the
        directory under src.

        Committed revision 547676.

        Show
        Laura Stewart added a comment - Removed the files for the Working with derby guide, including the directory under src. Committed revision 547676.

          People

          • Assignee:
            Laura Stewart
            Reporter:
            Laura Stewart
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development