doc: replace publican with xmlto

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.

Acked-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>

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

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

doc/publican/publican.cfg

@@ -1,9 +0,0 @@
-# Config::Simple 4.59
-# Fri Feb 24 09:36:50 2012
-
-xml_lang: "en-US"
-type: Book
-brand: common
-tmp_dir: Wayland
-toc_section_depth: 1
-chunk_section_depth: 0

doc/publican/sources/css/brand.css

@@ -0,0 +1,14 @@
+/*headings*/
+h1, h2, h3, h4, h5, h6,
+div.producttitle,
+div.subtitle,
+div.author div.author,
+div.translator div.translator,
+div.othercredit div.othercredit,
+div.editor div.editor,
+div.contrib div.contrib,
+.title,
+.titlepage .edition,
+.titlepage .releaseinfo {
+	color: #336699;
+}

doc/publican/sources/css/default.css

@@ -0,0 +1,3 @@
+@import url("common.css");
+@import url("overrides.css");
+@import url("lang.css");

doc/publican/sources/css/epub.css

@@ -0,0 +1,115 @@
+/*headings*/
+h1, h2, h3, h4, h5, h6,
+div.producttitle,
+div.subtitle,
+div.author div.author,
+div.translator div.translator,
+div.othercredit div.othercredit,
+div.editor div.editor,
+div.contrib div.contrib,
+.title,
+.titlepage .edition {
+}
+
+div.para {
+	margin-top: 1em;
+}
+/* inline syntax highlighting */
+.perl_Alert {
+	color: #0000ff;
+}
+
+.perl_BaseN {
+	color: #007f00;
+}
+
+.perl_BString {
+	color: #5C3566;
+}
+
+.perl_Char {
+	color: #ff00ff;
+}
+
+.perl_Comment {
+	color: #888888;
+}
+
+
+.perl_DataType {
+	color: #0000ff;
+}
+
+
+.perl_DecVal {
+	color: #00007f;
+}
+
+
+.perl_Error {
+	color: #ff0000;
+}
+
+
+.perl_Float {
+	color: #00007f;
+}
+
+
+.perl_Function {
+	color: #007f00;
+}
+
+
+.perl_IString {
+	color: #5C3566;
+}
+
+
+.perl_Keyword {
+	color: #002F5D;
+}
+
+
+.perl_Operator {
+	color: #ffa500;
+}
+
+
+.perl_Others {
+	color: #b03060;
+}
+
+
+.perl_RegionMarker {
+	color: #96b9ff;
+}
+
+
+.perl_Reserved {
+	color: #9b30ff;
+}
+
+
+.perl_String {
+	color: #5C3566;
+}
+
+
+.perl_Variable {
+	color: #0000ff;
+}
+
+
+.perl_Warning {
+	color: #0000ff;
+}
+
+b, strong {
+	font-weight: bolder;
+}
+
+code.command {
+	font-family: monospace;
+	font-weight: bolder;
+}

doc/publican/sources/css/print.css

@@ -0,0 +1,15 @@
+@import url("common.css");
+@import url("overrides.css");
+@import url("lang.css");
+
+#tocframe {
+	display: none;
+}
+
+body.toc_embeded {
+	margin-left: 30px;
+}
+
+.producttitle {
+	color: #336699;
+}