% \iffalse meta-comment
%
% Copyright (C) 1997-... by Rolf Niepraschk <Rolf.Niepraschk@gmx.de>
% ---------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Rolf Niepraschk.
%
% This work consists of the files overpic.dtx and overpic.ins
% and the derived filebase overpic.sty.
%
%<*package>
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\ProvidesPackage{overpic}[2024/01/06 2.1 picture overlays (RN)]
%</package>
%
%<*driver>
\ProvidesFile{overpic.dtx}
\documentclass{ltxdoc}
\usepackage{overpic,pict2e,xcolor}
\usepackage{lmodern}
\usepackage{listings}
\setlength\parindent{0pt}
\newlength\myparskip
\setlength\myparskip{.6em plus 0.1em minus 0.1em}
\setlength\parskip{\myparskip}
\lstset{%
  language=[AlLaTeX]TeX,
  gobble=2,
  keywordstyle=\bfseries,
  commentstyle=\small\ttfamily,
  basicstyle=\small\ttfamily,
  basewidth=0.55em,
  backgroundcolor=\color{black!10},
  keepspaces,
  numbers=none,
  aboveskip=\myparskip,
  belowskip=\myparskip,
  framesep=\fboxsep,
  frame=single
}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{overpic.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{199}
%
% \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         \~}
%
%
% \changes{0.60}{2014/06/16}{Converted to .dtx}
% \changes{1.0}{2017/10/06}{mostly rewritten}
%
% \DoNotIndex{\newcommand,\renewcommand,\newenvironment,\renewenvironment}
% \DoNotIndex{\providecommand,\def,\edef,\let,\gdef,\xdef,\global,\newtoks}
% \DoNotIndex{\usebox,\sbox,\relax,\@viipt,\@viiipt,\count@,\dimexpr,\newif}
% \DoNotIndex{\RequirePackage,\DeclareOption,\ProcessOptions,\ExecuteOptions}
% \DoNotIndex{\PassOptionsToPackage,\endinput,\lowercase}
% \DoNotIndex{\input,\InputIfFileExists}
% \DoNotIndex{\@ifdefinable,\@ifundefined,\@percentchar}
% \DoNotIndex{\AtBeginDocument,\AtEndOfPackage}
% \DoNotIndex{\PackageError,\PackageWarning,\PackageWarningNoLine,\PackageInfo}
% \DoNotIndex{\MessageBreak,\typeout}
% \DoNotIndex{\z@,\z@skip,\p@,\@ne,\tw@,\thr@@,\@iv,\@m,\strip@pt}
% \DoNotIndex{\the,\if,\else,\or,\fi,\ifnum,\ifdim,\ifcase,\ifodd}
% \DoNotIndex{\advance,\multiply,\divide}
% \DoNotIndex{\@tfor,\do,\@ehc,\@tempcnta,\@tempcntb}
% \DoNotIndex{\csname,\endcsname,\begingroup,\endgroup}
% \DoNotIndex{\expandafter,\afterassignment,\noexpand}
%
% \providecommand*{\url}{\texttt}
% \GetFileInfo{overpic.sty}
% \title{The \textsf{overpic} package}
% \author{Rolf Niepraschk \\ (\url{Rolf.Niepraschk@gmx.de)}}
% \date{Version~\fileversion~--~\filedate}
%
% \maketitle
%
% \section{Introduction}
%
% The overpic environment is a combination between the \LaTeX\ picture
% environment and another \LaTeX\ object like an image used with the
% command \cmd{\includegraphics} of graphicx or a tabular. The
% resulting picture environment has the same dimensions as the included
% object. \LaTeX\ commands can be placed on the object at any position;
% setting a grid for the orientation is possible.
%
% \section{Usage}
%
% Put |\usepackage[|\meta{options}|]{overpic}| in the preamble of the document.
% The following package options are available: 
% \begin{itemize}
%   \item |abs|: Absolute positioning in multiples of \cmd{\unitlength}.
%   \item |percent|: Relative positioning; the longer dimension has
%     value 100. The \cmd{\unitlength} will be calculated accordingly. This
%     is the default mode.
%   \item |permil|: Relative positioning; the longer dimension has
%     value 1000. The \cmd{\unitlength} will be calculated accordingly.
% \end{itemize}
% Other options will be tranfered to package |graphicx|. 
%
% \DescribeEnv{overpic}
% |\begin{overpic}[|\meta{options}|]{|\meta{filename}|}| \meta{picture code}
%  |\end{overpic}| \par
% Sets the graphic \meta{filename} and puts the \meta{picture code} on the
% top of the graphic. The picture code can be any \TeX\ code inclusive other
% graphics.
%
% The following options are possible:
% \begin{itemize}
%   \item |abs|, |percent|, |permil|: The same as the package
%     options (true or false).
%   \item |rel|: Other value as base for relative positioning
%     (e.g. 10000)
%   \item |grid|: Drawing a grid for better orientation (true or false,
%     default: false).
%   \item |tics|: The distance of the grid tics (default: 10).
%   \item |unit|: Sets \cmd{\unitlength} (any \TeX\ dimension, only
%     effective in abs mode).
% \end{itemize}
% \DescribeEnv{Overpic}
% |\begin{Overpic}[|\meta{options}|]{|\meta{\TeX\ code}|}|
%  \meta{picture code} |\end{Overpic}| \par
%  Similar to environment |overpic| but instead of a graphic any
%  \TeX\ code (e.g. a tabular) is set as basement of the following picture
%  overlay.
%
% \DescribeMacro\setOverpic
% \cmd{\setOverpic}|{|\meta{options}|}| \par
% Sets new default values.
%
% \section{Examples}
%
% The graphic (\texttt{golfer.eps}) in the following examples is
% part of the program \texttt{ghostscript} and must be accesible to \TeX{}.
% To use the command \cmd{\color} the package |xcolor| (or |color|) must
% be loaded.
%
% \subsection{Environment ``overpic'' (absolute positioning)}
%
% \begin{lstlisting}
% \begin{overpic}[abs,unit=1mm,scale=.25,grid]{golfer.eps}
%   \put(3,27){\color{blue}\huge\LaTeX}
% \end{overpic}
% \end{lstlisting}
% \par\medskip\pagebreak[3]
% \begin{overpic}[abs,unit=1mm,scale=.25,grid]{golfer.eps}
%   \put(3,27){\color{blue}\huge\LaTeX}
% \end{overpic}
%
% \subsection{Environment ``overpic'' (relative positioning)}
%
% The longer dimension is defined as 100\%. \pagebreak[3]
%
% \begin{lstlisting}
% \begin{overpic}[scale=.25,percent,grid]{golfer.eps}
%   \put(5,45){\color{blue}\huge\LaTeX}
%   \put(55,10){\color{red}%
%     \frame{\includegraphics[scale=.07]{golfer.eps}}}
% \end{overpic}
% \end{lstlisting}
% \par\medskip\pagebreak[3]
% \begin{overpic}[scale=.25,percent,grid]{golfer.eps}
%   \put(5,45){\color{blue}\huge\LaTeX}
%   \put(55,10){\color{red}%
%     \frame{\includegraphics[scale=.07]{golfer.eps}}}
% \end{overpic}
%  
% \subsection{Environment ``Overpic'' (absolute positioning)}
%
% To use the picture command \cmd{\polygon} the package |pict2e| must
% be loaded.
%
% \begin{lstlisting}
% \begin{Overpic}[abs,unit=1mm,grid=true,tics=5]{%
%   \bfseries\sffamily
%   \begin{tabular}{*{8}{p{8mm}}}
%   H  &    &    &    &    &    &    & He\\
%   Li & Be & B  & C  & N  & O  & F  & Ne\\
%   Na & Mg & Al & Si & P  & S  & Cl & Ar\\
%   K  & Ca & Ga & Ge & As & Se & Br & Kr\\
%   Rb & Sr & In & Sn & Sb & Te & I  & Xe\\
%   Cs & Ba & Tl & Pb & Bi & Po & At & Rn\\
%   Fr & Ra & 112&    & 114&    &    &\\
%   \end{tabular}}%
%   \put(0,0){\color{blue}\linethickness{0.5mm}
%     \polygon(0,30)(10,30)(10,21.5)(45,21.5)(45,13)(22,13)%
%       (22,4.5)(0,4.5)}
% \end{Overpic}  
% \end{lstlisting}
% \par\medskip\pagebreak[3]
% \begin{Overpic}[abs,unit=1mm,grid=true,tics=5]{%
%   \bfseries\sffamily
%   \begin{tabular}{*{8}{p{8mm}}}
%   H  &    &    &    &    &    &    & He\\
%   Li & Be & B  & C  & N  & O  & F  & Ne\\
%   Na & Mg & Al & Si & P  & S  & Cl & Ar\\
%   K  & Ca & Ga & Ge & As & Se & Br & Kr\\
%   Rb & Sr & In & Sn & Sb & Te & I  & Xe\\
%   Cs & Ba & Tl & Pb & Bi & Po & At & Rn\\
%   Fr & Ra & 112&    & 114&    &    &\\
%   \end{tabular}}%
%   \put(0,0){\color{blue}\linethickness{0.5mm}
%     \polygon(0,30)(10,30)(10,21.5)(45,21.5)(45,13)(22,13)%
%       (22,4.5)(0,4.5)}
% \end{Overpic}  
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%    \begin{macrocode}
\RequirePackage{keyval,graphicx,epic}
%    \end{macrocode}
%
% \begin{macro}{\OVP@scale}
% Reference value for rel mode (percent: 100, permil: 1000)
%    \begin{macrocode}
\newcommand*\OVP@scale{\z@}
%    \end{macrocode}
% \end{macro}
% All the keys: 
%    \begin{macrocode}
\define@key{OVP}{rel}{%
  \def\OVP@scale{#1}%
  \ifnum\OVP@scale>\z@
    \let\OVP@calc\OVP@calc@rel
  \else
    \PackageError{overpic}{Invalid number for option `rel'}\@ehc
  \fi
}
\define@key{OVP}{percent}[]{%
  \setkeys{OVP}{rel=100}%
}
\define@key{OVP}{permil}[]{%
  \setkeys{OVP}{rel=\@m}%
}
\define@key{OVP}{abs}[]{%
  \let\OVP@calc\OVP@calc@abs
}
\def\OVP@boolkey#1#2{%
  \csname OVP@#2\ifx\relax#1\relax true\else#1\fi\endcsname}
\newif\ifOVP@grid
\define@key{OVP}{grid}[true]{\lowercase{\OVP@boolkey{#1}}{grid}}
\define@key{OVP}{tics}{\count@=#1}
\define@key{OVP}{unit}{\unitlength=\dimexpr#1\relax}
%    \end{macrocode}
% \begin{macro}{\OVP@calc@abs}
% Some calculations in abs mode. \cmd{\@tempcnta} is the normalized width
% and \cmd{\@tempcntb} is the normalized height. \cmd{\count@} is the
% tics value.
%    \begin{macrocode}
\newcommand*\OVP@calc@abs{%
  \divide\@tempcnta by \unitlength
  \divide\@tempcntb by \unitlength
  \ifnum\count@=\z@\count@=10\fi
}
%    \end{macrocode}
% \end{macro}
% \changes{2.0}{2024/01/04}{Use a separate namespace for the keys to avoid
%   unfavorable influence on \cmd\includegraphics.}
% \begin{macro}{\OVP@calc@rel}
% Some calculations in rel mode. The bigger value of width or height
% is the base.
% \changes{1.0}{2017/10/06}{Suggested by \mbox{Heiko Oberdiek}}
%    \begin{macrocode}
\newcommand*\OVP@calc@rel{%
  \ifnum\@tempcnta>\@tempcntb
    \divide\@tempcnta by \OVP@scale
    \unitlength=\@tempcnta sp %
    \@tempcnta=\OVP@scale
    \divide\@tempcntb by \unitlength
  \else
    \divide\@tempcntb by \OVP@scale
    \unitlength=\@tempcntb sp %
    \@tempcntb=\OVP@scale
    \divide\@tempcnta by \unitlength
  \fi
  \ifnum\count@=\z@
    \count@=\OVP@scale
    \divide\count@ by 10 %
  \fi
}
%    \end{macrocode}
% \end{macro}
% The package options set the defaults:
%    \begin{macrocode}
\DeclareOption{percent}{\setkeys{OVP}{rel=100}}
\DeclareOption{permil}{\setkeys{OVP}{rel=\@m}}
\DeclareOption{abs}{\setkeys{OVP}{abs}}
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{graphicx}}
\ExecuteOptions{percent}
\ProcessOptions
\AtBeginDocument{%
  \@ifpackageloaded{xkeyval}{%
    \def\OVP@setkeys@relaxed{%
      \let\OVP@setkeys\setkeys
      \def\setkeys{\OVP@setkeys*}
    }
    \def\OVP@setkeys@strict{%
      \let\setkeys\OVP@setkeys
    }
  }{%
    \def\OVP@setkeys@relaxed{%
      \let\OVP@KV@errx\KV@errx
      \let\KV@errx\@gobble
    }
    \def\OVP@setkeys@strict{%
      \let\KV@errx\OVP@KV@errx
    }
  }
}
\newsavebox\OVP@box
%    \end{macrocode}
%
% \begin{environment}{overpic}
% Box \cmd{\OVP@box} gets a graphic.
% \changes{1.2}{2018/09/02}{Wrong place of \cmd\setkeys
%   (bug report from 'aminophen')}
% \changes{2.0}{2024/01/04}{Better key handling}
% \changes{2.1}{2024/01/06}{Consideration of xkeyval's \cmd\setkeys}
%    \begin{macrocode}
\newenvironment{overpic}[2][]{%
%    \end{macrocode}
% Silently ignore unknown keys.
%    \begin{macrocode}
  \OVP@setkeys@relaxed
  \sbox\OVP@box{\includegraphics[#1]{#2}}%
  \count@=\z@ \OVP@gridfalse
  \setkeys{OVP}{#1}%
%    \end{macrocode}
% Stop ignoring unknown keys.
%    \begin{macrocode}
  \OVP@setkeys@strict
  \OVP@picture{#1}%
}{\endpicture}
%    \end{macrocode}
% \end{environment}
% \begin{environment}{Overpic}
% \changes{1.0}{2017/10/06}{Suggested by \mbox{Herbert Vo\ss}}
% \changes{1.3}{2020/02/22}{Added missing \cmd\setkeys}
% Box \cmd{\OVP@box} gets any \TeX\ code.
%    \begin{macrocode}
\newenvironment{Overpic}[2][]{%
  \sbox\OVP@box{#2}%
  \count@=\z@ \OVP@gridfalse
  \setkeys{OVP}{#1}%  
  \OVP@picture{#1}%
}{\endpicture}
%    \end{macrocode}
% \end{environment}
% \begin{macro}{\OVP@picture}
% Put box \cmd{\OVP@box} and a optionally grid at the lower left corner of a
% picture environment. 
%    \begin{macrocode}
\newcommand*\OVP@picture[1]{%
  \settodepth{\@tempcnta}{\usebox\OVP@box}%
  \settoheight{\@tempcntb}{\usebox\OVP@box}%
  \advance\@tempcntb\@tempcnta
  \settowidth{\@tempcnta}{\usebox\OVP@box}%
  \OVP@calc
  \picture(\@tempcnta,\@tempcntb)%
    \put(0,0){\makebox(0,0)[bl]{\usebox\OVP@box}}%
    \ifOVP@grid
      \put(0,0){\normalfont\fontsize\@viipt\@viiipt\selectfont
        \grid(\@tempcnta,\@tempcntb)(\count@,\count@)[0,0]}%
    \fi
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\setOverpic}
% Sets new defaults.
%    \begin{macrocode}
\newcommand*\setOverpic[1]{%
  \setkeys{OVP}{#1}%
}
%    \end{macrocode}
% \end{macro}
%    \begin{macrocode}
\endinput
%    \end{macrocode}
%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput