db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] [Created] (DERBY-5182) Derby web page on writing guidelines needs some fixes
Date Thu, 07 Apr 2011 20:14:05 GMT
Derby web page on writing guidelines needs some fixes

                 Key: DERBY-5182
                 URL: https://issues.apache.org/jira/browse/DERBY-5182
             Project: Derby
          Issue Type: Bug
          Components: Documentation
    Affects Versions:
            Reporter: Kim Haase
            Priority: Minor

The guidelines at http://db.apache.org/derby/manuals/guidelines.html need some corrections
and enhancements. One item is related to accessibility, but most are not. I wish I could fix
these myself, but I am not set up to edit the web site.

The table in "Tagging examples - structural tags":

Tables: A title tag should be added to the table tagging example (as in the example in the
reference template):

<title>Title of table</title>
<tgroup ...

At the end of the tagging example I'd suggest adding the following text:

For accessibility, each table should be preceded by introductory text describing what it does
(for example, "The following table lists the limitations on XML data types in Derby."). It
is recommended not to use an <xref> element to introduce a table. Make sure the table
has no empty cells.

Index entries: The following sentences should be removed: "Index entries are displayed at
the end of the PDF output for each Derby manual. When there is an Information Center, the
index terms are added as metadata to help in searching for content in the Information Center."
The first sentence is not true, and I believe the second has no meaning outside of IBM?

I had thought of adding an entry on using figures, but since any new figures would not match
the look of the existing ones, I hesitate to do so.

The table in "Tagging examples - textual tags":

Links to external sites: The sentence "To create links to other topics in the Derby documentation,
edit the ditamap for the source manual to specify a related link to another Derby topic."
should be changed:

To create a link to another topic within the same manual, use an <xref> tag as in the
following example:

<xref href="tgsrunningsysinfo.dita#tgsrunningsysinfo"></xref>

To refer to a topic in another Derby manual, do not link directly to it. Instead, use tagging
similar to the following:

For more information about scopes, precedence, and persistence, see "Properties overview"
in the <ph conref="../conrefs.dita#pub/citdevelop"></ph>.

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

View raw message