Derby
  1. Derby
  2. DERBY-1920

DOCS - Improve topic titles for vague and duplicate topics

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.2.1.6
    • Fix Version/s: 10.2.2.1, 10.3.1.4
    • Component/s: Documentation
    • Labels:
      None

      Description

      1) Many of the topic titles are vague.
      Examples -
      a) Almost all of the titles for the built-in function topics do not indicate that the topic is about a "function".
      The word "function" should be added to all of the reference topics (In the Reference Manual) that discuss the built in functions
      b) Almost all of the titles for the data type topics do not indicate that the topic is about a data type.
      The words "data type" should be added to all of the reference topics (In the Reference Manual) that discuss the data types
      c) Some of the SQL statement topic titles do not include the word "statement" in the title and they should.

      2)Some of the topics use the same title, but discuss very different things. Each topic title in the Derby documentation should be
      unique.
      Examples -
      LOCK TABLE statement in the Reference Manual (http://db.apache.org/derby/docs/dev/ref/rrefsqlj40506.html)
      and in the Tuning Guide (http://db.apache.org/derby/docs/dev/tuning/ctunoptimz11775.html)

      This is just one of several examples.

      1. DERBY-1920-tuning.zip
        2 kB
        Kim Haase
      2. DERBY-1920-tuning.diff
        1 kB
        Kim Haase
      3. DERBY-1920-tools-2.zip
        116 kB
        Kim Haase
      4. DERBY-1920-tools-2.diff
        44 kB
        Kim Haase
      5. DERBY-1920-tools.zip
        116 kB
        Kim Haase
      6. DERBY-1920-tools.diff
        44 kB
        Kim Haase
      7. DERBY-1920-ref9.zip
        18 kB
        Kim Haase
      8. DERBY-1920-ref9.diff
        22 kB
        Kim Haase
      9. DERBY-1920-ref8.zip
        9 kB
        Kim Haase
      10. DERBY-1920-ref8.diff
        46 kB
        Kim Haase
      11. DERBY-1920-ref7.zip
        32 kB
        Kim Haase
      12. DERBY-1920-ref7.diff
        30 kB
        Kim Haase
      13. DERBY-1920-ref6.zip
        84 kB
        Kim Haase
      14. DERBY-1920-ref6.diff
        29 kB
        Kim Haase
      15. DERBY-1920-ref5.zip
        79 kB
        Kim Haase
      16. DERBY-1920-ref5.diff
        30 kB
        Kim Haase
      17. DERBY-1920-ref4.zip
        42 kB
        Kim Haase
      18. DERBY-1920-ref4.diff
        12 kB
        Kim Haase
      19. DERBY-1920-ref3.zip
        45 kB
        Kim Haase
      20. DERBY-1920-ref3.diff
        10 kB
        Kim Haase
      21. DERBY-1920-ref2.zip
        46 kB
        Kim Haase
      22. DERBY-1920-ref2.diff
        10 kB
        Kim Haase
      23. DERBY-1920-ref1.zip
        17 kB
        Kim Haase
      24. DERBY-1920-ref1.diff
        5 kB
        Kim Haase
      25. DERBY-1920-devguide.zip
        15 kB
        Kim Haase
      26. DERBY-1920-devguide.diff
        11 kB
        Kim Haase
      27. DERBY-1920-adminguide.zip
        23 kB
        Kim Haase
      28. DERBY-1920-adminguide.diff
        11 kB
        Kim Haase
      29. DERBY-1920.list-3.txt
        20 kB
        Kim Haase
      30. DERBY-1920.list-2.txt
        15 kB
        Kim Haase
      31. DERBY-1920.list
        14 kB
        Kim Haase
      32. DERBY-1920_list_ls.htm
        16 kB
        Laura Stewart

        Activity

        Hide
        Rick Hillegas added a comment -

        Reassign to 10.2.3.0.

        Show
        Rick Hillegas added a comment - Reassign to 10.2.3.0.
        Hide
        Kim Haase added a comment -

        I've attached a list of the files that I think would be affected by this fix – it's pretty big, especially for the Reference Manual. The order is the order in which the various files appear in the TOCs of the HTML Pages versions of the manuals. I've included a few questions and comments here and there; if any of the proposed answers seem wrong, please let me know.

        Show
        Kim Haase added a comment - I've attached a list of the files that I think would be affected by this fix – it's pretty big, especially for the Reference Manual. The order is the order in which the various files appear in the TOCs of the HTML Pages versions of the manuals. I've included a few questions and comments here and there; if any of the proposed answers seem wrong, please let me know.
        Hide
        Laura Stewart added a comment -

        This is one of those tasks that is probably going to come up again. I did not look at all of the guides when I created this issue,
        just the ones that I was working closely with at the time. But we can reopen the issue (or create a new one) as we see other problems
        with topic titles.

        Thanks for looking at this and putting together the list. I made comments directly in the list and have attached my own version of the list.
        There are only a few that I don't know what to do with - the "Path" capitalization and the angle brackets.

        Show
        Laura Stewart added a comment - This is one of those tasks that is probably going to come up again. I did not look at all of the guides when I created this issue, just the ones that I was working closely with at the time. But we can reopen the issue (or create a new one) as we see other problems with topic titles. Thanks for looking at this and putting together the list. I made comments directly in the list and have attached my own version of the list. There are only a few that I don't know what to do with - the "Path" capitalization and the angle brackets.
        Hide
        Kim Haase added a comment -

        Thanks very much, Laura. Some comments on your comments:

        About the two topics in the Developer's Guide (currently called "ALTER TABLE" and "BLOB and "CLOB"): this is an interesting problem. These are currently subsections under the heading "Derby and standards" and describe areas in which Derby follows or varies from a standard.

        Derby and standards

        • ALTER TABLE
        • Calling functions and procedures
        • CLOB and BLOB
        • Cursors
        • DECIMAL max precision
        • Dynamic SQL
        • Expressions on LONGs
        • Information schema
        • NOT NULL characteristic
        • Transactions
        • Stored routines and PSM
        • Unique constraints and nulls
        • XML data types and operators

        Most of them are just one or two sentences long, and in fact the text of most of them appears in the "Derby and standards" topic itself because of how DITA manuals are processed. We could argue that the individual topics should be removed and the texts instead be included in the "Derby and standards" topic. (The last one, "XML data types and operators," is too long for that.) What do you think?

        You ask "IS THERE A DIFFERENCE BETWEEN SYSTEM FUNCTION AND SYSTEM PROCEDURE???" Yes, you use a VALUES expression to call a function, but you use the CALL statement to call a procedure. The functions and procedures are under different section topics.

        About "ref/rrefsqlj1080962.dita" – the example is just two short lines long – not extensive at all. So I think it is best to merge it with the "Expression precedence" topic, which is not very long.

        Since you are equally mystified about the inconsistent syntax in the connection attribute titles, it seems likely that the inconsistencies are unintentional, and we can just go ahead and make the titles consistent with the majority of the topics. Unless someone can explain the inconsistencies, that is.

        Show
        Kim Haase added a comment - Thanks very much, Laura. Some comments on your comments: About the two topics in the Developer's Guide (currently called "ALTER TABLE" and "BLOB and "CLOB"): this is an interesting problem. These are currently subsections under the heading "Derby and standards" and describe areas in which Derby follows or varies from a standard. Derby and standards ALTER TABLE Calling functions and procedures CLOB and BLOB Cursors DECIMAL max precision Dynamic SQL Expressions on LONGs Information schema NOT NULL characteristic Transactions Stored routines and PSM Unique constraints and nulls XML data types and operators Most of them are just one or two sentences long, and in fact the text of most of them appears in the "Derby and standards" topic itself because of how DITA manuals are processed. We could argue that the individual topics should be removed and the texts instead be included in the "Derby and standards" topic. (The last one, "XML data types and operators," is too long for that.) What do you think? You ask "IS THERE A DIFFERENCE BETWEEN SYSTEM FUNCTION AND SYSTEM PROCEDURE???" Yes, you use a VALUES expression to call a function, but you use the CALL statement to call a procedure. The functions and procedures are under different section topics. About "ref/rrefsqlj1080962.dita" – the example is just two short lines long – not extensive at all. So I think it is best to merge it with the "Expression precedence" topic, which is not very long. Since you are equally mystified about the inconsistent syntax in the connection attribute titles, it seems likely that the inconsistencies are unintentional, and we can just go ahead and make the titles consistent with the majority of the topics. Unless someone can explain the inconsistencies, that is.
        Hide
        Kim Haase added a comment -

        I've added a revised list that incorporates your comments, Laura (to the extent we resolved the issues, I think) and also reflects the reordering that you did for DERBY-2013. I made headers for the different sections of the Reference Manual to make the list easier to navigate. I'll get started on this now. More comments and suggestions are welcome!

        Show
        Kim Haase added a comment - I've added a revised list that incorporates your comments, Laura (to the extent we resolved the issues, I think) and also reflects the reordering that you did for DERBY-2013 . I made headers for the different sections of the Reference Manual to make the list easier to navigate. I'll get started on this now. More comments and suggestions are welcome!
        Hide
        Christian d'Heureuse added a comment -

        Some HTML manual pages have meaningful file names, e.g.:
        http://db.apache.org/derby/docs/dev/ref/rrefcreatefunctionstatement.html
        = "CREATE FUNCTION statement"

        Other pages have generated file names, e.g.:
        http://db.apache.org/derby/docs/dev/ref/rrefsqlj20937.html
        = "CREATE INDEX statement"

        Would it be possible to give all the HTML pages meaningful file names, so that links to those pages are permanent? Or are the generated file names (e.g. 20937.html) also permanent?

        Show
        Christian d'Heureuse added a comment - Some HTML manual pages have meaningful file names, e.g.: http://db.apache.org/derby/docs/dev/ref/rrefcreatefunctionstatement.html = "CREATE FUNCTION statement" Other pages have generated file names, e.g.: http://db.apache.org/derby/docs/dev/ref/rrefsqlj20937.html = "CREATE INDEX statement" Would it be possible to give all the HTML pages meaningful file names, so that links to those pages are permanent? Or are the generated file names (e.g. 20937.html) also permanent?
        Hide
        Jean T. Anderson added a comment -

        One warning about changing file names: we might end up with broken links on the apache web site because of url's that get bookmarked, posted to the mail lists, etc.

        Show
        Jean T. Anderson added a comment - One warning about changing file names: we might end up with broken links on the apache web site because of url's that get bookmarked, posted to the mail lists, etc.
        Hide
        Christian d'Heureuse added a comment -

        If the non-meaningfil file names (e.g. 20937.html) are dynamically generated, those external links are already broken or will be broken over time. Thats just what I would like to prevent.

        Show
        Christian d'Heureuse added a comment - If the non-meaningfil file names (e.g. 20937.html) are dynamically generated, those external links are already broken or will be broken over time. Thats just what I would like to prevent.
        Hide
        Andrew McIntyre added a comment -

        The nonmeaningful filenames were generated in a one-time conversion to DITA. They do not change from build to build.

        Show
        Andrew McIntyre added a comment - The nonmeaningful filenames were generated in a one-time conversion to DITA. They do not change from build to build.
        Hide
        Laura Stewart added a comment -

        The links are not broken with the nonmeaningful names. The file names are permanent. It would be a tremendous amount of work to
        change the names for all of the files. As new topics are added, we are using meaningful names to make the topics easier to find.

        I added info to the Derby Doc Web pages about how to locate the filename for a topic, which might be helpful.
        http://db.apache.org/derby/manuals/dita.html#Locating+the+correct+DITA+file

        Show
        Laura Stewart added a comment - The links are not broken with the nonmeaningful names. The file names are permanent. It would be a tremendous amount of work to change the names for all of the files. As new topics are added, we are using meaningful names to make the topics easier to find. I added info to the Derby Doc Web pages about how to locate the filename for a topic, which might be helpful. http://db.apache.org/derby/manuals/dita.html#Locating+the+correct+DITA+file
        Hide
        Kim Haase added a comment -

        I found another file that needs a title change. (This will get lost if I just add it to a revised list.) It's ref/rrefjdbc32593.dita, "JDBC 3.0-only features". The problem is that these features actually apply to 3.0 and later releases (i.e. to 4.0 also).

        Similarly, adding a file named "JDBC 2.0-only features" won't do. So instead I'm changing ref/rrefjdbc32593.dita to "JDBC 3.0 features", and the new one for 2.0 is called "JDBC 2.0 features".

        The title for the 4.0 summary can stay "JDBC 4.0-only features" because that's currently true – but we'll need to change it if/when JDBC 5.0 comes along.

        Please let me know if you can think of a better solution. Would "Features new at JDBC x.0" or "Features added at JDBC x.0" be better?

        Show
        Kim Haase added a comment - I found another file that needs a title change. (This will get lost if I just add it to a revised list.) It's ref/rrefjdbc32593.dita, "JDBC 3.0-only features". The problem is that these features actually apply to 3.0 and later releases (i.e. to 4.0 also). Similarly, adding a file named "JDBC 2.0-only features" won't do. So instead I'm changing ref/rrefjdbc32593.dita to "JDBC 3.0 features", and the new one for 2.0 is called "JDBC 2.0 features". The title for the 4.0 summary can stay "JDBC 4.0-only features" because that's currently true – but we'll need to change it if/when JDBC 5.0 comes along. Please let me know if you can think of a better solution. Would "Features new at JDBC x.0" or "Features added at JDBC x.0" be better?
        Hide
        Kim Haase added a comment -

        I found some more titles that need changing, in the Tools guide, so I've updated the list (see DERBY-1920.list-3.txt). I'm wondering if it might make sense to provide several patch files for this (maybe one per book?) rather than one huge patch, since this bug involves changes to a large number of files. Would this make sense? Thanks for any suggestions.

        Show
        Kim Haase added a comment - I found some more titles that need changing, in the Tools guide, so I've updated the list (see DERBY-1920 .list-3.txt). I'm wondering if it might make sense to provide several patch files for this (maybe one per book?) rather than one huge patch, since this bug involves changes to a large number of files. Would this make sense? Thanks for any suggestions.
        Hide
        Kim Haase added a comment -

        Attaching the first and simplest incremental patch, for the tuning guide: DERBY-1920-tuning.diff and DERBY-1920-tuning.zip. This involves a change to only one topic file (and the map file). The topic title "LOCK TABLE statement" was identical to a topic title in the Reference Manual.

        Show
        Kim Haase added a comment - Attaching the first and simplest incremental patch, for the tuning guide: DERBY-1920 -tuning.diff and DERBY-1920 -tuning.zip. This involves a change to only one topic file (and the map file). The topic title "LOCK TABLE statement" was identical to a topic title in the Reference Manual.
        Hide
        Kim Haase added a comment -

        Partial patch; more to come.

        Show
        Kim Haase added a comment - Partial patch; more to come.
        Hide
        Kim Haase added a comment -

        This is another simple patch, involving only a few files in the Developer's Guide. In the "Derby and Standards" section I changed "ALTER TABLE" to "ALTER TABLE syntax", and "BLOB and CLOB" to "BLOB and CLOB data types". Also changed all occurrences of the titles in the map file (including the reltable). The other changes involve correcting cross-references to Reference Manual topics whose titles will change in an upcoming patch.

        Show
        Kim Haase added a comment - This is another simple patch, involving only a few files in the Developer's Guide. In the "Derby and Standards" section I changed "ALTER TABLE" to "ALTER TABLE syntax", and "BLOB and CLOB" to "BLOB and CLOB data types". Also changed all occurrences of the titles in the map file (including the reltable). The other changes involve correcting cross-references to Reference Manual topics whose titles will change in an upcoming patch.
        Hide
        Laura Stewart added a comment -

        Hi Kim -
        For the Tuning Guide change. Can we shorten this title?
        Instead of "Locking a table for the duration of a transaction"
        How about "Locking a table for the transaction duration"

        Show
        Laura Stewart added a comment - Hi Kim - For the Tuning Guide change. Can we shorten this title? Instead of "Locking a table for the duration of a transaction" How about "Locking a table for the transaction duration"
        Hide
        Kim Haase added a comment -

        Well, I was thinking of translatability, and clarity for non-native speakers of English. It's only 5 characters difference – is there some constraint I should have in mind?

        Show
        Kim Haase added a comment - Well, I was thinking of translatability, and clarity for non-native speakers of English. It's only 5 characters difference – is there some constraint I should have in mind?
        Hide
        Laura Stewart added a comment -

        For the flie cdevstandards806027.html (Alter Table syntax).
        Because this is in the Dev Guide and is under "Standards", maybe the title should be
        ALTER TABLE syntax standard or Syntax standard used by ALTER TABLE statement.

        This will help distinguish this file from the ALTER TABLE topic in the Ref Manual.

        Show
        Laura Stewart added a comment - For the flie cdevstandards806027.html (Alter Table syntax). Because this is in the Dev Guide and is under "Standards", maybe the title should be ALTER TABLE syntax standard or Syntax standard used by ALTER TABLE statement. This will help distinguish this file from the ALTER TABLE topic in the Ref Manual.
        Hide
        Laura Stewart added a comment -

        Same comment on the file cdevstandards805975.html (CLOB and BLOB). Even though there are
        separate files for these in the Ref Manual. I would be more comfortable with a title that
        specifies that this topic relates to the standards used.

        Standards used for CLOB and BLOB data types

        Show
        Laura Stewart added a comment - Same comment on the file cdevstandards805975.html (CLOB and BLOB). Even though there are separate files for these in the Ref Manual. I would be more comfortable with a title that specifies that this topic relates to the standards used. Standards used for CLOB and BLOB data types
        Hide
        Kim Haase added a comment -

        For the cdevstandards files, I was trying to be consistent with the other titles in that section:

        • ALTER TABLE
        • Calling functions and procedures
        • CLOB and BLOB
        • Cursors
        • DECIMAL max precision
        • Dynamic SQL
        • Expressions on LONGs
        • Information schema
        • NOT NULL characteristic
        • Transactions
        • Stored routines and PSM
        • Unique constraints and nulls
        • XML data types and operators

        Also, in fact, this is a list of *non*standard features, so we'd have to make each title "Nonstandard feature: xxx" or something like that.

        Also, see what happens in the main "Derby and standards" topic with them as they are: they're all pulled into that page, except for the long last topic. I've been puzzling over this. It's really kind of silly to have all these different tiny topics when what you really do want is just the bullet list in the "Derby and standards" topic. The only glitch is that really long last topic.

        What do you think is the best solution here?

        Show
        Kim Haase added a comment - For the cdevstandards files, I was trying to be consistent with the other titles in that section: ALTER TABLE Calling functions and procedures CLOB and BLOB Cursors DECIMAL max precision Dynamic SQL Expressions on LONGs Information schema NOT NULL characteristic Transactions Stored routines and PSM Unique constraints and nulls XML data types and operators Also, in fact, this is a list of *non*standard features, so we'd have to make each title "Nonstandard feature: xxx" or something like that. Also, see what happens in the main "Derby and standards" topic with them as they are: they're all pulled into that page, except for the long last topic. I've been puzzling over this. It's really kind of silly to have all these different tiny topics when what you really do want is just the bullet list in the "Derby and standards" topic. The only glitch is that really long last topic. What do you think is the best solution here?
        Hide
        Kim Haase added a comment -

        Here is another relatively small patch, for the Admin Guide: 12 source files plus the map file. It adds "property" to the titles and index entries for the dozen Network Server properties.

        Show
        Kim Haase added a comment - Here is another relatively small patch, for the Admin Guide: 12 source files plus the map file. It adds "property" to the titles and index entries for the dozen Network Server properties.
        Hide
        Laura Stewart added a comment -

        For the cdevstandards files...

        Sigh. Whoever set up this file is using the parent/child relationships in the ditamap to display the topic shortdesc in the main
        "Derby and standards" topic. My recommendation is that all of the content in these separate files (except the last one) be moved to the main
        topic as a formal bulleted list. For the last topic, keep it as a separate topic and keep the parent/child relationship in the ditamap (so that there is a link), since it is a long topic.

        But this is far more work than just changing topic titles

        So I suggest that you skip these topics in Dev Guide for Derby1920 and open a new issue for this problem. Then anyone can make this correction.
        But if you want to do it now ... up to you

        Show
        Laura Stewart added a comment - For the cdevstandards files... Sigh. Whoever set up this file is using the parent/child relationships in the ditamap to display the topic shortdesc in the main "Derby and standards" topic. My recommendation is that all of the content in these separate files (except the last one) be moved to the main topic as a formal bulleted list. For the last topic, keep it as a separate topic and keep the parent/child relationship in the ditamap (so that there is a link), since it is a long topic. But this is far more work than just changing topic titles So I suggest that you skip these topics in Dev Guide for Derby1920 and open a new issue for this problem. Then anyone can make this correction. But if you want to do it now ... up to you
        Hide
        Laura Stewart added a comment -

        The patch for the Admin guide Network Server properties topics looks good

        Please let me know which diff files are ready to be commited and I'll commit them.
        You have made a lot of great improvements so far and I want to be sure we implement them
        as soon as the diff files have been looked over and approved by someone. Want to
        implement these changes so that users can benefit from them right away !

        Show
        Laura Stewart added a comment - The patch for the Admin guide Network Server properties topics looks good Please let me know which diff files are ready to be commited and I'll commit them. You have made a lot of great improvements so far and I want to be sure we implement them as soon as the diff files have been looked over and approved by someone. Want to implement these changes so that users can benefit from them right away !
        Hide
        Kim Haase added a comment -

        Thanks, Laura! I agree that fixing the "Derby and standards" files is a separate issue. I'll file one.

        I think the three so far (Admin Guide, Dev Guide, Tuning Guide) are ready to commit, unless you see any other issues. I will start doing incremental Ref Manual title fixes.

        Show
        Kim Haase added a comment - Thanks, Laura! I agree that fixing the "Derby and standards" files is a separate issue. I'll file one. I think the three so far (Admin Guide, Dev Guide, Tuning Guide) are ready to commit, unless you see any other issues. I will start doing incremental Ref Manual title fixes.
        Hide
        Kim Haase added a comment -

        Here is an initial very small patch for the Reference Manual with title changes for some miscellaneous files. I will wait till the end to do the map file; it doesn't seem to matter at all if the navtitle strings don't match the actual titles, and it's the actual titles that show up in the TOCs. I can then pick up the DERBY-2387changes in the final map file.

        Show
        Kim Haase added a comment - Here is an initial very small patch for the Reference Manual with title changes for some miscellaneous files. I will wait till the end to do the map file; it doesn't seem to matter at all if the navtitle strings don't match the actual titles, and it's the actual titles that show up in the TOCs. I can then pick up the DERBY-2387 changes in the final map file.
        Hide
        Kim Haase added a comment -

        My apologies: patch files are DERBY-1920-ref1.diff and DERBY-1920-ref1.zip.

        Show
        Kim Haase added a comment - My apologies: patch files are DERBY-1920 -ref1.diff and DERBY-1920 -ref1.zip.
        Hide
        Kim Haase added a comment -

        Attaching another small patch (20 files), for the data types: DERBY-1920-ref2.diff and DERBY-1920-ref2.zip.

        Show
        Kim Haase added a comment - Attaching another small patch (20 files), for the data types: DERBY-1920 -ref2.diff and DERBY-1920 -ref2.zip.
        Hide
        Laura Stewart added a comment -

        Patch Derby-1920-ref1 looks good.

        Show
        Laura Stewart added a comment - Patch Derby-1920-ref1 looks good.
        Hide
        Laura Stewart added a comment -

        Patch Derby-1920-ref2 looks good

        I'll commit these patches later today.

        Show
        Laura Stewart added a comment - Patch Derby-1920-ref2 looks good I'll commit these patches later today.
        Hide
        Kim Haase added a comment -

        Thanks, Laura. Here's one more (19 files, system tables): DERBY-1920-ref3.diff and DERBY-1920-ref3.zip. No rush.

        Show
        Kim Haase added a comment - Thanks, Laura. Here's one more (19 files, system tables): DERBY-1920 -ref3.diff and DERBY-1920 -ref3.zip. No rush.
        Hide
        Laura Stewart added a comment -

        The admin guide patch was committed.
        Committed revision 513907.

        Show
        Laura Stewart added a comment - The admin guide patch was committed. Committed revision 513907.
        Hide
        Laura Stewart added a comment -

        The Dev guide patch was committed.
        Committed revision 513925.

        Show
        Laura Stewart added a comment - The Dev guide patch was committed. Committed revision 513925.
        Hide
        Laura Stewart added a comment -

        The Tuning Guide patch was committed.
        Committed revision 513927.

        Show
        Laura Stewart added a comment - The Tuning Guide patch was committed. Committed revision 513927.
        Hide
        Laura Stewart added a comment -

        The 1st Ref Guide patch was committed.
        You will want to update your source code before generating any additional patches (actually this applies to any of the docs, not just Ref)
        Committed revision 513932.

        Show
        Laura Stewart added a comment - The 1st Ref Guide patch was committed. You will want to update your source code before generating any additional patches (actually this applies to any of the docs, not just Ref) Committed revision 513932.
        Hide
        Laura Stewart added a comment -

        The 2nd Ref Guide patch was committed.
        Committed revision 513936.

        Show
        Laura Stewart added a comment - The 2nd Ref Guide patch was committed. Committed revision 513936.
        Hide
        Laura Stewart added a comment -

        The 3rd Ref Guide patch looks good and was committed.
        Committed revision 513945.

        Show
        Laura Stewart added a comment - The 3rd Ref Guide patch looks good and was committed. Committed revision 513945.
        Hide
        Kim Haase added a comment -

        Attaching another patch, this one for the built-in system procedures (17 files).

        Show
        Kim Haase added a comment - Attaching another patch, this one for the built-in system procedures (17 files).
        Hide
        Laura Stewart added a comment -

        The 4th Ref Guide patch looks good.

        Show
        Laura Stewart added a comment - The 4th Ref Guide patch looks good.
        Hide
        Laura Stewart added a comment -

        The 4th Ref Guide patch was committed.
        Committed revision 514770.

        Show
        Laura Stewart added a comment - The 4th Ref Guide patch was committed. Committed revision 514770.
        Hide
        Kim Haase added a comment -

        Thanks, Laura, for committing these!

        This one, DERBY-1920-ref5.diff and DERBY-1920-ref5.zip, is a good deal bigger – 45 files. It includes the changes to the builtin functions. These include the usual title and index fixes, plus some xref additions and corrections; the removal of an empty section from rrefidentityvallocal.dita; a correction to the first sentence of the SUM function file (rrefsqlj13083.dita); and a correction of the reference id in rrefsqlj29930.dita.

        Show
        Kim Haase added a comment - Thanks, Laura, for committing these! This one, DERBY-1920 -ref5.diff and DERBY-1920 -ref5.zip, is a good deal bigger – 45 files. It includes the changes to the builtin functions. These include the usual title and index fixes, plus some xref additions and corrections; the removal of an empty section from rrefidentityvallocal.dita; a correction to the first sentence of the SUM function file (rrefsqlj13083.dita); and a correction of the reference id in rrefsqlj29930.dita.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-1920-ref6.diff and DERBY-1920-ref6.zip, for the titles in the JDBC section of the Reference Manual (39 files). I'm not including the new file I proposed to organize the JDBC 2.0 topics (rrefjdbc2_0summary.dita); that will wait for the changes that involve the map file, at the end.

        In addition to title and index fixes, there are some xref fixes and a grammar correction (rrefjdbc15905.dita).

        Show
        Kim Haase added a comment - Attaching DERBY-1920 -ref6.diff and DERBY-1920 -ref6.zip, for the titles in the JDBC section of the Reference Manual (39 files). I'm not including the new file I proposed to organize the JDBC 2.0 topics (rrefjdbc2_0summary.dita); that will wait for the changes that involve the map file, at the end. In addition to title and index fixes, there are some xref fixes and a grammar correction (rrefjdbc15905.dita).
        Hide
        Laura Stewart added a comment -

        The 5th Ref Guide patch looks good.
        I was a little surprised that Concatenation is a operator rather than a function...

        Show
        Laura Stewart added a comment - The 5th Ref Guide patch looks good. I was a little surprised that Concatenation is a operator rather than a function...
        Hide
        Laura Stewart added a comment -

        Kim - You might want to ask on the derby-dev list about CASE, Concatenation, NULLIF, and the XML operators.
        This section you worked on is about Built-in Functions. Should these expressions and operators be moved to
        another section?

        Show
        Laura Stewart added a comment - Kim - You might want to ask on the derby-dev list about CASE, Concatenation, NULLIF, and the XML operators. This section you worked on is about Built-in Functions. Should these expressions and operators be moved to another section?
        Hide
        Laura Stewart added a comment -

        The 5th Ref Guide patch was committed.
        Committed revision 515215.

        Show
        Laura Stewart added a comment - The 5th Ref Guide patch was committed. Committed revision 515215.
        Hide
        Kim Haase added a comment -

        Good question about the operators/expressions. I feel confident in calling the concatenation operator (||) an operator just based on my long experience with programming languages.

        About the others I'd need to see the SQL spec, to which I don't have access – do you? NULLIF has the appearance of a function, but it's equivalent to CASE, which actually looks more like a statement to me. Those XML operators actually look more like functions. But I'm going by the terminology of other languages, not SQL For the most part SQL seems to use the same terminology as others, but there may be exceptions.

        Thanks for doing the commit. Any needed reorganization of these topics can be a separate issue.

        Show
        Kim Haase added a comment - Good question about the operators/expressions. I feel confident in calling the concatenation operator (||) an operator just based on my long experience with programming languages. About the others I'd need to see the SQL spec, to which I don't have access – do you? NULLIF has the appearance of a function, but it's equivalent to CASE, which actually looks more like a statement to me. Those XML operators actually look more like functions. But I'm going by the terminology of other languages, not SQL For the most part SQL seems to use the same terminology as others, but there may be exceptions. Thanks for doing the commit. Any needed reorganization of these topics can be a separate issue.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-1920-ref7.diff and DERBY-1920-ref7.zip, containing the fixes for the connection URL attribute topics (18 files). Again, the fixes involve titles, index entries, and xrefs. In a couple of xrefs that go to web sites, I also changed the scope of the website links from local to external so they will open in a new window.

        Show
        Kim Haase added a comment - Attaching DERBY-1920 -ref7.diff and DERBY-1920 -ref7.zip, containing the fixes for the connection URL attribute topics (18 files). Again, the fixes involve titles, index entries, and xrefs. In a couple of xrefs that go to web sites, I also changed the scope of the website links from local to external so they will open in a new window.
        Hide
        Kim Haase added a comment -

        This is the last (but trickiest) patch for the Ref Manual, DERBY-1920-ref8.diff and DERBY-1920-ref8.zip. In this patch, the following happens:

        Delete rrefsqlj76354.dita ("Value") and put the syntax for this in the "UPDATE statement" topic, rrefsqlj26498.dita, the only one that references it.

        Delete rrefsqlj87167.dita ("Value") and put the syntax for this in the "VALUES expression" topic, rrefsqlj11277.dita, the only one that references it.

        Delete rrefsqlj1080962.dita ("Example") and merge the contents with the
        "Expression precedence" topic, ref/rrefsqlj1080779.dita

        Add rrefjdbc2_0summary.dita, "JDBC 2.0 features", and place the next 7 topics (java.sql.Connection through "java.sql.ResultSetMetaData) under it, and reorder them alphabetically.

        Do a little more reordering of the JDBC topics so that methods go with their interfaces, etc.

        Update the map file with the new navtitles and restructuring.

        Show
        Kim Haase added a comment - This is the last (but trickiest) patch for the Ref Manual, DERBY-1920 -ref8.diff and DERBY-1920 -ref8.zip. In this patch, the following happens: Delete rrefsqlj76354.dita ("Value") and put the syntax for this in the "UPDATE statement" topic, rrefsqlj26498.dita, the only one that references it. Delete rrefsqlj87167.dita ("Value") and put the syntax for this in the "VALUES expression" topic, rrefsqlj11277.dita, the only one that references it. Delete rrefsqlj1080962.dita ("Example") and merge the contents with the "Expression precedence" topic, ref/rrefsqlj1080779.dita Add rrefjdbc2_0summary.dita, "JDBC 2.0 features", and place the next 7 topics (java.sql.Connection through "java.sql.ResultSetMetaData) under it, and reorder them alphabetically. Do a little more reordering of the JDBC topics so that methods go with their interfaces, etc. Update the map file with the new navtitles and restructuring.
        Hide
        Laura Stewart added a comment -

        Hi Kim -

        I agree that concatenation is probably an operator.

        I don't have access to the SQL specs for Derby. In looking at a related database, NULLIF is a scalar unction that takes expressions. Same with the XML functions. However the SQL/XML 2006 standard uses "operator" for the XML ones...

        When I first contributed the documentation for the XML topics (now I am recalling we discussed that they are the same as build in functions but the standard used the term operator, so we kept that.

        Show
        Laura Stewart added a comment - Hi Kim - I agree that concatenation is probably an operator. I don't have access to the SQL specs for Derby. In looking at a related database, NULLIF is a scalar unction that takes expressions. Same with the XML functions. However the SQL/XML 2006 standard uses "operator" for the XML ones... When I first contributed the documentation for the XML topics (now I am recalling we discussed that they are the same as build in functions but the standard used the term operator, so we kept that.
        Hide
        Kim Haase added a comment -

        Thanks for that history, Laura. One problem with finding a SQL spec is that when I looked on the web I found that you have to pay for it. I will check and see if someone here has a copy I can look at. In the meantime, do you think it would be safe to leave the list as is until we get better information?

        Show
        Kim Haase added a comment - Thanks for that history, Laura. One problem with finding a SQL spec is that when I looked on the web I found that you have to pay for it. I will check and see if someone here has a copy I can look at. In the meantime, do you think it would be safe to leave the list as is until we get better information?
        Hide
        Kim Haase added a comment -

        Here is a patch for the Tools manual: DERBY-1920-tools.diff and DERBY-1920-tools.zip. These changes add "property" to the names of the ij properties, and "command" to the names of the ij commands. There are also some xref and indexterm fixes and a font fix.

        This is almost the last one – there should be one more patch for a few stray cross-reference fixes in the Reference Manual.

        Show
        Kim Haase added a comment - Here is a patch for the Tools manual: DERBY-1920 -tools.diff and DERBY-1920 -tools.zip. These changes add "property" to the names of the ij properties, and "command" to the names of the ij commands. There are also some xref and indexterm fixes and a font fix. This is almost the last one – there should be one more patch for a few stray cross-reference fixes in the Reference Manual.
        Hide
        Laura Stewart added a comment -

        Yes Kim, I think that we can leave the list as is

        You are doing great work on these titles! Thank you
        I'll review and commit the new ones as time permits.

        Show
        Laura Stewart added a comment - Yes Kim, I think that we can leave the list as is You are doing great work on these titles! Thank you I'll review and commit the new ones as time permits.
        Hide
        Kim Haase added a comment -

        Thanks, Laura! Well, this should be the last of them – 5 files in the Ref Manual with xref fixes. I also added a couple of periods in one file (rrefsqlj19433.dita) for consistency with other table entries.

        Show
        Kim Haase added a comment - Thanks, Laura! Well, this should be the last of them – 5 files in the Ref Manual with xref fixes. I also added a couple of periods in one file (rrefsqlj19433.dita) for consistency with other table entries.
        Hide
        Kim Haase added a comment -

        Sorry, I'm getting careless – there are 6 files in this patch, not 5. Also the patch files are DERBY-1920-ref9.diff and DERBY-1920-ref9.zip.

        Show
        Kim Haase added a comment - Sorry, I'm getting careless – there are 6 files in this patch, not 5. Also the patch files are DERBY-1920 -ref9.diff and DERBY-1920 -ref9.zip.
        Hide
        Laura Stewart added a comment -

        Patch Ref-5.diff looks good.
        Committed revision 515685.

        Show
        Laura Stewart added a comment - Patch Ref-5.diff looks good. Committed revision 515685.
        Hide
        Laura Stewart added a comment -

        Patch Ref-6.doff looks good.
        Committed revision 515695.

        Show
        Laura Stewart added a comment - Patch Ref-6.doff looks good. Committed revision 515695.
        Hide
        Laura Stewart added a comment -

        My mistake.
        Patch Ref5 was already commited.
        Patch Ref 6 was committed with revision 515685.
        Patch Ref 7 was committed wtih revision 515695.

        Show
        Laura Stewart added a comment - My mistake. Patch Ref5 was already commited. Patch Ref 6 was committed with revision 515685. Patch Ref 7 was committed wtih revision 515695.
        Hide
        Laura Stewart added a comment -

        Kim - With regards to patch Ref-8, it looks like you removed the contents of some of the files, but they show up as "Modified" and not "Deleted" when I run svn stat:

        M src\ref\rrefsqlj11277.dita
        M src\ref\rrefsqlj26498.dita
        M src\ref\rrefsqlj87167.dita
        M src\ref\rrefsqlj1080779.dita
        M src\ref\rrefsqlj1080962.dita
        M src\ref\rrefsqlj76354.dita
        M src\ref\refderby.ditamap

        They should show up as D for deleted (or R for removed I can't recall

        Also, when you created rrefjdbc2_0summary.dita did you specify svn add? (title = JDBC 2.0 features)

        Show
        Laura Stewart added a comment - Kim - With regards to patch Ref-8, it looks like you removed the contents of some of the files, but they show up as "Modified" and not "Deleted" when I run svn stat: M src\ref\rrefsqlj11277.dita M src\ref\rrefsqlj26498.dita M src\ref\rrefsqlj87167.dita M src\ref\rrefsqlj1080779.dita M src\ref\rrefsqlj1080962.dita M src\ref\rrefsqlj76354.dita M src\ref\refderby.ditamap They should show up as D for deleted (or R for removed I can't recall Also, when you created rrefjdbc2_0summary.dita did you specify svn add? (title = JDBC 2.0 features)
        Hide
        Laura Stewart added a comment -

        In the Tools.diff patch
        file = rtoolsijcomref16653.dita
        Should the new title be "Comment syntax in ij commands" or "Syntax for comments in ij commands" or "Comment syntax for ij commands"
        The "in" in the new title doesn't sound quite right to me... I've asked an editor friend of mine.

        Same question for:
        rtoolsijcomref34110.dita String syntax in ij commands
        rtoolsijcomref40155.dita Identifier syntax in ij commands

        Show
        Laura Stewart added a comment - In the Tools.diff patch file = rtoolsijcomref16653.dita Should the new title be "Comment syntax in ij commands" or "Syntax for comments in ij commands" or "Comment syntax for ij commands" The "in" in the new title doesn't sound quite right to me... I've asked an editor friend of mine. Same question for: rtoolsijcomref34110.dita String syntax in ij commands rtoolsijcomref40155.dita Identifier syntax in ij commands
        Hide
        Kim Haase added a comment -

        Hm, that's very odd. I thought I had done svn rm on those files, and in fact I think I had to in order for them to show up with all the minus signs in the diff file. But I just did it again and didn't get errors:

        > svn rm src/ref/rrefsqlj76354.dita
        D src/ref/rrefsqlj76354.dita
        >svn rm src/ref/rrefsqlj87167.dita
        D src/ref/rrefsqlj87167.dita
        >svn rm src/ref/rrefsqlj1080962.dita
        D src/ref/rrefsqlj1080962.dita

        When I do svn add on the summary file, though, I get this:

        >svn add src/ref/rrefjdbc2_0summary.dita
        svn: warning: 'src/ref/rrefjdbc2_0summary.dita' is already under version control

        So it is already there, supposedly.

        Show
        Kim Haase added a comment - Hm, that's very odd. I thought I had done svn rm on those files, and in fact I think I had to in order for them to show up with all the minus signs in the diff file. But I just did it again and didn't get errors: > svn rm src/ref/rrefsqlj76354.dita D src/ref/rrefsqlj76354.dita >svn rm src/ref/rrefsqlj87167.dita D src/ref/rrefsqlj87167.dita >svn rm src/ref/rrefsqlj1080962.dita D src/ref/rrefsqlj1080962.dita When I do svn add on the summary file, though, I get this: >svn add src/ref/rrefjdbc2_0summary.dita svn: warning: 'src/ref/rrefjdbc2_0summary.dita' is already under version control So it is already there, supposedly.
        Hide
        Kim Haase added a comment -

        On the tools titles – very good catch, I was being careless. I think the most correct wording would be "Syntax for ___ in ij commands". I will refile the patch.

        Show
        Kim Haase added a comment - On the tools titles – very good catch, I was being careless. I think the most correct wording would be "Syntax for ___ in ij commands". I will refile the patch.
        Hide
        Kim Haase added a comment -

        Here's a hopefully improved patch with those three files retitled: DERBY-1920-tools-2.diff and DERBY-1920-tools-2.zip.

        Show
        Kim Haase added a comment - Here's a hopefully improved patch with those three files retitled: DERBY-1920 -tools-2.diff and DERBY-1920 -tools-2.zip.
        Hide
        Laura Stewart added a comment -

        Patch derby-1920-ref9.diff
        Committed revision 518195.

        Show
        Laura Stewart added a comment - Patch derby-1920-ref9.diff Committed revision 518195.
        Hide
        Laura Stewart added a comment -

        Patch derby-1920-ref9.diff looks good and was
        Committed revision 518201.

        Show
        Laura Stewart added a comment - Patch derby-1920-ref9.diff looks good and was Committed revision 518201.
        Hide
        Laura Stewart added a comment -

        Patch derby-1920-tools2.diff looks good and was
        Committed revision 518204.

        I think that this is the LAST one.
        Please confirm... there were so many

        GREAT JOB on all of these Kim. The clarification of the titles is an
        important improvement in retrievability !!!

        Show
        Laura Stewart added a comment - Patch derby-1920-tools2.diff looks good and was Committed revision 518204. I think that this is the LAST one. Please confirm... there were so many GREAT JOB on all of these Kim. The clarification of the titles is an important improvement in retrievability !!!
        Hide
        Kim Haase added a comment -

        Thanks very much, Laura, for all the help and suggestions and keeping up with all the patches. Yes, they are all in now and we're ready to put this one behind us!

        Show
        Kim Haase added a comment - Thanks very much, Laura, for all the help and suggestions and keeping up with all the patches. Yes, they are all in now and we're ready to put this one behind us!
        Hide
        Laura Stewart added a comment -

        Updates completed.

        Show
        Laura Stewart added a comment - Updates completed.

          People

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

            Dates

            • Created:
              Updated:
              Resolved:

              Development