db-derby-dev mailing list archives

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

    [ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13022895#comment-13022895
] 

Kim Haase commented on DERBY-5184:
----------------------------------

Thanks so much, Rick! Most of your suggestions are very straightforward. A few comments/questions
--

JDBCTypePrinter.java produces some odd output -- it does show SMALLINT as 5, but it shows
BIGINT as -5 and INTEGER as 4, among other things, so it seems not quite reliable?

rrefjdbc75719.dita: I thought about removing that INOUT table, since it seems so out of date.
However, the correspondences are not exact. Sometimes they would need to use an array of the
type in Column 2 and sometimes the type in Column 3 of the Arg Matching table. I'd also have
to emphasize that the parameter must be an array of the type. Also, some of the JDBC types
are not listed in the Argument Matching table (BINARY, LONGVARBINARY, VARBINARY, which correspond
to CHAR FOR BIT DATA, LONG VARCHAR FOR BIT DATA, VARCHAR FOR BIT DATA). So I may as well stick
with modifying the existing table.

For OTHER should I perhaps substitute User-defined type? Or is that not appropriate here?

rrefjdbc20377.html: I don't see a java.sql.BOOLEAN. I think it is just BOOLEAN (the constant
in java.sql.Types)?


> 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