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.

6 files changed, 97 insertions, 18 deletions

diff --git a/README b/README
index 5370f335..8689bab8 100644
--- a/README
+++ b/README
@@ -41,6 +41,7 @@ note that the range specifies every single year in that closed interval.
 
 Local Variables:
 mode: outline
+fill-column: 76
 End:
 
 Copyright (C) 1992, 1998-1999, 2003-2005, 2008-2015, 2018 Free Software
diff --git a/doc/bison.texi b/doc/bison.texi
index 6cd52917..b7945343 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -11066,14 +11066,13 @@ use characters such as @code{':'}, they must be declared with @code{%token}.
 @node A Complete C++ Example
 @subsection A Complete C++ Example
 
-This section demonstrates the use of a C++ parser with a simple but
-complete example.  This example should be available on your system,
-ready to compile, in the directory @dfn{.../bison/examples/calc++}.  It
-focuses on the use of Bison, therefore the design of the various C++
-classes is very naive: no accessors, no encapsulation of members etc.
-We will use a Lex scanner, and more precisely, a Flex scanner, to
-demonstrate the various interactions.  A hand-written scanner is
-actually easier to interface with.
+This section demonstrates the use of a C++ parser with a simple but complete
+example.  This example should be available on your system, ready to compile,
+in the directory @dfn{.../share/doc/bison/examples/calc++}.  It focuses on
+the use of Bison, therefore the design of the various C++ classes is very
+naive: no accessors, no encapsulation of members etc.  We will use a Lex
+scanner, and more precisely, a Flex scanner, to demonstrate the various
+interactions.  A hand-written scanner is actually easier to interface with.
 
 @menu
 * Calc++ --- C++ Calculator::   The specifications
@@ -11086,11 +11085,10 @@ actually easier to interface with.
 @node Calc++ --- C++ Calculator
 @subsubsection Calc++ --- C++ Calculator
 
-Of course the grammar is dedicated to arithmetics, a single
-expression, possibly preceded by variable assignments.  An
-environment containing possibly predefined variables such as
-@code{one} and @code{two}, is exchanged with the parser.  An example
-of valid input follows.
+Of course the grammar is dedicated to arithmetics, a single expression,
+possibly preceded by variable assignments.  An environment containing
+possibly predefined variables such as @code{one} and @code{two}, is
+exchanged with the parser.  An example of valid input follows.
 
 @example
 three := 3
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