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] [Updated] (DERBY-5182) Derby web page on writing guidelines needs some fixes
Date Thu, 11 Sep 2014 19:17:33 GMT

     [ https://issues.apache.org/jira/browse/DERBY-5182?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel

Kim Haase updated DERBY-5182:
    Component/s:     (was: Documentation)
                 Web Site

Issue applies to web site rather than user docs.

> 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: Web Site
>    Affects Versions:
>            Reporter: Kim Haase
>            Priority: Minor
>              Labels: derby_triage10_11
> 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):
> <table>
> <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 was sent by Atlassian JIRA

View raw message