diff options
| author | Théo Zimmermann | 2018-04-15 09:59:21 +0200 |
|---|---|---|
| committer | Théo Zimmermann | 2018-04-15 09:59:21 +0200 |
| commit | c739e641949522a4861ece4374fbf37f0052b89e (patch) | |
| tree | 6db201ce4e158eb7f7769a5611161ee1dc3619ca | |
| parent | c291a8829556dc2a61fcacc08b34e1d68d66b89e (diff) | |
| parent | 48ee801ef08529a049c1c57e31760e7d63a8f11a (diff) | |
Merge PR #7252: Sphinx doc fix warnings
30 files changed, 734 insertions, 652 deletions
diff --git a/Makefile.doc b/Makefile.doc index 087d0b36bf..dc2b9f55d9 100644 --- a/Makefile.doc +++ b/Makefile.doc @@ -82,7 +82,7 @@ doc: sphinx refman tutorial rectutorial stdlib $(INDEXURLS) sphinx: coq $(SHOW)'SPHINXBUILD doc/sphinx' - $(HIDE)COQBIN="$(PWD)/bin" $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) doc/sphinx $(SPHINXBUILDDIR)/html + $(HIDE)COQBIN="$(PWD)/bin" $(SPHINXBUILD) -W -b html $(ALLSPHINXOPTS) doc/sphinx $(SPHINXBUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(SPHINXBUILDDIR)/html." diff --git a/doc/sphinx/addendum/extended-pattern-matching.rst b/doc/sphinx/addendum/extended-pattern-matching.rst index 64d4eddf04..1d3b661732 100644 --- a/doc/sphinx/addendum/extended-pattern-matching.rst +++ b/doc/sphinx/addendum/extended-pattern-matching.rst @@ -305,6 +305,8 @@ explicitations (as for terms 2.7.11). end). +.. _matching-dependent: + Matching objects of dependent types ----------------------------------- @@ -414,6 +416,7 @@ length, by writing I have a copy of :g:`b` in type :g:`listn 0` resp :g:`listn (S n')`. +.. _match-in-patterns: Patterns in ``in`` ~~~~~~~~~~~~~~~~~~ diff --git a/doc/sphinx/addendum/extraction.rst b/doc/sphinx/addendum/extraction.rst index d7f97edab1..38365e4035 100644 --- a/doc/sphinx/addendum/extraction.rst +++ b/doc/sphinx/addendum/extraction.rst @@ -1,16 +1,16 @@ -.. _extraction: - .. include:: ../replaces.rst -Extraction of programs in OCaml and Haskell -============================================ +.. _extraction: + +Extraction of programs in |OCaml| and Haskell +============================================= :Authors: Jean-Christophe Filliâtre and Pierre Letouzey We present here the |Coq| extraction commands, used to build certified and relatively efficient functional programs, extracting them from either |Coq| functions or |Coq| proofs of specifications. The -functional languages available as output are currently OCaml, Haskell +functional languages available as output are currently |OCaml|, Haskell and Scheme. In the following, "ML" will be used (abusively) to refer to any of the three. @@ -89,11 +89,11 @@ in the |Coq| sources. .. cmd:: Extraction TestCompile @qualid ... @qualid. All the mentioned objects and all their dependencies are extracted - to a temporary OCaml file, just as in ``Extraction "file"``. Then + to a temporary |OCaml| file, just as in ``Extraction "file"``. Then this temporary file and its signature are compiled with the same - OCaml compiler used to built |Coq|. This command succeeds only - if the extraction and the OCaml compilation succeed. It fails - if the current target language of the extraction is not OCaml. + |OCaml| compiler used to built |Coq|. This command succeeds only + if the extraction and the |OCaml| compilation succeed. It fails + if the current target language of the extraction is not |OCaml|. Extraction Options ------------------- @@ -102,26 +102,26 @@ Setting the target language ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ability to fix target language is the first and more important -of the extraction options. Default is ``Ocaml``. +of the extraction options. Default is ``OCaml``. -.. cmd:: Extraction Language Ocaml. +.. cmd:: Extraction Language OCaml. .. cmd:: Extraction Language Haskell. .. cmd:: Extraction Language Scheme. Inlining and optimizations ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since OCaml is a strict language, the extracted code has to +Since |OCaml| is a strict language, the extracted code has to be optimized in order to be efficient (for instance, when using induction principles we do not want to compute all the recursive calls but only the needed ones). So the extraction mechanism provides an automatic optimization routine that will be called each time the user -want to generate OCaml programs. The optimizations can be split in two +want to generate |OCaml| programs. The optimizations can be split in two groups: the type-preserving ones (essentially constant inlining and reductions) and the non type-preserving ones (some function abstractions of dummy types are removed when it is deemed safe in order to have more elegant types). Therefore some constants may not appear in the -resulting monolithic OCaml program. In the case of modular extraction, +resulting monolithic |OCaml| program. In the case of modular extraction, even if some inlining is done, the inlined constant are nevertheless printed, to ensure session-independent programs. @@ -264,10 +264,9 @@ what ML term corresponds to a given axiom. be inlined everywhere instead of being declared via a ``let``. .. note:: - - This command is sugar for an ``Extract Constant`` followed - by a ``Extraction Inline``. Hence a ``Reset Extraction Inline`` - will have an effect on the realized and inlined axiom. + This command is sugar for an ``Extract Constant`` followed + by a ``Extraction Inline``. Hence a ``Reset Extraction Inline`` + will have an effect on the realized and inlined axiom. .. caution:: It is the responsibility of the user to ensure that the ML terms given to realize the axioms do have the expected types. In @@ -336,7 +335,7 @@ native boolean type instead of |Coq| one. The syntax is the following: argument is considered to have one unit argument, in order to block early evaluation of the branch: ``| O => bar`` leads to the functional form ``(fun () -> bar)``. For instance, when extracting ``nat`` - into OCaml ``int``, the code to provide has type: + into |OCaml| ``int``, the code to provide has type: ``(unit->'a)->(int->'a)->int->'a``. .. caution:: As for ``Extract Constant``, this command should be used with care: @@ -347,15 +346,15 @@ native boolean type instead of |Coq| one. The syntax is the following: * Extracting an inductive type to a pre-existing ML inductive type is quite sound. But extracting to a general type (by providing an ad-hoc pattern-matching) will often **not** be fully rigorously - correct. For instance, when extracting ``nat`` to OCaml ``int``, + correct. For instance, when extracting ``nat`` to |OCaml| ``int``, it is theoretically possible to build ``nat`` values that are - larger than OCaml ``max_int``. It is the user's responsibility to + larger than |OCaml| ``max_int``. It is the user's responsibility to be sure that no overflow or other bad events occur in practice. * Translating an inductive type to an arbitrary ML type does **not** magically improve the asymptotic complexity of functions, even if the ML type is an efficient representation. For instance, when extracting - ``nat`` to OCaml ``int``, the function ``Nat.mul`` stays quadratic. + ``nat`` to |OCaml| ``int``, the function ``Nat.mul`` stays quadratic. It might be interesting to associate this translation with some specific ``Extract Constant`` when primitive counterparts exist. @@ -369,9 +368,9 @@ Typical examples are the following: .. note:: - When extracting to Ocaml, if an inductive constructor or type has arity 2 and + When extracting to |OCaml|, if an inductive constructor or type has arity 2 and the corresponding string is enclosed by parentheses, and the string meets - Ocaml's lexical criteria for an infix symbol, then the rest of the string is + |OCaml|'s lexical criteria for an infix symbol, then the rest of the string is used as infix constructor or type. .. coqtop:: in @@ -380,7 +379,7 @@ Typical examples are the following: Extract Inductive prod => "(*)" [ "(,)" ]. As an example of translation to a non-inductive datatype, let's turn -``nat`` into OCaml ``int`` (see caveat above): +``nat`` into |OCaml| ``int`` (see caveat above): .. coqtop:: in @@ -394,7 +393,7 @@ directly depends from the names of the |Coq| files. It may happen that these filenames are in conflict with already existing files, either in the standard library of the target language or in other code that is meant to be linked with the extracted code. -For instance the module ``List`` exists both in |Coq| and in OCaml. +For instance the module ``List`` exists both in |Coq| and in |OCaml|. It is possible to instruct the extraction not to use particular filenames. .. cmd:: Extraction Blacklist @ident ... @ident. @@ -410,7 +409,7 @@ It is possible to instruct the extraction not to use particular filenames. Allow the extraction to use any filename. -For OCaml, a typical use of these commands is +For |OCaml|, a typical use of these commands is ``Extraction Blacklist String List``. Differences between |Coq| and ML type systems @@ -418,7 +417,7 @@ Differences between |Coq| and ML type systems Due to differences between |Coq| and ML type systems, some extracted programs are not directly typable in ML. -We now solve this problem (at least in OCaml) by adding +We now solve this problem (at least in |OCaml|) by adding when needed some unsafe casting ``Obj.magic``, which give a generic type ``'a`` to any term. @@ -432,7 +431,7 @@ function: Definition dp {A B:Type}(x:A)(y:B)(f:forall C:Type, C->C) := (f A x, f B y). -In Ocaml, for instance, the direct extracted term would be:: +In |OCaml|, for instance, the direct extracted term would be:: let dp x y f = Pair((f () x),(f () y)) @@ -455,12 +454,12 @@ of a constructor; for example: Inductive anything : Type := dummy : forall A:Set, A -> anything. which corresponds to the definition of an ML dynamic type. -In OCaml, we must cast any argument of the constructor dummy +In |OCaml|, we must cast any argument of the constructor dummy (no GADT are produced yet by the extraction). Even with those unsafe castings, you should never get error like ``segmentation fault``. In fact even if your program may seem -ill-typed to the Ocaml type-checker, it can't go wrong : it comes +ill-typed to the |OCaml| type-checker, it can't go wrong : it comes from a Coq well-typed terms, so for example inductive types will always have the correct number of arguments, etc. Of course, when launching manually some extracted function, you should apply it to arguments @@ -470,14 +469,14 @@ More details about the correctness of the extracted programs can be found in :cite:`Let02`. We have to say, though, that in most "realistic" programs, these problems do not -occur. For example all the programs of Coq library are accepted by the OCaml +occur. For example all the programs of Coq library are accepted by the |OCaml| type-checker without any ``Obj.magic`` (see examples below). Some examples ------------- We present here two examples of extractions, taken from the -|Coq| Standard Library. We choose OCaml as target language, +|Coq| Standard Library. We choose |OCaml| as target language, but all can be done in the other dialects with slight modifications. We then indicate where to find other examples and tests of extraction. @@ -493,7 +492,7 @@ This module contains a theorem ``eucl_dev``, whose type is:: where ``diveucl`` is a type for the pair of the quotient and the modulo, plus some logical assertions that disappear during extraction. -We can now extract this program to OCaml: +We can now extract this program to |OCaml|: .. coqtop:: none @@ -513,7 +512,7 @@ You can then copy-paste the output to a file ``euclid.ml`` or let Extraction "euclid" eucl_dev. -Let us play the resulting program (in an OCaml toplevel):: +Let us play the resulting program (in an |OCaml| toplevel):: #use "euclid.ml";; type nat = O | S of nat @@ -527,7 +526,7 @@ Let us play the resulting program (in an OCaml toplevel):: # eucl_dev (S (S O)) (S (S (S (S (S O)))));; - : diveucl = Divex (S (S O), S O) -It is easier to test on OCaml integers:: +It is easier to test on |OCaml| integers:: # let rec nat_of_int = function 0 -> O | n -> S (nat_of_int (n-1));; val nat_of_int : int -> nat = <fun> diff --git a/doc/sphinx/addendum/generalized-rewriting.rst b/doc/sphinx/addendum/generalized-rewriting.rst index da9e97e6fa..d60387f4f6 100644 --- a/doc/sphinx/addendum/generalized-rewriting.rst +++ b/doc/sphinx/addendum/generalized-rewriting.rst @@ -1,14 +1,12 @@ -.. _generalizedrewriting: - ------------------------ - Generalized rewriting ------------------------ +.. include:: ../preamble.rst +.. include:: ../replaces.rst -:Author: Matthieu Sozeau +.. _generalizedrewriting: Generalized rewriting ===================== +:Author: Matthieu Sozeau This chapter presents the extension of several equality related tactics to work over user-defined structures (called setoids) that are @@ -479,7 +477,7 @@ The declaration itself amounts to the definition of an object of the record type ``Coq.Classes.RelationClasses.Equivalence`` and a hint added to the ``typeclass_instances`` hint database. Morphism declarations are also instances of a type class defined in ``Classes.Morphisms``. See the -documentation on type classes :ref:`TODO-chapter-20-type-classes` +documentation on type classes :ref:`typeclasses` and the theories files in Classes for further explanations. One can inform the rewrite tactic about morphisms and relations just @@ -707,22 +705,20 @@ defined constants as transparent by default. This may slow down the resolution due to a lot of unifications (all the declared ``Proper`` instances are tried at each node of the search tree). To speed it up, declare your constant as rigid for proof search using the command -``Typeclasses Opaque`` (see :ref:`TODO-20.6.7-typeclasses-transparency`). - +``Typeclasses Opaque`` (see :ref:`TypeclassesTransparent`). Strategies for rewriting ------------------------ - Definitions ~~~~~~~~~~~ -The generalized rewriting tactic is based on a set of strategies that -can be combined to obtain custom rewriting procedures. Its set of -strategies is based on Elan’s rewriting strategies :ref:`TODO-102-biblio`. Rewriting +The generalized rewriting tactic is based on a set of strategies that can be +combined to obtain custom rewriting procedures. Its set of strategies is based +on Elan’s rewriting strategies :cite:`Luttik97specificationof`. Rewriting strategies are applied using the tactic ``rewrite_strat s`` where ``s`` is a -strategy expression. Strategies are defined inductively as described -by the following grammar: +strategy expression. Strategies are defined inductively as described by the +following grammar: .. productionlist:: rewriting s, t, u : `strategy` @@ -812,7 +808,7 @@ Hint databases created for ``autorewrite`` can also be used by ``rewrite_strat`` using the ``hints`` strategy that applies any of the lemmas at the current subterm. The ``terms`` strategy takes the lemma names directly as arguments. The ``eval`` strategy expects a reduction -expression (see :ref:`TODO-8.7-performing-computations`) and succeeds +expression (see :ref:`performingcomputations`) and succeeds if it reduces the subterm under consideration. The ``fold`` strategy takes a term ``c`` and tries to *unify* it to the current subterm, converting it to ``c`` on success, it is stronger than the tactic ``fold``. diff --git a/doc/sphinx/addendum/implicit-coercions.rst b/doc/sphinx/addendum/implicit-coercions.rst index f5ca5be44a..ec1b942e02 100644 --- a/doc/sphinx/addendum/implicit-coercions.rst +++ b/doc/sphinx/addendum/implicit-coercions.rst @@ -1,7 +1,7 @@ -.. _implicitcoercions: - .. include:: ../replaces.rst +.. _implicitcoercions: + Implicit Coercions ==================== @@ -166,7 +166,7 @@ Declaration of Coercions Assumptions can be declared as coercions at declaration time. This extends the grammar of assumptions from -Figure :ref:`TODO-1.3-sentences-syntax` as follows: +Figure :ref:`vernacular` as follows: .. FIXME: @@ -186,7 +186,7 @@ assumptions are declared as coercions. Similarly, constructors of inductive types can be declared as coercions at definition time of the inductive type. This extends and modifies the -grammar of inductive types from Figure :ref:`TODO-1.3-sentences-syntax` as follows: +grammar of inductive types from Figure :ref:`vernacular` as follows: .. FIXME: @@ -267,29 +267,29 @@ Activating the Printing of Coercions To skip the printing of coercion `qualid`, use ``Remove Printing Coercion`` `qualid`. By default, a coercion is never printed. +.. _coercions-classes-as-records: Classes as Records ------------------ -We allow the definition of *Structures with Inheritance* (or -classes as records) by extending the existing ``Record`` macro -(see Section :ref:`TODO-2.1-Record`). Its new syntax is: - -.. cmd:: Record {? >} @ident {? @binders} : @sort := {? @ident} { {+; @ident :{? >} @term } }. - - The first identifier `ident` is the name of the defined record and - `sort` is its type. The optional identifier after ``:=`` is the name - of the constuctor (it will be ``Build_``\ `ident` if not given). - The other identifiers are the names of the fields, and the `term` - are their respective types. If ``:>`` is used instead of ``:`` in - the declaration of a field, then the name of this field is automatically - declared as a coercion from the record name to the class of this - field type. Remark that the fields always verify the uniform - inheritance condition. If the optional ``>`` is given before the - record name, then the constructor name is automatically declared as - a coercion from the class of the last field type to the record name - (this may fail if the uniform inheritance condition is not - satisfied). +We allow the definition of *Structures with Inheritance* (or classes as records) +by extending the existing :cmd:`Record` macro. Its new syntax is: + +.. cmdv:: Record {? >} @ident {? @binders} : @sort := {? @ident} { {+; @ident :{? >} @term } }. + + The first identifier `ident` is the name of the defined record and + `sort` is its type. The optional identifier after ``:=`` is the name + of the constuctor (it will be ``Build_``\ `ident` if not given). + The other identifiers are the names of the fields, and the `term` + are their respective types. If ``:>`` is used instead of ``:`` in + the declaration of a field, then the name of this field is automatically + declared as a coercion from the record name to the class of this + field type. Remark that the fields always verify the uniform + inheritance condition. If the optional ``>`` is given before the + record name, then the constructor name is automatically declared as + a coercion from the class of the last field type to the record name + (this may fail if the uniform inheritance condition is not + satisfied). .. note:: diff --git a/doc/sphinx/addendum/miscellaneous-extensions.rst b/doc/sphinx/addendum/miscellaneous-extensions.rst index 3ed4ce7625..80ea8a1166 100644 --- a/doc/sphinx/addendum/miscellaneous-extensions.rst +++ b/doc/sphinx/addendum/miscellaneous-extensions.rst @@ -3,15 +3,10 @@ .. _miscellaneousextensions: Miscellaneous extensions -======================= - -.. contents:: - :local: - :depth: 1 ----- +======================== Program derivation ------------------ +------------------ |Coq| comes with an extension called ``Derive``, which supports program derivation. Typically in the style of Bird and Meertens or derivations @@ -25,7 +20,7 @@ The first `ident` can appear in `term`. This command opens a new proof presenting the user with a goal for term in which the name `ident` is bound to an existential variable `?x` (formally, there are other goals standing for the existential variables but they are shelved, as -described in Section :ref:`TODO-8.17.4`). +described in :tacn:`shelve`). When the proof ends two constants are defined: diff --git a/doc/sphinx/addendum/nsatz.rst b/doc/sphinx/addendum/nsatz.rst index ef9b3505d4..387d614956 100644 --- a/doc/sphinx/addendum/nsatz.rst +++ b/doc/sphinx/addendum/nsatz.rst @@ -19,7 +19,7 @@ where :math:`P, Q, P₁,Q₁,\ldots,Pₛ, Qₛ` are polynomials and :math:`A` is domain, i.e. a commutative ring with no zero divisor. For example, :math:`A` can be :math:`\mathbb{R}`, :math:`\mathbb{Z}`, or :math:`\mathbb{Q}`. Note that the equality :math:`=` used in these goals can be -any setoid equality (see :ref:`TODO-27.2.2`) , not only Leibnitz equality. +any setoid equality (see :ref:`tactics-enabled-on-user-provided-relations`) , not only Leibnitz equality. It also proves formulas diff --git a/doc/sphinx/addendum/parallel-proof-processing.rst b/doc/sphinx/addendum/parallel-proof-processing.rst index 8c1b9d152b..edb8676a5b 100644 --- a/doc/sphinx/addendum/parallel-proof-processing.rst +++ b/doc/sphinx/addendum/parallel-proof-processing.rst @@ -39,14 +39,14 @@ Proof annotations To process a proof asynchronously |Coq| needs to know the precise statement of the theorem without looking at the proof. This requires some annotations if the theorem is proved inside a Section (see -Section :ref:`TODO-2.4`). +Section :ref:`section-mechanism`). When a section ends, |Coq| looks at the proof object to decide which section variables are actually used and hence have to be quantified in the statement of the theorem. To avoid making the construction of proofs mandatory when ending a section, one can start each proof with -the ``Proof using`` command (Section :ref:`TODO-7.1.5`) that declares which section -variables the theorem uses. +the ``Proof using`` command (Section :ref:`proof-editing-mode`) that +declares which section variables the theorem uses. The presence of ``Proof`` using is needed to process proofs asynchronously in interactive mode. diff --git a/doc/sphinx/addendum/program.rst b/doc/sphinx/addendum/program.rst index eb50e52dc7..1c3fdeb430 100644 --- a/doc/sphinx/addendum/program.rst +++ b/doc/sphinx/addendum/program.rst @@ -135,7 +135,7 @@ support types, avoiding uses of proof-irrelevance that would come up when reasoning with equality on the subset types themselves. The next two commands are similar to their standard counterparts -Definition (see Section `TODO-1.3.2-Definition`_) and Fixpoint (see Section `TODO-1.3.4-Fixpoint`_) +:cmd:`Definition` and :cmd:`Fixpoint` in that they define constants. However, they may require the user to prove some goals to construct the final definitions. @@ -174,7 +174,7 @@ Program Definition .. TODO refer to production in alias -See also: Sections `TODO-6.10.1-Opaque`_, `TODO-6.10.2-Transparent`_, `TODO-8.7.5-unfold`_ +See also: Sections :ref:`vernac-controlling-the-reduction-strategies`, :tacn:`unfold` .. _program_fixpoint: @@ -196,7 +196,7 @@ The optional order annotation follows the grammar: + :g:`wf R x` which is equivalent to :g:`measure x (R)`. The structural fixpoint operator behaves just like the one of |Coq| (see -Section `TODO-1.3.4-Fixpoint`_), except it may also generate obligations. It works +:cmd:`Fixpoint`), except it may also generate obligations. It works with mutually recursive definitions too. .. coqtop:: reset none diff --git a/doc/sphinx/addendum/ring.rst b/doc/sphinx/addendum/ring.rst index b861892cbb..ae666a0d45 100644 --- a/doc/sphinx/addendum/ring.rst +++ b/doc/sphinx/addendum/ring.rst @@ -701,7 +701,7 @@ for |Coq|’s type-checker. Let us see why: At each step of rewriting, the whole context is duplicated in the proof term. Then, a tactic that does hundreds of rewriting generates huge proof terms. Since ``ACDSimpl`` was too slow, Samuel Boutin rewrote -it using reflection (see his article in TACS’97 [Bou97]_). Later, it +it using reflection (see :cite:`Bou97`). Later, it was rewritten by Patrick Loiseleur: the new tactic does not any more require ``ACDSimpl`` to compile and it makes use of |bdi|-reduction not only to replace the rewriting steps, but also to achieve the diff --git a/doc/sphinx/addendum/type-classes.rst b/doc/sphinx/addendum/type-classes.rst index 5518da9acc..8861cac8af 100644 --- a/doc/sphinx/addendum/type-classes.rst +++ b/doc/sphinx/addendum/type-classes.rst @@ -148,11 +148,10 @@ database. Sections and contexts --------------------- -To ease the parametrization of developments by type classes, we -provide a new way to introduce variables into section contexts, -compatible with the implicit argument mechanism. The new command works -similarly to the ``Variables`` vernacular (:ref:`TODO-1.3.2-Definitions`), except it -accepts any binding context as argument. For example: +To ease the parametrization of developments by type classes, we provide a new +way to introduce variables into section contexts, compatible with the implicit +argument mechanism. The new command works similarly to the :cmd:`Variables` +vernacular, except it accepts any binding context as argument. For example: .. coqtop:: all @@ -333,7 +332,7 @@ Variants: .. cmd:: Program Instance - Switches the type-checking to Program (chapter :ref:`program`) and + Switches the type-checking to Program (chapter :ref:`programs`) and uses the obligation mechanism to manage missing fields. .. cmd:: Declare Instance diff --git a/doc/sphinx/biblio.bib b/doc/sphinx/biblio.bib index 247f32103c..ef50923c72 100644 --- a/doc/sphinx/biblio.bib +++ b/doc/sphinx/biblio.bib @@ -675,7 +675,6 @@ s}, author = {G. Huet}, booktitle = {A perspective in Theoretical Computer Science. Commemorative Volume for Gift Siromoney}, editor = {R. Narasimhan}, - note = {Also in~\cite{CoC89}}, publisher = {World Scientific Publishing}, title = {{The Constructive Engine}}, year = {1989} @@ -815,11 +814,12 @@ of the {ML} language}, } @inproceedings{Luttik97specificationof, - Author = {Sebastiaan P. Luttik and Eelco Visser}, - Booktitle = {2nd International Workshop on the Theory and Practice of Algebraic Specifications (ASF+SDF'97), Electronic Workshops in Computing}, - Publisher = {Springer-Verlag}, - Title = {Specification of Rewriting Strategies}, - Year = {1997}} + author = {Sebastiaan P. Luttik and Eelco Visser}, + booktitle = {2nd International Workshop on the Theory and Practice of Algebraic Specifications (ASF+SDF'97), Electronic Workshops in Computing}, + publisher = {Springer-Verlag}, + title = {Specification of Rewriting Strategies}, + year = {1997} +} @Book{MaL84, author = {{P. Martin-L\"of}}, diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst index 67de2ae68e..4a313df0ce 100644 --- a/doc/sphinx/introduction.rst +++ b/doc/sphinx/introduction.rst @@ -60,7 +60,7 @@ continuous reading. However, it has some structure that is explained below. - The first part describes the specification language, |Gallina|. - Chapters :ref:`thegallinaspecificationlanguage` and :ref:`extensionsofgallina` describe the concrete + Chapters :ref:`gallinaspecificationlanguage` and :ref:`extensionsofgallina` describe the concrete syntax as well as the meaning of programs, theorems and proofs in the Calculus of Inductive Constructions. Chapter :ref:`thecoqlibrary` describes the standard library of |Coq|. Chapter :ref:`calculusofinductiveconstructions` is a mathematical description @@ -76,7 +76,7 @@ below. Chapter :ref:`proofhandling`. In Chapter :ref:`tactics`, all commands that realize one or more steps of the proof are presented: we call them *tactics*. The language to combine these tactics into complex proof - strategies is given in Chapter :ref:`thetacticlanguage`. Examples of tactics + strategies is given in Chapter :ref:`ltac`. Examples of tactics are described in Chapter :ref:`detailedexamplesoftactics`. - The third part describes how to extend the syntax of |Coq|. It diff --git a/doc/sphinx/language/cic.rst b/doc/sphinx/language/cic.rst index 13d20d7cf1..5a2aa0a1f8 100644 --- a/doc/sphinx/language/cic.rst +++ b/doc/sphinx/language/cic.rst @@ -97,7 +97,7 @@ ensure the existence of a mapping of the universes to the positive integers, the graph of constraints must remain acyclic. Typing expressions that violate the acyclicity of the graph of constraints results in a Universe inconsistency error (see also Section -:ref:`TODO-2.10`). +:ref:`printing-universes`). .. _Terms: @@ -401,9 +401,11 @@ can decide if two programs are *intentionally* equal (one says *convertible*). Convertibility is described in this section. -.. _β-reduction: +.. _beta-reduction: + +β-reduction +~~~~~~~~~~~ -**β-reduction.** We want to be able to identify some terms as we can identify the application of a function to a given argument with its result. For instance the identity function over a given type T can be written @@ -427,9 +429,11 @@ theoretically of great importance but we will not detail them here and refer the interested reader to :cite:`Coq85`. -.. _ι-reduction: +.. _iota-reduction: + +ι-reduction +~~~~~~~~~~~ -**ι-reduction.** A specific conversion rule is associated to the inductive objects in the global environment. We shall give later on (see Section :ref:`Well-formed-inductive-definitions`) the precise rules but it @@ -438,9 +442,11 @@ constructor behaves as expected. This reduction is called ι-reduction and is more precisely studied in :cite:`Moh93,Wer94`. -.. _δ-reduction: +.. _delta-reduction: + +δ-reduction +~~~~~~~~~~~ -**δ-reduction.** We may have variables defined in local contexts or constants defined in the global environment. It is legal to identify such a reference with its value, that is to expand (or unfold) it into its value. This @@ -461,9 +467,11 @@ reduction is called δ-reduction and shows as follows. E[Γ] ⊢ c~\triangleright_δ~t -.. _ζ-reduction: +.. _zeta-reduction: + +ζ-reduction +~~~~~~~~~~~ -**ζ-reduction.** |Coq| allows also to remove local definitions occurring in terms by replacing the defined variable by its value. The declaration being destroyed, this reduction differs from δ-reduction. It is called @@ -478,9 +486,11 @@ destroyed, this reduction differs from δ-reduction. It is called E[Γ] ⊢ \letin{x}{u}{t}~\triangleright_ζ~\subst{t}{x}{u} -.. _η-expansion: +.. _eta-expansion: + +η-expansion +~~~~~~~~~~~ -**η-expansion.** Another important concept is η-expansion. It is legal to identify any term :math:`t` of functional type :math:`∀ x:T, U` with its so-called η-expansion @@ -517,9 +527,11 @@ for :math:`x` an arbitrary variable name fresh in :math:`t`. convertible to the type of the original term :math:`∀ x:\Type(1),\Type(1).` -.. _Convertibility: +.. _convertibility: + +Convertibility +~~~~~~~~~~~~~~ -**Convertibility.** Let us write :math:`E[Γ] ⊢ t \triangleright u` for the contextual closure of the relation :math:`t` reduces to :math:`u` in the global environment :math:`E` and local context :math:`Γ` with one of the previous @@ -709,8 +721,6 @@ called the *context of parameters*. Furthermore, we must have that each :math:`T` in :math:`(t:T)∈Γ_I` can be written as: :math:`∀Γ_P,∀Γ_{\mathit{Arr}(t)}, S` where :math:`Γ_{\mathit{Arr}(t)}` is called the *Arity* of the inductive type t and :math:`S` is called the sort of the inductive type t (not to be confused with :math:`\Sort` which is the set of sorts). - - ** Examples** The declaration for parameterized lists is: .. math:: @@ -825,8 +835,9 @@ to inconsistent systems. We restrict ourselves to definitions which satisfy a syntactic criterion of positivity. Before giving the formal rules, we need a few definitions: +Arity of a given sort ++++++++++++++++++++++ -**Type is an Arity of Sort S.** A type :math:`T` is an *arity of sort s* if it converts to the sort s or to a product :math:`∀ x:T,U` with :math:`U` an arity of sort s. @@ -836,7 +847,8 @@ product :math:`∀ x:T,U` with :math:`U` an arity of sort s. :math:`\Prop`. -**Type is an Arity.** +Arity ++++++ A type :math:`T` is an *arity* if there is a :math:`s∈ \Sort` such that :math:`T` is an arity of sort s. @@ -846,32 +858,34 @@ sort s. :math:`A→ Set` and :math:`∀ A:\Prop,A→ \Prop` are arities. -**Type of Constructor of I.** +Type constructor +++++++++++++++++ We say that T is a *type of constructor of I* in one of the following two cases: - + :math:`T` is :math:`(I~t_1 … t_n )` + :math:`T` is :math:`∀ x:U,T'` where :math:`T'` is also a type of constructor of :math:`I` - - .. example:: :math:`\nat` and :math:`\nat→\nat` are types of constructor of :math:`\nat`. :math:`∀ A:Type,\List~A` and :math:`∀ A:Type,A→\List~A→\List~A` are types of constructor of :math:`\List`. -**Positivity Condition.** +.. _positivity: + +Positivity Condition +++++++++++++++++++++ + The type of constructor :math:`T` will be said to *satisfy the positivity condition* for a constant :math:`X` in the following cases: - + :math:`T=(X~t_1 … t_n )` and :math:`X` does not occur free in any :math:`t_i` + :math:`T=∀ x:U,V` and :math:`X` occurs only strictly positively in :math:`U` and the type :math:`V` satisfies the positivity condition for :math:`X`. - -**Occurs Strictly Positively.** +Strict positivity ++++++++++++++++++ + The constant :math:`X` *occurs strictly positively* in :math:`T` in the following cases: @@ -891,11 +905,12 @@ cases: any of the :math:`t_i`, and the (instantiated) types of constructor :math:`\subst{C_i}{p_j}{a_j}_{j=1… m}` of :math:`I` satisfy the nested positivity condition for :math:`X` -**Nested Positivity Condition.** +Nested Positivity ++++++++++++++++++ + The type of constructor :math:`T` of :math:`I` *satisfies the nested positivity condition* for a constant :math:`X` in the following cases: - + :math:`T=(I~b_1 … b_m~u_1 … u_p)`, :math:`I` is an inductive definition with :math:`m` parameters and :math:`X` does not occur in any :math:`u_i` + :math:`T=∀ x:U,V` and :math:`X` occurs only strictly positively in :math:`U` and the type :math:`V` @@ -942,12 +957,11 @@ For instance, if one considers the type │ ╰─ list satisfies the positivity condition for list A ... (bullet 1) - - - .. _Correctness-rules: -**Correctness rules.** +Correctness rules ++++++++++++++++++ + We shall now describe the rules allowing the introduction of a new inductive definition. @@ -1014,7 +1028,9 @@ has type :math:`\Type(k)` with :math:`k<j` and :math:`k≤ i`. .. _Template-polymorphism: -**Template polymorphism.** +Template polymorphism ++++++++++++++++++++++ + Inductive types declared in Type are polymorphic over their arguments in Type. If :math:`A` is an arity of some sort and s is a sort, we write :math:`A_{/s}` for the arity obtained from :math:`A` by replacing its sort with s. @@ -1058,7 +1074,7 @@ provided that the following side conditions hold: we have :math:`(E[Γ_{I′} ;Γ_{P′}] ⊢ C_i : s_{q_i})_{i=1… n}` ; + the sorts :math:`s_i` are such that all eliminations, to :math:`\Prop`, :math:`\Set` and :math:`\Type(j)`, are allowed - (see Section Destructors_). + (see Section :ref:`Destructors`). @@ -1088,14 +1104,14 @@ The sorts :math:`s_j` are chosen canonically so that each :math:`s_j` is minimal respect to the hierarchy :math:`\Prop ⊂ \Set_p ⊂ \Type` where :math:`\Set_p` is predicative :math:`\Set`. More precisely, an empty or small singleton inductive definition (i.e. an inductive definition of which all inductive types are -singleton – see paragraph Destructors_) is set in :math:`\Prop`, a small non-singleton +singleton – see Section :ref:`Destructors`) is set in :math:`\Prop`, a small non-singleton inductive type is set in :math:`\Set` (even in case :math:`\Set` is impredicative – see Section The-Calculus-of-Inductive-Construction-with-impredicative-Set_), and otherwise in the Type hierarchy. Note that the side-condition about allowed elimination sorts in the rule **Ind-Family** is just to avoid to recompute the allowed elimination -sorts at each instance of a pattern-matching (see section Destructors_). As +sorts at each instance of a pattern-matching (see Section :ref:`Destructors`). As an example, let us consider the following definition: .. example:: @@ -1111,7 +1127,7 @@ in the Type hierarchy. Here, the parameter :math:`A` has this property, hence, if :g:`option` is applied to a type in :math:`\Set`, the result is in :math:`\Set`. Note that if :g:`option` is applied to a type in :math:`\Prop`, then, the result is not set in :math:`\Prop` but in :math:`\Set` still. This is because :g:`option` is not a singleton type -(see section Destructors_) and it would lose the elimination to :math:`\Set` and :math:`\Type` +(see Section :ref:`Destructors`) and it would lose the elimination to :math:`\Set` and :math:`\Type` if set in :math:`\Prop`. .. example:: @@ -1219,9 +1235,11 @@ Coquand in :cite:`Coq92`. One is the definition by pattern-matching. The second one is a definition by guarded fixpoints. -.. _The-match…with-end-construction: +.. _match-construction: + +The match ... with ... end construction ++++++++++++++++++++++++++++++++++++++++ -**The match…with …end construction** The basic idea of this operator is that we have an object :math:`m` in an inductive type :math:`I` and we want to prove a property which possibly depends on :math:`m`. For this, it is enough to prove the property for @@ -1278,7 +1296,7 @@ and :math:`I:A` and :math:`λ a x . P : B` then by :math:`[I:A|B]` we mean that :math:`λ a x . P` with :math:`m` in the above match-construct. -.. _Notations: +.. _cic_notations: **Notations.** The :math:`[I:A|B]` is defined as the smallest relation satisfying the following rules: We write :math:`[I|B]` for :math:`[I:A|B]` where :math:`A` is the type of :math:`I`. @@ -1625,9 +1643,8 @@ Given a variable :math:`y` of type an inductive definition in a declaration ones in which one of the :math:`I_l` occurs) are structurally smaller than y. -The following definitions are correct, we enter them using the ``Fixpoint`` -command as described in Section :ref:`TODO-1.3.4` and show the internal -representation. +The following definitions are correct, we enter them using the :cmd:`Fixpoint` +command and show the internal representation. .. example:: .. coqtop:: all @@ -1684,7 +1701,7 @@ possible: **Mutual induction** The principles of mutual induction can be automatically generated -using the Scheme command described in Section :ref:`TODO-13.1`. +using the Scheme command described in Section :ref:`proofschemes-induction-principles`. .. _Admissible-rules-for-global-environments: diff --git a/doc/sphinx/language/coq-library.rst b/doc/sphinx/language/coq-library.rst index 82ced65b4a..6af6e78972 100644 --- a/doc/sphinx/language/coq-library.rst +++ b/doc/sphinx/language/coq-library.rst @@ -19,7 +19,7 @@ The |Coq| library is structured into two parts: developments of |Coq| axiomatizations about sets, lists, sorting, arithmetic, etc. This library comes with the system and its modules are directly accessible through the ``Require`` command (see - Section :ref:`TODO-6.5.1-Require`); + Section :ref:`compiled-files`); In addition, user-provided libraries or developments are provided by |Coq| users' community. These libraries and developments are available @@ -48,6 +48,7 @@ at the |Coq| root directory; this includes the modules ``Tactics``. Module ``Logic_Type`` also makes it in the initial state. +.. _init-notations: Notations ~~~~~~~~~ @@ -90,6 +91,8 @@ Notation Precedence Associativity ``_ ^ _`` 30 right ================ ============ =============== +.. _coq-library-logic: + Logic ~~~~~ @@ -521,7 +524,7 @@ provides a scope ``nat_scope`` gathering standard notations for common operations (``+``, ``*``) and a decimal notation for numbers, allowing for instance to write ``3`` for :g:`S (S (S O)))`. This also works on the left hand side of a ``match`` expression (see for example -section :ref:`TODO-refine-example`). This scope is opened by default. +section :tacn:`refine`). This scope is opened by default. .. example:: @@ -753,7 +756,7 @@ subdirectories: These directories belong to the initial load path of the system, and the modules they provide are compiled at installation time. So they are directly accessible with the command ``Require`` (see -Section :ref:`TODO-6.5.1-Require`). +Section :ref:`compiled-files`). The different modules of the |Coq| standard library are documented online at http://coq.inria.fr/stdlib. @@ -927,9 +930,8 @@ tactics (see Chapter :ref:`tactics`), there are also: Goal forall x y z:R, x * y * z <> 0. intros; split_Rmult. -These tactics has been written with the tactic language Ltac -described in Chapter :ref:`thetacticlanguage`. - +These tactics has been written with the tactic language |Ltac| +described in Chapter :ref:`ltac`. List library ~~~~~~~~~~~~ diff --git a/doc/sphinx/language/gallina-extensions.rst b/doc/sphinx/language/gallina-extensions.rst index 6877759806..f474eade71 100644 --- a/doc/sphinx/language/gallina-extensions.rst +++ b/doc/sphinx/language/gallina-extensions.rst @@ -183,7 +183,7 @@ other arguments are the parameters of the inductive type. .. note:: Induction schemes are automatically generated for inductive records. Automatic generation of induction schemes for non-recursive records defined with the ``Record`` keyword can be activated with the - ``Nonrecursive Elimination Schemes`` option (see :ref:`TODO-13.1.1-nonrecursive-elimination-schemes`). + ``Nonrecursive Elimination Schemes`` option (see :ref:`proofschemes-induction-principles`). .. note:: ``Structure`` is a synonym of the keyword ``Record``. @@ -193,9 +193,9 @@ other arguments are the parameters of the inductive type. This message is followed by an explanation of this impossibility. There may be three reasons: - #. The name `ident` already exists in the environment (see Section :ref:`TODO-1.3.1-axioms`). + #. The name `ident` already exists in the environment (see :cmd:`Axiom`). #. The body of `ident` uses an incorrect elimination for - `ident` (see Sections :ref:`TODO-1.3.4-fixpoint` and :ref:`TODO-4.5.3-case-expr`). + `ident` (see :cmd:`Fixpoint` and :ref:`Destructors`). #. The type of the projections `ident` depends on previous projections which themselves could not be defined. @@ -212,9 +212,9 @@ other arguments are the parameters of the inductive type. During the definition of the one-constructor inductive definition, all the errors of inductive definitions, as described in Section -:ref:`TODO-1.3.3-inductive-definitions`, may also occur. +:ref:`gallina-inductive-definitions`, may also occur. -**See also** Coercions and records in Section :ref:`TODO-18.9-coercions-and-records` of the chapter devoted to coercions. +**See also** Coercions and records in Section :ref:`coercions-classes-as-records` of the chapter devoted to coercions. .. _primitive_projections: @@ -316,7 +316,7 @@ printed back as :g:`match` constructs. Variants and extensions of :g:`match` ------------------------------------- -.. _extended pattern-matching: +.. _mult-match: Multiple and nested pattern-matching ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -330,8 +330,9 @@ into a sequence of match on simple patterns. Especially, a construction defined using the extended match is generally printed under its expanded form (see ``Set Printing Matching`` in :ref:`controlling-match-pp`). -See also: :ref:`extended pattern-matching`. +See also: :ref:`extendedpatternmatching`. +.. _if-then-else: Pattern-matching on boolean values: the if expression ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -626,7 +627,7 @@ The following experimental command is available when the ``FunInd`` library has This command can be seen as a generalization of ``Fixpoint``. It is actually a wrapper for several ways of defining a function *and other useful related objects*, namely: an induction principle that reflects the recursive -structure of the function (see Section :ref:`TODO-8.5.5-functional-induction`) and its fixpoint equality. +structure of the function (see :tacn:`function induction`) and its fixpoint equality. The meaning of this declaration is to define a function ident, similarly to ``Fixpoint`. Like in ``Fixpoint``, the decreasing argument must be given (unless the function is not recursive), but it might not @@ -639,8 +640,8 @@ The ``Function`` construction also enjoys the ``with`` extension to define mutually recursive definitions. However, this feature does not work for non structurally recursive functions. -See the documentation of functional induction (:ref:`TODO-8.5.5-functional-induction`) -and ``Functional Scheme`` (:ref:`TODO-13.2-functional-scheme`) for how to use +See the documentation of functional induction (:tacn:`function induction`) +and ``Functional Scheme`` (:ref:`functional-scheme`) for how to use the induction principle to easily reason about the function. Remark: To obtain the right principle, it is better to put rigid @@ -711,7 +712,7 @@ terminating functions. `functional inversion` will not be available for the function. -See also: :ref:`TODO-13.2-generating-ind-principles` and ref:`TODO-8.5.5-functional-induction` +See also: :ref:`functional-scheme` and :tacn:`function induction` Depending on the ``{…}`` annotation, different definition mechanisms are used by ``Function``. A more precise description is given below. @@ -722,7 +723,7 @@ used by ``Function``. A more precise description is given below. the following are defined: + `ident_rect`, `ident_rec` and `ident_ind`, which reflect the pattern - matching structure of `term` (see the documentation of :ref:`TODO-1.3.3-Inductive`); + matching structure of `term` (see :cmd:`Inductive`); + The inductive `R_ident` corresponding to the graph of `ident` (silently); + `ident_complete` and `ident_correct` which are inversion information linking the function and its graph. @@ -771,13 +772,14 @@ used by ``Function``. A more precise description is given below. hand. Remark: Proof obligations are presented as several subgoals belonging to a Lemma `ident`\ :math:`_{\sf tcc}`. +.. _section-mechanism: Section mechanism ----------------- The sectioning mechanism can be used to to organize a proof in structured sections. Then local declarations become available (see -Section :ref:`TODO-1.3.2-Definitions`). +Section :ref:`gallina-definitions`). .. cmd:: Section @ident. @@ -847,7 +849,7 @@ together, as well as a means of massive abstraction. In the syntax of module application, the ! prefix indicates that any `Inline` directive in the type of the functor arguments will be ignored -(see :ref:`named_module_type` below). +(see the ``Module Type`` command below). .. cmd:: Module @ident. @@ -933,8 +935,6 @@ Reserved commands inside an interactive module is equivalent to an interactive module where each `module_expression` is included. -.. _named_module_type: - .. cmd:: Module Type @ident. This command is used to start an interactive module type `ident`. @@ -1195,7 +1195,7 @@ component is equal ``nat`` and hence ``M1.T`` as specified. Check T. Some features defined in modules are activated only when a module is -imported. This is for instance the case of notations (see :ref:`TODO-12.1-Notations`). +imported. This is for instance the case of notations (see :ref:`Notations`). Declarations made with the Local flag are never imported by theImport command. Such declarations are only accessible through their fully @@ -1241,13 +1241,11 @@ qualified name. This option (off by default) disables the printing of the types of fields, leaving only their names, for the commands ``Print Module`` and ``Print Module Type``. -.. cmd:: Locate Module @qualid. - - Prints the full name of the module `qualid`. - Libraries and qualified names --------------------------------- +.. _names-of-libraries: + Names of libraries ~~~~~~~~~~~~~~~~~~ @@ -1255,15 +1253,16 @@ The theories developed in |Coq| are stored in *library files* which are hierarchically classified into *libraries* and *sublibraries*. To express this hierarchy, library names are represented by qualified identifiers qualid, i.e. as list of identifiers separated by dots (see -:ref:`TODO-1.2.3-identifiers`). For instance, the library file ``Mult`` of the standard +:ref:`gallina-identifiers`). For instance, the library file ``Mult`` of the standard |Coq| library ``Arith`` is named ``Coq.Arith.Mult``. The identifier that starts the name of a library is called a *library root*. All library files of the standard library of |Coq| have the reserved root |Coq| but library file names based on other roots can be obtained by using |Coq| commands -(coqc, coqtop, coqdep, …) options ``-Q`` or ``-R`` (see :ref:`TODO-14.3.3-command-line-options`). +(coqc, coqtop, coqdep, …) options ``-Q`` or ``-R`` (see :ref:`command-line-options`). Also, when an interactive |Coq| session starts, a library of root ``Top`` is -started, unless option ``-top`` or ``-notop`` is set (see :ref:`TODO-14.3.3-command-line-options`). +started, unless option ``-top`` or ``-notop`` is set (see :ref:`command-line-options`). +.. _qualified-names: Qualified names ~~~~~~~~~~~~~~~ @@ -1298,13 +1297,13 @@ names also applies to library file names. |Coq| maintains a table called the name table which maps partially qualified names of constructions to absolute names. This table is updated by the -commands ``Require`` (see :ref:`TODO-6.5.1-Require`), Import and Export (see :ref:`import_qualid`) and +commands :cmd:`Require`, :cmd:`Import` and :cmd:`Export` and also each time a new declaration is added to the context. An absolute name is called visible from a given short or partially qualified name when this latter name is enough to denote it. This means that the short or partially qualified name is mapped to the absolute name in |Coq| name table. Definitions flagged as Local are only accessible with -their fully qualified name (see :ref:`TODO-1.3.2-definitions`). +their fully qualified name (see :ref:`gallina-definitions`). It may happen that a visible name is hidden by the short name or a qualified name of another construction. In this case, the name that @@ -1326,16 +1325,15 @@ accessible, absolute names can never be hidden. Locate nat. -See also: Command Locate in :ref:`TODO-6.3.10-locate-qualid` and Locate Library in -:ref:`TODO-6.6.11-locate-library`. +See also: Commands :cmd:`Locate` and :cmd:`Locate Library`. +.. _libraries-and-filesystem: Libraries and filesystem ~~~~~~~~~~~~~~~~~~~~~~~~ -Please note that the questions described here have been subject to -redesign in |Coq| v8.5. Former versions of |Coq| use the same terminology -to describe slightly different things. +.. note:: The questions described here have been subject to redesign in |Coq| 8.5. + Former versions of |Coq| use the same terminology to describe slightly different things. Compiled files (``.vo`` and ``.vio``) store sub-libraries. In order to refer to them inside |Coq|, a translation from file-system names to |Coq| names @@ -1371,7 +1369,7 @@ translation and with an empty logical prefix. The command line option ``-R`` is a variant of ``-Q`` which has the strictly same behavior regarding loadpaths, but which also makes the corresponding ``.vo`` files available through their short names in a way -not unlike the ``Import`` command (see :ref:`import_qualid`). For instance, ``-R`` `path` ``Lib`` +not unlike the ``Import`` command (see :ref:`here <import_qualid>`). For instance, ``-R`` `path` ``Lib`` associates to the ``filepath/fOO/Bar/File.vo`` the logical name ``Lib.fOO.Bar.File``, but allows this file to be accessed through the short names ``fOO.Bar.File,Bar.File`` and ``File``. If several files with @@ -1379,7 +1377,7 @@ identical base name are present in different subdirectories of a recursive loadpath, which of these files is found first may be system- dependent and explicit qualification is recommended. The ``From`` argument of the ``Require`` command can be used to bypass the implicit shortening -by providing an absolute root to the required file (see :ref:`TODO-6.5.1-require-qualid`). +by providing an absolute root to the required file (see :ref:`compiled-files`). There also exists another independent loadpath mechanism attached to OCaml object files (``.cmo`` or ``.cmxs``) rather than |Coq| object @@ -1387,11 +1385,12 @@ files as described above. The OCaml loadpath is managed using the option ``-I`` `path` (in the OCaml world, there is neither a notion of logical name prefix nor a way to access files in subdirectories of path). See the command ``Declare`` ``ML`` ``Module`` in -:ref:`TODO-6.5-compiled-files` to understand the need of the OCaml loadpath. +:ref:`compiled-files` to understand the need of the OCaml loadpath. -See :ref:`TODO-14.3.3-command-line-options` for a more general view over the |Coq| command +See :ref:`command-line-options` for a more general view over the |Coq| command line options. +.. _ImplicitArguments: Implicit arguments ------------------ @@ -1586,6 +1585,7 @@ Declaring Implicit Arguments To set implicit arguments *a posteriori*, one can use the command: .. cmd:: Arguments @qualid {* @possibly_bracketed_ident }. + :name: Arguments (implicits) where the list of `possibly_bracketed_ident` is a prefix of the list of arguments of `qualid` where the ones to be declared implicit are @@ -1799,6 +1799,8 @@ declares implicit arguments to be automatically inserted when a function is partially applied and the next argument of the function is an implicit one. +.. _explicit-applications: + Explicit applications ~~~~~~~~~~~~~~~~~~~~~ @@ -2098,6 +2100,7 @@ implicitly, as maximally-inserted arguments. In these binders, the binding name for the bound object is optional, whereas the type is mandatory, dually to regular binders. +.. _Coercions: Coercions --------- @@ -2136,21 +2139,24 @@ Otherwise said, ``Set Printing All`` includes the effects of the commands ``Unset Printing Projections``, and ``Unset Printing Notations``. To reactivate the high-level printing features, use the command ``Unset Printing All``. +.. _printing-universes: + Printing universes ------------------ .. opt:: Printing Universes. -Turn this option on to activate the display of the actual level of each occurrence of ``Type``. -See :ref:`TODO-4.1.1-sorts` for details. This wizard option, in combination -with ``Set Printing All`` (see :ref:`printing_constructions_full`) can help to diagnose failures -to unify terms apparently identical but internally different in the -Calculus of Inductive Constructions. +Turn this option on to activate the display of the actual level of each +occurrence of :g:`Type`. See :ref:`Sorts` for details. This wizard option, in +combination with :opt:`Printing All` can help to diagnose failures to unify +terms apparently identical but internally different in the Calculus of Inductive +Constructions. The constraints on the internal level of the occurrences of Type -(see :ref:`TODO-4.1.1-sorts`) can be printed using the command +(see :ref:`Sorts`) can be printed using the command .. cmd:: Print {? Sorted} Universes. + :name: Print Universes If the optional ``Sorted`` option is given, each universe will be made equivalent to a numbered label reflecting its level (with a linear @@ -2158,12 +2164,13 @@ ordering) in the universe hierarchy. This command also accepts an optional output filename: -.. cmd:: Print {? Sorted} Universes @string. +.. cmdv:: Print {? Sorted} Universes @string. If `string` ends in ``.dot`` or ``.gv``, the constraints are printed in the DOT language, and can be processed by Graphviz tools. The format is unspecified if `string` doesn’t end in ``.dot`` or ``.gv``. +.. _existential-variables: Existential variables --------------------- @@ -2173,9 +2180,9 @@ subterms to eventually be replaced by actual subterms. Existential variables are generated in place of unsolvable implicit arguments or “_” placeholders when using commands such as ``Check`` (see -Section :ref:`TODO-6.3.1-check`) or when using tactics such as ``refine`` (see Section -:ref:`TODO-8.2.3-refine`), as well as in place of unsolvable instances when using -tactics such that ``eapply`` (see Section :ref:`TODO-8.2.4-apply`). An existential +Section :ref:`requests-to-the-environment`) or when using tactics such as +:tacn:`refine`, as well as in place of unsolvable instances when using +tactics such that :tacn:`eapply`. An existential variable is defined in a context, which is the context of variables of the placeholder which generated the existential variable, and a type, which is the expected type of the placeholder. @@ -2220,7 +2227,7 @@ existential variable used in the same context as its context of definition is wr Existential variables can be named by the user upon creation using the syntax ``?``\ `ident`. This is useful when the existential variable needs to be explicitly handled later in the script (e.g. -with a named-goal selector, see :ref:`TODO-9.2-goal-selectors`). +with a named-goal selector, see :ref:`goal-selectors`). .. _explicit-display-existentials: @@ -2245,7 +2252,7 @@ is not specified and is implementation-dependent. The inner tactic may use any variable defined in its scope, including repeated alternations between variables introduced by term binding as well as those introduced by tactic binding. The expression `tacexpr` can be any tactic -expression as described in :ref:`thetacticlanguage`. +expression as described in :ref:`ltac`. .. coqtop:: all @@ -2256,5 +2263,5 @@ using highly automated tactics without resorting to writing the proof-term by means of the interactive proof engine. This mechanism is comparable to the ``Declare Implicit Tactic`` command -defined at :ref:`TODO-8.9.7-implicit-automation`, except that the used +defined at :ref:`tactics-implicit-automation`, except that the used tactic is local to each hole instead of being declared globally. diff --git a/doc/sphinx/language/gallina-specification-language.rst b/doc/sphinx/language/gallina-specification-language.rst index 2a146c57aa..246f45b3e7 100644 --- a/doc/sphinx/language/gallina-specification-language.rst +++ b/doc/sphinx/language/gallina-specification-language.rst @@ -1,4 +1,4 @@ -.. _BNF-syntax: +.. _gallinaspecificationlanguage: ------------------------------------ The Gallina specification language @@ -13,7 +13,7 @@ language of commands, called *The Vernacular* is described in Section :ref:`vernacular`. In Coq, logical objects are typed to ensure their logical correctness. The -rules implemented by the typing algorithm are described in Chapter :ref:`cic`. +rules implemented by the typing algorithm are described in Chapter :ref:`calculusofinductiveconstructions`. About the grammars in the manual @@ -110,6 +110,8 @@ Special tokens longest possible one (among all tokens defined at this moment), and so on. +.. _term: + Terms ===== @@ -118,9 +120,9 @@ Syntax of terms The following grammars describe the basic syntax of the terms of the *Calculus of Inductive Constructions* (also called Cic). The formal -presentation of Cic is given in Chapter :ref:`cic`. Extensions of this syntax -are given in Chapter :ref:`gallinaextensions`. How to customize the syntax -is described in Chapter :ref:`syntaxextensions`. +presentation of Cic is given in Chapter :ref:`calculusofinductiveconstructions`. Extensions of this syntax +are given in Chapter :ref:`extensionsofgallina`. How to customize the syntax +is described in Chapter :ref:`syntaxextensionsandinterpretationscopes`. .. productionlist:: coq term : forall `binders` , `term` @@ -186,6 +188,8 @@ Coq terms are typed. Coq types are recognized by the same syntactic class as :token`term`. We denote by :token:`type` the semantic subclass of types inside the syntactic class :token:`term`. +.. _gallina-identifiers: + Qualified identifiers and simple identifiers -------------------------------------------- @@ -201,9 +205,9 @@ Numerals Numerals have no definite semantics in the calculus. They are mere notations that can be bound to objects through the notation mechanism -(see Chapter :ref:`syntaxextensions` for details). +(see Chapter :ref:`syntaxextensionsandinterpretationscopes` for details). Initially, numerals are bound to Peano’s representation of natural -numbers (see :ref:`libnats`). +numbers (see :ref:`datatypes`). .. note:: @@ -228,6 +232,8 @@ There are three sorts :g:`Set`, :g:`Prop` and :g:`Type`. More on sorts can be found in Section :ref:`sorts`. +.. _binders: + Binders ------- @@ -310,7 +316,7 @@ left. The notation ``(ident := term)`` for arguments is used for making explicit the value of implicit arguments (see -Section :ref:`Implicits-explicitation`). +Section :ref:`explicit-applications`). Type cast --------- @@ -328,6 +334,8 @@ Expressions often contain redundant pieces of information. Subterms that can be automatically inferred by Coq can be replaced by the symbol ``_`` and Coq will guess the missing piece of information. +.. _let-in: + Let-in definitions ------------------ @@ -348,7 +356,7 @@ expression is used to analyze the structure of an inductive objects and to apply specific treatments accordingly. This paragraph describes the basic form of pattern-matching. See -Section :ref:`Mult-match` and Chapter :ref:`Mult-match-full` for the description +Section :ref:`Mult-match` and Chapter :ref:`extendedpatternmatching` for the description of the general form. The basic form of pattern-matching is characterized by a single :token:`match_item` expression, a :token:`mult_pattern` restricted to a single :token:`pattern` and :token:`pattern` restricted to the form @@ -415,7 +423,7 @@ accepted and has the same meaning as the previous one. The second subcase is only relevant for annotated inductive types such as the equality predicate (see Section :ref:`Equality`), the order predicate on natural numbers or the type of lists of a given -length (see Section :ref:`listn`). In this configuration, the +length (see Section :ref:`matching-dependent`). In this configuration, the type of each branch can depend on the type dependencies specific to the branch and the whole pattern-matching expression has a type determined by the specific dependencies in the type of the term being matched. This @@ -458,18 +466,17 @@ in are available. There are specific notations for case analysis on types with one or two constructors: “if … then … else …” and “let (…, ” (see -Sections :ref:`if-then-else` and :ref:`Letin`). +Sections :ref:`if-then-else` and :ref:`let-in`). Recursive functions ------------------- The expression “fix :token:`ident`:math:`_1` :token:`binder`:math:`_1` : :token:`type`:math:`_1` ``:=`` :token:`term`:math:`_1` with … with -:token:`ident`:math:`_n` :token:`binder`:math:`_n` : :token:`type`:math:`_n` ``:=`` -:token:`term`:math:`_n` for :token:`ident`:math:`_i`” denotes the -:math:`i`\ component of a block of functions defined by mutual -well-founded recursion. It is the local counterpart of the ``Fixpoint`` -command. See Section :ref:`Fixpoint` for more details. When +:token:`ident`:math:`_n` :token:`binder`:math:`_n` : :token:`type`:math:`_n` +``:=`` :token:`term`:math:`_n` for :token:`ident`:math:`_i`” denotes the +:math:`i`\ component of a block of functions defined by mutual well-founded +recursion. It is the local counterpart of the :cmd:`Fixpoint` command. When :math:`n=1`, the “for :token:`ident`:math:`_i`” clause is omitted. The expression “cofix :token:`ident`:math:`_1` :token:`binder`:math:`_1` : @@ -484,6 +491,8 @@ The association of a single fixpoint and a local definition have a special syntax: “let fix f … := … in …” stands for “let f := fix f … := … in …”. The same applies for co-fixpoints. +.. _vernacular: + The Vernacular ============== @@ -527,6 +536,8 @@ dot. The different kinds of command are described hereafter. They all suppose that the terms occurring in the sentences are well-typed. +.. _gallina-assumptions: + Assumptions ----------- @@ -538,6 +549,8 @@ the same module. This :token:`type` is considered to be the type (or specification, or statement) assumed by :token:`ident` and we say that :token:`ident` has type :token:`type`. +.. _Axiom: + .. cmd:: Axiom @ident : @term. This command links *term* to the name *ident* as its specification in @@ -564,10 +577,9 @@ has type :token:`type`. .. cmdv:: Local Axiom @ident : @term. - Such axioms are never made accessible through their unqualified - name by ``Import`` and its variants (see :ref:`Import`). You - have to explicitly give their fully qualified name to refer to - them. + Such axioms are never made accessible through their unqualified name by + :cmd:`Import` and its variants. You have to explicitly give their fully + qualified name to refer to them. .. cmdv:: Conjecture @ident : @term @@ -576,11 +588,11 @@ has type :token:`type`. .. cmd:: Variable @ident : @term. This command links :token:`term` to the name :token:`ident` in the context of -the current section (see Section :ref:`Section` for a description of the section -mechanism). When the current section is closed, name :token:`ident` will be -unknown and every object using this variable will be explicitly parametrized -(the variable is *discharged*). Using the ``Variable`` command out of any -section is equivalent to using ``Local Parameter``. +the current section (see Section :ref:`section-mechanism` for a description of +the section mechanism). When the current section is closed, name :token:`ident` +will be unknown and every object using this variable will be explicitly +parametrized (the variable is *discharged*). Using the ``Variable`` command out +of any section is equivalent to using ``Local Parameter``. .. exn:: @ident already exists @@ -605,6 +617,8 @@ logical postulates (i.e. when the assertion *term* is of sort ``Prop``), and to use the keywords ``Parameter`` and ``Variable`` in other cases (corresponding to the declaration of an abstract mathematical entity). +.. _gallina-definitions: + Definitions ----------- @@ -614,7 +628,7 @@ way to abbreviate a term. In any case, the name can later be replaced at any time by its definition. The operation of unfolding a name into its definition is called -:math:`\delta`-conversion (see Section :ref:`delta`). A +:math:`\delta`-conversion (see Section :ref:`delta-reduction`). A definition is accepted by the system if and only if the defined term is well-typed in the current context of the definition and if the name is not already used. The name defined by the definition is called a @@ -622,7 +636,7 @@ not already used. The name defined by the definition is called a type which is the type of its body. A formal presentation of constants and environments is given in -Section :ref:`Typed-terms`. +Section :ref:`typing-rules`. .. cmd:: Definition @ident := @term. @@ -648,7 +662,7 @@ Section :ref:`Typed-terms`. .. cmdv:: Local Definition @ident := @term. Such definitions are never made accessible through their - unqualified name by Import and its variants (see :ref:`Import`). + unqualified name by :cmd:`Import` and its variants. You have to explicitly give their fully qualified name to refer to them. .. cmdv:: Example @ident := @term. @@ -661,7 +675,7 @@ These are synonyms of the Definition forms. .. exn:: The term @term has type @type while it is expected to have type @type -See also Sections :ref:`Opaque,Transparent,unfold`. +See also :cmd:`Opaque`, :cmd:`Transparent`, :tac:`unfold`. .. cmd:: Let @ident := @term. @@ -681,7 +695,10 @@ prefixed by the let-in definition ``let`` :token:`ident` ``:=`` :token:`term` .. cmdv:: Let CoFixpoint @ident @cofix_body {* with @cofix_body}. -See also Sections :ref:`Section,Opaque,Transparent,unfold`. +See also Sections :ref:`section-mechanism`, commands :cmd:`Opaque`, +:cmd:`Transparent`, and tactic :tacn:`unfold`. + +.. _gallina-inductive-definitions: Inductive definitions --------------------- @@ -701,7 +718,7 @@ The name :token:`ident` is the name of the inductively defined type and :token:`sort` is the universes where it lives. The :token:`ident` are the names of its constructors and :token:`type` their respective types. The types of the constructors have to satisfy a *positivity condition* (see Section -:ref:`Positivity`) for :token:`ident`. This condition ensures the soundness of +:ref:`positivity`) for :token:`ident`. This condition ensures the soundness of the inductive definition. If this is the case, the :token:`ident` are added to the environment with their respective types. Accordingly to the universe where the inductive type lives (e.g. its type :token:`sort`), Coq provides a number of @@ -842,8 +859,7 @@ arguments of the constructors rather than their full type. The ``Variant`` keyword is identical to the ``Inductive`` keyword, except that it disallows recursive definition of types (in particular lists cannot be defined with the Variant keyword). No induction scheme is generated for -this variant, unless the option ``Nonrecursive Elimination Schemes`` is set -(see :ref:`set-nonrecursive-elimination-schemes`). +this variant, unless :opt:`Nonrecursive Elimination Schemes` is set. .. exn:: The @num th argument of @ident must be @ident in @type @@ -885,7 +901,8 @@ instead of parameters but it will sometimes give a different (bigger) sort for the inductive definition and will produce a less convenient rule for case elimination. -See also Sections :ref:`Cic-inductive-definitions,Tac-induction`. +See also Section :ref:`inductive-definitions` and the :tacn:`induction` +tactic. Mutually defined inductive types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -954,7 +971,9 @@ section is closed, the variables declared in the section and occurring free in the declaration are added as parameters to the inductive definition. -See also Section :ref:`Section`. +See also Section :ref:`section-mechanism`. + +.. _coinductive-types: Co-inductive types ~~~~~~~~~~~~~~~~~~ @@ -976,12 +995,12 @@ Coq using the ``CoInductive`` command: CoInductive Stream : Set := Seq : nat -> Stream -> Stream. -The syntax of this command is the same as the command ``Inductive`` (see -Section :ref:`gal-Inductive-Definitions`. Notice that no principle of induction -is derived from the definition of a co-inductive type, since such principles -only make sense for inductive ones. For co-inductive ones, the only elimination -principle is case analysis. For example, the usual destructors on streams -:g:`hd:Stream->nat` and :g:`tl:Str->Str` can be defined as follows: +The syntax of this command is the same as the command :cmd:`Inductive`. Notice +that no principle of induction is derived from the definition of a co-inductive +type, since such principles only make sense for inductive ones. For co-inductive +ones, the only elimination principle is case analysis. For example, the usual +destructors on streams :g:`hd:Stream->nat` and :g:`tl:Str->Str` can be defined +as follows: .. coqtop:: all @@ -1001,7 +1020,7 @@ predicate is the extensional equality on streams: In order to prove the extensionally equality of two streams :g:`s1` and :g:`s2` we have to construct an infinite proof of equality, that is, an infinite object of type :g:`(EqSt s1 s2)`. We will see how to introduce infinite objects in -Section :ref:`CoFixpoint`. +Section :ref:`cofixpoint`. Definition of recursive functions --------------------------------- @@ -1010,12 +1029,14 @@ Definition of functions by recursion over inductive objects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section describes the primitive form of definition by recursion over -inductive objects. See Section :ref:`Function` for more advanced constructions. -The command: +inductive objects. See the :cmd:`Function` command for more advanced +constructions. + +.. _Fixpoint: .. cmd:: Fixpoint @ident @params {struct @ident} : @type := @term. -allows defining functions by pattern-matching over inductive objects +This command allows defining functions by pattern-matching over inductive objects using a fixed point construction. The meaning of this declaration is to define :token:`ident` a recursive function with arguments specified by the binders in :token:`params` such that :token:`ident` applied to arguments corresponding @@ -1057,7 +1078,8 @@ respective values to be returned, as functions of the parameters of the corresponding constructor. Thus here when :g:`n` equals :g:`O` we return :g:`m`, and when :g:`n` equals :g:`(S p)` we return :g:`(S (add p m))`. -The match operator is formally described in detail in Section :ref:`Caseexpr`. +The match operator is formally described in detail in Section +:ref:`match-construction`. The system recognizes that in the inductive call :g:`(add p m)` the first argument actually decreases because it is a *pattern variable* coming from :g:`match n with`. @@ -1145,7 +1167,10 @@ The size of trees and forests can be defined the following way: end. A generic command Scheme is useful to build automatically various mutual -induction principles. It is described in Section :ref:`Scheme`. +induction principles. It is described in Section +:ref:`proofschemes-induction-principles`. + +.. _cofixpoint: Definitions of recursive objects in co-inductive types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1154,8 +1179,8 @@ Definitions of recursive objects in co-inductive types introduces a method for constructing an infinite object of a coinductive type. For example, the stream containing all natural numbers can be -introduced applying the following method to the number :ref:`O` (see -Section :ref:`CoInductiveTypes` for the definition of :g:`Stream`, :g:`hd` and +introduced applying the following method to the number :g:`O` (see +Section :ref:`coinductive-types` for the definition of :g:`Stream`, :g:`hd` and :g:`tl`): .. coqtop:: all @@ -1198,8 +1223,8 @@ the normal forms of a term: .. cmdv:: CoFixpoint @ident : @type := @term {+ with @ident : @type := @term } - As in the ``Fixpoint`` command (see Section :ref:`Fixpoint`), it is possible - to introduce a block of mutually dependent methods. + As in the :cmd:`Fixpoint` command, it is possible to introduce a block of + mutually dependent methods. .. _Assertions: @@ -1208,7 +1233,7 @@ Assertions and proofs An assertion states a proposition (or a type) of which the proof (or an inhabitant of the type) is interactively built using tactics. The interactive -proof mode is described in Chapter :ref:`Proof-handling` and the tactics in +proof mode is described in Chapter :ref:`proofhandling` and the tactics in Chapter :ref:`Tactics`. The basic assertion command is: .. cmd:: Theorem @ident : @type. @@ -1239,15 +1264,14 @@ the theorem is bound to the name :token:`ident` in the environment. .. cmdv:: Theorem @ident : @type {* with @ident : @type}. - This command is useful for theorems that are proved by simultaneous - induction over a mutually inductive assumption, or that assert - mutually dependent statements in some mutual co-inductive type. It is - equivalent to ``Fixpoint`` or ``CoFixpoint`` (see - Section :ref:`CoFixpoint`) but using tactics to build - the proof of the statements (or the body of the specification, - depending on the point of view). The inductive or co-inductive types - on which the induction or coinduction has to be done is assumed to be - non ambiguous and is guessed by the system. + This command is useful for theorems that are proved by simultaneous induction + over a mutually inductive assumption, or that assert mutually dependent + statements in some mutual co-inductive type. It is equivalent to + :cmd:`Fixpoint` or :cmd:`CoFixpoint` but using tactics to build the proof of + the statements (or the body of the specification, depending on the point of + view). The inductive or co-inductive types on which the induction or + coinduction has to be done is assumed to be non ambiguous and is guessed by + the system. Like in a ``Fixpoint`` or ``CoFixpoint`` definition, the induction hypotheses have to be used on *structurally smaller* arguments (for a ``Fixpoint``) or @@ -1255,7 +1279,7 @@ the theorem is bound to the name :token:`ident` in the environment. recursive proof arguments are correct is done only at the time of registering the lemma in the environment. To know if the use of induction hypotheses is correct at some time of the interactive development of a proof, use the - command Guarded (see Section :ref:`Guarded`). + command :cmd:`Guarded`. The command can be used also with ``Lemma``, ``Remark``, etc. instead of ``Theorem``. @@ -1264,12 +1288,12 @@ the theorem is bound to the name :token:`ident` in the environment. This allows defining a term of type :token:`type` using the proof editing mode. It behaves as Theorem but is intended to be used in conjunction with - Defined (see :ref:`Defined`) in order to define a constant of which the - computational behavior is relevant. + :cmd:`Defined` in order to define a constant of which the computational + behavior is relevant. - The command can be used also with ``Example`` instead of ``Definition``. + The command can be used also with :cmd:`Example` instead of :cmd:`Definition`. - See also Sections :ref:`Opaque` :ref:`Transparent` :ref:`unfold`. + See also :cmd:`Opaque`, :cmd:`Transparent`, :tacn:`unfold`. .. cmdv:: Let @ident : @type. @@ -1295,7 +1319,7 @@ A proof starts by the keyword Proof. Then Coq enters the proof editing mode until the proof is completed. The proof editing mode essentially contains tactics that are described in chapter :ref:`Tactics`. Besides tactics, there are commands to manage the proof editing mode. They are described in Chapter -:ref:`Proof-handling`. When the proof is completed it should be validated and +:ref:`proofhandling`. When the proof is completed it should be validated and put in the environment using the keyword Qed. .. exn:: @ident already exists @@ -1313,7 +1337,7 @@ put in the environment using the keyword Qed. side, Qed (or Defined, see below) is mandatory to validate a proof. #. Proofs ended by Qed are declared opaque. Their content cannot be - unfolded (see :ref:`Conversion-tactics`), thus + unfolded (see :ref:`performingcomputations`), thus realizing some form of *proof-irrelevance*. To be able to unfold a proof, the proof should be ended by Defined (see below). @@ -1322,7 +1346,7 @@ put in the environment using the keyword Qed. Same as ``Proof. … Qed.`` but the proof is then declared transparent, which means that its content can be explicitly used for type-checking and that it can be unfolded in conversion tactics - (see :ref:`Conversion-tactics,Opaque,Transparent`). + (see :ref:`performingcomputations`, :cmd:`Opaque`, :cmd:`Transparent`). .. cmdv:: Proof. … Admitted. diff --git a/doc/sphinx/practical-tools/coq-commands.rst b/doc/sphinx/practical-tools/coq-commands.rst index 1ff808894a..93dcfca4bf 100644 --- a/doc/sphinx/practical-tools/coq-commands.rst +++ b/doc/sphinx/practical-tools/coq-commands.rst @@ -16,6 +16,8 @@ The options are (basically) the same for the first two commands, and roughly described below. You can also look at the ``man`` pages of ``coqtop`` and ``coqc`` for more details. +.. _interactive-use: + Interactive use (coqtop) ------------------------ @@ -39,10 +41,12 @@ Batch compilation (coqc) The ``coqc`` command takes a name *file* as argument. Then it looks for a vernacular file named *file*.v, and tries to compile it into a -*file*.vo file (See :ref:`TODO-6.5`). Warning: The name *file* should be a -regular |Coq| identifier, as defined in Section :ref:'TODO-1.1'. It should contain -only letters, digits or underscores (_). For instance, ``/bar/foo/toto.v`` is valid, but -``/bar/foo/to-to.v`` is invalid. +*file*.vo file (See :ref:`compiled-files`). + +.. caution:: The name *file* should be a + regular |Coq| identifier, as defined in Section :ref:'TODO-1.1'. It should contain + only letters, digits or underscores (_). For instance, ``/bar/foo/toto.v`` is valid, but + ``/bar/foo/to-to.v`` is invalid. Customization at launch time @@ -63,6 +67,7 @@ This file may contain, for instance, ``Add LoadPath`` commands to add directories to the load path of |Coq|. It is possible to skip the loading of the resource file with the option ``-q``. +.. _customization-by-environment-variables: By environment variables ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -70,7 +75,7 @@ By environment variables Load path can be specified to the |Coq| system by setting up ``$COQPATH`` environment variable. It is a list of directories separated by ``:`` (``;`` on Windows). |Coq| will also honor ``$XDG_DATA_HOME`` and -``$XDG_DATA_DIRS`` (see Section :ref:`TODO-2.6.3`). +``$XDG_DATA_DIRS`` (see Section :ref:`libraries-and-filesystem`). Some |Coq| commands call other |Coq| commands. In this case, they look for the commands in directory specified by ``$COQBIN``. If this variable is @@ -84,6 +89,8 @@ list of assignments of the form ``name=``:n:``{*; attr}`` where ANSI escape code. The list of highlight tags can be retrieved with the ``-list-tags`` command-line option of ``coqtop``. +.. _command-line-options: + By command line options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -91,25 +98,25 @@ The following command-line options are recognized by the commands ``coqc`` and ``coqtop``, unless stated otherwise: :-I *directory*, -include *directory*: Add physical path *directory* - to the OCaml loadpath. See also: :ref:`TODO-2.6.1` and the - command Declare ML Module Section :ref:`TODO-6.5`. + to the OCaml loadpath. See also: :ref:`names-of-libraries` and the + command Declare ML Module Section :ref:`compiled-files`. :-Q *directory* dirpath: Add physical path *directory* to the list of directories where |Coq| looks for a file and bind it to the the logical directory *dirpath*. The subdirectory structure of *directory* is recursively available from |Coq| using absolute names (extending the - dirpath prefix) (see Section :ref:`TODO-2.6.2`).Note that only those + dirpath prefix) (see Section :ref:`qualified-names`).Note that only those subdirectories and files which obey the lexical conventions of what is - an ident (see Section :ref:`TODO-1.1`) are taken into account. Conversely, the + an :n:`@ident` are taken into account. Conversely, the underlying file systems or operating systems may be more restrictive than |Coq|. While Linux’s ext4 file system supports any |Coq| recursive layout (within the limit of 255 bytes per file name), the default on NTFS (Windows) or HFS+ (MacOS X) file systems is on the contrary to disallow two files differing only in the case in the same directory. - See also: Section :ref:`TODO-2.6.1`. + See also: Section :ref:`names-of-libraries`. :-R *directory* dirpath: Do as -Q *directory* dirpath but make the subdirectory structure of *directory* recursively visible so that the recursive contents of physical *directory* is available from |Coq| using - short or partially qualified names. See also: Section :ref:`TODO-2.6.1`. + short or partially qualified names. See also: Section :ref:`names-of-libraries`. :-top dirpath: Set the toplevel module name to dirpath instead of Top. Not valid for `coqc` as the toplevel module name is inferred from the name of the output file. @@ -145,7 +152,7 @@ and ``coqtop``, unless stated otherwise: -compile-verbose. :-w (all|none|w₁,…,wₙ): Configure the display of warnings. This option expects all, none or a comma-separated list of warning names or - categories (see Section :ref:`TODO-6.9.3`). + categories (see Section :ref:`controlling-display`). :-color (on|off|auto): Enable or not the coloring of output of `coqtop`. Default is auto, meaning that `coqtop` dynamically decides, depending on whether the output channel supports ANSI escape sequences. @@ -170,7 +177,7 @@ and ``coqtop``, unless stated otherwise: :-compat *version*: Attempt to maintain some backward-compatibility with a previous version. :-dump-glob *file*: Dump references for global names in file *file* - (to be used by coqdoc, see :ref:`TODO-15.4`). By default, if *file.v* is being + (to be used by coqdoc, see :ref:`coqdoc`). By default, if *file.v* is being compiled, *file.glob* is used. :-no-glob: Disable the dumping of references for global names. :-image *file*: Set the binary image to be used by `coqc` to be *file* diff --git a/doc/sphinx/practical-tools/coqide.rst b/doc/sphinx/practical-tools/coqide.rst index a3b9426287..f9903e6104 100644 --- a/doc/sphinx/practical-tools/coqide.rst +++ b/doc/sphinx/practical-tools/coqide.rst @@ -75,7 +75,7 @@ There are two additional buttons for navigation within the running buffer. The "down" button with a line goes directly to the end; the "up" button with a line goes back to the beginning. The handling of errors when using the go-to-the-end button depends on whether |Coq| is running in asynchronous mode or not (see -Chapter :ref:`Asyncprocessing`). If it is not running in that mode, execution +Chapter :ref:`asynchronousandparallelproofprocessing`). If it is not running in that mode, execution stops as soon as an error is found. Otherwise, execution continues, and the error is marked with an underline in the error foreground color, with a background in the error background color (pink by default). The same @@ -90,10 +90,10 @@ There are other buttons on the |CoqIDE| toolbar: a button to save the running buffer; a button to close the current buffer (an "X"); buttons to switch among buffers (left and right arrows); an "information" button; and a "gears" button. -The "information" button is described in Section :ref:`sec:trytactics`. +The "information" button is described in Section :ref:`try-tactics-automatically`. The "gears" button submits proof terms to the |Coq| kernel for type-checking. -When |Coq| uses asynchronous processing (see Chapter :ref:`Asyncprocessing`), +When |Coq| uses asynchronous processing (see Chapter :ref:`asynchronousandparallelproofprocessing`), proofs may have been completed without kernel-checking of generated proof terms. The presence of unchecked proof terms is indicated by ``Qed`` statements that have a subdued *being-processed* color (light blue by default), rather than the @@ -150,8 +150,6 @@ arguments. Queries ------------ -.. _coqide_queryselected: - .. image:: ../_static/coqide-queries.png :alt: |CoqIDE| queries @@ -161,7 +159,7 @@ writing them in scripts, |CoqIDE| offers a *query pane*. The query pane can be displayed on demand by using the ``View`` menu, or using the shortcut ``F1``. Queries can also be performed by selecting a particular phrase, then choosing an item from the ``Queries`` menu. The response then appears in the message window. -Figure :ref:`fig:queryselected` shows the result after selecting of the phrase +The image above shows the result after selecting of the phrase ``Nat.mul`` in the script window, and choosing ``Print`` from the ``Queries`` menu. diff --git a/doc/sphinx/practical-tools/utilities.rst b/doc/sphinx/practical-tools/utilities.rst index 620c002ff3..59867988a4 100644 --- a/doc/sphinx/practical-tools/utilities.rst +++ b/doc/sphinx/practical-tools/utilities.rst @@ -33,6 +33,7 @@ For example, to statically link |L_tac|, you can just do: % ocamlfind ocamlopt -thread -rectypes -linkall -linkpkg \ -package coq.toplevel -package coq.ltac \ toplevel/coqtop\_bin.ml -o my\_toplevel.native + and similarly for other plugins. @@ -43,7 +44,7 @@ The majority of |Coq| projects are very similar: a collection of ``.v`` files and eventually some ``.ml`` ones (a |Coq| plugin). The main piece of metadata needed in order to build the project are the command line options to ``coqc`` (e.g. ``-R``, ``-I``, see also: Section -:ref:`bycommandline`). Collecting the list of files and options is the job +:ref:`command-line-options`). Collecting the list of files and options is the job of the ``_CoqProject`` file. A simple example of a ``_CoqProject`` file follows: @@ -59,7 +60,7 @@ A simple example of a ``_CoqProject`` file follows: src/qux_plugin.mlpack -Currently, both |CoqIDE| and |ProofGeneral| (version ≥ ``4.3pre``) +Currently, both |CoqIDE| and Proof-General (version ≥ ``4.3pre``) understand ``_CoqProject`` files and invoke |Coq| with the desired options. The ``coq_makefile`` utility can be used to set up a build infrastructure @@ -77,7 +78,7 @@ CoqMakefile is a generic makefile for ``GNU Make`` that provides targets to build the project (both ``.v`` and ``.ml*`` files), to install it system-wide in the ``coq-contrib`` directory (i.e. where |Coq| is installed) - as well as to invoke |coqdoc| to generate |HTML| documentation. + as well as to invoke coqdoc to generate HTML documentation. CoqMakefile.conf contains make variables assignments that reflect @@ -89,7 +90,7 @@ An optional file ``CoqMakefile.local`` can be provided by the user in order to extend ``CoqMakefile``. In particular one can declare custom actions to be performed before or after the build process. Similarly one can customize the install target or even provide new targets. Extension points are documented in -paragraph :ref:`coqmakefile:local`. +paragraph :ref:`coqmakefilelocal`. The extensions of the files listed in ``_CoqProject`` is used in order to decide how to build them. In particular: @@ -113,32 +114,38 @@ distinct plugins because of a clash in their auxiliary module names. .. _coqmakefilelocal: CoqMakefile.local -+++++++++++++++++ - - +~~~~~~~~~~~~~~~~~ The optional file ``CoqMakefile.local`` is included by the generated file ``CoqMakefile``. It can contain two kinds of directives. -Variable assignment - The variable must belong to the variables listed in the ``Parameters`` section of the generated makefile. - Here we describe only few of them. - :CAMLPKGS: - can be used to specify third party findlib packages, and is - passed to the OCaml compiler on building or linking of modules. Eg: - ``-package yojson``. - :CAMLFLAGS: - can be used to specify additional flags to the |OCaml| - compiler, like ``-bin-annot`` or ``-w``.... - :COQC, COQDEP, COQDOC: - can be set in order to use alternative binaries - (e.g. wrappers) - :COQ_SRC_SUBDIRS: can be extended by including other paths in which ``*.cm*`` files are searched. For example ``COQ\_SRC\_SUBDIRS+=user-contrib/Unicoq`` lets you build a plugin containing OCaml code that depends on the OCaml code of ``Unicoq``. - -Rule extension - The following makefile rules can be extended. - - .. example :: +**Variable assignment** + +The variable must belong to the variables listed in the ``Parameters`` +section of the generated makefile. +Here we describe only few of them. + +:CAMLPKGS: + can be used to specify third party findlib packages, and is + passed to the OCaml compiler on building or linking of modules. Eg: + ``-package yojson``. +:CAMLFLAGS: + can be used to specify additional flags to the |OCaml| + compiler, like ``-bin-annot`` or ``-w``.... +:COQC, COQDEP, COQDOC: + can be set in order to use alternative binaries + (e.g. wrappers) +:COQ_SRC_SUBDIRS: + can be extended by including other paths in which ``*.cm*`` files + are searched. For example ``COQ\_SRC\_SUBDIRS+=user-contrib/Unicoq`` + lets you build a plugin containing OCaml code that depends on the + OCaml code of ``Unicoq``. + +**Rule extension** + +The following makefile rules can be extended. + +.. example:: :: @@ -147,42 +154,41 @@ Rule extension install-extra:: cp ThisExtraFile /there/it/goes - ``pre-all::`` - run before the all target. One can use this to configure - the project, or initialize sub modules or check dependencies are met. +``pre-all::`` + run before the ``all`` target. One can use this to configure + the project, or initialize sub modules or check dependencies are met. - ``post-all::`` - run after the all target. One can use this to run a test - suite, or compile extracted code. +``post-all::`` + run after the ``all`` target. One can use this to run a test + suite, or compile extracted code. +``install-extra::`` + run after ``install``. One can use this to install extra files. - ``install-extra::`` - run after install. One can use this to install extra files. +``install-doc::`` + One can use this to install extra doc. - ``install-doc::`` - One can use this to install extra doc. +``uninstall::`` + \ - ``uninstall::`` - \ +``uninstall-doc::`` + \ - ``uninstall-doc::`` - \ +``clean::`` + \ - ``clean::`` - \ +``cleanall::`` + \ - ``cleanall::`` - \ +``archclean::`` + \ - ``archclean::`` - \ - - ``merlin-hook::`` - One can append lines to the generated .merlin file extending this - target. +``merlin-hook::`` + One can append lines to the generated ``.merlin`` file extending this + target. Timing targets and performance testing -++++++++++++++++++++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The generated ``Makefile`` supports the generation of two kinds of timing data: per-file build-times, and per-line times for an individual file. @@ -311,8 +317,8 @@ line timing data: + ``print-pretty-single-time-diff`` :: - print-pretty-single-time-diff BEFORE=path/to/file.v.before-timing AFTER=path/to/file.v.after-timing + this target will make a sorted table of the per-line timing differences between the timing logs in the ``BEFORE`` and ``AFTER`` files, display it, and save it to the file specified by the ``TIME_OF_PRETTY_BUILD_FILE`` variable, @@ -357,7 +363,7 @@ line timing data: Reusing/extending the generated Makefile -++++++++++++++++++++++++++++++++++++++++ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Including the generated makefile with an include directive is discouraged. The contents of this file, including variable names and @@ -400,8 +406,8 @@ have a generic target for invoking unknown targets. -Building a subset of the targets with -j -++++++++++++++++++++++++++++++++++++++++ +Building a subset of the targets with ``-j`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To build, say, two targets foo.vo and bar.vo in parallel one can use ``make only TGTS="foo.vo bar.vo" -j``. @@ -451,14 +457,16 @@ automatically compute the dependencies among the files part of the project. +.. _coqdoc: + Documenting |Coq| files with coqdoc ----------------------------------- -|coqdoc| is a documentation tool for the proof assistant |Coq|, similar to -``javadoc`` or ``ocamldoc``. The task of |coqdoc| is +coqdoc is a documentation tool for the proof assistant |Coq|, similar to +``javadoc`` or ``ocamldoc``. The task of coqdoc is -#. to produce a nice |Latex| and/or |HTML| document from the |Coq| +#. to produce a nice |Latex| and/or HTML document from the |Coq| sources, readable for a human and not only for the proof assistant; #. to help the user navigating in his own (or third-party) sources. @@ -468,18 +476,18 @@ Principles ~~~~~~~~~~ Documentation is inserted into |Coq| files as *special comments*. Thus -your files will compile as usual, whether you use |coqdoc| or not. |coqdoc| +your files will compile as usual, whether you use coqdoc or not. coqdoc presupposes that the given |Coq| files are well-formed (at least lexically). Documentation starts with ``(**``, followed by a space, and ends with the pending ``*)``. The documentation format is inspired by Todd A. Coram’s *Almost Free Text (AFT)* tool: it is mainly ``ASCII`` text with -some syntax-light controls, described below. |coqdoc| is robust: it +some syntax-light controls, described below. coqdoc is robust: it shouldn’t fail, whatever the input is. But remember: “garbage in, garbage out”. |Coq| material inside documentation. -++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++++ |Coq| material is quoted between the delimiters ``[`` and ``]``. Square brackets may be nested, the inner ones being understood as being part of the @@ -494,7 +502,7 @@ followed by a newline and the latter must follow a newline. Pretty-printing. ++++++++++++++++ -|coqdoc| uses different faces for identifiers and keywords. The pretty- +coqdoc uses different faces for identifiers and keywords. The pretty- printing of |Coq| tokens (identifiers or symbols) can be controlled using one of the following commands: @@ -512,8 +520,8 @@ or (** printing *token* $...LATEX math...$ #...html...# *) -It gives the |Latex| and |HTML| texts to be produced for the given |Coq| -token. One of the |Latex| or |HTML| text may be omitted, causing the +It gives the |Latex| and HTML texts to be produced for the given |Coq| +token. One of the |Latex| or HTML text may be omitted, causing the default pretty-printing to be used for this token. The printing for one token can be removed with @@ -530,27 +538,28 @@ Initially, the pretty-printing table contains the following mapping: `->` → `<-` ← `*` × `<=` ≤ `>=` ≥ `=>` ⇒ `<>` ≠ `<->` ↔ `|-` ⊢ -`\/` ∨ `/\` ∧ `~` ¬ +`\/` ∨ `/\\` ∧ `~` ¬ ==== === ==== ===== === ==== ==== === Any of these can be overwritten or suppressed using the printing commands. -.. note :: - The recognition of tokens is done by a (``ocaml``) lex - automaton and thus applies the longest-match rule. For instance, `->~` - is recognized as a single token, where |Coq| sees two tokens. It is the - responsibility of the user to insert space between tokens *or* to give - pretty-printing rules for the possible combinations, e.g. +.. note:: + + The recognition of tokens is done by a (``ocaml``) lex + automaton and thus applies the longest-match rule. For instance, `->~` + is recognized as a single token, where |Coq| sees two tokens. It is the + responsibility of the user to insert space between tokens *or* to give + pretty-printing rules for the possible combinations, e.g. - :: + :: (** printing ->~ %\ensuremath{\rightarrow\lnot}% *) -Sections. -+++++++++ +Sections +++++++++ Sections are introduced by 1 to 4 leading stars (i.e. at the beginning of the line) followed by a space. One star is a section, two stars a @@ -559,7 +568,7 @@ line. .. example:: - :: + :: (** * Well-founded relations @@ -614,18 +623,18 @@ emphasis. Usually, these are spaces or punctuation. -Escaping to |Latex| and |HTML|. +Escaping to |Latex| and HTML. +++++++++++++++++++++++++++++++ -Pure |Latex| or |HTML| material can be inserted using the following +Pure |Latex| or HTML material can be inserted using the following escape sequences: + ``$...LATEX stuff...$`` inserts some |Latex| material in math mode. - Simply discarded in |HTML| output. + Simply discarded in HTML output. + ``%...LATEX stuff...%`` inserts some |Latex| material. Simply - discarded in |HTML| output. -+ ``#...HTML stuff...#`` inserts some |HTML| material. Simply discarded in + discarded in HTML output. ++ ``#...HTML stuff...#`` inserts some HTML material. Simply discarded in |Latex| output. .. note:: @@ -654,7 +663,7 @@ at the beginning of a line. Hyperlinks ++++++++++ -Hyperlinks can be inserted into the |HTML| output, so that any +Hyperlinks can be inserted into the HTML output, so that any identifier is linked to the place of its definition. ``coqc file.v`` automatically dumps localization information in @@ -662,7 +671,7 @@ identifier is linked to the place of its definition. file``. Take care of erasing this global file, if any, when starting the whole compilation process. -Then invoke |coqdoc| or ``coqdoc --glob-from file`` to tell |coqdoc| to look +Then invoke coqdoc or ``coqdoc --glob-from file`` to tell coqdoc to look for name resolutions into the file ``file`` (it will look in ``file.glob`` by default). @@ -703,17 +712,17 @@ be used around a whole proof. Usage ~~~~~ -|coqdoc| is invoked on a shell command line as follows: +coqdoc is invoked on a shell command line as follows: ``coqdoc <options and files>``. Any command line argument which is not an option is considered to be a file (even if it starts with a ``-``). |Coq| files are identified by the suffixes ``.v`` and ``.g`` and |Latex| files by the suffix ``.tex``. -:|HTML| output: This is the default output. One |HTML| file is created for +:HTML output: This is the default output. One HTML file is created for each |Coq| file given on the command line, together with a file - ``index.html`` (unless ``option-no-index is passed``). The |HTML| pages use a - style sheet named ``style.css``. Such a file is distributed with |coqdoc|. + ``index.html`` (unless ``option-no-index is passed``). The HTML pages use a + style sheet named ``style.css``. Such a file is distributed with coqdoc. :|Latex| output: A single |Latex| file is created, on standard output. It can be redirected to a file with option ``-o``. The order of files on the command line is kept in the final document. |Latex| @@ -732,7 +741,7 @@ Command line options **Overall options** - :--|HTML|: Select a |HTML| output. + :--HTML: Select a HTML output. :--|Latex|: Select a |Latex| output. :--dvi: Select a DVI output. :--ps: Select a PostScript output. @@ -760,7 +769,7 @@ Command line options **Index options** - Default behavior is to build an index, for the |HTML| output only, + Default behavior is to build an index, for the HTML output only, into ``index.html``. :--no-index: Do not output the index. @@ -775,7 +784,7 @@ Command line options :-toc, --table-of-contents: Insert a table of contents. For a |Latex| output, it inserts a ``\tableofcontents`` at the beginning of the - document. For a |HTML| output, it builds a table of contents into + document. For a HTML output, it builds a table of contents into ``toc.html``. :--toc-depth int: Only include headers up to depth ``int`` in the table of contents. @@ -795,28 +804,28 @@ Command line options directory ``coqdir`` (similarly to |Coq| option ``-R``). .. note:: - option ``-R`` only has - effect on the files *following* it on the command line, so you will - probably need to put this option first. + + option ``-R`` only has + effect on the files *following* it on the command line, so you will + probably need to put this option first. **Title options** :-s , --short: Do not insert titles for the files. The default - behavior is to insert a title like “Library Foo” for each file. + behavior is to insert a title like “Library Foo” for each file. :--lib-name string: Print “string Foo” instead of “Library Foo” in - titles. For example “Chapter” and “Module” are reasonable choices. + titles. For example “Chapter” and “Module” are reasonable choices. :--no-lib-name: Print just “Foo” instead of “Library Foo” in titles. :--lib-subtitles: Look for library subtitles. When enabled, the - beginning of each file is checked for a comment of the form: - - :: + beginning of each file is checked for a comment of the form: + :: - (** * ModuleName : text *) + (** * ModuleName : text *) - where ``ModuleName`` must be the name of the file. If it is present, the - text is used as a subtitle for the module in appropriate places. + where ``ModuleName`` must be the name of the file. If it is present, the + text is used as a subtitle for the module in appropriate places. :-t string, --title string: Set the document title. @@ -854,11 +863,11 @@ Command line options :-latin1, --latin1: Select ISO-8859-1 input files. It is equivalent to --inputenc latin1 --charset iso-8859-1. :-utf8, --utf8: Set --inputenc utf8x for |Latex| output and--charset - utf-8 for |HTML| output. Also use Unicode replacements for a couple of + utf-8 for HTML output. Also use Unicode replacements for a couple of standard plain ASCII notations such as → for ``->`` and ∀ for ``forall``. |Latex| UTF-8 support can be found at `<http://www.ctan.org/pkg/unicode>`_. For the interpretation of Unicode - characters by |Latex|, extra packages which |coqdoc| does not provide + characters by |Latex|, extra packages which coqdoc does not provide by default might be required, such as textgreek for some Greek letters or ``stmaryrd`` for some mathematical symbols. If a Unicode character is missing an interpretation in the utf8x input encoding, add @@ -866,13 +875,13 @@ Command line options and declarations can be added with option ``-p``. :--inputenc string: Give a |Latex| input encoding, as an option to |Latex| package ``inputenc``. - :--charset string: Specify the |HTML| character set, to be inserted in - the |HTML| header. + :--charset string: Specify the HTML character set, to be inserted in + the HTML header. The coqdoc |Latex| style file -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In case you choose to produce a document without the default |Latex| preamble (by using option ``--no-preamble``), then you must insert into @@ -929,16 +938,16 @@ There are options to produce the |Coq| parts in smaller font, italic, between horizontal rules, etc. See the man page of ``coq-tex`` for more details. -|Coq| and |GNU| |Emacs| +|Coq| and GNU Emacs ----------------------- -The |Coq| |Emacs| mode +The |Coq| Emacs mode ~~~~~~~~~~~~~~~~~~~~~~~~~ -|Coq| comes with a Major mode for |GNU| |Emacs|, ``gallina.el``. This mode +|Coq| comes with a Major mode for GNU Emacs, ``gallina.el``. This mode provides syntax highlighting and also a rudimentary indentation -facility in the style of the ``Caml`` |GNU| |Emacs| mode. +facility in the style of the ``Caml`` GNU Emacs mode. Add the following lines to your ``.emacs`` file: @@ -956,26 +965,26 @@ facility: + pressing ``Tab`` at the beginning of a line indents the line like the line above; -+ extra ``Tab``s increase the indentation level (by 2 spaces by default); ++ extra tabulations increase the indentation level (by 2 spaces by default); + ``M-Tab`` decreases the indentation level. -An inferior mode to run |Coq| under |Emacs|, by Marco Maggesi, is also +An inferior mode to run |Coq| under Emacs, by Marco Maggesi, is also included in the distribution, in file ``inferior-coq.el``. Instructions to use it are contained in this file. -Proof General +Proof-General ~~~~~~~~~~~~~ -|ProofGeneral| is a generic interface for proof assistants based on -|Emacs|. The main idea is that the |Coq| commands you are editing are sent -to a |Coq| toplevel running behind |Emacs| and the answers of the system -automatically inserted into other |Emacs| buffers. Thus you don’t need +Proof-General is a generic interface for proof assistants based on +Emacs. The main idea is that the |Coq| commands you are editing are sent +to a |Coq| toplevel running behind Emacs and the answers of the system +automatically inserted into other Emacs buffers. Thus you don’t need to copy-paste the |Coq| material from your files to the |Coq| toplevel or conversely from the |Coq| toplevel to some files. -|ProofGeneral| is developed and distributed independently of the system +Proof-General is developed and distributed independently of the system |Coq|. It is freely available at `<https://proofgeneral.github.io/>`_. diff --git a/doc/sphinx/proof-engine/detailed-tactic-examples.rst b/doc/sphinx/proof-engine/detailed-tactic-examples.rst index 932f967881..84810ddba5 100644 --- a/doc/sphinx/proof-engine/detailed-tactic-examples.rst +++ b/doc/sphinx/proof-engine/detailed-tactic-examples.rst @@ -6,6 +6,8 @@ Detailed examples of tactics This chapter presents detailed examples of certain tactics, to illustrate their behavior. +.. _dependent-induction: + dependent induction ------------------- @@ -316,7 +318,7 @@ explicit proof terms: This concludes our example. -See also: The ``induction`` :ref:`TODO-9-induction`, ``case`` :ref:`TODO-9-induction` and ``inversion`` :ref:`TODO-8.14-inversion` tactics. +See also: The :tacn:`induction`, :tacn:`case`, and :tacn:`inversion` tactics. autorewrite @@ -403,6 +405,8 @@ Example 2: Mac Carthy function autorewrite with base1 using reflexivity || simpl. +.. _quote: + quote ----- @@ -544,8 +548,7 @@ Combining variables and constants ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ One can have both variables and constants in abstracts terms; for -example, this is the case for the ``ring`` tactic -:ref:`TODO-25-ringandfieldtacticfamilies`. Then one must provide to +example, this is the case for the :tacn:`ring` tactic. Then one must provide to ``quote`` a list of *constructors of constants*. For example, if the list is ``[O S]`` then closed natural numbers will be considered as constants and other terms as variables. @@ -606,7 +609,7 @@ don’t expect miracles from it! See also: comments of source file ``plugins/quote/quote.ml`` -See also: the ``ring`` tactic :ref:`TODO-25-ringandfieldtacticfamilies` +See also: the :tacn:`ring` tactic. Using the tactical language @@ -733,7 +736,7 @@ and this length is decremented for each rotation down to, but not including, 1 because for a list of length ``n``, we can make exactly ``n−1`` rotations to generate at most ``n`` distinct lists. Here, it must be noticed that we use the natural numbers of Coq for the -rotation counter. On Figure :ref:`TODO-9.1-tactic-language`, we can +rotation counter. In :ref:`ltac-syntax`, we can see that it is possible to use usual natural numbers but they are only used as arguments for primitive tactics and they cannot be handled, in particular, we cannot make computations with them. So, a natural @@ -830,7 +833,7 @@ The pattern matching on goals allows a complete and so a powerful backtracking when returning tactic values. An interesting application is the problem of deciding intuitionistic propositional logic. Considering the contraction-free sequent calculi LJT* of Roy Dyckhoff -:ref:`TODO-56-biblio`, it is quite natural to code such a tactic +:cite:`Dyc92`, it is quite natural to code such a tactic using the tactic language as shown on figures: :ref:`Deciding intuitionistic propositions (1) <decidingintuitionistic1>` and :ref:`Deciding intuitionistic propositions (2) @@ -868,7 +871,7 @@ Deciding type isomorphisms A more tricky problem is to decide equalities between types and modulo isomorphisms. Here, we choose to use the isomorphisms of the simply typed λ-calculus with Cartesian product and unit type (see, for -example, [:ref:`TODO-45`]). The axioms of this λ-calculus are given below. +example, :cite:`RC95`). The axioms of this λ-calculus are given below. .. coqtop:: in reset diff --git a/doc/sphinx/proof-engine/ltac.rst b/doc/sphinx/proof-engine/ltac.rst index 003d4b2438..247d5d899c 100644 --- a/doc/sphinx/proof-engine/ltac.rst +++ b/doc/sphinx/proof-engine/ltac.rst @@ -13,33 +13,34 @@ especially about its foundations, you can refer to :cite:`Del00`. Chapter :ref:`detailedexamplesoftactics` is devoted to giving examples of use of this language on small but also with non-trivial problems. +.. _ltac-syntax: + Syntax ------ -The syntax of the tactic language is given Figures :ref:`ltac, ltac_aux`. See -Chapter :ref:`gallina` for a description of the BNF metasyntax used in these -grammar rules. Various already defined entries will be used in this chapter: -entries :token:`natural`, :token:`integer`, :token:`ident`, :token:`qualid`, -:token:`term`, :token:`cpattern` and :token:`atomic_tactic` represent -respectively the natural and integer numbers, the authorized identificators and -qualified names, Coq terms and patterns and all the atomic tactics described in -Chapter :ref:`tactics`. The syntax of :token:`cpattern` is the same as that of -terms, but it is extended with pattern matching metavariables. In -:token:`cpattern`, a pattern-matching metavariable is represented with the -syntax :g:`?id` where :g:`id` is an :token:`ident`. The notation :g:`_` can also -be used to denote metavariable whose instance is irrelevant. In the notation -:g:`?id`, the identifier allows us to keep instantiations and to make -constraints whereas :g:`_` shows that we are not interested in what will be -matched. On the right hand side of pattern-matching clauses, the named -metavariable are used without the question mark prefix. There is also a special -notation for second-order pattern-matching problems: in an applicative pattern -of the form :g:`@?id id1 … idn`, the variable id matches any complex expression -with (possible) dependencies in the variables :g:`id1 … idn` and returns a -functional term of the form :g:`fun id1 … idn => term`. +The syntax of the tactic language is given below. See Chapter +:ref:`gallinaspecificationlanguage` for a description of the BNF metasyntax used +in these grammar rules. Various already defined entries will be used in this +chapter: entries :token:`natural`, :token:`integer`, :token:`ident`, +:token:`qualid`, :token:`term`, :token:`cpattern` and :token:`atomic_tactic` +represent respectively the natural and integer numbers, the authorized +identificators and qualified names, Coq terms and patterns and all the atomic +tactics described in Chapter :ref:`tactics`. The syntax of :token:`cpattern` is +the same as that of terms, but it is extended with pattern matching +metavariables. In :token:`cpattern`, a pattern-matching metavariable is +represented with the syntax :g:`?id` where :g:`id` is an :token:`ident`. The +notation :g:`_` can also be used to denote metavariable whose instance is +irrelevant. In the notation :g:`?id`, the identifier allows us to keep +instantiations and to make constraints whereas :g:`_` shows that we are not +interested in what will be matched. On the right hand side of pattern-matching +clauses, the named metavariable are used without the question mark prefix. There +is also a special notation for second-order pattern-matching problems: in an +applicative pattern of the form :g:`@?id id1 … idn`, the variable id matches any +complex expression with (possible) dependencies in the variables :g:`id1 … idn` +and returns a functional term of the form :g:`fun id1 … idn => term`. The main entry of the grammar is :n:`@expr`. This language is used in proof -mode but it can also be used in toplevel definitions as shown in -Figure :ref:`ltactop`. +mode but it can also be used in toplevel definitions as shown below. .. note:: @@ -153,6 +154,8 @@ Figure :ref:`ltactop`. ltac_def : `ident` [`ident` ... `ident`] := `expr` : | `qualid` [`ident` ... `ident`] ::= `expr` +.. _ltac-semantics: + Semantics --------- @@ -228,6 +231,8 @@ following form: independently. All the above variants work in this form too. Formally, :n:`@expr ; [ ... ]` is equivalent to :n:`[> @expr ; [> ... ] .. ]`. +.. _goal-selectors: + Goal selectors ~~~~~~~~~~~~~~ @@ -247,7 +252,7 @@ focused goals with: .. tacv:: [@ident] : @expr In this variant, :n:`@expr` is applied locally to a goal previously named - by the user (see :ref:`ExistentialVariables`). + by the user (see :ref:`existential-variables`). .. tacv:: @num : @expr @@ -275,6 +280,9 @@ focused goals with: the toplevel of a tactic expression. .. exn:: No such goal + :name: No such goal (goal selector) + + .. TODO change error message index entry For loop ~~~~~~~~ @@ -759,7 +767,7 @@ We can carry out pattern matching on terms with: matching subterm is tried. If no further subterm matches, the next clause is tried. Matching subterms are considered top-bottom and from left to right (with respect to the raw printing obtained by setting option - ``Printing All``, see Section :ref:`SetPrintingAll`). + :opt:`Printing All`). .. example:: @@ -775,6 +783,8 @@ We can carry out pattern matching on terms with: Goal True. f (3+4). +.. _ltac-match-goal: + Pattern matching on goals ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1009,6 +1019,7 @@ Proving a subgoal as a separate lemma don’t play well with asynchronous proofs. .. exn:: Proof is not complete + :name: Proof is not complete (abstract) Tactic toplevel definitions --------------------------- @@ -1253,4 +1264,4 @@ Run-time optimization tactic This tactic behaves like :n:`idtac`, except that running it compacts the heap in the OCaml run-time system. It is analogous to the Vernacular -command ``Optimize Heap`` (see :ref:`vernac-optimizeheap`). +command :cmd:`Optimize Heap`. diff --git a/doc/sphinx/proof-engine/proof-handling.rst b/doc/sphinx/proof-engine/proof-handling.rst index adf3da3ebb..a77b127ebe 100644 --- a/doc/sphinx/proof-engine/proof-handling.rst +++ b/doc/sphinx/proof-engine/proof-handling.rst @@ -20,20 +20,18 @@ prove. Initially, the list consists only in the theorem itself. After having applied some tactics, the list of goals contains the subgoals generated by the tactics. -To each subgoal is associated a number of hypotheses called the *local -context* of the goal. Initially, the local context contains the local -variables and hypotheses of the current section (see Section :ref:`TODO_gallina_assumptions`) -and the local variables and hypotheses of the theorem statement. It is -enriched by the use of certain tactics (see e.g. ``intro`` in Section -:ref:`managingthelocalcontext`). +To each subgoal is associated a number of hypotheses called the *local context* +of the goal. Initially, the local context contains the local variables and +hypotheses of the current section (see Section :ref:`gallina-assumptions`) and +the local variables and hypotheses of the theorem statement. It is enriched by +the use of certain tactics (see e.g. :tacn:`intro`). When a proof is completed, the message ``Proof completed`` is displayed. One can then register this proof as a defined constant in the environment. Because there exists a correspondence between proofs and -terms of λ-calculus, known as the *Curry-Howard isomorphism* [[How80]_, -[Bar81]_, [Gir89]_, [Hue88]_ ], |Coq| -stores proofs as terms of |Cic|. Those terms -are called *proof terms*. +terms of λ-calculus, known as the *Curry-Howard isomorphism* +:cite:`How80,Bar81,Gir89,Hue88`, |Coq| stores proofs as terms of |Cic|. Those +terms are called *proof terms*. .. exn:: No focused proof @@ -41,16 +39,15 @@ are called *proof terms*. Coq raises this error message when one attempts to use a proof editing command out of the proof editing mode. +.. _proof-editing-mode: + Switching on/off the proof editing mode ------------------------------------------- -The proof editing mode is entered by asserting a statement, which -typically is the assertion of a theorem: - -.. cmd:: Theorem @ident [@binders] : @form. - -The list of assertion commands is given in Section :ref:TODO-assertions_and_proof`. The -command ``Goal`` can also be used. +The proof editing mode is entered by asserting a statement, which typically is +the assertion of a theorem using an assertion command like :cmd:`Theorem`. The +list of assertion commands is given in Section :ref:`Assertions`. The command +:cmd:`Goal` can also be used. .. cmd:: Goal @form. @@ -93,14 +90,13 @@ Forces the name of the original goal to be :n:`@ident`. This command (and the following ones) can only be used if the original goal has been opened using the ``Goal`` command. - .. cmd:: Admitted. This command is available in interactive editing proof mode to give up the current proof and declare the initial goal as an axiom. - .. cmd:: Proof @term. + :name: Proof `term` This command applies in proof editing mode. It is equivalent to @@ -119,13 +115,13 @@ closing ``Qed``. See also: ``Proof with tactic.`` in Section -:ref:`setimpautotactics`. +:ref:`tactics-implicit-automation`. .. cmd:: Proof using @ident1 ... @identn. This command applies in proof editing mode. It declares the set of -section variables (see :ref:`TODO-gallina-assumptions`) used by the proof. At ``Qed`` time, the +section variables (see :ref:`gallina-assumptions`) used by the proof. At ``Qed`` time, the system will assert that the set of section variables actually used in the proof is a subset of the declared one. @@ -136,7 +132,7 @@ example if ``T`` is variable and a is a variable of type ``T``, the commands .. cmdv:: Proof using @ident1 ... @identn with @tactic. -in Section :ref:`setimpautotactics`. +in Section :ref:`tactics-implicit-automation`. .. cmdv:: Proof using All. @@ -262,11 +258,11 @@ Existentials`` (described in Section :ref:`requestinginformation`). This command is intended to be used to instantiate existential variables when the proof is completed but some uninstantiated existential variables remain. To instantiate existential variables -during proof edition, you should use the tactic instantiate. +during proof edition, you should use the tactic :tacn:`instantiate`. See also: ``instantiate (num:= term).`` in Section -:ref:`TODO-controllingtheproofflow`. +:ref:`controllingtheproofflow`. See also: ``Grab Existential Variables.`` below. @@ -327,6 +323,7 @@ last ``Focus`` command. Succeeds if the proof is fully unfocused, fails is there are some goals out of focus. +.. _curly-braces: .. cmd:: %{ %| %} @@ -351,12 +348,14 @@ Error messages: You are trying to use ``}`` but the current subproof has not been fully solved. .. exn:: No such goal + :name: No such goal (focusing) .. exn:: Brackets only support the single numbered goal selector - See also error messages about bullets below. +.. _bullets: + Bullets ``````` @@ -434,6 +433,7 @@ This makes bullets inactive. This makes bullets active (this is the default behavior). +.. _requestinginformation: Requesting information ---------------------- @@ -456,7 +456,7 @@ Displays only the :n:`@num`-th subgoal. Displays the named goal :n:`@ident`. This is useful in particular to display a shelved goal but only works if the corresponding existential variable has been named by the user -(see :ref:`exvariables`) as in the following example. +(see :ref:`existential-variables`) as in the following example. .. example:: @@ -536,7 +536,7 @@ debugging universe inconsistencies. .. cmd:: Guarded. -Some tactics (e.g. refine :ref:`applyingtheorems`) allow to build proofs using +Some tactics (e.g. :tacn:`refine` :ref:`applyingtheorems`) allow to build proofs using fixpoint or co-fixpoint constructions. Due to the incremental nature of interactive proof construction, the check of the termination (or guardedness) of the recursive calls in the fixpoint or cofixpoint @@ -591,4 +591,4 @@ the ongoing proof. This command forces the |OCaml| runtime to perform a heap compaction. This is in general an expensive operation. See: `OCaml Gc <http://caml.inria.fr/pub/docs/manual-ocaml/libref/Gc.html#VALcompact>`_ -There is also an analogous tactic ``optimize_heap`` (see~:ref:`tactic-optimizeheap`) +There is also an analogous tactic :tac:`optimize_heap`. diff --git a/doc/sphinx/proof-engine/ssreflect-proof-language.rst b/doc/sphinx/proof-engine/ssreflect-proof-language.rst index df5b362970..074c6f1e28 100644 --- a/doc/sphinx/proof-engine/ssreflect-proof-language.rst +++ b/doc/sphinx/proof-engine/ssreflect-proof-language.rst @@ -5185,6 +5185,7 @@ equivalences are indeed taken into account, otherwise only single |SSR| proposes an extension of the Search command. Its syntax is: .. cmd:: Search {? @pattern } {* {? - } %( @string %| @pattern %) {? % @ident} } {? in {+ {? - } @qualid } } + :name: Search (ssreflect) where :token:`qualid` is the name of an open module. This command returns the list of lemmas: diff --git a/doc/sphinx/proof-engine/tactics.rst b/doc/sphinx/proof-engine/tactics.rst index 2af73c28e5..08aa7110d1 100644 --- a/doc/sphinx/proof-engine/tactics.rst +++ b/doc/sphinx/proof-engine/tactics.rst @@ -24,7 +24,7 @@ Each (sub)goal is denoted with a number. The current goal is numbered 1. By default, a tactic is applied to the current goal, but one can address a particular goal in the list by writing n:tactic which means “apply tactic tactic to goal number n”. We can show the list of -subgoals by typing Show (see Section :ref:`TODO-7.3.1-Show`). +subgoals by typing Show (see Section :ref:`requestinginformation`). Since not every rule applies to a given statement, every tactic cannot be used to reduce any goal. In other words, before applying a tactic @@ -34,15 +34,16 @@ satisfied. If it is not the case, the tactic raises an error message. Tactics are built from atomic tactics and tactic expressions (which extends the folklore notion of tactical) to combine those atomic tactics. This chapter is devoted to atomic tactics. The tactic -language will be described in Chapter :ref:`TODO-9-Thetacticlanguage`. +language will be described in Chapter :ref:`ltac`. + +.. _invocation-of-tactics: Invocation of tactics ------------------------- A tactic is applied as an ordinary command. It may be preceded by a -goal selector (see Section :ref:`TODO-9.2-Semantics`). If no selector is -specified, the default selector (see Section -:ref:`TODO-8.1.1-Setdefaultgoalselector`) is used. +goal selector (see Section :ref:`ltac-semantics`). If no selector is +specified, the default selector is used. .. _tactic_invocation_grammar: @@ -94,7 +95,7 @@ bindings_list`` where ``bindings_list`` may be of two different forms: + A bindings list can also be a simple list of terms :n:`{* term}`. In that case the references to which these terms correspond are determined by the tactic. In case of ``induction``, ``destruct``, ``elim`` - and ``case`` (see :ref:`TODO-9-Thetacticlanguage`) the terms have to + and ``case`` (see :ref:`ltac`) the terms have to provide instances for all the dependent products in the type of term while in the case of ``apply``, or of ``constructor`` and its variants, only instances for the dependent products that are not bound in the conclusion of the type @@ -126,9 +127,9 @@ occurrences have to be selected in the hypotheses named :n:`@ident`. If no numbe are given for hypothesis :n:`@ident`, then all the occurrences of `term` in the hypothesis are selected. If numbers are given, they refer to occurrences of `term` when the term is printed using option ``Set Printing All`` (see -:ref:`TODO-2.9-Printingconstructionsinfull`), counting from left to right. In +:ref:`printing_constructions_full`), counting from left to right. In particular, occurrences of `term` in implicit arguments (see -:ref:`TODO-2.7-Implicitarguments`) or coercions (see :ref:`TODO-2.8-Coercions`) +:ref:`ImplicitArguments`) or coercions (see :ref:`Coercions`) are counted. If a minus sign is given between at and the list of occurrences, it @@ -154,10 +155,11 @@ Here are some tactics that understand occurrences clauses: ``set``, ``remember`` , ``induction``, ``destruct``. -See also: :ref:`TODO-8.3.7-Managingthelocalcontext`, -:ref:`TODO-8.5.2-Caseanalysisandinduction`, -:ref:`TODO-2.9-Printingconstructionsinfull`. +See also: :ref:`Managingthelocalcontext`, +:ref:`caseanalysisandinduction`, +:ref:`printing_constructions_full`. +.. _applyingtheorems: Applying theorems --------------------- @@ -168,7 +170,7 @@ Applying theorems This tactic applies to any goal. It gives directly the exact proof term of the goal. Let ``T`` be our goal, let ``p`` be a term of type ``U`` then ``exact p`` succeeds iff ``T`` and ``U`` are convertible (see -:ref:`TODO-4.3-Conversionrules`). +:ref:`Conversion-rules`). .. exn:: Not an exact proof. @@ -277,7 +279,7 @@ gets the form :g:`(fun x => Q) u`:sub:`1` :g:`...` :g:`u`:sub:`n`. The apply tactic failed to match the conclusion of term and the current goal. You can help the apply tactic by transforming your goal with the -:ref:`change <change_term>` or :tacn:`pattern` tactics. +:tacn:`change` or :tacn:`pattern` tactics. .. exn:: Unable to find an instance for the variables {+ @ident}. @@ -285,7 +287,7 @@ This occurs when some instantiations of the premises of term are not deducible from the unification. This is the case, for instance, when you want to apply a transitivity property. In this case, you have to use one of the variants below: -.. cmd:: apply @term with {+ @term} +.. tacv:: apply @term with {+ @term} Provides apply with explicit instantiations for all dependent premises of the type of term that do not occur in the conclusion and consequently cannot be @@ -314,7 +316,7 @@ generated by ``apply term``:sub:`i` , starting from the application of The tactic ``eapply`` behaves like ``apply`` but it does not fail when no instantiations are deducible for some variables in the premises. Rather, it turns these variables into existential variables which are variables still to -instantiate (see :ref:`TODO-2.11-ExistentialVariables`). The instantiation is +instantiate (see :ref:`Existential-Variables`). The instantiation is intended to be found later in the proof. .. tacv:: simple apply @term. @@ -598,7 +600,7 @@ Managing the local context This tactic applies to a goal that is either a product or starts with a let binder. If the goal is a product, the tactic implements the "Lam" rule given in -:ref:`TODO-4.2-Typing-rules` [1]_. If the goal starts with a let binder, then the +:ref:`Typing-rules` [1]_. If the goal starts with a let binder, then the tactic implements a mix of the "Let" and "Conv". If the current goal is a dependent product :math:`\forall` :g:`x:T, U` (resp @@ -632,14 +634,14 @@ be applied or the goal is not head-reducible. .. note:: If a name used by intro hides the base name of a global constant then the latter can still be referred to by a qualified name - (see :ref:`TODO-2.6.2-Qualified-names`). + (see :ref:`Qualified-names`). .. tacv:: intros {+ @ident}. This is equivalent to the composed tactic :n:`intro @ident; ... ; intro @ident`. More generally, the ``intros`` tactic takes a pattern as argument in order to introduce names for components of an inductive definition or to clear introduced hypotheses. This is - explained in :ref:`TODO-8.3.2`. + explained in :ref:`Managingthelocalcontext`. .. tacv:: intros until @ident @@ -1067,7 +1069,7 @@ The name of the hypothesis in the proof-term, however, is left unchanged. This decomposes record types (inductive types with one constructor, like "and" and "exists" and those defined with the Record macro, see - :ref:`TODO-2.1`). + :ref:`record-types`). .. _controllingtheproofflow: @@ -1089,7 +1091,7 @@ Controlling the proof flow .. tacv:: assert form - This behaves as :n:`assert (@ident : form ) but :n:`@ident` is generated by + This behaves as :n:`assert (@ident : form)` but :n:`@ident` is generated by Coq. .. tacv:: assert form by tactic @@ -1098,6 +1100,7 @@ Controlling the proof flow generated by assert. .. exn:: Proof is not complete + :name: Proof is not complete (assert) .. tacv:: assert form as intro_pattern @@ -1177,7 +1180,7 @@ Controlling the proof flow .. tacv:: cut form This tactic applies to any goal. It implements the non-dependent case of - the “App” rule given in :ref:`TODO-4.2`. (This is Modus Ponens inference + the “App” rule given in :ref:`typing-rules`. (This is Modus Ponens inference rule.) :n:`cut U` transforms the current goal :g:`T` into the two following subgoals: :g:`U -> T` and :g:`U`. The subgoal :g:`U -> T` comes first in the list of remaining subgoal to prove. @@ -1268,7 +1271,7 @@ name of the variable (here :g:`n`) is chosen based on :g:`T`. :n:`refine @term` (preferred alternative). .. note:: To be able to refer to an existential variable by name, the user - must have given the name explicitly (see :ref:`TODO-2.11`). + must have given the name explicitly (see :ref:`Existential-Variables`). .. note:: When you are referring to hypotheses which you did not name explicitly, be aware that Coq may make a different decision on how to @@ -1353,11 +1356,13 @@ goals cannot be closed with :g:`Qed` but only with :g:`Admitted`. then required to prove that False is indeed provable in the current context. This tactic is a macro for :n:`elimtype False`. +.. _CaseAnalysisAndInduction: + Case analysis and induction ------------------------------- The tactics presented in this section implement induction or case -analysis on inductive or co-inductive objects (see :ref:`TODO-4.5`). +analysis on inductive or co-inductive objects (see :ref:`inductive-definitions`). .. tacn:: destruct @term :name: destruct @@ -1746,7 +1751,7 @@ analysis on inductive or co-inductive objects (see :ref:`TODO-4.5`). results equivalent to ``inversion`` or ``dependent inversion`` if the hypothesis is dependent. -See also :ref:`TODO-10.1-dependentinduction` for a larger example of ``dependent induction`` +See also the larger example of :tacn:`dependent induction` and an explanation of the underlying technique. .. tacn:: function induction (@qualid {+ @term}) @@ -1754,8 +1759,8 @@ and an explanation of the underlying technique. The tactic functional induction performs case analysis and induction following the definition of a function. It makes use of a principle - generated by ``Function`` (see :ref:`TODO-2.3-Advancedrecursivefunctions`) or - ``Functional Scheme`` (see :ref:`TODO-13.2-Generationofinductionschemeswithfunctionalscheme`). + generated by ``Function`` (see :ref:`advanced-recursive-functions`) or + ``Functional Scheme`` (see :ref:`functional-scheme`). Note that this tactic is only available after a .. example:: @@ -1781,22 +1786,22 @@ and an explanation of the underlying technique. :n:`functional induction (f x1 x2 x3)` is actually a wrapper for :n:`induction x1, x2, x3, (f x1 x2 x3) using @qualid` followed by a cleaning phase, where :n:`@qualid` is the induction principle registered for :g:`f` - (by the ``Function`` (see :ref:`TODO-2.3-Advancedrecursivefunctions`) or - ``Functional Scheme`` (see :ref:`TODO-13.2-Generationofinductionschemeswithfunctionalscheme`) + (by the ``Function`` (see :ref:`advanced-recursive-functions`) or + ``Functional Scheme`` (see :ref:`functional-scheme`) command) corresponding to the sort of the goal. Therefore ``functional induction`` may fail if the induction scheme :n:`@qualid` is not - defined. See also :ref:`TODO-2.3-Advancedrecursivefunctions` for the function + defined. See also :ref:`advanced-recursive-functions` for the function terms accepted by ``Function``. .. note:: There is a difference between obtaining an induction scheme - for a function by using :g:`Function` (see :ref:`TODO-2.3-Advancedrecursivefunctions`) + for a function by using :g:`Function` (see :ref:`advanced-recursive-functions`) and by using :g:`Functional Scheme` after a normal definition using - :g:`Fixpoint` or :g:`Definition`. See :ref:`TODO-2.3-Advancedrecursivefunctions` + :g:`Fixpoint` or :g:`Definition`. See :ref:`advanced-recursive-functions` for details. -See also: :ref:`TODO-2.3-Advancedrecursivefunctions` - :ref:`TODO-13.2-Generationofinductionschemeswithfunctionalscheme` +See also: :ref:`advanced-recursive-functions` + :ref:`functional-scheme` :tacn:`inversion` .. exn:: Cannot find induction information on @qualid @@ -1902,7 +1907,7 @@ injected object has a dependent type :g:`P` with its two instances in different types :g:`(P t`:sub:`1` :g:`... t`:sub:`n` :g:`)` and :g:`(P u`:sub:`1` :g:`... u`:sub:`n` :sub:`)`. If :g:`t`:sub:`1` and :g:`u`:sub:`1` are the same and have for type an inductive type for which a decidable -equality has been declared using the command ``Scheme Equality`` (see :ref:`TODO-13.1-GenerationofinductionprincipleswithScheme`), +equality has been declared using the command ``Scheme Equality`` (see :ref:`proofschemes-induction-principles`), the use of a sigma type is avoided. .. note:: @@ -1984,7 +1989,7 @@ turned off by setting the option ``Set Keep Proof Equalities``. .. note:: As ``inversion`` proofs may be large in size, we recommend the user to stock the lemmas whenever the same instance needs to be - inverted several times. See :ref:`TODO-13.3-Generationofinversionprincipleswithderiveinversion`. + inverted several times. See :ref:`derive-inversion`. .. note:: Part of the behavior of the ``inversion`` tactic is to generate @@ -2300,7 +2305,7 @@ turned off by setting the option ``Set Keep Proof Equalities``. arguments are correct is done only at the time of registering the lemma in the environment. To know if the use of induction hypotheses is correct at some time of the interactive development of a proof, use - the command ``Guarded`` (see :ref:`TODO-7.3.2-Guarded`). + the command ``Guarded`` (see Section :ref:`requestinginformation`). .. tacv:: fix @ident @num with {+ (ident {+ @binder} [{struct @ident}] : @type)} @@ -2321,7 +2326,7 @@ turned off by setting the option ``Set Keep Proof Equalities``. done only at the time of registering the lemma in the environment. To know if the use of coinduction hypotheses is correct at some time of the interactive development of a proof, use the command ``Guarded`` - (see :ref:`TODO-7.3.2-Guarded`). + (see Section :ref:`requestinginformation`). .. tacv:: cofix @ident with {+ (@ident {+ @binder} : @type)} @@ -2335,7 +2340,7 @@ Rewriting expressions --------------------- These tactics use the equality :g:`eq:forall A:Type, A->A->Prop` defined in -file ``Logic.v`` (see :ref:`TODO-3.1.2-Logic`). The notation for :g:`eq T t u` is +file ``Logic.v`` (see :ref:`coq-library-logic`). The notation for :g:`eq T t u` is simply :g:`t=u` dropping the implicit type of :g:`t` and :g:`u`. .. tacn:: rewrite @term @@ -2546,7 +2551,7 @@ then replaces the goal by :n:`R @term @term` and adds a new goal stating Lemmas are added to the database using the command ``Declare Left Step @term.`` The tactic is especially useful for parametric setoids which are not accepted as regular setoids for :tacn:`rewrite` and :tacn:`setoid_replace` (see -:ref:`TODO-27-Generalizedrewriting`). +:ref:`Generalizedrewriting`). .. tacv:: stepl @term by tactic @@ -2564,7 +2569,7 @@ as regular setoids for :tacn:`rewrite` and :tacn:`setoid_replace` (see :name: change This tactic applies to any goal. It implements the rule ``Conv`` given in - :ref:`TODO-4.4-Subtypingrules`. :g:`change U` replaces the current goal `T` + :ref:`subtyping-rules`. :g:`change U` replaces the current goal `T` with `U` providing that `U` is well-formed and that `T` and `U` are convertible. @@ -2637,7 +2642,7 @@ the conversion in hypotheses :n:`{+ @ident}`. the normalization of the goal according to the specified flags. In correspondence with the kinds of reduction considered in Coq namely :math:`\beta` (reduction of functional application), :math:`\delta` - (unfolding of transparent constants, see :ref:`TODO-6.10.2-Transparent`), + (unfolding of transparent constants, see :ref:`vernac-controlling-the-reduction-strategies`), :math:`\iota` (reduction of pattern-matching over a constructed term, and unfolding of :g:`fix` and :g:`cofix` expressions) and :math:`\zeta` (contraction of local definitions), the @@ -2649,7 +2654,7 @@ the conversion in hypotheses :n:`{+ @ident}`. second case the constant to unfold to all but the ones explicitly mentioned. Notice that the ``delta`` flag does not apply to variables bound by a let-in construction inside the :n:`@term` itself (use here the ``zeta`` flag). In - any cases, opaque constants are not unfolded (see :ref:`TODO-6.10.1-Opaque`). + any cases, opaque constants are not unfolded (see :ref:`vernac-controlling-the-reduction-strategies`). Normalization according to the flags is done by first evaluating the head of the expression into a *weak-head* normal form, i.e. until the @@ -2768,7 +2773,7 @@ the conversion in hypotheses :n:`{+ @ident}`. :n:`hnf`. .. note:: - The :math:`\delta` rule only applies to transparent constants (see :ref:`TODO-6.10.1-Opaque` + The :math:`\delta` rule only applies to transparent constants (see :ref:`vernac-controlling-the-reduction-strategies` on transparency and opacity). .. tacn:: cbn @@ -2906,7 +2911,7 @@ the conversion in hypotheses :n:`{+ @ident}`. This tactic applies to any goal. The argument qualid must denote a defined transparent constant or local definition (see - :ref:`TODO-1.3.2-Definitions` and :ref:`TODO-6.10.2-Transparent`). The tactic + :ref:`gallina-definitions` and :ref:`vernac-controlling-the-reduction-strategies`). The tactic ``unfold`` applies the :math:`\delta` rule to each occurrence of the constant to which :n:`@qualid` refers in the current goal and then replaces it with its :math:`\beta`:math:`\iota`-normal form. @@ -2942,7 +2947,7 @@ the conversion in hypotheses :n:`{+ @ident}`. This is variant of :n:`unfold @string` where :n:`@string` gets its interpretation from the scope bound to the delimiting key :n:`key` - instead of its default interpretation (see :ref:`TODO-12.2.2-Localinterpretationrulesfornotations`). + instead of its default interpretation (see :ref:`Localinterpretationrulesfornotations`). .. tacv:: unfold {+, qualid_or_string at {+, @num}} This is the most general form, where :n:`qualid_or_string` is either a @@ -3389,7 +3394,7 @@ The ``hint_definition`` is one of the following expressions: + :n:`Cut @regexp` .. warning:: these hints currently only apply to typeclass - proof search and the ``typeclasses eauto`` tactic (:ref:`TODO-20.6.5-typeclasseseauto`). + proof search and the ``typeclasses eauto`` tactic (:ref:`typeclasses-eauto`). This command can be used to cut the proof-search tree according to a regular expression matching paths to be cut. The grammar for regular expressions is @@ -3521,7 +3526,7 @@ at every moment. (left to right). Notice that the rewriting bases are distinct from the ``auto`` hint bases and thatauto does not take them into account. - This command is synchronous with the section mechanism (see :ref:`TODO-2.4-Sectionmechanism`): + This command is synchronous with the section mechanism (see :ref:`section-mechanism`): when closing a section, all aliases created by ``Hint Rewrite`` in that section are lost. Conversely, when loading a module, all ``Hint Rewrite`` declarations at the global level of that module are loaded. @@ -3592,6 +3597,8 @@ non-imported hints. When set, it changes the behavior of an unloaded hint to a immediate fail tactic, allowing to emulate an import-scoped hint mechanism. +.. _tactics-implicit-automation: + Setting implicit automation tactics ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3602,40 +3609,37 @@ Setting implicit automation tactics In this case the tactic command typed by the user is equivalent to ``tactic``:sub:`1` ``;tactic``. -See also: Proof. in :ref:`TODO-7.1.4-Proofterm`. - -**Variants:** + See also: ``Proof.`` in :ref:`proof-editing-mode`. -.. cmd:: Proof with tactic using {+ @ident} - Combines in a single line ``Proof with`` and ``Proof using``, see :ref:`TODO-7.1.5-Proofusing` + .. cmdv:: Proof with tactic using {+ @ident} -.. cmd:: Proof using {+ @ident} with tactic + Combines in a single line ``Proof with`` and ``Proof using``, see :ref:`proof-editing-mode` - Combines in a single line ``Proof with`` and ``Proof using``, see :ref:`TODO-7.1.5-Proofusing` + .. cmdv:: Proof using {+ @ident} with tactic -.. cmd:: Declare Implicit Tactic tactic + Combines in a single line ``Proof with`` and ``Proof using``, see :ref:`proof-editing-mode` - This command declares a tactic to be used to solve implicit arguments - that Coq does not know how to solve by unification. It is used every - time the term argument of a tactic has one of its holes not fully - resolved. + .. cmd:: Declare Implicit Tactic tactic -Here is an example: + This command declares a tactic to be used to solve implicit arguments + that Coq does not know how to solve by unification. It is used every + time the term argument of a tactic has one of its holes not fully + resolved. -.. example:: + .. example:: - .. coqtop:: all + .. coqtop:: all - Parameter quo : nat -> forall n:nat, n<>0 -> nat. - Notation "x // y" := (quo x y _) (at level 40). - Declare Implicit Tactic assumption. - Goal forall n m, m<>0 -> { q:nat & { r | q * m + r = n } }. - intros. - exists (n // m). + Parameter quo : nat -> forall n:nat, n<>0 -> nat. + Notation "x // y" := (quo x y _) (at level 40). + Declare Implicit Tactic assumption. + Goal forall n m, m<>0 -> { q:nat & { r | q * m + r = n } }. + intros. + exists (n // m). - The tactic ``exists (n // m)`` did not fail. The hole was solved - by ``assumption`` so that it behaved as ``exists (quo n m H)``. + The tactic ``exists (n // m)`` did not fail. The hole was solved + by ``assumption`` so that it behaved as ``exists (quo n m H)``. .. _decisionprocedures: @@ -3713,7 +3717,7 @@ and then uses :tacn:`auto` which completes the proof. Originally due to César Muñoz, these tactics (:tacn:`tauto` and :tacn:`intuition`) have been completely re-engineered by David Delahaye using -mainly the tactic language (see :ref:`TODO-9-thetacticlanguage`). The code is +mainly the tactic language (see :ref:`ltac`). The code is now much shorter and a significant increase in performance has been noticed. The general behavior with respect to dependent types, unfolding and introductions has slightly changed to get clearer semantics. This may lead to @@ -3878,7 +3882,7 @@ succeeds, and results in an error otherwise. .. tacv:: unify @term @term with @ident Unification takes the transparency information defined in the hint database - :n:`@ident` into account (see :ref:`the hints databases for auto and eauto <the-hints-databases-for-auto-and-eauto>`). + :n:`@ident` into account (see :ref:`the hints databases for auto and eauto <thehintsdatabasesforautoandeauto>`). .. tacn:: is_evar @term :name: is_evar @@ -4044,7 +4048,7 @@ Inversion :tacn:`functional inversion` is a tactic that performs inversion on hypothesis :n:`@ident` of the form :n:`@qualid {+ @term} = @term` or :n:`@term = @qualid {+ @term}` where :n:`@qualid` must have been defined using Function (see -:ref:`TODO-2.3-advancedrecursivefunctions`). Note that this tactic is only +:ref:`advanced-recursive-functions`). Note that this tactic is only available after a ``Require Import FunInd``. @@ -4077,7 +4081,7 @@ This kind of inversion has nothing to do with the tactic :tacn:`inversion` above. This tactic does :g:`change (@ident t)`, where `t` is a term built in order to ensure the convertibility. In other words, it does inversion of the function :n:`@ident`. This function must be a fixpoint on a simple recursive -datatype: see :ref:`TODO-10.3-quote` for the full details. +datatype: see :ref:`quote` for the full details. .. exn:: quote: not a simple fixpoint @@ -4109,6 +4113,8 @@ using the ``Require Import`` command. Use ``classical_right`` to prove the right part of the disjunction with the assumption that the negation of left part holds. +.. _tactics-automatizing: + Automatizing ------------ @@ -4148,7 +4154,7 @@ formulas built with `~`, `\/`, `/\`, `->` on top of equalities, inequalities and disequalities on both the type :g:`nat` of natural numbers and :g:`Z` of binary integers. This tactic must be loaded by the command ``Require Import Omega``. See the additional documentation about omega -(see Chapter :ref:`TODO-21-omega`). +(see Chapter :ref:`omega`). .. tacn:: ring @@ -4168,7 +4174,7 @@ given in the conclusion of the goal by their normal forms. If no term is given, then the conclusion should be an equation and both hand sides are normalized. -See :ref:`TODO-Chapter-25-Theringandfieldtacticfamilies` for more information on +See :ref:`Theringandfieldtacticfamilies` for more information on the tactic and how to declare new ring structures. All declared field structures can be printed with the ``Print Rings`` command. @@ -4194,7 +4200,7 @@ denominators. So it produces an equation without division nor inverse. All of these 3 tactics may generate a subgoal in order to prove that denominators are different from zero. -See :ref:`TODO-Chapter-25-Theringandfieldtacticfamilies` for more information on the tactic and how to +See :ref:`Theringandfieldtacticfamilies` for more information on the tactic and how to declare new field structures. All declared field structures can be printed with the Print Fields command. @@ -4334,11 +4340,11 @@ A simple example has more value than a long explanation: The tactics macros are synchronous with the Coq section mechanism: a tactic definition is deleted from the current environment when you -close the section (see also :ref:`TODO-2.4Sectionmechanism`) where it was +close the section (see also :ref:`section-mechanism`) where it was defined. If you want that a tactic macro defined in a module is usable in the modules that require it, you should put it outside of any section. -:ref:`TODO-9-Thetacticlanguage` gives examples of more complex +:ref:`ltac` gives examples of more complex user-defined tactics. .. [1] Actually, only the second subgoal will be generated since the diff --git a/doc/sphinx/proof-engine/vernacular-commands.rst b/doc/sphinx/proof-engine/vernacular-commands.rst index 0bb6eea233..da4034fb8a 100644 --- a/doc/sphinx/proof-engine/vernacular-commands.rst +++ b/doc/sphinx/proof-engine/vernacular-commands.rst @@ -77,10 +77,11 @@ section. Flags, Options and Tables ----------------------------- -|Coq| configurability is based on flags (e.g. Set Printing All in -Section :ref:`TODO-2.9-printing-full`), options (e.g. ``Set Printing Widthinteger`` in Section -:ref:`TODO-6.9.6-set-printing-width`), or tables (e.g. ``Add Printing Record ident``, in Section -:ref:`TODO-2.2.4-add-printing-record`). The names of flags, options and tables are made of non-empty sequences of identifiers +|Coq| configurability is based on flags (e.g. ``Set Printing All`` in +Section :ref:`printing_constructions_full`), options (e.g. ``Set Printing Widthinteger`` in Section +:ref:`controlling-display`), or tables (e.g. ``Add Printing Record ident``, in Section +:ref:`record-types`). +The names of flags, options and tables are made of non-empty sequences of identifiers (conventionally with capital initial letter). The general commands handling flags, options and tables are given below. @@ -95,7 +96,6 @@ when the current module ends. Variants: - .. cmdv:: Local Set @flag. This command switches :n:`@flag` on. The original state @@ -228,7 +228,7 @@ Variants: .. cmdv:: @selector: Check @term. specifies on which subgoal to perform typing -(see Section :ref:`TODO-8.1-invocation-of-tactics`). +(see Section :ref:`invocation-of-tactics`). .. TODO : convtactic is not a syntax entry @@ -240,7 +240,7 @@ hypothesis introduced in the first subgoal (if a proof is in progress). -See also: Section :ref:`TODO-8.7-performing-computations`. +See also: Section :ref:`performingcomputations`. .. cmd:: Compute @term. @@ -250,7 +250,7 @@ bytecode-based virtual machine. It is a shortcut for ``Eval vm_compute in`` :n:`@term`. -See also: Section :ref:`TODO-8.7-performing-computations`. +See also: Section :ref:`performingcomputations`. .. cmd::Extraction @term. @@ -258,7 +258,7 @@ See also: Section :ref:`TODO-8.7-performing-computations`. This command displays the extracted term from :n:`@term`. The extraction is processed according to the distinction between ``Set`` and ``Prop``; that is to say, between logical and computational content (see Section -:ref:`TODO-4.1.1-sorts`). The extracted term is displayed in OCaml +:ref:`sorts`). The extracted term is displayed in OCaml syntax, where global identifiers are still displayed as in |Coq| terms. @@ -272,7 +272,7 @@ Recursively extracts all the material needed for the extraction of the qualified identifiers. -See also: Chapter ref:`TODO-23-chapter-extraction`. +See also: Chapter :ref:`extraction`. .. cmd:: Print Assumptions @qualid. @@ -326,13 +326,13 @@ displays the name and type of all objects (theorems, axioms, etc) of the current context whose name contains string. If string is a notation’s string denoting some reference :n:`@qualid` (referred to by its main symbol as in `"+"` or by its notation’s string as in `"_ + _"` or -`"_ 'U' _"`, see Section :ref:`TODO-12.1-notations`), the command works like ``Search`` :n:`@qualid`. +`"_ 'U' _"`, see Section :ref:`notations`), the command works like ``Search`` :n:`@qualid`. .. cmdv:: Search @string%@key. The string string must be a notation or the main symbol of a notation which is then interpreted in the scope bound to -the delimiting key :n:`@key` (see Section :ref:`TODO-12.2.2-local-interpretation-rules-for-notations`). +the delimiting key :n:`@key` (see Section :ref:`LocalInterpretationRulesForNotations`). .. cmdv:: Search @term_pattern. @@ -364,7 +364,7 @@ This restricts the search to constructions not defined in the modules named by t .. cmdv:: @selector: Search [-]@term_pattern_string … [-]@term_pattern_string. This specifies the goal on which to search hypothesis (see -Section :ref:`TODO-8.1-invocation-of-tactics`). +Section :ref:`invocation-of-tactics`). By default the 1st goal is searched. This variant can be combined with other variants presented here. @@ -382,11 +382,11 @@ be combined with other variants presented here. Search (?x * _ + ?x * _)%Z outside OmegaLemmas. .. note:: Up to |Coq| version 8.4, ``Search`` had the behavior of current -``SearchHead`` and the behavior of current Search was obtained with -command ``SearchAbout``. For compatibility, the deprecated name -SearchAbout can still be used as a synonym of Search. For -compatibility, the list of objects to search when using ``SearchAbout`` -may also be enclosed by optional[ ] delimiters. + ``SearchHead`` and the behavior of current Search was obtained with + command ``SearchAbout``. For compatibility, the deprecated name + SearchAbout can still be used as a synonym of Search. For + compatibility, the list of objects to search when using ``SearchAbout`` + may also be enclosed by optional ``[ ]`` delimiters. .. cmd:: SearchHead @term. @@ -420,12 +420,12 @@ Error messages: .. exn:: Module/section @qualid not found No module :n:`@qualid` has been required -(see Section :ref:`TODO-6.5.1-require`). +(see Section :ref:`compiled-files`). .. cmdv:: @selector: SearchHead @term. This specifies the goal on which to -search hypothesis (see Section :ref:`TODO-8.1-invocation-of-tactics`). +search hypothesis (see Section :ref:`invocation-of-tactics`). By default the 1st goal is searched. This variant can be combined with other variants presented here. @@ -479,7 +479,7 @@ This restricts the search to constructions not defined in the modules named by t .. cmdv:: @selector: SearchPattern @term. This specifies the goal on which to -search hypothesis (see Section :ref:`TODO-8.1-invocation-of-tactics`). By default the 1st goal is +search hypothesis (see Section :ref:`invocation-of-tactics`). By default the 1st goal is searched. This variant can be combined with other variants presented here. @@ -514,7 +514,7 @@ This restricts the search to constructions not defined in the modules named by t .. cmdv:: @selector: SearchRewrite @term. This specifies the goal on which to -search hypothesis (see Section :ref:`TODO-8.1-invocation-of-tactics`). By default the 1st goal is +search hypothesis (see Section :ref:`invocation-of-tactics`). By default the 1st goal is searched. This variant can be combined with other variants presented here. @@ -569,7 +569,7 @@ As Locate but restricted to modules. As Locate but restricted to tactics. -See also: Section :ref:`TODO-12.1.10-LocateSymbol` +See also: Section :ref:`locating-notations` .. _loading-files: @@ -589,7 +589,7 @@ toplevel. This kind of file is called a *script* for |Coq|. The standard This command loads the file named :n:`ident`.v, searching successively in each of the directories specified in the *loadpath*. (see Section -:ref:`TODO-2.6.3-libraries-and-filesystem`) +:ref:`libraries-and-filesystem`) Files loaded this way cannot leave proofs open, and the ``Load`` command cannot be used inside a proof either. @@ -610,7 +610,7 @@ will use the default extension ``.v``. Display, while loading, the answers of |Coq| to each command (including tactics) contained in -the loaded file See also: Section :ref:`TODO-6.9.1-silent`. +the loaded file See also: Section :ref:`controlling-display`. Error messages: @@ -626,7 +626,7 @@ Compiled files ------------------ This section describes the commands used to load compiled files (see -Chapter :ref:`TODO-14-coq-commands` for documentation on how to compile a file). A compiled +Chapter :ref:`thecoqcommands` for documentation on how to compile a file). A compiled file is a particular case of module called *library file*. @@ -644,7 +644,7 @@ replayed nor rechecked. To locate the file in the file system, :n:`@qualid` is decomposed under the form `dirpath.ident` and the file `ident.vo` is searched in the physical directory of the file system that is mapped in |Coq| loadpath to the -logical path dirpath (see Section :ref:`TODO-2.6.3-libraries-and-filesystem`). The mapping between +logical path dirpath (see Section :ref:`libraries-and-filesystem`). The mapping between physical directories and logical names at the time of requiring the file must be consistent with the mapping used to compile the file. If several files match, one of them is picked in an unspecified fashion. @@ -656,7 +656,7 @@ Variants: This loads and declares the module :n:`@qualid` and its dependencies then imports the contents of :n:`@qualid` as described -in Section :ref:`TODO-2.5.8-import`.It does not import the modules on which +:ref:`here <import_qualid>`. It does not import the modules on which qualid depends unless these modules were themselves required in module :n:`@qualid` using ``Require Export``, as described below, or recursively required @@ -696,7 +696,7 @@ Error messages: The command did not find the file foo.vo. Either foo.v exists but is not compiled or foo.vo is in a -directory which is not in your LoadPath (see Section :ref:`TODO-2.6.3-libraries-and-filesystem`). +directory which is not in your LoadPath (see Section :ref:`libraries-and-filesystem`). .. exn:: Compiled library ident.vo makes inconsistent assumptions over library qualid @@ -725,12 +725,12 @@ the time it was compiled. This command is not allowed inside a module or a module type being defined. It is meant to describe a dependency between compilation units. Note however -that the commands Import and Export alone can be used inside modules -(see Section :ref:`TODO-2.5.8-import`). +that the commands ``Import`` and ``Export`` alone can be used inside modules +(see Section :ref:`Import <import_qualid>`). -See also: Chapter :ref:`TODO-14-coq-commands` +See also: Chapter :ref:`thecoqcommands` .. cmd:: Print Libraries. @@ -746,8 +746,8 @@ This commands loads the OCaml compiled files with names given by the :n:`@string` sequence (dynamic link). It is mainly used to load tactics dynamically. The files are searched into the current OCaml loadpath (see the -command ``Add ML Path`` in Section :ref:`TODO-2.6.3-libraries-and-filesystem`). Loading of OCaml files is only possible under the bytecode version of ``coqtop`` (i.e. -``coqtop`` called with option ``-byte``, see chapter :ref:`TODO-14-coq-commands`), or when |Coq| has been compiled with a +command ``Add ML Path`` in Section :ref:`libraries-and-filesystem`). Loading of OCaml files is only possible under the bytecode version of ``coqtop`` (i.e. +``coqtop`` called with option ``-byte``, see chapter :ref:`thecoqcommands`), or when |Coq| has been compiled with a version of OCaml that supports native Dynlink (≥ 3.11). @@ -774,7 +774,7 @@ Error messages: This prints the name of all OCaml modules loaded with ``Declare ML Module``. To know from where these module were loaded, the user -should use the command Locate File (see Section :ref:`TODO-6.6.10-locate-file`) +should use the command ``Locate File`` (see :ref:`here <locate-file>`) .. _loadpath: @@ -783,7 +783,7 @@ Loadpath ------------ Loadpaths are preferably managed using |Coq| command line options (see -Section `2.6.3-libraries-and-filesystem`) but there remain vernacular commands to manage them +Section `libraries-and-filesystem`) but there remain vernacular commands to manage them for practical purposes. Such commands are only meant to be issued in the toplevel, and using them in source files is discouraged. @@ -862,14 +862,14 @@ the paths that extend the :n:`@dirpath` prefix. .. cmd:: Add ML Path @string. This command adds the path :n:`@string` to the current OCaml -loadpath (see the command `Declare ML Module`` in Section :ref:`TODO-6.5-compiled-files`). +loadpath (see the command `Declare ML Module`` in Section :ref:`compiled-files`). .. cmd:: Add Rec ML Path @string. This command adds the directory :n:`@string` and all its subdirectories to the current OCaml loadpath (see the command ``Declare ML Module`` -in Section :ref:`TODO-6.5-compiled-files`). +in Section :ref:`compiled-files`). .. cmd:: Print ML Path @string. @@ -877,8 +877,9 @@ in Section :ref:`TODO-6.5-compiled-files`). This command displays the current OCaml loadpath. This command makes sense only under the bytecode version of ``coqtop``, i.e. using option ``-byte`` -(see the command Declare ML Module in Section :ref:`TODO-6.5-compiled-files`). +(see the command Declare ML Module in Section :ref:`compiled-files`). +.. _locate-file: .. cmd:: Locate File @string. @@ -929,7 +930,7 @@ of the interactive session. This commands undoes all the effects of the last vernacular command. Commands read from a vernacular file via a ``Load`` are considered as a single command. Proof management commands are also handled by this -command (see Chapter :ref:`TODO-7-proof-handling`). For that, Back may have to undo more than +command (see Chapter :ref:`proofhandling`). For that, Back may have to undo more than one command in order to reach a state where the proof management information is available. For instance, when the last command is a ``Qed``, the management information about the closed proof has been @@ -978,9 +979,9 @@ three numbers represent the following: + *first number* : State label to reach, as for BackTo. + *second number* : *Proof state number* to unbury once aborts have been done. - |Coq| will compute the number of Undo to perform (see Chapter :ref:`TODO-7-proof-handling`). + |Coq| will compute the number of Undo to perform (see Chapter :ref:`proofhandling`). + *third number* : Number of Abort to perform, i.e. the number of currently - opened nested proofs that must be canceled (see Chapter :ref:`TODO-7-proof-handling`). + opened nested proofs that must be canceled (see Chapter :ref:`proofhandling`). @@ -1035,10 +1036,10 @@ Warnings: #. It only works with the bytecode version of |Coq| (i.e. `coqtop.byte`, - see Section `TODO-14.1-interactive-use`). + see Section `interactive-use`). #. You must have compiled |Coq| from the source package and set the environment variable COQTOP to the root of your copy of the sources - (see Section `14.3.2-customization-by-envionment-variables`). + (see Section `customization-by-environment-variables`). @@ -1108,7 +1109,7 @@ This command turns off the normal displaying. This command turns the normal display on. -TODO : check that spaces are handled well +.. todo:: check that spaces are handled well .. cmd:: Set Warnings ‘‘(@ident {* , @ident } )’’. @@ -1196,7 +1197,7 @@ This command displays the current state of compaction of goal. This command resets the displaying of goals to focused goals only (default). Unfocused goals are created by focusing other goals with -bullets (see :ref:`TODO-7.2.7-bullets`) or curly braces (see `7.2.6-curly-braces`). +bullets (see :ref:`bullets`) or curly braces (see `here <curly-braces>`). .. cmd:: Set Printing Unfocused. @@ -1221,6 +1222,7 @@ when -emacs is passed. This command disables the printing of the “(dependent evars: …)” line when -emacs is passed. +.. _vernac-controlling-the-reduction-strategies: Controlling the reduction strategies and the conversion algorithm ---------------------------------------------------------------------- @@ -1249,14 +1251,14 @@ a constant is replacing it by its definition). ``Opaque`` has also an effect on the conversion algorithm of |Coq|, telling it to delay the unfolding of a constant as much as possible when |Coq| -has to check the conversion (see Section :ref:`TODO-4.3-conversion-rules`) of two distinct +has to check the conversion (see Section :ref:`conversion-rules`) of two distinct applied constants. The scope of ``Opaque`` is limited to the current section, or current file, unless the variant ``Global Opaque`` is used. -See also: sections :ref:`TODO-8.7-performing-computations`, :ref:`TODO-8.16-automatizing`, :ref:`TODO-7.1-switching-on-off-proof-editing-mode` +See also: sections :ref:`performingcomputations`, :ref:`tactics-automatizing`, :ref:`proof-editing-mode` Error messages: @@ -1294,8 +1296,9 @@ There is no constant referred by :n:`@qualid` in the environment. -See also: sections :ref:`TODO-8.7-performing-computations`, :ref:`TODO-8.16-automatizing`, :ref:`TODO-7.1-switching-on-off-proof-editing-mode` +See also: sections :ref:`performingcomputations`, :ref:`tactics-automatizing`, :ref:`proof-editing-mode` +.. _vernac-strategy: .. cmd:: Strategy @level [ {+ @qualid } ]. @@ -1367,7 +1370,7 @@ nothing prevents the user to also perform a ``Ltac`` `ident` ``:=`` `convtactic`. -See also: sections :ref:`TODO-8.7-performing-computations` +See also: sections :ref:`performingcomputations` .. _controlling-locality-of-commands: @@ -1387,23 +1390,22 @@ scope of their effect. There are four kinds of commands: section and the module or library file they occur in. For these commands, the Local modifier limits the effect of the command to the current section or module it occurs in. As an example, the ``Coercion`` - (see Section :ref:`TODO-2.8-coercions`) and ``Strategy`` (see Section :ref:`TODO-6.10.3-strategy`) commands belong - to this category. + (see Section :ref:`coercions`) and ``Strategy`` (see :ref:`here <vernac-strategy>`) + commands belong to this category. + Commands whose default behavior is to stop their effect at the end - of the section they occur in but to extent their effect outside the - module or library file they occur in. For these commands, the Local - modifier limits the effect of the command to the current module if the - command does not occur in a section and the Global modifier extends - the effect outside the current sections and current module if the - command occurs in a section. As an example, the ``Implicit Arguments`` (see - Section :ref:`TODO-2.7-implicit-arguments`), Ltac (see Chapter :ref:`TODO-9-tactic-language`) or ``Notation`` (see Section - :ref:`TODO-12.1-notations`) commands belong to this category. Notice that a subclass of - these commands do not support extension of their scope outside - sections at all and the Global is not applicable to them. + of the section they occur in but to extent their effect outside the module or + library file they occur in. For these commands, the Local modifier limits the + effect of the command to the current module if the command does not occur in a + section and the Global modifier extends the effect outside the current + sections and current module if the command occurs in a section. As an example, + the :cmd:`Implicit Arguments`, :cmd:`Ltac` or :cmd:`Notation` commands belong + to this category. Notice that a subclass of these commands do not support + extension of their scope outside sections at all and the Global is not + applicable to them. + Commands whose default behavior is to stop their effect at the end of the section or module they occur in. For these commands, the Global modifier extends their effect outside the sections and modules they - occurs in. The ``Transparent`` and ``Opaque`` (see Section :ref:`TODO-6.10-opaque`) commands belong to this category. + occurs in. The ``Transparent`` and ``Opaque`` (see Section :ref:`vernac-controlling-the-reduction-strategies`) commands belong to this category. + Commands whose default behavior is to extend their effect outside sections but not outside modules when they occur in a section and to extend their effect outside the module or library file they occur in diff --git a/doc/sphinx/replaces.rst b/doc/sphinx/replaces.rst index 0fee3754b1..28a04f90ce 100644 --- a/doc/sphinx/replaces.rst +++ b/doc/sphinx/replaces.rst @@ -35,6 +35,7 @@ .. |ident_n,1| replace:: `ident`\ :math:`_{n,1}` .. |ident_n,k_n| replace:: `ident`\ :math:`_{n,k_n}` .. |ident_n| replace:: `ident`\ :math:`_{n}` +.. |Latex| replace:: :smallcaps:`LaTeX` .. |L_tac| replace:: `L`:sub:`tac` .. |Ltac| replace:: `L`:sub:`tac` .. |ML| replace:: :smallcaps:`ML` @@ -55,7 +56,7 @@ .. |module_type_n| replace:: `module_type`\ :math:`_{n}` .. |N| replace:: ``N`` .. |nat| replace:: ``nat`` -.. |Ocaml| replace:: :smallcaps:`OCaml` +.. |OCaml| replace:: :smallcaps:`OCaml` .. |p_1| replace:: `p`\ :math:`_{1}` .. |p_i| replace:: `p`\ :math:`_{i}` .. |p_n| replace:: `p`\ :math:`_{n}` diff --git a/doc/sphinx/user-extensions/proof-schemes.rst b/doc/sphinx/user-extensions/proof-schemes.rst index 583b73e53d..8a24a382a5 100644 --- a/doc/sphinx/user-extensions/proof-schemes.rst +++ b/doc/sphinx/user-extensions/proof-schemes.rst @@ -3,6 +3,8 @@ Proof schemes =============== +.. _proofschemes-induction-principles: + Generation of induction principles with ``Scheme`` -------------------------------------------------------- @@ -106,11 +108,10 @@ induction principles when defining a new inductive type with the ``Unset Elimination Schemes`` command. It may be reactivated at any time with ``Set Elimination Schemes``. -The types declared with the keywords ``Variant`` (see :ref:`TODO-1.3.3`) and ``Record`` -(see :ref:`Record Types <record-types>`) do not have an automatic declaration of the induction -principles. It can be activated with the command -``Set Nonrecursive Elimination Schemes``. It can be deactivated again with -``Unset Nonrecursive Elimination Schemes``. +.. opt:: Nonrecursive Elimination Schemes + +This option controls whether types declared with the keywords :cmd:`Variant` and +:cmd:`Record` get an automatic declaration of the induction principles. In addition, the ``Case Analysis Schemes`` flag governs the generation of case analysis lemmas for inductive types, i.e. corresponding to the @@ -163,6 +164,8 @@ concluded by the conjunction of their conclusions. Check tree_forest_mutind. +.. _functional-scheme: + Generation of induction principles with ``Functional`` ``Scheme`` ----------------------------------------------------------------- @@ -229,7 +232,7 @@ definition written by the user. simpl; auto with arith. Qed. - We can use directly the functional induction (:ref:`TODO-8.5.5`) tactic instead + We can use directly the functional induction (:tacn:`function induction`) tactic instead of the pattern/apply trick: .. coqtop:: all @@ -305,6 +308,8 @@ definition written by the user. .. coqtop:: all Check tree_size_ind2. + +.. _derive-inversion: Generation of inversion principles with ``Derive`` ``Inversion`` ----------------------------------------------------------------- diff --git a/doc/sphinx/user-extensions/syntax-extensions.rst b/doc/sphinx/user-extensions/syntax-extensions.rst index 531295b63a..9965d5002d 100644 --- a/doc/sphinx/user-extensions/syntax-extensions.rst +++ b/doc/sphinx/user-extensions/syntax-extensions.rst @@ -345,13 +345,13 @@ inductive type or a recursive constant and a notation for it. Simultaneous definition of terms and notations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Thanks to reserved notations, the inductive, co-inductive, record, recursive -and corecursive definitions can benefit of customized notations. To do -this, insert a ``where`` notation clause after the definition of the -(co)inductive type or (co)recursive term (or after the definition of -each of them in case of mutual definitions). The exact syntax is given -on Figure 12.1 for inductive, co-inductive, recursive and corecursive -definitions and on Figure :ref:`record-syntax` for records. Here are examples: +Thanks to reserved notations, the inductive, co-inductive, record, recursive and +corecursive definitions can benefit of customized notations. To do this, insert +a ``where`` notation clause after the definition of the (co)inductive type or +(co)recursive term (or after the definition of each of them in case of mutual +definitions). The exact syntax is given by :token:`decl_notation` for inductive, +co-inductive, recursive and corecursive definitions and in :ref:`record-types` +for records. Here are examples: .. coqtop:: in @@ -381,23 +381,21 @@ Displaying informations about notations :opt:`Printing All` To disable other elements in addition to notations. +.. _locating-notations: + Locating notations ~~~~~~~~~~~~~~~~~~ -.. cmd:: Locate @symbol - - To know to which notations a given symbol belongs to, use the command - ``Locate symbol``, where symbol is any (composite) symbol surrounded by double - quotes. To locate a particular notation, use a string where the variables of the - notation are replaced by “_” and where possible single quotes inserted around - identifiers or tokens starting with a single quote are dropped. - - .. coqtop:: all +To know to which notations a given symbol belongs to, use the :cmd:`Locate` +command. You can call it on any (composite) symbol surrounded by double quotes. +To locate a particular notation, use a string where the variables of the +notation are replaced by “_” and where possible single quotes inserted around +identifiers or tokens starting with a single quote are dropped. - Locate "exists". - Locate "exists _ .. _ , _". +.. coqtop:: all - .. todo:: See also: Section 6.3.10. + Locate "exists". + Locate "exists _ .. _ , _". Notations and binders ~~~~~~~~~~~~~~~~~~~~~ @@ -435,8 +433,7 @@ Binders bound in the notation and parsed as patterns In the same way as patterns can be used as binders, as in :g:`fun '(x,y) => x+y` or :g:`fun '(existT _ x _) => x`, notations can be -defined so that any pattern (in the sense of the entry :n:`@pattern` of -Figure :ref:`term-syntax-aux`) can be used in place of the +defined so that any :n:`@pattern` can be used in place of the binder. Here is an example: .. coqtop:: in reset @@ -475,7 +472,7 @@ variable. Here is an example showing the difference: The default level for a ``pattern`` is 0. One can use a different level by using ``pattern at level`` :math:`n` where the scale is the same as the one for -terms (Figure :ref:`init-notations`). +terms (see :ref:`init-notations`). Binders bound in the notation and parsed as terms +++++++++++++++++++++++++++++++++++++++++++++++++ @@ -491,7 +488,7 @@ the following: This is so because the grammar also contains rules starting with :g:`{}` and followed by a term, such as the rule for the notation :g:`{ A } + { B }` for the -constant :g:`sumbool` (see Section :ref:`sumbool`). +constant :g:`sumbool` (see Section :ref:`specification`). Then, in the rule, ``x ident`` is replaced by ``x at level 99 as ident`` meaning that ``x`` is parsed as a term at level 99 (as done in the notation for @@ -829,6 +826,8 @@ lonely notations. These scopes, in opening order, are ``core_scope``, These variants survive sections. They behave as if Global were absent when not inside a section. +.. _LocalInterpretationRulesForNotations: + Local interpretation rules for notations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -859,6 +858,7 @@ Binding arguments of a constant to an interpretation scope +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. cmd:: Arguments @qualid {+ @name%@scope} + :name: Arguments (scopes) It is possible to set in advance that some arguments of a given constant have to be interpreted in a given scope. The command is @@ -897,7 +897,7 @@ Binding arguments of a constant to an interpretation scope .. cmdv:: Arguments @qualid {+ @name%scope} : extra scopes Defines extra argument scopes, to be used in case of coercion to Funclass - (see Chapter :ref:`Coercions-full`) or with a computed type. + (see Chapter :ref:`implicitcoercions`) or with a computed type. .. cmdv:: Global Arguments @qualid {+ @name%@scope} @@ -957,7 +957,7 @@ Binding types of arguments to an interpretation scope type :g:`t` in :g:`f t a` is not recognized as an argument to be interpreted in scope ``scope``. - More generally, any coercion :n:`@class` (see Chapter :ref:`Coercions-full`) + More generally, any coercion :n:`@class` (see Chapter :ref:`implicitcoercions`) can be bound to an interpretation scope. The command to do it is :n:`Bind Scope @scope with @class` diff --git a/doc/tools/coqrst/coqdomain.py b/doc/tools/coqrst/coqdomain.py index 663ab9d371..f09ed4b55c 100644 --- a/doc/tools/coqrst/coqdomain.py +++ b/doc/tools/coqrst/coqdomain.py @@ -108,7 +108,7 @@ class CoqObject(ObjectDescription): annotation = self.annotation + ' ' signode += addnodes.desc_annotation(annotation, annotation) self._render_signature(signature, signode) - return self._name_from_signature(signature) + return self.options.get("name") or self._name_from_signature(signature) @property def _index_suffix(self): @@ -145,14 +145,6 @@ class CoqObject(ObjectDescription): index_text = name + self._index_suffix self.indexnode['entries'].append(('single', index_text, target, '', None)) - def run(self): - """Small extension of the parent's run method, handling user-provided names.""" - [idx, node] = super().run() - custom_name = self.options.get("name") - if custom_name: - self.add_target_and_index(custom_name, "", node.children[0]) - return [idx, node] - def add_target_and_index(self, name, _, signode): """Create a target and an index entry for name""" if name: @@ -194,13 +186,18 @@ class VernacObject(NotationObject): annotation = "Command" def _name_from_signature(self, signature): - return stringify_with_ellipses(signature) + m = re.match(r"[a-zA-Z ]+", signature) + if m: + return m.group(0).strip() class VernacVariantObject(VernacObject): """An object to represent variants of Coq commands""" index_suffix = "(cmdv)" annotation = "Variant" + def _name_from_signature(self, signature): + return None + class TacticNotationObject(NotationObject): """An object to represent Coq tactic notations""" subdomain = "tacn" |