% \iffalse meta-comment
% SPDX-FileCopyrightText: Copyright (c) 2021-2026 Yegor Bugayenko
% SPDX-License-Identifier: MIT
% \fi

% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}

% \GetFileInfo{docshots.dtx}
% \DoNotIndex{\endgroup,\begingroup,\let,\else,\s,\n,\r,\\,\1,\fi}

% \iffalse
%<*driver>
\ProvidesFile{docshots.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{docshots}
%<*package>
[2026-07-15 0.5.0 TeX Samples Next to Their PDF Snapshots in DTX]
%</package>
%<*driver>
\documentclass{ltxdoc}
\usepackage{lmodern}
\usepackage{microtype}
\AddToHook{env/verbatim/begin}{\microtypesetup{protrusion=false}}
\usepackage[dtx]{docshots}
\usepackage{href-ul}
\usepackage{xcolor}
\PageIndex
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{docshots.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi

% \title{|docshots|: \LaTeX{} Package that Renders \\ \TeX{} Samples Next to Their \\ PDF Snapshots\thanks{The sources are in GitHub at \href{https://github.com/yegor256/docshots}{yegor256/docshots}}}
% \author{Yegor Bugayenko \\ \texttt{yegor256@gmail.com}}
% \date{\filedate, \fileversion}
%
% \maketitle
%
% The \TeX{} processor must be invoked with the |--shell-escape| option,
% and the following must be installed on the host system:
% |pdflatex|,
% \href{https://www.perl.org}{Perl},
% \href{https://www.ghostscript.com}{Ghostscript},
% and \href{https://ctan.org/pkg/pdfcrop}{pdfcrop}.
% The |--shell-escape| option is required because the package launches these
% external programs from within the \TeX{} run in order to compile and crop each snippet.
% The package operates on Windows as well as on Unix, provided these tools are on the |PATH|.

% \section{Introduction}
%
% When demonstrating to the readers of a document how certain \TeX{}
% commands are to be employed, the most cogent approach is to display
% precisely how the entire document will be rendered as a PDF, by means
% of a subprocess (such as |pdflatex|) that performs the rendering.
% To the \href{https://tex.stackexchange.com/questions/661027}{author's
% best} knowledge, no existing package addresses this need; hence the
% present, modest package was devised.

% For instance, the following code:
%\iffalse%
%<*verb>%
%\fi%
\begin{verbatim}
\begin{docshot}
\documentclass{article}
\usepackage{xcolor}
\pagestyle{empty}
\begin{document}
  Hello, {\color{orange}\LaTeX}!
\end{document}
\end{docshot}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% is rendered thus:
% \begin{docshot}
% \documentclass{article}
% \usepackage{xcolor}
% \pagestyle{empty}
% \begin{document}
%   Hello, {\color{orange}\LaTeX}!
% \end{document}
% \end{docshot}

% A more elaborate example follows:
% \begin{docshot}
% \documentclass{article}
% \usepackage{tikz}
% \pagestyle{empty}
% \begin{document}
% \begin{tikzpicture}
% \node [circle,draw] (v0) {$v_0$};
% \node [circle,draw=orange,thick,
%   below right of=v0] (v1) {$v_1$};
% \draw [->] (v0) -- (v1);
% \end{tikzpicture}
% \end{document}
% \end{docshot}

% The body of every |docshot| environment must be a complete, self-contained
% \LaTeX{} document: it begins with |\documentclass|, loads whatever packages it
% requires, and wraps its content in |\begin{document}| and |\end{document}|. The
% body is written verbatim to a separate |.tex| file and compiled on its own, exactly
% as the two examples above demonstrate.

% The figure on the left is produced by a subprocess that executes
% |pdflatex| on the |.tex| content extracted from the source file.
% Once the \TeX{} sources have been successfully processed,
% \href{https://ctan.org/pkg/pdfcrop}{pdfcrop} is invoked to trim the document.

% |pdflatex| is run with the |-interaction=errorstopmode| and |-halt-on-error| options.
% Consequently, \TeX{} processing halts at the first error encountered. The \TeX{}
% log should be consulted to ascertain the cause of any failure; the |log| option,
% described below, copies the full output of |pdflatex| into that log.

% Whenever text rather than a single figure is to be rendered, the
% \href{https://ctan.org/pkg/geometry}{geometry} package is recommended for
% adjusting the page dimensions:
% \begin{docshot}
% \documentclass{article}
% \usepackage[paperwidth=2in,
%   paperheight=2.3in]{geometry}
% \begin{document}
% ``There is no sadder thing than
% a young pessimist, except an old
% pessimist'' --- \emph{Mark Twain}
% \end{document}
% \end{docshot}
% The use of |\pagestyle{empty}|, as in the preceding docshots, is likewise possible.

% \section{Package Options}

% All options listed below are supplied to the package in the usual way, within the
% optional argument of |\usepackage[...]{docshots}|.

% \DescribeMacro{pdflatex}
% The default command-line tool for converting |.tex| into
% |.pdf| is |pdflatex|. This may, however, be altered by means of the |pdflatex| package option,
% for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\documentclass{article}
\usepackage[pdflatex=/usr/local/bin/pdflatex]{docshots}
\begin{document}
\begin{docshot}
Hello, world!
\end{docshot}
\end{document}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{gs}
% The default location of Ghostscript is simply |gs| on Unix and |gswin64c| on Windows.
% This may be altered by means of the |gs| package option,
% for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[gs=/usr/bin/ghostscript]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{pdfcrop}
% The default location of |pdfcrop| is simply |pdfcrop|.
% This may be altered by means of the |pdfcrop| package option,
% for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[pdfcrop=/bin/pdfcrop]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{margin}
% When the rendered PDF is cropped, a margin is preserved around the content. The
% default value may be modified by the |margin| package option:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[margin=10]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{nocrop}
% Cropping may be disabled by means of the |nocrop| option:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[nocrop]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{hspace}
% The horizontal distance between the image and its verbatim \TeX{} source
% may be configured by means of the |hspace| package option:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[hspace=1em]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{left}
% \DescribeMacro{right}
% The default width of the image may be altered by the |left| option, while
% the width of the verbatim \TeX{} source may be adjusted by the |right| option:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[left=2in,right=.5\linewidth]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{dtx}
% Whenever this package is employed within |.dtx| documentation, the |dtx| package option must be added. Under
% this option, all leading comment symbols (the |%| characters) are removed from the start of each line:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[dtx]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{tmpdir}
% The default location for temporary files is |_docshots|. This may be altered by means of the |tmpdir| option:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[tmpdir=/tmp/foo]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{runs}
% By default, |pdflatex| is invoked but once per docshot. This number may be modified by means of the |runs| package
% option, which proves serviceable when Bib\TeX{} processing is required, for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[runs=3]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{small}
% \DescribeMacro{tiny}
% The latitude available for formatting verbatim texts is limited; nevertheless, the font
% may be reduced somewhat by means of the |small| package option, or made considerably
% smaller still by the |tiny| option:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[small]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{log}
% By means of the |log| option, the package writes all available logs into the main \TeX{} log.
% By default, this is not done, and the output of |pdflatex| compilation, for instance, remains hidden.
% The option is employed thus:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage[log]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{inputminted}
% By default, the verbatim text is rendered by means of the |\VerbatimInput| command. This
% may be substituted with |\inputminted|
% from the \href{https://ctan.org/pkg/minted}{minted} package, for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage{minted}
\setminted[java]{frame=lines,framesep=2mm}
\usepackage[inputminted=java]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{lstinputlisting}
% By default, the verbatim text is rendered by means of the |\VerbatimInput| command. This
% may be substituted with |\lstinputlisting| from the
% \href{https://ctan.org/pkg/listings}{listings} package, for example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\usepackage{listings}
\lstset{basicstyle=\small}
\usepackage[lstinputlisting]{docshots}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \section{Fine-tuning Options}

% \DescribeMacro{\docshotOptions}
% By default, the verbatim text is rendered by means of the |\VerbatimInput| command with
% no options. Additional options may be supplied via the |\docshotOptions| command:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\docshotOptions{firstline=4}
\begin{docshot}
...
\end{docshot}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% The options are cleared upon the first rendering of a docshot.

% \section{Prerequisites}

% \DescribeMacro{\docshotPrerequisite}
% \changes{0.0.3}{2022/10/14}{The command is added to enable copying of supplementary files into the directory where docshot snippets are processed.}
% Whenever certain files are required to be present alongside the |.tex| snippet during
% rendering by |pdflatex|, the |\docshotPrerequisite| command may be employed, accepting
% a single mandatory argument. The argument denotes the name of a file to be copied from
% the current directory to the temporary directory in which all snippets are rendered. The
% command may appear either in the body of the document or in the preamble---the placement is
% immaterial, provided that it precedes the docshot which requires the prerequisite. For example:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\documentclass{article}
\usepackage{docshots}
\docshotPrerequisite{duck.jpg}
\begin{document}
\begin{docshot}
  \documentclass{article}
  \usepackage{graphicx}
  \pagestyle{empty}
  \begin{document}
    A favoured photograph of a duck:
    \includegraphics[width=2in]{duck.jpg}
  \end{document}
\end{docshot}
\end{document}
\end{verbatim}
%\iffalse
%</verb>
%\fi

% \DescribeMacro{\docshotAfter}
% Should some action be required after each |pdflatex| run of a docshot, the
% |\docshotAfter| command may be placed immediately before the |docshot| environment. For example, when a bibliography file is to remain
% available to every snippet and \href{https://ctan.org/pkg/biber}{biber} is to be invoked
% on each in order to process citations:
%\iffalse
%<*verb>
%\fi
\begin{verbatim}
\documentclass{article}
\usepackage{docshots}
\docshotPrerequisite{main.bib}
\begin{document}
\docshotAfter{biber $2}
\begin{docshot}
  \documentclass{acmart}
  \usepackage[natbib=true]{biblatex}
  \addbibresource{main.bib}
  \pagestyle{empty}
  \begin{document}
    The book of \citet{knuth1984} is essential reading.
    \printbibliography
  \end{document}
\end{docshot}
\end{document}
\end{verbatim}
%\iffalse
%</verb>
%\fi
% The script supplied as the first argument of |\docshotAfter| receives
% three arguments at runtime:
% \begin{description}\setlength\itemsep{0em}
% \item[|\$1|] the cycle of |pdflatex| processing (1, 2, ...),
% \item[|\$2|] the hash of the snippet,
% \item[|\$3|] the name of the |.tex| file.
% \end{description}
% |$3| is, in essence, |$2| with an appended |.tex| suffix. |\docshotAfter|
% applies solely to the first |docshot| environment that follows it; |\docshotAfter|
% must therefore be specified before every |docshot| in which such post-processing
% is desired.

% \StopEventually{}

% \section{Implementation}
% \changes{0.0.1}{2022/10/09}{Initial version}

% First, we include \href{https://ctan.org/pkg/iexec}{iexec}
% in order to execute shell commands, such as |pdflatex| and |pdfcrop|:
%    \begin{macrocode}
\RequirePackage{iexec}
%    \end{macrocode}

% Then, we include \href{https://ctan.org/pkg/fancyvrb}{fancyvrb}
% in order to render verbatim texts:
%    \begin{macrocode}
\RequirePackage{fancyvrb}
%    \end{macrocode}

% Then, we include \href{https://ctan.org/pkg/xcolor}{xcolor}
% in order to make borders gray:
%    \begin{macrocode}
\RequirePackage{xcolor}
%    \end{macrocode}

% Then, we include \href{https://ctan.org/pkg/graphicx}{graphicx}
% in order to be able to use the |\includegraphics| command:
%    \begin{macrocode}
\RequirePackage{graphicx}
%    \end{macrocode}

% Then, we include \href{https://ctan.org/pkg/tikz}{tikz}
% in order to be able to position elements:
%    \begin{macrocode}
\RequirePackage{tikz}
%    \end{macrocode}

% Then, we process package options with the help of \href{https://ctan.org/pkg/pgfopts}{pgfopts}:
% \changes{0.0.4}{2022/10/18}{Package options "lstinputlisting" and "inputminted" introduced to enable printing of verbatim text via either the listings or the minted package.}
% \changes{0.0.5}{2022/10/24}{Package option "log" added, which enables detailed logging via exec. By default, there is no logging at all.}
% \changes{0.2.0}{2022/10/26}{New package option "nocrop" added to allow disabling of "pdfcrop" execution.}
% We also detect Windows, in order to pick the right default for Ghostscript,
% the right file separator for shell commands (a backslash, since |cmd.exe|
% rejects forward slashes in redirection targets), and an expanding variant of
% the string-replacement command for later use in \docshotAfter:
% \changes{0.5.0}{2026/07/13}{Windows compatibility: file operations go through Perl, and the "gs" default becomes "gswin64c" on Windows.}
%    \begin{macrocode}
\RequirePackage{pgfopts}
\RequirePackage{ifluatex}
\RequirePackage{ifxetex}
\RequirePackage{expl3}
\newif\ifdocshots@windows
\ExplSyntaxOn
\sys_if_platform_windows:TF{\docshots@windowstrue}{\docshots@windowsfalse}
\cs_generate_variant:Nn \str_replace_all:Nnn { Nne }
\newcommand\docshots@aftercmd[3]{%
  \str_set:Nx \l_tmpa_str { \docshots@after }%
  \str_replace_all:Nne \l_tmpa_str { $1 } { #1 }%
  \str_replace_all:Nne \l_tmpa_str { $2 } { #2 }%
  \str_replace_all:Nne \l_tmpa_str { $3 } { #3 }%
  \cs_set:Npx \docshots@aftersh { \str_use:N \l_tmpa_str }%
}
\ExplSyntaxOff
\ifdocshots@windows
  \def\docshots@gsdefault{gswin64c}%
  \edef\docshots@sep{\@backslashchar}%
\else
  \def\docshots@gsdefault{gs}%
  \def\docshots@sep{/}%
\fi
%    \end{macrocode}
% On Unix we render inside the temporary directory. On Windows we cannot, since
% |cmd.exe| keeps a |cd| in effect after the parentheses close, which would send
% iexec's exit-code file to the wrong place; instead we stay put and point
% |pdflatex| at the directory with |-output-directory|. The |pdflatex| arguments
% keep forward slashes, since \TeX{} reads a backslash as an escape character:
%    \begin{macrocode}
\ifdocshots@windows
  \def\docshots@render{"\docshots@pdflatex"
    -interaction=errorstopmode -halt-on-error -shell-escape
    -output-directory="\docshots@tmpdir/\jobname"
    "\docshots@tmpdir/\jobname/\hash.tex"}%
\else
  \def\docshots@render{cd "\docshots@tmpdir/\jobname" &&
    "\docshots@pdflatex"
    -interaction=errorstopmode -halt-on-error -shell-escape
    \hash.tex}%
\fi
\def\docshots@log{}
\pgfkeys{
  /docshots/.cd,
  dtx/.store in=\docshots@dtx,
  log/.code=\def\docshots@log{log},
  nocrop/.code=\def\docshots@nocrop{},
  lstinputlisting/.store in=\docshots@lstinputlisting,
  inputminted/.store in=\docshots@inputminted,
  tmpdir/.store in=\docshots@tmpdir,
  tmpdir/.default=_docshots\ifxetex-xe\else\ifluatex-lua\fi\fi,
  small/.store in=\docshots@small,
  tiny/.store in=\docshots@tiny,
  runs/.store in=\docshots@runs,
  runs/.default=1,
  pdflatex/.store in=\docshots@pdflatex,
  pdflatex/.default=pdflatex,
  gs/.store in=\docshots@gs,
  gs/.default=\docshots@gsdefault,
  pdfcrop/.store in=\docshots@pdfcrop,
  pdfcrop/.default=pdfcrop,
  margin/.store in=\docshots@margin,
  margin/.default=5,
  hspace/.store in=\docshots@hspace,
  hspace/.default=.05\linewidth,
  left/.store in=\docshots@left,
  left/.default=.3\linewidth,
  right/.store in=\docshots@right,
  right/.default=.55\linewidth,
  tmpdir,pdflatex,gs,pdfcrop,margin,hspace,left,right,runs
}
\ProcessPgfOptions{/docshots}
%    \end{macrocode}

% Then, we print the version of |pdflatex| to the \TeX{} log:
%    \begin{macrocode}
\iexec[\docshots@log,quiet]{"\docshots@pdflatex" --version}%
%    \end{macrocode}

% Then, we print the version of \href{https://ctan.org/pkg/pdfcrop}{pdfcrop} to the \TeX{} log:
%    \begin{macrocode}
\ifdefined\docshots@nocrop\else%
  \iexec[\docshots@log,quiet]{"\docshots@pdfcrop" --version}%
\fi%
%    \end{macrocode}

% Then, we print the version of |ghostscript| to the \TeX{} log, ignoring a
% failure, since Ghostscript is not strictly required for rendering:
%    \begin{macrocode}
\iexec[\docshots@log,quiet,ignore]{"\docshots@gs" --version}%
%    \end{macrocode}

% Then, we make a directory where all temporary files will be kept. We use
% Perl instead of |mkdir|, so that the code works on Windows too:
%    \begin{macrocode}
\iexec[null]{perl -MFile::Path=make_path -e "make_path(shift)"
  "\docshots@tmpdir/\jobname"}%
%    \end{macrocode}

% \begin{macro}{\docshots@mdfive}
% \changes{0.1.1}{2022/10/26}{New supplementary command added to calculate MD5 sum of a file.}
% Then, we define a command for MD5 hash calculating of a file, with
% the help of \href{https://ctan.org/pkg/pdftexcmds}{pdftexcmds}:
%    \begin{macrocode}
\RequirePackage{pdftexcmds}
\makeatletter
\newcommand\docshots@mdfive[1]{\pdf@filemdfivesum{#1}}
\makeatother
%    \end{macrocode}
% \end{macro}

% \begin{macro}{docshot}
% Then, we define |docshot| environment:
%    \begin{macrocode}
\makeatletter
\newenvironment{docshot}
{\VerbatimEnvironment\begin{VerbatimOut}
  {\docshots@tmpdir/\jobname/docshots-temp.tex}}
{\end{VerbatimOut}%
%    \end{macrocode}
% If we are in |dtx| mode, leading percent characters must be removed:
% \changes{0.3.1}{2022/11/20}{A bug fixed, now handling of leading percentage symbols is done right.}
%    \begin{macrocode}
  \ifdefined\docshots@dtx%
    \iexec[null]{perl -i -0777pe "s/(\\n|^)\\x{25}\\s?/\\1/g"
      \docshots@tmpdir/\jobname/docshots-temp.tex}%
  \fi%
%    \end{macrocode}
% We calculate MD5 hashsum of the file content:
%    \begin{macrocode}
  \def\hash{\docshots@mdfive{\docshots@tmpdir/\jobname/docshots-temp.tex}}%
%    \end{macrocode}
% If the PDF with the required name already exists, we ignore this step.
% Otherwise, we copy |docshots-temp.tex| into a new file and run |pdflatex|:
% \changes{0.1.0}{2022/10/26}{The output is saved to a hash-named file, for better uniqueness of temporary files.}
% \changes{0.4.0}{2022/11/29}{Now, \TeX output has a log message with the number of the line in the source file, which we render.}
%    \begin{macrocode}
  \IfFileExists{\docshots@tmpdir/\jobname/\hash.pdf}
    {\message{docshots: Won't render,
      the PDF '\docshots@tmpdir/\jobname/\hash.pdf' already exists^^J}}
    {\iexec[\docshots@log,quiet]{perl -MFile::Copy -e "copy(shift,shift) or die q(cannot copy)"
      "\docshots@tmpdir/\jobname/docshots-temp.tex"
      "\docshots@tmpdir/\jobname/\hash.tex"}%
    \message{docshots: rendering at line no. \the\inputlineno^^J}%
    \foreach \n in {1,...,\docshots@runs}{%
      \iexec[\docshots@log,
        stdout=\docshots@tmpdir\docshots@sep\jobname\docshots@sep\hash.stdout,
        exit=\docshots@tmpdir\docshots@sep\jobname\docshots@sep\hash.ret,
        quiet,trace]{\docshots@render}%
      \ifnum\n=1\else%
        \message{docshots: pdflatex run no.\n^^J}%
      \fi%
%    \end{macrocode}
% If a post-processing command was registered by \docshotAfter, we substitute
% its |$1|, |$2|, and |$3| placeholders and execute it. There is no shell script
% and no |chmod|, so the mechanism works on Windows too:
%    \begin{macrocode}
      \ifdefined\docshots@after%
        \begingroup%
          \docshots@aftercmd{\n}{\hash}{\hash.tex}%
          \iexec[\docshots@log,quiet]{cd "\docshots@tmpdir\docshots@sep\jobname" &&
            \docshots@aftersh}%
        \endgroup%
      \fi}}%
  \global\let\docshots@after\@undefined%
%    \end{macrocode}
% If a cropped version of the PDF with the required name already exists, we ignore this step.
% Otherwise, we ask |pdfcrop| to crop the PDF:
%    \begin{macrocode}
  \IfFileExists{\docshots@tmpdir/\jobname/\hash.crop.pdf}
    {\message{docshots: Won't pdfcrop,
      the PDF '\docshots@tmpdir/\jobname/\hash.crop.pdf'
      already exists^^J}}
    {\ifdefined\docshots@nocrop
      \iexec[\docshots@log,quiet]{perl -MFile::Copy -e "copy(shift,shift) or die q(cannot copy)"
        "\docshots@tmpdir/\jobname/\hash.pdf"
        "\docshots@tmpdir/\jobname/\hash.crop.pdf"}%
      \else%
      \iexec[\docshots@log,quiet]{"\docshots@pdfcrop"
        --gscmd "\docshots@gs"
        --margins 0
        "\docshots@tmpdir/\jobname/\hash.pdf"
        "\docshots@tmpdir/\jobname/\hash.crop.pdf"}%
      \fi}%
  \message{docshots: the PDF is ready from line no. \the\inputlineno^^J}%
%    \end{macrocode}
% Finally, we render the two-column content:
%    \begin{macrocode}
  \begingroup%
  \par%
  \tikz[baseline=(a.north)]
    \node (a) [draw=gray,inner sep=\docshots@margin,
      line width=.2pt]
    {\includegraphics[width=\docshots@left]
      {\docshots@tmpdir/\jobname/\hash.crop.pdf}};%
  \hspace{\docshots@hspace}%
  \begin{minipage}[t]{\docshots@right}%
    \vspace{0pt}%
    \ifdefined\docshots@lstinputlisting%
      \ifdefined\docshots@opts%
        \expandafter\lstset\expandafter{\docshots@opts}%
      \fi%
      \lstinputlisting{\docshots@tmpdir/\jobname/\hash.tex}%
    \else\ifdefined\docshots@inputminted%
      \expandafter\inputminted\expandafter[\docshots@opts]
        {\docshots@inputminted}
        {\docshots@tmpdir/\jobname/\hash.tex}%
    \else%
      \fvset{numbers=left,numbersep=3pt}%
      \fvset{frame=leftline,framerule=.2pt,rulecolor=\color{gray}}%
      \fvset{samepage=true}%
      \fvset{commandchars=none}%
      \fvset{baselinestretch=1}%
      \ifdefined\docshots@small%
        \fvset{fontsize=\small}%
      \fi%
      \ifdefined\docshots@tiny%
        \fvset{fontsize=\scriptsize}%
      \fi%
      \ifdefined\docshots@opts%
        \expandafter\fvset\expandafter{\docshots@opts}%
      \fi%
      \VerbatimInput{\docshots@tmpdir/\jobname/\hash.tex}%
    \fi\fi%
    \vspace{0pt}%
  \end{minipage}%
  \par%
  \endgroup%
  \docshotOptions{}%
}
\makeatother
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\docshotPrerequisite}
% Then, we define |\docshotPrerequisite| command:
%    \begin{macrocode}
\makeatletter
\newcommand\docshotPrerequisite[1]{
  \iexec[\docshots@log,quiet]{perl -MFile::Copy -e "copy(shift,shift) or die q(cannot copy)"
    "#1" "\docshots@tmpdir/\jobname/#1"}%
  \message{docshots: File '#1' copied to
    '\docshots@tmpdir/\jobname/#1'^^J}%
}
\makeatother
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\docshotAfter}
% Then, we define |\docshotAfter| command. Rather than writing a shell script,
% we merely remember the command as a detokenized string; the |docshot|
% environment substitutes its placeholders and runs it after each |pdflatex|:
% \changes{0.5.0}{2026/07/13}{The command is remembered as a string and executed directly, instead of being written to a shell script, for Windows compatibility.}
%    \begin{macrocode}
\makeatletter
\newcommand\docshotAfter[1]{
  \xdef\docshots@after{\detokenize{#1}}%
  \message{docshots: post-processing command '\docshots@after' registered^^J}%
}
\makeatother
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\docshotOptions}
% Finally, we define |\docshotOptions| command:
% \changes{0.3.0}{2022/11/10}{New command introduced to help specify custom options for verbatim environments.}
%    \begin{macrocode}
\makeatletter
\gdef\docshots@opts{}
\newcommand\docshotOptions[1]{%
  \gdef\docshots@opts{#1}%
}
\makeatother
%    \end{macrocode}
% \end{macro}

%    \begin{macrocode}
\endinput
%    \end{macrocode}

% \Finale

%\clearpage

%\PrintChanges
%\clearpage
%\PrintIndex