doc: Check DocBook XML validity during the build

Building the documentation with XSLT does not check the DTD, like a
DSSSL build would.  One can often get away with having invalid XML, but
the stylesheets might then create incorrect output, as they are not
designed to handle that.  Therefore, check the validity of the XML
against the DTD, using xmllint, during the build.

Add xmllint detection to configure, and add some documentation.

xmllint comes with libxml2, which is already in use, but it might be in
a separate package, such as libxml2-utils on Debian.

Reviewed-by: Fabien COELHO <[email protected]>

diff --git a/configure b/configure
index f0580ceb5e5dcb3fdae2789f29eaf3bc757d08ae..b403a041727a22da8504d231b1478563105b540b 100755 (executable)
--- a/configure
+++ b/configure
@@ -630,6 +630,7 @@ vpath_build
 PROVE
 OSX
 XSLTPROC
+XMLLINT
 DBTOEPUB
 COLLATEINDEX
 DOCBOOKSTYLE
@@ -14654,6 +14655,48 @@ fi
   test -n "$DBTOEPUB" && break
 done
 
+for ac_prog in xmllint
+do
+  # Extract the first word of "$ac_prog", so it can be a program name with args.
+set dummy $ac_prog; ac_word=$2
+{ $as_echo "$as_me:${as_lineno-$LINENO}: checking for $ac_word" >&5
+$as_echo_n "checking for $ac_word... " >&6; }
+if ${ac_cv_prog_XMLLINT+:} false; then :
+  $as_echo_n "(cached) " >&6
+else
+  if test -n "$XMLLINT"; then
+  ac_cv_prog_XMLLINT="$XMLLINT" # Let the user override the test.
+else
+as_save_IFS=$IFS; IFS=$PATH_SEPARATOR
+for as_dir in $PATH
+do
+  IFS=$as_save_IFS
+  test -z "$as_dir" && as_dir=.
+    for ac_exec_ext in '' $ac_executable_extensions; do
+  if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
+    ac_cv_prog_XMLLINT="$ac_prog"
+    $as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
+    break 2
+  fi
+done
+  done
+IFS=$as_save_IFS
+
+fi
+fi
+XMLLINT=$ac_cv_prog_XMLLINT
+if test -n "$XMLLINT"; then
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: $XMLLINT" >&5
+$as_echo "$XMLLINT" >&6; }
+else
+  { $as_echo "$as_me:${as_lineno-$LINENO}: result: no" >&5
+$as_echo "no" >&6; }
+fi
+
+
+  test -n "$XMLLINT" && break
+done
+
 for ac_prog in xsltproc
 do
   # Extract the first word of "$ac_prog", so it can be a program name with args.

diff --git a/configure.in b/configure.in
index 527b0762053e38af39c72ad137f52195f81a722b..df868823c0cd5800c95b4b2e67ee30820907d0c9 100644 (file)
--- a/configure.in
+++ b/configure.in
@@ -1869,6 +1869,7 @@ PGAC_CHECK_DOCBOOK(4.2)
 PGAC_PATH_DOCBOOK_STYLESHEETS
 PGAC_PATH_COLLATEINDEX
 AC_CHECK_PROGS(DBTOEPUB, dbtoepub)
+AC_CHECK_PROGS(XMLLINT, xmllint)
 AC_CHECK_PROGS(XSLTPROC, xsltproc)
 AC_CHECK_PROGS(OSX, [osx sgml2xml sx])
 

diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 1d42be8951be069a8be9e0ecb5831c62b3465ab9..8bdd26ce28edb8f44da689679db07e65e6a43541 100644 (file)
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -44,6 +44,10 @@ ifndef OSX
 OSX = $(missing) osx
 endif
 
+ifndef XMLLINT
+XMLLINT = $(missing) xmllint
+endif
+
 ifndef XSLTPROC
 XSLTPROC = $(missing) xsltproc
 endif
@@ -78,6 +82,7 @@ override SPFLAGS += -wall -wno-unused-param -wno-empty -wfully-tagged
 man distprep-man: man-stamp
 
 man-stamp: stylesheet-man.xsl postgres.xml
+       $(XMLLINT) --noout --valid postgres.xml
        $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_MAN_FLAGS) $^
        touch $@
 
@@ -254,11 +259,13 @@ endif
 xslthtml: xslthtml-stamp
 
 xslthtml-stamp: stylesheet.xsl postgres.xml
+       $(XMLLINT) --noout --valid postgres.xml
        $(XSLTPROC) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $^
        cp $(srcdir)/stylesheet.css html/
        touch $@
 
 htmlhelp: stylesheet-hh.xsl postgres.xml
+       $(XMLLINT) --noout --valid postgres.xml
        $(XSLTPROC) $(XSLTPROCFLAGS) $^
 
 %-A4.fo.tmp: stylesheet-fo.xsl %.xml
@@ -268,7 +275,6 @@ htmlhelp: stylesheet-hh.xsl postgres.xml
        $(XSLTPROC) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $^
 
 FOP = fop
-XMLLINT = xmllint
 
 # reformat FO output so that locations of errors are easier to find
 %.fo: %.fo.tmp
@@ -281,6 +287,7 @@ XMLLINT = xmllint
 
 epub: postgres.epub
 postgres.epub: postgres.xml
+       $(XMLLINT) --noout --valid $<
        $(DBTOEPUB) $<
 
 

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 0186ef4afba9ab2d2437344139f8188b83908649..e0ae262b8a556bad2c1af6e346d5a49a2d89db65 100644 (file)
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -148,6 +148,20 @@
      </listitem>
     </varlistentry>
 
+    <varlistentry>
+     <term><ulink url="http://xmlsoft.org/">Libxml2</ulink> for <command>xmllint</command></term>
+     <listitem>
+      <para>
+       This library and the <command>xmllint</command> tool it contains are
+       used for processing XML.  Many developers will already
+       have <application>Libxml2</application> installed, because it is also
+       used when building the PostgreSQL code.  Note, however,
+       that <command>xmllint</command> might need to be installed from a
+       separate subpackage.
+      </para>
+     </listitem>
+     </varlistentry>
+
     <varlistentry>
      <term><ulink url="http://xmlsoft.org/XSLT/">Libxslt</ulink> for <command>xsltproc</command></term>
      <listitem>
@@ -255,7 +269,7 @@ yum install docbook-dtds docbook-style-dsssl docbook-style-xsl libxslt openjade
     available for <productname>Debian GNU/Linux</productname>.
     To install, simply use:
 <programlisting>
-apt-get install docbook docbook-dsssl docbook-xsl openjade1.3 opensp xsltproc
+apt-get install docbook docbook-dsssl docbook-xsl libxml2-utils openjade1.3 opensp xsltproc
 </programlisting>
    </para>
   </sect2>

diff --git a/src/Makefile.global.in b/src/Makefile.global.in
index e76b22fb2d2ec652acb85035827948bc365ffac0..7648dba1723b22909c43c45e4559c0f4172728df 100644 (file)
--- a/src/Makefile.global.in
+++ b/src/Makefile.global.in
@@ -353,6 +353,7 @@ DOCBOOKSTYLE        = @DOCBOOKSTYLE@
 JADE                   = @JADE@
 NSGMLS                 = @NSGMLS@
 OSX                            = @OSX@
+XMLLINT                        = @XMLLINT@
 XSLTPROC               = @XSLTPROC@
 
 # Code coverage