[LUDOC-120] Add navigation to the HTML version of the manual

• Status: Resolved
• Project: Lustre Documentation
• Type: Improvement
• Priority: Minor
• Reporter: Linda Bebernes (Inactive)
• Assignee: Lustre Manual Triage
• Resolution: Fixed
• Labels: QInfrastructure
• Business Value: 2

Description

Create a more granular navigation structure for the Lustre manual.

Issue Links

• is related to: LUDOC-119 Segment HTML version of Lustre manual

Comments

[Richard Henwood (Inactive)]

Can you provide a description or link(s) to an example of granular navigation done well?

[Linda Bebernes (Inactive)]

This is a nice example. Unfortunately, I haven't been able to find out which tools were used.
https://developer.tizen.org/documentation/dev-guide

[Richard Henwood (Inactive)]

I was pottering around recently and found the fedora documentation to be pleasantly produced. A brief investigation led me to 'publican'

http://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/

I think publican can give us the desired navigation.

[Richard Henwood (Inactive)]

A further note: Publican version 2.1 is included in CentOS 6.

[Richard Henwood (Inactive)]

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.

[Richard Henwood (Inactive)]

An example of what publican can do with respect to navigation.

[Richard Henwood (Inactive)]

It seems this doesn't render correctly because additional files are missing. This is a zip of the publican output for the manual.

[Richard Henwood (Inactive)]

Zip version of the Publican rendered manual.

[Richard Henwood (Inactive)]

There is a publican build for the template here:

http://review.whamcloud.com/#change,5836

[Richard Henwood (Inactive)]

Webhelp is a chunked html output format in the DocBook xslt stylesheets that was introduced in version 1.76.1.

I've got it working locally, but Docbook 1.76.1 isn't included in CentOS 6 (which is the current manual builder version).

So, a path forward here is update the manual builder to CentOS 7 and land this patch:
http://review.whamcloud.com/#/c/18087

[Gerrit Updater]

Richard Henwood ([e-mail]) uploaded a new patch: http://review.whamcloud.com/18284
Subject: LUDOC-120 webhelp: enable building of webhelp.
Project: doc/manual
Branch: master
Current Patch Set: 1
Commit: 8784f412619e7fc20045e2b986ebb5704edd2e5f

[Gerrit Updater]

Richard Henwood ([e-mail]) uploaded a new patch: http://review.whamcloud.com/18364
Subject: LUDOC-120 webhelp: transform manual to webhelp.
Project: doc/manual
Branch: master
Current Patch Set: 1
Commit: 9b1e424920c8ba7e810fa001fee1994b567c0c2d

[Andreas Dilger]

I believe that this exists today. The .xhtml version has a TOC with links to each section of the manual.

[Richard Henwood (Inactive)]

I was thinking more like this, with search as well:

https://build.hpdd.intel.com/job/lustre-manual-reviews/665/artifact/webhelp-out/index.html

[Andreas Dilger]

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.

[Richard Henwood (Inactive)]

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.

I am in complete support that this is an optional derivative form of the manual - xhtml remains the primary form.

Thanks for spending time on this.

[Gerrit Updater]

Richard Henwood ([e-mail]) merged in patch http://review.whamcloud.com/18087/
Subject: LUDOC-120 presentation: build bits for webhelp.
Project: doc/manual
Branch: master
Current Patch Set:
Commit: 962666465779422201dab192d897b2f886ad1cf0

[Gerrit Updater]

Richard Henwood ([e-mail]) merged in patch http://review.whamcloud.com/18364/
Subject: LUDOC-120 webhelp: transform manual to webhelp.
Project: doc/manual
Branch: master
Current Patch Set:
Commit: 80246f2b00877f6fc49f053884b26f5733c0880b

[Joseph Gmitter (Inactive)]

Patches here have been merged a while back.