Make the latex docs more concise

doc/latex.rst

@@ -33,167 +33,143 @@ The *latex* target does not benefit from pre-prepared themes like the
 Basic customization
 -------------------
 
-It is available from ``conf.py`` via usage of the
+It is achieved via usage of the
-:ref:`latex-options` as described in :doc:`config` (backslashes must be doubled
+:ref:`latex-options` as described in :doc:`config`. For example::
-in Python string literals to reach latex.) For example::
 
-    # inside conf.py
+   # inside conf.py
-    latex_engine = 'xelatex'
+   latex_engine = 'xelatex'
-    latex_elements = {
+   latex_elements = {
-        'fontenc': '\\usepackage{fontspec}',
+       'fontpkg': r'''
-        'fontpkg': '''\
+   \setmainfont{DejaVu Serif}
-    \\setmainfont{DejaVu Serif}
+   \setsansfont{DejaVu Sans}
-    \\setsansfont{DejaVu Sans}
+   \setmonofont{DejaVu Sans Mono}
-    \\setmonofont{DejaVu Sans Mono}''',
+   ''',
-        'geometry': '\\usepackage[vmargin=2.5cm, hmargin=3cm]{geometry}',
+       'preamble': r'''
-        'preamble': '''\
+   \usepackage[titles]{tocloft}
-    \\usepackage[titles]{tocloft}
+   \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
-    \\cftsetpnumwidth {1.25cm}\\cftsetrmarg{1.5cm}
+   \setlength{\cftchapnumwidth}{0.75cm}
-    \\setlength{\\cftchapnumwidth}{0.75cm}
+   \setlength{\cftsecindent}{\cftchapnumwidth}
-    \\setlength{\\cftsecindent}{\\cftchapnumwidth}
+   \setlength{\cftsecnumwidth}{1.25cm}
-    \\setlength{\\cftsecnumwidth}{1.25cm}''',
+   ''',
-        'fncychap': '\\usepackage[Bjornstrup]{fncychap}',
+       'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
-        'printindex': '\\footnotesize\\raggedright\\printindex',
+       'printindex': r'\footnotesize\raggedright\printindex',
-    }
+   }
-    latex_show_urls = 'footnote'
+   latex_show_urls = 'footnote'
 
 .. the above was tested on Sphinx's own 1.5a2 documentation with good effect!
 
 .. highlight:: latex
 
-More advanced customization will be obtained via insertion into the LaTeX
+If the size of the ``'preamble'`` contents become inconvenient, one may put
-preamble of relevant ``\renewcommand``, ``\renewenvironment``, ``\setlength``,
+all needed macros into some file :file:`mystyle.tex` of the project source
-or ``\definecolor`` commands. The ``'preamble'`` key of
+repertory, and get LaTeX to import it at run time::
-:confval:`latex_elements` will serve for inserting these commands. If they are
-numerous, it may prove more convenient to assemble them into a specialized
-file :file:`mystyle.tex` and then use::
 
-    'preamble': r'\makeatletter\input{mystyle.tex}\makeatother',
+   'preamble': r'\input{mystyle.tex}',
+   # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
+   'preamble': r'\usepackage{mystyle}',
 
-or, better, to set up a style file
+It is needed to set appropriately :confval:`latex_additional_files`, for
-:file:`mystyle.sty` which can then be loaded via::
+example::
 
-    'preamble': r'\usepackage{mystyle}',
+   latex_additional_files = ["mystyle.tex"]
-
-The :ref:`build configuration file <build-config>` file for the project needs
-to have its variable :confval:`latex_additional_files` appropriately
-configured, for example::
-
-    latex_additional_files = ["mystyle.sty"]
 
 .. _latexsphinxsetup:
 
-The Sphinx LaTeX style package options
+The LaTeX style file options
---------------------------------------
+----------------------------
 
-The ``'sphinxsetup'`` key to :confval:`latex_elements` provides a
+The sphinxsetup interface
-more convenient interface to various style parameters. It is a comma separated
+~~~~~~~~~~~~~~~~~~~~~~~~~
-string of ``key=value`` instructions::
 
-    key1=value1,key2=value2, ...
+The ``'sphinxsetup'`` key of :confval:`latex_elements` provides a convenient
+interface to the package options of the Sphinx style file::
 
-- if a key is repeated, it is its last occurence which is used
+   latex_elements = {
-- spaces around the commas and equal signs are ignored
+       'sphinxsetup': 'key1=value1, key2=value2, ...',
+   }
 
-If non-empty, it will be passed as argument to the ``\sphinxsetup`` command::
+- some values may be LaTeX macros, then the backslashes must be
+  Python-escaped, or the whole must be a Python raw string,
+- LaTeX boolean keys require *lowercase* ``true`` or ``false`` values,
+- spaces around the commas and equal signs are ignored, spaces inside LaTeX
+  macros may be significant.
 
-    \usepackage{sphinx}
+If non-empty, it will be passed as argument to the ``\sphinxsetup`` macro
-    \sphinxsetup{key1=value1,key2=value2,...}
+inside the document preamble, like this::
+
+   \usepackage{sphinx}
+   \sphinxsetup{key1=value1, key2=value2,...}
 
 .. versionadded:: 1.5
 
+It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
+directly into the body of the document, via the help of the :rst:dir:`raw`
+directive. This is what is done for this documentation, for local styling
+of this chapter in the PDF output::
+
+   .. raw:: latex
+
+      \begingroup
+      \sphinxsetup{%
+            verbatimwithframe=false,
+            VerbatimColor={named}{OldLace},
+            TitleColor={named}{DarkGoldenrod},
+            hintBorderColor={named}{LightCoral},
+            attentionborder=3pt,
+            attentionBorderColor={named}{Crimson},
+            attentionBgColor={named}{FloralWhite},
+            noteborder=2pt,
+            noteBorderColor={named}{Olive},
+            cautionborder=3pt,
+            cautionBorderColor={named}{Cyan},
+            cautionBgColor={named}{LightCyan}}
+
+at the start of the chapter and::
+
+    .. raw:: latex
+
+       \endgroup
+
+at its end.
+
 .. note::
 
-   - Most options described next could also have been positioned as
+   The colors above are made available via the ``svgnames`` option of
-     :file:`sphinx.sty` package options. But for those where the key value
+   the "xcolor" package::
-     contains some LaTeX code the use of ``\sphinxsetup`` is mandatory. Hence
-     the whole ``'sphinxsetup'`` string is passed as argument to
-     ``\sphinxsetup``.
 
-   - As an alternative to the ``'sphinxsetup'`` key, it is possible
+      latex_elements = {
-     to insert the ``\\sphinxsetup{key=value,..}`` inside the
+          'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
-     ``'preamble'`` key. It is even possible to use the ``\sphinxsetup`` in
+      }
-     the body of the document, via the :rst:dir:`raw` directive, to modify
-     dynamically the option values: this is actually what we did for the
-     duration of this chapter for the PDF output, which is styled using::
-
-       \sphinxsetup{%
-         verbatimwithframe=false,
-         VerbatimColor={named}{OldLace},
-         TitleColor={named}{DarkGoldenrod},
-         hintBorderColor={named}{LightCoral},
-         attentionborder=3pt,
-         attentionBorderColor={named}{Crimson},
-         attentionBgColor={named}{FloralWhite},
-         noteborder=2pt,
-         noteBorderColor={named}{Olive},
-         cautionborder=3pt,
-         cautionBorderColor={named}{Cyan},
-         cautionBgColor={named}{LightCyan}}
-
-     and with the ``svgnames`` option having been passed to "xcolor" package::
-
-         latex_elements = {
-             'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
-         }
 
 
-Here are the currently available options together with their default values.
+The available styling options
-
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. caution::
-
-   These options correspond to what has been so far the default LaTeX
-   rendering by Sphinx; if in future Sphinx offers various *themes* for LaTeX,
-   the interface may change.
-
-.. attention::
-
-   LaTeX requires that keys with Boolean values use **lowercase** ``true`` or
-   ``false``.
 
 .. _latexsphinxsetuphmargin:
 
-``hmargin``
+``hmargin, vmargin``
-    The dimensions of the horizontal margins. Legacy Sphinx default value is
+    The dimensions of the horizontal (resp. vertical) margins, passed as
-    ``1in`` (which stands for ``{1in,1in}``.) It is passed over as ``hmargin``
+    ``hmargin`` (resp. ``vmargin``) option to
-    option to ``geometry`` package.
+    the ``geometry`` package. The default is ``1in``, which is equivalent to
-
+    ``{1in,1in}``. Example::
-    Here is an example for non-Japanese documents of use of this key::
 
       'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
 
-    Japanese documents currently accept only the form with only one dimension.
+    Japanese documents currently accept only the one-dimension format for
-    This option is handled then in a special manner in order for ``geometry``
+    these parameters. The ``geometry`` package is then passed suitable options
-    package to set the text width to an exact multiple of the *zenkaku* width
+    to get the text width set to an exact multiple of the *zenkaku* width, and
-    of the base document font.
+    the text height set to an integer multiple of the baselineskip, with the
+    closest fit for the margins.
 
     .. hint::
 
-       For a ``'manual'`` type document with :confval:`language` set to
+       For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``,
-       ``'ja'``, which by default uses the ``jsbook`` LaTeX document class, the
+       use the ``nomag`` extra document class option (cf.
-       dimension units, when the pointsize isn't ``10pt``, must be so-called TeX
+       ``'extraclassoptions'`` key of :confval:`latex_elements`) or so-called
-       "true" units::
+       TeX "true" units:
 
          'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
 
-       This is due to the way the LaTeX class ``jsbook`` handles the
-       pointsize.
-
-       Or, one uses regular units but with ``nomag`` as extra document class
-       option (cf. ``'extraclassoptions'`` key of :confval:`latex_elements`.)
-
-    .. versionadded:: 1.5.3
-
-``vmargin``
-    The dimension of the vertical margins. Legacy Sphinx default value is
-    ``1in`` (or ``{1in,1in}``.) Passed over as ``vmargin`` option to
-    ``geometry``.
-
-    Japanese documents will arrange for the text height to be an integer
-    multiple of the baselineskip, taking the closest match suitable for the
-    asked-for vertical margin. It can then be only one dimension. See notice
-    above.
-
     .. versionadded:: 1.5.3
 
 ``marginpar``
@@ -207,17 +183,12 @@ Here are the currently available options together with their default values.
     default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal
     includes are framed. Setting it to ``false`` does not deactivate use of
     package "framed", because it is still in use for the optional background
-    colour (see below).
+    colour.
 
 ``verbatimwrapslines``
     default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's
     contents should wrap.
 
-    .. (comment) It is theoretically possible to customize this even
-       more and decide at which characters a line-break can occur and whether
-       before or after, but this is accessible currently only by re-defining
-       some macros with complicated LaTeX syntax from :file:`sphinx.sty`.
-
 ``parsedliteralwraps``
     default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
     contents should wrap.
@@ -237,29 +208,19 @@ Here are the currently available options together with their default values.
 
 ``verbatimvisiblespace``
     default ``\textcolor{red}{\textvisiblespace}``. When a long code line is
-    split, space characters located at end of the line before the break are
+    split, the last space character from the source code line right before the
-    displayed using this code.
+    linebreak location is typeset using this.
 
 ``verbatimcontinued``
-    The default is::
+    A LaTeX macro inserted at start of continuation code lines. Its
+    (complicated...) default typesets a small red hook pointing to the right::
 
       \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
 
-    It is printed at start of continuation lines. This rather formidable
-    expression reserves twice the width of a typical character in the current
-    (monospaced) font and puts there a small red hook pointing to the right.
-
     .. versionchanged:: 1.5
-       The breaking of long code lines was introduced at 1.4.2. The space
+       The breaking of long code lines was added at 1.4.2. The default
-       reserved to the continuation symbol was changed at 1.5 to obey the
+       definition of the continuation symbol was changed at 1.5 to accomodate
-       current font characteristics (this was needed as Sphinx 1.5 LaTeX
+       various font sizes (e.g. code-blocks can be in footnotes).
-       allows code-blocks in footnotes which use a smaller font size).
-
-       .. hint::
-
-          This specification gives the same spacing as before 1.5::
-
-            \normalfont\normalsize\makebox[3ex][r]{\textcolor{red}{\tiny$\hookrightarrow$}
 
 ``TitleColor``
     default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured
@@ -384,39 +345,31 @@ Here are the currently available options together with their default values.
 
 ``BeforeFootnote``
     default ``\leavevmode\unskip``. LaTeX macros inserted before the footnote
-    mark. The default removes possible space before it.
+    mark. The default removes possible space before it (else, TeX could insert
-
+    a linebreak there).
-    It can be set to empty (``BeforeFootnote={},``) to recover the earlier
-    behaviour of Sphinx, or alternatively contain a ``\nobreak\space`` or a
-    ``\thinspace`` after the ``\unskip`` to insert some chosen
-    (non-breakable) space.
 
     .. versionadded:: 1.5
-       formerly, footnotes from explicit mark-up (but not automatically
-       generated ones) were preceded by a space in the output ``.tex`` file
-       hence a linebreak in PDF was possible. To avoid insertion of this space
-       one could use ``foo\ [#f1]`` mark-up, but this impacts all builders.
 
 ``HeaderFamily``
     default ``\sffamily\bfseries``. Sets the font used by headings.
 
-As seen above, key values may even be used for LaTeX commands. But don't
+LaTeX macros and environments
-forget to double the backslashes if not using "raw" Python strings.
+-----------------------------
 
-The LaTeX environments defined by Sphinx
+Here are some macros from the package file :file:`sphinx.sty` and class files
-----------------------------------------
+:file:`sphinxhowto.cls`, :file:`sphinxmanual.cls`, which have public names
+thus allowing redefinitions. Check the respective files for the defaults.
 
-Let us now list some macros from the package file
+Macros
-:file:`sphinx.sty` and class file :file:`sphinxhowto.cls` or
+~~~~~~
-:file:`sphinxmanual.cls`, which can be entirely redefined, if desired.
 
-- text styling commands (they have one argument): ``\sphinx<foo>`` with
+- text styling commands ``\sphinx<foo>`` with ``<foo>`` being one of
-  ``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
+  ``strong``, ``bfcode``, ``email``, ``tablecontinued``, ``titleref``,
-  ``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``,
+  ``menuselection``, ``accelerator``, ``crossref``, ``termref``, ``optional``.
-  ``optional``. The non-prefixed macros will still be defined if option
+  The non-prefixed macros will still be defined if option
   :confval:`latex_keep_old_macro_names` has been set to ``True`` (default is
-  ``False``), in which case the prefixed macros expand to the
+  ``False``), in which case the prefixed macros expand to the non-prefixed
-  non-prefixed ones.
+  ones.
 
   .. versionadded:: 1.4.5
      Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
@@ -427,21 +380,39 @@ Let us now list some macros from the package file
      already exists at ``sphinx.sty`` loading time, only the ``\sphinx``
      prefixed one will be defined. The setting will be removed at 1.7.
 
-- more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
+- more text styling: ``\sphinxstyle<bar>`` with ``<bar>`` one of
   ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
   ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
-  ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
+  ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``,
-  ``abbreviation``, ``literalintitle``.
+  ``literalstrong``, ``abbreviation``, ``literalintitle``.
 
   .. versionadded:: 1.5
-     the new macros are wrappers of the formerly hard-coded ``\texttt``,
+     these macros were formerly hard-coded as non customizable ``\texttt``,
-     ``\emph``, ... The default definitions can be found in
+     ``\emph``, etc...
-     :file:`sphinx.sty`.
   .. versionadded:: 1.6
      ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows
      multiple paragraphs in header cells of tables.
   .. deprecated:: 1.6
      macro ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7.
+- by default the Sphinx style file ``sphinx.sty`` executes the command
+  ``\fvset{fontsize=\small}`` as part of its configuration of
+  ``fancyvrb.sty``. This may be overriden for example via
+  ``\fvset{fontsize=auto}`` which will let code listings use the ambient font
+  size. Refer to ``fancyvrb.sty``'s documentation for further keys.
+
+  .. versionadded:: 1.5
+- the table of contents is typeset via ``\sphinxtableofcontents`` which is a
+  wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in
+  :file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
+
+  .. versionchanged:: 1.5
+     formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
+- the ``\maketitle`` command is redefined by the class files
+  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
+
+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``.
@@ -459,15 +430,17 @@ Let us now list some macros from the package file
   specific to each type, which can be set via ``'sphinxsetup'`` string.
 
   .. versionchanged:: 1.5
-     use of public environment names, separate customizability of the parameters.
+     use of public environment names, separate customizability of the
+     parameters, such as ``noteBorderColor``, ``noteborder``,
+     ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ...
 - the :dudir:`contents` directive (with ``:local:`` option) and the
   :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
-  See above for the three dimensions associated with it.
 
+  .. versionadded:: 1.4.2
+     former code refactored into an environment allowing page breaks.
   .. versionchanged:: 1.5
-     use of public names for the three lengths. The environment itself was
+     options ``shadowsep``, ``shadowsize``,  ``shadowrule``.
-     redefined to allow page breaks at release 1.4.2.
+- the literal blocks (via ``::`` or :rst:dir:`code-block`), are
-- the literal blocks (:rst:dir:`code-block` directives, etc ...), are
   implemented using ``sphinxVerbatim`` environment which is a wrapper of
   ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
   of the top caption and the wrapping of long lines, and a frame which allows
@@ -476,41 +449,12 @@ Let us now list some macros from the package file
   allows a caption).
 
   .. versionchanged:: 1.5
-     ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (meaning
+     ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also
-     which is the one of ``OriginalVerbatim`` too), and custom one is called
+     under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used
-     ``sphinxVerbatim``. Also, earlier version of Sphinx used
+     inside tables.
-     ``OriginalVerbatim`` inside tables (captions were lost, long code lines
-     were not wrapped), it now uses there ``sphinxVerbatimintable``.
   .. versionadded:: 1.5
-     the two customizable lengths, the ``sphinxVerbatimintable``, the boolean
+     options ``verbatimwithframe``, ``verbatimwrapslines``,
-     toggles described above.
+     ``verbatimsep``, ``verbatimborder``.
-- by default the Sphinx style file ``sphinx.sty`` includes the command
-  ``\fvset{fontsize=\small}`` as part of its configuration of
-  ``fancyvrb.sty``. The user may override this for example via
-  ``\fvset{fontsize=auto}`` which will use for listings the ambient
-  font size. Refer to ``fancyvrb.sty``'s documentation for further keys.
-
-  .. versionadded:: 1.5
-     formerly, the use of ``\small`` for code listings was not customizable.
-- the section, subsection, ...  headings are set using  *titlesec*'s
-  ``\titleformat`` command. Check :file:`sphinx.sty` for the definitions.
-- for the ``'sphinxmanual'`` class (corresponding to the fifth element of
-  :confval:`latex_documents` being set to ``'manual'``), the chapter headings
-  can be customized using *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``,
-  ``\ChTitleVar``. Check :file:`sphinx.sty` for the default definitions. They
-  are applied only if *fncychap* is loaded with option ``Bjarne``. It is also
-  possible to use an empty ``'fncychap'`` key, and use the *titlesec*
-  ``\titleformat`` command to style the chapter titles.
-
-  .. versionchanged:: 1.5
-     formerly, use of *fncychap* with other styles than ``Bjarne`` was
-     dysfunctional.
-- the table of contents is typeset via ``\sphinxtableofcontents`` which is a
-  wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in
-  :file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
-
-  .. versionchanged:: 1.5
-     formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
 - the bibliography and Python Module index are typeset respectively within
   environments ``sphinxthebibliography`` and ``sphinxtheindex``, which are
   simple wrappers of the non-modified ``thebibliography`` and ``theindex``
@@ -519,7 +463,20 @@ Let us now list some macros from the package file
   .. versionchanged:: 1.5
      formerly, the original environments were modified by Sphinx.
 
-- the list is not exhaustive: refer to :file:`sphinx.sty` for more.
+Miscellany
+~~~~~~~~~~
+
+- the section, subsection, ...  headings are set using  *titlesec*'s
+  ``\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``.
+
+  .. versionchanged:: 1.5
+     formerly, use of *fncychap* with other styles than ``Bjarne`` was
+     dysfunctional.
+- check file :file:`sphinx.sty` for more...
 
 .. hint::