summaryrefslogtreecommitdiff
path: root/doc/tools
diff options
context:
space:
mode:
Diffstat (limited to 'doc/tools')
-rw-r--r--doc/tools/Translator.tex898
-rwxr-xr-xdoc/tools/latex_filter43
-rwxr-xr-xdoc/tools/show_latex_messages8
3 files changed, 949 insertions, 0 deletions
diff --git a/doc/tools/Translator.tex b/doc/tools/Translator.tex
new file mode 100644
index 00000000..005ca9c0
--- /dev/null
+++ b/doc/tools/Translator.tex
@@ -0,0 +1,898 @@
+\ifx\pdfoutput\undefined % si on est pas en pdflatex
+\documentclass[11pt,a4paper]{article}
+\else
+\documentclass[11pt,a4paper,pdftex]{article}
+\fi
+\usepackage[latin1]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{pslatex}
+\usepackage{url}
+\usepackage{verbatim}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{array}
+\usepackage{fullpage}
+
+\title{Translation from Coq V7 to V8}
+\author{The Coq Development Team}
+
+%% Macros etc.
+\catcode`\_=13
+\let\subscr=_
+\def_{\ifmmode\sb\else\subscr\fi}
+
+\def\NT#1{\langle\textit{#1}\rangle}
+\def\NTL#1#2{\langle\textit{#1}\rangle_{#2}}
+%\def\TERM#1{\textsf{\bf #1}}
+\def\TERM#1{\texttt{#1}}
+\newenvironment{transbox}
+ {\begin{center}\tt\begin{tabular}{l|ll} \hfil\textrm{V7} & \hfil\textrm{V8} \\ \hline}
+ {\end{tabular}\end{center}}
+\def\TRANS#1#2
+ {\begin{tabular}[t]{@{}l@{}}#1\end{tabular} &
+ \begin{tabular}[t]{@{}l@{}}#2\end{tabular} \\}
+\def\TRANSCOM#1#2#3
+ {\begin{tabular}[t]{@{}l@{}}#1\end{tabular} &
+ \begin{tabular}[t]{@{}l@{}}#2\end{tabular} & #3 \\}
+
+%%
+%%
+%%
+\begin{document}
+\maketitle
+
+\section{Introduction}
+
+Coq version 8.0 is a major version and carries major changes: the
+concrete syntax was redesigned almost from scratch, and many notions
+of the libraries were renamed for uniformisation purposes. We felt
+that these changes could discourage users with large theories from
+switching to the new version.
+
+The goal of this document is to introduce these changes on simple
+examples (mainly the syntactic changes), and describe the automated
+tools to help moving to V8.0. Essentially, it consists of a translator
+that takes as input a Coq source file in old syntax and produces a
+file in new syntax and adapted to the new standard library. The main
+extra features of this translator is that it keeps comments, even
+those within expressions\footnote{The position of those comment might
+differ slightly since there is no exact matching of positions between
+old and new syntax.}.
+
+The document is organised as follows: first section describes the new
+syntax on simple examples. It is very translation-oriented. This
+should give users of older versions the flavour of the new syntax, and
+allow them to make translation manually on small
+examples. Section~\ref{Translation} explains how the translation
+process can be automatised for the most part (the boring one: applying
+similar changes over thousands of lines of code). We strongly advise
+users to follow these indications, in order to avoid many potential
+complications of the translation process.
+
+
+\section{The new syntax on examples}
+
+The goal of this section is to introduce to the new syntax of Coq on
+simple examples, rather than just giving the new grammar. It is
+strongly recommended to read first the definition of the new syntax
+(in the reference manual), but this document should also be useful for
+the eager user who wants to start with the new syntax quickly.
+
+The toplevel has an option {\tt -translate} which allows to
+interactively translate commands. This toplevel translator accepts a
+command, prints the translation on standard output (after a %
+\verb+New syntax:+ balise), executes the command, and waits for another
+command. The only requirements is that they should be syntactically
+correct, but they do not have to be well-typed.
+
+This interactive translator proved to be useful in two main
+usages. First as a ``debugger'' of the translation. Before the
+translation, it may help in spotting possible conflicts between the
+new syntax and user notations. Or when the translation fails for some
+reason, it makes it easy to find the exact reason why it failed and
+make attempts in fixing the problem.
+
+The second usage of the translator is when trying to make the first
+proofs in new syntax. Well trained users will automatically think
+their scripts in old syntax and might waste much time (and the
+intuition of the proof) if they have to search the translation in a
+document. Running a translator in the background will allow the user
+to instantly have the answer.
+
+The rest of this section is a description of all the aspects of the
+syntax that changed and how they were translated. All the examples
+below can be tested by entering the V7 commands in the toplevel
+translator.
+
+
+%%
+
+\subsection{Changes in lexical conventions w.r.t. V7}
+
+\subsubsection{Identifiers}
+
+The lexical conventions changed: \TERM{_} is not a regular identifier
+anymore. It is used in terms as a placeholder for subterms to be inferred
+at type-checking, and in patterns as a non-binding variable.
+
+Furthermore, only letters (Unicode letters), digits, single quotes and
+_ are allowed after the first character.
+
+\subsubsection{Quoted string}
+
+Quoted strings are used typically to give a filename (which may not
+be a regular identifier). As before they are written between double
+quotes ("). Unlike for V7, there is no escape character: characters
+are written normally except the double quote which is doubled.
+
+\begin{transbox}
+\TRANS{"abcd$\backslash\backslash$efg"}{"abcd$\backslash$efg"}
+\TRANS{"abcd$\backslash$"efg"}{"abcd""efg"}
+\end{transbox}
+
+
+\subsection{Main changes in terms w.r.t. V7}
+
+
+\subsubsection{Precedence of application}
+
+In the new syntax, parentheses are not really part of the syntax of
+application. The precedence of application (10) is tighter than all
+prefix and infix notations. It makes it possible to remove parentheses
+in many contexts.
+
+\begin{transbox}
+\TRANS{(A x)->(f x)=(g y)}{A x -> f x = g y}
+\TRANS{(f [x]x)}{f (fun x => x)}
+\end{transbox}
+
+
+\subsubsection{Arithmetics and scopes}
+
+The specialized notation for \TERM{Z} and \TERM{R} (introduced by
+symbols \TERM{`} and \TERM{``}) have disappeared. They have been
+replaced by the general notion of scope.
+
+\begin{center}
+\begin{tabular}{l|l|l}
+type & scope name & delimiter \\
+\hline
+types & type_scope & \TERM{type} \\
+\TERM{bool} & bool_scope & \\
+\TERM{nat} & nat_scope & \TERM{nat} \\
+\TERM{Z} & Z_scope & \TERM{Z} \\
+\TERM{R} & R_scope & \TERM{R} \\
+\TERM{positive} & positive_scope & \TERM{P}
+\end{tabular}
+\end{center}
+
+In order to use notations of arithmetics on \TERM{Z}, its scope must
+be opened with command \verb+Open Scope Z_scope.+ Another possibility
+is using the scope change notation (\TERM{\%}). The latter notation is
+to be used when notations of several scopes appear in the same
+expression.
+
+In examples below, scope changes are not needed if the appropriate scope
+has been opened. Scope \verb|nat_scope| is opened in the initial state of Coq.
+\begin{transbox}
+\TRANSCOM{`0+x=x+0`}{0+x=x+0}{\textrm{Z_scope}}
+\TRANSCOM{``0 + [if b then ``1`` else ``2``]``}{0 + if b then 1 else 2}{\textrm{R_scope}}
+\TRANSCOM{(0)}{0}{\textrm{nat_scope}}
+\end{transbox}
+
+Below is a table that tells which notation is available in which
+scope. The relative precedences and associativity of operators is the
+same as in usual mathematics. See the reference manual for more
+details. However, it is important to remember that unlike V7, the type
+operators for product and sum are left-associative, in order not to
+clash with arithmetic operators.
+
+\begin{center}
+\begin{tabular}{l|l}
+scope & notations \\
+\hline
+nat_scope & \texttt{+ - * < <= > >=} \\
+Z_scope & \texttt{+ - * / mod < <= > >= ?=} \\
+R_scope & \texttt{+ - * / < <= > >=} \\
+type_scope & \texttt{* +} \\
+bool_scope & \texttt{\&\& || -} \\
+list_scope & \texttt{:: ++}
+\end{tabular}
+\end{center}
+
+
+
+\subsubsection{Notation for implicit arguments}
+
+The explicitation of arguments is closer to the \emph{bindings}
+notation in tactics. Argument positions follow the argument names of
+the head constant. The example below assumes \verb+f+ is a function
+with two implicit dependent arguments named \verb+x+ and \verb+y+.
+\begin{transbox}
+\TRANS{f 1!t1 2!t2 t3}{f (x:=t1) (y:=t2) t3}
+\TRANS{!f t1 t2}{@f t1 t2}
+\end{transbox}
+
+
+\subsubsection{Inferred subterms}
+
+Subterms that can be automatically inferred by the type-checker is now
+written {\tt _}
+
+\begin{transbox}
+\TRANS{?}{_}
+\end{transbox}
+
+\subsubsection{Universal quantification}
+
+The universal quantification and dependent product types are now
+introduced by the \texttt{forall} keyword before the binders and a
+comma after the binders.
+
+The syntax of binders also changed significantly. A binder can simply be
+a name when its type can be inferred. In other cases, the name and the type
+of the variable are put between parentheses. When several consecutive
+variables have the same type, they can be grouped. Finally, if all variables
+have the same type, parentheses can be omitted.
+
+\begin{transbox}
+\TRANS{(x:A)B}{forall (x:~A), B ~~\textrm{or}~~ forall x:~A, B}
+\TRANS{(x,y:nat)P}{forall (x y :~nat), P ~~\textrm{or}~~ forall x y :~nat, P}
+\TRANS{(x,y:nat;z:A)P}{forall (x y :~nat) (z:A), P}
+\TRANS{(x,y,z,t:?)P}{forall x y z t, P}
+\TRANS{(x,y:nat;z:?)P}{forall (x y :~nat) z, P}
+\end{transbox}
+
+\subsubsection{Abstraction}
+
+The notation for $\lambda$-abstraction follows that of universal
+quantification. The binders are surrounded by keyword \texttt{fun}
+and \verb+=>+.
+
+\begin{transbox}
+\TRANS{[x,y:nat; z](f a b c)}{fun (x y:nat) z => f a b c}
+\end{transbox}
+
+
+\subsubsection{Pattern-matching}
+
+Beside the usage of the keyword pair \TERM{match}/\TERM{with} instead of
+\TERM{Cases}/\TERM{of}, the main change is the notation for the type of
+branches and return type. It is no longer written between \TERM{$<$ $>$} before
+the \TERM{Cases} keyword, but interleaved with the destructured objects.
+
+The idea is that for each destructured object, one may specify a
+variable name (after the \TERM{as} keyword) to tell how the branches
+types depend on this destructured objects (case of a dependent
+elimination), and also how they depend on the value of the arguments
+of the inductive type of the destructured objects (after the \TERM{in}
+keyword). The type of branches is then given after the keyword
+\TERM{return}, unless it can be inferred.
+
+Moreover, when the destructured object is a variable, one may use this
+variable in the return type.
+
+\begin{transbox}
+\TRANS{Cases n of\\~~ O => O \\| (S k) => (1) end}{match n with\\~~ 0 => 0 \\| S k => 1 end}
+\TRANS{Cases m n of \\~~0 0 => t \\| ... end}{match m, n with \\~~0, 0 => t \\| ... end}
+\TRANS{<[n:nat](P n)>Cases T of ... end}{match T as n return P n with ... end}
+\TRANS{<[n:nat][p:(even n)]\~{}(odd n)>Cases p of\\~~ ... \\end}{match p in even n return \~{} odd n with\\~~ ...\\end}
+\end{transbox}
+
+The annotations of the special pattern-matching operators
+(\TERM{if}/\TERM{then}/\TERM{else}) and \TERM{let()} also changed. The
+only restriction is that the destructuring \TERM{let} does not allow
+dependent case analysis.
+
+\begin{transbox}
+\TRANS{
+ \begin{tabular}{@{}l}
+ <[n:nat;x:(I n)](P n x)>if t then t1 \\
+ else t2
+ \end{tabular}}%
+{\begin{tabular}{@{}l}
+ if t as x in I n return P n x then t1 \\
+ else t2
+ \end{tabular}}
+\TRANS{<[n:nat](P n)>let (p,q) = t1 in t2}%
+{let (p,q) in I n return P n := t1 in t2}
+\end{transbox}
+
+
+\subsubsection{Fixpoints and cofixpoints}
+
+An simpler syntax for non-mutual fixpoints is provided, making it very close
+to the usual notation for non-recursive functions. The decreasing argument
+is now indicated by an annotation between curly braces, regardless of the
+binders grouping. The annotation can be omitted if the binders introduce only
+one variable. The type of the result can be omitted if inferable.
+
+\begin{transbox}
+\TRANS{Fix plus\{plus [n:nat] : nat -> nat :=\\~~ [m]...\}}{fix plus (n m:nat) \{struct n\}: nat := ...}
+\TRANS{Fix fact\{fact [n:nat]: nat :=\\
+~~Cases n of\\~~~~ O => (1) \\~~| (S k) => (mult n (fact k)) end\}}{fix fact
+ (n:nat) :=\\
+~~match n with \\~~~~0 => 1 \\~~| (S k) => n * fact k end}
+\end{transbox}
+
+There is a syntactic sugar for single fixpoints (defining one
+variable) associated to a local definition:
+
+\begin{transbox}
+\TRANS{let f := Fix f \{f [x:A] : T := M\} in\\(g (f y))}{let fix f (x:A) : T := M in\\g (f x)}
+\end{transbox}
+
+The same applies to cofixpoints, annotations are not allowed in that case.
+
+\subsubsection{Notation for type cast}
+
+\begin{transbox}
+\TRANS{O :: nat}{0 : nat}
+\end{transbox}
+
+\subsection{Main changes in tactics w.r.t. V7}
+
+The main change is that all tactic names are lowercase. This also holds for
+Ltac keywords.
+
+\subsubsection{Renaming of induction tactics}
+
+\begin{transbox}
+\TRANS{NewDestruct}{destruct}
+\TRANS{NewInduction}{induction}
+\TRANS{Induction}{simple induction}
+\TRANS{Destruct}{simple destruct}
+\end{transbox}
+
+\subsubsection{Ltac}
+
+Definitions of macros are introduced by \TERM{Ltac} instead of
+\TERM{Tactic Definition}, \TERM{Meta Definition} or \TERM{Recursive
+Definition}. They are considered recursive by default.
+
+\begin{transbox}
+\TRANS{Meta Definition my_tac t1 t2 := t1; t2.}%
+{Ltac my_tac t1 t2 := t1; t2.}
+\end{transbox}
+
+Rules of a match command are not between square brackets anymore.
+
+Context (understand a term with a placeholder) instantiation \TERM{inst}
+became \TERM{context}. Syntax is unified with subterm matching.
+
+\begin{transbox}
+\TRANS{Match t With [C[x=y]] -> Inst C[y=x]}%
+{match t with context C[x=y] => context C[y=x] end}
+\end{transbox}
+
+Arguments of macros use the term syntax. If a general Ltac expression
+is to be passed, it must be prefixed with ``{\tt ltac :}''. In other
+cases, when a \'{} was necessary, it is replaced by ``{\tt constr :}''
+
+\begin{transbox}
+\TRANS{my_tac '(S x)}{my_tac (S x)}
+\TRANS{my_tac (Let x=tac In x)}{my_tac ltac:(let x:=tac in x)}
+\TRANS{Let x = '[x](S (S x)) In Apply x}%
+{let x := constr:(fun x => S (S x)) in apply x}
+\end{transbox}
+
+{\tt Match Context With} is now called {\tt match goal with}. Its
+argument is an Ltac expression by default.
+
+
+\subsubsection{Named arguments of theorems ({\em bindings})}
+
+\begin{transbox}
+\TRANS{Apply thm with x:=t 1:=u}{apply thm with (x:=t) (1:=u)}
+\end{transbox}
+
+
+\subsubsection{Occurrences}
+
+To avoid ambiguity between a numeric literal and the optional
+occurrence numbers of this term, the occurrence numbers are put after
+the term itself and after keyword \TERM{as}.
+\begin{transbox}
+\TRANS{Pattern 1 2 (f x) 3 4 d y z}{pattern f x at 1 2, d at 3 4, y, z}
+\end{transbox}
+
+
+\subsubsection{{\tt LetTac} and {\tt Pose}}
+
+Tactic {\tt LetTac} was renamed into {\tt set}, and tactic {\tt Pose}
+was a particular case of {\tt LetTac} where the abbreviation is folded
+in the conclusion\footnote{There is a tactic called {\tt pose} in V8,
+but its behaviour is not to fold the abbreviation at all.}.
+
+\begin{transbox}
+\TRANS{LetTac x = t in H}{set (x := t) in H}
+\TRANS{Pose x := t}{set (x := t)}
+\end{transbox}
+
+{\tt LetTac} could be followed by a specification (called a clause) of
+the places where the abbreviation had to be folded (hypothese and/or
+conclusion). Clauses are the syntactic notion to denote in which parts
+of a goal a given transformation shold occur. Its basic notation is
+either \TERM{*} (meaning everywhere), or {\tt\textrm{\em hyps} |-
+\textrm{\em concl}} where {\em hyps} is either \TERM{*} (to denote all
+the hypotheses), or a comma-separated list of either hypothesis name,
+or {\tt (value of $H$)} or {\tt (type of $H$)}. Moreover, occurrences
+can be specified after every hypothesis after the {\TERM{at}}
+keyword. {\em concl} is either empty or \TERM{*}, and can be followed
+by occurences.
+
+\begin{transbox}
+\TRANS{in Goal}{in |- *}
+\TRANS{in H H1}{in H1, H2 |-}
+\TRANS{in H H1 ...}{in * |-}
+\TRANS{in H H1 Goal}{in H1, H2 |- *}
+\TRANS{in H H1 H2 ... Goal}{in *}
+\TRANS{in 1 2 H 3 4 H0 1 3 Goal}{in H at 1 2, H0 at 3 4 |- * at 1 3}
+\end{transbox}
+
+\subsection{Main changes in vernacular commands w.r.t. V7}
+
+
+\subsubsection{Require}
+
+The default behaviour of {\tt Require} is not to open the loaded
+module.
+
+\begin{transbox}
+\TRANS{Require Arith}{Require Import Arith}
+\end{transbox}
+
+\subsubsection{Binders}
+
+The binders of vernacular commands changed in the same way as those of
+fixpoints. This also holds for parameters of inductive definitions.
+
+
+\begin{transbox}
+\TRANS{Definition x [a:A] : T := M}{Definition x (a:A) : T := M}
+\TRANS{Inductive and [A,B:Prop]: Prop := \\~~conj : A->B->(and A B)}%
+ {Inductive and (A B:Prop): Prop := \\~~conj : A -> B -> and A B}
+\end{transbox}
+
+\subsubsection{Hints}
+
+Both {\tt Hints} and {\tt Hint} commands are beginning with {\tt Hint}.
+
+Command {\tt HintDestruct} has disappeared.
+
+
+The syntax of \emph{Extern} hints changed: the pattern and the tactic
+to be applied are separated by a {\tt =>}.
+\begin{transbox}
+\TRANS{Hint name := Resolve (f ? x)}%
+{Hint Resolve (f _ x)}
+\TRANS{Hint name := Extern 4 (toto ?) Apply lemma}%
+{Hint Extern 4 (toto _) => apply lemma}
+\TRANS{Hints Resolve x y z}{Hint Resolve x y z}
+\TRANS{Hints Resolve f : db1 db2}{Hint Resolve f : db1 db2}
+\TRANS{Hints Immediate x y z}{Hint Immediate x y z}
+\TRANS{Hints Unfold x y z}{Hint Unfold x y z}
+%% \TRANS{\begin{tabular}{@{}l}
+%% HintDestruct Local Conclusion \\
+%% ~~name (f ? ?) 3 [Apply thm]
+%% \end{tabular}}%
+%% {\begin{tabular}{@{}l}
+%% Hint Local Destuct name := \\
+%% ~~3 Conclusion (f _ _) => apply thm
+%% \end{tabular}}
+\end{transbox}
+
+
+\subsubsection{Implicit arguments}
+
+
+{\tt Set Implicit Arguments} changed its meaning in V8: the default is
+to turn implicit only the arguments that are {\em strictly} implicit
+(or rigid), i.e. that remains inferable whatever the other arguments
+are. For instance {\tt x} inferable from {\tt P x} is not strictly
+inferable since it can disappears if {\tt P} is instanciated by a term
+which erases {\tt x}.
+
+\begin{transbox}
+\TRANS{Set Implicit Arguments}%
+{\begin{tabular}{l}
+ Set Implicit Arguments. \\
+ Unset Strict Implicits.
+ \end{tabular}}
+\end{transbox}
+
+However, you may wish to adopt the new semantics of {\tt Set Implicit
+Arguments} (for instance because you think that the choice of
+arguments it sets implicit is more ``natural'' for you).
+
+
+\subsection{Changes in standard library}
+
+Many lemmas had their named changed to improve uniformity. The user
+generally do not have to care since the translators performs the
+renaming.
+
+ Type {\tt entier} from fast_integer.v is renamed into {\tt N} by the
+translator. As a consequence, user-defined objects of same name {\tt N}
+are systematically qualified even tough it may not be necessary. The
+following table lists the main names with which the same problem
+arises:
+\begin{transbox}
+\TRANS{IF}{IF_then_else}
+\TRANS{ZERO}{Z0}
+\TRANS{POS}{Zpos}
+\TRANS{NEG}{Zneg}
+\TRANS{SUPERIEUR}{Gt}
+\TRANS{EGAL}{Eq}
+\TRANS{INFERIEUR}{Lt}
+\TRANS{add}{Pplus}
+\TRANS{true_sub}{Pminus}
+\TRANS{entier}{N}
+\TRANS{Un_suivi_de}{Ndouble_plus_one}
+\TRANS{Zero_suivi_de}{Ndouble}
+\TRANS{Nul}{N0}
+\TRANS{Pos}{Npos}
+\end{transbox}
+
+
+\subsubsection{Implicit arguments}
+
+%% Hugo:
+Main definitions of standard library have now implicit
+arguments. These arguments are dropped in the translated files. This
+can exceptionally be a source of incompatibilities which has to be
+solved by hand (it typically happens for polymorphic functions applied
+to {\tt nil} or {\tt None}).
+%% preciser: avant ou apres trad ?
+
+\subsubsection{Logic about {\tt Type}}
+
+Many notations that applied to {\tt Set} have been extended to {\tt
+Type}, so several definitions in {\tt Type} are superseded by them.
+
+\begin{transbox}
+\TRANS{x==y}{x=y}
+\TRANS{(EXT x:Prop | Q)}{exists x:Prop, Q}
+\TRANS{identityT}{identity}
+\end{transbox}
+
+
+
+%% Doc of the translator
+\section{A guide to translation}
+\label{Translation}
+
+%%\subsection{Overview of the translation process}
+
+Here is a short description of the tools involved in the translation process:
+\begin{description}
+\item{\tt coqc -translate}
+is the automatic translator. It is a parser/pretty-printer. This means
+that the translation is made by parsing every command using a parser
+of old syntax, which is printed using the new syntax. Many efforts
+were made to preserve as much as possible of the quality of the
+presentation: it avoids expansion of syntax extensions, comments are
+not discarded and placed at the same place.
+\item{\tt translate-v8} (in the translation package) is a small
+shell-script that will help translate developments that compile with a
+Makefile with minimum requirements.
+\end{description}
+
+\subsection{Preparation to translation}
+
+This step is very important because most of work shall be done before
+translation. If a problem occurs during translation, it often means
+that you will have to modify the original source and restart the
+translation process. This also means that it is recommended not to
+edit the output of the translator since it would be overwritten if
+the translation has to be restarted.
+
+\subsubsection{Compilation with {\tt coqc -v7}}
+
+First of all, it is mandatory that files compile with the current
+version of Coq (8.0) with option {\tt -v7}. Translation is a
+complicated task that involves the full compilation of the
+development. If your development was compiled with older versions,
+first upgrade to Coq V8.0 with option {\tt -v7}. If you use a Makefile
+similar to those produced by {\tt coq\_makefile}, you probably just
+have to do
+
+{\tt make OPT="-opt -v7"} ~~~or~~~ {\tt make OPT="-byte -v7"}
+
+When the development compiles successfully, there are several changes
+that might be necessary for the translation. Essentially, this is
+about syntax extensions (see section below dedicated to porting syntax
+extensions). If you do not use such features, then you are ready to
+try and make the translation.
+
+\subsection{Translation}
+
+\subsubsection{The general case}
+
+The preferred way is to use script {\tt translate-v8} if your development
+is compiled by a Makefile with the following constraints:
+\begin{itemize}
+\item compilation is achieved by invoking make without specifying a target
+\item options are passed to Coq with make variable COQFLAGS that
+ includes variables OPT, COQLIBS, OTHERFLAGS and COQ_XML.
+\end{itemize}
+These constraints are met by the makefiles produced by {\tt coq\_makefile}
+
+Otherwise, modify your build program so as to pass option {\tt
+-translate} to program {\tt coqc}. The effect of this option is to
+ouptut the translated source of any {\tt .v} file in a file with
+extension {\tt .v8} located in the same directory than the original
+file.
+
+\subsubsection{What may happen during the translation}
+
+This section describes events that may happen during the
+translation and measures to adopt.
+
+These are the warnings that may arise during the translation, but they
+generally do not require any modification for the user:
+Warnings:
+\begin{itemize}
+\item {\tt Unable to detect if $id$ denotes a local definition}\\
+This is due to a semantic change in clauses. In a command such as {\tt
+simpl in H}, the old semantics were to perform simplification in the
+type of {\tt H}, or in its body if it is defined. With the new
+semantics, it is performed both in the type and the body (if any). It
+might lead to incompatibilities
+
+\item {\tt Forgetting obsolete module}\\
+Some modules have disappeared in V8.0 (new syntax). The user does not
+need to worry about it, since the translator deals with it.
+
+\item {\tt Replacing obsolete module}\\
+Same as before but with the module that were renamed. Here again, the
+translator deals with it.
+\end{itemize}
+
+\subsection{Verification of the translation}
+
+The shell-script {\tt translate-v8} also renames {\tt .v8} files into
+{\tt .v} files (older {\tt .v} files are put in a subdirectory called
+{\tt v7}) and tries to recompile them. To do so it invokes {\tt make}
+without option (which should cause the compilation using {\tt coqc}
+without particular option).
+
+If compilation fails at this stage, you should refrain from repairing
+errors manually on the new syntax, but rather modify the old syntax
+script and restart the translation. We insist on that because the
+problem encountered can show up in many instances (especially if the
+problem comes from a syntactic extension), and fixing the original
+sources (for instance the {\tt V8only} parts of notations) once will
+solve all occurrences of the problem.
+
+%%\subsubsection{Errors occurring after translation}
+%%Equality in {\tt Z} or {\tt R}...
+
+\subsection{Particular cases}
+
+\subsubsection{Lexical conventions}
+
+The definition of identifiers changed. Most of those changes are
+handled by the translator. They include:
+\begin{itemize}
+\item {\tt \_} is not an identifier anymore: it is tranlated to {\tt
+x\_}
+\item avoid clash with new keywords by adding a trailing {\tt \_}
+\end{itemize}
+
+If the choices made by translation is not satisfactory
+or in the following cases:
+\begin{itemize}
+\item use of latin letters
+\item use of iso-latin characters in notations
+\end{itemize}
+the user should change his development prior to translation.
+
+\subsubsection{{\tt Case} and {\tt Match}}
+
+These very low-level case analysis are no longer supported. The
+translator tries hard to translate them into a user-friendly one, but
+it might lack type information to do so\footnote{The translator tries
+to typecheck terms before printing them, but it is not always possible
+to determine the context in which terms appearing in tactics
+live.}. If this happens, it is preferable to transform it manually
+before translation.
+
+\subsubsection{Syntax extensions with {\tt Grammar} and {\tt Syntax}}
+
+
+{\tt Grammar} and {\tt Syntax} are no longer supported. They
+should be replaced by an equivalent {\tt Notation} command and be
+processed as described above. Before attempting translation, users
+should verify that compilation with option {\tt -v7} succeeds.
+
+In the cases where {\tt Grammar} and {\tt Syntax} cannot be emulated
+by {\tt Notation}, users have to change manually they development as
+they wish to avoid the use of {\tt Grammar}. If this is not done, the
+translator will simply expand the notations and the output of the
+translator will use the regular Coq syntax.
+
+\subsubsection{Syntax extensions with {\tt Notation} and {\tt Infix}}
+
+These commands do not necessarily need to be changed.
+
+Some work will have to be done manually if the notation conflicts with
+the new syntax (for instance, using keywords like {\tt fun} or {\tt
+exists}, overloading of symbols of the old syntax, etc.) or if the
+precedences are not right.
+
+ Precedence levels are now from 0 to 200. In V8, the precedence and
+associativity of an operator cannot be redefined. Typical level are
+(refer to the chapter on notations in the Reference Manual for the
+full list):
+
+\begin{center}
+\begin{tabular}{|cll|}
+\hline
+Notation & Precedence & Associativity \\
+\hline
+\verb!_ <-> _! & 95 & no \\
+\verb!_ \/ _! & 85 & right \\
+\verb!_ /\ _! & 80 & right \\
+\verb!~ _! & 75 & right \\
+\verb!_ = _!, \verb!_ <> _!, \verb!_ < _!, \verb!_ > _!,
+ \verb!_ <= _!, \verb!_ >= _! & 70 & no \\
+\verb!_ + _!, \verb!_ - _! & 50 & left \\
+\verb!_ * _!, \verb!_ / _! & 40 & left \\
+\verb!- _! & 35 & right \\
+\verb!_ ^ _! & 30 & left \\
+\hline
+\end{tabular}
+\end{center}
+
+
+ By default, the translator keeps the associativity given in V7 while
+the levels are mapped according to the following table:
+
+\begin{center}
+\begin{tabular}{l|l|l}
+V7 level & mapped to & associativity \\
+\hline
+0 & 0 & no \\
+1 & 20 & left \\
+2 & 30 & right \\
+3 & 40 & left \\
+4 & 50 & left \\
+5 & 70 & no \\
+6 & 80 & right \\
+7 & 85 & right \\
+8 & 90 & right \\
+9 & 95 & no \\
+10 & 100 & left
+\end{tabular}
+\end{center}
+
+If this is OK, just simply apply the translator.
+
+
+\paragraph{Associativity conflict}
+
+ Since the associativity of the levels obtained by translating a V7
+level (as shown on table above) cannot be changed, you have to choose
+another level with a compatible associativity.
+
+ You can choose any level between 0 and 200, knowing that the
+standard operators are already set at the levels shown on the list
+above.
+
+Assume you have a notation
+\begin{verbatim}
+Infix NONA 2 "=_S" my_setoid_eq.
+\end{verbatim}
+By default, the translator moves it to level 30 which is right
+associative, hence a conflict with the expected no associativity.
+
+To solve the problem, just add the "V8only" modifier to reset the
+level and enforce the associativity as follows:
+\begin{verbatim}
+Infix NONA 2 "=_S" my_setoid_eq V8only (at level 70, no associativity).
+\end{verbatim}
+The translator now knows that it has to translate "=_S" at level 70
+with no associativity.
+
+Remark: 70 is the "natural" level for relations, hence the choice of 70
+here, but any other level accepting a no-associativity would have been
+OK.
+
+Second example: assume you have a notation
+\begin{verbatim}
+Infix RIGHTA 1 "o" my_comp.
+\end{verbatim}
+By default, the translator moves it to level 20 which is left
+associative, hence a conflict with the expected right associativity.
+
+To solve the problem, just add the "V8only" modifier to reset the
+level and enforce the associativity as follows:
+\begin{verbatim}
+Infix RIGHTA 1 "o" my_comp V8only (at level 20, right associativity).
+\end{verbatim}
+The translator now knows that it has to translate "o" at level 20
+which has the correct "right associativity".
+
+Remark: we assumed here that the user wants a strong precedence for
+composition, in such a way, say, that "f o g + h" is parsed as
+"(f o g) + h". To get "o" binding less than the arithmetical operators,
+an appropriated level would have been close of 70, and below, e.g. 65.
+
+
+\paragraph{Conflict: notation hides another notation}
+
+Remark: use {\tt Print Grammar constr} in V8 to diagnose the overlap
+and see the section on factorization in the chapter on notations of
+the Reference Manual for hints on how to factorize.
+
+Example:
+\begin{verbatim}
+Notation "{ x }" := (my_embedding x) (at level 1).
+\end{verbatim}
+overlaps in V8 with notation \verb#{ x : A & P }# at level 0 and with
+x at level 99. The conflicts can be solved by left-factorizing the
+notation as follows:
+\begin{verbatim}
+Notation "{ x }" := (my_embedding x) (at level 1)
+ V8only (at level 0, x at level 99).
+\end{verbatim}
+
+\paragraph{Conflict: a notation conflicts with the V8 grammar}
+
+Again, use the {\tt V8only} modifier to tell the translator to
+automatically take in charge the new syntax.
+
+Example:
+\begin{verbatim}
+Infix 3 "@" app.
+\end{verbatim}
+Since {\tt @} is used in the new syntax for deactivating the implicit
+arguments, another symbol has to be used, e.g. {\tt @@}. This is done via
+the {\tt V8only} option as follows:
+\begin{verbatim}
+Infix 3 "@" app V8only "@@" (at level 40, left associativity).
+\end{verbatim}
+or, alternatively by
+\begin{verbatim}
+Notation "x @ y" := (app x y) (at level 3, left associativity)
+ V8only "x @@ y" (at level 40, left associativity).
+\end{verbatim}
+
+\paragraph{Conflict: my notation is already defined at another level
+ (or with another associativity)}
+
+In V8, the level and associativity of a given notation can no longer
+be changed. Then, either you adopt the standard reserved levels and
+associativity for this notation (as given on the list above) or you
+change your notation.
+\begin{itemize}
+\item To change the notation, follow the directions in the previous
+paragraph
+\item To adopt the standard level, just use {\tt V8only} without any
+argument.
+\end{itemize}
+
+Example:
+\begin{verbatim}
+Infix 6 "*" my_mult.
+\end{verbatim}
+is not accepted as such in V8. Write
+\begin{verbatim}
+Infix 6 "*" my_mult V8only.
+\end{verbatim}
+to tell the translator to use {\tt *} at the reserved level (i.e. 40
+with left associativity). Even better, use interpretation scopes (look
+at the Reference Manual).
+
+
+\subsubsection{Strict implicit arguments}
+
+In the case you want to adopt the new semantics of {\tt Set Implicit
+ Arguments} (only setting rigid arguments as implicit), add the option
+{\tt -strict-implicit} to the translator.
+
+Warning: changing the number of implicit arguments can break the
+notations. Then use the {\tt V8only} modifier of {\tt Notation}.
+
+\end{document}
diff --git a/doc/tools/latex_filter b/doc/tools/latex_filter
new file mode 100755
index 00000000..044a8642
--- /dev/null
+++ b/doc/tools/latex_filter
@@ -0,0 +1,43 @@
+#!/bin/sh
+
+# First argument is the number of lines to treat
+# Second argument is optional and, if it is "no", overfull are not displayed
+
+i=$1
+nooverfull=$2
+error=0
+verbose=0
+chapter=""
+file=""
+while : ; do
+ read -r line;
+ case $line in
+ "! "*)
+ echo $line $file;
+ error=1
+ verbose=1
+ ;;
+ "LaTeX Font Info"*|"LaTeX Info"*|"Underfull "*)
+ verbose=0
+ ;;
+ "Overfull "*)
+ verbose=0
+ if [ "$nooverfull" != "no" ]; then echo $line $file; fi
+ ;;
+ "LaTeX "*)
+ verbose=0
+ echo $line $chapter
+ ;;
+ "["*|"Chapter "*)
+ verbose=0
+ ;;
+ "(./"*)
+ file="(file `echo $line | cut -b 4- | cut -d' ' -f 1`)"
+ verbose=0
+ ;;
+ *)
+ if [ $verbose = 1 ]; then echo $line; fi
+ esac;
+ if [ "$i" = "0" ]; then break; else i=`expr $i - 1`; fi;
+done
+exit $error
diff --git a/doc/tools/show_latex_messages b/doc/tools/show_latex_messages
new file mode 100755
index 00000000..8f1470ec
--- /dev/null
+++ b/doc/tools/show_latex_messages
@@ -0,0 +1,8 @@
+#!/bin/sh
+
+if [ "$1" = "-no-overfull" ]; then
+ cat $2 | ../tools/latex_filter `cat $2 | wc -l` no
+else
+ cat $1 | ../tools/latex_filter `cat $1 | wc -l` yes
+fi
+