examples: sort them per language and complete them

Convert some of the READMEs to Markdown, which is now more common, and
nicely displayed in some git hosting services.

Add missing READMEs and Makefiles.  Generate XML, HTML and Dot files.  Be
sure to ship the test files.  Complete CLEANFILES to remove all generated
files.

* examples/calc++: Move into...
* examples/c++: here.
* examples/mfcalc, examples/rpcalc: Move into...
* examples/c: here.

* examples/README.md, examples/c++/calc++/Makefile, examples/c/local.mk,
* examples/c/mfcalc/Makefile, examples/c/rpcalc/Makefile,
* examples/d/README.md, examples/java/README.md:
New files.

* examples/test (medir): Be robust to deeper directory nesting.

examples/README.md

@@ -0,0 +1,28 @@
+This directory contains examples of Bison grammar files, sorted per
+language.
+
+Several of them come from the documentation, which should be installed
+together with Bison.  The URLs are provided for convenience.
+
+These examples come with a README and a Makefile.  Not only can they be used
+to toy with Bison, they can also be starting points for your own grammars.
+
+Please, be sure to read the C examples before looking at the other
+languages, as these examples are simpler.
+
+<!---
+
+Local Variables:
+fill-column: 76
+ispell-dictionary: "american"
+End:
+
+Copyright (C) 2018 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the "GNU Free
+Documentation License" file as part of this distribution.
+--->

examples/c++/README.md

@@ -1,11 +1,11 @@
-This directory contains examples of Bison grammar files in C++.
+# Examples in C++
 
-* Examples in C++
+This directory contains examples of Bison grammar files in C++.
 
 You can run `make` to compile these examples.  And `make clean` to tidy
 afterwards.
 
-** simple.yy - Simple example in C++14
+## simple.yy - Simple example in C++14
 A very simple example in C++, based on variants and symbol constructors.
 Variants allow to use any C++ type as semantic value type, and symbol
 constructors ensure consistency between declared token type and effective
@@ -16,21 +16,32 @@ Run as `./simple`.
 Extracted from the documentation: "A Simple C++ Example".
 https://www.gnu.org/software/bison/manual/html_node/A-Simple-C_002b_002b-Example.html
 
-** variant.yy - Self-contained example in C++98
+## variant.yy - Self-contained example in C++98
 A variation of simple.yy, in C++98.
 
 Run as `./variant`.
 
-** variant-11.yy - Self-contained example in modern C++
+## variant-11.yy - Self-contained example in modern C++
 Another variation of simple.yy, closely related to the previous one, but
 exhibiting support for C++11's move semantics.
 
 Run as `./variant` or `./variant NUMBER`.
 
------
+## calc++ - A Complete C++ Example
+A fully featured C++ version of the canonical example for parsers: a
+calculator.  Also uses Flex for the scanner.
+
+Don't look at this example first: it is fully featured and can serve as a
+starting point for a clean parser in C++.  The previous examples are better
+introductory examples, and the C examples are also useful introductory
+examples.
+
+Extracted from the documentation: "A Complete C++ Example".
+https://www.gnu.org/software/bison/manual/html_node/A-Complete-C_002b_002b-Example.html
+
+<!---
 
 Local Variables:
-mode: outline
 fill-column: 76
 ispell-dictionary: "american"
 End:
@@ -45,3 +56,4 @@ Texts.  A copy of the license is included in the "GNU Free
 Documentation License" file as part of this distribution.
 
 # LocalWords:  mfcalc calc parsers yy ispell american
+--->

examples/c++/calc++/Makefile

@@ -0,0 +1,41 @@
+# This Makefile is designed to be simple and readable.  It does not
+# aim at portability.  It requires GNU Make.
+
+BASE = calc++
+BISON = bison
+CXX = g++
+FLEX = flex
+XSLTPROC = xsltproc
+
+all: $(BASE)
+
+%.cc %.hh %.xml %.gv: %.yy
+	$(BISON) $(BISONFLAGS) --xml --graph=$*.gv -o $*.cc $<
+
+%.cc: %.ll
+	$(FLEX) $(FLEXFLAGS) -o$@ $<
+
+%.o: %.cc
+	$(CXX) $(CXXFLAGS) -c -o$@ $<
+
+$(BASE): $(BASE).o driver.o parser.o scanner.o
+	$(CXX) -o $@ $^
+
+$(BASE).o: parser.hh
+parser.o: parser.hh
+scanner.o: parser.hh
+
+run: $(BASE)
+	@echo "Type arithmetic expressions.  Quit with ctrl-d."
+	./$< -
+
+html: parser.html
+%.html: %.xml
+	$(XSLTPROC) $(XSLTPROCFLAGS) -o $@ $$($(BISON) --print-datadir)/xslt/xml2xhtml.xsl $<
+
+CLEANFILES =										\
+  $(BASE) *.o										\
+  parser.hh parser.cc parser.output parser.xml parser.html parser.gv location.hh	\
+  scanner.cc
+clean:
+	rm -f $(CLEANFILES)

examples/c++/calc++/README.md

@@ -13,6 +13,7 @@ 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
@@ -20,14 +21,14 @@ 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
 ispell-dictionary: "american"
 End:
@@ -50,3 +51,4 @@ 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 Ctrl ispell american
+--->

examples/c++/calc++/local.mk

@@ -79,6 +79,6 @@ EXTRA_DIST += %D%/calc++.test
 ## Installing.  ##
 ## ------------ ##
 
-calcxxdir = $(docdir)/examples/calc++
+calcxxdir = $(docdir)/%D%
 calcxx_DATA = $(calcxx_extracted)
-dist_calcxx_DATA = %D%/README %D%/Makefile
+dist_calcxx_DATA = %D%/README.md %D%/Makefile

examples/c++/local.mk

@@ -13,7 +13,8 @@
 ## You should have received a copy of the GNU General Public License
 ## along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-cxxdir = $(examplesdir)/c++
+cxxdir = $(docdir)/%D%
+include %D%/calc++/local.mk
 
 ## -------- ##
 ## Simple.  ##
@@ -66,5 +67,5 @@ if ENABLE_CXX11
 endif
 EXTRA_DIST += %D%/variant-11.test
 
-dist_cxx_DATA = %D%/README %D%/Makefile %D%/variant.yy %D%/variant-11.yy
+dist_cxx_DATA = %D%/README.md %D%/Makefile %D%/variant.yy %D%/variant-11.yy
 CLEANFILES += %D%/simple.output %D%/variant.output %D%/variant-11.output

examples/c/README.md

@@ -3,10 +3,7 @@ This directory contains examples of Bison grammar files.
 Most of them come from the documentation, which should be installed together
 with Bison.  The URLs are provided for convenience.
 
-
-* Examples in C
-
-** rpcalc - Reverse Polish Notation Calculator
+# rpcalc - Reverse Polish Notation Calculator
 The first example is that of a simple double-precision Reverse Polish
 Notation calculator (a calculator using postfix operators). This example
 provides a good starting point, since operator precedence is not an issue.
@@ -14,42 +11,16 @@ provides a good starting point, since operator precedence is not an issue.
 Extracted from the documentation: "Reverse Polish Notation Calculator"
 https://www.gnu.org/software/bison/manual/html_node/RPN-Calc.html
 
-** mfcalc - Multi-Function Calculator
+# mfcalc - Multi-Function Calculator
 A more complete C example: a multi-function calculator.
 
 Extracted from the documentation: "Multi-Function Calculator: mfcalc".
 https://www.gnu.org/software/bison/manual/html_node/Multi_002dfunction-Calc.html
 
 
-
-* Examples in C++
-
-** c++ - A directory of simple C++ examples
-
-** calc++ - A Complete C++ Example
-A fully featured C++ version of the canonical example for parsers: a
-calculator.  Also uses Flex for the scanner.
-
-Extracted from the documentation: "A Complete C++ Example".
-https://www.gnu.org/software/bison/manual/html_node/A-Complete-C_002b_002b-Example.html
-
-
-* Examples in D
-
-** d/calc.y
-The usual calculator.
-
-
-* Examples in Java
-
-** java/Calc.y
-The usual calculator.
-
-
------
+<!---
 
 Local Variables:
-mode: outline
 fill-column: 76
 ispell-dictionary: "american"
 End:
@@ -64,3 +35,4 @@ Texts.  A copy of the license is included in the "GNU Free
 Documentation License" file as part of this distribution.
 
 # LocalWords:  mfcalc calc parsers yy
+--->

examples/c/local.mk

@@ -0,0 +1,20 @@
+## Copyright (C) 2018 Free Software Foundation, Inc.
+##
+## 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/>.
+
+cdir = $(docdir)/%D%
+dist_c_DATA = %D%/README.md
+
+include %D%/mfcalc/local.mk
+include %D%/rpcalc/local.mk

examples/c/mfcalc/Makefile

@@ -0,0 +1,25 @@
+# This Makefile is designed to be simple and readable.  It does not
+# aim at portability.  It requires GNU Make.
+
+BASE = mfcalc
+BISON = bison
+XSLTPROC = xsltproc
+
+all: $(BASE)
+
+%.c %.xml %.gv: %.y
+	$(BISON) $(BISONFLAGS) --xml --graph=$*.gv -o $*.c $<
+
+%: %.c
+	$(CC) $(CFLAGS) -o $@ $<
+
+run: $(BASE)
+	@echo "Type arithmetic expressions.  Quit with ctrl-d."
+	./$<
+
+html: $(BASE).html
+%.html: %.xml
+	$(XSLTPROC) $(XSLTPROCFLAGS) -o $@ $$($(BISON) --print-datadir)/xslt/xml2xhtml.xsl $<
+
+clean:
+	rm -f $(BASE) $(BASE).c $(BASE).html $(BASE).xml $(BASE).gv $(BASE).output

examples/c/mfcalc/local.mk

@@ -38,5 +38,6 @@ dist_TESTS += %D%/mfcalc.test
 ## Installing.  ##
 ## ------------ ##
 
-mfcalcdir = $(docdir)/examples/mfcalc
+mfcalcdir = $(docdir)/%D%
 mfcalc_DATA = $(mfcalc_extracted)
+dist_mfcalc_DATA = %D%/Makefile

examples/c/rpcalc/Makefile

@@ -0,0 +1,25 @@
+# This Makefile is designed to be simple and readable.  It does not
+# aim at portability.  It requires GNU Make.
+
+BASE = rpcalc
+BISON = bison
+XSLTPROC = xsltproc
+
+all: $(BASE)
+
+%.c %.xml %.gv: %.y
+	$(BISON) $(BISONFLAGS) --xml --graph=$*.gv -o $*.c $<
+
+%: %.c
+	$(CC) $(CFLAGS) -o $@ $<
+
+run: $(BASE)
+	@echo "Type arithmetic expressions in reverse polish notation.  Quit with ctrl-d."
+	./$<
+
+html: $(BASE).html
+%.html: %.xml
+	$(XSLTPROC) $(XSLTPROCFLAGS) -o $@ $$($(BISON) --print-datadir)/xslt/xml2xhtml.xsl $<
+
+clean:
+	rm -f $(BASE) $(BASE).c $(BASE).html $(BASE).xml $(BASE).gv

examples/c/rpcalc/local.mk

@@ -38,5 +38,6 @@ dist_TESTS += %D%/rpcalc.test
 ## Installing.  ##
 ## ------------ ##
 
-rpcalcdir = $(docdir)/examples/rpcalc
+rpcalcdir = $(docdir)/%D%
 rpcalc_DATA = $(rpcalc_extracted)
+dist_rpcalc_DATA = %D%/Makefile

examples/calc++/Makefile

@@ -1,27 +0,0 @@
-# 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

examples/d/Makefile

@@ -14,7 +14,7 @@ all: calc
 	$(DC) $(DCFLAGS) $<
 
 run: calc
-	echo "Type arithmetic expressions.  Quit with ctrl-d."
+	@echo "Type arithmetic expressions.  Quit with ctrl-d."
 	./$<
 
 html: calc.html

examples/d/README.md

@@ -0,0 +1,28 @@
+# Examples in D
+
+This directory contains examples of Bison grammar files in D.
+
+You can run `make` to compile these examples.  And `make clean` to tidy
+afterwards.
+
+## d/calc.y
+The usual calculator.
+
+<!---
+
+Local Variables:
+fill-column: 76
+ispell-dictionary: "american"
+End:
+
+Copyright (C) 2018 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the "GNU Free
+Documentation License" file as part of this distribution.
+
+# LocalWords:  mfcalc calc parsers yy
+--->

examples/d/local.mk

@@ -23,6 +23,7 @@ if ENABLE_D
   check_SCRIPTS += %D%/calc
   TESTS += %D%/calc.test
 endif
+EXTRA_DIST += %D%/calc.test
 
 %D%/calc.d: %D%/calc.y $(BISON_IN) $(dist_pkgdata_DATA)
 	$(AM_V_GEN)$(MKDIR_P) %D%
@@ -31,5 +32,5 @@ endif
 %D%/calc: %D%/calc.d
 	$(AM_V_GEN) $(DC) $(DCFLAGS) -of$@ $<
 
-dist_d_DATA = %D%/calc.y %D%/Makefile
-CLEANFILES += %D%/calc %D%/Calc.d
+dist_d_DATA = %D%/calc.y %D%/Makefile %D%/README.md
+CLEANFILES += %D%/calc %D%/calc.[do]

examples/java/Makefile

@@ -15,7 +15,7 @@ all: Calc.class
 	$(JAVAC) $(JAVACFLAGS) $<
 
 run: Calc.class
-	echo "Type arithmetic expressions.  Quit with ctrl-d."
+	@echo "Type arithmetic expressions.  Quit with ctrl-d."
 	$(JAVA) $(JAVAFLAGS) Calc
 
 html: Calc.html

examples/java/README.md

@@ -0,0 +1,27 @@
+# Examples in Java
+
+This directory contains examples of Bison grammar files in Java.
+
+You can run `make` to compile these examples.  And `make clean` to tidy
+afterwards.
+
+## java/Calc.y
+The usual calculator.
+
+<!---
+
+Local Variables:
+mode: markdown
+fill-column: 76
+ispell-dictionary: "american"
+End:
+
+Copyright (C) 2018 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the "GNU Free
+Documentation License" file as part of this distribution.
+--->

examples/java/local.mk

@@ -23,6 +23,7 @@ if ENABLE_JAVA
   check_SCRIPTS += %D%/Calc.class
   TESTS += %D%/Calc.test
 endif
+EXTRA_DIST += %D%/Calc.test
 
 %D%/Calc.java: %D%/Calc.y $(BISON_IN) $(dist_pkgdata_DATA)
 	$(AM_V_GEN)$(MKDIR_P) %D%
@@ -31,5 +32,5 @@ endif
 %D%/Calc.class: %D%/Calc.java
 	$(AM_V_GEN) $(SHELL) $(top_builddir)/javacomp.sh $<
 
-dist_java_DATA = %D%/Calc.y %D%/Makefile
-CLEANFILES += %D%/Calc.class %D%/Calc.java
+dist_java_DATA = %D%/Calc.y %D%/Makefile %D%/README.md
+CLEANFILES += %D%/*.class %D%/Calc.java

examples/local.mk

@@ -71,13 +71,11 @@ examples-unline:
 ## ---------- ##
 
 examplesdir = $(docdir)/examples
-dist_examples_DATA = %D%/README
+dist_examples_DATA = %D%/README.md
 
 CLEANDIRS += %D%/*.dSYM
 
-include %D%/calc++/local.mk
+include %D%/c/local.mk
 include %D%/c++/local.mk
 include %D%/d/local.mk
 include %D%/java/local.mk
-include %D%/mfcalc/local.mk
-include %D%/rpcalc/local.mk

examples/test

@@ -16,7 +16,7 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 me=$(basename "$1" .test)
-medir=$(basename "$(dirname "$1")")
+medir=$(dirname "$1" | sed -e 's,.*examples/,,')
 
 # Number of the current test.
 number=1
@@ -28,7 +28,7 @@ exit=true
 cwd=$(pwd)
 
 # The exercised program.
-for p in "$cwd/examples/$medir/$me" "$cwd/examples/$me"
+for p in "$cwd/examples/$medir/$me"
 do
     if test -x "$p"; then
         prog=$p
@@ -40,7 +40,8 @@ do
     fi
 done
 if test x"$prog" = x; then
-    echo "$me: ERROR: cannot find program to exercise"
+    echo "$me: ERROR: cannot find program to exercise in:"
+    echo "$me: ERROR:   $cwd/examples/$medir/$me"
     exit 1
 fi