path: root/Master/texmf-dist/source/latex/shdoc/shdoc.dtx

% \iffalse meta-comment
%
% Copyright 2015 Simon M. Laube
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, 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 `author maintained'.
% 
% The Current Maintainer of this work is S. M. Laube
%
% \fi
%
%\iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{shdoc}[2015/05/24 v2.1 Package for documenting shell operations]
%<package>\RequirePackage[dvipsnames]{xcolor}
%<package>\RequirePackage{float}
%<package>\RequirePackage{caption}
%<package>\RequirePackage{mdframed}
%<package>\RequirePackage{kvoptions}
%<package>\RequirePackage{relsize}
%<package>\RequirePackage{stringstrings}
%<package>\RequirePackage{ifthen}
%<package>\makeatletter
%
%
%<*internal>
\iffalse
%</internal>
%<*readme>
 Copyright 2015 Simon M. Laube

 This work may be distributed and/or modified under the
 conditions of the LaTeX Project Public License, 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 `author maintained'.
 
 The Current Maintainer of this work is S. M. Laube

 The shdoc package provides a simple, though fancy, float
 environment that can be used to document operations or command
 executions of a terminal session on a shell.
 
 The current version of the package is v2.1.
 
 To create the package (*.sty) from source open a command line prompt,
 change to the package directory and type
     
     tex shdoc.ins
     
 Afterwards you can generate the package documentation by typing
   
     (pdf)latex shdoc.dtx
     
 Be aware, that the shdoc package is using Unix/Linux specific shell
 commands within the documentation. Thus, you may not be able to build
 the documentation on your system. For security reasons, make sure that
 you do not execute unknown shell scripts -- that are distributed with this
 or other packages -- blindly. Further, you will need to enable `write18'
 to build the documentation successfully.
%</readme>
%This is an example file that is needed to compile the manual
%The right file is generated by the docstrip utility
%<*avr>

avrdude: AVR device initialized and ready to accept instructions

Reading | ################################################## | 100% 0.01s

avrdude: Device signature = 0x1e910b

avrdude: safemode: Fuses OK (H:FF, E:DF, L:E2)

avrdude done.  Thank you.

%</avr>
%
%<*internal>
\fi
%</internal>



%<*driver>
\documentclass[a4paper, 10pt]{ltxdoc}
\usepackage{shdoc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{tikz}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\usepackage[colorlinks=true,linkcolor=black,urlcolor=blue,bookmarks=true]{hyperref}
\begin{document}
	\DocInput{shdoc.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{0}
%
% \changes{v1.0}{2015/03/10}{Initial version}
% \changes{v1.1}{2015/04/06}{Formatting changes}
% \changes{v1.2}{2015/05/20}{Background color changed globally}
% \changes{v2.0}{2015/08/10}{Added package options as kv-list: colors and symbols}
% \changes{v2.1}{2016/04/08}{Reworked the paragraph settings better typesetting of the output, font size is variable, added a whole bunch of new macros for automatic shell-command execution}
%
% \GetFileInfo{\jobname.sty}
%
% \DoNotIndex{}
%
%\def\dfcol#1{\raisebox{-5pt}{\tikz{\node[rectangle,draw=#1,fill=#1]{#1};}}}
%
%\title{The \textit{shdoc} package -- Manual for version~\fileversion, \filedate}
%\author{Simon Michael Laube \\ \texttt{simon.laube@gmx.at}}
%\date{}
%
%\maketitle
%
%\shuser{simon}
%\shmachine{linuxmint}
% \begin{shbox}
%	\shline{}{tex}
%   \shoutput{}{This is TeX, Version 3.14159265 (TeX Live 2014)}
%	\shoutput{}{**\cmd{\relax}}
%   \shoutput{}{*Hello World!}
%   \shoutput{}{*\cmd{\bye}}
% \end{shbox}
% \begin{abstract}
% \noindent The \textit{shdoc} packages helps documenting commandline actions in
% a fancy way. It tries to imitate the look and feel of the original shell prompt
% while offering a wide range of personalization options.
% \end{abstract}
%
%\tableofcontents
%
% \section{Introduction}
%
% Many people who use \LaTeX\ and do a bit of coding in other languages have used
% \LaTeX's \textit{listings} package at least once. However, when me and my colleague 
% wrote the documentation of our diploma project in 2015, we stumbled across a ``problem''\footnote{obviously it's not a
% real problem, but we wanted something more shell-specific} with
% \textit{listings}. A lot of command line scripting had to be done for our project to configure a Raspberry Pi B+ and those
% actions needed to be documented. \textit{listings} seemed to be the wrong package to look for, so we wrote our own.
%  At first there were few small macros that we referred to as \textit{bashdoc} -- this was
% version 1.0. Later the macros got a bit more complex and we simply threw away the \textit{ba} part of \textit{bashdoc},
% that's how the \textit{shdoc} package was born. The basic idea somehow
% stayed the same since the very first draft, but the package is much more applicable now.\par 
%
% I hope that \textit{shdoc} fits your application as it fitted ours. If there are any serious problems, feel free to 
% send me an email\footnote{Please do not send spam mails of any kind. Plain text email format would be appreciated}.
% Moreover, I do not guarantee full compatibility with other packages and different operating systems. 
% The package is distributed under the \LaTeX\ Project
% Public License version 1.3.\par 
% 
% \section{Acknowledgement}
%
% At this point I would like to thank \textit{Timm Severin} for his active feedback concerning problems and 
% ideas about the package. 
% He pointed out a major bug of version v2.0 and submitted the draft source for some of the new features in version v2.1.
% Thank you very much!
% \newpage
% \section{User commands}
%   \textit{shdoc} implements user commands that allow one to typeset the content/commands 
%	of a command line session appropriately. Further there are macros to
%   create and modify styles and appearance of the final output, as well as automated functions
%   that let the user execute commands via \textit{shdoc} and typeset their output immediately.\par 
%
%   \subsection{Package inclusion and options}
% 	Just like every \LaTeX\ package, \textit{shdoc} can be included using the standard
%   \cmd{\usepackage} command:
% 	\begin{quote}
%   \cmd{\usepackage\oarg{options}\{shdoc\}}
%	\end{quote}
%
%   Since version 2.0 \textit{shdoc} supports several package options to make the environment more
% 	adjustable for users. The available options are described in detail in the following 
%   sections.
%
%	
%   \subsection{Color and style management}\label{subsec:style}
%		The shbox environment uses plenty of \textit{different} colors and symbols, which can be adjusted through
%   	optional package arguments or macros within the document. Thus, you can either specify the color at the package
%		inclusion in the preamble or just before your session in the document. 
%
%		\DescribeMacro{\shchange}
%		To modify the appearance of shell sessions within your document one can use three different
%		commands. The essential macro is \cmd{\shchange\marg{<name>} \marg{<new value>}}, which lets you specify a new value for every 
%		existing package option. Basically this command is all you need, but it is not recommended to use it for style changes.
%		As mentioned there are two more macros, namely \cmd{\shchangecolor} and 
%		\cmd{\shchangesymbol}. The reason you should use these two for style changes is
%		simply because of enhanced readability of your code. Anyone who reads your source will be able to tell what
%		change you made at the first glimpse -- that is mainly important when defining presets, 
%		see section~\ref{subsubsec:presets}. However, the commands all work the same as the latter 
%		two are exact copies
%		of \cmd{\shchange}. Here are some examples of style changes:%
%		\begin{verbatim}
%			\usepackage[backgroundcolor=white,indicatorsymbol=$+$]{shdoc}
%			or
%			\shchangecolor{backgroundcolor}{white}
%			\shchangesymbol{indicatorsymbol}{$+$}
%
%
%			\usepackage[usernamecolor=blue!70]{shdoc}
%			or
%			\shchange{usernamecolor}{blue!70} % works, but isn't recommended
%		\end{verbatim}
%
%		\noindent Be aware that specifying style settings as a package option always sets the style for the whole
%		document, unless the settings are changed again via \cmd{\shchange}.
%
%
%		\subsubsection{Colors}
%   		Table~\ref{tab:color_var} shows the package-specific
% 			names of all the colors, their default value and where they are used. Every color is specified using a key-value 
%			element as an optional package argument. If no argument is given for a specific color the default value is used.
%		
%   
%   		\begin{table}[tbh!]
%			\centering\small
%			\begin{tabular}{lll}
%				Name & Description & Default color \\\hline
%	 			backgroundcolor & color of the environment background & \dfcol{gray!70}\\
%   	   		usernamecolor & color of the username&\dfcol{green!80!yellow}\\
%				machinenamecolor & color of the machine-name&\dfcol{green!80!yellow}\\
%				indicatorcolor & color of the indicator symbol&\dfcol{RoyalBlue}\\
%				separatorcolor & color of the user-machine separator symbol&\dfcol{green!80!yellow}\\
%				pathcolor & color of the current path& \dfcol{RoyalBlue}\\
% 				optioncolor & color of the little option box&\dfcol{white!60!gray}\\
%				textcolor & color of the rest of the text& \dfcol{black}\\
%			\end{tabular}
%			\caption{Adjustable colors of the shbox environment}
%			\label{tab:color_var}
% 			\end{table}
%
%
%   	\subsubsection{Symbols}
%   		In total, only two symbols can be changed in the \textit{shdoc} package.
%   		Table~\ref{tab:symbol_var} shows their name, default value and description. Just as the
%   		colors, every symbol is changed using a key-value element as an optional
%   		package argument. If no arguments are given, the default values are used. 
%
%
%   \begin{table}[tbh!]
%	\centering\small
%	\begin{tabular}{llc}
%		Name & Description & Default symbol \\\hline
%	 	indicatorsymbol & separates user input and displayed path & \$\\
%       separatorsymbol & separates user- and machine-name& @\\
%	\end{tabular}
%	\caption{Adjustable symbols of the shbox environment}
%	\label{tab:symbol_var}
% 	\end{table}
%   \noindent Please pay attention, that the @'s \textit{catcode} is changed to letter internally. Thus,
%   you can use @ directly:
%	\begin{verbatim}
%		\shchangesymbol{separatorsymbol}{@}
%	\end{verbatim}
%
%
%	\subsubsection{Appearance and presets}\label{subsubsec:presets}
%   As described above, \textit{shdoc} has some settings that can be
% 	changed by the user. Some setting values have been tested and 
%   stored as a preset that a user can easily load. Further, users are able to 
% 	create their own presets via built-in commands.\par
%
%	\DescribeMacro{\shpreset}
%	One can easily load a preset with \cmd{\shpreset\marg{<name>}} by using the preset's name
% 	as an argument to that macro. When a preset has been loaded it is valid for every 
%   new \textit{shbox} environment afterwards, until the \cmd{\shpreset} macro is invoked
%	again.\par 
%	\DescribeMacro{\shpresetdef} Most of the time, users might want to create their own styles,
%	which can be achieved by defining a new preset via \cmd{\shpresetdef\marg{<name>}\marg{<def>}}. The command has two
% 	mandatory arguments: The first one is the desired preset-name and the second one is the 
%	preset definition. For example one can use:
%	\begin{quote}
%		\verb|\shpresetdef{useless}{\relax}|
%	\end{quote}
%   and is then able to apply the preset by calling:
%	\begin{quote}
%		\verb|\shpreset{useless}|
%	\end{quote}
%	\par
%	\noindent A preset definition basically exists of multiple style changes, as described at the beginning of 
%	section~\ref{subsec:style}. For further information about preset definitions, please have a look
% 	at all the examples in section~\ref{subsubsec:presetdef} and section~\ref{subsec:presetdef}. 
%	Please also note that every new preset definition
%	is based on the default preset, as \cmd{\shpresetdef} invokes \cmd{\shpreset\{default\}} prior to the definition.\par 
%
%
%	Several presets have been defined by the author and are included in the \textit{shdoc} package.
% 	One can use them by calling the \cmd{\shpreset\marg{name}} command with the name of the desired
% 	preset. The following list shows the appearance and name of the predefined presets -- for visuals
%	see section~\ref{sec:examples}:
%
%	\begin{description}
%		\item[default/mint] The default preset. It implements a gray background theme
%		with light gray option boxes, light green user- and machine-name and a blue path value.
%
%		\item[arrows] Not recommended for printed documents. Implements a black background theme
%		with gray option boxes, red username, white separator, light green machine-name, blue path
%		and two arrows as an indicator symbol. The rest of the text is white, too.
%		
%		\item[darkblue] Implements a dark blue background theme with white text, light blue option
%		boxes, orange user- and machine-name and a green path value.
%
%		\item[airy] A light colored style. Implements a light blue background theme with cyan option
%		boxes and user- \& machine-name, as well as light orange path value and black text.
%
%		\item[blackwhite] Best for non-color prints. Implements a light gray background theme with white option
%		boxes, black text, darker gray user- and machine-name and a dark gray path value.
%	\end{description}
%	
%
%  	\subsection{The environment}\label{subsec:environment}
%	Basically a complete terminal session consists out of two environments that contain the
%	necessary information that is used to typeset the session. 
%	\DescribeMacro{\sh} The outer environment is named \cmd{\sh} and basically acts as the
% 	float environment that could contain one or more so called \cmd{\shbox}es.
%	\DescribeMacro{\shbox} Every \cmd{\shbox} contains in- and output lines of the terminal,
%	with information provided by the user. The following code shows a brief overview of the
%	possible and necessary commands:\par 
%	\begin{verbatim}
%	\shpreset{mint}
%	\begin{sh}
%		  \shuser{simon}
%		  \shmachine{linuxmint}
%		  \begin{shbox}
%		    	\shline{}{cd Desktop/}
%			     \shline{Desktop/}{whoami}
%		    	\shoutput{}{simon}
%		  \end{shbox}
%	\end{sh}
%	\end{verbatim}
%
%	\subsubsection{Metadata}
%	\DescribeMacro{\shuser} At least once before an occurrence of a \cmd{\shbox},
%	the user- and machine-name should be specified. \DescribeMacro{\shmachine}
%	They are set globally and thus are valid for
%	every \cmd{\shbox} that follows the macro call. If no user and machine values are
%	specified, the defaults user:\texttt{root} and machine:\texttt{linux} are used.\par
%
%	\subsubsection{Shell input \& path handling}\label{subsubsec:in_and_path}
%	\DescribeMacro{\shline}
%	Within the \cmd{\shbox} there are only two valid commands^^A
%	\footnote{Actually that's not true, but as you will probably know from the \TeX book, authors need to lie from time to time, to make things a bit easier.}, namely \cmd{\shline}, which 
%	is basically the users' input, the executed command or an arbitrary line; and \cmd{\shoutput}, 
%	which is ment to be the machine output.\cmd{\shline} has two mandatory arguments, where the first one is the path value
%	and the second one is the command that's
% 	about to be run.\par
%   There are several possibilities to handle the path value. First of all, you can leave the first argument empty,
% 	which will force \cmd{\shline} to print the \textit{default path}, namely \textasciitilde. 
%	\DescribeMacro{defaultpath}
%	As one may want to
%	have a different default path, it can be changed by either passing a key-value element of the form
%	\verb|defaultpath=<value>| as an optional argument to the package; or using the already mentioned 
%	\cmd{\shchange\marg{defaultpath}\marg{<value>}} command. 
%	\DescribeMacro{\shpath} Second, one could use \cmd{\shpath} to automatically get the absolute path
%	of the current \verb|*.tex| file. Please note that this command does not affect the default path. If you
%	would like to set the default path to the current path of your file, use 
%	\cmd{\shchange\{defaultpath\}\{\cmd{\shpath}\}}. At last, if you just want to use another path for one
%	line, just use the first argument of \cmd{\shline} to do so. For example: 
%	\begin{verbatim}
%	\shline{/home/user/Desktop}{exit}
%	\end{verbatim} 
%
%	\subsubsection{Shell output}
%	\DescribeMacro{\shoutput}
%	\cmd{\shoutput} implements two mandatory macros, too. Here, the first argument is ment for the options of a shell command.
% 	For example if you typeset the \verb|--help| output of a command, there may be one or more options like
%	\verb|-c|, \verb|-a| and \verb|-T|. These can be typeset within a fancy optionbox by using the first argument
%	of \cmd{\shoutput}. The second argument is ment for any text and is printed without any special formatting.
%	However, it is not mandatory and sometimes not even useful to use the optionbox. In this case you can leave the
%	first argument empty, which forces the macro to suppress the complete optionbox including the additional indent it
%	would otherwise cause.
% 	
%	\subsubsection{Name variables}
%	For international compatibility the \textit{shdoc} packages implements two commands to make the list and
% 	caption name of the float easily accessible. \par 
%	\DescribeMacro{\shlistname} One can use \cmd{\shlistname} to change the title of the sessions list. The default 
%	value is  ``\cmd{\shlistname}\{List of Terminal Sessions\}''.\par 
%
%	\DescribeMacro{\shfloatname} In the same manner as described above, the float caption that's displayed below
%	each float could be changed. Its default value is ``\cmd{\shfloatname}\{Terminal Session\}''.
%
%
%	\subsection{Automatic command execution and typesetting}
%	Starting with version v2.1, \textit{shdoc} includes macros that let the user execute shell commands
%	from within the \LaTeX{} file and typeset their output immediately. As the whole package is intended to
%	be used on a Linux/Unix shell it uses dedicated commands that will not work on other shells\footnote{The 
% 	manual mode, however, will always work the same.}.\par
%	Note that all the following macros in this subsection are valid within the \cmd{\sh} float environment,
%	but not within \cmd{\shbox}, as each of them produces its own, enclosed shbox. In other words, each
%	automatic inclusion macro produces a standalone shbox. The necessary float environment, caption and label 
%	stay the same.
%	
%	\subsubsection{Warning}
%	Caution! In order to make the following features work, you need to allow \TeX{} to use the \cmd{\write18}
%	instruction. For \TeX Live this can be done by using the \verb|--shell-escape| option on the shell. It is
%	not recommended to use this option permanently, as you could unconciously execute harmful \LaTeX{} code. 
%	Further, only execute \LaTeX{} and shell scripts that you trust, as nobody will take responsibility for
%	their effects.
%
%	\subsubsection{Read saved command outputs from a file}
%	\DescribeMacro{\shread} The easiest way to include shell output into your \LaTeX{} file automatically
%	is by redirecting the output stream of the shell command to a file, which is then read by \textit{shdoc}.
%	For example:
% 	\begin{verbatim}
%	root@linux ~ $ xsensors -help > xsensors-out.save
%	\end{verbatim}
%	The resulting file will look like this:
%	\begin{mdframed}[linecolor=black]	
%	\begin{verbatim}
%
%Usage: xsensors [options]
%
%Options:
%--------
%
%-f	            Display all temperatures in Fahrenheit.
%-h	            Display this help text and exit.
%-c filename    Specify the libsensors configuration file.
%-i filename    Specify the image file to use as a theme.
%-t time        Specify the update time in number of seconds.
%               Set this to a negative number for no update.
%               Don't set this to 0.
%-v	            Display version number.
%
%	\end{verbatim}
%	\end{mdframed}
% \hfill \raisebox{6pt}{\texttt{\scriptsize xsensors-out.save}}
%
%\noindent After saving the file, \cmd{\shread} is used to include it into your document.
%	The macro has two mandatory arguments: The first one is the initial command, as \textit{shdoc}
%	has no way to find out the matching input command to your output file, whereas the second one
% 	is the path and name of the file you want to read. Thus, to include the example file from above
%	one would write:
%	\begin{verbatim}
%	\shread{xsensors -help}{xsensors-out.save}
%	\end{verbatim}
%
%	While reading command output in that manner, the user still has to take care of at least two steps,
%	but it can be very useful if the output of a command is used elsewhere, too. Furthermore, this is still
% 	the fastest way to include command output as all the other methods slow down the \LaTeX{} build of your document.
%
%	\subsubsection{Run commands and typeset their output}
%	\DescribeMacro{\shrun} Nevertheless, two steps are still one too much. Thus, \cmd{\shrun} lets
% 	the user run a shell command from within the document and typesets its output automatically. The macro has one
%	mandatory argument, namely the command that should be passed to the shell. Once again make sure to have \cmd{\write18}
%	enabled:
%	\begin{verbatim}
%	\shrun{xsensors -help}
%	\end{verbatim}
%
%	\noindent The \cmd{\shrun} macro takes the shell command, passes it to the system shell and captures its
%	output in a file called \texttt{shrun.tmp}. This same file is used for every occuring \cmd{\shrun},
%	so its content is highly temporary. However, the file will not be deleted from your working directory,
% 	unless you tell \textit{shdoc} to do so -- see section~\ref{subsubsec:clearfiles}.
%	Note that the macro will also automatically redirect the \texttt{stderr} stream to the output
%	stream, so errors should be visible within your document -- see session~\ref{sh:error} for an example.
%
%	
%	\subsubsection{Autoread and typeset a file (experimental)}\label{subsubsec:autoread}
%	The results of \cmd{\shread} are normally nice, but the macro does not support
%	the optionbox of \cmd{\shoutput}. That's because files are read line by line, where
%	each line can be seen as a string that is directly passed to \cmd{\shoutput} as the second argument. 
%	Further, it is very difficult to isolate the shell options (\verb|-c|, \verb|-U|,\dots) from the
%	line of text. That's mainly because every single program formats its output in a slightly different way.
% 	Supporting every programs formatting would nearly be impossible, so another approach had to be taken by
%	the author; and that was string manipulation.\par
%	\DescribeMacro{\shautoread} The result of fooling around with various manipulation methods is a 
%	macro called \cmd{\shautoread}, which is basically \cmd{\shread} except for a few additions that are
%	provided by the \textit{stringstrings} package.\par
%	Just as \cmd{\shread}, the \cmd{\shautoread} macro accepts two mandatory arguments that are treated in
%	the same way as before. The real magic happens when \TeX{} is reading the given file line by line.
%	Each line is stored in an internal macro, which is subsequently accessed by \textit{stringstrings}, extracting the first word of
% 	the line. To find out if the first word is an option or not, \textit{stringstrings} then searches this word for the '-' character.
%	If the word contains the '-' exactly once\footnote{I know that there are hundrets of options like \texttt{-show-all} or options with two leading dashes, like \texttt{-\hbox{}-shell-escape}, but to differ between all these options would again be nearly impossible.},
% the word is treated as \textit{the option} an is thus passed to 
%	\cmd{\shoutput} as the first argument. The rest of the line gets printed as text i.e. the second argument.\par
%	To this day, the autoread feature is experimental. It may mess up with the output of some programs and you maybe
%	not liking it at all. That's fine, because the macro is simply ment to be worth a try, if you are looking for an opportunity
%	to enhance the appearance of your output once more.\par\medskip
%	\noindent\textcolor{red}{Warning:} Using the \cmd{\shautoread} function has a huge impact on your 
%	\LaTeX{} build time, as \textit{stringstrings} somehow has a lot of things to do when manipulating
%	strings. Expect at least one minute per autoread, depending on the length of the output and your system performance.
%	
%
%	\subsubsection{Run and autoread a command (experimental)}
%	\DescribeMacro{\shautorun} Just like \cmd{\shrun}, \cmd{\shautorun} lets the user
%	execute a shell command and typeset its output. The only difference is that \cmd{\shautorun}
%	reads the temporary file via \cmd{\shautoread} -- described in section~\ref{subsubsec:autoread}
%
%	\subsubsection{Autopath \& autoformat (experimental)}
%	\paragraph{Autopath}\DescribeMacro{\shautopath}	In section~\ref{subsubsec:in_and_path} 
% 	we learned that \cmd{\shpath} can be used to get the current
%	directory we are working in. To automate things even more both, \cmd{\shread} and \cmd{\shautoread} can
%	use the current path by invoking \cmd{\shpath} on their own. As this functionality is turned off by default, you
%	can enable it by typing:
%	\begin{verbatim}
%	\shautopath{true}
%	\end{verbatim}
%	\noindent You can also turn it off again by passing \texttt{'false'} to this macro. Passing any other text may not result
%	in a warning or error, but will be visible in the log file.\par
%
%	\paragraph{Autoformat}\DescribeMacro{\shautopath} Another automation feature -- and 
%	probably the most useful one -- is the autoformat script that
%	is distributed with the package. As is, the script uses the \texttt{'sed'} stream editor to modify the temporary
%	file \texttt{shrun.tmp} and stores the result in \texttt{shrun-formatted.tmp}. Thus, the script can be used by
%	both, \cmd{\shrun} and \cmd{\shautorun} to improve the visual quality of your document. This feature is
%	turned off by default. You can enable it by typing:
%	\begin{verbatim}
%	\shautoformat{true}
%	\end{verbatim} 
%	\noindent However, \textcolor{red}{before doing so}, you should open the script \texttt{shreformat.sh} 
%	with your favourite text
%	editor and double check that it won't \textit{harm your computer}\footnote{You shouldn't use unknown scripts blindly}! 
%	You can also modify it according to your 
%	needs in order to get even better results. 
%
%	\subsubsection{Clear temporary files}\label{subsubsec:clearfiles}
%	\DescribeMacro{\shclearfiles} Most of the time you may want to delete the three temporary files
%	\texttt{shrun.tmp}, \texttt{shpath.tmp} and \texttt{shrun-formatted.tmp}
%	at the end of your \LaTeX{} build, as they are not really useful for anything
% 	but the \textit{shdoc} package. One can do so by using \cmd{\shclearfiles} at an
%	appropriate point within the document, e.g. before the end.\newpage
%
% \section{Examples}\label{sec:examples}
% 	\subsection{Various examples}
%		\subsubsection{Basic Sessions}
%\shpreset{blackwhite}
%\begin{sh}
%	\begin{verbatim}
%	\shpreset{blackwhite}
%	\begin{sh}
%	    \shuser{simon}
%	    \shmachine{linuxmint}
%	    \begin{shbox}
%	        \shline{}{cd Desktop/}
%	        \shline{Desktop/}{xsensors -help}
%	        \shoutput{}{}
%	        \shoutput{}{\underline{Options:}}
%	        \shoutput{}{}
%	        \shoutput{-f}{Display all temperatures in Fahrenheit.}
%	        \shoutput{-h}{Display this help text and exit.}
%	        \shoutput{-c}{+filename	Specify the libsensors configuration file.}
%	        \shoutput{-t}{+time		Specify the update time in number of seconds.}
%	        \shoutput{-v}{Display version number.}
%	    \end{shbox}
%	    \caption{The options of \textit{xsensors}}
%	    \label{sh:xsensor}
%	\end{sh}
%	\end{verbatim}
%	\shuser{simon}
%	\shmachine{linuxmint}
%	\begin{shbox}
%		\shline{}{cd Desktop/}
%		\shline{Desktop/}{xsensors -help}
%		\shoutput{}{}
%		\shoutput{}{\underline{Options:}}
%		\shoutput{}{}
%		\shoutput{-f}	{Display all temperatures in Fahrenheit.}
%		\shoutput{-h}	{Display this help text and exit.}
%		\shoutput{-c} {+filename	Specify the libsensors configuration file.}
%		\shoutput{-i} {+filename	Specify the image file to use as a theme.}
%		\shoutput{-t} {+time		Specify the update time in number of seconds.}
%		\shoutput{-v}	{Display version number.}
%	\end{shbox}
%	\caption{The options of \textit{xsensors}}
%	\label{sh:xsensor}
%\end{sh}
%
%
%\shpreset{default}
%\begin{sh}
%	\begin{verbatim}
%		\shpreset{default}
%		\begin{sh}
%		    \shuser{simon}
%		    \shmachine{linuxmint}
% 		    \begin{shbox}
%		        \shline{}{tex}
%   	        \shoutput{}{This is TeX, Version 3.14159265 (TeX Live 2014)}
%		            \shoutput{}{**\cmd{\relax}}
%   	        \shoutput{}{*Hello World!}
%   	        \shoutput{}{*\cmd{\bye}}
%           \end{shbox}
%		    \caption{Hello World in \TeX{}}
%		    \label{sh:TeX}
%		\end{sh}
%	\end{verbatim}
%	\shuser{simon}
%	\shmachine{linuxmint}
% 	\begin{shbox}
%	\shline{}{tex}
%   \shoutput{}{This is TeX, Version 3.14159265 (TeX Live 2014)}
%	\shoutput{}{**\cmd{\relax}}
%   \shoutput{}{*Hello World!}
%   \shoutput{}{*\cmd{\bye}}
% 	\end{shbox}
%	\caption{Hello World in \TeX{}}
%	\label{sh:TeX}
%\end{sh}
%\newpage
%		\subsubsection{Preset creation}\label{subsubsec:presetdef}
%
%	\shpresetdef{odd}{
%		\shpreset{blackwhite}
%		\shchangecolor{usernamecolor}{orange}
%		\shchangecolor{machinenamecolor}{orange}
%	}
%	\shpreset{odd}
%	\begin{sh}[th!]
%	\begin{verbatim}
%	\shpresetdef{odd}{
%	    \shpreset{blackwhite}
%	    \shchangecolor{usernamecolor}{orange}
%	    \shchangecolor{machinenamecolor}{orange}
%	}
%	\shpreset{odd}
%	\begin{sh}
%	    \shuser{doctorX}
%	    \shmachine{supercomputer}
%	    \begin{shbox}
%	        \shline{/home/doctorX/Documents}{exit}
%	    \end{shbox}
%	    \caption{Go away.}
%	    \label{sh:exit}
%	\end{sh}
%	\end{verbatim}
%		\shuser{doctorX}
%		\shmachine{supercomputer}
%		\begin{shbox}
%			\shline{/home/doctorX/Documents}{exit}
%		\end{shbox}
%		\caption{Go away.}
%		\label{sh:exit}
%	\end{sh}
%
%	\shpresetdef{mystyle}{
%		\shchangecolor{backgroundcolor}{white}
%		\shchangecolor{usernamecolor}{red}
%		\shchangecolor{machinenamecolor}{red}
%		\shchangecolor{separatorcolor}{RoyalBlue}
%		\shchangecolor{optioncolor}{orange!50!yellow}
%		\shchangesymbol{indicatorsymbol}{!}
%		\shchangesymbol{separatorsymbol}{$\geq$}
%	}
%	\shpreset{mystyle}
%	\begin{sh}
%	\begin{verbatim}
%		\shpresetdef{mystyle}{
%		    \shchangecolor{backgroundcolor}{white}
%		    \shchangecolor{usernamecolor}{red}
%		    \shchangecolor{machinenamecolor}{red}
%		    \shchangecolor{separatorcolor}{RoyalBlue}
%		    \shchangecolor{optioncolor}{orange!50!yellow}
%		    \shchangesymbol{indicatorsymbol}{!}
%		    \shchangesymbol{separatorsymbol}{$\geq$}
%		}
%
%		\begin{sh}
%		    \shuser{joe}
%		    \shmachine{joesraspian}%
%		    \begin{shbox}
%		        \shline{}{history}
%		        \shoutput{480}{rubber}
%		        \shoutput{481}{xsensors}
%		        \shoutput{482}{tracepath www.google.com}
%		        \shoutput{483}{whoami}
%		        \shoutput{484}{help}
%		        \shoutput{485}{exit}
%		    \end{shbox}
%		    \caption{History of my session}
%		    \label{sh:history}
%		\end{sh}
%	\end{verbatim}
%		\shuser{joe}
%		\shmachine{joesraspian}%
%		\begin{shbox}
%			\shline{}{history}
%			\shoutput{480}{rubber}
%			\shoutput{481}{xsensors}
%			\shoutput{482}{tracepath www.google.com}
%			\shoutput{483}{whoami}
%			\shoutput{484}{help}
%			\shoutput{485}{exit}
%		\end{shbox}
%		\caption{History of my session}
%		\label{sh:history}
%	\end{sh}\newpage
%	
%
%	\subsection{All the predefined presets}
%   \shpreset{default}
%\begin{sh}[th!]
%	\shuser{simon}
%	\shmachine{linuxmint}
%	\begin{shbox}
%		\shline{}{cd Desktop/}
%		\shline{Desktop/}{xsensors -help}
%		\shoutput{}{}
%		\shoutput{}{\underline{Options:}}
%		\shoutput{}{}
%		\shoutput{-f}	{Display all temperatures in Fahrenheit.}
%		\shoutput{-h}	{Display this help text and exit.}
%		\shoutput{-c} {+filename	Specify the libsensors configuration file.}
%		\shoutput{-i} {+filename	Specify the image file to use as a theme.}
%		\shoutput{-t} {+time		Specify the update time in number of seconds.}
%		\shoutput{-v}	{Display version number.}
%	\end{shbox}
%	\caption{The options of \textit{xsensors} -- \textit{default} or \textit{mint} preset}
%	\label{sh:minttest}
%\end{sh}
%   \shpreset{arrows}
%\begin{sh}[th!]
%	\shuser{simon}
%	\shmachine{linuxmint}
%	\begin{shbox}
%		\shline{}{cd Desktop/}
%		\shline{Desktop/}{xsensors -help}
%		\shoutput{}{}
%		\shoutput{}{\underline{Options:}}
%		\shoutput{}{}
%		\shoutput{-f}	{Display all temperatures in Fahrenheit.}
%		\shoutput{-h}	{Display this help text and exit.}
%		\shoutput{-c} {+filename	Specify the libsensors configuration file.}
%		\shoutput{-i} {+filename	Specify the image file to use as a theme.}
%		\shoutput{-t} {+time		Specify the update time in number of seconds.}
%		\shoutput{-v}	{Display version number.}
%	\end{shbox}
%	\caption{The options of \textit{xsensors} -- \textit{arrows} preset}
%	\label{sh:arrtest}
%\end{sh}\newpage
%   \shpreset{darkblue}
%\begin{sh}[th!]
%	\shuser{simon}
%	\shmachine{linuxmint}
%	\begin{shbox}
%		\shline{}{cd Desktop/}
%		\shline{Desktop/}{xsensors -help}
%		\shoutput{}{}
%		\shoutput{}{\underline{Options:}}
%		\shoutput{}{}
%		\shoutput{-f}	{Display all temperatures in Fahrenheit.}
%		\shoutput{-h}	{Display this help text and exit.}
%		\shoutput{-c} {+filename	Specify the libsensors configuration file.}
%		\shoutput{-i} {+filename	Specify the image file to use as a theme.}
%		\shoutput{-t} {+time		Specify the update time in number of seconds.}
%		\shoutput{-v}	{Display version number.}
%	\end{shbox}
%	\caption{The options of \textit{xsensors} -- \textit{darkblue} preset}
%	\label{sh:dbtest}
%\end{sh}
%   \shpreset{airy}
%\begin{sh}[th!]
%	\shuser{simon}
%	\shmachine{linuxmint}
%	\begin{shbox}
%		\shline{}{cd Desktop/}
%		\shline{Desktop/}{xsensors -help}
%		\shoutput{}{}
%		\shoutput{}{\underline{Options:}}
%		\shoutput{}{}
%		\shoutput{-f}	{Display all temperatures in Fahrenheit.}
%		\shoutput{-h}	{Display this help text and exit.}
%		\shoutput{-c} {+filename	Specify the libsensors configuration file.}
%		\shoutput{-i} {+filename	Specify the image file to use as a theme.}
%		\shoutput{-t} {+time		Specify the update time in number of seconds.}
%		\shoutput{-v}	{Display version number.}
%	\end{shbox}
%	\caption{The options of \textit{xsensors} -- \textit{airy} preset}
%	\label{sh:airtest}
%\end{sh}
%\shpreset{blackwhite}
%\begin{sh}[th!]
%	\shuser{simon}
%	\shmachine{linuxmint}
%	\begin{shbox}
%		\shline{}{cd Desktop/}
%		\shline{Desktop/}{xsensors -help}
%		\shoutput{}{}
%		\shoutput{}{\underline{Options:}}
%		\shoutput{}{}
%		\shoutput{-f}	{Display all temperatures in Fahrenheit.}
%		\shoutput{-h}	{Display this help text and exit.}
%		\shoutput{-c} {+filename	Specify the libsensors configuration file.}
%		\shoutput{-i} {+filename	Specify the image file to use as a theme.}
%		\shoutput{-t} {+time		Specify the update time in number of seconds.}
%		\shoutput{-v}	{Display version number.}
%	\end{shbox}
%	\caption{The options of \textit{xsensors} -- \textit{blackwhite} preset}
%	\label{sh:bwtest}
%\end{sh}
%	\newpage
%	\subsection{Automated command execution and formatting}\shpreset{default}
%	\subsubsection{Basic examples}
%
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \scriptsize
%	    \shread{avrdude -c usbasp -p attiny24}{avrdude-log.save}
%	    \caption{\texttt{avrdude} session, read from a file via \cmd{\shread}}
%	    \label{sh:avrdude_session}
%	\end{sh}
%	\end{verbatim}
%		\scriptsize
%		\shread{avrdude -c usbasp -p attiny24}{avrdude-log.save}
%		\caption{\texttt{avrdude} session, read from a file via \cmd{\shread}}
%		\label{sh:avrdude_session}
%	\end{sh}
%
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \shautoformat{false}
%	    \shrun{ifup --help}
%	    \caption{The help pages of \texttt{ifup}, standard \cmd{\shrun}}
%	    \label{sh:ifup}
%	\end{sh}
%	\end{verbatim}
%		\shrun{ifup --help}
%		\caption{The help pages of \texttt{ifup}, standard \cmd{\shrun}}
%		\label{sh:ifup}
%	\end{sh}
%
%
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \shrun{xsensor -help}
%	    \caption{A typo resulting in an error}
%	    \label{sh:error}
%	\end{sh}
%	\end{verbatim}
%		\shrun{xsensor -help}
%		\caption{A typo resulting in an error}
%		\label{sh:error}
%	\end{sh}
%
%	
%	\noindent As you can see the automatic execution of commands works 
%	fine\footnote{Note: In case you want to build this documentation on your own, you will need to run \texttt{tex shdoc.ins} to get the package file, as well as the file for the \texttt{avrdude} session-read example. Further, you may want to make sure to use a system where the given shell commands actually exist.}, although most of the tab characters in
%	session~\ref{sh:ifup} get
%	printed as dashes or other weird symbols. Thus, I recommend to at least use the autoformat script option permanently.
%	The redirection of the error stream in session~\ref{sh:error} also shows the expected result.
%
%
%	\subsubsection{Autoformat script before/after comparison}
%
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \shautoformat{false}
%	    \shautorun{xsensors -help}
%	    \caption{The options of xsensors before using the autoformat script}
%	    \label{sh:xsensors_noautof}
%	\end{sh}
%	\end{verbatim}
%		\shautoformat{false}
%		\shautorun{xsensors -help}
%		\caption{The options of xsensors before using the autoformat script}
%		\label{sh:xsensors_noautof}
%	\end{sh}
%
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \shautoformat{true}
%	    \shautorun{xsensors -help}
%	    \caption{The options of xsensors after using the autoformat script}
%	    \label{sh:xsensors_autof}
%	\end{sh}
%	\end{verbatim}
%		\shautoformat{true}
%		\shautorun{xsensors -help}
%		\caption{The options of xsensors after using the autoformat script}
%		\label{sh:xsensors_autof}
%	\end{sh}
%
%	As you can see in session~\ref{sh:xsensors_noautof} and~\ref{sh:xsensors_autof} the autoformat script
%	can really improve your output. However, xsensors is still an easy job for \textit{shdoc} and sometimes 
%	the \cmd{\shautorun} macro is not really the best way to run a command. At first, it's still experimental 
%	and due to the \textit{stringstrings} manipulation it can take a massive amount of time to build your document.
%	The second reason you might not always use autorun is, when commands output a large number of lines and the 
%	occuring options vary a lot in terms of length and style. In this case autorun is not likely to produce a nice output --
%	as seen in session~\ref{sh:gcc_noautof} and~\ref{sh:gcc_autof}.
%
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \tiny
%	    \shautoformat{false}
%	    \shrun{gcc --help}
%	    \caption{Help pages of gcc before autoformat, standard \cmd{\shrun}}
%	    \label{sh:gcc_noautof_noautorun}
%	\end{sh}
%	\end{verbatim}
%		\tiny
%		\shautoformat{false}
%		\shrun{gcc --help}
%		\caption{Help pages of gcc before autoformat, standard \cmd{\shrun}}
%		\label{sh:gcc_noautof_noautorun}
%	\end{sh}
%
%	\vspace*{-5mm}
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \tiny
%	    \shautoformat{false}
%	    \shautorun{gcc --help}
%	    \caption{Help pages of gcc before using the autoformat script}
%	    \label{sh:gcc_noautof}
%	\end{sh}
%	\end{verbatim}\vspace{-5mm}
%		\tiny
%		\shautoformat{false}
%		\shautorun{gcc --help}
%		\caption{Help pages of gcc before using the autoformat script}
%		\label{sh:gcc_noautof}
%	\end{sh}
%
%	\vspace*{-5mm}
%	\begin{sh}
%	\begin{verbatim}
%	\begin{sh}
%	    \tiny
%	    \shautoformat{true}
%	    \shautorun{gcc --help}
%	    \caption{Help pages of gcc after using the autoformat script}
%	    \label{sh:gcc_autof}
%	\end{sh}
%	\end{verbatim}\vspace{-5mm}
%		\tiny
%		\shautoformat{true}
%		\shautorun{gcc --help}
%		\caption{Help pages of gcc after using the autoformat script}
%		\label{sh:gcc_autof}
%	\end{sh}
% \newpage
% \addcontentsline{toc}{section}{List of Terminal Sessions}
% \phantomsection
% \listofsh\bigskip
% 
% \noindent\DescribeMacro{\listofsh}As the float environment supports automatic lists, you can use them with
% \textit{shdoc}, too. Just use \cmd{\listofsh} for that.
%
% \shclearfiles
%
% ^^A Implementation from here
%\StopEventually{\PrintIndex}
%
% \newpage
% \section{Implementation}\label{sec:implementation}
% This section describes the implementation of the \textit{shdoc} package and its
% features. The package was written as a \texttt{*.dtx} source file and therefore the
% package code begins with the following instruction:\par 
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% \subsection{Options}
% First of all, the package options for colouring and symbol options and their default values are defined. The options
% are then processed to make them available for the user.
%\begin{macro}{
%		color, symbol
%				}
%    \begin{macrocode}
\DeclareStringOption[gray!70]{backgroundcolor}
\DeclareStringOption[green!80!yellow]{usernamecolor}
\DeclareStringOption[green!80!yellow]{machinenamecolor}
\DeclareStringOption[RoyalBlue]{pathcolor}
\DeclareStringOption[RoyalBlue]{indicatorcolor}
\DeclareStringOption[green!80!yellow]{separatorcolor}
\DeclareStringOption[white!60!gray]{optioncolor}
\DeclareStringOption[black]{textcolor}
\DeclareStringOption[\$]{indicatorsymbol}
\DeclareStringOption[\~]{defaultpath}
\DeclareStringOption[@]{separatorsymbol}
\ProcessKeyvalOptions*
%    \end{macrocode}
%\end{macro}
%
% \subsection{Presets}\label{subsec:presetdef}
% Right after the option definitions the preset commands are defined. 
% Every preset is stored in a macro with the generic name \cmd{\sh@preset@NAME}, where
% \texttt{NAME} stands for the preset name.
% To make the presets better loadable for users \cmd{\shpreset} is defined
% to simply execute the package internal preset macro:
%
%\begin{macro}{\shpreset}
%    \begin{macrocode}
\def\shpreset#1{\csname sh@preset@#1\endcsname}%
%    \end{macrocode}    
%\end{macro}
% To simplify the creation of new presets a few macros are needed. The main command
% is \cmd{\shpresetdef}, which creates a new preset macro with the desired settings. 
% The macro calls \cmd{\shpreset\{default\}} at the beginning, so the inital settings of the new preset
% are the default settings of \textit{shdoc}.
%\begin{macro}{
%	\shpresetdef}
%    \begin{macrocode}
\def\shpresetdef#1#2{%
	\expandafter\gdef\csname sh@preset@#1\endcsname{\shpreset{default} #2}%
}%
%    \end{macrocode}
%\end{macro}
% Basically, every command can be used as the second argument of \cmd{\shpresetdef}, but
% most of them won't change any settings in \textit{shdoc}. The only useful macros in this
% context are those, who explicitly change a color, symbol or value within the package, namely
% \cmd{\shchange}, \cmd{\shchangecolor} and \cmd{\shchangesymbol}.
%
% \cmd{\shchange} has two arguments, where the first is the name of the parameter that
% should be changed and the second is the new value. Although there won't be an error,
% other names than those implemented by the package are not valid. The macro simply
% redefines the according parameter.
%\begin{macro}{\shchange}
%    \begin{macrocode}
\def\shchange#1#2{\expandafter\gdef\csname shdoc@#1\endcsname{#2}}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\shchangesymbol}
%\begin{macro}{\shchangecolor}
% \cmd{\shchangesymbol} and \cmd{\shchangecolor} are two other commands, that implement the exact same
% definition as \cmd{\shchange}. 
% Thus, these commands only exists for logical reasons. They simply redefine the 
% desired symbol or color.
%    \begin{macrocode}
\let\shchangesymbol\shchange%
\let\shchangecolor\shchange%
%    \end{macrocode}
%\end{macro}\end{macro}
%
% \noindent Since \cmd{\shpresetdef} calls \cmd{\shpreset\{default\}}, the default preset
% had to be defined manually via \cmd{\def}.
%\begin{macro}{\sh@preset@default}
%    \begin{macrocode}
\def\sh@preset@default{%
	\shchangecolor{backgroundcolor}{gray!70}%
	\shchangecolor{usernamecolor}{green!80!yellow}%
	\shchangecolor{machinenamecolor}{green!80!yellow}%
	\shchangecolor{pathcolor}{RoyalBlue}%
	\shchangecolor{indicatorcolor}{RoyalBlue}%
	\shchangecolor{separatorcolor}{green!80!yellow}%
	\shchangecolor{optioncolor}{white!60!gray}%
	\shchangecolor{textcolor}{black}%
	\shchangesymbol{indicatorsymbol}{\$}%
	\shchangesymbol{defaultpath}{\~}%
	\shchangesymbol{separatorsymbol}{@}%
}%
%    \end{macrocode}
%\end{macro}
% As the \textit{shdoc} package was initally ment to imitate the Linux Mint bash, the
% default preset is equal to the \textit{mint} style, which is defined right after the default preset:
%\begin{macro}{\sh@preset@mint}
%    \begin{macrocode}
\shpresetdef{mint}{\shpreset{default}}%
%    \end{macrocode}
%\end{macro}
%
% \noindent The second preset style is the ``arrows'' style, which is a dark color scheme with
% two arrows as the indicator symbol.
%\begin{macro}{\sh@preset@arrows}
%    \begin{macrocode}
\shpresetdef{arrows}{%
	\shchangecolor{usernamecolor}{red}%
	\shchangecolor{machinenamecolor}{green!80!yellow}%
	\shchangecolor{separatorcolor}{white}%
	\shchangecolor{indicatorsymbol}{$\gg$}%
	\shchangecolor{indicatorcolor}{green!80!yellow}%
	\shchangecolor{backgroundcolor}{black}%
	\shchangecolor{textcolor}{white}%
	\shchangecolor{optioncolor}{gray}%
}%
%    \end{macrocode}
%\end{macro}
%
% \noindent Another dark scheme is the ``darkblue'' preset, which defines a dark blue background color
% and more or less appropriate other colors. The definition of this preset is furthermore a
% nice example, how macros of other packages could also make sense within the \cmd{\shpresetdef} 
% command.
%\begin{macro}{\sh@preset@darkblue}
%    \begin{macrocode}
\shpresetdef{darkblue}{%
	\definecolor{shdarkblue}{RGB}{7,75,138}% xcolor syntax
	\shchangecolor{backgroundcolor}{shdarkblue}%	
	\shchangecolor{textcolor}{white}%
	\shchangecolor{separatorcolor}{white}%
	\shchangecolor{usernamecolor}{orange}%
	\shchangecolor{machinenamecolor}{orange}%
	\shchangecolor{pathcolor}{green!60!black}%
	\shchangecolor{optioncolor}{SkyBlue!80!black}%
}
%    \end{macrocode}
%\end{macro}
%
% For those, who print their documents with the black ink cartridge only there is the
% ``blackwhite'' preset. The definition sets the background and all the other colors to
% different versions of gray, black and white -- see the examples in section~\ref{sec:examples}.
%\begin{macro}{\sh@preset@blackwhite}
%    \begin{macrocode}
\shpresetdef{blackwhite}{%
	\shchangecolor{backgroundcolor}{gray!30}%	
	\shchangecolor{textcolor}{black}%
	\shchangecolor{separatorcolor}{black}%
	\shchangecolor{usernamecolor}{gray}%
	\shchangecolor{machinenamecolor}{gray}%
	\shchangecolor{pathcolor}{gray!50!black}%
	\shchangecolor{optioncolor}{white}%
	\shchangecolor{indicatorcolor}{white}%
}
%    \end{macrocode}
%\end{macro}
%
% The last and probably lightest preset is the ``airy'' preset with light blue and green elements.\par 
%\begin{macro}{\sh@preset@airy}
%    \begin{macrocode}
\shpresetdef{airy}{%
	\shchangecolor{backgroundcolor}{SkyBlue!15}%
	\shchangecolor{usernamecolor}{Emerald}%
	\shchangecolor{machinenamecolor}{Emerald}%
	\shchangecolor{pathcolor}{orange!70}%
	\shchangecolor{indicatorcolor}{orange!70}%	
	\shchangecolor{separatorcolor}{Emerald}%
	\shchangecolor{optioncolor}{Emerald!30}%
}
%    \end{macrocode}
%\end{macro}
%
% \subsection{Environment}
% After all the setting definitions above the actual environment for the 
% shell commands can be defined. The whole environment consists of a
% float environment with caption and label and one or more inner frameboxes, which
% are generated with the \textit{mdframed} package. Further there is a
% line number on the left side of every box. The number is defined as a
% standard \LaTeX\ counter and is initially set to 0.
%\begin{macro}{\shlinenumber}
%    \begin{macrocode}
\newcounter{shlinenumber}% def new counter
\setcounter{shlinenumber}{0}% set counter to 0
%    \end{macrocode}
%\end{macro}
%
% \noindent Since the outer environment is a float, a list name variable is 
% needed to make the name user-adjustable. There are two macros that
% implement this functionality: \cmd{\@shlistname} is the 
% name variable that holds the current value of the list name.
% \cmd{\shlistname} is a user command, that redefines the
% name according to the users' input. After the definition the
% standard value is set.
%\begin{macro}{\shlistname}
%    \begin{macrocode}
\let\@shlistname\relax%
\gdef\shlistname#1{\gdef\@shlistname{#1}}%
\shlistname{List of Terminal Sessions}% set default value
%    \end{macrocode}
%\end{macro}
%
% \subsubsection{Float environment}
% Now, the whole float environment is defined. The float is named
% \cmd{\sh} and uses the plain float style. The float name is stored
% in a variable, which is implemented in the same way as the list name.
% Afterwards the name is set. The caption is set to be at the bottom of the
% float and a macro for the generation of the ``List of Terminal Sessions''
% is defined.
%\begin{macro}{\sh}
%    \begin{macrocode}
\newfloat{sh}{tbph}{lsh}% define new float
\restylefloat*{sh}%
\floatstyle{plain}% set style

\let\@shfloatname\relax%
\gdef\shfloatname#1{\gdef\@shfloatname{#1}}%
\shfloatname{Terminal~Session}% default float name
\floatname{sh}{\@shfloatname}%

\captionsetup[sh]{position=bottom}% 
\def\listofsh{\listof{sh}{\@shlistname}}%
%    \end{macrocode}
%\end{macro}
%
% \subsubsection{Framebox}
% For each session the user and machine values can and must be set, but they could also be 
% set at the beginning of a document to be valid for every terminal session. In the same manner 
% as before, two name variables and their setup commands are defined. The default value for the username is \texttt{root},
% whereas the default for the machine is \texttt{linux}.
%\begin{macro}{
% 		\shuser,
%		\shmachine}
%    \begin{macrocode}
\let\@shuser\relax%
\let\@shmachine\relax%
\def\shuser#1{\gdef\@shuser{#1}}%
\def\shmachine#1{\gdef\@shmachine{#1}}%
\def\@default@shuser{root}%
\def\@default@shmachine{linux}%
\shuser{\@default@shuser}%
\shmachine{\@default@shmachine}%
%    \end{macrocode}
%\end{macro}
%
% 
%\begin{macro}{\sh@lnscale}
%\begin{macro}{\sh@fontcheck}
% Within the framebox \cmd{\shbox} -- which is defined at the very end of the source code -- 
% there are two commands: \cmd{\shline} for user inputs and \cmd{\shoutput} for shell outputs.
% Each of these macros prints the line number onto the left side of the box first.
% The number is relatively scaled down by a factor of $0.7$, which is stored in \cmd{\sh@lnscale}. 
% However, if the overall font size gets too small (i.e. when using \cmd{\scriptsize}, \cmd{\tiny}, \dots)
% this factor is increased to prevent warnings from the \textit{relscale} package, which does the line
% number scaling. The macro that acomplishes this automatic scaling is \cmd{\sh@fontcheck}.
%
%    \begin{macrocode}
\def\sh@lnscale{.7}% default number scaling
\def\sh@fontcheck{% if fontsize < 6pt
	\ifthenelse{\f@size<6}{%
		\gdef\sh@lnscale{1}% factor = 1
	}{% elif fontsize < 8pt
		\ifthenelse{\f@size<8}{%
			\gdef\sh@lnscale{.84}% factor = 0.84
		}{% else: nothing
		}%
	}%	
}%
%    \end{macrocode}
%\end{macro}\end{macro}
%
%\begin{macro}{\shline}
%
%	In order to keep the text from mixing up with the line numbers a hangindent is required.
%	The indent is set according to the width of the linenumbers, so at the beginning of the
%	\cmd{\shline} definition \cmd{\sh@linenumberwidth} is defined.\par
%	Within a \cmd{\shline} the font is set to typewriter style, the font size gets checked and
% 	the scaling factor for the line numbers is adjusted. Starting without any indent, \cmd{\shline}
%	determines if a leading 0 for the line number is needed. If so, the 0 is added, the number gets typeset
%	and the width of the line number is stored. After the number a small horizontal space creates the
%	distance, that's needed between the number and the following username and machine values. They are
% 	typeset in their dedicated colors right after the appropriate hangindent is set. A small if-else construct
%	checks if the first argument of the macro is empty and acts accordingly -- see section~\ref{subsubsec:in_and_path}.
%	At the end, the line number is incremented to be ready for the next line.
%    \begin{macrocode}
\newlength{\sh@linenumberwidth}%
\long\def\shline#1#2{
	\ttfamily\sh@fontcheck\noindent%
	\ifnum\value{shlinenumber}<10%
		\textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}0\theshlinenumber}%
		\settowidth{\sh@linenumberwidth}{%
			\relscale{\sh@lnscale}0\theshlinenumber%
		}%
	\else%
		\textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}\theshlinenumber}%
		\settowidth{\sh@linenumberwidth}{%
			\relscale{\sh@lnscale}\theshlinenumber%
		}%
	\fi\hspace{\sh@linenumberwidth}%
	\hangindent=2\sh@linenumberwidth%
	\textcolor{\shdoc@usernamecolor}{\@shuser}%
	\textcolor{\shdoc@separatorcolor}{\shdoc@separatorsymbol}%
	\textcolor{\shdoc@machinenamecolor}{\@shmachine}%
	\ \ifx&#1&%
		\textcolor{\shdoc@pathcolor}{\shdoc@defaultpath\ }%
		\textcolor{\shdoc@indicatorcolor}{\shdoc@indicatorsymbol}
	\else%
		\textcolor{\shdoc@pathcolor}{#1\ }%
		\textcolor{\shdoc@indicatorcolor}{\shdoc@indicatorsymbol}%
	\fi\ \textcolor{\shdoc@textcolor}{#2}%
	\stepcounter{shlinenumber}\par
}
%    \end{macrocode}
%\end{macro}
%-----------------------------------------------------------------
%
%\begin{macro}{\shoutput}
%
% The \cmd{\shoutput} command is very similar to its pendant, but has other requirements, too.
% As there may be optionboxes within an output line, the hangindent handling needs to be adjusted.
% Thus, a new length \cmd{\sh@optionboxwidth} is added.\par
% Just as before, the font is set to typewriter style and the size is checked. The line number gets
% typeset, the horizontal space is added and the hangindent is set. Again a small if-else construct checks
% the first argument. If the argument is empty, the width of the optionbox is set to zero and the box is
% suppressed. Otherwise, a framed colorbox is used to create the optionbox and the width of 
% the whole box is stored. The stored value is then used to increase the hangindent appropriately.
%    \begin{macrocode}
\newlength{\sh@optionboxwidth}
\long\def\shoutput#1#2{
	\ttfamily\sh@fontcheck\noindent%
	\ifnum\value{shlinenumber}<10%
		\textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}0\theshlinenumber}%
		\settowidth{\sh@linenumberwidth}{%
			\relscale{\sh@lnscale}0\theshlinenumber%
		}%
	\else%
		\textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}\theshlinenumber}%
		\settowidth{\sh@linenumberwidth}{%
			\relscale{\sh@lnscale}\theshlinenumber%
		}%
	\fi\hspace{\sh@linenumberwidth}%
	\hangindent=2\sh@linenumberwidth%
	\ifx&#1&%
		\textcolor{\shdoc@textcolor}{#2}\stepcounter{shlinenumber}%
		\settowidth{\sh@optionboxwidth}{0cm}%
	\else%	
		\fcolorbox{\shdoc@optioncolor}%
			{\shdoc@optioncolor}{\textcolor{\shdoc@textcolor}{[#1]}}\ %
		\settowidth{\sh@optionboxwidth}{%
			\fcolorbox{\shdoc@optioncolor}%
				{\shdoc@optioncolor}{\textcolor{\shdoc@textcolor}{[#1]}}\ }%
		\addtolength{\hangindent}{\sh@optionboxwidth}%	
		\textcolor{\shdoc@textcolor}{#2}\stepcounter{shlinenumber}%	
	\fi\par%
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\shautoformat, \shautopath}
%	The autoformat and autopath macros that enable or disable the corresponding functionality
%	are defined as a macro that holds whatever text the user passes as an argument. If the 
% 	given text is valid is decided later through an if-else statement.
%    \begin{macrocode}
\let\sh@autoformat\relax%
\def\shautoformat#1{\gdef\sh@autoformat{#1}}%
\shautoformat{false}%

\let\sh@autopath\relax%
\def\shautopath#1{\gdef\sh@autopath{#1}}%
\shautopath{false}%
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\shpath}
% 	Sometimes it's desired to get the path of the actual working directory. \cmd{\shpath}
%	prints the current path by capturing the output of the Linux-specific \textit{print working
% 	directory} '\texttt{pwd}' command. The output is further stored in the temporary file \texttt{shpath.tmp}.
%    \begin{macrocode}
\def\shpath{%
	\immediate\write18{pwd >shpath.tmp 2>&1}%
	\newread\sh@pathfile%
	\openin\sh@pathfile=shpath.tmp%
	\endlinechar=-1%
	\readline\sh@pathfile to \sh@path%
	\sh@path%
	\closein\sh@pathfile		
}
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\shread}
%	\textit{shdoc} is able to read text files, that contain the output of a shell command, via
%	the \cmd{\shread} macro. At first a new readfile needs to be opened. The endlinechar is set
% 	to $-1$, so it won't appear in the document. After that a new \cmd{\shbox} is started and a
%	loop reads the lines from the text file. A few ifs are used to check if the first argument 
%	of \cmd{\shread} is empty and to check if autopath is enabled.
%
%    \begin{macrocode}
\def\shread#1#2{%
	\newread\sh@inputfile%
	\openin\sh@inputfile=#2%
	
	\endlinechar=-1% hide the endlinechar (-1 is invalid, thus not printed)
	\begin{shbox}%
		\ifthenelse{\equal{#1}{}}{}% empty: do not print
		{%
			\ifthenelse{\equal{\sh@autopath}{true}}{%
				\shline{\shpath}{#1}%
			}{%
			\ifthenelse{\equal{\sh@autopath}{false}}{}%
			{\typeout{-----------------------------------------------}%
				\typeout{ Package shdoc info: I don't know what you}%
				\typeout{ mean when passing '\sh@autopath' to autopath}%
				\typeout{ and I'm going to ignore it and restore the}%
				\typeout{default 'false'} %
				\typeout{-----------------------------------------------}%
				\shautopath{false}}% 
			\shline{}{#1}%
		}%
	}
	\loop\unless\ifeof\sh@inputfile%
	\readline\sh@inputfile to \sh@fileline%
	\ifeof\sh@inputfile% again check of eof prevents last blank line
	\else%
	\shoutput{}{\sh@fileline}%			
	\fi%
	\repeat%
\end{shbox}%
\closein\sh@inputfile%
}
%    \end{macrocode}
%\end{macro}
%
%
%\begin{macro}{\shrun}
%	\cmd{\shrun} lets the user specify a command that is passed to the 
% 	system shell. Its output is stored in a file -- and possibly preformatted by
% 	the reformat script -- and is then read by \cmd{\shread}. An if statement checks
% 	if autoformat is enabled.
%
%    \begin{macrocode}
\def\shrun#1{%
	\ifthenelse{\equal{\sh@autoformat}{true}}{%
		\immediate\write18{#1 >shrun.tmp 2>&1}%
		\immediate\write18{./shreformat.sh}%	
		\shread{#1}{shrun-formatted.tmp}%
	}{%
	\ifthenelse{\equal{\sh@autoformat}{false}}{}%
	{\typeout{-----------------------------------------------}%
	\typeout{ Package shdoc info: I don't know what you}% 
	\typeout{ mean when passing '\sh@autoformat' to autoformat}% 
	\typeout{ and I'm going to ignore it and restore the}%
	\typeout{default 'false'}% 
	\typeout{-----------------------------------------------}%
	\shautoformat{false}}%
	\immediate\write18{#1 >shrun.tmp 2>&1}%
	\shread{#1}{shrun.tmp}%
}%
}%
%    \end{macrocode}
%\end{macro}
%
%
%\begin{macro}{\shautoread}
%	Autoread is an experimental feature of \textit{shdoc} that lets the package detect possible
%	shell options and typeset them within an optionbox. The read functionality is the same as
%	in \cmd{\shread}, however \textit{stringstrings} is used to modify the read file lines.
%	At first the first word is extracted from the line via \cmd{\getnextword}. After that, 
%	the word is searched for the '-' character. If exactly one is found, the word is typeset
%	within an optionbox. The amount of chars that the word consists of is then removed from the
%	complete line and the rest of the line gets typeset as text.
%
%    \begin{macrocode}
\def\shautoread#1#2{%
	\newread\sh@inputfile%
	\openin\sh@inputfile=#2%
	\endlinechar=-1%
	\begin{shbox}
		\ifthenelse{\equal{#1}{}}{%
		}{%
		\ifthenelse{\equal{\sh@autopath}{true}}{%
			\shline{\shpath}{#1}%
		}{%
		\ifthenelse{\equal{\sh@autopath}{false}}{}%
		{\typeout{-----------------------------------------------}%
			\typeout{ Package shdoc info: I don't know what you}% 
			\typeout{ mean when passing '\sh@autopath' to autopath}% 
			\typeout{ and I'm going to ignore it and restore the}%
			\typeout{default 'false'}% 
			\typeout{-----------------------------------------------}%
			\shautopath{false}}%
		\shline{}{#1}%
	}%
}%
\loop\unless\ifeof\sh@inputfile%
	\readline\sh@inputfile to \sh@fileline%
	\ifeof\sh@inputfile%
\else%
	\getnextword[e]{\sh@fileline}%
	\findchars[q]{\thestring}{-}%
	\ifthenelse{\equal{\theresult}{1}}{%
	\shoutput{\thestring}%
		{\stringlength[e]{\thestring}\gobblechars[v]{\sh@fileline}{\theresult}}%	
}{%
	\shoutput{}{\sh@fileline}%				
}%			
\fi%
\repeat%
\end{shbox}%
\closein\sh@inputfile%
}%
%    \end{macrocode}
%\end{macro}
%
%
%\begin{macro}{\shautorun}
%	\cmd{\shautorun} implements the same functionality as \cmd{\shrun}, but invokes
%	autoread to read the file.
%
%    \begin{macrocode}
\def\shautorun#1{
	\ifthenelse{\equal{\sh@autoformat}{true}}{%
		\immediate\write18{#1 >shrun.tmp 2>&1}%
		\immediate\write18{./shreformat.sh}%	
		\shautoread{#1}{shrun-formatted.tmp}%
	}{%	
	\ifthenelse{\equal{\sh@autoformat}{false}}{}%
	{\typeout{-----------------------------------------------}%
		\typeout{ Package shdoc info: I don't know what you}%
		\typeout{ mean when passing '\sh@autoformat' to autoformat}% 
		\typeout{ and I'm going to ignore it and restore the}%
		\typeout{default 'false'}%
		\typeout{-----------------------------------------------}%
		\shautoformat{false}}%
	\immediate\write18{#1 >shrun.tmp 2>&1}%
	\shautoread{#1}{shrun.tmp}%
}%
}
%    \end{macrocode}
%\end{macro}
%
%
%\begin{macro}{\shclearfiles}
%	\cmd{\shclearfiles} removes all the temporary files by calling the shell command '\texttt{rm}'.
%    \begin{macrocode}
\def\shclearfiles{
	\immediate\write18{rm shrun.tmp; rm shrun-formatted.tmp; rm shpath.tmp}	
}
%    \end{macrocode}
%\end{macro}
%
% \noindent Finally, the mdframed box is defined through the environment definition command of the
% \textit{mdframed} package. The frameline color is white and the default backgroundcolor
% is set. Further, the linecounter is set to 1, when the \cmd{\shbox} environment is started.
%\begin{macro}{\shbox}
%    \begin{macrocode}
\newmdenv[linecolor=white,backgroundcolor=\shdoc@backgroundcolor,
settings=\setcounter{shlinenumber}{1}]{shbox}
%    \end{macrocode}
%\end{macro}
%    \begin{macrocode}
\makeatother
%</package>
%    \end{macrocode}
%\Finale
%