Derby
  1. Derby
  2. DERBY-1194

Clarify wording for ways to manage the Network Server in the Derby Server and Administration Guide

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.1.3.1
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None
    • Environment:
      DITA files

      Description

      In this manual is written:

      Managing the Derby Network Server

      The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application.

      It can also be managed remotely from a web server by using a servlet interface. You can manage the Network Server by using shell scripts, the command line, or the Network Server API. See Managing the Derby Network Server remotely by using the servlet interface for information about starting and shutting down the Network Server using the servlet interface.

      It seems to me that the sentences of this last paragraph are not in the correct order, and the first and second sentences should be swapped, becoming:

      You can manage the Network Server by using shell scripts, the command line, or the Network Server API. It can also be managed remotely from a web server by using a servlet interface. See Managing the Derby Network Server remotely by using the servlet interface for information about starting and shutting down the Network Server using the servlet interface.

      1. cadminconfig86869.diff
        1 kB
        Halley Pacheco de Oliveira
      2. cadminconfig86869.diff.html
        11 kB
        Halley Pacheco de Oliveira
      3. cadminconfig86869.html
        4 kB
        Halley Pacheco de Oliveira
      4. cadminconfig86869_a.diff
        1 kB
        Halley Pacheco de Oliveira
      5. cadminconfig86869_a.diff.html
        12 kB
        Halley Pacheco de Oliveira
      6. docs.diff
        2 kB
        Bryan Pendleton
      7. cadminconfig86869.html
        7 kB
        Bryan Pendleton

        Activity

        Hide
        Halley Pacheco de Oliveira added a comment -

        svn diff file and the HTMLized version

        Show
        Halley Pacheco de Oliveira added a comment - svn diff file and the HTMLized version
        Hide
        John H. Embretsen added a comment -

        I agree that the flow is much better when the two sentences are swapped.

        Also, I am not sure I completely understand what is meant by the first paragraph,
        "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application."

        Is it that the Derby "engine" is an embedded part of the Network Server application? Or is the purpose to say that is is possible to run the Network server either as a stand-alone server or as an embedded server in the user's Java application?
        If the latter case is true, I think the sentence should be rephrased to something like this:
        "The Derby Network Server can run as a stand-alone server, or as an embedded part of a Java application."

        What do others think?

        Halley, in the future, it would be nice (easier for for reviewers) if you attached the html output generated by the DITA toolkit, as explained here:
        http://db.apache.org/derby/manuals/dita.html#Creating+output

        In this particular case, you would find the generated html file in this location in your docs repository:
        out/adminguide/cadminconfig86869.html

        Show
        John H. Embretsen added a comment - I agree that the flow is much better when the two sentences are swapped. Also, I am not sure I completely understand what is meant by the first paragraph, "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application." Is it that the Derby "engine" is an embedded part of the Network Server application? Or is the purpose to say that is is possible to run the Network server either as a stand-alone server or as an embedded server in the user's Java application? If the latter case is true, I think the sentence should be rephrased to something like this: "The Derby Network Server can run as a stand-alone server, or as an embedded part of a Java application." What do others think? Halley, in the future, it would be nice (easier for for reviewers) if you attached the html output generated by the DITA toolkit, as explained here: http://db.apache.org/derby/manuals/dita.html#Creating+output In this particular case, you would find the generated html file in this location in your docs repository: out/adminguide/cadminconfig86869.html
        Hide
        Halley Pacheco de Oliveira added a comment -

        About John H. Embretsen's comment:

        In my opinion, in the sentence "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application." the word "application" stands for "Derby Network Server", and the sentence could be:

        "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the Derby Network Server."

        or

        "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of it."

        My opinion is based on this part of the manual:

        The Derby Network Server

        The Network Server is a solution for multiple JVMs that connect to the database, unlike the embedded scenario where only one JVM runs as part of the system. When Derby is embedded in a single-JVM application, the embedded JDBC driver calls the local Derby database. When Derby is embedded in a server framework, the server framework's connectivity software provides data to multiple client JDBC applications over a network or the Internet.

        PS: I will attach the HTML output along with the new correction. Thank you for the tip.

        Show
        Halley Pacheco de Oliveira added a comment - About John H. Embretsen's comment: In my opinion, in the sentence "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application." the word "application" stands for "Derby Network Server", and the sentence could be: "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the Derby Network Server." or "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of it." My opinion is based on this part of the manual: The Derby Network Server The Network Server is a solution for multiple JVMs that connect to the database, unlike the embedded scenario where only one JVM runs as part of the system. When Derby is embedded in a single-JVM application, the embedded JDBC driver calls the local Derby database. When Derby is embedded in a server framework, the server framework's connectivity software provides data to multiple client JDBC applications over a network or the Internet. PS: I will attach the HTML output along with the new correction. Thank you for the tip.
        Hide
        Halley Pacheco de Oliveira added a comment -

        New manual page file, diff file, and HTMLized diff file.

        Show
        Halley Pacheco de Oliveira added a comment - New manual page file, diff file, and HTMLized diff file.
        Hide
        Jean T. Anderson added a comment -

        regarding this paragraph:
        "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application."

        Actually, the Network Server can either run stand-alone, as depicted in Figure 2 at http://db.apache.org/derby/papers/DerbyTut/ns_intro.html#Embedded+Server, or it can run as an embedded server, as depicted in Figure 3 at http://db.apache.org/derby/papers/DerbyTut/ns_intro.html#Embedded+Server .

        Here's another suggestion that bounces off of Halley's, but it isn't quite there yet because it's JVM-centric:

        "The Derby Network Server can run stand-alone, in its own JVM, with Derby embedded in it. Or it can run in another application's JVM, and it's the Java application that loads both Derby and the Network Server."

        more suggestions?

        Show
        Jean T. Anderson added a comment - regarding this paragraph: "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application." Actually, the Network Server can either run stand-alone, as depicted in Figure 2 at http://db.apache.org/derby/papers/DerbyTut/ns_intro.html#Embedded+Server , or it can run as an embedded server, as depicted in Figure 3 at http://db.apache.org/derby/papers/DerbyTut/ns_intro.html#Embedded+Server . Here's another suggestion that bounces off of Halley's, but it isn't quite there yet because it's JVM-centric: "The Derby Network Server can run stand-alone, in its own JVM, with Derby embedded in it. Or it can run in another application's JVM, and it's the Java application that loads both Derby and the Network Server." more suggestions?
        Hide
        John H. Embretsen added a comment -

        Here is another suggestion which captures both interpretations of the sentence "The Derby Network Server can run as a stand-alone server,
        with Derby as an embedded part of the application.":

        "The Derby Network Server can either run stand-alone, that is as an independent Java process embedding the Derby database engine, or embedded within another Java application. In the latter ("embedded server") setting both the Network Server framework and Derby are loaded by the Java application."

        I still think it can be improved, but to me this seems clearer than the other suggestions seen so far.

        Show
        John H. Embretsen added a comment - Here is another suggestion which captures both interpretations of the sentence "The Derby Network Server can run as a stand-alone server, with Derby as an embedded part of the application.": "The Derby Network Server can either run stand-alone, that is as an independent Java process embedding the Derby database engine, or embedded within another Java application. In the latter ("embedded server") setting both the Network Server framework and Derby are loaded by the Java application." I still think it can be improved, but to me this seems clearer than the other suggestions seen so far.
        Hide
        Kathey Marsden added a comment -

        Halley, are you actively working on this issue? Do you still need more reviews of the patch after John's review? If not can we uncheck "Patch Available"? I have not looked at the patch itsself but have a comment on the Jira Summary for this issue. Since the Jira Summary is what prints in the release notes and is the primary search mechnism used by users to search for issues, it is good to have something quite specific so that users don't have to drill down into the description to find out what is fixed by the issue.

        For this issue, something like:

        "Clarify wording for ways to manage the Network Server in the Derby Server and Administration Guide"

        would be a more clear description of what is being fixed.

        Show
        Kathey Marsden added a comment - Halley, are you actively working on this issue? Do you still need more reviews of the patch after John's review? If not can we uncheck "Patch Available"? I have not looked at the patch itsself but have a comment on the Jira Summary for this issue. Since the Jira Summary is what prints in the release notes and is the primary search mechnism used by users to search for issues, it is good to have something quite specific so that users don't have to drill down into the description to find out what is fixed by the issue. For this issue, something like: "Clarify wording for ways to manage the Network Server in the Derby Server and Administration Guide" would be a more clear description of what is being fixed.
        Hide
        Rick Hillegas added a comment -

        Moving to 10.2.2.0.

        Show
        Rick Hillegas added a comment - Moving to 10.2.2.0.
        Hide
        Mike Matrigali added a comment -

        From the comments, and no response to kathy's query months back it looks like this "patch" is not really ready.

        Show
        Mike Matrigali added a comment - From the comments, and no response to kathy's query months back it looks like this "patch" is not really ready.
        Hide
        Rick Hillegas added a comment -

        Move to 10.2.3.0.

        Show
        Rick Hillegas added a comment - Move to 10.2.3.0.
        Hide
        Andrew McIntyre added a comment -

        Unsetting Fix Version for unassigned issues.

        Show
        Andrew McIntyre added a comment - Unsetting Fix Version for unassigned issues.
        Hide
        Bryan Pendleton added a comment -

        There are a lot of good suggestions in the attached patches, and in the various comments.

        I will see if I can incorporate these into the current documentation page.

        Show
        Bryan Pendleton added a comment - There are a lot of good suggestions in the attached patches, and in the various comments. I will see if I can incorporate these into the current documentation page.
        Hide
        Bryan Pendleton added a comment -

        Attached is an updated patch proposal, and an updated HTML version of the man page.

        I think I included all the comments from this issue. Any suggestions or feedback
        are quite appreciated!

        Show
        Bryan Pendleton added a comment - Attached is an updated patch proposal, and an updated HTML version of the man page. I think I included all the comments from this issue. Any suggestions or feedback are quite appreciated!
        Hide
        Kim Haase added a comment -

        I think you've done a great job disentangling all the various suggestions, Bryan. I think I looked at them a long time ago and couldn't think what to do.

        Also, pointing to those figures in the tutorial works really well.

        You don't really need the "Or" in the bullet list, and you don't need punctuation at the end – it can just be

        o As .... engine
        o As .... application

        Show
        Kim Haase added a comment - I think you've done a great job disentangling all the various suggestions, Bryan. I think I looked at them a long time ago and couldn't think what to do. Also, pointing to those figures in the tutorial works really well. You don't really need the "Or" in the bullet list, and you don't need punctuation at the end – it can just be o As .... engine o As .... application
        Hide
        Bryan Pendleton added a comment -

        Thanks Jean and John for the wording suggestions, and thanks Kim for the review!

        I updated the bullet points and committed this change to the docs trunk as revision 882792.

        Show
        Bryan Pendleton added a comment - Thanks Jean and John for the wording suggestions, and thanks Kim for the review! I updated the bullet points and committed this change to the docs trunk as revision 882792.

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            Halley Pacheco de Oliveira
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development