[
https://issues.apache.org/jira/browse/KARAF-799?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jean-Baptiste Onofré reassigned KARAF-799:
------------------------------------------
Assignee: (was: Jean-Baptiste Onofré)
> Left-side navigation menus for User and Developer guides falling out of sync
> with actual contents
> -------------------------------------------------------------------------------------------------
>
> Key: KARAF-799
> URL: https://issues.apache.org/jira/browse/KARAF-799
> Project: Karaf
> Issue Type: Improvement
> Components: website
> Reporter: Glen Mazza
> Priority: Minor
> Attachments: Solution1.patch, Solution2.patch
>
>
> The karaf/manual/_navigation.conf page holds the left-side menu items you see
> when viewing the HTML of the User's or Developer's Guides:
> [1] website: http://karaf.apache.org/manual/2.2.2/users-guide/index.html
> SVN:
> http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/_navigation.conf?revision=1069882&view=markup
> The above page has fallen out of sync, on both 3.0 and 2.2 branches, because
> there's additional documentation pages in both the User's and Dev's guides
> not shown in the above menu. The definitive contents of both manuals are
> controlled by the index.conf in users-guide and developers-guide under
> karaf-manual:
> http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/index.conf?revision=1138747&view=markup
> http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/developers-guide/index.conf?revision=1138747&view=markup
> On the left-side navigation menu, the definitive links of user's guide and
> dev guide chapters can always be had by directly clicking directly on the
> Developer's Guide or the User's Guide links. That causes the right side
> frame to display the full list of chapters (for example, on [1] above).
> I suspect this to become an ongoing problem over time because people will
> update the latter two but forget to update the former, also, as the guides
> get larger and larger, it will become overly burdensome/ugly for the left
> hand menu to list every chapter/section of the users and developer's guides.
> Keeping just a subset of the chapters in the far-left menu creates the
> additional problem of people not realizing that there's more chapters out
> there than just those shown in the left-side menu -- it's a good habit to
> encourage the reader to just click the Developer's Guide or User's Guide
> title directly to see the definitive list in the right-side frame.
> I see two solutions:
> 1.) Remove from _navigation.conf in 3.0 and 2.2 branches all chapter listings
> from the User's and Developer's Guides (just have the top level User's Guide
> and Developer's Guide links, clicking on which takes you to the official list
> as before.) Those wishing to retain the present functionality can download
> the PDF (which has a live left-side menu constantly in sync), or just
> right-click on a link on the official chapter list from a browser and select
> "Open on New Tab".
> This will be an easier to maintain solution over time, also, I suspect
> there's going to be more left-side manual documents (beyond our current
> User's Guide, Developer's Guide, Commands) so we may want to pull out the
> individual chapter listings anyway. (For example, the three links under XML
> Schemas here: http://karaf.apache.org/index/documentation.html we may wish to
> move to the left-side menu.)
> 2.) Continue with the status quo for the time being, but refresh the
> _navigation.conf with the latest chapter listings, copying into them the
> contents of the index.conf in the user-guide and developers-guide folders.
> Patches for both options (for Karaf 3.0) included.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
