Re: [Nbd] [patch] manpages generation fixes

[Wouter Verhelst <w@...112...>]

On Fri, Feb 17, 2012 at 04:06:44PM +1100, Alex 'AdUser' Z wrote:
> Hi all.
> 
> I decided to share a set of patches to fix the generation of manpages.
> 
> It fixes build failure with this message:.
> ----8<-----------
> nbd-server.5.in.sgml:1: parser error : StartTag: invalid element name
> <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
>  ^
> nbd-server.5.in.sgml:1: parser error : Extra content at the end of
> the document
> <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
>  ^
> unable to parse nbd-server.5.in.sgml

That's because you're using docbook-xml rather than "plain" docbook. SGML and
XML are similar, but not the same thing.

Having said that, your patch does not turn it into invalid SGML, so I suppose I
can accept that.

Your second patch is different, though:

[...]
> .... and optionally simplifies generation routine.
> >From db6c036716528e539ecc31ef1cffb912683cf7ab Mon Sep 17 00:00:00 2001
> From: Alex 'AdUser' Z <ad_user@...1007...>
> Date: Wed, 21 Dec 2011 15:10:32 +1100
> Subject: [PATCH 2/2] * simplified manpage generation
> 
> ---
>  autogen.sh      |    2 +-
>  configure.ac    |    2 +-
>  man/Makefile.am |   43 ++++++++++---------------------------------
>  man/sh.tmpl     |    7 -------
>  4 files changed, 12 insertions(+), 42 deletions(-)
>  delete mode 100644 man/sh.tmpl
> 
> diff --git a/autogen.sh b/autogen.sh
> index a8fbf14..8d2348d 100755
> --- a/autogen.sh
> +++ b/autogen.sh
> @@ -1,4 +1,4 @@
>  #!/bin/sh
>  set -ex
> -make -C man -f Makefile.am nbd-server.1.sh.in nbd-server.5.sh.in nbd-client.8.sh.in nbd-trdump.1.sh.in
> +make -C man -f Makefile.am

The whole point of this "make" snippet here is to generate the manpages,
so that they don't cause the autogeneration to fail. If you're going to
redo the manpage generation in the way that you suggest, then this
"make" doesn't make much sense anymore.

>  exec autoreconf -f -i
> diff --git a/configure.ac b/configure.ac
> index e085ce0..985db53 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -140,6 +140,6 @@ AC_TYPE_PID_T
>  nbd_server_CPPFLAGS=$nbd_server_CPPFLAGS" -DSYSCONFDIR='\"$sysconfdir\"'"
>  AC_SUBST(nbd_server_CPPFLAGS)
>  AC_CONFIG_HEADERS([config.h])
> -AC_CONFIG_FILES([Makefile doc/Doxyfile man/Makefile man/nbd-client.8.sh man/nbd-server.5.sh man/nbd-server.1.sh man/nbd-trdump.1.sh])
> +AC_CONFIG_FILES([Makefile doc/Doxyfile man/Makefile])
>  AC_OUTPUT
>  
> diff --git a/man/Makefile.am b/man/Makefile.am
> index 10d244f..44c71fb 100644
> --- a/man/Makefile.am
> +++ b/man/Makefile.am
> @@ -1,38 +1,15 @@
>  man_MANS = nbd-server.1 nbd-server.5 nbd-client.8 nbd-trdump.1
>  CLEANFILES = manpage.links manpage.refs
>  DISTCLEANFILES = nbd-server.1 nbd-client.8 nbd-server.5 nbd-trdump.1
> -MAINTAINERCLEANFILES = nbd-server.1.sh.in nbd-client.8.sh.in nbd-server.5.sh.in nbd-trdump.1.sh.in
>  EXTRA_DIST = nbd-server.1.in.sgml nbd-client.8.in.sgml nbd-server.5.in.sgml nbd-trdump.1.in.sgml nbd-server.1.sh.in nbd-server.5.sh.in nbd-client.8.sh.in nbd-trdump.1.sh.in sh.tmpl
>  
> -nbd-server.1: nbd-server.1.sh
> -	sh nbd-server.1.sh > nbd-server.1
> -nbd-server.5: nbd-server.5.sh
> -	sh nbd-server.5.sh > nbd-server.5
> -nbd-client.8: nbd-client.8.sh
> -	sh nbd-client.8.sh > nbd-client.8
> -nbd-trdump.1: nbd-trdump.1.sh
> -	sh nbd-trdump.1.sh > nbd-trdump.1
> -nbd-server.1.sh.in: nbd-server.1.in.sgml sh.tmpl
> -	LC_ALL=C docbook2man nbd-server.1.in.sgml
> -	cat sh.tmpl > nbd-server.1.sh.in
> -	cat NBD-SERVER.1 >> nbd-server.1.sh.in
> -	echo "EOF" >> nbd-server.1.sh.in
> -	rm NBD-SERVER.1
> -nbd-client.8.sh.in: nbd-client.8.in.sgml sh.tmpl
> -	LC_ALL=C docbook2man nbd-client.8.in.sgml
> -	cat sh.tmpl > nbd-client.8.sh.in
> -	cat NBD-CLIENT.8 >> nbd-client.8.sh.in
> -	echo "EOF" >> nbd-client.8.sh.in
> -	rm NBD-CLIENT.8
> -nbd-server.5.sh.in: nbd-server.5.in.sgml sh.tmpl
> -	LC_ALL=C docbook2man nbd-server.5.in.sgml
> -	cat sh.tmpl > nbd-server.5.sh.in
> -	cat NBD-SERVER.5 >> nbd-server.5.sh.in
> -	echo "EOF" >> nbd-server.5.sh.in
> -	rm NBD-SERVER.5
> -nbd-trdump.1.sh.in: nbd-trdump.1.in.sgml sh.tmpl
> -	LC_ALL=C docbook2man nbd-trdump.1.in.sgml
> -	cat sh.tmpl > nbd-trdump.1.sh.in
> -	cat NBD-TRDUMP.1 >> nbd-trdump.1.sh.in
> -	echo "EOF" >> nbd-trdump.1.sh.in
> -	rm NBD-TRDUMP.1
> +all: nbd-server.1 nbd-server.5 nbd-client.8 nbd-trdump.1
> +
> +clean:
> +	rm -rf nbd-*.[0-9]
> +
> +%: %.in.sgml
> +	LC_ALL=C docbook2man $< --to-stdout > $@
> +	sed -i -e 's|$$sysconfdir|$(sysconfdir)|g' $@

This template is too broad.

> +# vim: noet:ts=4
> diff --git a/man/sh.tmpl b/man/sh.tmpl
> deleted file mode 100644
> index d97aa3f..0000000
> --- a/man/sh.tmpl
> +++ /dev/null
> @@ -1,7 +0,0 @@
> -#!/bin/sh
> -
> -prefix=@prefix@
> -exec_prefix=@exec_prefix@
> -sysconfdir=@sysconfdir@
> -
> -cat <<EOF
> -- 
> 1.7.7

Did you test if this method still works if a user runs configure with a
--prefix argument, but without a --sysconfdir argument?

-- 
The volume of a pizza of thickness a and radius z can be described by
the following formula:

pi zz a