Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %<=*COPYRIGHT>
3 %% Copyright (C) 2011-2018 by Martin Scharrer <[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 Martin Scharrer.
16 %%
17 %% This work consists of the files easyfig.dtx and easyfig.ins
18 %% and the derived filebase easyfig.sty.
19 %%
20 %<=/COPYRIGHT>
21 % \fi
22 %
23 % \iffalse
24 %<*driver>
25 \ProvidesFile{easyfig.dtx}[%
26 %<=*DATE>
27 2018/03/30
28 %<=/DATE>
29 %<=*VERSION>
30 v1.2a
31 %<=/VERSION>
32 Easily include images as figures]
33 \documentclass{ydoc}
34 \GetFileInfo{easyfig.dtx}
35 \usepackage{easyfig}[\filedate]
36 \usepackage{flafter}
37 %\usepackage{mwe}
38 \graphicspath{{example-}}
39 \EnableCrossrefs
40 \CodelineIndex
41 \RecordChanges
42 \OnlyDescription
43 \optionaloff
44 \def\textfraction{0.2}
45 \def\bottomfraction{0.8}
46 \begin{document}
47 \DocInput{\jobname.dtx}
48 \PrintChanges
49 \PrintIndex
50 \end{document}
51 %</driver>
52 % \fi
53 %
54 % \CheckSum{207}
55 %
56 % \CharacterTable
57 % {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
58 % 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
59 % Digits \0\1\2\3\4\5\6\7\8\9
60 % Exclamation \! Double quote \" Hash (number) \#
61 % Dollar \$ Percent \% Ampersand \&
62 % Acute accent \' Left paren \( Right paren \)
63 % Asterisk \* Plus \+ Comma \,
64 % Minus \- Point \. Solidus \/
65 % Colon \: Semicolon \; Less than \<
66 % Equals \= Greater than \> Question mark \?
67 % Commercial at \@ Left bracket \[ Backslash \\
68 % Right bracket \] Circumflex \^ Underscore \_
69 % Grave accent \` Left brace \{ Vertical bar \|
70 % Right brace \} Tilde \~}
71 %
72 %
73 % \changes{v1.0}{2011/10/31}{Initial release.}
74 % \changes{v1.1}{2012/05/06}{Fix of "placement" key and non-e-TeX fallback code.}
75 % \changes{v1.2}{2012/05/15}{Added "here" key.}
76 % \changes{v1.2a}{2018/03/30}{Updated manual to mentioned \pkg{adjustbox} as alternative.}
77 %
78 % \DoNotIndex{\newcommand,\newenvironment}
79 %
80 % \GetFileInfo{easyfig.dtx}
81 % \author{Martin Scharrer}
82 % \email{[email protected]}
83 % \ifdefined\repository
84 % \repository{https://bitbucket.org/martin_scharrer/easyfig}
85 % \fi
86 %
87 % \maketitle
88 %
89 % \begin{abstract}\noindent
90 % This package aims to simplify the most common usage of \env{figure} environments
91 % to include a single image with a caption and label.
92 %
93 % Current versions of the \pkg{adjustbox} package now provide keys for turning an image or other content into a
94 % float or non-float inclusive a caption. This makes this package quite redundant.
95 % \end{abstract}
96 %
97 % \section{Introduction}
98 % A very high percentage of all \LaTeX\ figures aim to simply display a simple image with a caption and label.
99 % A common way to code this is:
100 % \begin{lstlisting}[gobble=4,numbers=none,language={[latex]tex}]
101 % \begin{figure}
102 % \centering
103 % \includegraphics[<options>]{<filename>}
104 % \caption{<caption text>}
105 % \label{<label>}
106 % \end{figure}
107 % \end{lstlisting}
108 %
109 % This package provides an easy and short way to include figures like this. At the moment only single image figures
110 % are supported but it is planned to also support common 1x2 and 2x1 figures in future releases.
111 %
112 % \iffalse
113 % \section{Dependecies}
114 % This package uses the following packages: \pkg{xkeyval}, \pkg{adjustbox} (which uses \pkg{graphicx}) and \pkg{ifetex}.
115 % \fi
116 %
117 % \section{Usage}
118 % \subsection*{Macros}
119 % \DescribeMacro\Figure[<key=value pairs>]{<image filename>}
120 % \DescribeMacro\Figure*[<key=value pairs>]{<image filename>}
121 % The macro creates a \env{figure} environment where the given image file is included using \Macro\includegraphics wrapped in an \env{adjustbox} environment.
122 % By default the image is centered and all keys which are not known by \Macro\Figure are passed to the internal \env{adjustbox} environment. This accepts all normal
123 % \Macro\includegraphics keys as well as many more. The starred version uses the \env{figure*} environment instead which will insert the figure over both columns in \opt{twocolumn} mode.
124 %
125 % \noindent
126 % Usually this macro is used as follows:\nopagebreak
127 % \begingroup
128 % \leftmargin=0pt
129 % \rightmargin=0pt
130 % \begin{macroquote}
131 % \Figure['caption='{My caption},label=fig:mypic]{myimage}\\
132 % \Figure['caption='{My caption}]{myimage}\\
133 % \Figure['caption='{My caption},label=fig:mypic,placement=ht]{myimage}
134 % \end{macroquote}
135 % \endgroup
136 %
137 % \DescribeMacro\easyfigdefault{<key=value pairs (before)>}
138 % \DescribeMacro\easyfigdefault*{<key=value pairs (after)>}
139 % Defines a list of key/value pairs which should be used by default. The normal version adds the pairs before the one
140 % given with the optional argument of \Macro\Figure, while the starred version adds them after these.
141 % If these macros are used more then once the old default settings are overwritten.
142 % This feature is similar to \Macro\adjustboxset from the used \pkg{adjustbox} package, but the keys are only affecting \Macro\Figure macros and do not stack.
143 % By default the \emph{before} key list is empty and the \emph{after} list is set to \Key{center} which centers the image around the \Macro\linewidth, after any other
144 % transformation is applied. The default centering can be deleted using \Macro\easyfigdefault*{}.
145 %
146 %
147 % \subsection*{Keys}
148 % The following keys exist to control the elements of the figure. All other keys are passed to the inner \env{adjustbox} environment from the \pkg{adjustbox} package.
149 %
150 % \DescribeKey{caption}'='<caption>
151 % Sets the \Macro\caption of the figure.
152 %
153 % \DescribeKey{captionabove}'='<caption>
154 % Sets the \Macro\caption of the figure which is placed above the figure instead of the default placement below it.
155 %
156 % \DescribeKey{shortcaption}'='<short caption>
157 % Sets the short version of the caption, i.e. the optional argument of \Macro\caption, used for the table-of-figures.
158 % This key only has an effect if either \Key{caption} or \Key{captionabove} is used as well. However, the order of keys is not meaningful.
159 %
160 % \DescribeKey{label}'='<label>
161 % Sets the \Macro\label of the figure. The order of this key and \Key{caption} or \Key{captionabove} is not meaningful.
162 % If the figure has a caption but this key is not used, a default label `\MacroArgs'fig:'<image filename>\relax' is used instead.
163 %
164 % \DescribeKey{placement}'='<placement characters>
165 % This key defines the requested placement of the figure. The value is then passed to the optional argument of \env{figure} or \env{figure*}.
166 % Valid positioning characters are `|p|' (page), `|t|' (top), `|b|' (bottom), `|h|' (here) and `|!|' (force) and any additional characters defined by packages (like `|H|').
167 %
168 % \DescribeKey{here}
169 % Using this key the figure is placed at the current position and not using a \env{figure} float. Any \Key{placement}
170 % key will be ignored. Note that this key is overwritten by any following \Key{twocolumn} key.
171 %
172 % \DescribeKey{twocolumn}
173 % \DescribeKey{twocolumn}'=true|false'
174 % This boolean key will use the \env{figure*} environment which make the figure span over both columns in a \opt{twocolumn} document. It has the same effect as using \Macro\Figure*, but allows
175 % to switch between this two modes for all figures using \Macro\easyfigdefault. When used without a value `|true|' is assumed.
176 % Any other value as `|true|' switches to one-column mode, even if \Macro\Figure* was used.
177 %
178 % \subsection*{Notable \pkg{adjustbox} Keys}
179 % The following keys are mentioned here because they are might be often used for images inside figures. Please see the \pkg{adjustbox} manual for further details and keys.
180 % In addition all \Macro\includegraphics keys as mentioned in the \href{http://www.ctan.org/pkg/grfguide}{grfguide} can of course be used.
181 %
182 % \DescribeKey{center}'='<length>
183 % \DescribeKey{left}'='<length>
184 % \DescribeKey{right}'='<length>
185 % Aligns the image at the center or to the left or right. The \emph{optional} length defines the final width in with the image is aligned. By default the current \Macro\linewidth is used, which
186 % inside figures is normally identical to the \Macro\textwidth. If the image is wider than the given width it will overlap accordantly, i.e. on both sites, on the right or on the left, respectively.
187 % As mentioned above by default \Key{center} is applied to all figures. This replaces the normally used \Macro\centering.
188 %
189 % \DescribeKey{width}'='<length>
190 % \DescribeKey{height}'='<length>
191 % \DescribeKey{totalheight}'='<length>
192 % \DescribeKey{min width}'='<length>
193 % \DescribeKey{min height}'='<length>
194 % \DescribeKey{min size}'='{<length>}{<length>}
195 % \DescribeKey{max width}'='<length>
196 % \DescribeKey{max height}'='<length>
197 % \DescribeKey{max size}'='{<length>}{<length>}
198 % Can be used to set the nominal/minimal/maximum width and height of the image.
199 %
200 % \DescribeKey{frame}
201 % \DescribeKey{frame}'='<length>
202 % Adds a tight frame around the image.
203 %
204 % \DescribeKey{fbox}
205 % \DescribeKey{fbox}'='<length>
206 % \DescribeKey{fbox}'='<length>~<sep>
207 % Adds a frame around the image.
208 %
209 % \DescribeKey{margin}'='<all sites>
210 % \DescribeKey{margin}'='<left/right>~<top/bottom>
211 % \DescribeKey{margin}'='<llx>~<lly>~<urx>~<ury>
212 % This key can be used to add a margin (white space) around the image.
213 %
214 %
215 % \clearpage
216 % \section{Examples}
217 %
218 % \subsection{Simple figure with an image and caption, automated label}
219 % A default label `|fig:image|' is used here.
220 % \par\smallskip\noindent
221 % \Macro\Figure['width=10cm,caption={An image}']{image}
222 % \Figure[width=10cm,caption={An image}]{image}
223 %
224 % \clearpage
225 % \subsection{Simple figure with an image and caption, manual label}
226 % Normal usage with a manual label.
227 % \par\smallskip\noindent
228 % \Macro\Figure['width=10cm,caption={Second image},label=fig:myimage']{image}
229 % \Figure[width=10cm,caption={Second image},label=fig:myimage]{image}
230 %
231 % \clearpage
232 % \subsection{Usage of other keys}
233 % Adds a frame around the image which is rotated a little.
234 % The placement is fixed to top or bottom.
235 % \par\smallskip\noindent
236 % \Macro\Figure['width=10cm,angle=10,position=tb,caption={Another image},frame']{image}
237 % \Figure[width=10cm,angle=10,placement=tb,caption={Another image},frame]{image}
238 %
239 % \StopEventually{}
240 % \clearpage
241 % \section{Implementation}
242 %
243 % \iffalse
244 %<*easyfig.sty>
245 % \fi
246 % \begin{macrocode}
247 %<!COPYRIGHT>
248 \ProvidesPackage{easyfig}[%
249 %<!DATE>
250 %<!VERSION>
251 %<*DRIVER>
252 2099/01/01 develop
253 %</DRIVER>
254 Easy way to include figures]
255 % \end{macrocode}
256 %
257 % \begin{macrocode}
258 \RequirePackage{adjustbox}
259 \RequirePackage{xkeyval}
260 \RequirePackage{ifetex}
261 % \end{macrocode}
262 %
263 % \begin{macrocode}
264 \let\easyfig@caption\@gobble
265 \let\easyfig@captionabove\@gobble
266 \let\easyfig@placement\@empty
267 \let\easyfig@default\@empty
268 \let\easyfig@default@end\@empty
269 \let\easyfig@shortcaption\@empty
270 \def\easyfig@env{{figure}}
271 % \end{macrocode}
272 %
273 % \begin{macro}{\easyfigdefault}
274 % \begin{macrocode}
275 \newcommand*{\easyfigdefault}{%
276 \@ifstar
277 {\def\easyfig@default@end}%
278 {\def\easyfig@default}%
279 }
280 \easyfigdefault*{center}
281 % \end{macrocode}
282 % \end{macro}
283 %
284 %
285 % \begin{macro}{\easyfig@label}
286 % \begin{macrocode}
287 \def\easyfig@label#1{%
288 \@ifundefined {easyfig@r@fig:#1}{%
289 \label{fig:#1}%
290 \global\@namedef{easyfig@r@fig:#1}{}%
291 }{}%
292 }
293 % \end{macrocode}
294 % \end{macro}
295 %
296 %
297 % \begin{key}{easyfig}{caption}
298 % \begin{macrocode}
299 \define@key{easyfig}{caption}{%
300 \def\easyfig@caption##1{\expandafter\caption\easyfig@shortcaption{#1}\easyfig@label{##1}}%
301 \let\easyfig@captionabove\@gobble
302 }
303 % \end{macrocode}
304 % \end{key}
305 %
306 %
307 % \begin{key}{easyfig}{shortcaption}
308 % \begin{macrocode}
309 \define@key{easyfig}{shortcaption}{%
310 \def\easyfig@shortcaption{[{#1}]}%
311 }
312 % \end{macrocode}
313 % \end{key}
314 %
315 %
316 % \begin{key}{easyfig}{captionabove}
317 % \begin{macrocode}
318 \define@key{easyfig}{captionabove}{%
319 \let\easyfig@caption\@gobble
320 \def\easyfig@captionabove##1{{%
321 \@tempdima=\abovecaptionskip
322 \abovecaptionskip=\belowcaptionskip
323 \belowcaptionskip=\@tempdima
324 \expandafter\caption\easyfig@shortcaption{#1}%
325 \easyfig@label{##1}%
326 }}%
327 }
328 % \end{macrocode}
329 % \end{key}
330 %
331 %
332 % \begin{key}{easyfig}{label}
333 % \begin{macrocode}
334 \define@key{easyfig}{label}{%
335 \def\easyfig@label##1{\label{#1}}%
336 }
337 % \end{macrocode}
338 % \end{key}
339 %
340 %
341 % \begin{key}{easyfig}{placement}
342 % \begin{macrocode}
343 \define@key{easyfig}{placement}{%
344 \def\easyfig@placement{[#1]}%
345 }
346 % \end{macrocode}
347 % \end{key}
348 %
349 % \begin{key}{easyfig}{here}
350 % \begin{macrocode}
351 \define@key{easyfig}{here}[]{%
352 \def\easyfig@env{{easyfighere}}%
353 }
354 % \end{macrocode}
355 % \end{key}
356 %
357 %
358 % \begin{environment}{easyfighere}
359 % \begin{macrocode}
360 \newenvironment{easyfighere}{%
361 \trivlist
362 \def\@captype{figure}%
363 \item\relax
364 }{%
365 \endtrivlist
366 }
367 % \end{macrocode}
368 % \end{environment}
369 %
370 %
371 % \begin{key}{easyfig}{twocolumn}
372 % \begin{macrocode}
373 \define@key{easyfig}{twocolumn}[true]{%
374 \begingroup
375 \def\@tempa{#1}%
376 \def\@tempb{true}%
377 \ifx\@tempa\@tempb
378 \endgroup
379 \def\easyfig@env{{figure*}}%
380 \else
381 \endgroup
382 \def\easyfig@env{{figure}}%
383 \fi
384 }
385 % \end{macrocode}
386 % \end{key}
387 %
388 % \begin{macro}{\Figure}
389 % \begin{macrocode}
390 \newcommand{\Figure}{%
391 \begingroup
392 \@ifstar
393 {\def\easyfig@env{{figure*}}\@Figure}%
394 {\@Figure}%
395 }
396 % \end{macrocode}
397 % \end{macro}
398 %
399 % \begin{macrocode}
400 \ifetex
401 % \end{macrocode}
402 %
403 % Efficient $\epsilon$-\TeX\ definition:
404 %
405 % \begin{macro}{\easyfig@expandonce}
406 % \begin{macrocode}
407 \def\easyfig@expandonce#1{%
408 \expandafter\unexpanded\expandafter{#1}%
409 }
410 % \end{macrocode}
411 % \end{macro}
412 %
413 %
414 % \begin{macro}{\@Figure}
415 % \begin{macrocode}
416 \newcommand{\@Figure}[2][]{%
417 \edef\@tempa{%
418 \noexpand\setkeys*{easyfig}{%
419 \easyfig@expandonce\easyfig@default,%
420 \unexpanded{#1},%
421 \easyfig@expandonce\easyfig@default@end
422 }%
423 }%
424 \@tempa
425 \edef\@tempa{%
426 \noexpand\begin\easyfig@env%
427 \easyfig@placement
428 }%
429 \@tempa
430 \easyfig@captionabove{#2}%
431 \edef\@tempa{\noexpand\begin{adjustbox}{\easyfig@expandonce\XKV@rm}}%
432 \@tempa
433 \includegraphics{#2}%
434 \end{adjustbox}%
435 \easyfig@caption{#2}%
436 \expandafter\end\easyfig@env%
437 \endgroup
438 }
439 % \end{macrocode}
440 % \end{macro}
441 %
442 % \begin{macrocode}
443 \else
444 % \end{macrocode}
445 %
446 % Fall-back definition for distributions which do not support $\epsilon$-\TeX:
447 %
448 % \begin{macro}{\@Figure}
449 % \begin{macrocode}
450 \newcommand{\@Figure}[2][]{%
451 \def\@tempa{\setkeys*{easyfig}}%
452 \expandafter\toks@\expandafter{\easyfig@default,#1}%
453 \expandafter\expandafter\expandafter\toks@
454 \expandafter\expandafter\expandafter{\expandafter\the\expandafter\toks@\expandafter,\easyfig@default@end}%
455 \expandafter\@tempa\expandafter{\the\toks@}
456 \edef\@tempa{\noexpand\begin\easyfig@env}%
457 \expandafter\@tempa\easyfig@placement
458 \easyfig@captionabove{#2}%
459 \def\@tempa{\begin{adjustbox}}%
460 \expandafter\def\expandafter\@tempb\expandafter{\expandafter{\XKV@rm}}%
461 \expandafter\@tempa\@tempb
462 \includegraphics{#2}%
463 \end{adjustbox}%
464 \easyfig@caption{#2}%
465 \expandafter\end\easyfig@env%
466 \endgroup
467 }
468 % \end{macrocode}
469 % \end{macro}
470 %
471 %
472 % \begin{macrocode}
473 \fi
474 % \end{macrocode}
475 % \iffalse
476 %</easyfig.sty>
477 % \fi
478 %
479 % \Finale
480 \endinput