Derby
  1. Derby
  2. DERBY-4629

Explicitly document how to get case-insensitive sorts and comparisons of string data

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.6.1.0
    • Fix Version/s: 10.10.2.0, 10.11.1.1
    • Component/s: Documentation
    • Labels:
      None
    • Issue & fix info:
      High Value Fix

      Description

      The most frequently asked question about Derby's support for language-sensitive strings is this: "How do I get Derby to perform case-insensitive sorts and comparisons?" I think that the answer to this question could be figured out by a reasonably intrepid reader who understood a lot about Java's locale and collation support, perhaps supplemented with a fair amount of googling.

      If we made the answer to this question really pop out to the casual reader, then I think we would do a great service to our users and to developers and tech writers who answer questions on the community lists. Perhaps it would be sufficient to add a "Case-insensitive strings" section parallel to "Character-based collation in Derby" in the Developer's Guide.

      1. DERBY-4629.zip
        16 kB
        Kim Haase
      2. DERBY-4629.stat
        0.2 kB
        Kim Haase
      3. DERBY-4629.diff
        14 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        Rick, do you think that more is needed here in addition to the work on DERBY-4627 and DERBY-4628? Or would it still be helpful to have a topic on "Performing case-insensitive sorts and comparisons" in the "Localizing Derby" section, in addition to the one on "Creating a case-insensitive database" further up under "Working with the database connection URL attributes"?

        As near as I can tell, you must have a case-insensitive database in order to perform case-insensitive string sorts – is that correct?

        Show
        Kim Haase added a comment - Rick, do you think that more is needed here in addition to the work on DERBY-4627 and DERBY-4628 ? Or would it still be helpful to have a topic on "Performing case-insensitive sorts and comparisons" in the "Localizing Derby" section, in addition to the one on "Creating a case-insensitive database" further up under "Working with the database connection URL attributes"? As near as I can tell, you must have a case-insensitive database in order to perform case-insensitive string sorts – is that correct?
        Hide
        Rick Hillegas added a comment -

        Hi Kim,

        To answer your question, I refreshed my docs client and rebuilt the docs. Then I went to the Developer's Guide to look up the material on how to get Derby to sort data in a case-insensitive way. The first place I looked was in the table of contents under "Localizing Derby". I think that a lot of people will go to that section first. Many people coming from other databases will think of sort-order as an attribute of individual table columns, not a bulk attribute of the entire database.

        However, the material is under the "Working with the database connection URL attributes" topic. This probably makes a lot of sense for people who are familiar with Derby. But newbies aren't going to know to look for case-sensitivity information under a topic on connection URLs. If only we had a document index, this would be less of a problem.

        I think that people will look for this material in a couple places:

        1) Where I initially looked, under "Localizing Derby" in the Developer's Guide.

        2) In the Reference Guide section titled "Data type assignments and comparison, sorting, and ordering".

        3) Maybe even under the "CREATE INDEX statement" topic in the Reference Guide.

        At a minimum, I'd recommend adding pointers from the above topics to the relevant material. I think that the pointers for (1) are handled by the work you did on DERBY-4627. We could probably do with some pointers for (2) and (3).

        But at the end of the day, it would really be great if this material popped when you scanned the table of contents. I wonder if it's worth putting a dummy section under "Localizing Derby" just so that it pops when the reader looks there. The dummy section could just forward the user to the relevant material. On the other hand, that would be trying to make the table of contents function like an index and so is the beginning of a slippery slope which we may regret later.

        Those are my $0.02. Thanks.

        Show
        Rick Hillegas added a comment - Hi Kim, To answer your question, I refreshed my docs client and rebuilt the docs. Then I went to the Developer's Guide to look up the material on how to get Derby to sort data in a case-insensitive way. The first place I looked was in the table of contents under "Localizing Derby". I think that a lot of people will go to that section first. Many people coming from other databases will think of sort-order as an attribute of individual table columns, not a bulk attribute of the entire database. However, the material is under the "Working with the database connection URL attributes" topic. This probably makes a lot of sense for people who are familiar with Derby. But newbies aren't going to know to look for case-sensitivity information under a topic on connection URLs. If only we had a document index, this would be less of a problem. I think that people will look for this material in a couple places: 1) Where I initially looked, under "Localizing Derby" in the Developer's Guide. 2) In the Reference Guide section titled "Data type assignments and comparison, sorting, and ordering". 3) Maybe even under the "CREATE INDEX statement" topic in the Reference Guide. At a minimum, I'd recommend adding pointers from the above topics to the relevant material. I think that the pointers for (1) are handled by the work you did on DERBY-4627 . We could probably do with some pointers for (2) and (3). But at the end of the day, it would really be great if this material popped when you scanned the table of contents. I wonder if it's worth putting a dummy section under "Localizing Derby" just so that it pops when the reader looks there. The dummy section could just forward the user to the relevant material. On the other hand, that would be trying to make the table of contents function like an index and so is the beginning of a slippery slope which we may regret later. Those are my $0.02. Thanks.
        Hide
        Kim Haase added a comment -

        Thanks for all the great suggestions, Rick.

        I will certainly add links to the collation material as you suggest. It must be confusing to readers that the reference manual section called "Data type assignments and comparison, sorting, and ordering" really has nothing in it about sorting or ordering.

        I'm wondering if it might be helpful to split off the "Collation examples" section of the URL attributes topic into a separate topic and retitle it "Examples of case-sensitive and case-insensitive string sorting"?? That would at least add another word besides "collation" for readers to find. It seemed too closely related to the attributes topic to split off, but it might work better on its own.

        Show
        Kim Haase added a comment - Thanks for all the great suggestions, Rick. I will certainly add links to the collation material as you suggest. It must be confusing to readers that the reference manual section called "Data type assignments and comparison, sorting, and ordering" really has nothing in it about sorting or ordering. I'm wondering if it might be helpful to split off the "Collation examples" section of the URL attributes topic into a separate topic and retitle it "Examples of case-sensitive and case-insensitive string sorting"?? That would at least add another word besides "collation" for readers to find. It seemed too closely related to the attributes topic to split off, but it might work better on its own.
        Hide
        Rick Hillegas added a comment -

        Hi Kim,

        Where were you thinking of putting the "Examples of case-sensitive and case-insensitive string sorting" section? From the point of view of reference material, it's good to have this material where it is today: under the documentation on URL attributes. But the "Localizing Derby" section is a better home for this material for someone who is trying to grasp what Derby's capabilities are. Thanks.

        Show
        Rick Hillegas added a comment - Hi Kim, Where were you thinking of putting the "Examples of case-sensitive and case-insensitive string sorting" section? From the point of view of reference material, it's good to have this material where it is today: under the documentation on URL attributes. But the "Localizing Derby" section is a better home for this material for someone who is trying to grasp what Derby's capabilities are. Thanks.
        Hide
        Kim Haase added a comment -

        I'd put it in the same position it's in now – just in the form of a separate topic. So it would be under "Localizing Derby", between "Database connection URL attributes that control collation" and "Differences between LIKE and equal (=) comparisons". It does logically depend on the info provided in the URL attributes topic, I think.

        Show
        Kim Haase added a comment - I'd put it in the same position it's in now – just in the form of a separate topic. So it would be under "Localizing Derby", between "Database connection URL attributes that control collation" and "Differences between LIKE and equal (=) comparisons". It does logically depend on the info provided in the URL attributes topic, I think.
        Hide
        Rick Hillegas added a comment -

        Thanks, Kim. That sounds good to me.

        Show
        Rick Hillegas added a comment - Thanks, Kim. That sounds good to me.
        Hide
        Kim Haase added a comment -

        Thanks, Rick, for all the advice. I'm attaching DERBY-4629.diff, DERBY-4629.stat, and DERBY-4629.zip, with the following changes:

        A src/devguide/cdevcollationexamples.dita
        M src/devguide/cdevcollationattribs.dita
        M src/devguide/derbydev.ditamap
        M src/ref/rrefsqlj20937.dita
        M src/ref/rrefattrib56769.dita
        M src/ref/rrefsqlj58560.dita

        I added identical paragraphs to the CREATE INDEX topic and ""Data type assignments and comparison, sorting, and ordering".

        I welcome additional edits and suggestions.

        Show
        Kim Haase added a comment - Thanks, Rick, for all the advice. I'm attaching DERBY-4629 .diff, DERBY-4629 .stat, and DERBY-4629 .zip, with the following changes: A src/devguide/cdevcollationexamples.dita M src/devguide/cdevcollationattribs.dita M src/devguide/derbydev.ditamap M src/ref/rrefsqlj20937.dita M src/ref/rrefattrib56769.dita M src/ref/rrefsqlj58560.dita I added identical paragraphs to the CREATE INDEX topic and ""Data type assignments and comparison, sorting, and ordering". I welcome additional edits and suggestions.
        Hide
        Rick Hillegas added a comment -

        Thanks, Kim. These changes look good to me. Now sort order is actually mentioned by "Data type assignments and comparison, sorting, and ordering"! +1

        Show
        Rick Hillegas added a comment - Thanks, Kim. These changes look good to me. Now sort order is actually mentioned by "Data type assignments and comparison, sorting, and ordering"! +1
        Hide
        ASF subversion and git services added a comment -

        Commit 1517897 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1517897 ]

        DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data

        Split a Developer's Guide topic into 2 and updated map file; modified 3 Reference Manual topics.

        Patch: DERBY-4629.diff

        Show
        ASF subversion and git services added a comment - Commit 1517897 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1517897 ] DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data Split a Developer's Guide topic into 2 and updated map file; modified 3 Reference Manual topics. Patch: DERBY-4629 .diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1517897 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1517897 ]

        DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data

        Split a Developer's Guide topic into 2 and updated map file; modified 3 Reference Manual topics.

        Patch: DERBY-4629.diff

        Show
        ASF subversion and git services added a comment - Commit 1517897 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1517897 ] DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data Split a Developer's Guide topic into 2 and updated map file; modified 3 Reference Manual topics. Patch: DERBY-4629 .diff
        Hide
        Kim Haase added a comment -

        Thanks very much, Rick!

        Committed patch DERBY-4629.diff to documentation trunk at revision 1517897.

        Show
        Kim Haase added a comment - Thanks very much, Rick! Committed patch DERBY-4629 .diff to documentation trunk at revision 1517897.
        Hide
        ASF subversion and git services added a comment -

        Commit 1518727 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1518727 ]

        DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data

        Merged patch DERBY-4629.diff to 10.10 doc branch from trunk revision 1517897.

        Show
        ASF subversion and git services added a comment - Commit 1518727 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1518727 ] DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data Merged patch DERBY-4629 .diff to 10.10 doc branch from trunk revision 1517897.
        Hide
        ASF subversion and git services added a comment -

        Commit 1518727 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1518727 ]

        DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data

        Merged patch DERBY-4629.diff to 10.10 doc branch from trunk revision 1517897.

        Show
        ASF subversion and git services added a comment - Commit 1518727 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1518727 ] DERBY-4629 Explicitly document how to get case-insensitive sorts and comparisons of string data Merged patch DERBY-4629 .diff to 10.10 doc branch from trunk revision 1517897.
        Hide
        Kim Haase added a comment -

        Reopened for backport to 10.10.

        Show
        Kim Haase added a comment - Reopened for backport to 10.10.
        Hide
        Kim Haase added a comment -

        Merged DERBY-4629.diff to 10.10 doc branch at revision 1518727.

        Show
        Kim Haase added a comment - Merged DERBY-4629 .diff to 10.10 doc branch at revision 1518727.

          People

          • Assignee:
            Kim Haase
            Reporter:
            Rick Hillegas
          • Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development