[PATCH wayland] doc: replace publican with xmlto

Pekka Paalanen ppaalanen at gmail.com
Mon Sep 22 00:31:47 PDT 2014 

On Thu, 4 Sep 2014 17:32:10 +1000
Peter Hutterer <peter.hutterer at who-t.net> wrote:

> Publican isn't packaged for some distros, xmlto is a lot more common. Most of
> what publican provides for us is the stylesheet anyway, so we can just use
> xmlto and the publican stylesheet to get roughly the same look.
> 
> PDF and XML generation has been dropped, this needs a bit more more effort
> than a mere switchover to xmlto.
> 
> The top-level directory structure imposed by publican is kept for now
> (specifically the Wayland/en-US/html tree). This makes it easier to transition over
> for packagers. Note that the list of files inside has changed.
> 
> CSS files are taken from publican to keep a uniform look compared to previous
> documentations. Stylesheets are licensed under CC0 1.0 Universal license, see
> publican/LICENSE:
> 
> 1.  Files in the datadir/Common_Content directory and its subdirectories are
>     licensed under the CC0 1.0 Universal license.
> 
>     To the extent possible under law, the developers of Publican waive all
>     copyright and related or neighboring rights to the files contained
>     in the datadir/Common_Content directory and its subdirectories.
> ---
> I didn't know if you wanted to merge this before the release. This is pretty
> much the minimum required, a full conversion would mean generating PDF again
> (not sure XML is worth it) and re-arranging a few trees.
> 
> Either way, this one passes make distcheck and generates HTML that looks
> almost the same as the publican output.

Pushed, thank you,
pq


> 
>  configure.ac                         |   12 +-
>  doc/publican/Makefile.am             |   70 +-
>  doc/publican/publican.cfg            |    9 -
>  doc/publican/sources/css/brand.css   |   14 +
>  doc/publican/sources/css/common.css  | 1769 ++++++++++++++++++++++++++++++++++
>  doc/publican/sources/css/default.css |    3 +
>  doc/publican/sources/css/epub.css    |  115 +++
>  doc/publican/sources/css/print.css   |   15 +
>  8 files changed, 1956 insertions(+), 51 deletions(-)
>  delete mode 100644 doc/publican/publican.cfg
>  create mode 100644 doc/publican/sources/css/brand.css
>  create mode 100644 doc/publican/sources/css/common.css
>  create mode 100644 doc/publican/sources/css/default.css
>  create mode 100644 doc/publican/sources/css/epub.css
>  create mode 100644 doc/publican/sources/css/print.css
> 
> diff --git a/configure.ac b/configure.ac
> index d8e42d9..57c3599 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -109,14 +109,10 @@ if test "x$enable_documentation" = "xyes"; then
>  		AC_MSG_ERROR([Documentation build requested but doxygen not found. Install doxygen or disable the documentation using --disable-documentation])
>  	fi
>  
> -	AC_PATH_PROG(PUBLICAN, publican)
> +	AC_PATH_PROG(XMLTO, xmlto)
>  
> -	if test "x$PUBLICAN" != "x"; then
> -		PUBLICAN_VERSION=[`$PUBLICAN -v | sed -e 's/version=v\?\([0-9]*\.[0-9]*\).*/\1/'`]
> -
> -		if test [ 1 -eq `echo "${PUBLICAN_VERSION} < 2.8" | bc` ]; then
> -			AC_MSG_ERROR([Publican version is not supported. Install publican >= 2.8 or disable the documentation using --disable-documentation])
> -		fi
> +	if test "x$XMLTO" = "x"; then
> +		AC_MSG_ERROR([Documentation build requested but xmlto not found. Install xmlto or disable the documentation using --disable-documentation])
>  	fi
>  
>  	AC_CONFIG_FILES([
> @@ -124,7 +120,7 @@ if test "x$enable_documentation" = "xyes"; then
>  	])
>  
>  fi
> -AM_CONDITIONAL([HAVE_PUBLICAN], [test "x$PUBLICAN" != "x"])
> +AM_CONDITIONAL([HAVE_XMLTO], [test "x$XMLTO" != "x"])
>  
>  AC_CONFIG_FILES([Makefile
>  		 cursor/wayland-cursor.pc
> diff --git a/doc/publican/Makefile.am b/doc/publican/Makefile.am
> index 47fc66d..cf0f533 100644
> --- a/doc/publican/Makefile.am
> +++ b/doc/publican/Makefile.am
> @@ -1,14 +1,10 @@
> -# Documentation is built with publican
> -# https://fedorahosted.org/publican/
> -# Publican takes docbook-style input files and compiles them to various
> -# output formats.
> +# Documentation is built with xmlto, but some of the recipes in here are
> +# leftovers from building with Publican (https://fedorahosted.org/publican/)
>  #
>  # How this build works:
>  # * the main target is Wayland, documentation ends up in $(builddir)/Wayland/
> -# * hand-written chapters are located in sources
> -#   Publican does not take a source path, so to support out-of-tree builds
> -#   these are copied to $(builddir)/en-US which is the actual directory
> -#   Publican uses.
> +# * hand-written chapters and CSS files are located in sources. These are
> +#   copied into $(builddir)/en-US/
>  # * ProtocolSpec.xml is generated from $(top_srcdir)/protocol/wayland.xml,
>  #   changed into docbook via XSLT and saved in $(builddir)/en-US/
>  # * ProtocolInterfaces.xml, same as above, uses a different XSLT
> @@ -16,7 +12,7 @@
>  #   $(builddir)/en-US
>  # * WaylandServerAPI.xml is generated from the doxygen output and saved in
>  #   $(builddir)/en-US
> -# * run Publican on en-US
> +# * run xmlto on $(builddir)/en-US, output to $(builddir)/Wayland/en-US
>  publican_sources = \
>  	$(srcdir)/sources/Wayland.ent \
>  	$(srcdir)/sources/Wayland.xml \
> @@ -35,9 +31,36 @@ publican_sources = \
>  	$(srcdir)/sources/images/wayland.png  \
>  	$(srcdir)/sources/images/x-architecture.png
>  
> -if HAVE_PUBLICAN
> +css_sources = \
> +	$(srcdir)/sources/css/brand.css \
> +	$(srcdir)/sources/css/common.css \
> +	$(srcdir)/sources/css/default.css \
> +	$(srcdir)/sources/css/epub.css \
> +	$(srcdir)/sources/css/print.css
> +img_sources = \
> +	$(srcdir)/sources/images/icon.svg \
> +	$(srcdir)/sources/images/wayland-architecture.png \
> +	$(srcdir)/sources/images/wayland.png \
> +	$(srcdir)/sources/images/x-architecture.png
> +
> +if HAVE_XMLTO
>  if HAVE_XSLTPROC
>  noinst_DATA = Wayland $(publican_targets)
> +XMLTO_PARAM = \
> +	--stringparam chunk.section.depth=0 \
> +	--stringparam toc.section.depth=1 \
> +	--stringparam html.stylesheet=css/default.css
> +
> +html_destdir = $(builddir)/Wayland/en-US/html
> +
> +Wayland: $(publican_targets)
> +	$(AM_V_GEN)$(MKDIR_P) -p $(html_destdir)/css
> +	$(AM_V_GEN)cp -f $(css_sources) $(html_destdir)/css/
> +	$(AM_V_GEN)$(MKDIR_P) -p $(html_destdir)/images
> +	$(AM_V_GEN)cp -f $(img_sources) $(html_destdir)/images/
> +	$(AM_V_GEN)$(XMLTO) $(XMLTO_PARAM) html en-US/Wayland.xml -o $(html_destdir)
> +	@touch Wayland
> +
>  pubdir = $(docdir)/Wayland/en-US
>  
>  publican_targets = $(publican_sources:$(srcdir)/sources%=$(builddir)/en-US%) \
> @@ -85,37 +108,16 @@ $(builddir)/en-US/%: $(srcdir)/sources/% en-US/ProtocolSpec.xml en-US/ProtocolIn
>  	$(AM_V_GEN)cp -f $< $@
>  	$(AM_V_GEN)chmod a+w $@
>  
> -# 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)
> -	$(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)" \
> -		--config $(builddir)/publican-copy.cfg
> -	$(AM_V_GEN)$(PUBLICAN) build --quiet --langs en-US --pdftool fop --formats html,pdf \
> -		--config $(builddir)/publican-copy.cfg
> -	@touch Wayland
> -
>  CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(publican_targets)
>  
>  clean-local:
>  	$(AM_V_at)rm -fr $(builddir)/en-US
>  	$(AM_V_at)rm -fr $(builddir)/Wayland
> -	$(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/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/css"
>  	test -z "$(pubdir)/html/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html/images"
> -	test -z "$(pubdir)/html-pdf/Common_Content/css" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html-pdf/Common_Content/css"
> -	test -z "$(pubdir)/html-pdf/Common_Content/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html-pdf/Common_Content/images"
> -	test -z "$(pubdir)/html-pdf/images" || $(mkdir_p) "$(DESTDIR)$(pubdir)/html-pdf/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"
> -	list=`find $(builddir)/Wayland/en-US -type f -not -path '$(builddir)/Wayland/en-US/xml_tmp*'`; \
> +	list=`find $(builddir)/Wayland/en-US -type f`; \
>  	for p in $$list; do \
>  	  echo " $(INSTALL_DATA) '$$p' '$(DESTDIR)$(docdir)/$$p'"; \
>  	  $(INSTALL_DATA) "$$p" "$(DESTDIR)$(docdir)/$$p"; \
> @@ -132,4 +134,4 @@ uninstall-local:
>  endif
>  endif
>  
> -EXTRA_DIST = $(publican_sources) publican.cfg protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-publican.xsl
> +EXTRA_DIST = $(publican_sources) $(css_sources) $(img_sources) protocol-to-docbook.xsl protocol-interfaces-to-docbook.xsl doxygen-to-publican.xsl

More information about the wayland-devel mailing list