[jira] [Updated] (DERBY-5184) Tables in documentation need introductions and formatting fixes

["Rick Hillegas (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Rick Hillegas updated DERBY-5184:
---------------------------------

    Attachment: JDBCTypePrinter.java

Hi Kim,

Here are some answers to your questions.

>SYSCS_DIAG diagnostic tables and functions (http://db.apache.org/derby/docs/dev/ref/rrefsyscsdiagtables.html)
>
>I missed the second table on this page, which has a number of empty cells, when I was working on DERBY-5154. It's just like the system tables and XPLAIN tables, so I put the same values in (19 for BIGINT, 10 for INTEGER). I deduced that SMALLINT is 5. Is that right?

Right. I'm attaching JDBCTypePrinter.java. This program prints out the values of the java.sql.Types constants.

>CallableStatements and INOUT Parameters (http://db.apache.org/derby/docs/dev/ref/rrefjdbc75719.html)
>
>Last row, "JAVA_OBJECT (only valid in Java2/JDBC 2.0 environments)": should this parenthesis be removed, or the entire row? If the type exists in 2.0 and above, it's always valid; if it exists in 2.0 only, it's now unsupported and should be removed entirely.

Right. The parenthesis should be removed because we no longer support running Derby in JDBC 2.0 environments. In addition, the BIT data type should be replaced with BOOLEAN. Also, the BLOB and CLOB types should be documented. Also, I don't know what the OTHER type corresponds to. In general, this section presents some of the information found in the "Argument matching" section (http://db.apache.org/derby/docs/dev/ref/rrefsqljargmatching.html). Maybe we should remove the table from "CallableStatements and INOUT Parameters" and just point at "Argument matching".

>Mapping of java.sql.Types to SQL types (http://db.apache.org/derby/docs/dev/ref/rrefjdbc20377.html)
>
>Footnote on BIT row says, "BIT is only valid in JDBC 2.0 and earlier environments." Shouldn't this row be removed now, along with the footnote? Also, parentheses that say "(JDBC 2.0 and up) should be removed, right?

Right, the JDBC 2.0 verbiage should be removed because we no longer support Derby in those environments. The BIT data type should be whacked and replaced with java.sql.BOOLEAN, which corresponds to the SQL BOOLEAN data type.

>Supported territories (http://db.apache.org/derby/docs/dev/ref/rrefsqlj75638.html)
>
>What's "derby.territory"? I know of no such property. Remove? Replace with the territory=ll_CC URL attribute?

Right. This should be a reference to the territory attribute.

>Limitations for database manager values (http://db.apache.org/derby/docs/dev/ref/rrefdbmlimits.html)
>
>What's a database manager? Outside of this topic it is mentioned only in the CREATE FUNCTION and CREATE PROCEDURE topics. Is there another more commonly used term?

I would just say "database".

Thanks,
-Rick


> Tables in documentation need introductions and formatting fixes
> ---------------------------------------------------------------
>
>                 Key: DERBY-5184
>                 URL: https://issues.apache.org/jira/browse/DERBY-5184
>             Project: Derby
>          Issue Type: Sub-task
>          Components: Documentation
>    Affects Versions: 10.7.1.1
>            Reporter: Kim Haase
>            Assignee: Kim Haase
>            Priority: Minor
>         Attachments: JDBCTypePrinter.java
>
>
> Many tables in the Derby documentation appear abruptly, with conceptual prose followed immediately by a table (with or without a title). Here are some examples:
> http://db.apache.org/derby/docs/dev/devguide/devguide-single.html#tdevupgradedb
> http://db.apache.org/derby/docs/dev/adminguide/adminguide-single.html#cadminappsclient
> http://db.apache.org/derby/docs/dev/ref/ref-single.html#rrefjdbc27734
> There is no specific accessibility requirement that tables be properly introduced, but many companies' technical writing style guides require or strongly recommend it. Moreover, the WCAG guidelines have the following statements (http://www.w3.org/TR/WCAG10/#context-and-orientation):
> "Content developers should make content understandable and navigable. This includes not only making the language clear and simple, but also providing understandable mechanisms for navigating within and between pages. Providing navigation tools and orientation information in pages will maximize accessibility and usability. ... The theme of making content understandable and navigable is addressed primarily in guidelines 12 to 14."
> Therefore, in the interest of accessibility, each table should be introduced with some indication that a table is coming. 
> Further details will be provided in comments.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira