[PATCH wayland 1/3] doc: Enable docbook building without Publican also

Tiago Vignatti tiago.vignatti at intel.com
Wed Nov 14 08:18:21 PST 2012


This patch enables the docbook XML documentation to be built even in the
absence of the Publican tool. Though, when lacking Publican, no pdf/html/etc
conversion from XML is performed yet.

Signed-off-by: Tiago Vignatti <tiago.vignatti at intel.com>
---
 doc/Wayland/Makefile.am             |   43 +++++++++++----------
 doc/Wayland/doxygen-to-docbook.xsl  |   72 +++++++++++++++++++++++++++++++++++
 doc/Wayland/doxygen-to-publican.xsl |   72 -----------------------------------
 3 files changed, 94 insertions(+), 93 deletions(-)
 create mode 100644 doc/Wayland/doxygen-to-docbook.xsl
 delete mode 100644 doc/Wayland/doxygen-to-publican.xsl

diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
index f919a89..6c328ea 100644
--- a/doc/Wayland/Makefile.am
+++ b/doc/Wayland/Makefile.am
@@ -1,4 +1,4 @@
-publican_sources = \
+doc_sources = \
 	$(srcdir)/en_US/Wayland.ent \
 	$(srcdir)/en_US/Wayland.xml \
 	$(srcdir)/en_US/Book_Info.xml \
@@ -15,15 +15,13 @@ publican_sources = \
 	$(srcdir)/en_US/images/wayland.png  \
 	$(srcdir)/en_US/images/x-architecture.png
 
-if HAVE_PUBLICAN
-noinst_DATA = Wayland $(publican_targets)
-pubdir = $(docdir)/Wayland/en-US
+noinst_DATA = Wayland $(doc_targets)
+doc_dir = $(docdir)/Wayland/en-US
 
-publican_targets = $(publican_sources:$(srcdir)/en_US%=$(builddir)/en-US%) \
+doc_targets = $(doc_sources:$(srcdir)/en_US%=$(builddir)/en-US%) \
 	en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml \
 	en-US/WaylandClientAPI.xml
 
-# The Protocol.xml is purely generated and required before running publican
 en-US/ProtocolSpec.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/protocol-to-docbook.xsl
 	$(AM_V_GEN)$(MKDIR_P) en-US/images
 	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-to-docbook.xsl \
@@ -37,7 +35,7 @@ en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/proto
 # WaylandClientAPI.xml is generated after combining all xml in one single file
 # with the exception of wayland-client_8h.xml that is omitted to not duplicate
 # the output methods.
-en-US/WaylandClientAPI.xml: $(top_builddir)/doc/doxygen/xml/index.xml $(srcdir)/doxygen-to-publican.xsl
+en-US/WaylandClientAPI.xml: $(top_builddir)/doc/doxygen/xml/index.xml $(srcdir)/doxygen-to-docbook.xsl
 	$(AM_V_GEN)$(MKDIR_P) en-US/images
 	$(AM_V_GEN)mv $(top_srcdir)/doc/doxygen/xml/wayland-client_8h.xml \
 		$(top_srcdir)/doc/doxygen/
@@ -46,20 +44,21 @@ en-US/WaylandClientAPI.xml: $(top_builddir)/doc/doxygen/xml/index.xml $(srcdir)/
 		$(top_srcdir)/doc/doxygen/xml/clientAPI.xml
 	$(AM_V_GEN)mv $(top_srcdir)/doc/doxygen/wayland-client_8h.xml \
 		$(top_srcdir)/doc/doxygen/xml
-	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/doxygen-to-publican.xsl \
+	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/doxygen-to-docbook.xsl \
 		$(top_builddir)/doc/doxygen/xml/clientAPI.xml > en-US/WaylandClientAPI.xml
 
 # Copy the en_US source files into en-US destination
 # This is required for out-of-source-tree build as publican does not allow us
 # to specify the location of the source code.
-$(builddir)/en-US/%: $(srcdir)/en_US/% en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_sources)
+$(builddir)/en-US/%: $(srcdir)/en_US/% en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(doc_sources)
 	$(AM_V_GEN)cp -f $< $@
 	$(AM_V_GEN)chmod a+w $@
 
+if HAVE_PUBLICAN
 # Run publican for the builddir on the generated (or copied) source
 # The output formats are generated in the Wayland sub directory. Also, we need
 # to use a tmp publican.cfg cause 'publican rename' modifies the original.
-Wayland: $(publican_targets)
+Wayland: $(doc_targets)
 	$(AM_V_GEN)cp -f $(srcdir)/publican.cfg $(builddir)/publican-copy.cfg
 	$(AM_V_GEN)$(PUBLICAN) rename --name Wayland \
 		--version "$(WAYLAND_VERSION_MAJOR).$(WAYLAND_VERSION_MINOR)" \
@@ -67,8 +66,12 @@ Wayland: $(publican_targets)
 	$(AM_V_GEN)$(PUBLICAN) build --quiet --lang en-US --format html,pdf \
 		--config $(builddir)/publican-copy.cfg
 	@touch Wayland
+else
+Wayland: $(doc_targets)
+	$(AM_V_GEN)mkdir -p $(srcdir)/Wayland
+endif
 
-CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_targets)
+CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(doc_targets)
 
 clean-local:
 	$(AM_V_at)rm -fr $(builddir)/en-US
@@ -76,13 +79,13 @@ clean-local:
 	$(AM_V_at)rm -fr $(builddir)/publican-copy.cfg
 
 install-data-local:
-	test -z "$(pubdir)/html/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/Common_Content/css"
-	test -z "$(pubdir)/html/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/Common_Content/images"
-	test -z "$(pubdir)/html/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/images"
-	test -z "$(pubdir)/pdf" || $(mkdir_p) "$(DESTDIR)$(pubdir)/pdf"
-	test -z "$(pubdir)/xml/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/Common_Content/css"
-	test -z "$(pubdir)/xml/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/Common_Content/images"
-	test -z "$(pubdir)/xml/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/xml/images"
+	test -z "$(doc_dir)/html/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(doc_dir)/html/Common_Content/css"
+	test -z "$(doc_dir)/html/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(doc_dir)/html/Common_Content/images"
+	test -z "$(doc_dir)/html/images" || $(mkdir_p) "$(DESTDIR)$(doc_dir)/html/images"
+	test -z "$(doc_dir)/pdf" || $(mkdir_p) "$(DESTDIR)$(doc_dir)/pdf"
+	test -z "$(doc_dir)/xml/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(doc_dir)/xml/Common_Content/css"
+	test -z "$(doc_dir)/xml/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(doc_dir)/xml/Common_Content/images"
+	test -z "$(doc_dir)/xml/images" || $(mkdir_p) "$(DESTDIR)$(doc_dir)/xml/images"
 	list=`find $(builddir)/Wayland/en-US -type f -not -path '$(builddir)/Wayland/en-US/xml_tmp*'`; \
 	for p in $$list; do \
 	  echo " $(INSTALL_DATA) '$$p' '$(DESTDIR)$(docdir)/$$p'"; \
@@ -97,6 +100,4 @@ uninstall-local:
 	  fi; \
 	fi;
 
-endif
-
-EXTRA_DIST = $(publican_sources) publican.cfg protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-publican.xsl
+EXTRA_DIST = $(doc_sources) publican.cfg protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-docbook.xsl
diff --git a/doc/Wayland/doxygen-to-docbook.xsl b/doc/Wayland/doxygen-to-docbook.xsl
new file mode 100644
index 0000000..3ddcbd3
--- /dev/null
+++ b/doc/Wayland/doxygen-to-docbook.xsl
@@ -0,0 +1,72 @@
+<?xml version="1.0" ?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="xml" encoding="UTF-8" indent="yes" />
+
+<xsl:template match="/">
+  <!-- insert docbook's DOCTYPE blurb -->
+    <xsl:text disable-output-escaping = "yes"><![CDATA[
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+  <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
+%BOOK_ENTITIES;
+]>
+]]></xsl:text>
+
+  <section id="sect-Library-Client">
+    <title>Client API</title>
+    <para>Following is the Wayland library classes for clients
+	  (<emphasis>libwayland-client</emphasis>). Note that most of the
+	  procedures are related with IPC, which is the main responsibility of
+	  the library.
+    </para>
+
+    <para>
+    <variablelist>
+    <xsl:apply-templates select="/doxygen/compounddef" />
+    </variablelist>
+    </para>
+
+    <para>And methods for the respective classes.</para>
+
+    <para>
+    <variablelist>
+    <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" />
+    </variablelist>
+    </para>
+  </section>
+</xsl:template>
+
+
+<!-- methods -->
+<xsl:template match="memberdef" >
+    <xsl:if test="@kind = 'function' and @static = 'no'">
+    <varlistentry>
+        <term>
+        <xsl:value-of select="name" />
+        - <xsl:value-of select="briefdescription" />
+        </term>
+        <listitem>
+            <para></para>
+        </listitem>
+    </varlistentry>
+    </xsl:if>
+</xsl:template>
+
+<!-- classes -->
+<xsl:template match="compounddef" >
+    <xsl:if test="@kind = 'class' ">
+    <varlistentry>
+        <term>
+            <xsl:value-of select="compoundname" />
+            <xsl:if test="briefdescription">
+                - <xsl:value-of select="briefdescription" />
+            </xsl:if>
+        </term>
+
+        <!-- TODO: the output text is not splitting paragraphs correctly -->
+        <listitem>
+            <para><xsl:value-of select="detaileddescription"/></para>
+        </listitem>
+    </varlistentry>
+    </xsl:if>
+</xsl:template>
+</xsl:stylesheet>
diff --git a/doc/Wayland/doxygen-to-publican.xsl b/doc/Wayland/doxygen-to-publican.xsl
deleted file mode 100644
index 3ddcbd3..0000000
--- a/doc/Wayland/doxygen-to-publican.xsl
+++ /dev/null
@@ -1,72 +0,0 @@
-<?xml version="1.0" ?>
-<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
-<xsl:output method="xml" encoding="UTF-8" indent="yes" />
-
-<xsl:template match="/">
-  <!-- insert docbook's DOCTYPE blurb -->
-    <xsl:text disable-output-escaping = "yes"><![CDATA[
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-  <!ENTITY % BOOK_ENTITIES SYSTEM "Wayland.ent">
-%BOOK_ENTITIES;
-]>
-]]></xsl:text>
-
-  <section id="sect-Library-Client">
-    <title>Client API</title>
-    <para>Following is the Wayland library classes for clients
-	  (<emphasis>libwayland-client</emphasis>). Note that most of the
-	  procedures are related with IPC, which is the main responsibility of
-	  the library.
-    </para>
-
-    <para>
-    <variablelist>
-    <xsl:apply-templates select="/doxygen/compounddef" />
-    </variablelist>
-    </para>
-
-    <para>And methods for the respective classes.</para>
-
-    <para>
-    <variablelist>
-    <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" />
-    </variablelist>
-    </para>
-  </section>
-</xsl:template>
-
-
-<!-- methods -->
-<xsl:template match="memberdef" >
-    <xsl:if test="@kind = 'function' and @static = 'no'">
-    <varlistentry>
-        <term>
-        <xsl:value-of select="name" />
-        - <xsl:value-of select="briefdescription" />
-        </term>
-        <listitem>
-            <para></para>
-        </listitem>
-    </varlistentry>
-    </xsl:if>
-</xsl:template>
-
-<!-- classes -->
-<xsl:template match="compounddef" >
-    <xsl:if test="@kind = 'class' ">
-    <varlistentry>
-        <term>
-            <xsl:value-of select="compoundname" />
-            <xsl:if test="briefdescription">
-                - <xsl:value-of select="briefdescription" />
-            </xsl:if>
-        </term>
-
-        <!-- TODO: the output text is not splitting paragraphs correctly -->
-        <listitem>
-            <para><xsl:value-of select="detaileddescription"/></para>
-        </listitem>
-    </varlistentry>
-    </xsl:if>
-</xsl:template>
-</xsl:stylesheet>
-- 
1.7.9.5



More information about the wayland-devel mailing list