Debian Codegraph @

texmf-dist/source/latex/transparent/transparent.dtx

raw
1 % \iffalse meta-comment
2 %
3 % File: transparent.dtx
4 % Version: 2025-06-23 v1.6
5 % Info: Transparency via pdfTeX's color stack
6 %
7 % Copyright (C)
8 % 2007 Heiko Oberdiek
9 % 2016-2025 Oberdiek Package Support Group
10 % https://github.com/ho-tex/transparent/issues
11 %
12 % This work may be distributed and/or modified under the
13 % conditions of the LaTeX Project Public License, either
14 % version 1.3c of this license or (at your option) any later
15 % version. This version of this license is in
16 % https://www.latex-project.org/lppl/lppl-1-3c.txt
17 % and the latest version of this license is in
18 % https://www.latex-project.org/lppl.txt
19 % and version 1.3 or later is part of all distributions of
20 % LaTeX version 2005/12/01 or later.
21 %
22 % This work has the LPPL maintenance status "maintained".
23 %
24 % The Current Maintainers of this work are
25 % Heiko Oberdiek and the Oberdiek Package Support Group
26 % https://github.com/ho-tex/transparent/issues
27 %
28 % This work consists of the main source file transparent.dtx
29 % and the derived files
30 % transparent.sty, transparent-nometadata.sty, transparent.pdf,
31 % transparent.ins, transparent.drv, transparent-example.tex.
32 %
33 % Distribution:
34 % CTAN:macros/latex/contrib/transparent/transparent.dtx
35 % CTAN:macros/latex/contrib/transparent/transparent.pdf
36 %
37 % Unpacking:
38 % (a) If transparent.ins is present:
39 % tex transparent.ins
40 % (b) Without transparent.ins:
41 % tex transparent.dtx
42 % (c) If you insist on using LaTeX
43 % latex \let\install=y\input{transparent.dtx}
44 % (quote the arguments according to the demands of your shell)
45 %
46 % Documentation:
47 % (a) If transparent.drv is present:
48 % latex transparent.drv
49 % (b) Without transparent.drv:
50 % latex transparent.dtx; ...
51 % The class ltxdoc loads the configuration file ltxdoc.cfg
52 % if available. Here you can specify further options, e.g.
53 % use A4 as paper format:
54 % \PassOptionsToClass{a4paper}{article}
55 %
56 % Programm calls to get the documentation (example):
57 % pdflatex transparent.dtx
58 % makeindex -s gind.ist transparent.idx
59 % pdflatex transparent.dtx
60 % makeindex -s gind.ist transparent.idx
61 % pdflatex transparent.dtx
62 %
63 % Installation:
64 % TDS:tex/latex/transparent/transparent.sty
65 % TDS:tex/latex/transparent/transparent-nometadata.sty
66 % TDS:doc/latex/transparent/transparent.pdf
67 % TDS:source/latex/transparent/transparent.dtx
68 %
69 %<*ignore>
70 \begingroup
71 \catcode123=1 %
72 \catcode125=2 %
73 \def\x{LaTeX2e}%
74 \expandafter\endgroup
75 \ifcase 0\ifx\install y1\fi\expandafter
76 \ifx\csname processbatchFile\endcsname\relax\else1\fi
77 \ifx\fmtname\x\else 1\fi\relax
78 \else\csname fi\endcsname
79 %</ignore>
80 %<*install>
81 \input docstrip.tex
82 \Msg{************************************************************************}
83 \Msg{* Installation}
84 \Msg{* Package: transparent 2025-06-23 v1.6 Transparency via pdfTeX's color stack (HO)}
85 \Msg{************************************************************************}
86
87 \keepsilent
88 \askforoverwritefalse
89
90 \let\MetaPrefix\relax
91 \preamble
92
93 This is a generated file.
94
95 Project: transparent
96 Version: 2025-06-23 v1.6
97
98 Copyright (C)
99 2007 Heiko Oberdiek
100 2016-2025 Oberdiek Package Support Group
101
102 This work may be distributed and/or modified under the
103 conditions of the LaTeX Project Public License, either
104 version 1.3c of this license or (at your option) any later
105 version. This version of this license is in
106 https://www.latex-project.org/lppl/lppl-1-3c.txt
107 and the latest version of this license is in
108 https://www.latex-project.org/lppl.txt
109 and version 1.3 or later is part of all distributions of
110 LaTeX version 2005/12/01 or later.
111
112 This work has the LPPL maintenance status "maintained".
113
114 The Current Maintainers of this work are
115 Heiko Oberdiek and the Oberdiek Package Support Group
116 https://github.com/ho-tex/transparent/issues
117
118
119 This work consists of the main source file transparent.dtx
120 and the derived files
121 transparent.sty, transparent-nometadata.sty, transparent.pdf,
122 transparent.ins, transparent.drv, transparent-example.tex.
123
124 \endpreamble
125 \let\MetaPrefix\DoubleperCent
126
127 \generate{%
128 \file{transparent.ins}{\from{transparent.dtx}{install}}%
129 \file{transparent.drv}{\from{transparent.dtx}{driver}}%
130 \usedir{tex/latex/transparent}%
131 \file{transparent-nometadata.sty}{\from{transparent.dtx}{package}}%
132 \file{transparent.sty}{\from{transparent.dtx}{package-new}}%
133 \usedir{doc/latex/transparent}%
134 \file{transparent-example.tex}{\from{transparent.dtx}{example}}%
135 }
136
137 \catcode32=13\relax% active space
138 \let =\space%
139 \Msg{************************************************************************}
140 \Msg{*}
141 \Msg{* To finish the installation you have to move the following}
142 \Msg{* file into a directory searched by TeX:}
143 \Msg{*}
144 \Msg{* transparent.sty}
145 \Msg{* transparent-nometadata.sty}
146 \Msg{*}
147 \Msg{* To produce the documentation run the file `transparent.drv'}
148 \Msg{* through LaTeX.}
149 \Msg{*}
150 \Msg{* Happy TeXing!}
151 \Msg{*}
152 \Msg{************************************************************************}
153
154 \endbatchfile
155 %</install>
156 %<*ignore>
157 \fi
158 %</ignore>
159 %<*driver>
160 \NeedsTeXFormat{LaTeX2e}
161 \ProvidesFile{transparent.drv}%
162 [2025-06-23 v1.6 Transparency via pdfTeX's color stack (HO)]%
163 \documentclass{ltxdoc}
164 \usepackage{holtxdoc}[2011/11/22]
165 \begin{document}
166 \DocInput{transparent.dtx}%
167 \end{document}
168 %</driver>
169 % \fi
170 %
171 %
172 %
173 % \GetFileInfo{transparent.drv}
174 %
175 % \title{The \xpackage{transparent} package}
176 % \date{2025-06-23 v1.6}
177 % \author{Heiko Oberdiek\thanks
178 % {Please report any issues at \url{https://github.com/ho-tex/transparent/issues}}}
179 %
180 % \maketitle
181 %
182 % \begin{abstract}
183 % \pdfTeX\ and lua\TeX{} supports several color stacks. This
184 % package shows, how a separate color stack can be used for transparency,
185 % a property besides color, that also works across page break.
186 % \end{abstract}
187 %
188 % \tableofcontents
189 %
190 % \section{User interface}
191 %
192 % The package \xpackage{transparent} defines \cs{transparent} and
193 % \cs{texttransparent}. They are used like \cs{color} and \cs{textcolor}.
194 % The first argument is the transparency value between 0 and 1 where 0
195 % is fully transparent and 1 is opaque.
196 %
197 % \section{Engine support}
198 % If the PDF management is loaded (e.g. by using \verb+\DocumentMetadata{}+ at the beginning
199 % of the document) the package makes use of \texttt{l3opacity} and
200 % can be used with all engines supported by \texttt{l3backend}.
201 % But only with \pdfTeX\ and lua\TeX{} the transparency will also work across page break.
202 %
203 %
204 % Without the PDF management, the package works only with \pdfTeX\ and lua\TeX{}.
205 % It then uses the original code by Heiko Oberdiek. It then uses the
206 % primitive \cs{pdfpageresources} and can clash with other packages that also use
207 % \cs{pdfpageresources}.
208 %
209 %
210 % \section{Example for usage}
211 % \begin{macrocode}
212 %<*example>
213 \documentclass[12pt]{article}
214
215 \usepackage{color}
216 \usepackage{transparent}
217
218 \begin{document}
219 \colorbox{yellow}{%
220 \bfseries
221 \color{blue}%
222 Blue and %
223 \transparent{0.6}%
224 transparent blue%
225 }
226
227 \bigskip
228 Hello World
229 \texttransparent{0.5}{Hello\newpage World}
230 Hello World
231 \end{document}
232 %</example>
233 % \end{macrocode}
234 %
235 % \StopEventually{
236 % }
237 %
238 % \section{Implementation}
239 % \subsection{New version using the methods of the PDF management}
240 % Identification
241 % \begin{macrocode}
242 %<*package-new>
243 \NeedsTeXFormat{LaTeX2e}[2020/10/01]
244 \ProvidesExplPackage{transparent}{2025-06-23}{1.6}
245 {Transparency with color stacks}%
246 % \end{macrocode}
247 % Testing if the pdfmanagement is used
248 % \begin{macrocode}
249 \IfPDFManagementActiveF {\RequirePackage{transparent-nometadata}}
250 \IfPDFManagementActiveF {\endinput}
251 % \end{macrocode}
252 % \begin{macrocode}
253 \NewDocumentCommand{\transparent} { m }
254 {
255 \opacity_select:n{\fp_eval:n{ min(max(0,#1),1) } }
256 }
257
258 \NewDocumentCommand{\texttransparent}{m m}
259 {
260 \mode_leave_vertical:
261 \group_begin:
262 \transparent{#1}
263 #2
264 \group_end:
265 }
266 %</package-new>
267 % \end{macrocode}
268 % \subsection{Old version without the PDF management}
269 % \begin{macrocode}
270 %<*package>
271 \NeedsTeXFormat{LaTeX2e}
272 \ProvidesPackage{transparent-nometadata}%
273 [2025-06-23 v1.6 Transparency via pdfTeX's color stack (HO)]%
274 % \end{macrocode}
275 %
276 % \subsection{Initial checks}
277 %
278 % \subsubsection{Check for \pdfTeX\ in PDF mode}
279 % \begin{macrocode}
280 \RequirePackage{iftex}
281 \ifpdf
282 \else
283 \PackageWarningNoLine{transparent}{%
284 Loading aborted, because pdfTeX is not running in PDF mode%
285 }%
286 \expandafter\endinput
287 \fi
288 % \end{macrocode}
289 %
290 % \subsubsection{Check \pdfTeX\ or Lua\TeX\ version}
291 % \begin{macrocode}
292 \ifx\pdfextension\@undefined
293 \let\TRP@pdfcolorstackinit\pdfcolorstackinit
294 \let\TRP@pdfpageresources\pdfpageresources
295 \let\TRP@pdfcolorstack\pdfcolorstack
296 \else
297 \def\TRP@pdfcolorstackinit {\pdffeedback colorstackinit}
298 \protected\edef\TRP@pdfpageresources {\pdfvariable pageresources}
299 \protected\def\TRP@pdfcolorstack {\pdfextension colorstack}
300 \fi
301 % \end{macrocode}
302 %
303 % \begin{macrocode}
304 \ifcsname TRP@pdfcolorstackinit\endcsname\else
305 \PackageWarningNoLine{transparent}{%
306 Your pdfTeX version does not support color stacks%
307 }%
308 \expandafter\endinput
309 \fi
310 % \end{macrocode}
311 %
312 % \subsection{Compatibility with pgf}
313 % https://github.com/ho-tex/transparent/issues/1
314 % https://github.com/ho-tex/transparent/issues/3
315 % \begin{macrocode}
316 \AtBeginDocument
317 {%
318 \ifcsname pgf@sys@addpdfresource@extgs@plain\endcsname
319 \let\TRP@addresource\relax
320 \pgfutil@addpdfresource@extgs{\TRP@list}%
321 \fi
322 }
323 % \end{macrocode}
324 % \subsection{Transparency}
325 %
326 % The setting for the different transparency values must
327 % be added to the page resources. In the first run the values
328 % are recorded in the \xfile{.aux} file. In the second run
329 % the values are set and transparency is available.
330 % \begin{macrocode}
331 \RequirePackage{auxhook}
332 \AddLineBeginAux{%
333 \string\providecommand{\string\transparent@use}[1]{}%
334 }
335 \gdef\TRP@list{/TRP1<</ca 1/CA 1>>}
336 \def\transparent@use#1{%
337 \@ifundefined{TRP#1}{%
338 \g@addto@macro\TRP@list{%
339 /TRP#1<</ca #1/CA #1>>%
340 }%
341 \expandafter\gdef\csname TRP#1\endcsname{/TRP#1 gs}%
342 }{%
343 % #1 is already known, nothing to do
344 }%
345 }
346 \AtBeginDocument{%
347 \TRP@addresource
348 \let\transparent@use\@gobble
349 }
350 % \end{macrocode}
351 % Unhappily the interface setting page resources is very
352 % poor, only a token register \cs{pdfpageresources}.
353 % Thus this package tries to be cooperative in the way that
354 % it embeds the previous contents of \cs{pdfpageresources}.
355 % However it does not solve the problem, if several packages
356 % want to set |/ExtGState|.
357 % \begin{macrocode}
358 \def\TRP@addresource{%
359 \begingroup
360 \edef\x{\endgroup
361 \TRP@pdfpageresources{%
362 \the\TRP@pdfpageresources
363 /ExtGState<<\TRP@list>>%
364 }%
365 }%
366 \x
367 }
368 \newif\ifTRP@rerun
369 \xdef\TRP@colorstack{%
370 \TRP@pdfcolorstackinit page direct{/TRP1 gs}%
371 }
372 % \end{macrocode}
373 % \begin{macro}{\transparent}
374 % \begin{macrocode}
375 \newcommand*{\transparent}[1]{%
376 \begingroup
377 \dimen@=#1\p@\relax
378 \ifdim\dimen@>\p@
379 \dimen@=\p@
380 \fi
381 \ifdim\dimen@<\z@
382 \dimen@=\z@
383 \fi
384 \ifdim\dimen@=\p@
385 \def\x{1}%
386 \else
387 \ifdim\dimen@=\z@
388 \def\x{0}%
389 \else
390 \edef\x{\strip@pt\dimen@}%
391 \edef\x{\expandafter\@gobble\x}%
392 \fi
393 \fi
394 \if@filesw
395 \immediate\write\@auxout{%
396 \string\transparent@use{\x}%
397 }%
398 \fi
399 \edef\x{\endgroup
400 \def\noexpand\transparent@current{\x}%
401 }%
402 \x
403 \transparent@set
404 }
405 % \end{macrocode}
406 % \end{macro}
407 % \begin{macrocode}
408 \AtEndDocument{%
409 \ifTRP@rerun
410 \PackageWarningNoLine{transparent}{%
411 Rerun to get transparencies right%
412 }%
413 \fi
414 }
415 \def\transparent@current{/TRP1 gs}
416 \def\transparent@set{%
417 \@ifundefined{TRP\transparent@current}{%
418 \global\TRP@reruntrue
419 }{%
420 \TRP@pdfcolorstack\TRP@colorstack push{%
421 \csname TRP\transparent@current\endcsname
422 }%
423 \aftergroup\transparent@reset
424 }%
425 }
426 \def\transparent@reset{%
427 \TRP@pdfcolorstack\TRP@colorstack pop\relax
428 }
429 % \end{macrocode}
430 % \begin{macro}{\texttransparent}
431 % \begin{macrocode}
432 \newcommand*{\texttransparent}[2]{%
433 \protect\leavevmode
434 \begingroup
435 \transparent{#1}%
436 #2%
437 \endgroup
438 }
439 % \end{macrocode}
440 % \end{macro}
441 %
442 % \begin{macrocode}
443 %</package>
444 % \end{macrocode}
445 %
446 % \section{Installation}
447 %
448 % \subsection{Download}
449 %
450 % \paragraph{Package.} This package is available on
451 % CTAN\footnote{\CTANpkg{transparent}}:
452 % \begin{description}
453 % \item[\CTAN{macros/latex/contrib/transparent/transparent.dtx}] The source file.
454 % \item[\CTAN{macros/latex/contrib/transparent/transparent.pdf}] Documentation.
455 % \end{description}
456 %
457 %
458 %
459 % \subsection{Package installation}
460 %
461 % \paragraph{Unpacking.} The \xfile{.dtx} file is a self-extracting
462 % \docstrip\ archive. The files are extracted by running the
463 % \xfile{.dtx} through \plainTeX:
464 % \begin{quote}
465 % \verb|tex transparent.dtx|
466 % \end{quote}
467 %
468 % \paragraph{TDS.} Now the different files must be moved into
469 % the different directories in your installation TDS tree
470 % (also known as \xfile{texmf} tree):
471 % \begin{quote}
472 % \def\t{^^A
473 % \begin{tabular}{@{}>{\ttfamily}l@{ $\rightarrow$ }>{\ttfamily}l@{}}
474 % transparent.sty & tex/latex/transparent/transparent.sty\\
475 % transparent-nometadata.sty & tex/latex/transparent/transparent-nometadata.sty\\
476 % transparent.pdf & doc/latex/transparent/transparent.pdf\\
477 % transparent-example.tex & doc/latex/transparent/transparent-example.tex\\
478 % transparent.dtx & source/latex/transparent/transparent.dtx\\
479 % \end{tabular}^^A
480 % }^^A
481 % \sbox0{\t}^^A
482 % \ifdim\wd0>\linewidth
483 % \begingroup
484 % \advance\linewidth by\leftmargin
485 % \advance\linewidth by\rightmargin
486 % \edef\x{\endgroup
487 % \def\noexpand\lw{\the\linewidth}^^A
488 % }\x
489 % \def\lwbox{^^A
490 % \leavevmode
491 % \hbox to \linewidth{^^A
492 % \kern-\leftmargin\relax
493 % \hss
494 % \usebox0
495 % \hss
496 % \kern-\rightmargin\relax
497 % }^^A
498 % }^^A
499 % \ifdim\wd0>\lw
500 % \sbox0{\small\t}^^A
501 % \ifdim\wd0>\linewidth
502 % \ifdim\wd0>\lw
503 % \sbox0{\footnotesize\t}^^A
504 % \ifdim\wd0>\linewidth
505 % \ifdim\wd0>\lw
506 % \sbox0{\scriptsize\t}^^A
507 % \ifdim\wd0>\linewidth
508 % \ifdim\wd0>\lw
509 % \sbox0{\tiny\t}^^A
510 % \ifdim\wd0>\linewidth
511 % \lwbox
512 % \else
513 % \usebox0
514 % \fi
515 % \else
516 % \lwbox
517 % \fi
518 % \else
519 % \usebox0
520 % \fi
521 % \else
522 % \lwbox
523 % \fi
524 % \else
525 % \usebox0
526 % \fi
527 % \else
528 % \lwbox
529 % \fi
530 % \else
531 % \usebox0
532 % \fi
533 % \else
534 % \lwbox
535 % \fi
536 % \else
537 % \usebox0
538 % \fi
539 % \end{quote}
540 % If you have a \xfile{docstrip.cfg} that configures and enables \docstrip's
541 % TDS installing feature, then some files can already be in the right
542 % place, see the documentation of \docstrip.
543 %
544 % \subsection{Refresh file name databases}
545 %
546 % If your \TeX~distribution
547 % (\TeX\,Live, \mikTeX, \dots) relies on file name databases, you must refresh
548 % these. For example, \TeX\,Live\ users run \verb|texhash| or
549 % \verb|mktexlsr|.
550 %
551 % \subsection{Some details for the interested}
552 %
553 % \paragraph{Unpacking with \LaTeX.}
554 % The \xfile{.dtx} chooses its action depending on the format:
555 % \begin{description}
556 % \item[\plainTeX:] Run \docstrip\ and extract the files.
557 % \item[\LaTeX:] Generate the documentation.
558 % \end{description}
559 % If you insist on using \LaTeX\ for \docstrip\ (really,
560 % \docstrip\ does not need \LaTeX), then inform the autodetect routine
561 % about your intention:
562 % \begin{quote}
563 % \verb|latex \let\install=y\input{transparent.dtx}|
564 % \end{quote}
565 % Do not forget to quote the argument according to the demands
566 % of your shell.
567 %
568 % \paragraph{Generating the documentation.}
569 % You can use both the \xfile{.dtx} or the \xfile{.drv} to generate
570 % the documentation. The process can be configured by the
571 % configuration file \xfile{ltxdoc.cfg}. For instance, put this
572 % line into this file, if you want to have A4 as paper format:
573 % \begin{quote}
574 % \verb|\PassOptionsToClass{a4paper}{article}|
575 % \end{quote}
576 % An example follows how to generate the
577 % documentation with pdf\LaTeX:
578 % \begin{quote}
579 %\begin{verbatim}
580 %pdflatex transparent.dtx
581 %makeindex -s gind.ist transparent.idx
582 %pdflatex transparent.dtx
583 %makeindex -s gind.ist transparent.idx
584 %pdflatex transparent.dtx
585 %\end{verbatim}
586 % \end{quote}
587 %
588 % \begin{History}
589 % \begin{Version}{2007/01/08 v1.0}
590 % \item
591 % First version.
592 % \end{Version}
593 % \begin{Version}{2016/05/16 v1.1}
594 % \item
595 % Documentation updates.
596 % \end{Version}
597 % \begin{Version}{2018/09/10 v1.2}
598 % \item
599 % Update for LuaTeX, remove dependency on Pdf\TeX\ command names.
600 % \end{Version}
601 % \begin{Version}{2018/11/18 v1.3}
602 % \item
603 % Added code for pgf compatibility, see https://github.com/ho-tex/transparent/issues/1
604 % \end{Version}
605 % \begin{Version}{2019/11/29 v1.4}
606 % \item
607 % Documentation updates.
608 % \item
609 % Use \xpackage{iftex} package.
610 % \end{Version}
611 % \begin{Version}{2022-10-27 v1.5}
612 % \item Made the package compatible with the PDF management.
613 % \end{Version}
614 % \begin{Version}{2025-06-23 v1.6}
615 % \item l3opacity is in the l3kernel
616 % \item Avoid error if only pdfutil-common is loaded,
617 % see https://github.com/ho-tex/transparent/issues/3
618 % \end{Version}
619 % \end{History}
620 %
621 % \PrintIndex
622 %
623 % \Finale
624 \endinput