You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@karaf.apache.org by "Glen Mazza (JIRA)" <ji...@apache.org> on 2011/07/31 02:28:11 UTC
[jira] [Created] (KARAF-799) Left-side navigation menus for User
and Developer guides falling out of sync with actual contents
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
[jira] [Assigned] (KARAF-799) Left-side navigation menus for User
and Developer guides falling out of sync with actual contents
Posted by "Jean-Baptiste Onofré (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/KARAF-799?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Jean-Baptiste Onofré reassigned KARAF-799:
------------------------------------------
Assignee: 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
> Assignee: Jean-Baptiste Onofré
> 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
[jira] [Assigned] (KARAF-799) Left-side navigation menus for User
and Developer guides falling out of sync with actual contents
Posted by "Jean-Baptiste Onofré (JIRA)" <ji...@apache.org>.
[ 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
[jira] [Updated] (KARAF-799) Left-side navigation menus for User
and Developer guides falling out of sync with actual contents
Posted by "Glen Mazza (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/KARAF-799?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Glen Mazza updated KARAF-799:
-----------------------------
Attachment: Solution1.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
[jira] [Updated] (KARAF-799) Left-side navigation menus for User
and Developer guides falling out of sync with actual contents
Posted by "Glen Mazza (JIRA)" <ji...@apache.org>.
[ 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