package: install the examples

Currently, we do not install the various examples extracted from the
documentation.  Let's do it, as they are useful starting points.

* configure.ac: When --enable-gcc-warnings is set, enable ENABLE_GCC_WARNINGS.
* examples/extexi: No longer issue synclines by default.
* examples/local.mk: Except if ENABLE_GCC_WARNINGS.
* examples/calc++/local.mk, examples/mfcalc/local.mk,
* examples/rpcalc/local.mk: Install the example files.

NEWS

@@ -24,6 +24,20 @@ GNU Bison NEWS
   Now, the "previous" declaration is always the first one.
 
 
+** Documentation
+
+  Bison now installs various files in its docdir (which defaults to
+  '/usr/local/share/doc/bison'), including the three fully blown examples
+  extracted from the documentation:
+
+   - rpcalc
+     Reverse polish calculator, a simple introductory example.
+   - mfcalc
+     Multi-function Calc, a calculator with memory and functions and located
+     error messages.
+   - calc++
+     a calculator in C++ using variant support and token constructors.
+
 * Noteworthy changes in release 3.0.2 (2013-12-05) [stable]
 
 ** Bug fixes

configure.ac

@@ -71,12 +71,15 @@ AC_CACHE_CHECK([whether pragma GCC diagnostic push works],
   CFLAGS=$save_CFLAGS])
 
 AC_ARG_ENABLE([gcc-warnings],
-[  --enable-gcc-warnings   turn on lots of GCC warnings (not recommended)],
+[  --enable-gcc-warnings   turn on lots of GCC warnings (not recommended).
+                           Also, issue synclines from the examples/ to
+                           the corresponding source in the Texinfo doc.],
 [case $enable_gcc_warnings in
    yes|no) ;;
    *)  AC_MSG_ERROR([invalid value for --gcc-warnings: $enable_gcc_warnings]);;
  esac],
               [enable_gcc_warnings=no])
+AM_CONDITIONAL([ENABLE_GCC_WARNINGS], [test "$enable_gcc_warnings" = yes])
 if test "$enable_gcc_warnings" = yes; then
   warn_common='-Wall-Wextra -Wno-sign-compare -Wcast-align -Wdocumentation
     -Wformat -Wpointer-arith -Wwrite-strings'

examples/calc++/local.mk

@@ -27,11 +27,11 @@ SUFFIXES += .yy .stamp
 	$(AM_V_at)$(YACCCOMPILE) -o $*.cc $<
 	$(AM_V_at)mv -f $@.tmp $@
 
-$(calc_sources_generated): %D%/calc++-parser.stamp
+$(calcxx_sources_generated): %D%/calc++-parser.stamp
 	@test -f $@ || rm -f %D%/calc++-parser.stamp
 	@test -f $@ || $(MAKE) $(AM_MAKEFLAGS) %D%/calc++-parser.stamp
 CLEANFILES +=                                   \
-  $(calc_sources_generated)                     \
+  $(calcxx_sources_generated)                   \
   %D%/calc++-parser.output                      \
   %D%/calc++-parser.stamp                       \
   %D%/calc++-scanner.cc
@@ -42,31 +42,31 @@ CLEANFILES +=                                   \
 ## -------------------- ##
 
 # Avoid using BUILT_SOURCES which is too global.
-$(%C%_calc___OBJECTS): $(calc_sources_generated)
+$(%C%_calc___OBJECTS): $(calcxx_sources_generated)
 
-calc_sources_extracted =                        \
+calcxx_sources_extracted =                      \
   %D%/calc++-driver.cc                          \
   %D%/calc++-driver.hh                          \
   %D%/calc++-scanner.ll                         \
   %D%/calc++.cc
-calc_extracted =                                \
-  $(calc_sources_extracted)                     \
+calcxx_extracted =                              \
+  $(calcxx_sources_extracted)                   \
   %D%/calc++-parser.yy
-extracted += $(calc_extracted)
-calc_sources_generated =                        \
+extracted += $(calcxx_extracted)
+calcxx_sources_generated =                      \
   %D%/calc++-parser.cc                          \
   %D%/calc++-parser.hh                          \
   %D%/location.hh                               \
   %D%/position.hh                               \
   %D%/stack.hh
-calc_sources =                                  \
-  $(calc_sources_extracted)                     \
-  $(calc_sources_generated)
+calcxx_sources =                                \
+  $(calcxx_sources_extracted)                   \
+  $(calcxx_sources_generated)
 
 if FLEX_CXX_WORKS
 check_PROGRAMS += %D%/calc++
 nodist_%C%_calc___SOURCES =                     \
-  $(calc_sources)
+  $(calcxx_sources)
 
 %C%_calc___CPPFLAGS = -I$(top_builddir)/%D%
 %C%_calc___CXXFLAGS = $(AM_CXXFLAGS) $(FLEX_SCANNER_CXXFLAGS)
@@ -74,3 +74,11 @@ dist_TESTS += %D%/calc++.test
 else
 EXTRA_DIST += %D%/calc++.test
 endif
+
+
+## ------------ ##
+## Installing.  ##
+## ------------ ##
+
+calcxxdir = $(docdir)/examples/calc++
+calcxx_DATA = $(calcxx_extracted)

examples/extexi

@@ -19,7 +19,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-# Usage: extexi input-file.texi ... -- [FILES to extract]
+# Usage: extexi [OPTION...] input-file.texi ... -- [FILES to extract]
 
 # Look for @example environments preceded with lines such as:
 #
@@ -35,6 +35,9 @@
 
 use strict;
 
+# Whether we generate synclines.
+my $synclines = 0;
+
 # normalize($block)
 # -----------------
 # Remove Texinfo mark up.
@@ -102,7 +105,7 @@ sub process ($)
             {
               # Bison supports synclines, but not Flex.
               $input .= sprintf ("#line %s \"$in\"\n", $. + 1)
-                if $file =~ /\.[chy]*$/;
+                if $synclines && $file =~ /\.[chy]*$/;
               next;
             }
           elsif (/^\@end (small)?example$/)
@@ -136,15 +139,19 @@ my @input;
 my $seen_dash = 0;
 for my $arg (@ARGV)
 {
-  if ($arg eq '--')
-    {
-      $seen_dash = 1;
-    }
-  elsif ($seen_dash)
+  if ($seen_dash)
     {
       use File::Basename;
       $file_wanted{basename($arg)} = $arg;
     }
+  elsif ($arg eq '--')
+    {
+      $seen_dash = 1;
+    }
+  elsif ($arg eq '--synclines')
+    {
+      $synclines = 1;
+    }
   else
     {
       push @input, $arg;

examples/local.mk

@@ -25,7 +25,10 @@ AM_CXXFLAGS =							\
 
 doc = $(top_srcdir)/doc/bison.texi
 extexi = $(top_srcdir)/%D%/extexi
-extract = VERSION="$(VERSION)" $(PERL) $(extexi) $(doc) --
+if ENABLE_GCC_WARNINGS
+extexiFLAGS = --synclines
+endif
+extract = VERSION="$(VERSION)" $(PERL) $(extexi) $(extexiFLAGS) $(doc) --
 extracted =
 CLEANFILES += $(extracted) %D%/extracted.stamp
 %D%/extracted.stamp: $(doc) $(extexi)

examples/mfcalc/local.mk

@@ -30,3 +30,10 @@ nodist_%C%_mfcalc_SOURCES = $(mfcalc_sources)
 
 %C%_mfcalc_CPPFLAGS = -I$(top_builddir)/%D%
 dist_TESTS += %D%/mfcalc.test
+
+## ------------ ##
+## Installing.  ##
+## ------------ ##
+
+mfcalcdir = $(docdir)/examples/mfcalc
+mfcalc_DATA = $(mfcalc_extracted)

examples/rpcalc/local.mk

@@ -30,3 +30,10 @@ nodist_%C%_rpcalc_SOURCES = $(rpcalc_sources)
 
 %C%_rpcalc_CPPFLAGS = -I$(top_builddir)/%D%
 dist_TESTS += %D%/rpcalc.test
+
+## ------------ ##
+## Installing.  ##
+## ------------ ##
+
+rpcalcdir = $(docdir)/examples/rpcalc
+rpcalc_DATA = $(rpcalc_extracted)