build: fix the generation of the documentation.

Some of our targets use "bison --help", but they can't depend on
"bison" itself (to avoid additional requirements on the user), so
they used to call "make src/bison" in the commands.  Then
concurrent builds may fail: one make might be aiming one of its
jobs at compiling src/bison, and another job at generating the man
page.  If the latter is faster than the former, then we have two
makes that concurrently try to compile src/bison.

This might also be a more convincing explanation for the failure
described in the patch "build: fix paths".

	* Makefile.am (SUFFIXES): Initialize.
	* build-aux/move-if-change: New, symlink to gnulib's.
	* build-aux/local.mk: Ship it.
	* doc/common.x: Remove, merged into...
	* doc/bison.x: here.
	* doc/local.mk (doc/bison.help): New.
	($(CROSS_OPTIONS_TEXI)): Depend on it.
	Use src/bison.
	(.x.1): Replace with...
	(doc/bison.1): this explicit, simpler, target.
	(common_dep): Remove, inlined where appropriate.
	(SUFFIXES, PREPATH): Remove, unused.

9 files changed, 83 insertions, 37 deletions

diff --git a/ChangeLog b/ChangeLog
index 5668c721..7f3e157f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,32 @@
 2009-08-12  Akim Demaille  <demaille@gostai.com>
 
+	build: fix the generation of the documentation.
+	Some of our targets use "bison --help", but they can't depend on
+	"bison" itself (to avoid additional requirements on the user), so
+	they used to call "make src/bison" in the commands.  Then
+	concurrent builds may fail: one make might be aiming one of its
+	jobs at compiling src/bison, and another job at generating the man
+	page.  If the latter is faster than the former, then we have two
+	makes that concurrently try to compile src/bison.
+
+	This might also be a more convincing explanation for the failure
+	described in the patch "build: fix paths".
+
+	* Makefile.am (SUFFIXES): Initialize.
+	* build-aux/move-if-change: New, symlink to gnulib's.
+	* build-aux/local.mk: Ship it.
+	* doc/common.x: Remove, merged into...
+	* doc/bison.x: here.
+	* doc/local.mk (doc/bison.help): New.
+	($(CROSS_OPTIONS_TEXI)): Depend on it.
+	Use src/bison.
+	(.x.1): Replace with...
+	(doc/bison.1): this explicit, simpler, target.
+	(common_dep): Remove, inlined where appropriate.
+	(SUFFIXES, PREPATH): Remove, unused.
+
+2009-08-12  Akim Demaille  <demaille@gostai.com>
+
 	gnulib: improve prefixing.
 	* configure.ac (gl_PREFIXED_LIBOBJS): Don't rename it, rather,
 	change the value of...
diff --git a/Makefile.am b/Makefile.am
index 1bd44016..c507cc8e 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -36,6 +36,7 @@ AM_CPPFLAGS =
 BUILT_SOURCES =
 DISTCLEANFILES =
 MOSTLYCLEANFILES =
+SUFFIXES =
 include build-aux/local.mk
 include data/local.mk
 include djgpp/local.mk
diff --git a/build-aux/local.mk b/build-aux/local.mk
index c914172e..141081e7 100644
--- a/build-aux/local.mk
+++ b/build-aux/local.mk
@@ -1,4 +1,5 @@
 EXTRA_DIST +=					\
-build-aux/update-b4-copyright			\
-build-aux/prev-version.txt			\
-build-aux/cross-options.pl
+  build-aux/cross-options.pl			\
+  build-aux/move-if-change			\
+  build-aux/prev-version.txt			\
+  build-aux/update-b4-copyright
diff --git a/build-aux/move-if-change b/build-aux/move-if-change
new file mode 120000
index 00000000..2df61a60
--- /dev/null
+++ b/build-aux/move-if-change
@@ -0,0 +1 @@
+../gnulib/build-aux/move-if-change
\ No newline at end of file
diff --git a/doc/.cvsignore b/doc/.cvsignore
index a5a4f9d3..7854e0a9 100644
--- a/doc/.cvsignore
+++ b/doc/.cvsignore
@@ -6,6 +6,7 @@ bison.cps
 bison.dvi
 bison.fn
 bison.html
+bison.help
 bison.ky
 bison.log
 bison.pdf
diff --git a/doc/.gitignore b/doc/.gitignore
index 62a4e198..edd2e36b 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -5,6 +5,7 @@
 /bison.cps
 /bison.dvi
 /bison.fn
+/bison.help
 /bison.html
 /bison.ky
 /bison.log
diff --git a/doc/bison.x b/doc/bison.x
index 1eaa9fdf..c7335154 100644
--- a/doc/bison.x
+++ b/doc/bison.x
@@ -53,3 +53,8 @@ are unique.  When a long option takes an argument, like
 .BR \-\-file-prefix ,
 connect the option name and the argument with
 .BR = .
+
+[see also]
+.BR lex (1),
+.BR flex (1),
+.BR yacc (1).
diff --git a/doc/common.x b/doc/common.x
deleted file mode 100644
index 60224c39..00000000
--- a/doc/common.x
+++ /dev/null
@@ -1,4 +0,0 @@
-[see also]
-.BR lex (1),
-.BR flex (1),
-.BR yacc (1).
diff --git a/doc/local.mk b/doc/local.mk
index cb7d00d1..f0860848 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -26,16 +26,17 @@ CLEANDIRS = doc/*.t2d
 clean-local:
 	rm -rf $(CLEANDIRS)
 
+MOSTLYCLEANFILES += $(top_srcdir)/doc/*.t
+
 CROSS_OPTIONS_PL = $(top_srcdir)/build-aux/cross-options.pl
 CROSS_OPTIONS_TEXI = $(top_srcdir)/doc/cross-options.texi
-$(CROSS_OPTIONS_TEXI): $(top_srcdir)/src/getargs.c $(CROSS_OPTIONS_PL)
+$(CROSS_OPTIONS_TEXI): doc/bison.help $(CROSS_OPTIONS_PL)
 # Create $@~ which is the previous contents.  Don't use `mv' here so
 # that even if we are interrupted, the file is still available for
 # diff in the next run.  Note that $@ might not exist yet.
 	{ test ! -f $@ || cat $@; } >$@~
 	test ! -f $@.tmp || rm -f $@.tmp
-	$(MAKE) $(AM_MAKEFLAGS) src/bison$(EXEEXT)
-	src/bison --help |				 \
+	src/bison$(EXEEXT) --help |					 \
 	  perl $(CROSS_OPTIONS_PL) $(top_srcdir)/src/scan-gram.l >$@.tmp
 	diff -u $@~ $@.tmp || true
 	mv $@.tmp $@
@@ -54,49 +55,61 @@ doc/refcard.dvi: doc/refcard.tex
 doc/refcard.ps: doc/refcard.dvi
 
 
+## ---------------- ##
+## doc/bison.help.  ##
+## ---------------- ##
+
+# Some of our targets (cross-option.texi, bison.1) use "bison --help".
+# Since we want to ship the generated file to avoid additional
+# requirements over the user environment, we used not depend on
+# src/bison itself, but on src/getargs.c and other files.  Yet, we
+# need "bison --help" to work to make help2man happy, so we used to
+# include "make src/bison" in the commands.  Then we may have a
+# problem with concurrent builds, since one make might be aiming one
+# of its jobs at compiling src/bison, and another job at generating
+# the man page.  If the latter is faster than the former, then we have
+# two makes that concurrently try to compile src/bison.  Doomed to
+# failure.
+#
+# As a simple scheme to get our way out, make a stamp file,
+# bison.help, which contains --version then --help.  This file can
+# depend on bison, which ensures its correctness.  But update it
+# *only* if needed (content changes).  This way, we avoid useless
+# compilations of cross-option.texi and bison.1.  At the cost of
+# repeated builds of bison.help.
+
+EXTRA_DIST += $(top_srcdir)/doc/bison.help
+MAINTAINERCLEANFILES += $(top_srcdir)/doc/bison.help
+$(top_srcdir)/doc/bison.help: src/bison$(EXEEXT)
+	$< --version >doc/bison.help.t
+	$< --help   >>doc/bison.help.t
+	$(top_srcdir)/build-aux/move-if-change doc/bison.help.t $@
+
+
 ## ----------- ##
 ## Man Pages.  ##
 ## ----------- ##
 
 dist_man_MANS = $(top_srcdir)/doc/bison.1
 
-EXTRA_DIST += $(dist_man_MANS:.1=.x) doc/common.x
+EXTRA_DIST += $(dist_man_MANS:.1=.x)
 MAINTAINERCLEANFILES += $(dist_man_MANS)
 
-# Depend on configure to get version number changes.
-common_dep = $(top_srcdir)/configure $(top_srcdir)/doc/common.x
-$(top_srcdir)/doc/bison.1:      $(common_dep) $(top_srcdir)/src/getargs.c
-
 # Differences to ignore when comparing the man page (the date).
 remove_time_stamp = \
   sed 's/^\(\.TH[^"]*"[^"]*"[^"]*\)"[^"]*"/\1/'
 
-MOSTLYCLEANFILES += $(top_srcdir)/doc/*.t
-
-SUFFIXES = .x .1
-
-PREPATH = src
-.x.1:
-	@program=`expr "/$*" : '.*/\(.*\)'` &&				 \
-	save_IFS=$IFS;							 \
-	IFS=$(PATH_SEPARATOR);						 \
-	for dir in $(PREPATH); do					 \
-	  IFS=$save_IFS;						 \
-	  echo $(MAKE) $(AM_MAKEFLAGS) $$dir/$$program;			 \
-	  $(MAKE) $(AM_MAKEFLAGS) $$dir/$$program || exit;		 \
-	done
+# Depend on configure to get version number changes.
+$(top_srcdir)/doc/bison.1: doc/bison.help doc/bison.x $(top_srcdir)/configure
 	@echo "Updating man page $@"
-	PATH="$(top_builddir)/$(PREPATH)$(PATH_SEPARATOR)$$PATH";	 \
-	export PATH;							 \
-	$(HELP2MAN)							 \
-	    --include=$*.x						 \
-	    --include=$(top_srcdir)/doc/common.x			 \
-	    --output=$@.t `echo '$*' | sed 's,.*/,,'`
+	$(HELP2MAN)					\
+	    --include=$(top_srcdir)/doc/bison.x		\
+	    --output=$@.t src/bison$(EXEEXT)
 	if $(remove_time_stamp) $@ >$@a.t 2>/dev/null &&		 \
 	   $(remove_time_stamp) $@.t | cmp $@a.t - >/dev/null 2>&1; then \
-		touch $@;						 \
+	  touch $@;							 \
 	else								 \
-		mv $@.t $@;						 \
+	  mv $@.t $@;							 \
 	fi
 	rm -f $@*.t