Debian Codegraph @

texmf-dist/source/latex/shdoc/shdoc.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright 2016 Simon M. Laube
4 %
5 % This work may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either version 1.3
7 % of this license or (at your option) any later version.
8 % The latest version of this license is in
9 % http://www.latex-project.org/lppl.txt
10 % and version 1.3 or later is part of all distributions of LaTeX
11 % version 2005/12/01 or later.
12 %
13 % This work has the LPPL maintenance status `author maintained'.
14 %
15 % The Current Maintainer of this work is S. M. Laube
16 %
17 % \fi
18 %
19 %\iffalse
20 %<package>\NeedsTeXFormat{LaTeX2e}
21 %<package>\ProvidesPackage{shdoc}[2016/09/04 v2.1b Package for documenting shell operations]
22 %<package>\RequirePackage[dvipsnames]{xcolor}
23 %<package>\RequirePackage{float}
24 %<package>\RequirePackage{caption}
25 %<package>\RequirePackage{mdframed}
26 %<package>\RequirePackage{kvoptions}
27 %<package>\RequirePackage{relsize}
28 %<package>\RequirePackage{stringstrings}
29 %<package>\RequirePackage{ifthen}
30 %<package>\makeatletter
31 %
32 %
33 %<*internal>
34 \iffalse
35 %</internal>
36 %<*readme>
37 Copyright 2016 Simon M. Laube
38
39 This work may be distributed and/or modified under the
40 conditions of the LaTeX Project Public License, either version 1.3
41 of this license or (at your option) any later version.
42 The latest version of this license is in
43 http://www.latex-project.org/lppl.txt
44 and version 1.3 or later is part of all distributions of LaTeX
45 version 2005/12/01 or later.
46
47 This work has the LPPL maintenance status `author maintained'.
48
49 The Current Maintainer of this work is S. M. Laube
50
51 The shdoc package provides a simple, though fancy, float
52 environment that can be used to document operations or command
53 executions of a terminal session on a shell.
54
55 The current version of the package is v2.1b.
56
57 To create the package (*.sty) from source open a command line prompt,
58 change to the package directory and type
59
60 tex shdoc.ins
61
62 Afterwards you can generate the package documentation by typing
63
64 (pdf)latex shdoc.dtx
65
66 Be aware, that the shdoc package is using Unix/Linux specific shell
67 commands within the documentation. Thus, you may not be able to build
68 the documentation on your system. For security reasons, make sure that
69 you do not execute unknown shell scripts -- that are distributed with this
70 or other packages -- blindly. Further, you will need to enable `write18'
71 to build the documentation successfully.
72 %</readme>
73 %This is an example file that is needed to compile the manual
74 %The right file is generated by the docstrip utility
75 %<*avr>
76
77 avrdude: AVR device initialized and ready to accept instructions
78
79 Reading | ################################################## | 100% 0.01s
80
81 avrdude: Device signature = 0x1e910b
82
83 avrdude: safemode: Fuses OK (H:FF, E:DF, L:E2)
84
85 avrdude done. Thank you.
86
87 %</avr>
88 %
89 %<*internal>
90 \fi
91 %</internal>
92
93
94
95 %<*driver>
96 \documentclass[a4paper, 10pt]{ltxdoc}
97 \usepackage{shdoc}
98 \usepackage[utf8]{inputenc}
99 \usepackage[T1]{fontenc}
100 \usepackage{graphicx}
101 \usepackage{tikz}
102 \EnableCrossrefs
103 \CodelineIndex
104 \RecordChanges
105 \usepackage[colorlinks=true,linkcolor=black,urlcolor=blue,bookmarks=true]{hyperref}
106 \begin{document}
107 \DocInput{shdoc.dtx}
108 \end{document}
109 %</driver>
110 % \fi
111 %
112 % \CheckSum{0}
113 %
114 % \changes{v1.0}{2015/03/10}{Initial version}
115 % \changes{v1.1}{2015/04/06}{Formatting changes}
116 % \changes{v1.2}{2015/05/20}{Background color changed globally}
117 % \changes{v2.0}{2015/08/10}{Added package options as kv-list: colors and symbols}
118 % \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}
119 % \changes{v2.1a}{2016/08/27}{Small changes in the documentation}
120 % \changes{v2.1b}{2016/09/04}{Changes in the documentation yet again}
121 %
122 % \GetFileInfo{\jobname.sty}
123 %
124 % \DoNotIndex{}
125 %
126 %\def\dfcol#1{\raisebox{-5pt}{\tikz{\node[rectangle,draw=#1,fill=#1]{#1};}}}
127 %
128 %\title{The \textit{shdoc} package -- Manual for version~\fileversion, \filedate}
129 %\author{Simon Michael Laube \\ \texttt{[email protected]}}
130 %\date{}
131 %
132 %\maketitle
133 %
134 %\shuser{simon}
135 %\shmachine{linuxmint}
136 % \begin{shbox}
137 % \shline{}{tex}
138 % \shoutput{}{This is TeX, Version 3.14159265 (TeX Live 2015)}
139 % \shoutput{}{**\cmd{\relax}}
140 % \shoutput{}{*Hello World!}
141 % \shoutput{}{*\cmd{\bye}}
142 % \end{shbox}
143 % \begin{abstract}
144 % \noindent The \textit{shdoc} packages helps documenting commandline actions in
145 % a fancy way. It tries to imitate the look and feel of the original shell prompt
146 % while offering a wide range of personalization options.
147 % \end{abstract}
148 %
149 %\tableofcontents
150 %
151 % \section{Introduction}
152 %
153 % Many people who use \LaTeX\ and do a bit of coding in other languages have used
154 % \LaTeX's \textit{listings} package at least once. However, when me and my colleague
155 % wrote the documentation of our diploma project in 2015, we stumbled across a ``problem''\footnote{obviously it's not a
156 % real problem, but we wanted something more shell-specific} with
157 % \textit{listings}. A lot of command line scripting had to be done for our project to configure a Raspberry Pi B+ and those
158 % actions needed to be documented. \textit{listings} seemed to be the wrong package to look for, so we wrote our own.
159 % At first there were few small macros that we referred to as \textit{bashdoc} -- this was
160 % version 1.0. Later the macros got a bit more complex and we simply threw away the \textit{ba} part of \textit{bashdoc},
161 % that's how the \textit{shdoc} package was born. The basic idea somehow
162 % stayed the same since the very first draft, but the package is much more applicable now.\par
163 %
164 % I hope that \textit{shdoc} fits your application as it fitted ours. If there are any serious problems, feel free to
165 % send me an email\footnote{Please do not send spam mails of any kind. Plain text email format would be appreciated}.
166 % Moreover, I do not guarantee full compatibility with other packages and different operating systems.
167 % The package is distributed under the \LaTeX\ Project
168 % Public License version 1.3.\par
169 %
170 % \section{Acknowledgement}
171 %
172 % At this point I would like to thank \textit{Timm Severin} for his active feedback concerning problems and
173 % ideas about the package.
174 % 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.
175 % Thank you very much!
176 % \newpage
177 % \section{User commands}
178 % \textit{shdoc} implements user commands that allow one to typeset the content/commands
179 % of a command line session appropriately. Further there are macros to
180 % create and modify styles and appearance of the final output, as well as automated functions
181 % that let the user execute commands via \textit{shdoc} and typeset their output immediately.\par
182 %
183 % \subsection{Package inclusion and options}
184 % Just like every \LaTeX\ package, \textit{shdoc} can be included using the standard
185 % \cmd{\usepackage} command:
186 % \begin{quote}
187 % \cmd{\usepackage\oarg{options}\{shdoc\}}
188 % \end{quote}
189 %
190 % Since version 2.0 \textit{shdoc} supports several package options to make the environment more
191 % adjustable for users. The available options are described in detail in the following
192 % sections.
193 %
194 %
195 % \subsection{Color and style management}\label{subsec:style}
196 % The shbox environment uses plenty of \textit{different} colors and symbols, which can be adjusted through
197 % optional package arguments or macros within the document. Thus, you can either specify the color at the package
198 % inclusion in the preamble or just before your session in the document.
199 %
200 % \DescribeMacro{\shchange}
201 % To modify the appearance of shell sessions within your document one can use three different
202 % commands. The essential macro is \cmd{\shchange\marg{<name>} \marg{<new value>}}, which lets you specify a new value for every
203 % existing package option. Basically this command is all you need, but it is not recommended to use it for style changes.
204 % As mentioned there are two more macros, namely \cmd{\shchangecolor} and
205 % \cmd{\shchangesymbol}. The reason you should use these two for style changes is
206 % simply because of enhanced readability of your code. Anyone who reads your source will be able to tell what
207 % change you made at the first glimpse -- that is mainly important when defining presets,
208 % see section~\ref{subsubsec:presets}. However, the commands all work the same as the latter
209 % two are exact copies
210 % of \cmd{\shchange}. Here are some examples of style changes:%
211 % \begin{verbatim}
212 % \usepackage[backgroundcolor=white,indicatorsymbol=$+$]{shdoc}
213 % or
214 % \shchangecolor{backgroundcolor}{white}
215 % \shchangesymbol{indicatorsymbol}{$+$}
216 %
217 %
218 % \usepackage[usernamecolor=blue!70]{shdoc}
219 % or
220 % \shchange{usernamecolor}{blue!70} % works, but isn't recommended
221 % \end{verbatim}
222 %
223 % \noindent Be aware that specifying style settings as a package option always sets the style for the whole
224 % document, unless the settings are changed again via \cmd{\shchange}.
225 %
226 %
227 % \subsubsection{Colors}
228 % Table~\ref{tab:color_var} shows the package-specific
229 % names of all the colors, their default value and where they are used. Every color is specified using a key-value
230 % element as an optional package argument. If no argument is given for a specific color the default value is used.
231 %
232 %
233 % \begin{table}[tbh!]
234 % \centering\small
235 % \begin{tabular}{lll}
236 % Name & Description & Default color \\\hline
237 % backgroundcolor & color of the environment background & \dfcol{gray!70}\\
238 % usernamecolor & color of the username&\dfcol{green!80!yellow}\\
239 % machinenamecolor & color of the machine-name&\dfcol{green!80!yellow}\\
240 % indicatorcolor & color of the indicator symbol&\dfcol{RoyalBlue}\\
241 % separatorcolor & color of the user-machine separator symbol&\dfcol{green!80!yellow}\\
242 % pathcolor & color of the current path& \dfcol{RoyalBlue}\\
243 % optioncolor & color of the little option box&\dfcol{white!60!gray}\\
244 % textcolor & color of the rest of the text& \dfcol{black}\\
245 % \end{tabular}
246 % \caption{Adjustable colors of the shbox environment}
247 % \label{tab:color_var}
248 % \end{table}
249 %
250 %
251 % \subsubsection{Symbols}
252 % In total, only two symbols can be changed in the \textit{shdoc} package.
253 % Table~\ref{tab:symbol_var} shows their name, default value and description. Just as the
254 % colors, every symbol is changed using a key-value element as an optional
255 % package argument. If no arguments are given, the default values are used.
256 %
257 %
258 % \begin{table}[tbh!]
259 % \centering\small
260 % \begin{tabular}{llc}
261 % Name & Description & Default symbol \\\hline
262 % indicatorsymbol & separates user input and displayed path & \$\\
263 % separatorsymbol & separates user- and machine-name& @\\
264 % \end{tabular}
265 % \caption{Adjustable symbols of the shbox environment}
266 % \label{tab:symbol_var}
267 % \end{table}
268 % \noindent Please pay attention, that the @'s \textit{catcode} is changed to letter internally. Thus,
269 % you can use @ directly:
270 % \begin{verbatim}
271 % \shchangesymbol{separatorsymbol}{@}
272 % \end{verbatim}
273 %
274 %
275 % \subsubsection{Appearance and presets}\label{subsubsec:presets}
276 % As described above, \textit{shdoc} has some settings that can be
277 % changed by the user. Some setting values have been tested and
278 % stored as a preset that a user can easily load. Further, users are able to
279 % create their own presets via built-in commands.\par
280 %
281 % \DescribeMacro{\shpreset}
282 % One can easily load a preset with \cmd{\shpreset\marg{<name>}} by using the preset's name
283 % as an argument to that macro. When a preset has been loaded it is valid for every
284 % new \textit{shbox} environment afterwards, until the \cmd{\shpreset} macro is invoked
285 % again.\par
286 % \DescribeMacro{\shpresetdef} Most of the time, users might want to create their own styles,
287 % which can be achieved by defining a new preset via \cmd{\shpresetdef\marg{<name>}\marg{<def>}}. The command has two
288 % mandatory arguments: The first one is the desired preset-name and the second one is the
289 % preset definition. For example one can use:
290 % \begin{quote}
291 % \verb|\shpresetdef{useless}{\relax}|
292 % \end{quote}
293 % and is then able to apply the preset by calling:
294 % \begin{quote}
295 % \verb|\shpreset{useless}|
296 % \end{quote}
297 % \par
298 % \noindent A preset definition basically exists of multiple style changes, as described at the beginning of
299 % section~\ref{subsec:style}. For further information about preset definitions, please have a look
300 % at all the examples in section~\ref{subsubsec:presetdef} and section~\ref{subsec:presetdef}.
301 % Please also note that every new preset definition
302 % is based on the default preset, as \cmd{\shpresetdef} invokes \cmd{\shpreset\{default\}} prior to the definition.\par
303 %
304 %
305 % Several presets have been defined by the author and are included in the \textit{shdoc} package.
306 % One can use them by calling the \cmd{\shpreset\marg{name}} command with the name of the desired
307 % preset. The following list shows the appearance and name of the predefined presets -- for visuals
308 % see section~\ref{sec:examples}:
309 %
310 % \begin{description}
311 % \item[default/mint] The default preset. It implements a gray background theme
312 % with light gray option boxes, light green user- and machine-name and a blue path value.
313 %
314 % \item[arrows] Not recommended for printed documents. Implements a black background theme
315 % with gray option boxes, red username, white separator, light green machine-name, blue path
316 % and two arrows as an indicator symbol. The rest of the text is white, too.
317 %
318 % \item[darkblue] Implements a dark blue background theme with white text, light blue option
319 % boxes, orange user- and machine-name and a green path value.
320 %
321 % \item[airy] A light colored style. Implements a light blue background theme with cyan option
322 % boxes and user- \& machine-name, as well as light orange path value and black text.
323 %
324 % \item[blackwhite] Best for non-color prints. Implements a light gray background theme with white option
325 % boxes, black text, darker gray user- and machine-name and a dark gray path value.
326 % \end{description}
327 %
328 %
329 % \subsection{The environment}\label{subsec:environment}
330 % Basically a complete terminal session consists out of two environments that contain the
331 % necessary information that is used to typeset the session.
332 % \DescribeMacro{\sh} The outer environment is named \cmd{\sh} and basically acts as the
333 % float environment that could contain one or more so called \cmd{\shbox}es.
334 % \DescribeMacro{\shbox} Every \cmd{\shbox} contains in- and output lines of the terminal,
335 % with information provided by the user. The following code shows a brief overview of the
336 % possible and necessary commands:\par
337 % \begin{verbatim}
338 % \shpreset{mint}
339 % \begin{sh}
340 % \shuser{simon}
341 % \shmachine{linuxmint}
342 % \begin{shbox}
343 % \shline{}{cd Desktop/}
344 % \shline{Desktop/}{whoami}
345 % \shoutput{}{simon}
346 % \end{shbox}
347 % \end{sh}
348 % \end{verbatim}
349 %
350 % \subsubsection{Metadata}
351 % \DescribeMacro{\shuser} At least once before an occurrence of a \cmd{\shbox},
352 % the user- and machine-name should be specified. \DescribeMacro{\shmachine}
353 % They are set globally and thus are valid for
354 % every \cmd{\shbox} that follows the macro call. If no user and machine values are
355 % specified, the defaults user:\texttt{root} and machine:\texttt{linux} are used.\par
356 %
357 % \subsubsection{Shell input \& path handling}\label{subsubsec:in_and_path}
358 % \DescribeMacro{\shline}
359 % Within the \cmd{\shbox} there are only two valid commands^^A
360 % \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
361 % is basically the users' input, the executed command or an arbitrary line; and \cmd{\shoutput},
362 % which is ment to be the machine output.\cmd{\shline} has two mandatory arguments, where the first one is the path value
363 % and the second one is the command that's
364 % about to be run.\par
365 % There are several possibilities to handle the path value. First of all, you can leave the first argument empty,
366 % which will force \cmd{\shline} to print the \textit{default path}, namely \textasciitilde.
367 % \DescribeMacro{defaultpath}
368 % As one may want to
369 % have a different default path, it can be changed by either passing a key-value element of the form
370 % \verb|defaultpath=<value>| as an optional argument to the package; or using the already mentioned
371 % \cmd{\shchange\marg{defaultpath}\marg{<value>}} command.
372 % \DescribeMacro{\shpath} Second, one could use \cmd{\shpath} to automatically get the absolute path
373 % of the current \verb|*.tex| file. Please note that this command does not affect the default path. If you
374 % would like to set the default path to the current path of your file, use
375 % \cmd{\shchange\{defaultpath\}\{\cmd{\shpath}\}}. At last, if you just want to use another path for one
376 % line, just use the first argument of \cmd{\shline} to do so. For example:
377 % \begin{verbatim}
378 % \shline{/home/user/Desktop}{exit}
379 % \end{verbatim}
380 %
381 % \subsubsection{Shell output}
382 % \DescribeMacro{\shoutput}
383 % \cmd{\shoutput} implements two mandatory macros, too. Here, the first argument is ment for the options of a shell command.
384 % For example if you typeset the \verb|--help| output of a command, there may be one or more options like
385 % \verb|-c|, \verb|-a| and \verb|-T|. These can be typeset within a fancy optionbox by using the first argument
386 % of \cmd{\shoutput}. The second argument is ment for any text and is printed without any special formatting.
387 % However, it is not mandatory and sometimes not even useful to use the optionbox. In this case you can leave the
388 % first argument empty, which forces the macro to suppress the complete optionbox including the additional indent it
389 % would otherwise cause.
390 %
391 % \subsubsection{Name variables}
392 % For international compatibility the \textit{shdoc} packages implements two commands to make the list and
393 % caption name of the float easily accessible. \par
394 % \DescribeMacro{\shlistname} One can use \cmd{\shlistname} to change the title of the sessions list. The default
395 % value is ``\cmd{\shlistname}\{List of Terminal Sessions\}''.\par
396 %
397 % \DescribeMacro{\shfloatname} In the same manner as described above, the float caption that's displayed below
398 % each float could be changed. Its default value is ``\cmd{\shfloatname}\{Terminal Session\}''.
399 %
400 %
401 % \subsection{Automatic command execution and typesetting}
402 % Starting with version v2.1, \textit{shdoc} includes macros that let the user execute shell commands
403 % from within the \LaTeX{} file and typeset their output immediately. As the whole package is intended to
404 % be used on a Linux/Unix shell it uses dedicated commands that will not work on other shells\footnote{The
405 % manual mode, however, will always work the same.}.\par
406 % Note that all the following macros in this subsection are valid within the \cmd{\sh} float environment,
407 % but not within \cmd{\shbox}, as each of them produces its own, enclosed shbox. In other words, each
408 % automatic inclusion macro produces a standalone shbox. The necessary float environment, caption and label
409 % stay the same.
410 %
411 % \subsubsection{Warning}
412 % Caution! In order to make the following features work, you need to allow \TeX{} to use the \cmd{\write18}
413 % instruction. For \TeX Live this can be done by using the \verb|--shell-escape| option on the shell. It is
414 % not recommended to use this option permanently, as you could unconciously execute harmful \LaTeX{} code.
415 % Further, only execute \LaTeX{} and shell scripts that you trust, as nobody will take responsibility for
416 % their effects.
417 %
418 % \subsubsection{Read saved command outputs from a file}
419 % \DescribeMacro{\shread} The easiest way to include shell output into your \LaTeX{} file automatically
420 % is by redirecting the output stream of the shell command to a file, which is then read by \textit{shdoc}.
421 % For example:
422 % \begin{verbatim}
423 % root@linux ~ $ xsensors -help > xsensors-out.save
424 % \end{verbatim}
425 % The resulting file will look like this:
426 % \begin{mdframed}[linecolor=black]
427 % \begin{verbatim}
428 %
429 %Usage: xsensors [options]
430 %
431 %Options:
432 %--------
433 %
434 %-f Display all temperatures in Fahrenheit.
435 %-h Display this help text and exit.
436 %-c filename Specify the libsensors configuration file.
437 %-i filename Specify the image file to use as a theme.
438 %-t time Specify the update time in number of seconds.
439 % Set this to a negative number for no update.
440 % Don't set this to 0.
441 %-v Display version number.
442 %
443 % \end{verbatim}
444 % \end{mdframed}
445 % \hfill \raisebox{6pt}{\texttt{\scriptsize xsensors-out.save}}
446 %
447 %\noindent After saving the file, \cmd{\shread} is used to include it into your document.
448 % The macro has two mandatory arguments: The first one is the initial command, as \textit{shdoc}
449 % has no way to find out the matching input command to your output file, whereas the second one
450 % is the path and name of the file you want to read. Thus, to include the example file from above
451 % one would write:
452 % \begin{verbatim}
453 % \shread{xsensors -help}{xsensors-out.save}
454 % \end{verbatim}
455 %
456 % While reading command output in that manner, the user still has to take care of at least two steps,
457 % but it can be very useful if the output of a command is used elsewhere, too. Furthermore, this is still
458 % the fastest way to include command output as all the other methods slow down the \LaTeX{} build of your document.
459 %
460 % \subsubsection{Run commands and typeset their output}
461 % \DescribeMacro{\shrun} Nevertheless, two steps are still one too much. Thus, \cmd{\shrun} lets
462 % the user run a shell command from within the document and typesets its output automatically. The macro has one
463 % mandatory argument, namely the command that should be passed to the shell. Once again make sure to have \cmd{\write18}
464 % enabled:
465 % \begin{verbatim}
466 % \shrun{xsensors -help}
467 % \end{verbatim}
468 %
469 % \noindent The \cmd{\shrun} macro takes the shell command, passes it to the system shell and captures its
470 % output in a file called \texttt{shrun.tmp}. This same file is used for every occuring \cmd{\shrun},
471 % so its content is highly temporary. However, the file will not be deleted from your working directory,
472 % unless you tell \textit{shdoc} to do so -- see section~\ref{subsubsec:clearfiles}.
473 % Note that the macro will also automatically redirect the \texttt{stderr} stream to the output
474 % stream, so errors should be visible within your document -- see session~\ref{sh:error} for an example.
475 %
476 %
477 % \subsubsection{Autoread and typeset a file (experimental)}\label{subsubsec:autoread}
478 % The results of \cmd{\shread} are normally nice, but the macro does not support
479 % the optionbox of \cmd{\shoutput}. That's because files are read line by line, where
480 % each line can be seen as a string that is directly passed to \cmd{\shoutput} as the second argument.
481 % Further, it is very difficult to isolate the shell options (\verb|-c|, \verb|-U|,\dots) from the
482 % line of text. That's mainly because every single program formats its output in a slightly different way.
483 % Supporting every programs formatting would nearly be impossible, so another approach had to be taken by
484 % the author; and that was string manipulation.\par
485 % \DescribeMacro{\shautoread} The result of fooling around with various manipulation methods is a
486 % macro called \cmd{\shautoread}, which is basically \cmd{\shread} except for a few additions that are
487 % provided by the \textit{stringstrings} package.\par
488 % Just as \cmd{\shread}, the \cmd{\shautoread} macro accepts two mandatory arguments that are treated in
489 % the same way as before. The real magic happens when \TeX{} is reading the given file line by line.
490 % Each line is stored in an internal macro, which is subsequently accessed by \textit{stringstrings}, extracting the first word of
491 % the line. To find out if the first word is an option or not, \textit{stringstrings} then searches this word for the '-' character.
492 % 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.},
493 % the word is treated as \textit{the option} an is thus passed to
494 % \cmd{\shoutput} as the first argument. The rest of the line gets printed as text i.e. the second argument.\par
495 % To this day, the autoread feature is experimental. It may mess up with the output of some programs and you maybe
496 % 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
497 % to enhance the appearance of your output once more.\par\medskip
498 % \noindent\textcolor{red}{Warning:} Using the \cmd{\shautoread} function has a huge impact on your
499 % \LaTeX{} build time, as \textit{stringstrings} somehow has a lot of things to do when manipulating
500 % strings. Expect at least one minute per autoread, depending on the length of the output and your system performance.
501 %
502 %
503 % \subsubsection{Run and autoread a command (experimental)}
504 % \DescribeMacro{\shautorun} Just like \cmd{\shrun}, \cmd{\shautorun} lets the user
505 % execute a shell command and typeset its output. The only difference is that \cmd{\shautorun}
506 % reads the temporary file via \cmd{\shautoread} -- described in section~\ref{subsubsec:autoread}
507 %
508 % \subsubsection{Autopath \& autoformat (experimental)}
509 % \paragraph{Autopath}\DescribeMacro{\shautopath} In section~\ref{subsubsec:in_and_path}
510 % we learned that \cmd{\shpath} can be used to get the current
511 % directory we are working in. To automate things even more both, \cmd{\shread} and \cmd{\shautoread} can
512 % use the current path by invoking \cmd{\shpath} on their own. As this functionality is turned off by default, you
513 % can enable it by typing:
514 % \begin{verbatim}
515 % \shautopath{true}
516 % \end{verbatim}
517 % \noindent You can also turn it off again by passing \texttt{'false'} to this macro. Passing any other text may not result
518 % in a warning or error, but will be visible in the log file.\par
519 %
520 % \paragraph{Autoformat}\DescribeMacro{\shautopath} Another automation feature -- and
521 % probably the most useful one -- is the autoformat script that
522 % is distributed with the package. As is, the script uses the \texttt{'sed'} stream editor to modify the temporary
523 % file \texttt{shrun.tmp} and stores the result in \texttt{shrun-formatted.tmp}. Thus, the script can be used by
524 % both, \cmd{\shrun} and \cmd{\shautorun} to improve the visual quality of your document. This feature is
525 % turned off by default. You can enable it by typing:
526 % \begin{verbatim}
527 % \shautoformat{true}
528 % \end{verbatim}
529 % \noindent However, \textcolor{red}{before doing so}, you should open the script \texttt{shreformat.sh}
530 % with your favourite text
531 % editor and double check that it won't \textit{harm your computer}\footnote{You shouldn't use unknown scripts blindly}!
532 % You can also modify it according to your
533 % needs in order to get even better results.
534 %
535 % \subsubsection{Clear temporary files}\label{subsubsec:clearfiles}
536 % \DescribeMacro{\shclearfiles} Most of the time you may want to delete the three temporary files
537 % \texttt{shrun.tmp}, \texttt{shpath.tmp} and \texttt{shrun-formatted.tmp}
538 % at the end of your \LaTeX{} build, as they are not really useful for anything
539 % but the \textit{shdoc} package. One can do so by using \cmd{\shclearfiles} at an
540 % appropriate point within the document, e.g. before the end.\newpage
541 %
542 % \section{Examples}\label{sec:examples}
543 % \subsection{Various examples}
544 % \subsubsection{Basic Sessions}
545 %\shpreset{blackwhite}
546 %\begin{sh}
547 % \begin{verbatim}
548 % \shpreset{blackwhite}
549 % \begin{sh}
550 % \shuser{simon}
551 % \shmachine{linuxmint}
552 % \begin{shbox}
553 % \shline{}{cd Desktop/}
554 % \shline{Desktop/}{xsensors -help}
555 % \shoutput{}{}
556 % \shoutput{}{\underline{Options:}}
557 % \shoutput{}{}
558 % \shoutput{-f}{Display all temperatures in Fahrenheit.}
559 % \shoutput{-h}{Display this help text and exit.}
560 % \shoutput{-c}{+filename Specify the libsensors configuration file.}
561 % \shoutput{-t}{+time Specify the update time in number of seconds.}
562 % \shoutput{-v}{Display version number.}
563 % \end{shbox}
564 % \caption{The options of \textit{xsensors}}
565 % \label{sh:xsensor}
566 % \end{sh}
567 % \end{verbatim}
568 % \shuser{simon}
569 % \shmachine{linuxmint}
570 % \begin{shbox}
571 % \shline{}{cd Desktop/}
572 % \shline{Desktop/}{xsensors -help}
573 % \shoutput{}{}
574 % \shoutput{}{\underline{Options:}}
575 % \shoutput{}{}
576 % \shoutput{-f} {Display all temperatures in Fahrenheit.}
577 % \shoutput{-h} {Display this help text and exit.}
578 % \shoutput{-c} {+filename Specify the libsensors configuration file.}
579 % \shoutput{-i} {+filename Specify the image file to use as a theme.}
580 % \shoutput{-t} {+time Specify the update time in number of seconds.}
581 % \shoutput{-v} {Display version number.}
582 % \end{shbox}
583 % \caption{The options of \textit{xsensors}}
584 % \label{sh:xsensor}
585 %\end{sh}
586 %
587 %
588 %\shpreset{default}
589 %\begin{sh}
590 % \begin{verbatim}
591 % \shpreset{default}
592 % \begin{sh}
593 % \shuser{simon}
594 % \shmachine{linuxmint}
595 % \begin{shbox}
596 % \shline{}{tex}
597 % \shoutput{}{This is TeX, Version 3.14159265 (TeX Live 2015)}
598 % \shoutput{}{**\cmd{\relax}}
599 % \shoutput{}{*Hello World!}
600 % \shoutput{}{*\cmd{\bye}}
601 % \end{shbox}
602 % \caption{Hello World in \TeX{}}
603 % \label{sh:TeX}
604 % \end{sh}
605 % \end{verbatim}
606 % \shuser{simon}
607 % \shmachine{linuxmint}
608 % \begin{shbox}
609 % \shline{}{tex}
610 % \shoutput{}{This is TeX, Version 3.14159265 (TeX Live 2015)}
611 % \shoutput{}{**\cmd{\relax}}
612 % \shoutput{}{*Hello World!}
613 % \shoutput{}{*\cmd{\bye}}
614 % \end{shbox}
615 % \caption{Hello World in \TeX{}}
616 % \label{sh:TeX}
617 %\end{sh}
618 %\newpage
619 % \subsubsection{Preset creation}\label{subsubsec:presetdef}
620 %
621 % \shpresetdef{odd}{
622 % \shpreset{blackwhite}
623 % \shchangecolor{usernamecolor}{orange}
624 % \shchangecolor{machinenamecolor}{orange}
625 % }
626 % \shpreset{odd}
627 % \begin{sh}[th!]
628 % \begin{verbatim}
629 % \shpresetdef{odd}{
630 % \shpreset{blackwhite}
631 % \shchangecolor{usernamecolor}{orange}
632 % \shchangecolor{machinenamecolor}{orange}
633 % }
634 % \shpreset{odd}
635 % \begin{sh}
636 % \shuser{doctorX}
637 % \shmachine{supercomputer}
638 % \begin{shbox}
639 % \shline{/home/doctorX/Documents}{exit}
640 % \end{shbox}
641 % \caption{Go away.}
642 % \label{sh:exit}
643 % \end{sh}
644 % \end{verbatim}
645 % \shuser{doctorX}
646 % \shmachine{supercomputer}
647 % \begin{shbox}
648 % \shline{/home/doctorX/Documents}{exit}
649 % \end{shbox}
650 % \caption{Go away.}
651 % \label{sh:exit}
652 % \end{sh}
653 %
654 % \shpresetdef{mystyle}{
655 % \shchangecolor{backgroundcolor}{white}
656 % \shchangecolor{usernamecolor}{red}
657 % \shchangecolor{machinenamecolor}{red}
658 % \shchangecolor{separatorcolor}{RoyalBlue}
659 % \shchangecolor{optioncolor}{orange!50!yellow}
660 % \shchangesymbol{indicatorsymbol}{!}
661 % \shchangesymbol{separatorsymbol}{$\geq$}
662 % }
663 % \shpreset{mystyle}
664 % \begin{sh}
665 % \begin{verbatim}
666 % \shpresetdef{mystyle}{
667 % \shchangecolor{backgroundcolor}{white}
668 % \shchangecolor{usernamecolor}{red}
669 % \shchangecolor{machinenamecolor}{red}
670 % \shchangecolor{separatorcolor}{RoyalBlue}
671 % \shchangecolor{optioncolor}{orange!50!yellow}
672 % \shchangesymbol{indicatorsymbol}{!}
673 % \shchangesymbol{separatorsymbol}{$\geq$}
674 % }
675 %
676 % \begin{sh}
677 % \shuser{joe}
678 % \shmachine{joesraspian}%
679 % \begin{shbox}
680 % \shline{}{history}
681 % \shoutput{480}{rubber}
682 % \shoutput{481}{xsensors}
683 % \shoutput{482}{tracepath www.google.com}
684 % \shoutput{483}{whoami}
685 % \shoutput{484}{help}
686 % \shoutput{485}{exit}
687 % \end{shbox}
688 % \caption{History of my session}
689 % \label{sh:history}
690 % \end{sh}
691 % \end{verbatim}
692 % \shuser{joe}
693 % \shmachine{joesraspian}%
694 % \begin{shbox}
695 % \shline{}{history}
696 % \shoutput{480}{rubber}
697 % \shoutput{481}{xsensors}
698 % \shoutput{482}{tracepath www.google.com}
699 % \shoutput{483}{whoami}
700 % \shoutput{484}{help}
701 % \shoutput{485}{exit}
702 % \end{shbox}
703 % \caption{History of my session}
704 % \label{sh:history}
705 % \end{sh}\newpage
706 %
707 %
708 % \subsection{All the predefined presets}
709 % \shpreset{default}
710 %\begin{sh}[th!]
711 % \shuser{simon}
712 % \shmachine{linuxmint}
713 % \begin{shbox}
714 % \shline{}{cd Desktop/}
715 % \shline{Desktop/}{xsensors -help}
716 % \shoutput{}{}
717 % \shoutput{}{\underline{Options:}}
718 % \shoutput{}{}
719 % \shoutput{-f} {Display all temperatures in Fahrenheit.}
720 % \shoutput{-h} {Display this help text and exit.}
721 % \shoutput{-c} {+filename Specify the libsensors configuration file.}
722 % \shoutput{-i} {+filename Specify the image file to use as a theme.}
723 % \shoutput{-t} {+time Specify the update time in number of seconds.}
724 % \shoutput{-v} {Display version number.}
725 % \end{shbox}
726 % \caption{The options of \textit{xsensors} -- \textit{default} or \textit{mint} preset}
727 % \label{sh:minttest}
728 %\end{sh}
729 % \shpreset{arrows}
730 %\begin{sh}[th!]
731 % \shuser{simon}
732 % \shmachine{linuxmint}
733 % \begin{shbox}
734 % \shline{}{cd Desktop/}
735 % \shline{Desktop/}{xsensors -help}
736 % \shoutput{}{}
737 % \shoutput{}{\underline{Options:}}
738 % \shoutput{}{}
739 % \shoutput{-f} {Display all temperatures in Fahrenheit.}
740 % \shoutput{-h} {Display this help text and exit.}
741 % \shoutput{-c} {+filename Specify the libsensors configuration file.}
742 % \shoutput{-i} {+filename Specify the image file to use as a theme.}
743 % \shoutput{-t} {+time Specify the update time in number of seconds.}
744 % \shoutput{-v} {Display version number.}
745 % \end{shbox}
746 % \caption{The options of \textit{xsensors} -- \textit{arrows} preset}
747 % \label{sh:arrtest}
748 %\end{sh}\newpage
749 % \shpreset{darkblue}
750 %\begin{sh}[th!]
751 % \shuser{simon}
752 % \shmachine{linuxmint}
753 % \begin{shbox}
754 % \shline{}{cd Desktop/}
755 % \shline{Desktop/}{xsensors -help}
756 % \shoutput{}{}
757 % \shoutput{}{\underline{Options:}}
758 % \shoutput{}{}
759 % \shoutput{-f} {Display all temperatures in Fahrenheit.}
760 % \shoutput{-h} {Display this help text and exit.}
761 % \shoutput{-c} {+filename Specify the libsensors configuration file.}
762 % \shoutput{-i} {+filename Specify the image file to use as a theme.}
763 % \shoutput{-t} {+time Specify the update time in number of seconds.}
764 % \shoutput{-v} {Display version number.}
765 % \end{shbox}
766 % \caption{The options of \textit{xsensors} -- \textit{darkblue} preset}
767 % \label{sh:dbtest}
768 %\end{sh}
769 % \shpreset{airy}
770 %\begin{sh}[th!]
771 % \shuser{simon}
772 % \shmachine{linuxmint}
773 % \begin{shbox}
774 % \shline{}{cd Desktop/}
775 % \shline{Desktop/}{xsensors -help}
776 % \shoutput{}{}
777 % \shoutput{}{\underline{Options:}}
778 % \shoutput{}{}
779 % \shoutput{-f} {Display all temperatures in Fahrenheit.}
780 % \shoutput{-h} {Display this help text and exit.}
781 % \shoutput{-c} {+filename Specify the libsensors configuration file.}
782 % \shoutput{-i} {+filename Specify the image file to use as a theme.}
783 % \shoutput{-t} {+time Specify the update time in number of seconds.}
784 % \shoutput{-v} {Display version number.}
785 % \end{shbox}
786 % \caption{The options of \textit{xsensors} -- \textit{airy} preset}
787 % \label{sh:airtest}
788 %\end{sh}
789 %\shpreset{blackwhite}
790 %\begin{sh}[th!]
791 % \shuser{simon}
792 % \shmachine{linuxmint}
793 % \begin{shbox}
794 % \shline{}{cd Desktop/}
795 % \shline{Desktop/}{xsensors -help}
796 % \shoutput{}{}
797 % \shoutput{}{\underline{Options:}}
798 % \shoutput{}{}
799 % \shoutput{-f} {Display all temperatures in Fahrenheit.}
800 % \shoutput{-h} {Display this help text and exit.}
801 % \shoutput{-c} {+filename Specify the libsensors configuration file.}
802 % \shoutput{-i} {+filename Specify the image file to use as a theme.}
803 % \shoutput{-t} {+time Specify the update time in number of seconds.}
804 % \shoutput{-v} {Display version number.}
805 % \end{shbox}
806 % \caption{The options of \textit{xsensors} -- \textit{blackwhite} preset}
807 % \label{sh:bwtest}
808 %\end{sh}
809 % \newpage
810 % \subsection{Automated command execution and formatting}\shpreset{default}
811 % \subsubsection{Basic examples}
812 %
813 % \begin{sh}
814 % \begin{verbatim}
815 % \begin{sh}
816 % \scriptsize
817 % \shread{avrdude -c usbasp -p attiny24}{avrdude-log.save}
818 % \caption{\texttt{avrdude} session, read from a file via \cmd{\shread}}
819 % \label{sh:avrdude_session}
820 % \end{sh}
821 % \end{verbatim}
822 % \scriptsize
823 % \shread{avrdude -c usbasp -p attiny24}{avrdude-log.save}
824 % \caption{\texttt{avrdude} session, read from a file via \cmd{\shread}}
825 % \label{sh:avrdude_session}
826 % \end{sh}
827 %
828 % \begin{sh}
829 % \begin{verbatim}
830 % \begin{sh}
831 % \shautoformat{false}
832 % \shrun{ifup --help}
833 % \caption{The help pages of \texttt{ifup}, standard \cmd{\shrun}}
834 % \label{sh:ifup}
835 % \end{sh}
836 % \end{verbatim}
837 % \shrun{ifup --help}
838 % \caption{The help pages of \texttt{ifup}, standard \cmd{\shrun}}
839 % \label{sh:ifup}
840 % \end{sh}
841 %
842 %
843 % \begin{sh}
844 % \begin{verbatim}
845 % \begin{sh}
846 % \shrun{xsensor -help}
847 % \caption{A typo resulting in an error}
848 % \label{sh:error}
849 % \end{sh}
850 % \end{verbatim}
851 % \shrun{xsensor -help}
852 % \caption{A typo resulting in an error}
853 % \label{sh:error}
854 % \end{sh}
855 %
856 %
857 % \noindent As you can see the automatic execution of commands works
858 % 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
859 % session~\ref{sh:ifup} get
860 % printed as dashes or other weird symbols. Thus, I recommend to at least use the autoformat script option permanently.
861 % The redirection of the error stream in session~\ref{sh:error} also shows the expected result.
862 %
863 %
864 % \subsubsection{Autoformat script before/after comparison}
865 %
866 % \begin{sh}
867 % \begin{verbatim}
868 % \begin{sh}
869 % \shautoformat{false}
870 % \shautorun{xsensors -help}
871 % \caption{The options of xsensors before using the autoformat script}
872 % \label{sh:xsensors_noautof}
873 % \end{sh}
874 % \end{verbatim}
875 % \shautoformat{false}
876 % \shautorun{xsensors -help}
877 % \caption{The options of xsensors before using the autoformat script}
878 % \label{sh:xsensors_noautof}
879 % \end{sh}
880 %
881 % \begin{sh}
882 % \begin{verbatim}
883 % \begin{sh}
884 % \shautoformat{true}
885 % \shautorun{xsensors -help}
886 % \caption{The options of xsensors after using the autoformat script}
887 % \label{sh:xsensors_autof}
888 % \end{sh}
889 % \end{verbatim}
890 % \shautoformat{true}
891 % \shautorun{xsensors -help}
892 % \caption{The options of xsensors after using the autoformat script}
893 % \label{sh:xsensors_autof}
894 % \end{sh}
895 %
896 % As you can see in session~\ref{sh:xsensors_noautof} and~\ref{sh:xsensors_autof} the autoformat script
897 % can really improve your output. However, xsensors is still an easy job for \textit{shdoc} and sometimes
898 % the \cmd{\shautorun} macro is not really the best way to run a command. At first, it's still experimental
899 % and due to the \textit{stringstrings} manipulation it can take a massive amount of time to build your document.
900 % The second reason you might not always use autorun is, when commands output a large number of lines and the
901 % occuring options vary a lot in terms of length and style. In this case autorun is not likely to produce a nice output --
902 % as seen in session~\ref{sh:gcc_noautof} and~\ref{sh:gcc_autof}.
903 %
904 % \begin{sh}
905 % \begin{verbatim}
906 % \begin{sh}
907 % \tiny
908 % \shautoformat{false}
909 % \shrun{gcc --help}
910 % \caption{Help pages of gcc before autoformat, standard \cmd{\shrun}}
911 % \label{sh:gcc_noautof_noautorun}
912 % \end{sh}
913 % \end{verbatim}
914 % \tiny
915 % \shautoformat{false}
916 % \shrun{gcc --help}
917 % \caption{Help pages of gcc before autoformat, standard \cmd{\shrun}}
918 % \label{sh:gcc_noautof_noautorun}
919 % \end{sh}
920 %
921 % \vspace*{-5mm}
922 % \begin{sh}
923 % \begin{verbatim}
924 % \begin{sh}
925 % \tiny
926 % \shautoformat{false}
927 % \shautorun{gcc --help}
928 % \caption{Help pages of gcc before using the autoformat script}
929 % \label{sh:gcc_noautof}
930 % \end{sh}
931 % \end{verbatim}\vspace{-5mm}
932 % \tiny
933 % \shautoformat{false}
934 % \shautorun{gcc --help}
935 % \caption{Help pages of gcc before using the autoformat script}
936 % \label{sh:gcc_noautof}
937 % \end{sh}
938 %
939 % \vspace*{-5mm}
940 % \begin{sh}
941 % \begin{verbatim}
942 % \begin{sh}
943 % \tiny
944 % \shautoformat{true}
945 % \shautorun{gcc --help}
946 % \caption{Help pages of gcc after using the autoformat script}
947 % \label{sh:gcc_autof}
948 % \end{sh}
949 % \end{verbatim}\vspace{-5mm}
950 % \tiny
951 % \shautoformat{true}
952 % \shautorun{gcc --help}
953 % \caption{Help pages of gcc after using the autoformat script}
954 % \label{sh:gcc_autof}
955 % \end{sh}
956 % \newpage
957 % \addcontentsline{toc}{section}{List of Terminal Sessions}
958 % \phantomsection
959 % \listofsh\bigskip
960 %
961 % \noindent\DescribeMacro{\listofsh}As the float environment supports automatic lists, you can use them with
962 % \textit{shdoc}, too. Just use \cmd{\listofsh} for that.
963 %
964 % \shclearfiles
965 %
966 % ^^A Implementation from here
967 %\StopEventually{\PrintIndex}
968 %
969 % \newpage
970 % \section{Implementation}\label{sec:implementation}
971 % This section describes the implementation of the \textit{shdoc} package and its
972 % features. The package was written as a \texttt{*.dtx} source file and therefore the
973 % package code begins with the following instruction:\par
974 % \begin{macrocode}
975 %<*package>
976 % \end{macrocode}
977 % \subsection{Options}
978 % First of all, the package options for colouring and symbol options and their default values are defined. The options
979 % are then processed to make them available for the user.
980 %\begin{macro}{
981 % color, symbol
982 % }
983 % \begin{macrocode}
984 \DeclareStringOption[gray!70]{backgroundcolor}
985 \DeclareStringOption[green!80!yellow]{usernamecolor}
986 \DeclareStringOption[green!80!yellow]{machinenamecolor}
987 \DeclareStringOption[RoyalBlue]{pathcolor}
988 \DeclareStringOption[RoyalBlue]{indicatorcolor}
989 \DeclareStringOption[green!80!yellow]{separatorcolor}
990 \DeclareStringOption[white!60!gray]{optioncolor}
991 \DeclareStringOption[black]{textcolor}
992 \DeclareStringOption[\$]{indicatorsymbol}
993 \DeclareStringOption[\~]{defaultpath}
994 \DeclareStringOption[@]{separatorsymbol}
995 \ProcessKeyvalOptions*
996 % \end{macrocode}
997 %\end{macro}
998 %
999 % \subsection{Presets}\label{subsec:presetdef}
1000 % Right after the option definitions the preset commands are defined.
1001 % Every preset is stored in a macro with the generic name \cmd{\sh@preset@NAME}, where
1002 % \texttt{NAME} stands for the preset name.
1003 % To make the presets better loadable for users \cmd{\shpreset} is defined
1004 % to simply execute the package internal preset macro:
1005 %
1006 %\begin{macro}{\shpreset}
1007 % \begin{macrocode}
1008 \def\shpreset#1{\csname sh@preset@#1\endcsname}%
1009 % \end{macrocode}
1010 %\end{macro}
1011 % To simplify the creation of new presets a few macros are needed. The main command
1012 % is \cmd{\shpresetdef}, which creates a new preset macro with the desired settings.
1013 % The macro calls \cmd{\shpreset\{default\}} at the beginning, so the inital settings of the new preset
1014 % are the default settings of \textit{shdoc}.
1015 %\begin{macro}{
1016 % \shpresetdef}
1017 % \begin{macrocode}
1018 \def\shpresetdef#1#2{%
1019 \expandafter\gdef\csname sh@preset@#1\endcsname{\shpreset{default} #2}%
1020 }%
1021 % \end{macrocode}
1022 %\end{macro}
1023 % Basically, every command can be used as the second argument of \cmd{\shpresetdef}, but
1024 % most of them won't change any settings in \textit{shdoc}. The only useful macros in this
1025 % context are those, who explicitly change a color, symbol or value within the package, namely
1026 % \cmd{\shchange}, \cmd{\shchangecolor} and \cmd{\shchangesymbol}.
1027 %
1028 % \cmd{\shchange} has two arguments, where the first is the name of the parameter that
1029 % should be changed and the second is the new value. Although there won't be an error,
1030 % other names than those implemented by the package are not valid. The macro simply
1031 % redefines the according parameter.
1032 %\begin{macro}{\shchange}
1033 % \begin{macrocode}
1034 \def\shchange#1#2{\expandafter\gdef\csname shdoc@#1\endcsname{#2}}
1035 % \end{macrocode}
1036 %\end{macro}
1037 %
1038 %\begin{macro}{\shchangesymbol}
1039 %\begin{macro}{\shchangecolor}
1040 % \cmd{\shchangesymbol} and \cmd{\shchangecolor} are two other commands, that implement the exact same
1041 % definition as \cmd{\shchange}.
1042 % Thus, these commands only exists for logical reasons. They simply redefine the
1043 % desired symbol or color.
1044 % \begin{macrocode}
1045 \let\shchangesymbol\shchange%
1046 \let\shchangecolor\shchange%
1047 % \end{macrocode}
1048 %\end{macro}\end{macro}
1049 %
1050 % \noindent Since \cmd{\shpresetdef} calls \cmd{\shpreset\{default\}}, the default preset
1051 % had to be defined manually via \cmd{\def}.
1052 %\begin{macro}{\sh@preset@default}
1053 % \begin{macrocode}
1054 \def\sh@preset@default{%
1055 \shchangecolor{backgroundcolor}{gray!70}%
1056 \shchangecolor{usernamecolor}{green!80!yellow}%
1057 \shchangecolor{machinenamecolor}{green!80!yellow}%
1058 \shchangecolor{pathcolor}{RoyalBlue}%
1059 \shchangecolor{indicatorcolor}{RoyalBlue}%
1060 \shchangecolor{separatorcolor}{green!80!yellow}%
1061 \shchangecolor{optioncolor}{white!60!gray}%
1062 \shchangecolor{textcolor}{black}%
1063 \shchangesymbol{indicatorsymbol}{\$}%
1064 \shchangesymbol{defaultpath}{\~}%
1065 \shchangesymbol{separatorsymbol}{@}%
1066 }%
1067 % \end{macrocode}
1068 %\end{macro}
1069 % As the \textit{shdoc} package was initally ment to imitate the Linux Mint bash, the
1070 % default preset is equal to the \textit{mint} style, which is defined right after the default preset:
1071 %\begin{macro}{\sh@preset@mint}
1072 % \begin{macrocode}
1073 \shpresetdef{mint}{\shpreset{default}}%
1074 % \end{macrocode}
1075 %\end{macro}
1076 %
1077 % \noindent The second preset style is the ``arrows'' style, which is a dark color scheme with
1078 % two arrows as the indicator symbol.
1079 %\begin{macro}{\sh@preset@arrows}
1080 % \begin{macrocode}
1081 \shpresetdef{arrows}{%
1082 \shchangecolor{usernamecolor}{red}%
1083 \shchangecolor{machinenamecolor}{green!80!yellow}%
1084 \shchangecolor{separatorcolor}{white}%
1085 \shchangecolor{indicatorsymbol}{$\gg$}%
1086 \shchangecolor{indicatorcolor}{green!80!yellow}%
1087 \shchangecolor{backgroundcolor}{black}%
1088 \shchangecolor{textcolor}{white}%
1089 \shchangecolor{optioncolor}{gray}%
1090 }%
1091 % \end{macrocode}
1092 %\end{macro}
1093 %
1094 % \noindent Another dark scheme is the ``darkblue'' preset, which defines a dark blue background color
1095 % and more or less appropriate other colors. The definition of this preset is furthermore a
1096 % nice example, how macros of other packages could also make sense within the \cmd{\shpresetdef}
1097 % command.
1098 %\begin{macro}{\sh@preset@darkblue}
1099 % \begin{macrocode}
1100 \shpresetdef{darkblue}{%
1101 \definecolor{shdarkblue}{RGB}{7,75,138}% xcolor syntax
1102 \shchangecolor{backgroundcolor}{shdarkblue}%
1103 \shchangecolor{textcolor}{white}%
1104 \shchangecolor{separatorcolor}{white}%
1105 \shchangecolor{usernamecolor}{orange}%
1106 \shchangecolor{machinenamecolor}{orange}%
1107 \shchangecolor{pathcolor}{green!60!black}%
1108 \shchangecolor{optioncolor}{SkyBlue!80!black}%
1109 }
1110 % \end{macrocode}
1111 %\end{macro}
1112 %
1113 % For those, who print their documents with the black ink cartridge only there is the
1114 % ``blackwhite'' preset. The definition sets the background and all the other colors to
1115 % different versions of gray, black and white -- see the examples in section~\ref{sec:examples}.
1116 %\begin{macro}{\sh@preset@blackwhite}
1117 % \begin{macrocode}
1118 \shpresetdef{blackwhite}{%
1119 \shchangecolor{backgroundcolor}{gray!30}%
1120 \shchangecolor{textcolor}{black}%
1121 \shchangecolor{separatorcolor}{black}%
1122 \shchangecolor{usernamecolor}{gray}%
1123 \shchangecolor{machinenamecolor}{gray}%
1124 \shchangecolor{pathcolor}{gray!50!black}%
1125 \shchangecolor{optioncolor}{white}%
1126 \shchangecolor{indicatorcolor}{white}%
1127 }
1128 % \end{macrocode}
1129 %\end{macro}
1130 %
1131 % The last and probably lightest preset is the ``airy'' preset with light blue and green elements.\par
1132 %\begin{macro}{\sh@preset@airy}
1133 % \begin{macrocode}
1134 \shpresetdef{airy}{%
1135 \shchangecolor{backgroundcolor}{SkyBlue!15}%
1136 \shchangecolor{usernamecolor}{Emerald}%
1137 \shchangecolor{machinenamecolor}{Emerald}%
1138 \shchangecolor{pathcolor}{orange!70}%
1139 \shchangecolor{indicatorcolor}{orange!70}%
1140 \shchangecolor{separatorcolor}{Emerald}%
1141 \shchangecolor{optioncolor}{Emerald!30}%
1142 }
1143 % \end{macrocode}
1144 %\end{macro}
1145 %
1146 % \subsection{Environment}
1147 % After all the setting definitions above the actual environment for the
1148 % shell commands can be defined. The whole environment consists of a
1149 % float environment with caption and label and one or more inner frameboxes, which
1150 % are generated with the \textit{mdframed} package. Further there is a
1151 % line number on the left side of every box. The number is defined as a
1152 % standard \LaTeX\ counter and is initially set to 0.
1153 %\begin{macro}{\shlinenumber}
1154 % \begin{macrocode}
1155 \newcounter{shlinenumber}% def new counter
1156 \setcounter{shlinenumber}{0}% set counter to 0
1157 % \end{macrocode}
1158 %\end{macro}
1159 %
1160 % \noindent Since the outer environment is a float, a list name variable is
1161 % needed to make the name user-adjustable. There are two macros that
1162 % implement this functionality: \cmd{\@shlistname} is the
1163 % name variable that holds the current value of the list name.
1164 % \cmd{\shlistname} is a user command, that redefines the
1165 % name according to the users' input. After the definition the
1166 % standard value is set.
1167 %\begin{macro}{\shlistname}
1168 % \begin{macrocode}
1169 \let\@shlistname\relax%
1170 \gdef\shlistname#1{\gdef\@shlistname{#1}}%
1171 \shlistname{List of Terminal Sessions}% set default value
1172 % \end{macrocode}
1173 %\end{macro}
1174 %
1175 % \subsubsection{Float environment}
1176 % Now, the whole float environment is defined. The float is named
1177 % \cmd{\sh} and uses the plain float style. The float name is stored
1178 % in a variable, which is implemented in the same way as the list name.
1179 % Afterwards the name is set. The caption is set to be at the bottom of the
1180 % float and a macro for the generation of the ``List of Terminal Sessions''
1181 % is defined.
1182 %\begin{macro}{\sh}
1183 % \begin{macrocode}
1184 \newfloat{sh}{tbph}{lsh}% define new float
1185 \restylefloat*{sh}%
1186 \floatstyle{plain}% set style
1187
1188 \let\@shfloatname\relax%
1189 \gdef\shfloatname#1{\gdef\@shfloatname{#1}}%
1190 \shfloatname{Terminal~Session}% default float name
1191 \floatname{sh}{\@shfloatname}%
1192
1193 \captionsetup[sh]{position=bottom}%
1194 \def\listofsh{\listof{sh}{\@shlistname}}%
1195 % \end{macrocode}
1196 %\end{macro}
1197 %
1198 % \subsubsection{Framebox}
1199 % For each session the user and machine values can and must be set, but they could also be
1200 % set at the beginning of a document to be valid for every terminal session. In the same manner
1201 % as before, two name variables and their setup commands are defined. The default value for the username is \texttt{root},
1202 % whereas the default for the machine is \texttt{linux}.
1203 %\begin{macro}{
1204 % \shuser,
1205 % \shmachine}
1206 % \begin{macrocode}
1207 \let\@shuser\relax%
1208 \let\@shmachine\relax%
1209 \def\shuser#1{\gdef\@shuser{#1}}%
1210 \def\shmachine#1{\gdef\@shmachine{#1}}%
1211 \def\@default@shuser{root}%
1212 \def\@default@shmachine{linux}%
1213 \shuser{\@default@shuser}%
1214 \shmachine{\@default@shmachine}%
1215 % \end{macrocode}
1216 %\end{macro}
1217 %
1218 %
1219 %\begin{macro}{\sh@lnscale}
1220 %\begin{macro}{\sh@fontcheck}
1221 % Within the framebox \cmd{\shbox} -- which is defined at the very end of the source code --
1222 % there are two commands: \cmd{\shline} for user inputs and \cmd{\shoutput} for shell outputs.
1223 % Each of these macros prints the line number onto the left side of the box first.
1224 % The number is relatively scaled down by a factor of $0.7$, which is stored in \cmd{\sh@lnscale}.
1225 % However, if the overall font size gets too small (i.e. when using \cmd{\scriptsize}, \cmd{\tiny}, \dots)
1226 % this factor is increased to prevent warnings from the \textit{relscale} package, which does the line
1227 % number scaling. The macro that acomplishes this automatic scaling is \cmd{\sh@fontcheck}.
1228 %
1229 % \begin{macrocode}
1230 \def\sh@lnscale{.7}% default number scaling
1231 \def\sh@fontcheck{% if fontsize < 6pt
1232 \ifthenelse{\f@size<6}{%
1233 \gdef\sh@lnscale{1}% factor = 1
1234 }{% elif fontsize < 8pt
1235 \ifthenelse{\f@size<8}{%
1236 \gdef\sh@lnscale{.84}% factor = 0.84
1237 }{% else: nothing
1238 }%
1239 }%
1240 }%
1241 % \end{macrocode}
1242 %\end{macro}\end{macro}
1243 %
1244 %\begin{macro}{\shline}
1245 %
1246 % In order to keep the text from mixing up with the line numbers a hangindent is required.
1247 % The indent is set according to the width of the linenumbers, so at the beginning of the
1248 % \cmd{\shline} definition \cmd{\sh@linenumberwidth} is defined.\par
1249 % Within a \cmd{\shline} the font is set to typewriter style, the font size gets checked and
1250 % the scaling factor for the line numbers is adjusted. Starting without any indent, \cmd{\shline}
1251 % determines if a leading 0 for the line number is needed. If so, the 0 is added, the number gets typeset
1252 % and the width of the line number is stored. After the number a small horizontal space creates the
1253 % distance, that's needed between the number and the following username and machine values. They are
1254 % typeset in their dedicated colors right after the appropriate hangindent is set. A small if-else construct
1255 % checks if the first argument of the macro is empty and acts accordingly -- see section~\ref{subsubsec:in_and_path}.
1256 % At the end, the line number is incremented to be ready for the next line.
1257 % \begin{macrocode}
1258 \newlength{\sh@linenumberwidth}%
1259 \long\def\shline#1#2{
1260 \ttfamily\sh@fontcheck\noindent%
1261 \ifnum\value{shlinenumber}<10%
1262 \textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}0\theshlinenumber}%
1263 \settowidth{\sh@linenumberwidth}{%
1264 \relscale{\sh@lnscale}0\theshlinenumber%
1265 }%
1266 \else%
1267 \textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}\theshlinenumber}%
1268 \settowidth{\sh@linenumberwidth}{%
1269 \relscale{\sh@lnscale}\theshlinenumber%
1270 }%
1271 \fi\hspace{\sh@linenumberwidth}%
1272 \hangindent=2\sh@linenumberwidth%
1273 \textcolor{\shdoc@usernamecolor}{\@shuser}%
1274 \textcolor{\shdoc@separatorcolor}{\shdoc@separatorsymbol}%
1275 \textcolor{\shdoc@machinenamecolor}{\@shmachine}%
1276 \ \ifx&#1&%
1277 \textcolor{\shdoc@pathcolor}{\shdoc@defaultpath\ }%
1278 \textcolor{\shdoc@indicatorcolor}{\shdoc@indicatorsymbol}
1279 \else%
1280 \textcolor{\shdoc@pathcolor}{#1\ }%
1281 \textcolor{\shdoc@indicatorcolor}{\shdoc@indicatorsymbol}%
1282 \fi\ \textcolor{\shdoc@textcolor}{#2}%
1283 \stepcounter{shlinenumber}\par
1284 }
1285 % \end{macrocode}
1286 %\end{macro}
1287 %-----------------------------------------------------------------
1288 %
1289 %\begin{macro}{\shoutput}
1290 %
1291 % The \cmd{\shoutput} command is very similar to its pendant, but has other requirements, too.
1292 % As there may be optionboxes within an output line, the hangindent handling needs to be adjusted.
1293 % Thus, a new length \cmd{\sh@optionboxwidth} is added.\par
1294 % Just as before, the font is set to typewriter style and the size is checked. The line number gets
1295 % typeset, the horizontal space is added and the hangindent is set. Again a small if-else construct checks
1296 % the first argument. If the argument is empty, the width of the optionbox is set to zero and the box is
1297 % suppressed. Otherwise, a framed colorbox is used to create the optionbox and the width of
1298 % the whole box is stored. The stored value is then used to increase the hangindent appropriately.
1299 % \begin{macrocode}
1300 \newlength{\sh@optionboxwidth}
1301 \long\def\shoutput#1#2{
1302 \ttfamily\sh@fontcheck\noindent%
1303 \ifnum\value{shlinenumber}<10%
1304 \textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}0\theshlinenumber}%
1305 \settowidth{\sh@linenumberwidth}{%
1306 \relscale{\sh@lnscale}0\theshlinenumber%
1307 }%
1308 \else%
1309 \textcolor{\shdoc@textcolor}{\relscale{\sh@lnscale}\theshlinenumber}%
1310 \settowidth{\sh@linenumberwidth}{%
1311 \relscale{\sh@lnscale}\theshlinenumber%
1312 }%
1313 \fi\hspace{\sh@linenumberwidth}%
1314 \hangindent=2\sh@linenumberwidth%
1315 \ifx&#1&%
1316 \textcolor{\shdoc@textcolor}{#2}\stepcounter{shlinenumber}%
1317 \settowidth{\sh@optionboxwidth}{0cm}%
1318 \else%
1319 \fcolorbox{\shdoc@optioncolor}%
1320 {\shdoc@optioncolor}{\textcolor{\shdoc@textcolor}{[#1]}}\ %
1321 \settowidth{\sh@optionboxwidth}{%
1322 \fcolorbox{\shdoc@optioncolor}%
1323 {\shdoc@optioncolor}{\textcolor{\shdoc@textcolor}{[#1]}}\ }%
1324 \addtolength{\hangindent}{\sh@optionboxwidth}%
1325 \textcolor{\shdoc@textcolor}{#2}\stepcounter{shlinenumber}%
1326 \fi\par%
1327 }
1328 % \end{macrocode}
1329 %\end{macro}
1330 %
1331 %\begin{macro}{\shautoformat, \shautopath}
1332 % The autoformat and autopath macros that enable or disable the corresponding functionality
1333 % are defined as a macro that holds whatever text the user passes as an argument. If the
1334 % given text is valid is decided later through an if-else statement.
1335 % \begin{macrocode}
1336 \let\sh@autoformat\relax%
1337 \def\shautoformat#1{\gdef\sh@autoformat{#1}}%
1338 \shautoformat{false}%
1339
1340 \let\sh@autopath\relax%
1341 \def\shautopath#1{\gdef\sh@autopath{#1}}%
1342 \shautopath{false}%
1343 % \end{macrocode}
1344 %\end{macro}
1345 %
1346 %\begin{macro}{\shpath}
1347 % Sometimes it's desired to get the path of the actual working directory. \cmd{\shpath}
1348 % prints the current path by capturing the output of the Linux-specific \textit{print working
1349 % directory} '\texttt{pwd}' command. The output is further stored in the temporary file \texttt{shpath.tmp}.
1350 % \begin{macrocode}
1351 \def\shpath{%
1352 \immediate\write18{pwd >shpath.tmp 2>&1}%
1353 \newread\sh@pathfile%
1354 \openin\sh@pathfile=shpath.tmp%
1355 \endlinechar=-1%
1356 \readline\sh@pathfile to \sh@path%
1357 \sh@path%
1358 \closein\sh@pathfile
1359 }
1360 % \end{macrocode}
1361 %\end{macro}
1362 %
1363 %\begin{macro}{\shread}
1364 % \textit{shdoc} is able to read text files, that contain the output of a shell command, via
1365 % the \cmd{\shread} macro. At first a new readfile needs to be opened. The endlinechar is set
1366 % to $-1$, so it won't appear in the document. After that a new \cmd{\shbox} is started and a
1367 % loop reads the lines from the text file. A few ifs are used to check if the first argument
1368 % of \cmd{\shread} is empty and to check if autopath is enabled.
1369 %
1370 % \begin{macrocode}
1371 \def\shread#1#2{%
1372 \newread\sh@inputfile%
1373 \openin\sh@inputfile=#2%
1374
1375 \endlinechar=-1% hide the endlinechar (-1 is invalid, thus not printed)
1376 \begin{shbox}%
1377 \ifthenelse{\equal{#1}{}}{}% empty: do not print
1378 {%
1379 \ifthenelse{\equal{\sh@autopath}{true}}{%
1380 \shline{\shpath}{#1}%
1381 }{%
1382 \ifthenelse{\equal{\sh@autopath}{false}}{}%
1383 {\typeout{-----------------------------------------------}%
1384 \typeout{ Package shdoc info: I don't know what you}%
1385 \typeout{ mean when passing '\sh@autopath' to autopath}%
1386 \typeout{ and I'm going to ignore it and restore the}%
1387 \typeout{default 'false'} %
1388 \typeout{-----------------------------------------------}%
1389 \shautopath{false}}%
1390 \shline{}{#1}%
1391 }%
1392 }
1393 \loop\unless\ifeof\sh@inputfile%
1394 \readline\sh@inputfile to \sh@fileline%
1395 \ifeof\sh@inputfile% again check of eof prevents last blank line
1396 \else%
1397 \shoutput{}{\sh@fileline}%
1398 \fi%
1399 \repeat%
1400 \end{shbox}%
1401 \closein\sh@inputfile%
1402 }
1403 % \end{macrocode}
1404 %\end{macro}
1405 %
1406 %
1407 %\begin{macro}{\shrun}
1408 % \cmd{\shrun} lets the user specify a command that is passed to the
1409 % system shell. Its output is stored in a file -- and possibly preformatted by
1410 % the reformat script -- and is then read by \cmd{\shread}. An if statement checks
1411 % if autoformat is enabled.
1412 %
1413 % \begin{macrocode}
1414 \def\shrun#1{%
1415 \ifthenelse{\equal{\sh@autoformat}{true}}{%
1416 \immediate\write18{#1 >shrun.tmp 2>&1}%
1417 \immediate\write18{./shreformat.sh}%
1418 \shread{#1}{shrun-formatted.tmp}%
1419 }{%
1420 \ifthenelse{\equal{\sh@autoformat}{false}}{}%
1421 {\typeout{-----------------------------------------------}%
1422 \typeout{ Package shdoc info: I don't know what you}%
1423 \typeout{ mean when passing '\sh@autoformat' to autoformat}%
1424 \typeout{ and I'm going to ignore it and restore the}%
1425 \typeout{default 'false'}%
1426 \typeout{-----------------------------------------------}%
1427 \shautoformat{false}}%
1428 \immediate\write18{#1 >shrun.tmp 2>&1}%
1429 \shread{#1}{shrun.tmp}%
1430 }%
1431 }%
1432 % \end{macrocode}
1433 %\end{macro}
1434 %
1435 %
1436 %\begin{macro}{\shautoread}
1437 % Autoread is an experimental feature of \textit{shdoc} that lets the package detect possible
1438 % shell options and typeset them within an optionbox. The read functionality is the same as
1439 % in \cmd{\shread}, however \textit{stringstrings} is used to modify the read file lines.
1440 % At first the first word is extracted from the line via \cmd{\getnextword}. After that,
1441 % the word is searched for the '-' character. If exactly one is found, the word is typeset
1442 % within an optionbox. The amount of chars that the word consists of is then removed from the
1443 % complete line and the rest of the line gets typeset as text.
1444 %
1445 % \begin{macrocode}
1446 \def\shautoread#1#2{%
1447 \newread\sh@inputfile%
1448 \openin\sh@inputfile=#2%
1449 \endlinechar=-1%
1450 \begin{shbox}
1451 \ifthenelse{\equal{#1}{}}{%
1452 }{%
1453 \ifthenelse{\equal{\sh@autopath}{true}}{%
1454 \shline{\shpath}{#1}%
1455 }{%
1456 \ifthenelse{\equal{\sh@autopath}{false}}{}%
1457 {\typeout{-----------------------------------------------}%
1458 \typeout{ Package shdoc info: I don't know what you}%
1459 \typeout{ mean when passing '\sh@autopath' to autopath}%
1460 \typeout{ and I'm going to ignore it and restore the}%
1461 \typeout{default 'false'}%
1462 \typeout{-----------------------------------------------}%
1463 \shautopath{false}}%
1464 \shline{}{#1}%
1465 }%
1466 }%
1467 \loop\unless\ifeof\sh@inputfile%
1468 \readline\sh@inputfile to \sh@fileline%
1469 \ifeof\sh@inputfile%
1470 \else%
1471 \getnextword[e]{\sh@fileline}%
1472 \findchars[q]{\thestring}{-}%
1473 \ifthenelse{\equal{\theresult}{1}}{%
1474 \shoutput{\thestring}%
1475 {\stringlength[e]{\thestring}\gobblechars[v]{\sh@fileline}{\theresult}}%
1476 }{%
1477 \shoutput{}{\sh@fileline}%
1478 }%
1479 \fi%
1480 \repeat%
1481 \end{shbox}%
1482 \closein\sh@inputfile%
1483 }%
1484 % \end{macrocode}
1485 %\end{macro}
1486 %
1487 %
1488 %\begin{macro}{\shautorun}
1489 % \cmd{\shautorun} implements the same functionality as \cmd{\shrun}, but invokes
1490 % autoread to read the file.
1491 %
1492 % \begin{macrocode}
1493 \def\shautorun#1{
1494 \ifthenelse{\equal{\sh@autoformat}{true}}{%
1495 \immediate\write18{#1 >shrun.tmp 2>&1}%
1496 \immediate\write18{./shreformat.sh}%
1497 \shautoread{#1}{shrun-formatted.tmp}%
1498 }{%
1499 \ifthenelse{\equal{\sh@autoformat}{false}}{}%
1500 {\typeout{-----------------------------------------------}%
1501 \typeout{ Package shdoc info: I don't know what you}%
1502 \typeout{ mean when passing '\sh@autoformat' to autoformat}%
1503 \typeout{ and I'm going to ignore it and restore the}%
1504 \typeout{default 'false'}%
1505 \typeout{-----------------------------------------------}%
1506 \shautoformat{false}}%
1507 \immediate\write18{#1 >shrun.tmp 2>&1}%
1508 \shautoread{#1}{shrun.tmp}%
1509 }%
1510 }
1511 % \end{macrocode}
1512 %\end{macro}
1513 %
1514 %
1515 %\begin{macro}{\shclearfiles}
1516 % \cmd{\shclearfiles} removes all the temporary files by calling the shell command '\texttt{rm}'.
1517 % \begin{macrocode}
1518 \def\shclearfiles{
1519 \immediate\write18{rm shrun.tmp; rm shrun-formatted.tmp; rm shpath.tmp}
1520 }
1521 % \end{macrocode}
1522 %\end{macro}
1523 %
1524 % \noindent Finally, the mdframed box is defined through the environment definition command of the
1525 % \textit{mdframed} package. The frameline color is white and the default backgroundcolor
1526 % is set. Further, the linecounter is set to 1, when the \cmd{\shbox} environment is started.
1527 %\begin{macro}{\shbox}
1528 % \begin{macrocode}
1529 \newmdenv[linecolor=white,backgroundcolor=\shdoc@backgroundcolor,
1530 settings=\setcounter{shlinenumber}{1}]{shbox}
1531 % \end{macrocode}
1532 %\end{macro}
1533 % \begin{macrocode}
1534 \makeatother
1535 %</package>
1536 % \end{macrocode}
1537 %\Finale
1538 %
1539