db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DERBY-6379) Manuals are inconsistent in their use of the <shortdesc> element
Date Tue, 15 Oct 2013 20:43:42 GMT

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

Kim Haase commented on DERBY-6379:

The manuals currently use shortdescs as follows:

Getting Started: Every subtopic has a shortdesc.

Developer's Guide: Most subtopics have shortdescs. Only one of the subtopics in the Working
with Derby properties section has one; the section was brought over from the Reference Manual,
I think. Other than that, only 13 subtopics, mostly code examples, do not have them.

Admin Guide: In part 1, only 11 subtopics have shortdescs; in part 2, most subtopics have
shortdescs (all but 12).

Reference Manual: Few subtopics have shortdescs, though 39 of 78 function topics, 17 of 38
system procedure topics, and all the system table and XPLAIN style table topics have them;
outside of these sections, only 12 do.

Tools Guide: Only 5 subtopics have shortdescs.

Tuning Derby: Only 2 subtopics have shortdescs.

We could deal with this inconsistency in any of several ways --

1) Add shortdescs to all subtopics where they do not exist.

2) Remove all shortdescs where they exist.

3) An in-between solution: remove the scattered shortdescs from the Tools and Tuning manuals.
Add shortdescs where they are missing from the Developer's Guide and Admin Guide. Add shortdescs
where they are missing from the function and system procedure sections of the Reference Manual,
and remove the scattered ones elsewhere in that manual.

I am inclined to go with the third solution. It would make the docs more internally consistent
without requiring a huge amount of work. I'm open to suggestions, though.

By "add" and "remove" I mean change the first paragraph (or sentence) of the topic to be the
shortdesc, and vice versa.

> Manuals are inconsistent in their use of the <shortdesc> element
> ----------------------------------------------------------------
>                 Key: DERBY-6379
>                 URL: https://issues.apache.org/jira/browse/DERBY-6379
>             Project: Derby
>          Issue Type: Improvement
>          Components: Documentation
>    Affects Versions:
>            Reporter: Kim Haase
>            Priority: Minor
> When topics are organized as subtopics of other topics, our tools generate a list of
the subtopics at the end of the parent topic. If the DITA source of the subtopic begins with
a <shortdesc> element, the contents of the <shortdesc> appear under the subtopic
title in the parent topic. These contents also form the first paragraph of the subtopic. It
does not seem to be possible to suppress the list of subtopics; they appear in the HTML output,
but not in the PDF.
> Generally, the documentation is not consistent in its use of the <shortdesc> element.
> I'll add more detail in a comment.

This message was sent by Atlassian JIRA

View raw message