[PATCH wayland 3/3] doc: Provide a fallback solution when Publican is not found

[Pekka Paalanen]

On Wed, 14 Nov 2012 14:18:23 -0200
Tiago Vignatti <tiago.vignatti at intel.com> wrote:

> It provides a simple HTML solution from DocBook.
> 
> Signed-off-by: Tiago Vignatti <tiago.vignatti at intel.com>
> ---
>  configure.ac            |   13 ++++++++++++-
>  doc/Wayland/Makefile.am |    5 ++++-
>  2 files changed, 16 insertions(+), 2 deletions(-)

Hi Tiago,

I tried building the docs at least, I applied your 7+3 patches from the
list. I needed the following patch to make it go through without
warnings:

diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
index 8386942..b6c933a 100644
--- a/doc/Wayland/Makefile.am
+++ b/doc/Wayland/Makefile.am
@@ -37,13 +37,9 @@ en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/proto
 # the output methods.
 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/
 	$(AM_V_GEN)$(XSLTPROC) $(top_srcdir)/doc/doxygen/xml/combine.xslt \
 		$(top_srcdir)/doc/doxygen/xml/index.xml > \
 		$(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-docbook.xsl \
 		$(top_builddir)/doc/doxygen/xml/clientAPI.xml > en-US/WaylandClientAPI.xml
 
@@ -71,7 +67,7 @@ Wayland: $(doc_targets)
 	$(AM_V_GEN)$(mkdir_p) $(srcdir)/Wayland/en-US/html/
 	$(AM_V_GEN)cp -rf $(srcdir)/en-US/images/ $(srcdir)/Wayland/en-US/html/
 	$(AM_V_GEN)$(XMLLINT) --xinclude $(builddir)/en-US/Wayland.xml > $(builddir)/en-US/resolved.xml
-	$(AM_V_GEN)$(XSLTPROC) /usr/share/xml/docbook/stylesheet/docbook-xsl/xhtml/docbook.xsl $(builddir)/en-US/resolved.xml > $(srcdir)/Wayland/en-US/html/index.html
+	$(AM_V_GEN)$(XSLTPROC) http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl $(builddir)/en-US/resolved.xml > $(srcdir)/Wayland/en-US/html/index.html
 endif
 
 CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(doc_targets)

I'm not sure if that's right or not, but seems to work for me.

I'm a bit worried about all the mv'ing and cp'ing into srcdirs.

In the final html file, Chapter 4, Client API, the dt-lists collapse
into a single unformatted paragraph. Looks like a missing CSS stylesheet
(definition?).

> 
> diff --git a/configure.ac b/configure.ac
> index a451948..f423991 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -53,6 +53,12 @@ AC_ARG_ENABLE([documentation],
>  	      [],
>  	      [enable_documentation=yes])
>  
> +AC_ARG_ENABLE([publican],
> +	      [AC_HELP_STRING([--disable-publican],
> +		              [Disable building the documentation with Publican])],
> +	      [],
> +	      [enable_publican=yes])
> +
>  AM_CONDITIONAL(ENABLE_SCANNER, test "x$enable_scanner" = xyes)
>  
>  AC_ARG_WITH(icondir, [  --with-icondir=<dir>    Look for cursor icons here],
> @@ -84,7 +90,12 @@ 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)
> +	# fallback to xmllint + a XSLT xsltproc when publican is lacking
> +	if test "x$enable_publican" = "xyes"; then
> +		AC_PATH_PROG(PUBLICAN, publican)

If publican is not found, there is no error.

Forgetting --disable-publican, and not having publican installed, leads
to empty XMLLINT, which causes the build to attempt to run the command
'xinclude'. Quite confusing. ;-)

> +	else
> +		AC_PATH_PROG(XMLLINT, xmllint)

XMLLINT and XSLTPROC are actually hard requirements in this branch,
would need to be checked, too.

> +	fi
>  
>  	if test "x$PUBLICAN" != "x"; then
>  		PUBLICAN_VERSION=`$PUBLICAN -v | cut -d'=' -f2`
> diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
> index 6c328ea..8386942 100644
> --- a/doc/Wayland/Makefile.am
> +++ b/doc/Wayland/Makefile.am
> @@ -68,7 +68,10 @@ Wayland: $(doc_targets)
>  	@touch Wayland
>  else
>  Wayland: $(doc_targets)
> -	$(AM_V_GEN)mkdir -p $(srcdir)/Wayland
> +	$(AM_V_GEN)$(mkdir_p) $(srcdir)/Wayland/en-US/html/
> +	$(AM_V_GEN)cp -rf $(srcdir)/en-US/images/ $(srcdir)/Wayland/en-US/html/
> +	$(AM_V_GEN)$(XMLLINT) --xinclude $(builddir)/en-US/Wayland.xml > $(builddir)/en-US/resolved.xml
> +	$(AM_V_GEN)$(XSLTPROC) /usr/share/xml/docbook/stylesheet/docbook-xsl/xhtml/docbook.xsl $(builddir)/en-US/resolved.xml > $(srcdir)/Wayland/en-US/html/index.html
>  endif
>  
>  CLEANFILES = en-US/ProtocolSpec.xml en-US/ProtocolInterfaces.xml en-US/WaylandClientAPI.xml $(doc_targets)


Thanks,
pq