From f5be988da566d0a48c67bd81be6d32376b3ba2a5 Mon Sep 17 00:00:00 2001 From: Théo Zimmermann Date: Thu, 13 Feb 2020 18:47:42 +0100 Subject: [refman] Move chapters into new structure. As a first step toward a deeper refactoring of the reference manual, we move existing chapters into a new structure. We use the Sphinx support for top-level chapters spanning multiple pages to consolidate existing chapters into a smaller number of chapters and a smaller number of parts. Now the full top-level table of content can be seen in one glance. Most of the new chapters are divided into several sub-chapters (on separate pages) that correspond to the pre-existing chapters. These new top-level chapters gathering several chapters together have gained a new introduction. The main introduction has been rewritten / simplified as well. For now, the URL of pre-existing chapters does not change. The intent is to further refactor the manual by splitting some of these sub-chapters into smaller ones, and by moving things around. While the sub-chapters are likely to evolve very much in the future, the top-level table of content is almost final (except that the "Using Coq" part may gain one or two additional chapters on proof engineering / project management). Thanks to Jim Fehrle for investigating how to split a chapter on multiple pages and to both Jim and Matthieu Sozeau for the discussion that led to this new structure. See also the related CEP: https://github.com/coq/ceps/pull/43 Additional notes: - A new directory structure has been created reflecting the new chapter structure. - The indexes chapter has been removed from the PDF version since it wasn't working. Co-authored-by: Jim Fehrle --- doc/sphinx/proofs/automatic-tactics/index.rst | 22 +++++++++++++++++ doc/sphinx/proofs/creating-tactics/index.rst | 35 +++++++++++++++++++++++++++ doc/sphinx/proofs/writing-proofs/index.rst | 34 ++++++++++++++++++++++++++ 3 files changed, 91 insertions(+) create mode 100644 doc/sphinx/proofs/automatic-tactics/index.rst create mode 100644 doc/sphinx/proofs/creating-tactics/index.rst create mode 100644 doc/sphinx/proofs/writing-proofs/index.rst (limited to 'doc/sphinx/proofs') diff --git a/doc/sphinx/proofs/automatic-tactics/index.rst b/doc/sphinx/proofs/automatic-tactics/index.rst new file mode 100644 index 0000000000..e89bde63bc --- /dev/null +++ b/doc/sphinx/proofs/automatic-tactics/index.rst @@ -0,0 +1,22 @@ +.. _automatic-tactics: + +===================================================== +Built-in decision procedures and programmable tactics +===================================================== + +Some tactics are largely automated and are able to solve complex +goals. This chapter presents both some decision procedures that can +be used to solve some specific categories of goals, and some +programmable tactics, that the user can instrument to handle some +complex goals in new domains. + +This chapter is divided in several sub-chapters: + +.. toctree:: + :maxdepth: 1 + + ../../addendum/omega + ../../addendum/micromega + ../../addendum/ring + ../../addendum/nsatz + ../../addendum/generalized-rewriting diff --git a/doc/sphinx/proofs/creating-tactics/index.rst b/doc/sphinx/proofs/creating-tactics/index.rst new file mode 100644 index 0000000000..5882f10ec3 --- /dev/null +++ b/doc/sphinx/proofs/creating-tactics/index.rst @@ -0,0 +1,35 @@ +.. _writing-tactics: + +==================== +Creating new tactics +==================== + +The languages presented in this chapter allow one to build complex +tactics by combining existing ones with constructs such as +conditionals and looping. While :ref:`Ltac ` was initially +thought of as a language for doing some basic combinations, it has +been used successfully to build highly complex tactics as well, but +this has also highlighted its limits and fragility. The experimental +language :ref:`Ltac2 ` is a typed and more principled variant +which is more adapted to building complex tactics. + +.. toctree:: + :maxdepth: 1 + + ../../proof-engine/ltac + ../../proof-engine/ltac2 + + +There are other solutions beyond these two tactic languages to write +new tactics: + +- `Mtac2 `_ is an external plugin + which provides another typed tactic language. While Ltac2 belongs + to the ML language family, Mtac2 reuses the language of Coq itself + as the language to build Coq tactics. + +- The most traditional way of building new complex tactics is to write + a Coq plugin in OCaml. Beware that this also requires much more + effort and commitment. A tutorial for writing Coq plugins is + available in the Coq repository in `doc/plugin_tutorial + `_. diff --git a/doc/sphinx/proofs/writing-proofs/index.rst b/doc/sphinx/proofs/writing-proofs/index.rst new file mode 100644 index 0000000000..cc4f7e1305 --- /dev/null +++ b/doc/sphinx/proofs/writing-proofs/index.rst @@ -0,0 +1,34 @@ +.. _writing-proofs: + +============== +Writing proofs +============== + +Coq is an interactive theorem prover, or proof assistant, which means +that proofs can be constructed interactively through a dialog between +the user and the assistant. The building blocks for this dialog are +tactics which the user will use to represent steps in the proof of a +theorem. + +Incomplete proofs have one or more open (unproven) sub-goals. Each +goal has its own context (a set of assumptions that can be used to +prove the goal). Tactics can transform goals and contexts. +Internally, the incomplete proof is represented as a partial proof +term, with holes for the unproven sub-goals. + +When a proof is complete, the user leaves the proof mode and defers +the verification of the resulting proof term to the :ref:`kernel +`. + +This chapter is divided in several sub-chapters, describing the basic +ideas of the proof mode (during which tactics can be used), and +several flavors of tactics, including the SSReflect proof language: + +.. toctree:: + :maxdepth: 1 + + ../../proof-engine/proof-handling + ../../proof-engine/tactics + ../../proof-engine/ssreflect-proof-language + ../../proof-engine/detailed-tactic-examples + ../../user-extensions/proof-schemes -- cgit v1.2.3 From 1be31dea4cfd31522898edc07fee0829fea7c68d Mon Sep 17 00:00:00 2001 From: Théo Zimmermann Date: Thu, 19 Mar 2020 15:51:18 +0100 Subject: Adapt to sub-TOC not showing in PDF output. --- doc/sphinx/proofs/automatic-tactics/index.rst | 2 -- doc/sphinx/proofs/creating-tactics/index.rst | 13 ++++++------- doc/sphinx/proofs/writing-proofs/index.rst | 6 +++--- 3 files changed, 9 insertions(+), 12 deletions(-) (limited to 'doc/sphinx/proofs') diff --git a/doc/sphinx/proofs/automatic-tactics/index.rst b/doc/sphinx/proofs/automatic-tactics/index.rst index e89bde63bc..a219770c69 100644 --- a/doc/sphinx/proofs/automatic-tactics/index.rst +++ b/doc/sphinx/proofs/automatic-tactics/index.rst @@ -10,8 +10,6 @@ be used to solve some specific categories of goals, and some programmable tactics, that the user can instrument to handle some complex goals in new domains. -This chapter is divided in several sub-chapters: - .. toctree:: :maxdepth: 1 diff --git a/doc/sphinx/proofs/creating-tactics/index.rst b/doc/sphinx/proofs/creating-tactics/index.rst index 5882f10ec3..1af1b0b726 100644 --- a/doc/sphinx/proofs/creating-tactics/index.rst +++ b/doc/sphinx/proofs/creating-tactics/index.rst @@ -13,13 +13,6 @@ this has also highlighted its limits and fragility. The experimental language :ref:`Ltac2 ` is a typed and more principled variant which is more adapted to building complex tactics. -.. toctree:: - :maxdepth: 1 - - ../../proof-engine/ltac - ../../proof-engine/ltac2 - - There are other solutions beyond these two tactic languages to write new tactics: @@ -33,3 +26,9 @@ new tactics: effort and commitment. A tutorial for writing Coq plugins is available in the Coq repository in `doc/plugin_tutorial `_. + +.. toctree:: + :maxdepth: 1 + + ../../proof-engine/ltac + ../../proof-engine/ltac2 diff --git a/doc/sphinx/proofs/writing-proofs/index.rst b/doc/sphinx/proofs/writing-proofs/index.rst index cc4f7e1305..a279a5957f 100644 --- a/doc/sphinx/proofs/writing-proofs/index.rst +++ b/doc/sphinx/proofs/writing-proofs/index.rst @@ -20,9 +20,9 @@ When a proof is complete, the user leaves the proof mode and defers the verification of the resulting proof term to the :ref:`kernel `. -This chapter is divided in several sub-chapters, describing the basic -ideas of the proof mode (during which tactics can be used), and -several flavors of tactics, including the SSReflect proof language: +This chapter is divided in several parts, describing the basic ideas +of the proof mode (during which tactics can be used), and several +flavors of tactics, including the SSReflect proof language. .. toctree:: :maxdepth: 1 -- cgit v1.2.3