From 7ea542b83e68eee79ead8fe4b2cb298882e1cb22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Fri, 23 Aug 2024 09:34:21 +0200 Subject: [PATCH] LaTeX: clarify some docs, add syntax highlighting (refactoring) --- doc/latex.rst | 465 +++++++++++++++++++----------------- doc/usage/configuration.rst | 51 ++-- 2 files changed, 269 insertions(+), 247 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 5c9c503565b..a46258f2d28 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -4,6 +4,9 @@ LaTeX customization .. module:: latex :synopsis: LaTeX specifics. +.. role:: code-tex(code) + :language: LaTeX + .. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents .. raw:: latex @@ -120,7 +123,7 @@ Keys that you may want to override include: ``'passoptionstopackages'`` A string which will be positioned early in the preamble, designed to - contain ``\\PassOptionsToPackage{options}{foo}`` commands. + contain :code-tex:`\\PassOptionsToPackage{options}{foo}` commands. .. hint:: @@ -133,7 +136,7 @@ Keys that you may want to override include: .. versionadded:: 1.4 ``'babel'`` - "babel" package inclusion, default ``'\\usepackage{babel}'`` (the + "babel" package inclusion, default :code-tex:`r'\\usepackage{babel}'` (the suitable document language string is passed as class option, and ``english`` is used if no language.) For Japanese documents, the default is the empty string. @@ -152,7 +155,7 @@ Keys that you may want to override include: build repertory before next PDF build, else left-over auxiliary files are likely to break the build. - Default: ``'\\usepackage{babel}'`` (for Japanese documents) + Default: :code-tex:`r'\\usepackage{babel}'` (for Japanese documents) .. versionchanged:: 1.5 For :confval:`latex_engine` set to ``'xelatex'``, the default @@ -168,6 +171,8 @@ Keys that you may want to override include: .. versionchanged:: 7.4.0 For French with ``'lualatex'`` the default is to use ``babel``. +.. _fontpkg: + ``'fontpkg'`` Font package inclusion. The default is:: @@ -176,8 +181,11 @@ Keys that you may want to override include: \renewcommand\ttdefault{txtt} """ - For ``'xelatex'`` and ``'lualatex'`` however the default is to use - the GNU FreeFont. + For ``'xelatex'`` and ``'lualatex'`` on the other hand the + :code-tex:`\\setmainfont`, :code-tex:`\\setsansfont` and + :code-tex:`\\setmonofont` commands of LaTeX package ``fontspec`` (included + via :ref:`fontenc`) are used to set up the OpenType fonts GNU FreeSerif, + FreeSans, and FreeMono as document fonts. .. versionchanged:: 1.2 Defaults to ``''`` when the :confval:`language` uses the Cyrillic @@ -188,27 +196,25 @@ Keys that you may want to override include: Greek or Cyrillic in a document using ``'pdflatex'`` engine. .. versionchanged:: 4.0.0 - - - The font substitution commands added at ``2.0`` have been moved - to the ``'fontsubstitution'`` key, as their presence here made - it complicated for user to customize the value of ``'fontpkg'``. - - The default font setting has changed: it still uses Times and - Helvetica clones for serif and sans serif, but via better, more - complete TeX fonts and associated LaTeX packages. The - monospace font has been changed to better match the Times clone. + The default font setting was changed. As shown above it still uses + Times and Helvetica clones for serif and sans serif, but via better, + more complete TeX fonts and associated LaTeX packages. The monospace + font has been changed to better match the Times clone. ``'fncychap'`` Inclusion of the "fncychap" package (which makes fancy chapter titles), - default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation + default :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English documentation (this option is slightly customized by Sphinx), - ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because + :code-tex:`r'\\usepackage[Sonny]{fncychap}'` for internationalized docs (because the "Bjarne" style uses numbers spelled out in English). Other "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and "Bjornstrup". You can also set this to ``''`` to disable fncychap. - Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents, - ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and - ``''`` for Japanese documents. + Default: :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English + documents, :code-tex:`r'\\usepackage[Sonny]{fncychap}'` for + internationalized documents, and ``''`` for Japanese documents. + +.. _preamble: ``'preamble'`` Additional preamble content. One may move all needed macros into some file @@ -314,7 +320,7 @@ Keys that don't need to be overridden unless in special cases are: ``'inputenc'`` "inputenc" package inclusion. - Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else + Default: :code-tex:`r'\\usepackage[utf8]{inputenc}'` when using pdflatex, else ``''``. .. note:: @@ -340,63 +346,72 @@ Keys that don't need to be overridden unless in special cases are: ``utf8x`` is in use. .. versionchanged:: 1.4.3 - Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all + Previously :code-tex:`r'\\usepackage[utf8]{inputenc}'` was used for all compilers. ``'cmappkg'`` "cmap" package inclusion. - Default: ``'\\usepackage{cmap}'`` + Default: :code-tex:`r'\\usepackage{cmap}'` .. versionadded:: 1.2 +.. _fontenc: + ``'fontenc'`` - Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to: + Its default, for ``'pdflatex'`` as :confval:`latex_engine`, is + :code-tex:`r'\\usepackage[T1]{fontenc}'`. Replace it (if using + ``'pdflatex'``) with: - - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional + - :code-tex:`r'\\usepackage[X2,T1]{fontenc}'` if you need occasional Cyrillic letters (физика частиц), - - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional - Greek letters (Σωματιδιακή φυσική). + - :code-tex:`r'\\usepackage[LGR,T1]{fontenc}'` if you need occasional + Greek letters (Σωματιδιακή φυσική), - Use ``[LGR,X2,T1]`` rather if both are needed. + - :code-tex:`r'\\usepackage[LGR,X2,T1]{fontenc}'` if you need both. - .. attention:: + The TeX installation may need some extra packages. For example, on Ubuntu + xenial: - - Do not use this key for a :confval:`latex_engine` other than - ``'pdflatex'``. + - ``texlive-lang-greek`` and ``cm-super`` are needed for Greek (``LGR``), - - If Greek is main language, do not use this key. Since Sphinx 2.2.1, - ``xelatex`` will be used automatically as :confval:`latex_engine`. + - ``texlive-lang-cyrillic`` and ``cm-super`` are needed for Cyrillic + (``X2``). - - The TeX installation may need some extra packages. For example, - on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super`` - are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and - ``cm-super`` are needed for support of Cyrillic. + With ``'xelatex'`` and ``'lualatex'``, support for Greek and Cyrillic is + out-of-the-box: this :ref:`fontenc` key defaults to including the LaTeX + package ``fontspec`` (with some extras described below) and selects the GNU + FreeSerif font as body font. See :ref:`fontpkg`. .. versionchanged:: 1.5 - Defaults to ``'\\usepackage{fontspec}'`` when - :confval:`latex_engine` is ``'xelatex'``. + Defaults to :code-tex:`r'\\usepackage{fontspec}'` if + :confval:`latex_engine` is set to ``'xelatex'``. .. versionchanged:: 1.6 - ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``. + Defaults to :code-tex:`r'\\usepackage{fontspec}'` if + :confval:`latex_engine` is set to ``'lualatex'``. .. versionchanged:: 2.0 - ``'lualatex'`` executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX - ligatures transforming ``<<`` and ``>>`` as escaping working with - ``pdflatex/xelatex`` failed with ``lualatex``. + ``'lualatex'`` executes additionally + :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` to disable TeX + ligatures for ``<<`` and ``>>``. .. versionchanged:: 2.0 - Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of - occasional Greek or Cyrillic letters (``'pdflatex'``). + Extra LaTeX configuration is automatically executed if ``LGR``, ``T2A``, + or ``X2`` are detected in this key, in order to support occasional Greek + or Cyrillic with ``'pdflatex'``. + + .. versionchanged:: 2.2.1 + Documents having Greek as main language default to ``'xelatex'`` and + should not set the :ref:`fontenc` key, which will load ``fontspec``. .. versionchanged:: 2.3.0 ``'xelatex'`` executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid - contractions of ``--`` into en-dash or transforms of straight quotes - into curly ones in PDF (in non-literal text paragraphs) despite - :confval:`smartquotes` being set to ``False``. + :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` in order to + avoid contractions of ``--`` into en-dash and also transforms of + straight quotes into curly quotes (which otherwise would happen even + with :confval:`smartquotes` set to ``False``). ``'fontsubstitution'`` Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or @@ -413,7 +428,7 @@ Keys that don't need to be overridden unless in special cases are: It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as :confval:`latex_engine` and defaults to either the empty string or - to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on + to :code-tex:`r'\\usepackage{textalpha}'` for ``'pdflatex'`` depending on whether the ``'fontenc'`` key was used with ``LGR`` or not. Only expert LaTeX users may want to customize this key. @@ -421,20 +436,16 @@ Keys that don't need to be overridden unless in special cases are: ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context. For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`. - Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not + Default: :code-tex:`r'\\usepackage{textalpha}'` or ``''`` if ``fontenc`` does not include the ``LGR`` option. .. versionadded:: 2.0 ``'geometry'`` - "geometry" package inclusion, the default definition is: - - .. code-block:: latex - - '\\usepackage{geometry}' - - with an additional ``[dvipdfm]`` for Japanese documents. - The Sphinx LaTeX style file executes: + "geometry" package inclusion, defaults to + :code-tex:`r'\\usepackage{geometry}'` or + :code-tex:`r'\\usepackage[dvipdfm]{geometry}'` for Japanese documents. + The Sphinx LaTeX style file executes additionally: .. code-block:: latex @@ -443,9 +454,6 @@ Keys that don't need to be overridden unless in special cases are: which can be customized via corresponding :ref:`'sphinxsetup' options `. - Default: ``'\\usepackage{geometry}'`` (or - ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents) - .. versionadded:: 1.5 .. versionchanged:: 1.5.2 @@ -483,11 +491,11 @@ Keys that don't need to be overridden unless in special cases are: .. hint:: If the key value is set to - ``r'\newcommand\sphinxbackoftitlepage{}\sphinxmaketitle'``, then ```` will be + :code-tex:`r'\\newcommand\sphinxbackoftitlepage{}\\sphinxmaketitle'`, then ```` will be typeset on back of title page (``'manual'`` docclass only). - Default: ``'\\sphinxmaketitle'`` + Default: :code-tex:`r'\\sphinxmaketitle'` .. versionchanged:: 1.8.3 Original ``\maketitle`` from document class is not overwritten, @@ -505,12 +513,12 @@ Keys that don't need to be overridden unless in special cases are: Default: ``'Release'`` ``'tableofcontents'`` - "tableofcontents" call. The default of ``'\\sphinxtableofcontents'`` is a + "tableofcontents" call. The default of :code-tex:`r'\\sphinxtableofcontents'` is a wrapper of unmodified ``\tableofcontents``, which may itself be customized by user loaded packages. Override if you want to generate a different table of contents or put content between the title page and the TOC. - Default: ``'\\sphinxtableofcontents'`` + Default: :code-tex:`r'\\sphinxtableofcontents'` .. versionchanged:: 1.5 Previously the meaning of ``\tableofcontents`` itself was modified @@ -521,56 +529,57 @@ Keys that don't need to be overridden unless in special cases are: Commands used to display transitions. Override if you want to display transitions differently. - Default: ``'\n\n\\bigskip\\hrule\\bigskip\n\n'`` + Default: :code-tex:`'\\n\\n\\\\bigskip\\\\hrule\\\\bigskip\\n\\n'` .. versionadded:: 1.2 .. versionchanged:: 1.6 - Remove unneeded ``{}`` after ``\\hrule``. + Remove unneeded ``{}`` formerly located after :code-tex:`\\hrule`. ``'makeindex'`` "makeindex" call, the last thing before ``\begin{document}``. With - ``'\\usepackage[columns=1]{idxlayout}\\makeindex'`` the index will use + :code-tex:`r'\\usepackage[columns=1]{idxlayout}\\makeindex'` the index will use only one column. You may have to install ``idxlayout`` LaTeX package. - Default: ``'\\makeindex'`` + Default: :code-tex:`r'\\makeindex'` ``'printindex'`` "printindex" call, the last thing in the file. Override if you want to generate the index differently, append some content after the index, or - change the font. As LaTeX uses two-column mode for the index it is - often advisable to set this key to - ``'\\footnotesize\\raggedright\\printindex'``. Or, to obtain a one-column - index, use ``'\\def\\twocolumn[#1]{#1}\\printindex'`` (this trick may fail - if using a custom document class; then try the ``idxlayout`` approach - described in the documentation of the ``'makeindex'`` key). + change the font. As LaTeX uses two-column mode for the index it is often + advisable to set this key to + :code-tex:`r'\\footnotesize\\raggedright\\printindex'`. Or, to obtain a + one-column index, use :code-tex:`r'\\def\\twocolumn[#1]{#1}\\printindex'` + (this trick may fail if using a custom document class; then try the + ``idxlayout`` approach described in the documentation of the + ``'makeindex'`` key). - Default: ``'\\printindex'`` + Default: :code-tex:`r'\\printindex'` ``'fvset'`` Customization of ``fancyvrb`` LaTeX package. - The default value is ``'\\fvset{fontsize=auto}'`` which means that the + The default value is :code-tex:`r'\\fvset{fontsize=auto}'` which means that the font size will adjust correctly if a code-block ends up in a footnote. You may need to modify this if you use custom fonts: - ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like. + :code-tex:`r'\\fvset{fontsize=\\small}'` if the monospace font is Courier-like. - Default: ``'\\fvset{fontsize=auto}'`` + Default: :code-tex:`r'\\fvset{fontsize=auto}'` .. versionadded:: 1.8 .. versionchanged:: 2.0 For ``'xelatex'`` and ``'lualatex'`` defaults to - ``'\\fvset{fontsize=\\small}'`` as this + :code-tex:`r'\\fvset{fontsize=\\small}'` as this is adapted to the relative widths of the FreeFont family. .. versionchanged:: 4.0.0 Changed default for ``'pdflatex'``. Previously it was using - ``'\\fvset{fontsize=\\small}'``. + :code-tex:`r'\\fvset{fontsize=\\small}'`. .. versionchanged:: 4.1.0 Changed default for Chinese documents to - ``'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'`` + :code-tex:`r'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'` Keys that are set by other options and therefore should not be overridden are: @@ -683,8 +692,9 @@ The color used in the above example is available from having passed the .. versionadded:: 1.5.3 ``marginpar`` - The ``\marginparwidth`` LaTeX dimension. For Japanese documents, the value - is modified to be the closest integer multiple of the *zenkaku* width. + The :code-tex:`\\marginparwidth` LaTeX dimension. For Japanese documents, + the value is modified to be the closest integer multiple of the *zenkaku* + width. Default: ``0.5in`` @@ -821,9 +831,11 @@ The color used in the above example is available from having passed the ``verbatimcontinued`` A LaTeX macro inserted at start of continuation code lines. Its - (complicated...) default typesets a small red hook pointing to the right:: + (complicated...) default typesets a small red hook pointing to the right: + + .. code-block:: latex - \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} + \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} .. versionchanged:: 1.5 The breaking of long code lines was added at 1.4.2. The default @@ -834,12 +846,12 @@ The color used in the above example is available from having passed the Values for color keys must either: - - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something + - obey the syntax of the :code-tex:`\\definecolor` LaTeX command, e.g. something such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or ``{gray}{0.75}`` or ``{HTML}{808080}`` or ... - - or obey the syntax of the ``\colorlet`` command from package ``xcolor`` + - or obey the syntax of the :code-tex:`\\colorlet` command from package ``xcolor`` e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or ``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for this syntax. @@ -847,7 +859,7 @@ The color used in the above example is available from having passed the .. _xcolor: https://ctan.org/pkg/xcolor .. versionchanged:: 5.3.0 - Formerly only the ``\definecolor`` syntax was accepted. + Formerly only the :code-tex:`\\definecolor` syntax was accepted. ``TitleColor`` The color for titles (as configured via use of package "titlesec".) @@ -901,9 +913,10 @@ The color used in the above example is available from having passed the class. It is ignored for tables with ``nocolorrows`` class. As for the other ``'sphinxsetup'`` keys, it can also be set or modified - from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw` - directive, or also from a LaTeX environment associated to a `container - class `_ and using such ``\sphinxsetup{...}``. + from a :code-tex:`\\sphinxsetup{...}` LaTeX command inserted via the + :dudir:`raw` directive, or also from a LaTeX environment associated to a + `container class `_ and using such + :code-tex:`\\sphinxsetup{...}`. Default: ``{gray}{0.86}`` @@ -939,13 +952,13 @@ The color used in the above example is available from having passed the See :ref:`additionalcss` for its alias ``pre_padding`` and additional keys. - Default: ``\fboxsep`` + Default: :code-tex:`\\fboxsep` ``verbatimborder`` The width of the frame around :rst:dir:`code-block`\ s. See also :ref:`additionalcss` for ``pre_border-width``. - Default: ``\fboxrule`` + Default: :code-tex:`\\fboxrule` .. important:: @@ -1017,8 +1030,8 @@ The color used in the above example is available from having passed the which supports the customizability described in :ref:`additionalcss`. |notetexextras| - Some extra LaTeX code (such as ``\bfseries`` or ``\footnotesize``) - to be executed at start of the contents. + Some extra LaTeX code (such as :code-tex:`\\bfseries` or + :code-tex:`\\footnotesize`) to be executed at start of the contents. Default: empty @@ -1072,18 +1085,18 @@ The color used in the above example is available from having passed the LaTeX macros inserted at the start of the footnote text at bottom of page, after the footnote number. - Default: ``\mbox{ }`` + Default: :code-tex:`\\mbox{ }` ``BeforeFootnote`` LaTeX macros inserted before the footnote mark. The default removes possible space before it (else, TeX could insert a line break there). - Default: ``\leavevmode\unskip`` + Default: :code-tex:`\\leavevmode\\unskip` .. versionadded:: 1.5 ``HeaderFamily`` - default ``\sffamily\bfseries``. Sets the font used by headings. + default :code-tex:`\\sffamily\\bfseries`. Sets the font used by headings. .. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``, @@ -1157,15 +1170,15 @@ Additional CSS-like ``'sphinxsetup'`` keys Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally imported from some genuine CSS external file, but currently they have to be used -via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command +via the ``'sphinxsetup'`` interface (or the :code-tex:`\\sphinxsetup` LaTeX command inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. .. important:: Low-level LaTeX errors causing a build failure can happen if the input syntax is not respected. * In particular colors must be input as for the other color related options - previously described, i.e. either in the ``\definecolor`` syntax or via the - ``\colorlet`` syntax:: + previously described, i.e. either in the :code-tex:`\\definecolor` syntax + or via the :code-tex:`\\colorlet` syntax:: ... div.warning_border-TeXcolor={rgb}{1,0,0},% \definecolor syntax @@ -1185,17 +1198,18 @@ inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. but not by ``xelatex`` or ``platex``. * It is allowed for such specifications to be so-called "dimensional - expressions", e.g. ``\fboxsep+2pt`` or ``0.5\baselineskip`` are valid - inputs. The expressions will be evaluated only at the typesetting time. - Be careful though if using as in these examples TeX control sequences to - double the backslash or to employ a raw Python string for the value of - the :ref:`'sphinxsetup' ` key. + expressions", e.g. :code-tex:`\\fboxsep+2pt` or + :code-tex:`0.5\\baselineskip` are valid inputs. The expressions will be + evaluated only at the typesetting time. Be careful though if using as in + these examples TeX control sequences to double the backslash or to employ + a raw Python string for the value of the :ref:`'sphinxsetup' + ` key. * As a rule, avoid inserting unneeded spaces in the key values: especially - for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also - that ``\fboxsep \fboxsep`` will not be seen as space separated in LaTeX. - You must use something such as ``{\fboxsep} \fboxsep``. Or use - directly ``3pt 3pt`` which is a priori equivalent and simpler. + for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also + that :code-tex:`\\fboxsep \\fboxsep` will not be seen as space separated + in LaTeX. You must use something such as ``{\fboxsep} \fboxsep``. Or + use directly ``3pt 3pt`` which is a priori equivalent and simpler. The options are all named in a similar pattern which depends on a ``prefix``, which is then followed by an underscore, then the property name. @@ -1351,14 +1365,14 @@ forget the underscore separating the prefix from the property names. Consider passing options such as ``dvipsnames``, ``svgnames`` or ``x11names`` to ``xcolor`` via ``'passoptionstopackages'`` key of :confval:`latex_elements`. - If ``_TeXcolor`` is set, a ``\color`` command is inserted at + If ``_TeXcolor`` is set, a :code-tex:`\\color` command is inserted at start of the directive contents; for admonitions, this happens after the heading which reproduces the admonition type. - ``_TeXextras``: if set, its value must be some LaTeX command or - commands, for example ``\itshape``. These commands will be inserted at the - start of the contents; for admonitions, this happens after the heading which - reproduces the admonition type. + commands, for example :code-tex:`\\itshape`. These commands will be + inserted at the start of the contents; for admonitions, this happens after + the heading which reproduces the admonition type. The next keys, for admonitions, :dudir:`topic`, contents_, and :dudir:`sidebar`, were all three added at 7.4.0 (and 8.1.0 for the latter three). @@ -1368,8 +1382,9 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and .. important:: The colored title-row is produced as a result of the Sphinx default - definitions for the various ``\sphinxstyletitle`` commands, which - employ the ``\sphinxdotitlerow`` LaTeX command. See :ref:`latex-macros`. + definitions for the various :code-tex:`\\sphinxstyletitle` + commands, which employ the :code-tex:`\\sphinxdotitlerow` LaTeX command. + See :ref:`latex-macros`. - ``div._title-foreground-TeXcolor``: the color to be used for the icon (it applies only to the icon, not to the title of the admonition). @@ -1380,11 +1395,12 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and LaTeX ``fontawesome5`` package, which is loaded automatically if available. If neither ``fontawesome5`` nor fall-back ``fontawesome`` (for which the - associated command is ``\faicon``, not ``\faIcon``) are found, or if the - ``iconpackage`` key of :ref:`'sphinxsetup' ` is set to - load some other user-chosen package, or no package at all, all the - ``title-icons`` default to empty LaTeX code. It is up to user to employ - this interface to inject the icon (or anything else) into the PDF output. + associated command is :code-tex:`\\faicon`, not :code-tex:`\\faIcon`) are + found, or if the ``iconpackage`` key of :ref:`'sphinxsetup' + ` is set to load some other user-chosen package, or no + package at all, all the ``title-icons`` default to empty LaTeX code. It is + up to user to employ this interface to inject the icon (or anything else) + into the PDF output. .. note:: @@ -1423,9 +1439,10 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of the :confval:`latex_elements` key ``'fvset'``. For ``'lualatex'`` or ``'xelatex'`` Sphinx includes in the preamble already - ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into - overriding a ``\footnotesize`` coming from ``pre_TeXextras``. One has - to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax. + :code-tex:`\\fvset{fontsize=\\small}` and this induces ``fancyvrb`` + into overriding a :code-tex:`\\footnotesize` coming from + ``pre_TeXextras``. One has to use + :code-tex:`pre_TeXextras=\\fvset{fontsize=\\footnotesize}` syntax. Simpler to set directly the :confval:`latex_elements` key ``'fvset'``... @@ -1530,25 +1547,26 @@ Macros with LaTeX packages. .. versionadded:: 1.8 - ``\sphinxguilabel`` + :code-tex:`\\sphinxguilabel` .. versionadded:: 3.0 - ``\sphinxkeyboard`` + :code-tex:`\\sphinxkeyboard` .. versionadded:: 6.2.0 - ``\sphinxparam``, ``\sphinxsamedocref`` + :code-tex:`\\sphinxparam`, :code-tex:`\\sphinxsamedocref` .. versionadded:: 7.1.0 - ``\sphinxparamcomma`` which defaults to a comma followed by a space and - ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line - signatures (see :confval:`maximum_signature_line_length`). It defaults - to ``\texttt{,}`` to make these end-of-line separators more distinctive. - - Signatures of Python functions are rendered as ``name(parameters)`` - or ``name[type parameters](parameters)`` (see :pep:`695`) - where the length of ```` is set to ``0pt`` by default. - This can be changed via ``\setlength{\sphinxsignaturelistskip}{1ex}`` - for instance. + :code-tex:`\\sphinxparamcomma` which defaults to a comma followed by a + space and :code-tex:`\\sphinxparamcommaoneperline`. It is sed for + one-parameter-per-line signatures (see + :confval:`maximum_signature_line_length`) and defaults to + :code-tex:`\\texttt{,}`. + + Signatures of Python functions are rendered as + ``name(parameters)`` or ``name[type + parameters](parameters)`` (see :pep:`695`) where the length of + ```` is set to ``0pt`` by default. This can be changed via + :code-tex:`\\setlength{\\sphinxsignaturelistskip}{1ex}` for instance. - More text styling: @@ -1595,7 +1613,7 @@ Macros .. note:: To let this table fit on the page width in PDF output we have lied a bit. - For instance, the actual definition of ``\sphinxstylenotetitle`` is: + For instance, the actual definition of :code-tex:`\\sphinxstylenotetitle` is: .. code-block:: latex @@ -1604,90 +1622,98 @@ Macros The same remark applies to all other similar commands associated with admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not - use ``\sphinxremovefinalcolon`` as they don't need it. + use :code-tex:`\\sphinxremovefinalcolon` as they don't need it. .. versionadded:: 1.5 - These macros were formerly hard-coded as non customizable ``\texttt``, - ``\emph``, etc... + These macros were formerly hard-coded as non customizable :code-tex:`\\texttt`, + :code-tex:`\\emph`, etc... .. versionadded:: 1.6 - ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows + :code-tex:`\\sphinxstyletheadfamily` which defaults to + :code-tex:`\\sffamily` and allows multiple paragraphs in header cells of tables. .. versionadded:: 1.6.3 - ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``. + :code-tex:`\\sphinxstylecodecontinued` and + :code-tex:`\\sphinxstylecodecontinues`. .. versionadded:: 1.8 - ``\sphinxstyleindexlettergroup``, ``\sphinxstyleindexlettergroupDefault``. + :code-tex:`\\sphinxstyleindexlettergroup`, + :code-tex:`\\sphinxstyleindexlettergroupDefault`. .. versionadded:: 6.2.0 - ``\sphinxstylenotetitle`` et al. The ``#1`` is the localized name of the - directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}`` - if this final colon is to be removed. + :code-tex:`\\sphinxstylenotetitle` et al. The ``#1`` is the localized + name of the directive, with a final colon. Wrap it as + :code-tex:`\\sphinxremovefinalcolon{#1}` if this final colon is to be + removed. .. versionadded:: 7.4.0 - Added the ``\sphinxdotitlerowwithicon`` LaTeX command. + Added the :code-tex:`\\sphinxdotitlerowwithicon` LaTeX command. .. versionchanged:: 8.1.0 - ``\sphinxdotitlerowwithicon`` now detects automatically if an icon is + :code-tex:`\\sphinxdotitlerowwithicon` now detects automatically if an icon is associated or not with the rendered element used as first argument. - .. versionadded:: 8.1.0 - Make ``\sphinxdotitlerow`` an alias to ``\sphinxdotitlerowwithicon``. + .. versionadded:: 8.1.0 Make :code-tex:`\\sphinxdotitlerow` an alias to + :code-tex:`\\sphinxdotitlerowwithicon`. .. versionadded:: 8.1.0 Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are - also styled using ``\sphinxdotitlerow`` (they have no default icons + also styled using :code-tex:`\\sphinxdotitlerow` (they have no default icons associated with them). -- ``\sphinxtableofcontents``: A wrapper (defined differently in +- :code-tex:`\\sphinxtableofcontents`: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard - ``\tableofcontents``. The macro ``\sphinxtableofcontentshook`` is executed - during its expansion right before ``\tableofcontents`` itself. + :code-tex:`\\tableofcontents`. The macro + :code-tex:`\\sphinxtableofcontentshook` is executed during its expansion right + before :code-tex:`\\tableofcontents` itself. .. versionchanged:: 1.5 - Formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. + Formerly, the meaning of :code-tex:`\\tableofcontents` was modified by Sphinx. .. versionchanged:: 2.0 - Hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly - done during loading of ``'manual'`` docclass are now executed later via - ``\sphinxtableofcontentshook``. This macro is also executed by the - ``'howto'`` docclass, but defaults to empty with it. + Hard-coded redefinitions of :code-tex:`\\l@section` and + :code-tex:`\\l@subsection` formerly done during loading of ``'manual'`` + docclass are now executed later via + :code-tex:`\\sphinxtableofcontentshook`. This macro is also executed by + the ``'howto'`` docclass, but defaults to empty with it. .. hint:: If adding to preamble the loading of ``tocloft`` package, also add to - preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset - ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization. + preamble :code-tex:`\\renewcommand\sphinxtableofcontentshook{}` else it + will reset :code-tex:`\\l@section` and :code-tex:`\\l@subsection` + cancelling ``tocloft`` customization. -- ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'`` +- :code-tex:`\\sphinxmaketitle`: Used as the default setting of the ``'maketitle'`` :confval:`latex_elements` key. Defined in the class files :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`. .. versionchanged:: 1.8.3 - Formerly, ``\maketitle`` from LaTeX document class was modified by + Formerly, :code-tex:`\\maketitle` from LaTeX document class was modified by Sphinx. -- ``\sphinxbackoftitlepage``: For ``'manual'`` docclass, and if it is - defined, it gets executed at end of ``\sphinxmaketitle``, before the final - ``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key - of :confval:`latex_elements` to add a custom definition of - ``\sphinxbackoftitlepage``. +- :code-tex:`\\sphinxbackoftitlepage`: For ``'manual'`` docclass, and if it is + defined, it gets executed at end of :code-tex:`\\sphinxmaketitle`, before + the final :code-tex:`\\clearpage`. Use either the ``'maketitle'`` key or + the ``'preamble'`` key of :confval:`latex_elements` to add a custom + definition of :code-tex:`\\sphinxbackoftitlepage`. .. versionadded:: 1.8.3 -- ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references. +- :code-tex:`\\sphinxcite`: A wrapper of standard :code-tex:`\\cite` for + citation references. .. _sphinxbox: -The ``\sphinxbox`` command -~~~~~~~~~~~~~~~~~~~~~~~~~~ +The :code-tex:`\\sphinxbox` command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 6.2.0 -The ``\sphinxbox[key=value,...]{inline text}`` command can be used to "box" +The :code-tex:`\\sphinxbox[key=value,...]{inline text}` command can be used to "box" inline text elements with all the customizability which has been described in :ref:`additionalcss`. It is a LaTeX command with one optional argument, which is a comma-separated list of key=value pairs, as for :ref:`latexsphinxsetup`. @@ -1708,33 +1734,27 @@ Here is the complete list of keys. They don't use any prefix. - and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``, or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``. -This last key is specific to ``\sphinxbox`` and it means to add a ``\strut`` -so that heights and depths are equalized across various instances on the same -line with varying contents. The default is ``addstrut=false``. - -.. important:: - - Perhaps the default will turn into ``addstrut=true`` at 7.0.0 depending on - feedback until then. - -The combination ``addstrut, padding-bottom=0pt, padding-top=1pt`` is often -satisfactory. +This last key is specific to :code-tex:`\\sphinxbox` and it means to add a +:code-tex:`\\strut` so that heights and depths are equalized across various +instances on the same line with varying contents. The default is +``addstrut=false``. The combination ``addstrut, padding-bottom=0pt, +padding-top=1pt`` is often satisfactory. Refer to :ref:`additionalcss` for important syntax information regarding the -other keys. The default -configuration uses no shadow, a border-width of ``\fboxrule``, a padding of -``\fboxsep``, circular corners with radii ``\fboxsep`` and background and -border colors as for the default rendering of code-blocks. +other keys. The default configuration uses no shadow, a border-width of +:code-tex:`\\fboxrule`, a padding of :code-tex:`\\fboxsep`, circular corners +with radii :code-tex:`\\fboxsep` and background and border colors as for the +default rendering of code-blocks. -When a ``\sphinxbox`` usage is nested within another one, it will ignore the +When a :code-tex:`\\sphinxbox` usage is nested within another one, it will ignore the options of the outer one: it first resets all options to their default state as they were prior to applying the outer box options, then it applies its own specific ones. -One can modify these defaults via the command ``\sphinxboxsetup{key=value,...}``. -The effect is cumulative, if one uses this command multiple times. Here the -options are a mandatory argument so are within curly braces, not square -brackets. +One can modify these defaults via the command +:code-tex:`\\sphinxboxsetup{key=value,...}`. The effect is cumulative, if one +uses this command multiple times. Here the options are a mandatory argument +so are within curly braces, not square brackets. Here is some example of use: @@ -1751,9 +1771,9 @@ Here is some example of use: ''', } -A utility ``\newsphinxbox`` is provided to create a new boxing macro, say -``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra -configuration: +A utility :code-tex:`\\newsphinxbox` is provided to create a new boxing macro, +say :code-tex:`\\foo` which will act exactly like :code-tex:`\\sphinxbox` but +with a given extra configuration: .. code-block:: latex @@ -1763,13 +1783,15 @@ configuration: \protected\def\sphinxguilabel#1{\foo{#1}} \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}} -Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox`` -the current configuration as set possibly mid-way in document via -``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference -is that they have an initial additional set of default extras. +Boxes rendered with :code-tex:`\\foo` obey as the ones using directly +:code-tex:`\\sphinxbox` the current configuration as set possibly mid-way in +document via :code-tex:`\\sphinxboxsetup` (from a :dudir:`raw` LaTeX mark-up), +the only difference is that they have an initial additional set of default +extras. -In the above examples, you can probably use ``\renewcommand`` syntax if you -prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then). +In the above examples, you can probably use :code-tex:`\\renewcommand` syntax +if you prefer it to :code-tex:`\\protected\\def` (with ``[1]`` in place of +``#1`` then). Environments @@ -1777,11 +1799,11 @@ Environments - A :dudir:`figure` may have an optional legend with arbitrary body elements: they are rendered in a ``sphinxlegend`` environment. The default - definition issues ``\small``, and ends with ``\par``. + definition issues :code-tex:`\\small`, and ends with :code-tex:`\\par`. .. versionadded:: 1.5.6 - Formerly, the ``\small`` was hardcoded in LaTeX writer and the ending - ``\par`` was lacking. + Formerly, the :code-tex:`\\small` was hardcoded in LaTeX writer and the ending + :code-tex:`\\par` was lacking. - Environments associated with admonitions: @@ -1795,7 +1817,7 @@ Environments - ``sphinxdanger``, - ``sphinxerror``. - They may be ``\renewenvironment`` + They may be :code-tex:`\\renewenvironment` 'd individually, and must then be defined with one argument (it is the heading of the notice, for example ``Warning:`` for :dudir:`warning` directive, if English is the document language). Their default definitions use either the @@ -1861,7 +1883,7 @@ Environments .. versionadded:: 1.6.6 Easier customizability of the formatting via exposed to user LaTeX macros - such as ``\sphinxVerbatimHighlightLine``. + such as :code-tex:`\\sphinxVerbatimHighlightLine`. - The bibliography uses ``sphinxthebibliography`` and the Python Module index as well as the general index both use ``sphinxtheindex``; these environments @@ -1874,36 +1896,37 @@ Environments Miscellany ~~~~~~~~~~ -- Every text paragraph in document body starts with ``\sphinxAtStartPar``. +- Every text paragraph in document body starts with :code-tex:`\\sphinxAtStartPar`. Currently, this is used to insert a zero width horizontal skip which is a trick to allow TeX hyphenation of the first word of a paragraph in a narrow context (like a table cell). For ``'lualatex'`` which - does not need the trick, the ``\sphinxAtStartPar`` does nothing. + does not need the trick, the :code-tex:`\\sphinxAtStartPar` does nothing. .. versionadded:: 3.5.0 - The section, subsection, ... headings are set using *titlesec*'s - ``\titleformat`` command. + :code-tex:`\\titleformat` command. - For the ``'manual'`` docclass, the chapter headings can be customized using - *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File - :file:`sphinx.sty` has custom re-definitions in case of *fncychap* - option ``Bjarne``. + *fncychap*'s commands :code-tex:`\\ChNameVar`, :code-tex:`\\ChNumVar`, + :code-tex:`\\ChTitleVar`. File :file:`sphinx.sty` has custom re-definitions in + case of *fncychap* option ``Bjarne``. .. versionchanged:: 1.5 Formerly, use of *fncychap* with other styles than ``Bjarne`` was dysfunctional. - The :dudir:`role` directive allows to mark inline text with class arguments. - This is handled in LaTeX output via the ``\DUrole`` dispatcher command `as - in Docutils `_. Object signatures also use ``\DUrole`` for - some components, with one or two-letters class names as in HTML output. + This is handled in LaTeX output via the :code-tex:`\\DUrole` dispatcher + command `as in Docutils `_. Object signatures also use + :code-tex:`\\DUrole` for some components, with one or two-letters class + names as in HTML output. .. versionchanged:: 8.1.0 When multiple classes are injected via a a custom role, the LaTeX output - uses nested ``\DUrole``'s as in the `Docutils documentation - `_. Formerly it used a single ``\DUrole`` with comma - separated classes, making the LaTeX customization more arduous. + uses nested :code-tex:`\\DUrole`'s as in the `Docutils documentation + `_. Formerly it used a single :code-tex:`\\DUrole` with + comma separated classes, making the LaTeX customization more arduous. .. _classarguments: https://docutils.sourceforge.io/docs/user/latex.html#custom-interpreted-text-roles diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 5ffe2ea4a38..8ae9a0cc55a 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -2788,7 +2788,8 @@ These options influence LaTeX output. * :code-py:`'uplatex'` -- upLaTeX (default if :confval:`language` is :code-py:`'ja'`) - .. caution:: + .. important:: + ``'pdflatex'``\ 's support for Unicode characters is limited. If your project uses Unicode characters, setting the engine to ``'xelatex'`` or ``'lualatex'`` @@ -2800,10 +2801,10 @@ These options influence LaTeX output. .. note:: - Sphinx 2.0 adds support to ``'pdflatex'`` in Latin language document of - occasional Cyrillic or Greek letters or words. - This is not automatic, see the discussion - of the ``'fontenc'`` key in :confval:`latex_elements` . + Sphinx 2.0 adds support for occasional Cyrillic and Greek letters or + words in documents using a Latin language and ``'pdflatex'``. To enable + this, the :ref:`fontenc` key of :ref:`latex_elements + ` must be used appropriately. .. note:: @@ -2813,23 +2814,24 @@ These options influence LaTeX output. the only comprehensive solution (as far as we know) is to use ``'xelatex'`` or ``'lualatex'`` *and* to add ``r'\usepackage{unicode-math}'`` - (e.g. via the :confval:`latex_elements` ``'preamble'`` key). + (e.g. via the :ref:`preamble` key of :ref:`latex_elements + `). You may prefer ``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode literal such as ``α`` (U+03B1) as-is in output, rather than being rendered as :math:`\alpha`. .. versionchanged:: 2.1.0 - Use ``xelatex`` (and LaTeX package ``xeCJK``) + Use ``'xelatex'`` (and LaTeX package ``xeCJK``) by default for Chinese documents. .. versionchanged:: 2.2.1 - Use ``xelatex`` by default for Greek documents. + Use ``'xelatex'`` by default for Greek documents. .. versionchanged:: 2.3 - Add ``uplatex`` support. + Add ``'uplatex'`` support. .. versionchanged:: 4.0 - Use ``uplatex`` by default for Japanese documents. + Use ``'uplatex'`` by default for Japanese documents. .. confval:: latex_documents :type: :code-py:`Sequence[tuple[str, str, str, str, str, bool]]` @@ -2899,16 +2901,16 @@ These options influence LaTeX output. :type: :code-py:`'part' | 'chapter' | 'section'` :default: :code-py:`None` - This value determines the topmost sectioning unit. - By default, the topmost sectioning unit is switched by documentclass: - ``section`` is used if documentclass will be ``howto``, - otherwise ``chapter`` is used be used. + This value determines the topmost sectioning unit. The default setting is + ``'section'`` if :confval:`latex_theme` is ``'howto'``, and ``'chapter'`` + if it is ``'manual'``. The alternative in both cases is to specify + ``'part'``, which means that LaTeX document will use the :code-tex:`\\part` + command. - Note that if LaTeX uses :code-tex:`\\part` command, - then the numbering of sectioning units one level deep gets off-sync - with HTML numbering, - because LaTeX numbers :code-tex:`\\chapter` continuously - (or :code-tex:`\\section` for ``howto``). + In that case the numbering of sectioning units one level deep gets off-sync + with HTML numbering, as by default LaTeX does not reset + :code-tex:`\\chapter` numbering (or :code-tex:`\\section` for ``'howto'`` + theme) when encountering :code-tex:`\\part` command. .. versionadded:: 1.4 @@ -3107,7 +3109,7 @@ These options influence LaTeX output. Use Xindy_ to prepare the index of general terms. By default, the LaTeX builder uses :program:`makeindex` for preparing the index of general terms . - This means that words with UTF-8 characters will be + Using Xindy_ means that words with UTF-8 characters will be ordered correctly for the :confval:`language`. .. _Xindy: https://xindy.sourceforge.net/ @@ -3131,7 +3133,7 @@ These options influence LaTeX output. for using :code-py:`'pdflatex'` engine with Cyrillic scripts. With both :code-py:`'pdflatex'` and Unicode engines, Cyrillic documents handle the indexing of Latin names correctly, - even with diacritics. + even those having diacritics. .. versionadded:: 1.8 @@ -3167,12 +3169,9 @@ These options influence LaTeX output. A list of file names, relative to the :term:`configuration directory`, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn't copy automatically, - e.g. if they are referenced in custom LaTeX added in ``latex_elements``. + or to overwrite Sphinx LaTeX support files with custom versions. Image files that are referenced in source files (e.g. via ``.. image::``) - are copied automatically. - - You have to make sure yourself that the filenames don't collide with those - of any automatically copied files. + are copied automatically and should not be listed there. .. attention:: Filenames with the ``.tex`` extension will be automatically