db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Rick Hillegas (JIRA)" <j...@apache.org>
Subject [jira] [Updated] (DERBY-5184) Tables in documentation need introductions and formatting fixes
Date Thu, 21 Apr 2011 13:14:05 GMT

     [ 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

Mime
View raw message