/
l3color-base.dtx
194 lines (194 loc) · 6.14 KB
/
l3color-base.dtx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
% \iffalse meta-comment
%
%% File: l3color-base.dtx Copyright(C) 2011,2012,2014,2016-2018 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 2018-10-17}
%
% \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 almost the same as using the basic \cs{group_begin:}
% and \cs{group_end:} functions. However, in vertical mode the end-of-group
% needs a \tn{par}, which in horizontal mode does nothing.
% \begin{macrocode}
\cs_new_eq:NN \color_group_begin: \group_begin:
\cs_new_protected:Npn \color_group_end:
{
\par
\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>
\driver_color_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
{ \driver_color_cmyk:nnnn {#1} {#2} {#3} {#4} }
\cs_new_protected:Npn \@@_select_gray:w #1 \q_stop
{ \driver_color_gray:n {#1} }
\cs_new_protected:Npn \@@_select_rgb:w #1 ~ #2 ~ #3 \q_stop
{ \driver_color_rgb:nnn {#1} {#2} {#3} }
\cs_new_protected:Npn \@@_select_spot:w #1 ~ #2 \q_stop
{ \driver_color_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