https://jira.whamcloud.com This file is an XML representation of an issue en-us 9.4.14 940014 05-12-2023 https://jira.whamcloud.com/browse/LUDOC-120 Lustre Documentation <p>Create a more granular navigation structure for the Lustre manual.</p> LUDOC-120

Add navigation to the HTML version of the manual

Improvement Minor Resolved Fixed Lustre Manual Triage Linda Bebernes QInfrastructure Tue, 15 Jan 2013 13:28:44 +0000 Wed, 25 Oct 2017 15:46:35 +0000 Wed, 25 Oct 2017 15:46:35 +0000 0 4 <p>Can you provide a description or link(s) to an example of granular navigation done well?</p> <p>This is a nice example. Unfortunately, I haven't been able to find out which tools were used.<br/> <a href="https://developer.tizen.org/documentation/dev-guide" class="external-link" target="_blank" rel="nofollow noopener">https://developer.tizen.org/documentation/dev-guide</a></p> <p>I was pottering around recently and found the fedora documentation to be pleasantly produced. A brief investigation led me to 'publican'</p> <p><a href="http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/" class="external-link" target="_blank" rel="nofollow noopener">http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/</a></p> <p>I think publican can give us the desired navigation.</p> <p>A further note: Publican version 2.1 is included in CentOS 6.</p> <p>Docbook 5 (the version used by our existing Manual) support became experimental in 3.0. The current version is 3.1. I'm investigating it's suitability for the Lustre manual.</p> <p>An example of what publican can do with respect to navigation.</p> <p>It seems this doesn't render correctly because additional files are missing. This is a zip of the publican output for the manual.</p> <p>Zip version of the Publican rendered manual.</p> <p>There is a publican build for the template here:</p> <p><a href="http://review.whamcloud.com/#change,5836" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/#change,5836</a></p> <p>Webhelp is a chunked html output format in the DocBook xslt stylesheets that was introduced in version 1.76.1. </p> <p>I've got it working locally, but Docbook 1.76.1 isn't included in CentOS 6 (which is the current manual builder version).</p> <p>So, a path forward here is update the manual builder to CentOS 7 and land this patch:<br/> <a href="http://review.whamcloud.com/#/c/18087" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/#/c/18087</a></p> <p>Richard Henwood (richard.henwood@intel.com) uploaded a new patch: <a href="http://review.whamcloud.com/18284" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/18284</a><br/> Subject: <a href="https://jira.whamcloud.com/browse/LUDOC-120" title="Add navigation to the HTML version of the manual" class="issue-link" data-issue-key="LUDOC-120"><del>LUDOC-120</del></a> webhelp: enable building of webhelp.<br/> Project: doc/manual<br/> Branch: master<br/> Current Patch Set: 1<br/> Commit: 8784f412619e7fc20045e2b986ebb5704edd2e5f</p> <p>Richard Henwood (richard.henwood@intel.com) uploaded a new patch: <a href="http://review.whamcloud.com/18364" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/18364</a><br/> Subject: <a href="https://jira.whamcloud.com/browse/LUDOC-120" title="Add navigation to the HTML version of the manual" class="issue-link" data-issue-key="LUDOC-120"><del>LUDOC-120</del></a> webhelp: transform manual to webhelp.<br/> Project: doc/manual<br/> Branch: master<br/> Current Patch Set: 1<br/> Commit: 9b1e424920c8ba7e810fa001fee1994b567c0c2d</p> <p>I believe that this exists today. The .xhtml version has a TOC with links to each section of the manual.</p> <p>I was thinking more like this, with search as well:</p> <p><a href="https://build.hpdd.intel.com/job/lustre-manual-reviews/665/artifact/webhelp-out/index.html" class="external-link" target="_blank" rel="nofollow noopener">https://build.hpdd.intel.com/job/lustre-manual-reviews/665/artifact/webhelp-out/index.html</a></p> <p>Looks nice, though "Command-F" or "Ctrl-F" searching in the current HTML or PDF doc also works, and doesn't require Java (or whatever) complicating the access and distribution of the manual in HTML format. I'm not against it, but there is also value in simplicity and ease of access/distribution of the document. I definitely don't want this to become the only way to access the manual online.</p> <p>The Java requirement is only during the creation of the webhelp format to construct an index. The search in the webhelp output uses this pre-generated index file and javascript. In my experience it out performs ctrl-f. For example, a search of LFSCK pulls up a short list of topic subjects.</p> <p>I am in complete support that this is an optional derivative form of the manual - xhtml remains the primary form.</p> <p>Thanks for spending time on this.</p> <p>Richard Henwood (richard.henwood@intel.com) merged in patch <a href="http://review.whamcloud.com/18087/" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/18087/</a><br/> Subject: <a href="https://jira.whamcloud.com/browse/LUDOC-120" title="Add navigation to the HTML version of the manual" class="issue-link" data-issue-key="LUDOC-120"><del>LUDOC-120</del></a> presentation: build bits for webhelp.<br/> Project: doc/manual<br/> Branch: master<br/> Current Patch Set: <br/> Commit: 962666465779422201dab192d897b2f886ad1cf0</p> <p>Richard Henwood (richard.henwood@intel.com) merged in patch <a href="http://review.whamcloud.com/18364/" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/18364/</a><br/> Subject: <a href="https://jira.whamcloud.com/browse/LUDOC-120" title="Add navigation to the HTML version of the manual" class="issue-link" data-issue-key="LUDOC-120"><del>LUDOC-120</del></a> webhelp: transform manual to webhelp.<br/> Project: doc/manual<br/> Branch: master<br/> Current Patch Set: <br/> Commit: 80246f2b00877f6fc49f053884b26f5733c0880b</p> <p>Patches here have been merged a while back.</p> Blocker Related LUDOC-119 Business Value 2.0 Development Rank 1|hzvfbj: Rank (Obsolete) 6128