Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.7.1.1
    • Component/s: Documentation
    • Labels:
      None
    • Urgency:
      Normal

      Description

      Providing a user guide documentation in http://db.apache.org/derby/docs/10.6/tools/

      1. ctoolsplanexp.html
        4 kB
        Kim Haase
      2. derby-4758-4.diff
        0.6 kB
        Kim Haase
      3. Derby-4758-3b.zip
        9 kB
        Nirmal Fernando
      4. derby-4758-3b.diff
        4 kB
        Nirmal Fernando
      5. derby-4758-3a.diff
        5 kB
        Kim Haase
      6. derby-4758-3.zip
        12 kB
        Kim Haase
      7. derby-4758.stat
        0.3 kB
        Kim Haase
      8. derby-4758-3.diff
        14 kB
        Kim Haase
      9. DERBY-4758-2.zip
        4 kB
        Nirmal Fernando
      10. derby4758-2.diff
        5 kB
        Nirmal Fernando
      11. derby4758.diff
        11 kB
        Nirmal Fernando
      12. DERBY-4758.zip
        13 kB
        Nirmal Fernando

        Issue Links

          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
          Kim Haase added a comment -

          Committed patch derby-4758-4.diff to documentation trunk at revision 1003560.

          Show
          Kim Haase added a comment - Committed patch derby-4758-4.diff to documentation trunk at revision 1003560.
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          Thanks for the patch. Looks good to me. I think this is sufficient to warn users that the behavior and api may change in future releases. +1

          Show
          Rick Hillegas added a comment - Hi Kim, Thanks for the patch. Looks good to me. I think this is sufficient to warn users that the behavior and api may change in future releases. +1
          Hide
          Kim Haase added a comment -

          A few minor edits (patch available, priority, version affected).

          Show
          Kim Haase added a comment - A few minor edits (patch available, priority, version affected).
          Hide
          Kim Haase added a comment -

          Attaching derby-4758-4.diff, which adds a note to the introductory topic on PlanExporter. Comments welcome.

          Show
          Kim Haase added a comment - Attaching derby-4758-4.diff, which adds a note to the introductory topic on PlanExporter. Comments welcome.
          Hide
          Rick Hillegas added a comment -

          We should add a disclaimer to the 10.7 docs, stating that the PlanExporter api and output are experimental and intended to elicit user feedback.

          Show
          Rick Hillegas added a comment - We should add a disclaimer to the 10.7 docs, stating that the PlanExporter api and output are experimental and intended to elicit user feedback.
          Hide
          Nirmal Fernando added a comment -

          Thanks Bryan!

          Show
          Nirmal Fernando added a comment - Thanks Bryan!
          Hide
          Bryan Pendleton added a comment -

          Patch 3b looks good and builds successfully for me. Committed to the
          Derby trunk as revision 985711.

          Show
          Bryan Pendleton added a comment - Patch 3b looks good and builds successfully for me. Committed to the Derby trunk as revision 985711.
          Hide
          Nirmal Fernando added a comment -

          Hi Kim,

          Thanks for all the formatting you have done to the initial documentation.
          Now, it's looking far nice!

          Last few days I've modified some of the features of PlanExporter tool, so
          I'm attaching patch 3b to address them.

          Show
          Nirmal Fernando added a comment - Hi Kim, Thanks for all the formatting you have done to the initial documentation. Now, it's looking far nice! Last few days I've modified some of the features of PlanExporter tool, so I'm attaching patch 3b to address them.
          Hide
          Kim Haase added a comment -

          Committed patches derby-4758-3.diff and derby-4758-3a.diff to documentation trunk at revision 984851.

          Show
          Kim Haase added a comment - Committed patches derby-4758-3.diff and derby-4758-3a.diff to documentation trunk at revision 984851.
          Hide
          Kim Haase added a comment -

          Realized that derby-4758-3.diff did not include the new file rtoolsplanexpxmlformat.dita. Attaching a supplementary patch that adds this file.

          I am committing these patches so that future documentation can build on them.

          Show
          Kim Haase added a comment - Realized that derby-4758-3.diff did not include the new file rtoolsplanexpxmlformat.dita. Attaching a supplementary patch that adds this file. I am committing these patches so that future documentation can build on them.
          Hide
          Rick Hillegas added a comment -

          Linking to DERBY-4768. After we add template style sheets and logic to build them into release distributions, we should enhance the documentation for PlanExporter to explain where the templates live in the distribution and how to customize them.

          Show
          Rick Hillegas added a comment - Linking to DERBY-4768 . After we add template style sheets and logic to build them into release distributions, we should enhance the documentation for PlanExporter to explain where the templates live in the distribution and how to customize them.
          Hide
          Kim Haase added a comment -

          Darn! A slip of the finger. Attaching the correct zip file. Thanks, Rick, for catching this. Now can I delete the wrong one? Will work on this.

          Show
          Kim Haase added a comment - Darn! A slip of the finger. Attaching the correct zip file. Thanks, Rick, for catching this. Now can I delete the wrong one? Will work on this.
          Hide
          Rick Hillegas added a comment -

          Thanks Nirmal and Kim for working on this documentation. I am starting to experiment with the tool. In doing so, I am first trying to wrap my head around the documentation.

          One thing that jumps out at me early on is this: in order to pilot this tool I need to have 3 user manuals open all at once:

          1) The Tools guide.

          2) The Reference guide, which the Tools guide points me at.

          3) The Tuning guide, which the Reference guides points me at.

          I think it would be a better user experience if I only had to consult one manual. For detailed operation, I can see the value in consulting multiple manuals, but I think that the first experience of this tool should be simple and straightforward. My gut feeling is that the Tuning guide is the right place to start. I think it would be very helpful if the Tuning guide's section titled "How you use the XPLAIN style" contained instructions and examples on how to use PlanExporter to study the output of your statistics run.

          Thanks,
          -Rick

          Show
          Rick Hillegas added a comment - Thanks Nirmal and Kim for working on this documentation. I am starting to experiment with the tool. In doing so, I am first trying to wrap my head around the documentation. One thing that jumps out at me early on is this: in order to pilot this tool I need to have 3 user manuals open all at once: 1) The Tools guide. 2) The Reference guide, which the Tools guide points me at. 3) The Tuning guide, which the Reference guides points me at. I think it would be a better user experience if I only had to consult one manual. For detailed operation, I can see the value in consulting multiple manuals, but I think that the first experience of this tool should be simple and straightforward. My gut feeling is that the Tuning guide is the right place to start. I think it would be very helpful if the Tuning guide's section titled "How you use the XPLAIN style" contained instructions and examples on how to use PlanExporter to study the output of your statistics run. Thanks, -Rick
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          Did you intend to attach a different zip file? The attached DERBY-4592-3.zip seems to hold doc pages for a different issue. Thanks.

          Show
          Rick Hillegas added a comment - Hi Kim, Did you intend to attach a different zip file? The attached DERBY-4592 -3.zip seems to hold doc pages for a different issue. Thanks.
          Hide
          Kim Haase added a comment -

          Attaching derby-4758-3.diff, derby-4758.stat, and derby-4758-3.zip, with changes to the following files:

          A src/tools/rtoolsplanexpxmlformat.dita
          M src/tools/ctoolsusingplanexp.dita
          M src/tools/derbytools.ditamap
          M src/tools/rtoolsplanexpexamples.dita
          M src/tools/ctoolspre23947.dita
          M src/tools/ctoolspre11181.dita
          M src/tools/ctoolsplanexp.dita

          src/tools/rtoolsplanexpxmlformat.dita is also added by patch derby-4758-2.diff – this patch would make it unnecessary to commit that one.

          The changes are mainly for formatting consistency and documentation style. I also added cross-references to the tool in a couple of introductory topics. I'm not sure whether it makes sense to refer to the tool in other manuals (reference or tuning, for example) or, if so, where; that can be left to a later patch if need be.

          Please let me know if these changes have introduced any inaccuracies and if other changes are needed.

          Show
          Kim Haase added a comment - Attaching derby-4758-3.diff, derby-4758.stat, and derby-4758-3.zip, with changes to the following files: A src/tools/rtoolsplanexpxmlformat.dita M src/tools/ctoolsusingplanexp.dita M src/tools/derbytools.ditamap M src/tools/rtoolsplanexpexamples.dita M src/tools/ctoolspre23947.dita M src/tools/ctoolspre11181.dita M src/tools/ctoolsplanexp.dita src/tools/rtoolsplanexpxmlformat.dita is also added by patch derby-4758-2.diff – this patch would make it unnecessary to commit that one. The changes are mainly for formatting consistency and documentation style. I also added cross-references to the tool in a couple of introductory topics. I'm not sure whether it makes sense to refer to the tool in other manuals (reference or tuning, for example) or, if so, where; that can be left to a later patch if need be. Please let me know if these changes have introduced any inaccuracies and if other changes are needed.
          Hide
          Kim Haase added a comment -

          Thanks so much for the helpful answers and quick response, Nirmal.

          There's no need for you to file an updated patch – I am including your information in a patch I'll be filing, which incorporates your second patch and modifies the contents.

          Show
          Kim Haase added a comment - Thanks so much for the helpful answers and quick response, Nirmal. There's no need for you to file an updated patch – I am including your information in a patch I'll be filing, which incorporates your second patch and modifies the contents.
          Hide
          Nirmal Fernando added a comment -

          Hi Kim,

          Ya, it's STMT_TEXT row of the SYSXPLAIN_STATEMENTS table.

          >visited_pages, from SYSXPLAIN_SCAN_PROPS – is this NO_VISITED_PAGES?
          >scanned_object, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_NAME?
          You got these two right.

          >scan_type, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_TYPE?
          It's SCAN_TYPE from SYSXPLAIN_SCAN_PROPS.

          >sorter_output, from SYSXPLAIN_SORT_PROPS
          It's NO_OUTPUT_ROWS of SYSXPLAIN_SORT_PROPS

          Sorry for not being clear.

          Thanks.

          Show
          Nirmal Fernando added a comment - Hi Kim, Ya, it's STMT_TEXT row of the SYSXPLAIN_STATEMENTS table. >visited_pages, from SYSXPLAIN_SCAN_PROPS – is this NO_VISITED_PAGES? >scanned_object, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_NAME? You got these two right. >scan_type, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_TYPE? It's SCAN_TYPE from SYSXPLAIN_SCAN_PROPS. >sorter_output, from SYSXPLAIN_SORT_PROPS It's NO_OUTPUT_ROWS of SYSXPLAIN_SORT_PROPS Sorry for not being clear. Thanks.
          Hide
          Kim Haase added a comment -

          A few questions on the PlanExporter XML Format topic:

          In some cases it's clear what row of a SYSXPLAIN table the topic is referring to, but in others it is not.

          "The statement element ... This element has only its value. That value implies the query executed as mentioned in SYSXPLAIN_STATEMENTS table."

          Is this the value from the STMT_TEXT row of the SYSXPLAIN_STATEMENTS table?

          The attributes of the node element sometimes have the same name as the corresponding row of the SYSXPLAIN table, but in some cases they don't, so I want to make sure I know the right one:

          visited_pages, from SYSXPLAIN_SCAN_PROPS – is this NO_VISITED_PAGES?

          scanned_object, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_NAME?

          scan_type, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_TYPE?

          sorter_output, from SYSXPLAIN_SORT_PROPS – I can't tell what row this might refer to at all.

          I'm thinking this bullet list should be a two-column table – I'll work on that.

          Show
          Kim Haase added a comment - A few questions on the PlanExporter XML Format topic: In some cases it's clear what row of a SYSXPLAIN table the topic is referring to, but in others it is not. "The statement element ... This element has only its value. That value implies the query executed as mentioned in SYSXPLAIN_STATEMENTS table." Is this the value from the STMT_TEXT row of the SYSXPLAIN_STATEMENTS table? The attributes of the node element sometimes have the same name as the corresponding row of the SYSXPLAIN table, but in some cases they don't, so I want to make sure I know the right one: visited_pages, from SYSXPLAIN_SCAN_PROPS – is this NO_VISITED_PAGES? scanned_object, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_NAME? scan_type, from SYSXPLAIN_SCAN_PROPS – is this SCAN_OBJECT_TYPE? sorter_output, from SYSXPLAIN_SORT_PROPS – I can't tell what row this might refer to at all. I'm thinking this bullet list should be a two-column table – I'll work on that.
          Hide
          Nirmal Fernando added a comment - - edited

          Hi Kim,

          Thanks for looking into this.

          >The syntax shows "[arguments]" in square brackets, which would normally indicate that the arguments are optional. However, I don't >see any indication of what the default behavior is if an argument is omitted. Does the tool automatically generate some form of output >with a default name, or do you in fact have to specify one or more of the >arguments described? If you do, there should be no >brackets around "arguments".
          >(Actually, the correct term here would be "options", not arguments, since they start with a hyphen.)

          You're absolutely correct! Tool need at least one option (-html or -xsl) in minimum. So brackets should be removed.

          >In the argument syntax, there's currently no description of what "path" must be. I gather you can specify an absolute or relative path, >rather than just a filename in the current directory as with the -adv -xsl option. But to judge from the example, it seems the tool >appends the ".xml" or ".html" suffix to the root filename you specify. Is that true?

          Actually path can be absolute or relative (Relative in the sense of the same directory but not sub directories). The tool appends ".xml" or ".html" suffix only if it is not present.

          If you think it's better, if I can submit a modified patch adding your suggestions, please let me know.

          Thanks.

          Show
          Nirmal Fernando added a comment - - edited Hi Kim, Thanks for looking into this. >The syntax shows " [arguments] " in square brackets, which would normally indicate that the arguments are optional. However, I don't >see any indication of what the default behavior is if an argument is omitted. Does the tool automatically generate some form of output >with a default name, or do you in fact have to specify one or more of the >arguments described? If you do, there should be no >brackets around "arguments". >(Actually, the correct term here would be "options", not arguments, since they start with a hyphen.) You're absolutely correct! Tool need at least one option (-html or -xsl) in minimum. So brackets should be removed. >In the argument syntax, there's currently no description of what "path" must be. I gather you can specify an absolute or relative path, >rather than just a filename in the current directory as with the -adv -xsl option. But to judge from the example, it seems the tool >appends the ".xml" or ".html" suffix to the root filename you specify. Is that true? Actually path can be absolute or relative (Relative in the sense of the same directory but not sub directories). The tool appends ".xml" or ".html" suffix only if it is not present. If you think it's better, if I can submit a modified patch adding your suggestions, please let me know. Thanks.
          Hide
          Kim Haase added a comment -

          Thanks for the additional documentation, Nirmal. I'll take a look at the formatting and style here too.

          I have a couple of questions about the Using PlanExporter topic.

          The syntax shows "[arguments]" in square brackets, which would normally indicate that the arguments are optional. However, I don't see any indication of what the default behavior is if an argument is omitted. Does the tool automatically generate some form of output with a default name, or do you in fact have to specify one or more of the arguments described? If you do, there should be no brackets around "arguments".

          (Actually, the correct term here would be "options", not arguments, since they start with a hyphen.)

          In the argument syntax, there's currently no description of what "path" must be. I gather you can specify an absolute or relative path, rather than just a filename in the current directory as with the -adv -xsl option. But to judge from the example, it seems the tool appends the ".xml" or ".html" suffix to the root filename you specify. Is that true?

          Thanks!

          Show
          Kim Haase added a comment - Thanks for the additional documentation, Nirmal. I'll take a look at the formatting and style here too. I have a couple of questions about the Using PlanExporter topic. The syntax shows " [arguments] " in square brackets, which would normally indicate that the arguments are optional. However, I don't see any indication of what the default behavior is if an argument is omitted. Does the tool automatically generate some form of output with a default name, or do you in fact have to specify one or more of the arguments described? If you do, there should be no brackets around "arguments". (Actually, the correct term here would be "options", not arguments, since they start with a hyphen.) In the argument syntax, there's currently no description of what "path" must be. I gather you can specify an absolute or relative path, rather than just a filename in the current directory as with the -adv -xsl option. But to judge from the example, it seems the tool appends the ".xml" or ".html" suffix to the root filename you specify. Is that true? Thanks!
          Hide
          Nirmal Fernando added a comment -

          Hi,

          I'm attaching a documentation patch that contains a page
          which describes the XML format outputted by the
          PlanExporter tool.

          Thanks.

          Show
          Nirmal Fernando added a comment - Hi, I'm attaching a documentation patch that contains a page which describes the XML format outputted by the PlanExporter tool. Thanks.
          Hide
          Nirmal Fernando added a comment -

          Thanks Kim, for look into the documentation.
          It's really nice to add new formatting features here.

          Show
          Nirmal Fernando added a comment - Thanks Kim, for look into the documentation. It's really nice to add new formatting features here.
          Hide
          Kim Haase added a comment -

          This is excellent documentation, Nirmal. It could use a few formatting and style tweaks, and should be linked to from some introductory topics. I'll file a suggested doc patch in the next day or two.

          Show
          Kim Haase added a comment - This is excellent documentation, Nirmal. It could use a few formatting and style tweaks, and should be linked to from some introductory topics. I'll file a suggested doc patch in the next day or two.
          Hide
          Nirmal Fernando added a comment -

          Hi Bryan,

          Thanks for reviewing it and committing it.

          Yeah, it would be nice to get a document on the XML format
          as well, I'll try to work on that in near future.

          Show
          Nirmal Fernando added a comment - Hi Bryan, Thanks for reviewing it and committing it. Yeah, it would be nice to get a document on the XML format as well, I'll try to work on that in near future.
          Hide
          Bryan Pendleton added a comment -

          Committed the documentation patch to the docs trunk as revision 982865.

          Show
          Bryan Pendleton added a comment - Committed the documentation patch to the docs trunk as revision 982865.
          Hide
          Bryan Pendleton added a comment -

          I think that the documentation that you have provided is very useful and
          I am intending to commit it, as it will be of great help to users who are
          learning how to use the PlanExporter tool.

          At some point, I think that we should document the XML format that is
          emitted by PlanExporter. But I think we can do that as a separate,
          subsequent change, some time in the future.

          Show
          Bryan Pendleton added a comment - I think that the documentation that you have provided is very useful and I am intending to commit it, as it will be of great help to users who are learning how to use the PlanExporter tool. At some point, I think that we should document the XML format that is emitted by PlanExporter. But I think we can do that as a separate, subsequent change, some time in the future.
          Hide
          Nirmal Fernando added a comment -

          Hi All,

          Attaching a documentation diff and html & dita files as a zipped folder.
          Highly appreciate your comments on this.

          Thanks.

          Show
          Nirmal Fernando added a comment - Hi All, Attaching a documentation diff and html & dita files as a zipped folder. Highly appreciate your comments on this. 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