#1338 db4-upgrade and manpages generation

[Mathieu Malaterre]

docbook 1.78.1 does not produce valid manpages output, see attached file: glMemoryBarrier.3G

Steps:
$ xsltproc -o glMemoryBarrier-db4.xml /usr/share/xml/docbook/stylesheet/docbook5/db4-upgrade.xsl glMemoryBarrier.xml
$ xsltproc opengl-manpages.xsl glMemoryBarrier-db4.xml

Where glMemoryBarrier.xml and opengl-manpages.xsl are attached.

Thanks.

[Mathieu Malaterre]

Adding glMemoryBarrier.xml

[Mathieu Malaterre]

Adding opengl-manpages.xsl

[Mathieu Malaterre]

Just in case directly converting the docbook 4 to man page using the original file does work. So something is either broken in db4-upgrade or the manpages mecanism does not cope with db 5 files.

[Robert Stayton]

Actually, the 1.78.1 manpage stylesheet produces the correct result with your DB5 file. But the files at http://docbook.sourceforge.net/release/xsl/current/ are not 1.78.1, they are some mix of older files. I'm not sure how or when those files were messed up, so I'll need to investigate.

In the mean time, you should use an XML catalog to map that URL to a local copy of the 1.78.1 stylesheet (or use it directly without a catalog), and you will get the correct results. BTW, I don't recommend running an XSL process over the web anyway. It can be very slow because DocBook XSL uses a lot of files/.

[Robert Stayton]

I have investigated this issue further, and I have determined that the upgraded file is correct, and the stylesheets under /current on SourceForge are also correct. The problem comes from processing the converted db5 source file with the manpage stylesheet intended for db4. Your opengl-manpages.xsl imports

<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"

which are the db4 stylesheets. For db5 documents you should instead import:

<xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/manpages/docbook.xsl"

(replace /xsl/ with /xsl-ns/ in the URL).

Generally using /xsl/ works because when the db4 stylesheet detects a db5 document, it applies templates in mode="stripNS" to strip the namespace from the document so the db4 templates will match. In this case, that process somehow allows whitespace nodes in the source file to be passed through the man page output, creating the incorrect format you see. I'm still trying to track down exactly why that happens, but you should be able to use the db5 stylesheet with your db5 source with good results.

[Robert Stayton]

OK, I figured out the problem. In manpages/other.xsl, there is an xsl:strip-space element that cleans out nonsignificant whitespace between elements at parse time, by listing the element names. When the db5 file is processed with the db4 stylesheet, that strip-space list of elements are all non-namespaced (no d: prefix), so they don't match the db5 elements, and no space is stripped. If I copy the xsl:strip-space element from the xsl-ns stylesheet to your customization layer that imports the db4 stylesheet, then it matches on the db5 elements when they are parsed, and the extra white space is removed before the content is passed to stripNS.

[Mathieu Malaterre]

Wonderful ! Thanks much. Feel free to close this issue.