summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3kernel/l3color-base.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3kernel/l3color-base.dtx')
-rw-r--r--macros/latex/contrib/l3kernel/l3color-base.dtx192
1 files changed, 192 insertions, 0 deletions
diff --git a/macros/latex/contrib/l3kernel/l3color-base.dtx b/macros/latex/contrib/l3kernel/l3color-base.dtx
new file mode 100644
index 0000000000..4881aae53e
--- /dev/null
+++ b/macros/latex/contrib/l3kernel/l3color-base.dtx
@@ -0,0 +1,192 @@
+% \iffalse meta-comment
+%
+%% File: l3color-base.dtx
+%
+% Copyright (C) 2011,2012,2014,2016-2019 The LaTeX3 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
+%
+% https://www.latex-project.org/lppl.txt
+%
+% This file is part of the "l3kernel 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>
+\documentclass[full,kernel]{l3doc}
+\begin{document}
+ \DocInput{\jobname.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \title{^^A
+% The \textsf{l3color-base} package\\ Color support^^A
+% }
+%
+% \author{^^A
+% The \LaTeX3 Project\thanks
+% {^^A
+% E-mail:
+% \href{mailto:latex-team@latex-project.org}
+% {latex-team@latex-project.org}^^A
+% }^^A
+% }
+%
+% \date{Released 2019-08-25}
+%
+% \maketitle
+%
+% \begin{documentation}
+%
+% This module provides support for color in \LaTeX3{}. At present, the
+% material here is mainly intended to support a small number of low-level
+% requirements in other \pkg{l3kernel} modules.
+%
+% \section{Color in boxes}
+%
+% Controlling the color of text in boxes requires a small number of control
+% functions, so that the boxed material uses the color at the point where
+% it is set, rather than where it is used.
+%
+% \begin{function}[added = 2011-09-03]{\color_group_begin:, \color_group_end:}
+% \begin{syntax}
+% \cs{color_group_begin:}
+% \ldots
+% \cs{color_group_end:}
+% \end{syntax}
+% Creates a color group: one used to \enquote{trap} color settings.
+% \end{function}
+%
+% \begin{function}[added = 2011-09-03]{\color_ensure_current:}
+% \begin{syntax}
+% \cs{color_ensure_current:}
+% \end{syntax}
+% Ensures that material inside a box uses the foreground color
+% at the point where the box is set, rather than that in force when the
+% box is used. This function should usually be used within a
+% \cs{color_group_begin:} \ldots \cs{color_group_end:} group.
+% \end{function}
+%
+% \end{documentation}
+%
+% \begin{implementation}
+%
+% \section{\pkg{l3color-base} Implementation}
+%
+% \begin{macrocode}
+%<*initex|package>
+% \end{macrocode}
+%
+% \begin{macrocode}
+%<@@=color>
+% \end{macrocode}
+%
+% \begin{variable}
+% {\l_@@_current_tl}
+% The color currently active for foreground (text, \emph{etc.}) material.
+% This is stored in the form of a color model followed by one or more
+% values. There are four pre-defined models, three of which take numerical
+% values in the range $[0,1]$:
+% \begin{itemize}
+% \item \texttt{gray \meta{gray}} Grayscale color with the \meta{gray}
+% value running from $0$ (fully black) to $1$ (fully white)
+% \item \texttt{cmyk \meta{cyan} \meta{magenta} \meta{yellow} \meta{black}}
+% \item \texttt{rgb \meta{red} \meta{green} \meta{blue}}
+% \end{itemize}
+% Notice that the value are separated by spaces. There is a fourth pre-defined
+% model using a string value and a numerical one:
+% \begin{itemize}
+% \item \texttt{spot \meta{name} \meta{tint}} A pre-defined spot color,
+% where the \meta{name} should be a pre-defined string color name and the
+% \meta{tint} should be in the range $[0,1]$.
+% \end{itemize}
+%
+% Additional models may be created to allow mixing of spot colors. The
+% number of data entries these require will depend on the number of
+% colors to be mixed.
+% \begin{texnote}
+% The content of \cs{l_@@_current_tl} is space-separated as
+% this allows it to be used directly in specials in many common cases.
+% This internal representation is close to that used by the \texttt{dvips}
+% program.
+% \end{texnote}
+% \end{variable}
+%
+% \begin{macro}{\color_group_begin:, \color_group_end:}
+% Grouping for color is the same as using the basic \cs{group_begin:}
+% and \cs{group_end:} functions. However, for semantic reasons, they
+% are renamed here.
+% \begin{macrocode}
+\cs_new_eq:NN \color_group_begin: \group_begin:
+\cs_new_eq:NN \color_group_end: \group_end:
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\color_ensure_current:}
+% A driver-independent wrapper for setting the foreground color to the
+% current color \enquote{now}.
+% \begin{macrocode}
+\cs_new_protected:Npn \color_ensure_current:
+ {
+%<*package>
+ \@@_backend_pickup:N \l_@@_current_tl
+%</package>
+ \@@_select:V \l_@@_current_tl
+ }
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@@_select:n, \@@_select:V}
+% \begin{macro}{\@@_select:w}
+% \begin{macro}
+% {\@@_select_cmyk:w, \@@_select_gray:w, \@@_select_rgb:w, \@@_select_spot:w}
+% Take an internal color specification and pass it to the driver. This code
+% is needed to ensure the current color but will also be used by the
+% higher-level experimental material.
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_select:n #1
+ { \@@_select:w #1 \q_stop }
+\cs_generate_variant:Nn \@@_select:n { V }
+\cs_new_protected:Npn \@@_select:w #1 ~ #2 \q_stop
+ { \use:c { @@_select_ #1 :w } #2 \q_stop }
+\cs_new_protected:Npn \@@_select_cmyk:w #1 ~ #2 ~ #3 ~ #4 \q_stop
+ { \@@_backend_cmyk:nnnn {#1} {#2} {#3} {#4} }
+\cs_new_protected:Npn \@@_select_gray:w #1 \q_stop
+ { \@@_backend_gray:n {#1} }
+\cs_new_protected:Npn \@@_select_rgb:w #1 ~ #2 ~ #3 \q_stop
+ { \@@_backend_rgb:nnn {#1} {#2} {#3} }
+\cs_new_protected:Npn \@@_select_spot:w #1 ~ #2 \q_stop
+ { \@@_backend_spot:nn {#1} {#2} }
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{variable}{\l_@@_current_tl}
+% As the setting data is used only
+% for specials, and those are always space-separated, it makes most sense to
+% hold the internal information in that form.
+% \begin{macrocode}
+\tl_new:N \l_@@_current_tl
+\tl_set:Nn \l_@@_current_tl { gray~0 }
+% \end{macrocode}
+% \end{variable}
+%
+% \begin{macrocode}
+%</initex|package>
+% \end{macrocode}
+%
+% \end{implementation}
+%
+% \PrintIndex