From 37e8149db7bfa2e7d7fe571b92752f6589101852 Mon Sep 17 00:00:00 2001 From: Théo Zimmermann Date: Fri, 22 Jun 2018 09:06:57 +0200 Subject: Clarify further doc/README.md following Jim's comments. Relative links. Cf. #7800. --- doc/README.md | 63 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 31 insertions(+), 32 deletions(-) (limited to 'doc') diff --git a/doc/README.md b/doc/README.md index 416726e1b..6c6e1f01f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -13,58 +13,56 @@ Additionnally, you can view the documentation for the current master version at . The reference manual is written is reStructuredText and compiled -using Sphinx (see [`sphinx/README.rst`](/doc/sphinx/README.rst)) +using Sphinx. See [`sphinx/README.rst`](sphinx/README.rst) to learn more about the format that is used. The documentation for the standard library is generated from the `.v` source files using coqdoc. -Prerequisite +Dependencies ------------ -To produce the complete documentation in HTML, the following tools are required: +### HTML documentation - - Python 3 - - Sphinx 1.6.5 (http://www.sphinx-doc.org/en/stable/) - - sphinx_rtd_theme - - pexpect - - beautifulsoup4 - - Antlr4 runtime for Python 3 +To produce the complete documentation in HTML, you will need Coq dependencies +listed in [`INSTALL`](../INSTALL). Additionally, the Sphinx-based +reference manual requires Python 3, and the following Python packages: -To produce the documentation in PDF and PostScript formats the following -additional tools are required: + sphinx sphinx_rtd_theme beautifulsoup4 antlr4-python3-runtime pexpect sphinxcontrib-bibtex - - latex (latex2e) - - pdflatex - - dvips - - makeindex - -Under recent Debian based operating systems (Debian 10 "Buster", -Ubuntu 18.04, ...) a working set of packages for compiling the -documentation for Coq is: +You can install them using `pip3 install` or using your distribution's package +manager. E.g. under recent Debian-based operating systems (Debian 10 "Buster", +Ubuntu 18.04, ...) you can use: - texlive-latex-extra texlive-fonts-recommended - python3-sphinx python3-pexpect python3-sphinx-rtd-theme - python3-bs4 python3-sphinxcontrib.bibtex python3-pip + apt install python3-sphinx python3-pexpect python3-sphinx-rtd-theme \ + python3-bs4 python3-sphinxcontrib.bibtex python3-pip -Then, install the Python3 Antlr4 package: +Then, install the missing Python3 Antlr4 package: pip3 install antlr4-python3-runtime Nix users should get the correct development environment to build the -HTML documentation from Coq's [`default.nix`](/default.nix) (note this +HTML documentation from Coq's [`default.nix`](../default.nix) (note this doesn't include the LaTeX packages needed to build the full documentation). -If you are in an older / different distribution / operating system, you can -install the Python packages required to build the reference manual using -python3-pip: +### Other formats + +To produce the documentation in PDF and PostScript formats, the following +additional tools are required: + + - latex (latex2e) + - pdflatex + - dvips + - makeindex + +Install them using your package manager. E.g. on Debian / Ubuntu: - pip3 install sphinx sphinx_rtd_theme beautifulsoup4 antlr4-python3-runtime pexpect sphinxcontrib-bibtex + apt install texlive-latex-extra texlive-fonts-recommended Compilation ----------- -To produce all documentation about Coq, just run: +To produce all documentation about Coq in all formats, just run: ./configure # (if you hadn't already) make doc @@ -97,7 +95,8 @@ Installation To install all produced documents, do: - make DOCDIR=/some/directory/for/documentation install-doc + make install-doc -`DOCDIR` defaults to `/usr/share/doc/coq` or whatever value was specificied -through the `-docdir` option of `./configure`. +This will install the documentation in `/usr/share/doc/coq` unless you +specify another value through the `-docdir` option of `./configure` or the +`DOCDIR` environment variable. -- cgit v1.2.3