CTAN sync 202210170304

4 files changed, 216 insertions, 53 deletions

diff --git a/macros/latex/contrib/docshots/DEPENDS.txt b/macros/latex/contrib/docshots/DEPENDS.txt
index d8361a6695..194336badc 100644
--- a/macros/latex/contrib/docshots/DEPENDS.txt
+++ b/macros/latex/contrib/docshots/DEPENDS.txt
@@ -3,3 +3,4 @@ hard fancyvrb
 hard pdfcrop
 hard pgf
 hard pgf-blur
+hard pgfopts
diff --git a/macros/latex/contrib/docshots/README.md b/macros/latex/contrib/docshots/README.md
index 6201451a88..3e8327ed79 100644
--- a/macros/latex/contrib/docshots/README.md
+++ b/macros/latex/contrib/docshots/README.md
@@ -2,20 +2,22 @@
 [![CTAN](https://img.shields.io/ctan/v/docshots)](https://ctan.org/pkg/docshots)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/docshots/blob/master/LICENSE.txt)
 
-This LaTeX package helps you add PDF snapshots to DTX documentation.
+This LaTeX package helps you show TeX code next to their PDF snapshots,
+in two-column formatting. You can use it either in `.dtx` documentation
+or in `.tex` file.
 
 First, [install it](https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages)
 from [CTAN](https://ctan.org/pkg/docshots)
-and then use in DTX:
+and then use like this:
 
 ```tex
-% \begin{docshot}
-% \documentclass{article}
-% \pagestyle{empty}
-% \begin{document}
-%   Hello, \LaTeX!
-% \end{document}
-% \end{docshot}
+\begin{docshot}
+\documentclass{article}
+\pagestyle{empty}
+\begin{document}
+  Hello, \LaTeX!
+\end{document}
+\end{docshot}
 ```
 
 If you want to contribute yourself, make a fork, then create a branch, 
diff --git a/macros/latex/contrib/docshots/docshots.dtx b/macros/latex/contrib/docshots/docshots.dtx
index 3fa5c9ac13..65eade188b 100644
--- a/macros/latex/contrib/docshots/docshots.dtx
+++ b/macros/latex/contrib/docshots/docshots.dtx
@@ -50,14 +50,15 @@
 %<package>\NeedsTeXFormat{LaTeX2e}
 %<package>\ProvidesPackage{docshots}
 %<*package>
-[2022-10-14 0.0.1 TeX Samples Next to Their PDF Snapshots in DTX]
+[2022-10-16 0.0.2 TeX Samples Next to Their PDF Snapshots in DTX]
 %</package>
 %<*driver>
 \documentclass{ltxdoc}
 \usepackage[tt=false, type1=true]{libertine}
 \usepackage{microtype}
-\usepackage{docshots}
+\usepackage[dtx]{docshots}
 \usepackage{href-ul}
+\usepackage{xcolor}
 \PageIndex
 \EnableCrossrefs
 \CodelineIndex
@@ -70,46 +71,63 @@
 %</driver>
 % \fi
 
-% \title{|docshots|: \TeX{} Samples Next to Their \\ PDF Snapshots in DTX\thanks{The sources are in GitHub at \href{https://github.com/yegor256/docshots}{yegor256/docshots}}}
+% \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
 %
-% \textbf{NB!}
+% \textbf{\color{red}NB!}
 % You must run \TeX{} processor with |--shell-escape| option
-% and you must have \href{https://www.perl.org}{Perl} installed.
+% and you must have
+% \href{...}{pdflatex},
+% \href{https://www.perl.org}{Perl},
+% \href{...}{Ghostscript},
+% and \href{https://ctan.org/pkg/pdfcrop}{pdfcrop}
+% installed.
 
 % \section{Introduction}
 %
-% You put this into your |.dtx| file:
-%
-% \vspace{0pt}\begingroup\ttfamily\noindent
-% \% \char`\\begin\char`\{docshot\char`\} \\
-% \% \char`\\documentclass\char`\{article\char`\} \\
-% \% \char`\\begin\char`\{document\char`\} \\
-% \% \char`\\pagestyle\char`\{empty\char`\} \\
-% \% ~~Hello, \char`\\LaTeX! \\
-% \% \char`\\end\char`\{document\char`\} \\
-% \% \char`\\end\char`\{docshot\char`\}
-% \endgroup\vspace{0pt}
-%
-% It will be rendered as such:
+% When you want to demonstrate to the readers of your documentation
+% how to use certain \TeX{} commands, the best way would be
+% to show exactly how the entire document will be rendered in PDF,
+% using a subprocess that would render it (via |pdflatex|, for example).
+% To my best knowledge, there were no packages that would allow
+% you do exactly this. That's why I created this simple package.
+% For example, this code:
 %
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\begin{docshot}
+\documentclass{article}
+\usepackage{xcolor}
+\begin{document}
+\pagestyle{empty}
+  Hello, {\color{orange}\LaTeX}!
+\end{document}
+\end{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+% is rendered as such:
 % \begin{docshot}
 % \documentclass{article}
+% \usepackage{xcolor}
 % \begin{document}
 % \pagestyle{empty}
-%   Hello, \LaTeX!
+%   Hello, {\color{orange}\LaTeX}!
 % \end{document}
 % \end{docshot}
 
 % Here is a more complex example:
-%
 % \begin{docshot}
 % \documentclass{article}
 % \usepackage{tikz}
-% \begin{document}\pagestyle{empty}
+% \begin{document}
+% \pagestyle{empty}
 % \begin{tikzpicture}
 % \node [circle,draw] (v0) {$v_0$};
 % \node [circle,draw,
@@ -119,11 +137,118 @@
 % \end{document}
 % \end{docshot}
 
-% The pictures you see on the left sides are rendered by a subprocess
-% executing |pdflatex| with the |.tex| content taken from |dtx| file.
+% The picture you see on the left side is rendered by a subprocess
+% executing |pdflatex| with the |.tex| content taken from the source file.
 % After a successful processing of \TeX{} sources, we use
-% \href{https://ctan.org/pkg/pdfcrop}{pdfcrop} to trim the document. Then,
-% the trimmed PDF is embedded into the final document.
+% \href{https://ctan.org/pkg/pdfcrop}{pdfcrop} to trim the document.
+
+% We execute |pdflatex| with |-interaction=batchmode| option. This means that
+% \TeX{} processing errors will be ignored as much as possible and the PDF
+% rendered may look not like you expect it to look. Check your \TeX{} log
+% to understand what may go wrong.
+
+% \section{Package Options}
+
+% \DescribeMacro{pdflatex}
+% The default command line tool for turning |.tex| into
+% |.pdf| is |pdflatex|. However, you can change that by using |pdflatex| package option,
+% for example:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\documentclass{article}
+\usepackage[pdflatex=/usr/local/bin/pdflatex]{docshot}
+\begin{document}
+\begin{docshot}
+Hello, world!
+\end{docshot}
+\end{document}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{gs}
+% The default location of Ghostscript is just |gs|.
+% You can change that by using |gs| package option,
+% for example:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[gs=/usr/bin/ghostscript]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{pdfcrop}
+% The default location of |pdfcrop| is just |pdfcrop|.
+% You can change that by using |pdfcrop| package option,
+% for example:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[pdfcrop=/bin/pdfcrop]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{margin}
+% When we crop the PDF rendered, we leave a margin around the content. The
+% default value may be changed by the package option |margin|:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[margin=10]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{hspace}
+% The horizontal distance between the image and its verbatim \TeX{} source
+% may be configured via |hspace| package option:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[hspace=1em]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{left}
+% \DescribeMacro{right}
+% The default width of the image may be changed by |left| option, while
+% the width of the verbatim \TeX{} source may be modified by |right| option:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[left=2in,right=.5\linewidth]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{dtx}
+% If you use this package inside |.dtx| documentation, add |dtx| package option. Thanks
+% to this option all comment symbols will be removed from line starts:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[dtx]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
 
 % \StopEventually{}
 
@@ -141,19 +266,44 @@
 \usetikzlibrary{shadows.blur}
 %    \end{macrocode}
 
-% Then, we show the version of |pdflatex|:
+% Then, we process package options:
+%    \begin{macrocode}
+\RequirePackage{pgfopts}
+\pgfkeys{
+  /docshots/.cd,
+  dtx/.store in=\docshots@dtx,
+  pdflatex/.store in=\docshots@pdflatex,
+  pdflatex/.default=pdflatex,
+  gs/.store in=\docshots@gs,
+  gs/.default=gs,
+  pdfcrop/.store in=\docshots@pdfcrop,
+  pdfcrop/.default=pdfcrop,
+  margin/.store in=\docshots@margin,
+  margin/.default=5,
+  hspace/.store in=\docshots@hspace,
+  hspace/.default=1.8em,
+  left/.store in=\docshots@left,
+  left/.default=.3\linewidth,
+  right/.store in=\docshots@right,
+  right/.default=.65\linewidth,
+  pdflatex,gs,pdfcrop,margin,hspace,left,right
+}
+\ProcessPgfOptions{/docshots}
+%    \end{macrocode}
+
+% Then, we print the version of |pdflatex| to \TeX{} log:
 %    \begin{macrocode}
-\iexec[log,quiet]{pdflatex --version}%
+\iexec[log,quiet]{\docshots@pdflatex\space --version}%
 %    \end{macrocode}
 
-% Then, we show the version of |pdfcrop|:
+% Then, we print the version of \href{https://ctan.org/pkg/pdfcrop}{pdfcrop} to \TeX{} log:
 %    \begin{macrocode}
-\iexec[log,quiet]{pdfcrop --version}%
+\iexec[log,quiet]{\docshots@pdfcrop\space --version}%
 %    \end{macrocode}
 
-% Then, we show the version of |ghostscript|:
+% Then, we print the version of |ghostscript| to \TeX{} log:
 %    \begin{macrocode}
-\iexec[log,quiet]{gs --version}%
+\iexec[log,quiet]{\docshots@gs\space --version}%
 %    \end{macrocode}
 
 % Then, we make a directory where all temporary files will be kept:
@@ -165,26 +315,36 @@
 % Then, we define |docshot| environment:
 %    \begin{macrocode}
 \newenvironment{docshot}
-{\VerbatimEnvironment\begin{VerbatimOut}{_docshots/\jobname/verbatim.tex}}
+{\VerbatimEnvironment\begin{VerbatimOut}
+  {_docshots/\jobname/verbatim.tex}}
 {\end{VerbatimOut}%
-  \iexec[null]{perl -i -0777pe "s/(\\n|^)\\x{25} /\\1/g"
-    _docshots/\jobname/verbatim.tex}%
+  \ifdefined\docshots@dtx%
+    \iexec[null]{perl -i -0777pe "s/(\\n|^)\\x{25} /\\1/g"
+      _docshots/\jobname/verbatim.tex}%
+  \fi%
   \def\hash{\pdfmdfivesum file {_docshots/\jobname/verbatim.tex}}%
-  \message{^^Jdocshots: name set to "\hash"^^J}%
-  \iexec[log,quiet]{cp _docshots/\jobname/verbatim.tex
-    _docshots/\jobname/\hash.tex}%
-  \iexec[log,quiet]{(cd _docshots/\jobname;
-    pdflatex -interaction=batchmode -shell-escape \hash.tex)}%
-  \iexec[log,quiet]{pdfcrop --margins 5 _docshots/\jobname/\hash.pdf
-    _docshots/\jobname/\hash.crop.pdf}%
+  \IfFileExists{_docshots/\jobname/\hash.pdf}
+    {\message{won't render, the PDF already exists: _docshots/\jobname/\hash.pdf^^J}}
+    {\iexec[log,quiet]{cp _docshots/\jobname/verbatim.tex
+      _docshots/\jobname/\hash.tex}%
+    \iexec[log,quiet]{cd _docshots/\jobname;
+      \docshots@pdflatex\space -interaction=batchmode
+      -shell-escape \hash.tex}}%
+  \IfFileExists{_docshots/\jobname/\hash.crop.pdf}
+    {\message{won't pdfcrop, the PDF already exists: _docshots/\jobname/\hash.crop.pdf^^J}}
+    {\iexec[log,quiet]{\docshots@pdfcrop\space
+      --margins \docshots@margin\space
+      _docshots/\jobname/\hash.pdf
+      _docshots/\jobname/\hash.crop.pdf}}%
   \fvset{frame=leftline,numbers=left,numbersep=3pt,
       framerule=.4pt,rulecolor=\color{gray},
       samepage=true}%
   \par%
   \tikz[baseline=(a.north)] \node[draw=gray] (a)
-    {\includegraphics[width=.3\linewidth]{_docshots/\jobname/\hash.crop.pdf}};%
-  \hspace{1.8em}%
-  \begin{minipage}[t]{.65\linewidth}%
+    {\includegraphics[width=\docshots@left]
+      {_docshots/\jobname/\hash.crop.pdf}};%
+  \hspace{\docshots@hspace}%
+  \begin{minipage}[t]{\docshots@right}%
     \vspace{0pt}%
     \VerbatimInput{_docshots/\jobname/\hash.tex}%
     \vspace{0pt}%
diff --git a/macros/latex/contrib/docshots/docshots.pdf b/macros/latex/contrib/docshots/docshots.pdf
index 402009aed3..4c03380bb6 100644
--- a/macros/latex/contrib/docshots/docshots.pdf
+++ b/macros/latex/contrib/docshots/docshots.pdf