[PATCH v2 wayland 1/4] doc: Enable docbook building without Publican also
Kristian Høgsberg
hoegsberg at gmail.com
Mon Nov 19 14:22:25 PST 2012
On Mon, Nov 19, 2012 at 10:32:57AM -0200, Tiago Vignatti wrote:
> 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.
We dont want two different documentation tools in here. The doc build
system is hard enough to follow as it is. If we can generate a nice
enough result without publican, we should just drop that. If not,
let's just keep publican as a requirement for building the docs.
Kristian
> Signed-off-by: Tiago Vignatti <tiago.vignatti at intel.com>
> ---
> - no changes since v1
>
> 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
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list