[LUDOC-13] reviewing changes is difficult in docbook xml

• Type: Improvement
• Resolution: Unresolved
• Priority: Minor
• Labels: QInfrastructure
• Business Value: 25
• Assignee: Lustre Manual Triage
• Reporter: Richard Henwood (Inactive)

Description

I suggest that the Makefile be enhanced with a 'make htmldiff'.

I have had some success with:

1. Build a manual.html (xhtml-1_1) from MASTER:

   xsltproc --stringparam  fop1.extensions  1 --stringparam  section.label.includes.component.label 1 --stringparam  section.autolabel 1 --stringparam  chapter.autolabel 1 --stringparam  appendix.autolabel 1 --xinclude -o /tmp/newmanual.html /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/xhtml-1_1/docbook.xsl ./index.xml
   

2. Build a newmanual.html (xhtml-1_1) from REVIEW.
3. Create a diff.html with diff annotation using diff.py
4. Point browser at diff.html.

Issue Links

• Trackbacks: Guidance for Manual reviewers The Lustre manual is written in XML and changes can be made using Gerrit workflow typical for code. However some additional tips are necessary to ensure high quality reviews. Always visit the HTML or PDF version of the document....
• Trackbacks: Guidance for Manual reviewers The Lustre manual is written in XML and changes can be made using Gerrit workflow typical for code. However some additional tips are necessary to ensure high quality reviews. Always visit the HTML or PDF version of the document....

Comments

[Richard Henwood (Inactive)]

I've recently needed to do a diff again, and found that:

https://github.com/cygri/htmldiff

produces ok output on my test (but is slow.)

[Richard Henwood (Inactive)]

An additional enhancement is now available:

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

[Richard Henwood (Inactive)]

A couple of tweaks to the make file and ./diff.py are available here:

http://review.whamcloud.com/1909

[Richard Henwood (Inactive)]

Joshua has fixed IT-44, progress continues...

[Richard Henwood (Inactive)]

I believe the problem here is that the xhtml artifacts are not appearing in the expect place at the end of the build:

http://jira.whamcloud.com/browse/IT-44

[Richard Henwood (Inactive)]

Change,1127 has landed. However, xhtml is still not being built.

Either LUDOC-8 needs to land or a manual build job modification needs to be made.

[Richard Henwood (Inactive)]

First draft at this feature:

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

NOTE: This depends on MASTER branch xhtml being built and available on build.whamcloud.com. This is not currently available.

[Richard Henwood (Inactive)]

The current html build task does not produce xhtml-1_1. Using diff.py on the current html output does not produce a useful result.

It is probably prudent to wait for LUDOC-8 to complete first. This should enable simple addition of a xhtml build target.