pyluatex (27jul21)

git-svn-id: svn://tug.org/texlive/trunk@60095 c570f23f-e606-0410-a88d-b1316a301751

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
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.