IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Improve formatting of docs about LaTeX builder

Browse Source
This commit is contained in:
jfbu 2018-04-02 19:21:48 +02:00
parent 3525c5a3b1
commit 5473851e8c
1 changed files with 37 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
doc/builders.rst
View File

@ -155,36 +155,30 @@ The builder's "name" must be given to the **-b** command-line option of
configuration values that customize the output of this builder, see the configuration values that customize the output of this builder, see the
chapter :ref:`latex-options` for details. chapter :ref:`latex-options` for details.
The produced LaTeX file uses several LaTeX packages that may not be present
in a "minimal" TeX distribution installation. For example, on Ubuntu, the
following packages need to be installed for successful PDF builds:
* texlive-latex-recommended
* texlive-fonts-recommended
* texlive-latex-extra
* latexmk (for ``make latexpdf`` on GNU/Linux and MacOS X)
* latex-xcolor (old Ubuntu)
* texlive-luatex, texlive-xetex (see :confval:`latex_engine`)
The testing of Sphinx LaTeX is done on Ubuntu trusty with the above
mentioned packages, which are from a TeXLive 2013 snapshot dated
February 2014.
.. versionchanged:: 1.6
Formerly, testing had been done on Ubuntu precise (TeXLive 2009).
.. note:: .. note::
The produced LaTeX file uses several LaTeX packages that may not be Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This
present in a "minimal" TeX distribution installation. For example, on makes sure the needed number of runs is automatically executed to get
Ubuntu, the following packages need to be installed for successful PDF the cross-references, bookmarks, indices, and tables of contents right.
builds:
* texlive-latex-recommended
* texlive-fonts-recommended
* texlive-latex-extra
* latexmk (for ``make latexpdf``)
Sphinx will use ``xcolor.sty`` if present: recent Ubuntu distributions
have ``xcolor.sty`` included in latex-recommended, earlier ones have it
in latex-xcolor. Unicode engines will need texlive-luatex or
texlive-xetex.
The testing of Sphinx LaTeX is done on Ubuntu trusty with the above
mentioned packages, which are from a TeXLive 2013 snapshot dated
February 2014.
.. versionchanged:: 1.6
Formerly, testing had been done for some years on Ubuntu precise
(based on TeXLive 2009).
.. versionchanged:: 1.6
Use of ``latexmk`` for ``make latexpdf`` on GNU/Linux and Mac OS X
Since 1.6, ``make latexpdf`` (or
``make -C "<builddir>/latex"`` after a ``sphinx-build`` run) uses
``latexmk`` (not on Windows).
One can pass to ``latexmk`` options via the ``LATEXMKOPTS`` One can pass to ``latexmk`` options via the ``LATEXMKOPTS``
Makefile variable. For example: Makefile variable. For example:
@ -192,13 +186,22 @@ The builder's "name" must be given to the **-b** command-line option of
make latexpdf LATEXMKOPTS="-silent" make latexpdf LATEXMKOPTS="-silent"
reduces console output to a minimum. Also, if ``latexmk`` version is reduces console output to a minimum.
4.52b or higher (Jan 17) and ``xelatex`` is the :confval:`latex_engine`,
then ``LATEXMKOPTS="-xelatex"`` will speed up PDF builds.
To pass options directly to the Also, if ``latexmk`` version is 4.52b or higher (Jan 17)
``(pdf|xe|lua)latex`` executable, use variable ``LATEXOPTS`` (for example ``LATEXMKOPTS="-xelatex"`` will speed up PDF builds via XeLateX in case
``LATEXOPTS="--interaction=nonstopmode"``). of numerous graphics inclusions.
.. code-block:: console
make latexpdf LATEXMKOPTS="-xelatex"
To pass options directly to the ``(pdf|xe|lua)latex`` executable, use
variable ``LATEXOPTS``.
.. code-block:: console
make latexpdf LATEXOPTS="--interaction=nonstopmode"
.. autoattribute:: name .. autoattribute:: name