Derby
  1. Derby
  2. DERBY-6379

Manuals are inconsistent in their use of the <shortdesc> element

    Details

    • Type: Improvement Improvement
    • Status: Reopened
    • Priority: Minor Minor
    • Resolution: Unresolved
    • Affects Version/s: 10.10.1.1
    • Fix Version/s: 10.11.0.0, 10.10.2.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      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.

      1. DERBY-6379-refprocs.stat
        2 kB
        Kim Haase
      2. DERBY-6379-refprocs.diff
        64 kB
        Kim Haase
      3. DERBY-6379-reffuncs.stat
        1 kB
        Kim Haase
      4. DERBY-6379-reffuncs.diff
        49 kB
        Kim Haase
      5. DERBY-6379-devguide-branch.diff
        2 kB
        Kim Haase
      6. DERBY-6379-devguide-branch.diff
        2 kB
        Kim Haase
      7. DERBY-6379-devguide.stat
        2 kB
        Kim Haase
      8. DERBY-6379-devguide.diff
        51 kB
        Kim Haase
      9. DERBY-6379-admintasks.stat
        2 kB
        Kim Haase
      10. DERBY-6379-admintasks.diff
        103 kB
        Kim Haase
      11. DERBY-6379-adminreference.stat
        2 kB
        Kim Haase
      12. DERBY-6379-adminreference.diff
        103 kB
        Kim Haase
      13. DERBY-6379-adminconcepts.stat
        3 kB
        Kim Haase
      14. DERBY-6379-adminconcepts.diff
        201 kB
        Kim Haase
      15. DERBY-6379-toolstuning.stat
        0.5 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        It turns out that the <shortdesc> element is essential for search engine optimization. Its contents are used for the description attribute of a meta element in the generated HTML. It appears that the contents of the description attribute are in turn used by search engines. This means that all topics that we want found by search engines should have a shortdesc element that includes keywords relevant to that topic.

        In practice, this means that we need to add shortdesc elements to the Tools Guide, Tuning Derby, and the remaining topics in the Reference Manual.

        Show
        Kim Haase added a comment - It turns out that the <shortdesc> element is essential for search engine optimization. Its contents are used for the description attribute of a meta element in the generated HTML. It appears that the contents of the description attribute are in turn used by search engines. This means that all topics that we want found by search engines should have a shortdesc element that includes keywords relevant to that topic. In practice, this means that we need to add shortdesc elements to the Tools Guide, Tuning Derby, and the remaining topics in the Reference Manual.
        Hide
        Kim Haase added a comment -

        Fixes appear in latest alpha manuals.

        Show
        Kim Haase added a comment - Fixes appear in latest alpha manuals.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6379-refprocs.diff to documentation trunk at revision 1542068.
        Merged to 10.10 doc branch at revision 1542079.

        Show
        Kim Haase added a comment - Committed patch DERBY-6379 -refprocs.diff to documentation trunk at revision 1542068. Merged to 10.10 doc branch at revision 1542079.
        Hide
        ASF subversion and git services added a comment -

        Commit 1542079 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1542079 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-refprocs.diff to 10.10 doc branch from trunk revision 1542068.

        Show
        ASF subversion and git services added a comment - Commit 1542079 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1542079 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -refprocs.diff to 10.10 doc branch from trunk revision 1542068.
        Hide
        ASF subversion and git services added a comment -

        Commit 1542068 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1542068 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 41 Reference Manual topics, mostly system function and procedure topics..

        Patch: DERBY-6379-refprocs.diff

        Show
        ASF subversion and git services added a comment - Commit 1542068 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1542068 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 41 Reference Manual topics, mostly system function and procedure topics.. Patch: DERBY-6379 -refprocs.diff
        Hide
        Kim Haase added a comment -

        I should mention that I left out the changes to two IMPORT procedures because they are part of the patch for DERBY-6403, which is still under review.

        Show
        Kim Haase added a comment - I should mention that I left out the changes to two IMPORT procedures because they are part of the patch for DERBY-6403 , which is still under review.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6379-refprocs.diff and DERBY-6379-refprocs.stat, modifying 41 Reference Manual topics: specifically, adding shortdescs where they are missing from the system function and procedure topics, and removing them from 10 stray topics where all the other topics in the group lack them. Also fixed a few format consistency problems in these topics.

        Once I commit this patch, the Reference Manual will have some sections where all topics have shortdesc elements, and some sections where no topics have them.

        Show
        Kim Haase added a comment - Attaching DERBY-6379 -refprocs.diff and DERBY-6379 -refprocs.stat, modifying 41 Reference Manual topics: specifically, adding shortdescs where they are missing from the system function and procedure topics, and removing them from 10 stray topics where all the other topics in the group lack them. Also fixed a few format consistency problems in these topics. Once I commit this patch, the Reference Manual will have some sections where all topics have shortdesc elements, and some sections where no topics have them.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6379-reffuncs.diff to documentation trunk at revision 1541660.
        Merged to 10.10 doc branch at revision 1541663.

        Show
        Kim Haase added a comment - Committed patch DERBY-6379 -reffuncs.diff to documentation trunk at revision 1541660. Merged to 10.10 doc branch at revision 1541663.
        Hide
        ASF subversion and git services added a comment -

        Commit 1541663 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1541663 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-reffuncs.diff to 10.10 doc branch from trunk revision 1541660.

        Show
        ASF subversion and git services added a comment - Commit 1541663 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1541663 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -reffuncs.diff to 10.10 doc branch from trunk revision 1541660.
        Hide
        ASF subversion and git services added a comment -

        Commit 1541660 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1541660 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 40 Reference Manual built-in function topics.

        Patch: DERBY-6379-reffuncs.diff

        Show
        ASF subversion and git services added a comment - Commit 1541660 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1541660 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 40 Reference Manual built-in function topics. Patch: DERBY-6379 -reffuncs.diff
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6379-reffuncs.diff and DERBY-6379-reffuncs.stat, with changes to 40 Reference Manual topics on built-in functions (adding shortdesc elements to 39 topics and fixing one that already had one).

        Will commit shortly.

        Show
        Kim Haase added a comment - Attaching DERBY-6379 -reffuncs.diff and DERBY-6379 -reffuncs.stat, with changes to 40 Reference Manual topics on built-in functions (adding shortdesc elements to 39 topics and fixing one that already had one). Will commit shortly.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6379-devguide-branch.diff to 10.10 doc branch at revision 1541105.

        Show
        Kim Haase added a comment - Committed patch DERBY-6379 -devguide-branch.diff to 10.10 doc branch at revision 1541105.
        Hide
        ASF subversion and git services added a comment -

        Commit 1541105 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1541105 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 1 Developer's Guide topic in 10.10 branch.

        Patch: DERBY-6379-devguide-branch.diff

        Show
        ASF subversion and git services added a comment - Commit 1541105 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1541105 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 1 Developer's Guide topic in 10.10 branch. Patch: DERBY-6379 -devguide-branch.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1541105 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1541105 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 1 Developer's Guide topic in 10.10 branch.

        Patch: DERBY-6379-devguide-branch.diff

        Show
        ASF subversion and git services added a comment - Commit 1541105 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1541105 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 1 Developer's Guide topic in 10.10 branch. Patch: DERBY-6379 -devguide-branch.diff
        Hide
        Kim Haase added a comment -

        Correcting the 10.10 branch patch.

        Show
        Kim Haase added a comment - Correcting the 10.10 branch patch.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6379-devguide-branch.diff, which adds a shortdesc and fixes the formatting in the "Examples of trigger actions" topic but does not add the new example provided by DERBY-6390.

        M src/devguide/cdevspecial13670.dita

        The topic has always had just one example, in spite of the plural in the title.

        Show
        Kim Haase added a comment - Attaching DERBY-6379 -devguide-branch.diff, which adds a shortdesc and fixes the formatting in the "Examples of trigger actions" topic but does not add the new example provided by DERBY-6390 . M src/devguide/cdevspecial13670.dita The topic has always had just one example, in spite of the plural in the title.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6379-devguide.diff to documentation trunk at revision 1541073.
        Merged to 10.10 doc branch at revision 1541093.

        Will file additional patch for a trigger topic that is different from the trunk version.

        Show
        Kim Haase added a comment - Committed patch DERBY-6379 -devguide.diff to documentation trunk at revision 1541073. Merged to 10.10 doc branch at revision 1541093. Will file additional patch for a trigger topic that is different from the trunk version.
        Hide
        ASF subversion and git services added a comment -

        Commit 1541093 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1541093 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-devguide.diff to 10.10 doc branch from trunk revision 1541073.

        Show
        ASF subversion and git services added a comment - Commit 1541093 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1541093 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -devguide.diff to 10.10 doc branch from trunk revision 1541073.
        Hide
        ASF subversion and git services added a comment -

        Commit 1541093 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1541093 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-devguide.diff to 10.10 doc branch from trunk revision 1541073.

        Show
        ASF subversion and git services added a comment - Commit 1541093 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1541093 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -devguide.diff to 10.10 doc branch from trunk revision 1541073.
        Hide
        ASF subversion and git services added a comment -

        Commit 1541073 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1541073 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 37 Developer's Guide topics.

        Patch: DERBY-6379-devguide.diff

        Show
        ASF subversion and git services added a comment - Commit 1541073 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1541073 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 37 Developer's Guide topics. Patch: DERBY-6379 -devguide.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1541073 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1541073 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 37 Developer's Guide topics.

        Patch: DERBY-6379-devguide.diff

        Show
        ASF subversion and git services added a comment - Commit 1541073 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1541073 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 37 Developer's Guide topics. Patch: DERBY-6379 -devguide.diff
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6379-devguide.diff and DERBY-6379-devguide.stat, adding shortdesc elements (and making a few formatting tweaks) in 37 topics.

        Show
        Kim Haase added a comment - Attaching DERBY-6379 -devguide.diff and DERBY-6379 -devguide.stat, adding shortdesc elements (and making a few formatting tweaks) in 37 topics.
        Hide
        Kim Haase added a comment -

        Sorry – merged to doc branch at revision 1540840.

        Show
        Kim Haase added a comment - Sorry – merged to doc branch at revision 1540840.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6379-adminleftovers.diff to documentation trunk at revision 1540836.
        Merged to 10.10 doc branch at revision

        There's still a formatting fix needed for cadminimport27052.dita, which I'll do after DERBY-6403 is completed.

        Developer's Guide fixes are next.

        Show
        Kim Haase added a comment - Committed patch DERBY-6379 -adminleftovers.diff to documentation trunk at revision 1540836. Merged to 10.10 doc branch at revision There's still a formatting fix needed for cadminimport27052.dita, which I'll do after DERBY-6403 is completed. Developer's Guide fixes are next.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540840 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540840 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-adminleftovers.diff to 10.10 doc branch from trunk revision 1540836.

        Show
        ASF subversion and git services added a comment - Commit 1540840 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540840 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -adminleftovers.diff to 10.10 doc branch from trunk revision 1540836.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540840 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540840 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-adminleftovers.diff to 10.10 doc branch from trunk revision 1540836.

        Show
        ASF subversion and git services added a comment - Commit 1540840 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540840 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -adminleftovers.diff to 10.10 doc branch from trunk revision 1540836.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540836 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540836 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 4 Admin Guide concept topics that had missing newline problems, and 1 Admin Guide reference topic with a font inconsistency.

        Patch: DERBY-6379-adminleftovers.diff

        Show
        ASF subversion and git services added a comment - Commit 1540836 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540836 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 4 Admin Guide concept topics that had missing newline problems, and 1 Admin Guide reference topic with a font inconsistency. Patch: DERBY-6379 -adminleftovers.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1540836 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540836 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 4 Admin Guide concept topics that had missing newline problems, and 1 Admin Guide reference topic with a font inconsistency.

        Patch: DERBY-6379-adminleftovers.diff

        Show
        ASF subversion and git services added a comment - Commit 1540836 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540836 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 4 Admin Guide concept topics that had missing newline problems, and 1 Admin Guide reference topic with a font inconsistency. Patch: DERBY-6379 -adminleftovers.diff
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6379-adminconcepts.diff to documentation trunk at revision 1540771, with the exception of 4 files that were omitted because of a missing newline and cadminimport27052.dita, which will be fixed after DERBY-6403 is completed.
        Merged to 10.10 doc branch at revision 1540788.

        Show
        Kim Haase added a comment - Committed patch DERBY-6379 -adminconcepts.diff to documentation trunk at revision 1540771, with the exception of 4 files that were omitted because of a missing newline and cadminimport27052.dita, which will be fixed after DERBY-6403 is completed. Merged to 10.10 doc branch at revision 1540788.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540788 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540788 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-adminconcepts.diff (except for 4 files for which I will file another patch) to 10.10 doc branch from trunk revision 1540771.

        Show
        ASF subversion and git services added a comment - Commit 1540788 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540788 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -adminconcepts.diff (except for 4 files for which I will file another patch) to 10.10 doc branch from trunk revision 1540771.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540788 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540788 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-adminconcepts.diff (except for 4 files for which I will file another patch) to 10.10 doc branch from trunk revision 1540771.

        Show
        ASF subversion and git services added a comment - Commit 1540788 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540788 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -adminconcepts.diff (except for 4 files for which I will file another patch) to 10.10 doc branch from trunk revision 1540771.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540771 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540771 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 66 Admin Guide concept topics. (Will file additional patch for 4 topics that were not patched because of a missing newline at end of a topic.)

        Patch: DERBY-6379-adminconcepts.diff

        Show
        ASF subversion and git services added a comment - Commit 1540771 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540771 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 66 Admin Guide concept topics. (Will file additional patch for 4 topics that were not patched because of a missing newline at end of a topic.) Patch: DERBY-6379 -adminconcepts.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1540771 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540771 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 66 Admin Guide concept topics. (Will file additional patch for 4 topics that were not patched because of a missing newline at end of a topic.)

        Patch: DERBY-6379-adminconcepts.diff

        Show
        ASF subversion and git services added a comment - Commit 1540771 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540771 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 66 Admin Guide concept topics. (Will file additional patch for 4 topics that were not patched because of a missing newline at end of a topic.) Patch: DERBY-6379 -adminconcepts.diff
        Hide
        Kim Haase added a comment -

        Fixes to reference topics done:

        Committed patch DERBY-6379-adminreference.diff to documentation trunk at revision 1540754.
        Merged to 10.10 doc branch at revision 1540756.

        Show
        Kim Haase added a comment - Fixes to reference topics done: Committed patch DERBY-6379 -adminreference.diff to documentation trunk at revision 1540754. Merged to 10.10 doc branch at revision 1540756.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540756 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540756 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-adminreference.diff to 10.10 doc branch from trunk revision 1540754.

        Show
        ASF subversion and git services added a comment - Commit 1540756 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540756 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -adminreference.diff to 10.10 doc branch from trunk revision 1540754.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540756 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540756 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-adminreference.diff to 10.10 doc branch from trunk revision 1540754.

        Show
        ASF subversion and git services added a comment - Commit 1540756 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540756 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -adminreference.diff to 10.10 doc branch from trunk revision 1540754.
        Hide
        Kim Haase added a comment -

        Fixes to tasks topics done:

        Committed patch DERBY-6379-admintasks.diff to documentation trunk at revision 1540743.
        Merged to 10.10 doc branch at revision 1540750.

        Show
        Kim Haase added a comment - Fixes to tasks topics done: Committed patch DERBY-6379 -admintasks.diff to documentation trunk at revision 1540743. Merged to 10.10 doc branch at revision 1540750.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540754 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540754 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 46 Admin Guide reference topics.

        Patch: DERBY-6379-adminreference.diff

        Show
        ASF subversion and git services added a comment - Commit 1540754 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540754 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 46 Admin Guide reference topics. Patch: DERBY-6379 -adminreference.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1540754 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540754 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 46 Admin Guide reference topics.

        Patch: DERBY-6379-adminreference.diff

        Show
        ASF subversion and git services added a comment - Commit 1540754 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540754 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 46 Admin Guide reference topics. Patch: DERBY-6379 -adminreference.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1540750 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540750 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-admintasks.diff to 10.10 doc branch from trunk revision 1540743.

        Show
        ASF subversion and git services added a comment - Commit 1540750 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540750 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -admintasks.diff to 10.10 doc branch from trunk revision 1540743.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540750 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1540750 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-admintasks.diff to 10.10 doc branch from trunk revision 1540743.

        Show
        ASF subversion and git services added a comment - Commit 1540750 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1540750 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -admintasks.diff to 10.10 doc branch from trunk revision 1540743.
        Hide
        ASF subversion and git services added a comment -

        Commit 1540743 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540743 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 36 Admin Guide task topics.

        Patch: DERBY-6379-admintasks.diff

        Show
        ASF subversion and git services added a comment - Commit 1540743 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540743 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 36 Admin Guide task topics. Patch: DERBY-6379 -admintasks.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1540743 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1540743 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 36 Admin Guide task topics.

        Patch: DERBY-6379-admintasks.diff

        Show
        ASF subversion and git services added a comment - Commit 1540743 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1540743 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 36 Admin Guide task topics. Patch: DERBY-6379 -admintasks.diff
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6379-adminconcepts.diff, DERBY-6379-adminconcepts.stat, DERBY-6379-adminreference.diff, DERBY-6379-adminreference.stat, DERBY-6379-admintasks.diff, and DERBY-6379-admintasks.stat, with modifications to the Admin Guide's concept, reference, and task topics.

        I am afraid I went a bit overboard and made a number of formatting fixes in addition to the <shortdesc> ones, mainly for the sake of consistency and conformance with the doc conventions in Getting Started.

        Touches 70 concept topics, 45 reference topics, 36 task topics, and the map file.

        I will commit these patches in due course; I'm not asking for review, though you are welcome to take a look.

        Show
        Kim Haase added a comment - Attaching DERBY-6379 -adminconcepts.diff, DERBY-6379 -adminconcepts.stat, DERBY-6379 -adminreference.diff, DERBY-6379 -adminreference.stat, DERBY-6379 -admintasks.diff, and DERBY-6379 -admintasks.stat, with modifications to the Admin Guide's concept, reference, and task topics. I am afraid I went a bit overboard and made a number of formatting fixes in addition to the <shortdesc> ones, mainly for the sake of consistency and conformance with the doc conventions in Getting Started. Touches 70 concept topics, 45 reference topics, 36 task topics, and the map file. I will commit these patches in due course; I'm not asking for review, though you are welcome to take a look.
        Hide
        Kim Haase added a comment -

        Committed patch DERBY-6379-toolstuning.diff to documentation trunk at revision 1535443.
        Merged to 10.10 doc branch at revision 1535465.

        Next: Admin Guide.

        Show
        Kim Haase added a comment - Committed patch DERBY-6379 -toolstuning.diff to documentation trunk at revision 1535443. Merged to 10.10 doc branch at revision 1535465. Next: Admin Guide.
        Hide
        ASF subversion and git services added a comment -

        Commit 1535465 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1535465 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-toolstuning.diff to 10.10 doc branch from trunk revision 1535443.

        Show
        ASF subversion and git services added a comment - Commit 1535465 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1535465 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -toolstuning.diff to 10.10 doc branch from trunk revision 1535443.
        Hide
        ASF subversion and git services added a comment -

        Commit 1535465 from Kim Haase in branch 'docs/branches/10.10'
        [ https://svn.apache.org/r1535465 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Merged DERBY-6379-toolstuning.diff to 10.10 doc branch from trunk revision 1535443.

        Show
        ASF subversion and git services added a comment - Commit 1535465 from Kim Haase in branch 'docs/branches/10.10' [ https://svn.apache.org/r1535465 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Merged DERBY-6379 -toolstuning.diff to 10.10 doc branch from trunk revision 1535443.
        Hide
        ASF subversion and git services added a comment -

        Commit 1535443 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1535443 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 8 Tools Guide and 5 Tuning Derby topics.

        Patch: DERBY-6379-toolstuning.diff

        Show
        ASF subversion and git services added a comment - Commit 1535443 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1535443 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 8 Tools Guide and 5 Tuning Derby topics. Patch: DERBY-6379 -toolstuning.diff
        Hide
        ASF subversion and git services added a comment -

        Commit 1535443 from Kim Haase in branch 'docs/trunk'
        [ https://svn.apache.org/r1535443 ]

        DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element

        Modified 8 Tools Guide and 5 Tuning Derby topics.

        Patch: DERBY-6379-toolstuning.diff

        Show
        ASF subversion and git services added a comment - Commit 1535443 from Kim Haase in branch 'docs/trunk' [ https://svn.apache.org/r1535443 ] DERBY-6379 Manuals are inconsistent in their use of the <shortdesc> element Modified 8 Tools Guide and 5 Tuning Derby topics. Patch: DERBY-6379 -toolstuning.diff
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6379-toolstuning.diff and DERBY-6379-toolstuning.stat, removing the shortdesc elements from the following topics:
        M src/tools/ctoolsijtools20118.dita
        M src/tools/ctoolsijtools26429.dita
        M src/tools/ctoolsij34525.dita
        M src/tools/rtoolsoptforeignviews.dita
        M src/tools/ctoolsijtools30948.dita
        M src/tools/rtoolslicense.dita
        M src/tools/ctoolsijtools11318.dita
        M src/tools/rtoolsoptdbmetadata.dita
        M src/tuning/ctundepth1002853.dita
        M src/tuning/rtunlicense.dita
        M src/tuning/ctuntransform25857.dita
        M src/tuning/ctunperf98197.dita
        M src/tuning/rtuntransform582.dita

        I have not attached a zip, because a) the appearance of the topics has not changed (the appearance of the parent topics has); and b) I am not asking for review of these formatting changes and will commit the patch shortly.

        Show
        Kim Haase added a comment - Attaching DERBY-6379 -toolstuning.diff and DERBY-6379 -toolstuning.stat, removing the shortdesc elements from the following topics: M src/tools/ctoolsijtools20118.dita M src/tools/ctoolsijtools26429.dita M src/tools/ctoolsij34525.dita M src/tools/rtoolsoptforeignviews.dita M src/tools/ctoolsijtools30948.dita M src/tools/rtoolslicense.dita M src/tools/ctoolsijtools11318.dita M src/tools/rtoolsoptdbmetadata.dita M src/tuning/ctundepth1002853.dita M src/tuning/rtunlicense.dita M src/tuning/ctuntransform25857.dita M src/tuning/ctunperf98197.dita M src/tuning/rtuntransform582.dita I have not attached a zip, because a) the appearance of the topics has not changed (the appearance of the parent topics has); and b) I am not asking for review of these formatting changes and will commit the patch shortly.
        Hide
        Kim Haase added a comment -

        Thanks for filing DERBY-6389. It will be useful to bring that info up to date.

        So I can leave the IBM JCE in that topic at least for the time being.

        Thanks also for the clarification on "console" – I wonder how confusing it is to refer to standard output as the console. It's pretty old terminology. However, we use that term in Getting Started and in the Tools Guide, mainly in reference to sysinfo and dblook. I'll leave it, and if we can think of a better option, we can file a separate issue.

        Show
        Kim Haase added a comment - Thanks for filing DERBY-6389 . It will be useful to bring that info up to date. So I can leave the IBM JCE in that topic at least for the time being. Thanks also for the clarification on "console" – I wonder how confusing it is to refer to standard output as the console. It's pretty old terminology. However, we use that term in Getting Started and in the Tools Guide, mainly in reference to sysinfo and dblook. I'll leave it, and if we can think of a better option, we can file a separate issue.
        Hide
        Knut Anders Hatlen added a comment -

        I've filed DERBY-6389 for updating the section on differences between embedded and client. I found that at least the information about exceptions was outdated. There may be more, but I haven't checked yet.

        Show
        Knut Anders Hatlen added a comment - I've filed DERBY-6389 for updating the section on differences between embedded and client. I found that at least the information about exceptions was outdated. There may be more, but I haven't checked yet.
        Hide
        Knut Anders Hatlen added a comment -

        I think IBM JCE is mentioned because that particular functionality does not work with the JCE libraries that come with Oracle's JDK since the public prime specified by the DRDA spec is too short. More details here: http://db.apache.org/derby/docs/10.10/adminguide/cadminapps811695.html. I'm not sure, though, why this is listed as a difference between embedded and network.

        +1 to removing 3.0 from the topic title.

        I think the "Network Server console" means the standard output destination of the network server process. That is, when it says a message goes to derby.log and the network server console, it means that the network server writes the message to derby.log and System.out.

        Show
        Knut Anders Hatlen added a comment - I think IBM JCE is mentioned because that particular functionality does not work with the JCE libraries that come with Oracle's JDK since the public prime specified by the DRDA spec is too short. More details here: http://db.apache.org/derby/docs/10.10/adminguide/cadminapps811695.html . I'm not sure, though, why this is listed as a difference between embedded and network. +1 to removing 3.0 from the topic title. I think the "Network Server console" means the standard output destination of the network server process. That is, when it says a message goes to derby.log and the network server console, it means that the network server writes the message to derby.log and System.out.
        Hide
        Kim Haase added a comment -

        Here's another sanity check. The Admin Guide mentions a "Network Server console" in two places:

        http://db.apache.org/derby/docs/10.10/adminguide/radminconfigdb2jdrdalogconnections.html

        http://db.apache.org/derby/docs/10.10/adminguide/tadminlogfile.html

        There's no such thing, right? If so, I'll remove those phrases.

        Show
        Kim Haase added a comment - Here's another sanity check. The Admin Guide mentions a "Network Server console" in two places: http://db.apache.org/derby/docs/10.10/adminguide/radminconfigdb2jdrdalogconnections.html http://db.apache.org/derby/docs/10.10/adminguide/tadminlogfile.html There's no such thing, right? If so, I'll remove those phrases.
        Hide
        Kim Haase added a comment -

        Going through the Admin Guide to add shortdescs, I've come up with a couple of questions involving content.

        1) Is there a reason why the IBM JCE is mentioned specifically in http://db.apache.org/derby/docs/10.10/adminguide/cadminappsclientdiffs.html?

        2) I am assuming I can change the title of the topic http://db.apache.org/derby/docs/10.10/adminguide/cadminappsjdbcdiffs.html to just "Differences in JDBC methods". Right?

        Actually, someone might want to go through the section http://db.apache.org/derby/docs/10.10/adminguide/cadminapps.html ("Differences between running Derby in embedded mode and using the Network Server") and see if the content is all still current. If any changes are needed, you can file an issue, or let me know and I can.

        Show
        Kim Haase added a comment - Going through the Admin Guide to add shortdescs, I've come up with a couple of questions involving content. 1) Is there a reason why the IBM JCE is mentioned specifically in http://db.apache.org/derby/docs/10.10/adminguide/cadminappsclientdiffs.html? 2) I am assuming I can change the title of the topic http://db.apache.org/derby/docs/10.10/adminguide/cadminappsjdbcdiffs.html to just "Differences in JDBC methods". Right? Actually, someone might want to go through the section http://db.apache.org/derby/docs/10.10/adminguide/cadminapps.html ("Differences between running Derby in embedded mode and using the Network Server") and see if the content is all still current. If any changes are needed, you can file an issue, or let me know and I can.
        Hide
        Kim Haase added a comment -

        Yes, thanks, Knut. I was planning to keep the system and XPLAIN table shortdescs as they are, and only to remove the scattered outliers in sections that have very few. For those that are about halfway there (functions and system procedures), I would add the missing ones. That way I think we would have some sections with full coverage, some with none, and nothing in between.

        Show
        Kim Haase added a comment - Yes, thanks, Knut. I was planning to keep the system and XPLAIN table shortdescs as they are, and only to remove the scattered outliers in sections that have very few. For those that are about halfway there (functions and system procedures), I would add the missing ones. That way I think we would have some sections with full coverage, some with none, and nothing in between.
        Hide
        Knut Anders Hatlen added a comment -

        Option 3 sounds like a reasonable approach to me.

        It might also make sense to keep the shortdescs in the cases where all sibling topics have them. For example, in the reference manual, the subtopics of "Derby system tables" and "XPLAIN style tables" seem to use them consistently:

        http://db.apache.org/derby/docs/10.10/ref/rrefsistabs38369.html
        http://db.apache.org/derby/docs/10.10/ref/rref_xplain_tables.html

        But it's not like the information goes away or is more difficult to find if we convert a shortdesc to an ordinary paragraph, so I'd be fine with either approach.

        Show
        Knut Anders Hatlen added a comment - Option 3 sounds like a reasonable approach to me. It might also make sense to keep the shortdescs in the cases where all sibling topics have them. For example, in the reference manual, the subtopics of "Derby system tables" and "XPLAIN style tables" seem to use them consistently: http://db.apache.org/derby/docs/10.10/ref/rrefsistabs38369.html http://db.apache.org/derby/docs/10.10/ref/rref_xplain_tables.html But it's not like the information goes away or is more difficult to find if we convert a shortdesc to an ordinary paragraph, so I'd be fine with either approach.
        Hide
        Kim Haase added a comment -

        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.

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

          People

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

            Dates

            • Created:
              Updated:

              Development