summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/docshots/docshots.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2022-10-16 20:13:35 +0000
committerKarl Berry <karl@freefriends.org>2022-10-16 20:13:35 +0000
commit8bef47547f86e14494c02edeaf377bac25279156 (patch)
treefe6932cb9e7b2f01c1ff069a8b699950eb7920bc /Master/texmf-dist/source/latex/docshots/docshots.dtx
parentbb3cce09999dca0412d465b9d2cdc4e5e5b0a497 (diff)
docshots (16oct22)
git-svn-id: svn://tug.org/texlive/trunk@64722 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.dtx248
1 files changed, 204 insertions, 44 deletions
diff --git a/Master/texmf-dist/source/latex/docshots/docshots.dtx b/Master/texmf-dist/source/latex/docshots/docshots.dtx
index 3fa5c9ac13a..65eade188b3 100644
--- a/Master/texmf-dist/source/latex/docshots/docshots.dtx
+++ b/Master/texmf-dist/source/latex/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}%