summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/docshots/docshots.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/docshots/docshots.dtx')
-rw-r--r--macros/latex/contrib/docshots/docshots.dtx137
1 files changed, 87 insertions, 50 deletions
diff --git a/macros/latex/contrib/docshots/docshots.dtx b/macros/latex/contrib/docshots/docshots.dtx
index 2e6d03614c..0a559d7edf 100644
--- a/macros/latex/contrib/docshots/docshots.dtx
+++ b/macros/latex/contrib/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}