summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/bashful
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/bashful
Initial commit
Diffstat (limited to 'macros/latex/contrib/bashful')
-rw-r--r--macros/latex/contrib/bashful/Makefile26
-rw-r--r--macros/latex/contrib/bashful/README13
-rw-r--r--macros/latex/contrib/bashful/bashful.pdfbin0 -> 568694 bytes
-rw-r--r--macros/latex/contrib/bashful/bashful.sty544
-rw-r--r--macros/latex/contrib/bashful/bashful.tex893
5 files changed, 1476 insertions, 0 deletions
diff --git a/macros/latex/contrib/bashful/Makefile b/macros/latex/contrib/bashful/Makefile
new file mode 100644
index 0000000000..aa090be88d
--- /dev/null
+++ b/macros/latex/contrib/bashful/Makefile
@@ -0,0 +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) ${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.* 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/macros/latex/contrib/bashful/README b/macros/latex/contrib/bashful/README
new file mode 100644
index 0000000000..347c72834a
--- /dev/null
+++ b/macros/latex/contrib/bashful/README
@@ -0,0 +1,13 @@
+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
+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/macros/latex/contrib/bashful/bashful.pdf b/macros/latex/contrib/bashful/bashful.pdf
new file mode 100644
index 0000000000..3dea2a9acf
--- /dev/null
+++ b/macros/latex/contrib/bashful/bashful.pdf
Binary files differ
diff --git a/macros/latex/contrib/bashful/bashful.sty b/macros/latex/contrib/bashful/bashful.sty
new file mode 100644
index 0000000000..21b6f43402
--- /dev/null
+++ b/macros/latex/contrib/bashful/bashful.sty
@@ -0,0 +1,544 @@
+% Copyright (C) 2011,2012 by Yossi Gil yogi@cs.technion.ac.il
+% ---------------------------------------------------------------------------
+% This work may be distributed and/or modified under the conditions of the
+% 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
+% 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 bashful.tex and bashful.sty and the derived
+% bashful.pdf
+
+\NeedsTeXFormat{LaTeX2e}%
+
+% Auxiliary identification information
+\newcommand\date@bashful{2012/03/08}%
+\newcommand\version@bashful{V 0.93}%
+\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
+ without displaying the script and/or its output.
+]
+\PackageInfo{bashful}{This is bashful, \signature@bashful}%
+
+\RequirePackage{xcolor}
+\RequirePackage{catchfile}
+\RequirePackage{xkeyval} % Use xkeyval for retrieving parameters
+\RequirePackage{textcomp} % For upquote
+
+% If true, all activities take place in a designated directory.
+\newif\if@hide@BL@\@hide@BL@false
+
+% \if@unique@BL@ is a Boolean flag, telling us whether unique names should be
+% generated for the auxiliary files (XX.sh, XX.stdout, XX.stderr and
+% XX.exitCode) in each invocation of the \bash command.
+\newif\if@unique@BL@\@unique@BL@false
+\def\unique@BL{\if@unique@BL@ @\the\inputlineno\fi}
+
+% 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{bashfulScript}{
+ basicstyle=\ttfamily,
+ keywords={},
+ upquote=true,
+ showstringspaces=false}%
+ % listings style for the standard output file, can be redefined by client
+ \lstdefinestyle{bashfulStdout}{
+ basicstyle=\sl\ttfamily,
+ keywords={},
+ upquote=true,
+ showstringspaces=false
+ }%
+ % listings style for the standard error file, can be redefined by client
+ \lstdefinestyle{bashfulStderr}{
+ basicstyle=\sl\ttfamily\color{red},
+ keywords={},
+ upquote=true,
+ showstringspaces=false
+ }%
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% Keys generating file names in alphabetical order:
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% dir: String = \directory@BL: Name of directory in which execution is going
+% to take place
+\define@cmdkey{bashful}[BL@]{dir}{\def\directory@BL{#1}}%
+
+% exitCodeFile: String = \BL@exitCodeFile: In which file should the exit code
+% be stored if it is not zero.
+\def\BL@exitCodeFile{\jobname\unique@BL.exitCode}%
+\define@cmdkey{bashful}[BL@]{exitCodeFile}{}%
+
+% scriptFile: String = \BL@scriptFile: In which file should the script be
+% saved?
+\def\BL@scriptFile{\jobname\unique@BL.sh}%
+\define@cmdkey{bashful}[BL@]{scriptFile}{}%
+
+% stderrFile: String = \BL@stderrFile: In which file should the standard
+% error stream be saved?
+\def\BL@stderrFile{\jobname\unique@BL.stderr}%
+\define@cmdkey{bashful}[BL@]{stderrFile}{}%
+
+% stdoutFile: String = \BL@stdoutFile: In which file should the standard
+% output stream be saved?
+\def\BL@stdoutFile{\jobname\unique@BL.stdout}%
+\define@cmdkey{bashful}[BL@]{stdoutFile}{}%
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% 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
+\def\BL@environment{none@BL}%
+\define@cmdkey{bashful}[BL@]{environment}{}%
+\newenvironment{none@BL}{}{} % Default, empty environment for wrapping
+ % the listings
+
+% prefix: String = \BL@prefix: What prefix should be printed before a listing.
+\def\BL@prefix{\@percentchar\space}%
+\define@cmdkey{bashful}[BL@]{prefix}{}%
+
+% shell: String = \BL@shell: Which shell should be used for execution?
+\def\BL@shell{bash}%
+\define@cmdkey{bashful}[BL@]{shell}{}%
+
+% verbose: Boolean = \ifBL@verbose: Log every step we do
+\define@boolkey{bashful}[BL@]{verbose}[true]{}%
+
+% The "unique" package flag that tells the package to generated unique names
+% for the auxiliary files. If true the generated files (XX.sh, XX.stdout,
+% XX.stderr and XX.exitCode) are given unique names in each invocation of the
+% \bash command. Unique names are generated by the pattern JOB@LINE.EXTENSION,
+% where JOB is the job's name, LINE is the number of the line in the input in
+% which the \bash command was invoked, and EXTENSION is one of "sh", "stdout",
+% "stderr" and "exitCode".
+\DeclareOptionX{unique} {\@unique@BL@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{%
+ \logBL{Beginning a group so that all cat code changes are local}%
+ \begingroup%
+ \logBL{Making \^\^M a true newline}%
+ \catcode`\^^M\active%
+ \def^^M{^^J}%
+ \logBL{Checking for optional arguments}%
+ \@ifnextchar[{\bashI}{\bashI[]}%
+ }%
+\endgroup
+
+% \bashI: Process the optional arguments and continue
+\def\bashI[#1]{\setKeys@BL{#1}\bashII}
+
+% \bashII: Set category codes of all characters to special, and proceed.
+\begingroup
+ \catcode`\^^M\active%
+ \gdef\bashII{%
+ \logBL{bashII: Making \^\^M a true new line}%
+ \catcode`\^^M\active%
+ \def^^M{^^J}%
+ \logBL{bashII: Making all characters other}%
+ \let\do\@makeother%
+ \dospecials%
+ \bashIII}%
+\endgroup
+
+% \bashIII: Consume all tokens until \END (but ignoring the preceding and
+% terminating newline), and proceed.
+\begingroup
+ \catcode`\@=0\relax
+ \catcode`\^^M\active
+ @catcode`@\=12@relax%
+ @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, and executing
+% this file,
+\newcommand\bashIV[1]{%
+ \logBL{BashIV: begin}%
+ \makeDirectory@BL
+ \generateScriptFile@BL{#1}\relax
+ \executeScriptFile@BL
+ \logBL{BashIV: done}%
+}%
+
+% \logBL: record a log message in verbose mode
+\newcommand\logBL[1]{\ifBL@verbose\typeout{L\the\inputlineno: #1}\fi}
+
+% A macro to create a new directory
+\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
+% standard error files 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
+ \defineMacros@BL
+ \logBL{Wrap up done}}
+
+\def\expandFileName@BL#1{%
+ \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{%
+ \logBL{Processing key=val pairs in options string [#1]}\relax
+ \setkeys{bashful}{#1}%
+}%
+
+% Store the list of tokens in the first argument into our script file
+\newcommand\generateScriptFile@BL[1]{%
+ \logBL{Generating script file \BL@scriptFile}
+ \storeToFile@BL{#1}{\BL@scriptFile}%
+}%
+
+\newwrite\writer@BL
+% Store the list of tokens in the first argument into the file given
+% 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{%
+ \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 message if errors found during execution
+\newcommand\checkScriptErrors@BL{%
+ \logBL{Checking for script errors}%
+% \begingroup
+ \newif\ifErrorsFound@\ErrorsFound@false
+ \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 now print the contents of file \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>>>>\firstErrorLine
+ ^^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...}%
+ \BL@verbosetrue
+ \logBL{Switching to verbose mode}%
+ \else
+ \logBL{File \BL@stderrFile\space was empty}%
+ \logBL{Proceeding as usual}%
+ \fi
+% \endgroup
+}%
+
+\newcommand\checkExitCodeFile@BL{%
+ \logBL{Considering \BL@exitCodeFile}%
+ \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 is missing, exit code was probably 0}
+ \closein\reader@BL
+ \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
+ \logBL{Hmm... \BL@stderrFile\space does not exist (probably a package bug)}%
+ \logBL{Switching to verbose mode}%
+ \BL@verbosetrue
+ \else
+ \logBL{Reading first line of \BL@stderrFile}%
+ \catcode`\^^M=5
+ \read\reader@BL to \firstErrorLine
+ \ifeof\reader@BL
+ \ifx\firstErrorLine\eoln
+ \logBL{File \BL@stderrFile\space is empty}
+ \else
+ \logBL{File \BL@stderrFile\space has one line [\firstErrorLine]}%
+ \ErrorsFound@true
+ \fi
+ \else
+ \logBL{File \BL@stderrFile\space has two lines or more}%
+ \ErrorsFound@true
+ \fi
+ \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
+ \listEverythingWithinEnvironment@BL
+ \endWrappingEnvironment@BL
+ \else
+ \logBL{Nothing has to be listed}%
+ \fi
+}
+
+% Auxiliary macro to list the contents of the script, stdout and stderr, as per
+% the flags.
+\newcommand\listEverythingWithinEnvironment@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
+}%
+
+\newcommand\listScript@BL[1]{%
+ \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
+}%
+
+% Define the \bashStdout and \bashStderr macro.
+\newcommand\defineMacros@BL{%
+ \logBL{Defining macro for the contents of the standard output file}%
+ \immediate\openin\reader@BL=\BL@stdoutFile
+ \logBL{Opened file \BL@stdoutFile}%
+ \begingroup
+ \endlinechar=-1%
+ \ifeof\reader@BL
+ \logBL{File \BL@stdoutFile was empty}%
+ \global\let\bashStdout\relax
+ \else
+ \logBL{Reading contents of \BL@stdoutFile}%
+ \immediate\read\reader@BL to \BL@temp
+ \global\let\bashStdout\BL@temp
+ \fi
+ \typeout{after EOF}%
+ \logBL{bashStdout :=^^J\bashStdout^^J}%
+ \endgroup
+ \logBL{Closing file \BL@stdoutFile}%
+ \immediate\closein\reader@BL
+ \logBL{Defining macro for the contents of the standard error file}%
+ \immediate\openin\reader@BL=\BL@stderrFile
+ \logBL{Opened file \BL@stderrFile}%
+ \begingroup
+ \endlinechar=-1%
+ \ifeof\reader@BL
+ \logBL{File \BL@stdoutFile was empty}%
+ \global\let\bashStdout\relax
+ \else
+ \logBL{Reading contents of \BL@stderrFile}%
+ \immediate\read\reader@BL to \BL@temp
+ \global\let\bashStderr\BL@temp
+ \fi
+ \logBL{bashStderr :=^^J\bashStderr^^J}%
+ \endgroup
+ \logBL{Closing file \BL@stderrFile}%
+ \immediate\closein\reader@BL
+}
+
+\newcommand\fixPolyglossiaBug@BL{%
+ \logBL{Trying to fix a Polyglossia package bug}%
+ \ifdefined\ttfamilylatin
+ \logBL{Replacing \noexpand\ttfamily with \noexpand\ttfamilylatin}%
+ \let\ttfamily=\ttfamilylatin
+ \logBL{Replacing \noexpand\rmfamily with \noexpand\rmfamilylatin}%
+ \let\rmfamily=\rmfamilylatin
+ \logBL{Replacing \noexpand\sffamily with \noexpand\sffamilylatin}%
+ \let\sffamily=\sffamilylatin
+ \logBL{Replacing \noexpand\normalfont with \noexpand\normalfontlatin}%
+ \let\normalfont=\normalfontlatin
+ \else
+ \logBL{Polyglossia package probably not loaded}%
+ \relax
+ \fi
+}%
+
+\newcommand\forceLTR@BL{%
+ \logBL{Making sure we are not in right-to-left mode}%
+ \ifdefined\setLTR
+ \logBL{Command \noexpand\setLTR is defined, invoking it}%
+ \setLTR
+ \else
+ \logBL{Command \noexpand\setLTR is not defined, we are probably LTR}%
+ \relax
+ \fi
+}%
diff --git a/macros/latex/contrib/bashful/bashful.tex b/macros/latex/contrib/bashful/bashful.tex
new file mode 100644
index 0000000000..9bca08b88d
--- /dev/null
+++ b/macros/latex/contrib/bashful/bashful.tex
@@ -0,0 +1,893 @@
+\documentclass{ltxdoc} % Process with xelatex -shell-escape
+\usepackage[verbose,unique]{bashful}
+
+\usepackage[colorlinks=true]{hyperref}
+\usepackage{gensymb}
+\usepackage{graphicx}
+\usepackage{metalogo}
+\usepackage{xkvview}
+\usepackage{xspace}
+\usepackage{amsmath}
+\usepackage{multicol}
+
+\newcommand\me{bashful}
+\newcommand\bashful{\textsf{\me}\xspace}
+\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, 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
+ 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.
+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.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
+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
+
+\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{}.
+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
+ \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}
+
+\begin{multicols}{2}
+\footnotesize
+\tableofcontents
+\end{multicols}
+
+\parindent 1.5ex
+\parskip 0.5em
+
+\section{Introduction}
+
+\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}\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 the input.
+
+\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.
+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 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.
+
+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} flag does that.
+To process my document, I typed, at the command line,
+\begin{quote}
+ \tt
+ \% latex -shell-escape \jobname.tex
+\end{quote}
+
+What I actually wrote in the input
+ 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,belowskip=0pt]{temperature.sh}
+\verb+\END+\\
+\end{quote}
+\end{minipage}
+
+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]+
+\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}
+\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{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 short program.
+Then, I will explain how I used the \verb+\bash+
+ 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{}.
+
+\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}:
+
+
+\bash[verbose,environment=quote,script]
+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
+
+\subsubsection{Compiling}
+Now, let's compile this program:
+\bash[environment=quote,script,stdout]
+cc hello.c
+\END
+
+\subsubsection{Executing}
+Finally, we can execute this program,
+ and see that indeed, it prints the ``Hello, World!''
+ string.
+\bash[environment=quote,script,stdout]
+./a.out
+\END
+
+
+\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[script]
+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}
+\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 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}.
+
+\subsubsection{Compiling}
+Next, I wrote
+\begin{quote}
+\begin{verbatim}
+\bash[script,stdout]
+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{script} flag,
+ the command for compiling this program
+ was included in the printed version of
+ this document.
+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.
+
+
+\subsubsection{Executing}
+
+Finally, I wrote
+\begin{quote}
+\begin{verbatim}
+\bash[script,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 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 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,
+ 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 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
+ 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[script]
+cat << EOF > minimal.tex
+\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
+EOF
+\END
+\item Adding \verb+\END+ to \texttt{minimal.tex}
+\bash[script]
+echo "\\END" >> minimal.tex
+\END
+\item Finalizing \texttt{minimal.tex}
+\bash[script]
+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[script,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 send a ``\texttt{q}'' character
+ to it to abort execution when the anticipated error occurs.
+
+\lstdefinestyle{bashfulScript}{style=scriptsize}
+\lstdefinestyle{bashfulStdout}{style=scriptsize}
+\bash[script,stdout]
+yes q | xelatex -shell-esc minimal.tex | sed /texmf-dist/d
+\END
+\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
+ \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[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.
+
+Here is what \texttt{minimal.pdf} looks like:
+
+\begin{center}
+ \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}
+
+\newcommand\option[3]{%
+ \noindent\(
+ \text{\bfseries\texttt{#1}}
+ =
+ \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.
+
+\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
+ 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.
+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{exitCodeFile}{\sl fileName}{\textbackslash jobname.stderr}
+Name of file into which the shell standard error stream is
+ redirected.
+
+\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{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.
+
+\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+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{bashfulScript}{
+ basicstyle=\ttfamily,
+ keywords={},
+ 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}
+ % 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}
+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.
+\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}
+\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{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.
+\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.
+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}}
+ \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}