Debian Codegraph @

texmf-dist/source/latex/bosisio/graphfig.dtx

raw
1 %\iffalse % MetaComment
2 %%
3 %% + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
4 %% | Copyright(C) 1997-2010 by F. Bosisio |
5 %% | |
6 %% | This program can be redistributed and/or modified under |
7 %% | the terms of the LaTeX Project Public License, either |
8 %% | version 1.3 of this license or (at your option) any later |
9 %% | version. The latest version of this license is in |
10 %% | http://www.latex-project.org/lppl.txt |
11 %% | and version 1.3 or later is part of all LaTeX distributions |
12 %% | version 2005/12/01 or later. |
13 %% | |
14 %% | This work has the LPPL maintenance status `maintained'. |
15 %% | The Current Maintainer of this work is F. Bosisio. |
16 %% | |
17 %% | This work consists of files graphfig.dtx and graphfig.html |
18 %% | and of the derived files graphfig.sty and graphfig.pdf. |
19 %% | |
20 %% | E-mail: [email protected] |
21 %% | CTAN location: macros/latex/contrib/bosisio/ |
22 %% + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
23 %%
24 %% If you make any improvment, find any bug or have
25 %% any suggestion, please let me know about it.
26 %%
27 %<*package,driver>
28 %\fi
29 %
30 \def\FileName{graphfig}
31 %\iffalse % MetaComment
32 %</package,driver>
33 %<*package>
34 %\fi
35 \def\fileversion{2.2}
36 \def\filedate{1997/12/15}
37 \def\docdate{2005/04/09}
38 \def\filedescr{Commands to include graphics files (FB)}
39 %
40 %\iffalse % MetaComment
41 %</package>
42 %<*dtx>
43 %- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
44 % This section is the installation driver
45 %
46 \def\batchfile{\FileName.dtx}
47 %
48 \input docstrip
49 %
50 \keepsilent
51 % \askforoverwritefalse
52 %
53 \generateFile{\FileName.sty}{f}{\from{\FileName.dtx}{package}}
54 %
55 \generateFile{\FileName.drv}{f}{\from{\FileName.dtx}{driver}}
56 %
57 \Msg{******************************************************}
58 \Msg{*}
59 \Msg{* To produce the documentation run the}
60 \Msg{* file `\FileName.drv' through LaTeX.}
61 \Msg{*}
62 \Msg{******************************************************}
63 %
64 \endbatchfile
65 %
66 % End of the installation driver
67 %- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
68 %</dtx>
69 %
70 % This section is the documentation driver
71 %
72 %<+driver>\documentclass[12pt,a4paper]{article}
73 %<+driver>\usepackage{doc}
74 %<+driver> \EnableCrossrefs
75 %<+driver> \CodelineIndex
76 %<+driver> \RecordChanges
77 %<+driver> %\OnlyDescription % Uncomment not to see the implementation
78 %<+driver>\begin{document}
79 %<+driver> \DocInput{\FileName.dtx}
80 %<+driver> \PrintIndex
81 %<+driver> \PrintChanges
82 %<+driver>\end{document}
83 %
84 % End of the documentation driver
85 %- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
86 %<*package>
87 %\fi
88 %
89 % \changes{v0.1}{21 April 1997}{First release}
90 % \changes{v0.2}{5 July 1997}{Added the ``\texttt{clip}'' option to ``\texttt{psfig}''}
91 % \changes{v0.3}{29 August 1997}{Modified the ``\texttt{@PS@Figure}'' command}
92 % \changes{v1.0}{8 September 1997}{Documentation added}
93 % \changes{v1.1}{19 November 1997}{Improved the ``SubFigure'' command}
94 % \changes{v1.2}{11 December 1997}{Fixed a bug in ``SubFigure'' references}
95 % \changes{v1.3}{12 December 1997}{Standard ``graphics'' package instead of ``psfig''}
96 %\iffalse % MetaComment
97 % The previous change has been suggested by Sebastian Rahtz ([email protected])
98 %\fi
99 % \changes{v2.0}{15 December 1997}{``graphfile'' instead of ``PSFigure/SubFigure''}
100 % \changes{v2.1}{5 March 1999}{Added copyright notice and changed addresses}
101 % \changes{v2.2}{9 April 2005}{Usage of the double-quote character (") avoided}
102 %
103 % \MakeShortVerb{\|}
104 %
105 % \title{Package \texttt{\FileName}\thanks{This is version \fileversion,
106 % last revised \filedate; documentation date \docdate}}
107 % \author{F. Bosisio\\\normalsize E-mail: \texttt{[email protected]}}
108 % \date{\filedate}
109 % \maketitle
110 %
111 % \begin{abstract}
112 % Documentation for the package \texttt{\FileName}.
113 % \end{abstract}
114 %
115 % \section{Introduction}
116 % This package provides some commands to make the use of graphic
117 % files in \LaTeX{} simpler.
118 %
119 % \noindent
120 % It declares the ``|Figure|'' environment (capitalized!) and
121 % the two commands ``|\graphfile|'' and ``|\graphfile*|''.
122 % Combining this commands, it it possible to include graphic
123 % files in a \LaTeX{} document very simply.
124 %
125 % \section{Required packages}
126 % This package uses the ``|\includegraphics*|'' command defined in the
127 % standard |graphics| package.
128 % Moreover, it uses the package |subfigure| when the |subfigure|
129 % option is specified, and the |float| package if the |AllowH|
130 % option is used.
131 %
132 % \section{The options}
133 % At now, two options are available: ``|subfigure|'' and ``|AllowH|''.
134 %
135 % \noindent
136 % The ``|subfigure|'' option allow the use of sub-figures
137 % inside a |Figure| environment, in order to place multiple
138 % pictures in a single \LaTeX{} figure (cfr. the |subfigure|
139 % standard package).
140 %
141 % \noindent
142 % The ``|AllowH|'' option allow the use of the ``|H|'' float specifier
143 % for the |Figure| environment, in order to place the figure exaclty
144 % where the command is placed (cfr. the |float| standard package).
145 %
146 % \section{The \texttt{Figure} environment and its relatives}
147 % The ``|Figure|'' environment (capitalized!) is somewhat different
148 % from the standard \LaTeX{} ``|figure|'' environment: besides an
149 % optional argument used to specify the placement parameters (which
150 % now defaults to ``|[htbp]|''), it has a mandatory argument specifying
151 % the ``caption'' and another optional argument, used as a ``label'' for
152 % cross-referencies:
153 %
154 % \begin{verbatim}
155 % \begin{Figure}[<htbpH>]{<caption>}[<label>]
156 % ...
157 % \end{Figure}
158 % \end{verbatim}
159 %
160 % \noindent
161 % The use of the ``|H|'' specifier (i.e. ``I want my float here!'') is
162 % possible only if the ``|AllowH|'' option has been specified.
163 %
164 % \subsection{The \texttt{graphfile} command}
165 % Inside the ``|Figure|'' environment, are available the commands:
166 %
167 % \begin{verbatim}
168 % \graphfile[<width>]{<file>}[<sub-caption>]
169 % \graphfile*[<heigth>]{<file>}[<sub-caption>]
170 % \end{verbatim}
171 %
172 % \noindent
173 % which are a simplified version of the ``|\includegraphics*|''
174 % command (which is automatically included by this package; see the
175 % |graphics| package for reference), since you don't have to worry
176 % about scaling: the mandatory argument is the name of the graphic file to
177 % include, whereas the first optional argument specifies the desired
178 % width (in the non *-form) or heigth (in the *-form) of the figure as
179 % a fraction of ``|\linewidth|'' (e.g. ``|50|'' means ``|.50\linewidth|'',
180 % i.e. half a line! ), so no unit of measure (as ``|cm|'' or ``|pt|'')
181 % is required.
182 % Moreover, since the ``*-form'' of ``|\includegraphics|'' is used, the
183 % regions outside the bounding-box are not drawn.
184 % Another advantage of the combined use of the ``|Figure|'' environment
185 % and the ``|\graphfile|'' commands is that the picture is automatically
186 % centered horizontally, so no ``|\centering|'' or similar declartion
187 % is required.
188 %
189 % \begin{verbatim}
190 % \begin{Figure}[<htbpH>]{<caption>}[<label>]
191 % \graphfile[<width>]{<file>}
192 % \end{Figure}
193 % \end{verbatim}
194 %
195 % \subsection{Sub-figures}
196 %
197 % If you want to include more than one file in a single figure,
198 % you need to specify the ``|subfigure|'' option, which includes the
199 % |subfigure| package and provides the authomatic placement of a
200 % sub-caption below each picture.
201 %
202 % \begin{verbatim}
203 % \graphfile[<width_1>]{<file_1>}[<sub-caption_1>]
204 % ...
205 % \graphfile[<width_N>]{<file_N>}[<sub-caption_N>]
206 % \end{verbatim}
207 %
208 % \noindent
209 % which is a combined version of ``|\subfigure|'' and ``|\includegraphics*|''
210 % (see the |subfigure| and |graphics| packages for reference):
211 % the last optional argument specify a ``caption'' for the sub-figure under
212 % consideration, while the first two arguments work exactly like as
213 % described above in the case of one only picture (indeed, you can
214 % use the last optional argument even if the |subfigure| option was
215 % not specified, in which case it is simply ignored).
216 % Each individual caption is printed preceded by a bracketed letter,
217 % which is the sub-figure counter and is printed even if no caption is
218 % specified.
219 % Using only a series of ``|\graphfile[|$\dots$|]{|$\dots$|}[|$\dots$|]|''
220 % commands inside a ``|Figure|'' environment provides an equal spacing
221 % beetween the pictures and around them, without the need for any
222 % extra command.
223 % Finally, if a ``|<label>|'' was specified as the last optional argument
224 % to the ``|Figure|'' environment, you can reference to each individual
225 % sub-figure by the labels ``|<label>:a|'', ``|<label>:b|'', and so on,
226 % without the need for declaring them.
227 %
228 % \begin{verbatim}
229 % \begin{Figure}[<htbpH>]{<caption>}[<label>]
230 % \graphfile[<width_1>]{<file_1>}[<sub-caption_1>]
231 % \graphfile[<width_2>]{<file_2>}[<sub-caption_2>]
232 % :
233 % :
234 % \end{Figure}
235 % \end{verbatim}
236 %
237 % \subsection{The \texttt{FigureDefaultPlacement} command}
238 %
239 % The command ``|FigureDefaultPlacement{|$\dots$|}|'' can be used to
240 % specify the default value for the placement argument of the ``|Figure|''
241 % environment.
242 % This is useful to change the default placement from the standard
243 % value ``htbp''.
244 %
245 % \StopEventually{}
246 % \newpage
247 % \section{Implementation}
248 % We start defining the options and including the required packages.
249 % \begin{macrocode}
250 %%
251 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
252 \ProvidesPackage{\FileName}[\filedate\space v\fileversion\space\filedescr]
253 \RequirePackage{graphics}
254 %%
255 \newif\if@AllowSubFigure\@AllowSubFigurefalse
256 \newif\if@AllowHfloat\@AllowHfloatfalse
257 %%
258 \DeclareOption{subfigure}{\@AllowSubFiguretrue}
259 \DeclareOption{AllowH}{\@AllowHfloattrue}
260 %%
261 \ProcessOptions
262 %%
263 \if@AllowSubFigure
264 \RequirePackage{subfigure}[1995/03/06 v2.0]
265 % \end{macrocode}
266 %
267 % These redefinitions are needed in order to obtain the right form
268 % of the references (i.e. like ``Fig. 1a'' and not ``Fig. 1(a)'')
269 % \begin{macrocode}
270 \def\thesubfigure{\alph{subfigure}}
271 % \end{macrocode}
272 %
273 % We use ``|\renewcommand|'' instead of ``|\def|'' in order to realize
274 % possible changes in the |subfigure| package which may eliminate the
275 % inner command ``|\@thesubfigure|''.
276 % \begin{macrocode}
277 \renewcommand*\@thesubfigure{{\subcaplabelfont(\thesubfigure)}\space}
278 \let\SubGR@PH=\subfigure
279 \else
280 % \end{macrocode}
281 %
282 % If the ``subfigure'' option is not present, we let the internal
283 % command ``|\SubGR@PH|'' to simply execute its mandatory argument
284 % \begin{macrocode}
285 \newcommand*\SubGR@PH[2][]{#2}
286 \fi
287 \if@AllowHfloat
288 \RequirePackage{float}[1995/03/29 v1.2c]
289 \restylefloat{figure}
290 \fi
291 %%
292 \newif\if@FirstPicture\@FirstPicturetrue
293 \let\SubFig@Label=\relax
294 % \end{macrocode}
295 %
296 % \begin{macro}{\@Graph@Figure}
297 % This is the core command which includes and scales the graphic file
298 % using the commands provided by the |graphic| package.
299 % \begin{macrocode}
300 %%
301 \newcommand*\@Graph@Figure[3]{\resizebox{#1}{#2}{\includegraphics*{#3}}}
302 % \end{macrocode}
303 % \end{macro}
304 %
305 % \begin{macro}{\graphfile}
306 % The command ``|\graphfile''| and its *-version simply calls one
307 % of the forthcoming commands.
308 % \begin{macrocode}
309 \newcommand*\graphfile{\@ifnextchar*{\graphfile@star}{%
310 \@ifnextchar[{\GraphFile@width}{\GraphFile@noSize}}%
311 }
312 \def\graphfile@star*{\@ifnextchar[{\GraphFile@heigth}{\GraphFile@noSize}}
313 % \end{macrocode}
314 % These commands, in turns, calls ``|\@GraphFile@Draw|'' with suitable
315 % arguments (i.e. the lengths are turned into fractions of ``|\linewidth|''
316 % and an exclamation mark ``|!|'' is used where the scaling factor has
317 % to be the same as the other direction; furthermore the actual size
318 % of the graphic image is used [throught the ``|\width|'' command] if
319 % no scaling parameter is given).
320 % \begin{macrocode}
321 %%
322 \def\GraphFile@width[#1]{%
323 \@ifnextchar[{\@GraphFile@width@heigth{#1}}{\@GraphFile@widthNOheigth{#1}}%
324 }
325 \def\@GraphFile@width@heigth#1[#2]#3{%
326 \@ifnextchar[{\@GraphFile@Draw{.#1\linewidth}{.#2\linewidth}{#3}}{%
327 \@GraphFile@Draw{.#1\linewidth}{.#2\linewidth}{#3}[]}%
328 }
329 \def\@GraphFile@widthNOheigth#1#2{%
330 \@ifnextchar[{\@GraphFile@Draw{.#1\linewidth}{!}{#2}}{%
331 \@GraphFile@Draw{.#1\linewidth}{!}{#2}[]}%
332 }
333 \def\GraphFile@heigth[#1]#2{%
334 \@ifnextchar[{\@GraphFile@Draw{!}{.#1\linewidth}{#2}}{%
335 \@GraphFile@Draw{!}{.#1\linewidth}{#2}[]}%
336 }
337 \newcommand*\GraphFile@noSize[1]{%
338 \@ifnextchar[{\@GraphFile@Draw{\expandafter\width}{!}{#1}}{%
339 \@GraphFile@Draw{\expandafter\width}{!}{#1}[]}%
340 }
341 % \end{macrocode}
342 % \end{macro}
343 %
344 % \begin{macro}{\@GraphFile@Draw}
345 % This command has three mandatory arguments and an optional one,
346 % which represent, respectively, the width, heigth, file-name and
347 % sub-caption of the current picture.
348 % \begin{macrocode}
349 %%
350 \def\@GraphFile@Draw#1#2#3[#4]{%
351 \if@FirstPicture%
352 % \end{macrocode}
353 % If it is the first call to this command in the current |Figure|
354 % environment, we simply store it in ``|\TMP@Graph|''.
355 % We also set ``|@FirstPicture|'' to false for the next call.
356 % \begin{macrocode}
357 \@FirstPicturefalse%
358 \def\TMP@Graph{\SubGR@PH[#4\SubFig@Label]{\@Graph@Figure{#1}{#2}{#3}}}%
359 \else%
360 \ifx\TMP@Graph\undefined%
361 % \end{macrocode}
362 % If ``|\TMP@Graph|'' is not defined, this is the third call (or more).
363 % So we invoke the ``|\SubGR@PH|'' command (which may be ``|\subfigure|''
364 % or simply its second argument depending on the options) with a
365 % ``|\@Graph@Figure|'' command inside and followed by an ``|\hfill|''
366 % command for centering purposes.
367 % \begin{macrocode}
368 \SubGR@PH[#4\SubFig@Label]{\@Graph@Figure{#1}{#2}{#3}}\hspace*{\fill}%
369 \else%
370 % \end{macrocode}
371 % If we arrive at this point it is the second call to ``|\graphfile|''
372 % inside the current |Figure| environment: before plotting the
373 % current figure (as above) we must call ``|\TMP@Graph|'' to plot
374 % the first one (which was only saved).
375 % We also undefine ``|\TMP@Graph|'' for the next time.
376 % \begin{macrocode}
377 \hspace*{-4pt}\TMP@Graph\hspace*{\fill}%
378 \let\TMP@Graph\undefined%
379 \SubGR@PH[#4\SubFig@Label]{\@Graph@Figure{#1}{#2}{#3}}\hspace*{\fill}%
380 \fi%
381 \fi%
382 }
383 % \end{macrocode}
384 % \end{macro}
385 %
386 % \begin{macro}{\FigureDefaultPlacement}
387 % The ``|\FigureDefaultPlacement|'' macro is defined to set the value of
388 % the ``|\Default@FigurePlacement|'' to its argument.
389 % Also ``|\Default@FigurePlacement|'' is initialized to ``|htbp|''.
390 % \begin{macrocode}
391 %%
392 \newcommand*\FigureDefaultPlacement[1]{\def\Default@FigurePlacement{#1}}
393 \def\Default@FigurePlacement{htbp}
394 % \end{macrocode}
395 % \end{macro}
396 %
397 % \begin{environment}{Figure}
398 % \begin{macrocode}
399 %%
400 \newenvironment{Figure}[2][\Default@FigurePlacement]{%
401 % \end{macrocode}
402 % The code for ``|\begin{Figure}|'' starts by setting ``|@FirstPicture|''
403 % to true.
404 % \begin{macrocode}
405 \@FirstPicturetrue%
406 % \end{macrocode}
407 % Then we start a standard ``|figure|'' environment followed by an
408 % ``|\hfill|'' command (for centering purposes).
409 % \begin{macrocode}
410 \figure[#1]%
411 \hspace*{\fill}%
412 % \end{macrocode}
413 % We change the definition of ``|\\|'' so that an ``|\hfill|'' command
414 % is added at the beginning of next line.
415 % \begin{macrocode}
416 \let\@Figure@CR=\\%
417 \def\\{\par\hspace*{\fill}}%
418 % \end{macrocode}
419 % If there is the last optional argument, ``|\@Figure@quadra|'' is
420 % invoked, otherwise ``|\MK@Figure@Caption|'' is directly defined
421 % to print the specified caption.
422 % \begin{macrocode}
423 \@ifnextchar[{\@Figure@quadra{#2}}{\def\MK@Figure@Caption{\caption{#2}}}%
424 }{%
425 % \end{macrocode}
426 % The code for ``|\end{Figure}|'' starts by checking that ``|\TMP@Graph|''
427 % is undefined, otherwise this means that there was one only picture:
428 % in such a case we have to print it out before continuing.
429 % \begin{macrocode}
430 \ifx\TMP@Graph\undefined\else%
431 \if@AllowSubFigure%
432 \renewcommand*\SubGR@PH[2][]{##2}%
433 \TMP@Graph\hspace*{\fill}%
434 \let\SubGR@PH=\subfigure%
435 \else%
436 \TMP@Graph\hspace*{\fill}%
437 \fi%
438 \global\let\TMP@Graph\undefined%
439 \fi%
440 % \end{macrocode}
441 % The ``|\MK@Figure@Caption|'' prints the previously saved caption.
442 % \begin{macrocode}
443 \MK@Figure@Caption%
444 % \end{macrocode}
445 % All local commands are undefined in order to save \TeX{} memory.
446 % \begin{macrocode}
447 \let\Mk@Figure@Caption\undefined%
448 \let\SubFig@Label=\relax%
449 \let\\=\@Figure@CR%
450 \let\@Figure@CR\undefined%
451 % \end{macrocode}
452 % The standard ``|figure|'' environment is closed.
453 % \begin{macrocode}
454 \endfigure%
455 % \end{macrocode}
456 % The command ``|\thesubfigure|'' is redefined so that it correctly
457 % prints the figure number, too.
458 % \begin{macrocode}
459 \def\thesubfigure{\thefigure\alph{subfigure}}%
460 }
461 % \end{macrocode}
462 % \end{environment}
463 %
464 % \begin{macro}{\@Figure@quadra}
465 % The ``|\MK@Figure@Caption|'' is defined to print the specified
466 % caption with an added label.
467 % Also ``|\SubFig@Label|'' generates a label in the form ``|<label>:a|''.
468 % \begin{macrocode}
469 %%
470 \def\@Figure@quadra#1[#2]{%
471 \def\MK@Figure@Caption{\caption{#1}\label{#2}}%
472 \def\SubFig@Label{\expandafter\label{#2:\expandafter\alph{subfigure}}}%
473 }
474 % \end{macrocode}
475 % \end{macro}
476 %
477 %\iffalse % MetaComment
478 %<*package>
479 %\fi
480 %
481 % \CheckSum{214}
482 % \Finale
483 %
484 \endinput
485