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 "Kim Haase (JIRA)" <ji...@apache.org> on 2011/04/08 19:28:06 UTC
[jira] [Created] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
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
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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13027070#comment-13027070 ]
Kim Haase commented on DERBY-5184:
----------------------------------
Committed patch DERBY-5184-tools.diff to documentation trunk at revision 1097872.
Merged to 10.8 doc branch at revision 1097878.
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Resolved] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase resolved DERBY-5184.
------------------------------
Resolution: Fixed
Fix Version/s: 10.9.0.0
10.8.1.3
Issue & fix info: (was: [Patch Available])
Committed patch DERBY-5184-ref.diff to documentation trunk at revision 1097897.
Merged to 10.8 doc branch at revision 1097901.
Previously committed patches to Admin Guide, Developer's Guide, Getting Started, Tools Guide, and Tuning Guide.
> 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
> Fix For: 10.8.1.3, 10.9.0.0
>
> Attachments: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13027082#comment-13027082 ]
Kim Haase commented on DERBY-5184:
----------------------------------
Committed patch DERBY-5184-gs.diff to documentation trunk at revision 1097888.
Merged to 10.8 doc branch at revision 1097890.
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5184:
-----------------------------
Attachment: DERBY-5184-dev.zip
DERBY-5184-dev.stat
DERBY-5184-dev.diff
Attaching DERBY-5184-dev.diff, DERBY-5184-dev.stat, and DERBY-5184-dev.zip, with changes to the following Developer's Guide topics. The previous version had 13 formal and 1 choice table. Topics are listed in the order in which they appear in the manual.
tdevupgradedb.dita Upgrading a database (1 choice)
cdevdvlp40724.dita The database directory (1 formal, properly introduced, with xref)
cdevsetprop24843.dita Setting properties in a client/server environment (1 formal)
cdevspecialtfgetxxx.dita Preferred getXXX() methods for Derby-style table functions (1 formal, properly introduced)
cdevconcepts29416.dita Using auto-commit (1 formal)
cdevconcepts15366.dita Isolation levels and concurrency (3 formal, introduced by xrefs)
rdevconcepts2462.dita Lock compatibility (1 formal, properly introduced)
rdevconcepts8424.dita Scope of locks (1 formal)
rdevconcepts713.dita Deployment options and threading and connection modes (1 formal, introduced by xref)
rdevcsecure557.dita List of user authentication properties (1 formal)
rdevcsecure190.dita Read-only and full access permissions (1 formal, properly introduced)
cdevcollation.dita Character-based collation in Derby (1 formal)
> 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: DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Rick Hillegas (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13019872#comment-13019872 ]
Rick Hillegas commented on DERBY-5184:
--------------------------------------
Hi Kim,
Thanks for working on this issue. Here are answers to the questions you posed:
>ttoolsimporting.dita, Importing data using the built-in procedures (http://db.apache.org/derby/docs/dev/tools/ttoolsimporting.html -- don't worry, the formatting was fixed a while ago, it just hasn't shown up >on the site):
>
>In the third row of the table, there are references to the insertColumns and columnIndex parameters. Should this not be INSERTCOLUMNS and COLUMNINDEXES (plural)?
Yes, that looks better to me.
>cadminappsclient.dita, Accessing the Network Server by using the network client driver (http://db.apache.org/derby/docs/dev/adminguide/cadminappsclient.html):
>
>The second table lists a retrieveMessageText URL attribute corresponding to the retrieveMessageText property. The Reference Manual documents no such attribute. Is there an equivalent or should this >cell say "None"?
Turns out there is such an URL attribute. Looks like we need to add it to the Reference Guide.
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
>
> 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5184:
-----------------------------
Attachment: DERBY-5184-ref.zip
DERBY-5184-ref.stat
DERBY-5184-ref.diff
Attaching DERBY-5184-ref.diff, DERBY-5184-ref.stat, and DERBY-5184-ref.zip, with changes to the following 55 Reference Manual topics. The previous version had 139 formal tables, including 30 without titles. Topics are listed in the order in which they appear in the manual.
rrefsqlj37836.dita generated-column-spec (1 formal)
rrefsqlj19433.dita SQL expressions (4 formal)
rrefsqlj23075.dita Boolean expressions (1 formal, introduced by xref)
rrefsqlj33923.dita Aggregates (set functions) (1 formal, introduced by xref)
rrefsqlj33562.dita CAST function (1 formal, properly introduced) (try valign="bottom")
rrefsyscsdiagtables.dita SYSCS_DIAG diagnostic tables and functions (2 formal; 1 properly introduced, 1 with no title)
Oh no! one more table with empty cells that I missed! 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?
rrefsqlj27767.dita Numeric type promotion in expressions (1 formal, introduced by xref)
rrefsqlj58560.dita Data type assignments and comparison, sorting, and ordering (2 formal, with <desc> elements)
rrefsqljargmatching.dita Argument matching (1 formal, properly introduced)
rrefsql9241891.dita Derby support for SQL-92 features (26 formal, 1 properly introduced) (Intro should apply to all, and no sections should be used (so that they will be numbered consecutively in the frames version)
rrefsistabs28114.dita SYSALIASES system table (all formal but with no title)
rrefsistabs26665.dita SYSCHECKS system table
rrefsistabssyscolperms.dita SYSCOLPERMS system table
rrefsistabs22441.dita SYSCOLUMNS system table
rrefsistabs39391.dita SYSCONGLOMERATES system table
rrefsistabs23241.dita SYSCONSTRAINTS system table
rrefsistabs12813.dita SYSDEPENDS system table
rrefsistabs40972.dita SYSFILES system table
rrefsistabs13420.dita SYSFOREIGNKEYS system table
rrefsistabs33921.dita SYSKEYS system table
rrefsistabssysperms.dita SYSPERMS system table
rrefsistabssysroles.dita SYSROLES system table
rrefsistabssysroutineperms.dita SYSROUTINEPERMS system table
rrefsistabs12085.dita SYSSCHEMAS system table
rrefsistabssyssequences.dita SYSSEQUENCES system table
rrefsistabs33768.dita SYSSTATEMENTS system table
rrefsistabslilanguageitemsysstatistics.dita SYSSTATISTICS system table
rrefsistabssystableperms.dita SYSTABLEPERMS system table
rrefsistabs24269.dita SYSTABLES system table
rrefsistabs79888.dita SYSTRIGGERS system table
rrefsistabs24045.dita SYSVIEWS system table
rrefsysxplain_statements.dita SYSXPLAIN_STATEMENTS system table
Each topic: changed "see the RUNTIMESTATISTICS section in the
<ph conref="../conrefs.dita#pub/citref"></ph> for more information on how to configure this" to "See "Working with RunTimeStatistics" in the
<ph conref="../conrefs.dita#pub/cittuning"></ph> for information on how to configure this". There is no RUNTIMESTATISTICS section in the Reference Manual,
only two different sections on SYSCS_UTIL.SYSCS_GET_RUNTIMESTATISTICS and SYSCS_UTIL.SYSCS_SET_RUNTIMESTATISTICS that don't say anything about configuring XPLAIN. All of that is in the tuning guide.
rrefsysxplain_statement_timings.dita SYSXPLAIN_STATEMENT_TIMINGS system table
rrefsysxplain_resultsets.dita SYSXPLAIN_RESULTSETS system table
rrefsysxplain_resultset_timings.dita SYSXPLAIN_RESULTSET_TIMINGS system table
rrefsysxplain_scan_props.dita SYSXPLAIN_SCAN_PROPS system table
rrefsysxplain_sort_props.dita SYSXPLAIN_SORT_PROPS system table
rrefexcept71493.dita SQL error messages and exceptions (52 formal) (generated, can't touch, and no need)
rrefjdbc27734.dita java.sql.Connection interface (1 formal)
rrefjdbc40794.dita java.sql.Statement interface (1 formal)
rrefjdbc75719.dita CallableStatements and INOUT Parameters (1 formal)
Please check updated version.
rrefjavsqlprst.dita Prepared statements and streaming columns (1 formal, properly introduced)
rrefjdbc23502.dita java.sql.ResultSet interface (1 formal)
rrefjdbc38274.dita java.sql.ResultSetMetaData interface (1 formal, but with no title)
rrefjdbc20377.dita Mapping of java.sql.Types to SQL types (1 formal, properly introduced)
rrefjdbc96386.dita Mapping of java.sql.Blob and java.sql.Clob interfaces (2 formal)
rrefattrib56769.dita territory=ll_CC attribute (2 formal)
rrefattribtracelevel.dita traceLevel=value attribute (1 formal, properly introduced)
crefproper22250.dita Derby properties (1 formal, introduced by xref)
rrefsqlj75638.dita Supported territories (1 formal, but with no title)
rrefdbmlimits.dita Limitations for database manager values (1 formal, with <desc> element)
rrefdttlimits.dita DATE, TIME, and TIMESTAMP limitations (1 formal, properly introduced)
rrefidlengthlimits.dita Limitations on identifier length (1 formal, with <desc> element)
rrefnumericlimits.dita Numeric limitations (1 formal)
rrefstringlimits.dita String limitations (1 formal, with <desc> element)
rreflimitsxml.dita XML limitations (1 formal)
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, 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
[jira] [Closed] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase closed DERBY-5184.
----------------------------
Changes appear in Latest Alpha Manuals.
> 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
> Fix For: 10.8.1.3, 10.9.0.0
>
> Attachments: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13021740#comment-13021740 ]
Kim Haase commented on DERBY-5184:
----------------------------------
I have run into a few more technical questions, having to do with Reference Manual topics:
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?
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.
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?
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?
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 will be grateful for any help on these.
> 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
>
> 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13027056#comment-13027056 ]
Kim Haase commented on DERBY-5184:
----------------------------------
Committed patch DERBY-5184-admin.diff to documentation trunk at revision 1097855.
Merged to 10.8 doc branch at revision 1097862.
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5184:
-----------------------------
Attachment: DERBY-5184-gs.zip
DERBY-5184-gs.stat
DERBY-5184-gs.diff
Attaching DERBY-5184-gs.diff. DERBY-5184-gs.stat, and DERBY-5184-gs.zip, with changes to the following Getting Started topics. Each previous version had 1 simpletable unless otherwise stated; there are 28 total tables.Topics are listed in the order in which they appear in the manual.
tgsruntoolsutils.dita Choosing a method to run the Derby tools and startup utilities (also fixed instruction on setting PATH variable and conrefs phrase)
tgssetupjavaenvir.dita Setting the environment variables (2 choicetables)
rgsderbyrunjarsyntax.dita Syntax for the derbyrun.jar file
tgsrunningsysinfo.dita Running sysinfo (made consistent with other 2)
tgsrunningij.dita Running ij (made consistent with other 2)
tgsrunningdblook.dita Running dblook (made consistent with other 2)
tgssetupverify.dita Verifying the Derby system configuration (1 formal but with no title)
twwdactivity1_Setup.dita Creating a directory and copying scripts into the directory (4 simpletables)
twwdactivity1.dita Creating a Derby database and running SQL statements
twwdactivity2.dita Activity 2: Run SQL using the client driver (3 simpletables)
twwdactivity3_Setup.dita Activity 3: Run a JDBC program using the embedded driver
twwdactivity4.dita Activity 4: Create and run a JDBC program using the client driver and Network Server (4 simpletables)
rgsdocs10012.dita SQL syntax (1 formal but with no title)
rgsdocs18277.dita Typographical conventions (1 formal, with title)
rgslib46043.dita Libraries provided by Derby (5 simpletables)
> 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: DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5184:
-----------------------------
Attachment: DERBY-5184-tun.zip
DERBY-5184-tun.stat
DERBY-5184-tun.diff
Attaching DERBY-5184-tools.diff, DERBY-5184-tools.stat, and DERBY-5184-tools.zip, with changes to the following Tools Guide topics. The previous version had 9 formal tables, but 3 were layout tables, used for appearance. Topics are listed in the order in which they appear in the manual.
ctunperf98197.dita Use the appropriate getXXX and setXXX methods for the type (1 formal, properly introduced)
ctundepth14326.dita Shielding users from Derby class-loading events (2 layout tables, removed)
ctunoptimz42065.dita Transaction-based lock escalation (3 formal, but with no titles)
ctunstats52657.dita Selectivity from hard-wired assumptions (1 formal, introduced by xref)
ctuntransform13966.dita Internal language transformations (1 layout table, removed)
ctuntransform867201.dita IN/ANY subquery transformation (1 formal, introduced by xref)
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13027034#comment-13027034 ]
Kim Haase commented on DERBY-5184:
----------------------------------
Committed patch DERBY-5184-tun.diff to documentation trunk at revision 1097840.
Merged to 10.8 doc branch at revision 1097844.
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5184:
-----------------------------
Attachment: DERBY-5184-tools.zip
DERBY-5184-tools.stat
DERBY-5184-tools.diff
Attaching DERBY-5184-tools.diff, DERBY-5184-tools.stat, and DERBY-5184-tools.zip, with changes to the following Tools Guide topics. The previous version had 5 formal and 3 simple tables. Topics are listed in the order in which they appear in the manual.
rtoolsdrvrnmeurl.dita The ij Driver name and connection URL (1 formal) (has intro with xref)
rtoolsijpropref97949.dita derby.ui.codeset property (1 formal, properly introduced and with xref above)
rtoolsijlocale.dita derby.ui.locale property (2 formal)
ttoolsimporting.dita Importing data using the built-in procedures (1 simple)
In the 3rd row, changed references to the insertColumns and columnIndex parameters to INSERTCOLUMNS and COLUMNINDEXES.
ttoolsexporting.dita Exporting data using the built-in procedures (1 simple)
rtoolsimportcodeset.dita CODESET values for import and export procedures (1 formal, properly introduced; has desc element) (table is identical to the one in rtoolsijpropref97949.dita -- has been removed and replaced by an xref to it)
rtoolsplanexpxmlformat.dita PlanExporter XML format (1 simple)
Another problem: This topic used preformatted text to render ASCII art (the tree structure), which is frowned upon by the accessibility standards. In the absence of an actual graphic I converted this to a bullet list.
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13019475#comment-13019475 ]
Kim Haase commented on DERBY-5184:
----------------------------------
A couple of technical questions have come up as I've been going through the tables.
ttoolsimporting.dita, Importing data using the built-in procedures (http://db.apache.org/derby/docs/dev/tools/ttoolsimporting.html -- don't worry, the formatting was fixed a while ago, it just hasn't shown up on the site):
In the third row of the table, there are references to the insertColumns and columnIndex parameters. Should this not be INSERTCOLUMNS and COLUMNINDEXES (plural)?
cadminappsclient.dita, Accessing the Network Server by using the network client driver (http://db.apache.org/derby/docs/dev/adminguide/cadminappsclient.html):
The second table lists a retrieveMessageText URL attribute corresponding to the retrieveMessageText property. The Reference Manual documents no such attribute. Is there an equivalent or should this cell say "None"?
Thanks very much.
> 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
>
> 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5184:
-----------------------------
Attachment: DERBY-5184-admin.zip
DERBY-5184-admin.stat
DERBY-5184-admin.diff
Attaching DERBY-5184-admin.diff, DERBY-5184-admin.stat, and DERBY-5184-admin.zip, with changes to the following Admin Guide topics. The previous version had 8 formal and 3 simple tables. Topics are listed in the order in which they appear in the manual.
tadmincbdjhhfd.dita Starting the Network Server (3 simple)
cadminappsclient.dita Accessing the Network Server by using the network client driver (3 formal)
cadminappsclientsecurity.dita Network client security (1 formal, introduced by xref)
cadminappsclienttracing.dita Network client tracing (1 formal)
radminappsresultsetdiffs.dita Updatable Result Sets (1 formal, properly introduced) (cleaned up the first sentence, redid table)
cadminreplicsecurity.dita Replication and security (1 formal, properly introduced)
cadminreplicfailures.dita Replication failure handling (1 formal, properly introduced)
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13019919#comment-13019919 ]
Kim Haase commented on DERBY-5184:
----------------------------------
Thanks, Rick!
I will make the fix to ttoolsimporting.dita, and I'll file an issue for documenting retrieveMessageText.
> 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
>
> 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13017562#comment-13017562 ]
Kim Haase commented on DERBY-5184:
----------------------------------
I recommend using the phrase "the following table" to introduce a table, rather than an <xref> element, mainly because of the way the DITA toolkit handles table cross-references: the output has the table title rather than the table number (possibly because in the Frames output almost all tables are "Table 1" because table numbering starts over with a new section), so the user would still have no indication that what followed was a table.
There are some exceptions to this rule. I don't think introductions are needed for the individual tables in http://db.apache.org/derby/docs/dev/ref/ref-single.html#rrefsql9241891 (in fact, it might be good to remove the section heads here, since they duplicate the titles and force renumbering in the frames output) and in http://db.apache.org/derby/docs/dev/ref/ref-single.html#rrefexcept71493.
I would like to suggest that every table should be a formal table with a title. The docs are currently inconsistent in how they use choicetables and simpletables, which do not allow titles. My reasoning is a bit indirect: only tables with titles can have a <desc> element. Ideally, the DITA toolkit would use the <desc> element to populate the summary attribute of each table to provide a detailed description of the table that would be used only by screen readers. Currently we can't really use the <desc> element because it simply gets stuck after the table caption (I plan to remove the <desc> element and use its contents as the table introduction for the 4 topics that use one). But if we can somehow get DITA to do the right thing with <desc>, we can eventually provide more accessibility help for tables than introductions to the tables will provide.
WCAG (Guidelines 3 and 5) recommends avoiding layout tables. We have a few, where table format is used solely for appearance; for example, http://db.apache.org/derby/docs/dev/tuning/ctundepth14326.html. For accessibility, these should not be tables.
I may also make a few formatting changes elsewhere in the topics as needed (case consistency in titles, for instance, and paragraphing before tables for vertical spacing).
> 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
>
> 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
[jira] [Updated] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Kim Haase updated DERBY-5184:
-----------------------------
Issue & fix info: [Patch Available]
I will plan to commit these patches around Wednesday 4/27 unless a delay is needed.
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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
[jira] [Commented] (DERBY-5184) Tables in documentation need
introductions and formatting fixes
Posted by "Kim Haase (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/DERBY-5184?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13027077#comment-13027077 ]
Kim Haase commented on DERBY-5184:
----------------------------------
Committed patch DERBY-5184-dev.diff to documentation trunk at revision 1097882.
Merged to 10.8 doc branch at revision 1097886.
> 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: DERBY-5184-admin.diff, DERBY-5184-admin.stat, DERBY-5184-admin.zip, DERBY-5184-dev.diff, DERBY-5184-dev.stat, DERBY-5184-dev.zip, DERBY-5184-gs.diff, DERBY-5184-gs.stat, DERBY-5184-gs.zip, DERBY-5184-ref.diff, DERBY-5184-ref.stat, DERBY-5184-ref.zip, DERBY-5184-tools.diff, DERBY-5184-tools.stat, DERBY-5184-tools.zip, DERBY-5184-tun.diff, DERBY-5184-tun.stat, DERBY-5184-tun.zip, 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