*********************************
Sage, LaTeX and Friends
*********************************

Sage and the LaTeX dialect of TeX have an intensely synergistic relationship.
This section aims to introduce the variety of interactions, beginning with the
most basic and proceeding to the more unusual.

Overview
========

It may be easiest to understand the various uses of LaTeX with a
brief overview of the mechanics of the three principal methods
employed by Sage.

    #. Every "object" in Sage is required to have a LaTeX representation.  You
       can access this representation by executing ``latex(foo)`` where
       ``foo`` is some object in Sage.  The output is a string that should
       render a reasonably accurate representation of ``foo`` when used in
       TeX's math-mode (for example, when enclosed between a pair of single
       dollar signs). Some examples of this follow below.

       In this way, Sage can be used effectively for constructing portions of
       a LaTeX document: create or compute an object in Sage, print ``latex()``
       of the object and cut/paste it into your document.

    #. The Jupyter notebook interface uses `MathJax <http://www.mathjax.org>`_
       to render mathematics cleanly in a web browser. You can start this
       automatic rendering by executing ``%display latex`` (and stop by
       executing ``%display plain``).

       MathJax is an open source JavaScript display engine for mathematics that
       works in all modern browsers.  It is able to render a large, but not
       totally complete, subset of TeX.  It has no support for things like
       complicated tables, sectioning or document management, as it is oriented
       towards accurately rendering "snippets" of TeX. Seemingly automatic
       rendering of math in the notebook is provided by converting the
       ``latex()`` representation of an object (as described above) into a form
       of HTML palatable to MathJax.

    #. A system-wide installation of LaTeX can be employed.  Sage includes
       almost everything you need to build and use Sage, but a significant
       exception is TeX itself.  So in these situations you need to have
       TeX installed, along with some associated conversion utilities, to
       utilize the full power.

Here we demonstrate some basic uses of the ``latex()`` function. ::

    sage: var('z')
    z
    sage: latex(z^12)
    z^{12}
    sage: latex(integrate(z^4, z))
    \frac{1}{5} \, z^{5}
    sage: latex('a string')
    \text{\texttt{a{ }string}}
    sage: latex(QQ)
    \Bold{Q}
    sage: latex(matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]))
    \left(\begin{array}{rrr}
    2 & 4 & 6 \\
    -1 & -1 & -1
    \end{array}\right)

Basic MathJax functionality is largely automatic in the notebook, but we can
partially demonstrate this support with the ``MathJax`` class.  The object of
this class converts a Sage object to its LaTeX representation and then wraps it
in HTML.  ::

    sage: from sage.misc.html import MathJax
    sage: mj = MathJax()
    sage: var('z')
    z
    sage: mj(z^12)
    <html>\[z^{12}\]</html>
    sage: mj(QQ)
    <html>\[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Q}\]</html>
    sage: mj(ZZ['x'])
    <html>\[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Z}[x]\]</html>
    sage: mj(integrate(z^4, z))
    <html>\[\frac{1}{5} \, z^{5}\]</html>

Basic Use
=========

As indicated in the overview, the simplest way to exploit Sage's support of
LaTeX is to use the ``latex()`` function to create legitimate LaTeX code to
represent mathematical objects.  These strings can then be incorporated into
standalone LaTeX documents.

At the other extreme is the ``view()`` command. The command ``view(foo)`` will
create the LaTeX representation of ``foo``, incorporate this into a simple
LaTeX document, and then process that document with your system-wide TeX
installation.  Finally, the appropriate viewer will be called to display the
output from the TeX command.  Which version of TeX is used, and therefore the
nature of the output and associated viewer, can be customized (see
:ref:`sec-custom-processing`).

.. _sec-custom-generation:

Customizing LaTeX Generation
============================

There are several ways to customize the actual LaTeX code generated by the
``latex()`` command. There is a pre-defined object named ``latex`` which has
several methods, which you can list by typing ``latex.``, followed by the
:kbd:`Tab` key (note the period).

A good example is the ``latex.matrix_delimiters`` method.  It can be
used to change the notation surrounding a matrix -- large parentheses,
brackets, braces, vertical bars.  No notion of style is enforced,
you can mix and match as you please.  Notice how the backslashes
needed in LaTeX require an extra slash so they are escaped
properly within the Python string.  ::

    sage: A = matrix(ZZ, 2, 2, range(4))
    sage: latex(A)
    \left(\begin{array}{rr}
    0 & 1 \\
    2 & 3
    \end{array}\right)
    sage: latex.matrix_delimiters(left='[', right=']')
    sage: latex(A)
    \left[\begin{array}{rr}
    0 & 1 \\
    2 & 3
    \end{array}\right]
    sage: latex.matrix_delimiters(left='\\{', right='\\}')
    sage: latex(A)
    \left\{\begin{array}{rr}
    0 & 1 \\
    2 & 3
    \end{array}\right\}

The ``latex.vector_delimiters`` method works similarly.

The way common rings and fields (integers, rational, reals, etc.)
are typeset can be controlled by the ``latex.blackboard_bold``
method.  These sets are by default typeset in bold, but may
optionally be written in a double-struck fashion as sometimes
done in written work.  This is accomplished by redefining the
``\Bold{}`` macro which is built-in to Sage. ::

    sage: latex(QQ)
    \Bold{Q}
    sage: from sage.misc.html import MathJax
    sage: mj = MathJax()
    sage: mj(QQ)
    <html>\[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Q}\]</html>
    sage: latex.blackboard_bold(True)
    sage: mj(QQ)
    <html>\[\newcommand{\Bold}[1]{\mathbb{#1}}\Bold{Q}\]</html>
    sage: latex.blackboard_bold(False)

It is possible to take advantage of the extensible nature of TeX by adding in
new macros and new packages.  First, individual macros can be added so that
they are used when MathJax interprets a snippet of TeX in the notebook.  ::

    sage: latex.extra_macros()
    ''
    sage: latex.add_macro("\\newcommand{\\foo}{bar}")
    sage: latex.extra_macros()
    '\\newcommand{\\foo}{bar}'
    sage: var('x y')
    (x, y)
    sage: latex(x+y)
    x + y
    sage: from sage.misc.html import MathJax
    sage: mj = MathJax()
    sage: mj(x+y)
    <html>\[\newcommand{\foo}{bar}x + y\]</html>

Additional macros added this way will also be used in the event that the
system-wide version of TeX is called on something larger than MathJax can
handle.  The command ``latex_extra_preamble`` is used to build the preamble of
a complete LaTeX document, so the following illustrates how this is
accomplished. As usual note the need for the double-backslashes in the Python
strings.  ::

    sage: latex.extra_macros('')
    sage: latex.extra_preamble('')
    sage: from sage.misc.latex import latex_extra_preamble
    sage: print(latex_extra_preamble())
    \newcommand{\ZZ}{\Bold{Z}}
    ...
    \newcommand{\Bold}[1]{\mathbf{#1}}
    sage: latex.add_macro("\\newcommand{\\foo}{bar}")
    sage: print(latex_extra_preamble())
    \newcommand{\ZZ}{\Bold{Z}}
    ...
    \newcommand{\Bold}[1]{\mathbf{#1}}
    \newcommand{\foo}{bar}

Again, for larger or more complicated LaTeX expressions, it is possible to add
packages (or anything else) to the preamble of the LaTeX file.  Anything may be
incorporated into the preamble with the ``latex.add_to_preamble`` command, and
the specialized command ``latex.add_package_to_preamble_if_available`` will
first check if a certain package is actually available before trying to add it
to the preamble.

Here we add the geometry package to the preamble and use it to set the size of
the region on the page that TeX will use (effectively setting the margins).  As
usual, note the need for the double-backslashes in the Python strings.  ::

    sage: from sage.misc.latex import latex_extra_preamble
    sage: latex.extra_macros('')
    sage: latex.extra_preamble('')
    sage: latex.add_to_preamble('\\usepackage{geometry}')
    sage: latex.add_to_preamble('\\geometry{letterpaper,total={8in,10in}}')
    sage: latex.extra_preamble()
    '\\usepackage{geometry}\\geometry{letterpaper,total={8in,10in}}'
    sage: print(latex_extra_preamble())
    \usepackage{geometry}\geometry{letterpaper,total={8in,10in}}
    \newcommand{\ZZ}{\Bold{Z}}
    ...
    \newcommand{\Bold}[1]{\mathbf{#1}}

A particular package may be added along with a check on its existence, as
follows.  As an example, we just illustrate an attempt to add to the preamble a
package that presumably does not exist. ::

    sage: latex.extra_preamble('')
    sage: latex.extra_preamble()
    ''
    sage: latex.add_to_preamble('\\usepackage{foo-bar-unchecked}')
    sage: latex.extra_preamble()
    '\\usepackage{foo-bar-unchecked}'
    sage: latex.add_package_to_preamble_if_available('foo-bar-checked')
    sage: latex.extra_preamble()
    '\\usepackage{foo-bar-unchecked}'

.. _sec-custom-processing:

Customizing LaTeX Processing
============================

It is also possible to control which variant of TeX is used for system-wide
invocations, thus also influencing the nature of the output.

The ``latex.engine()`` command can be used to control if the system-wide
executables ``latex``, ``pdflatex`` or ``xelatex`` are employed for more
complicated LaTeX expressions.  When ``view()`` is called and the engine is set
to ``latex``, a dvi file is produced and Sage will use a dvi viewer (like xdvi)
to display the result.  In contrast, using ``view()`` when the engine is set to
``pdflatex`` will produce a PDF as the result and Sage will call your system's
utility for displaying PDF files (acrobat, okular, evince, etc.).

For a concrete example of how complicated LaTeX expressions can be processed,
see the example in the next section (:ref:`sec-tkz-graph`) for using the LaTeX
``tkz-graph`` package to produce high-quality renderings of combinatorial
graphs.  For other examples, there are some pre-packaged test cases.  To use
these, it is necessary to import the ``sage.misc.latex.latex_examples`` object,
which is an instance of the ``sage.misc.latex.LatexExamples`` class, as
illustrated below.  This class currently has examples of commutative diagrams,
combinatorial graphs, knot theory and pstricks, which respectively exercise the
following packages: xy, tkz-graph, xypic, pstricks.  After the import, use
tab-completion on ``latex_examples`` to see the pre-packaged examples.  Calling
each example will give you back some explanation about what is required to make
the example render properly.  To actually see the examples, it is necessary to
use ``view()`` (once the preamble, engine, etc are all set properly).  ::

    sage: from sage.misc.latex import latex_examples
    sage: latex_examples.diagram()
    LaTeX example for testing display of a commutative diagram produced
    by xypic.
    <BLANKLINE>
    To use, try to view this object -- it will not work.  Now try
    'latex.add_to_preamble("\\usepackage[matrix,arrow,curve,cmtip]{xy}")',
    and try viewing again. You should get a picture (a part of the diagram arising
    from a filtered chain complex).

.. _sec-tkz-graph:

An Example: Combinatorial Graphs with tkz-graph
===============================================

High-quality illustrations of combinatorial graphs (henceforth just "graphs")
are possible with the ``tkz-graph`` package.  This package is built on top of
the ``tikz`` front-end to the ``pgf`` library.  So all of these components need
to be part of a system-wide TeX installation, and it may be possible that these
components may not be at their most current versions as packaged in some TeX
implementations. So for best results, it could be necessary or advisable to
install these as part of your personal texmf tree.  Creating, maintaining and
customizing a system-wide or personal TeX installation is beyond the scope of
this document, but it should be easy to find instructions.  The necessary files
are listed in :ref:`sec-system-wide-tex`.

Thus, to start we need to insure that the relevant packages are included by
adding them to the preamble of the eventual LaTeX document.  The images of
graphs do not form properly when a dvi file is used as an intermediate format,
so it is best to set the latex engine to the ``pdflatex`` executable.  At this
point a command like ``view(graphs.CompleteGraph(4))`` should produce a PDF
with an appropriate image of the complete graph `K_4`.

Note that there is a variety of options to affect how a graph is rendered in
LaTeX via ``tkz-graph``, which is again outside the scope of this section, see
the section of the Reference manual titled "LaTeX Options for Graphs" for
instructions and details.

.. _sec-system-wide-tex:

A Fully Capable TeX Installation
================================

Many of the more advanced features of the integration of TeX with Sage requires
a system-wide installation of TeX.  Many versions of Linux have base TeX
packages based on TeX Live, for macOS there is TeXShop and for Windows there is
MiKTeX.  The ``convert`` utility is part of the `ImageMagick
<http://www.imagemagick.org/>`_ suite (which should be a package or an easy
download), and the three programs ``dvipng``, ``ps2pdf``, and ``dvips`` may be
included with your TeX distribution.  The first two may also be obtained,
respectively, from http://sourceforge.net/projects/dvipng/ and as part of
`Ghostscript <http://www.ghostscript.com/>`_.

Rendering combinatorial graphs requires a recent version of the PGF library,
the file ``tkz-graph.sty`` from https://www.ctan.org/pkg/tkz-graph, and the
files ``tkz-arith.sty`` and perhaps ``tkz-berge.sty`` from
https://www.ctan.org/pkg/tkz-berge.

SageTeX
=======

SageTeX is a program available to further integrate TeX and Sage. A concise
description of SageTeX is that it is a collection of TeX macros that allow a
LaTeX document to include instructions to have Sage compute various objects
and/or format objects using the ``latex()`` support built into Sage.  So as an
intermediate step of compiling a LaTeX document, all of the computational and
LaTeX-formatting features of Sage can be handled automatically.  As an example,
a mathematics examination can maintain a correct correspondence between
questions and answers by using SageTeX to have Sage compute one from the other.
See :ref:`sec-sagetex` for more information.
