Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % %%----------------------------------------------------------------------------
3 %
4 %% File: photo.dtx Copyright 1994 1998 1999 Volker Kuhlmann
5 %% All rights are reserved.
6 %%
7 %
8 %<*dtx>
9 \ProvidesFile{photo.dtx}
10 %</dtx>
11 %<package>\NeedsTeXFormat{LaTeX2e}[1998/06/01]
12 %<package>\ProvidesPackage{photo}
13 %<driver> \ProvidesFile{photo.drv}
14 %
15 % \fi
16 % \ProvidesFile{photo.dtx}
17 [2004/07/15 v2.1f Placing photos in documents (VK)]
18 %
19 %%
20 %% \CharacterTable
21 %% {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
22 %% 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
23 %% Digits \0\1\2\3\4\5\6\7\8\9
24 %% Exclamation \! Double quote \" Hash (number) \#
25 %% Dollar \$ Percent \% Ampersand \&
26 %% Acute accent \' Left paren \( Right paren \)
27 %% Asterisk \* Plus \+ Comma \,
28 %% Minus \- Point \. Solidus \/
29 %% Colon \: Semicolon \; Less than \<
30 %% Equals \= Greater than \> Question mark \?
31 %% Commercial at \@ Left bracket \[ Backslash \\
32 %% Right bracket \] Circumflex \^ Underscore \_
33 %% Grave accent \` Left brace \{ Vertical bar \|
34 %% Right brace \} Tilde \~}
35 %%
36 % \iffalse
37 %
38 %<*driver>
39 %
40
41 \NeedsTeXFormat{LaTeX2e}[1994/12/01]
42 \documentclass{ltxdoc}
43 %\IfFileExists{ltxdoc.cfg}{}{\OnlyDescription\RecordChanges\CodelineIndex}
44
45 %\RecordChanges % for developing
46 %\CodelineIndex\EnableCrossrefs % for developing
47 \GetFileInfo{photo.dtx}
48
49 \begin{document}
50 \DocInput{photo.dtx}
51 %\IfFileExists{ltxdoc.cfg}{}{\PrintChanges\PrintIndex}
52 %\PrintChanges % for developing
53 %\PrintIndex % for developing
54 \end{document}
55
56 %</driver>
57 %
58 % \fi
59 %
60 % \GetFileInfo{photo.dtx}
61 % \CheckSum{522}
62 %
63 % \date{\filedate}
64 % \title{The \textsf{photo} package\thanks
65 % {This file has version number \fileversion,
66 % last revised \filedate.}}
67 % \author{Volker Kuhlmann\thanks{%^^A
68 % ^^AEmail:\ \url{[email protected]}}}
69 % Email:\ \url{[email protected]}}}
70 %
71 %
72 % \let\package\textsf
73 % \let\env\textsf
74 % \let\url\texttt
75 % \newcommand\optmeta[1]{[\meta{#1}]}
76 %
77 %
78 % \changes{v0.0}{1994/07/03}
79 % {TROG94.sty V3.0, Created out of TROG93.sty, V2.5, 20 Dec 93.}
80 %
81 % \changes{v1.0}{1998/07/20}
82 % {Created from TROG94.sty, V4.1, 07 Feb 95.}
83 %
84 % \changes{v1.1}{1998/07/21}
85 % {Changed args \cs{oephoto}. Environment OEphoto.}
86 %
87 % \changes{v1.1b}{1999/03/25}
88 % {Commented bug.}
89 %
90 % \changes{v2.0}{1999/06/15}
91 % {Added placements for photo, caption, photographer: \cs{putphoto}.
92 % Added \cs{phref}, \cs{Phref}.
93 % Introduced package options.}
94 %
95 % \changes{v2.00}{1999/06/16}
96 % {Put under the \LaTeX\ Project Public License (LPPL).}
97 %
98 % \changes{v2.1}{1999/06/17}
99 % {Added \cs{ifoddpagelabel}.}
100 %
101 % \changes{v2.1b}{1999/06/25}
102 % {Documentation. Commented out OEphoto-environment.}
103 %
104 % \changes{v2.1c}{1999/07/01}
105 % {Changed \cs{boxbasec} to avoid brace error in some cases.}
106 %
107 % \changes{v2.1d}{1999/07/27}
108 % {Put into docstrip format. First public release.}
109 %
110 % \changes{v2.1e}{2001/09/14}
111 % {Fixed \cs{phref}, \cs{Phref}.}
112 %
113 % \changes{v2.1f}{2004/07/15}
114 % {Changed email, packaged with PDF.}
115 %
116 %
117 % \maketitle
118 %
119 % \begin{abstract}
120 % This package introduces a new float type called photo which works
121 % similar to the float types table and figure. Various options exist for
122 % placing photos, captions, and a ``photographer'' line. In twocolumn
123 % documents, a possibility exists to generate double-column floats
124 % automatically if the photo does not fit into one column. Photos do not
125 % have to be placed as floats, they can also be placed as boxes, with
126 % captions and photographer line still being available.
127 %
128 % ^^A explain photographer line?
129 % ^^A explain captions shifted underneath automatically?
130 %
131 % \end{abstract}
132 %
133 % \tableofcontents
134 %
135 %
136 % \section{License}
137 %
138 % This package is copyright (C) 1994, 1998, 1999, 2001, 2004 by:
139 %
140 % \begin{quote}
141 % Volker Kuhlmann\\
142 % c/o University of Canterbury\\
143 % ELEC Dept, Creyke Road\\
144 % Christchurch, New Zealand\\
145 % E-Mail: \url{[email protected]}
146 % ^^AE-Mail: \url{[email protected]}
147 % \end{quote}
148 %
149 % This software can be redistributed and/or modified under the terms
150 % of the LaTeX Project Public License, distributed from CTAN
151 % archives as \url{macros/latex/base/lppl.txt}; either
152 % version 1 of the License, or (at your option) any later version.
153 %
154 %
155 % \section{User manual}
156 %
157 % \subsection{Introduction}
158 %
159 % The \package{photo} package allows photos to be inserted into
160 % documents, taking care of a variety of caption positions and a
161 % ``photographer'' line. By default captions are placed next to the
162 % photo, but they will be put underneath automatically if there is not
163 % enough space left next to the photo. Both caption and photographer
164 % line are optional and can be left empty.
165 %
166 % The photographer line is a short piece of text printed in small print
167 % close to the photo, which can e.g.\ be used to give the name of the
168 % person who took the photo, or the filename.
169 %
170 % A command and an environment are provided to place a photo with caption
171 % and photographer line, resulting in either a box (the photo will appear
172 % at the same place as the placement command in the document), or in a
173 % float.
174 %
175 % A new photo float is defined, which behaves like the existing table and
176 % figure floats.
177 %
178 % The provided file \url{photo\_test.tex} is a test file for the
179 % \package{photo} package. It also shows its various capabilities and
180 % can serve as an example.
181 %
182 %
183 % \subsection{Package options}
184 %
185 % The following package options are defined.
186 %
187 % \begin{description}
188 % \item[shortlof]
189 % The list of photos is typeset with a parskip of 0 (plus a little
190 % stretch). This is useful for documents using a non-zero parskip.
191 % It saves having to put |\listofphotos| inside a group with a
192 % zero-parskip setting. This problem is the same for
193 % |\tableofcontents|, |\listoftables|, |\listoffigures| by the way.
194 % \end{description}
195 %
196 % The caption is placed beside the photo by default, the side can be
197 % selected by one of:
198 % \begin{description}
199 % \item[left]
200 % Place the photo on the left.
201 % \item[right]
202 % Place the photo on the right.
203 % \item[in]
204 % Place the photo on the inside, this is the left on odd pages and
205 % the right on even pages.
206 % \item[out]
207 % Place the photo on the outside, this is the right on odd pages
208 % and the left on even pages. (default)
209 % \end{description}
210 %
211 % The vertical placement for captions which are beside the photo can be
212 % one of
213 % \begin{description}
214 % \item[top]
215 % The top of the caption is aligned with the top of the photo.
216 % \item[center]
217 % The centre of the caption is aligned with the centre of the
218 % photo. (default)
219 % \item[bottom]
220 % The bottom of the caption is aligned with the bottom of the
221 % photo.
222 % \end{description}
223 %
224 % The photographer or attribution line can be placed in either one of
225 % these positions:
226 % \begin{description}
227 % \item[under]
228 % Underneath the photo. (default)
229 % \item[side]
230 % Beside the photo.
231 % \end{description}
232 %
233 % If options bottom and side are in effect, the text placed by them
234 % might collide because there is not enough space for both. Choose
235 % different places for either of these 2 texts. The same can happen with
236 % center and top if the height of the caption text comes close to the
237 % height of the photo.
238 %
239 %
240 % \subsection{Provide a conditional test for an odd/even page}
241 %
242 % When captions are placed next to photos, we often need to know whether
243 % the photo will end up on an odd or even page. A general-purpose macro
244 % is provided which works similar to |\@ifundefined|.
245 % \DescribeMacro{\ifoddpage}
246 % \begin{quote}
247 % |\ifoddpage|[\meta{label}]|{|\meta{yes}|}{|\meta{no}|}|
248 % \end{quote}
249 % Expands to \meta{yes} if it is on an odd page, otherwise to \meta{no}.
250 %
251 % \DescribeMacro{\ifoddpagelabel}
252 % A label is required for this to work; if none is given one is created.
253 % Whatever label is used, it is stored in |\ifoddpagelabel|, which allows
254 % this label to be re-used with another |\ifoddpage| if it belongs to the
255 % same object. This might reduce the number of labels used. |\ifoddpage|
256 % only gives a correct answer if the document is compiled at least twice
257 % (because it uses |\label{}|).
258 %
259 %
260 % \subsection{Vertical box alignment}
261 %
262 % These macros put their argument into an hbox, and vertically shift the
263 % baseline of the box to the top edge, center, or bottom edge of the
264 % box. By default, the \TeX\ box-commands |\vtop| and |\vbox| align the
265 % baseline of the box on the baseline of the top or bottom line
266 % contained in the box, which is also very useful but does not visually
267 % line up things for the \package{photo} package.
268 % \DescribeMacro{\boxbaset}
269 % \DescribeMacro{\boxbasec}
270 % \DescribeMacro{\boxbaseb}
271 % \begin{quote}
272 % |\boxbaset{|\meta{LR-material}|}|\\
273 % |\boxbasec{|\meta{LR-material}|}|\\
274 % |\boxbaseb{|\meta{LR-material}|}|
275 % \end{quote}
276 % The \package{photo} package needs these in various places, but they are
277 % general-purpose and also otherwise useful. Note that the argument may
278 % only consist of LR-material.
279 %
280 %
281 % \subsection{Defining a new float type for photos}
282 %
283 % A new float type is defined for photos, which behaves in a similar way
284 % to the figure and table floats.
285 % \DescribeEnv{photo}
286 % \DescribeEnv{photo*}
287 % \begin{quote}
288 % |\begin{photo}|[\meta{floatpos}]\\
289 % |\begin{photo*}|[\meta{floatpos}]
290 % \end{quote}
291 %
292 % The star-form gives a double-column float in a twocolumn document,
293 % otherwise it is the same as the starless form. The optional
294 % \meta{floatpos} argument is the float placement specifier \meta{pos}
295 % as described in the \LaTeX-manual. Its default is the same as for
296 % figure and table: tbp.
297 %
298 % \DescribeMacro{\defaultphotoplacement}
299 % To change the default float placement specifier for photos, use:
300 % \begin{quote}
301 % |\defaultphotoplacement{|\meta{floatpos}|}|
302 % \end{quote}
303 % This affects photo floats only, and will be active for the photo float
304 % placed next. It can be changed any time, but to change the placement
305 % for a single float the \meta{floatpos} argument would be more convenient.
306 %
307 % \DescribeMacro{\thephoto}
308 % \DescribeMacro{\photoname}
309 % \DescribeMacro{\listphotoname}
310 % The counter defined for numbering photos is |photo|, its value can be
311 % obtained in the currently set numbering format with |\thephoto|. The
312 % macros |\photoname| and |\listphotoname| contain the respective texts
313 % for adaptations to non-english languages.
314 %
315 % \DescribeMacro{\listofphotos}
316 % A list of photos can be obtained with |\listofphotos|.
317 %
318 %
319 % \subsection{Placing a photo in the document}
320 %
321 % ^^A\putphoto[PHOTOPOS]{LABEL}{PHOTOGRAPHER}{PHOTO}[TOC-CAPTION]{CAPTION}
322 %
323 % \DescribeMacro{\putphoto}
324 % This command places a photo together with a caption and a photographer
325 % name. |\putphoto| produces a paragraph of boxes, not a float! The
326 % syntax is
327 % \begin{quote}
328 % |\putphoto|\optmeta{photopos}|{|\meta{label}|}|\\
329 % \hspace*{3em}|{|\meta{photographer}|}{|\meta{photo}|}|^^A
330 % \optmeta{toc-caption}|{|\meta{caption}|}|
331 % \end{quote}
332 %
333 % \meta{photopos} is an optional placement specification for the photo,
334 % the caption, and the photographer line. It overrides, for this photo
335 % only, the default arrangement as specified by the package options. Up to
336 % one letter of each of the three groups |l, r, i, o| (left, right, in,
337 % out), |t, c, b| (top, center, bottom), and |u, s| (under, side) may be
338 % given. If \meta{photopos} is given, it may not be empty \emph{is this
339 % true?}.
340 %
341 % \meta{label} is the cross-reference key for this photo. If no
342 % \meta{label} is given but |\putphoto| finds it needs one, it will
343 % create one itself.
344 %
345 % \meta{photographer} is the text for the photographer line, which must
346 % be LR-material. If it is empty, no such line will be printed.
347 %
348 % \meta{photo} is the photo itself, which must be LR-material and
349 % typically is an |\includegraphics| command.
350 %
351 % \meta{toc-caption} and \meta{caption} are the caption for this photo,
352 % and the text for the list of photos if different from the caption.
353 % This works the same as |\caption|. If the \meta{caption} argument is
354 % empty, no caption (and no entry in the |\listofphotos|) will be
355 % generated.
356 %
357 % \DescribeMacro{\oecaptionsep}
358 % \DescribeMacro{\minoecaptionwidth}
359 % The placement of captions beside the photo is controlled by these two
360 % dimensions. A horizontal space of |\oecaptionsep| is inserted between
361 % the caption and the photo. The width of the caption is the remaining
362 % space after the width of the photo and |\oecaptionsep| have been taken
363 % off. If less than |\minoecaptionwidth| is left, the caption will be put
364 % underneath the photo instead.
365 %
366 % \DescribeMacro{\photographerfont}
367 % The font selection command selecting the font in which
368 % \meta{photographer} will be printed. It defaults to a tiny sans-serif.
369 %
370 % The result of |\putphoto| is a paragraph (or two) containing various
371 % boxes. (Would it be better if it resulted in a single box?)
372 %
373 %
374 % \subsection{Placing a photo in the document as float}
375 %
376 % ^^A\begin{Photo}[PHOTOPOS]{LABEL}{PHOTOGRAPHER}[TOC-CAPTION]{CAPTION}
377 % ^^APHOTO (LR material only!)
378 % ^^A\end{Photo}
379 %
380 % \DescribeEnv{Photo}
381 % Instead of contributing text material, this environment produces a
382 % float (either |photo| or |photo*|). The syntax is very similar to
383 % |\putphoto|, except the photo body now comes from the content of the
384 % environment.
385 %
386 % \begin{quote}
387 % |\begin{Photo}|[\meta{photopos}]|{|\meta{label}|}|\\
388 % \hspace*{3em}|{|\meta{photographer}|}|^^A
389 % [\meta{toc-caption}]|{|\meta{caption}|}|\\
390 % \meta{photo}\\
391 % |\end{Photo}|
392 % \end{quote}
393 %
394 % All arguments behave the same as for |\putphoto|. The body of the
395 % \env{Photo} environment must be LR-material. |\oecaptionsep| and
396 % |\minoecaptionwidth| apply, if those two plus the width of the photo
397 % exceed |\columnwidth| in two-column documents, the \env{photo*}
398 % environment is called, otherwise \env{photo}. \env{Photo} uses
399 % |\putphoto| to do the work.
400 %
401 % Note that the \meta{photopos} argument of the \env{Photo} environment
402 % has nothing to do with the \meta{floatpos} argument of the \env{photo}
403 % and \env{photo*} environments. There is currently no way to specify a
404 % \meta{floatpos} with \env{Photo}.
405 %
406 %
407 % \subsection{Cross-referencing}
408 %
409 % \DescribeMacro{\phref}
410 % \DescribeMacro{\Phref}
411 % Works as usual. The shortcuts |\phref{|\meta{refkey}|}| and
412 % |\Phref{|\meta{refkey}|}| might save a little typing. They work like
413 % |\ref|, but also print ``photo'' resp.\ ``Photo''.
414 %
415 %
416 % \subsection{Problems / Limitations}
417 %
418 % \begin{itemize}
419 % \item
420 % Mixing the |\putphoto| command with the |\begin{Photo}|
421 % environment can severely mix up the order of the photos in the
422 % document. Even the |\listofphotos| may not be in order!! \LaTeX\
423 % isn't designed to handle this case, there is probably nothing
424 % that can be done about this. Don't mix the two in the same
425 % document (though ensuring all photo floats are written out
426 % before using |\putphoto| seems to be safe).
427 % \item
428 % |\Phref| does not use |\photoname| (how do I uppercase a first
429 % letter only?).
430 % \item
431 % There is currently no way to specify a \meta{floatpos} with
432 % \env{Photo}.
433 % \item
434 % It should be possible to revert back to the \LaTeX-default of
435 % placing captions underneath.
436 % \end{itemize}
437 %
438 %
439 % \subsection{To do}
440 %
441 % \begin{itemize}
442 % \item
443 % Check what happens if \meta{photopos} is given but empty.
444 % \item
445 % Give option of setting the caption above the photo.
446 % \end{itemize}
447 %
448 %
449 % \DoNotIndex{\@@t,\@CAP,\@CAPf,\@CPOS,\@CPOSdflt,\@LAB,\@OEPOS}
450 % \DoNotIndex{\@OEPOSdflt,\@PGR,\@POS@DFLT,\@PPOS,\@PPOSdflt,\@TCAP}
451 % \DoNotIndex{\@TCAPf,\@arabic,\@captype,\@dblarg,\@dblfloat}
452 % \DoNotIndex{\@dottedtocline,\@float,\@ifundefined,\@mkboth}
453 % \DoNotIndex{\@secondoftwo,\@starttoc,\@tempa,\@tempb,\@tfor}
454 % \DoNotIndex{\abovecaptionskip,\advance,\begin,\begingroup}
455 % \DoNotIndex{\belowcaptionskip,\box,\c@photo,\cap@width,\caption}
456 % \DoNotIndex{\centering,\chapter,\columnwidth,\csname}
457 % \DoNotIndex{\DeclareOption,\def,\depth,\dimen,\do,\edef,\else}
458 % \DoNotIndex{\empty,\end,\end@dblfloat,\end@float,\endcsname}
459 % \DoNotIndex{\endgroup,\ExecuteOptions,\expandafter,\ext@photo,\fi}
460 % \DoNotIndex{\fnum@photo,\fps@photo,\ftype@photo,\global,\hbox}
461 % \DoNotIndex{\height,\hskip,\if,\if@twocolumn,\ifdim,\ifodd,\ifx}
462 % \DoNotIndex{\l@photo,\label,\leavevmode,\llap,\lop@parskip}
463 % \DoNotIndex{\MakeUppercase,\newbox,\newcommand,\newcount}
464 % \DoNotIndex{\newcounter,\newdimen,\newenvironment,\newline,\oe@box}
465 % \DoNotIndex{\oe@labcnt,\oe@temp,\PackageError,\pageref,\par}
466 % \DoNotIndex{\parbox,\parskip,\photo@caption,\Photo@ii,\photo@lift}
467 % \DoNotIndex{\photo@scap,\photo@ucap,\ProcessOptions,\protect}
468 % \DoNotIndex{\putphoto@ii,\raggedleft,\raisebox,\ref,\renewcommand}
469 % \DoNotIndex{\rlap,\romannumeral,\section,\setbox,\sffamily}
470 % \DoNotIndex{\textwidth,\thephoto,\tiny,\totalheight,\typeout,\wd,\z@}
471 %
472 % \StopEventually{}
473 %
474 %
475 %
476 % \section{Implementation}
477 % \begin{macrocode}
478 %<*package>
479 % \end{macrocode}
480 %
481 %
482 % \subsection{Package options}
483 %
484 % Reduce parskip for list of photos
485 % \begin{macrocode}
486 \DeclareOption{shortlop}{\newcommand\lop@parskip{\parskip 0ex plus0.03ex}}
487 % \end{macrocode}
488 % Photo placement
489 % \begin{macrocode}
490 \DeclareOption{left}{\def\@OEPOSdflt{l}}
491 \DeclareOption{right}{\def\@OEPOSdflt{r}}
492 \DeclareOption{in}{\def\@OEPOSdflt{i}}
493 \DeclareOption{out}{\def\@OEPOSdflt{o}}
494 % \end{macrocode}
495 % Vertical caption placement
496 % \begin{macrocode}
497 \DeclareOption{top}{\def\@CPOSdflt{t}}
498 \DeclareOption{center}{\def\@CPOSdflt{c}}
499 \DeclareOption{bottom}{\def\@CPOSdflt{b}}
500 % \end{macrocode}
501 % Photographer line placement
502 % \begin{macrocode}
503 \DeclareOption{under}{\def\@PPOSdflt{u}}
504 \DeclareOption{side}{\def\@PPOSdflt{s}}
505 % \end{macrocode}
506 %
507 %
508 % \subsection{Option default and processing}
509 %
510 % \begin{macrocode}
511 %\edef\@POS@DFLT{\@OEPOSdflt\@CPOSdflt\@PPOSdflt}
512 \ExecuteOptions{out,center,under}
513 \ProcessOptions
514 % \end{macrocode}
515 %
516 %
517 % \subsection{A conditional test for an odd/even page}
518 %
519 % \begin{macro}{\ifoddpage}
520 % Like |\@ifundefined|, but test whether page is odd.
521 % If no label is supplied, one is made up. Whichever label is used is returned
522 % in |\ifoddpagelabel|, so a made-up label can be reused.
523 % Thanks to David Carlisle \url{[email protected]} for getting me on
524 % track for deciding whether we are on an odd or even page.
525 % \begin{macrocode}
526 \newcount\oe@labcnt
527 \newcommand\ifoddpage[3][]{%
528 % make a label if none given
529 \edef\ifoddpagelabel{#1}%
530 \ifx\ifoddpagelabel\empty
531 \global\advance\oe@labcnt 1%
532 \edef\ifoddpagelabel{oelbl@\romannumeral\oe@labcnt}%
533 %\typeout{empty label: using \ifoddpagelabel}%
534 \label\ifoddpagelabel
535 \fi
536 % execute either YES or NO
537 %\typeout{\ifoddpagelabel, 0\pageref{\ifoddpagelabel},
538 % r@\ifoddpagelabel, \csname r@\ifoddpagelabel\endcsname,
539 % \page@ref@@\ifoddpagelabel}%
540 %\ifodd0\pageref{\ifoddpagelabel}\def\oe@temp{#2}\else\def\oe@temp{#3}\fi
541 \ifodd0\page@ref@@\def\oe@temp{#2}\else\def\oe@temp{#3}\fi
542 \oe@temp
543 }
544 % \end{macrocode}
545 % \end{macro}
546 % \begin{macro}{\page@ref@@}
547 % The \package{babel} package |\protect|'s |\pageref|, which then becomes
548 % useless for |\ifodd|. We emulate the original unprotected definition
549 % of the \LaTeX\ kernel (is there a better solution?).
550 % \begin{macrocode}
551 \newcommand\page@ref@@{\expandafter\expandafter\expandafter
552 \@secondoftwo\csname r@\ifoddpagelabel\endcsname}
553 % \end{macrocode}
554 % \end{macro}
555 %
556 %
557 % \subsection{Vertical box alignment}
558 %
559 % Shift the baseline of the argument to the top edge, center, bottom edge
560 % respectively.
561 % \begin{macrocode}
562 \newcommand\boxbaset{\raisebox{-\height}}
563 \newcommand\boxbaseb{\raisebox{\depth}}
564 \newcommand\boxbasec[1]{\raisebox{-0.5\totalheight}{\boxbaseb{#1}}}
565 % \end{macrocode}
566 %
567 %
568 % \subsection{A new float type for photos}
569 %
570 % A new float type. As for figures and tables.
571 %
572 % counter, names, file extension, default placement
573 % \begin{macrocode}
574 \newcounter{photo}
575 \renewcommand\thephoto{\@arabic\c@photo}
576 \newcommand\photoname{Photo}
577 \newcommand\listphotoname{List of Photos}
578 \def\fps@photo{tbp}
579 \def\ftype@photo{4}
580 \def\ext@photo{lop}
581 \def\fnum@photo{\photoname~\thephoto}
582 % \end{macrocode}
583 % The default photo placement can be changed with this command:
584 % \begin{macrocode}
585 \newcommand\defaultphotoplacement[1]{\def\fps@photo{#1}}
586 % \end{macrocode}
587 % single-column float
588 % \begin{macrocode}
589 \newenvironment{photo}%
590 {\@float{photo}}%
591 {\end@float}
592 % \end{macrocode}
593 % double-column float
594 % \begin{macrocode}
595 \newenvironment{photo*}%
596 {\@dblfloat{photo}}%
597 {\end@dblfloat}
598 % \end{macrocode}
599 % Generate a list of photos.
600 % For the list of photos we need to take care of the document class.
601 % Do a crude job and use |\chapter| if it is defined, |\section| otherwise.
602 % \begin{macrocode}
603 \newcommand\listofphotos{%
604 \begingroup
605 \csname lop@parskip\endcsname
606 \@ifundefined{chapter}{\section}{\chapter}*{\listphotoname
607 \@mkboth{\MakeUppercase\listphotoname}%
608 {\MakeUppercase\listphotoname}}%
609 \@starttoc{\ext@photo}%
610 \endgroup
611 }
612 % \end{macrocode}
613 % A table-of-contents entry.
614 % \begin{macrocode}
615 \newcommand*\l@photo{\@dottedtocline{1}{1.5em}{2.3em}}
616 % \end{macrocode}
617 %
618 %
619 % \subsection{Command for placing a photo}
620 %
621 % declare some variables
622 % \begin{macrocode}
623 \newdimen\oecaptionsep
624 \newdimen\minoecaptionwidth
625 \newbox\oe@box
626 \oecaptionsep 10mm
627 \minoecaptionwidth 35mm
628 \newcommand\photographerfont{\tiny\sffamily}
629 % \end{macrocode}
630 %
631 % \begin{macro}{\putphoto}
632 % This command places a photo into the document. It does not produce a
633 % float!
634 % \begin{macrocode}
635 \newcommand\putphoto[4][\@OEPOSdflt\@CPOSdflt\@PPOSdflt]{%
636 \par
637 \begingroup
638 \edef\@OEPOS{#1}\edef\@LAB{#2}\def\@PGR{#3}%
639 \setbox\oe@box\hbox{#4}%
640 \putphoto@ii
641 }
642 % \end{macrocode}
643 % \end{macro}
644 % \begin{macrocode}
645 \newcommand*\putphoto@ii[2][]{%
646 \def\@TCAP{#1}\def\@CAP{#2}%
647 %
648 \def\@captype{photo}% make (photo-)\caption available outside float
649 %
650 \def\cap@width{\dimen0}% shortcut - w/o introducing a new variable
651 %
652 % process placement info
653 \def\@CPOS{\@CPOSdflt}\def\@PPOS{\@PPOSdflt}%
654 %\typeout{photo pos: ... \@OEPOS, \@PPOS, \@CPOS}%
655 \def\@tempb{\@tfor\@tempa:=}%
656 \expandafter\@tempb\@OEPOS\do{%
657 %\typeout{loop: \@tempa}
658 \if l\@tempa \def\@OEPOS{l}\else
659 \if r\@tempa \def\@OEPOS{r}\else
660 \if i\@tempa \ifx\@PGR\empty\else
661 \ifoddpage[\@LAB]{\def\@OEPOS{l}}{\def\@OEPOS{r}}\fi\else
662 \if o\@tempa \ifx\@PGR\empty\else
663 \ifoddpage[\@LAB]{\def\@OEPOS{r}}{\def\@OEPOS{l}}\fi\else
664 \if u\@tempa \def\@PPOS{u}\else
665 \if s\@tempa \def\@PPOS{s}\else
666 \if t\@tempa \def\@CPOS{t}\else
667 \if c\@tempa \def\@CPOS{c}\else
668 \if b\@tempa \def\@CPOS{b}\else
669 \PackageError{photo}{illegal pos: \@tempa}{}%
670 \fi\fi\fi\fi\fi\fi\fi\fi\fi}%
671 %\typeout{photo pos: ==> \@OEPOS, \@PPOS, \@CPOS}%
672 %
673 % calculate width available for caption:
674 \cap@width\columnwidth
675 \advance\cap@width-\wd\oe@box \advance\cap@width-\oecaptionsep
676 %
677 % place caption beside photo if there is enough space left, underneath
678 % otherwise:
679 \ifdim\minoecaptionwidth>\cap@width\photo@ucap\else\photo@scap\fi
680 \endgroup
681 }
682 % \end{macrocode}
683 % photo with caption underneath
684 % \begin{macrocode}
685 \newcommand\photo@ucap{%
686 \begingroup
687 \centering\parbox{\wd\oe@box}{%
688 \leavevmode\box\oe@box
689 \ifx\@PGR\empty\else
690 \newline\photographerfont
691 \if r\@OEPOS \raggedleft \fi
692 \@PGR
693 \fi
694 }\par
695 \endgroup
696 \photo@caption
697 }
698 % \end{macrocode}
699 % photo with caption beside
700 % \begin{macrocode}
701 \newcommand\photo@scap{%
702 \abovecaptionskip\z@
703 \belowcaptionskip\z@
704 \leavevmode
705 \ifx\@PGR\empty\else\if s\@PPOS \if r\@OEPOS
706 \rlap{\boxbaseb{\parbox{\cap@width}{%
707 \photographerfont\raggedleft\@PGR}}}\fi\fi\fi
708 \boxbaseb{%
709 \if l\@OEPOS
710 \photo@lift{\wd\oe@box}{\box\oe@box}\hskip\oecaptionsep
711 \photo@lift\cap@width\photo@caption
712 \else
713 \photo@lift\cap@width\photo@caption\hskip\oecaptionsep
714 \photo@lift{\wd\oe@box}{\box\oe@box}%
715 \fi
716 }%
717 \ifx\@PGR\empty\else
718 \if u\@PPOS
719 \newline\photographerfont\if r\@OEPOS \raggedleft \fi\@PGR
720 \else\if l\@OEPOS
721 \llap{\boxbaseb{\parbox{\cap@width}{\photographerfont\@PGR}}}\fi
722 \fi
723 \fi
724 \par
725 }
726 % \end{macrocode}
727 % This creates a parbox, with its baseline shifted to the top edge /
728 % centre / bottom edge.
729 % \begin{macrocode}
730 \newcommand\photo@lift[2]{%
731 %\if t\@CPOS \raisebox{-\height}{\parbox{#1}{#2}}\else
732 %\if b\@CPOS \raisebox{\depth}{\parbox{#1}{#2}}\else
733 %\raisebox{-0.5\totalheight}{\raisebox{\depth}{\parbox{#1}{#2}}}\fi\fi
734 \csname boxbase\@CPOS\endcsname{\parbox{#1}{#2}}%
735 }
736 % \end{macrocode}
737 % Set the caption, within the provided width.
738 % \begin{macrocode}
739 \newcommand\photo@caption{%
740 \ifx\@CAP\empty\else
741 \ifx\@TCAP\empty
742 \caption{\@CAP}\else
743 \caption[\@TCAP]{\@CAP}\fi
744 \ifx\@LAB\empty\else\label\@LAB\fi
745 \fi
746 }
747 % \end{macrocode}
748 %
749 %
750 % \subsection{Environment for placing a floating photo}
751 %
752 % ^^A\begin{macro}{Photo} ^^A This does not work for environments!
753 % This environment produces a photo float, single-column if possible or
754 % double-column otherwise. It uses |\putphoto|.
755 % \begin{macrocode}
756 \newenvironment{Photo}[3][\@OEPOSdflt\@CPOSdflt\@PPOSdflt]{%
757 \par
758 \begingroup
759 \edef\@OEPOS{#1}\edef\@LAB{#2}\def\@PGR{#3}%
760 %\Photo@ii
761 \@dblarg\Photo@ii
762 }{%
763 \end{lrbox}%
764 \def\@@t{photo}%
765 \if@twocolumn\ifdim\wd\oe@box>\columnwidth
766 % for this photo, the column width is effectively \textwidth
767 \def\@@t{photo*}\columnwidth\textwidth
768 \fi\fi
769 \expandafter\begin\expandafter{\@@t}%
770 \begingroup
771 \putphoto@ii[\@TCAPf]\@CAPf
772 \expandafter\end\expandafter{\@@t}%
773 \endgroup
774 }
775 % \end{macrocode}
776 % ^^A\end{macro}
777 % continue with part 2
778 % \begin{macrocode}
779 \newcommand\Photo@ii[2][]{%
780 \def\@TCAPf{#1}\def\@CAPf{#2}%
781 \begin{lrbox}\oe@box
782 }
783 % \end{macrocode}
784 %
785 %
786 % \subsection{Cross-referencing}
787 %
788 % The ``photo'' name shouldn't be hard-coded.
789 % \begin{macrocode}
790 \newcommand\phref[1]{photo~\ref{#1}}
791 \newcommand\Phref[1]{\photoname~\ref{#1}}
792 % \end{macrocode}
793 %
794 %
795 %
796 % \begin{macrocode}
797 %</package>
798 % \end{macrocode}
799 %
800 % \Finale
801 %
802 % \iffalse
803 % %% EOF photo.dtx
804 % %%----------------------------------------------------------------------------
805 % \fi