Debian Codegraph @

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

raw
1 %
2 % \iffalse meta-comment
3 %
4 % graphbox.dtx Copyright (C) 2013-2025 Niklas Beisert
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % https://www.latex-project.org/lppl.txt
11 % and version 1.3c or later is part of all distributions of LaTeX
12 % version 2008 or later.
13 %
14 % This work has the LPPL maintenance status `maintained'.
15 %
16 % The Current Maintainer of this work is Niklas Beisert.
17 %
18 % This work consists of the files graphbox.dtx and graphbox.ins
19 % and the derived files graphbox.sty, gboxsamp.tex and gboxsamp.mps.
20 %
21 %<package|sample>\NeedsTeXFormat{LaTeX2e}[1996/12/01]
22 %<package>\ProvidesPackage{graphbox}[2025/03/25 v1.1.1 extension for graphicx to adjust containing box]
23 %<sample>\ProvidesFile{gboxsamp.tex}[2025/03/25 v1.1.1 sample for graphbox]
24 %<figure>%!PS-Adobe-3.0 EPSF-3.0
25 %<*driver>
26 \def\thedate#1{2025/03/25}\def\theversion#1{v1.1.1}
27 \ProvidesFile{graphbox.dtx}[\thedate{} \theversion{} graphbox reference manual file]
28 \PassOptionsToClass{10pt,a4paper}{article}
29 \documentclass{ltxdoc}
30
31 \usepackage[margin=35mm]{geometry}
32 \usepackage[hyperindex=false]{hyperref}
33 \usepackage{hyperxmp}
34 \usepackage[usenames]{color}
35
36 \AddToHook{begindocument/before}{\hypersetup{colorlinks=false}}
37 \hypersetup{urlbordercolor={.5 1 1}}
38 \hypersetup{linkbordercolor={1 .7 .7}}
39 \AddToHook{begindocument/before}{\hypersetup{pdfstartview=FitH}}
40 \hypersetup{keeppdfinfo=true}
41 \hypersetup{pdfsource={}}
42 \hypersetup{pdflang={en-UK}}
43 \hypersetup{pdfurl={https://ctan.org/pkg/graphbox}}
44 \hypersetup{pdfcopyright={Copyright 2013-2025 Niklas Beisert.
45 This work may be distributed and/or modified under the
46 conditions of the LaTeX Project Public License, either version 1.3
47 of this license or (at your option) any later version.}}
48 \hypersetup{pdflicenseurl={https://www.latex-project.org/lppl.txt}}
49 \hypersetup{pdfcontactaddress={ETH Zurich, ITP, HIT K,
50 Wolfgang-Pauli-Strasse 27}}
51 \hypersetup{pdfcontactpostcode={8093}}
52 \hypersetup{pdfcontactcity={Zurich}}
53 \hypersetup{pdfcontactcountry={Switzerland}}
54 \hypersetup{pdfcontactemail={[email protected]}}
55 \hypersetup{pdfcontacturl={https://people.phys.ethz.ch/\xmptilde nbeisert/}}
56
57 \newcommand{\markpkg}[1]{\textsf{#1}}
58 \newcommand{\secref}[1]{\hyperref[#1]{section \ref*{#1}}}
59 \newcommand{\ctanref}[2]{\href{https://ctan.org/#1}{#2}}
60 \newcommand{\ctanpkg}[1]{\ctanref{pkg/#1}{\markpkg{#1}}}
61
62 \def\textvert{\texttt{\char"7C}}
63
64 \parskip1ex
65 \parindent0pt
66 \let\olditemize\itemize
67 \def\itemize{\olditemize\parskip0pt}
68
69 \begin{document}
70
71 \title{The \markpkg{graphbox} Package}
72 \hypersetup{pdftitle={The graphbox Package}}
73 \author{Niklas Beisert\\[2ex]
74 Institut f\"ur Theoretische Physik\\
75 Eidgen\"ossische Technische Hochschule Z\"urich\\
76 Wolfgang-Pauli-Strasse 27, 8093 Z\"urich, Switzerland\\[1ex]
77 \href{mailto:[email protected]}
78 {\texttt{[email protected]}}}
79 \hypersetup{pdfauthor={Niklas Beisert}}
80 \hypersetup{pdfsubject={Manual for the LaTeX2e Package graphbox}}
81 \date{\thedate{}, \theversion{}\\[1ex]
82 \url{https://ctan.org/pkg/graphbox}}
83 \maketitle
84
85 \begin{abstract}\noindent
86 \markpkg{graphbox} is an extension for the \LaTeXe{} package
87 \markpkg{graphicx} to facilitate the placement of graphics
88 relative to the current position
89 using additional optional arguments |[...]|
90 of |\includegraphics|.
91 For example, changing the vertical alignment is convenient
92 for using graphics as elements of (mathematical) formulae.
93 Options for shifting, smashing and hiding the graphics
94 are mainly intended for designing presentations using,
95 e.g., the \markpkg{beamer} framework.
96 \end{abstract}
97
98 \begingroup
99 \parskip0ex
100 \tableofcontents
101 \endgroup
102
103 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
104 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
105
106 \newcommand{\drawbox}[1]{%
107 \setlength{\unitlength}{#1}%
108 \begin{picture}(1, 1)%
109 \put(0,0){\line(1,1){1}}%
110 \put(1,0){\line(-1,1){1}}%
111 \end{picture}%
112 }
113 \newcommand{\hidebox}[1]{%
114 \setlength{\unitlength}{#1}%
115 \begin{picture}(1, 1)%
116 \end{picture}%
117 }
118
119 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
120 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
121 \section{Introduction}
122
123 Changing the placement of graphics using |\includegraphics|
124 of the \ctanpkg{graphicx} package is tedious.
125 The command allows to scale and even rotate a figure
126 by the optional arguments |[...]| of |\includegraphics|, namely |scale|
127 (|xscale|, |yscale|) and |rotate|.
128 However, it lacks options to change the vertical alignment,
129 shift the graphics or modify the containing {\TeX} box.
130 In order to position the graphics according to one's needs,
131 one would normally use the standard boxing tools of {\LaTeX} such as
132 |\makebox|,
133 |\parbox|,
134 |\raisebox|
135 or the
136 |minipage| and |picture| environments.
137 %
138 While practically anything can be achieved by a combination of these tools,
139 it has several disadvantages:
140 %
141 \begin{itemize}
142 \item
143 use of complex commands for standard situations;
144 \item
145 several boxing commands need to be combined to achieve the desired effect;
146 leads to several levels of nesting around the actual |\includegraphics| command;
147 \item
148 readability of the {\LaTeX} construction is low (what is going on?);
149 \item
150 adjusting the placement is tedious;
151 \item
152 the higher-level boxing commands of {\LaTeX} require to specify the box width;
153 however, the actual dimensions of the graphics are typically not known
154 (or they change as the graphics is modified);
155 furthermore the same number needs to be used in several places;
156 \item
157 guessing the width of the required boxes may lead to extra space
158 around the graphics or warning messages about an overfull box;
159 \item
160 \ldots
161 \end{itemize}
162 %
163 Therefore it would be desirable to specify the placement
164 along with other options in the |[...]| argument
165 of |\includegraphics|.
166 This may be helpful in the following situations:
167 %
168 \begin{itemize}
169 \item
170 presentations where several figure
171 need to be placed across the frames
172 without disturbing the flow of the text;
173 similarly, in the composition of posters;
174 \item
175 when graphics are used as elements
176 of (mathematical) formulae
177 one might prefer a central vertical alignment
178 over the default baseline alignment of
179 |\includegraphics|.
180 \end{itemize}
181
182 The following discusses these situations in more detail.
183
184 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
185 \subsection{Vertical Alignment}
186
187 Suppose you want to show graphics files%
188 \footnote{a diagonal cross will serve as the sample figure in this documentation.}
189 of different height next to each other
190 (potentially accompanied by some text).
191 A plain inclusion via |\includegraphics| will produce
192 the output:
193 %
194 \[\drawbox{1cm}\qquad\drawbox{2cm}\qquad\mbox{some text}\]
195 %
196 This is because |\includegraphics| puts the graphics into a box
197 whose baseline is the lower bound of the box:
198 %
199 \[\underline{\qquad\fbox{\drawbox{1cm}}\qquad\fbox{\drawbox{2cm}}\qquad\fbox{\mbox{some text}}\qquad}\]
200 %
201 Instead, a central alignment of the graphics is desirable in many situations:
202 %
203 \[
204 \parbox{1cm}{\drawbox{1cm}}\qquad
205 \parbox{2cm}{\drawbox{2cm}}
206 \qquad\mbox{some text}
207 \]
208 %
209 This can be achieved by code such as:
210 %
211 \begin{verbatim}
212 \parbox{1cm}{\includegraphics[width=1cm]{...}}
213 \qquad
214 \parbox{2cm}{\includegraphics[width=2cm]{...}}
215 \qquad
216 \mbox{some text}
217 \end{verbatim}
218 %
219 However, if the width of the graphics is not as evident
220 (e.g.\ when no width is specified or the graphics is scaled),
221 the resulting output may easily look like:%
222 \footnote{Boxes were added to display the size of the bounding boxes.}
223 %
224 \[
225 \fbox{\parbox{0.8cm}{\makebox[0cm][l]{\drawbox{1cm}}}}
226 \qquad
227 \fbox{\parbox{3cm}{\centering\drawbox{2cm}}}
228 \qquad\mbox{some text}
229 \]
230 %
231 The present extension \markpkg{graphbox} adds the option |align| to
232 |\includegraphics| to simplify the declaration:
233 \begin{verbatim}
234 \includegraphics[align=c,width=1cm]{...}
235 \qquad
236 \includegraphics[align=c,width=2cm]{...}
237 \qquad
238 \mbox{some text}
239 \end{verbatim}
240 %
241
242
243 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
244 \subsection{Graphics Placement}
245
246 A related issue is the fine-tuning of graphics placement:
247 In {\LaTeX} this can be achieved by the commands
248 |\raisebox| (vertically) and |\hspace| (horizontally).
249 Furthermore, one might want to place
250 the graphics into some free space relative to the present position.
251 This is commonly needed in designing presentations or posters,
252 where the flow of the text and the graphics is often fine-tuned.
253 For example, one may ignore the vertical height of the graphics
254 using |\smash|. Or one might place the graphics
255 at the present horizontal position without allocating space by
256 |\makebox[0pt]|, |\llap| or |\rlap|.
257
258 Each of these elementary operations can be handled well,
259 but their combination can become very involved:
260 %
261 \begin{verbatim}
262 \smash{\raisebox{.1cm}{\makebox[0pt][l]{\hspace{1cm}{\includegraphics{...}}}}}
263 \end{verbatim}
264 %
265 For example, this may be used to produce the output:
266 \[
267 \begin{tabular}[b]{cccc}
268 & A & B & C \\\hline
269 D & 1 & 2 & 3 \\
270 E & 4 & 5 & 6 \\
271 F & 7 & 8 & 9
272 \end{tabular}
273 \fbox{\smash{\raisebox{.1cm}{\makebox[0pt][l]{\hspace{1cm}\drawbox{2cm}}}}}
274 \]
275 %
276 Here, the graphics was put next to a table.
277 The small box represents the anchor of the graphics.
278 It occupies no space which allows
279 to centre the table irrespectively of
280 the size of the graphics.
281 Unfortunately, the command is not easily readable.
282 The \markpkg{graphbox} extension abbreviates the declaration
283 and make it much more accessible:
284 %
285 \begin{verbatim}
286 \includegraphics[smash=tr,hshift=1cm,vshift=.1cm]{...}
287 \end{verbatim}
288 %
289
290 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
291 \subsection{Hiding Graphics}\label{sec:hide}
292
293 Sometimes one might wish to hide a graphics while reserving the space
294 it would occupy.%
295 \footnote{In the \ctanpkg{graphicx} package a
296 similar effect achieved by the option |draft|.
297 However, here the graphics are replaced by a box containing the file name.}
298 For example, this feature is needed in
299 presentations where the frames are successively uncovered.
300 In the \ctanpkg{beamer} class the uncovering of frames is
301 conveniently achieved by the command |\pause|.
302 Unfortunately, the effect of |\pause| on graphics
303 is that they are either displayed or taken out of the text flow.
304 This has the effect that the formatting
305 can change drastically when graphics elements are uncovered:
306 %
307 \[
308 \fbox{
309 \mbox{\textcolor[gray]{0.5}{before}}
310 \
311 \mbox{\textcolor[gray]{0.5}{after}}
312 }
313 \quad\longrightarrow\quad
314 \fbox{
315 \mbox{before}\
316 \drawbox{1cm}
317 \mbox{after}\
318 }
319 \]
320 %
321
322
323 The \markpkg{graphbox} extension adds the option |hide|
324 to |\includegraphics| to hide the corresponding
325 graphics while reserving the space it would otherwise occupy:
326 %
327 \[
328 \fbox{\hidebox{1.5cm}}
329 \quad\longleftrightarrow\quad
330 \fbox{\drawbox{1.5cm}}
331 \]
332 %
333 Moreover, in conjunction with the \ctanpkg{beamer} class,
334 the definition of the |\includegraphics| command
335 is altered such that it uses the same amount of
336 space in all visibility modes (specified through the
337 |\pause| mechanism and the |<...>| extension).
338 Visibility is handled by automatically setting the |hide| option:
339 %
340 \[
341 \fbox{
342 \mbox{\textcolor[gray]{0.5}{before}}\
343 \hidebox{1cm}\
344 \mbox{\textcolor[gray]{0.5}{after}}
345 }
346 \quad\longrightarrow\quad
347 \fbox{
348 \mbox{before}\
349 \drawbox{1cm}\
350 \mbox{after}
351 }
352 \]
353
354
355 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
356 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
357 \section{Usage}
358
359 To use \markpkg{graphbox} simply add the command
360 \begin{center}|\usepackage{graphbox}|\end{center}
361 to the preamble of your {\LaTeX} document.
362 If not yet present,
363 the package \ctanpkg{graphicx} will automatically be loaded.
364
365 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
366 \subsection{Extensions}
367
368 The package mainly extends the functionality of
369 the |\includegraphics| command of the \ctanpkg{graphicx} package
370 by allowing several additional optional arguments |[...]| as follows:
371
372 \begin{itemize}
373 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
374 \item
375 |hide|[|=|\textit{bool}]
376
377 hides the graphics (unless \textit{bool}=|false|) but reserves the space
378 it would have occupied.
379
380 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
381 \item
382 |align|[|=|\textit{valign}]
383
384 adjusts the vertical alignment of the graphics where \textit{valign} is one of the following:
385 \begin{itemize}
386 \item[|b|:]
387 baseline aligned to bottom of graphics;\\
388 default behaviour when |align| is not specified;
389 \item[|c|:]
390 centre of current line aligned to centre of graphics;%
391 \footnote{The centre of the line appears to be (18/31)ex above the baseline
392 which is at the centre of a capital letter for the default font.}\\
393 default behaviour when no parameter is given;
394 \item[|t|:]
395 top of current line aligned to top of graphics;%
396 \footnote{The top of the line is defined as (36/31)ex above the baseline
397 which is the height of a capital letter for the default font.}
398 \item[|l|:]
399 baseline aligned to bottom of graphics; same as |b|;
400 \item[|m|:]
401 baseline aligned to centre of graphics;
402 \item[|u|:]
403 baseline aligned to top of graphics.
404 \end{itemize}
405
406 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
407 \item
408 |vsmash|[|=|\textit{vpos}]
409
410 reduces the height of the bounding box to zero
411 (equivalent to |\smash|);
412 places the graphics according to
413 \textit{vpos} which can take the following values:
414 \begin{itemize}
415 \item[|b|:]
416 positions top of graphics below top of current line;
417 \item[|c|:]
418 positions centre of graphics at centre of current line;\\
419 default behaviour when no parameter is given;
420 \item[|t|:]
421 positions bottom of graphics at baseline;
422 \item[|l|:]
423 positions top of graphics at baseline;
424 \item[|m|:]
425 positions centre of graphics at baseline;
426 \item[|u|:]
427 positions bottom of graphics at baseline; same as |t|;
428 \item[|n|:]
429 no vertical smashing.
430 \end{itemize}
431 %
432 Note that the parameter \textit{vpos}
433 has the opposite effect
434 of the parameter \textit{valign} of |align|.
435
436 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
437 \item
438 |hsmash|[|=|\textit{hpos}]
439
440 reduces the width of the bounding box to zero
441 (equivalent to |\makebox[0pt]|);
442 places the graphics according to
443 \textit{hpos} which can take the following values
444 \begin{itemize}
445 \item[|r|:]
446 positions graphics right of current position;
447 \item[|c|:]
448 positions centre of the graphics at current position;
449 default behaviour when no parameter is given;
450 \item[|l|:]
451 positions graphics left of current position;
452 \item[|n|:]
453 no horizontal smashing;
454 default behaviour when |hsmash| is not specified.
455 \end{itemize}
456
457 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
458 \item
459 |smash|[|=|\textit{vpos}\,\textit{hpos}]
460
461 combination of |vsmash=|\textit{vpos} and
462 |hsmash=|\textit{hpos};
463 default behaviour is |cc|.
464
465 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
466 \item
467 |vshift=|\textit{len}
468
469 shifts the graphics up by \textit{len}.
470
471 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
472 \item
473 |hshift=|\textit{len}
474
475 shifts the graphics to the right by \textit{len};
476 has no effect unless |hsmash| is activated.
477
478 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
479 \item
480 |tmargin=|\textit{len}
481
482 adds a top margin of height \textit{len};
483 has no effect when |vsmash| is activated.
484
485 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
486 \item
487 |bmargin=|\textit{len}
488
489 adds a bottom margin of height \textit{len}
490 below the baseline;
491 has no effect when |vsmash| is activated.
492
493 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
494 \item
495 |vmargin=|\textit{len}
496
497 adds a bottom and top margin of height \textit{len};
498 has no effect when |vsmash| is activated.
499
500 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
501 \item
502 |lmargin=|\textit{len}
503
504 adds a left margin of width \textit{len};
505 has no effect when |hsmash| is activated.
506
507 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
508 \item
509 |rmargin=|\textit{len}
510
511 adds a right margin of width \textit{len};
512 has no effect when |hsmash| is activated.
513
514 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
515 \item
516 |hmargin=|\textit{len}
517
518 adds a left and right margin of width \textit{len};
519 has no effect when |hsmash| is activated.
520
521 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
522 \item
523 |margin=|\textit{len}
524
525 adds an overall margin of length \textit{len}
526 around the graphics;
527 has no effect when |smash| is activated.
528
529 \end{itemize}
530 %
531 In specifying lengths in the above arguments,
532 there are two additional dimensions |\gwidth| and |\gheight|
533 representing the actual width and height of the included graphics.
534 For example, one can add a horizontal margin of 10\%
535 of the size of the graphics by specifying |hmargin=0.1\gwidth|.
536
537 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
538 \subsection{Package Options}
539
540 The package provides one option:
541 %
542 \begin{itemize}
543 \item
544 |nobeamer|
545
546 do not override the overlay processing
547 of the \ctanpkg{beamer} class for |\includegraphics|;
548 as usual, graphics will occupy no space when covered.
549 \end{itemize}
550
551
552
553 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
554 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
555 \section{Information}
556
557 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
558 \subsection{Copyright}
559
560 Copyright \copyright{} 2013--2018 Niklas Beisert
561
562 This work may be distributed and/or modified under the
563 conditions of the \LaTeX{} Project Public License, either version 1.3
564 of this license or (at your option) any later version.
565 The latest version of this license is in
566 \url{https://www.latex-project.org/lppl.txt}
567 and version 1.3c or later is part of all distributions of \LaTeX{}
568 version 2008 or later.
569
570 This work has the LPPL maintenance status `maintained'.
571
572 The Current Maintainer of this work is Niklas Beisert.
573
574 This work consists of the files |README.txt|, |graphbox.ins| and |graphbox.dtx|
575 as well as the derived files |graphbox.sty|, |gboxsamp.tex| with |gboxsamp.mps|
576 and |graphbox.pdf|.
577
578 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
579 \subsection{Files and Installation}
580
581 The package consists of the files
582 %
583 \begin{center}
584 \begin{tabular}{ll}
585 |README.txt| & readme file \\
586 |graphbox.ins| & installation file \\
587 |graphbox.dtx| & source file \\
588 |graphbox.sty| & package file \\
589 |gboxsamp.tex| & sample file \\
590 |gboxsamp.mps| & sample figure \\
591 |graphbox.pdf| & manual
592 \end{tabular}
593 \end{center}
594 %
595 The distribution consists of the files
596 |README.txt|, |graphbox.ins| and |graphbox.dtx|.
597 %
598 \begin{itemize}
599 \item
600 Run (pdf)\LaTeX{} on |graphbox.dtx|
601 to compile the manual |graphbox.pdf| (this file).
602 \item
603 Run \LaTeX{} on |graphbox.ins| to create the package |graphbox.sty|
604 and the sample consisting of |gboxsamp.tex| and |gboxsamp.mps|.
605 Copy the file |graphbox.sty| to an appropriate directory of your \LaTeX{}
606 distribution, e.g.\ \textit{texmf-root}|/tex/latex/graphbox|.
607 \end{itemize}
608
609 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
610 \subsection{Interaction with CTAN Packages}
611
612 The \markpkg{graphbox} package extends the
613 package \ctanpkg{graphicx}.
614 It also changes some functionality of the class
615 \ctanpkg{beamer}
616 if present:
617 %
618 \begin{itemize}
619 \item
620 Compatibility with the \ctanpkg{graphicx} package
621 has been tested with
622 v1.0f (1999/02/16) and
623 v1.0g (2014/04/25).
624
625 \item
626 Compatibility with the
627 \ctanpkg{beamer} class
628 has been tested with v3.33 (2013/12/25).
629 The changes of functionality are described
630 in \secref{sec:hide}.
631
632 \end{itemize}
633
634 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
635 \iffalse
636 \subsection{Feature Suggestions}
637
638 \begin{itemize}
639 \item
640 Combine hshift and vshift into one definition. how? which order?
641 \item
642 negative bmargin
643 \item
644 change |\includegraphics| missing file error into a warning?
645 \item
646 similar positioning extensions for |\parbox| and |minipage|
647 (extend vertical placement argument |c|, |t|, |b| to keyval);
648 thanks to David Ploog for suggestion
649 \end{itemize}
650
651 \fi
652
653 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
654 \subsection{Revision History}
655
656 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
657 \iffalse
658 \paragraph{vN.N.N+:} 20YY/MM/NN
659
660 \begin{itemize}
661 \item
662 \ldots
663 \end{itemize}
664 \fi
665
666 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
667 \paragraph{v1.1.1:} 2025/03/25
668
669 \begin{itemize}
670 \item
671 maintenance and manual update
672 \end{itemize}
673
674 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
675 \paragraph{v1.1:} 2018/01/17
676
677 \begin{itemize}
678 \item
679 hooked deeper into |\includegraphics| chain
680 \item
681 manual rearranged
682 \item
683 minor internal changes
684 \end{itemize}
685
686 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
687 \paragraph{v1.0:} 2014/08/31
688
689 \begin{itemize}
690 \item
691 added further placement options
692 \item
693 manual and installation package added
694 \item
695 first version published on CTAN
696 \end{itemize}
697
698 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
699 \paragraph{v0.8:} 2014/08/25
700
701 \begin{itemize}
702 \item
703 basic functionality
704 \end{itemize}
705
706
707 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
708 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
709 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
710 \appendix
711
712 \settowidth\MacroIndent{\rmfamily\scriptsize 000\ }
713
714 \DocInput{graphbox.dtx}
715
716 \end{document}
717 %</driver>
718 % \fi
719 %
720 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
721 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
722 % \section{Sample File}
723 %\iffalse
724 %<*sample>
725 %\fi
726 %
727 % In this section we provide a {\LaTeX} example how to use
728 % some of the \markpkg{graphbox} extensions to \ctanpkg{graphicx}.
729 % Preamble:
730 %
731 % \begin{macrocode}
732 \documentclass[12pt]{article}
733
734 \usepackage[margin=2cm]{geometry}
735 \usepackage{graphicx}
736 \usepackage{graphbox}
737 % \end{macrocode}
738
739 % The macro |\sample{|\textit{options}|}| prints a block demonstrating the flow of text
740 % testing the new |\includegraphics| arguments \textit{options}:
741 %
742 % \fbox{\parbox{0.6\textwidth}
743 % {\textbf{options:} \textit{options}\par\vspace{1ex}
744 % \parbox{0.6\textwidth}
745 % {
746 % XXXXXX\phantom{\fbox{}}XXXXXX\\
747 % XXXXXX\phantom{\fbox{}}XXXXXX\\
748 % XXXXXX\fbox{\drawbox{1cm}}XXXXXX\\
749 % XXXXXX\phantom{\fbox{}}XXXXXX\\
750 % XXXXXX\phantom{\fbox{}}XXXXXX
751 % }}}\par
752 %
753 % The box indicates the resulting bounding box of the
754 % |\includegraphics| command.
755 % It is defined as follows:
756 % \begin{macrocode}
757 \newcommand{\sample}[1]{
758 \textbf{options:} \texttt{#1}\par\vspace{1ex}
759 \parbox{0.6\textwidth}{%
760 XXXXXX\phantom{\fbox{}}XXXXXX\\%
761 XXXXXX\phantom{\fbox{}}XXXXXX\\%
762 XXXXXX\fbox{\includegraphics[#1]{gboxsamp.mps}}XXXXXX\\%
763 XXXXXX\phantom{\fbox{}}XXXXXX\\%
764 XXXXXX\phantom{\fbox{}}XXXXXX%
765 }\vspace{1cm}\par}
766 % \end{macrocode}
767
768 % In the document body we test the various new options for |\includegraphics|:
769 % \begin{macrocode}
770 \begin{document}
771 \sample{}
772 \sample{hide}
773 \sample{hide=true}
774 \sample{hide=false}
775 \newpage
776 \sample{align=b}
777 \sample{align=c}
778 \sample{align=t}
779 \newpage
780 \sample{align=l}
781 \sample{align=m}
782 \sample{align=u}
783 \newpage
784 \sample{vshift=10pt}
785 \sample{vshift=-10pt}
786 \newpage
787 \sample{lmargin=10pt}
788 \sample{rmargin=10pt}
789 \sample{tmargin=10pt}
790 \sample{bmargin=10pt}
791 \newpage
792 \sample{lmargin=-10pt}
793 \sample{rmargin=-10pt}
794 \sample{tmargin=-10pt}
795 \sample{bmargin=-10pt}
796 \newpage
797 \sample{vsmash=b}
798 \sample{vsmash=c}
799 \sample{vsmash=t}
800 \newpage
801 \sample{vsmash=l}
802 \sample{vsmash=m}
803 \sample{vsmash=u}
804 \newpage
805 \sample{hsmash=l}
806 \sample{hsmash=c}
807 \sample{hsmash=r}
808 \newpage
809 \sample{smash=tl}
810 \sample{smash=cc}
811 \sample{smash=br}
812 \newpage
813 \sample{smash,vshift=10pt}
814 \sample{smash,hshift=10pt}
815 \sample{smash,hshift=-10pt,vshift=-10pt}
816 \end{document}
817 % \end{macrocode}
818 %\iffalse
819 %</sample>
820 %\fi
821 %
822 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
823 % \paragraph{Sample Graphics.}
824 %\iffalse
825 %<*figure>
826 %\fi
827 %
828 % The following is a sample Metapost graphics file (|gboxsamp.mps|)
829 % for use in the sample {\LaTeX} file:
830 %
831 % \begin{macrocode}
832 %!PS-Adobe-3.0 EPSF-3.0
833 %%BoundingBox: -21 -21 21 21
834 %%EndComments
835 %%Page: 1 1
836 0 0 0 setrgbcolor 0 1.5 dtransform truncate idtransform setlinewidth pop []
837 0 setdash 1 setlinecap 1 setlinejoin 10 setmiterlimit
838 newpath -20 20 moveto 20 -20 lineto stroke
839 newpath -20 -20 moveto 20 20 lineto stroke
840 %%EOF
841 % \end{macrocode}
842 % It contains a black cross:
843 % \[\fbox{\drawbox{1.5cm}}\]
844 % The frame indicates the size of the graphics but it does not belong to it.
845 %
846 %\iffalse
847 %</figure>
848 %\fi
849 %
850 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
851 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
852 % \section{Implementation}
853 %\iffalse
854 %<*package>
855 %\fi
856 %
857 % In this section we describe the package |graphbox.sty|.
858
859 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
860 % \paragraph{Package Options.}
861 %
862 % By default, the package overrides the overlay meachanism
863 % for includegraphics of the class beamer.
864 % The global option |nobeamer| disables the interaction.
865 % \begin{macrocode}
866 \newif\ifGin@box@beamer\Gin@box@beamertrue
867 \DeclareOption{nobeamer}{\Gin@box@beamerfalse}
868 \ProcessOptions
869 % \end{macrocode}
870
871 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
872 % \paragraph{Required Packages.}
873 %
874 % The package loads \ctanpkg{graphicx} if not yet present:
875 % \begin{macrocode}
876 \RequirePackage{graphicx}
877 % \end{macrocode}
878
879 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
880 % \paragraph{Internal Definitions.}
881 %
882 % The package defines a box and several dimension registers:
883 %
884 % \begin{macrocode}
885 \newsavebox{\Gin@box@box}
886 \newlength{\Gin@box@width}
887 \newlength{\Gin@box@height}
888 \newlength{\Gin@box@raise}
889 \newlength{\Gin@box@hspace}
890 \newlength{\Gin@box@bwidth}
891 \newlength{\Gin@box@bheight}
892 % \end{macrocode}
893
894 % The following macros store the parameters for the present graphics:
895 %
896 % \begin{macrocode}
897 \def\Gin@box@align{b}
898 \def\Gin@box@hsmash{n}
899 \def\Gin@box@hshift{0pt}
900 \def\Gin@box@vshift{0pt}
901 \def\Gin@box@lmargin{0pt}
902 \def\Gin@box@rmargin{0pt}
903 \def\Gin@box@tmargin{0pt}
904 \def\Gin@box@bmargin{0pt}
905 \newif\ifGin@box@hide\Gin@box@hidefalse
906 \newif\ifGin@box@vsmash\Gin@box@vsmashfalse
907 % \end{macrocode}
908
909 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
910 % \paragraph{Additional Arguments.}
911 %
912 % The optional arguments of |\includegraphics| are parsed by \ctanpkg{keyval}
913 % which calls the appropriate handlers. We add handlers to introduce additional
914 % optional arguments:
915 %
916 % \begin{macrocode}
917 \define@key{Gin}{hide}[true]{\lowercase{\Gin@boolkey{#1}}{box@hide}}
918 \define@key{Gin}{align}[c]{\def\Gin@box@align{#1}}
919 \define@key{Gin}{hsmash}[c]{\edef\Gin@box@hsmash{#1}}
920 \define@key{Gin}{vsmash}[c]{\if#1n\Gin@box@vsmashfalse\else%
921 \Gin@box@vsmashtrue\edef\Gin@box@align{%
922 \if#1bt\else\if#1tb\else%
923 \if#1lu\else\if#1ul\else#1\fi\fi\fi\fi\fi}}
924 \define@key{Gin}{smash}[cc]{\expandafter\KV@Gin@vsmash\@firstoftwo#1%
925 \expandafter\KV@Gin@hsmash\@secondoftwo#1}
926 \define@key{Gin}{hshift}{\def\Gin@box@hshift{#1}}
927 \define@key{Gin}{vshift}{\def\Gin@box@vshift{#1}}
928 \define@key{Gin}{lmargin}{\def\Gin@box@lmargin{#1}}
929 \define@key{Gin}{rmargin}{\def\Gin@box@rmargin{#1}}
930 \define@key{Gin}{tmargin}{\def\Gin@box@tmargin{#1}}
931 \define@key{Gin}{bmargin}{\def\Gin@box@bmargin{#1}}
932 \define@key{Gin}{hmargin}{\def\Gin@box@lmargin{#1}\def\Gin@box@rmargin{#1}}
933 \define@key{Gin}{vmargin}{\def\Gin@box@tmargin{#1}\def\Gin@box@bmargin{#1}}
934 \define@key{Gin}{margin}{\def\Gin@box@lmargin{#1}\def\Gin@box@rmargin{#1}%
935 \def\Gin@box@tmargin{#1}\def\Gin@box@bmargin{#1}}
936 % \end{macrocode}
937 %
938 % The options are stored in internal registers for later processing.
939 % The arguments of |hsmash| and |vsmash| work in the opposite direction
940 % for conventional alignment of {\LaTeX} boxes. Therefore the parameters
941 % |t| and |b| as well as |r| and |l| are interchanged.
942
943 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
944 % \paragraph{Argument Processing.}
945 %
946 % Next, we overwrite the function |\Gin@setfile| called by |\includegraphics|
947 % after the optional parameters have been processed
948 % by |\setkeys{Gin}{...}|:
949 % \begin{macrocode}
950 \let\old@box@Gin@setfile\Gin@setfile
951 \def\Gin@setfile#1#2#3{%
952 % \end{macrocode}
953 % We first save the graphics into the box |\Gin@box@box|
954 % and compute its width and height:
955 % \begin{macrocode}
956 \sbox{\Gin@box@box}{\old@box@Gin@setfile{#1}{#2}{#3}}%
957 \settowidth{\Gin@box@width}{\usebox{\Gin@box@box}}%
958 \settoheight{\Gin@box@height}{\usebox{\Gin@box@box}}%
959 % \end{macrocode}
960 % Temporarily define the macros |\gwidth| and |\gheight|
961 % to represent the width and height of the graphics, respectively:
962 % \begin{macrocode}
963 \def\gwidth{\Gin@box@width}%
964 \def\gheight{\Gin@box@height}%
965 % \end{macrocode}
966 % Ignore top and bottom margin if vsmash is active:
967 % \begin{macrocode}
968 \ifGin@box@vsmash%
969 \def\Gin@box@tmargin{0pt}\def\Gin@box@bmargin{0pt}\fi%
970 % \end{macrocode}
971 % Compute the vertical box dimensions:
972 % \begin{macrocode}
973 \setlength{\Gin@box@raise}{\Gin@box@vshift}%
974 \setlength{\Gin@box@bheight}{\Gin@box@height}%
975 \addtolength{\Gin@box@bheight}{\Gin@box@tmargin}%
976 \addtolength{\Gin@box@bheight}{\Gin@box@bmargin}%
977 \if\Gin@box@align t%
978 \addtolength{\Gin@box@raise}{-\Gin@box@height}%
979 \addtolength{\Gin@box@raise}{1.161290323ex}\fi%
980 \if\Gin@box@align u%
981 \addtolength{\Gin@box@raise}{-\Gin@box@height}\fi%
982 \if\Gin@box@align c%
983 \addtolength{\Gin@box@raise}{-0.5\Gin@box@height}%
984 \addtolength{\Gin@box@raise}{0.580645161ex}\fi%
985 \if\Gin@box@align m%
986 \addtolength{\Gin@box@raise}{-0.5\Gin@box@height}\fi%
987 % \end{macrocode}
988 % Compute the horizontal box dimensions:
989 % \begin{macrocode}
990 \setlength{\Gin@box@hspace}{0pt}%
991 \if\Gin@box@hsmash n%
992 \setlength{\Gin@box@bwidth}{\Gin@box@width}%
993 \addtolength{\Gin@box@bwidth}{\Gin@box@lmargin}%
994 \addtolength{\Gin@box@bwidth}{\Gin@box@rmargin}%
995 \setlength{\Gin@box@hspace}{\Gin@box@lmargin}%
996 \else%
997 \setlength{\Gin@box@bwidth}{0pt}%
998 \setlength{\Gin@box@hspace}{\Gin@box@hshift}%
999 \if\Gin@box@hsmash l%
1000 \addtolength{\Gin@box@hspace}{-\Gin@box@width}\fi%
1001 \if\Gin@box@hsmash c%
1002 \addtolength{\Gin@box@hspace}{-0.5\Gin@box@width}\fi%
1003 \fi%
1004 % \end{macrocode}
1005 % Define the vertical box:
1006 % \begin{macrocode}
1007 \ifGin@box@vsmash\expandafter\smash\fi{%
1008 \raisebox{\Gin@box@raise}{%
1009 \parbox[b]{\Gin@box@bwidth}{%
1010 \rule[-\Gin@box@bmargin]{0pt}{\Gin@box@bheight}%
1011 \smash{%
1012 % \end{macrocode}
1013 % Define the horizontal box:
1014 % \begin{macrocode}
1015 \makebox[0pt][l]{%
1016 \hspace*{\Gin@box@hspace}%
1017 % \end{macrocode}
1018 % Print the graphics unless hidden:
1019 % \begin{macrocode}
1020 \ifGin@box@hide\else\usebox{\Gin@box@box}\fi%
1021 }%
1022 }%
1023 }%
1024 }%
1025 }%
1026 }
1027 % \end{macrocode}
1028
1029 % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1030 %\paragraph{Interaction with class beamer.}
1031 %
1032 % For the class \ctanpkg{beamer} we want to override the overlay mechanism
1033 % to always reserve the space the graphics would occupy.
1034 % Here we have to overwrite the command |\includegraphics|.
1035 % \begin{macrocode}
1036 \@ifclassloaded{beamer}{\ifGin@box@beamer
1037 % \end{macrocode}
1038 % Save the original definition of |\includegraphics| and begin the new one:
1039 % \begin{macrocode}
1040 \let\old@box@includegraphics\includegraphics
1041 \newcommand<>{\fibox@includegraphics}[2][]{\Gin@box@hidefalse%
1042 % \end{macrocode}
1043 % Check whether overlay parameters |<...>| are specified.
1044 % If none, use the counter of the |\pause| mechanism to determine visibility.
1045 % Call |\alt<...>| to set the |hide| argument according to visibility:
1046 % \begin{macrocode}
1047 \beamer@ifempty{#3}%
1048 {\alt<\c@beamerpauses->{}{\Gin@box@hidetrue}}%
1049 {\alt#3{}{\Gin@box@hidetrue}}%
1050 % \end{macrocode}
1051 % Pass on to old definition:
1052 % \begin{macrocode}
1053 \old@box@includegraphics[#1]{#2}}
1054 % \end{macrocode}
1055 % \ctanpkg{beamer} overwrites |\includegraphics|
1056 % at the beginning of the document body.
1057 % We have to overwrite it again discarding
1058 % the changes introduced by \ctanpkg{beamer}:
1059 % \begin{macrocode}
1060 \AtBeginDocument{\let\includegraphics=\fibox@includegraphics}
1061 \fi}{}
1062 % \end{macrocode}
1063
1064 %\iffalse
1065 %</package>
1066 %\fi
1067 %
1068 \endinput