Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Trivial Trivial
    • Resolution: Fixed
    • Affects Version/s: 10.10.1.1
    • Fix Version/s: 10.10.1.1
    • Component/s: Documentation
    • Labels:
      None

      Description

      Every topic in our documentation set appears in the table of contents for its manual, except for four syntax-related topics in the Reference Manual:

      • column-definition, generated-column-spec, and generation-clause, all under the CREATE TABLE statement
      • ReferencingClause, under the CREATE TRIGGER statement

      All of these have the following attribute setting in the map file:

      toc="no"

      I'd like to remove this setting for the following reasons:

      • The documentation for all other syntax clauses can be found in the ToC.
      • Except for ReferencingClause, all are linked to from other topics in addition to their parent topic.
      • I have often been puzzled that I can get to those topics by clicking links but not by locating them in the ToC. (I may spend more time navigating the Reference Manual than most people do, of course.)

      Unless someone can provide a reason why these topics in particular should be hidden, I'll file a patch soon and commit it in a day or two.

      Although this situation has existed since 10.1, I don't plan to backport the fix, since it's a very minor issue.

      1. DERBY-6050.diff
        1 kB
        Kim Haase
      2. DERBY-6050-2.diff
        6 kB
        Kim Haase
      3. toc.html
        12 kB
        Kim Haase
      4. toc.html
        37 kB
        Kim Haase

        Activity

        Hide
        Kim Haase added a comment -

        Attaching DERBY-6050.diff and the resulting toc.html, with changes to the following file:

        M src/ref/refderby.ditamap

        Suggestions welcome.

        Show
        Kim Haase added a comment - Attaching DERBY-6050 .diff and the resulting toc.html, with changes to the following file: M src/ref/refderby.ditamap Suggestions welcome.
        Hide
        Dag H. Wanvik added a comment -

        +1, good idea. Thanks KIm!

        Show
        Dag H. Wanvik added a comment - +1, good idea. Thanks KIm!
        Hide
        Kim Haase added a comment -

        Thanks, Dag!

        Committed patch DERBY-6050.diff to documentation trunk at revision 1438044.

        Show
        Kim Haase added a comment - Thanks, Dag! Committed patch DERBY-6050 .diff to documentation trunk at revision 1438044.
        Hide
        Kim Haase added a comment -

        I just realized that the Tuning Guide also has a number of invisible topics – 17, to be exact. Only three of them seem to have cross-references to them from elsewhere in the book. However, it's probably useful to make them all visible in the ToC. I will file a patch to do so.

        Show
        Kim Haase added a comment - I just realized that the Tuning Guide also has a number of invisible topics – 17, to be exact. Only three of them seem to have cross-references to them from elsewhere in the book. However, it's probably useful to make them all visible in the ToC. I will file a patch to do so.
        Hide
        Kim Haase added a comment -

        Attaching DERBY-6050-2.diff, with changes to the src/tuning/tuningderby.ditamap file, and the toc.html file that it generates.

        Show
        Kim Haase added a comment - Attaching DERBY-6050 -2.diff, with changes to the src/tuning/tuningderby.ditamap file, and the toc.html file that it generates.
        Hide
        Kathey Marsden added a comment -

        Is it possible the reference guide properties have this issue or something similar for some versions e.g. 10.5. I have noticed in the past doing a search on properties from the derby home page that they will show only the older version of the docs when the properties were still in the tuning guide. Now I see 10.8 and 10.9 showing up with a google search for:

        derby.storage.pageCachSize site:db.apache.org

        But not 10.5. As I still often have to refer to 10.5 docs it would be good to know if there is a change that could be backported to get the search to pick up 10.5 properties.

        I must say the feature I miss most from the old Cloudscape is the global index. I seem to recall some discussion of this that it was not possible with Dita to have a cross manual reference. Do you think it would be worth filing a Jira issue just to give it some thought?

        Show
        Kathey Marsden added a comment - Is it possible the reference guide properties have this issue or something similar for some versions e.g. 10.5. I have noticed in the past doing a search on properties from the derby home page that they will show only the older version of the docs when the properties were still in the tuning guide. Now I see 10.8 and 10.9 showing up with a google search for: derby.storage.pageCachSize site:db.apache.org But not 10.5. As I still often have to refer to 10.5 docs it would be good to know if there is a change that could be backported to get the search to pick up 10.5 properties. I must say the feature I miss most from the old Cloudscape is the global index. I seem to recall some discussion of this that it was not possible with Dita to have a cross manual reference. Do you think it would be worth filing a Jira issue just to give it some thought?
        Hide
        Rick Hillegas added a comment -

        Hi Kathey,

        I think it would be a great idea to open a JIRA on the topic of reviving the global index. Even if DITA can't do the job, we might be able to write our own tool to walk the source files and build an index. I believe that indexable terms are still tagged in the source. Thanks.

        Show
        Rick Hillegas added a comment - Hi Kathey, I think it would be a great idea to open a JIRA on the topic of reviving the global index. Even if DITA can't do the job, we might be able to write our own tool to walk the source files and build an index. I believe that indexable terms are still tagged in the source. Thanks.
        Hide
        Kim Haase added a comment -

        I thought we had a JIRA for the index, but it must have been closed as will not fix, or it is buried under some other heading. I agree it would be valuable to be able to produce one. Some areas are, I think, spottily indexed, but it should be possible to add index terms where they are needed.

        It is very mysterious to me that the properties for pre-10.8 docs don't show up in searches. The indexterm entries are exactly the same for all releases – for pageCacheSize, at least.

        Show
        Kim Haase added a comment - I thought we had a JIRA for the index, but it must have been closed as will not fix, or it is buried under some other heading. I agree it would be valuable to be able to produce one. Some areas are, I think, spottily indexed, but it should be possible to add index terms where they are needed. It is very mysterious to me that the properties for pre-10.8 docs don't show up in searches. The indexterm entries are exactly the same for all releases – for pageCacheSize, at least.
        Hide
        Kim Haase added a comment -

        Since the comments have headed in a different direction (and a new JIRA has been filed), I've committed the Tuning Guide ToC fixes.

        Committed patch DERBY-6050-2.diff to documentation trunk at revision 1439554.

        I don't think that backporting these ToC fixes will resolve any of the search issues, so I'm not planning to do that.

        Show
        Kim Haase added a comment - Since the comments have headed in a different direction (and a new JIRA has been filed), I've committed the Tuning Guide ToC fixes. Committed patch DERBY-6050 -2.diff to documentation trunk at revision 1439554. I don't think that backporting these ToC fixes will resolve any of the search issues, so I'm not planning to do that.
        Hide
        Kim Haase added a comment -

        Closing, since changes have appeared in Latest Alpha Manuals.

        Show
        Kim Haase added a comment - Closing, since changes have appeared in Latest Alpha Manuals.

          People

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

            Dates

            • Created:
              Updated:
              Resolved:

              Development