% \iffalse
%%
%% File: nccpic.dtx Copyright (C) 2002--2005 by Alexander I. Rozhenko
%%
%<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01]
%<package>\ProvidesPackage{nccpic}
%<package>         [2005/03/06 v1.2 NCC Extention of Graphicx (NCC)]
%
% \changes{v1.01}{2002/01/23}{This version is uploaded to CTAN}
% \changes{v1.02}{2002/02/17}{All options are passed to graphicx}
% \changes{v1.03}{2002/03/20}{|\draftgraphics| and |\finalgraphics| introduced}
% \changes{v1.04}{2004/09/04}{Patch for bounding box calculation}
% \changes{v1.1}{2004/12/09}{Documentation was prepared}
% \changes{v1.2}{2005/03/06}{Correct extension lists}
%
%<*driver>
\let\makeindex\relax
\documentclass{ltxdoc}
\usepackage{nccpic,desclist}
\GetFileInfo{nccpic.sty}
\begin{document}
\title{The \textsf{nccpic} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{Alexander I. Rozhenko\\rozhenko@oapmg.sscc.ru}
\date{\filedate}
\maketitle
\DocInput{nccpic.dtx}
\end{document}
%</driver>
% \fi
%
% \section{User Interface}
%
% The package is considered as an extension of the |graphicx| package.
% It passes all options to the |graphicx| and customizes graphics
% extensions list for most popular drivers, namely |dvips| and |dvidpf|.
%
% This allows us omit an extension of a graphics file in the
% |\includegraphics| command. When a file without extension is searched,
% this command sequentially tries extensions from the list of extensions
% until an appropriate file will be found.
%
% Using this feature, you can support multiple output from a \LaTeX\
% document with minimum changes in |.tex| sources. The only required
% thing is to prepare a number of versions for all graphics files
% used in the document. For example, the |dvips| program and YAP previewer
% like |.eps| and |.bmp| files, and the |pdftex| likes |.png| files. To
% satisfy their needs, you can prepare the |.eps| or |.bmp| version
% of all pictures for use with dvips and the |.png| version for use with
% |pdftex|. Then, when you translate your source file with the |latex|
% command, the |.eps| or |.bmp| versions of graphics files are used.
% But when you translate your source file with the |pdflatex| command,
% the |.png| versions of graphics files are used.
%
% The next aim of this package is the regulation of
% placement of graphics files in the file system. It is the bad idea
% to place graphics together with \LaTeX\ sources, especially when
% your prepare a book containing many pictures. It will be much better
% if graphics will be stored in a subdirectory relative to the
% base directory of your \LaTeX\ sources.
% We propose to store graphics files in the
% |graphics| subdirectory of the source directory. To support
% the search in this storage, the graphics path is customized in
% this package.
%
% \DescribeMacro\ipic
% The graphics in \LaTeX\ can be prepared at least in two ways:
% as an external graphics file included with the |\includegraphics|
% command or its analogue; as a \LaTeX\ |picture| environment
% or its analogues provided with special graphics packages.
% In the last case, the placing a picture inside a \LaTeX\ source
% file is inconvenient. It will be better to put a \LaTeX\ picture
% in a separate file and include it using the |\input| command.
% The next step is to place such pictures together with other
% graphics material into the |graphics| subdirectory and load them using
% the |\ipic|\marg{filename} command. This command appends
% the \meta{filename} with the |.pic| extension and tries to load
% the `\meta{filename}|.pic|' file at first from the base directory
% of your document and then from the |graphics| subdirectory.
%
% \DescribeMacro\draftgraphics
% \DescribeMacro\finalgraphics
% The |\draftgraphics| and |\finalgraphics| commands respectively
% set the draft and final modes for graphics inclusion with the
% |\includegraphics| command. They are analogues for the |draft|
% and |final| options of the |graphics| package. But the commands
% allow more flexible control of graphics mode especially for
% document classes including this package by default (the |ncc|
% class from NCC-\LaTeX\ does this).
% A graphics file included in the draft
% mode is shown as a rectangle containing the name of graphics file.
% This is quite useful on the stage of editing a document.
%
% \DescribeMacro\putimage
% The following command includes a graphics file using the
% |\includegraphics| command. It is provided for compatibility with
% old NCC-\LaTeX:
% \begin{quote}
% |\putimage(|$x$|,|$y$|)[|$x_{\rm real}$|,|$y_{\rm real}$|](|$x_{\rm shift}$|,|$y_{\rm shift}$|)|\marg{filename}
% \end{quote}
% Here:
% \begin{desclist}{}{\hfill}[\tt($x_{\rm shift}$,$y_{\rm shift}$)]
%  \item[\meta{filename}] is a name of graphics file;
%
% \item[\tt($x$,$y$)] are dimensions (in |\unitlength|) of the prepared image box;
%
% \item[\tt{[$x_{\rm real}$,$y_{\rm real}$]}] are dimensions (in |\unitlength|)
%       of graphics file that are passed to the |\includegraphics| command;
%
% \item[\tt($x_{\rm shift}$,$y_{\rm shift}$)] are shifts (in |\unitlength|)
%       of the graphics image with respect to the image box.
% \end{desclist}
% The |(|$x$|,|$y$|)| and \meta{filename} parameters are required. Others
% are optional. If the |[|$x_{\rm real}$|,|$y_{\rm real}$|]| parameter is
% omitted, $x_{\rm real}:=x$ and $y_{\rm real}:=y$. If the
% |(|$x_{\rm shift}$|,|$y_{\rm shift}$|)| parameter is omitted, the shift values
% are set to zero.
%
% The |\putimage| command vertically aligns the image box in the different
% way than the |\includegraphics|. The first one lowers the box in such a way
% to align its top edge with the top edge of letter `A' of the current font.
% But the last one aligns the bottom edge of graphics on the baseline.
%
% Other distinction between these commands consists in their work in the
% draft mode. The |\putimage| command does not test a required graphics
% file on existence and puts the filename at the center of bounding
% rectangle. But the |\includegraphics| searches the graphics file
% and puts the filename at the left top corner of bounding rectangle.
%
% In version 1.04 of this package, we add a patch to the |graphics| package.
% The reason of this patch is the following.
% In latest versions of the MiKTeX, graphics rules
% are specified for many graphics formats. As a result, if a bounding
% box is not specified in parameters of the |\includegraphics| command,
% a file with |.bb| extension is tested on the ps-like bounding box
% specification. If such file does not exist, the |\includegraphics| command
% fails even if its parameters exactly specify the graphics width and height.
% We have changed the unconditional testing of the bounding box
% to the conditional one: testing is applied if the required file exists,
% otherwise, this operation is ignored.
% \StopEventually{}
%
% \section{The Implementation}
%
% Load required packages. We use some features of the |nccboxes| package
% in the |\putimage| command: the |\Strut| and |\jvbox| commands.
%    \begin{macrocode}
%<*package>
\RequirePackageWithOptions{graphicx}[1999/02/16]
\RequirePackage{nccboxes}[2002/01/09]
%    \end{macrocode}
%
% Customize extension lists for |dvips| and |dvipdf|% drivers. 
%    \begin{macrocode}
\def\@tempa{dvips.def}
\ifx\Gin@driver\@tempa
  \DeclareGraphicsExtensions{.eps,.ps,.eps.gz,.ps.gz,.eps.Z,%
                             .bmp,.msp,.pcx,.pict,.pntg}
\else
  \def\@tempa{dvipdf.def}
  \ifx\Gin@driver\@tempa
    \DeclareGraphicsExtensions{.eps,.ps,.eps.gz,.ps.gz,.eps.Z,%
                               .bmp,.msp,.jpg}
  \fi
\fi
%    \end{macrocode}
%
% Set the path list for search graphics files. It is not necessary to
% set the base directory in the list, because it is always searched
% first and the search in the graphics path list is applied only if
% the search in the base directory fails.
%    \begin{macrocode}
\graphicspath{{graphics/}}
%    \end{macrocode}
%
% \begin{macro}{\draftgraphics}
% \begin{macro}{\finalgraphics}
% Specify graphics mode control commands:
%    \begin{macrocode}
\newcommand\draftgraphics{\Gin@drafttrue}
\newcommand\finalgraphics{\Gin@draftfalse}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\ipic}
% The |\ipic|\marg{filename} command is equivalent to
% |\input{|\meta{filename}|.pic}| command with search in
% the directory list specified by the |\graphicspath|.
% The file is opened within a group and the beginning and
% final spaces are removed in it.
%    \begin{macrocode}
\newcommand*{\ipic}[1]{%
  \begingroup \let\input@path\Ginput@path
    \ignorespaces\input{#1.pic}\unskip
  \endgroup
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\putimage}
% Introduce the |\putimage| command. Using the empty definition
% we ensure the command was undefined before.
%    \begin{macrocode}
\newcommand{\putimage}{}
\def\putimage(#1,#2){%
  \@ifnextchar[{\NCC@Gim(#1,#2)}{\NCC@Gim(#1,#2)[#1,#2]}%
}
\def\NCC@Gim(#1,#2)[#3,#4]{%
  \ifGin@draft
    \def\NCC@temp(##1,##2)##3{%
      \edef\@tempa{##3}%
      \put(0,0){%
        \framebox(#1,#2){\ttfamily\expandafter\strip@prefix\meaning\@tempa}%
      }%
    }%
  \else
    \def\NCC@temp(##1,##2)##3{%
      \put(##1,##2){%
        \includegraphics[width=#3\unitlength,height=#4\unitlength]{##3}%
      }%
    }%
  \fi
  \@ifnextchar({\NCC@Gim@(#1,#2)}{\NCC@Gim@(#1,#2)(0,0)}%
}
\def\NCC@Gim@(#1,#2)(#3,#4)#5{%
  \jvbox{\Strut}[t]{%
    \begin{picture}(#1,#2)\NCC@temp(#3,#4){#5}\end{picture}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Gin@setfile}
% The patch to the |\Gin@setfile| command slightly
% changes its behaviour: if bounding box calculations are
% required and the corresponding graphics rule contains an extension
% of file for reading the bounding box info, we skip the reading
% of given file if it does not exist.
%    \begin{macrocode}
\let\NCC@Ginsetfile\Gin@setfile
\def\Gin@setfile#1#2{%
  \ifGin@bbox\else
    \ifx\\#2\\\else
      \IfFileExists{\Gin@base#2}{}{\Gread@false}%
    \fi
  \fi
  \NCC@Ginsetfile{#1}{#2}%
}
%</package>
%    \end{macrocode}
% \end{macro}
\endinput