diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/xypic/xycolor.doc')
-rw-r--r-- | Master/texmf-dist/source/generic/xypic/xycolor.doc | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/generic/xypic/xycolor.doc b/Master/texmf-dist/source/generic/xypic/xycolor.doc new file mode 100644 index 00000000000..dfbb4d05b4f --- /dev/null +++ b/Master/texmf-dist/source/generic/xypic/xycolor.doc @@ -0,0 +1,349 @@ +%% $Id: xycolor.doc,v 3.3 1996/12/19 03:50:08 ross Exp $ +%% +%% Xy-pic ``Colour extension'' option. +%% Copyright (c) 1993-1996 Ross Moore <ross@mpce.mq.edu.au> +%% +%% This file is part of the Xy-pic package for graphs and diagrams in TeX. +%% See the companion README and INSTALL files for further information. +%% Copyright (c) 1991-1996 Kristoffer H. Rose <krisrose@brics.dk> +%% +%% The Xy-pic package is free software; you can redistribute it and/or modify +%% it under the terms of the GNU General Public License as published by the +%% Free Software Foundation; either version 2 of the License, or (at your +%% option) any later version. +%% +%% The Xy-pic package is distributed in the hope that it will be useful, but +%% WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY +%% or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +%% for more details. +%% +%% You should have received a copy of the GNU General Public License along +%% with this package; if not, write to the Free Software Foundation, Inc., +%% 675 Mass Ave, Cambridge, MA 02139, USA. +%% +\ifx\xyloaded\undefined \input xy \fi + +\xyprovide{color}{Colour extension}{\stripRCS$Revision: 3.3 $}% + {Ross Moore}{ross@mpce.mq.edu.au}% + {Mathematics Department, Macquarie University, NSW~2109, Australia} + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +This extension provides the ability to request that any object be displayed +in a particular colour. + +It requires a suitable `driver' option to provide the necessary |\special| +commands to implement the effects. Thus +$$ +\xy + *+\txt<.8\hsize>{Using this extension will have no effect on the output + unless used with a dvi-driver that explicitly supports it.} + *\frm{-} +\endxy +$$ + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\paragraph*{Header:}\leavevmode +\DOCHEADER + +All effects defined in the |color| extension can be implemented using most +\PS\ <driver>s, and some non-\PS\ ones, loaded using |\xyoption{xyps}|. +This file provides `generic' code which is known to work correctly with +most drivers. For driver-specific variations, consult the appropriate +<driver> file. + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%\paragraph*{Colour} +Colours are specified as a <shape> modifier which gives the name of the +colour requested. It is applied to the whole of the current <object> +whether this be text, an \Xy-pic line, curve or arrow-tip, or a composite +object such as a matrix or the complete picture. However some DVI drivers +may not be able to support the colour in all of these cases. +% +\begin{defs} +|[|<colour name>|]| & use named colour\cr +\noalign{\smallskip} +??c![\newxycolor]|{|<name>|}{|<code>|}|\kern-20pt &\kern25pt + define colour \cr +??c![\UseCrayolaColors] & load colour names \cr +\end{defs} +% +If the DVI-driver cannot support colour then a request for colour +only produces a warning message in the log file. After two such +messages subsequent requests are ignored completely. + +\DOCMODE( +\xydef@\xycolorwarning@@{\xycolormessage@ + \gdef\xycolorwarning@{\xycolormessage@ + \xywarning@{...no further colour warnings will be given.}% + \global\let\xycolorwarning@=\relax }} +\xylet@\xycolorwarning@=\xycolorwarning@@ + +\xydef@\xycolormessage@{% + \xywarning@{Current driver does not support colour.}}% +\DOCMODE) + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +There are two methods, perhaps used simultaneously, for handling requests +for colour. The |\xylocalColor@| is the normal method, colouring whatever +objects \TeX\ typesets from fonts. The more specialized |\xycolor@| is used +with the \PS\ back-end. This is necessary since some <driver>s assume that +the current colour should be `black' when the contents of a |\special| is +interpreted, e.g. within \PS. + +Thus a <driver> which supports both colour and \PS\ must define a method +to handle |\xylocalColor@| but should leave alone |\xycolor@|. The latter +method will be adjusted appropriately when a \PS\ <driver> is installed. + +\DOCMODE( +\xydef@\xyNoColor@#1{} +\xylet@\xycolor@@=\xyNoColor@ +\xydef@\xyNoColor@@#1#2{\xycolorwarning@} + +\xydef@\xycolor@{\xycolor@@} +\xylet@\xylocalColor@=\xyNoColor@@ + +\xydef@\UnloadColor@{% + \let\xylocalColor@=\xyNoColor@@ +% \let\xycolor@=\xyNoColor@ + \let\xycolor@@=\xyNoColor@ + \let\xycolorwarning@=\xycolorwarning@@ } +\xylet@\UnloadColor@@=\UnloadColor@ + +\xyaddunsupport{color}{\UnloadColor@@\relax} +\DOCMODE) + +This next macro is to inherit a default colour from the surrounding +document, perhaps using one already defined by \LaTeXe + +\DOCMODE( +\ifx\current@color\undefined \xydef@\xybasecolor@{}% +\else \def\xybasecolor@{\current@color}\fi + +%\xydef@\xycmath@{\hbox\bgroup\dimen@=.55ex \checkxycolor@ \xyinside@} +%\xydef@\xycnomath@{\hbox\bgroup\dimen@=\z@ \checkxycolor@ \xyinside@} + +%\xydef@\checkxycolor@{\ifx\xybasecolor@\empty\else +% \expandafter\imposexycolor@\fi} +%\xydef@\imposexycolor@{\xylocalColor@} +\DOCMODE) + +A commonly used method is to maintain a colour-stack. +The following commands are for use with such a setup, however they should +only be called from code installed from a <driver>-file. Different drivers +may do things differently; e.g. |dvips| uses a single |\special| via: +|\def\xycolor@push@@#1{\special{color push #1}}|, but Textures uses two: +|\xydef@\xycolor@push#1{\special{color push}\special{color #1}}|. +Since the colour-stack idea was proposed by Tomas Rokicki,the |dvips| method +is the default behaviour. + +\DOCMODE( +\xydef@\xystackcolor@{\bgroup \DN@##1##2{\egroup}% + \ifInvisible@\else\ifHidden@\else\DNii@{\no@@}\ifx\nextii@\Connect@@ + \else\DN@{\xystackcolor@i}\fi\fi\fi \next@ } + +\xydef@\xystackcolor@i#1#2{\checkXyStyle@ + \DN@{#2}\ifx\next@\empty + \def\tmp@##1{\DN@{\xycolor@push{#1}##1\xycolor@pop}}% + \else\def\tmp@##1{\DN@{\xycolor@push{#2 #1}##1\xycolor@pop}}\fi + \toks@={\egroup \let\xy@style@=\relax \def\Drop@@}% + \expandafter\tmp@\expandafter{\Drop@@}% + \expandafter\addtotoks@\expandafter{\expandafter{\next@}\def\Connect@@}% + \expandafter\tmp@\expandafter{\Connect@@}% + \expandafter\addtotoks@\expandafter{\expandafter{\next@}}% + \the\toks@ }% + +\xydef@\xycolor@push@@#1{\special{color push #1}} +\xydef@\xycolor@pop{\special{color pop}} +\xylet@\xycolor@push=\xycolor@push@@ +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\paragraph*{Named colours and colour models} + +New colour names are created with |\newxycolor|, taking two arguments. +Firstly a name for the colour is given, followed by the code which will +ultimately be passed to the output device in order to specify the colour. +If the current driver cannot support colour, or grayscale shading, then +the new name will be recognised, but ignored during typesetting. + +\DOCMODE( +\xydef@\newxycolor#1#2{\newxyColor{#1}{}{}{#2}{}} +\xydef@\newxyColor#1#2#3#4{\newxycolor@{#1}{#2}{#3}{#4}{}} +\DOCMODE) + +For \PS\ devices, the \Xy-ps \PS\ dictionary defines operators |rgb|, +|cmyk| and |gray| corresponding to the standard RGB and CMYK colour models +and grayscale shadings. +Colours and shades are described as: +$r\;g\;b$ |rgb| or $c\;m\;y\;k$ |cmyk| or $s$ |gray|, where the parameters +are numbers in the range $0\le r,g,b,c,m,y,k,s\le 1$. +The operators link to the built-in colour models + or, in the case of |cmyk| for earlier versions of \PS, give a simple +emulation in terms of the RGB model. + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +Existing color names can be overridden using |\newxycolor@#1#2\relax|. + +\DOCMODE( +\xydef@\newxycolor@#1#2#3#4#5{% + \expandafter\let\expandafter\next@\csname shape [#1]\endcsname + \ifx\next@\relax + \DN@{#4}\ifx\next@\empty + \DN@{#2}\ifx\next@\empty + \DN@{\newxystyle{#1}{\xylocalColor@{}{#3}\xycolor@{#3}}}% + \else + \DN@{\newxystyle{#1}{\xylocalColor@{#2}{#3}\xycolor@{#2 #3}}}% + \fi + \else\DN@{#2#3}\ifx\next@\empty + \DN@{\newxystyle{#1}{\xylocalColor@{#4}{}\xycolor@{#4}}}% + \else + \DN@{\newxystyle{#1}{\xylocalColor@{#2}{#3}\xycolor@{#4}}}% + \fi \fi + \else \def\tmp@{\relax}\DNii@{#5}% + \ifx\nextii@\tmp@ + \DN@{#4}\ifx\next@\empty + \DN@{#2}\ifx\next@\empty + \DN@{\newxystyle{#1}{\xylocalColor@{}{#3}\xycolor@{#3}}}% + \else + \DN@{\newxystyle{#1}{\xylocalColor@{#2}{#3}\xycolor@{#2 #3}}}% + \fi + \else + \DN@{#2#3}\ifx\next@\empty + \DN@{\newxystyle{#1}{\xylocalColor@{#4}{}\xycolor@{#4}}}% + \else + \DN@{\newxystyle{#1}{\xylocalColor@{#2}{#3}\xycolor@{#4}}}% + \fi \fi + \else\DN@{}\fi\fi \next@\relax} +\DOCMODE) + +Standard colour names which are defined automatically correspond +to the three primaries |red|, |green|, |blue| and their complements +|cyan|, |magenta|, |yellow| as well as three extreme grayscale shades +|black|, |white|, |gray|. + +\DOCMODE( +\xydef@\xystandardcolors@{% +% \newxycolor@{black}{1.}{gray}{}\relax % Textures reverses gray-scales +% \newxycolor@{white}{0.}{gray}{}\relax % +% \newxycolor@{black}{0.}{gray}{}\relax % This is normal for PostScript +% \newxycolor@{white}{1.}{gray}{}\relax % + \newxycolor@{black}{0. 0. 0.}{rgb}{}\relax % avoid the hassles. + \newxycolor@{white}{1. 1. 1.}{rgb}{}\relax % + \newxycolor@{gray}{.5}{gray}{}\relax + \newxycolor@{grey}{.5}{gray}{}\relax + \newxycolor@{red}{1. 0. 0.}{rgb}{}\relax + \newxycolor@{green}{0. 1. 0.}{rgb}{}\relax + \newxycolor@{blue}{0. 0. 1.}{rgb}{}\relax + \newxycolor@{cyan}{0. 1. 1.}{rgb}{}\relax + \newxycolor@{magenta}{1. 0. 1.}{rgb}{}\relax + \newxycolor@{yellow}{1. 1. 0.}{rgb}{}\relax + \xyuncatcodes } +\DOCMODE) + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\NOTE: The driver file must call |\xystandardcolors@| before these colours +become accessible. This is to allow any <driver>-specific definitions +to be active when these colours are defined. + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\paragraph*{Saving colour and styles} +% +When styles are saved using |[=|<word>|]|, see~??c[[=], +then the current colour setting (if any) is saved also. +Subsequent use of |[|<word>|]| recovers the colour and accompanying +line-style settings. + +Further colour names are defined by the command |\UseCrayolaColours| that +loads the |crayon| option, in which more colours are defined. Consult the +file |xyps-col.doc| for the colours and their specifications in the RGB +or CMYK models. + +\DOCMODE( +\xydef@\UseCrayolaColors{\xyrequire{crayon}\xyuncatcodes}% +% \xyinputorelse@{xyps-col}{\xyerror@{Could not load xyps-col}{}}} +\DOCMODE) + +\DOCMODE1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\subparagraph*{xyps-col.tex:} +\subparagraph*{xycrayon.tex:} +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\subsubsection{{\tt xyps-col.doc}:} +\subsubsection{{\tt xycrayon.doc}:} +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%\inputdoc!{xyps-col.doc} +\inputdoc!{xycrayon.doc} + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\paragraph*{\PS\ colour} +% +When \PS\ driver support is available, the method for handling colour +within diagrams may be different. The reason for this is that some +dvi-drivers reset the colour to black before placing the contents of the +|\special|. To counter this, the \PS\ code maintains its own colour-stack. +Support is established within a separate file |xyps-c.tex|, loaded from +the appropriate <driver>-files. + +\DOCMODE( +\xydef@\xyBEcolorcheck@{\ifx\xycolor@@\xyNoColor@\else + \xywarning@{PostScript colour support should be OK.}\fi }% + +\xywithoption{ps}{% + \xyinputorelse@{xyps-c}{\xyerror@{Could not load xyps-c}{}}}% + \xycatcodes +\DOCMODE) + +\DOCMODE2%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\paragraph*{The end \& Log}\leavevmode + +\DOCMODE( +\xyendinput + +% $Log: xycolor.doc,v $ +% Revision 3.3 1996/12/19 03:50:08 ross +% Maintenance release. +% +% Revision 3.3 1996/12/18 08:56:49 ross +% minor updates +% +% Revision 3.2 1995/09/19 18:20:20 ross +% Bug fix release. +% +% Revision 3.1 1995/09/05 20:36:33 ross +% Release! +% +% Revision 3.0 1995/07/07 20:13:19 ross +% Major release w/new User's Guide! +% +% Revision 2.14 1995/07/06 02:56:02 kris +% Buglets... +% +% Revision 2.13 1995/07/04 15:04:51 ross +% Ready for release of v3. +% +% Revision 2.10 1994/06/15 12:46:03 ross +% Second release 3beta. +% Colour and line style saving works; label colouring bug fixed. +% +% Revision 2.9 1994/06/09 14:39:49 ross +% Release 3beta. +% +% NEW for version 2.9 by by Ross Moore. +\DOCMODE) + +\DOCMODE3%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% Tell Emacs that this is a LaTeX document and how it is formatted: +% Local Variables: +% mode:latex +% fill-column:77 +% fill-prefix:"" +% End: |