Derby
  1. Derby
  2. DERBY-4482

Property to set IJ session locale not documented (assume this is derby.ui.locale)

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.0.2.0, 10.0.2.1, 10.1.1.0, 10.1.2.1, 10.1.3.1, 10.2.1.6, 10.2.2.0, 10.3.1.4, 10.3.2.1, 10.3.3.0, 10.4.1.3, 10.4.2.0, 10.5.1.1, 10.5.2.0, 10.5.3.0
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      The property derby.ui.locale is used in an example in the Tools guide but not documented anywhere. Serveral places mention the Session locale but nothing is said about how to specify the Session locale. Presumably derby.ui.locale is the missing link?

      See DERBY-2188 for a discussion that identifies a couple of issues including that the property needs to be documented.
      Knut wrote (comment - 20/Oct/07 04:23 PM ):
      > Knut mentions the Tools and Utilities guide example under
      > 'derby.ui.codeset' which uses a property called
      > 'derby.ui.territory'.

      I believe this is a typo in the example. It should have said
      'derby.ui.locale'. To my knowledge, there is no property called
      'derby.ui.territory'.

      1. ctools1004764.html
        4 kB
        Bryan Pendleton
      2. ctools1004764.html
        4 kB
        Bryan Pendleton
      3. docs.diff
        7 kB
        Bryan Pendleton
      4. docs.diff
        6 kB
        Bryan Pendleton
      5. rtoolsijlocale.html
        9 kB
        Bryan Pendleton
      6. rtoolsijlocale.html
        9 kB
        Bryan Pendleton

        Activity

        Stan Bradbury created issue -
        Stan Bradbury made changes -
        Field Original Value New Value
        Summary Property to set IJ session locale not documented (assume this is derby.ui.locacle) Property to set IJ session locale not documented (assume this is derby.ui.locale)
        Stan Bradbury made changes -
        Description The property derby.ui.locale is used in an example in the Tools guide but not documented anywhere. Serveral places mention the Session locale but nothing is said about how to specify the Session locale. Presumably derby.ui.locale is the missing link?

        See DERBY-2188 for a discussion that identifies a couple of issues including that the property
        Knut wrote (comment - 20/Oct/07 04:23 PM ):
        > Knut mentions the Tools and Utilities guide example under
        > 'derby.ui.codeset' which uses a property called
        > 'derby.ui.territory'.

        I believe this is a typo in the example. It should have said
        'derby.ui.locale'. To my knowledge, there is no property called
        'derby.ui.territory'.
        The property derby.ui.locale is used in an example in the Tools guide but not documented anywhere. Serveral places mention the Session locale but nothing is said about how to specify the Session locale. Presumably derby.ui.locale is the missing link?

        See DERBY-2188 for a discussion that identifies a couple of issues including that the property needs to be documented.
        Knut wrote (comment - 20/Oct/07 04:23 PM ):
        > Knut mentions the Tools and Utilities guide example under
        > 'derby.ui.codeset' which uses a property called
        > 'derby.ui.territory'.

        I believe this is a typo in the example. It should have said
        'derby.ui.locale'. To my knowledge, there is no property called
        'derby.ui.territory'.
        Hide
        Bryan Pendleton added a comment -

        Hi Stan,

        I think that http://db.apache.org/derby/docs/10.5/tools/rtoolsijpropref97949.html
        is the page which has the example that you're referring to, but it looks like Laura
        fixed this as part of DERBY-2188 – am I overlooking a place in this page, or
        looking at the wrong page?

        I think there are 2 or 3 additional things that would be useful to do to improve
        the documentation regarding derby.ui.locale:

        1) I think we should add a sentence to the third bullet item in
        http://db.apache.org/derby/docs/10.5/tools/ctools1004764.html
        specifying that derby.ui.locale can be used to control the ij or dblook session locale.

        2) I think we should add a page to the "ij properties" section of the Tools guide
        http://db.apache.org/derby/docs/10.5/tools/rtoolsijpropref29864.html
        to document the derby.ui.locale property, similar to the page that we have in
        that section for the derby.ui.codeset property.

        3) Possibly, we should have some information about derby.ui.locale and derby.ui.codeset
        in the Reference guide, in the section "Derby properties"
        http://db.apache.org/derby/docs/10.5/ref/crefproper22250.html
        I'm a little confused about this one, because it seems like maybe this section is
        only supposed to describe system and database properties, not tools properties?
        Perhaps the thing to do here is to add a brief note to this section, indicating that
        there are some Derby properties that only affect the behavior of the Derby tools, and
        that those properties are documented in the Tools guide?

        If you can give me your thoughts about what sort of documentation improvements
        would be most useful here, that would be great!

        Show
        Bryan Pendleton added a comment - Hi Stan, I think that http://db.apache.org/derby/docs/10.5/tools/rtoolsijpropref97949.html is the page which has the example that you're referring to, but it looks like Laura fixed this as part of DERBY-2188 – am I overlooking a place in this page, or looking at the wrong page? I think there are 2 or 3 additional things that would be useful to do to improve the documentation regarding derby.ui.locale: 1) I think we should add a sentence to the third bullet item in http://db.apache.org/derby/docs/10.5/tools/ctools1004764.html specifying that derby.ui.locale can be used to control the ij or dblook session locale. 2) I think we should add a page to the "ij properties" section of the Tools guide http://db.apache.org/derby/docs/10.5/tools/rtoolsijpropref29864.html to document the derby.ui.locale property, similar to the page that we have in that section for the derby.ui.codeset property. 3) Possibly, we should have some information about derby.ui.locale and derby.ui.codeset in the Reference guide, in the section "Derby properties" http://db.apache.org/derby/docs/10.5/ref/crefproper22250.html I'm a little confused about this one, because it seems like maybe this section is only supposed to describe system and database properties, not tools properties? Perhaps the thing to do here is to add a brief note to this section, indicating that there are some Derby properties that only affect the behavior of the Derby tools, and that those properties are documented in the Tools guide? If you can give me your thoughts about what sort of documentation improvements would be most useful here, that would be great!
        Bryan Pendleton made changes -
        Assignee Bryan Pendleton [ bryanpendleton ]
        Hide
        Bryan Pendleton added a comment -

        Attached is a patch proposal which makes two changes to the Tools guide:
        1) Adds a new page describing the derby.ij.locale property. The description
        on this page was mostly taken from the description of the "territory"
        attribute for the database connection URL, since I think it mostly applies
        to derby.ij.locale as well.
        2) Adds a sentence to the "About Locales" page in the tools guide giving
        a cross-reference to the new page to help users find this page more easily.

        HTML versions of the two modifies pages are also attached.

        Please let me know what you think of this idea, and whether it would
        resolve the issues raised by this JIRA entry.

        Show
        Bryan Pendleton added a comment - Attached is a patch proposal which makes two changes to the Tools guide: 1) Adds a new page describing the derby.ij.locale property. The description on this page was mostly taken from the description of the "territory" attribute for the database connection URL, since I think it mostly applies to derby.ij.locale as well. 2) Adds a sentence to the "About Locales" page in the tools guide giving a cross-reference to the new page to help users find this page more easily. HTML versions of the two modifies pages are also attached. Please let me know what you think of this idea, and whether it would resolve the issues raised by this JIRA entry.
        Bryan Pendleton made changes -
        Attachment rtoolsijlocale.html [ 12428767 ]
        Attachment docs.diff [ 12428765 ]
        Attachment ctools1004764.html [ 12428766 ]
        Hide
        Knut Anders Hatlen added a comment -

        Hi Bryan,

        Perhaps the "Function" section should say something about what the property controls? For example:

        "Set this property to a supported locale name when using one of the Derby tools, if you want another locale than the system default locale. The locale determines the localized display format for numbers, dates, times and timestamps, as well as the language of the messages from the Derby tools."

        Similarly, in About locales -> ij or dblook Session locale, it might be worth mentioning that the session locale also controls the language of the messages. (I'm not sure why that paragraph limits the scope to ij and dblook. The property applies to all the tools. Would it make sense to replace "ij or dblook session" with "tools session", and mention ij and dblook as examples?)

        In About locales, the property name is misspelled: derby.ij.locale -> derby.ui.locale.

        Show
        Knut Anders Hatlen added a comment - Hi Bryan, Perhaps the "Function" section should say something about what the property controls? For example: "Set this property to a supported locale name when using one of the Derby tools, if you want another locale than the system default locale. The locale determines the localized display format for numbers, dates, times and timestamps, as well as the language of the messages from the Derby tools." Similarly, in About locales -> ij or dblook Session locale, it might be worth mentioning that the session locale also controls the language of the messages. (I'm not sure why that paragraph limits the scope to ij and dblook. The property applies to all the tools. Would it make sense to replace "ij or dblook session" with "tools session", and mention ij and dblook as examples?) In About locales, the property name is misspelled: derby.ij.locale -> derby.ui.locale.
        Hide
        Bryan Pendleton added a comment -

        Thanks Knut, those suggestions definitely improve the material.

        Attached is a revised patch diff, and revised HTML versions of the two pages.

        Show
        Bryan Pendleton added a comment - Thanks Knut, those suggestions definitely improve the material. Attached is a revised patch diff, and revised HTML versions of the two pages.
        Bryan Pendleton made changes -
        Attachment docs.diff [ 12429032 ]
        Attachment ctools1004764.html [ 12429033 ]
        Attachment rtoolsijlocale.html [ 12429034 ]
        Hide
        Knut Anders Hatlen added a comment -

        The new HTML files look great. One small typo: there should be a full stop instead of a comma before the last sentence in the "Function" section.

        Show
        Knut Anders Hatlen added a comment - The new HTML files look great. One small typo: there should be a full stop instead of a comma before the last sentence in the "Function" section.
        Hide
        Bryan Pendleton added a comment -

        Fixed the comma typo and committed to the docs trunk as revision 894926.

        Show
        Bryan Pendleton added a comment - Fixed the comma typo and committed to the docs trunk as revision 894926.
        Bryan Pendleton made changes -
        Status Open [ 1 ] Resolved [ 5 ]
        Fix Version/s 10.6.0.0 [ 12313727 ]
        Resolution Fixed [ 1 ]
        Kathey Marsden made changes -
        Status Resolved [ 5 ] Closed [ 6 ]
        Gavin made changes -
        Workflow jira [ 12485050 ] Default workflow, editable Closed status [ 12800097 ]

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            Stan Bradbury
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development