Description: Proposed improvements to the Khronos OpenCL man pages package
 Ref: http://lists.alioth.debian.org/pipermail/pkg-nvidia-devel/2013-May/008821.html
Author: Giuseppe Bilotta <giuseppe.bilotta@gmail.com>
Forwarded: no
Reviewed-By: Mathieu Malaterre <malat@debian.org>
Last-Update: 2013-05-30

Index: khronos-opencl-man-1.0~svn27110/Makefile
===================================================================
--- khronos-opencl-man-1.0~svn27110.orig/Makefile	2014-06-18 21:24:34.678206415 +0200
+++ khronos-opencl-man-1.0~svn27110/Makefile	2014-06-18 21:24:44.798206278 +0200
@@ -25,7 +25,8 @@
 include $(ROOT)/usr/include/make/commondefs
 
 SUBDIRS = \
-	html \
+	xhtml \
+	man \
 	$(NULL)
 
 default $(ALLTARGS): $(_FORCE)
Index: khronos-opencl-man-1.0~svn27110/man/Makefile
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ khronos-opencl-man-1.0~svn27110/man/Makefile	2014-06-18 21:24:37.190206382 +0200
@@ -0,0 +1,70 @@
+#!gmake
+
+# This Makefile is used to transform OpenCL reference pages in DocBook XML format to man pages.
+# The input .xml files are assumed to be in the parent directory
+
+# XSLT processor - other possibilities like Saxon exist
+XSLT	= xsltproc --nonet
+
+SED	= sed
+MV	= mv
+
+# Location of locally customized stylesheet, which imports
+# the Docbook modular stylesheets, and specifically the
+# stylesheet to convert Docbook+MathML => man+MathML
+DB2MAN = opencl-manpages.xsl
+
+# OpenCL man pages currently need some preprocessing to produce quality man pages.
+# This is done using the following XSLT
+DB2MANPRE = opencl-manpages-pre.xsl
+
+# The Khronos Group also provides a ruby script that fixups named-section links to the
+# OpenCL specifications into links to the appropriate pages on the PDF. We extract the relevant data
+# from this script to assemble a an XSLT that does something similar for us
+SECREF2PAGE = section-to-page.xml
+
+.SUFFIXES: .xml .3clc .xsl
+
+# The list of man pages to be produced. This is obtained by changing the extension of all
+# source files that contain the '<keyword>' tag.
+MANFILES=$(patsubst %.xml,%.3clc,$(shell cd .. && grep -l '<keyword>' *.xml))
+
+default: $(MANFILES)
+
+# Some source files depend on additional files. These dependencies can be extracted running
+#    grep '!ENTITY' *.xml | sed -e 's/:.*SYSTEM "/: ..\//' -e 's/">//' -e 's/\.xml:/.3cl:/'
+# in the source file directory
+XMLDEPS=Makefile.xmldeps
+
+$(XMLDEPS):
+	(cd .. && grep '!ENTITY' *.xml | sed -e 's/:.*SYSTEM "/: ..\//' -e 's/">//' -e 's/\.xml:/.3clc:/') > $@
+
+sinclude $(XMLDEPS)
+
+$(SECREF2PAGE): ../xhtml/pageNumberLookup.rb Makefile
+	@echo '<sections>' > $@
+	@$(SED) -n -e '/=>/ { s!^\s\+!<section id=! ; s!\s\+=>\s\+\[!><spec>! ; s!, !</spec><page>! ; s!\],\s\+\# !</page><title>! ; s!$$!</title></section>! ; p }' \
+		$< >> $@
+	@echo '</sections>' >> $@
+
+
+# First preprocess the original docbook to a more man-compatible form
+# Then turn it into an actual manpage
+# And finally do some whitespace cleanup to fix some DB2MAN problems:
+# * unindent lines (this is necessary to fix some indented .RE commands,
+#   and also fixes other spurious indentation that have only aesthetical
+#   effects)
+# * much less aggressive interparagraph spacing
+%.3clc: ../%.xml $(DB2MAN) $(DB2MANPRE) $(SECREF2PAGE)
+	@$(XSLT) --xinclude -o $@.tmp $(DB2MANPRE) $<
+	@$(XSLT) --xinclude -o $@ $(DB2MAN) $@.tmp
+	@$(SED) -i -e 's/^\s\+//' -e '/^.sp$$/ {N;N;s/^\.sp\n\n/.sp/}' $@
+	@$(RM) $@.tmp
+
+clean:
+	$(RM) $(MANFILES)
+
+clobber: clean
+	$(RM) $(XMLDEPS) $(SECREF2PAGE)
+
+
Index: khronos-opencl-man-1.0~svn27110/man/opencl-manpages-pre.xsl
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ khronos-opencl-man-1.0~svn27110/man/opencl-manpages-pre.xsl	2014-06-18 21:24:37.190206382 +0200
@@ -0,0 +1,182 @@
+<?xml version='1.0'?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+    <xsl:output
+        doctype-public="-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
+        doctype-system="http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"
+        cdata-section-elements="book"
+        indent="yes"
+        encoding="UTF-8"
+    />
+
+    <!-- split an element with comma-separated text into multiple elements -->
+    <xsl:template name="str.split">
+        <xsl:param name="text"/>
+        <xsl:param name="elem"/>
+        <xsl:param name="sep" />
+        <xsl:if test="string-length($text) > 0">
+            <xsl:variable name="next" select="substring-before(concat($text,$sep), $sep)"/>
+            <xsl:element name="{$elem}">
+                <xsl:value-of select="normalize-space($next)"/>
+            </xsl:element>
+            <xsl:call-template name="str.split">
+                <xsl:with-param name="text" select="substring-after($text, $sep)"/>
+                <xsl:with-param name="elem" select="$elem"/>
+                <xsl:with-param name="sep" select="$sep"/>
+            </xsl:call-template>
+        </xsl:if>
+    </xsl:template>
+
+    <!-- identity transform, for nodes that do not match anything else -->
+    <xsl:template match="@*|node()">
+        <xsl:copy>
+            <xsl:apply-templates select="@*|node()"/>
+        </xsl:copy>
+    </xsl:template>
+
+    <xsl:template match="refpurpose">
+    <refpurpose>
+    <xsl:value-of select="normalize-space(.)"/>
+    </refpurpose>
+    </xsl:template>
+
+    <xsl:template match="refname">
+    <refname>
+    <xsl:value-of select="normalize-space(.)"/>
+    </refname>
+    </xsl:template>
+
+    <xsl:template match="refentrytitle">
+    <refentrytitle>
+    <xsl:value-of select="normalize-space(.)"/>
+    </refentrytitle>
+    </xsl:template>
+
+    <!-- keywords should be individual keywords, not a comma-separated list -->
+    <xsl:template match="keyword">
+        <xsl:call-template name="str.split">
+            <xsl:with-param name="text" select="."/>
+            <xsl:with-param name="elem" select="'keyword'"/>
+            <xsl:with-param name="sep" select="', '"/>
+        </xsl:call-template>
+    </xsl:template>
+    <!-- TODO the same treatment should be reserved to refentrytitle -->
+
+    <!-- The khronos documents are marked to be in man section 3, but this
+         causes conflicts with the C standard library pages (e.g. cbrt).
+         Append 'cl' to the OpenCL sections to resolve the conflict. -->
+    <xsl:template match="/refentry/refmeta/manvolnum">
+        <manvolnum>
+            <xsl:value-of select="concat(normalize-space(.), 'clc')"/>
+        </manvolnum>
+    </xsl:template>
+
+    <!-- copyright/holder should only be the copyright holder. The rest of the legal notice should
+         go into a legalnotice element inside refentryinfo -->
+    <xsl:template match="copyright/holder">
+        <holder>
+            <xsl:value-of select="concat(substring-before(normalize-space(), '. '), '.')"/>
+        </holder>
+    </xsl:template>
+
+    <!-- The copyright info should be inside refentryinfo, not inside refmeta/refmiscinfo -->
+    <xsl:template match="/refentry/refentryinfo">
+        <xsl:copy>
+            <!-- copy existing stuff in refentryinfo -->
+            <xsl:apply-templates select="@*|node()"/>
+            <!-- copy and fix the copyright; note that this can't all be done from the
+                 copyright/holder template because the legalnotice must go out -->
+            <xsl:variable name="wrongpath" select="../refmeta/refmiscinfo/copyright"/>
+            <!-- extract copyright/holder text -->
+            <xsl:variable name="cprt" select="normalize-space($wrongpath)"/>
+            <xsl:apply-templates select="$wrongpath"/>
+            <xsl:element name="legalnotice">
+                <!-- get the text after the first full-stop in the former
+                     copyright/holder text -->
+                <xsl:value-of select="substring-after($cprt, '. ')"/>
+            </xsl:element>
+            <!-- while we're at it, add the orgname that should go here too -->
+            <xsl:element name="orgname">
+                <xsl:attribute name="class">consortium</xsl:attribute>
+                <xsl:text>The Khronos Group</xsl:text>
+            </xsl:element>
+        </xsl:copy>
+    </xsl:template>
+    <!-- delete the copyright from original position, as well as the now-empty refmiscinfo
+         TODO: check that refmiscinfo is actually empty.
+         This is simply done by NOT copying it to the output file -->
+    <xsl:template match="/refentry/refmeta/refmiscinfo"/>
+
+    <!-- now we recreate refmiscinfo to read "OpenCL Manual" -->
+    <xsl:template match="/refentry/refmeta">
+        <xsl:copy>
+            <!-- again, copy existing children -->
+            <xsl:apply-templates select="@*|node()"/>
+            <!-- and add our new refmiscinfo now -->
+            <xsl:element name="refmiscinfo">
+                <xsl:attribute name="class">manual</xsl:attribute>
+                <xsl:text>OpenCL Manual</xsl:text>
+            </xsl:element>
+        </xsl:copy>
+    </xsl:template>
+
+    <!-- links are used throughout the OpenCL man pages to cross-reference enums and data types.
+         For the manpages production, we replace them with their textual content -->
+    <!-- TODO: we might want to automatically add these to the "see also" section" -->
+    <xsl:template match="link">
+        <xsl:value-of select="normalize-space(.)"/>
+    </xsl:template>
+
+    <!-- paramdefs have no space after them, and the * is inside the parameter,
+         so we manipulate them to add a space, and a * if necessary;
+         parameter elements are stripped of the leading * -->
+    <xsl:template match="paramdef/parameter/text()[starts-with(.,'*')]">
+        <xsl:value-of select="substring-after(., '*')"/>
+    </xsl:template>
+    <xsl:template match="paramdef/parameter">
+        <xsl:text> </xsl:text>
+        <xsl:if test="starts-with(text(), '*')">
+            <xsl:text>*</xsl:text>
+        </xsl:if>
+        <xsl:copy>
+            <xsl:apply-templates select="@*|node()"/>
+        </xsl:copy>
+    </xsl:template>
+
+<!--
+         section manipulation
+-->
+
+    <!-- 'specification' section: skip the image. -->
+    <xsl:template match="refsect1[@id='specification']//imageobject"/>
+
+    <!-- turn olinks into ulinks with an url attribute that renders to page XX, section Title,
+         using data looked up from the section-to-page.xml table -->
+    <xsl:key name='specref' match='section' use='@id'/>
+    <xsl:template match="olink">
+        <xsl:variable name="secref" select="@uri"/>
+        <xsl:element name="ulink">
+            <xsl:attribute name="url">
+                <!-- TODO there must be a way to collect both in one go -->
+                <xsl:text>page </xsl:text>
+                <xsl:for-each select="document('section-to-page.xml')">
+                    <xsl:value-of select="key('specref', $secref)/page"/>
+                </xsl:for-each>
+                <xsl:text>, section </xsl:text>
+                <xsl:for-each select="document('section-to-page.xml')">
+                    <xsl:value-of select="key('specref', $secref)/title"/>
+                </xsl:for-each>
+            </xsl:attribute>
+            <xsl:apply-templates/>
+        </xsl:element>
+    </xsl:template>
+
+    <!-- don't copy 'copyright' section, it's automatically created from the legal notice -->
+    <xsl:template match="refsect3[@id='Copyright']"/>
+
+    <!-- Also see is more usually written See also in man pages-->
+    <xsl:template match="refsect1[@id='seealso']/title">
+        <title>See also</title>
+    </xsl:template>
+
+</xsl:stylesheet>
Index: khronos-opencl-man-1.0~svn27110/man/opencl-manpages.xsl
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ khronos-opencl-man-1.0~svn27110/man/opencl-manpages.xsl	2014-06-18 21:24:37.190206382 +0200
@@ -0,0 +1,51 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>
+<xsl:param name="man.base.url.for.relative.links"></xsl:param>
+
+<!-- OpenCL XML sources are not very man-friendly: they have a single
+     refentry with comma-space separated entries instead of multiple refentries,
+     and some general pages have refentry names that are not individual function names.
+     Therefore, we can't use the default write.man.file template from the docbook manpage
+     stylesheet, and it's better to specify the output filename on the command line instead. -->
+<xsl:template name="write.man.file">
+    <xsl:param name="name"/>
+    <xsl:param name="section"/>
+    <xsl:param name="lang"/>
+    <xsl:param name="content"/>
+    <xsl:call-template name="write.text.chunk">
+        <xsl:with-param name="filename" select="''"/>
+        <xsl:with-param name="suppress-context-node-name" select="1"/>
+        <xsl:with-param name="quiet" select="$man.output.quietly"/>
+        <xsl:with-param
+            name="message-prolog"
+            >Note: </xsl:with-param>
+        <xsl:with-param name="encoding" select="$man.output.encoding"/>
+        <xsl:with-param name="content" select="$content"/>
+    </xsl:call-template>
+</xsl:template>
+
+    <!-- citerefentry should use the href to get the correct reference if present.
+         also, no manvolnum is specified in the OpenCL pages, so assume our own -->
+    <xsl:template match="citerefentry">
+        <xsl:variable name="vol" select="/refentry/refmeta/manvolnum"/>
+        <xsl:variable name="entry">
+            <xsl:choose>
+                <xsl:when test="@href">
+                    <xsl:value-of select="@href"/>
+                </xsl:when>
+                <xsl:otherwise>
+                    <xsl:value-of select="refentrytitle"/>
+                </xsl:otherwise>
+            </xsl:choose>
+        </xsl:variable>
+        <xsl:call-template name="do-citerefentry">
+            <xsl:with-param name="refentrytitle" select="$entry"/>
+            <xsl:with-param name="manvolnum" select="$vol"/>
+        </xsl:call-template>
+    </xsl:template>
+
+
+</xsl:stylesheet>