summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/bashful
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-03-01 23:47:19 +0000
committerKarl Berry <karl@freefriends.org>2011-03-01 23:47:19 +0000
commitf128ebd6f9643de2a990dcf9e92e8f6f3d8774bc (patch)
treea370c1bde7126c3ec85ba568e9409a60f3aca837 /Master/texmf-dist/doc/latex/bashful
parented0d8b94e2434831b339aaab91e00879a53bd96d (diff)
new latex package bashful (1mar11)
git-svn-id: svn://tug.org/texlive/trunk@21577 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/bashful')
-rw-r--r--Master/texmf-dist/doc/latex/bashful/Makefile14
-rw-r--r--Master/texmf-dist/doc/latex/bashful/bashful.pdfbin0 -> 422132 bytes
-rw-r--r--Master/texmf-dist/doc/latex/bashful/bashful.tex617
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
Binary files differ
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}