summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/bashful
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-03-10 23:34:45 +0000
committerKarl Berry <karl@freefriends.org>2012-03-10 23:34:45 +0000
commit23bc2839e583571da662eee773fad32e73c06e92 (patch)
treee18c848606498f13fdb95401de4f060fa0d0ba42 /Master/texmf-dist/doc/latex/bashful
parent82e25e064ddf4debd7223a07bcd6312fbbb23333 (diff)
bashful 0.93 (10mar12)
git-svn-id: svn://tug.org/texlive/trunk@25597 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/bashful')
-rw-r--r--Master/texmf-dist/doc/latex/bashful/Makefile16
-rw-r--r--Master/texmf-dist/doc/latex/bashful/README2
-rw-r--r--Master/texmf-dist/doc/latex/bashful/bashful.pdfbin470434 -> 568694 bytes
-rw-r--r--Master/texmf-dist/doc/latex/bashful/bashful.tex246
4 files changed, 221 insertions, 43 deletions
diff --git a/Master/texmf-dist/doc/latex/bashful/Makefile b/Master/texmf-dist/doc/latex/bashful/Makefile
index 1cf8a1d9cb2..aa090be88d9 100644
--- a/Master/texmf-dist/doc/latex/bashful/Makefile
+++ b/Master/texmf-dist/doc/latex/bashful/Makefile
@@ -1,16 +1,26 @@
PACKAGE=bashful
+ARTICLE=00
SOURCES=${PACKAGE}.tex ${PACKAGE}.sty Makefile README
${PACKAGE}.pdf: ${SOURCES}
pdflatex -shell-esc ${PACKAGE}.tex
pdflatex -shell-esc ${PACKAGE}.tex
+${ARTICLE}.pdf: ${ARTICLE}.tex
+ xelatex -shell-esc ${ARTICLE}.tex
+ xelatex -shell-esc ${ARTICLE}.tex
+
wrap: ${PACKAGE}.zip
-${PACKAGE}.zip: ${PACKAGE}.pdf $(SOURCES)
+${PACKAGE}.zip: ${PACKAGE}.pdf $(SOURCES) ${ARTICLE}.tex ${ARTICLE}.pdf
+ zip $@ $?
+
+${ARTICLE}.zip: *.sty *.tex *.sh *.stderr *.stdout error.*
zip $@ $?
clean:
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
+ *.stdout *.toc *.c minimal.* error.* date bashful.date *.exitCode \
+ condition.* temperature.* _00 _bashful bashful.pdf *.pdf *.backup *.ps \
+ begins.tex examining.tex good.* morning.* evening.* *.lst init.tex \
+ lines.tex weather.tex words.tex ls.* _rev.tex
diff --git a/Master/texmf-dist/doc/latex/bashful/README b/Master/texmf-dist/doc/latex/bashful/README
index d3a28c02793..347c72834ac 100644
--- a/Master/texmf-dist/doc/latex/bashful/README
+++ b/Master/texmf-dist/doc/latex/bashful/README
@@ -1,4 +1,4 @@
-The bashful package, v 0.92
+The bashful package, v 0.93
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
diff --git a/Master/texmf-dist/doc/latex/bashful/bashful.pdf b/Master/texmf-dist/doc/latex/bashful/bashful.pdf
index b8cd348bc61..3dea2a9acf2 100644
--- a/Master/texmf-dist/doc/latex/bashful/bashful.pdf
+++ 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
index c2247d1266f..9bca08b88d7 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[verbose]{bashful}
+\usepackage[verbose,unique]{bashful}
\usepackage[colorlinks=true]{hyperref}
\usepackage{gensymb}
@@ -12,14 +12,23 @@
\newcommand\me{bashful}
\newcommand\bashful{\textsf{\me}\xspace}
- \lstdefinestyle{input}{
- basicstyle=\ttfamily,
- showstringspaces=false,
- aboveskip=0pt,
- belowskip=0pt}%
+\lstdefinestyle{input}{basicstyle=\ttfamily\footnotesize,
+ keywords={},upquote=true,extendedchars=false,
+ showstringspaces=false,aboveskip=0pt,belowskip=0pt}
+\lstdefinestyle{scriptsize}{style=input,basicstyle=\ttfamily\scriptsize}
+
+% listings style for the script, standard output file, and standard error file.
+\lstdefinestyle{bashfulScript}{style=input}
+\lstdefinestyle{bashfulStdout}{style=input}
+\lstdefinestyle{bashfulStderr}{style=input,
+ basicstyle=\ttfamily\footnotesize\color{red}}
+\newcommand\listFile[1]{%
+ \vspace{0.8em plus 0.3em minus 0.3em}%
+ \lstinputlisting[style=input,frameround=ftttt,frame=trBL]{#1}%
+ \vspace{0.8em plus 0.3em minus 0.3em}}
\title{The \bashful Package\thanks{
- Copyright \copyright{} 2011 by Yossi Gil
+ Copyright \copyright{} 2011, 2012 by Yossi Gil
\url{mailto:yogi@cs.technion.ac.il}.
This work may be distributed and/or modified under the conditions of the
\emph{\LaTeX{} Project Public License} (LPPL), either version 1.3 of this
@@ -46,10 +55,9 @@ 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.92
+The bashful package, v 0.93
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
@@ -71,7 +79,6 @@ stat -c %y bashful.sty | sed -e s+-+/+g -e 's/ .*//g' > date
\maketitle
-
\begin{abstract}
\parindent 1.5ex
\parskip 0.5em
@@ -146,7 +153,44 @@ You may not care so much about these bits of truly
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
+\bash
+cat << EOF > ls.tex
+\documentclass{article}
+\usepackage[a6paper]{geometry}
+\usepackage{bashful}
+\pagestyle{empty}
+\begin{document}
+The directories in my \texttt{/usr} directory are:
+\bash[stdout]
+ls -F /usr
+EOF
+echo "\\END" >> ls.tex
+cat << EOF >> ls.tex
+That's it!
+\end{document}
+EOF
+xelatex -shell-escape ls.tex
+\END
+
+Before I tell you how I generated this information,
+ let me demonstrate the use of the \bashful package for the purpose of
+ incorporating the list of files in a folder into your output.
+
+This simple \LaTeX{} file generates a listing of all files
+ in the \texttt{/usr} directory, using the UNIX \texttt{ls}
+ command:
+
+\begin{minipage}{\textwidth}
+\listFile{ls.tex}
+\end{minipage}
+
+The printed output of this file is then
+
+\begin{center}
+ \fbox{\includegraphics[scale=0.8,trim=20 200 40 50]{ls.pdf}}
+\end{center}
+
+To generate the weather information, I wrote
a series of shell commands that retrieve the current temperature,
and another such series to obtain the current
weather conditions.
@@ -237,7 +281,6 @@ When \LaTeX{} encountered these, it executed the bash commands and
Subsequently, I could use the content of these files by writing:
-
\begin{quote}
\bash
sed -n "/^At the time/,/^You may not/ p" bashful.tex > init.tex
@@ -246,16 +289,16 @@ sed -n "/^At the time/,/^You may not/ p" bashful.tex > init.tex
\lstinputlisting[style=input,belowskip=0pt]{init.tex}\ldots
\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
+\section{Application for Teaching Programming}
+\bashful primary application is for writing documents which describe
+ computer programming.
+You can include the programs in your text, and have them compiled
+ and executed as part of the \LaTeX{} processing.
+To demonstrated I will first tell a simple story
of writing, compiling and executing and
- a simple program.
+ a short program.
Then, I will explain how I used the \verb+\bash+
- command to not only tell a story, but
+ command to not only tell the story, but
also to play it live: that is, authoring
a simple~C program, compiling it and executing
it, all from within \LaTeX{}.
@@ -380,7 +423,7 @@ The \texttt{stdout} adds to my listing
the string \texttt{Hello, World!} that this
execution produces to the standard output.
-\section{Dealing with Shell Command Errors}
+\section{Dealing With Errors}
Using \bashful{} to demonstrate
my \emph{Hello, World!} program, made
sure that the story I told is accurate:
@@ -423,13 +466,16 @@ Since \texttt{minimal.tex} contains \verb+\END+,
\item Creating the header of \texttt{minimal.tex}:
\bash[script]
cat << EOF > minimal.tex
-\documentclass{standalone}
+\documentclass{article}
+\usepackage[a6paper]{geometry}
\usepackage{bashful}
+\pagestyle{empty}
\begin{document}
This document creates a simple erroneous C program
and then compiles it:
\bash[script,stdout]
-echo "main(){return int;}" > error.c; cc error.c
+echo "main(){return int;}" > error.c
+cc error.c
EOF
\END
\item Adding \verb+\END+ to \texttt{minimal.tex}
@@ -450,20 +496,18 @@ 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.
+I am now ready to run \texttt{minimal.tex} through \LaTeX{},
+ but since I will not run the \texttt{latex} command myself,
+ I will send a ``\texttt{q}'' character
+ to it to abort execution when the anticipated error occurs.
-\begin{minipage}{\textwidth}
- \lstdefinestyle{bashfulStdout}{
- showstringspaces=false,
- basicstyle=\small\ttfamily,
- }%
+\lstdefinestyle{bashfulScript}{style=scriptsize}
+\lstdefinestyle{bashfulStdout}{style=scriptsize}
\bash[script,stdout]
-yes q | pdflatex -shell-esc minimal.tex | fmt -s -w 55
+yes q | xelatex -shell-esc minimal.tex | sed /texmf-dist/d
\END
-\end{minipage}
+\lstdefinestyle{bashfulScript}{style=input}
+\lstdefinestyle{bashfulStdout}{style=input}
You can see that when \LaTeX{} tried to process \texttt{minimal.tex},
it stopped execution while indicating that file
@@ -485,9 +529,93 @@ Note that the failure to compile \texttt{hello.c},
Here is what \texttt{minimal.pdf} looks like:
\begin{center}
- \includegraphics[scale=0.9]{minimal.pdf}
+ \fbox{\includegraphics[scale=0.8,trim=30 300 10 40]{minimal.pdf}}
\end{center}
+\section{Other Commands}
+\begin{description}
+\item[\texttt{\textbackslash{}bashStdout}]
+After each execution of \verb+\bash+, the macro \verb+\bashStdout+
+is defined to entire contents of
+ the standard output of the executed script.
+
+For example, I can write
+\begin{quote}
+\begin{verbatim}
+To obtain the following sentence:
+\bash
+uname -o
+\END
+\begin{quote}
+``This document was prepared on \emph{\bashStdout}''
+\end{quote}
+\end{verbatim}
+\end{quote}
+To obtain the following sentence:
+\bash
+uname -o
+\END
+\begin{quote}
+``This document was prepared on \emph{\bashStdout}''
+\end{quote}
+
+\item[\texttt{\textbackslash{}bashStderr}]
+Similar to \verb+\bashStderr+, except that it
+ is defined is defined to the standard error of the executed script.
+(Be ware that you must apply error tolerance flags
+ to use this command, since normally,
+ if the script generates anything to the standard error stream,
+ \LaTeX{} processing will halt, asking for your attention.)
+
+\item[\texttt{\textbackslash{}splice}]
+Shell commands passed to the \verb+\splice+
+ macro are executed in a similar fashion to
+ commands enclosed between \verb+\bash+
+ and \verb+\END+, but, in addition to this execution,
+ \bashful incorporates the standard output into the main file.
+For example, I can write
+\begin{quote}
+\begin{verbatim}
+Here is a nice quote for you to remember.
+\begin{quote}
+\emph{\splice{fortune}}
+\end{quote}
+\end{verbatim}
+\end{quote}
+To obtain
+\begin{quote}
+Here is a nice quote for you to remember.
+\begin{quote}
+\emph{\splice{fortune}}
+\end{quote}
+\end{quote}
+
+Unlike the \verb+\bash+\ldots\verb+\END+,
+ \verb+\splice+ does not treat its argument
+ as if it was \texttt{verbatim}.
+Using special characters can therefore be
+ tricky with \verb+\splice+.
+On the positive side, macro expansion within
+ this argument can be handy.
+\end{description}
+
+\bash
+cat 00.tex |\
+tr -c "a-zA-Z\\\\" "\012" |\
+tr "\\\\" "@" |
+sed "s/@/ @/g" |\
+tr " " "\012" |\
+sed "/^@$/d" |\
+grep @ | sort |\
+uniq -c |\
+sort -n |\
+awk '{print$1}' | uniq -c
+\END
+
+
+
+
+
\section{Customization}
@@ -519,6 +647,36 @@ Note that if you use \TeX{}live 2010, you have to configure certain
\option{verbose}{\texttt{true}/\texttt{false}}{\texttt{false}}
If \texttt{true}, be chatty.
+\option{unique}{\texttt{true}/\texttt{false}}{\texttt{false}}
+If \texttt{true}, then \bashful uses
+ unique names for the files it generates in each
+ invocation of the \verb+\bash+ command: \textsf{XX}\texttt{.sh},
+ \textsf{XX}\texttt{.stdout}, \textsf{XX}\texttt{.stderr} and
+ \textsf{XX}\texttt{.exitCode}.
+These names then follow the pattern
+ \textsf{JOB}\texttt{@}\textsf{LINE}\texttt{.}\textsf{EXTENSION},
+ where \textsf{JOB} is the job's name (i.e., \verb+\jobname+),
+ \textsf{LINE} is the number of the line in the input file in
+ which the \verb+\bash+ command was invoked, and
+ \textsf{EXTENSION} is one of ``\texttt{sh}'',
+ ``\texttt{stdout}", ``\texttt{stderr}'' and
+ ``\texttt{exitCode}.
+
+If \texttt{false}, then these files follow the pattern
+ \textsf{JOB}\texttt{.}\textsf{EXTENSION}.
+
+You should use this option your input invokes
+ \verb+\bash+ more than once.
+
+\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, 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.
+
\subsection{Command Options}
Options to \verb+\bash+ command
@@ -669,15 +827,21 @@ Also, in case bidirectional \TeX{}ing is in effect,
Renamed \texttt{list} to \texttt{script}.
\item
Added \texttt{hide} and \texttt{dir} package options.
- \end{itemize}
+\end{itemize}
+\item[Version 0.93]
+\begin{itemize}
+ \item Added the \texttt{unique} package flag.
+ \item Added the \verb+\splice+, \verb+\bashStdout+ and \verb+\bashStderr+
+ commands.
+ \item Enclosed in the packaging the Prac\TeX{} article
+ source and \texttt{.pdf} file.
+\end{itemize}
\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
@@ -686,7 +850,6 @@ The following may get implemented some day.
\item \emph{A \texttt{noclobber} option.} This option
will make this package safer, by reducing the risk
of accidentally erasing existing files.
-
\end{enumerate}
\section{Acknowledgments}
@@ -697,6 +860,11 @@ The manner by which \verb+\bash+
{\textsf{tobiShell}}.
Martin Scharrer tips on \TeX{} internals
were invaluable.
+I pay tribute to the insight and encouragement offered by Francisco Reinaldo
+ which lead to the Prac\TeX{} journal publication entitled
+ \emph{Bashful Writing and Active Documents} that describes
+ sophisticated applications of this package.
+
\appendix
\section{Source of \texttt{\jobname.sty}}