Moved obsolete Makefiles to demos/obsolete/.

Documentation update.

CHANGES

+2015/02/09:
+Moved all of the demos to ocamlbuild (instead of make).
+
 2015/01/18:
 Incompatible change of the incremental API.
 The incremental API now exposes shift events too.

TODO

@@ -35,10 +35,6 @@
   between 4.01.0 and 4.02.1. Use the tag last309 for this purpose,
   or the master branch.
 
-* Is it possible to update calc-two and calc-param to use ocamlbuild?
-    (they need --external-tokens and --only-tokens)
-  Then, one could remove Makefile.shared and ocamldep.wrapper.
-
 * Suite des patchs de Frédéric Bour.
     API d'inspection complète.
       Exposer le nombre d'états (pour la mémoisation) et une conversion état -> entier.
@@ -195,7 +191,7 @@
 
 * expliquer aussi les conflits end-of-stream
 
-* Documenter l'emploi d'ocamlbuild et décourager make/omake.
+* Documenter l'emploi d'ocamlbuild.
 
 * Lorsqu'on crée un pseudo-lexème pour utiliser dans les
   directives %prec, la question de savoir s'il est associatif

demos/calc-two/Makefile.old → demos/obsolete/Makefile.calc-two

-# This is the old Makefile, based on Makefile.shared.
-# Superseded by the new Makefile, based on ocamlbuild.
+# This is the old version of calc-two/Makefile, based on Makefile.shared.
+# It has been superseded by the calc-two/Makefile, based on ocamlbuild.
 
 # Find Menhir.
 ifndef MENHIR

doc/main.tex

@@ -122,8 +122,9 @@ to be textually included within a \Makefile. It is important to note that
 \texttt{.cm[iox]} prerequisites. This is because, when the \oinfer switch
 is used, \menhir infers types by invoking \ocamlc, and \ocamlc itself requires
 the \ocaml modules that the grammar specification depends upon to have been
-compiled first. The file \distrib{demos/Makefile.shared} helps exploit the
-\odepend switch.
+compiled first.
+% The file \distrib{demos/obsolete/Makefile.shared} exploits the \odepend switch.
+An end user who uses \ocamlbuild does not need this switch.
 
 When in \odepend mode, \menhir computes dependencies by invoking \ocamldep.
 The command that is used to run \ocamldep is controlled by the \oocamldep
@@ -163,10 +164,10 @@ especially when advanced features such as \menhir's standard library or
 \dinline keyword are exploited. One downside of \oinfer is that the \ocaml
 compiler usually needs to consult a few \texttt{.cm[iox]} files. This means
 that these files must have been created first, requiring \Makefile changes and
-use of the \odepend switch. The file \distrib{demos/Makefile.shared} suggests
+use of the \odepend switch. The file \distrib{demos/obsolete/Makefile.shared} suggests
 how to deal with this difficulty. A better option is to avoid \make altogether
 and use \ocamlbuild, which has built-in knowledge of \menhir. Using
-\ocamlbuild is also \textbf{strongly recommended}!
+\ocamlbuild is \textbf{strongly recommended}!
 
 % There is a slight catch with \oinfer. The types inferred by \ocamlc are valid
 % in the toplevel context, but can change meaning when inserted into a local
@@ -228,8 +229,11 @@ a single set of tokens is to be shared between several parsers. The directory
 
 \docswitch{\orawdepend} This switch is analogous to \odepend, except that
 \ocamldep's output is not postprocessed by \menhir; it is echoed without
-change. This switch is \emph{not} suitable for direct use with \make; it is
-intended for use with \omake, which performs its own postprocessing.
+change. This switch is not suitable for direct use with \make; it is
+intended for use with \omake or \ocamlbuild, which perform their own
+postprocessing.
+An end user who uses \ocamlbuild does not need to mention this switch:
+\ocamlbuild uses it automatically.
 
 \docswitch{\ostrict} This switch causes several warnings about the grammar
 and about the automaton to be considered errors. This includes warnings about
@@ -245,9 +249,9 @@ parser generated by \menhir. What are these flags? In the absence of the
 \otable switch, they are empty. When \otable is set, these flags ensure that
 \menhirlib is visible to the \ocaml compiler. If the support library
 \menhirlib was installed via \ocamlfind, a \texttt{-package} directive is
-issued; otherwise, a \texttt{-I} directive is used. The file
-\distrib{demos/Makefile.shared} shows how to exploit the \texttt{--suggest-*}
-switches.
+issued; otherwise, a \texttt{-I} directive is used.
+% The file \distrib{demos/obsolete/Makefile.shared} shows how to exploit
+% the \texttt{--suggest-*} switches.
 
 \docswitch{\osuggestlinkb} This switch causes \menhir to print a set of
 suggested link flags, and exit. These flags are intended to be passed to
@@ -255,9 +259,9 @@ suggested link flags, and exit. These flags are intended to be passed to
 the absence of the \otable switch, they are empty. When \otable is set, these
 flags ensure that \menhirlib is linked in. If the support library \menhirlib
 was installed via \ocamlfind, a \texttt{-linkpkg} directive is issued;
-otherwise, the object file \texttt{menhirLib.cmo} is named. The file
-\distrib{demos/Makefile.shared} shows how to exploit the \texttt{--suggest-*}
-switches.
+otherwise, the object file \texttt{menhirLib.cmo} is named.
+% The file \distrib{demos/obsolete/Makefile.shared} shows how to exploit
+% the \texttt{--suggest-*} switches.
 
 \docswitch{\osuggestlinko} This switch causes \menhir to print a set of
 suggested link flags, and exit. These flags are intended to be passed to
@@ -265,9 +269,9 @@ suggested link flags, and exit. These flags are intended to be passed to
 flags? In the absence of the \otable switch, they are empty. When \otable is
 set, these flags ensure that \menhirlib is linked in. If the support library
 \menhirlib was installed via \ocamlfind, a \texttt{-linkpkg} directive is
-issued; otherwise, the object file \texttt{menhirLib.cmx} is named. The file
-\distrib{demos/Makefile.shared} shows how to exploit the \texttt{--suggest-*}
-switches.
+issued; otherwise, the object file \texttt{menhirLib.cmx} is named.
+% The file \distrib{demos/obsolete/Makefile.shared} shows how to exploit
+% the \texttt{--suggest-*} switches.
 
 \docswitch{\ostdlib \nt{directory}} This switch controls the directory
 where the standard library is found. It allows overriding the default
@@ -2243,14 +2247,16 @@ scientific) benchmark suggests that the parsers produced by \ocamlyacc and
 \texttt{menhir} are between 2 and 5 times faster. This benchmark excludes the
 time spent in the lexer and in the semantic actions.
 
-\question{Turning on \oinfer broke my \Makefile! What should I do?}
-Look at \distrib{demos/Makefile.shared}. It is meant to be re-used
-without change. If it does not suit your needs, you can copy parts
-of it into your own \Makefile, or submit suggestions for improvement.
-
-\question{I am unable to write a correct \Makefile for \menhir, and so are
-  you.} True enough. Have a look at \ocamlbuild. It has built-in compilation
-rules for \ocaml and \menhir. That should help.
+\question{How do I write \Makefile rules for Menhir?}
+This can be quite difficult, especially when \oinfer is used.
+Look at \distrib{demos/obsolete/Makefile.shared} or (better) use \ocamlbuild,
+which has built-in compilation rules for \ocaml and \menhir.
+% TEMPORARY document the use of \ocamlbuild (and point to the demos)
+% basic scenario: ocamlbuild -use-menhir
+% what to add for the table back-end? (--table and -package menhirLib)
+%   or use the --suggest options?
+% advanced scenario: multi-module, use .mlypack
+% advanced scenario: --only-tokens and -external-tokens, use .mlypack + _tags + myocamlbuild.ml
 
 \question{\menhir reports \emph{more} shift/reduce conflicts than
 \ocamlyacc! How come?} \ocamlyacc sometimes merges two states