Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 1997-... by Rolf Niepraschk <[email protected]>
4 % ---------------------------------------------------------------------------
5 % This work may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either version 1.3
7 % of this license or (at your option) any later version.
8 % The latest version of this license is in
9 % http://www.latex-project.org/lppl.txt
10 % and version 1.3 or later is part of all distributions of LaTeX
11 % version 2005/12/01 or later.
12 %
13 % This work has the LPPL maintenance status `maintained'.
14 %
15 % The Current Maintainer of this work is Rolf Niepraschk.
16 %
17 % This work consists of the files overpic.dtx and overpic.ins
18 % and the derived filebase overpic.sty.
19 %
20 %<*package>
21 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
22 \ProvidesPackage{overpic}[2026/01/06 2.2 picture overlays (RN)]
23 %</package>
24 %
25 %<*driver>
26 \ProvidesFile{overpic.dtx}
27 \documentclass{ltxdoc}
28 \usepackage{overpic,pict2e,xcolor}
29 \usepackage{lmodern}
30 \usepackage{listings}
31 \setlength\parindent{0pt}
32 \newlength\myparskip
33 \setlength\myparskip{.6em plus 0.1em minus 0.1em}
34 \setlength\parskip{\myparskip}
35 \lstset{%
36 language=[AlLaTeX]TeX,
37 gobble=2,
38 keywordstyle=\bfseries,
39 commentstyle=\small\ttfamily,
40 basicstyle=\small\ttfamily,
41 basewidth=0.55em,
42 backgroundcolor=\color{black!10},
43 keepspaces,
44 numbers=none,
45 aboveskip=\myparskip,
46 belowskip=\myparskip,
47 framesep=\fboxsep,
48 frame=single
49 }
50 \EnableCrossrefs
51 \CodelineIndex
52 \RecordChanges
53 \begin{document}
54 \DocInput{overpic.dtx}
55 \PrintChanges
56 \PrintIndex
57 \end{document}
58 %</driver>
59 % \fi
60 %
61 % \CheckSum{210}
62 %
63 % \CharacterTable
64 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
65 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
66 % Digits \0\1\2\3\4\5\6\7\8\9
67 % Exclamation \! Double quote \" Hash (number) \#
68 % Dollar \$ Percent \% Ampersand \&
69 % Acute accent \' Left paren \( Right paren \)
70 % Asterisk \* Plus \+ Comma \,
71 % Minus \- Point \. Solidus \/
72 % Colon \: Semicolon \; Less than \<
73 % Equals \= Greater than \> Question mark \?
74 % Commercial at \@ Left bracket \[ Backslash \\
75 % Right bracket \] Circumflex \^ Underscore \_
76 % Grave accent \` Left brace \{ Vertical bar \|
77 % Right brace \} Tilde \~}
78 %
79 %
80 % \changes{0.60}{2014/06/16}{Converted to .dtx}
81 % \changes{1.0}{2017/10/06}{mostly rewritten}
82 %
83 % \DoNotIndex{\newcommand,\renewcommand,\newenvironment,\renewenvironment}
84 % \DoNotIndex{\providecommand,\def,\edef,\let,\gdef,\xdef,\global,\newtoks}
85 % \DoNotIndex{\usebox,\sbox,\relax,\@viipt,\@viiipt,\count@,\dimexpr,\newif}
86 % \DoNotIndex{\RequirePackage,\DeclareOption,\ProcessOptions,\ExecuteOptions}
87 % \DoNotIndex{\PassOptionsToPackage,\endinput,\lowercase}
88 % \DoNotIndex{\input,\InputIfFileExists}
89 % \DoNotIndex{\@ifdefinable,\@ifundefined,\@percentchar}
90 % \DoNotIndex{\AtBeginDocument,\AtEndOfPackage}
91 % \DoNotIndex{\PackageError,\PackageWarning,\PackageWarningNoLine,\PackageInfo}
92 % \DoNotIndex{\MessageBreak,\typeout}
93 % \DoNotIndex{\z@,\z@skip,\p@,\@ne,\tw@,\thr@@,\@iv,\@m,\strip@pt}
94 % \DoNotIndex{\the,\if,\else,\or,\fi,\ifnum,\ifdim,\ifcase,\ifodd}
95 % \DoNotIndex{\advance,\multiply,\divide}
96 % \DoNotIndex{\@tfor,\do,\@ehc,\@tempcnta,\@tempcntb}
97 % \DoNotIndex{\csname,\endcsname,\begingroup,\endgroup}
98 % \DoNotIndex{\expandafter,\afterassignment,\noexpand}
99 %
100 % \providecommand*{\url}{\texttt}
101 % \GetFileInfo{overpic.sty}
102 % \title{The \textsf{overpic} package}
103 % \author{Rolf Niepraschk \\ (\url{[email protected])}}
104 % \date{Version~\fileversion~--~\filedate}
105 %
106 % \maketitle
107 %
108 % \section{Introduction}
109 %
110 % The overpic environment is a combination between the \LaTeX\ picture
111 % environment and another \LaTeX\ object like an image used with the
112 % command \cmd{\includegraphics} of graphicx or a tabular. The
113 % resulting picture environment has the same dimensions as the included
114 % object. \LaTeX\ commands can be placed on the object at any position;
115 % setting a grid for the orientation is possible.
116 %
117 % \section{Usage}
118 %
119 % Put |\usepackage[|\meta{options}|]{overpic}| in the preamble of the document.
120 % The following package options are available:
121 % \begin{itemize}
122 % \item |abs|: Absolute positioning in multiples of \cmd{\unitlength}.
123 % \item |percent|: Relative positioning; the longer dimension has
124 % value 100. The \cmd{\unitlength} will be calculated accordingly. This
125 % is the default mode.
126 % \item |permil|: Relative positioning; the longer dimension has
127 % value 1000. The \cmd{\unitlength} will be calculated accordingly.
128 % \end{itemize}
129 % Other options will be tranfered to package |graphicx|.
130 %
131 % \DescribeEnv{overpic}
132 % |\begin{overpic}[|\meta{options}|]{|\meta{filename}|}| \meta{picture code}
133 % |\end{overpic}| \par
134 % Sets the graphic \meta{filename} and puts the \meta{picture code} on the
135 % top of the graphic. The picture code can be any \TeX\ code inclusive other
136 % graphics.
137 %
138 % The following options are possible:
139 % \begin{itemize}
140 % \item |abs|, |percent|, |permil|: The same as the package
141 % options (true or false).
142 % \item |rel|: Other value as base for relative positioning
143 % (e.g. 10000)
144 % \item |grid|: Drawing a grid for better orientation (true or false,
145 % default: false).
146 % \item |tics|: The distance of the grid tics (default: 10).
147 % \item |unit|: Sets \cmd{\unitlength} (any \TeX\ dimension, only
148 % effective in abs mode).
149 % \end{itemize}
150 % The macros \cmd\width, \cmd\height, \cmd\depth, and \cmd\totalheight\ are
151 % defined within the environment. They contain the dimensions of the graphic
152 % (parameter 2).
153 %
154 % \DescribeEnv{Overpic}
155 % |\begin{Overpic}[|\meta{options}|]{|\meta{\TeX\ code}|}|
156 % \meta{picture code} |\end{Overpic}| \par
157 % Similar to environment |overpic| but instead of a graphic any
158 % \TeX\ code (e.g. a tabular) is set as basement of the following picture
159 % overlay. The macros \cmd\width, \cmd\height, \cmd\depth, and
160 % \cmd\totalheight\ are defined within the environment. They contain the
161 % dimensions of the box created by the \TeX\ code (parameter 2).
162 %
163 % \DescribeMacro\setOverpic
164 % \cmd{\setOverpic}|{|\meta{options}|}| \par
165 % Sets new default values.
166 %
167 % \section{Examples}
168 %
169 % The graphic (\texttt{golfer.eps}) in the following examples is
170 % part of the program \texttt{ghostscript} and must be accesible to \TeX{}.
171 % To use the command \cmd{\color} the package |xcolor| (or |color|) must
172 % be loaded.
173 %
174 % \subsection{Environment ``overpic'' (absolute positioning)}
175 %
176 % \begin{lstlisting}
177 % \begin{overpic}[abs,unit=1mm,scale=.25,grid]{golfer.eps}
178 % \put(3,27){\color{blue}\huge\LaTeX}
179 % \end{overpic}
180 % \end{lstlisting}
181 % \par\medskip\pagebreak[3]
182 % \begin{overpic}[abs,unit=1mm,scale=.25,grid]{golfer.eps}
183 % \put(3,27){\color{blue}\huge\LaTeX}
184 % \end{overpic}
185 %
186 % \subsection{Environment ``overpic'' (relative positioning)}
187 %
188 % The longer dimension is defined as 100\%. \pagebreak[3]
189 %
190 % \begin{lstlisting}
191 % \begin{overpic}[scale=.25,percent,grid]{golfer.eps}
192 % \put(5,45){\color{blue}\huge\LaTeX}
193 % \put(55,10){\color{red}%
194 % \frame{\includegraphics[scale=.07]{golfer.eps}}}
195 % \end{overpic}
196 % \end{lstlisting}
197 % \par\medskip\pagebreak[3]
198 % \begin{overpic}[scale=.25,percent,grid]{golfer.eps}
199 % \put(5,45){\color{blue}\huge\LaTeX}
200 % \put(56,10){\color{red}%
201 % \frame{\includegraphics[scale=.07]{golfer.eps}}}
202 % \end{overpic}
203 %
204 % \subsection{Environment ``Overpic'' (absolute positioning)}
205 %
206 % To use the picture command \cmd{\polygon} the package |pict2e| must
207 % be loaded.
208 %
209 % \begin{lstlisting}
210 % \begin{Overpic}[abs,unit=1mm,grid=true,tics=5]{%
211 % \bfseries\sffamily
212 % \begin{tabular}{*{8}{p{8mm}}}
213 % H & & & & & & & He\\
214 % Li & Be & B & C & N & O & F & Ne\\
215 % Na & Mg & Al & Si & P & S & Cl & Ar\\
216 % K & Ca & Ga & Ge & As & Se & Br & Kr\\
217 % Rb & Sr & In & Sn & Sb & Te & I & Xe\\
218 % Cs & Ba & Tl & Pb & Bi & Po & At & Rn\\
219 % Fr & Ra & 112& & 114& & &\\
220 % \end{tabular}}%
221 % \put(0,0){\color{blue}\linethickness{0.5mm}
222 % \polygon(0,30)(10,30)(10,21.5)(45,21.5)(45,13)(22,13)%
223 % (22,4.5)(0,4.5)}
224 % \end{Overpic}
225 % \end{lstlisting}
226 % \par\medskip\pagebreak[3]
227 % \begin{Overpic}[abs,unit=1mm,grid=true,tics=5]{%
228 % \bfseries\sffamily
229 % \begin{tabular}{*{8}{p{8mm}}}
230 % H & & & & & & & He\\
231 % Li & Be & B & C & N & O & F & Ne\\
232 % Na & Mg & Al & Si & P & S & Cl & Ar\\
233 % K & Ca & Ga & Ge & As & Se & Br & Kr\\
234 % Rb & Sr & In & Sn & Sb & Te & I & Xe\\
235 % Cs & Ba & Tl & Pb & Bi & Po & At & Rn\\
236 % Fr & Ra & 112& & 114& & &\\
237 % \end{tabular}}%
238 % \put(0,0){\color{blue}\linethickness{0.5mm}
239 % \polygon(0,30)(10,30)(10,21.5)(45,21.5)(45,13)(22,13)%
240 % (22,4.5)(0,4.5)}
241 % \end{Overpic}
242 %
243 % \StopEventually{}
244 %
245 % \section{Implementation}
246 %
247 % \iffalse
248 %<*package>
249 % \fi
250 % \begin{macrocode}
251 \RequirePackage{keyval,graphicx,epic}
252 % \end{macrocode}
253 %
254 % \begin{macro}{\OVP@scale}
255 % Reference value for rel mode (percent: 100, permil: 1000)
256 % \begin{macrocode}
257 \newcommand*\OVP@scale{\z@}
258 % \end{macrocode}
259 % \end{macro}
260 % All the keys:
261 % \begin{macrocode}
262 \define@key{OVP}{rel}{%
263 \def\OVP@scale{#1}%
264 \ifnum\OVP@scale>\z@
265 \let\OVP@calc\OVP@calc@rel
266 \else
267 \PackageError{overpic}{Invalid number for option `rel'}\@ehc
268 \fi
269 }
270 \define@key{OVP}{percent}[]{%
271 \setkeys{OVP}{rel=100}%
272 }
273 \define@key{OVP}{permil}[]{%
274 \setkeys{OVP}{rel=\@m}%
275 }
276 \define@key{OVP}{abs}[]{%
277 \let\OVP@calc\OVP@calc@abs
278 }
279 \def\OVP@boolkey#1#2{%
280 \csname OVP@#2\ifx\relax#1\relax true\else#1\fi\endcsname}
281 \newif\ifOVP@grid
282 \define@key{OVP}{grid}[true]{\lowercase{\OVP@boolkey{#1}}{grid}}
283 \define@key{OVP}{tics}{\count@=#1}
284 \define@key{OVP}{unit}{\unitlength=\dimexpr#1\relax}
285 % \end{macrocode}
286 % \begin{macro}{\OVP@calc@abs}
287 % Some calculations in abs mode. \cmd{\@tempcnta} is the normalized width
288 % and \cmd{\@tempcntb} is the normalized height. \cmd{\count@} is the
289 % tics value.
290 % \begin{macrocode}
291 \newcommand*\OVP@calc@abs{%
292 \divide\@tempcnta by \unitlength
293 \divide\@tempcntb by \unitlength
294 \ifnum\count@=\z@\count@=10\fi
295 }
296 % \end{macrocode}
297 % \end{macro}
298 % \changes{2.0}{2024/01/04}{Use a separate namespace for the keys to avoid
299 % unfavorable influence on \cmd\includegraphics.}
300 % \begin{macro}{\OVP@calc@rel}
301 % Some calculations in rel mode. The bigger value of width or height
302 % is the base.
303 % \changes{1.0}{2017/10/06}{Suggested by \mbox{Heiko Oberdiek}}
304 % \begin{macrocode}
305 \newcommand*\OVP@calc@rel{%
306 \ifnum\@tempcnta>\@tempcntb
307 \divide\@tempcnta by \OVP@scale
308 \unitlength=\@tempcnta sp %
309 \@tempcnta=\OVP@scale
310 \divide\@tempcntb by \unitlength
311 \else
312 \divide\@tempcntb by \OVP@scale
313 \unitlength=\@tempcntb sp %
314 \@tempcntb=\OVP@scale
315 \divide\@tempcnta by \unitlength
316 \fi
317 \ifnum\count@=\z@
318 \count@=\OVP@scale
319 \divide\count@ by 10 %
320 \fi
321 }
322 % \end{macrocode}
323 % \end{macro}
324 % The package options set the defaults:
325 % \begin{macrocode}
326 \DeclareOption{percent}{\setkeys{OVP}{rel=100}}
327 \DeclareOption{permil}{\setkeys{OVP}{rel=\@m}}
328 \DeclareOption{abs}{\setkeys{OVP}{abs}}
329 \DeclareOption*{\PassOptionsToPackage{\CurrentOption}{graphicx}}
330 \ExecuteOptions{percent}
331 \ProcessOptions
332 \AtBeginDocument{%
333 \@ifpackageloaded{xkeyval}{%
334 \def\OVP@setkeys@relaxed{%
335 \let\OVP@setkeys\setkeys
336 \def\setkeys{\OVP@setkeys*}
337 }
338 \def\OVP@setkeys@strict{%
339 \let\setkeys\OVP@setkeys
340 }
341 }{%
342 \def\OVP@setkeys@relaxed{%
343 \let\OVP@KV@errx\KV@errx
344 \let\KV@errx\@gobble
345 }
346 \def\OVP@setkeys@strict{%
347 \let\KV@errx\OVP@KV@errx
348 }
349 }
350 }
351 \newsavebox\OVP@box
352 \newdimen\OVP@totalheight
353 % \end{macrocode}
354 %
355 % \begin{environment}{overpic}
356 % Box \cmd{\OVP@box} gets a graphic.
357 % \changes{1.2}{2018/09/02}{Wrong place of \cmd\setkeys
358 % (bug report from 'aminophen')}
359 % \changes{2.0}{2024/01/04}{Better key handling}
360 % \changes{2.1}{2024/01/06}{Consideration of xkeyval's \cmd\setkeys}
361 % \begin{macrocode}
362 \newenvironment{overpic}[2][]{%
363 % \end{macrocode}
364 % Silently ignore unknown keys.
365 % \begin{macrocode}
366 \OVP@setkeys@relaxed
367 \sbox\OVP@box{\includegraphics[#1]{#2}}%
368 \count@=\z@ \OVP@gridfalse
369 \setkeys{OVP}{#1}%
370 % \end{macrocode}
371 % Stop ignoring unknown keys.
372 % \begin{macrocode}
373 \OVP@setkeys@strict
374 \OVP@picture
375 }{\endpicture}
376 % \end{macrocode}
377 % \end{environment}
378 % \begin{environment}{Overpic}
379 % \changes{1.0}{2017/10/06}{Suggested by \mbox{Herbert Vo\ss}}
380 % \changes{1.3}{2020/02/22}{Added missing \cmd\setkeys}
381 % Box \cmd{\OVP@box} gets any \TeX\ code.
382 % \begin{macrocode}
383 \newenvironment{Overpic}[2][]{%
384 \sbox\OVP@box{#2}%
385 \count@=\z@ \OVP@gridfalse
386 \setkeys{OVP}{#1}%
387 \OVP@picture
388 }{\endpicture}
389 % \end{macrocode}
390 % \end{environment}
391 % \begin{macro}{\OVP@picture}
392 % \changes{2.2}{2026/01/06}{Added \cmd\width\ and similar macros}
393 % Put box \cmd{\OVP@box} and a optionally grid at the lower left corner of a
394 % picture environment.
395 % \begin{macrocode}
396 \newcommand*\OVP@picture{%
397 \def\width{\wd\OVP@box}%
398 \def\height{\ht\OVP@box}%
399 \def\depth{\dp\OVP@box}%
400 \let\totalheight\OVP@totalheight
401 \totalheight=\height
402 \advance\totalheight\depth
403 \@tempcnta=\width
404 \@tempcntb=\totalheight
405 \OVP@calc
406 \picture(\@tempcnta,\@tempcntb)%
407 \put(0,0){\makebox(0,0)[bl]{\usebox\OVP@box}}%
408 \ifOVP@grid
409 \put(0,0){\normalfont\fontsize\@viipt\@viiipt\selectfont
410 \grid(\@tempcnta,\@tempcntb)(\count@,\count@)[0,0]}%
411 \fi
412 }
413 % \end{macrocode}
414 % \end{macro}
415 % \begin{macro}{\setOverpic}
416 % Sets new defaults.
417 % \begin{macrocode}
418 \newcommand*\setOverpic[1]{%
419 \setkeys{OVP}{#1}%
420 }
421 % \end{macrocode}
422 % \end{macro}
423 % \begin{macrocode}
424 \endinput
425 % \end{macrocode}
426 %
427 % \iffalse
428 %</package>
429 % \fi
430 %
431 % \Finale
432 \endinput