[PATCH xkeyboard-config] Use XSL to generate man page from the rules XML

Peter Hutterer peter.hutterer at who-t.net
Thu Jun 9 22:45:12 PDT 2011


Generate a man-page from the evdev.xml through the xslt/man.xsl stylesheet.

Adds a requirement on the xorg util-macros and xsltproc.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
Taking this from a private thread to a public (archived!) list. Last
argument of discussion was whether to distribute the man pages with the
tarball or let the user build them (adding the requirement of xsltproc to
build from the tarball). I don't care either way and Gaetan indicated that
there are a few painful points when distributing generate man pages. So
I say, screw it, let the users do it.

This should be the patch then.

 Makefile.am     |    2 +-
 configure.in    |   10 ++++
 man/Makefile.am |   17 +++++++
 man/man.xsl     |  133 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 161 insertions(+), 1 deletions(-)
 create mode 100644 man/Makefile.am
 create mode 100644 man/man.xsl

diff --git a/Makefile.am b/Makefile.am
index e98117e..943539f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,6 @@
 AUTOMAKE_OPTIONS = foreign
 
-SUBDIRS = compat geometry keycodes keymap po rules semantics symbols types docs
+SUBDIRS = compat geometry keycodes keymap po rules semantics symbols types docs man
 
 pkgconfigdir = $(datadir)/pkgconfig
 pkgconfig_DATA = xkeyboard-config.pc
diff --git a/configure.in b/configure.in
index 527e807..e98919a 100644
--- a/configure.in
+++ b/configure.in
@@ -3,6 +3,15 @@ AC_CONFIG_SRCDIR(rules/base.xml.in)
 AM_INIT_AUTOMAKE([foreign dist-bzip2])
 AM_MAINTAINER_MODE
 
+# Require X.Org macros 1.12 or later for XORG_WITH_XSLTPROC
+m4_ifndef([XORG_MACROS_VERSION],
+          [m4_fatal([must install xorg-macros 1.12 or later before
+          running autoconf/autogen])])
+XORG_MACROS_VERSION(1.12)
+XORG_MANPAGE_SECTIONS
+XORG_WITH_XSLTPROC
+AC_PROG_SED
+
 AC_SUBST(VERSION)
 
 AC_PATH_PROG([XKBCOMP], [xkbcomp], [not_found])
@@ -104,6 +113,7 @@ types/Makefile
 xkeyboard-config.pc
 xkeyboard-config.spec
 docs/Makefile
+man/Makefile
 ])
 
 echo '***********************************************************'
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..f090f88
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,17 @@
+EXTRA_DIST = man.xsl
+
+if HAVE_XSLTPROC
+miscmandir = $(MISC_MAN_DIR)
+miscman_PRE = xkeyboard-config.man
+miscman_DATA = $(miscman_PRE:man=@MISC_MAN_SUFFIX@)
+CLEANFILES = $(miscman_DATA) $(miscman_PRE)
+SUFFIXES = .$(MISC_MAN_SUFFIX) .man
+MAN_SUBSTS += -e 's|__xkb_base__|$(xkb_base)|g'
+
+xkeyboard-config.man: $(top_builddir)/rules/evdev.xml $(srcdir)/man.xsl
+	$(XSLTPROC) -nonet $(srcdir)/man.xsl $(top_builddir)/rules/evdev.xml > $@
+
+.man.$(MISC_MAN_SUFFIX):
+	$(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
+
+endif
diff --git a/man/man.xsl b/man/man.xsl
new file mode 100644
index 0000000..a46e7af
--- /dev/null
+++ b/man/man.xsl
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" >
+    <xsl:output method="text" encoding="UTF-8" doctype-system="xkb.dtd"/>
+    <xsl:template match="/xkbConfigRegistry">
+        <xsl:text><![CDATA[.\" WARNING: this man page is autogenerated. Do not edit or you will lose all your changes.
+.TH XKEYBOARD-CONFIG __miscmansuffix__ __vendorversion__
+.SH NAME
+xkeyboard-config \- XKB data description files
+.SH DESCRIPTION
+xkeyboard-config provides the description files for the X Keyboard
+Extension (XKB). The configuration options below are usually applied with
+setxkbmap(__appmansuffix__).
+.SH MODELS
+.TS
+lB lB
+___
+lB l.
+Model	Description
+]]></xsl:text>
+        <xsl:apply-templates select="modelList"/>
+        <xsl:text><![CDATA[
+.TE
+.SH LAYOUTS
+.TS
+lB lB
+____
+lB l.
+Layout(Variant)	Description
+]]></xsl:text>
+        <xsl:apply-templates select="layoutList"/>
+        <xsl:text><![CDATA[
+.TE
+.SH OPTIONS
+]]></xsl:text>
+        <xsl:apply-templates select="optionList"/>
+        <xsl:text><![CDATA[
+.SH FILES
+__xkb_base__/compat
+
+__xkb_base__/compiled
+
+__xkb_base__/geometry
+
+__xkb_base__/keycodes
+
+__xkb_base__/keymap
+
+__xkb_base__/rules
+
+__xkb_base__/semantics
+
+__xkb_base__/symbols
+
+__xkb_base__/types
+
+.SH SEE ALSO
+setxkbmap(__appmansuffix__)
+]]></xsl:text>
+    </xsl:template>
+
+<!-- split model/description into a normal table -->
+    <xsl:template match="modelList">
+        <xsl:for-each select="model">
+            <xsl:value-of select="configItem/name"/><xsl:text>&#9;</xsl:text><xsl:value-of select="configItem/description"/>
+            <xsl:text>&#10;</xsl:text>
+        </xsl:for-each>
+    </xsl:template>
+
+<!-- split layout/variant/description into a table like this
+
+        layout1                 description
+        layout1(variant1)       description
+        layout1(variant2)       description
+        layout2                 description
+        layout2(variant1)       description
+-->
+    <xsl:template match="layoutList">
+        <xsl:for-each select="layout">
+            <xsl:value-of select="configItem/name"/>
+            <xsl:text>&#9;</xsl:text>
+            <xsl:value-of select="configItem/description"/>
+            <xsl:text>&#10;</xsl:text>
+            <xsl:for-each select="variantList/variant">
+                <xsl:value-of select="../../configItem/name"/>
+                <xsl:text>(</xsl:text>
+                <xsl:value-of select="configItem/name"/>
+                <xsl:text>)</xsl:text>
+                <xsl:text>&#9;</xsl:text>
+                <xsl:value-of select="configItem/description"/>
+                <xsl:text>&#10;</xsl:text>
+            </xsl:for-each>
+            <xsl:text>&#10;</xsl:text>
+        </xsl:for-each>
+    </xsl:template>
+
+<!-- split option into a table like this
+
+option description:
+        optarg          description
+        optarg          description
+        optarg          description
+
+option2 description:
+        optarg          description
+        optarg          description
+-->
+    <xsl:template match="optionList">
+        <xsl:for-each select="group">
+            <xsl:text><![CDATA[
+.SS]]></xsl:text>
+            <xsl:text>&#10;</xsl:text>
+            <xsl:value-of select="configItem/description"/>
+            <xsl:text><![CDATA[
+.BR
+.TS
+lB lB
+___
+lB l.
+Option	Description
+]]></xsl:text>
+            <xsl:for-each select="option">
+                <xsl:value-of select="configItem/name"/>
+                <xsl:text>&#9;</xsl:text>
+                <xsl:value-of select="configItem/description"/>
+                <xsl:text>&#10;</xsl:text>
+            </xsl:for-each>
+            <xsl:text><![CDATA[
+.TE
+
+]]></xsl:text>
+        </xsl:for-each>
+    </xsl:template>
+</xsl:stylesheet>
-- 
1.7.5.1



More information about the xorg-devel mailing list