summaryrefslogtreecommitdiff
path: root/macros/latex209/contrib/misc/truecols.doc
blob: 0517057972d7e1f384306ebb9ac93d16c227c908 (plain)
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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
\iffalse
% This is truecols.doc, a sub-style for use with SliTeX.
% It is documented with the conventions of doc.sty; run it through a
% suitable driver file to print format the documentation.
% It is intended for use with ltugboat.sty as it stands.
% Note that with the old doc.sty you'll get extra space at the front
% of paras starting with \DescribeMacro.
% Use docstrip.tex to strip the comments to form truecols.sty.

%% Copyright D.Love, SERC Daresbury Laboratory, 1991
%% The `doc' version of this style is re-distributable and usuable
%% under conditions of the GNU copyleft, but please mark any changes,
%% list them here and report any major enhancements to the author.
\fi
\def\filedate{18/4/90}
\def\fileversion{1.2}
% \NoBlackBoxes
% \def\ps{\PS}\def\dvi{{\tt dvi}}\def\pj{Paint\-Jet}
%^^A can't use \verb in arguments:
% \def\sp{{\tt\char\escapechar special}}
% \title{Experiments in \TeX nicolour --- A \SliTeX\ Sub-style for
% Colour Printers\footnote{File version \fileversion, dated
% \filedate.}}
% \author{David Love}
% \address{SERC Daresbury Laboratory,\\Warrington WA4 4AD, UK}
% \netaddress{d.love@daresbury.ac.uk}
%
% \maketitle
%
% \begin{abstract}
% \noindent 
% \SliTeX\ assumes that colour transparencies will be produced from
% layers, each printed in a single colour.  This sub-style allows a
% suitable \dvi{} driver to produce multi-coloured
% slides in one go (i.e., using a single layer).  It is customisable
% for \ps{} printers or simpler colour devices like the the HP \pj{}.
% \end{abstract}
%
% \section{Introduction}
% \SliTeX{}---a version of \LaTeX{} for making slides---supports colours
% in its output by producing `colour layers', one per colour \cite{slitex}.
% It is assumed that these will be copied to transparencies of the
% appropriate colour and overlapped to make a composite multi-colour
% slide.  Colour is valuable on slides, but this means
% of producing it is inconvenient and inappropriate if you have
% a colour printer and a suitable \dvi{} driver for it.
%
% This sub-style for \SliTeX{} allows all the colours to be produced
% in one layer.  It is designed for use with colour \ps{} printers or
% others like the HP \pj{} with suitable \dvi{} drivers, following
% experiments with these printers at Daresbury.
% It is intended to provoke discussion
% of the use of colour with \TeX{}, a subject about which little
% has been said so far in public, rather than be at all definitive.
% 
% \section{Approach}
% Use of colour with \TeX{} is non-standard and has to
% be done by passing information to the \dvi{} driver.  This could be
% done in one of two ways:
% \begin{itemize}
% \item using fonts whose names idenitify them to the driver to
% be printed in a particular colour but are otherwise
% identical to the black version (possibly using virtual fonts \cite{vf});
% \item using the \sp{} mechanism to tell the driver to
% change colours.
% \end{itemize}
% The second option is easier to implement with an existing driver and
% allows colour for other objects than characters i.e.,
% rules,\footnote{{\tt \char\escapechar colorslides} doesn't work
% properly with rules---they come out in each layer.} 
% and has been adopted here.
% Unfortunately, existing drivers differ in their \verb+\special+
% mechanisms and few understand colour explicitly.
% However, drivers which  allow you to include arbitrary \ps{} with a
% \sp{} have this ability implicitly
% since colour operators are defined in \ps{} \cite{redbook}.
% (Colour gets rendered in shades of grey on a normal laser printer,
% which can help with proofing.)
%
% There is a proposed standard for \sp{}s \cite{hosek}
% which includes colour information, but the definition of the
% \verb+textcolor+ \sp{} is inconveniently related to the \dvi{} stack.
% Working with existing \ps{} drivers, one has to make
% some assumptions about them, as detailed below.
%
% In the case of the \pj{} printer there does not appear to be an existing
% driver, so one was produced with a suitable \sp{} defined arbitrarily.
%
% \section{\pj{} Driver}
% The Hewlett-Packard \pj{} can print in colour at 180~dpi, which
% is quite adequate for making transparencies.  A driver for it was
% produced using the HP Laserjet version from Beebe's family \cite{beebe}
% as a basis since this has rather similar control sequences.
% It was extended to maintain four bitmaps independently,
% allowing three colours other than black to be printed.  Allowing
% more colours would make the code more complicated and slower as well
% as using more memory for the bitmaps.  It supports one
% \sp{} to allow colour changes between black, red, green
% and blue.  A defect is that the result of overlapping items of
% different colours is independent of their order in the \dvi{} file,
% but this simplifies the driver considerably.
% 
% \section{Assumptions}
% The necessary assumptions about the driver are largely isolated in
% the macros \verb+\special@color+
% and \verb+\colormix+.\footnote{I spell the
% English way except in code names, where I reluctantly use `color'
% for consistency with existing code.}
% Suitable changes could be quite easily made to conform with an
% eventual standard for \sp{}s or use a different driver.
% 
% \subsection{\ps}
% We assume that a \ps{} driver understands
% \sp{}s of the form
% \begin{center}
% \verb*+\special{ps:: +\meta{code}\verb+}+,
% \end{center}
% where \meta{code} is
% arbitrary \ps{} from which the surrounding code output by the driver is not
% protected.  This is appropriate for Rokicki's
% {\tt dvips} and ArborText's DVILASER/PS\@.
\iffalse
% and
% would be for the Daresbury {\tt dvitops} if it didn't zap the
% graphics state at each font change.\footnote{This can probably be
% fixed by messing with the header.}
\fi
% We use the RGB colour model \cite[\S 4.8]{redbook}.
%
% \subsection{\pj{} or other printer}
% A non-\ps{} printer should understand a special of the form
% \verb*+{color +\meta{colour}\verb+}+, where \meta{colour} can take
% the values {\tt black\rm, \tt red\rm, \tt green\rm\ or \tt blue},
% determining the colour of all subsequent printing until the next
% change.  The default is assumed to be black.
%
% \section{User interface}
% As well as re-defining some internal \SliTeX{} macros, we make some
% new ones as described below.
% 
% \DescribeMacro{\psprinterfalse}
% The default is to assume the use of a \ps{} printer.  Saying
% \verb+\psprinterfalse+ changes this to produce output suitable for
% the \pj{} (or similar printer).  This should only be done
% in the preamble.
% 
% Any colours you use {\em must\/} be declared using
% \verb+\colors+ \DescribeMacro{\colors}(even red, green, blue and black).
% \DescribeEnv{slide}
% They do not need including in the argument of \verb+\begin{slide}+ for
% use with \verb+\truecolors+, but there needs to be some argument,
% even if it's null.
%
% \DescribeMacro{\truecolors}
% Like \verb+\blackandwhite+, \verb+\truecolors+ is
% invoked from the driver file to process a batch of slides described
% in the file given as its argument.  It works like
% \verb+\blackandwhite+ in that it only makes one layer, but will
% include the 
% information for the printer to produce the
% colours in the \dvi{} file.  Notes are not printed by
% \verb+\truecolors+. 
% 
% \subsection{\ps{} specifics}
% \DescribeMacro{\colormix}
% Before you use a new \ps{} colour, you have to define how it is
% mixed from red, green and blue.  \verb+\colormix+ does this for you.
% It takes four arguments.  The first is the name of the colour and
% the others are numeric values for the intensities of red, green and
% blue respectively in the mixture.  (See the description of RGB in
% \cite{redbook}.)  These values must lie in the
% range 0--1 such that 1 is most intense and 0 is no
% intensity.  Thus you might define yellow by
% \[\verb+\colormix{yellow}{0}{1}{1}+\]
% You don't need to define red, green, blue or black---they are done
% already.
%
% You could put blocks of text on a coloured background either by
% setting it on top of a suitably-sized rule or using explicit \sp s.
%
% \subsection{Other printers}
% Only red, green, blue and black are available.  Use of
% \verb+\colormix+ will produce a warning.  Using a non-white
% background won't work very well with the \pj{}.
%
% \subsection{Problem with list environments}
% A problem occurs if you want the first text in a list environment
% item to be a different colour to the label since \verb+\special+s
% before the text appear in the \dvi{} file before the label.
% A way round this is to insert \verb+\leavevmode+ after \verb+\item+.
% This sort of problem may occur in other situtaions.
% 
% \section{Code}
% \subsection{Driver-independent code}
%    \begin{macrocode}
\typeout{SliTeX style option `truecols' (v. \fileversion\space of \filedate)}
%    \end{macrocode}
% \DescribeMacro{\if@truecol}
% We introduce a new switch to tell us whether we can assume we have
% true colour printing capability and unset it initially.
%    \begin{macrocode}
\newif \if@truecol \@truecolfalse
%    \end{macrocode}
% \DescribeMacro{\the@color}
% We keep track of the current colour using \verb+\the@color+
% (to get colours right with grouping).
% Initially it's black.
%    \begin{macrocode}
\def\the@color{\black}
%    \end{macrocode}
% \DescribeMacro{\ifpsprinter}
% This tells us if we're dealing with a \ps{} printer (the default)
% or not.
%    \begin{macrocode}
\newif \ifpsprinter \psprintertrue
%    \end{macrocode}
% \DescribeMacro{\truecolors}
% A new \verb+\truecolors+ command is defined, which works like
% \verb+\blackandwhite+, printing everything in the file given as its
% argument  in one layer.  Thus it must set the \verb+\@bw+
% switch.  This slightly unfortunate change to \verb+\@bw+'s
% meaning makes the alterations easier.
%    \begin{macrocode}
\newcommand{\truecolors}[1]{\@truecoltrue \blackandwhite{#1}}
%    \end{macrocode}
%\DescribeMacro{\@color}
% We modify \verb+\@color+ to take note of the \verb+@truecol+ setting
% (if \verb+@bw+ is set).  If appropriate, it puts out a
% colour-changing \sp{} using \verb+\special@color+.  We can omit the
% test for a colour change in math mode if we're not depending on
% invisible fonts.
%    \begin{macrocode}
\def\@color#1{%
  \if@truecol \else \@mmodetest \fi %  change
  \if@bw \@visibletrue 
    \if@truecol \special@color{#1}\fi %  change
  \else \@visiblefalse
    \@for \@x@a :=#1\do{\ifx\@x@a\@currcolor\@visibletrue\fi}\fi
  \@currsize \@currfont \ignorespaces}
%    \end{macrocode}
% \DescribeMacro{\endslide} 
% We ensure that the driver colour is
% reset to black at the end of each slide
% by setting it in \verb+\endslide+. 
%    \begin{macrocode}
\def\endslide{\@color{black}\par\break}
%    \end{macrocode}
% \DescribeMacro{\note}
% We don't want to waste truecolour output on producing notes, which
% we will if we don't re-define \verb+\note+ (since \verb+@bw+ is set
% by \verb+\truecolors+).  We just add a test on \verb+@truecol+.
%    \begin{macrocode}
\def\note{%
  \stepcounter{note}%
  \if@bw 
    \if@truecol \gdef\@slidesw{F}%  added
    \else
      \gdef\@slidesw{T}%
      \if@onlynotesw\@whilenum \c@slide > \@donotehigh\relax
        \do{\@setlimits\@donotelist\@donotelow\@donotehigh}\ifnum
        \c@slide < \@donotelow\relax \gdef\@slidesw{F}\fi\fi\fi
  \else \gdef\@slidesw{F}\fi
  \if\@slidesw T\newpage\thispagestyle{note}\else
  \end{note}\@gobbletoend{note}\fi }
%    \end{macrocode}
% \DescribeMacro{\colors}
% We re-define \verb+\colors+ to check that we know about those
% specified.  It could, perhaps, be dispensed with at the cost of
% incompatibility with standard \SliTeX{}.  If we're not using \ps{}
% only the four pre-defined colours are available.
%    \begin{macrocode}
\def\colors#1{%
  \@for\@colortemp:=#1\do{%
    \@ifundefined{\@colortemp @mix}{%  change
      \ifpsprinter
        \errhelp{You could use I to define it now.}%
        \errmessage{You need to use \noexpand\colormix to define 
                    \@colortemp}%
      \else
        \errhelp{It's safe to carry on.}%
        \errmessage{You can only use black, red, green and blue with
                    this printer, not \@colortemp}%
        \expandafter\xdef\csname\@colortemp\endcsname{\relax}%
      \fi
    }{}
    \expandafter\xdef\csname\@colortemp\endcsname
      {\noexpand\@color{\@colortemp}}%
  }% (do)
  \ifx\@colorlist\@empty \gdef\@colorlist{#1}%
  \else \xdef\@colorlist{\@colorlist,#1}\fi} 
%    \end{macrocode}
% \DescribeMacro{\pagestyle}
% Finally we change the default pagestyle since the alignment marks
% would only be useful with overlays.
%    \begin{macrocode}
\pagestyle{plain}
%    \end{macrocode}
%
% \subsection{Driver-dependent code}
% \DescribeMacro{\colormix}
% The \ps{} user can mix new colours in the RGB model using
% \verb+\colormix+.  It takes four arguments, the name of the colour
% (which must then be declared with \verb+\colors+) and three real numbers
% in the range 0--1 describing respectively the intensity of red,
% green and blue in the result.  The result is to define a macro of
% the form \verb+\+\meta{colour}\verb+@mix+ to be a list of arguments 2--4.
%    \begin{macrocode}
\def\colormix#1#2#3#4{%
  \ifpsprinter \else \typeout{Warning: \noexpand\colormix used with
    \noexpand\psprinterfalse.}\fi
  \color@range@check{#2}\color@range@check{#3}\color@range@check{#4}%
  \expandafter\xdef\csname#1@mix\endcsname{#2 #3 #4}}
%    \end{macrocode}
% \DescribeMacro{\color@range@check}
% We need to check that the numeric arguments of \verb+\colormix+ are
% in the range 0--1.  Since they're real numbers we
% convert them to dimensions to test.
%    \begin{macrocode}
\def\color@range@check#1{%
  \def\fred{\errhelp{Carry on, but you'll get a PostScript error if
              you try to print the results.}%
            \errmessage{\noexpand\colormix arguments must be in the 
              range 0--1}}%
  \ifdim#1 pt < 0pt \fred \fi \ifdim#1 pt > 1pt \fred \fi }
%    \end{macrocode}
% \DescribeMacro{\special@color}
% This has to change the current colour on the output device to that
% given as its argument,
% but first has to store the current value and make sure it is
% re-instated at the end of the current group.  (Coloured fonts would
% avoid the need for this.)  Note the \verb+{}+ inserted at the end of
% the group to avoid spaces being gobbled afterwards as with
% \verb+{\red foo} bar+.  Probably there's a better way of doing this.
%    \begin{macrocode}
\def\special@color#1{%
  \def\the@color{\csname#1\endcsname}\aftergroup\the@color
    \aftergroup{\aftergroup}%
%    \end{macrocode}
% To change colour with \ps{} we use a \sp{} which
% will emit code of the form
% \begin{center} \meta{red level}\verb*+ +\meta{green level}\verb*+ +^^A
% \meta{blue level}\verb*+ +{\tt setrgbcolor} \end{center}
% Perhaps this should be parameterised.
% The three levels are provided by a macro of the form
% \verb+\+\meta{colour}\verb+@mix+ which must be defined for each
% \meta{colour} which is used.
% It might be useful is to
% define a white font (RGB=[1~1~1]) which could be painted over a
% coloured region.
%    \begin{macrocode}
  \ifpsprinter \special{ps:: \csname#1@mix\endcsname\space 
                        setrgbcolor\space}%
%    \end{macrocode}
% For the \pj{} we output
% \begin{center}\verb*+\special{color +\meta{colour}\verb+}+,
% \end{center}
% where \meta{colour} can be {\tt black\rm, \tt red\rm, \tt green \rm
% or \tt blue} and we assume that \verb+#1+ is one of these.
%    \begin{macrocode}
  \else \special{color #1}\fi % (\ifpsprinter)
} % (\def\special@color)
%    \end{macrocode}
% \DescribeMacro{\black@mix}\DescribeMacro{\red@mix}
% \DescribeMacro{\blue@mix}\DescribeMacro{\green@mix}
% Here we define the RGB mixes for the \ps{} colours we support
% initially.  These macros need defining for the \pj{} too, so that we
% can check on colours the user tries to invoke.
%    \begin{macrocode}
\def\black@mix{0 0 0} \def\red@mix{1 0 0}
\def\blue@mix{0 0 1}  \def\green@mix{0 1 0}
%    \end{macrocode}
% \begin{thebibliography}{1}
% \bibitem{slitex} Leslie Lamport. {\sl \LaTeX{}: A Document
% Preparation System}; {\tt slitex.tex} dated 10 November 1986; {\tt
% slides.sty} dated 17 January 1986.
% \bibitem{vf} Donald Knuth. \TUB, 11(1), 1990, p.~13.
% \bibitem{redbook} Adobe Systems Inc. {\sl\ps\ Language Reference Manual}.
% \bibitem{hosek} Don Hosek.  Proposed \verb+DVI \special+ command
% standard.  (See \TUB, 10(2), 1989, p.~188.)
%^^A \bibitem{glv&tjr} Glenn L. Vandenberg and Thomas J. Reid.
%^^A \sp{} issues.  \TUB, 8(3), 1987, p.~287.
% \bibitem{beebe} Nelson H. F. Beebe.  {\sl A \TeX{} DVI Driver Family}.
% \end{thebibliography}
% {\tenuit Note added:\enspace } Since doing this work I have become
% aware of two related pieces of work.  One is Ken Yap's article
% ``Making 35~mm Colour Slides with \SliTeX'' in \TUB{} 11.2 (1990),
% p.~279.  He also used a modified version of a Beebe driver for his
% raster device, but maintained the colour layers idea.  This style
% provides the `more elegant and general solution' to the problem
% mentioned in his conclusion.
% 
% The other work is concerned with specifically \PS{} printers rather
% than raster ones.  It is Leslie Lamport's {\tt ps-slides.sty} which
% Sebastian Rahtz pointed out to me, available from the Aston archive.
% Since it is specific to \PS{} it can support fancier facilities.  His
% approach to changing the way standard \SliTeX{} works is somewhat
% different from mine, which presumably means I was a little misguided.
% \makesignature