diff --git a/NEWS b/NEWS
index b4f38496..0d09dc72 100644
--- a/NEWS
+++ b/NEWS
@@ -75,6 +75,15 @@ GNU Bison NEWS
   the translated symbol (i.e., it returns '_("variable")' rather that
   '"variable"').
 
+** Documentation
+
+  There are now two examples in examples/java: a very simple calculator, and
+  one that tracks locations to provide acurate error messages.
+
+  A new C example, bistromathic, is a fully featured calculator using many
+  Bison features: pure interface, location tracking, internationalized
+  custom error messages, lookahead-correction, rich debug traces, etc.
+
 * Noteworthy changes in release 3.5.1 (2020-01-19) [stable]
 
 ** Bug fixes
diff --git a/examples/java/README.md b/examples/java/README.md
index 99275756..4be92c80 100644
--- a/examples/java/README.md
+++ b/examples/java/README.md
@@ -5,8 +5,11 @@ 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.
+## simple/Calc.y
+The usual calculator, a very simple version.
+
+## calc/Calc.y
+The calculator, but with location tracking and debug traces.
 
 <!---
 
diff --git a/examples/java/Calc.test b/examples/java/calc/Calc.test
similarity index 100%
rename from examples/java/Calc.test
rename to examples/java/calc/Calc.test
diff --git a/examples/java/Calc.y b/examples/java/calc/Calc.y
similarity index 97%
rename from examples/java/Calc.y
rename to examples/java/calc/Calc.y
index 94411898..dc3f99df 100644
--- a/examples/java/Calc.y
+++ b/examples/java/calc/Calc.y
@@ -160,7 +160,7 @@ class Position {
     line = p.line;
     column = p.column;
   }
-  
+
   public boolean equals (Position l)
   {
     return l.line == line && l.column == column;
@@ -168,7 +168,7 @@ class Position {
 
   public String toString ()
   {
-    return Integer.toString (line) + "." + Integer.toString(column);
+    return Integer.toString (line) + "." + Integer.toString (column);
   }
 
   public int line ()
@@ -187,7 +187,7 @@ class PositionReader extends BufferedReader {
   private Position position = new Position ();
 
   public PositionReader (Reader reader) {
-    super(reader);
+    super (reader);
   }
 
   public int read () throws IOException {
diff --git a/examples/java/Makefile b/examples/java/calc/Makefile
similarity index 100%
rename from examples/java/Makefile
rename to examples/java/calc/Makefile
diff --git a/examples/java/calc/local.mk b/examples/java/calc/local.mk
new file mode 100644
index 00000000..60fad4b9
--- /dev/null
+++ b/examples/java/calc/local.mk
@@ -0,0 +1,36 @@
+## Copyright (C) 2018-2020 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/>.
+
+java_calcdir = $(docdir)/%D%
+
+## ------ ##
+## Calc.  ##
+## ------ ##
+
+if ENABLE_JAVA
+  check_SCRIPTS += %D%/Calc.class
+  TESTS += %D%/Calc.test
+endif
+EXTRA_DIST += %D%/Calc.test
+
+%D%/Calc.java: %D%/Calc.y $(dependencies)
+	$(AM_V_GEN)$(MKDIR_P) %D%
+	$(AM_V_at)$(BISON) $(srcdir)/%D%/Calc.y -o $@
+
+%D%/Calc.class: %D%/Calc.java
+	$(AM_V_GEN) $(SHELL) $(top_builddir)/javacomp.sh %D%/Calc.java
+
+dist_java_calc_DATA = %D%/Calc.y %D%/Makefile
+CLEANFILES += %D%/*.class %D%/Calc.java
diff --git a/examples/java/local.mk b/examples/java/local.mk
index 917bd100..447ae528 100644
--- a/examples/java/local.mk
+++ b/examples/java/local.mk
@@ -1,4 +1,4 @@
-## Copyright (C) 2018-2020 Free Software Foundation, Inc.
+## Copyright (C) 2020 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
@@ -14,23 +14,7 @@
 ## along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 javadir = $(docdir)/%D%
+dist_java_DATA = %D%/README.md
 
-## ------ ##
-## Calc.  ##
-## ------ ##
-
-if ENABLE_JAVA
-  check_SCRIPTS += %D%/Calc.class
-  TESTS += %D%/Calc.test
-endif
-EXTRA_DIST += %D%/Calc.test
-
-%D%/Calc.java: %D%/Calc.y $(dependencies)
-	$(AM_V_GEN)$(MKDIR_P) %D%
-	$(AM_V_at)$(BISON) $(srcdir)/%D%/Calc.y -o $@
-
-%D%/Calc.class: %D%/Calc.java
-	$(AM_V_GEN) $(SHELL) $(top_builddir)/javacomp.sh %D%/Calc.java
-
-dist_java_DATA = %D%/Calc.y %D%/Makefile %D%/README.md
-CLEANFILES += %D%/*.class %D%/Calc.java
+include %D%/calc/local.mk
+include %D%/simple/local.mk
diff --git a/examples/java/simple/Calc.test b/examples/java/simple/Calc.test
new file mode 100644
index 00000000..70494124
--- /dev/null
+++ b/examples/java/simple/Calc.test
@@ -0,0 +1,33 @@
+#! /bin/sh
+
+# Copyright (C) 2018-2020 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/>.
+
+cat >input <<EOF
+1 + 2 * 3
+EOF
+run 0 7
+
+cat >input <<EOF
+1 + 2 * 3 = 7
+(1 + 2) * 3 = 9
+EOF
+run 0 '7
+9'
+
+cat >input <<EOF
+1 + 2 * * 3
+EOF
+run 0 "err: syntax error, unexpected '*', expecting number or '-' or '(' or '!'"
diff --git a/examples/java/simple/Calc.y b/examples/java/simple/Calc.y
new file mode 100644
index 00000000..0337e49d
--- /dev/null
+++ b/examples/java/simple/Calc.y
@@ -0,0 +1,109 @@
+%language "Java"
+
+%define api.parser.class {Calc}
+%define api.parser.public
+
+%define parse.error verbose
+
+%code imports {
+  import java.io.IOException;
+  import java.io.InputStream;
+  import java.io.InputStreamReader;
+  import java.io.Reader;
+  import java.io.StreamTokenizer;
+}
+
+%code {
+  public static void main (String args[]) throws IOException
+  {
+    CalcLexer l = new CalcLexer (System.in);
+    Calc p = new Calc (l);
+    if (!p.parse ())
+      System.exit (1);
+  }
+}
+
+/* Bison Declarations */
+%token <Integer> NUM "number"
+%type  <Integer> exp
+
+%nonassoc '='       /* comparison            */
+%left '-' '+'
+%left '*' '/'
+%precedence NEG     /* negation--unary minus */
+%right '^'          /* exponentiation        */
+
+/* Grammar follows */
+%%
+input:
+  line
+| input line
+;
+
+line:
+  '\n'
+| exp '\n'           { System.out.println ($exp); }
+| error '\n'
+;
+
+exp:
+  NUM                { $$ = $1; }
+| exp '=' exp
+  {
+    if ($1.intValue () != $3.intValue ())
+      yyerror ("calc: error: " + $1 + " != " + $3);
+  }
+| exp '+' exp        { $$ = $1 + $3;  }
+| exp '-' exp        { $$ = $1 - $3;  }
+| exp '*' exp        { $$ = $1 * $3;  }
+| exp '/' exp        { $$ = $1 / $3;  }
+| '-' exp  %prec NEG { $$ = -$2; }
+| exp '^' exp        { $$ = (int) Math.pow ($1, $3); }
+| '(' exp ')'        { $$ = $2; }
+| '(' error ')'      { $$ = 1111; }
+| '!'                { $$ = 0; return YYERROR; }
+| '-' error          { $$ = 0; return YYERROR; }
+;
+
+
+%%
+class CalcLexer implements Calc.Lexer {
+
+  StreamTokenizer st;
+
+  public CalcLexer (InputStream is)
+  {
+    st = new StreamTokenizer (new InputStreamReader (is));
+    st.resetSyntax ();
+    st.eolIsSignificant (true);
+    st.wordChars ('0', '9');
+  }
+
+  public void yyerror (String s)
+  {
+    System.err.println (s);
+  }
+
+  Integer yylval;
+
+  public Object getLVal () {
+    return yylval;
+  }
+
+  public int yylex () throws IOException {
+    int ttype = st.nextToken ();
+    if (ttype == st.TT_EOF)
+      return EOF;
+    else if (ttype == st.TT_EOL)
+      return (int) '\n';
+    else if (ttype == st.TT_WORD)
+      {
+        yylval = new Integer (st.sval);
+        return NUM;
+      }
+    else if (st.ttype == ' ' || st.ttype == '\t')
+      return yylex ();
+    else
+      return st.ttype;
+  }
+}
diff --git a/examples/java/simple/Makefile b/examples/java/simple/Makefile
new file mode 100644
index 00000000..5a165205
--- /dev/null
+++ b/examples/java/simple/Makefile
@@ -0,0 +1,26 @@
+# This Makefile is designed to be simple and readable.  It does not
+# aim at portability.  It requires GNU Make.
+
+BISON = bison
+JAVAC = javac
+JAVA = java
+XSLTPROC = xsltproc
+
+all: Calc.class
+
+%.java %.xml %.gv: %.y
+	$(BISON) $(BISONFLAGS) --xml --graph=$*.gv -o $*.java $<
+
+%.class: %.java
+	$(JAVAC) $(JAVACFLAGS) $<
+
+run: Calc.class
+	@echo "Type arithmetic expressions.  Quit with ctrl-d."
+	$(JAVA) $(JAVAFLAGS) Calc
+
+html: Calc.html
+%.html: %.xml
+	$(XSLTPROC) $(XSLTPROCFLAGS) -o $@ $$($(BISON) --print-datadir)/xslt/xml2xhtml.xsl $<
+
+clean:
+	rm -f *.class Calc.java Calc.html Calc.xml Calc.gv
diff --git a/examples/java/simple/local.mk b/examples/java/simple/local.mk
new file mode 100644
index 00000000..09958dc0
--- /dev/null
+++ b/examples/java/simple/local.mk
@@ -0,0 +1,36 @@
+## Copyright (C) 2018-2020 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/>.
+
+java_simpledir = $(docdir)/%D%
+
+## ------ ##
+## Calc.  ##
+## ------ ##
+
+if ENABLE_JAVA
+  check_SCRIPTS += %D%/Calc.class
+  TESTS += %D%/Calc.test
+endif
+EXTRA_DIST += %D%/Calc.test
+
+%D%/Calc.java: %D%/Calc.y $(dependencies)
+	$(AM_V_GEN)$(MKDIR_P) %D%
+	$(AM_V_at)$(BISON) $(srcdir)/%D%/Calc.y -o $@
+
+%D%/Calc.class: %D%/Calc.java
+	$(AM_V_GEN) $(SHELL) $(top_builddir)/javacomp.sh %D%/Calc.java
+
+dist_java_simple_DATA = %D%/Calc.y %D%/Makefile
+CLEANFILES += %D%/*.class %D%/Calc.java