examples: calc++: a Makefile and a README

* examples/calc++/Makefile, examples/calc++/README: New.
* examples/calc++/local.mk: Ship and install them.
* doc/bison.texi: Formatting changes.

4 files changed, 85 insertions, 5 deletions

diff --git a/examples/README b/examples/README
index bfdd8c68..9780d829 100644
--- a/examples/README
+++ b/examples/README
@@ -5,18 +5,19 @@ A C example of a multi-function calculator.  Extracted from the
 documentation.
 
 * calc++
-A C++ version of the canonical example for parsers: a calculator.
-Also uses Flex for the scanner.  Extracted from the documentation.
+A C++ version of the canonical example for parsers: a calculator.  Also uses
+Flex for the scanner.  Extracted from the documentation.
 
 * variant.yy
-A C++ example that uses variants (they allow to use any C++ type as
-semantic value type) and symbol constructors (they ensure consistency
-between declared token type and effective semantic value).
+A C++ example that uses variants (they allow to use any C++ type as semantic
+value type) and symbol constructors (they ensure consistency between
+declared token type and effective semantic value).
 
 -----
 
 Local Variables:
 mode: outline
+fill-column: 76
 End:
 
 Copyright (C) 2018 Free Software Foundation, Inc.
diff --git a/examples/calc++/Makefile b/examples/calc++/Makefile
new file mode 100644
index 00000000..6b6c4998
--- /dev/null
+++ b/examples/calc++/Makefile
@@ -0,0 +1,27 @@
+# This Makefile is designed to be simple and readable.  It does not
+# aim at portability.  It requires GNU Make.
+
+BISON = bison
+CXX = g++
+FLEX = flex
+
+all: calc++
+
+%.cc %.hh: %.yy
+	$(BISON) $(BISONFLAGS) -o $*.cc $<
+
+%.cc: %.ll
+	$(FLEX) $(FLEXFLAGS) -o$@ $<
+
+%.o: %.cc
+	$(CXX) $(CXXFLAGS) -c -o$@ $<
+
+calc++: calc++.o driver.o parser.o scanner.o
+	$(CXX) -o $@ $^
+
+calc++.o: parser.hh
+parser.o: parser.hh
+scanner.o: parser.hh
+
+clean:
+	rm -f calc++ *.o parser.hh parser.cc scanner.cc
diff --git a/examples/calc++/README b/examples/calc++/README
new file mode 100644
index 00000000..679c4a1a
--- /dev/null
+++ b/examples/calc++/README
@@ -0,0 +1,51 @@
+This directory contains calc++, a simple Bison grammar file in C++.
+
+Please, read the corresponding chapter in the documentation: "A Complete C++
+Example".  It is also available on line (maybe with a different version of
+Bison):
+https://www.gnu.org/software/bison/manual/html_node/A-Complete-C_002b_002b-Example.html
+
+To use it, copy this directory into some work directory, and run `make` to
+compile the executable, and try it.  It is a simple calculator which accepts
+several variable definitions, one per line, and then a single expression to
+evaluate.
+
+The program calc++ expects the file to parse as argument; pass `-` to read
+the standard input (and then hit <Ctrl-d>, control-d, to end your input).
+
+$ ./calc++ -
+one := 1
+two := 2
+three := 3
+(one + two * three) * two * three
+<Ctrl-d>
+42
+
+You may pass `-p` to activate the parser debug traces, and `-s` to activate
+the scanner's.
+
+-----
+
+Local Variables:
+mode: outline
+fill-column: 76
+End:
+
+Copyright (C) 2018 Free Software Foundation, Inc.
+
+This file is part of Bison, the GNU Compiler Compiler.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# LocalWords:  mfcalc calc parsers yy MERCHANTABILITY
diff --git a/examples/calc++/local.mk b/examples/calc++/local.mk
index 06c1ed67..28f9f908 100644
--- a/examples/calc++/local.mk
+++ b/examples/calc++/local.mk
@@ -83,3 +83,4 @@ endif
 
 calcxxdir = $(docdir)/examples/calc++
 calcxx_DATA = $(calcxx_extracted)
+dist_calcxx_DATA = %D%/README %D%/Makefile