path: root/macros/latex/contrib/photo/photo.dtx

% \iffalse meta-comment
% %%----------------------------------------------------------------------------
%
%% File: photo.dtx Copyright 1994 1998 1999 Volker Kuhlmann
%% All rights are reserved.
%%
%
%<*dtx>
          \ProvidesFile{photo.dtx}
%</dtx>
%<package>\NeedsTeXFormat{LaTeX2e}[1998/06/01]
%<package>\ProvidesPackage{photo}
%<driver> \ProvidesFile{photo.drv}
%
% \fi
%         \ProvidesFile{photo.dtx}
       [2004/07/15 v2.1f Placing photos in documents (VK)]
%
%%
%% \CharacterTable
%%  {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
%%   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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
% \iffalse
%
%<*driver>
%

\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\documentclass{ltxdoc}
 %\IfFileExists{ltxdoc.cfg}{}{\OnlyDescription\RecordChanges\CodelineIndex}

 %\RecordChanges % for developing
 %\CodelineIndex\EnableCrossrefs % for developing
\GetFileInfo{photo.dtx}

\begin{document}
  \DocInput{photo.dtx}
  %\IfFileExists{ltxdoc.cfg}{}{\PrintChanges\PrintIndex}
  %\PrintChanges % for developing
  %\PrintIndex % for developing
\end{document}

%</driver>
%
% \fi
%
% \GetFileInfo{photo.dtx}
% \CheckSum{522}
%
% \date{\filedate}
% \title{The \textsf{photo} package\thanks
%        {This file has version number \fileversion,
%         last revised \filedate.}}
% \author{Volker Kuhlmann\thanks{%^^A
%         ^^AEmail:\ \url{v.kuhlmann@elec.canterbury.ac.nz}}}
%         Email:\ \url{VolkerKuhlmann@GMX.de}}}
%
%
% \let\package\textsf
% \let\env\textsf
% \let\url\texttt
% \newcommand\optmeta[1]{[\meta{#1}]}
%
%
% \changes{v0.0}{1994/07/03}
%    {TROG94.sty V3.0, Created out of TROG93.sty, V2.5, 20 Dec 93.}
%
% \changes{v1.0}{1998/07/20}
%    {Created from TROG94.sty, V4.1, 07 Feb 95.}
%
% \changes{v1.1}{1998/07/21}
%    {Changed args \cs{oephoto}. Environment OEphoto.}
%
% \changes{v1.1b}{1999/03/25}
%    {Commented bug.}
%
% \changes{v2.0}{1999/06/15}
%    {Added placements for photo, caption, photographer: \cs{putphoto}.
%     Added \cs{phref}, \cs{Phref}.
%     Introduced package options.}
%
% \changes{v2.00}{1999/06/16}
%    {Put under the \LaTeX\ Project Public License (LPPL).}
%
% \changes{v2.1}{1999/06/17}
%    {Added \cs{ifoddpagelabel}.}
%
% \changes{v2.1b}{1999/06/25}
%    {Documentation. Commented out OEphoto-environment.}
%
% \changes{v2.1c}{1999/07/01}
%    {Changed \cs{boxbasec} to avoid brace error in some cases.}
%
% \changes{v2.1d}{1999/07/27}
%    {Put into docstrip format. First public release.}
%
% \changes{v2.1e}{2001/09/14}
%    {Fixed \cs{phref}, \cs{Phref}.}
%
% \changes{v2.1f}{2004/07/15}
%    {Changed email, packaged with PDF.}
%
%
% \maketitle
%
% \begin{abstract}
% This package introduces a new float type called photo which works
% similar to the float types table and figure. Various options exist for
% placing photos, captions, and a ``photographer'' line. In twocolumn
% documents, a possibility exists to generate double-column floats
% automatically if the photo does not fit into one column. Photos do not
% have to be placed as floats, they can also be placed as boxes, with
% captions and photographer line still being available.
% 
% ^^A explain photographer line?
% ^^A explain captions shifted underneath automatically?
%
% \end{abstract}
%
% \tableofcontents
%
%
% \section{License}
%
% This package is copyright (C) 1994, 1998, 1999, 2001, 2004 by:
%
% \begin{quote}
%   Volker Kuhlmann\\
%   c/o University of Canterbury\\
%   ELEC Dept, Creyke Road\\
%   Christchurch, New Zealand\\
%   E-Mail: \url{VolkerKuhlmann@GMX.de}
%   ^^AE-Mail: \url{v.kuhlmann@elec.canterbury.ac.nz}
% \end{quote}
%
% This software can be redistributed and/or modified under the terms
% of the LaTeX Project Public License, distributed from CTAN
% archives as \url{macros/latex/base/lppl.txt}; either
% version 1 of the License, or (at your option) any later version.
%
%
% \section{User manual}
%
% \subsection{Introduction}
%
% The \package{photo} package allows photos to be inserted into
% documents, taking care of a variety of caption positions and a
% ``photographer'' line. By default captions are placed next to the
% photo, but they will be put underneath automatically if there is not
% enough space left next to the photo. Both caption and photographer
% line are optional and can be left empty.
%
% The photographer line is a short piece of text printed in small print
% close to the photo, which can e.g.\ be used to give the name of the
% person who took the photo, or the filename.
%
% A command and an environment are provided to place a photo with caption
% and photographer line, resulting in either a box (the photo will appear
% at the same place as the placement command in the document), or in a
% float.
%
% A new photo float is defined, which behaves like the existing table and
% figure floats.
%
% The provided file \url{photo\_test.tex} is a test file for the
% \package{photo} package. It also shows its various capabilities and
% can serve as an example.
%
%
% \subsection{Package options}
%
% The following package options are defined.
%
% \begin{description}
% \item[shortlof]
%	The list of photos is typeset with a parskip of 0 (plus a little
%	stretch). This is useful for documents using a non-zero parskip.
%	It saves having to put |\listofphotos| inside a group with a
%	zero-parskip setting. This problem is the same for
%	|\tableofcontents|, |\listoftables|, |\listoffigures| by the way.
% \end{description}
%
% The caption is placed beside the photo by default, the side can be
% selected by one of:
% \begin{description}
% \item[left]
% 	Place the photo on the left.
% \item[right]
% 	Place the photo on the right.
% \item[in]
% 	Place the photo on the inside, this is the left on odd pages and
% 	the right on even pages.
% \item[out]
% 	Place the photo on the outside, this is the right on odd pages
% 	and the left on even pages. (default)
% \end{description}
%
% The vertical placement for captions which are beside the photo can be
% one of
% \begin{description}
% \item[top]
%	The top of the caption is aligned with the top of the photo.
% \item[center]
%	The centre of the caption is aligned with the centre of the
%	photo. (default)
% \item[bottom]
%	The bottom of the caption is aligned with the bottom of the
%	photo.
% \end{description}
%
% The photographer or attribution line can be placed in either one of
% these positions:
% \begin{description}
% \item[under]
%	Underneath the photo. (default)
% \item[side]
%	Beside the photo.
% \end{description}
%
% If options bottom and side are in effect, the text placed by them
% might collide because there is not enough space for both. Choose
% different places for either of these 2 texts. The same can happen with
% center and top if the height of the caption text comes close to the
% height of the photo.
%
%
% \subsection{Provide a conditional test for an odd/even page}
%
% When captions are placed next to photos, we often need to know whether
% the photo will end up on an odd or even page. A general-purpose macro
% is provided which works similar to |\@ifundefined|.
% \DescribeMacro{\ifoddpage}
%    \begin{quote}
%    |\ifoddpage|[\meta{label}]|{|\meta{yes}|}{|\meta{no}|}|
%    \end{quote}
% Expands to \meta{yes} if it is on an odd page, otherwise to \meta{no}.
%
% \DescribeMacro{\ifoddpagelabel}
% A label is required for this to work; if none is given one is created.
% Whatever label is used, it is stored in |\ifoddpagelabel|, which allows
% this label to be re-used with another |\ifoddpage| if it belongs to the
% same object. This might reduce the number of labels used. |\ifoddpage|
% only gives a correct answer if the document is compiled at least twice
% (because it uses |\label{}|).
%
%
% \subsection{Vertical box alignment}
%
% These macros put their argument into an hbox, and vertically shift the
% baseline of the box to the top edge, center, or bottom edge of the
% box. By default, the \TeX\ box-commands |\vtop| and  |\vbox| align the
% baseline of the box on the baseline of the top or bottom line
% contained in the box, which is also very useful but does not visually
% line up things for the \package{photo} package.
% \DescribeMacro{\boxbaset}
% \DescribeMacro{\boxbasec}
% \DescribeMacro{\boxbaseb}
%    \begin{quote}
%    |\boxbaset{|\meta{LR-material}|}|\\
%    |\boxbasec{|\meta{LR-material}|}|\\
%    |\boxbaseb{|\meta{LR-material}|}|
%    \end{quote}
% The \package{photo} package needs these in various places, but they are
% general-purpose and also otherwise useful. Note that the argument may
% only consist of LR-material.
%
%
% \subsection{Defining a new float type for photos}
%
% A new float type is defined for photos, which behaves in a similar way
% to the figure and table floats.
% \DescribeEnv{photo}
% \DescribeEnv{photo*}
%    \begin{quote}
%    |\begin{photo}|[\meta{floatpos}]\\
%    |\begin{photo*}|[\meta{floatpos}]
%    \end{quote}
%
% The star-form gives a double-column float in a twocolumn document,
% otherwise it is the same as the starless form. The optional
% \meta{floatpos} argument is the float placement specifier \meta{pos}
% as described in the \LaTeX-manual. Its default is the same as for
% figure and table: tbp.
%
% \DescribeMacro{\defaultphotoplacement}
% To change the default float placement specifier for photos, use:
%    \begin{quote}
%    |\defaultphotoplacement{|\meta{floatpos}|}|
%    \end{quote}
% This affects photo floats only, and will be active for the photo float
% placed next. It can be changed any time, but to change the placement
% for a single float the \meta{floatpos} argument would be more convenient.
%
% \DescribeMacro{\thephoto}
% \DescribeMacro{\photoname}
% \DescribeMacro{\listphotoname}
% The counter defined for numbering photos is |photo|, its value can be
% obtained in the currently set numbering format with |\thephoto|. The
% macros |\photoname| and |\listphotoname| contain the respective texts
% for adaptations to non-english languages.
%
% \DescribeMacro{\listofphotos}
% A list of photos can be obtained with |\listofphotos|.
%
%
% \subsection{Placing a photo in the document}
%
% ^^A\putphoto[PHOTOPOS]{LABEL}{PHOTOGRAPHER}{PHOTO}[TOC-CAPTION]{CAPTION}
%
% \DescribeMacro{\putphoto}
% This command places a photo together with a caption and a photographer
% name. |\putphoto| produces a paragraph of boxes, not a float! The
% syntax is
%    \begin{quote}
%    |\putphoto|\optmeta{photopos}|{|\meta{label}|}|\\
%	\hspace*{3em}|{|\meta{photographer}|}{|\meta{photo}|}|^^A
%	\optmeta{toc-caption}|{|\meta{caption}|}|
%    \end{quote}
%
% \meta{photopos} is an optional placement specification for the photo,
% the caption, and the photographer line. It overrides, for this photo
% only, the default arrangement as specified by the package options. Up to
% one letter of each of the three groups |l, r, i, o| (left, right, in,
% out), |t, c, b| (top, center, bottom), and |u, s| (under, side) may be
% given. If \meta{photopos} is given, it may not be empty \emph{is this
% true?}.
%
% \meta{label} is the cross-reference key for this photo. If no
% \meta{label} is given but |\putphoto| finds it needs one, it will
% create one itself.
%
% \meta{photographer} is the text for the photographer line, which must
% be LR-material. If it is empty, no such line will be printed.
%
% \meta{photo} is the photo itself, which must be LR-material and
% typically is an |\includegraphics| command.
%
% \meta{toc-caption} and \meta{caption} are the caption for this photo,
% and the text for the list of photos if different from the caption.
% This works the same as |\caption|. If the \meta{caption} argument is
% empty, no caption (and no entry in the |\listofphotos|) will be
% generated.
%
% \DescribeMacro{\oecaptionsep}
% \DescribeMacro{\minoecaptionwidth}
% The placement of captions beside the photo is controlled by these two
% dimensions. A horizontal space of |\oecaptionsep| is inserted between
% the caption and the photo. The width of the caption is the remaining
% space after the width of the photo and |\oecaptionsep| have been taken
% off. If less than |\minoecaptionwidth| is left, the caption will be put
% underneath the photo instead.
%
% \DescribeMacro{\photographerfont}
% The font selection command selecting the font in which
% \meta{photographer} will be printed. It defaults to a tiny sans-serif.
%
% The result of |\putphoto| is a paragraph (or two) containing various
% boxes. (Would it be better if it resulted in a single box?)
%
%
% \subsection{Placing a photo in the document as float}
%
% ^^A\begin{Photo}[PHOTOPOS]{LABEL}{PHOTOGRAPHER}[TOC-CAPTION]{CAPTION}
% ^^APHOTO (LR material only!)
% ^^A\end{Photo}
%
% \DescribeEnv{Photo}
% Instead of contributing text material, this environment produces a
% float (either |photo| or |photo*|). The syntax is very similar to
% |\putphoto|, except the photo body now comes from the content of the
% environment.
%
% \begin{quote}
%    |\begin{Photo}|[\meta{photopos}]|{|\meta{label}|}|\\
%	\hspace*{3em}|{|\meta{photographer}|}|^^A
%	[\meta{toc-caption}]|{|\meta{caption}|}|\\
%    \meta{photo}\\
%    |\end{Photo}|
% \end{quote}
%
% All arguments behave the same as for |\putphoto|. The body of the
% \env{Photo} environment must be LR-material. |\oecaptionsep| and
% |\minoecaptionwidth| apply, if those two plus the width of the photo
% exceed |\columnwidth| in two-column documents, the \env{photo*}
% environment is called, otherwise \env{photo}. \env{Photo} uses
% |\putphoto| to do the work.
% 
% Note that the \meta{photopos} argument of the \env{Photo} environment
% has nothing to do with the \meta{floatpos} argument of the \env{photo}
% and \env{photo*} environments. There is currently no way to specify a
% \meta{floatpos} with \env{Photo}.
%
%
% \subsection{Cross-referencing}
%
% \DescribeMacro{\phref}
% \DescribeMacro{\Phref}
% Works as usual. The shortcuts |\phref{|\meta{refkey}|}| and
% |\Phref{|\meta{refkey}|}| might save a little typing. They work like
% |\ref|, but also print ``photo'' resp.\ ``Photo''.
%
%
% \subsection{Problems / Limitations}
%
% \begin{itemize}
% \item
%	Mixing the |\putphoto| command with the |\begin{Photo}|
%	environment can  severely mix up the order of the photos in the
%	document. Even the |\listofphotos| may not be in order!! \LaTeX\
%	isn't designed to handle this case, there is probably nothing
%	that can be done about this. Don't mix the two in the same
%	document (though ensuring all photo floats are written out
%	before using |\putphoto| seems to be safe).
% \item
%	|\Phref| does not use |\photoname| (how do I uppercase a first
%	letter only?).
% \item
%	There is currently no way to specify a \meta{floatpos} with
%	\env{Photo}.
% \item
%	It should be possible to revert back to the \LaTeX-default of
%	placing captions underneath.
% \end{itemize}
%
%
% \subsection{To do}
%
% \begin{itemize}
% \item
%	Check what happens if \meta{photopos} is given but empty.
% \item
%	Give option of setting the caption above the photo.
% \end{itemize}
%
%
% \DoNotIndex{\@@t,\@CAP,\@CAPf,\@CPOS,\@CPOSdflt,\@LAB,\@OEPOS}
% \DoNotIndex{\@OEPOSdflt,\@PGR,\@POS@DFLT,\@PPOS,\@PPOSdflt,\@TCAP}
% \DoNotIndex{\@TCAPf,\@arabic,\@captype,\@dblarg,\@dblfloat}
% \DoNotIndex{\@dottedtocline,\@float,\@ifundefined,\@mkboth}
% \DoNotIndex{\@secondoftwo,\@starttoc,\@tempa,\@tempb,\@tfor}
% \DoNotIndex{\abovecaptionskip,\advance,\begin,\begingroup}
% \DoNotIndex{\belowcaptionskip,\box,\c@photo,\cap@width,\caption}
% \DoNotIndex{\centering,\chapter,\columnwidth,\csname}
% \DoNotIndex{\DeclareOption,\def,\depth,\dimen,\do,\edef,\else}
% \DoNotIndex{\empty,\end,\end@dblfloat,\end@float,\endcsname}
% \DoNotIndex{\endgroup,\ExecuteOptions,\expandafter,\ext@photo,\fi}
% \DoNotIndex{\fnum@photo,\fps@photo,\ftype@photo,\global,\hbox}
% \DoNotIndex{\height,\hskip,\if,\if@twocolumn,\ifdim,\ifodd,\ifx}
% \DoNotIndex{\l@photo,\label,\leavevmode,\llap,\lop@parskip}
% \DoNotIndex{\MakeUppercase,\newbox,\newcommand,\newcount}
% \DoNotIndex{\newcounter,\newdimen,\newenvironment,\newline,\oe@box}
% \DoNotIndex{\oe@labcnt,\oe@temp,\PackageError,\pageref,\par}
% \DoNotIndex{\parbox,\parskip,\photo@caption,\Photo@ii,\photo@lift}
% \DoNotIndex{\photo@scap,\photo@ucap,\ProcessOptions,\protect}
% \DoNotIndex{\putphoto@ii,\raggedleft,\raisebox,\ref,\renewcommand}
% \DoNotIndex{\rlap,\romannumeral,\section,\setbox,\sffamily}
% \DoNotIndex{\textwidth,\thephoto,\tiny,\totalheight,\typeout,\wd,\z@}
%
% \StopEventually{}
%
%
%
% \section{Implementation}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
%
% \subsection{Package options}
%
% Reduce parskip for list of photos
%    \begin{macrocode}
\DeclareOption{shortlop}{\newcommand\lop@parskip{\parskip 0ex plus0.03ex}}
%    \end{macrocode}
% Photo placement
%    \begin{macrocode}
\DeclareOption{left}{\def\@OEPOSdflt{l}}
\DeclareOption{right}{\def\@OEPOSdflt{r}}
\DeclareOption{in}{\def\@OEPOSdflt{i}}
\DeclareOption{out}{\def\@OEPOSdflt{o}}
%    \end{macrocode}
% Vertical caption placement
%    \begin{macrocode}
\DeclareOption{top}{\def\@CPOSdflt{t}}
\DeclareOption{center}{\def\@CPOSdflt{c}}
\DeclareOption{bottom}{\def\@CPOSdflt{b}}
%    \end{macrocode}
% Photographer line placement
%    \begin{macrocode}
\DeclareOption{under}{\def\@PPOSdflt{u}}
\DeclareOption{side}{\def\@PPOSdflt{s}}
%    \end{macrocode}
%
%
% \subsection{Option default and processing}
%
%    \begin{macrocode}
%\edef\@POS@DFLT{\@OEPOSdflt\@CPOSdflt\@PPOSdflt}
\ExecuteOptions{out,center,under}
\ProcessOptions
%    \end{macrocode}
%
%
% \subsection{A conditional test for an odd/even page}
%
% \begin{macro}{\ifoddpage}
% Like |\@ifundefined|, but test whether page is odd.
% If no label is supplied, one is made up. Whichever label is used is returned
% in |\ifoddpagelabel|, so a made-up label can be reused.
% Thanks to David Carlisle \url{carlisle@cs.man.ac.uk} for getting me on
% track for deciding whether we are on an odd or even page.
%    \begin{macrocode}
\newcount\oe@labcnt
\newcommand\ifoddpage[3][]{%
	% make a label if none given
	\edef\ifoddpagelabel{#1}%
	\ifx\ifoddpagelabel\empty
		\global\advance\oe@labcnt 1%
		\edef\ifoddpagelabel{oelbl@\romannumeral\oe@labcnt}%
		%\typeout{empty label: using \ifoddpagelabel}%
		\label\ifoddpagelabel
	\fi
	% execute either YES or NO
	%\typeout{\ifoddpagelabel, 0\pageref{\ifoddpagelabel},
	%	 r@\ifoddpagelabel, \csname r@\ifoddpagelabel\endcsname,
	%	 \page@ref@@\ifoddpagelabel}%
	%\ifodd0\pageref{\ifoddpagelabel}\def\oe@temp{#2}\else\def\oe@temp{#3}\fi
	\ifodd0\page@ref@@\def\oe@temp{#2}\else\def\oe@temp{#3}\fi
	\oe@temp
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\page@ref@@}
% The \package{babel} package |\protect|'s |\pageref|, which then becomes
% useless for |\ifodd|. We emulate the original unprotected definition
% of the \LaTeX\ kernel (is there a better solution?).
%    \begin{macrocode}
\newcommand\page@ref@@{\expandafter\expandafter\expandafter
			\@secondoftwo\csname r@\ifoddpagelabel\endcsname}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Vertical box alignment}
%
% Shift the baseline of the argument to the top edge, center, bottom edge
% respectively.
%    \begin{macrocode}
\newcommand\boxbaset{\raisebox{-\height}}
\newcommand\boxbaseb{\raisebox{\depth}}
\newcommand\boxbasec[1]{\raisebox{-0.5\totalheight}{\boxbaseb{#1}}}
%    \end{macrocode}
%
%
% \subsection{A new float type for photos}
%
% A new float type. As for figures and tables.
%
% counter, names, file extension, default placement
%    \begin{macrocode}
\newcounter{photo}
\renewcommand\thephoto{\@arabic\c@photo}
\newcommand\photoname{Photo}
\newcommand\listphotoname{List of Photos}
\def\fps@photo{tbp}
\def\ftype@photo{4}
\def\ext@photo{lop}
\def\fnum@photo{\photoname~\thephoto}
%    \end{macrocode}
% The default photo placement can be changed with this command:
%    \begin{macrocode}
\newcommand\defaultphotoplacement[1]{\def\fps@photo{#1}}
%    \end{macrocode}
% single-column float
%    \begin{macrocode}
\newenvironment{photo}%
               {\@float{photo}}%
               {\end@float}
%    \end{macrocode}
% double-column float
%    \begin{macrocode}
\newenvironment{photo*}%
               {\@dblfloat{photo}}%
               {\end@dblfloat}
%    \end{macrocode}
% Generate a list of photos.
% For the list of photos we need to take care of the document class.
% Do a crude job and use |\chapter| if it is defined, |\section| otherwise.
%    \begin{macrocode}
\newcommand\listofphotos{%
\begingroup
\csname lop@parskip\endcsname
\@ifundefined{chapter}{\section}{\chapter}*{\listphotoname
      \@mkboth{\MakeUppercase\listphotoname}%
              {\MakeUppercase\listphotoname}}%
    \@starttoc{\ext@photo}%
\endgroup
    }
%    \end{macrocode}
% A table-of-contents entry.
%    \begin{macrocode}
\newcommand*\l@photo{\@dottedtocline{1}{1.5em}{2.3em}}
%    \end{macrocode}
%
%
% \subsection{Command for placing a photo}
%
% declare some variables
%    \begin{macrocode}
\newdimen\oecaptionsep
\newdimen\minoecaptionwidth
\newbox\oe@box
\oecaptionsep		10mm
\minoecaptionwidth	35mm
\newcommand\photographerfont{\tiny\sffamily}
%    \end{macrocode}
%
% \begin{macro}{\putphoto}
% This command places a photo into the document. It does not produce a
% float!
%    \begin{macrocode}
\newcommand\putphoto[4][\@OEPOSdflt\@CPOSdflt\@PPOSdflt]{%
	\par
	\begingroup
	\edef\@OEPOS{#1}\edef\@LAB{#2}\def\@PGR{#3}%
	\setbox\oe@box\hbox{#4}%
	\putphoto@ii
}
%    \end{macrocode}
% \end{macro}
%    \begin{macrocode}
\newcommand*\putphoto@ii[2][]{%
	\def\@TCAP{#1}\def\@CAP{#2}%
	%
	\def\@captype{photo}% make (photo-)\caption available outside float
	%
	\def\cap@width{\dimen0}% shortcut - w/o introducing a new variable
	%
	% process placement info
	\def\@CPOS{\@CPOSdflt}\def\@PPOS{\@PPOSdflt}%
	%\typeout{photo pos: ... \@OEPOS, \@PPOS, \@CPOS}%
	\def\@tempb{\@tfor\@tempa:=}%
	\expandafter\@tempb\@OEPOS\do{%
	  %\typeout{loop: \@tempa}
	  \if l\@tempa \def\@OEPOS{l}\else
	  \if r\@tempa \def\@OEPOS{r}\else
	  \if i\@tempa \ifx\@PGR\empty\else
		\ifoddpage[\@LAB]{\def\@OEPOS{l}}{\def\@OEPOS{r}}\fi\else
	  \if o\@tempa \ifx\@PGR\empty\else
		\ifoddpage[\@LAB]{\def\@OEPOS{r}}{\def\@OEPOS{l}}\fi\else
	  \if u\@tempa \def\@PPOS{u}\else
	  \if s\@tempa \def\@PPOS{s}\else
	  \if t\@tempa \def\@CPOS{t}\else
	  \if c\@tempa \def\@CPOS{c}\else
	  \if b\@tempa \def\@CPOS{b}\else
	  \PackageError{photo}{illegal pos: \@tempa}{}%
	  \fi\fi\fi\fi\fi\fi\fi\fi\fi}%
	%\typeout{photo pos: ==> \@OEPOS, \@PPOS, \@CPOS}%
	%
	% calculate width available for caption:
	\cap@width\columnwidth
	\advance\cap@width-\wd\oe@box \advance\cap@width-\oecaptionsep
	%
	% place caption beside photo if there is enough space left, underneath
	% otherwise:
	\ifdim\minoecaptionwidth>\cap@width\photo@ucap\else\photo@scap\fi
	\endgroup
}
%    \end{macrocode}
% photo with caption underneath
%    \begin{macrocode}
\newcommand\photo@ucap{%
	\begingroup
	\centering\parbox{\wd\oe@box}{%
		\leavevmode\box\oe@box
		\ifx\@PGR\empty\else
		  \newline\photographerfont
		  \if r\@OEPOS \raggedleft \fi
		  \@PGR
		\fi
	}\par
	\endgroup
	\photo@caption
}
%    \end{macrocode}
% photo with caption beside
%    \begin{macrocode}
\newcommand\photo@scap{%
	\abovecaptionskip\z@
	\belowcaptionskip\z@
	\leavevmode
	\ifx\@PGR\empty\else\if s\@PPOS \if r\@OEPOS
	  \rlap{\boxbaseb{\parbox{\cap@width}{%
	    \photographerfont\raggedleft\@PGR}}}\fi\fi\fi
	\boxbaseb{%
	  \if l\@OEPOS
	    \photo@lift{\wd\oe@box}{\box\oe@box}\hskip\oecaptionsep
	      \photo@lift\cap@width\photo@caption
	  \else
	    \photo@lift\cap@width\photo@caption\hskip\oecaptionsep
	      \photo@lift{\wd\oe@box}{\box\oe@box}%
	  \fi
	}%
	\ifx\@PGR\empty\else
	  \if u\@PPOS
	    \newline\photographerfont\if r\@OEPOS \raggedleft \fi\@PGR
	  \else\if l\@OEPOS
	      \llap{\boxbaseb{\parbox{\cap@width}{\photographerfont\@PGR}}}\fi
	  \fi
	\fi
	\par
}
%    \end{macrocode}
% This creates a parbox, with its baseline shifted to the top edge /
% centre / bottom edge.
%    \begin{macrocode}
\newcommand\photo@lift[2]{%
	%\if t\@CPOS \raisebox{-\height}{\parbox{#1}{#2}}\else
	%\if b\@CPOS \raisebox{\depth}{\parbox{#1}{#2}}\else
	%\raisebox{-0.5\totalheight}{\raisebox{\depth}{\parbox{#1}{#2}}}\fi\fi
	\csname boxbase\@CPOS\endcsname{\parbox{#1}{#2}}%
}
%    \end{macrocode}
% Set the caption, within the provided width.
%    \begin{macrocode}
\newcommand\photo@caption{%
	\ifx\@CAP\empty\else
		\ifx\@TCAP\empty
			\caption{\@CAP}\else
			\caption[\@TCAP]{\@CAP}\fi
		\ifx\@LAB\empty\else\label\@LAB\fi
	\fi
}
%    \end{macrocode}
%
%
% \subsection{Environment for placing a floating photo}
%
% ^^A\begin{macro}{Photo}  ^^A This does not work for environments!
% This environment produces a photo float, single-column if possible or
% double-column otherwise. It uses |\putphoto|.
%    \begin{macrocode}
\newenvironment{Photo}[3][\@OEPOSdflt\@CPOSdflt\@PPOSdflt]{%
	\par
	\begingroup
	\edef\@OEPOS{#1}\edef\@LAB{#2}\def\@PGR{#3}%
	%\Photo@ii
	\@dblarg\Photo@ii
}{%
	\end{lrbox}%
	\def\@@t{photo}%
	\if@twocolumn\ifdim\wd\oe@box>\columnwidth
		% for this photo, the column width is effectively \textwidth
		\def\@@t{photo*}\columnwidth\textwidth
	\fi\fi
	\expandafter\begin\expandafter{\@@t}%
	\begingroup
	\putphoto@ii[\@TCAPf]\@CAPf
	\expandafter\end\expandafter{\@@t}%
	\endgroup
}
%    \end{macrocode}
% ^^A\end{macro}
% continue with part 2
%    \begin{macrocode}
\newcommand\Photo@ii[2][]{%
	\def\@TCAPf{#1}\def\@CAPf{#2}%
	\begin{lrbox}\oe@box
}
%    \end{macrocode}
%
%
% \subsection{Cross-referencing}
%
% The ``photo'' name shouldn't be hard-coded.
%    \begin{macrocode}
\newcommand\phref[1]{photo~\ref{#1}}
\newcommand\Phref[1]{\photoname~\ref{#1}}
%    \end{macrocode}
%
%
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
% \iffalse
% %% EOF photo.dtx
% %%----------------------------------------------------------------------------
% \fi