new latex package bashful (1mar11)

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

3 files changed, 631 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/bashful/Makefile b/Master/texmf-dist/doc/latex/bashful/Makefile
new file mode 100644
index 00000000000..3ea9362ec96
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bashful/Makefile
@@ -0,0 +1,14 @@
+PACKAGE=bashful
+SOURCES=${PACKAGE}.tex ${PACKAGE}.sty Makefile README
+
+${PACKAGE}.pdf: ${SOURCES}
+	pdflatex -shell-esc ${PACKAGE}.tex
+	pdflatex -shell-esc ${PACKAGE}.tex
+
+wrap: ${PACKAGE}.zip 
+
+${PACKAGE}.zip: ${PACKAGE}.pdf $(SOURCES) 
+	zip $@ $?
+
+clean:
+	rm -f [dD]elme* *.aux *.sh *.osh *.toc *~ *.log *.out *.dvi *.lsh *.stderr *.stdout *.toc *.c
diff --git a/Master/texmf-dist/doc/latex/bashful/bashful.pdf b/Master/texmf-dist/doc/latex/bashful/bashful.pdf
new file mode 100644
index 00000000000..43a9f56fa5c
--- /dev/null
+++ 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
new file mode 100644
index 00000000000..5b853991152
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/bashful/bashful.tex
@@ -0,0 +1,617 @@
+\documentclass{ltxdoc} % Process with xelatex -shell-escape
+\usepackage{bashful}
+
+\usepackage[colorlinks=true]{hyperref}
+\usepackage{gensymb}
+\usepackage{graphicx}
+\usepackage{metalogo}
+\usepackage{xkvview}
+\usepackage{xspace}
+\usepackage{amsmath}
+
+
+\newcommand\me{bashful}
+\newcommand\bashful{\textsf{\me}\xspace}
+  \lstdefinestyle{input}{
+    basicstyle=\ttfamily, 
+    showstringspaces=false,
+    aboveskip=0pt,
+    belowskip=0pt}%
+
+\title{The \bashful Package\thanks{
+  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}.
+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.
+This work has the LPPL maintenance status `maintained'.
+The Current Maintainer of this work is Yossi Gil. 
+This work consists of the files \texttt{\me.tex} and \texttt{\me.sty} 
+  and the derived file
+  \texttt{\me.pdf}
+}}
+
+\author{Yossi Gil\thanks{\url{mailto:yogi@cs.Technion.ac.IL}}\\
+   \normalsize Department of Computer Science\\
+   \normalsize The Technion---Israel Institute of Technology\\
+   \normalsize Technion City, Haifa 32000, Israel
+}
+
+\makeatletter
+\date{\date@bashful\thanks{
+      This document describes \bashful \version@bashful.}}
+\makeatother
+
+\begin{document}
+\bash
+cat << EOF > README
+The bashful package, v 0.91
+
+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>
+EOF
+\END
+
+\maketitle
+
+\begin{abstract}
+\parindent 1.5ex
+\parskip 0.5em
+
+\sl
+It is sometimes useful to ``\emph{escape-to-shell}'' from within
+	\LaTeX{}. 
+The most obvious application is when the document
+	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{}.
+	
+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}. 
+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.
+Various flags control whether the executed commands and their output 
+	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.
+\end{abstract}
+\eject
+
+\tableofcontents
+
+\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
+server="http://www.Google.com/ig/api"
+request="$server?weather=$location" 
+wget -q -O - $request |\
+tr "<>" "\012\012" |\
+grep temp_c |\
+sed 's/[^0-9]//g'
+\END
+
+\bash[verbose,scriptFile=condition.sh,stdoutFile=condition.tex]
+location=Jerusalem,Israel
+server="http://www.Google.com/ig/api"
+request="$server?weather=$location" 
+wget -q -O - $request |\
+tr "<>" "\012\012" |\
+grep "condition data" |\
+head -n 1 |\ 
+sed -e 's/^.*="//' -e 's/"\/*//' |\
+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.
+	
+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. 
+
+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.  
+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.
+My command series to obtain the current temperature was:
+ 
+\begin{minipage}{\textwidth}
+\begin{quote}
+	\lstinputlisting[style=input]{temperature.sh}
+\end{quote}
+\end{minipage}
+
+while the weather condition was obtained by 
+
+\begin{minipage}{\textwidth}
+\begin{quote}
+	\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.
+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.
+
+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.
+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,
+\begin{quote}
+	\tt
+	\% latex -shell-escape \jobname.tex
+\end{quote}
+
+What I actually wrote in my \texttt{.tex} file 
+  to produce the temperature in 
+	Jerusalem, Israel was: 
+	
+\begin{minipage}{\textwidth}
+\begin{quote}
+\noindent\verb+\bash[verbose,scriptFile=temperature.sh,stdoutFile=temperature.tex]+
+\lstinputlisting[style=input]{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}
+
+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]+
+\lstinputlisting[style=input]{condition.sh}
+\verb+\END+
+\end{quote}
+\end{minipage}
+
+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}.
+
+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}
+\end{quote}
+
+\section{An Easy to Digest Example}
+If you were intimidated by technicalities of the
+  above description, let's try another example
+  that might be easier to digest.
+  
+I will start by telling a simple story
+  of writing, compiling and executing and 
+    a simple program.
+Then, I will explain how I used the \verb+\bash+
+  command to not only tell a story, but
+  also to play it live: that is, authoring
+  a simple~C program, compiling it and executing
+  it, all from within \LaTeX{}.
+  
+\subsection{A ``Hello, World'' Program} 
+ 
+\subsubsection{Authoring}
+Let's first write a simple 
+  \href{http://en.wikipedia.org/wiki/Hello_world_program}
+    {Hello, World!} program in the 
+    \href{http://en.wikipedia.org/wiki/C_(programming_language)}
+    {C programming language}:
+
+\begin{quote}
+\bash[verbose,list]
+rm -f hello.c; cat << EOF > hello.c
+/* 
+** hello.c: My first C program; it prints 
+** "Hello, World!", and dies.
+*/
+
+#include <stdio.h> 
+
+int main() 
+{
+  printf("Hello, World!\n");
+  return 0;
+}
+EOF
+\END
+\end{quote}
+
+\subsubsection{Compiling}
+Now, let's compile this program:
+\begin{quote}
+\bash[list,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]
+./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{quote}
+\begin{verbatim}
+\bash[list]
+rm -f hello.c; cat << EOF > hello.c
+/* 
+** hello.c: My first C program; it prints 
+** "Hello, World!", and dies.
+*/
+
+#include <stdio.h> 
+
+int main() 
+{
+  printf("Hello, World!\n");
+  return 0;
+}
+EOF
+\END
+\end{verbatim}
+\end{quote}
+
+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+
+  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}.
+ 
+\subsubsection{Compiling} 
+Next, I wrote
+\begin{quote}
+\begin{verbatim}
+\bash[list]
+cc hello.c
+\END
+\end{verbatim}
+\end{quote}
+
+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,
+  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 printed version of this document.
+In this case, no such messages were produced.
+
+
+\subsubsection{Executing}
+
+Finally, I wrote 
+\begin{quote}
+\begin{verbatim}
+\bash[list,stdout]
+./a.out
+\END
+\end{verbatim}
+\end{quote}
+to run the program I just wrote.
+The \texttt{stdout} adds to my listing
+  the output that this execution produces, i.e.,
+  the string \texttt{Hello, World!} that this
+  execution produces to the standard output.
+  
+\section{Dealing with Shell Command Errors}
+Using \bashful{} to demonstrate
+  my \emph{Hello, World!} program, made
+  sure that the story I told is accurate:
+I really did everything I said I did.
+More accurately, the \verb+\bash+ command
+  acted as my proxy, and did it for me.
+  
+Luckily, my \texttt{hello.c} program was 
+  correct.
+But, if it was not, the \verb+\bash+ command would have detected
+  the error, and would have stopped the \LaTeX{} process, 
+  indicating that the compilation did not succeed.
+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 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;
+\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.
+\end{enumerate}
+
+Let me demonstrate a situation in which the execution of 
+  the script generates an error.
+To do that, I will write a short \LaTeX{} file, named \texttt{minimal.tex}
+  which tries to use \verb+\bash+ to compile an incorrect~C program.
+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]
+cat << EOF > minimal.tex
+\documentclass{minimal}
+\usepackage{bashful}
+\begin{document}
+\bash
+echo "main(){return int;}" > error.c
+cc error.c
+EOF
+\END
+\item Adding \verb+\END+ to \texttt{minimal.tex}
+\bash[list]
+echo "\\END" >> minimal.tex
+\END
+\item Finalizing \texttt{minimal.tex}
+\bash[list]
+echo "\\end{document}" >> minimal.tex
+\END
+\end{enumerate}
+
+Let me now make sure \texttt{minimal.tex} was what I expect it to be:
+
+\begin{minipage}{\textwidth}
+\bash[list,stdout]
+cat minimal.tex
+\END
+\end{minipage}
+
+I am now ready to run \texttt{minimal.tex} through \LaTeX{},
+  but since I will not run the \texttt{latex} command myself,
+  I will make sure a \texttt{q} character is sent to it
+  when the anticipated error occurs. 
+ 
+\begin{minipage}{\textwidth}
+  \lstdefinestyle{bashfulStdoutFile}{
+    showstringspaces=false,
+    basicstyle=\scriptsize\ttfamily,
+  }%
+\bash[list,stdout]
+yes x | latex -shell-esc minimal.tex
+\END
+\end{minipage}
+
+You can see that when \LaTeX{} tried to process \texttt{minimal.tex},
+  it stopped execution while indicating that file
+  \texttt{minimal.stderr} was not 
+  empty after the compilation. The first line of \texttt{minimal.stderr}
+  was displayed, and I was advised to examine this file myself.
+Inspecting \texttt{minimal.stderr}, we see the C compiler error messages:
+
+\begin{minipage}{\textwidth}
+\bash[list,stdout]
+cat minimal.stderr
+\END
+\end{minipage}
+  
+\section{Customization}
+
+\subsection{Options}
+
+Options to \verb+\bash+ are passed using the \textsf{xkeyval} syntax:
+
+\newcommand\option[3]{%
+      \noindent\(
+          \text{\bfseries\texttt{#1}}
+          =
+          \langle\text{{#2}}\rangle
+      \)
+      \hfill\texttt{#3}\\}
+      
+
+\option{scriptFile}{\sl fileName}{\textbackslash jobname.sh}
+Name of file into which the script instructions are spilled prior 
+  to execution.
+The default is \verb+\jobname.sh+; this file
+  will be reused by all \verb+\bash+ commands in your documents.
+  This is rarely a problem, since these scripts
+  execute sequentially.
+
+\option{stdoutFile}{\sl fileName}{\textbackslash jobname.stdout}
+Name of file into which the shell standard output stream is 
+  redirected. 
+  
+
+\option{stderrFile}{\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}}
+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 
+  \texttt{true}, then \texttt{scriptFile} is listed
+  first, and leaving no vertical space, 
+  \texttt{stdoutFile} is listed next.
+  
+\option{prefix}{tokens}{\percentchar\textvisiblespace}
+String that prefixes the listing of \texttt{scriptFile}. 
+
+\option{verbose}{\texttt{true}/\texttt{false}}{\texttt{false}}
+If \texttt{true}, the package logs every step it takes.
+
+\subsection{Listings Styles}
+Package 
+  \href
+    {ftp://ftp.tex.ac.uk/tex-archive/macros/latex/contrib/listings/listings.pdf}
+    {\textsf{listing}}
+  is used for all listing both the executed shell
+  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).
+The current definition of this style is:
+\begin{verbatim}
+\lstdefinestyle{bashfulList}{
+    basicstyle=\ttfamily,
+    showstringspaces=false}
+\end{verbatim}
+Redefine this style to match your needs.
+
+\subsubsection{Listings Style for Standard Output}
+
+Style \verb+bashfulStdout+ is used for displaying the output of the 
+  executed shell
+  commands (when option \texttt{stdout} is used).
+The current definition is:
+\begin{verbatim}
+  \lstdefinestyle{bashfulStdout}{
+    basicstyle=\sl\ttfamily,
+    showstringspaces=false
+  }
+\end{verbatim}
+Redefine this style to match your needs.
+
+\section{Interaction with Other Packages}
+This packages tries to work around a bug in \texttt{polyglossia}
+  by which \verb+\texttt+ is garbled upon 
+  switching to languages which do not use the Latin alphabet.
+Also, in case bidirectional \TeX{}ing is in effect,
+  \bashful forces the listing to be left-to-right.
+
+
+\section{History}
+\begin{description}
+\item[Version 0.91] Initial release
+\end{description}
+
+\section{Future}
+The following may get implemented some day.
+
+\begin{enumerate}
+\item \emph{Package options.} Currently all options are 
+    passed to the command itself.
+\item \emph{A \texttt{clean} option.} This option
+  will automatically erase files
+  generated for storing the script, and its standard
+  output and standard error streams.
+  
+\item \emph{A \texttt{noclobber} option.} This option
+  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}
+The manner by which \verb+\bash+ 
+  collects its arguments is based on that of
+ \href
+  {http://www.tn-home.de/Tobias/Soft/TeX/tobiShell.pdf}
+  {\textsf{tobiShell}}.
+Martin Scharrer tips on \TeX{} internals
+  were invaluable.
+
+\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}
+
+
+\end{document}