Derby
  1. Derby
  2. DERBY-6121

Regularize how we refer to object names in the Reference Manual

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.10.1.1
    • Fix Version/s: 10.11.0.0, 10.10.2.0
    • Component/s: Documentation
    • Labels:
      None
    • Urgency:
      Normal

      Description

      This issue came up during the buddy testing of user-defined aggregates. Here's what Dag discovered:

      identifiers (seen when looking at GRANT USAGE of aggregates): "table-Name" occurences are linked to a section explainig them (rreftablename.html), but UDA names are defined in-lined as

      GRANT USAGE ON DERBY AGGREGATE [ schemaName. ] SQL92Identifier TO grantees

      In a third variant,

      GRANT EXECUTE ON

      { FUNCTION | PROCEDURE }

      routine-designator TO grantees

      routine-designator is defined locally as

      routine-designator

      { function-name | procedure-name }

      without links to what "function-name" or "procedure-name" might look like. It would be good to harmonize the latter two forms to a central definition as for "table-Name".

      Finally, I noted that the definition page for SchemaName doesn't link to the SQL92Identifier page...

      1. rrefsqlj32268.html
        6 kB
        Kim Haase
      2. DERBY-6121-3.zip
        7 kB
        Kim Haase
      3. DERBY-6121-3.stat
        0.1 kB
        Kim Haase
      4. DERBY-6121-3.diff
        3 kB
        Kim Haase
      5. DERBY-6121-2.zip
        99 kB
        Kim Haase
      6. DERBY-6121-2.stat
        2 kB
        Kim Haase
      7. DERBY-6121-2.diff
        106 kB
        Kim Haase
      8. DERBY-6121.zip
        249 kB
        Kim Haase
      9. DERBY-6121.stat
        4 kB
        Kim Haase
      10. DERBY-6121.diff
        242 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          This issue affects more than the GRANT and REVOKE statements, and could lead to quite a few consistency fixes.

          Several CREATE statement topics specify the syntax for the created object in the topic itself rather than in a separate topic under "SQL identifiers." These include

          CREATE DERBY AGGREGATE statement
          CREATE FUNCTION statement
          CREATE PROCEDURE statement
          CREATE SEQUENCE statement
          CREATE TYPE statement

          I can create separate object-Name topics for each of these. Most of the existing topics have hyphens but some don't – table-Name vs. schemaName, RoleName, etc. I may as well hyphenate the new ones.

          It would probably be helpful to alphabetize the topics under "SQL identifiers." The current order seems semi-random.

          Some of the syntax for other statement topics can then be regularized as well, in addition to that for GRANT and REVOKE.

          Show
          Kim Haase added a comment - This issue affects more than the GRANT and REVOKE statements, and could lead to quite a few consistency fixes. Several CREATE statement topics specify the syntax for the created object in the topic itself rather than in a separate topic under "SQL identifiers." These include CREATE DERBY AGGREGATE statement CREATE FUNCTION statement CREATE PROCEDURE statement CREATE SEQUENCE statement CREATE TYPE statement I can create separate object-Name topics for each of these. Most of the existing topics have hyphens but some don't – table-Name vs. schemaName, RoleName, etc. I may as well hyphenate the new ones. It would probably be helpful to alphabetize the topics under "SQL identifiers." The current order seems semi-random. Some of the syntax for other statement topics can then be regularized as well, in addition to that for GRANT and REVOKE.
          Hide
          Kim Haase added a comment -

          This is not entirely afield from the issue, I hope – are my eyes deceiving me, or do the last two lines in the ReferencingClause syntax specify exactly the same syntax?

          http://db.apache.org/derby/docs/10.10/ref/rrefsqlj89752.html

          Show
          Kim Haase added a comment - This is not entirely afield from the issue, I hope – are my eyes deceiving me, or do the last two lines in the ReferencingClause syntax specify exactly the same syntax? http://db.apache.org/derby/docs/10.10/ref/rrefsqlj89752.html
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          Yes, that does look odd to me. This makes more sense to me:

          REFERENCING
          {

          { OLD | NEW } [ ROW ] [ AS ] correlation-Name [ { OLD | NEW }

          [ ROW ] [ AS ] correlation-Name ] |

          { OLD TABLE | NEW TABLE } [ AS ] Identifier [ { OLD TABLE | NEW TABLE }

          [AS] Identifier ]
          }

          Show
          Rick Hillegas added a comment - Hi Kim, Yes, that does look odd to me. This makes more sense to me: REFERENCING { { OLD | NEW } [ ROW ] [ AS ] correlation-Name [ { OLD | NEW } [ ROW ] [ AS ] correlation-Name ] | { OLD TABLE | NEW TABLE } [ AS ] Identifier [ { OLD TABLE | NEW TABLE } [AS] Identifier ] }
          Hide
          Kim Haase added a comment -

          Thanks, Rick!

          Show
          Kim Haase added a comment - Thanks, Rick!
          Hide
          Kim Haase added a comment - - edited

          Here's another syntax puzzle:

          GRANT roleName [ {, roleName }* ] TO grantees
          

          Can you think why this isn't the following? The curly braces seem pointless within the square ones.

          GRANT roleName [ , roleName ]* TO grantees

          Show
          Kim Haase added a comment - - edited Here's another syntax puzzle: GRANT roleName [ {, roleName }* ] TO grantees Can you think why this isn't the following? The curly braces seem pointless within the square ones. GRANT roleName [ , roleName ]* TO grantees
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          I agree that the syntax you prefer fits better with other examples in the Reference Guide. The other syntax looks more like the BNF used by other, non-Derby documents. I'm not sure where we describe the differences between Derby's modified BNF and the more usual BNF. Thanks.

          Show
          Rick Hillegas added a comment - Hi Kim, I agree that the syntax you prefer fits better with other examples in the Reference Guide. The other syntax looks more like the BNF used by other, non-Derby documents. I'm not sure where we describe the differences between Derby's modified BNF and the more usual BNF. Thanks.
          Hide
          Knut Anders Hatlen added a comment - - edited

          The latter looks cleaner to me, and they are equivalent as far as I can tell.

          Another equivalent alternative is the following:

          GRANT roleName { , roleName }* TO grantees
          

          The square bracket style seems to be the more common one, though, used for example in FROM clause, GROUP BY clause, ORDER BY clause, USING clause. However, the curly style is used two more places in the GRANT statement topic; for privilege-list and column list. We might want to make them consistent.

          Speaking of consistency, I wonder why "privilege-list" has a hyphen whereas "column list" has not.

          [edit: added markup to prevent JIRA from garbling the syntax description]

          Show
          Knut Anders Hatlen added a comment - - edited The latter looks cleaner to me, and they are equivalent as far as I can tell. Another equivalent alternative is the following: GRANT roleName { , roleName }* TO grantees The square bracket style seems to be the more common one, though, used for example in FROM clause, GROUP BY clause, ORDER BY clause, USING clause. However, the curly style is used two more places in the GRANT statement topic; for privilege-list and column list. We might want to make them consistent. Speaking of consistency, I wonder why "privilege-list" has a hyphen whereas "column list" has not. [edit: added markup to prevent JIRA from garbling the syntax description]
          Hide
          Kim Haase added a comment - - edited

          I understand the square brackets to enclose optional items, while the curly braces enclose required items that need to be separated by "|" to indicate choices. That's how I've always used them in syntax sections of compiler docs since the beginning of time (more or less).

          And I was going to say, "We document the modified BNF syntax in the Getting Started Guide, here": http://db.apache.org/derby/docs/10.10/getstart/rgsdocs10012.html

          However, what it says there is incorrect, at least in terms of our customary usage. Looks like a separate JIRA issue.

          I changed the rolename syntax to

           GRANT roleName [ , roleName ]* TO grantees 
          

          I should enclose the privilege-type syntax in curly braces.

          I already changed "column list" to "column-list".

          Show
          Kim Haase added a comment - - edited I understand the square brackets to enclose optional items, while the curly braces enclose required items that need to be separated by "|" to indicate choices. That's how I've always used them in syntax sections of compiler docs since the beginning of time (more or less). And I was going to say, "We document the modified BNF syntax in the Getting Started Guide, here": http://db.apache.org/derby/docs/10.10/getstart/rgsdocs10012.html However, what it says there is incorrect, at least in terms of our customary usage. Looks like a separate JIRA issue. I changed the rolename syntax to GRANT roleName [ , roleName ]* TO grantees I should enclose the privilege-type syntax in curly braces. I already changed "column list" to "column-list".
          Hide
          Rick Hillegas added a comment -

          Thanks for pulling on this ball of yarn, Kim. Maybe the description of the modified BNF syntax should be movied/copied to the Reference Guide. Thanks.

          Show
          Rick Hillegas added a comment - Thanks for pulling on this ball of yarn, Kim. Maybe the description of the modified BNF syntax should be movied/copied to the Reference Guide. Thanks.
          Hide
          Kim Haase added a comment -

          Thanks for that excellent suggestion, Rick! After all, this book is the main place where the syntax is used. It should be added to the "About this guide" section, I think.

          Show
          Kim Haase added a comment - Thanks for that excellent suggestion, Rick! After all, this book is the main place where the syntax is used. It should be added to the "About this guide" section, I think.
          Hide
          Kim Haase added a comment -

          Does anyone have any thoughts one way or the other about whether syntax should use hyphenated lower camel case (table-Name, role-Name) or non-hyphenated lower camel case (tableName, roleName)? Some syntax uses upper camel case (SelectExpression, TableExpression, ScalarSubquery). That's another possibility.

          More of the existing topics are hyphenated than not, but I'm not crazy about the look. This is turning into a rather large syntax overhaul, and we may as well do it right.

          Any preferences?

          Show
          Kim Haase added a comment - Does anyone have any thoughts one way or the other about whether syntax should use hyphenated lower camel case (table-Name, role-Name) or non-hyphenated lower camel case (tableName, roleName)? Some syntax uses upper camel case (SelectExpression, TableExpression, ScalarSubquery). That's another possibility. More of the existing topics are hyphenated than not, but I'm not crazy about the look. This is turning into a rather large syntax overhaul, and we may as well do it right. Any preferences?
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          I prefer non-hyphenated, lower camel case. For me, it's purely esthetic. I don't think I can offer any technical arguments for this preference. Here's my esthetic rank-ordering of the possibilities you listed:

          selectExpression
          select-expression
          SelectExpression
          select-Expression

          Thanks.

          Show
          Rick Hillegas added a comment - Hi Kim, I prefer non-hyphenated, lower camel case. For me, it's purely esthetic. I don't think I can offer any technical arguments for this preference. Here's my esthetic rank-ordering of the possibilities you listed: selectExpression select-expression SelectExpression select-Expression Thanks.
          Hide
          Kim Haase added a comment -

          Thanks for the feedback, Rick! It tallies with my esthetic sense, too. In the absence of contrary advice, I'll go with it.

          Show
          Kim Haase added a comment - Thanks for the feedback, Rick! It tallies with my esthetic sense, too. In the absence of contrary advice, I'll go with it.
          Hide
          Kim Haase added a comment -

          The syntax for the ALTER TABLE topic (http://db.apache.org/derby/docs/10.10/ref/rrefsqlj81859.html) is a bit confusing. Should there be vertical bars (|) after the DROP [COLUMN]... and DROP { PRIMARY KEY ... parts of the syntax? Or can you actually have a DROP COLUMN followed by a DROP on a constraint followed by an ALTER COLUMN? Thanks for any assistance.

          Show
          Kim Haase added a comment - The syntax for the ALTER TABLE topic ( http://db.apache.org/derby/docs/10.10/ref/rrefsqlj81859.html ) is a bit confusing. Should there be vertical bars (|) after the DROP [COLUMN] ... and DROP { PRIMARY KEY ... parts of the syntax? Or can you actually have a DROP COLUMN followed by a DROP on a constraint followed by an ALTER COLUMN? Thanks for any assistance.
          Hide
          Knut Anders Hatlen added a comment -

          It doesn't look like that syntax is supported, so I think you're right that there should be vertical bars after those two parts. Good catch.

          Show
          Knut Anders Hatlen added a comment - It doesn't look like that syntax is supported, so I think you're right that there should be vertical bars after those two parts. Good catch.
          Hide
          Kim Haase added a comment -

          Thanks, Knut. I'll fix the ALTER TABLE syntax. I am also wondering about a couple other syntax sections, in SET SCHEMA (http://db.apache.org/derby/docs/10.10/ref/rrefsqlj32268.html) and SET ISOLATION (http://db.apache.org/derby/docs/10.10/ref/rrefsqlj41180.html).

          The syntax of SET SCHEMA is hard to untangle, and I am wondering if the way I straightened it out (I will attach the file) is correct.

          For SET ISOLATION, the description suggests that SERIALIZABLE is a synonym of RS, so it ought to be on the same line as RS, you might think? Also, you can only have one argument to SET ISOLATION, so I think there need to be vertical bars at the end of each line inside the curly braces?

          These don't actually need to be changed as part of this issue, since there are no changes regarding argument names, so I can file a separate issue if these could use some changes.

          Show
          Kim Haase added a comment - Thanks, Knut. I'll fix the ALTER TABLE syntax. I am also wondering about a couple other syntax sections, in SET SCHEMA ( http://db.apache.org/derby/docs/10.10/ref/rrefsqlj32268.html ) and SET ISOLATION ( http://db.apache.org/derby/docs/10.10/ref/rrefsqlj41180.html ). The syntax of SET SCHEMA is hard to untangle, and I am wondering if the way I straightened it out (I will attach the file) is correct. For SET ISOLATION, the description suggests that SERIALIZABLE is a synonym of RS, so it ought to be on the same line as RS, you might think? Also, you can only have one argument to SET ISOLATION, so I think there need to be vertical bars at the end of each line inside the curly braces? These don't actually need to be changed as part of this issue, since there are no changes regarding argument names, so I can file a separate issue if these could use some changes.
          Hide
          Dag H. Wanvik added a comment -

          The corresponding levels are as follows: ISO vs DB2 nomenclature (cf. http://www.ibm.com/developerworks/data/library/techarticle/dm-1107db2isolationlevel/)

          Serializable RR (repeatable read)
          Repeatable read RS (read stability)
          Read committed CS (cursor stability)
          Read uncommitted UR (uncommitted read)

          Our syntax is a mix of these it seems: SERIALIZABLE obviously refers to the ISO name (synonym RR).
          REPEATABLE READ is a also a synonym for RR, and this is the DB2 meaning of "repeatable read". SO if the user wants ISO REPETABLE READ, he needs to specify RS, confusingly enough.

          So the table is correctly aligned by this layout (according to meaning):

          UR | DIRTY READ | READ UNCOMMITTED
          CS | READ COMMITTED | CURSOR STABILITY
          RS |
          RR | REPEATABLE READ | SERIALIZABLE

          as far as I can tell (see parsing logic in sqlgrammar.jj, ca line 12169. And yes, "|" at the end of the lines.

          Show
          Dag H. Wanvik added a comment - The corresponding levels are as follows: ISO vs DB2 nomenclature (cf. http://www.ibm.com/developerworks/data/library/techarticle/dm-1107db2isolationlevel/ ) Serializable RR (repeatable read) Repeatable read RS (read stability) Read committed CS (cursor stability) Read uncommitted UR (uncommitted read) Our syntax is a mix of these it seems: SERIALIZABLE obviously refers to the ISO name (synonym RR). REPEATABLE READ is a also a synonym for RR, and this is the DB2 meaning of "repeatable read". SO if the user wants ISO REPETABLE READ, he needs to specify RS, confusingly enough. So the table is correctly aligned by this layout (according to meaning): UR | DIRTY READ | READ UNCOMMITTED CS | READ COMMITTED | CURSOR STABILITY RS | RR | REPEATABLE READ | SERIALIZABLE as far as I can tell (see parsing logic in sqlgrammar.jj, ca line 12169. And yes, "|" at the end of the lines.
          Hide
          Kim Haase added a comment -

          Thanks, Dag!

          Show
          Kim Haase added a comment - Thanks, Dag!
          Hide
          Kim Haase added a comment -

          Sorry, here's something else that puzzles me: http://db.apache.org/derby/docs/10.10/ref/rrefsqlj31783.html

          If you can say either FOR READ ONLY, FOR FETCH ONLY, or FOR UPDATE, why does the topic not describe the other two possibilities but only talk about FOR UPDATE? The other two possibilities are described under the SELECT statement, so perhaps they should be mentioned here too?

          Show
          Kim Haase added a comment - Sorry, here's something else that puzzles me: http://db.apache.org/derby/docs/10.10/ref/rrefsqlj31783.html If you can say either FOR READ ONLY, FOR FETCH ONLY, or FOR UPDATE, why does the topic not describe the other two possibilities but only talk about FOR UPDATE? The other two possibilities are described under the SELECT statement, so perhaps they should be mentioned here too?
          Hide
          Kim Haase added a comment -

          Attaching DERBY-6121.diff, DERBY-6121.stat, and DERBY-6121.zip, with 5 new topics and changes to 100 other files including the map file.

          I decided to fix the SET ISOLATION syntax while I was at it, rather than forget to file a new issue for it.

          There are still plenty of syntax inconsistencies, which may become more obvious once these fixes are in.

          Please let me know if this seems like the right direction to go in. If it is, it might make sense to commit this patch and then make additional fixes in smaller patches. For instance, I plan to make another patch to camelcase the arguments in the function topics.

          Show
          Kim Haase added a comment - Attaching DERBY-6121 .diff, DERBY-6121 .stat, and DERBY-6121 .zip, with 5 new topics and changes to 100 other files including the map file. I decided to fix the SET ISOLATION syntax while I was at it, rather than forget to file a new issue for it. There are still plenty of syntax inconsistencies, which may become more obvious once these fixes are in. Please let me know if this seems like the right direction to go in. If it is, it might make sense to commit this patch and then make additional fixes in smaller patches. For instance, I plan to make another patch to camelcase the arguments in the function topics.
          Hide
          Knut Anders Hatlen added a comment -

          The patch looks good to me. +1

          I see that the tableFunctionInvocation topic changes function-name to tableFunctionName, which is not explained. Would it make sense to use functionName instead, and link it to the new functionName topic?

          Show
          Knut Anders Hatlen added a comment - The patch looks good to me. +1 I see that the tableFunctionInvocation topic changes function-name to tableFunctionName, which is not explained. Would it make sense to use functionName instead, and link it to the new functionName topic?
          Hide
          Kim Haase added a comment -

          Thanks, Knut.

          I was wondering what to do about the tableFunctionInvocation topic – a table function is a special type of function, but the function name syntax is the same, of course. I can commit this patch and file another to fix this item (and anything else anyone notices).

          I am wondering whether to commit this patch to both the trunk and the 10.10 branch or just to the trunk. The change is kind of disruptive and almost the equivalent of a new feature, for docs. On the other hand, committing it to the branch will not result in any invalid information or break anything. Any thoughts?

          Show
          Kim Haase added a comment - Thanks, Knut. I was wondering what to do about the tableFunctionInvocation topic – a table function is a special type of function, but the function name syntax is the same, of course. I can commit this patch and file another to fix this item (and anything else anyone notices). I am wondering whether to commit this patch to both the trunk and the 10.10 branch or just to the trunk. The change is kind of disruptive and almost the equivalent of a new feature, for docs. On the other hand, committing it to the branch will not result in any invalid information or break anything. Any thoughts?
          Hide
          Rick Hillegas added a comment -

          I wonder if we'll see another kind of disruption if we don't commit this patch to the 10.10 branch. That is, disruption caused by the divergence in so many grammar descriptions. I would vote for backporting this to 10.10. Thanks.

          Show
          Rick Hillegas added a comment - I wonder if we'll see another kind of disruption if we don't commit this patch to the 10.10 branch. That is, disruption caused by the divergence in so many grammar descriptions. I would vote for backporting this to 10.10. Thanks.
          Hide
          Kim Haase added a comment -

          Thanks for that perspective, Rick. I'll do the backport.

          Show
          Kim Haase added a comment - Thanks for that perspective, Rick. I'll do the backport.
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Major update of Reference Manual syntax formats; added 5 topics, modified 100.

          Patch: DERBY-6121.diff

          Show
          ASF subversion and git services added a comment - Commit 1527587 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1527587 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Major update of Reference Manual syntax formats; added 5 topics, modified 100. Patch: DERBY-6121 .diff
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Major update of Reference Manual syntax formats; added 5 topics, modified 100.

          Patch: DERBY-6121.diff

          Show
          ASF subversion and git services added a comment - Commit 1527587 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1527587 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Major update of Reference Manual syntax formats; added 5 topics, modified 100. Patch: DERBY-6121 .diff
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Merged patch DERBY-6121.diff to 10.10 doc branch from trunk revision 1527587.

          Show
          ASF subversion and git services added a comment - Commit 1527603 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1527603 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Merged patch DERBY-6121 .diff to 10.10 doc branch from trunk revision 1527587.
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Merged patch DERBY-6121.diff to 10.10 doc branch from trunk revision 1527587.

          Show
          ASF subversion and git services added a comment - Commit 1527603 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1527603 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Merged patch DERBY-6121 .diff to 10.10 doc branch from trunk revision 1527587.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-6121.diff to documentation trunk at revision 1527587.
          Merged to 10.10 doc branch at revision 1527603.

          I'm going to submit a patch for the functions and for Knut's recommendation about functionName.

          Show
          Kim Haase added a comment - Committed patch DERBY-6121 .diff to documentation trunk at revision 1527587. Merged to 10.10 doc branch at revision 1527603. I'm going to submit a patch for the functions and for Knut's recommendation about functionName.
          Hide
          Kim Haase added a comment -

          Here's the second stage of these fixes. The attached patch, DERBY-6121-2.diff, DERBY-6121-2.stat, and DERBY-6121-2.zip, makes the object names and formatting more consistent in the built-in functions section of the Reference Manual, in the JDBC escape syntax topics, and in two other JDBC topics.

          I also made the fix Knut suggested to the tableFunctionInvocation topic (rrefsqljtfinvoke.html).

          A couple of additional notes:

          1) I took the liberty of changing "cotangens" to "cotangent" in the topic on the COT function (rreffunccot.html). I think "cotangens" is the term in some languages – not English, though.

          2) The topic on the CHAR function (rrefbuiltchar.html) mentions using the "DECIMAL scalar function". I can't find any reference to this function. Do you have any idea what is being referred to here? There's a long list of scalar functions in "JDBC escape syntax for fn keyword" (rrefjdbc88908.html), but "decimal" is not among them.

          3) I notice that for all the functions that take a DOUBLE argument, there is a link to the topic on that data type. Topics that take other kinds of arguments often don't link to the topics on those data types (see the DATE function topic, rrefdatefunc.html, or the LTRIM function topic, rrefsqlj97870.html, for example). Would it be useful to add these links? Or should we not bother?

          4) The bullet lists in two of the JDBC topics, rrefpgc1.html and rrefcrsrgpc1.html should arguably be tables. This could be a separate issue, though. (In the book they are subtopics of the topic on the DatabaseMetaData interface.)

          Thanks in advance for your feedback.

          Show
          Kim Haase added a comment - Here's the second stage of these fixes. The attached patch, DERBY-6121 -2.diff, DERBY-6121 -2.stat, and DERBY-6121 -2.zip, makes the object names and formatting more consistent in the built-in functions section of the Reference Manual, in the JDBC escape syntax topics, and in two other JDBC topics. I also made the fix Knut suggested to the tableFunctionInvocation topic (rrefsqljtfinvoke.html). A couple of additional notes: 1) I took the liberty of changing "cotangens" to "cotangent" in the topic on the COT function (rreffunccot.html). I think "cotangens" is the term in some languages – not English, though. 2) The topic on the CHAR function (rrefbuiltchar.html) mentions using the "DECIMAL scalar function". I can't find any reference to this function. Do you have any idea what is being referred to here? There's a long list of scalar functions in "JDBC escape syntax for fn keyword" (rrefjdbc88908.html), but "decimal" is not among them. 3) I notice that for all the functions that take a DOUBLE argument, there is a link to the topic on that data type. Topics that take other kinds of arguments often don't link to the topics on those data types (see the DATE function topic, rrefdatefunc.html, or the LTRIM function topic, rrefsqlj97870.html, for example). Would it be useful to add these links? Or should we not bother? 4) The bullet lists in two of the JDBC topics, rrefpgc1.html and rrefcrsrgpc1.html should arguably be tables. This could be a separate issue, though. (In the book they are subtopics of the topic on the DatabaseMetaData interface.) Thanks in advance for your feedback.
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          Looks nice. +1 to this increment. A couple comments follow:

          o I wonder if "JOIN operations" should be "joinOperation" in rrefjdbc37244.

          Some responses to your questions:

          > 2) The topic on the CHAR function (rrefbuiltchar.html) mentions using
          > the "DECIMAL scalar function". I can't find any reference to this
          > function. Do you have any idea what is being referred to here?
          > There's a long list of scalar functions in "JDBC escape syntax for fn
          > keyword" (rrefjdbc88908.html), but "decimal" is not among them.

          I can't find any reference to a DECIMAL scalar function in the current Reference Manual or in the Reference Manuals for Cloudscape 3.5 or 5.1. However, I see that DB2 supports such a function: https://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?topic=%2Fcom.ibm.db2.udb.admin.doc%2Fdoc%2Fr0000791.htm Maybe this is left over from a Cloudscape version produced after 5.1 but before Derby was open-sourced. I would recommend striking this confusing sentence.

          > 3) I notice that for all the functions that take a DOUBLE argument,
          > there is a link to the topic on that data type. Topics that take other
          > kinds of arguments often don't link to the topics on those data types
          > (see the DATE function topic, rrefdatefunc.html, or the LTRIM function
          > topic, rrefsqlj97870.html, for example). Would it be useful to add
          > these links? Or should we not bother?

          It is puzzling that this is only done regularly for DOUBLE PRECISION. Note that rreffuncrand hot-links to both DOUBLE PRECISION and INTEGER. My question would be: where do we draw the line? Do we want to go through the whole Reference Manual and regularize this? I can see that these hotlinks are convenient but I'm not sure this is worth doing if it's a big rototill.

          Thanks,
          -Rick

          Show
          Rick Hillegas added a comment - Hi Kim, Looks nice. +1 to this increment. A couple comments follow: o I wonder if "JOIN operations" should be "joinOperation" in rrefjdbc37244. Some responses to your questions: > 2) The topic on the CHAR function (rrefbuiltchar.html) mentions using > the "DECIMAL scalar function". I can't find any reference to this > function. Do you have any idea what is being referred to here? > There's a long list of scalar functions in "JDBC escape syntax for fn > keyword" (rrefjdbc88908.html), but "decimal" is not among them. I can't find any reference to a DECIMAL scalar function in the current Reference Manual or in the Reference Manuals for Cloudscape 3.5 or 5.1. However, I see that DB2 supports such a function: https://publib.boulder.ibm.com/infocenter/db2luw/v9/index.jsp?topic=%2Fcom.ibm.db2.udb.admin.doc%2Fdoc%2Fr0000791.htm Maybe this is left over from a Cloudscape version produced after 5.1 but before Derby was open-sourced. I would recommend striking this confusing sentence. > 3) I notice that for all the functions that take a DOUBLE argument, > there is a link to the topic on that data type. Topics that take other > kinds of arguments often don't link to the topics on those data types > (see the DATE function topic, rrefdatefunc.html, or the LTRIM function > topic, rrefsqlj97870.html, for example). Would it be useful to add > these links? Or should we not bother? It is puzzling that this is only done regularly for DOUBLE PRECISION. Note that rreffuncrand hot-links to both DOUBLE PRECISION and INTEGER. My question would be: where do we draw the line? Do we want to go through the whole Reference Manual and regularize this? I can see that these hotlinks are convenient but I'm not sure this is worth doing if it's a big rototill. Thanks, -Rick
          Hide
          Kim Haase added a comment -

          Thanks, Rick! I will commit this and then file a patch for the additional changes you suggest.

          About JOIN operations links – the usage there is consistent with what we have in the tableExpression topic, though it should be singular, actually. But it would make sense to change both of them to use "joinOperation".

          Thanks for the info about the probable history behind that reference to the DECIMAL scalar function. I'll remove the sentence.

          I am fine with remaining inconsistent in our links to data type topics. The topics are easy to find if a reader wants the info.

          Show
          Kim Haase added a comment - Thanks, Rick! I will commit this and then file a patch for the additional changes you suggest. About JOIN operations links – the usage there is consistent with what we have in the tableExpression topic, though it should be singular, actually. But it would make sense to change both of them to use "joinOperation". Thanks for the info about the probable history behind that reference to the DECIMAL scalar function. I'll remove the sentence. I am fine with remaining inconsistent in our links to data type topics. The topics are easy to find if a reader wants the info.
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Modified 45 topics in Reference Manual – functions, JDBC.

          Patch: DERBY-6121-2.diff

          Show
          ASF subversion and git services added a comment - Commit 1528945 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1528945 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Modified 45 topics in Reference Manual – functions, JDBC. Patch: DERBY-6121 -2.diff
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Modified 45 topics in Reference Manual – functions, JDBC.

          Patch: DERBY-6121-2.diff

          Show
          ASF subversion and git services added a comment - Commit 1528945 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1528945 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Modified 45 topics in Reference Manual – functions, JDBC. Patch: DERBY-6121 -2.diff
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Merged patch DERBY-6121-2.diff to 10.10 doc branch from trunk revision 1528945.

          Show
          ASF subversion and git services added a comment - Commit 1528947 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1528947 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Merged patch DERBY-6121 -2.diff to 10.10 doc branch from trunk revision 1528945.
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Merged patch DERBY-6121-2.diff to 10.10 doc branch from trunk revision 1528945.

          Show
          ASF subversion and git services added a comment - Commit 1528947 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1528947 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Merged patch DERBY-6121 -2.diff to 10.10 doc branch from trunk revision 1528945.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-6121-2.diff to documentation trunk at revision 1528945.
          Merged to 10.10 doc branch at revision 1528947.

          Leaving open for the next little patch.

          Show
          Kim Haase added a comment - Committed patch DERBY-6121 -2.diff to documentation trunk at revision 1528945. Merged to 10.10 doc branch at revision 1528947. Leaving open for the next little patch.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-6121-3.diff, DERBY-6121-3.stat, and DERBY-6121-3.zip, with changes to the CHAR function topic and to two topics that reference the JOIN operations topic:

          M src/ref/rrefbuiltchar.dita
          M src/ref/rrefjdbc37244.dita
          M src/ref/rreftableexpression.dita

          I will go ahead and commit these. Thanks for all the feedback, everyone.

          Show
          Kim Haase added a comment - Attaching DERBY-6121 -3.diff, DERBY-6121 -3.stat, and DERBY-6121 -3.zip, with changes to the CHAR function topic and to two topics that reference the JOIN operations topic: M src/ref/rrefbuiltchar.dita M src/ref/rrefjdbc37244.dita M src/ref/rreftableexpression.dita I will go ahead and commit these. Thanks for all the feedback, everyone.
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Modified 3 topics in Reference Manual.

          Patch: DERBY-6121-3.diff

          Show
          ASF subversion and git services added a comment - Commit 1528981 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1528981 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Modified 3 topics in Reference Manual. Patch: DERBY-6121 -3.diff
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Modified 3 topics in Reference Manual.

          Patch: DERBY-6121-3.diff

          Show
          ASF subversion and git services added a comment - Commit 1528981 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1528981 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Modified 3 topics in Reference Manual. Patch: DERBY-6121 -3.diff
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Merged patch DERBY-6121-3.diff to 10.10 doc branch from trunk revision 1528981.

          Show
          ASF subversion and git services added a comment - Commit 1528983 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1528983 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Merged patch DERBY-6121 -3.diff to 10.10 doc branch from trunk revision 1528981.
          Hide
          ASF subversion and git services added a comment -

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

          DERBY-6121 Regularize how we refer to object names in the Reference Manual

          Merged patch DERBY-6121-3.diff to 10.10 doc branch from trunk revision 1528981.

          Show
          ASF subversion and git services added a comment - Commit 1528983 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1528983 ] DERBY-6121 Regularize how we refer to object names in the Reference Manual Merged patch DERBY-6121 -3.diff to 10.10 doc branch from trunk revision 1528981.
          Hide
          Kim Haase added a comment -

          I think I can actually resolve this now.

          Committed patch DERBY-6121-3.diff to documentation trunk at revision 1528981.
          Merged to 10.10 doc branch at revision 1528983.

          Show
          Kim Haase added a comment - I think I can actually resolve this now. Committed patch DERBY-6121 -3.diff to documentation trunk at revision 1528981. Merged to 10.10 doc branch at revision 1528983.

            People

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

              Dates

              • Created:
                Updated:
                Resolved:

                Development