path: root/macros/latex-dev/required/graphics/color.dtx

%
% \iffalse
%
%% color.dtx Copyright (C) 1994--1999 David Carlisle
%%           Copyright (C) 2005-2024 LaTeX Project
%% The LaTeX Project and any individual authors listed elsewhere
%% in this file.
%%
%% This file is part of the Standard LaTeX `Graphics Bundle'.
%% It may be distributed under the terms of the LaTeX Project Public
%% License, as described in lppl.txt in the base LaTeX distribution.
%% Either version 1.3c or, at your option, any later version.
%%
%% This file has the LPPL maintenance status "maintained".
%%
%<*dtx>
          \ProvidesFile{color.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
%<package>\ProvidesPackage{color}
%<driver> \ProvidesFile{color.drv}
% \fi
%         \ProvidesFile{color.dtx}
          [2024/06/23 v1.3e Standard LaTeX Color (DPC)]
%
% \iffalse
%<*driver>
\documentclass{ltxdoc}
\newenvironment{option}[1]{\expandafter\macro\expandafter{%
   \csname ds@#1\endcsname}}{\endmacro}
\begin{document}
 \DocInput{color.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{color.dtx}
%
% \title{The \textsf{color} package\thanks{This file
%        has version number \fileversion, last
%        revised \filedate.}}
% \author{D. P. Carlisle}
% \date{\filedate}
% \MaintainedByLaTeXTeam{graphics}
% \maketitle
%
%
%
% \title{The implementation of the \LaTeX\ Colour interface.}
%
% \section{Introduction}
% This package implements \LaTeX\ support for colour, for those
% \texttt{dvi} drivers that can produce coloured text.
%
% The user level documentation of this package is contained in the
% document \emph{Packages in the `graphics' bundle} in the file
% \texttt{grfguide.tex}.
%
% \MaybeStop{}
%
%
% \section{Options}
%
% \changes{v0.2a}{1994/04/13}
%     {TEMP KLUDGE for Feb 94 release of 2e:
%      Add extra groups}
% \changes{v0.2d}{1994/05/13}
%     {All support for Feb 1994 release removed (so used optional arg
%     of \cs{NeedsTeXFormat}).}
% \changes{v1.0}{1996/05/29}
%     {Version 1 at last}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% First we save the catcodes of some characters, and set them to
% fixed values whilst this file is being read.
% \changes{v0.3b}{1994/09/14}
%     {Save and restore catcodes}
% \changes{v1.3a}{2021/09/27}
%     {Use \cs{@backslashchar} in preference to \cs{string} gh/659}
% \changes{v1.3c}{2021/12/07}
%     {Remove stray spaces after change to \cs{@backslashchar} xcolor/gh/10}
%
%    \begin{macrocode}
\edef\Gin@codes{%
 \catcode`\noexpand\^^A\the\catcode`\^^A\relax
 \catcode`\noexpand\"\the\catcode`\"\relax
 \catcode`\noexpand\*\the\catcode`\*\relax
 \catcode`\noexpand\!\the\catcode`\!\relax
 \catcode`\noexpand\:\the\catcode`\:\relax}
\catcode`\^^A=\catcode`\%
\catcode`\"=12
\catcode`\*=11
\catcode`\!=12
\catcode`\:=12
%    \end{macrocode}
%
% \begin{macro}{\Gin@driver}
% Initialize the macro to hold the driver file name.
%    \begin{macrocode}
\providecommand\Gin@driver{}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\c@lor@error}
% \changes{v1.0d}{1997/01/07}
%      {Macro added for graphics/2350}
% Helper macro for error handling (redefined by the monochrome option
% to make errors warnings).
%    \begin{macrocode}
\def\c@lor@error#1{%
  \@latex@error{Undefined color #1}\@ehd}
%    \end{macrocode}
% \end{macro}
%
% \begin{option}{monochrome}
% The |monochrome| option should be used \emph{in addition}
%  to one of the standard driver options.
% \changes{v0.3j}{1995/06/16}
%      {Use single hash for latex/1557}
% \changes{v1.0b}{1996/10/29}
%      {Add \cs{colors@false}}
% \changes{v1.0d}{1997/01/07}
%      {Add \cs{c@lor@error} for graphics/2350}
%    \begin{macrocode}
\DeclareOption{monochrome}{%
  \def\c@lor@error#1{\PackageInfo{color}{Undefined color #1}}%
  \AtEndOfPackage{%
    \colors@false
    \def\set@color{%
      \c@lor@special\m@ne
        {color push \current@color}\aftergroup\reset@color}%
    \def\reset@color{\c@lor@special\m@ne{color pop}}%
    \def\set@page@color{%
      \c@lor@special\m@ne{background \current@color}}%
    \def\define@color#1#2{%
      \c@lor@special\m@ne{define #1 #2}}}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{debugshow}
% The |debugshow| option turns on debugging info (perhaps).
% \changes{v1.0a}{1996/09/16}
%     {debugshow option added}
%    \begin{macrocode}
\DeclareOption{debugshow}{\catcode`\^^A=9 \let\GDebug\typeout}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{setpagesize}
% \begin{option}{nosetpagesize}
% The |setpagesize| option requests that the driver option sets the page size.
% \changes{v1.1d}{2016/06/02}
%     {(no)setpagesize options added}
% (Whichever option is used, the page size is not set by this package if |\mag|
% has been changed from its default value.)
%    \begin{macrocode}
\newif\ifGin@setpagesize\Gin@setpagesizetrue
\DeclareOption{setpagesize}{\Gin@setpagesizetrue}
\DeclareOption{nosetpagesize}{\Gin@setpagesizefalse}
%    \end{macrocode}
% \end{option}
% \end{option}
%
% Now the options for supported drivers.
%
% \begin{option}{dvips}
% \begin{option}{xdvi}
% Tom Rokicki's dvips driver, and the X Windows previewer, xdvi, which uses
% (a subset of) the same |\specials|.
%    \begin{macrocode}
\DeclareOption{dvips}{\def\Gin@driver{dvips.def}%
                      \def\c@lor@namefile{dvipsnam.def}}
\DeclareOption{xdvi}{\ExecuteOptions{dvips,monochrome}}
%    \end{macrocode}
% \end{option}
% \end{option}
%
% \begin{option}{dvipdf}
% \changes{v1.0c}{1996/10/31}
%     {dvipdf added}
% Sergey Lesenko's dvipdf driver.
%    \begin{macrocode}
\DeclareOption{dvipdf}{\def\Gin@driver{dvipdf.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{dvipdfm}
% \changes{v1.0h}{1999/01/13}
%     {dvipdfm added}
% \changes{v1.3b}{2021/10/11}
%     {make dvipdfm an alias for dvipdfmx}
% Mark Wick's dvipdfm driver (now merged with xdvipdfmx).
%    \begin{macrocode}
\DeclareOption{dvipdfm}{\def\Gin@driver{dvipdfmx.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{dvipdfmx}
% \changes{v1.0j}{2005/11/14}
%     {dvipdfmx added}
% The driver for the dvipdfmx project.
%    \begin{macrocode}
\DeclareOption{dvipdfmx}{\def\Gin@driver{dvipdfmx.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{pdftex}
% \changes{v1.0e}{1997/06/07}
%     {pdftex added}
%  Han The Thanh's \TeX\ variant.
%    \begin{macrocode}
\DeclareOption{pdftex}{\def\Gin@driver{pdftex.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{luatex}
% \changes{v1.1b}{2016/01/03}
%     {luatex added}
%  Lua\TeX\ \TeX\ variant.
%    \begin{macrocode}
\DeclareOption{luatex}{\def\Gin@driver{luatex.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{luatex}
% \changes{v1.1c}{2016/05/09}
%     {dvisvgm added}
%  dvisvgm driver.
%    \begin{macrocode}
\DeclareOption{dvisvgm}{\def\Gin@driver{dvisvgm.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{xetex}
% \changes{v1.0j}{2005/11/14}
%     {xetex added}
%  Jonathan Kew's \TeX\ variant.
%    \begin{macrocode}
\DeclareOption{xetex}{\def\Gin@driver{xetex.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{dvipsone}
% \begin{option}{dviwindo}
% \changes{v0.3k}{1995/09/07}
%      {Merge dviwindo and dvipsone options}
% The drivers of the Y\&Y \TeX\ system.
% (Which use the same |\specials|.)
%    \begin{macrocode}
\DeclareOption{dvipsone}{\def\Gin@driver{dvipsone.def}}
\DeclareOption{dviwindo}{\ExecuteOptions{dvipsone}}
%    \end{macrocode}
% \end{option}
% \end{option}
%
% \begin{option}{emtex}
% \begin{option}{dviwin}
% Freely available drivers for PCs.
%    \begin{macrocode}
\DeclareOption{emtex}{\def\Gin@driver{emtex.def}}
\DeclareOption{dviwin}{\def\Gin@driver{dviwin.def}}
%    \end{macrocode}
% \end{option}
% \end{option}
%
% \begin{option}{oztex}
% \changes{v1.0f}{1997/09/09}
%     {Merge dvips and oztex options}
% The Oz\TeX\ system for a Macintosh.
% Since release 3 of Oz\TeX, merge with dvips back end.
%    \begin{macrocode}
\DeclareOption{oztex}{\ExecuteOptions{dvips}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{textures}
% Blue sky's Textures system on a Macintosh.
%    \begin{macrocode}
\DeclareOption{textures}{\def\Gin@driver{textures.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{pctexps}
% \begin{option}{pctexwin}
% \begin{option}{pctexhp}
% \begin{option}{pctex32}
% \changes{v1.0b}{1996/10/29}
%     {pctex32 option added}
% The drivers for PTI's \TeX\ system on PCs.
%    \begin{macrocode}
\DeclareOption{pctexps}{\def\Gin@driver{pctexps.def}}
\DeclareOption{pctexwin}{\def\Gin@driver{pctexwin.def}}
\DeclareOption{pctexhp}{\def\Gin@driver{pctexhp.def}}
\DeclareOption{pctex32}{\def\Gin@driver{pctex32.def}}
%    \end{macrocode}
% \end{option}
% \end{option}
% \end{option}
% \end{option}
%
% \begin{option}{truetex}
% \begin{option}{tcidvi}
% \changes{v1.0b}{1996/10/29}
%     {truetex and tcidvi options added}
% The drivers of the Kinch \TeX\ system on PCs, and its
% version with extra  |\special| handling dll's as shipped with
% TCI's Scientific Word.
%    \begin{macrocode}
\DeclareOption{truetex}{\def\Gin@driver{truetex.def}}
\DeclareOption{tcidvi}{\def\Gin@driver{tcidvi.def}}
%    \end{macrocode}
% \end{option}
% \end{option}
%
% \begin{option}{vtex}
% \changes{v1.0g}{1998/05/27}
%     {vtex option added}
% V\TeX\ driver.
%    \begin{macrocode}
\DeclareOption{vtex}{\def\Gin@driver{vtex.def}}
%    \end{macrocode}
% \end{option}
%
% \begin{option}{dvi2ps}
% \begin{option}{dvialw}
% \begin{option}{dvilaser}
% \begin{option}{dvitops}
% \begin{option}{psprint}
% \begin{option}{pubps}
% \begin{option}{ln}
% \changes{v1.0b}{1996/10/29}
%     {old driver options depreciated}
% Old, probably obsolete, drivers commented out. See the section
% on `Driver support' in grfguide to see how to re-enable these
% options in |color.cfg| if you need them.
%    \begin{macrocode}
%\DeclareOption{dvi2ps}{\def\Gin@driver{dvi2ps.def}}
%\DeclareOption{dvialw}{\def\Gin@driver{dvialw.def}}
%\DeclareOption{dvilaser}{\def\Gin@driver{dvilaser.def}}
%\DeclareOption{dvitops}{\def\Gin@driver{dvitops.def}}
%\DeclareOption{psprint}{\def\Gin@driver{psprint.def}}
%\DeclareOption{pubps}{\def\Gin@driver{pubps.def}}
%\DeclareOption{ln}{\def\Gin@driver{ln.def}}
%    \end{macrocode}
% \end{option}
% \end{option}
% \end{option}
% \end{option}
% \end{option}
% \end{option}
% \end{option}
%
%
% \begin{option}{dvipsnames}
% \begin{option}{nodvipsnames}
% 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.
%    \begin{macrocode}
\DeclareOption{dvipsnames}{\def\c@lor@namefile{dvipsnam.def}}
\DeclareOption{nodvipsnames}{\let\c@lor@namefile\relax}
%    \end{macrocode}
% \end{option}
% \end{option}
%
% \begin{option}{usenames}
% 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 declare the name in the named colour
% model.
%    \begin{macrocode}
\let\c@lor@usename\@gobble
%    \end{macrocode}
%
%    \begin{macrocode}
\DeclareOption{usenames}{%
  \def\c@lor@usename#1{%
    \expandafter\color@named\csname\@backslashchar color@#1\endcsname{#1}}}
%    \end{macrocode}
% \end{option}
%
% \section{Using Colours}
%
% \subsection{Declarative form}
%
%  \begin{macro}{\color}
% |\color{|\emph{declared-colour}|}| switches to the colour
% \emph{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[|\emph{model}|]{|\emph{colour-specification}|}| is similar
% to the above, but uses a colour not declared by |\definecolor|. The
% allowed \emph{model}'s vary depending on the driver. The syntax of
% the \emph{colour-specification} argument depends on the model.
%
% \changes{v0.3a}{1994/07/20}
%     {Make \cs{color} robust}
%    \begin{macrocode}
\DeclareRobustCommand\color{%
  \@ifnextchar[\@undeclaredcolor\@declaredcolor}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@undeclaredcolor}
% \changes{v0.2c}{1994/05/09}
%     {Improve error messages}
% \changes{v0.3a}{1994/07/20}
%     {New internal implementation of colour commands}
% Call the driver-dependent command |\color@|\meta{model} to define
% |\current@color|, then call |\set@color| to change the current colour
% accordingly.
%    \begin{macrocode}
\def\@undeclaredcolor[#1]#2{%
  \@ifundefined{color@#1}%
    {\c@lor@error{model `#1'}}%
    {\csname color@#1\endcsname\current@color{#2}%
     \set@color}%
  \ignorespaces}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\@declaredcolor}%
% \changes{v0.1c}{1994/04/01}
%     {Add \cs{ignorespaces}}
% \changes{v0.1e}{1994/05/14}
%     {Minor change to error message}
% \changes{v0.3a}{1994/07/20}
%     {New internal implementation of colour commands}
% |\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.
%    \begin{macrocode}
\def\@declaredcolor#1{%
  \@ifundefined{\@backslashchar color@#1}%
    {\c@lor@error{`#1'}}%
    {\expandafter\let\expandafter\current@color
     \csname\@backslashchar color@#1\endcsname
     \set@color}%
  \ignorespaces}
%    \end{macrocode}
%  \end{macro}
%
% \subsection{Command (Argument) Form}
%
%  \begin{macro}{\textcolor}
% |\textcolor{|\emph{declared-colour}|}{|\emph{text}|}| and
% |\textcolor[|\emph{model}|]{|\emph{colour-spec}|}{|\emph{text}|}|
% are just alternative syntax for |\color|, in
% which the groups are added implicitly. Thus \emph{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
%\begin{verbatim}
% xxx\parbox[t]{1cm}{\textcolor{red}{a}.....
%\end{verbatim}
% now works as expected, with the |xxx| and the red |a| lining up
% correctly.
% \changes{v0.3a}{1994/07/20}
%     {Stop command being \cs{long}, and make robust.}
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
%    \begin{macrocode}
\protected\def\textcolor#1#{\@textcolor{#1}}
\def\@textcolor#1#2#3{\protect\leavevmode{\color#1{#2}#3}}
%    \end{macrocode}
%  \end{macro}
%
% \subsection{Background (Page) Colour}
%
% \begin{macro}{\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.
%
% \changes{v0.1c}{1994/04/01}
%     {end the group even if the colour command generates an error}
% \changes{v0.3c}{1994/09/19}
%     {Use \cs{color} to parse arguments}
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
%    \begin{macrocode}
\protected\def\pagecolor{%
  \begingroup
      \let\ignorespaces\endgroup
      \let\set@color\set@page@color
      \color}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\nopagecolor}
% |\nopagecolor| (suggested by Heiko Oberdiek) removes any currently specified page colour
% returning to the default transparent background. It is not yet supported by all driver options
% and so generates a warning if there is no definition in the driver file.
%
% \changes{v1.1a}{2014/04/23}
%     {add \cs{nopagecolor} graphics/3873}
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
%    \begin{macrocode}
\protected\def\nopagecolor{%
  \@ifundefined{no@page@color}{%
    \PackageInfo{color}{\@backslashchar nopagecolor\space is not supported}%
  }{%
    \no@page@color
  }%
}
%    \end{macrocode}
%  \end{macro}
%
%
% \section{Defining Colours}
%
%  \begin{macro}{\definecolor}
% |\definecolor{|\emph{name}|}{|\emph{model}|}{|\emph{colour-spec}|}|
% defines the color \emph{name}, which may then be used in subsequent
% |\color| or |\textcolor| commands to refer to a colour specified by
% \emph{colour-spec} in the colour model \emph{model}.
%
% |\definecolor| associates the \emph{name} to a colour in
% \emph{model}. So |\color{|\emph{name}|}| would check \emph{name}
% then issue a |\special| for the colour model \emph{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 \emph{model}.
%
% \changes{v0.1b}{1994/03/15}
%     {change name from \cs{newcolor} to \cs{definecolor}}
% \changes{v0.1e}{1994/05/14}
%     {Minor change to error message}
% \changes{v0.3a}{1994/07/20}
%     {New internal implementation of colour commands}
% \changes{v0.3f}{1994/10/04}
%     {Give info about redefinitions}
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
%    \begin{macrocode}
\protected\def\definecolor#1#2#3{%
  \@ifundefined{color@#2}%
    {\c@lor@error{model `#2'}}%
    {\@ifundefined{\@backslashchar color@#1}{}%
      {\PackageInfo{color}{Redefining color #1}}%
     \csname color@#2\expandafter\endcsname
         \csname\@backslashchar color@#1\endcsname{#3}}}
%    \end{macrocode}
%  \end{macro}
%
%
%  \begin{macro}{\DefineNamedColor}
% \changes{v0.3d}{1994/09/29}
%     {Macro added}
% \changes{v0.3e}{1994/10/03}
%     {usenames option added}
% \changes{v0.3f}{1994/10/04}
%     {Give info about redefinitions}
% \changes{v1.2b}{2020/02/24}
%     {corrected test, see https://www.latex-project.org/cgi-bin/ltxbugs2html?pr=graphics/3635}
%
% 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 \texttt{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
% not 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.
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
%    \begin{macrocode}
\protected\def\DefineNamedColor#1#2#3#4{%
  \@ifundefined{define@color@#1}%
    {\c@lor@error{model `#1'}}%
    {\@ifundefined{color@#3}%
      {\c@lor@error{model `#3'}}%
      {\@ifundefined{col@#2}{}%
        {\PackageInfo{color}{Redefining color #2 in named color model}}%
      \csname color@#3\endcsname\@tempa{#4}%
      \csname define@color@#1\endcsname{#2}\@tempa
      \c@lor@usename{#2}}}}
\@onlypreamble\DefineNamedColor
%    \end{macrocode}
%  \end{macro}
%
% \section{Colour Switch}
%
%  \begin{macro}{\ifcolors@}
% This boolean can be tested by higher level macros that may want to
% alter their behaviour if a monochrome driver is being used.
%    \begin{macrocode}
\newif\ifcolors@
\colors@true
%    \end{macrocode}
%  \end{macro}
%
% \section{Whatsit\ldots}
%
% \begin{macro}{\c@lor@special}
% Some drivers can not support all the features of this package. They
% should always put a \meta{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|).
%    \begin{macrocode}
\def\c@lor@special#1#2{%
  \edef\@tempa{\write#1{#2}}\@tempa}
%    \end{macrocode}
%  \end{macro}
%
% \section{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.
%    \begin{macrocode}
\InputIfFileExists{color.cfg}{}{}
%    \end{macrocode}
%
% 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.
% \changes{v0.3b}{1994/09/14}
%                {New style of loading driver files}
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
%
%    \begin{macrocode}
\if!\Gin@driver!
  \PackageError{color}
    {No driver specified}
    {You should make a default driver option in a file \MessageBreak
     color.cfg\MessageBreak
     eg: \protect\ExecuteOptions{dvips}%
     }
\else
  \PackageInfo{color}{Driver file: \Gin@driver}
  \@ifundefined{ver@\Gin@driver}{\input{\Gin@driver}}{}
\fi
%    \end{macrocode}
%
%    \begin{macrocode}
\@ifundefined{c@lor@namefile}{}{\input{\c@lor@namefile}}
%    \end{macrocode}
%
% \section{Default Colour}
%
% \begin{macro}{\normalcolor}
% Early versions of this package redefined |\reset@font| to reset the
% color as well. Current versions do not do this (since there are too many
% |\reset@font| commands hidden in strange places) and so they define 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 \LaTeX\ 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.
% \changes{v0.2b}{1994/04/18}
%     {Only reset the colour with \cmd{\reset@font} not
%      \cmd{\normalfont}}
% \changes{v0.2d}{1994/05/13}
%     {Stop changing \cs{reset@font}. Use the new \cs{normalfont}
%     instead.}
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
%    \begin{macrocode}
\protected\def\normalcolor{\let\current@color\default@color\set@color}
%    \end{macrocode}
% \end{macro}
%
%  \begin{macro}{\default@color}
% Internal macro to store the `default' colour used by |\normalcolor|.
%    \begin{macrocode}
\AtBeginDocument{\let\default@color\current@color}
%    \end{macrocode}
% \end{macro}
%
% |\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| 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 \emph{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.
%
% \section{Higher Level Commands}
%
% With the basic colour primitives specified above we may define a few
% higher 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 document-level commands.
%
% \subsection{Colour Block}
%
% \begin{macro}{\color@block}
% |\color@block{|\emph{width}|}{|\emph{height}|}{|\emph{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 |\special|s, the line is automatically omitted,
% without needing to modify the source of the document (for instance by
% adding the |monochrome| option).
%
%    \begin{macrocode}
\def\color@block#1#2#3{%
  {\set@color\rlap{\ifcolors@\vrule\@width#1\@height#2\@depth#3\fi}}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Coloured Boxes}
%
% \begin{macro}{\colorbox}
% |\colorbox| takes the same argument forms as |\textcolor|, but the
% colour specifies the \emph{background} colour of the box.
% \changes{v0.3b}{1994/09/14}
%                {New implementation}
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
%    \begin{macrocode}
\protected\def\colorbox#1#{\color@box{#1}}
%    \end{macrocode}
% \end{macro}
%
% \changes{v0.3i}{1995/04/27}
%                {Move \cs{leavevmode} for graphics/1521}
% \begin{macro}{\color@box}
%    \begin{macrocode}
\def\color@box#1#2{\color@b@x\relax{\color#1{#2}}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\fcolorbox}
% |\fcolorbox| has an extra \emph{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.
% \changes{v0.3b}{1994/09/14}
%                {New implementation}
% \changes{v1.2a}{2019/11/23}
%      {Add \cs{protected} gh/208}
% \begin{macro}{\fcolorbox}
%    \begin{macrocode}
\protected\def\fcolorbox#1#{\color@fbox{#1}}
%    \end{macrocode}
%
%    \begin{macrocode}
\def\color@fbox#1#2#3{%
  \color@b@x{\fboxsep\z@\color#1{#2}\fbox}{\color#1{#3}}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%

%  \begin{macro}{\color@b@x}
% Internal macro for |\colorbox| and |\fcolorbox|.
% \changes{v0.3b}{1994/09/14}
%                {Macro added.}
% \changes{v0.3i}{1995/04/27}
%                {Add \cs{leavevmode} for graphics/1521}
%    \begin{macrocode}
\long\def\color@b@x#1#2#3{%
 \leavevmode
 \setbox\z@\hbox{\kern\fboxsep{\set@color#3}\kern\fboxsep}%
 \dimen@\ht\z@\advance\dimen@\fboxsep\ht\z@\dimen@
 \dimen@\dp\z@\advance\dimen@\fboxsep\dp\z@\dimen@
 {#1{#2\color@block{\wd\z@}{\ht\z@}{\dp\z@}%
      \box\z@}}}
%    \end{macrocode}
%  \end{macro}
%
% \subsection{Providing \cs{mathcolor}}
%
% This is shared coded between different packages, so external.
%
%    \begin{macrocode}
\input{mathcolor.ltx}
%    \end{macrocode}
%
% \section{Extra Groups}
% Turning on extra groups in the standard \LaTeX\ commands, so that
% colour commands are scoped correctly.
%
% 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.
%
% \begin{macro}{\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.
% \changes{v0.2d}{1994/05/13}
%     {Macro added}
%    \begin{macrocode}
\def\color@setgroup{\begingroup\set@color}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\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.
% \changes{v0.2d}{1994/05/13}
%     {New definition, was previously like \cs{color@setgroup}}
%    \begin{macrocode}
\let\color@begingroup\begingroup
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\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.
% The |\@endpefalse| is required for the newer \texttt{@endpe}
%    handling, again it is harmless if an older kernel is used
%    (because there it was a local assignment).
% \changes{v0.2d}{1994/05/13}
%     {New definition, was previously just \cs{endgroup}}
% \changes{v1.3e}{2024/06/23}
%     {Support new \texttt{@endpe} mechanism}
%    \begin{macrocode}
\def\color@endgroup{\endgraf\@endpefalse\endgroup}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\color@hbox}
% To be used to open a `coloured hbox'
% \changes{v0.3g}{1994/11/08}
%     {Macro added}
%    \begin{macrocode}
\def\color@hbox{\hbox\bgroup\color@begingroup}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\color@vbox}
% To be used to open a `coloured vbox'
% \changes{v0.3h}{1994/11/22}
%     {Macro added}
%    \begin{macrocode}
\def\color@vbox{\vbox\bgroup\color@begingroup}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\color@endbox}
% To be used to close a `coloured hbox'
% \changes{v0.3g}{1994/11/08}
%     {Macro added}
%    \begin{macrocode}
\def\color@endbox{\color@endgroup\egroup}
%    \end{macrocode}
%  \end{macro}
%
%
% \changes{v0.2d}{1994/05/13}
%     {tabbing support removed (now in kernel)}
%
% \changes{v0.3l}{1995/12/07}
%      {\cs{underbar} removed (now in kernel)}
%
% \changes{v0.3h}{1994/11/22}
%     {marginpar, phantom and smash now supported in kernel}
%
% \changes{v0.3l}{1995/12/07}
%      {\cs{showhyphens} removed (now in kernel)}
%
%
% \section{Predefining Colours}
%
% As long as the driver file has defined sufficient colour models, we
% define a few colours, just to get people started.
%
% \begin{macro}{black}
% \begin{macro}{white}
% Black and white `colours'.
%    \begin{macrocode}
\ifx\color@gray\@undefined
  \ifx\color@rgb\@undefined
  \else
    \definecolor{black}{rgb}{0,0,0}
    \definecolor{white}{rgb}{1,1,1}
  \fi
\else
  \definecolor{black}{gray}{0}
  \definecolor{white}{gray}{1}
\fi
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{red}
% \begin{macro}{green}
% \begin{macro}{blue}
% Additive primaries.
%    \begin{macrocode}
\ifx\color@rgb\@undefined\else
  \definecolor{red}{rgb}{1,0,0}
  \definecolor{green}{rgb}{0,1,0}
  \definecolor{blue}{rgb}{0,0,1}
\fi
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{cyan}
% \begin{macro}{magenta}
% \begin{macro}{yellow}
% Subtractive primaries.
%    \begin{macrocode}
\ifx\color@cmyk\@undefined\else
  \definecolor{cyan}{cmyk}{1,0,0,0}
  \definecolor{magenta}{cmyk}{0,1,0,0}
  \definecolor{yellow}{cmyk}{0,0,1,0}
\fi
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \section{And Finally}
%
% Restore Catcodes
%    \begin{macrocode}
\Gin@codes
\let\Gin@codes\relax
%    \end{macrocode}
%
% \Finale
%