karaf-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Glen Mazza (JIRA)" <j...@apache.org>
Subject [jira] [Updated] (KARAF-799) Left-side navigation menus for User and Developer guides falling out of sync with actual contents
Date Sun, 31 Jul 2011 00:28:11 GMT

     [ https://issues.apache.org/jira/browse/KARAF-799?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]

Glen Mazza updated KARAF-799:
-----------------------------

    Attachment: Solution2.patch

> 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.
For more information on JIRA, see: http://www.atlassian.com/software/jira

        

Mime
View raw message