texlive[64161] Master/texmf-dist: runcode (21aug22)
commits+karl at tug.org
commits+karl at tug.org
Sun Aug 21 22:03:00 CEST 2022
Revision: 64161
http://tug.org/svn/texlive?view=revision&revision=64161
Author: karl
Date: 2022-08-21 22:03:00 +0200 (Sun, 21 Aug 2022)
Log Message:
-----------
runcode (21aug22)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/runcode/README
trunk/Master/texmf-dist/doc/latex/runcode/runcode.pdf
trunk/Master/texmf-dist/doc/latex/runcode/runcode.tex
trunk/Master/texmf-dist/tex/latex/runcode/runcode.sty
Added Paths:
-----------
trunk/Master/texmf-dist/doc/latex/runcode/generated/
trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln2.tex
trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln4.tex
trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln5.tex
trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln6.tex
trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln7.tex
trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln8.tex
trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln9.tex
trunk/Master/texmf-dist/doc/latex/runcode/generated/testWithrunR.tex
trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.pdf
trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.tex
Removed Paths:
-------------
trunk/Master/texmf-dist/doc/latex/runcode/troubleshoot.pdf
trunk/Master/texmf-dist/doc/latex/runcode/troubleshoot.tex
Modified: trunk/Master/texmf-dist/doc/latex/runcode/README
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/README 2022-08-21 19:59:22 UTC (rev 64160)
+++ trunk/Master/texmf-dist/doc/latex/runcode/README 2022-08-21 20:03:00 UTC (rev 64161)
@@ -1,4 +1,4 @@
-LaTeX Package: runcode 2022/08/10 v1.6
+LaTeX Package: runcode 2022/08/20 v1.7
----------------------------------------
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
@@ -9,11 +9,13 @@
Haim Bar and HaiYing Wang https://github.com/Ossifragus/runcode
Files:
- * README - this file
- * runcode.sty - package source
- * runcode.tex - documentation (source)
- * runcode.pdf - documentation (pdf format)
- * runcodetroubleshoot.pdf (pdf format)
+ * README - this file
+ * runcode.sty - package source
+ * runcode.tex - documentation (source)
+ * runcode.pdf - documentation (pdf format)
+ * runcode_troubleshoot.tex - documentation (source)
+ * runcode_troubleshoot.pdf - documentation (pdf format)
+ * generated/ - a folder which contains files generated by runcode for the runcode_troubleshoot file
Installation:
[manual installation]
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln2.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln2.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln2.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1 @@
+Error in Factorial(6) : could not find function "Factorial"
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln2.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln4.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln4.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln4.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1 @@
+**ZERO BYTES IN OUTPUT**
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln4.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln5.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln5.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln5.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1 @@
+**ZERO BYTES IN OUTPUT**
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln5.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln6.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln6.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln6.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1 @@
+720
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln6.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln7.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln7.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln7.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1,4 @@
+ [,1] [,2] [,3]
+[1,] 1 4 7
+[2,] 2 5 8
+[3,] 3 6 9
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln7.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln8.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln8.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln8.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1,4 @@
+ [,1] [,2] [,3]
+[1,] 1 4 7
+[2,] 2 5 8
+[3,] 3 6 9
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln8.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln9.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln9.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln9.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1 @@
+TIMED OUT+
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/runcode_troubleshoot_inln9.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/generated/testWithrunR.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/generated/testWithrunR.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/generated/testWithrunR.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1,19 @@
+
+Call:
+lm(formula = y ~ x)
+
+Residuals:
+ Min 1Q Median 3Q Max
+-1.5900 -0.8153 -0.1531 0.6379 2.8379
+
+Coefficients:
+ Estimate Std. Error t value Pr(>|t|)
+(Intercept) 0.95130 0.09629 9.88 <2e-16 ***
+x 1.13879 0.10960 10.39 <2e-16 ***
+---
+Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
+
+Residual standard error: 0.9626 on 98 degrees of freedom
+Multiple R-squared: 0.5242, Adjusted R-squared: 0.5193
+F-statistic: 108 on 1 and 98 DF, p-value: < 2.2e-16
+
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/generated/testWithrunR.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: trunk/Master/texmf-dist/doc/latex/runcode/runcode.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/runcode/runcode.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/runcode.tex 2022-08-21 19:59:22 UTC (rev 64160)
+++ trunk/Master/texmf-dist/doc/latex/runcode/runcode.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -1,94 +1,184 @@
- % LaTeX Package: runcode v1.6 2022/08/10
- %
- % Copyright (C) 2021 by Haim Bar and HaiYing Wang
- %
- % This file may be distributed and/or modified under the
- % conditions of the LaTeX Project Public License, either
- % version 1.3c of this license or (at your option) any later
- % version. The latest version of this license is in:
- %
- % http://www.latex-project.org/lppl.txt
- %
- % and version 1.3c or later is part of all distributions of
- % LaTeX version 2005/12/01 or later.
+% LaTeX Package: runcode 2022/08/20 v1.7
+%
+% Copyright (C) 2020-2022 by Haim Bar and HaiYing Wang
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.3c of this license or (at your option) any later
+% version. The latest version of this license is in:
+%
+% http://www.latex-project.org/lppl.txt
+%
+% and version 1.3c or later is part of all distributions of
+% LaTeX version 2005/12/01 or later.
\documentclass{ltxdoc}
-\usepackage[hyphens]{url}
-\usepackage{runcode}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{graphicx}
+\usepackage{longtable}
+\usepackage{wrapfig}
+\usepackage{rotating}
+\usepackage[normalem]{ulem}
+\usepackage{amsmath}
+\usepackage{amssymb}
+\usepackage{capt-of}
+\usepackage{hyperref}
+\usepackage{minted}
+\author{Haim Bar and HaiYing Wang \\haim.bar at uconn.edu, haiying.wang at uconn.edu}
+\date{\today}
+\title{The \textbf{runcode} package}
\begin{document}
- \title{The \textsf{runcode} package\thanks{This document corresponds to \textsf{runcode}~v1.6, dated~2022/08/10.}}
- \author{Haim Bar and HaiYing Wang \\ \texttt{haim.bar at uconn.edu}, \texttt{haiying.wang at uconn.edu}}
- \maketitle
-\abstract{\textsf{runcode} is a \LaTeX package that executes programming source codes (including all command line tools) from \LaTeX, and embeds the results in the resulting pdf file. Many programming languages can be easily used and any command-line executable can be invoked when preparing the pdf file from a tex file.
+\maketitle
+\begin{abstract}
-It is recommended to use this package in the server-mode together with the Python talk2stat package. Currently, the server-mode supports Julia, MatLab, Python, and R. More languages will be added.
+\texttt{runcode} is a \LaTeX{} package that executes programming source codes (including
+all command line tools) from \LaTeX{}, and embeds the results in the resulting pdf
+file. Many programming languages can be easily used and any command-line
+executable can be invoked when preparing the pdf file from a tex file. \texttt{runcode}
+is also available on \href{https://ctan.org/pkg/runcode}{CTAN}.
-For more details and usage examples and troubleshooting, refer to the package's github repository, at
-\url{https://github.com/Ossifragus/runcode}.
-}
+It is recommended to use this package in the server mode together with the
+\href{https://www.python.org/}{Python} \href{https://pypi.org/project/talk2stat/}{talk2stat} package. Currently, the server mode supports \href{https://julialang.org/}{Julia}, \href{https://www.mathworks.com/products/matlab.html}{MatLab},
+\href{https://www.python.org/}{Python}, and \href{https://www.r-project.org/}{R}. More languages will be added.
+For more details and usage examples and troubleshooting, refer to the
+package’s github repository, at \url{https://github.com/Ossifragus/runcode}.
+
+\end{abstract}
+
\section{Installation}
-The package on CTAN can be installed automatically by your \TeX\space software (e.g., MikTeX Update Wizard). You can also simply put the runcode.sty file in the \LaTeX\space project folder. To use the package you have to enable the `shell-escape' option when compiling a \LaTeX\space document.
-
-The server mode requires the \textit{talk2stat} Python package. To install it from the command line, use:
-\verb|pip3 install talk2stat|\\
-The \textit{talk2stat} source is available from \url{https://pypi.org/project/talk2stat/}.
-Note that Python version 3.8.* and up is required.
+\label{sec:org7e4c2ed}
+You can simply put the runcode.sty file in the \LaTeX{} project folder.
+The server mode requires the
+\href{https://pypi.org/project/talk2stat/}{talk2stat} package. To install
+it from the command line, use:
+
+\begin{verbatim}
+pip3 install talk2stat
+\end{verbatim}
+
+\textbf{Note}: \texttt{runcode} requires to enable the \texttt{shell-escape} option when
+compiling a \LaTeX{} document.
+
+
\section{Usage}
-\subsection{Load the package}
-\verb|\usepackage[options]{runcode}|\\
-\\
-Available options are:
+\label{sec:org2d22735}
+\subsection{Load the package:}
+\label{sec:orgbfab84d}
+\begin{minted}[]{latex}
+\usepackage[options]{runcode}
+\end{minted}
+
+Available options are:
+
\begin{itemize}
-\item \texttt{julia}: start a \textit{talk2stat} server* for Julia [\url{https://julialang.org/}].
-\item \texttt{matlab}: start a \textit{talk2stat} server* for MatLab [\url{https://www.mathworks.com/products/matlab.html}].
-\item \texttt{R}: start a \textit{talk2stat} server* for R [\url{https://www.r-project.org/}].
-\item \texttt{run}: run source code, and store results in cache files.
-\item \texttt{cache}: use cached results.
-\item \texttt{stopserver}: stop the \textit{talk2stat} server(s) when the pdf compilation is done.
-\item \texttt{nohup}: when using the server-mode, some editors terminate all child processes after LaTeX compiling such as Emacs with Auctex. For this case, use the nohup option. It set the variable notnohup to be false, and the server will not be terminated by the parent process.
-\item \texttt{nominted}: use the \textit{fvextra} package [\url{https://ctan.org/pkg/fvextra}] instead of the \textit{minted} package [\url{https://ctan.org/pkg/minted}] to show code (\textit{fvextra} does not require Python's pygments package [\url{https://pygments.org/}], but it does not provide syntax highlights).
-\item \texttt{reducedspace}: with some document classes minted puts too much space after an embedded block of code. Use this option to remove the extra space.
+\item \texttt{cache}: use cached results.
+
+\item \texttt{julia}: start server for \href{https://julialang.org/}{Julia} (requires
+\href{https://pypi.org/project/talk2stat/}{talk2stat}).
+
+\item \texttt{matlab}: start server for
+\href{https://www.mathworks.com/products/matlab.html}{MatLab} (requires
+\href{https://pypi.org/project/talk2stat/}{talk2stat}).
+
+\item \texttt{nominted}: use the \href{https://ctan.org/pkg/fvextra}{fvextra} package
+instead of the \href{https://ctan.org/pkg/minted}{minted} package to show
+code (this does not require the \href{https://pygments.org/}{pygments}
+package, but it does not provide syntax highlights).
+
+\item \texttt{nohup}: use the \texttt{nohup} command when starting a server. When using
+the server-mode, some editors terminate all child processes after
+\LaTeX{} compiling such as Emacs with Auctex. This option set the
+variable notnohup to be false, and the server will not be terminated
+by the parent process. \textbf{This option has to be declared before
+declaring any language}, e.g., \texttt{[nohup, R]} works but \texttt{[R, nohup]}
+does not work.
+
+\item \texttt{python}: start server for \href{https://www.python.org/}{Python}
+(requires \href{https://pypi.org/project/talk2stat/}{talk2stat}).
+
+\item \texttt{run}: run source code.
+
+\item \texttt{R}: start server for \href{https://www.r-project.org/}{R} (requires
+\href{https://pypi.org/project/talk2stat/}{talk2stat}).
+
+\item \texttt{stopserver}: stop the server(s) when the pdf compilation is done.
\end{itemize}
-* Requires the Python package \textit{talk2stat} to be installed.
-\subsection{Basic commands}
-\verb|\runExtCode{Arg1}{Arg2}{Arg3}[Arg4]| runs an external code. The arguments are:
+\textbf{Note}: If \href{https://ctan.org/pkg/minted}{minted} is used, the style of
+the code block is controlled through the minted package,
+\href{https://github.com/Ossifragus/runcode/blob/master/examples/MontyHall/MontyHall.tex\#L3-L4}{e.g.:}
+
+\begin{minted}[]{latex}
+\setminted[julia]{linenos, frame=single, bgcolor=bg, breaklines=true}
+\setminted[R]{linenos, frame=single, bgcolor=lightgray, breaklines=true}
+\end{minted}
+
+The outputs from executing codes are displayed in
+\href{https://ctan.org/pkg/tcolorbox?lang=en}{tcolorbox}, so the style can
+be customized with \texttt{\textbackslash{}tcbset},
+\href{https://github.com/Ossifragus/runcode/blob/master/examples/MontyHall/MontyHall.tex\#L5}{e.g.:}
+
+\begin{minted}[]{latex}
+\tcbset{breakable,colback=red!5!white,colframe=red!75!black}
+\end{minted}
+
+\subsection{Basic commands:}
+\label{sec:org1b11cd1}
\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 `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} as determined by the \texttt{run} option when loading the package, is used; if the value is set to `run`, the code will be executed; if set to `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: 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).
\end{itemize}
-\bigskip
-\noindent \verb|\showCode{Arg1}{Arg2}[Arg3][Arg4]| shows the source code, using minted for a pretty layout or fvextra (if pygments is not installed).
+\item \texttt{\textbackslash{}showCode\{Arg1\}\{Arg2\}[Arg3][Arg4]} shows the source code, using
+\href{https://ctan.org/pkg/minted}{minted} for a pretty layout or
+\href{https://ctan.org/pkg/fvextra}{fvextra} (if
+\href{https://pygments.org/}{pygments} is not installed).
+
\begin{itemize}
\item \texttt{Arg1} is the programming language.
\item \texttt{Arg2} is the source file name.
\item \texttt{Arg3} is the first line to show (optional with a default value 1).
-\item \texttt{Arg4} is the last line to show (optional with a default value of the last line).
+\item \texttt{Arg4} is the last line to show (optional with a default value of
+the last line).
\end{itemize}
-\bigskip
-\noindent \verb|\includeOutput{Arg1}[Arg2]| is used to embed the output from executed code.
+\item \texttt{\textbackslash{}includeOutput\{Arg1\}[Arg2]} is used to embed the output from executed
+code.
+
\begin{itemize}
-\item \texttt{Arg1} is the output file name, and it needs to have the same value as that of \texttt{Arg3} in \verb|\runExtCode|. If an empty value is given to \texttt{Arg1}, the counter `codeOutput` is used.
-\item \texttt{Arg2} is optional and it controls the type of output with a default value `vbox`
+\item \texttt{Arg1} is the output file name, and it needs to have the same value
+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}
\begin{itemize}
\item \texttt{vbox} (or skipped) = verbatim in a box.
\item \texttt{tex} = pure latex.
-\item \texttt{inline} = embed result in text.
+\item \texttt{inline} = embed result in text.
\end{itemize}
\end{itemize}
-\bigskip
-\noindent \verb|\inln{Arg1}{Arg2}[Arg3]| is designed for simple calculations; it runs one command (or a short batch) and displays the output within the text.
+\item \texttt{\textbackslash{}inln\{Arg1\}\{Arg2\}[Arg3]} is designed for simple calculations; it runs
+one command (or a short batch) and displays the output within the
+text.
+
\begin{itemize}
-\item \texttt{Arg1} is the executable program or programming language.
-\item \texttt{Arg2} is the source code.
+\item \texttt{Arg1} is the executable program or programming language.
+\item \texttt{Arg2} is the source code.
\item \texttt{Arg3} is the output type.
\begin{itemize}
\item \texttt{inline} (or skipped or with empty value) = embed result in text.
@@ -95,88 +185,161 @@
\item \texttt{vbox} = verbatim in a box.
\end{itemize}
\end{itemize}
+\end{itemize}
-\subsection{Language specific shortcuts}
-\verb|\runJulia[Arg1]{Arg2}{Arg3}[Arg4]| runs an external Julia code file.
+\subsection{Language specific shortcuts:}
+\label{sec:org154f922}
+\href{https://julialang.org/}{Julia}
+
\begin{itemize}
-\item \texttt{Arg1} is optional and uses \textit{talk2stat}'s Julia server by default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \verb|\runExtCode|.
+\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}.
\end{itemize}
-
-\noindent \verb|\inlnJulia[Arg1]{Arg2}[Arg3]| runs Julia source code (\texttt{Arg2}) and displays the output in line.
+\item \texttt{\textbackslash{}inlnJulia[Arg1]\{Arg2\}[Arg3]} 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 Julia server by default.
-\item \texttt{Arg2} is the Julia source code to run. If the Julia source code is wrapped between \verb|```| 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} has the same effect as that of the basic command \verb|\inln|.
+\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} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
+\end{itemize}
-\bigskip
-\noindent \verb|\runMatLab[Arg1]{Arg2}{Arg3}[Arg4]| runs an external MatLab code file.
+\href{https://www.mathworks.com/products/matlab.html}{MatLab}
+
\begin{itemize}
-\item \texttt{Arg1} is optional and uses \textit{talk2stat}'s MatLab server by default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \verb|\runExtCode|.
+\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}.
\end{itemize}
-
-\noindent
-\verb|\inlnMatLab[Arg1]{Arg2}[Arg3]| runs MatLab source code (\texttt{Arg2}) and displays the output in line.
+\item \texttt{\textbackslash{}inlnMatLab[Arg1]\{Arg2\}[Arg3]} 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 MatLab server by default.
-\item \texttt{Arg2} is the MatLab source code to run. If the MatLab source code is wrapped between \verb|```| 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} has the same effect as that of the basic command \verb|\inln|.
+\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} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
+\end{itemize}
+\href{https://www.python.org/}{Python}
-\bigskip
-\noindent \verb|\runR[Arg1]{Arg2}{Arg3}[Arg4]| runs an external R code file.
\begin{itemize}
-\item \texttt{Arg1} is optional and uses \textit{talk2stat]}'s R server by default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \verb|\runExtCode|.
+\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}.
\end{itemize}
-
-\noindent \verb|\inlnR[Arg1]{Arg2}[Arg3]| runs R source code (\texttt{Arg2}) and displays the output in line.
+\item \texttt{\textbackslash{}inlnPython[Arg1]\{Arg2\}[Arg3]} 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 R server by default.
-\item \texttt{Arg2} is the R source code to run. If the R source code is wrapped between \verb|```| 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} has the same effect as that of the basic command \verb|\inln|.
+\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} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
-
-
-\bigskip
-\noindent \verb|\runPython[Arg1]{Arg2}{Arg3}[Arg4]| runs an external Python code file.
+\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 optional and uses \textit{talk2stat]}'s Python server by default.
-\item \texttt{Arg2}, \texttt{Arg3}, and \texttt{Arg4} have the same effects as those of the basic command \verb|\runExtCode|.
+\item \texttt{Arg1} is the \href{https://www.python.org/}{Python} source file name,
+\item \texttt{Arg2} is the output file name.
\end{itemize}
+\end{itemize}
-\noindent \verb|\inlnPython[Arg1]{Arg2}[Arg3]| runs Python source code (\texttt{Arg2}) and displays the output in line.
+\href{https://www.r-project.org/}{R}
+
\begin{itemize}
-\item \texttt{Arg1} is optional and uses the Python server by default.
-\item \texttt{Arg2} is the R source code to run. If the Python source code is wrapped between \verb|```| 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} has the same effect as that of the basic command \verb|\inln|.
+\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}
-
-\noindent \verb|\runPythonBatch[Arg1][Arg2]| runs an external Python source code (\texttt{Arg1}) 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 environment (variable, functions) is deleted. In order to allow a batch-mode in Python, we implemented such capability. It requires the dill module (https://pypi.org/project/dill/) module, which has to be installed via `pip3 install dill`.
+\item \texttt{\textbackslash{}inlnR[Arg1]\{Arg2\}[Arg3]} runs \href{https://www.r-project.org/}{R}
+source code (\texttt{Arg2}) and displays the output in line.
\begin{itemize}
-\item \texttt{Arg1} is the Python source code to run.
-\item \texttt{Arg2} is the output file name.
+\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} has the same effect as that of the basic command \texttt{\textbackslash{}inln}.
\end{itemize}
+\end{itemize}
-
-
\section{Revisions}
+\label{sec:orgf446497}
\begin{itemize}
-\item v1.6, August 10, 2022: stop only configured/running servers; a new reducedspace option - some document classes put more space after the code box; changed the default timeout of servers to 60 seconds; expanded the troubleshooting document. New examples are now available on GitHub, including how to collaborate with people who use Overleaf.
-\item v1.5, July 23, 2022: Removed the utf8x option when loading inputenc due to a conflict with hyperref.
+\item v1.7, August 20, 2022: changed the tmp/ folder to generated/ in order to
+conform with CTAN suggestions; renamed the troubleshooting file.
+\item v1.6, August 10, 2022: stop only configured/running servers; a new
+reducedspace option - some document classes put more space after the code box;
+changed the default timeout of servers to 60 seconds; expanded the
+troubleshooting document. New examples are now available on GitHub, including
+how to collaborate with people who use Overleaf.
+\item v1.5, July 23, 2022: Removed the utf8x option when loading inputenc due to a
+conflict with hyperref.
\item v1.4, July 18, 2022: Fixed a bug in the cache mode.
\item v1.3, May 14, 2022: Removed the hard-coded minted options.
\item v1.2, May 3, 2022: Added python options (server and batch).
-\item v1.1, April 17, 2021: Added a nohup option; improved error handling (missing code files, zero bytes in output files.)
+\item v1.1, April 17, 2021: Added a nohup option; improved error handling (missing
+code files, zero bytes in output files.)
\end{itemize}
-
-%
\section{Contributing}
-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 \textsf{runcode}.
+\label{sec:org0730899}
+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}.
+
+\textbf{Citing} \texttt{runcode}:
+Haim Bar and HaiYing Wang (2021). \href{https://jds-online.org/journal/JDS/article/103/info}{Reproducible Science with \LaTeX{}},
+\emph{Journal of Data Science} 2021; 19, no. 1, 111-125, DOI 10.6339/21-JDS998
\end{document}
Added: trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.pdf
===================================================================
(Binary files differ)
Index: trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.pdf
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.pdf 2022-08-21 19:59:22 UTC (rev 64160)
+++ trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.pdf 2022-08-21 20:03:00 UTC (rev 64161)
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.pdf
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+application/pdf
\ No newline at end of property
Added: trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.tex (rev 0)
+++ trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -0,0 +1,309 @@
+\documentclass[a4paper,10pt]{article}
+\usepackage[a4paper, total={6in, 10in}]{geometry}
+%\usepackage[square,sort,comma]{natbib}
+% \usepackage[R,stopserver]{runcode}
+\usepackage[cache]{runcode}
+
+\usepackage{caption}
+%\usepackage{subcaption}
+\usepackage{subfig}
+
+
+\newcommand{\prob}[1] {\bigskip\noindent\textbf{\textcolor{orange}{Problem:}}\\#1\\\\}
+\newcommand{\cause}[1] {\noindent\textit{\textcolor{blue}{Possible reason and solution:}}\\#1}
+\newcommand{\cmnt}[1] {\bigskip\noindent\textit{Notes:} #1}
+
+% Title Page
+\title{The runcode package -- troubleshooting}
+\author{Haim Bar and HaiYing Wang}
+
+
+\begin{document}
+\maketitle
+
+When using the runcode package, you have to be aware of some usage rules, so this document attempts to anticipate all the possible user or system errors, and show how to interpret the output and fix the problems.
+
+\subsection*{Before you start using runcode}
+
+Before using the package make sure that you have Python (version 3.x) installed and in your path. Also, you must install the required \LaTeX~ packages:
+morewrites, tcolorbox, xcolor, inputenc, textgreek, filecontents, xifthen, xparse, xstring, and fvextra. The minted package is optional but recommended.
+
+If you try to compile this file from its tex source, you will get errors (because the purpose of this document is to demonstrate errors and how to fix them.) It is assumed that you are using a cloned runcode repository, so files used in this document are ones in the directory structure as it is stored on github.
+
+The files generated by runcode live in the project's directory, so we assume the user has the necessary permissions to create, modify, delete files and subfolder.
+
+For the server mode the folder must contain a configuration file for each statistical language used (R, julia, matlab, Python). If such files don't exist, runcode will create them with default values. Remember to check if the defaults work for you. For example, you may need to change the port number, or increase the timeout parameter.
+
+\subsection*{Some possible errors and solutions}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\prob{runcode functions are not executed.}
+\cause\bgroup
+Check if you enabled the \verb|shell-escape| option when the document is compiled. If not, you will see warnings in the project's log file. For example:
+\begin{Verbatim}
+Package ifplatform Warning:
+ shell escape is disabled, so I can only detect \ifwindows.
+! Package minted Error: You must invoke LaTeX with the -shell-escape flag.
+\end{Verbatim}
+\egroup
+
+\cause\bgroup
+Check if the command-line tools you invoke from runcode are installed, and in your path (e.g., R, Julia, Matlab, Python).
+\egroup
+
+\cmnt\bgroup
+The runcode package can call any command-line function when it is used in `batch-mode'. That is, when the command-line tool is called separately each time a computation is performed from within the tex document (upon compilation). When using R, Julia, Python, or Matlab, the user can maintain a continuous session to the corresponding command-line tool. This saves initialization time, and allows to keep a session's history, for performing steps sequentially and efficiently. This is the recommended way to use runcode with R, Julia, Python, and Matlab.
+At the present time, no other languages are supported for `server-mode' operation.
+\egroup
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\prob{Code highlighting is not working properly.}
+\cause\bgroup
+When code is included in the manuscript, it is done via the \verb|\showCode| command. By default, the code-highlighting it done via the minted package. If code highlighting doesn't work, check if the minted package is installed properly. Python (3.x) also has to be installed, and also the Pygments package (which has to be installed via pip3). If you have trouble with the installation of minted, use the \verb|nominted| option when you include the runcode package. This will cause runcode to use the fvextra for code display, instead.
+\egroup
+
+
+\prob{Embedded code is not shown.}
+\cause\bgroup
+Check if you specified the source file correctly.
+\verb|\showCode| prints the source code, using minted for a pretty layout. It takes 4 arguments.
+Arg \#1 is the programming language,
+Arg \#2 is the source file name,
+Args \#3 and \#4 are the first and last line to show (optional).
+If the source file name does not exist, you will get a red and bold error message. For example:
+\begin{verbatim}\showCode{R}{Sim23.R}
+\end{verbatim}
+\showCode{R}{Sim23.R}
+\noindent
+In contrast, when the file exists, as in this example
+\begin{verbatim}\showCode{R}{paper/supplement/Code/code1.R}
+\end{verbatim}
+the file will be shown correctly:
+\showCode{R}{paper/supplement/Code/code1.R}
+\egroup
+
+\cause\bgroup
+If the programming language is misspecified or not recognized by minted or fvextra, the code highlighting may not be shown correctly.
+\begin{verbatim}\showCode{matlab}{paper/supplement/Code/code1.R}
+\end{verbatim}
+\showCode{matlab}{paper/supplement/Code/code1.R}
+\egroup
+
+\cause\bgroup
+If the line number in Arg \#3 exceeds the actual number of lines in the code, the code box will be empty, and the \LaTeX~ compiler will show an error message in its log file (`Empty verbatim environment'). For example:
+\begin{verbatim}\showCode{R}{paper/supplement/Code/code1.R}[6][8]
+\end{verbatim}
+% \showCode{R}{paper/supplement/Code/code1.R}[6][8]
+% \vspace{-2em}
+\noindent Some \LaTeX~ compilers will stop the compilation when they encounter `Empty verbatim environment' but will allow you to manually continue the compilation (and the generated pdf will contain an empty box with no code in it.)
+
+\noindent If the number in Arg. \#4 is greater than the number of lines in the file, minted will show the code up to the last line (so this misspecification is harmless).
+\begin{verbatim}\showCode{R}{paper/supplement/Code/code1.R}[4][8]
+\end{verbatim}
+\showCode{R}{paper/supplement/Code/code1.R}[4][8]
+\egroup
+
+\cmnt{Remember that the compiler is case-sensitive, so test.R is not the same as Test.R.}
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\prob{Errors when running code.}
+\cause\bgroup
+In batch-mode with \verb|\runExtCode|, if the source file name does not exist, you will get a red and bold error message:\\
+\verb|\runExtCode{julia}{test2.jl}{test2}|\\
+\runExtCode{julia}{test2.jl}{test2}\\
+Again, check for spelling errors in the file name, which is the most common reason for such problems.\\
+
+\noindent Similarly, when using the \textit{server-mode} of runcode, we can use the shortcuts to R, Julia, Python, or Matlab instead of \verb|\runExtCode|. The usage is similar, but the language name is inferred from the command. For example, we can have:\\
+\verb|\runR{paper/supplement/Code/code1.R}{testWithrunR}|
+\runR{paper/supplement/Code/code1.R}{testWithrunR}\\
+If the source code file doesn't exist, we get an error message as with \verb|\runExtCode|\\
+\verb|\runJulia{test2.jl}{test2}|\\
+\runJulia{test2.jl}{test2}\\
+\egroup
+
+\cause\bgroup
+Check that the correct executable is used, since \verb|\runExtCode| requires the specific program and command line arguments. For example, using R as the executable will not work in the following example:\\
+\verb|\runExtCode{R}{paper/supplement/Code/code1.R}{testWithR}|\\
+%\runExtCode{R}{paper/supplement/Code/code1.R}{testWithR}
+It will create the file generated/testWithR.tex, and in it you will see\\
+\verb|ARGUMENT 'paper/supplement/Code/code1.R' __ignored__|\\
+This is a fatal error -- the compiler will get stuck because it will wait for the code to finish, and the compilation process will have to be terminated by the user.
+\noindent
+The correct way to use \verb|\runExtCode| with R in batch-mode is\\
+\verb|\runExtCode{Rscript --save --restore}{paper/supplement/Code/code1.R}{test}|\\
+See the package's documentation for more working examples.\\
+\egroup
+
+
+\cause\bgroup
+Check for syntax errors int the code.
+In the \textit{server-mode} only, \verb|\inln|, \verb|\inlnR|, \verb|\inlnJulia|, \verb|\inlnPython|, and \verb|\inlnMatlab| commands can be used to execute short source code and embed the resulting output within the text. It takes 3 arguments.
+Arg \#1 is the executable program;
+Arg \#2 is the source code
+Arg \#3 is the type output (if skipped or with empty value the default type is inline; vbox = verbatim in a box).
+
+\noindent If the code contains a syntax error, the error produced by the statistical software will be embedded in the text. For example, if we use Factorial, instead of the real function (factorial) we get an error message:\\
+\verb|The factorial of 6 is \inlnR{```cat(Factorial(6))```}.|\\
+would produce the following:\\
+The factorial of 6 is \inlnR{```cat(Factorial(6))```}.\\
+
+\noindent Such errors are not due to \LaTeX~ syntax or compilation, so runcode doesn't highlight them. Automatically identifying and highlighting such errors would require case-by-case analysis of the output of specific command-line tools. For now, it's up to the user to check the code before it is embedded in the tex document, and to check the output after the compilation.
+\egroup
+
+
+\cmnt\bgroup
+Recall that \verb|\runExtCode| which is used to run an external code takes 4 arguments:
+Arg \#1 is the executable program,
+Arg \#2 is the source file name,
+Arg \#3 is the output file name (optional - if not given, the counter
+ codeOutput is used).
+Arg \#4 controls when to run the code (optional - if not given, it listens
+ to \verb|\runcode|; run = force the code to run; cache or anything else =
+ use cache).\\
+The first argument can be \textit{any} command-line executable, including user-defined program names (compiled code, aliases, etc.). Because of that, we do not perform validity check before trying to execute it.
+For example, the following will not produce any error message:\\
+\verb|\runExtCode{C}{test.R}{}|\\
+but it will be possible to see an empty file in the generated folder. This will be obvious to the user once the \verb|\includeOutput| command is executed in order to embed results in the compiled pdf document.
+\egroup
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\prob{Output is not produced, or unexpected/incorrect results are shown.}
+\cause\bgroup
+This could happen due to incorrect usage of the \verb|\includeOutput| function, which is used to embed the output from executed code. It takes 2 arguments:
+Arg \#1 is the output file name (optional - if not given, the counter codeOutput is used).
+Arg \#2 is the optional type output with default "vbox" (vbox = verbatim in a box, tex = pure latex, or inline).
+For example, if we run the code\\
+\verb|\runR{paper/supplement/Code/code1.R}{testWithrunR}|
+\runR{paper/supplement/Code/code1.R}{testWithrunR}\\
+\noindent
+Then to see the output, the correct usage is\\
+\verb|\includeOutput{testWithrunR}[vbox]|\\
+\includeOutput{testWithrunR}[vbox]
+
+\noindent Although the physical file is named generated/testWithrunR.tex, we drop the generated/ prefix and the .tex suffix. If we do include them, the file will not be found and we'll get an error message:\\
+\verb|\includeOutput{testWithrunR.tex}[vbox]|
+\includeOutput{testWithrunR.tex}[vbox]
+\egroup
+
+\cmnt\bgroup
+If anything other than vbox, tex, or inline is provided in the square brackets when using \verb|\includeOutput|, the output will be embedded in the document as plain text. While no error or warning is raised, this may cause problems in the compilation of the tex file and therefore should be avoided. (For example, if the output contains underscores then the compiler will report an error because it would appear that math symbols are used in text mode).\\
+\egroup
+
+
+\cause\bgroup
+When using one of the \verb|inln| functions, the code does not produce any output.
+In some cases it is perfectly fine if embedded code does not produce output, but when using \verb|\inln| this is not the case, so runcode checks if the command used within \verb|\inln| produced a zero-byte output file. If it did, runcode will show an appropriate message, like in the following example. Note that the reason no output is produced is that file.csv does not exist.\\
+\verb|The number of columns is \inlnR{```dat <- read.csv("file.csv"); cat(ncol(dat))```}.|\\
+This will result in:\\
+The number of columns is \inlnR{```dat <- read.csv("file.csv"); cat(ncol(dat))```}.\\
+\egroup
+
+\cause\bgroup
+When using one of the \verb|inln| functions, more than one line of output is produced by the code.
+The \verb|\inln| commands are designed to put a single string in a line, so the code which produces the output should not include a new line. For example, the following is incorrect:\\
+\verb|The factorial of 6 is \inlnR{```cat(factorial(6),"\\n")```}.|\\
+The factorial of 6 is \inlnR{```cat(factorial(6),"\\n")```}.
+\noindent
+The correct way is:\\
+\verb|The factorial of 6 is \inlnR{```cat(factorial(6))```}.|\\
+which produces the following:
+The factorial of 6 is \inlnR{```cat(factorial(6))```}.
+
+
+\noindent
+Similarly, if we want to print more than a one-line string, we should use the vbox option (or use \verb|\includeOutput|.) For example,\\
+\verb|A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}.|\\
+Will appear like this: A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}.
+\\
+\verb|A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}[vbox].|\\
+Will look better: A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}[vbox].
+\egroup
+
+
+\cause\bgroup
+This type of problem can also be due to invalid output in the cache files. If for some reason, the cache files contain special characters or an underscore in text-mode, then the output will be corrupted. It is recommended to clear the cache, and if server-mode is used to also restart the server. For example, suppose that the directory of the project is called proj, and we're using Python in server-mode. From the command line, run the following:
+\begin{Verbatim}
+cd proj
+rm -f proj.aux generated/*.txt nohup.out proj.synctex.gz
+python3 -c 'from talk2stat.talk2stat import client; client("./","python","QUIT")'
+rm -f serverPIDpython.txt pythondebug.txt talk2stat.log
+\end{Verbatim}
+Then, recompile the project.\\
+\egroup
+
+
+\cause\bgroup
+Invalid, missing, or unexpected output can be due to having another runcode running on the system, but in another directory. If this happens, you will see a message in the log file saying that the server is already running. When multiple projects attempt to connect with the statistical software through the same port, only the first invocation will succeed but the subsequent ones will be connected to the first one. This will create unexpected results for all projects using the same port. Suppose your new project is B, and the runcode server of project A is still running and using the same port. In this case you may, for example,
+\begin{itemize}
+\item Accidentally overwrite variables in project A, or use the wrong ones in project B if they were also defined in A;
+\item Try to run code which is stored in project B, but you get an error message in the pdf file such as `\texttt{cannot open file 'mycode.R': No such file or directory}'. The reason for this error is that the other instance of the runcode server uses project A's base directory, and the file mycode.R is not in the right path.
+\end{itemize}
+To fix it, you can do one of the following:
+\begin{enumerate}
+\item configure each project to use another port to communicate with talk2stat (which will prevent any conflict between the projects), or,
+\item you can stop all instances of talk2stat running on the system before compiling your current project.
+\end{enumerate}
+To do the latter, find all the talk2stat processes, and find the corresponding directories. For example, suppose that multiple projects use talk2stat to communicate with Julia. From the command-line, do the following:
+\begin{Verbatim}
+cd proj
+ps -ef | grep talk2stat # get all the PIDs. E.g., 36797
+# on Mac:
+lsof -a -d cwd -p 36797
+# on Linux:
+pwdx 36797
+# lsof or pwdx will give you the directory name of the other projects which run talk2stat
+# cd to each directory, and run:
+python3 -c 'from talk2stat.talk2stat import client; client("./","julia","QUIT")'
+rm -f serverPIDjulia.txt juliadebug.txt talk2stat.log
+\end{Verbatim}
+\egroup
+
+
+\cause\bgroup
+If the correct output is in the files in generated directory, but it's not showing in the pdf file, it can be due to the \LaTeX~ compiler's naming of temporary files. Usually, the auto-generated file names start with the main tex file name (e.g. if the main tex file is called troubleshoot.tex then runcode will create files such as \verb|troubleshoot_inln5.tex|). However, working with Overleaf we noticed that their compiler uses another convention for temporary file names. To prevent such problems, you can add the following in the preamble of the main document:
+\begin{Verbatim}
+\edef\TeXjobname{\jobname} % (this line is not really essential.)
+\edef\jobname{\detokenize{troubleshoot}}
+\end{Verbatim}
+\egroup
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\prob{Working in server-mode, the server is stopped after each compilation.}
+\cause\bgroup
+If you are using the server-mode, be aware that some editors terminate all child processes at the end of \LaTeX compilation. For example, Emacs with Auctex behaves this way. For this case, use the nohup option, and the server will not be terminated by the parent process.\\
+If you want the server to be stopped after each compilation (regardless of the editor you are using), use the stopserver option. While you are compiling the tex document often, you may want to keep the server side running in order to save time during initialization, and to maintain the variables and results already in memory. However, it is a good idea to use the stopserver option when you are done, just to prevent any conflicts (see above).\\
+It's recommended to check that port numbers are unique, and when a project is not expected to be compiled for a while to enable the stopserver option.
+\egroup
+
+
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+
+\prob{The process seems to hang during code execution when the \LaTeX~ document is compiled.}
+\cause\bgroup
+We mentioned that code being sent to the software must be syntactically valid. In addition, keep in mind that the server waits for complete commands. So, for example, if we try\\
+\verb|The factorial of 6 is \inlnR{```cat(factorial(6)```}.|\\
+it will cause the server to hang because it awaits the closing parenthesis. Eventually, it will time out but the code cannot be executed, so the desired output will not be produced, and an error message will replace the output, as in the following example. The timeout interval is set in the config files for R, Julia, Python, and Matlab.
+\verb|The factorial of 6 is \inlnR{```cat(factorial(6)```}.|\\
+The factorial of 6 is \inlnR{```cat(factorial(6)```}.\\
+In this example the cat statement is missing a closing parenthesis.\\
+\egroup
+
+
+
+\end{document}
+
+
Property changes on: trunk/Master/texmf-dist/doc/latex/runcode/runcode_troubleshoot.tex
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Deleted: trunk/Master/texmf-dist/doc/latex/runcode/troubleshoot.pdf
===================================================================
(Binary files differ)
Deleted: trunk/Master/texmf-dist/doc/latex/runcode/troubleshoot.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/runcode/troubleshoot.tex 2022-08-21 19:59:22 UTC (rev 64160)
+++ trunk/Master/texmf-dist/doc/latex/runcode/troubleshoot.tex 2022-08-21 20:03:00 UTC (rev 64161)
@@ -1,309 +0,0 @@
-\documentclass[a4paper,10pt]{article}
-\usepackage[a4paper, total={6in, 10in}]{geometry}
-%\usepackage[square,sort,comma]{natbib}
-%\usepackage[R,stopserver]{runcode}
-\usepackage[cache]{runcode}
-
-\usepackage{caption}
-%\usepackage{subcaption}
-\usepackage{subfig}
-
-
-\newcommand{\prob}[1] {\bigskip\noindent\textbf{\textcolor{orange}{Problem:}}\\#1\\\\}
-\newcommand{\cause}[1] {\noindent\textit{\textcolor{blue}{Possible reason and solution:}}\\#1}
-\newcommand{\cmnt}[1] {\bigskip\noindent\textit{Notes:} #1}
-
-% Title Page
-\title{The runcode package -- troubleshooting}
-\author{Haim Bar and HaiYing Wang}
-
-
-\begin{document}
-\maketitle
-
-When using the runcode package, you have to be aware of some usage rules, so this document attempts to anticipate all the possible user or system errors, and show how to interpret the output and fix the problems.
-
-\subsection*{Before you start using runcode}
-
-Before using the package make sure that you have Python (version 3.x) installed and in your path. Also, you must install the required \LaTeX~ packages:
-morewrites, tcolorbox, xcolor, inputenc, textgreek, filecontents, xifthen, xparse, xstring, and fvextra. The minted package is optional but recommended.
-
-If you try to compile this file from its tex source, you will get errors (because the purpose of this document is to demonstrate errors and how to fix them.) It is assumed that you are using a cloned runcode repository, so files used in this document are ones in the directory structure as it is stored on github.
-
-The files generated by runcode live in the project's directory, so we assume the user has the necessary permissions to create, modify, delete files and subfolder.
-
-For the server mode the folder must contain a configuration file for each statistical language used (R, julia, matlab, Python). If such files don't exist, runcode will create them with default values. Remember to check if the defaults work for you. For example, you may need to change the port number, or increase the timeout parameter.
-
-\subsection*{Some possible errors and solutions}
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\prob{runcode functions are not executed.}
-\cause\bgroup
-Check if you enabled the \verb|shell-escape| option when the document is compiled. If not, you will see warnings in the project's log file. For example:
-\begin{Verbatim}
-Package ifplatform Warning:
- shell escape is disabled, so I can only detect \ifwindows.
-! Package minted Error: You must invoke LaTeX with the -shell-escape flag.
-\end{Verbatim}
-\egroup
-
-\cause\bgroup
-Check if the command-line tools you invoke from runcode are installed, and in your path (e.g., R, Julia, Matlab, Python).
-\egroup
-
-\cmnt\bgroup
-The runcode package can call any command-line function when it is used in `batch-mode'. That is, when the command-line tool is called separately each time a computation is performed from within the tex document (upon compilation). When using R, Julia, Python, or Matlab, the user can maintain a continuous session to the corresponding command-line tool. This saves initialization time, and allows to keep a session's history, for performing steps sequentially and efficiently. This is the recommended way to use runcode with R, Julia, Python, and Matlab.
-At the present time, no other languages are supported for `server-mode' operation.
-\egroup
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\prob{Code highlighting is not working properly.}
-\cause\bgroup
-When code is included in the manuscript, it is done via the \verb|\showCode| command. By default, the code-highlighting it done via the minted package. If code highlighting doesn't work, check if the minted package is installed properly. Python (3.x) also has to be installed, and also the Pygments package (which has to be installed via pip3). If you have trouble with the installation of minted, use the \verb|nominted| option when you include the runcode package. This will cause runcode to use the fvextra for code display, instead.
-\egroup
-
-
-\prob{Embedded code is not shown.}
-\cause\bgroup
-Check if you specified the source file correctly.
-\verb|\showCode| prints the source code, using minted for a pretty layout. It takes 4 arguments.
-Arg \#1 is the programming language,
-Arg \#2 is the source file name,
-Args \#3 and \#4 are the first and last line to show (optional).
-If the source file name does not exist, you will get a red and bold error message. For example:
-\begin{verbatim}\showCode{R}{Sim23.R}
-\end{verbatim}
-\showCode{R}{Sim23.R}
-\noindent
-In contrast, when the file exists, as in this example
-\begin{verbatim}\showCode{R}{paper/supplement/Code/code1.R}
-\end{verbatim}
-the file will be shown correctly:
-\showCode{R}{paper/supplement/Code/code1.R}
-\egroup
-
-\cause\bgroup
-If the programming language is misspecified or not recognized by minted or fvextra, the code highlighting may not be shown correctly.
-\begin{verbatim}\showCode{matlab}{paper/supplement/Code/code1.R}
-\end{verbatim}
-\showCode{matlab}{paper/supplement/Code/code1.R}
-\egroup
-
-\cause\bgroup
-If the line number in Arg \#3 exceeds the actual number of lines in the code, the code box will be empty, and the \LaTeX~ compiler will show an error message in its log file (`Empty verbatim environment'). For example:
-\begin{verbatim}\showCode{R}{paper/supplement/Code/code1.R}[6][8]
-\end{verbatim}
-% \showCode{R}{paper/supplement/Code/code1.R}[6][8]
-% \vspace{-2em}
-\noindent Some \LaTeX~ compilers will stop the compilation when they encounter `Empty verbatim environment' but will allow you to manually continue the compilation (and the generated pdf will contain an empty box with no code in it.)
-
-\noindent If the number in Arg. \#4 is greater than the number of lines in the file, minted will show the code up to the last line (so this misspecification is harmless).
-\begin{verbatim}\showCode{R}{paper/supplement/Code/code1.R}[4][8]
-\end{verbatim}
-\showCode{R}{paper/supplement/Code/code1.R}[4][8]
-\egroup
-
-\cmnt{Remember that the compiler is case-sensitive, so test.R is not the same as Test.R.}
-
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\prob{Errors when running code.}
-\cause\bgroup
-In batch-mode with \verb|\runExtCode|, if the source file name does not exist, you will get a red and bold error message:\\
-\verb|\runExtCode{julia}{test2.jl}{test2}|\\
-\runExtCode{julia}{test2.jl}{test2}\\
-Again, check for spelling errors in the file name, which is the most common reason for such problems.\\
-
-\noindent Similarly, when using the \textit{server-mode} of runcode, we can use the shortcuts to R, Julia, Python, or Matlab instead of \verb|\runExtCode|. The usage is similar, but the language name is inferred from the command. For example, we can have:\\
-\verb|\runR{paper/supplement/Code/code1.R}{testWithrunR}|
-\runR{paper/supplement/Code/code1.R}{testWithrunR}\\
-If the source code file doesn't exist, we get an error message as with \verb|\runExtCode|\\
-\verb|\runJulia{test2.jl}{test2}|\\
-\runJulia{test2.jl}{test2}\\
-\egroup
-
-\cause\bgroup
-Check that the correct executable is used, since \verb|\runExtCode| requires the specific program and command line arguments. For example, using R as the executable will not work in the following example:\\
-\verb|\runExtCode{R}{paper/supplement/Code/code1.R}{testWithR}|\\
-%\runExtCode{R}{paper/supplement/Code/code1.R}{testWithR}
-It will create the file tmp/testWithR.tex, and in it you will see\\
-\verb|ARGUMENT 'paper/supplement/Code/code1.R' __ignored__|\\
-This is a fatal error -- the compiler will get stuck because it will wait for the code to finish, and the compilation process will have to be terminated by the user.
-\noindent
-The correct way to use \verb|\runExtCode| with R in batch-mode is\\
-\verb|\runExtCode{Rscript --save --restore}{paper/supplement/Code/code1.R}{test}|\\
-See the package's documentation for more working examples.\\
-\egroup
-
-
-\cause\bgroup
-Check for syntax errors int the code.
-In the \textit{server-mode} only, \verb|\inln|, \verb|\inlnR|, \verb|\inlnJulia|, \verb|\inlnPython|, and \verb|\inlnMatlab| commands can be used to execute short source code and embed the resulting output within the text. It takes 3 arguments.
-Arg \#1 is the executable program;
-Arg \#2 is the source code
-Arg \#3 is the type output (if skipped or with empty value the default type is inline; vbox = verbatim in a box).
-
-\noindent If the code contains a syntax error, the error produced by the statistical software will be embedded in the text. For example, if we use Factorial, instead of the real function (factorial) we get an error message:\\
-\verb|The factorial of 6 is \inlnR{```cat(Factorial(6))```}.|\\
-would produce the following:\\
-The factorial of 6 is \inlnR{```cat(Factorial(6))```}.\\
-
-\noindent Such errors are not due to \LaTeX~ syntax or compilation, so runcode doesn't highlight them. Automatically identifying and highlighting such errors would require case-by-case analysis of the output of specific command-line tools. For now, it's up to the user to check the code before it is embedded in the tex document, and to check the output after the compilation.
-\egroup
-
-
-\cmnt\bgroup
-Recall that \verb|\runExtCode| which is used to run an external code takes 4 arguments:
-Arg \#1 is the executable program,
-Arg \#2 is the source file name,
-Arg \#3 is the output file name (optional - if not given, the counter
- codeOutput is used).
-Arg \#4 controls when to run the code (optional - if not given, it listens
- to \verb|\runcode|; run = force the code to run; cache or anything else =
- use cache).\\
-The first argument can be \textit{any} command-line executable, including user-defined program names (compiled code, aliases, etc.). Because of that, we do not perform validity check before trying to execute it.
-For example, the following will not produce any error message:\\
-\verb|\runExtCode{C}{test.R}{}|\\
-but it will be possible to see an empty file in the tmp folder. This will be obvious to the user once the \verb|\includeOutput| command is executed in order to embed results in the compiled pdf document.
-\egroup
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\prob{Output is not produced, or unexpected/incorrect results are shown.}
-\cause\bgroup
-This could happen due to incorrect usage of the \verb|\includeOutput| function, which is used to embed the output from executed code. It takes 2 arguments:
-Arg \#1 is the output file name (optional - if not given, the counter codeOutput is used).
-Arg \#2 is the optional type output with default "vbox" (vbox = verbatim in a box, tex = pure latex, or inline).
-For example, if we run the code\\
-\verb|\runR{paper/supplement/Code/code1.R}{testWithrunR}|
-\runR{paper/supplement/Code/code1.R}{testWithrunR}\\
-\noindent
-Then to see the output, the correct usage is\\
-\verb|\includeOutput{testWithrunR}[vbox]|\\
-\includeOutput{testWithrunR}[vbox]
-
-\noindent Although the physical file is named tmp/testWithrunR.tex, we drop the tmp/ prefix and the .tex suffix. If we do include them, the file will not be found and we'll get an error message:\\
-\verb|\includeOutput{testWithrunR.tex}[vbox]|
-\includeOutput{testWithrunR.tex}[vbox]
-\egroup
-
-\cmnt\bgroup
-If anything other than vbox, tex, or inline is provided in the square brackets when using \verb|\includeOutput|, the output will be embedded in the document as plain text. While no error or warning is raised, this may cause problems in the compilation of the tex file and therefore should be avoided. (For example, if the output contains underscores then the compiler will report an error because it would appear that math symbols are used in text mode).\\
-\egroup
-
-
-\cause\bgroup
-When using one of the \verb|inln| functions, the code does not produce any output.
-In some cases it is perfectly fine if embedded code does not produce output, but when using \verb|\inln| this is not the case, so runcode checks if the command used within \verb|\inln| produced a zero-byte output file. If it did, runcode will show an appropriate message, like in the following example. Note that the reason no output is produced is that file.csv does not exist.\\
-\verb|The number of columns is \inlnR{```dat <- read.csv("file.csv"); cat(ncol(dat))```}.|\\
-This will result in:\\
-The number of columns is \inlnR{```dat <- read.csv("file.csv"); cat(ncol(dat))```}.\\
-\egroup
-
-\cause\bgroup
-When using one of the \verb|inln| functions, more than one line of output is produced by the code.
-The \verb|\inln| commands are designed to put a single string in a line, so the code which produces the output should not include a new line. For example, the following is incorrect:\\
-\verb|The factorial of 6 is \inlnR{```cat(factorial(6),"\\n")```}.|\\
-The factorial of 6 is \inlnR{```cat(factorial(6),"\\n")```}.
-\noindent
-The correct way is:\\
-\verb|The factorial of 6 is \inlnR{```cat(factorial(6))```}.|\\
-which produces the following:
-The factorial of 6 is \inlnR{```cat(factorial(6))```}.
-
-
-\noindent
-Similarly, if we want to print more than a one-line string, we should use the vbox option (or use \verb|\includeOutput|.) For example,\\
-\verb|A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}.|\\
-Will appear like this: A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}.
-\\
-\verb|A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}[vbox].|\\
-Will look better: A matrix \inlnR{```matrix(1:9,ncol=3,nrow=3)```}[vbox].
-\egroup
-
-
-\cause\bgroup
-This type of problem can also be due to invalid output in the cache files. If for some reason, the cache files contain special characters or an underscore in text-mode, then the output will be corrupted. It is recommended to clear the cache, and if server-mode is used to also restart the server. For example, suppose that the directory of the project is called proj, and we're using Python in server-mode. From the command line, run the following:
-\begin{Verbatim}
-cd proj
-rm -f proj.aux tmp/*.txt nohup.out proj.synctex.gz
-python3 -c 'from talk2stat.talk2stat import client; client("./","python","QUIT")'
-rm -f serverPIDpython.txt pythondebug.txt talk2stat.log
-\end{Verbatim}
-Then, recompile the project.\\
-\egroup
-
-
-\cause\bgroup
-Invalid, missing, or unexpected output can be due to having another runcode running on the system, but in another directory. If this happens, you will see a message in the log file saying that the server is already running. When multiple projects attempt to connect with the statistical software through the same port, only the first invocation will succeed but the subsequent ones will be connected to the first one. This will create unexpected results for all projects using the same port. Suppose your new project is B, and the runcode server of project A is still running and using the same port. In this case you may, for example,
-\begin{itemize}
-\item Accidentally overwrite variables in project A, or use the wrong ones in project B if they were also defined in A;
-\item Try to run code which is stored in project B, but you get an error message in the pdf file such as `\texttt{cannot open file 'mycode.R': No such file or directory}'. The reason for this error is that the other instance of the runcode server uses project A's base directory, and the file mycode.R is not in the right path.
-\end{itemize}
-To fix it, you can do one of the following:
-\begin{enumerate}
-\item configure each project to use another port to communicate with talk2stat (which will prevent any conflict between the projects), or,
-\item you can stop all instances of talk2stat running on the system before compiling your current project.
-\end{enumerate}
-To do the latter, find all the talk2stat processes, and find the corresponding directories. For example, suppose that multiple projects use talk2stat to communicate with Julia. From the command-line, do the following:
-\begin{Verbatim}
-cd proj
-ps -ef | grep talk2stat # get all the PIDs. E.g., 36797
-# on Mac:
-lsof -a -d cwd -p 36797
-# on Linux:
-pwdx 36797
-# lsof or pwdx will give you the directory name of the other projects which run talk2stat
-# cd to each directory, and run:
-python3 -c 'from talk2stat.talk2stat import client; client("./","julia","QUIT")'
-rm -f serverPIDjulia.txt juliadebug.txt talk2stat.log
-\end{Verbatim}
-\egroup
-
-
-\cause\bgroup
-If the correct output is in the files in tmp directory, but it's not showing in the pdf file, it can be due to the \LaTeX~ compiler's naming of temporary files. Usually, the auto-generated file names start with the main tex file name (e.g. if the main tex file is called troubleshoot.tex then runcode will create files such as \verb|troubleshoot_inln5.tex|). However, working with Overleaf we noticed that their compiler uses another convention for temporary file names. To prevent such problems, you can add the following in the preamble of the main document:
-\begin{Verbatim}
-\edef\TeXjobname{\jobname} % (this line is not really essential.)
-\edef\jobname{\detokenize{troubleshoot}}
-\end{Verbatim}
-\egroup
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-
-\prob{Working in server-mode, the server is stopped after each compilation.}
-\cause\bgroup
-If you are using the server-mode, be aware that some editors terminate all child processes at the end of \LaTeX compilation. For example, Emacs with Auctex behaves this way. For this case, use the nohup option, and the server will not be terminated by the parent process.\\
-If you want the server to be stopped after each compilation (regardless of the editor you are using), use the stopserver option. While you are compiling the tex document often, you may want to keep the server side running in order to save time during initialization, and to maintain the variables and results already in memory. However, it is a good idea to use the stopserver option when you are done, just to prevent any conflicts (see above).\\
-It's recommended to check that port numbers are unique, and when a project is not expected to be compiled for a while to enable the stopserver option.
-\egroup
-
-
-
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-
-\prob{The process seems to hang during code execution when the \LaTeX~ document is compiled.}
-\cause\bgroup
-We mentioned that code being sent to the software must be syntactically valid. In addition, keep in mind that the server waits for complete commands. So, for example, if we try\\
-\verb|The factorial of 6 is \inlnR{```cat(factorial(6)```}.|\\
-it will cause the server to hang because it awaits the closing parenthesis. Eventually, it will time out but the code cannot be executed, so the desired output will not be produced, and an error message will replace the output, as in the following example. The timeout interval is set in the config files for R, Julia, Python, and Matlab.
-\verb|The factorial of 6 is \inlnR{```cat(factorial(6)```}.|\\
-The factorial of 6 is \inlnR{```cat(factorial(6)```}.\\
-In this example the cat statement is missing a closing parenthesis.\\
-\egroup
-
-
-
-\end{document}
-
-
Modified: trunk/Master/texmf-dist/tex/latex/runcode/runcode.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/runcode/runcode.sty 2022-08-21 19:59:22 UTC (rev 64160)
+++ trunk/Master/texmf-dist/tex/latex/runcode/runcode.sty 2022-08-21 20:03:00 UTC (rev 64161)
@@ -4,7 +4,7 @@
%
% This package is based on an ongoing work by Haim Bar and HaiYing Wang, and comments and questions are welcome!
-\ProvidesPackage{runcode}[2022/08/10 runcode v1.6]
+\ProvidesPackage{runcode}[2022/08/20 runcode v1.7]
\newif\ifruncode
% Change to \runcodefalse if you want to suspend code execution
@@ -144,7 +144,8 @@
\usepackage{fvextra}
\fi
-\immediate\write18{mkdir -p tmp}
+\newcommand{\generated}{generated}
+\immediate\write18{mkdir -p \generated}
\definecolor{bg}{rgb}{0.95,0.95,0.95} % code block background color
@@ -226,8 +227,8 @@
\IfFileExists{#2}{
\stepcounter{codeOutput}
\ifthenelse{\isempty{#3}}
- { \setvalue{\tmpname}{tmp/\jobname_tmp\thecodeOutput.tex} }
- { \setvalue{\tmpname}{tmp/#3.tex} }
+ { \setvalue{\tmpname}{\generated/\jobname_tmp\thecodeOutput.tex} }
+ { \setvalue{\tmpname}{\generated/#3.tex} }
% toggle \runcode above if you want to enable/disable code execution
\ifthenelse{\isempty{#4}}
{ \ifruncode
@@ -250,8 +251,8 @@
\NewDocumentCommand{\includeOutput}{m O{vbox}}{\-
\ifthenelse{\isempty{#1}}
- {\setvalue{\tmpname}{tmp/\jobname_tmp\thecodeOutput.tex}}
- {\unskip\setvalue{\tmpname}{tmp/#1.tex}\unskip}\unskip
+ {\setvalue{\tmpname}{\generated/\jobname_tmp\thecodeOutput.tex}}
+ {\unskip\setvalue{\tmpname}{\generated/#1.tex}\unskip}\unskip
% even if the code is not executed, but we ran it before, we can use a
% cached version if it exists.
\IfFileExists{\tmpname}
@@ -288,7 +289,7 @@
\NewDocumentCommand{\inln}{m m O{inline}}{\-
\stepcounter{codeOutput}\unskip
- \unskip\setvalue{\tmpname}{tmp/\jobname_inln\thecodeOutput}\unskip\unskip\unskip
+ \unskip\setvalue{\tmpname}{\generated/\jobname_inln\thecodeOutput}\unskip\unskip\unskip
\ifruncode % cache mode - don't try to run the code, just get the previous results
\IfBeginWith{#2}{```}{\ifruncode\immediate\write18{#1 > \tmpname.tex}\unskip\fi}
{\newwrite\tempfile
@@ -362,17 +363,17 @@
\NewDocumentCommand{\runPythonBatch}{m m}{%\-\\
\stepcounter{codeOutput}
\ifthenelse{\isempty{#2}} % set the output file name
- { \setvalue{\tmpname}{tmp/\jobname_tmp\thecodeOutput.tex} }
- { \setvalue{\tmpname}{tmp/#2.tex} }
+ { \setvalue{\tmpname}{\generated/\jobname_tmp\thecodeOutput.tex} }
+ { \setvalue{\tmpname}{\generated/#2.tex} }
\IfFileExists{#1}{
\ifruncode
\newwrite\tempfile
- \immediate\openout\tempfile=tmp/\jobname_#1
+ \immediate\openout\tempfile=\generated/\jobname_#1
\immediate\write\tempfile{import dill}
\immediate\write\tempfile{from os.path import exists}
- \immediate\write\tempfile{if exists('tmp/session'):}
- \immediate\write\tempfile{ dill.load_session('tmp/session')}
+ \immediate\write\tempfile{if exists('\generated/session'):}
+ \immediate\write\tempfile{ dill.load_session('\generated/session')}
\immediate\write\tempfile{}
\newread\infile
\openin\infile=#1
@@ -383,10 +384,10 @@
\repeat
\endgroup
\closein\infile
- \immediate\write\tempfile{dill.dump_session('tmp/session')}
+ \immediate\write\tempfile{dill.dump_session('\generated/session')}
\immediate\write\tempfile{}
\immediate\closeout\tempfile
- \immediate\write18{python3 tmp/\jobname_#1 > \tmpname}
+ \immediate\write18{python3 \generated/\jobname_#1 > \tmpname}
\fi
}
{
More information about the tex-live-commits
mailing list.