Derby
  1. Derby
  2. DERBY-4618

"Syntax for the derbyrun.jar file" document page modification

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Trivial Trivial
    • Resolution: Fixed
    • Affects Version/s: 10.3.1.4, 10.3.2.1, 10.3.3.0, 10.4.1.3, 10.4.2.0, 10.5.1.1, 10.5.2.0, 10.5.3.0
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      In "Syntax for the derbyrun.jar file" (http://db.apache.org/derby/docs/10.5/getstart/rgsderbyrunjarsyntax.html) document page the use of -classpath or -cp when issuing java commands is not that explicitly explained.

      1. DERBY-4618_tools.diff
        2 kB
        Nirmal Fernando
      2. DERBY-4618_tools.zip
        5 kB
        Nirmal Fernando
      3. derby4618.diff
        2 kB
        Nirmal Fernando
      4. Derby-4618.zip
        4 kB
        Nirmal Fernando
      5. derby4618-2.diff
        2 kB
        Nirmal Fernando
      6. Derby-4618-2.zip
        4 kB
        Nirmal Fernando
      7. derby4618-3.diff
        2 kB
        Nirmal Fernando
      8. Derby-4618-3.zip
        4 kB
        Nirmal Fernando

        Activity

        Hide
        Kim Haase added a comment -

        Closing, since fixes appeared in docs some time ago.

        Show
        Kim Haase added a comment - Closing, since fixes appeared in docs some time ago.
        Hide
        Nirmal Fernando added a comment -

        Resolving this issue!

        Show
        Nirmal Fernando added a comment - Resolving this issue!
        Hide
        Nirmal Fernando added a comment -

        I'm closing this issue, as it fixed.

        Show
        Nirmal Fernando added a comment - I'm closing this issue, as it fixed.
        Hide
        Nirmal Fernando added a comment -

        Okey, Bryan. Thanks for committing it.

        Show
        Nirmal Fernando added a comment - Okey, Bryan. Thanks for committing it.
        Hide
        Bryan Pendleton added a comment -

        Thanks Nirmal for the patch to the Tools doc. It looks fine and builds
        fine for me. Committed to the docs trunk as revision 937630.

        Show
        Bryan Pendleton added a comment - Thanks Nirmal for the patch to the Tools doc. It looks fine and builds fine for me. Committed to the docs trunk as revision 937630.
        Hide
        Nirmal Fernando added a comment -

        Hi All,

        I have created a patch for the http://db.apache.org/derby/docs/10.5/tools/ttoolsij11815.html document page as Kim requested.

        Thanks.

        Show
        Nirmal Fernando added a comment - Hi All, I have created a patch for the http://db.apache.org/derby/docs/10.5/tools/ttoolsij11815.html document page as Kim requested. Thanks.
        Hide
        Nirmal Fernando added a comment -

        Thanks Bryan for committing the patch.

        Show
        Nirmal Fernando added a comment - Thanks Bryan for committing the patch.
        Hide
        Bryan Pendleton added a comment -

        Thanks Nirmal for the patch and thanks Kim and Knut Anders for the reviews
        and suggestions. Committed to the docs trunk as revision 937122.

        Show
        Bryan Pendleton added a comment - Thanks Nirmal for the patch and thanks Kim and Knut Anders for the reviews and suggestions. Committed to the docs trunk as revision 937122.
        Hide
        Kim Haase added a comment -

        Thanks for the fix, Nirmal – that was fast. The patch is good to go then, whenever Bryan can commit it. +1

        Show
        Kim Haase added a comment - Thanks for the fix, Nirmal – that was fast. The patch is good to go then, whenever Bryan can commit it. +1
        Hide
        Nirmal Fernando added a comment -

        Hi Kim,

        Thanks for mentioning it. I attached the modified diff and the zip, adding suffix '-3'.

        Show
        Nirmal Fernando added a comment - Hi Kim, Thanks for mentioning it. I attached the modified diff and the zip, adding suffix '-3'.
        Hide
        Kim Haase added a comment -

        The patch looks good, Nirmal. In the first sentence "using -jar argument" needs to be changed to "using the -jar argument" – perhaps Bryan can make that change before he commits the patch.

        Show
        Kim Haase added a comment - The patch looks good, Nirmal. In the first sentence "using -jar argument" needs to be changed to "using the -jar argument" – perhaps Bryan can make that change before he commits the patch.
        Hide
        Nirmal Fernando added a comment -

        Ok Bryan, thanks.

        And also I like to thank Knut Anders and Kim Haase for reviewing the patch and commenting on it.

        Show
        Nirmal Fernando added a comment - Ok Bryan, thanks. And also I like to thank Knut Anders and Kim Haase for reviewing the patch and commenting on it.
        Hide
        Bryan Pendleton added a comment -

        Thanks Nirmal for the patch. The new doc seems clear and useful to me,
        and should help people avoid a simple mistake with -cp and -jar.

        I intend to submit this patch to the docs trunk (once I get my build
        environment set up on my new machine).

        Show
        Bryan Pendleton added a comment - Thanks Nirmal for the patch. The new doc seems clear and useful to me, and should help people avoid a simple mistake with -cp and -jar. I intend to submit this patch to the docs trunk (once I get my build environment set up on my new machine).
        Hide
        Nirmal Fernando added a comment -

        Hi All,

        I have modified the earlier patch (to getstart) as Knut and Kim suggested. Attached new diff file and zip file named by adding a suffix '-2'.

        Thanks.

        Show
        Nirmal Fernando added a comment - Hi All, I have modified the earlier patch (to getstart) as Knut and Kim suggested. Attached new diff file and zip file named by adding a suffix '-2'. Thanks.
        Hide
        Kim Haase added a comment -

        The suggestion about an 80-character line length has nothing to do with DITA – it just has to do with the text editor you are using. Whatever you do to keep lines of Java code from being too long, you should do the same for DITA. But don't worry about it if you can't figure it out.

        Thanks, Knut, for the corrections on the wording.

        Show
        Kim Haase added a comment - The suggestion about an 80-character line length has nothing to do with DITA – it just has to do with the text editor you are using. Whatever you do to keep lines of Java code from being too long, you should do the same for DITA. But don't worry about it if you can't figure it out. Thanks, Knut, for the corrections on the wording.
        Hide
        Nirmal Fernando added a comment -

        Hi Kim & Knut,

        Thanks for reviewing the patch and suggest me the more appropriate wording.

        Kim, I can add the wording you suggested to Tools Guide topic (ttoolsij11815.dita), I will provide a patch soon. Actually I do not know how to set a 80 character line length in Dita (I did not see that functionality in http://db.apache.org/derby/manuals/guidelines.html#Understanding+DITA+tags ), if you can please help me on that. Thanks.

        Knut, I will create a patch by applying your wording. Thanks.

        Show
        Nirmal Fernando added a comment - Hi Kim & Knut, Thanks for reviewing the patch and suggest me the more appropriate wording. Kim, I can add the wording you suggested to Tools Guide topic (ttoolsij11815.dita), I will provide a patch soon. Actually I do not know how to set a 80 character line length in Dita (I did not see that functionality in http://db.apache.org/derby/manuals/guidelines.html#Understanding+DITA+tags ), if you can please help me on that. Thanks. Knut, I will create a patch by applying your wording. Thanks.
        Hide
        Knut Anders Hatlen added a comment -

        > "You cannot use the -cp argument to set the classpath when you use
        > the -jar argument to start the ij tool. Instead, you need to set the
        > CLASSPATH environment variable beforehand. (...)"

        I think the above paragraph is not entirely accurate. The CLASSPATH
        enviroment variable will also be ignored when you use the -jar
        argument to the java command, so I'd suggest this:

        "You cannot use the -cp argument or the CLASSPATH environment variable
        to set the classpath when you use the -jar argument to start the ij
        tool. If you want to run the ij tool with a custom classpath, you
        cannot use the -jar argument. Instead, you have to use the full class
        name to start the ij tool (java org.apache.derby.tools.ij).

        See Manually setting the CLASSPATH environment variable for more
        information about setting up the classpath and running the ij tool."

        > I notice that the syntax for sysinfo in the table actually shows the
        > -cp option, while the syntax for both ij and dblook as well as the
        > server argument does not.

        Here, the -cp argument is an argument to the sysinfo command, and it
        tells it to analyze the classpath. It is not an argument to the java
        command to set up the classpath. So I believe the syntax description
        is correct.

        Show
        Knut Anders Hatlen added a comment - > "You cannot use the -cp argument to set the classpath when you use > the -jar argument to start the ij tool. Instead, you need to set the > CLASSPATH environment variable beforehand. (...)" I think the above paragraph is not entirely accurate. The CLASSPATH enviroment variable will also be ignored when you use the -jar argument to the java command, so I'd suggest this: "You cannot use the -cp argument or the CLASSPATH environment variable to set the classpath when you use the -jar argument to start the ij tool. If you want to run the ij tool with a custom classpath, you cannot use the -jar argument. Instead, you have to use the full class name to start the ij tool (java org.apache.derby.tools.ij). See Manually setting the CLASSPATH environment variable for more information about setting up the classpath and running the ij tool." > I notice that the syntax for sysinfo in the table actually shows the > -cp option, while the syntax for both ij and dblook as well as the > server argument does not. Here, the -cp argument is an argument to the sysinfo command, and it tells it to analyze the classpath. It is not an argument to the java command to set up the classpath. So I believe the syntax description is correct.
        Hide
        Kim Haase added a comment -

        Thank you very much, Nirmal, for adding this helpful information (and for your skill using DITA). I am wondering, though, whether the very simple "Getting Started" manual is the best place for information on using a special classpath to bring in additional classes for running ij. This information might be more suited to the "Starting ij" topic of the Tools and Utilities Guide. In any case, I think it should be added to that topic too.

        I have some suggestions on rewording the text (English syntax, terminology, documentation conventions – nothing major).

        Suggested rewording if you keep it in Getting Started:

        "You cannot use the -cp argument to set the classpath when you use the -jar argument to start the ij tool. Instead, you need to set the CLASSPATH environment variable beforehand. See Choosing a method to run the Derby tools and startup utilities for more information on setting the CLASSPATH environment variable.

        There is no such limitation when you run the sysinfo tool. See Running sysinfo for more information on running the sysinfo tool."

        For this topic I have another question that may need an expert to answer it. I notice that the syntax for sysinfo in the table actually shows the -cp option, while the syntax for both ij and dblook as well as the server argument does not. Do you know whether -cp is also ignored when you run dblook or start the network server? There is probably less need for a special classpath with those, of course.

        Suggested rewording for adding it to the Tools Guide topic (ttoolsij11815.dita):

        If you need to use other classes in addition to derbyrun.jar, you cannot use the -cp argument to set the classpath when you use the -jar argument to start the ij tool. Instead, you need to set the CLASSPATH environment variable beforehand."

        Maybe the best place would be after the paragraph that begins "If you use the last form of the command ..."

        One further suggestion – when you add new material, it is helpful to use an 80-character line length rather than putting an entire paragraph on one line. It helps readability in different editors.

        Thanks very much for this contribution.

        Show
        Kim Haase added a comment - Thank you very much, Nirmal, for adding this helpful information (and for your skill using DITA). I am wondering, though, whether the very simple "Getting Started" manual is the best place for information on using a special classpath to bring in additional classes for running ij. This information might be more suited to the "Starting ij" topic of the Tools and Utilities Guide. In any case, I think it should be added to that topic too. I have some suggestions on rewording the text (English syntax, terminology, documentation conventions – nothing major). Suggested rewording if you keep it in Getting Started: "You cannot use the -cp argument to set the classpath when you use the -jar argument to start the ij tool. Instead, you need to set the CLASSPATH environment variable beforehand. See Choosing a method to run the Derby tools and startup utilities for more information on setting the CLASSPATH environment variable. There is no such limitation when you run the sysinfo tool. See Running sysinfo for more information on running the sysinfo tool." For this topic I have another question that may need an expert to answer it. I notice that the syntax for sysinfo in the table actually shows the -cp option, while the syntax for both ij and dblook as well as the server argument does not. Do you know whether -cp is also ignored when you run dblook or start the network server? There is probably less need for a special classpath with those, of course. Suggested rewording for adding it to the Tools Guide topic (ttoolsij11815.dita): If you need to use other classes in addition to derbyrun.jar, you cannot use the -cp argument to set the classpath when you use the -jar argument to start the ij tool. Instead, you need to set the CLASSPATH environment variable beforehand." Maybe the best place would be after the paragraph that begins "If you use the last form of the command ..." One further suggestion – when you add new material, it is helpful to use an 80-character line length rather than putting an entire paragraph on one line. It helps readability in different editors. Thanks very much for this contribution.
        Hide
        Nirmal Fernando added a comment -

        I have attached a document patch (derby4618.diff) and Derby-4618.zip which contains modified dita file and HTML page generated after testing.

        Appreciate your comments on this patch.

        Thanks.

        Show
        Nirmal Fernando added a comment - I have attached a document patch (derby4618.diff) and Derby-4618.zip which contains modified dita file and HTML page generated after testing. Appreciate your comments on this patch. Thanks.

          People

          • Assignee:
            Nirmal Fernando
            Reporter:
            Nirmal Fernando
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development