summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2021-07-27 20:36:31 +0000
committerKarl Berry <karl@freefriends.org>2021-07-27 20:36:31 +0000
commitc5b5e3fd195d647f3107171ca73a29b83bf4d7b3 (patch)
tree01eb2e0fef4c2aea7fcd43dab80ee549d89851fb /Master/texmf-dist/doc
parentd94a4be7eef3b68410940ceebbd4bd2401aebbce (diff)
pyluatex (27jul21)
git-svn-id: svn://tug.org/texlive/trunk@60095 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/lualatex/pyluatex/README.md6
-rw-r--r--Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdfbin65417 -> 78301 bytes
-rw-r--r--Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex100
3 files changed, 98 insertions, 8 deletions
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/README.md b/Master/texmf-dist/doc/lualatex/pyluatex/README.md
index a555ec20086..6c8015dce92 100644
--- a/Master/texmf-dist/doc/lualatex/pyluatex/README.md
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/README.md
@@ -7,6 +7,11 @@ LaTeX documents must be compiled with LuaLaTeX for this to work.
## Example
1\. LaTeX document `example.tex`
+
+**Note:** PyLuaTeX starts Python 3 using the command `python3` by default.
+If `python3` does not start Python 3 on your system, find the correct command
+and replace `\usepackage{pyluatex}` with `\usepackage[executable={your python command}]{pyluatex}`.
+For example, `\usepackage[executable=python.exe]{pyluatex}`.
```latex
\documentclass{article}
@@ -31,6 +36,7 @@ $\sqrt{371} = \py{math.sqrt(371)}$
\randint{2}{5}
\end{document}
```
+
2\. Compile using LuaLaTeX (shell escape is required)
```
lualatex -shell-escape example.tex
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
index 4e93fb29355..58d2de88e15 100644
--- a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex
index c64d7579459..ffaf503914c 100644
--- a/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex
+++ b/Master/texmf-dist/doc/lualatex/pyluatex/pyluatex.tex
@@ -15,7 +15,7 @@
\usepackage{url}
\title{The \emph{pyluatex} package}
\author{Tobias Enderle\\\url{https://github.com/tndrle/PyLuaTeX}}
-\date{v0.1.3 (2021/07/15)}
+\date{v0.2.0 (2021/07/26)}
\begin{document}
\maketitle
\raggedright
@@ -28,7 +28,11 @@ PyLuaTeX allows you to execute Python code and to include the resulting output i
\section{Example}
\begin{enumerate}
-\item \LaTeX{} document \inlcode|example.tex|
+\item \LaTeX{} document \inlcode|example.tex|\\[0.5ex]
+\textbf{Note:} PyLuaTeX starts Python 3 using the command \inlcode|python3| by default.
+If \inlcode|python3| does not start Python 3 on your system, find the correct command
+and replace \inlcode|\usepackage{pyluatex}| with \inlcode|\usepackage[executable={your python command}]{pyluatex}|.
+For example, \inlcode|\usepackage[executable=python.exe]{pyluatex}|.
\begin{tcblisting}{breakable,listing only,
size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
\documentclass{article}
@@ -54,6 +58,8 @@ $\sqrt{371} = \py{math.sqrt(371)}$
\randint{2}{5}
\end{document}
\end{tcblisting}
+\end{enumerate}
+\begin{enumerate}
\item Compile using Lua\LaTeX{} (shell escape is required)
\begin{tcblisting}{breakable,listing only,
size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
@@ -76,12 +82,20 @@ The folder \inlcode|example| contains additional example documents:
Demonstrates how \textit{matplotlib} plots can be generated and included in a document
\item \inlcode|matplotlib-pgf.tex|\\[0.5ex]
Demonstrates how \textit{matplotlib} plots can be generated and included in a document using \textit{PGF}
+\item \inlcode|typesetting-example.tex|\\[0.5ex]
+ The code typesetting example below
+\item \inlcode|typesetting-listings.tex|\\[0.5ex]
+ A detailed example for typesetting code and output with the \textit{listings} package
+\item \inlcode|typesetting-minted.tex|\\[0.5ex]
+ A detailed example for typesetting code and output with the \textit{minted} package
\end{itemize}
For more intricate use cases have a look at our tests in the folder \inlcode|test|.
\section{Installation}
-PyLuaTeX is available on CTAN\footnote{\url{https://ctan.org/pkg/pyluatex}} and in MiKTeX.
-It will be available in TeX Live soon (when you read this it probably already is).
+PyLuaTeX is available in TeX Live, MiKTeX, and on CTAN\footnote{\url{https://ctan.org/pkg/pyluatex}} as \inlcode|pyluatex|.
+
+To install PyLuaTeX in \textbf{TeX Live} run \inlcode|tlmgr install pyluatex|.\\[0.5ex]
+In \textbf{MiKTeX}, PyLuaTeX can be installed in the \textit{MiKTeX Console}.
To install PyLuaTeX \textbf{manually}, do the following steps:
\begin{enumerate}
@@ -106,6 +120,12 @@ TEXMF/tex/latex/pyluatex/
\section{Reference}
PyLuaTeX offers a simple set of options, macros and environments.
+Most macros and environments are available as \textit{quiet} versions as well.
+They have the suffix \inlcode|q| in their name, e.g. \inlcode|\pycq| or \inlcode|\pyfileq|.
+The quiet versions suppress any output, even if the Python code explicitly calls \inlcode|print()|.
+This is helpful if you want to process code or output further and do your own typesetting.
+For an example, see the Typesetting Code section.
+
\subsection{Package Options}
\begin{itemize}
\item \inlcode|verbose|\\[0.5ex]
@@ -118,14 +138,23 @@ PyLuaTeX offers a simple set of options, macros and environments.
\subsection{Macros}
\begin{itemize}
\item \inlcode|\py{code}|\\[0.5ex]
- Executes \inlcode|code| and writes the output to the document.\\[0.5ex]
+ Executes (object-like) \inlcode|code| and writes its string representation to the document.\\[0.5ex]
\textit{Example:} \inlcode|\py{3 + 7}|
+\item \inlcode|\pyq{code}|\\[0.5ex]
+ Executes (object-like) \inlcode|code|. Any output is suppressed.\\[0.5ex]
+ \textit{Example:} \inlcode|\pyq{3 + 7}|
\item \inlcode|\pyc{code}|\\[0.5ex]
- Executes \inlcode|code|\\[0.5ex]
- \textit{Example:} \inlcode|\pyc{x = 5}|
+ Executes \inlcode|code|. Output (e.g. from a call to \inlcode|print()|) is written to the document.\\[0.5ex]
+ \textit{Examples:} \inlcode|\pyc{x = 5}|, \inlcode|\pyc{print('hello')}|
+\item \inlcode|\pycq{code}|\\[0.5ex]
+ Executes \inlcode|code|. Any output is suppressed.\\[0.5ex]
+ \textit{Example:} \inlcode|\pycq{x = 5}|
\item \inlcode|\pyfile{path}|\\[0.5ex]
- Executes the Python file specified by \inlcode|path|.\\[0.5ex]
+ Executes the Python file specified by \inlcode|path|. Output (e.g. from a call to \inlcode|print()|) is written to the document.\\[0.5ex]
\textit{Example:} \inlcode|\pyfile{main.py}|
+\item \inlcode|\pyfileq{path}|\\[0.5ex]
+ Executes the Python file specified by \inlcode|path|. Any output is suppressed.\\[0.5ex]
+ \textit{Example:} \inlcode|\pyfileq{main.py}|
\item \inlcode|\pysession{session}|\\[0.5ex]
Selects \inlcode|session| as Python session for subsequent Python code.\\[0.5ex]
The session that is active at the beginning is \inlcode|default|.\\[0.5ex]
@@ -146,6 +175,8 @@ PyLuaTeX offers a simple set of options, macros and environments.
print(x)
\end{python}
\end{tcblisting}
+\item \inlcode|pythonq|\\[0.5ex]
+ Same as the \inlcode|python| environment, but any output is suppressed.
\end{itemize}
\section{Requirements}
\begin{itemize}
@@ -156,6 +187,59 @@ PyLuaTeX offers a simple set of options, macros and environments.
Our automated tests currently use TeX Live 2021 and Python 3.7+ on
Ubuntu 20.04, macOS Catalina 10.15 and Windows Server 2019.
+\section{Typesetting Code}
+Sometimes, in addition to having Python code executed and the output written to your document, you also want to show the code itself in your document.
+PyLuaTeX does not offer any macros or environments that directly typeset code.
+However, PyLuaTeX has a \textbf{code and output buffer} which you can use to create your own typesetting functionality.
+This provides a lot of flexibility for your typesetting.
+
+After a PyLuaTeX macro or environment has been executed, the corresponding Python code and output can be accessed via the Lua functions \inlcode|pyluatex.get_last_code()| and \inlcode|pyluatex.get_last_output()|, respectively.
+Both functions return a Lua table\footnote{\url{https://www.lua.org/pil/2.5.html}} where each table item corresponds to a line of code or output.
+
+A simple example for typesetting code and output using the \textit{listings} package would be:
+\begin{tcblisting}{breakable,listing only,
+ size=fbox,colframe=black!8,boxrule=3pt,colback=black!8}
+\documentclass{article}
+
+\usepackage{pyluatex}
+\usepackage{listings}
+\usepackage{luacode}
+
+\begin{luacode}
+function pytypeset()
+ tex.print("\\begin{lstlisting}[language=Python]")
+ tex.print(pyluatex.get_last_code())
+ tex.print("\\end{lstlisting}")
+ tex.print("") -- ensure newline
+end
+\end{luacode}
+
+\newcommand*{\pytypeset}{%
+ \noindent\textbf{Input:}
+ \directlua{pytypeset()}
+ \textbf{Output:}
+ \begin{center}
+ \directlua{tex.print(pyluatex.get_last_output())}
+ \end{center}
+}
+
+\begin{document}
+
+\begin{pythonq}
+greeting = 'Hello PyLuaTeX!'
+print(greeting)
+\end{pythonq}
+\pytypeset
+
+\end{document}
+\end{tcblisting}
+
+Notice that we use the \inlcode|pythonq| environment, which suppresses any output.
+After that, the custom macro \inlcode|\pytypeset| is responsible for typesetting the code and its output.
+
+Using a different code listings package like \textit{minted}, or typesetting inline code is very easy.
+See the \inlcode|typesetting-*.tex| examples in the \inlcode|example| folder.
+
\section{How It Works}
PyLuaTeX runs a Python \inlcode|InteractiveInterpreter|\footnote{\url{https://docs.python.org/3/library/code.html#code.InteractiveInterpreter}} (actually several if you use different sessions) in the background for on the fly code execution.
Python code from your \LaTeX{} file is sent to the background interpreter through a TCP socket.