Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.7.1.1
    • Fix Version/s: 10.8.2.2, 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      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.

      1. JDBCTypePrinter.java
        3 kB
        Rick Hillegas
      2. DERBY-5184-tun.zip
        15 kB
        Kim Haase
      3. DERBY-5184-tun.stat
        0.2 kB
        Kim Haase
      4. DERBY-5184-tun.diff
        13 kB
        Kim Haase
      5. DERBY-5184-tools.zip
        18 kB
        Kim Haase
      6. DERBY-5184-tools.stat
        0.3 kB
        Kim Haase
      7. DERBY-5184-tools.diff
        31 kB
        Kim Haase
      8. DERBY-5184-ref.zip
        145 kB
        Kim Haase
      9. DERBY-5184-ref.stat
        2 kB
        Kim Haase
      10. DERBY-5184-ref.diff
        217 kB
        Kim Haase
      11. DERBY-5184-gs.zip
        42 kB
        Kim Haase
      12. DERBY-5184-gs.stat
        0.6 kB
        Kim Haase
      13. DERBY-5184-gs.diff
        77 kB
        Kim Haase
      14. DERBY-5184-dev.zip
        34 kB
        Kim Haase
      15. DERBY-5184-dev.stat
        0.5 kB
        Kim Haase
      16. DERBY-5184-dev.diff
        28 kB
        Kim Haase
      17. DERBY-5184-admin.zip
        21 kB
        Kim Haase
      18. DERBY-5184-admin.stat
        0.3 kB
        Kim Haase
      19. DERBY-5184-admin.diff
        21 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Changes appear in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Changes appear in Latest Alpha Manuals.
          Hide
          Kim Haase added a comment -

          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.

          Show
          Kim Haase added a comment - 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.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5184-gs.diff to documentation trunk at revision 1097888.
          Merged to 10.8 doc branch at revision 1097890.

          Show
          Kim Haase added a comment - Committed patch DERBY-5184 -gs.diff to documentation trunk at revision 1097888. Merged to 10.8 doc branch at revision 1097890.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5184-dev.diff to documentation trunk at revision 1097882.
          Merged to 10.8 doc branch at revision 1097886.

          Show
          Kim Haase added a comment - Committed patch DERBY-5184 -dev.diff to documentation trunk at revision 1097882. Merged to 10.8 doc branch at revision 1097886.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5184-tools.diff to documentation trunk at revision 1097872.
          Merged to 10.8 doc branch at revision 1097878.

          Show
          Kim Haase added a comment - Committed patch DERBY-5184 -tools.diff to documentation trunk at revision 1097872. Merged to 10.8 doc branch at revision 1097878.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5184-admin.diff to documentation trunk at revision 1097855.
          Merged to 10.8 doc branch at revision 1097862.

          Show
          Kim Haase added a comment - Committed patch DERBY-5184 -admin.diff to documentation trunk at revision 1097855. Merged to 10.8 doc branch at revision 1097862.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5184-tun.diff to documentation trunk at revision 1097840.
          Merged to 10.8 doc branch at revision 1097844.

          Show
          Kim Haase added a comment - Committed patch DERBY-5184 -tun.diff to documentation trunk at revision 1097840. Merged to 10.8 doc branch at revision 1097844.
          Hide
          Kim Haase added a comment -

          I will plan to commit these patches around Wednesday 4/27 unless a delay is needed.

          Show
          Kim Haase added a comment - I will plan to commit these patches around Wednesday 4/27 unless a delay is needed.
          Hide
          Kim Haase added a comment -

          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)

          Show
          Kim Haase added a comment - 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)
          Hide
          Kim Haase added a comment -

          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.

          Show
          Kim Haase added a comment - 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.
          Hide
          Kim Haase added a comment -

          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)

          Show
          Kim Haase added a comment - 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)
          Hide
          Kim Haase added a comment -

          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)

          Show
          Kim Haase added a comment - 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)
          Hide
          Kim Haase added a comment -

          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)

          Show
          Kim Haase added a comment - 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)
          Hide
          Kim Haase added a comment -

          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)

          Show
          Kim Haase added a comment - 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)
          Hide
          Kim Haase added a comment -

          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)?

          Show
          Kim Haase added a comment - 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)?
          Hide
          Rick Hillegas added a comment -

          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

          Show
          Rick Hillegas added a comment - 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
          Hide
          Kim Haase added a comment -

          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.

          Show
          Kim Haase added a comment - 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.
          Hide
          Kim Haase added a comment -

          Thanks, Rick!

          I will make the fix to ttoolsimporting.dita, and I'll file an issue for documenting retrieveMessageText.

          Show
          Kim Haase added a comment - Thanks, Rick! I will make the fix to ttoolsimporting.dita, and I'll file an issue for documenting retrieveMessageText.
          Hide
          Rick Hillegas added a comment -

          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

          Show
          Rick Hillegas added a comment - 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
          Hide
          Kim Haase added a comment -

          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.

          Show
          Kim Haase added a comment - 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.
          Hide
          Kim Haase added a comment -

          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).

          Show
          Kim Haase added a comment - 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).

            People

            • Assignee:
              Kim Haase
              Reporter:
              Kim Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development