Debian Codegraph @

texmf-dist/source/latex/epsdice/epsdice.dtx

raw
1 % \iffalse
2 %
3 % EPSDICE.DTX by Thomas Heim ([email protected])
4 %
5 % LICENSE: LPPL
6 %
7 % a small package to include dice faces in .eps format
8 %
9 % provides the command \epsdice{#1}
10 % taking one mandatory argument, an integer from 1 to 6
11 % and one optional argument: 'black' (for black background, with white dots);
12 % default is white background with black dots)
13 %
14 % HISTORY:
15 % ========
16 %
17 % 2001/02/11 -- first release, for dvips only
18 %
19 % 2001/02/13 -- now works under pdfLaTeX, too
20 % (with Rolf Niepraschk's help)
21 %
22 % 2001/09/04 -- "program encapsulated" by introducing "@" in counter name
23 % -- distributed as .dtx and .ins files, plus binary .pdf file
24 % -- some modifications in documentation
25 % -- NO CHANGES IN USER INTERFACE (tah)
26 %
27 % 2007/02/11 -- added OPTIONAL argument [black] to user interface, for
28 % reversed colors (extension suggested and drawings provided
29 % by Christoph Zurnieden, [email protected])
30 %
31 % 2007/02/15 -- removed spurious comment line from generated EPS file
32 % (thanks to Christoph for spotting the bug)
33 % \fi
34 %<*sampledoc>
35 \documentclass[11pt]{article}
36 \usepackage{epsdice}
37 %
38 \title{Package `epsdice' --- a scalable dice font}
39 \author{2007/02/15 -- Version 2.1 \\[.5ex] Thomas Heim \\[.5ex]
40 ([email protected])}
41 \date{}
42 \begin{document}
43 \maketitle
44 \section{Introduction}
45 Dice fonts are already available in \textsc{metafont} format.
46 (I should know, I wrote one myself: \texttt{dice3d.mf}.)
47 For some applications it seems preferable, however, to have the fonts
48 in scalable form. The package \texttt{epsdice} fills this gap.
49
50 \texttt{epsdice.sty} provides a single command,
51 \verb+\epsdice{#1}+, taking one mandatory argument, an integer from 1 to 6,
52 and recognising one optional argument, namely \verb+[black]+
53 for a black die with white dots.\footnote{Thanks to Chrisoph Zurnieden for
54 suggesting the extension with reversed colors, and for adjusting the drawings
55 to this purpose.} The default behavior (i.e., with \emph{no} optional argument
56 or with \emph{any optional argument other} than \verb+[black]+) results in
57 a white die with black dots.
58
59 The mandatory argument may also be the value of a counter. Thus
60 automatic representation of (generated or input) data is possible as well.
61 Of course, values outside the range 1--6 will not be represented as die faces.
62
63 Depending on the value of the argument, \verb+\epsdice+ includes the
64 appropriately clipped region from a file containing simple drawings
65 of die faces. The drawings scale with the current font because the
66 height of the included graphics file is set in terms of `ex' units.
67 %
68 \section{Requirements and limitations}
69 \texttt{epsdice} relies on the \texttt{graphicx} package to include
70 the drawings.
71 It also uses the \texttt{ifthen} package to validate the arguments
72 (error checking).
73
74 The package has been tested with two widely used package drivers
75 for \texttt{graphicx}: \verb+[dvips]+ and \verb+[pdftex]+. By
76 default, the command \verb+\epsdice+ includes
77 \texttt{epsdice.eps} under \LaTeXe, and \texttt{epsdice.pdf}
78 under pdf\LaTeX, respectively\footnote{Many thanks to Rolf
79 Niepraschk for his help with the latter!}
80 (unless your \texttt{graphics.cfg} file specifies non-standard
81 settings).
82
83 Clipping is supported only in pdf\TeX\ versions
84 $\ge 0.14$. You will also need an up-to-date version of
85 \texttt{pdftex.def}: Clipping is not supported in versions
86 \texttt{v0.03c} \texttt{[2000/09/04]} or earlier.
87 If your pdf\TeX\ is up-to-date but
88 you still receive error messages about clipping not being
89 supported, get the latest \texttt{pdftex.def}
90 here: \\[.5ex]
91 \verb+http://www.tug.org/applications/pdftex/pdftex.def+
92 \\[.5ex]
93 I tested the package successfully with pdf\TeX\ 0.14e
94 and \texttt{pdftex.def} v0.03f \texttt{[2000/11/10]}.
95 %
96 \section{Configuring this package}
97 To finish the installation of the package,
98 simply move the following files somewhere in your ``local texmf tree'':
99 \begin{verbatim}
100 epsdice.sty, epsdice.cfg, dice.eps, dice.pdf
101 \end{verbatim}
102 e.g.\ to a new subdirectory
103 \verb+/tex/latex/epsdice/+. Refresh the
104 \TeX-system's file name database, and that's it, you're all set!
105 The remainder of this section applies only if you want to change
106 the default settings.
107
108 The command \verb+\epsdice+ works by including an
109 external file, so this file must be found by \LaTeXe. The package comes with
110 a configuration file \texttt{epsdice.cfg} containing the file name in the
111 variable \verb+\dicefile+. By default, this variable points to the file
112 \verb+dice.{eps|pdf}+ (without file name extension). If you don't like my
113 drawings and would like to ``roll your own'', a look at section~\ref{pscode}
114 may give some hints.
115 It contains the same PostScript code as \texttt{dice.eps},
116 with some comments about what's going on. Conversion to \textsc{pdf}
117 format has been accomplished with \texttt{epstopdf} (using
118 GhostScript), see pdf\TeX's web page.
119
120 If you intend to keep the external file with the dice drawings in a
121 different place or if you want to use your own version you have to
122 edit the configuration file \texttt{epsdice.cfg} accordingly,
123 by adding the path to the file name, or by changing the file name in the
124 variable \verb+\dicefile+.
125 If a configuration file does not exist, the external file
126 is assumed to be located in the present working directory.
127 %
128 \section{Examples}
129 Die faces in an 11pt environment: The pictures fit into the surrounding
130 text, as in \epsdice{1} \epsdice[black]{2} \epsdice[black]{3}
131 \epsdice[red]{4} \epsdice[black]{5} \epsdice[white]{6}. The code used to set
132 these die faces was:
133 \begin{verbatim}
134 \epsdice{1} \epsdice[black]{2} \epsdice[black]{3}
135 \epsdice[red]{4} \epsdice[black]{5} \epsdice[white]{6}
136 \end{verbatim}
137 The only effective option to the command \verb+\epsdice+ is \verb+[black]+.
138 Anything else results in the default behavior with white background.
139
140 \medskip
141 {\Large
142 Here is some \verb+\Large+ text. The die pictures scale accordingly:%
143 \footnote{\ldots as they do in footnotes, \epsdice{\value{footnote}},
144 like this.} \epsdice{3} \epsdice[black]{5}. See?}
145
146 \medskip
147 Finally, note that the package works with
148 standard counters, too: Here's the result of \verb+\epsdice{\value{section}}+
149 \epsdice{\value{section}}.
150 %
151 \section{Drawing dice in PostScript}
152 \label{pscode}
153 Something as simple as a ``square with dots
154 on it'' is rather straightforward to draw in PostScript. The first line
155 \begin{flushleft}
156 \verb+%!PS-Adobe-2.0 EPSF-1.2+
157 \end{flushleft}
158 is just a standard header. Next comes the bounding box: Each face measures
159 $32\times 32$~pt, centered in a $43\times43$~pt box. For six faces in a row,
160 this gives a bounding box of $258\times43$~pt. We have two rows of dice,
161 the lower row containing the white dice with black dots, the upper one the
162 black dice with white dots. So the total bounding box is $258\times86$~pt.
163 The background color will be stored in the variable $bw=0$ or 1.
164 \begin{verbatim}
165 %%BoundingBox: 0 0 258 86
166 \end{verbatim}
167 The \verb+/frame+ macro defines a simple box with rounded corners. It takes
168 one argument, the face index $n$, and calculates a corresponding $x$-offset:
169 $x_{\mathrm{off}}=43 (n-1)$. The point $(x_{\mathrm{off}},y_{\mathrm{off}})$
170 then becomes the origin of the coordinate system for this particular face.
171 This macro uses the variable $bw$ to calculate the vertical offset
172 $y_{\mathrm{off}}=43 bw$.
173 The frame consists of straight lines separated by 5~pt from the outer margin,
174 and of four quarter circles with radius $r$ ($r=5$~pt for black on white and
175 $r=6$~pt for white on black) centered at $(10,10),\,(32,10),\,(10,32)$, and $(32,32)$.
176 \begin{verbatim}
177 /frame {
178 /n exch def % take n off the stack, store it
179 /xoffset n 1 sub 43 mul def % xoffset = 43*(n-1)
180 gsave % save the graphics state
181 newpath % start a new path
182 xoffset yoffset translate % move origin to (xoffset,yoffset)
183 32 5 bw sub moveto % go to (32,5) or (32,4) in this system
184 32 10 r -90 0 arc % SE quarter circle around (32,10)
185 37 bw add 32 lineto % right line
186 32 32 r 0 90 arc % NE quarter circle around (32,32)
187 10 37 bw add lineto % top line
188 10 32 r 90 180 arc % NW quarter circle around (10,32)
189 5 bw add 10 lineto % left line
190 10 10 r 180 270 arc % SW quarter circle around (10,10)
191 closepath % bottom line (closes the path)
192 bw 0 eq { stroke } % either paint (lower row, bw=0)
193 { fill } ifelse % or fill (upper row, bw=1) the path
194 grestore % restore graphics state
195 } def
196 \end{verbatim}
197 The dot positions are labelled within a face by $(x,y)$-coordinates
198 running from $(1,1)$
199 for bottom left to $(3,3)$ for top right. The dot itself is
200 a filled circle with radius $3.5$~pt. Change the dots' positions
201 within the frame, or their radius, as you like. The \verb+/dot+ macro
202 takes three arguments off the stack: (i) the face index, to determine
203 the $x$-offset, (ii) the $x$-coordinate (1, 2, or 3) on the face, and
204 (iii) the $y$-coordinate (1, 2, or 3) on the face.
205 \begin{verbatim}
206 /dot {
207 /y exch def % take y-coordinate off the stack
208 /x exch def % take x-coordinate off the stack
209 /n exch def % take face index n off the stack
210 /xoffset n 1 sub 43 mul def % xoffset = 43*(n-1)
211 gsave % save the graphics state
212 newpath % start a new path
213 xoffset yoffset translate % move origin to (xoffset,yoffset)
214 x 8 mul 5 add % the dot's x-position: 8*x+5
215 y 8 mul 5 add % the dot's y-position: 8*y+5
216 3.5 0 360 arc % a circle with radius 3.5 pt
217 closepath % close the circle
218 bw setgray % set the appropriate color
219 fill % fill the circle
220 grestore % restore graphics state
221 } def
222 \end{verbatim}
223 Now choose a linewidth (2~pt)
224 \begin{verbatim}
225 2 setlinewidth
226 \end{verbatim}
227 and loop over the background color (and hence the rows) from 0 to 1.
228 The color counter is stored in $bw$ and used
229 to determine $y_{\mathrm{off}}$ as well as the radius of the circles,
230 $r=5+bw$~pt.
231 \begin{verbatim}
232 0 1 1 { % set up loop from 0 to 1
233 /bw exch def % store loop index in bw
234 /yoffset bw 43 mul def % yoffset = 43*bw
235 /r 5 bw add def % radius r = 5+bw
236 0 setgray % set color to black for all frames
237 \end{verbatim}
238 All we have to do now is draw the six faces
239 \begin{verbatim}
240 1 1 6 { frame } for % call /frame macro for n=1..6
241 \end{verbatim}
242 and fill in the appropriate dots.
243 The bottom left and top right dots appear on faces 2, 3, 4, 5, and 6.
244 Thus there is an outer loop from 2 to 6 in steps of 1. For each of these
245 face indices, we call the dot macro with $(x,y)$-argument equal to
246 $(1,1)$ and $(3,3)$. This can be achieved with an inner loop running
247 from 1 to 3 in steps of 2. Because the $x$- and $y$-coordinates coincide
248 for these particular points, we obtain them by duplicating the inner
249 loop index. The \verb+/dot+ macro gobbles not only the $x$- and
250 $y$-coordinates but the face index as well. In order to draw \emph{two}
251 dots on the same face, we thus have to duplicate the outer loop index, too.
252 \begin{verbatim}
253 2 1 6 { % start loop 2 to 6 in steps of 1
254 dup % duplicate index (two dots on each face)
255 1 2 3 { % start loop 1 to 3 in steps of 2
256 dup % duplicate loop index -> 1 1 and 3 3
257 dot % call /dot macro, using three arguments
258 } for % inner loop (dot positions)
259 } for % outer loop (face index)
260 \end{verbatim}
261 The center dot appears on faces 1, 3, and 5. We get it in a simple loop
262 from 1 to 5 in steps of 2, calling the \verb+/dot+ macro for each index
263 together with the coordinate set $(2,2)$ corresponding to the center.
264 \begin{verbatim}
265 1 2 5 { 2 2 dot } for % (2,2) dot on 1, 3, 5
266 \end{verbatim}
267 The top left and the bottom right dots appear on faces 4, 5, and 6. Again,
268 in order to draw \emph{two} dots on each face, we have to duplicate the
269 loop index, i.e., the face index:
270 \begin{verbatim}
271 4 1 6 { % start loop 4 to 6 in steps of 1
272 dup % duplicate index (two dots on each face)
273 1 3 dot % call /dot macro for (1,3) dot on this face
274 3 1 dot % call /dot macro for (3,1) dot on this face
275 } for % loop over face index
276 \end{verbatim}
277 Finally, on face 6 we have two dots in positions $(1,2)$ and $(3,2)$. We can
278 use a loop, but then we have to swap the loop index, i.e., the dot's
279 $x$-coordinate, with the (constant) face index 6 inside the loop.
280 \begin{verbatim}
281 1 2 3 { % start loop 1 to 3 in steps of 2
282 6 exch % swap loop index and constant face index
283 2 % push constant y-coordinate on stack
284 dot % call /dot macro for (x,2) dot on face 6
285 } for % loop over x-coordinates 1 and 3
286 \end{verbatim}
287 And this closes the loop over background colors:
288 \begin{verbatim}
289 } for % loop over bw 0 and 1
290 \end{verbatim}
291 That's it!
292 \begin{verbatim}
293 %%EOF
294 \end{verbatim}
295 \section{Errors}
296 Of course it doesn't make sense to ask for die faces with arguments
297 other than 1, 2, 3, 4, 5, or 6. The package generates error
298 messages and simply prints the offending argument in the \TeX\ output.
299 %
300 % This generates `benign' errors: \epsdice{99} and \epsdice{-3}.
301 % The following is more serious, generating two different errors:
302 % \epsdice{epsfoo}. Nevertheless, output continues with a fall-back
303 % solution.
304 \end{document}
305 %
306 %</sampledoc>
307 %
308 %<*package>
309 %
310 % I don't think the package code needs much of an explanation;
311 % it's really very simple\ldots
312 %
313 \NeedsTeXFormat{LaTeX2e}
314 \ProvidesPackage{epsdice}[2007/02/15 by Thomas Heim (v. 2.1)]
315 \RequirePackage{graphicx}
316 \RequirePackage{ifthen}
317 \InputIfFileExists{epsdice.cfg}{}{\def\dicefile{dice}}
318 %
319 \newcounter{eps@face}
320 \newcommand*\epsdice[2][white]{%
321 \setcounter{eps@face}{\number #2}%
322 \ifthenelse{\value{eps@face}>6}{\theeps@face\setcounter{eps@face}{0}}{}%
323 \ifthenelse{\value{eps@face}<0}{\theeps@face\setcounter{eps@face}{0}}{}%
324 \ifthenelse {\equal{#1}{black}} {\addtocounter{eps@face}{6}} {}%
325 \eps@dice{\value{eps@face}}}
326 \newcommand*\eps@dice[1]{%
327 \setcounter{eps@face}{\number #1}%
328 \ifcase\value{eps@face}%
329 \PackageError{EPSDICE}{%
330 Argument is not a number, or its value\MessageBreak
331 lies outside the allowed range for dice}{%
332 Make sure the argument is either 1, 2, 3, 4, 5, or 6.\MessageBreak
333 -- Just go on and I'll write whatever you typed;\MessageBreak
334 the output may not make much sense, though}%
335 \or
336 \includegraphics[height=1.75ex,viewport= 3 4 38 39,%
337 clip=true]{\dicefile}%
338 \or
339 \includegraphics[height=1.75ex,viewport= 46 4 81 39,%
340 clip=true]{\dicefile}%
341 \or
342 \includegraphics[height=1.75ex,viewport= 89 4 124 39,%
343 clip=true]{\dicefile}%
344 \or
345 \includegraphics[height=1.75ex,viewport= 132 4 167 39,%
346 clip=true]{\dicefile}%
347 \or
348 \includegraphics[height=1.75ex,viewport= 175 4 210 39,%
349 clip=true]{\dicefile}%
350 \or
351 \includegraphics[height=1.75ex,viewport= 218 4 253 39,%
352 clip=true]{\dicefile}%
353 \or
354 \includegraphics[height=1.75ex,viewport= 3 47 38 82,%
355 clip=true]{\dicefile}%
356 \or
357 \includegraphics[height=1.75ex,viewport= 46 47 81 82,%
358 clip=true]{\dicefile}%
359 \or
360 \includegraphics[height=1.75ex,viewport= 89 47 124 82,%
361 clip=true]{\dicefile}%
362 \or
363 \includegraphics[height=1.75ex,viewport= 132 47 167 82,%
364 clip=true]{\dicefile}%
365 \or
366 \includegraphics[height=1.75ex,viewport= 175 47 210 82,%
367 clip=true]{\dicefile}%
368 \or
369 \includegraphics[height=1.75ex,viewport= 218 47 253 82,%
370 clip=true]{\dicefile}%
371 \fi}
372 %
373 %</package>
374 %
375 %<config>\def\dicefile{dice}
376 %
377 %<*epsfile>
378 %
379 % Here's the PostScript code for the drawings:
380 %
381 %<<PSFILE
382 %!PS-Adobe-2.0 EPSF-1.2
383 %%BoundingBox: 0 0 258 86
384 /frame { /n exch def /xoffset n 1 sub 43 mul def gsave newpath
385 xoffset yoffset translate 32 5 bw sub moveto 32 10 r -90 0 arc
386 37 bw add 32 lineto 32 32 r 0 90 arc 10 37 bw add lineto
387 10 32 r 90 180 arc 5 bw sub 10 lineto 10 10 r 180 270 arc closepath
388 bw 0 eq { stroke } { fill } ifelse grestore } def
389 /dot { /y exch def /x exch def /n exch def /xoffset n 1 sub 43
390 mul def gsave newpath xoffset yoffset translate x 8 mul 5 add y 8 mul
391 5 add 3.5 0 360 arc closepath bw setgray fill grestore } def
392 2 setlinewidth 0 1 1 { /bw exch def /yoffset bw 43 mul def /r 5 bw
393 add def 0 setgray 1 1 6 { frame } for 2 1 6 { dup 1 2 3 { dup dot }
394 for } for 1 2 5 { 2 2 dot } for 4 1 6 { dup 1 3 dot 3 1 dot } for
395 1 2 3 { 6 exch 2 dot } for } for
396 %%EOF
397 %PSFILE
398 %
399 %</epsfile>
400 \endinput
401
402