\documentclass[10pt]{article}
\usepackage{a4wide,amstext,amssymb}
\makeindex

% Some special symbols
\def\RR{\mathbb{R}}
\def\QQ{\mathbb{Q}}
\def\NN{\mathbb{N}}
\def\ZZ{\mathbb{Z}}
\def\noto{\mathrel{\#}}
\newcommand{\ac}{^{\prime}}
\def\eqqe{\leftrightarrow}
\newcommand{\maxx}{\mbox{max}}

% environments that are not numbered
\newcommand{\newenvs}[1]{\begin{list}{}{\setlength{\leftmargin}{0pt}
                         \setlength{\rightmargin}{0pt}}\item {#1}}
\newcommand{\newenve}[1]{{#1}\end{list}}
\newcommand{\newenv}[3]{\newenvironment{#1}{\newenvs{#2}}{\newenve{#3}}}

\newenv{convention}{\bf Convention:}{}
\newenv{nameconvention}{\bf Name convention:}{}
\newenv{shortcoming}{\bf Coq shortcoming:}{}
\newenv{notation}{\bf Notation:}{}
\newtheorem{numnotation}{Notation}
\newtheorem{numconvention}[numnotation]{Convention}
\newtheorem{definition}{Definition}[section]
\newtheorem{lemma}[definition]{Lemma}
\newtheorem{conjecture}[definition]{Conjecture}
\newtheorem{proposition}[definition]{Proposition}
\newtheorem{theorem}[definition]{Theorem}
\newtheorem{corollary}[definition]{Corollary}
\newtheorem{remark}[definition]{Remark}
\newtheorem{fact}[definition]{Fact}
\newtheorem{example}[definition]{Example}
\newtheorem{examples}[definition]{Examples}
\newtheorem{claim}[definition]{Claim}

\sloppy
\begin{document}
\title{Theory development leading to the Fundamental
Theorem of Algebra} 
\author{Herman Geuvers, Randy Pollack, Freek Wiedijk, Jan Zwanenburg}
\maketitle
\tableofcontents
\newpage
\section{About this document}
\subsection{Why this document}
To have an actual overview of the concrete Coq proof-development of
FTA, we need to have a document in which all lemmas and definition can
be found, with the actual names (in Coq), together with (syntactic)
conventions, design decisions and explanations. We produce this
document in \LaTeX, to be able to use ordinary mathematical notation
for explanation.

This document should always reflect the actual state of affairs of the
Coq development. Therefore it is best to extract this \LaTeX\ code
form the Coq code. Coq already provides one way of doing so, by the so
called `gallina' files. These remove from a Coq file all proofs,
yielding a \verb!.g! file. However, we want more: notably we want to
add {\em mathematical\/} comments. Hence we introduce a different
set-up, where we add comments to the Coq files. A small compiler
script then translates the Coq files to \LaTeX\ source code (taking
the comments into account, comaparable with compiler-directives in
programs). Note that there are two other possibilities: (1) Use
\LaTeX\ files with comments that facilitate the extraction of Coq
code; (2) Define a new file format from which both the Coq code and
the \LaTeX\ code can be extracted. As we are working with Coq most of
the time, these two options seem less convenient.  So, taking the
option of using the Coq files as basic, the comments will have to be
written as Coq-comments to be able to use the files as valid Coq proof
scripts.

\subsection{How to make this document}
In the \verb!algebra! main directory, type \verb!maketex!  (or
\verb!bin/maketex! if you get the reply
\verb!maketex: command not found!).  This command concatenates the
file \verb!body/body_pre.tex!, the tex comments in the Coq script
files (see below), and the file \verb!body/body_post.tex!  into the
file \verb!body/body.tex!. The file \verb!body/body.tex! should not be
edited manually!  Go to the \verb!body! subdirectory, and latex the
file \verb!body.tex!.

\subsection{Tex comments in script files}
\begin{itemize}
\item To put some piece of the script file verbatim in the tex file (e.g.\ for
lemmas and definitions), insert
\[\verb!(* Begin_Tex_Verb *)!\]
before this piece, and
\[\verb!(* End_Tex_Verb *)!\]
just after this piece.
\item In order to put some prose in the tex file, insert a line
\[\verb!(* Tex_Prose!\]
then insert the text, and then insert a line
\[\verb!*)!\]
\end{itemize}
\subsection{Guidelines for producing this document}
We have made the following \LaTeX\ environments:
\begin{itemize}
\item The {\sf convention}, {\sf numconvention} environments for unnumbered
      and numbered conventions, respectively.
\item The {\sf nameconvention} environment.
\item The {\sf notation}, {\sf numnotation} environments.
\item The {\sf shortcoming} environment.
\end{itemize}
What {\em should\/} be included and how:
\begin{itemize}
\item Lemmas: verbatim.
\item Definitions: verbatim. (It is not clear how interactively constructed
definitions should be included; see below.)
\item Variable declarations: typically with the \LaTeX\ convention environment.
\item Syntactic definitions: with the \LaTeX\ notation environment.
\item Sections: Since every script file corresponds with one section
in the \LaTeX\ document, a Coq-section should usually be included as a
\LaTeX-subsection, and a nested Coq-section should be included as a
\LaTeX-subsubsection.  However, the end of one Coq-section does not
always coincide with the start of a next Coq-section (in contrast to
\LaTeX). In these cases, additional \LaTeX\ ((sub)sub)sections are
introduced to avoid confusion (e.g.\ see \verb!CSetoids.v!).

If a Coq-section is introduced only for a few definitions/lemmas, it is
sometimes simpler not to include this structure in the \LaTeX\ file.

\item Coercions: as conventions.
\item Comments: usually as \LaTeX\ prose.
\end{itemize}
What {\em should not\/} be included:
\begin{itemize}
\item Proofs.
\item Tactic definitions.
\item Import lists ({\tt Require}).
\item Commands for setting implicit arguments on/off.
\item Hints.
\end{itemize}
\section{General notes}
\subsection{Notes about the development}
\begin{itemize}
\item We would like to avoid giving explicit proof terms in
definitions and lemmas as much as possible. (In mathematics, the
existence (or construction) of an object may depend on the {\em
truth\/} (or {\em provability}) of a statement, but not on its actual
proof.  In Coq, we cannot always avoid this, in particular, when
making definitions.  
\item In Coq, a definition can be given in two
ways. Either it must be completely written out, or it is completely
constructed interactively; there is no in-between.  The latter option
has as disadvantage that we cannot really see how something is defined. 
(We do not display the proof script, but even a proof script says little 
about the actual constructed object). The
former has as disadvantage that the subterms corresponding with proofs
may be hard to write. Currently, we don't have any guideline which of
the two options to choose.  (One would like to pack all proof
information in lemmas, so that each proof occurring in a definition
could be denoted by just a variable.) What soemtimes works well for 
objects that are hard to define is to define the object interactively, then
to print it (using the \verb!Print! command) and then to redefine the 
printed thing (possibly after some editing).

\item The word \verb!Axiom! occurring in proof scripts usually means we 
      just did not prove the property yet.
\item Many operations \verb!op! have a syntactically sugared version, e.g.
      for which some arguments are implicit (e.g. defined by the ``Syntactic
      Definition'' construction in combination with ``?'').
      This sugared version is always denoted by capitalizing the first letter
      of \verb!op!.
\item In Coq, there are two ways to provide implicit arguments.
First the {\tt Implicit Arguments} mechanism. Second, the {\tt Syntactic
Definition} mechanism in combination with {\tt ?}. We need a guideline when
to use which one.
\end{itemize}
\subsection{Notes about Coq (shortcomings)}
\begin{enumerate}
\item
   The Coq syntax is not particularly perfect.  All kinds of
   operators can not be written down in the way one would want to.  A
   mature parser with overloading (where the  $+$ in $x+y$
   depends on the types of $x$ and $y$) would help.
\item
   Proof obligations can be very cumbersome.  If you write down
    something like \verb!3^(1-k)!, you have to think about whether it
    is {\em allowed\/} to user a power to the $1-k$th.  That's ok to a
    certain extent (it's in the mathematics), {\em but} you will have
    to add the {\em reason\/} why you're allowed to do it as an
    argument. This makes expressions very heavy.
\item
   Continuing forward and then `backwards' constructing what you need
   can be inefficient, because what you are going to {\em use\/} are
   the things that are already there, instead of {\em extending\/} the
   things that are already there. So, you will take detours, do things
   in an unnecesarily ugly way and do things in a too restricted way
   (where you could prove a more general result), just to prevent you
   from having to add a whole list of elementary lemmas. (You have the
   feeling that `that level of generality is not the issue right
   now'.) Moreover, re-coqing the whole development, taking into
   account all the new `basic generalities' will take a lot of time,
   which discourages you even stronger to prove the add the
   generalities.

   On the other hand, starting from the basics only works (and even
   then only to a certain extent) if you know what the basic results
   are that you will be needing. This is the case for established
   theories, like groups (but even then you will notice that when
   you're in Coq, you will need a lot more then you had imagined), but
   it does not work if you want to set up, say, a small library for
   dealing with finite sequences: you will reamin working on the
   basics for a long time, to find out later that you needed different
   definitions and properties about them.
\item
   `Efficiency' makes that you will write down the development less
   clearly then possible and desirable. For example Freek uses
   \verb!Half! instead of \verb!One[/]Two! and then chooses a
   derivation that uses only multiplication, because division is so
   complicated. That is not what you want, because the development
   gets less perspicuous.
\end{enumerate}
General namegiving conventions:
\begin{itemize}
\item \verb!imp! stands for implies.
\item ``left'' and ``right'' are abbreviated to \verb!lft! and \verb!rht!,
      respectively.
\item 
\begin{tabular}[t]{lll}
preserve & $\mapsto$ & {\tt pres}\\
predicate & $\mapsto$ & {\tt pred}\\
relation & $\mapsto$ & {\tt rel}\\
respects & $\mapsto$ & {\tt resp}\\
\end{tabular}
\end{itemize}
\newpage
\section{Formalization of the algebraic hierarchy in Coq}

We extend 
structures according to the following abstract
pattern (the reader might find it easier to consider a specific example,
e.g. see Section~\ref{section:monoids}).

\newcommand{\mvar}[1]{{\it #1}}
\newcommand{\mvarSub}[2]{$\text{\it#1}_#2$}
Let us say we extend structure $A$ (with name \mvar{AName}) to structure $B$
(with name \mvar{BName}, abbreviated to \mvar{b}), with operations
\mvarSub{opName}{1} : $\sigma_1$, \ldots,
\mvarSub{opName}{n} : $\sigma_n$, and with properties
\mvarSub{propName}{1} : $P_1$, \ldots,
\mvarSub{propName}{m} : $P_m$.
We do this as follows.

First we define a record \verb!is_!\mvar{Bname} in which all properties are
grouped:
\begin{tabbing}
\tt Record \verb!is_!\mvar{BName} 
    [A:\mvar{AName}; \mvarSub{opName}{1} : $\sigma_1$; {\ldots} ; 
                     \mvarSub{opName}{n} : $\sigma_n$] : Prop := \\
\tt \verb!  {ax_!\mvarSub{propName}{1} : $P_1$; \\
\tt \verb!   !\vdots \\
\tt \verb!   ax_!\mvarSub{propName}{m} : $P_m$\\
\tt \verb!  }.!
\end{tabbing}
Then we define the actual structure $B$:
\begin{tabbing}
\tt Record \mvar{BName} : Type :=\\
\tt  \verb!  {!\mvar{b}\verb!_crr :> !\mvar{AName};\\
\tt  \verb!   !\mvar{b}\verb!_!\mvarSub{opName}{1} : $\sigma_1$; \\
\tt  \verb!   !\vdots \\
\tt  \verb!   !\mvar{b}\verb!_!\mvarSub{opName}{n} : $\sigma_n$; \\
\tt  \verb!   !\mvar{b}\verb!_proof : (is_!\mvar{BName} \mvar{b}\verb!_crr!
                                  \mvar{b}\verb!_!\mvarSub{opName}{1} \ldots
                                  \mvar{b}\verb!_!\mvarSub{opName}{n}\verb!)!\\
\tt  \verb!  }.!
\end{tabbing}
And then we prove the basic lemmas directly corresponding to the properties
(maybe after introducing some notational conveniences).
\begin{tabbing}
\tt Section \mvar{BName}\verb!_axioms.!\\
\tt Variable B : \mvar{BName}.\\
\tt Lemma \mvar{BName}\verb!_is_!\mvar{BName} : \verb!is_!\mvar{BName} B 
\mvar{b}\verb!_!\mvarSub{opName}{1}\ldots\mvar{b}\verb!_!\mvarSub{opName}{n}.\\
\tt Lemma \mvarSub{propName}{1} : $P_1$.\\
\tt \vdots\\
\tt Lemma \mvarSub{propName}{m} : $P_m$.\\
\tt End \mvar{BName}\verb!_axioms.!\\
\end{tabbing}
The reason for introducing
the basic lemmas is stated in note~\ref{item:basic-lemmas}
below.

Notes.
\begin{enumerate}
\item The properties $P_1$ through $P_m$ are always written using auxiliary
definitions, often defined directly before \verb!is_!\mvar{Bname}.
E.g.\ in the definition of monoids (Section~\ref{section:monoids}) $P_1$ is
\verb!is_rht_unit G Csg_op Zero!, and \verb!is_rht_unit! is defined 
directly before \verb!is_Monoid!.
\item If there is just one property (i.e.\ $m=1$), then we do not use the
record mechanism to define \verb!is_!\mvar{Bname}, but use an ordinary
definition instead.
\item\label{item:basic-lemmas}
Each field in the record \verb!is_!\mvar{Bname} has an associated
function \verb!ax_!\mvarSub{propName}{i}, with the following type:
\begin{tabbing}\tt
(A:\mvar{AName}; \mvarSub{opName}{1} : $\sigma_1$; {\ldots} ; 
                 \mvarSub{opName}{n} : $\sigma_n$)
 \verb!is_!\mvar{BName} \verb!->! $P_i$.
\end{tabbing}
This type is very cumbersome to use. Therefore we introduced the basic lemmas.
The natural names \mvarSub{propName}{1}\ldots \mvarSub{propName}{m}
are reserved for these basic lemmas, and to avoid name clashes
the field names are prefixed with ``\verb!ax_!''.
\item The operations may be either functions that deliver a mathematical
object (e.g.\ addition), or predicates (e.g.\ less than).
\end{enumerate}
\subsection*{Alternatives and design decisions}
\begin{itemize}
\item Alternative: more structuring, with \verb!sig_!\mvar{bName}.
\item Alternative: less structuring, without \verb!is_!\mvar{bName}.
\end{itemize}

\section{New tactics}
There are two groups of new tactics, each treated in a separate subsection.
To understand their description the reader
should have basic knowledge of our implementation of the algebraic hierarchy.

\subsection{Proving equalities}
There are two new tactics that prove \verb!CSetoid! equalities, i.e.\ goals of
the form $a$ \verb![=]! $b$.
First, we have the \verb!Algebra! tactic, which is implemented with Coq's Auto
mechanism.
It can be used to prove simple equalities, typically only those that are
just one application of a lemma.

Second, we have the \verb!Rational! tactic.
This tactic works only from \verb!CRings! onwards, so for \verb!CRings!,
\verb!CFields!, \verb!COrdFields! and so on, but not for \verb!CGroups!,
\verb!CMonoids!, etc.
The tactic \verb!Rational! is much more clever than \verb!Algebra!: it rewrites
both sides of the equality to some canonical form and compares these.
It automatically uses commutativity, associativity and so on.

\subsection{Using equalities}
Consider the following situation:
the goal is of the form $a$ \verb![#]! $b$ and the user wants to prove this
by showing $a'$ \verb![#]! $b$, since $a$ \verb![=]! $a'$.
In this situation, the user can type \verb!Step_ap_lft! $a'$.
This generates the goal $a'$ \verb![#]! $b$, and a goal $a$ \verb![=]! $a'$,
which the \verb!Algebra! tactic tries to solve.

Similarly, the right hand side $b$ of an apartness can be replaced by an equal
$b'$ by typing \verb!Step_ap_rht! $b'$.
Similar to \verb!Step_ap_lft! and \verb!Step_ap_rht! are the
\verb!Step_Rat_ap_lft! and \verb!Step_Rat_ap_rht! tactics, which use 
\verb!Rational! instead of \verb!Algebra! to prove the equality.

These four tactic are for the apartness relation. Similar tactics exist for
\verb![=]!, \verb![:<]!, \verb![:<=]!, and \verb!AbsSmall!, as shown below.

\begin{tabular}{l|l|l}
Relation & equality proved with \verb!Algebra!
         & equality proved with \verb!Rational! \\\hline
\verb![#]! & \verb!Step_ap_lft! & \verb!Step_Rat_ap_lft! \\
           & \verb!Step_ap_rht! & \verb!Step_Rat_ap_rht! \\\hline
\verb![=]! & \verb!Step_lft! (or \verb!Step!)&  \verb!Step_Rat_lft! \\
           & \verb!Step_rht! (or \verb!Stepr!) & \verb!Step_Rat_rht! \\\hline
\verb![:<]! & \verb!Step_less_lft! & \verb!Step_Rat_less_lft! \\
           & \verb!Step_less_rht! & \verb!Step_Rat_less_rht! \\\hline
\verb![:<=]! & \verb!Step_leEq_lft! & \verb!Step_Rat_leEq_lft! \\
             & \verb!Step_leEq_rht! & \verb!Step_Rat_leEq_rht! \\\hline
\verb!AbsSmall! & \verb!Step_AbsSmall_lft!&\verb!Step_Rat_AbsSmall_lft! \\
                & \verb!Step_AbsSmall_rht!&\verb!Step_Rat_AbsSmall_rht!\\\hline
\end{tabular}

Finally, the \verb!Step_final! $c$ tactic tries to prove the equality
$a$ \verb![=]! $b$ by applying \verb!Algebra! to 
$a$ \verb![=]! $c$ and $c$ \verb![=]! $b$.
