diff options
| -rw-r--r-- | Master/texmf-dist/doc/latex/bashful/Makefile | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/bashful/README | 13 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/bashful/bashful.pdf | bin | 422132 -> 470434 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/bashful/bashful.tex | 402 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/bashful/bashful.sty | 464 |
5 files changed, 587 insertions, 296 deletions
diff --git a/Master/texmf-dist/doc/latex/bashful/Makefile b/Master/texmf-dist/doc/latex/bashful/Makefile index 3ea9362ec96..1cf8a1d9cb2 100644 --- a/Master/texmf-dist/doc/latex/bashful/Makefile +++ b/Master/texmf-dist/doc/latex/bashful/Makefile @@ -11,4 +11,6 @@ ${PACKAGE}.zip: ${PACKAGE}.pdf $(SOURCES) zip $@ $? clean: - rm -f [dD]elme* *.aux *.sh *.osh *.toc *~ *.log *.out *.dvi *.lsh *.stderr *.stdout *.toc *.c + rm -rf [dD]elme* *.aux *.sh *.osh *.toc *~ *.log *.out *.dvi *.lsh *.stderr \ + *.stdout *.toc *.c minimal* date bashful.date *.exitCode condition.* \ + temperature.* _00 _bashful diff --git a/Master/texmf-dist/doc/latex/bashful/README b/Master/texmf-dist/doc/latex/bashful/README new file mode 100644 index 00000000000..d3a28c02793 --- /dev/null +++ b/Master/texmf-dist/doc/latex/bashful/README @@ -0,0 +1,13 @@ +The bashful package, v 0.92 + +This package makes it possible to execute bash scripts from within LaTeX. The +main application is in writing computer-science texts, in which you want to +make sure the programs listed in the document are executed directly from the +input. + +This package may be distributed and/or modified under the LaTeX Project Public +License, version 1.3 or higher (your choice). The latest version of this +license is at: http://www.latex-project.org/lppl.txt + +This work is author-maintained (as per LPPL maintenance status) +by Yossi Gil, <yogi@cs.Technion.ac.i> diff --git a/Master/texmf-dist/doc/latex/bashful/bashful.pdf b/Master/texmf-dist/doc/latex/bashful/bashful.pdf Binary files differindex 43a9f56fa5c..b8cd348bc61 100644 --- a/Master/texmf-dist/doc/latex/bashful/bashful.pdf +++ b/Master/texmf-dist/doc/latex/bashful/bashful.pdf diff --git a/Master/texmf-dist/doc/latex/bashful/bashful.tex b/Master/texmf-dist/doc/latex/bashful/bashful.tex index 5b853991152..c2247d1266f 100644 --- a/Master/texmf-dist/doc/latex/bashful/bashful.tex +++ b/Master/texmf-dist/doc/latex/bashful/bashful.tex @@ -1,5 +1,5 @@ \documentclass{ltxdoc} % Process with xelatex -shell-escape -\usepackage{bashful} +\usepackage[verbose]{bashful} \usepackage[colorlinks=true]{hyperref} \usepackage{gensymb} @@ -8,7 +8,7 @@ \usepackage{xkvview} \usepackage{xspace} \usepackage{amsmath} - +\usepackage{multicol} \newcommand\me{bashful} \newcommand\bashful{\textsf{\me}\xspace} @@ -19,8 +19,11 @@ belowskip=0pt}% \title{The \bashful Package\thanks{ + Copyright \copyright{} 2011 by Yossi Gil + \url{mailto:yogi@cs.technion.ac.il}. This work may be distributed and/or modified under the conditions of the - \emph{GNU GENERAL PUBLIC LICENSE}{http://www.gnu.org/licenses/gpl.html}. + \emph{\LaTeX{} Project Public License} (LPPL), either version 1.3 of this + license or (at your option) any later version. The latest version of this license is in \url{http://www.latex-project.org/lppl.txt} and version 1.3 or later is part of all distributions of \LaTeX{} version 2005/12/01 or later. @@ -43,9 +46,10 @@ This work consists of the files \texttt{\me.tex} and \texttt{\me.sty} \makeatother \begin{document} + \bash cat << EOF > README -The bashful package, v 0.91 +The bashful package, v 0.92 This package makes it possible to execute bash scripts from within LaTeX. The main application is in writing computer-science texts, in which you want to @@ -61,50 +65,53 @@ by Yossi Gil, <yogi@cs.Technion.ac.i> EOF \END +\bash[verbose,stdoutFile=bashful.date] +stat -c %y bashful.sty | sed -e s+-+/+g -e 's/ .*//g' > date +\END + \maketitle + \begin{abstract} \parindent 1.5ex \parskip 0.5em \sl It is sometimes useful to ``\emph{escape-to-shell}'' from within - \LaTeX{}. + \LaTeX{}. The most obvious application is when the document - explains something about the working of a computer program. + explains something about the working of a computer program. Your text would be more robust to changes, and easier to write, - if all the examples it gives, are run directly from - within \LaTeX{}. - + if all the examples it gives, are run directly from + within \LaTeX{}. + To facilitate this and other applications, package \bashful{} provides a convenient interface to \TeX's - primitive \verb+\write18+---the execution of shell commands from within - your input files, also known as \emph{shell escape}. + primitive \verb+\write18+---the execution of shell commands from within + your input files, also known as \emph{shell escape}. Text between \verb+\bash+ and \verb+\END+ is executed by - the \href - {http://en.wikipedia.org/wiki/Bash_%28Unix_shell%29} - {\texttt{bash}}, - a popular Unix command line interpreter. + \href + {http://en.wikipedia.org/wiki/Bash_%28Unix_shell%29} + {\texttt{bash}}, + a popular Unix command line interpreter. Various flags control whether the executed commands and their output - show up in the printed document, and whether they are saved - to files. + show up in the printed document, and whether they are saved + to files. Although provisions are made for using shells other - than \texttt{bash}, this package may \emph{not} operate without - modifications on Microsoft's operating systems. + than \texttt{bash}, this package may \emph{not} operate without + modifications on Microsoft's operating systems. \end{abstract} -\eject +\begin{multicols}{2} +\footnotesize \tableofcontents +\end{multicols} \parindent 1.5ex \parskip 0.5em \section{Introduction} -\bash[verbose] -rm -f temperature.tex -rm -f condition.tex -\END \bash[verbose,scriptFile=temperature.sh,stdoutFile=temperature.tex] location=Jerusalem,Israel @@ -129,28 +136,31 @@ tr 'A-Z' 'a-z' \END At the time I run this document through \LaTeX{}, - the temperature in Jerusalem, Israel, - was~\emph{\input{temperature.tex}\celsius}, - while the weather condition was \emph{\input{condition}}\unskip. - + the temperature in Jerusalem, Israel, + was~\emph{\input{temperature}\unskip\celsius}, + while the weather condition was + \emph{\input{condition}}\unskip. + You may not care so much about these bits of truly ephemeral information, - but you may be surprised that they were produced - by the very process of \LaTeX{}ing. + but you may be surprised that they were produced + by the very process of \LaTeX{}ing the input. How did I do that? Well, the first step was to write - a series of shell commands that retrieve the current temperature, - and another such series to obtain the current - weather conditions. + a series of shell commands that retrieve the current temperature, + and another such series to obtain the current + weather conditions. This task required connection to -\href{http://www.Google.com/support/forum/p/apps-apis/thread?tid=0c95e45bd80def1a&hl=en}% -{Google's weather service} and - minimal dexterity with Unix pipes and filters to process the output. + \href{http://www.Google.com/support/forum/p/% + apps-apis/thread?tid=0c95e45bd80def1a&hl=en}% + {Google's weather service} and + minimal dexterity with Unix pipes and filters to process the output. + My command series to obtain the current temperature was: \begin{minipage}{\textwidth} \begin{quote} - \lstinputlisting[style=input]{temperature.sh} + \lstinputlisting[style=input]{temperature.sh} \end{quote} \end{minipage} @@ -158,57 +168,61 @@ while the weather condition was obtained by \begin{minipage}{\textwidth} \begin{quote} - \lstinputlisting[style=input]{condition.sh} + \lstinputlisting[style=input]{condition.sh} \end{quote} \end{minipage} The second step was coercing \LaTeX{} to run these commands - while processing this file. -To do that, I wrapped these two series within - a \verb+\bash+\ldots\verb+\END+ pair. + while processing my document. +To do that, I used package \bashful, +\begin{verbatim} +\usepackage{bashful} +\end{verbatim} +And, then, I wrapped each of these two series within + a \verb+\bash+\ldots\verb+\END+ pair. + The \verb+\bash+ command, offered by this package, - takes all subsequent lines, stopping at the closing \verb+\END+, - places these in a file, and then - lets the \texttt{bash} shell interpreter execute this file. + takes all subsequent lines, stopping at the closing \verb+\END+, + places these in a file, and then + lets the \texttt{bash} shell interpreter execute this file. Allowing \LaTeX{} to run arbitrary shell commands can be - dangerous---you never know whether that nice looking \texttt{tex} - file you received by email was prepared by a friend or - a foe. + dangerous---you never know whether that nice looking \texttt{.tex} + file you received by email was prepared by a friend or + a foe. This is the reason that you have to tell \LaTeX{} - explicitly that shell escapes - are allowed. -The \texttt{-shell-esc} does that. -Processing this file was thus done by executing, at the command line, + explicitly that shell escapes + are allowed. +The \texttt{-shell-esc} flag does that. +To process my document, I typed, at the command line, \begin{quote} - \tt - \% latex -shell-escape \jobname.tex + \tt + \% latex -shell-escape \jobname.tex \end{quote} -What I actually wrote in my \texttt{.tex} file +What I actually wrote in the input to produce the temperature in - Jerusalem, Israel was: - + Jerusalem, Israel was: + \begin{minipage}{\textwidth} \begin{quote} \noindent\verb+\bash[verbose,scriptFile=temperature.sh,stdoutFile=temperature.tex]+ -\lstinputlisting[style=input]{temperature.sh} +\lstinputlisting[style=input,belowskip=0pt]{temperature.sh} \verb+\END+\\ \end{quote} \end{minipage} -The flags passed to above to the \verb+bash+ control sequence instructed it: - \begin{enumerate} - \item to be verbose, typing out a detailed log of everything it did; - \item to save the shell commands in a script file named - \texttt{temperature.sh}; and, - \item to store the standard output of the script in a file named - \texttt{temperature.tex}. - \end{enumerate} +The flags passed to the \verb+bash+ control sequence above instructed it: + \begin{enumerate} + \item to be verbose, typing out a detailed log of everything it did; + \item to save the shell commands in a script file named + \texttt{temperature.sh}; and, + \item to store the standard output of the script in a file named + \texttt{temperature.tex}. + \end{enumerate} To obtain the current weather condition in the capital I wrote: - \begin{minipage}{\textwidth} \begin{quote} \noindent\verb+\bash[verbose,scriptFile=condition.sh,stdoutFile=condition.tex]+ @@ -219,18 +233,17 @@ To obtain the current weather condition in the capital I wrote: I wrote these two just after my \verb+\begin{document}+. When \LaTeX{} encountered these, it executed the bash commands and - created two files \texttt{temperature.tex} and \texttt{condition.tex}. + created two files \texttt{temperature.tex} and \texttt{condition.tex}. Subsequently, I could use the content of these files by writing: \begin{quote} -\begin{verbatim} -At the time I run this document through \LaTeX{}, - the temperature in Jerusalem, Israel, - was~\emph{\input{temperature.tex}\celsius}, - while the weather condition was \emph{\input{condition}}\unskip. -\end{verbatim} +\bash +sed -n "/^At the time/,/^You may not/ p" bashful.tex > init.tex +\END + +\lstinputlisting[style=input,belowskip=0pt]{init.tex}\ldots \end{quote} \section{An Easy to Digest Example} @@ -256,8 +269,8 @@ Let's first write a simple \href{http://en.wikipedia.org/wiki/C_(programming_language)} {C programming language}: -\begin{quote} -\bash[verbose,list] + +\bash[verbose,environment=quote,script] rm -f hello.c; cat << EOF > hello.c /* ** hello.c: My first C program; it prints @@ -273,33 +286,31 @@ int main() } EOF \END -\end{quote} \subsubsection{Compiling} Now, let's compile this program: -\begin{quote} -\bash[list,stdout] +\bash[environment=quote,script,stdout] cc hello.c \END -\end{quote} \subsubsection{Executing} Finally, we can execute this program, and see that indeed, it prints the ``Hello, World!'' string. -\begin{quote} -\bash[list,stdout] +\bash[environment=quote,script,stdout] ./a.out \END -\end{quote} + \subsection{Behind the Scenes} \subsubsection{Authoring} What I wrote in the input to produce the \texttt{hello.c} program was: + +\begin{minipage}{\textwidth} \begin{quote} \begin{verbatim} -\bash[list] +\bash[script] rm -f hello.c; cat << EOF > hello.c /* ** hello.c: My first C program; it prints @@ -317,12 +328,12 @@ EOF \END \end{verbatim} \end{quote} +\end{minipage} In doing so, all the text between the \verb+\bash+ and \verb+\END+ was sent to a temporary file, - which was then sent to the \texttt{bash} - bash shell for execution. -The \texttt{list} flag instructed \verb+\bash+ + which was then sent for execution. +The \texttt{script} flag instructed \verb+\bash+ to list this file in the main document. This listing was prefixed with \verb*+% + to make it clear that it was input to \texttt{bash}. @@ -331,7 +342,7 @@ This listing was prefixed with \verb*+% + Next, I wrote \begin{quote} \begin{verbatim} -\bash[list] +\bash[script,stdout] cc hello.c \END \end{verbatim} @@ -341,13 +352,14 @@ As before, in doing that, I achieved two objectives: first, when \LaTeX{} processed the input, it also invokes the~C compiler to compile file \texttt{hello.c}, the file which I just created. -Second, thanks to the \texttt{list} flag, + +Second, thanks to the \texttt{script} flag, the command for compiling this program was included in the printed version of this document. -Thanks to the \texttt{stdout} option, - plain messages, i.e., not error messages, - produced by the compiler would show on +The \texttt{stdout} option instructed \verb+\bash+ + to include plain messages, i.e., not error messages, + produced by the compiler in the printed version of this document. In this case, no such messages were produced. @@ -357,7 +369,7 @@ In this case, no such messages were produced. Finally, I wrote \begin{quote} \begin{verbatim} -\bash[list,stdout] +\bash[script,stdout] ./a.out \END \end{verbatim} @@ -385,15 +397,20 @@ More specifically, the \verb+\bash+ command \begin{enumerate} \item collects all commands up to \verb+\END+; \item places these commands in a script file; +\item change directory to a designated directory if the \texttt{hide} + option is set (the \texttt{dir} option sets the directory name); \item executes this script file, redirecting its standard output and its standard error streams to distinct files; \item checks whether the exit code of the execution indicates an error (i.e., exit code which is different from~$0$), and if so, - appends this exit code to the file containing the standard error; + place this exit code in a distinct file; \item checks whether the file containing the standard error is empty, and if not, pauses execution after displaying an error message; -\item lists, if requested to, the script file; and, -\item lists, if requested to, the file containing the standard output. +\item checks whether the file containing the exit code is empty, + and if not, pauses execution after displaying an error message; +\item lists, if requested to, the script file; +\item lists, if requested to, the file containing the standard output; and, +\item lists, if requested to, the file containing the standard error; \end{enumerate} Let me demonstrate a situation in which the execution of @@ -404,22 +421,23 @@ Since \texttt{minimal.tex} contains \verb+\END+, I will have to author this file in three steps: \begin{enumerate} \item Creating the header of \texttt{minimal.tex}: -\bash[list] +\bash[script] cat << EOF > minimal.tex -\documentclass{minimal} +\documentclass{standalone} \usepackage{bashful} \begin{document} -\bash -echo "main(){return int;}" > error.c -cc error.c +This document creates a simple erroneous C program + and then compiles it: +\bash[script,stdout] +echo "main(){return int;}" > error.c; cc error.c EOF \END \item Adding \verb+\END+ to \texttt{minimal.tex} -\bash[list] +\bash[script] echo "\\END" >> minimal.tex \END \item Finalizing \texttt{minimal.tex} -\bash[list] +\bash[script] echo "\\end{document}" >> minimal.tex \END \end{enumerate} @@ -427,7 +445,7 @@ echo "\\end{document}" >> minimal.tex Let me now make sure \texttt{minimal.tex} was what I expect it to be: \begin{minipage}{\textwidth} -\bash[list,stdout] +\bash[script,stdout] cat minimal.tex \END \end{minipage} @@ -438,12 +456,12 @@ I am now ready to run \texttt{minimal.tex} through \LaTeX{}, when the anticipated error occurs. \begin{minipage}{\textwidth} - \lstdefinestyle{bashfulStdoutFile}{ + \lstdefinestyle{bashfulStdout}{ showstringspaces=false, - basicstyle=\scriptsize\ttfamily, + basicstyle=\small\ttfamily, }% -\bash[list,stdout] -yes x | latex -shell-esc minimal.tex +\bash[script,stdout] +yes q | pdflatex -shell-esc minimal.tex | fmt -s -w 55 \END \end{minipage} @@ -455,16 +473,23 @@ You can see that when \LaTeX{} tried to process \texttt{minimal.tex}, Inspecting \texttt{minimal.stderr}, we see the C compiler error messages: \begin{minipage}{\textwidth} -\bash[list,stdout] +\bash[script,stdout] cat minimal.stderr \END \end{minipage} + +Note that the failure to compile \texttt{hello.c}, + did not stop \verb+\bash+ from including + this file in the source. -\section{Customization} +Here is what \texttt{minimal.pdf} looks like: -\subsection{Options} +\begin{center} + \includegraphics[scale=0.9]{minimal.pdf} +\end{center} -Options to \verb+\bash+ are passed using the \textsf{xkeyval} syntax: + +\section{Customization} \newcommand\option[3]{% \noindent\( @@ -473,8 +498,36 @@ Options to \verb+\bash+ are passed using the \textsf{xkeyval} syntax: \langle\text{{#2}}\rangle \) \hfill\texttt{#3}\\} +\subsection{Package Options} +Options to the \verb+\bashful+ package passed using the \textsf{xkeyval} syntax: + +\option{hide}{\texttt{true}/\texttt{false}}{\texttt{false}} +If \texttt{true}, scripts are + executed in a designated directory; + if \texttt{false}, scrips are executed + in the current working directory. + +\option{dir}{\sl directoryName}{} +If \texttt{hide} option is \texttt{true}, then + scripts are executed in this directory. +Initial value of this options is \verb+_00+. +Note that if you use \TeX{}live 2010, you have to configure certain + security flags to make it possible to write to directories + whose name start with a dot, or to directories + which are not below the current working directory. + +\option{verbose}{\texttt{true}/\texttt{false}}{\texttt{false}} +If \texttt{true}, be chatty. + +\subsection{Command Options} + +Options to \verb+\bash+ command + are passed using the \textsf{xkeyval} syntax: + + +\subsubsection{File names} \option{scriptFile}{\sl fileName}{\textbackslash jobname.sh} Name of file into which the script instructions are spilled prior to execution. @@ -491,22 +544,55 @@ Name of file into which the shell standard output stream is \option{stderrFile}{\sl fileName}{\textbackslash jobname.stderr} Name of file into which the shell standard error stream is redirected. + +\option{exitCodeFile}{\sl fileName}{\textbackslash jobname.stderr} +Name of file into which the shell standard error stream is + redirected. -\option{list}{\texttt{true}/\texttt{false}}{\texttt{false}} +\subsubsection{Listing Structure} +\option{script}{\texttt{true}/\texttt{false}}{\texttt{false}} If \texttt{true}, the content of \texttt{scriptFile} is listed in the main document. \option{stdout}{\texttt{true}/\texttt{false}}{\texttt{false}} If \texttt{true}, the content of \texttt{stdoutFile} is listed in the main document. -If both \texttt{list} and \texttt{stdout} are +If both \texttt{script} and \texttt{stdout} are \texttt{true}, then \texttt{scriptFile} is listed first, and leaving no vertical space, \texttt{stdoutFile} is listed next. +\option{stderr}{\texttt{true}/\texttt{false}}{\texttt{false}} +If \texttt{true}, the content of \texttt{stderrFile} + is listed in the main document, following + \texttt{scriptFile} (if \texttt{script} is + \texttt{true}) + and + \texttt{stdoutFile} (if \texttt{stdout} is + \texttt{true}). + +\subsubsection{Tolerance to Errors} +\option{ignoreExitCode}{\texttt{true}/\texttt{false}}{\texttt{false}} +When + \texttt{true} \verb+\bash+ will consider + an execution correct even if its exit code + is not 0. + +\option{ignoreStderr}{\texttt{true}/\texttt{false}}{\texttt{false}} + When \texttt{true} \verb+\bash+ will consider + an execution correct even if produces + output to the standard error stream. + +\subsubsection{Appearance} + \option{prefix}{tokens}{\percentchar\textvisiblespace} String that prefixes the listing of \texttt{scriptFile}. +\option{environment}{enrionmentName}{none} +Name of \LaTeX{} environment (e.g., \texttt{quote}) + in which the listing is wrapped. + +\subsubsection{Miscellaneous} \option{verbose}{\texttt{true}/\texttt{false}}{\texttt{false}} If \texttt{true}, the package logs every step it takes. @@ -519,13 +605,16 @@ Package commands and their output. \subsubsection{Listings Style for Script File} -Style \verb+bashfulList+ is used for displaying the executed shell - commands (when option \texttt{list} is used). +Style \verb+bashfulScript+ is used for displaying the executed shell + commands (when option \texttt{script} is used). The current definition of this style is: \begin{verbatim} -\lstdefinestyle{bashfulList}{ + \lstdefinestyle{bashfulScript}{ basicstyle=\ttfamily, + keywords={}, showstringspaces=false} + + \end{verbatim} Redefine this style to match your needs. @@ -536,8 +625,24 @@ Style \verb+bashfulStdout+ is used for displaying the output of the commands (when option \texttt{stdout} is used). The current definition is: \begin{verbatim} + % listings style for the stdoutFile, can be redefined by client \lstdefinestyle{bashfulStdout}{ basicstyle=\sl\ttfamily, + keywords={}, + showstringspaces=false + }% + +\end{verbatim} +Redefine this style to match your needs. + + +Style \verb+bashfulStderr+ is used for displaying the output of the + executed shell + commands (when option \texttt{stderr} is used). +\begin{verbatim} + \lstdefinestyle{bashfulStderr}{ + basicstyle=\sl\ttfamily\color{red}, + keywords={}, showstringspaces=false } \end{verbatim} @@ -553,7 +658,18 @@ Also, in case bidirectional \TeX{}ing is in effect, \section{History} \begin{description} -\item[Version 0.91] Initial release +\item[Version 0.91] Initial release. +\item[Version 0.92] +\begin{itemize} + \item Added \texttt{ignoreExitCode}, + \texttt{ignoreStderr}, \texttt{stderr}, + \texttt{exitCodeFile} command options. + + \item + Renamed \texttt{list} to \texttt{script}. + \item + Added \texttt{hide} and \texttt{dir} package options. + \end{itemize} \end{description} \section{Future} @@ -571,16 +687,6 @@ The following may get implemented some day. will make this package safer, by reducing the risk of accidentally erasing existing files. - -\item \emph{A \texttt{ignoreExitCode} option.} When - \texttt{true} \verb+\bash+ will consider - an execution correct even if its exit code - is not 0. - -\item \emph{A \texttt{ignoreStderr} option.} When - \texttt{true} \verb+\bash+ will consider - an execution correct even if produces - output to the standard error stream. \end{enumerate} \section{Acknowledgments} @@ -594,24 +700,26 @@ Martin Scharrer tips on \TeX{} internals \appendix \section{Source of \texttt{\jobname.sty}} - \lstinputlisting - [ style=input, - basicstyle=\scriptsize\ttfamily, - numbers=left, - stepnumber=10, - numberstyle=\scriptsize\rmfamily\bfseries - ] - {\jobname.sty} - -\section{Source of the Current Document} - \lstinputlisting - [ style=input, - basicstyle=\scriptsize\ttfamily, - numbers=left, - stepnumber=10, - numberstyle=\scriptsize\rmfamily\bfseries - ] - {\jobname.tex} - - + \lstinputlisting + [ style=input, + basicstyle=\scriptsize\ttfamily, + numbers=left, + stepnumber=10, + firstnumber=1, + numberfirstline=true, + numberstyle=\scriptsize\rmfamily\bfseries + ] + {\jobname.sty} + +\section{Source of \texttt{\jobname.tex}} + \lstinputlisting + [ style=input, + basicstyle=\scriptsize\ttfamily, + numbers=left, + stepnumber=10, + firstnumber=1, + numberfirstline=true, + numberstyle=\scriptsize\rmfamily\bfseries + ] + {\jobname.tex} \end{document} diff --git a/Master/texmf-dist/tex/latex/bashful/bashful.sty b/Master/texmf-dist/tex/latex/bashful/bashful.sty index 326b999158f..fab73a2de26 100644 --- a/Master/texmf-dist/tex/latex/bashful/bashful.sty +++ b/Master/texmf-dist/tex/latex/bashful/bashful.sty @@ -16,15 +16,15 @@ \NeedsTeXFormat{LaTeX2e}% % Auxiliary identification information -\newcommand\date@bashful{2011/02/28}% -\newcommand\version@bashful{V 0.91}% +\newcommand\date@bashful{2011/03/12}% +\newcommand\version@bashful{V 0.92}% \newcommand\author@bashful{Yossi Gil}% \newcommand\mail@bashful{yogi@cs.technion.ac.il}% \newcommand\signature@bashful{% bashful \version@bashful{} by \author@bashful{} \mail@bashful }% - + % Identify this package \ProvidesPackage{bashful}[\date@bashful{} \signature@bashful: Write and execute a bash script within LaTeX, with, or @@ -32,37 +32,101 @@ ] \PackageInfo{bashful}{This is bashful, \signature@bashful}% +\RequirePackage{catchfile} +% Use xkeyval for retrieving parameters +\RequirePackage{xkeyval}% + +% If true, all activities take place in a designated directory. +\newif\if@hide@BL@\@hide@BL@false + +% This is the default name for a directory in which processing should +% take place if \@hide@BL@true. +\def\directory@BL{_00} + % Use listing to display bash scripts. \RequirePackage{listings}% + % listings style for the script, can be redefined by client - \lstdefinestyle{bashfulList}{ + \lstdefinestyle{bashfulScript}{ basicstyle=\ttfamily, + keywords={}, showstringspaces=false}% % listings style for the stdoutFile, can be redefined by client \lstdefinestyle{bashfulStdout}{ basicstyle=\sl\ttfamily, + keywords={}, + showstringspaces=false + }% + % listings style for the stderrFile, can be redefined by client + \lstdefinestyle{bashfulStderr}{ + basicstyle=\sl\ttfamily\color{red}, + keywords={}, showstringspaces=false }% -% Use xkeyval for retrieving parameters -\RequirePackage{xkeyval}% - %%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % Keys in alphabetical order: - %%%%%%%%%%%%%%%%%%%%%%%%%%%%% + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + % File Name keys in alphabetical order: + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + % scriptFile: String = \BL@exitCodeFile: Where should the exit code be stored + % if it is not zero. + \edef\BL@exitCodeFile{\jobname.exitCode}% + \define@cmdkey{bashful}[BL@]{exitCodeFile}{}% + + % scriptFile: String = \BL@scriptFile: Where should the script be saved? + \edef\BL@scriptFile{\jobname.sh}% + \define@cmdkey{bashful}[BL@]{scriptFile}{}% + + % stderrFile: String = \BL@stderrFile: Where should the standard error + % sream be saved? + \edef\BL@stderrFile{\jobname.stderr}% + \define@cmdkey{bashful}[BL@]{stderrFile}{}% + + % stdoutFile: String = \BL@stdoutFile: Where should the standard output stream + % be saved? + \edef\BL@stdoutFile{\jobname.stdout}% + \define@cmdkey{bashful}[BL@]{stdoutFile}{}% + + % dir: String = \directory@BL: name of directory in which execution is going to take + % place + \define@cmdkey{bashful}[BL@]{dir}{\def\directory@BL{#1}}% + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + % List configuration boolean keys + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + % list: Boolean = \ifBL@script: Should we list the script we generate? + \define@boolkey{bashful}[BL@]{script}[true]{}% + + % stdout: Boolean = \ifBL@stderr: Should we list the standard error? + \define@boolkey{bashful}[BL@]{stderr}[true]{}% + + % stdout: Boolean = \ifBL@stdout: Should we list the standard output? + \define@boolkey{bashful}[BL@]{stdout}[true]{} + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + % Error checking Boolean keys. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + % stdout: Boolean = \ifBL@ignoreExitCode: Should we ignore the exit + % code? + \define@boolkey{bashful}[BL@]{ignoreExitCode}[true]{} + + % stdout: Boolean = \ifBL@ignoreStderr: Should we ignore the exit + % code? + \define@boolkey{bashful}[BL@]{ignoreStderr}[true]{} + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + % Miscelaneous keys + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - % environment: String = \BL@environment: Which environment should we wrap the listings + % environment: String = \BL@environment: Which environment should we wrap + % the listings \def\BL@environment{none@BL}% \define@cmdkey{bashful}[BL@]{environment}{}% \newenvironment{none@BL}{}{} % Default, empty environment for wrapping the listings - % scriptFile: String = Where should the listed script be saved? - \def\BL@scriptFile{\jobname.lsh}% - \define@cmdkey{bashful}[BL@]{scriptFile}{}% - - % list: Boolean = \ifBL@list: Should we list the script we generate? - \define@boolkey{bashful}[BL@]{list}[true]{}% - % prefix: String = \BL@prefix: What prefix should be printed before a listing. \def\BL@prefix{\@percentchar\space}% \define@cmdkey{bashful}[BL@]{prefix}{}% @@ -70,58 +134,47 @@ % shell: String = \BL@shell: Which shell should be used for execution? \def\BL@shell{bash}% \define@cmdkey{bashful}[BL@]{shell}{}% - - % scriptFile: String = \BL@scriptFile: Where should the script be saved? - \def\BL@scriptFile{\jobname.sh}% - \define@cmdkey{bashful}[BL@]{scriptFile}{}% - % stderrFile: String = \BL@stderrFile: Where should the standard error be saved? - \def\BL@stderrFile{\jobname.stderr}% - \define@cmdkey{bashful}[BL@]{stderrFile}{}% + % verbose: Boolean = \ifBL@verbose: Log every step we do + \define@boolkey{bashful}[BL@]{verbose}[true]{}% - % stdout: Boolean = \ifBL@stdout: Should we list the standard output? - \define@boolkey{bashful}[BL@]{stdout}[true]{}% - - % stdoutFile: String = \BL@stdoutFile: Where should the standard output be saved? - \def\BL@stdoutFile{\jobname.stdout}% - \define@cmdkey{bashful}[BL@]{stdoutFile}{}% - % verbose: Boolean = \ifBL@verbose: Log every step we do - \define@boolkey{bashful}[BL@]{verbose}[true]{}% +\DeclareOptionX{hide}{\@hide@BL@true} +\DeclareOptionX{dir}{\@hide@BL@true\def\directory@BL{#1}} +\DeclareOptionX{verbose}{\BL@verbosetrue} +\ExecuteOptionsX{} +\ProcessOptionsX\relax % \bash: the main command we define. It chains to \bashI which chains to % \bashII, etc. \begingroup + %\where@BL \catcode`\^^M\active% \gdef\bash{% - \log@BL{Beginning a group so that all cat code changes are local}% + \logBL{Beginning a group so that all cat code changes are local}% \begingroup% - \log@BL{Making \^\^M a true newline}% + \logBL{Making \^\^M a true newline}% \catcode`\^^M\active% \def^^M{^^J}% - \log@BL{Checking for optional arguments}% + \logBL{Checking for optional arguments}% \@ifnextchar[\bashI{\bashI[]}% }% \endgroup % \bashI: Process the optional arguments and continue -\def\bashI[#1]{% - \setKeys@BL{#1}% - \bashII% And, continue processing. -}% +\def\bashI[#1]{\setKeys@BL{#1}\bashII} -% \bashII: Set category codes of all to special, and proceed. +% \bashII: Set category codes of all characters to special, and proceed. \begingroup \catcode`\^^M\active% \gdef\bashII{% - \log@BL{bashII: Making ^^M a true new line}% + \logBL{bashII: Making \^\^M a true new line}% \catcode`\^^M\active% \def^^M{^^J}% - \log@BL{bashII: Making all characters other}% + \logBL{bashII: Making all characters other}% \let\do\@makeother% \dospecials% - \bashIII% - }% + \bashIII}% \endgroup % \bashIII: Consume all tokens until \END (but ignoring the preceding and @@ -130,23 +183,61 @@ \catcode`\@=0\relax \catcode`\^^M\active @catcode`@\=12@relax% - @gdef@bashIII^^M#1^^M\END{@bashIV{#1}}@relax% -@endgroup + @gdef@bashIII^^M#1^^M\END{@bashIV{#1}@bashV{#1}@logBL{bashV: Done!}@endgroup}@endgroup +% -% \bashIV: Process the tokens by storing them in a script file, executing this -% file, listing it if required, and presenting the standard output if required. +\newcommand\logBL[1]{\ifBL@verbose\typeout{L\the\inputlineno: #1}\fi} + +% \bashIV: Process the tokens by storing them in a script file, and executing +% this file, \newcommand\bashIV[1]{% - \generateScriptFile@BL{#1}\relax + \logBL{BashIV: begin}% + \makeDirectory@BL + \generateScriptFile@BL{#1}\relax \executeScriptFile@BL - \checkStderr@BL - \listScript@BL{#1}\relax% - \listStdout@BL - \log@BL{Ending group so that all cat codes changes disappear}\relax% - \endgroup + \logBL{BashIV: done}% }% +\def\makeDirectory@BL{% + \if@hide@BL@ + \logBL{Making directory \directory@BL}% + \immediate\write18{mkdir -p \directory@BL}% + \else + \logBL{Using current directory}% + \fi +} + +\newcommand\splice[1]{% + \bashIV{#1}% + \expandFileName@BL{\BL@stdoutFile}% + \CatchFileDef{\BL@file@contents}{\BL@stdoutFile}{\relax}% + \ignorespaces\BL@file@contents\unskip +} + +% listing the script file if required, and presenting the standard output and +% standar error if required. +\newcommand\bashV[1]{% + \logBL{Wrapping up after execution}% + \storeToFile@BL{\BL@prefix#1}{\BL@scriptFile}% + \expandFileName@BL\BL@scriptFile + \expandFileName@BL\BL@stdoutFile + \expandFileName@BL\BL@stderrFile + \logBL{Files are: \BL@scriptFile, \BL@stdoutFile, and \BL@stderrFile}% + %\checkScriptErrors@BL + \listEverything@BL + \logBL{Wrap up done}} + +\def\expandFileName@BL#1{% + \logBL{expandFileName}% + \logBL{Setting, if necessary, correct path of \noexpand#1 }% + \if@hide@BL@ + \logBL{Prepending path (\directory@BL) to #1}% + \edef#1{\directory@BL/#1}% + \logBL{Obtained #1}% + \fi +} \def\setKeys@BL#1{% - \log@BL{Processing key=val pairs in options string [#1]}\relax + \logBL{Processing key=val pairs in options string [#1]}\relax \setkeys{bashful}{#1}% }% @@ -157,153 +248,230 @@ \newwrite\writer@BL % Store the list of tokens in the first argument into the file given -% in the second argument -\newcommand\storeToFile@BL[2]{% - \log@BL{Creating file #2 :=^^J#1^^J}% - \immediate\openout\writer@BL#2 +% in the second argument; prepend directory if necessary +\newcommand\storeToFile@BL[2]{% + \logBL{ #2 :=^^J#1^^J}% + \if@hide@BL@ + \logBL{File #2 will be created in \directory@BL}% + \storeToFileI@BL{#1}{\directory@BL/#2} + \else + \logBL{File #2 will be created in current directory}% + \storeToFileI@BL{#1}{#2}% + \fi + \logBL{Writing done!}% +}% + +% Store the list of tokens in the first argument into the file given +% in the second argument; the second argument could be qualified with +% a directory name. +\newcommand\storeToFileI@BL[2]{% + \logBL{Writing to file #2...}% + \immediate\openout\writer@BL#2% \immediate\write\writer@BL{#1}% \immediate\closeout\writer@BL }% % Execute the content of our script file. \newcommand\executeScriptFile@BL{% - \def\command@BL{\BL@shell\space\BL@scriptFile}% - \edef\command@BL{% - \BL@shell\space -c - "\command@BL \space > \BL@stdoutFile \space2> \BL@stderrFile \space - || echo '\command@BL' exit code was $? 2>>\BL@stderrFile"% - }% - \log@BL{Executing:^^J \command@BL}% - \immediate\write18{\command@BL}% + \edef\command@BL{\BL@shell \space \BL@scriptFile}% + \if@hide@BL@ + \logBL{Adding a "cd command"}% + \edef\command@BL{cd \directory@BL;\command@BL} + \fi% + \edef\command@BL{\command@BL \space >\BL@stdoutFile \space 2>\BL@stderrFile}% + \edef\command@BL{\command@BL \space || echo $? >\BL@exitCodeFile}% + \edef\command@BL{\BL@shell\space -c "\command@BL"}% + \logBL{Executing:^^J \command@BL}% + \immediate\write18{\command@BL}% }% \newread\reader@BL -% Issue an error if stderr is not empty -\newcommand\checkStderr@BL{% - \log@BL{Examining \BL@stderrFile}% + +% Issue an error message if errors found during execution +\newcommand\checkScriptErrors@BL{% + \logBL{Checking for script errors}% \begingroup \newif\ifErrorsFound@\ErrorsFound@false - \log@BL{Opening \BL@stderrFile}% + \checkExitCodeFile@BL + \ifdefined\exitCode@BL + \logBL{Non zero exit code found (\exitCode@BL), and I was not instructed to ignore it} + \ErrorsFound@true + \fi + \def\eoln{\par} + \def\firstErrorLine{\par} + \checkStderrFile@BL + \logBL{I will print content of \BL@stderrFile\space (if found)} + \ifx\firstErrorLine\eoln + \relax + \else + \logBL{Standard error was not empty, and I was not instructed to ignore it} + \message{Standard error not empty. Here is how + ^^Jfile \BL@stderrFile\space begins: + ^^J>>>>\space + ^^Jbut, you really ought to examine this file yourself!} + \ErrorsFound@true + \fi + \ifErrorsFound@ + \logBL{Issuing an error message since \BL@stderrFile\space was not empty}% + \errmessage{Your shell script failed....} + \else + \logBL{Proceeding as usual}% + \fi + \endgroup +}% + +\newcommand\checkExitCodeFile@BL{% + \ifBL@ignoreExitCode + \logBL{Ignoring \BL@exitCodeFile, as per command flag}% + \else + \logBL{Opening \BL@exitCodeFile}% + \openin\reader@BL=\BL@exitCodeFile + \ifeof\reader@BL + \logBL{File \BL@exitCodeFile\space missing, exit code was probably 0} + \else + \logBL{File \BL@exitCodeFile\space exists, let's get the exit code}% + \logBL{Reading first line of \BL@exitCodeFile}% + \catcode`\^^M=5 + \read\reader@BL to \exitCode@BL + \closein\reader@BL + \fi + \fi +} + +\newcommand\checkStderrFile@BL{% + \ifBL@stderr + \logBL{Will be listing \BL@stderrFile, so erroneous content is ignored}% + \else + \ifBL@ignoreStderr + \logBL{Ignoring \BL@stderrFile, as per command flag}% + \else + \checkStderrFileI@BL + \fi + \fi +} + +\newcommand\checkStderrFileI@BL{% + \logBL{Opening \BL@stderrFile}% \openin\reader@BL=\BL@stderrFile\relax \ifeof\reader@BL \BL@verbosetrue - \log@BL{Strange... \BL@stderrFile{} does not exist (probably bashful bug)}% - \log@BL{Switching to verbose mode}% + \logBL{Hmm... \BL@stderrFile\space does not exist (probably a package bug)}% + \logBL{Switching to verbose mode}% \else - \log@BL{Reading first line of \BL@stderrFile}% + \logBL{Reading first line of \BL@stderrFile}% \catcode`\^^M=5 \read\reader@BL to \firstErrorLine \ifeof\reader@BL - \def\eoln{\par} \ifx\firstErrorLine\eoln - \log@BL{File \BL@stderrFile\space is empty}% - \closein\reader@BL + \logBL{File \BL@stderrFile\space is empty} \else - \log@BL{File \BL@stderrFile\space has one line [\firstErrorLine]}% - \ErrorsFound@true - \closein\reader@BL + \logBL{File \BL@stderrFile\space has one line [\firstErrorLine]}% + \ErrorsFound@true \fi \else - \log@BL{File \BL@stderrFile\space has two lines or more}% - \ErrorsFound@true - \closein\reader@BL - \fi - \fi - \ifErrorsFound@ - \log@BL{Issuing an error message since \BL@stderrFile\space was not empty}% - \let\please=\relax\let\examine=\relax\let\stderr=\relax - \errmessage{^^JError(s) executing \BL@scriptFile. Here is how - ^^Jfile \BL@stderrFile\space begins: - ^^J\firstErrorLine - ^^Jbut, you really ought to examine this file yourself} - \please - \examine - \stderr + \logBL{File \BL@stderrFile\space has two lines or more}% + \ErrorsFound@true + \fi + \closein\reader@BL +} + +% List the contents of the script, stdout and stderr, as per the flags. +\newcommand\listEverything@BL{% + \logBL{Checking whether any listings are required}% + \newif\if@listSomething@BL@ + \ifBL@script\@listSomething@BL@true\fi + \ifBL@stdout\@listSomething@BL@true\fi + \ifBL@stderr\@listSomething@BL@true\fi + \if@listSomething@BL@ + \beginWrappingEnvironment@BL + \listEverythingI@BL + \endWrappingEnvironment@BL \else - \log@BL{Proceeding as usual since \BL@stderrFile{} is empty}% + \logBL{Nothing has to be listed}% \fi - \endgroup +} + +% Auxiliary macro to list the contents of the script, stdout and stderr, as per +% the flags. +\newcommand\listEverythingI@BL{% + \logBL{Laying out the correct \noexpand\lstinputlisting commands}%1 + \ifBL@script\listScript@BL\BL@scriptFile\fi + \ifBL@stdout\listStdout@BL\BL@stdoutFile\fi + \ifBL@stderr\listStderr@BL\BL@stderrFile\fi }% -% List the content of the script file. \newcommand\listScript@BL[1]{% - \ifBL@list{% - \log@BL{Prepending prefix [[\BL@prefix]] to generate \BL@scriptFile}% - \storeToFile@BL{\BL@prefix#1}{\BL@scriptFile}% - \forceLTR@BL - \fixPolyglossiaBug@BL - \log@BL{Invoking \noexpand\lstinputlisting to list \BL@scriptFile}% - \ifBL@stdout - % trim bottom - \beginWrappingEnvironment@BL - \lstinputlisting[style=bashfulList,belowskip=0pt]{\BL@scriptFile}% - \else - \beginWrappingEnvironment@BL - \lstinputlisting[style=bashfulList]{\BL@scriptFile}% - \endWrappingEnvironment@BL - \fi - }\else\relax\fi + \logBL{Listing script: #1} + \def\flags@BL{style=bashfulScript} + \logBL{Initial flags for listing #1 are \flags@BL} + \ifBL@stdout\edef\flags@BL{\flags@BL, belowskip=0pt}\fi + \ifBL@stderr\edef\flags@BL{\flags@BL, belowskip=0pt}\fi + \doList@BL#1\flags@BL +} + +\newcommand\listStdout@BL[1]{% + \logBL{Listing stdout: #1} + \edef\flags@BL{style=bashfulStdout} + \logBL{Initial flags for listing stdout file are \flags@BL} + \ifBL@script\edef\flags@BL{\flags@BL, aboveskip=0pt}\fi + \ifBL@stderr\edef\flags@BL{\flags@BL, belowskip=0pt}\fi + \doList@BL#1\flags@BL }% +\newcommand\listStderr@BL[1]{% + \logBL{Listing stderr: #1}% + \def\flags@BL{style=bashfulStderr}% + \logBL{Initial flags for listing stderr file are \flags@BL} + \ifBL@script\edef\flags@BL{\flags@BL, aboveskip=0pt}\fi + \ifBL@stdout\edef\flags@BL{\flags@BL, aboveskip=0pt}\fi + \doList@BL#1\flags@BL +}% + +\newcommand\doList@BL[2]{% + \logBL{Flags for listing #1 are #2}% + \expandafter\lstset\expandafter{#2}% + \lstinputlisting{#1}% + }% + \def\beginWrappingEnvironment@BL{% + \logBL{Beginning environment \BL@environment}% \expandafter\csname\BL@environment\endcsname + \forceLTR@BL + \fixPolyglossiaBug@BL }% \def\endWrappingEnvironment@BL{% \expandafter\csname end\BL@environment\endcsname }% -% Display the standard output of the execution -\newcommand\listStdout@BL{% - \ifBL@stdout{% - \log@BL{Listing stdout file \BL@stdoutFile}% - \forceLTR@BL - \fixPolyglossiaBug@BL - \log@BL{Invoking \noexpand\lstinputlisting to list \BL@stdoutFile}% - \ifBL@list % trim top - \lstinputlisting[style=bashfulStdout,aboveskip=0pt]{\BL@stdoutFile}% - \endWrappingEnvironment@BL - \else - \beginWrappingEnvironment@BL - \lstinputlisting[style=bashfulStdout]{\BL@stdoutFile}% - \endWrappingEnvironment@BL - \fi - }\else\relax\fi -}% - \newcommand\fixPolyglossiaBug@BL{% - \log@BL{Trying to fix a Polyglossia package bug}% + \logBL{Trying to fix a Polyglossia package bug}% \ifdefined\ttfamilylatin - \log@BL{Replacing \noexpand\ttfamily with \noexpand\ttfamilylatin}% + \logBL{Replacing \noexpand\ttfamily with \noexpand\ttfamilylatin}% \let\ttfamily=\ttfamilylatin - \log@BL{Replacing \noexpand\rmfamily with \noexpand\rmfamilylatin}% + \logBL{Replacing \noexpand\rmfamily with \noexpand\rmfamilylatin}% \let\rmfamily=\rmfamilylatin - \log@BL{Replacing \noexpand\sffamily with \noexpand\sffamilylatin}% + \logBL{Replacing \noexpand\sffamily with \noexpand\sffamilylatin}% \let\sffamily=\sffamilylatin - \log@BL{Replacing \noexpand\normalfont with \noexpand\normalfontlatin}% + \logBL{Replacing \noexpand\normalfont with \noexpand\normalfontlatin}% \let\normalfont=\normalfontlatin \else - \log@BL{Polyglossia package probably not loaded}% + \logBL{Polyglossia package probably not loaded}% \relax \fi }% \newcommand\forceLTR@BL{% - \log@BL{Making sure we are not in right-to-left mode}% + \logBL{Making sure we are not in right-to-left mode}% \ifdefined\setLTR - \log@BL{Command \noexpand\setLTR is defined, invoking it}% + \logBL{Command \noexpand\setLTR is defined, invoking it}% \setLTR \else - \log@BL{Command \noexpand\setLTR is not defined, we are probably LTR}% + \logBL{Command \noexpand\setLTR is not defined, we are probably LTR}% \relax \fi }% -\newcommand\log@BL[1]{% - \ifBL@verbose - \typeout{L\the\inputlineno: #1}% - \else - \relax - \fi -}% + + |