Derby
  1. Derby
  2. DERBY-79

Provide Derby Documentation in PDF format and improve navigation

    Details

    • Type: Task Task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.1.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      Since the format of the documentation is a recurring theme, this issue should be tracked in JIRA.

      Summary of requirements from a user's perspective:

      • Provide manuals in a PDF format (one manual per PDF file, not PDF files for every page, see mail thread in derby-dev below)
      • Improve navigation in HTML format. For example, have left hand frame with table of contents and less pages to navigate (see mail thread in derby-user below)
      • Provide hyperlinks across manuals
      • Make it easier to search the manual (on the user's PC, not refering to the Google search on the Derby web site). PDFs will address this. Having less HTML pages would also help here.

      See the following email threads:

      http://nagoya.apache.org/eyebrowse/ReadMsg?listName=derby-user@db.apache.org&msgNo=199

      http://nagoya.apache.org/eyebrowse/BrowseList?listName=derby-dev@db.apache.org&by=subject&from=651389&to=651389&first=1&count=15

        Activity

        Hide
        Kim Haase added a comment -

        Issue was resolved a long time ago; closing.

        Show
        Kim Haase added a comment - Issue was resolved a long time ago; closing.
        Hide
        Kim Haase added a comment -

        Thanks, Andrew, for this suggestion. I filed a new issue (DERBY-3006).

        Show
        Kim Haase added a comment - Thanks, Andrew, for this suggestion. I filed a new issue ( DERBY-3006 ).
        Hide
        Andrew McIntyre added a comment -

        Kim, issue #1 in your comment above, linking to other manuals, could be solved by having the links open in a new window by adding a target attribute to the link, e.g. <a target="derbymanual" href="../ref/rrefderby.html"/>

        The DITA toolkit would need to be modified to add that attribute, and as such, should probably be handled as a separate issue.

        Show
        Andrew McIntyre added a comment - Kim, issue #1 in your comment above, linking to other manuals, could be solved by having the links open in a new window by adding a target attribute to the link, e.g. <a target="derbymanual" href="../ref/rrefderby.html"/> The DITA toolkit would need to be modified to add that attribute, and as such, should probably be handled as a separate issue.
        Hide
        Kim Haase added a comment -

        Please reopen if you disagree with resolving it.

        Show
        Kim Haase added a comment - Please reopen if you disagree with resolving it.
        Hide
        Kim Haase added a comment -

        I would like to close this longstanding issue. Three of the four requests have been completed. The last request – providing hyperlinks across manuals – is not practicable with the existing tools, for the following reasons:

        1) In the HTML Pages version, the linked-to topic opens in the right-hand frame, replacing the current topic. However, the TOC remains that of the manual containing the link, not the manual linked to. This makes navigation extremely confusing. I don't see any way to correct this, given the way HTML frames work.

        2) In the PDF and the HTML one-page versions, the links do not work at all. In the HTML one-page version, if the link in, for example, the Getting Started manual is to "../adminguide/cadminnetservsecurity.dita#cadminnetservsecurity", the tools truncate it to "#cadminnetservsecurity" – a link within the current manual, not the one linked to, and therefore a bad link. This could possibly be fixed in the tools, but it would be a separate issue.

        Show
        Kim Haase added a comment - I would like to close this longstanding issue. Three of the four requests have been completed. The last request – providing hyperlinks across manuals – is not practicable with the existing tools, for the following reasons: 1) In the HTML Pages version, the linked-to topic opens in the right-hand frame, replacing the current topic. However, the TOC remains that of the manual containing the link, not the manual linked to. This makes navigation extremely confusing. I don't see any way to correct this, given the way HTML frames work. 2) In the PDF and the HTML one-page versions, the links do not work at all. In the HTML one-page version, if the link in, for example, the Getting Started manual is to "../adminguide/cadminnetservsecurity.dita#cadminnetservsecurity", the tools truncate it to "#cadminnetservsecurity" – a link within the current manual, not the one linked to, and therefore a bad link. This could possibly be fixed in the tools, but it would be a separate issue.
        Hide
        Jeff Levitt added a comment -

        Updated status on this issue

        Of the requirements first listed in this issue:

        • Provide manuals in a PDF format (one manual per PDF file, not PDF files for every page...)
        • This is complete, as the Manuals page of the Derby website now links to nightly PDF builds of the docs, and includes a process for users to create their own PDF's from the source. While the PDF's are still not perfect, there will always be ways to improve them, so this is a neverending task.
        • Improve navigation in HTML format. For example, have left hand frame with table of contents and less pages to navigate...
        • This is complete, as the Manuals page of the Derby website now links to nightly html builds of the docs, complete with a navigation page.
        • Provide hyperlinks across manuals
        • Not yet complete. These will have to be hard-coded in...
        • Make it easier to search the manual (on the user's PC, not refering to the Google search on the Derby web site). PDFs will address this. Having less HTML pages would also help here.
        • This is complete (see first two bullets above)

        So the one remaining item on this list is the links between Manuals.

        Show
        Jeff Levitt added a comment - Updated status on this issue Of the requirements first listed in this issue: Provide manuals in a PDF format (one manual per PDF file, not PDF files for every page...) This is complete, as the Manuals page of the Derby website now links to nightly PDF builds of the docs, and includes a process for users to create their own PDF's from the source. While the PDF's are still not perfect, there will always be ways to improve them, so this is a neverending task. Improve navigation in HTML format. For example, have left hand frame with table of contents and less pages to navigate... This is complete, as the Manuals page of the Derby website now links to nightly html builds of the docs, complete with a navigation page. Provide hyperlinks across manuals Not yet complete. These will have to be hard-coded in... Make it easier to search the manual (on the user's PC, not refering to the Google search on the Derby web site). PDFs will address this. Having less HTML pages would also help here. This is complete (see first two bullets above) So the one remaining item on this list is the links between Manuals.
        Show
        John Sisson added a comment - Also see thread http://nagoya.apache.org/eyebrowse/BrowseList?listName=derby-dev@db.apache.org&by=thread&from=950534

          People

          • Assignee:
            Unassigned
            Reporter:
            John Sisson
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development