From 8dee1185d8ddeb416cfc8a279ab11d3eb4a702a5 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Thu, 24 Aug 2023 18:18:54 +0900 Subject: [PATCH 1/9] Update a part of the tutorial --- src/doc/en/tutorial/latex.rst | 304 +++++++++++++++++----------------- 1 file changed, 152 insertions(+), 152 deletions(-) diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index aafaaea6ac5..b418ef63ed8 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -1,71 +1,83 @@ -********************************* +*********************** 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 -======== +Basic Use +========= -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 `_ - 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. :: +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. :: sage: var('z') z sage: latex(z^12) z^{12} - sage: latex(integrate(z^4, z)) - \frac{1}{5} \, z^{5} + sage: latex(sqrt(z^2 + 1/2)) + \sqrt{z^{2} + \frac{1}{2}} sage: latex('a string') \text{\texttt{a{ }string}} sage: latex(QQ) \Bold{Q} + sage: latex(ZZ['x']) + \Bold{Z}[x] 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. :: +In this way, Sage can be used effectively for constructing portions of +a LaTeX document: create or compute an object in Sage, do ``latex(foo)`` +of the object ``foo`` and cut/paste the LaTeX string into your document. + +In the terminal, the command ``view(foo)`` will show the rendered LaTeX +representation of ``foo``. In the background, the command runs ``latex(foo)`` +and incorporates the LaTeX string into a simple LaTeX document, processes that +document with your system-wide TeX installation, and finally an appropriate +viewer will be called to display the output. + +In the Jupyter notebook, you can see the rendered LaTeX representation of the +output of commands in each input cell automatically. You can start this +automatic rendering by executing ``%display latex`` (and stop by executing +``%display plain``). Thus, in the Jupyter notebook, you input:: + + sage: %display latex + sage: var('z') + sage: z^12 + ... + sage: sqrt(z^2 + 1/2) + ... + sage: 'a string' + ... + sage: QQ + ... + sage: ZZ['x'] + ... + sage: matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]) + ... + +where ``...`` denotes the rendered LaTeX representation, which we cannot show +here on a web browser, of course. + +The Jupyter notebook uses `MathJax `_ to render +mathematics cleanly in a web browser. 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 LaTeX. It has no +support for things like complicated tables, sectioning or document management, +as it is oriented towards accurately rendering math snippets of LaTeX. + +The automatic LaTeX rendering in the Jupyter notebook is internally done via +the :class:`MathJax` class. The object of this class converts a Sage object +through ``latex()`` to a form of HTML palatable to MathJax and then wraps it in +HTML. :: sage: from sage.misc.html import MathJax sage: mj = MathJax() @@ -73,28 +85,22 @@ in HTML. :: z sage: mj(z^12) \[z^{12}\] + sage: mj(sqrt(z^2 + 1/2)) + \[\sqrt{z^{2} + \frac{1}{2}}\] + sage: mj('a string') + \[\verb|a|\verb| |\verb|string|\] sage: mj(QQ) \[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Q}\] sage: mj(ZZ['x']) \[\newcommand{\Bold}[1]{\mathbf{#1}}\Bold{Z}[x]\] - sage: mj(integrate(z^4, z)) - \[\frac{1}{5} \, z^{5}\] - -Basic Use -========= + sage: mj(matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]])) + \[\left(\begin{array}{rrr} + 2 & 4 & 6 \\ + -1 & -1 & -1 + \end{array}\right)\] -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. +This is useful to know if you need to understand the LaTeX rendering of a Sage object. -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: @@ -152,30 +158,36 @@ done in written work. This is accomplished by redefining the \[\newcommand{\Bold}[1]{\mathbb{#1}}\Bold{Q}\] 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. :: +It is possible to take advantage of the extensible nature of LaTeX by adding in +new macros. Individual macros can be added so that they are used when MathJax +interprets a snippet of LaTeX in the notebook. :: sage: latex.extra_macros() '' - sage: latex.add_macro("\\newcommand{\\foo}{bar}") + sage: latex.add_macro(r"\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}") sage: latex.extra_macros() - '\\newcommand{\\foo}{bar}' + '\\newcommand{\\sqrt}[1]{(#1)^\\frac{1}{2}}' sage: var('x y') (x, y) - sage: latex(x+y) - x + y + sage: latex(sqrt(x+y)) + \sqrt{x + y} sage: from sage.misc.html import MathJax sage: mj = MathJax() - sage: mj(x+y) - \[\newcommand{\foo}{bar}x + y\] + sage: mj(sqrt(x + y)) + \[\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}\sqrt{x + y}\] -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. :: + +.. _sec-custom-processing: + +Customizing LaTeX Processing +============================ + +The system-wide TeX is called to process a complete LaTeX document, such as +when you ``view(foo)``, where ``foo`` is a complicated Sage object, too +complicated for ``MathJax`` to 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('') @@ -229,38 +241,44 @@ package that presumably does not exist. :: sage: latex.extra_preamble() '\\usepackage{foo-bar-unchecked}' -.. _sec-custom-processing: +Which dialect of TeX is used, and therefore the nature of the output and +associated viewer, can also be customized. -Customizing LaTeX Processing -============================ +.. NOTE:: -It is also possible to control which variant of TeX is used for system-wide -invocations, thus also influencing the nature of the output. + Sage includes almost everything you need to build and use Sage, but a + significant exception is TeX itself. So in the following situations you + need to have a full TeX system installed, along with some associated + conversion utilities. Many versions of Linux have packages based on + TeXLive, for macOS there is MacTeX and for Windows there is MiKTeX. 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). :: +executables ``latex``, ``pdflatex`` or ``xelatex`` are employed. 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.). + + +Examples +======== + +For your exercises with these facilities, there are some pre-packaged examples. +To use these, it is necessary to import the ``sage.misc.latex.latex_examples`` +object, which is an instance of the :class:`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(foo)`` (once the preamble, engine, etc are all set +properly). :: sage: from sage.misc.latex import latex_examples - sage: latex_examples.diagram() + sage: foo = latex_examples.diagram() + sage: foo LaTeX example for testing display of a commutative diagram produced by xypic. @@ -269,63 +287,45 @@ use ``view()`` (once the preamble, engine, etc are all set properly). :: 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`. +For an example of how complicated LaTeX expressions can be processed, let us see the +example of combinatorial graphs, that use ``tkz-graph`` LaTeX package. -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. +.. NOTE:: + + ``tkz-graph`` LaTeX package is built on top of the ``tikz`` front-end to + the ``pgf`` library. Rendering combinatorial graphs requires a recent + version of the ``pgf`` library, and the files ``tkz-graph.sty`` and + ``tkz-berge.sty``. It is highly likely that they are already part of your + system-wide TeX installation. Even if not, it should be easy to find + instructions to install them. -.. _sec-system-wide-tex: +For convenience, the relevant packages are already included to the default +preamble of the LaTeX document. :: -A Fully Capable TeX Installation -================================ + sage: latex.extra_preamble() + '\\usepackage{tikz}\n\\usepackage{tkz-graph}\n\\usepackage{tkz-berge}\n\\usetikzlibrary{arrows,shapes}' -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 -`_ 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 `_. +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, which is also the default:: + + sage: latex.engine() + 'pdflatex' + +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 outside the scope of this section. See the +section of the Reference manual titled "LaTeX Options for Graphs" for +instructions and details. -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. +LaTeX document to include instructions to have Sage compute various objects and +format objects using the ``latex()``. See :ref:`sec-sagetex` for more +information. From c1119e9404e29ad25f0500902076b0e8cc801c5c Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Thu, 24 Aug 2023 21:06:42 +0900 Subject: [PATCH 2/9] Further edits --- src/doc/en/tutorial/latex.rst | 47 ++++++++++++++++------------------- 1 file changed, 21 insertions(+), 26 deletions(-) diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index b418ef63ed8..08f92e7356f 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -38,16 +38,16 @@ In this way, Sage can be used effectively for constructing portions of a LaTeX document: create or compute an object in Sage, do ``latex(foo)`` of the object ``foo`` and cut/paste the LaTeX string into your document. -In the terminal, the command ``view(foo)`` will show the rendered LaTeX +The command ``view(foo)`` will show the rendered LaTeX representation of ``foo``. In the background, the command runs ``latex(foo)`` and incorporates the LaTeX string into a simple LaTeX document, processes that -document with your system-wide TeX installation, and finally an appropriate +document with the system-wide TeX installation, and finally an appropriate viewer will be called to display the output. In the Jupyter notebook, you can see the rendered LaTeX representation of the -output of commands in each input cell automatically. You can start this +output of the entered commands automatically. You can start this automatic rendering by executing ``%display latex`` (and stop by executing -``%display plain``). Thus, in the Jupyter notebook, you input:: +``%display plain``). Thus, in the Jupyter notebook, you get:: sage: %display latex sage: var('z') @@ -74,10 +74,10 @@ to render a large, but not totally complete, subset of LaTeX. It has no support for things like complicated tables, sectioning or document management, as it is oriented towards accurately rendering math snippets of LaTeX. -The automatic LaTeX rendering in the Jupyter notebook is internally done via -the :class:`MathJax` class. The object of this class converts a Sage object -through ``latex()`` to a form of HTML palatable to MathJax and then wraps it in -HTML. :: +The automatic LaTeX rendering in the Jupyter notebook (with ``%display latex`` +on) is internally done via the :class:`sage.misc.html.MathJax` class. The +object of this class converts a Sage object through ``latex()`` to a form of +HTML palatable to MathJax and then wraps it in HTML. :: sage: from sage.misc.html import MathJax sage: mj = MathJax() @@ -160,7 +160,7 @@ done in written work. This is accomplished by redefining the It is possible to take advantage of the extensible nature of LaTeX by adding in new macros. Individual macros can be added so that they are used when MathJax -interprets a snippet of LaTeX in the notebook. :: +interprets a LaTeX snippet in the notebook. :: sage: latex.extra_macros() '' @@ -185,7 +185,7 @@ Customizing LaTeX Processing The system-wide TeX is called to process a complete LaTeX document, such as when you ``view(foo)``, where ``foo`` is a complicated Sage object, too complicated for ``MathJax`` to handle. The command ``latex_extra_preamble`` is -used to build the preamble of a complete LaTeX document, so the following +used to build the preamble of the complete LaTeX document, so the following illustrates how this is accomplished. As usual note the need for the double-backslashes in the Python strings. :: @@ -260,10 +260,6 @@ 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.). - -Examples -======== - For your exercises with these facilities, there are some pre-packaged examples. To use these, it is necessary to import the ``sage.misc.latex.latex_examples`` object, which is an instance of the :class:`sage.misc.latex.LatexExamples` @@ -293,11 +289,11 @@ example of combinatorial graphs, that use ``tkz-graph`` LaTeX package. .. NOTE:: ``tkz-graph`` LaTeX package is built on top of the ``tikz`` front-end to - the ``pgf`` library. Rendering combinatorial graphs requires a recent - version of the ``pgf`` library, and the files ``tkz-graph.sty`` and - ``tkz-berge.sty``. It is highly likely that they are already part of your - system-wide TeX installation. Even if not, it should be easy to find - instructions to install them. + the ``pgf`` library. Rendering combinatorial graphs requires the ``pgf`` + library, and the files ``tkz-graph.sty`` and ``tkz-berge.sty``. It is + highly likely that they are already part of your system-wide TeX + installation. Even if not, it should be easy to find instructions to + install them. For convenience, the relevant packages are already included to the default preamble of the LaTeX document. :: @@ -317,15 +313,14 @@ 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 outside the scope of this section. See the -section of the Reference manual titled "LaTeX Options for Graphs" for -instructions and details. +section :ref:`sage.graphs.graph_latex` of the Reference Manual for instructions +and details. 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 -format objects using the ``latex()``. See :ref:`sec-sagetex` for more -information. +SageTeX is a program available to further integrate TeX and Sage. It is a +collection of TeX macros that allow a LaTeX document to include instructions to +have Sage compute various objects and format objects using the ``latex()``. +See :ref:`sec-sagetex` for more information. From 4c32abbb462ba222ac8df6a543b3811ceae215fc Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Thu, 24 Aug 2023 21:43:15 +0900 Subject: [PATCH 3/9] More edits --- src/doc/en/tutorial/latex.rst | 34 ++++++++++++++++++---------------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index 08f92e7356f..fc263628fb8 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -49,19 +49,20 @@ output of the entered commands automatically. You can start this automatic rendering by executing ``%display latex`` (and stop by executing ``%display plain``). Thus, in the Jupyter notebook, you get:: - sage: %display latex - sage: var('z') - sage: z^12 + %display latex + var('z') + ... + z^12 ... - sage: sqrt(z^2 + 1/2) + sqrt(z^2 + 1/2) ... - sage: 'a string' + 'a string' ... - sage: QQ + QQ ... - sage: ZZ['x'] + ZZ['x'] ... - sage: matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]) + matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]) ... where ``...`` denotes the rendered LaTeX representation, which we cannot show @@ -295,21 +296,22 @@ example of combinatorial graphs, that use ``tkz-graph`` LaTeX package. installation. Even if not, it should be easy to find instructions to install them. -For convenience, the relevant packages are already included to the default +First, we ensure that the relevant packages are included by adding them to the preamble of the LaTeX document. :: - sage: latex.extra_preamble() - '\\usepackage{tikz}\n\\usepackage{tkz-graph}\n\\usepackage{tkz-berge}\n\\usetikzlibrary{arrows,shapes}' + sage: latex.extra_preamble('\\usepackage{tikz}\n\\usepackage{tkz-graph}\n' + ....: '\\usepackage{tkz-berge}\n\\usetikzlibrary{arrows,shapes}') 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, which is also the default:: +executable:: - sage: latex.engine() - 'pdflatex' + sage: latex.engine('pdflatex') -At this point a command like ``view(graphs.CompleteGraph(4))`` -should produce a PDF with an appropriate image of the complete graph `K_4`. +At this point a command like ``view(graphs.CompleteGraph(4))`` should produce a +PDF with an appropriate image of the complete graph `K_4`. (In fact, the first +step could be omitted as the preamble is automatically set up properly for +graphs.) Note that there is a variety of options to affect how a graph is rendered in LaTeX via ``tkz-graph``, which is outside the scope of this section. See the From 414a981d91375a39a5cf76e39d723a78f59ce973 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 25 Aug 2023 00:05:29 +0900 Subject: [PATCH 4/9] More edits --- src/doc/en/tutorial/latex.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index fc263628fb8..0335bd7073f 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -309,9 +309,11 @@ executable:: sage: latex.engine('pdflatex') At this point a command like ``view(graphs.CompleteGraph(4))`` should produce a -PDF with an appropriate image of the complete graph `K_4`. (In fact, the first -step could be omitted as the preamble is automatically set up properly for -graphs.) +PDF with an appropriate image of the complete graph `K_4`. + +Actually the preliminary steps could be omitted as the preamble is +automatically set up properly for graphs and ``pdflatex`` is the default LaTeX +engine in Sage. Try the command again after restarting Sage. Note that there is a variety of options to affect how a graph is rendered in LaTeX via ``tkz-graph``, which is outside the scope of this section. See the From 92dcb7635499962d9009c8200cefc0bc632555f0 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 25 Aug 2023 07:36:38 +0900 Subject: [PATCH 5/9] Upgrade jupyter-sphinx to 0.4.0 --- build/pkgs/jupyter_sphinx/checksums.ini | 6 ++-- build/pkgs/jupyter_sphinx/package-version.txt | 2 +- src/doc/en/tutorial/latex.rst | 31 +++++++++++++------ 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/build/pkgs/jupyter_sphinx/checksums.ini b/build/pkgs/jupyter_sphinx/checksums.ini index f53c5af453a..14f1bdf7594 100644 --- a/build/pkgs/jupyter_sphinx/checksums.ini +++ b/build/pkgs/jupyter_sphinx/checksums.ini @@ -1,5 +1,5 @@ tarball=jupyter_sphinx-VERSION.tar.gz -sha1=241f6dfcd3aae4f44f330e2ba76480011b382d3d -md5=e7ab370d9793be5b20bce5447ccbd45b -cksum=2021246952 +sha1=fb2abdd5e35da0886b12d45a6373c4dbcc24b244 +md5=130daa6be810976c9f8e30aa04011e50 +cksum=2882523000 upstream_url=https://pypi.io/packages/source/j/jupyter_sphinx/jupyter_sphinx-VERSION.tar.gz diff --git a/build/pkgs/jupyter_sphinx/package-version.txt b/build/pkgs/jupyter_sphinx/package-version.txt index d15723fbe8d..1d0ba9ea182 100644 --- a/build/pkgs/jupyter_sphinx/package-version.txt +++ b/build/pkgs/jupyter_sphinx/package-version.txt @@ -1 +1 @@ -0.3.2 +0.4.0 diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index 0335bd7073f..2a06556919f 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -47,26 +47,37 @@ viewer will be called to display the output. In the Jupyter notebook, you can see the rendered LaTeX representation of the output of the entered commands automatically. You can start this automatic rendering by executing ``%display latex`` (and stop by executing -``%display plain``). Thus, in the Jupyter notebook, you get:: +``%display plain``). Thus, in the Jupyter notebook, you get + +.. JUPYTER-EXECUTE:: %display latex var('z') - ... z^12 - ... + +.. JUPYTER-EXECUTE:: + sqrt(z^2 + 1/2) - ... + +.. JUPYTER-EXECUTE:: + 'a string' - ... + +.. JUPYTER-EXECUTE:: + QQ - ... + +.. JUPYTER-EXECUTE:: + ZZ['x'] - ... + +.. JUPYTER-EXECUTE:: + matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]) - ... -where ``...`` denotes the rendered LaTeX representation, which we cannot show -here on a web browser, of course. +.. JUPYTER-EXECUTE:: + + %display plain The Jupyter notebook uses `MathJax `_ to render mathematics cleanly in a web browser. MathJax is an open source JavaScript From 5a6cba81bddf85d007843613c0927d87824c0651 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 25 Aug 2023 11:07:28 +0900 Subject: [PATCH 6/9] Tweak jupyter-sphinx css for better look --- src/doc/common/static/custom-jupyter-sphinx.css | 16 ++++++++++++++++ src/sage_docbuild/conf.py | 1 + 2 files changed, 17 insertions(+) create mode 100644 src/doc/common/static/custom-jupyter-sphinx.css diff --git a/src/doc/common/static/custom-jupyter-sphinx.css b/src/doc/common/static/custom-jupyter-sphinx.css new file mode 100644 index 00000000000..e560cb370ba --- /dev/null +++ b/src/doc/common/static/custom-jupyter-sphinx.css @@ -0,0 +1,16 @@ +div.jupyter_container { + margin: .5em 0; +} + +div.jupyter_container + div.jupyter_container { + margin: 0 0 0.5em 0; +} + +div.jupyter_container div.cell_input pre { + margin: .5em; +} + +div.jupyter_container div.cell_output div.output { + margin: .5em; +} + diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index b493b3b2897..89359c30880 100644 --- a/src/sage_docbuild/conf.py +++ b/src/sage_docbuild/conf.py @@ -310,6 +310,7 @@ def set_intersphinx_mappings(app, config): # or fully qualified paths (eg. https://...) html_css_files = [ 'custom-furo.css', + 'custom-jupyter-sphinx.css', ] # A list of paths that contain extra templates (or templates that overwrite # builtin/theme-specific templates). Relative paths are taken as relative From 80689b46c221224ec442741bacfc4a536c779916 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 25 Aug 2023 13:15:40 +0900 Subject: [PATCH 7/9] More jupyter execution --- src/doc/en/tutorial/latex.rst | 38 ++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index 2a06556919f..cf994c39af4 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -170,12 +170,27 @@ done in written work. This is accomplished by redefining the \[\newcommand{\Bold}[1]{\mathbb{#1}}\Bold{Q}\] sage: latex.blackboard_bold(False) +In the Jupyter notebook, you see + +.. JUPYTER-EXECUTE:: + + %display latex + QQ + +.. JUPYTER-EXECUTE:: + + latex.blackboard_bold(True) + QQ + +.. JUPYTER-EXECUTE:: + + latex.blackboard_bold(False) + %display plain + It is possible to take advantage of the extensible nature of LaTeX by adding in new macros. Individual macros can be added so that they are used when MathJax -interprets a LaTeX snippet in the notebook. :: +interprets a LaTeX snippet. :: - sage: latex.extra_macros() - '' sage: latex.add_macro(r"\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}") sage: latex.extra_macros() '\\newcommand{\\sqrt}[1]{(#1)^\\frac{1}{2}}' @@ -187,6 +202,23 @@ interprets a LaTeX snippet in the notebook. :: sage: mj = MathJax() sage: mj(sqrt(x + y)) \[\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}\sqrt{x + y}\] + sage: latex.extra_macros('') + +In the Jupyter notebook, + +.. JUPYTER-EXECUTE:: + + %display latex + var('x y') + sqrt(x + y) + +.. JUPYTER-EXECUTE:: + latex.add_macro(r"\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}") + sqrt(x + y) + +.. JUPYTER-EXECUTE:: + latex.extra_macros('') + %display plain .. _sec-custom-processing: From f06544de8391be22e7346868c1414a547877471e Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 25 Aug 2023 13:31:28 +0900 Subject: [PATCH 8/9] Fix wrong formatting --- src/doc/en/tutorial/latex.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index cf994c39af4..e15bea9d793 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -213,12 +213,14 @@ In the Jupyter notebook, sqrt(x + y) .. JUPYTER-EXECUTE:: + latex.add_macro(r"\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}") sqrt(x + y) .. JUPYTER-EXECUTE:: + latex.extra_macros('') - %display plain + %display plain .. _sec-custom-processing: From 67a41ad8a745c377bfaf8291f312e02bf49e4250 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Fri, 25 Aug 2023 13:49:09 +0900 Subject: [PATCH 9/9] Fix for pdf doc --- src/doc/en/tutorial/latex.rst | 84 +++++++++++++++++++---------------- 1 file changed, 46 insertions(+), 38 deletions(-) diff --git a/src/doc/en/tutorial/latex.rst b/src/doc/en/tutorial/latex.rst index e15bea9d793..185820c7de2 100644 --- a/src/doc/en/tutorial/latex.rst +++ b/src/doc/en/tutorial/latex.rst @@ -47,37 +47,41 @@ viewer will be called to display the output. In the Jupyter notebook, you can see the rendered LaTeX representation of the output of the entered commands automatically. You can start this automatic rendering by executing ``%display latex`` (and stop by executing -``%display plain``). Thus, in the Jupyter notebook, you get +``%display plain``). -.. JUPYTER-EXECUTE:: +.. ONLY:: html - %display latex - var('z') - z^12 + Thus, in the Jupyter notebook, you get -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - sqrt(z^2 + 1/2) + %display latex + var('z') + z^12 -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - 'a string' + sqrt(z^2 + 1/2) -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - QQ + 'a string' -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - ZZ['x'] + QQ -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]) + ZZ['x'] -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - %display plain + matrix(QQ, 2, 3, [[2,4,6],[-1,-1,-1]]) + + .. JUPYTER-EXECUTE:: + + %display plain The Jupyter notebook uses `MathJax `_ to render mathematics cleanly in a web browser. MathJax is an open source JavaScript @@ -170,22 +174,24 @@ done in written work. This is accomplished by redefining the \[\newcommand{\Bold}[1]{\mathbb{#1}}\Bold{Q}\] sage: latex.blackboard_bold(False) -In the Jupyter notebook, you see +.. ONLY:: html -.. JUPYTER-EXECUTE:: + In the Jupyter notebook, - %display latex - QQ + .. JUPYTER-EXECUTE:: -.. JUPYTER-EXECUTE:: + %display latex + QQ - latex.blackboard_bold(True) - QQ + .. JUPYTER-EXECUTE:: -.. JUPYTER-EXECUTE:: + latex.blackboard_bold(True) + QQ - latex.blackboard_bold(False) - %display plain + .. JUPYTER-EXECUTE:: + + latex.blackboard_bold(False) + %display plain It is possible to take advantage of the extensible nature of LaTeX by adding in new macros. Individual macros can be added so that they are used when MathJax @@ -204,23 +210,25 @@ interprets a LaTeX snippet. :: \[\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}\sqrt{x + y}\] sage: latex.extra_macros('') -In the Jupyter notebook, +.. ONLY:: html + + In the Jupyter notebook, -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - %display latex - var('x y') - sqrt(x + y) + %display latex + var('x y') + sqrt(x + y) -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - latex.add_macro(r"\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}") - sqrt(x + y) + latex.add_macro(r"\newcommand{\sqrt}[1]{(#1)^\frac{1}{2}}") + sqrt(x + y) -.. JUPYTER-EXECUTE:: + .. JUPYTER-EXECUTE:: - latex.extra_macros('') - %display plain + latex.extra_macros('') + %display plain .. _sec-custom-processing: