You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Rick Hillegas (JIRA)" <ji...@apache.org> on 2007/09/14 00:04:35 UTC
[jira] Created: (DERBY-3072) User documentation for Table Functions
User documentation for Table Functions
--------------------------------------
Key: DERBY-3072
URL: https://issues.apache.org/jira/browse/DERBY-3072
Project: Derby
Issue Type: New Feature
Components: Documentation
Reporter: Rick Hillegas
This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Dag H. Wanvik (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12528406 ]
Dag H. Wanvik commented on DERBY-3072:
--------------------------------------
Thanks for providing the docs, Rick. Just some initial comments:
* Should the docs show an example that actually implements the
ResultSet interface (the current example passes on one from another
driver)? Maybe adding a worked example to demos would be good,
and just add a pointer in the docs. What level of JDBC ResultSet
(2,3 or 4) is implemented doesn't matter as far as I understand, but
maybe that fact should be called out explicitly.
* The description for VTICosting override:
getEstimatedCostPerInstantiation
doesn't mention what units cost is expressed in. I know this is a bit
vague in Derby, but I think the docs should attempt some kind of
guidance. The interface source code doesn't speak about it either as
far as I can see (default is 100000, but unit is unclear).
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12528810 ]
Kim Haase commented on DERBY-3072:
----------------------------------
This is great work, Rick -- you've structured the new topics very well, and they are clear and well written. The tuning topics are amazingly clear for such complex material. Here are some suggestions for improvement. Any topic with no comments is just fine.
Global nit: According to the rules about restrictive and nonrestrictive clauses as I learned them, "which" should be "that" in every location where it is used in these topics. (Briefly, if the sentence would be meaningless without the clause, use "that"; if the clause adds nonessential information, use "which" and set it off with commas.)
Tuning Guide comments:
I think you may need to change one more file, the parent file of the new performance tips file. The parent file is "The tips," ctunperf25864.dita. It contains a manually created list of subtopics, with additional verbiage, in addition to the autogenerated list at the bottom. So you'd need to add your new topic there.
ctunperftablefunctions.html:
I'm wondering about "to cost" as a verb, from the point of view of translation. Maybe "how to cost a ..." could be "how to calculate the cost of a ..." You could also make the index terms similar to the ones for cdevspecialtfopttune.dita.
I think we try to talk about topics rather than sections, but to avoid the whole issue you could just say
See "Programming Derby-style table functions" in the Derby Developer's Guide.
Developer's Guide comments:
cdevspecialtabfuncs.html:
Paragraph 1: In the second sentence, "These" lacks a referent; when you are introducing a topic it helps to be crystal clear. (This rule doesn't matter much, since the meaning is clear regardless; it's just an FYI.) In the third sentence, "xml" should be "XML". So I'd suggest the following:
Derby lets you create table functions. Table functions are functions that package up external data to look like Derby tables. The external data can be an XML file, a table in a foreign database, a live data feed--in short, any information source that can be presented as a JDBC ResultSet.
Paragraph 2: It seems awkward to have a clause in between "the following data sources" and the list of the data sources. It might be clearer to swap them and use a sub-bullet list, like this:
For example, Derby-style table functions let you do the following:
* Perform a bulk import of foreign data into local Derby tables
* Join Derby tables with any of the following data sources:
* XML-formatted reports and logs
* Queries that have been run in foreign databases
* Streaming data from sensors
* RSS feeds
(I don't know that "bulk import" is a well-known verb -- in the Tools guide, it is a noun; list items that aren't sentences shouldn't end with periods; "XML" again; and "run" can be either a participle or a verb, so it should be disambiguated.)
Paragraph 3: The following might be clearer:
See "CREATE FUNCTION statement" in the Derby Reference Manual for the complete syntax needed to declare Derby-style table functions. The following topics provide information on how to write Java methods that wrap foreign data sources inside ResultSets.
cdevspecialtfbasic.html:
Paragraph 2: Do you think "may be stubbed out and simply raise exceptions" will be completely clear even to non-native speakers of English? I'm wondering if the following (or something similar) would be clearer:
Most of the ResultSet methods can be written as stubs that do nothing but throw exceptions.
4th bullet: It's not clear what the XXX in getXXX means until you look at the linked-to topic. Would it be helpful to say the following?
...Derby calls a getXXX() method on each referenced column, where XXX is the column's data type.
In the example, you might line up the table data types vertically if you can.
Elsewhere we say "FROM list" instead of "from-list"; also, the passive verbs in this sentence make it rather convoluted, so how about the following?
To invoke the table function, wrap it with [in??] a TABLE constructor in the FROM list of a query.
cdevspecialtfgetxxx.html:
I think "data type" is the more common form. Also, in text you'd want to put "getXXX()" in italics as you do in the parent topic. And in the second sentence, add "method":
While scanning a Derby-style table function, Derby calls a preferred getXXX() method for each column, based on the column's data type.
The following table lists the preferred getXXX() method for each Derby data type.
cdevspecialtfexample.html:
The first sentence is not very substantive. It might be more economical to have just one sentence saying something like
The following simple table function selects rows from a foreign database.
cdevspecialtfoptimizer.html:
Paragraph 1: I think we usually say "topic" rather than "section".
Bullet item 1: From the point of view of the translator or non-native speaker of English, "inclines" may be a somewhat unusual word. How about
Therefore, the optimizer is likely to place ...
Bullet item 2: Participial and gerund phrases (such as "Knowing ...") are often ambiguous. How about
If it knows that a table function is repeatable, the optimizer can place ...
I'm not sure about "siphoning" -- is "putting" incorrect or too boring?
Bullet item 1 (new bullet list): You might spell out "no-argument".
Bullet item 2: Are there javadocs for the VTICosting interface? I'm not sure they would be available in the commonest (bin) distribution of Derby, since that has only the JDBC javadocs as far as I know. If they are reachable somewhere, you might provide a pointer. I think you've done a great job providing all the information people need, though.
It might be helpful to add xref links in the second sentence as follows:
This involves implementing the following methods, as described in Measuring the cost of Derby-style table functions and Example VTICosting implementation:
Even though the generated HTML includes links to those subtopics at the end of this topic, it would still be reassuring to clarify that the needed info is available there.
In the three sub-bullets, you might want to change "This" to "This method".
First sub-bullet: I don't see any mention of STARTUP and SCAN in the two subtopics. What is the relationship between these terms and the values mentioned in "Measuring the cost of Derby-style table functions"? The value returned by getEstimatedCostPerInstantiation() doesn't look like a sum of two values to me, so I'm a bit confused.
cdevspecialtfopttune.html:
You might want to create some sections within this topic, because right now the transitions from one part to another are not entirely clear. For example, you might put the part beginning "We treat optimizer Imprecision as a constant ..." in a section called "Calculating the optimizer's Imprecision", and you might put the part beginning "The following formula explains how to compute the Actual runtime cost ..." in a section called "Calculating the Actual run time for the table function". Finally. you might put the part beginning "Putting all of this together ..." in a section called "Computing the value returned by getEstimatedCostPerInstantiation()".
"Short-circuit" bullet: Would it be helpful to give an example of how to do this? Would all of your audience know? Also, I think "next()" should be in italics. And "table function" is not capitalized elsewhere in this topic, so should it be capitalized here?
"Record" bullet" (two occurrences): Should VTIResultSet be in italics?
At the end, since you've broken down the A value, wouldn't it be consistent to break down the I value too? That would make the formula
C = O/T * [ ( P * N ) + E ]
cdevspecialtfoptexample.html:
Paragraph 1: Again, saying that something is easy is not very substantive (and may not have the reassuring effect that was probably intended). Maybe something like
Once you have measured your table function's cost, you can write the VTICosting methods.
Reference Manual comments:
rrefcreatefunctionstatement.html:
In the TableType section, again, you might want to cut "the section on" and just say
For more information, see "Programming Derby-style table functions" in the Derby Developer's Guide.
In the third paragraph of the ParameterStyle section, I don't think DERBY_JDBC_RESULT_SET and JAVA need to be in italics here.
rrefsqljtfinvoke.html:
I assume you made a deliberate decision to place this new topic as a subtopic of "TableViewOrFunctionExpression" rather than to move it up to the "SQL identifiers" topic, where all the other xrefs in the syntax statement can be found (table-Name, view-Name, etc.). If the parent topic will always be the only topic that refers to this topic, that makes sense, I guess. However, I believe this is a deeper level of topic nesting than occurs anywhere else in this manual.
DITA note: I believe an example element can contain paragraphs, so you don't have to structure the topic example/section/example; it can be all one example with a paragraph in the middle. Unimportant, though; doesn't affect the look of the output.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-3072) User documentation for Table Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-3072:
---------------------------------
Attachment: derby-3072-02-jsr169-ab.diff
derby-3072-02-jsr169-ab.tar
Thanks for the quick review, Kim. I've managed to turn off the boldness on the third column--it turned out that in addtion to your advice, I needed to adjust the table header. I made the copyedits you suggested, too. Attaching a new rev of this patch with these changes: derby-3072-02-jsr169-ab.diff and a corresponding tarball containing the ouput html.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar, derby-3072-02-jsr169-ab.diff, derby-3072-02-jsr169-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Closed: (DERBY-3072) User documentation for Table Functions
Posted by "Dyre Tjeldvoll (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Dyre Tjeldvoll closed DERBY-3072.
---------------------------------
I believe this is complete.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar, derby-3072-02-jsr169-ab.diff, derby-3072-02-jsr169-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-3072) User documentation for Table Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-3072:
---------------------------------
Attachment: derby-3072-02-jsr169-aa.tar
derby-3072-02-jsr169-aa.diff
Attaching derby-3072-02-jsr169-aa.diff and a corresponding tarball containing the resulting html output (1 file). This adjusts the documentation on the getXXX() methods which Derby calls for table function columns. The adjustment reflects the fact that Derby calls getString() for DECIMAL and NUMERIC columns on JSR 169 platforms rather than getBigDecimal(). See DERBY-3135.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12536284 ]
Kim Haase commented on DERBY-3072:
----------------------------------
The content looks great, Rick, but there seems to be a problem with the table formatting. I don't think you intended all the contents of the third column to be in bold, did you? I cannot tell why that happened, but I do notice that the third column has the same colname value ("2") as the second column, in each row. You might want to name it "3" and see what happens.
Also, some consistency nits (feel free to ignore if they seem too picky):
1) "Same" should be initial-capped in each row, as "Not supported" is. (You could remove the initial cap from "Not supported", but it's more consistent with common doc conventions to start the column text with a capital.
2) "Not supported (two instances) should not have a period at the end. (Again, you could put a period at the end of "Same", but doc conventions normally say don't put a period at the end of table cell content if it's not a sentence.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-3072) User documentation for Table Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-3072:
---------------------------------
Derby Info: [Patch Available]
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-3072) User documentation for Table Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-3072:
---------------------------------
Attachment: derby-3072-01-basic-aa.tar
derby-3072-01-basic-aa.diff
Attaching derby-3072-01-basic-aa.diff and the corresponding html output, derby-3072-01-basic-aa.tar. This is a first cut at writing the user documentation for table functions, as laid out in the Documentation section of the functional spec attached to DERBY-716. Touches the following files:
M src/tuning/tuningderby.ditamap
A src/tuning/ctunperftablefunctions.dita
A src/devguide/cdevspecialtfopttune.dita
M src/devguide/cdevspecial.dita
A src/devguide/cdevspecialtfoptexample.dita
M src/devguide/derbydev.ditamap
A src/devguide/cdevspecialtabfuncs.dita
A src/devguide/cdevspecialtfbasic.dita
A src/devguide/cdevspecialtfgetxxx.dita
A src/devguide/cdevspecialtfoptimizer.dita
A src/devguide/cdevspecialtfexample.dita
A src/ref/rrefsqljtfinvoke.dita
M src/ref/rreftableexpression.dita
M src/ref/rrefsqlj33215.dita
M src/ref/refderby.ditamap
M src/ref/rrefcreatefunctionstatement.dita
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12530848 ]
Kim Haase commented on DERBY-3072:
----------------------------------
(Belatedly) The fixed files look great, Rick.
Yup, that link offers a very good summary of the which/that issue. Shakespeare and E.M. Forster ignored the distinction. But if I were in their league, I wouldn't be here. ;)
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Resolved: (DERBY-3072) User documentation for Table
Functions
Posted by "Dyre Tjeldvoll (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Dyre Tjeldvoll resolved DERBY-3072.
-----------------------------------
Resolution: Fixed
I think this is done
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar, derby-3072-02-jsr169-ab.diff, derby-3072-02-jsr169-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12536309 ]
Rick Hillegas commented on DERBY-3072:
--------------------------------------
Thanks, Kim. Committed at subversion revision 586573.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar, derby-3072-02-jsr169-ab.diff, derby-3072-02-jsr169-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12529408 ]
Rick Hillegas commented on DERBY-3072:
--------------------------------------
Committed derby-3072-01-basic.ab.diff at subversion revision 578086. This incorporates Kim's feedback.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12536301 ]
Kim Haase commented on DERBY-3072:
----------------------------------
It looks perfect now. Glad you figured out the table header problem -- I was stumped.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar, derby-3072-02-jsr169-ab.diff, derby-3072-02-jsr169-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (DERBY-3072) User documentation for Table
Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12528911 ]
Rick Hillegas commented on DERBY-3072:
--------------------------------------
Thanks for the review, Dag. I agree that the example table function doesn't show the tricky bits of stubbing out ResultSet methods. I think what I would like to do is this: check in my demo code (for my Apachecon talk) and then point the user guide at the demo code. I think this will give the user an extensive example of how to write table functions.
I don't know how to improve the description of optimizer units. They are sort of measures of milliseconds scaled by an environment-specific imprecision factor. Would it help to say that? Better words are welcome.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-3072) User documentation for Table Functions
Posted by "Dyre Tjeldvoll (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Dyre Tjeldvoll updated DERBY-3072:
----------------------------------
Derby Info: (was: [Patch Available])
Unchecking 'Patch available' since all patches seem to have been committed.
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar, derby-3072-02-jsr169-aa.diff, derby-3072-02-jsr169-aa.tar, derby-3072-02-jsr169-ab.diff, derby-3072-02-jsr169-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Updated: (DERBY-3072) User documentation for Table Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas updated DERBY-3072:
---------------------------------
Attachment: derby-3072-01-basic-ab.diff
derby-3072-01-basic-ab.tar
Thanks for the extensive review, Kim. I have attached a new rev addressing the issues you raised: derby-3072-01-basic-ab.diff and the corresponding tarball of output files, derby-3072-01-basic-ab.tar.
On the whole, I made most of the changes you suggested, with the following exceptions:
- Usage of "which" vs. "that". Thank you for opening my eyes to the controversy which is swirling around this issue. See for instance, http://www.worldwidewords.org/articles/which.htm This reminds me of the controversy which erupted over the use of "like" as a conjunction a couple decades ago. It was a perfectly acceptable usage in Middle English, then it fell out of favor a couple hundred years ago, then it crept back into vogue in the last century, and now we all have to agree to disagree. I'm afraid that I am going to persist in my cussed, hillbilly ways.
- I have kept the topic nesting as is in the Reference Guide. We can move the TABLE constructor topic around when we introduce new usages for it.
Your advice has made this material much easier to read. Thanks!
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
> Attachments: derby-3072-01-basic-aa.diff, derby-3072-01-basic-aa.tar, derby-3072-01-basic-ab.diff, derby-3072-01-basic-ab.tar
>
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Assigned: (DERBY-3072) User documentation for Table
Functions
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-3072?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Rick Hillegas reassigned DERBY-3072:
------------------------------------
Assignee: Rick Hillegas
> User documentation for Table Functions
> --------------------------------------
>
> Key: DERBY-3072
> URL: https://issues.apache.org/jira/browse/DERBY-3072
> Project: Derby
> Issue Type: New Feature
> Components: Documentation
> Reporter: Rick Hillegas
> Assignee: Rick Hillegas
>
> This issue tracks changes to the user guides to describe table functions. This is the work needed for the "Documentation" section of the functional spec attached to DERBY-716.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.