[Pkg-shadow-devel] Rebuilding the manpages from XML at build time?

[Tomasz Kłoczko]

On Sun, 28 Aug 2005, Christian Perrier wrote:

> During the cleanout of the Debian patches I had to do for 4.0.12
> builds, I completely removed the patches we made for the same changes
> both in the XML files and the generated man pages files.
> 
> I kept these changes ONLY in the XML files.
> 
> As a consequence, because man pages are not rebuilt during shadow
> build, the changes do NOT go in the Debian package. This is quiet
> bad...
> 
> So, imho, we have two solutions:
> 
> -include a rebuild of the man pages while building the Debian package
> 
> -convince Tomasz that rebuilding the man pages at build time would be
>  a good idea
> 
> I personnally favor the latter, which will minimize the risks of
> outdated man pages...
> 
> Comments?

Few things are not ready for rebuild.
Most importand is correct XSLT sheet for converting to roff.
Current DocBook XSL Stylesheets 1.69.1 do not adds new line before .TH and 
.SH in some cases.
Next are autoconf/automake fixes.
Now I have redy to commit autoconf fixes for enable force regenerate roff
files on build stage basing on glib autoconf suit (in attachment if you 
want review) but commiting this without automake fixes will not be good.

I'll try spend more time on finish this in comming week.

Probably it will be bood send Debian DocBook XSL Stylesheets package 
maintainer sent informations about bugs in 1.69.1 .. maybe it will allow 
find and fix .TH/.SH bugs faster.

kloczek
-- 
-----------------------------------------------------------
*Ludzie nie mają problemów, tylko sobie sami je stwarzają*
-----------------------------------------------------------
Tomasz Kłoczko, sys adm @zie.pg.gda.pl|*e-mail: kloczek at rudy.mif.pg.gda.pl*
-------------- next part --------------
Index: configure.in
===================================================================
RCS file: /cvsroot/shadow/configure.in,v
retrieving revision 1.120
diff -u -u -r1.120 configure.in
--- configure.in	25 Aug 2005 14:05:43 -0000	1.120
+++ configure.in	28 Aug 2005 17:05:32 -0000
@@ -211,6 +211,13 @@
 	[enable_shadowgrp="yes"]
 )
 
+AC_ARG_ENABLE(man,
+	[AC_HELP_STRING([--enable-man],
+		[regenerate roff man pages from Docbook (default=no)])],
+	[enable_man=yes],
+        [enable_man=no]
+)
+
 AC_ARG_WITH(libpam,
 	[AC_HELP_STRING([--with-libpam], [use libpam for PAM support (default=yes if found)])])
 AC_ARG_WITH(selinux,
@@ -231,6 +238,20 @@
 if test "$enable_shadowgrp" = "yes"; then
 	AC_DEFINE(SHADOWGRP, 1, [Define to support the shadow group file.])
 fi
+
+if test "$enable_man" = "yes"; then
+	dnl
+	dnl Check for xsltproc
+	dnl
+	AC_PATH_PROG([XSLTPROC], [xsltproc], [], [enable_man=no])
+
+	dnl check for DocBook DTD and stylesheets in the local catalog.
+	JH_CHECK_XML_CATALOG([-//OASIS//DTD DocBook XML V4.1.2//EN],
+		[DocBook XML DTD V4.1.2], [], enable_man=no)
+	JH_CHECK_XML_CATALOG([http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl],
+		[DocBook XSL Stylesheets], [], enable_man=no)
+fi
+AM_CONDITIONAL(ENABLE_REGENERATE_MAN, test x$enable_man != xno)
 
 AC_SUBST(LIBCRYPT)
 AC_CHECK_LIB(crypt, crypt, [LIBCRYPT=-lcrypt],
--- /dev/null	2005-08-24 11:33:56.614964250 +0200
+++ acinclude.m4	2005-08-24 14:56:21.000000000 +0200
@@ -0,0 +1,54 @@
+# Checks the location of the XML Catalog
+# Usage:
+#   JH_PATH_XML_CATALOG([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
+# Defines XMLCATALOG and XML_CATALOG_FILE substitutions
+AC_DEFUN([JH_PATH_XML_CATALOG],
+[
+  # check for the presence of the XML catalog
+  AC_ARG_WITH([xml-catalog],
+              AC_HELP_STRING([--with-xml-catalog=CATALOG],
+                             [path to xml catalog to use]),,
+              [with_xml_catalog=/etc/xml/catalog])
+  jh_found_xmlcatalog=true
+  XML_CATALOG_FILE="$with_xml_catalog"
+  AC_SUBST([XML_CATALOG_FILE])
+  AC_MSG_CHECKING([for XML catalog ($XML_CATALOG_FILE)])
+  if test -f "$XML_CATALOG_FILE"; then
+    AC_MSG_RESULT([found])
+  else
+    jh_found_xmlcatalog=false
+    AC_MSG_RESULT([not found])
+  fi
+
+  # check for the xmlcatalog program
+  AC_PATH_PROG(XMLCATALOG, xmlcatalog, no)
+  if test "x$XMLCATALOG" = xno; then
+    jh_found_xmlcatalog=false
+  fi
+
+  if $jh_found_xmlcatalog; then
+    ifelse([$1],,[:],[$1])
+  else
+    ifelse([$2],,[AC_MSG_ERROR([could not find XML catalog])],[$2])
+  fi
+])
+
+# Checks if a particular URI appears in the XML catalog
+# Usage:
+#   JH_CHECK_XML_CATALOG(URI, [FRIENDLY-NAME], [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])
+AC_DEFUN([JH_CHECK_XML_CATALOG],
+[
+  AC_REQUIRE([JH_PATH_XML_CATALOG],[JH_PATH_XML_CATALOG(,[:])])dnl
+  AC_MSG_CHECKING([for ifelse([$2],,[$1],[$2]) in XML catalog])
+  if $jh_found_xmlcatalog && \
+     AC_RUN_LOG([$XMLCATALOG --noout "$XML_CATALOG_FILE" "$1" >&2]); then
+    AC_MSG_RESULT([found])
+    ifelse([$3],,,[$3
+])dnl
+  else
+    AC_MSG_RESULT([not found])
+    ifelse([$4],,
+       [AC_MSG_ERROR([could not find ifelse([$2],,[$1],[$2]) in XML catalog])],
+       [$4])
+  fi
+])