Details
-
Improvement
-
Status: Resolved
-
Minor
-
Resolution: Fixed
-
None
-
None
-
None
Description
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.