The color package^{∗}

D. P. Carlisle

1995/12/07

1 Options

1 ⟨∗package⟩

First we save the catcodes of some characters, and set them to fixed values whilst this file is being read.

 2 \edef\Gin@codes{%
 3 \catcode`\noexpand\^^A\the\catcode`\^^A\relax
 4 \catcode`\noexpand\"\the\catcode`\"\relax
 5 \catcode`\noexpand\*\the\catcode`\*\relax
 6 \catcode`\noexpand\!\the\catcode`\!\relax
 7 \catcode`\noexpand\:\the\catcode`\:\relax}
 8 \catcode`\^^A=\catcode`\%
 9 \catcode`\"=12
10 \catcode`\*=11
11 \catcode`\!=12
12 \catcode`\:=12
13 \providecommand\Gin@driver{}

The monochrome should be used in addition to one of the standard driver options.

14 \DeclareOption{monochrome}{%
15 \AtEndOfPackage{%
16  \def\set@color{%
17  \c@lor@special\m@ne
18  {color push \current@color}\aftergroup\reset@color}%
19  \def\reset@color{\c@lor@special\m@ne{color pop}}%
20  \def\set@page@color{%
21  \c@lor@special\m@ne{background \current@color}}%
22  \def\define@color#1#2{%
23  \c@lor@special\m@ne{define #1 #2}}}}

Now the options for supported drivers.

24 \DeclareOption{dvips}{\def\Gin@driver{dvips.def}%
25  \def\c@lor@namefile{dvipsnam.def}}

∗This file has version number v0.3l, last revised 1995/12/07.

26 \DeclareOption{xdvi}{\ExecuteOptions{dvips,monochrome}}
27 \DeclareOption{dvgt}{\def\Gin@driver{dvgt.def}}
28 \DeclareOption{dvi2ps}{\def\Gin@driver{dvi2ps.def}}
29 \DeclareOption{dvialw}{\def\Gin@driver{dvialw.def}}
30 \DeclareOption{dvilaser}{\def\Gin@driver{dvilaser.def}}
31 \DeclareOption{dvipsone}{\def\Gin@driver{dvipsone.def}}
32 \DeclareOption{dviwindo}{\ExecuteOptions{dvipsone}}
33 \DeclareOption{dvitops}{\def\Gin@driver{dvitops.def}}
34 \DeclareOption{emtex}{\def\Gin@driver{emtex.def}}
35 \DeclareOption{dviwin}{\def\Gin@driver{dviwin.def}}
36 \DeclareOption{oztex}{\def\Gin@driver{oztex.def}}
37 \DeclareOption{psprint}{\def\Gin@driver{psprint.def}}
38 \DeclareOption{pubps}{\def\Gin@driver{pubps.def}}
39 \DeclareOption{textures}{\def\Gin@driver{textures.def}}
40 \DeclareOption{pctexps}{\def\Gin@driver{pctexps.def}}
41 \DeclareOption{pctexwin}{\def\Gin@driver{pctexwin.def}}
42 \DeclareOption{pctexhp}{\def\Gin@driver{pctexhp.def}}
43 \DeclareOption{ln}{\def\Gin@driver{ln.def}}

By default the named colour model has no pre-declared names. The dvipsnames option predeclares all the names in the colour prologue of dvips. The dvips option automatically implies dvipsnames unless this choice is overruled with the nodvipsnames option. For other drivers, eg textures you may use this option to explicitly request that these names be declared.

44 \DeclareOption{dvipsnames}{\def\c@lor@namefile{dvipsnam.def}}
45 \DeclareOption{nodvipsnames}{\let\c@lor@namefile\relax}

The usenames option modifies the behaviour of \DefineNamedColor So that it declares the same name as a “‘user’s colour” for use in a \color command, as well as a name in the named colour model. The normal behaviour is just to decalare the name in the named colour model.

46 \let\c@lor@usename\@gobble
47 \DeclareOption{usenames}{%
48 \def\c@lor@usename#1{%
49  \expandafter\color@named\csname\string\color @#1\endcsname{#1}}}

2 Using Colours

2.1 Declarative form

\color \color{declared-colour} switches to the colour declared-colour, which must previously have been defined using \definecolor. This colour will stay in effect until the end of the current TEX group.

\color[model]{colour-specification} is similar to the above, but uses a colour not declared by \definecolor. The allowed model’s vary depending on the driver. The syntax of the colour-specification argument depends on the model.

50 \DeclareRobustCommand\color{%
51 \@ifnextchar[\@undeclaredcolor\@declaredcolor}

\@undeclaredcolor Call the driver-dependent command \color@⟨model⟩ to define \current@color, then call \set@color to change the current colour accordingly.

52 \def\@undeclaredcolor[#1]#2{%
53 \@ifundefined{color@#1}%
54  {\@latex@error{Undefined color model `#1'}\@ehd}%
55  {\csname color@#1\endcsname\current@color{#2}%
56  \set@color}%
57 \ignorespaces}

\@declaredcolor \let \current@color to the internal representation of the colour if the colour has been declared, otherwise generate an error. Finally call \set@color to effect the colour change.

58 \def\@declaredcolor#1{%
59 \@ifundefined{\string\color @#1}%
60  {\@latex@error{Undefined color `#1'}\@ehd}%
61  {\expandafter\let\expandafter\current@color
62  \csname\string\color @#1\endcsname
63  \set@color}%
64 \ignorespaces}

2.2 Command (Argument) Form

\textcolor \textcolor{declared-colour}{text} and \textcolor[model]{colour-spec}{text} are just alternative syntax for \color, in which the groups are added implicitly. Thus text appears in the specified colour, but then the colour reverts to its previous value. The naming is by analogy with \textrm (as opposed to \rm and \rmfamily) although it is slightly a misnomer as the command also works in math-mode.

Since December 95, in fact this command has one other difference from \color. It calls \leavevmode to ensure the start of horizontal mode. Specifically this means that a construction such as

 xxx\parbox[t]{1cm}{\textcolor{red}{a}.....

now works as expected, with the xxx and the red a lining up correctly.

65 \def\textcolor#1#{\@textcolor{#1}}
66 \def\@textcolor#1#2#3{\protect\leavevmode{\color#1{#2}#3}}

2.3 Background (Page) Colour

\pagecolor \pagecolor, which has the same argument forms as \color, specifies the background colour for the current, and all following, pages. It is a global declaration which does not respect TEX groups.

67 \def\pagecolor{%
68 \begingroup
69  \let\ignorespaces\endgroup
70  \let\set@color\set@page@color
71  \color}

3 Defining Colours

\definecolor \definecolor{name}{model}{colour-spec} defines the color name, which may then be used in subsequent \color or \textcolor commands to refer to a colour specified by colour-spec in the colour model model.

\definecolor associates the name the to a colour in model. So \color{name} would check name then issue a \special for the colour model model.

\definecolor just calls an internal macro that defines the colour for a particular model. This macro must have been defined by the driver file that supports the requested model.

72 \def\definecolor#1#2#3{%
73 \@ifundefined{color@#2}%
74  {\@latex@error{Undefined color model `#2'}\@ehd}%
75  {\@ifundefined{\string\color @#1}{}%
76  {\PackageInfo{color}{Redefining color #1}}%
77  \csname color@#2\expandafter\endcsname
78  \csname\string\color @#1\endcsname{#3}}}

\DefineNamedColor Driver files may opt to define a ‘named’ colour model. Placing colour names rather than numeric specifications into the dvi file has certain advantages, in that post processing software can tune the colour specifications to the particular technology being used, and more easily make colour separations for that colour. The disadvantage is that the driver must ‘know’ the colour names.

The ‘color1’ drivers (dvips) currently ignore the specification of the colour, and once a name is defined, just put the colour name in the dvi file. For dvips, The header file color.pro is used to give the cmyk equivalents of the names.

The ‘color2’ drivers (textures) use a special postscript operator that takes both the name and the cmyk equivalent. so if the names are no being used, fall back’ definitions in the cmyk model are available. These drivers also allow a numeric value to affect the ‘density’ of the colour to use.

Drivers based on ‘color3’ do not support named colours at the dvi level, but to ease document portability, the named model is still defined, but the \special’s just put the colour specifications, not the names, into the dvi file.

Normally after a colour, say JungleGreen, has been declared with:

\DefineNamedColor{named}{JungleGreen}{cmyk}{1,2,3,4}

it is available in the ‘named’ colour model, for instance by

\color[named]{JungleGreen}

A user may give a more convenient name, using

\definecolor{mygreen}{named}{JungleGreen}

If however you are happy with the original names, and want to use them directly, as in \color{JungleGreen} without specifying [named] all the time, just give the package option usenames, which will redefine \DefineNamedColor, so that the colour name is declared as a user-colour as well as a name in the ‘named’ model.

79 \def\DefineNamedColor#1#2#3#4{%
80 \@ifundefined{define@color@#1}%

81  {\@latex@error{Undefined color model `#1'}\@ehd}%
82  {\@ifundefined{color@#3}%
83  {\@latex@error{Undefined color model `#3'}\@ehd}%
84  {\@ifundefined{c@lor@#1@#2}{}%
85  {\PackageInfo{color}{Redefining color #2 in named color model}}%
86  \csname color@#3\endcsname\@tempa{#4}%
87  \csname define@color@#1\endcsname{#2}\@tempa
88  \c@lor@usename{#2}}}}
89 \@onlypreamble\DefineNamedColor

4 Colour Switch

\ifcolor@ This boolean can be tested by higher level macros that may want to alter their behaviour if a monochrome driver is being used.

90 \newif\ifcolors@
91 \colors@true

5 Whatsit…

\c@lor@special Some drivers can not support all the features of this package. They should always put a ⟨whatsit⟩ in the current list though. the following macro has most of the features of \special, but does not put anything into the dvi file. It does write to the log file or the terminal (depending on the value of #1).

92 \def\c@lor@special#1#2{%
93 \edef\@tempa{\write#1{#2}}\@tempa}

6 Processing Options

A local configuration file may declare more options. It should also make one driver option the default, by calling \ExecuteOptions with the appropriate option.

94 \InputIfFileExists{color.cfg}{}{}

After the options are processed, load the appropriate driver file. If a site wants a default driver (eg dvips) it just needs to put \ExecuteOptions{dvips} in a

color.cfg file.
95 \ProcessOptions
96 \if!\Gin@driver!
97 \PackageError{color}
98  {No driver specified}
99  {You should make a default driver option in a file \MessageBreak
100  color.cfg\MessageBreak
101  eg: \protect\ExecuteOptions{dvips}%

102 }

103 \else
104 \PackageInfo{color}{Driver file: \Gin@driver}

105 \@ifundefined{ver@\Gin@driver}{\input{\Gin@driver}}{}
106 \fi
107 \@ifundefined{c@lor@namefile}{}{\input{\c@lor@namefile}}

7 Default Colour

\normalcolor Early versions of this package redefined \reset@font to reset the color as well. Current versions do not do this (there are too many \reset@font commands hidden in strange places) and so defines a separate command, \normalcolor to reset the colour to the colour in effect at the start of the document.

\normalcolor is defined (to \relax) in the L^{A}TEX kernel, so it is safe to use this in macros that may possibly be used in conjunction with colour. It will have no effect until the color package is also loaded.

108 \def\normalcolor{\let\current@color\default@color\set@color}

\default@color Internal macro to store the ‘default’ colour used by \normalcolor.

109 \AtBeginDocument{\let\default@color\current@color}

\current@color contains an internal representation of the colour at this point in the document. (This can only be an approximation to the truth as the ‘macro layer’ of TEX does not know where the output routine is going to re-insert floats. This is why drivers must maintain their own stack of colours in order to fully support these commands.

For dvips, the \current@color it is something like ‘Black’ or ‘rgb 0 1 0’, but other packages should not rely on any particular format for this macro.

The driver file must initialise \current@color to a specification for Black. This initialisation can not occur here, as the possible colour models (and thus the syntax for ‘black’) are not known at this point.

8 Higher Level Commands

With the basic colour primitives specified above we may define a few higer level commands for coloured boxes etc. This is still quite a low level and presumably packages and classes making use of colour will define more appropriate documentlevel commands.

8.1 Colour Block

\color@block  \color@block{width}{height}{depth}

Should take up no space for TEX, but produce a block in the current colour of the specified size. It is mainly used for producing box backgrounds.

The definition here works by selecting a colour, and then drawing a TEX rule (unless \ifcolors@false). This allows the ‘driver independent’ colour specials to be used. However it is defined using \providecommand, so that this file will not over-write any other definition of this command. A graphics package may want to define it using a special to produce (for example) a PostScript line. Producing the line in the \special has the advantage that on a preview that does not understand \specials, the line is automatically omited, without needing to modify the source of the document (for instance by adding the monochrome option).

110 \def\color@block#1#2#3{%
111 {\set@color\rlap{\ifcolors@\vrule\@width#1\@height#2\@depth#3\fi}}}

8.2 Coloured Boxes

\colorbox \colorbox takes the same argument forms as \textcolor, but the colour specifies the background colour of the box.

112 \def\colorbox#1#{\color@box{#1}}
\color@box
113 \def\color@box#1#2{\color@b@x\relax{\color#1{#2}}}

\fcolorbox \fcolorbox has an extra colour-spec argument, and puts a frame of the first colour around a box with a background specified by the second colour. If an optional argument is given, it specifies the colour model for both colours.

\fcolorbox
114 \def\fcolorbox#1#{\color@fbox{#1}}
115 \def\color@fbox#1#2#3{%
116 \color@b@x{\fboxsep\z@\color#1{#2}\fbox}{\color#1{#3}}}
\color@b@x Internal macro for \colorbox and \fcolorbox.
117 \long\def\color@b@x#1#2#3{%
118 \leavevmode
119 \setbox\z@\hbox{\kern\fboxsep{\set@color#3}\kern\fboxsep}%
120 \dimen@\ht\z@\advance\dimen@\fboxsep\ht\z@\dimen@
121 \dimen@\dp\z@\advance\dimen@\fboxsep\dp\z@\dimen@
122 {#1{#2\color@block{\wd\z@}{\ht\z@}{\dp\z@}%
123  \box\z@}}}

9 Extra Groups

Turning on extra groups in the standard L^{A}TEX commands, so that colour commands are scoped corectly.

Like \normalcolor, the following five commands are defined in the kernel, with empty definitions (\relax). This means that they can be used to make macros in packages ‘colour safe’. The commands will not have any effect unless a user also uses this colour package, when the ‘active definitions’ here will take effect and keep colour commands correctly scoped.

\color@setgroup This is to be used in contexts (eg ‘lrbox’) where text is to be saved and used after some other, unknown, text that may contain colour commands. A matching \color@endgroup should be used at the end of the text.

124 \def\color@setgroup{\begingroup\set@color}

\color@begingroup This is to be used at the start of contexts that may contain colour commands, but where it is not necessary to save the current colour. Examples of this are in the box commands of ltboxes.dtx where user-supplied text is saved internally in a box between \color@begingroup, \color@endgroup, but the box is used before any other colour commands could intervene. A matching \color@endgroup should be used at the end of the text.

125 \let\color@begingroup\begingroup

\color@endgroup To be used to close the ‘group’ started by one of the above two commands. The \endgraf in its definition is required in the case of groups of text in vertical ‘par’ mode, but doesn’t do any harm in horizontal ‘LR’ contexts.

126 \def\color@endgroup{\endgraf\endgroup}

\color@hbox To be used to open a ‘coloured hbox’

127 \def\color@hbox{\hbox\bgroup\color@begingroup}

\color@vbox To be used to open a ‘coloured hbox’

128 \def\color@vbox{\vbox\bgroup\color@begingroup}

\color@endbox To be used to close a ‘coloured hbox’

129 \def\color@endbox{\color@endgroup\egroup}

10 Predefining Colours

As long as the driver file has defined sufficient colour models, we define a few colours, just to get people started.

black white Black and white ‘colours’.

130 \ifx\color@gray\@undefined
131 \ifx\color@rgb\@undefined
132 \else
133  \definecolor{black}{rgb}{0,0,0}
134  \definecolor{white}{rgb}{1,1,1}
135 \fi
136 \else
137 \definecolor{black}{gray}{0}
138 \definecolor{white}{gray}{1}
139 \fi

red green blue Additive primaries.

140 \ifx\color@rgb\@undefined\else
141 \definecolor{red}{rgb}{1,0,0}

142 \definecolor{green}{rgb}{0,1,0}
143 \definecolor{blue}{rgb}{0,0,1}
144 \fi

cyan magenta yellow Subtractive primaries.

145 \ifx\color@cmyk\@undefined\else
146 \definecolor{cyan}{cmyk}{1,0,0,0}
147 \definecolor{magenta}{cmyk}{0,1,0,0}
148 \definecolor{yellow}{cmyk}{0,0,1,0}
149 \fi

150 ⟨/package⟩

11 And Finally

Restore Catcodes

151 \Gin@codes
152 \let\Gin@codes\relax