summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/docshots/docshots.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-10-17 20:17:57 +0000
committerKarl Berry <karl@freefriends.org>2022-10-17 20:17:57 +0000
commitd52f52b48cc3dbaa2410a6b12edb2471e2ab9653 (patch)
tree5e8095441cdfa258b722c456d707b1cdba9c4363 /Master/texmf-dist/source/latex/docshots/docshots.dtx
parent6e8255e0ec57c131e5fdd727f2d471e0e780335d (diff)
docshots (17oct22)
git-svn-id: svn://tug.org/texlive/trunk@64729 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/docshots/docshots.dtx')
-rw-r--r--Master/texmf-dist/source/latex/docshots/docshots.dtx282
1 files changed, 244 insertions, 38 deletions
diff --git a/Master/texmf-dist/source/latex/docshots/docshots.dtx b/Master/texmf-dist/source/latex/docshots/docshots.dtx
index 65eade188b3..18f9b6356ad 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-16 0.0.2 TeX Samples Next to Their PDF Snapshots in DTX]
+[2022-10-17 0.0.3 TeX Samples Next to Their PDF Snapshots in DTX]
%</package>
%<*driver>
\documentclass{ltxdoc}
@@ -78,11 +78,12 @@
% \maketitle
%
% \textbf{\color{red}NB!}
-% You must run \TeX{} processor with |--shell-escape| option
-% and you must have
-% \href{...}{pdflatex},
+% This package doesn't work on Windows!
+% Also, you must run \TeX{} processor with |--shell-escape| option.
+% Also, you must have
+% |pdlaftex|,
% \href{https://www.perl.org}{Perl},
-% \href{...}{Ghostscript},
+% \href{https://www.ghostscript.com}{Ghostscript},
% and \href{https://ctan.org/pkg/pdfcrop}{pdfcrop}
% installed.
@@ -92,7 +93,8 @@
% 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
+% To \href{https://tex.stackexchange.com/questions/661027}{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:
%
@@ -103,8 +105,8 @@
\begin{docshot}
\documentclass{article}
\usepackage{xcolor}
-\begin{document}
\pagestyle{empty}
+\begin{document}
Hello, {\color{orange}\LaTeX}!
\end{document}
\end{docshot}
@@ -116,8 +118,8 @@
% \begin{docshot}
% \documentclass{article}
% \usepackage{xcolor}
-% \begin{document}
% \pagestyle{empty}
+% \begin{document}
% Hello, {\color{orange}\LaTeX}!
% \end{document}
% \end{docshot}
@@ -126,11 +128,11 @@
% \begin{docshot}
% \documentclass{article}
% \usepackage{tikz}
-% \begin{document}
% \pagestyle{empty}
+% \begin{document}
% \begin{tikzpicture}
% \node [circle,draw] (v0) {$v_0$};
-% \node [circle,draw,
+% \node [circle,draw=orange,thick,
% below right of=v0] (v1) {$v_1$};
% \draw [->] (v0) -- (v1);
% \end{tikzpicture}
@@ -142,10 +144,24 @@
% After a successful processing of \TeX{} sources, we use
% \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.
+% We execute |pdflatex| with |-interaction=batchmode| and |-halt-on-error| options.
+% This means that
+% \TeX{} processing will stop at the first error. Check your \TeX{} log
+% to understand what went wrong.
+
+% 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:
+% \begin{docshot}
+% \documentclass{article}
+% \usepackage[paperwidth=2in]{geometry}
+% \pagestyle{empty}
+% \begin{document}
+% ``There is no sadder thing than
+% a young pessimist, except an old
+% pessimist'' --- \emph{Mark Twain}
+% \end{document}
+% \end{docshot}
% \section{Package Options}
@@ -250,6 +266,120 @@ Hello, world!
%</verb>
%\fi
+% \DescribeMacro{tmpdir}
+% The default location of temp files is |\docshots@tmpdir|. You can change this using |tmpdir| option:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[tmpdir=/tmp/foo]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{runs}
+% By default, we run |pdflatex| just once for each docshot. You can change this number using the package
+% option |runs|. This may be helpful if you need Bib\TeX{} processing, for example:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[runs=3]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{small}
+% \DescribeMacro{tiny}
+% You don't have too much freedom in formatting of verbatim texts, but you can make
+% their font a bit smaller using |small| package option. You can also make it very
+% small using |tiny| option:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\usepackage[small]{docshot}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \section{Prerequisites}
+
+% \DescribeMacro{\docshotPrerequisite}
+% If you need some files to be present next to the |.tex| snippet while
+% it's rendered by |pdflatex|, you can use |\docshotPrerequisite| with
+% a single mandatory argument. The argument is the name of a file you need
+% to be copied from current directory to the temporary directory, where
+% all snippets are rendered. The command can be used either in the body
+% of the document or in the preamble --- it doesn't matter, as long as
+% it shows up before the docshot that needs the prerequisite. For example:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\documentclass{article}
+\usepackage{docshot}
+\docshotPrerequisite{duck.jpg}
+\begin{document}
+\begin{docshot}
+ \documentclass{article}
+ \usepackage{graphicx}
+ \pagestyle{empty}
+ \begin{document}
+ This is my favorite picture of a duck:
+ \includegraphics[width=2in]{duck.jpg}
+ \end{document}
+\end{docshot}
+\end{document}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+
+% \DescribeMacro{\docshotAfter}
+% If you need something to happen after each |pdflatex| run of a docshot, you may use
+% |\docshotAfter| command right before |docshot| environment. For example, you have a bibliography file that
+% you want to be visible for all snippets and you want all of them to
+% run \href{https://ctan.org/pkg/biber}{biber} in order to process citations:
+%\iffalse
+%<*verb>
+%\fi
+\begin{verbatim}
+\documentclass{article}
+\usepackage{docshot}
+\docshotPrerequisite{main.bib}
+\begin{document}
+\docshotAfter{biber $2}
+\begin{docshot}
+ \documentclass{acmart}
+ \usepackage[natbib=true]{biblatex}
+ \addbibresource{main.bib}
+ \pagestyle{empty}
+ \begin{document}
+ You must read the book of \citet{knuth1984}.
+ \printbibliography
+ \end{document}
+\end{docshot}
+\end{document}
+\end{verbatim}
+%\iffalse
+%</verb>
+%\fi
+% The script you specify in the first argument of |\docshotAfter| will get
+% three arguments when it runs:
+% \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}
+% |$2| is basically equals to |$1| with an
+% attached |.tex| suffix. |\docshotAfter| applies only to the first |docshot|
+% environment that goes after it! You must specify |\docshotAfter| before
+% each |docshot| where you want such post-processing to happen.
+
% \StopEventually{}
% \section{Implementation}
@@ -272,6 +402,12 @@ Hello, world!
\pgfkeys{
/docshots/.cd,
dtx/.store in=\docshots@dtx,
+ tmpdir/.store in=\docshots@tmpdir,
+ tmpdir/.default=_docshots,
+ 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,
@@ -281,12 +417,12 @@ Hello, world!
margin/.store in=\docshots@margin,
margin/.default=5,
hspace/.store in=\docshots@hspace,
- hspace/.default=1.8em,
+ hspace/.default=.05\linewidth,
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
+ right/.default=.55\linewidth,
+ tmpdir,pdflatex,gs,pdfcrop,margin,hspace,left,right,runs
}
\ProcessPgfOptions{/docshots}
% \end{macrocode}
@@ -308,7 +444,7 @@ Hello, world!
% Then, we make a directory where all temporary files will be kept:
% \begin{macrocode}
-\iexec[null]{mkdir -p _docshots/\jobname}%
+\iexec[null]{mkdir -p \docshots@tmpdir/\jobname}%
% \end{macrocode}
% \begin{macro}{docshot}
@@ -316,40 +452,110 @@ Hello, world!
% \begin{macrocode}
\newenvironment{docshot}
{\VerbatimEnvironment\begin{VerbatimOut}
- {_docshots/\jobname/verbatim.tex}}
+ {\docshots@tmpdir/\jobname/verbatim.tex}}
{\end{VerbatimOut}%
+% \end{macrocode}
+% If we are in |dtx| mode, leading percent characters must be removed:
+% \begin{macrocode}
\ifdefined\docshots@dtx%
\iexec[null]{perl -i -0777pe "s/(\\n|^)\\x{25} /\\1/g"
- _docshots/\jobname/verbatim.tex}%
+ \docshots@tmpdir/\jobname/verbatim.tex}%
\fi%
- \def\hash{\pdfmdfivesum file {_docshots/\jobname/verbatim.tex}}%
- \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}}
+% \end{macrocode}
+% We calculate MD5 hashsum of the file content:
+% \begin{macrocode}
+ \def\hash{\pdfmdfivesum file {\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|:
+% \begin{macrocode}
+ \IfFileExists{\docshots@tmpdir/\jobname/\hash.pdf}
+ {\message{docshots: won't render, the PDF already exists
+ (\docshots@tmpdir/\jobname/\hash.pdf)^^J}}
+ {\iexec[log,quiet]{cp \docshots@tmpdir/\jobname/verbatim.tex
+ \docshots@tmpdir/\jobname/\hash.tex}%
+ \foreach \n in {1,...,\docshots@runs}{
+ \iexec[log,quiet]{cd \docshots@tmpdir/\jobname;
+ \docshots@pdflatex\space
+ -interaction=errorstopmode
+ -halt-on-error
+ -shell-escape
+ \hash.tex}
+ \message{docshots: pdflatex run no.\n^^J}
+ \IfFileExists{\docshots@tmpdir/\jobname/after.sh}
+ {\iexec[log,quiet]{chmod a+x
+ \docshots@tmpdir/\jobname/after.sh}
+ \iexec[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[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: on't pdfcrop, the PDF already exists
+ (\docshots@tmpdir/\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}%
+ \docshots@tmpdir/\jobname/\hash.pdf
+ \docshots@tmpdir/\jobname/\hash.crop.pdf}}%
+% \end{macrocode}
+% We configure |fancyvrb|:
+% \begin{macrocode}
+ \fvset{numbers=left,numbersep=3pt}%
+ \fvset{frame=leftline,framerule=.4pt,rulecolor=\color{gray}}%
+ \fvset{samepage=true,baselinestretch=1}%
+ \fvset{baselinestretch=1}%
+ \ifdefined\docshots@small%
+ \fvset{fontsize=\small}%
+ \fi%
+ \ifdefined\docshots@tiny%
+ \fvset{fontsize=\scriptsize}%
+ \fi%
+% \end{macrocode}
+% We render the two column content:
+% \begin{macrocode}
+ \begingroup%
\par%
- \tikz[baseline=(a.north)] \node[draw=gray] (a)
+ \tikz[baseline=(a.north)]
+ \node (a) [draw=gray]
{\includegraphics[width=\docshots@left]
- {_docshots/\jobname/\hash.crop.pdf}};%
+ {\docshots@tmpdir/\jobname/\hash.crop.pdf}};%
\hspace{\docshots@hspace}%
\begin{minipage}[t]{\docshots@right}%
\vspace{0pt}%
- \VerbatimInput{_docshots/\jobname/\hash.tex}%
+ \VerbatimInput{\docshots@tmpdir/\jobname/\hash.tex}%
\vspace{0pt}%
\end{minipage}%
\par%
+ \endgroup%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\docshotPrerequisite}
+% Then, we define |\docshotPrerequisite| command:
+% \begin{macrocode}
+\newcommand\docshotPrerequisite[1]{
+ \iexec[log,quiet]{cp #1 \docshots@tmpdir/\jobname}%
+ \message{docshots: file #1 copied to
+ \docshots@tmpdir/\jobname/#1^^J}%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \begin{macro}{\docshotAfter}
+% Finally, we define |\docshotAfter| command:
+% \begin{macrocode}
+\newcommand\docshotAfter[1]{
+ \iexec[log,quiet]{/bin/echo -n '\detokenize{#1}'
+ > \docshots@tmpdir/\jobname/after.sh}%
+ \message{docshots: file \docshots@tmpdir/\jobname/after.sh created^^J}%
}
% \end{macrocode}
% \end{macro}