summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3experimental/l3opacity.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3experimental/l3opacity.dtx')
-rw-r--r--macros/latex/contrib/l3experimental/l3opacity.dtx140
1 files changed, 140 insertions, 0 deletions
diff --git a/macros/latex/contrib/l3experimental/l3opacity.dtx b/macros/latex/contrib/l3experimental/l3opacity.dtx
new file mode 100644
index 0000000000..4b1e7ea64f
--- /dev/null
+++ b/macros/latex/contrib/l3experimental/l3opacity.dtx
@@ -0,0 +1,140 @@
+% \iffalse meta-comment
+%
+%% File: l3opacity.dtx
+%
+% Copyright (C) 2021 The LaTeX Project
+%
+% It may be distributed and/or modified under the conditions of the
+% LaTeX Project Public License (LPPL), either version 1.3c of this
+% license or (at your option) any later version. The latest version
+% of this license is in the file
+%
+% http://www.latex-project.org/lppl.txt
+%
+% This file is part of the "l3experimental bundle" (The Work in LPPL)
+% and all files in that bundle must be distributed together.
+%
+% -----------------------------------------------------------------------
+%
+% The development version of the bundle can be found at
+%
+% https://github.com/latex3/latex3
+%
+% for those people who are interested.
+%
+%<*driver|package>
+\RequirePackage{expl3}
+%</driver|package>
+%<*driver>
+\documentclass[full]{l3doc}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+% The \textsf{l3opacity} package\\ Experimental opacity (transparency) support^^A
+% }
+%
+% \author{^^A
+% The \LaTeX{} Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team@latex-project.org}
+% {latex-team@latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Released 2021-07-12}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% \section{Selecting opacity}
+%
+% Opacity (transparency) shares many characteristics with color. However,
+% limitations in terms of backends mean that it is not always possible
+% to use a dedicated stack for tracking opacity. The best results when
+% breaking pages are therefore likely to result using direct PDF output
+% (\pdfTeX{}, \LuaTeX{}) or with recent versions of \texttt{(x)dvipdfmx}:
+% these backends do offer the necessary support.
+%
+% For users of PostScript-based routes, note that there are security
+% restrictions which can prevent opacity being available in output. In
+% particular, using Adobe Distiller, you will need to enable transparency
+% in the (text-based) configuration: this is not selectable from the GUI.
+%
+% \begin{function}[added = 2021-07-01]{\opacity_select:n}
+% \begin{syntax}
+% \cs{opacity_select:n} \Arg{expression}
+% \end{syntax}
+% Evaluates the \meta{expression}, which should yield a value in the range $[0,1]$.
+% This is then activated as an opacity for both filling and stroking.
+% \end{function}
+%
+% \begin{function}[added = 2021-07-01]{\opacity_fill:n, \opacity_stroke:n}
+% \begin{syntax}
+% \cs{opacity_fill:n} \Arg{expression}
+% \end{syntax}
+% Evaluates the \meta{expression}, which should yield a value in the range $[0,1]$.
+% This is then activated as an opacity for filling or stroking, respectively.
+% \end{function}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3opacity} Implementation}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<@@=opacity>
+% \end{macrocode}
+%
+% \begin{macrocode}
+\ProvidesExplPackage{l3opacity}{2021-07-12}{}
+ {L3 Experimental opacity support}
+% \end{macrocode}
+%
+% \begin{macro}{\opacity_select:n, \opacity_fill:n, \opacity_stroke:n}
+% \begin{macro}{\@@_select:nN, \@@_select_aux:nN}
+% Thin wrapper with error checking.
+% \begin{macrocode}
+\cs_new_protected:Npn \opacity_select:n #1
+ { \@@_select:nN {#1} \@@_backend_select:n }
+\cs_new_protected:Npn \opacity_fill:n #1
+ { \@@_select:nN {#1} \@@_backend_fill:n }
+\cs_new_protected:Npn \opacity_stroke:n #1
+ { \@@_select:nN {#1} \@@_backend_stroke:n }
+\cs_new_protected:Npn \@@_select:nN #1#2
+ { \exp_args:Ne \@@_select_aux:nN { \fp_eval:n {#1} } #2 }
+\cs_new_protected:Npn \@@_select_aux:nN #1#2
+ {
+ \bool_lazy_or:nnTF
+ { \fp_compare_p:nNn {#1} < { 0 } }
+ { \fp_compare_p:nNn {#1} > { 1 } }
+ { \msg_error:nnn { opacity } { out-of-range } {#1} }
+ { #2 {#1} }
+ }
+\msg_new:nnnn { opacity } { out-of-range }
+ { Opacity~value~out~of~range. }
+ {
+ LaTeX~was~asked~to~set~opacity~of~#1,~but~only~values~in~the~range~
+ 0~to~1~are~supported.
+ }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%
+% \end{implementation}
+%
+% \PrintIndex