docshots (26oct22)

git-svn-id: svn://tug.org/texlive/trunk@64820 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 87 insertions, 50 deletions

diff --git a/Master/texmf-dist/source/latex/docshots/docshots.dtx b/Master/texmf-dist/source/latex/docshots/docshots.dtx
index 2e6d03614c2..0a559d7edf8 100644
--- a/Master/texmf-dist/source/latex/docshots/docshots.dtx
+++ b/Master/texmf-dist/source/latex/docshots/docshots.dtx
@@ -50,7 +50,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}
 %<package>\ProvidesPackage{docshots}
 %<*package>
-[2022-10-25 0.0.5 TeX Samples Next to Their PDF Snapshots in DTX]
+[2022-10-26 0.2.0 TeX Samples Next to Their PDF Snapshots in DTX]
 %</package>
 %<*driver>
 \documentclass{ltxdoc}
@@ -128,13 +128,9 @@
 % \begin{docshot}
 % \documentclass{article}
 % \usepackage{tikz}
-% \usetikzlibrary{backgrounds}
 % \pagestyle{empty}
 % \begin{document}
-% \begin{tikzpicture}[
-%   show background rectangle,
-%   background rectangle/.style=
-%     {draw=none,fill=gray!20}]
+% \begin{tikzpicture}
 % \node [circle,draw] (v0) {$v_0$};
 % \node [circle,draw=orange,thick,
 %   below right of=v0] (v1) {$v_1$};
@@ -155,17 +151,18 @@
 
 % When you render a text instead of a single picture, it's recommended to use
 % \href{https://ctan.org/pkg/geometry}{geometry} package to change the size
-% of the page and then |empty| page style to remove page numbering:
+% of the page:
 % \begin{docshot}
 % \documentclass{article}
-% \usepackage[paperwidth=2in]{geometry}
-% \pagestyle{empty}
+% \usepackage[paperwidth=2in,
+%   paperheight=2.2in]{geometry}
 % \begin{document}
 % ``There is no sadder thing than
 % a young pessimist, except an old
 % pessimist'' --- \emph{Mark Twain}
 % \end{document}
 % \end{docshot}
+% You can also use |\pagestyle{empty}| as was done in previous docshots.
 
 % \section{Package Options}
 
@@ -230,6 +227,18 @@ Hello, world!
 %</verb>
 %\fi
 
+% \DescribeMacro{nocrop}
+% You may disable cropping with the help of |nocrop| option:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[nocrop]{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:
@@ -271,7 +280,7 @@ Hello, world!
 %\fi
 
 % \DescribeMacro{tmpdir}
-% The default location of temp files is |\docshots@tmpdir|. You can change this using |tmpdir| option:
+% The default location of temp files is |_docshots|. You can change this using |tmpdir| option:
 %\iffalse
 %<*verb>
 %\fi
@@ -448,17 +457,21 @@ Hello, world!
 % Then, we process package options:
 % \changes{0.0.4}{2022/10/18}{Package options "lstinputlisting" and "inputminted" introduced to enable printing of verbatim text either via listings or minted packages.}
 % \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.}
 %    \begin{macrocode}
 \RequirePackage{pgfopts}
+\RequirePackage{ifluatex}
+\RequirePackage{ifxetex}
 \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,
+  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,
@@ -484,28 +497,39 @@ Hello, world!
 
 % Then, we print the version of |pdflatex| to \TeX{} log:
 %    \begin{macrocode}
-\iexec[\docshots@log,quiet]{\docshots@pdflatex\space --version}%
+\iexec[\docshots@log,quiet]{"\docshots@pdflatex" --version}%
 %    \end{macrocode}
 
 % Then, we print the version of \href{https://ctan.org/pkg/pdfcrop}{pdfcrop} to \TeX{} log:
 %    \begin{macrocode}
-\iexec[\docshots@log,quiet]{\docshots@pdfcrop\space --version}%
+\ifdefined\docshots@nocrop\else%
+  \iexec[\docshots@log,quiet]{"\docshots@pdfcrop" --version}%
+\fi%
 %    \end{macrocode}
 
 % Then, we print the version of |ghostscript| to \TeX{} log:
 %    \begin{macrocode}
-\iexec[\docshots@log,quiet]{\docshots@gs\space --version}%
+\iexec[\docshots@log,quiet]{"\docshots@gs" --version}%
 %    \end{macrocode}
 
 % Then, we make a directory where all temporary files will be kept:
 %    \begin{macrocode}
-\iexec[null]{mkdir -p \docshots@tmpdir/\jobname}%
+\iexec[null]{mkdir -p "\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:
+%    \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}
-\newenvironment{docshot}
+\makeatletter\newenvironment{docshot}
 {\VerbatimEnvironment\begin{VerbatimOut}
   {\docshots@tmpdir/\jobname/verbatim.tex}}
 {\end{VerbatimOut}%
@@ -519,52 +543,64 @@ Hello, world!
 %    \end{macrocode}
 % We calculate MD5 hashsum of the file content:
 %    \begin{macrocode}
-  \def\hash{\pdfmdfivesum file
-    {\docshots@tmpdir/\jobname/verbatim.tex}}%
+  \def\hash{\docshots@mdfive{\docshots@tmpdir/\jobname/verbatim.tex}}%
 %    \end{macrocode}
 % If the PDF with the required name already exists, we ignore this step.
 % Otherwise, we copy |verbatim.tex| into 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.}
 %    \begin{macrocode}
   \IfFileExists{\docshots@tmpdir/\jobname/\hash.pdf}
-    {\message{docshots: won't render, the PDF already exists
-      (\docshots@tmpdir/\jobname/\hash.pdf)^^J}}
-    {\iexec[\docshots@log,quiet]{cp \docshots@tmpdir/\jobname/verbatim.tex
-      \docshots@tmpdir/\jobname/\hash.tex}%
-    \foreach \n in {1,...,\docshots@runs}{
-      \iexec[\docshots@log,quiet]{cd \docshots@tmpdir/\jobname;
-        \docshots@pdflatex\space
+    {\message{docshots: Won't render,
+      the PDF '\docshots@tmpdir/\jobname/\hash.pdf' already exists^^J}}
+    {\iexec[\docshots@log,quiet]{cp "\docshots@tmpdir/\jobname/verbatim.tex"
+      "\docshots@tmpdir/\jobname/\hash.tex"}%
+    \foreach \n in {1,...,\docshots@runs}{%
+      \iexec[\docshots@log,
+        stdout=\docshots@tmpdir/\jobname/\hash.stdout,
+        exit=\docshots@tmpdir/\jobname/\hash.ret,
+        quiet,trace]{cd "\docshots@tmpdir/\jobname" &&
+        "\docshots@pdflatex"
         -interaction=errorstopmode
         -halt-on-error
         -shell-escape
-        \hash.tex}
-      \message{docshots: pdflatex run no.\n^^J}
+        \hash.tex}%
+      \ifnum\n=1\else%
+        \message{docshots: pdflatex run no.\n^^J}%
+      \fi%
       \IfFileExists{\docshots@tmpdir/\jobname/after.sh}
         {\iexec[\docshots@log,quiet]{chmod a+x
-          \docshots@tmpdir/\jobname/after.sh}
-        \iexec[\docshots@log,quiet]{cd \docshots@tmpdir/\jobname;
+          "\docshots@tmpdir/\jobname/after.sh"}
+        \iexec[\docshots@log,quiet]{cd "\docshots@tmpdir/\jobname" &&
           ./after.sh \n\space \hash\space \hash.tex}}
         {}}}%
 %    \end{macrocode}
 % Here we delete |after.sh| which may exist here after the last
 % compilation of |pdflatex|:
 %    \begin{macrocode}
-  \iexec[\docshots@log,quiet]{rm -f \docshots@tmpdir/\jobname/after.sh}
+  \iexec[\docshots@log,quiet]{rm -f "\docshots@tmpdir/\jobname/after.sh"}
 %    \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 already exists
-      (\docshots@tmpdir/\jobname/\hash.crop.pdf)^^J}}
-    {\iexec[\docshots@log,quiet]{\docshots@pdfcrop\space
-      --margins \docshots@margin\space
-      \docshots@tmpdir/\jobname/\hash.pdf
-      \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]{cp
+        "\docshots@tmpdir/\jobname/\hash.pdf"
+        "\docshots@tmpdir/\jobname/\hash.crop.pdf"}%
+      \else%
+      \iexec[\docshots@log,quiet]{"\docshots@pdfcrop"
+        --margins 0
+        "\docshots@tmpdir/\jobname/\hash.pdf"
+        "\docshots@tmpdir/\jobname/\hash.crop.pdf"}%
+      \fi}%
 %    \end{macrocode}
 % We configure |fancyvrb|:
 %    \begin{macrocode}
   \fvset{numbers=left,numbersep=3pt}%
-  \fvset{frame=leftline,framerule=.4pt,rulecolor=\color{gray}}%
+  \fvset{frame=leftline,framerule=.2pt,rulecolor=\color{gray}}%
   \fvset{samepage=true}%
   \fvset{baselinestretch=1}%
   \ifdefined\docshots@small%
@@ -574,12 +610,13 @@ Hello, world!
     \fvset{fontsize=\scriptsize}%
   \fi%
 %    \end{macrocode}
-% We render the two column content:
+% Finally, we render the two-column content:
 %    \begin{macrocode}
   \begingroup%
   \par%
   \tikz[baseline=(a.north)]
-    \node (a) [draw=gray,inner sep=0]
+    \node (a) [draw=gray,inner sep=\docshots@margin,
+      line width=.2pt]
     {\includegraphics[width=\docshots@left]
       {\docshots@tmpdir/\jobname/\hash.crop.pdf}};%
   \hspace{\docshots@hspace}%
@@ -597,30 +634,30 @@ Hello, world!
   \end{minipage}%
   \par%
   \endgroup%
-}
+}\makeatother
 %    \end{macrocode}
 % \end{macro}
 
 % \begin{macro}{\docshotPrerequisite}
 % Then, we define |\docshotPrerequisite| command:
 %    \begin{macrocode}
-\newcommand\docshotPrerequisite[1]{
-  \iexec[\docshots@log,quiet]{cp #1 \docshots@tmpdir/\jobname}%
-  \message{docshots: file #1 copied to
-    \docshots@tmpdir/\jobname/#1^^J}%
-}
+\makeatletter\newcommand\docshotPrerequisite[1]{
+  \iexec[\docshots@log,quiet]{cp #1 "\docshots@tmpdir/\jobname"}%
+  \message{docshots: File '#1' copied to
+    '\docshots@tmpdir/\jobname/#1'^^J}%
+}\makeatother
 %    \end{macrocode}
 % \end{macro}
 
 % \begin{macro}{\docshotAfter}
 % Finally, we define |\docshotAfter| command:
 %    \begin{macrocode}
-\newcommand\docshotAfter[1]{
+\makeatletter\newcommand\docshotAfter[1]{
   \iexec[\docshots@log,quiet]{/bin/echo -n '\detokenize{#1}'
-    > \docshots@tmpdir/\jobname/after.sh}%
-  \message{docshots: file
-    \docshots@tmpdir/\jobname/after.sh created^^J}%
-}
+    > "\docshots@tmpdir/\jobname/after.sh"}%
+  \message{docshots: File
+    '\docshots@tmpdir/\jobname/after.sh' created^^J}%
+}\makeatother
 %    \end{macrocode}
 % \end{macro}