summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2023-06-23 20:33:51 +0000
committerKarl Berry <karl@freefriends.org>2023-06-23 20:33:51 +0000
commitdf318de1935235e68ef8894a50a09b8e3bd8e6d4 (patch)
treecc3865453735c26a4d70738d885b886d18579fb2 /Master/texmf-dist/doc
parent75e729bd7c61127bcf2eb1b54739af2a724cfdbb (diff)
runcode (23jun23)
git-svn-id: svn://tug.org/texlive/trunk@67453 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/runcode/README2
-rw-r--r--Master/texmf-dist/doc/latex/runcode/runcode.pdfbin247859 -> 251041 bytes
-rw-r--r--Master/texmf-dist/doc/latex/runcode/runcode.tex238
3 files changed, 137 insertions, 103 deletions
diff --git a/Master/texmf-dist/doc/latex/runcode/README b/Master/texmf-dist/doc/latex/runcode/README
index 010d8f44845..7a1480a3b1a 100644
--- a/Master/texmf-dist/doc/latex/runcode/README
+++ b/Master/texmf-dist/doc/latex/runcode/README
@@ -1,4 +1,4 @@
-LaTeX Package: runcode 2023/06/13 v1.9
+LaTeX Package: runcode 2023/06/23 v2.0
----------------------------------------
The runcode package enables the execution of source code (e.g., R,
Julia, Matlab, shell, Python, etc.) and embed the results in the pdf file
diff --git a/Master/texmf-dist/doc/latex/runcode/runcode.pdf b/Master/texmf-dist/doc/latex/runcode/runcode.pdf
index 0a84593cf21..95afe135322 100644
--- a/Master/texmf-dist/doc/latex/runcode/runcode.pdf
+++ b/Master/texmf-dist/doc/latex/runcode/runcode.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/runcode/runcode.tex b/Master/texmf-dist/doc/latex/runcode/runcode.tex
index 04c67fd5a2e..89c7acd6aad 100644
--- a/Master/texmf-dist/doc/latex/runcode/runcode.tex
+++ b/Master/texmf-dist/doc/latex/runcode/runcode.tex
@@ -1,6 +1,6 @@
-% LaTeX Package: runcode 2023/06/13 v1.9
+% LaTeX Package: runcode 2023/06/23 v2.0
%
-% Copyright (C) 2020-2022 by Haim Bar and HaiYing Wang
+% Copyright (C) 2020-2023 by Haim Bar and HaiYing Wang
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
@@ -49,7 +49,7 @@ package’s github repository, at \url{https://github.com/Ossifragus/runcode}.
\end{abstract}
\section{Installation}
-\label{sec:org8c6be84}
+\label{sec:org594ce40}
You can simply put the runcode.sty file in the \LaTeX{} project folder.
The server mode requires the
@@ -65,9 +65,9 @@ compiling a \LaTeX{} document.
\section{Usage}
-\label{sec:org951dfd0}
+\label{sec:org826d1b1}
\subsection{Load the package:}
-\label{sec:org516e8f6}
+\label{sec:orgfba21b6}
\begin{minted}[]{latex}
\usepackage[options]{runcode}
\end{minted}
@@ -121,12 +121,12 @@ the code block is controlled through the minted package,
\setminted[R]{linenos, frame=single, bgcolor=lightgray, breaklines=true}
\end{minted}
-Similarly, \href{https://ctan.org/pkg/fvextra}{fvextra} and \href{https://ctan.org/pkg/listings?lang=en}{listings} packages can be customized through the \texttt{\textbackslash{}lstset}
-and \texttt{\textbackslash{}fvset} commands, respectively, e.g.:
+Similarly, \href{https://ctan.org/pkg/fvextra}{fvextra} and \href{https://ctan.org/pkg/listings?lang=en}{listings} packages can be customized through the \texttt{\textbackslash{}fvset}
+and \texttt{\textbackslash{}lstset} commands, respectively, e.g.:
\begin{minted}[]{latex}
-\lstset{basicstyle=\large, frame=single}
\fvset{fontsize=\small, linenos=true, frame=single}
+\lstset{basicstyle=\large, frame=single}
\end{minted}
The outputs from executing codes are displayed in
@@ -139,20 +139,24 @@ be customized with \texttt{\textbackslash{}tcbset},
\end{minted}
\subsection{Basic commands:}
-\label{sec:org917f9dc}
+\label{sec:org9a60003}
\begin{itemize}
\item \texttt{\textbackslash{}runExtCode\{Arg1\}\{Arg2\}\{Arg3\}[Arg4]} runs an external code.
\begin{itemize}
\item \texttt{Arg1} is the executable program.
\item \texttt{Arg2} is the source file name.
-\item \texttt{Arg3} is the output file name (with an empty value, the counter
-\texttt{codeOutput} is used).
-\item \texttt{Arg4} controls whether to run the code. \texttt{Arg4} is optional with
-three possible values: if skipped or with empty value, the value of
-the global Boolean variable \texttt{runcode} is used; if the value is set
-to \texttt{run}, the code will be executed; if set to \texttt{cache} (or anything
-else), use cached results (see more about the cache below).
+\item \texttt{Arg3} is the output file name (with an empty value, the counter \texttt{codeOutput} is
+used).
+\item \texttt{Arg4} controls whether to run the code. \texttt{Arg4} is optional with three possible
+values.
+\begin{itemize}
+\item empty value or skipped: the value of the global Boolean variable \texttt{runcode}
+is used;
+\item \texttt{run}: the code will be executed;
+\item \texttt{cache} (or anything else): use cached results; if the output file does not
+exist, the cache option will be overridden and the code will run.
+\end{itemize}
\end{itemize}
\item \texttt{\textbackslash{}showCode\{Arg1\}\{Arg2\}[Arg3][Arg4]} shows the source code, using
@@ -174,10 +178,10 @@ code.
as that of \texttt{Arg3} in \texttt{\textbackslash{}runExtCode}. If an empty value is given to
\texttt{Arg1}, the counter \texttt{codeOutput} is used.
\item \texttt{Arg2} is optional and it controls the type of output with a default
-value \texttt{vbox}
+value \texttt{vbox}.
\begin{itemize}
-\item \texttt{vbox} (or skipped) = verbatim in a box.
-\item \texttt{tex} = pure latex.
+\item \texttt{vbox} (or skipped) = verbatim in a box;
+\item \texttt{tex} = pure latex;
\item \texttt{inline} = embed result in text.
\end{itemize}
\end{itemize}
@@ -190,38 +194,61 @@ text.
\item \texttt{Arg1} is the executable program or programming language.
\item \texttt{Arg2} is the source code.
\item \texttt{Arg3} is the output file name (optional);
-\item \texttt{Arg4} is the output type.
+\item \texttt{Arg4} is the output type and controls whether to run the code.
\begin{itemize}
-\item \texttt{inline} (or skipped or with empty value) = embed result in text.
-\item \texttt{vbox} = verbatim in a box.
+\item \texttt{inline} (or skipped or with empty value): embed result in text;
+\item \texttt{vbox}: verbatim in a box;
+\item \texttt{cache} or appending \texttt{.cache} to the argument (e.g., \texttt{vbox.cache}) AND the
+output file in \texttt{Arg3} exists: the cached result will be used and the code
+will not run.
\end{itemize}
\end{itemize}
\end{itemize}
+
+\subsection{Extended commands:}
+\label{sec:org57656ef}
+\begin{itemize}
+\item \texttt{\textbackslash{}runCodeIncOut\{Arg1\}\{Arg2\}[Arg3][Arg4][Arg5]} runs an external code and
+embeds the output. This is a combination of \texttt{\textbackslash{}runExtCode} and \texttt{\textbackslash{}includeOutput}.
+\begin{itemize}
+\item \texttt{Arg1} is the executable program.
+\item \texttt{Arg2} is the source file name.
+\item \texttt{Arg3} (optional) controls whether to run the code. Its functionality is the
+same as that of \texttt{Arg4} of \texttt{\textbackslash{}runExtCode}.
+\item \texttt{Arg4} (optional) is the output file name. Its functionality is the same as
+that of \texttt{Arg3} of \texttt{\textbackslash{}runExtCode}.
+\item \texttt{Arg5} (optional) controls the type of output with a default value \texttt{vbox}. Its
+functionality is the same as that of \texttt{Arg3} of \texttt{\textbackslash{}includeOutput}.
+\end{itemize}
+\end{itemize}
+
\subsection{Language specific shortcuts:}
-\label{sec:org7b04bad}
+\label{sec:org9f79956}
\href{https://julialang.org/}{Julia}
\begin{itemize}
-\item \texttt{\textbackslash{}runJulia[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
-\href{https://julialang.org/}{Julia} code file.
+\item \texttt{\textbackslash{}runJulia[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external \href{https://julialang.org/}{Julia} code file.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses
-\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
-\href{https://julialang.org/}{Julia} server by default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
-basic command \texttt{\textbackslash{}runExtCode}.
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://julialang.org/}{Julia} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command
+\texttt{\textbackslash{}runExtCode}.
\end{itemize}
-\item \texttt{\textbackslash{}inlnJulia[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://julialang.org/}{Julia}
-source code (\texttt{Arg2}) and displays the output in line.
+\item \texttt{\textbackslash{}runJuliaIncOut[Arg1]\{Arg2\}[Arg3][Arg4][Arg5]} runs an external \href{https://julialang.org/}{Julia} code
+file and embeds the output.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses the \href{https://julialang.org/}{Julia}
-server by default.
-\item \texttt{Arg2} is the \href{https://julialang.org/}{Julia} source code to run.
-If the \href{https://julialang.org/}{Julia} source code is wrapped
-between "\texttt{```}" on both sides (as in the markdown grammar), then it
-will be implemented directly; otherwise the code will be written to
-a file on the disk and then be called.
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://julialang.org/}{Julia} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, \texttt{Arg4}, and \texttt{Arg5} have the same effects as those of the command
+\texttt{\textbackslash{}runCodeIncOut}.
+\end{itemize}
+\item \texttt{\textbackslash{}inlnJulia[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://julialang.org/}{Julia} source code (\texttt{Arg2}) and displays
+the output in line.
+\begin{itemize}
+\item \texttt{Arg1} is optional and uses the \href{https://julialang.org/}{Julia} server by default.
+\item \texttt{Arg2} is the \href{https://julialang.org/}{Julia} source code to run. If the \href{https://julialang.org/}{Julia} source code is wrapped
+between "\texttt{```}" on both sides (as in the markdown grammar), then it will be
+implemented directly; otherwise the code will be written to a file on the
+disk and then be called.
\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
\end{itemize}
@@ -229,30 +256,27 @@ a file on the disk and then be called.
\href{https://www.mathworks.com/products/matlab.html}{MatLab}
\begin{itemize}
-\item \texttt{\textbackslash{}runMatLab[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
-\href{https://www.mathworks.com/products/matlab.html}{MatLab} code file.
+\item \texttt{\textbackslash{}runMatLab[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external \href{https://www.mathworks.com/products/matlab.html}{MatLab} code file.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses
-\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
-\href{https://www.mathworks.com/products/matlab.html}{MatLab} server by
-default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
-basic command \texttt{\textbackslash{}runExtCode}.
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://www.mathworks.com/products/matlab.html}{MatLab} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command
+\texttt{\textbackslash{}runExtCode}.
\end{itemize}
-\item \texttt{\textbackslash{}inlnMatLab[Arg1]\{Arg2\}[Arg3][Arg4]} runs
-\href{https://www.mathworks.com/products/matlab.html}{MatLab} source code
-(\texttt{Arg2}) and displays the output in line.
+\item \texttt{\textbackslash{}runMatLabIncOut[Arg1]\{Arg2\}[Arg3][Arg4][Arg5]} runs an external \href{https://www.mathworks.com/products/matlab.html}{MatLab} code
+file and embeds the output.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses the
-\href{https://www.mathworks.com/products/matlab.html}{MatLab} server by
-default.
-\item \texttt{Arg2} is the
-\href{https://www.mathworks.com/products/matlab.html}{MatLab} source
-code to run. If the
-\href{https://www.mathworks.com/products/matlab.html}{MatLab} source
-code is wrapped between "```" on both sides (as in the markdown
-grammar), then it will be implemented directly; otherwise the code
-will be written to a file on the disk and then be called.
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://www.mathworks.com/products/matlab.html}{MatLab} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, \texttt{Arg4}, and \texttt{Arg5} have the same effects as those of the command
+\texttt{\textbackslash{}runCodeIncOut}.
+\end{itemize}
+\item \texttt{\textbackslash{}inlnMatLab[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://www.mathworks.com/products/matlab.html}{MatLab} source code (\texttt{Arg2}) and
+displays the output in line.
+\begin{itemize}
+\item \texttt{Arg1} is optional and uses the \href{https://www.mathworks.com/products/matlab.html}{MatLab} server by default.
+\item \texttt{Arg2} is the \href{https://www.mathworks.com/products/matlab.html}{MatLab} source code to run. If the \href{https://www.mathworks.com/products/matlab.html}{MatLab} source code is wrapped
+between "```" on both sides (as in the markdown grammar), then it will be
+implemented directly; otherwise the code will be written to a file on the
+disk and then be called.
\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
\end{itemize}
@@ -260,36 +284,35 @@ will be written to a file on the disk and then be called.
\href{https://www.python.org/}{Python}
\begin{itemize}
-\item \texttt{\textbackslash{}runPython[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
-\href{https://www.python.org/}{Python} code file.
+\item \texttt{\textbackslash{}runPython[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external \href{https://www.python.org/}{Python} code file.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses
-\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
-\href{https://julialang.org/}{Julia} server by default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
-basic command \texttt{\textbackslash{}runExtCode}.
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://www.python.org/}{Python} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command
+\texttt{\textbackslash{}runExtCode}.
\end{itemize}
-\item \texttt{\textbackslash{}inlnPython[Arg1]\{Arg2\}[Arg3][Arg4]} runs
-\href{https://www.python.org/}{Python} source code (\texttt{Arg2}) and displays
-the output in line.
+\item \texttt{\textbackslash{}runPythonIncOut[Arg1]\{Arg2\}[Arg3][Arg4][Arg5]} runs an external \href{https://www.python.org/}{Python} code
+file and embeds the output.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses the \href{https://www.python.org/}{Python}
-server by default.
-\item \texttt{Arg2} is the \href{https://julialang.org/}{Julia} source code to run.
-If the \href{https://www.python.org/}{Python} source code is wrapped
-between "```" on both sides (as in the markdown grammar), then it
-will be implemented directly; otherwise the code will be written to
-a file on the disk and then be called.
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://www.python.org/}{Python} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, \texttt{Arg4}, and \texttt{Arg5} have the same effects as those of the command
+\texttt{\textbackslash{}runCodeIncOut}.
+\end{itemize}
+\item \texttt{\textbackslash{}inlnPython[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://www.python.org/}{Python} source code (\texttt{Arg2}) and
+displays the output in line.
+\begin{itemize}
+\item \texttt{Arg1} is optional and uses the \href{https://www.python.org/}{Python} server by default.
+\item \texttt{Arg2} is the \href{https://julialang.org/}{Julia} source code to run. If the \href{https://www.python.org/}{Python} source code is wrapped
+between "```" on both sides (as in the markdown grammar), then it will be
+implemented directly; otherwise the code will be written to a file on the
+disk and then be called.
\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
-\item \texttt{\textbackslash{}runPythonBatch[Arg1][Arg2]} runs an external
-\href{https://www.python.org/}{Python} code file in batch mode (without a
-server running). Python (at least currently), unlike the other
-languages we use, does not have an option to save and restore a
-session, which means that once a Python session ends, the working
-environement (variable, functions) is deleted. In order to allow a
-batch-mode in Python, we implemented such capability. It requires the
-\href{https://pypi.org/project/dill/}{dill} module, which has to be
+\item \texttt{\textbackslash{}runPythonBatch[Arg1][Arg2]} runs an external \href{https://www.python.org/}{Python} code file in batch mode
+(without a server running). Python (at least currently), unlike the other
+languages we use, does not have an option to save and restore a session, which
+means that once a Python session ends, the working environement (variable,
+functions) is deleted. In order to allow a batch-mode in Python, we
+implemented such capability. It requires the \href{https://pypi.org/project/dill/}{dill} module, which has to be
installed via \texttt{pip3 install dill}.
\begin{itemize}
\item \texttt{Arg1} is the \href{https://www.python.org/}{Python} source file name,
@@ -300,34 +323,45 @@ installed via \texttt{pip3 install dill}.
\href{https://www.r-project.org/}{R}
\begin{itemize}
-\item \texttt{\textbackslash{}runR[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external
-\href{https://www.r-project.org/}{R} code file.
+\item \texttt{\textbackslash{}runR[Arg1]\{Arg2\}\{Arg3\}[Arg4]} runs an external \href{https://www.r-project.org/}{R} code file.
+\begin{itemize}
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://www.r-project.org/}{R} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command
+\texttt{\textbackslash{}runExtCode}.
+\end{itemize}
+
+\item \texttt{\textbackslash{}runRIncOut[Arg1]\{Arg2\}[Arg3][Arg4][Arg5]} runs an external \href{https://www.r-project.org/}{R} code file and
+embeds the output.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses
-\href{https://pypi.org/project/talk2stat/}{talk2stat}'s
-\href{https://www.r-project.org/}{R} server by default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the
-basic command \texttt{\textbackslash{}runExtCode}.
+\item \texttt{Arg1} is optional and uses \href{https://pypi.org/project/talk2stat/}{talk2stat}'s \href{https://www.r-project.org/}{R} server by default.
+\item \texttt{Arg2}, \texttt{Arg3}, \texttt{Arg4}, and \texttt{Arg5} have the same effects as those of the command
+\texttt{\textbackslash{}runCodeIncOut}.
\end{itemize}
+
\item \texttt{\textbackslash{}inlnR[Arg1]\{Arg2\}[Arg3][Arg4]} runs \href{https://www.r-project.org/}{R}
source code (\texttt{Arg2}) and displays the output in line.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses the \href{https://www.r-project.org/}{R}
-server by default.
-\item \texttt{Arg2} is the \href{https://www.r-project.org/}{R} source code to run.
-If the \href{https://www.r-project.org/}{R} source code is wrapped
-between "```" on both sides (as in the markdown grammar), then it
-will be implemented directly; otherwise the code will be written to
-a file on the disk and then be called.
+\item \texttt{Arg1} is optional and uses the \href{https://www.r-project.org/}{R} server by default.
+\item \texttt{Arg2} is the \href{https://www.r-project.org/}{R} source code to run. If the \href{https://www.r-project.org/}{R} source code is wrapped between
+"```" on both sides (as in the markdown grammar), then it will be
+implemented directly; otherwise the code will be written to a file on the
+disk and then be called.
\item \texttt{Arg3} and \texttt{Arg4} have the same effects as those of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
\end{itemize}
\section{Revisions}
-\label{sec:orgdd95675}
+\label{sec:orga78221a}
\begin{itemize}
-\item v1.9, June 13, 2023: Update \texttt{\textbackslash{}inln} command; the optional \texttt{Arg3} is the output
+\item v2.0, June 23, 2023: add \texttt{\textbackslash{}runCodeIncOut} command that runs an external code and
+embeds the output and andd some language specific shortcuts; update
+\texttt{\textbackslash{}runExtCode} so that if the output file does not exist, the \texttt{cache} option will
+be overridden and the code will run; update \texttt{\textbackslash{}inln} so that its \texttt{Arg4} accept
+\texttt{cache} or appending \texttt{.cache} to use the cached result. We thank \href{https://github.com/kiryph}{kiryph} for
+suggesting these features.
+
+\item v1.9, June 13, 2023: update \texttt{\textbackslash{}inln} command; the optional \texttt{Arg3} is the output
file name and the optional \texttt{Arg4} is the output type.
\item v1.8, January 18, 2023, add support to \href{https://ctan.org/pkg/listings?lang=en}{listings.}
\item v1.7, August 20, 2022: changed the tmp/ folder to generated/ in order to
@@ -347,7 +381,7 @@ code files, zero bytes in output files.)
\end{itemize}
\section{Contributing}
-\label{sec:orge68f2c0}
+\label{sec:org097e6a5}
We welcome your contributions to this package by opening issues on
GitHub and/or making a pull request. We also appreciate more example
documents written using \texttt{runcode}.