Merge PR #8616: Include the full Table of Contents document in the on-screen TOC, ...

12 files changed, 45 insertions, 53 deletions

diff --git a/.gitignore b/.gitignore
index 39ef20970d..05869e2a0c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -101,7 +101,6 @@ doc/faq/axioms.pdf_t
 doc/faq/axioms.png
 doc/sphinx/index.rst
 doc/sphinx/zebibliography.rst
-doc/sphinx/credits.rst
 doc/stdlib/Library.out
 doc/stdlib/Library.ps
 doc/stdlib/Library.coqdoc.tex
diff --git a/Makefile.doc b/Makefile.doc
index 1184cc186b..9e6ec4955a 100644
--- a/Makefile.doc
+++ b/Makefile.doc
@@ -10,7 +10,7 @@
 
 # Makefile for the Coq documentation
 
-# Read INSTALL.doc to learn about the dependencies
+# Read doc/README.md to learn about the dependencies
 
 # The main entry point :
 
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index 71f01cbb17..d98b8641e9 100755
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -193,8 +193,9 @@ html_theme = 'sphinx_rtd_theme'
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
-
+html_theme_options = {
+    'collapse_navigation': False
+}
 html_context = {
     'display_github': True,
     'github_user': 'coq',
diff --git a/doc/sphinx/credits.html.rst b/doc/sphinx/credits.html.rst
deleted file mode 100644
index 0b2b1c6ad1..0000000000
--- a/doc/sphinx/credits.html.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-.. _credits:
-
--------
-Credits
--------
-
-.. include:: credits-contents.rst
diff --git a/doc/sphinx/credits.latex.rst b/doc/sphinx/credits.latex.rst
deleted file mode 100644
index 39101f9d52..0000000000
--- a/doc/sphinx/credits.latex.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-.. _credits:
-
-.. include:: credits-contents.rst
diff --git a/doc/sphinx/credits-contents.rst b/doc/sphinx/credits.rst
index d1df0657aa..ffdc4f3ec6 100644
--- a/doc/sphinx/credits-contents.rst
+++ b/doc/sphinx/credits.rst
@@ -1,3 +1,7 @@
+-------
+Credits
+-------
+
 Coq is a proof assistant for higher-order logic, allowing the
 development of computer programs consistent with their formal
 specification. It is the result of about ten years of research of the
@@ -186,7 +190,7 @@ definitions of “inversion predicates”.
 |
 
 Credits: addendum for version 6.1
-=================================
+---------------------------------
 
 The present version 6.1 of |Coq| is based on the V5.10 architecture. It
 was ported to the new language Objective Caml by Bruno Barras. The
@@ -223,7 +227,7 @@ Barras.
 |
 
 Credits: addendum for version 6.2
-=================================
+---------------------------------
 
 In version 6.2 of |Coq|, the parsing is done using camlp4, a preprocessor
 and pretty-printer for CAML designed by Daniel de Rauglaudre at INRIA.
@@ -268,7 +272,7 @@ Loiseleur.
 |
 
 Credits: addendum for version 6.3
-=================================
+---------------------------------
 
 The main changes in version V6.3 were the introduction of a few new
 tactics and the extension of the guard condition for fixpoint
@@ -301,7 +305,7 @@ Monin from CNET Lannion.
 |
 
 Credits: versions 7
-===================
+-------------------
 
 The version V7 is a new implementation started in September 1999 by
 Jean-Christophe Filliâtre. This is a major revision with respect to the
@@ -390,7 +394,7 @@ J.-F. Monin from France Telecom R & D.
 |
 
 Credits: version 8.0
-====================
+--------------------
 
 Coq version 8 is a major revision of the |Coq| proof assistant. First, the
 underlying logic is slightly different. The so-called *impredicativity*
@@ -492,7 +496,7 @@ under the responsibility of Christine Paulin.
 |
 
 Credits: version 8.1
-====================
+--------------------
 
 Coq version 8.1 adds various new functionalities.
 
@@ -571,7 +575,7 @@ and Yale University.
 |
 
 Credits: version 8.2
-====================
+--------------------
 
 Coq version 8.2 adds new features, new libraries and improves on many
 various aspects.
@@ -665,7 +669,7 @@ the Coq-Club mailing list.
 |
 
 Credits: version 8.3
-====================
+--------------------
 
 Coq version 8.3 is before all a transition version with refinements or
 extensions of the existing features and libraries and a new tactic nsatz
@@ -739,7 +743,7 @@ Pierce for the excellent teaching materials they provided.
 |
 
 Credits: version 8.4
-====================
+--------------------
 
 Coq version 8.4 contains the result of three long-term projects: a new
 modular library of arithmetic by Pierre Letouzey, a new proof engine by
@@ -895,7 +899,7 @@ Eelis van der Weegen.
 |
 
 Credits: version 8.5
-====================
+--------------------
 
 Coq version 8.5 contains the result of five specific long-term projects:
 
@@ -1049,7 +1053,7 @@ Tankink. Maxime Dénès coordinated the release process.
 |
 
 Credits: version 8.6
-====================
+--------------------
 
 Coq version 8.6 contains the result of refinements, stabilization of
 8.5’s features and cleanups of the internals of the system. Over the
@@ -1189,7 +1193,8 @@ Dénès to put together a |Coq| consortium.
 |
 
 Credits: version 8.7
-====================
+--------------------
+
 |Coq| version 8.7 contains the result of refinements, stabilization of features
 and cleanups of the internals of the system along with a few new features. The
 main user visible changes are:
@@ -1294,8 +1299,7 @@ system, is now upcoming and will rely on Inria’s newly created Foundation.
 |
 
 Credits: version 8.8
-====================
-
+--------------------
 
 |Coq| version 8.8 contains the result of refinements and stabilization of
 features and deprecations, cleanups of the internals of the system along
diff --git a/doc/sphinx/index.html.rst b/doc/sphinx/index.html.rst
index cf12b57414..a652b9e1ca 100644
--- a/doc/sphinx/index.html.rst
+++ b/doc/sphinx/index.html.rst
@@ -1,13 +1,11 @@
-.. _introduction:
-
 ==========================
-Introduction
+Introduction and Contents
 ==========================
 
 .. include:: introduction.rst
 
-Table of contents
------------------
+Contents
+--------
 
 .. toctree::
    :caption: Indexes
@@ -82,9 +80,6 @@ Table of contents
 
    zebibliography
 
-License
--------
-
 .. include:: license.rst
 
 .. [#PG] Proof-General is available at https://proofgeneral.github.io/.
diff --git a/doc/sphinx/index.latex.rst b/doc/sphinx/index.latex.rst
index af757f8746..9e9eb330fe 100644
--- a/doc/sphinx/index.latex.rst
+++ b/doc/sphinx/index.latex.rst
@@ -2,26 +2,22 @@
  The Coq Reference Manual
 ==========================
 
+------------
 Introduction
 ------------
 
 .. include:: introduction.rst
 
+.. include:: license.rst
+
 .. [#PG] Proof-General is available at https://proofgeneral.github.io/.
    Optionally, you can enhance it with the minor mode
    Company-Coq :cite:`Pit16`
    (see https://github.com/cpitclaudel/company-coq).
 
-Credits
--------
-
 .. include:: credits.rst
 
-License
--------
-
-.. include:: license.rst
-
+------------
 The language
 ------------
 
@@ -33,6 +29,7 @@ The language
    language/cic
    language/module-system
 
+----------------
 The proof engine
 ----------------
 
@@ -45,6 +42,7 @@ The proof engine
    proof-engine/detailed-tactic-examples
    proof-engine/ssreflect-proof-language
 
+---------------
 User extensions
 ---------------
 
@@ -53,6 +51,7 @@ User extensions
    user-extensions/syntax-extensions
    user-extensions/proof-schemes
 
+---------------
 Practical tools
 ---------------
 
@@ -62,6 +61,7 @@ Practical tools
    practical-tools/utilities
    practical-tools/coqide
 
+--------
 Addendum
 --------
 
diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst
index 5bb7bf542c..bcdf3277ad 100644
--- a/doc/sphinx/introduction.rst
+++ b/doc/sphinx/introduction.rst
@@ -44,7 +44,7 @@ are processed from a file.
 .. seealso:: :ref:`thecoqcommands`.
 
 How to read this book
-=====================
+---------------------
 
 This is a Reference Manual, so it is not intended for continuous reading.
 We recommend using the various indexes to quickly locate the documentation
@@ -90,7 +90,7 @@ Nonetheless, the manual has some structure that is explained below.
    solvers and tactics. See the table of contents for a complete list.
 
 List of additional documentation
-================================
+--------------------------------
 
 This manual does not contain all the documentation the user may need
 about |Coq|. Various informations can be found in the following documents:
diff --git a/doc/sphinx/license.rst b/doc/sphinx/license.rst
index 232b04211c..55c6d988f0 100644
--- a/doc/sphinx/license.rst
+++ b/doc/sphinx/license.rst
@@ -1,3 +1,6 @@
+License
+-------
+
 This material (the Coq Reference Manual) may be distributed only subject to the
 terms and conditions set forth in the Open Publication License, v1.0 or later
 (the latest version is presently available at
diff --git a/doc/sphinx/proof-engine/proof-handling.rst b/doc/sphinx/proof-engine/proof-handling.rst
index 46851050ac..c802f44ac1 100644
--- a/doc/sphinx/proof-engine/proof-handling.rst
+++ b/doc/sphinx/proof-engine/proof-handling.rst
@@ -632,16 +632,15 @@ How to enable diffs
 ```````````````````
 
 .. opt:: Diffs %( "on" %| "off" %| "removed" %)
+   :name: Diffs
 
-  .. This ref doesn't work: :opt:`Set Diffs %( "on" %| "off" %| "removed" %)`
-
-  The “on” option highlights added tokens in green, while the “removed” option
-  additionally reprints items with removed tokens in red.  Unchanged tokens in
-  modified items are shown with pale green or red.  (Colors are user-configurable.)
+   The “on” option highlights added tokens in green, while the “removed” option
+   additionally reprints items with removed tokens in red.  Unchanged tokens in
+   modified items are shown with pale green or red.  (Colors are user-configurable.)
 
 For coqtop, showing diffs can be enabled when starting coqtop with the
-``-diffs on|off|removed`` command-line option or with the ``Set Diffs``
-command within Coq.  You will need to provide the ``-color on|auto`` command-line option when
+``-diffs on|off|removed`` command-line option or by setting the :opt:`Diffs` option
+within Coq.  You will need to provide the ``-color on|auto`` command-line option when
 you start coqtop in either case.
 
 Colors for coqtop can be configured by setting the ``COQ_COLORS`` environment
diff --git a/doc/sphinx/proof-engine/vernacular-commands.rst b/doc/sphinx/proof-engine/vernacular-commands.rst
index 125c4c25a3..a69cf209c7 100644
--- a/doc/sphinx/proof-engine/vernacular-commands.rst
+++ b/doc/sphinx/proof-engine/vernacular-commands.rst
@@ -461,6 +461,7 @@ Requests to the environment
 .. note::
 
    .. table:: Search Blacklist @string
+      :name: Search Blacklist
 
       Specifies a set of strings used to exclude lemmas from the results of :cmd:`Search`,
       :cmd:`SearchHead`, :cmd:`SearchPattern` and :cmd:`SearchRewrite` queries.  A lemma whose