diff options
author | Karl Berry <karl@freefriends.org> | 2022-10-17 20:17:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-10-17 20:17:57 +0000 |
commit | d52f52b48cc3dbaa2410a6b12edb2471e2ab9653 (patch) | |
tree | 5e8095441cdfa258b722c456d707b1cdba9c4363 /Master/texmf-dist/source/latex/docshots/docshots.dtx | |
parent | 6e8255e0ec57c131e5fdd727f2d471e0e780335d (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.dtx | 282 |
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} |