summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/docshots
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-10-15 03:01:23 +0000
committerNorbert Preining <norbert@preining.info>2022-10-15 03:01:23 +0000
commit716f66d13d38e113c2d0491804fae5879de67bb3 (patch)
tree98e4752aa89041db35c60e5b893897e714561340 /macros/latex/contrib/docshots
parent1c0d5e0721918b8ee790c9f1c11f1543e0403322 (diff)
CTAN sync 202210150301
Diffstat (limited to 'macros/latex/contrib/docshots')
-rw-r--r--macros/latex/contrib/docshots/DEPENDS.txt5
-rw-r--r--macros/latex/contrib/docshots/LICENSE.txt21
-rw-r--r--macros/latex/contrib/docshots/README.md25
-rw-r--r--macros/latex/contrib/docshots/docshots.dtx203
-rw-r--r--macros/latex/contrib/docshots/docshots.ins55
-rw-r--r--macros/latex/contrib/docshots/docshots.pdfbin0 -> 279951 bytes
6 files changed, 309 insertions, 0 deletions
diff --git a/macros/latex/contrib/docshots/DEPENDS.txt b/macros/latex/contrib/docshots/DEPENDS.txt
new file mode 100644
index 0000000000..d8361a6695
--- /dev/null
+++ b/macros/latex/contrib/docshots/DEPENDS.txt
@@ -0,0 +1,5 @@
+hard iexec
+hard fancyvrb
+hard pdfcrop
+hard pgf
+hard pgf-blur
diff --git a/macros/latex/contrib/docshots/LICENSE.txt b/macros/latex/contrib/docshots/LICENSE.txt
new file mode 100644
index 0000000000..bd949ffdab
--- /dev/null
+++ b/macros/latex/contrib/docshots/LICENSE.txt
@@ -0,0 +1,21 @@
+(The MIT License)
+
+Copyright (c) 2021-2022 Yegor Bugayenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/macros/latex/contrib/docshots/README.md b/macros/latex/contrib/docshots/README.md
new file mode 100644
index 0000000000..6201451a88
--- /dev/null
+++ b/macros/latex/contrib/docshots/README.md
@@ -0,0 +1,25 @@
+[![l3build](https://github.com/yegor256/docshots/actions/workflows/l3build.yml/badge.svg)](https://github.com/yegor256/docshots/actions/workflows/l3build.yml)
+[![CTAN](https://img.shields.io/ctan/v/docshots)](https://ctan.org/pkg/docshots)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/docshots/blob/master/LICENSE.txt)
+
+This LaTeX package helps you add PDF snapshots to DTX documentation.
+
+First, [install it](https://en.wikibooks.org/wiki/LaTeX/Installing_Extra_Packages)
+from [CTAN](https://ctan.org/pkg/docshots)
+and then use in DTX:
+
+```tex
+% \begin{docshot}
+% \documentclass{article}
+% \pagestyle{empty}
+% \begin{document}
+% Hello, \LaTeX!
+% \end{document}
+% \end{docshot}
+```
+
+If you want to contribute yourself, make a fork, then create a branch,
+then run `l3build ctan` in the root directory.
+It should compile everything without errors. If not, submit an issue and wait.
+Otherwise, make your changes and then run `l3build ctan` again. If the build is
+still clean, submit a pull request.
diff --git a/macros/latex/contrib/docshots/docshots.dtx b/macros/latex/contrib/docshots/docshots.dtx
new file mode 100644
index 0000000000..3fa5c9ac13
--- /dev/null
+++ b/macros/latex/contrib/docshots/docshots.dtx
@@ -0,0 +1,203 @@
+% \iffalse meta-comment
+% (The MIT License)
+%
+% Copyright (c) 2021-2022 Yegor Bugayenko
+%
+% Permission is hereby granted, free of charge, to any person obtaining a copy
+% of this software and associated documentation files (the 'Software'), to deal
+% in the Software without restriction, including without limitation the rights
+% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+% copies of the Software, and to permit persons to whom the Software is
+% furnished to do so, subject to the following conditions:
+%
+% The above copyright notice and this permission notice shall be included in all
+% copies or substantial portions of the Software.
+%
+% THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+% SOFTWARE.
+% \fi
+
+% \CheckSum{0}
+%
+% \CharacterTable
+% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+
+% \GetFileInfo{docshots.dtx}
+% \DoNotIndex{\endgroup,\begingroup,\let,\else,\s,\n,\r,\\,\1,\fi}
+
+% \iffalse
+%<*driver>
+\ProvidesFile{docshots.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{docshots}
+%<*package>
+[2022-10-14 0.0.1 TeX Samples Next to Their PDF Snapshots in DTX]
+%</package>
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[tt=false, type1=true]{libertine}
+\usepackage{microtype}
+\usepackage{docshots}
+\usepackage{href-ul}
+\PageIndex
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+ \DocInput{docshots.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</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}}}
+% \author{Yegor Bugayenko \\ \texttt{yegor256@gmail.com}}
+% \date{\filedate, \fileversion}
+%
+% \maketitle
+%
+% \textbf{NB!}
+% You must run \TeX{} processor with |--shell-escape| option
+% and you must have \href{https://www.perl.org}{Perl} 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:
+%
+% \begin{docshot}
+% \documentclass{article}
+% \begin{document}
+% \pagestyle{empty}
+% Hello, \LaTeX!
+% \end{document}
+% \end{docshot}
+
+% Here is a more complex example:
+%
+% \begin{docshot}
+% \documentclass{article}
+% \usepackage{tikz}
+% \begin{document}\pagestyle{empty}
+% \begin{tikzpicture}
+% \node [circle,draw] (v0) {$v_0$};
+% \node [circle,draw,
+% below right of=v0] (v1) {$v_1$};
+% \draw [->] (v0) -- (v1);
+% \end{tikzpicture}
+% \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.
+% 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.
+
+% \StopEventually{}
+
+% \section{Implementation}
+
+% \changes{v0.0.1}{2022/10/09}{Initial version}
+
+% First, we include a few packages:
+% \begin{macrocode}
+\RequirePackage{iexec}
+\RequirePackage{fancyvrb}
+\RequirePackage{xcolor}
+\RequirePackage{graphicx}
+\RequirePackage{tikz}
+\usetikzlibrary{shadows.blur}
+% \end{macrocode}
+
+% Then, we show the version of |pdflatex|:
+% \begin{macrocode}
+\iexec[log,quiet]{pdflatex --version}%
+% \end{macrocode}
+
+% Then, we show the version of |pdfcrop|:
+% \begin{macrocode}
+\iexec[log,quiet]{pdfcrop --version}%
+% \end{macrocode}
+
+% Then, we show the version of |ghostscript|:
+% \begin{macrocode}
+\iexec[log,quiet]{gs --version}%
+% \end{macrocode}
+
+% Then, we make a directory where all temporary files will be kept:
+% \begin{macrocode}
+\iexec[null]{mkdir -p _docshots/\jobname}%
+% \end{macrocode}
+
+% \begin{macro}{docshot}
+% Then, we define |docshot| environment:
+% \begin{macrocode}
+\newenvironment{docshot}
+{\VerbatimEnvironment\begin{VerbatimOut}{_docshots/\jobname/verbatim.tex}}
+{\end{VerbatimOut}%
+ \iexec[null]{perl -i -0777pe "s/(\\n|^)\\x{25} /\\1/g"
+ _docshots/\jobname/verbatim.tex}%
+ \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}%
+ \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}%
+ \vspace{0pt}%
+ \VerbatimInput{_docshots/\jobname/\hash.tex}%
+ \vspace{0pt}%
+ \end{minipage}%
+ \par%
+}
+% \end{macrocode}
+% \end{macro}
+
+% \Finale
+
+%\clearpage
+
+%\PrintChanges
+%\clearpage
+%\PrintIndex
diff --git a/macros/latex/contrib/docshots/docshots.ins b/macros/latex/contrib/docshots/docshots.ins
new file mode 100644
index 0000000000..d7ba42bfee
--- /dev/null
+++ b/macros/latex/contrib/docshots/docshots.ins
@@ -0,0 +1,55 @@
+%% (The MIT License)
+%%
+%% Copyright (c) 2021-2022 Yegor Bugayenko
+%%
+%% Permission is hereby granted, free of charge, to any person obtaining a copy
+%% of this software and associated documentation files (the 'Software'), to deal
+%% in the Software without restriction, including without limitation the rights
+%% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+%% copies of the Software, and to permit persons to whom the Software is
+%% furnished to do so, subject to the following conditions:
+%%
+%% The above copyright notice and this permission notice shall be included in all
+%% copies or substantial portions of the Software.
+%%
+%% THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+%% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+%% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+%% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+%% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+%% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+%% SOFTWARE.
+
+\input docstrip.tex
+\keepsilent
+\usedir{macros/latex/contrib/docshots}
+\preamble
+(The MIT License)
+
+Copyright (c) 2021-2022 Yegor Bugayenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+\endpreamble
+\generate{\file{docshots.sty}{\from{docshots.dtx}{package}}}
+\obeyspaces
+\Msg{To finish the installation you have to move the ".sty"}
+\Msg{file into a directory searched by TeX. To produce the}
+\Msg{documentation run the file ".dtx" through LaTeX. If any}
+\Msg{questions, submit a new GitHub issue.}
+\endbatchfile
diff --git a/macros/latex/contrib/docshots/docshots.pdf b/macros/latex/contrib/docshots/docshots.pdf
new file mode 100644
index 0000000000..402009aed3
--- /dev/null
+++ b/macros/latex/contrib/docshots/docshots.pdf
Binary files differ