| 1 |
% \iffalse |
| 2 |
%% |
| 3 |
%% File: nccpic.dtx Copyright (C) 2002--2005 by Alexander I. Rozhenko |
| 4 |
%% |
| 5 |
%<package>\NeedsTeXFormat{LaTeX2e}[1995/12/01] |
| 6 |
%<package>\ProvidesPackage{nccpic} |
| 7 |
%<package> [2005/03/06 v1.2 NCC Extention of Graphicx (NCC)] |
| 8 |
% |
| 9 |
% \changes{v1.01}{2002/01/23}{This version is uploaded to CTAN} |
| 10 |
% \changes{v1.02}{2002/02/17}{All options are passed to graphicx} |
| 11 |
% \changes{v1.03}{2002/03/20}{|\draftgraphics| and |\finalgraphics| introduced} |
| 12 |
% \changes{v1.04}{2004/09/04}{Patch for bounding box calculation} |
| 13 |
% \changes{v1.1}{2004/12/09}{Documentation was prepared} |
| 14 |
% \changes{v1.2}{2005/03/06}{Correct extension lists} |
| 15 |
% |
| 16 |
%<*driver> |
| 17 |
\let\makeindex\relax |
| 18 |
\documentclass{ltxdoc} |
| 19 |
\usepackage{nccpic,desclist} |
| 20 |
\GetFileInfo{nccpic.sty} |
| 21 |
\begin{document} |
| 22 |
\title{The \textsf{nccpic} package\thanks{This file |
| 23 |
has version number \fileversion, last |
| 24 |
revised \filedate.}} |
| 25 |
\author{Alexander I. Rozhenko\\[email protected]} |
| 26 |
\date{\filedate} |
| 27 |
\maketitle |
| 28 |
\DocInput{nccpic.dtx} |
| 29 |
\end{document} |
| 30 |
%</driver> |
| 31 |
% \fi |
| 32 |
% |
| 33 |
% \section{User Interface} |
| 34 |
% |
| 35 |
% The package is considered as an extension of the |graphicx| package. |
| 36 |
% It passes all options to the |graphicx| and customizes graphics |
| 37 |
% extensions list for most popular drivers, namely |dvips| and |dvidpf|. |
| 38 |
% |
| 39 |
% This allows us omit an extension of a graphics file in the |
| 40 |
% |\includegraphics| command. When a file without extension is searched, |
| 41 |
% this command sequentially tries extensions from the list of extensions |
| 42 |
% until an appropriate file will be found. |
| 43 |
% |
| 44 |
% Using this feature, you can support multiple output from a \LaTeX\ |
| 45 |
% document with minimum changes in |.tex| sources. The only required |
| 46 |
% thing is to prepare a number of versions for all graphics files |
| 47 |
% used in the document. For example, the |dvips| program and YAP previewer |
| 48 |
% like |.eps| and |.bmp| files, and the |pdftex| likes |.png| files. To |
| 49 |
% satisfy their needs, you can prepare the |.eps| or |.bmp| version |
| 50 |
% of all pictures for use with dvips and the |.png| version for use with |
| 51 |
% |pdftex|. Then, when you translate your source file with the |latex| |
| 52 |
% command, the |.eps| or |.bmp| versions of graphics files are used. |
| 53 |
% But when you translate your source file with the |pdflatex| command, |
| 54 |
% the |.png| versions of graphics files are used. |
| 55 |
% |
| 56 |
% The next aim of this package is the regulation of |
| 57 |
% placement of graphics files in the file system. It is the bad idea |
| 58 |
% to place graphics together with \LaTeX\ sources, especially when |
| 59 |
% your prepare a book containing many pictures. It will be much better |
| 60 |
% if graphics will be stored in a subdirectory relative to the |
| 61 |
% base directory of your \LaTeX\ sources. |
| 62 |
% We propose to store graphics files in the |
| 63 |
% |graphics| subdirectory of the source directory. To support |
| 64 |
% the search in this storage, the graphics path is customized in |
| 65 |
% this package. |
| 66 |
% |
| 67 |
% \DescribeMacro\ipic |
| 68 |
% The graphics in \LaTeX\ can be prepared at least in two ways: |
| 69 |
% as an external graphics file included with the |\includegraphics| |
| 70 |
% command or its analogue; as a \LaTeX\ |picture| environment |
| 71 |
% or its analogues provided with special graphics packages. |
| 72 |
% In the last case, the placing a picture inside a \LaTeX\ source |
| 73 |
% file is inconvenient. It will be better to put a \LaTeX\ picture |
| 74 |
% in a separate file and include it using the |\input| command. |
| 75 |
% The next step is to place such pictures together with other |
| 76 |
% graphics material into the |graphics| subdirectory and load them using |
| 77 |
% the |\ipic|\marg{filename} command. This command appends |
| 78 |
% the \meta{filename} with the |.pic| extension and tries to load |
| 79 |
% the `\meta{filename}|.pic|' file at first from the base directory |
| 80 |
% of your document and then from the |graphics| subdirectory. |
| 81 |
% |
| 82 |
% \DescribeMacro\draftgraphics |
| 83 |
% \DescribeMacro\finalgraphics |
| 84 |
% The |\draftgraphics| and |\finalgraphics| commands respectively |
| 85 |
% set the draft and final modes for graphics inclusion with the |
| 86 |
% |\includegraphics| command. They are analogues for the |draft| |
| 87 |
% and |final| options of the |graphics| package. But the commands |
| 88 |
% allow more flexible control of graphics mode especially for |
| 89 |
% document classes including this package by default (the |ncc| |
| 90 |
% class from NCC-\LaTeX\ does this). |
| 91 |
% A graphics file included in the draft |
| 92 |
% mode is shown as a rectangle containing the name of graphics file. |
| 93 |
% This is quite useful on the stage of editing a document. |
| 94 |
% |
| 95 |
% \DescribeMacro\putimage |
| 96 |
% The following command includes a graphics file using the |
| 97 |
% |\includegraphics| command. It is provided for compatibility with |
| 98 |
% old NCC-\LaTeX: |
| 99 |
% \begin{quote} |
| 100 |
% |\putimage(|$x$|,|$y$|)[|$x_{\rm real}$|,|$y_{\rm real}$|](|$x_{\rm shift}$|,|$y_{\rm shift}$|)|\marg{filename} |
| 101 |
% \end{quote} |
| 102 |
% Here: |
| 103 |
% \begin{desclist}{}{\hfill}[\tt($x_{\rm shift}$,$y_{\rm shift}$)] |
| 104 |
% \item[\meta{filename}] is a name of graphics file; |
| 105 |
% |
| 106 |
% \item[\tt($x$,$y$)] are dimensions (in |\unitlength|) of the prepared image box; |
| 107 |
% |
| 108 |
% \item[\tt{[$x_{\rm real}$,$y_{\rm real}$]}] are dimensions (in |\unitlength|) |
| 109 |
% of graphics file that are passed to the |\includegraphics| command; |
| 110 |
% |
| 111 |
% \item[\tt($x_{\rm shift}$,$y_{\rm shift}$)] are shifts (in |\unitlength|) |
| 112 |
% of the graphics image with respect to the image box. |
| 113 |
% \end{desclist} |
| 114 |
% The |(|$x$|,|$y$|)| and \meta{filename} parameters are required. Others |
| 115 |
% are optional. If the |[|$x_{\rm real}$|,|$y_{\rm real}$|]| parameter is |
| 116 |
% omitted, $x_{\rm real}:=x$ and $y_{\rm real}:=y$. If the |
| 117 |
% |(|$x_{\rm shift}$|,|$y_{\rm shift}$|)| parameter is omitted, the shift values |
| 118 |
% are set to zero. |
| 119 |
% |
| 120 |
% The |\putimage| command vertically aligns the image box in the different |
| 121 |
% way than the |\includegraphics|. The first one lowers the box in such a way |
| 122 |
% to align its top edge with the top edge of letter `A' of the current font. |
| 123 |
% But the last one aligns the bottom edge of graphics on the baseline. |
| 124 |
% |
| 125 |
% Other distinction between these commands consists in their work in the |
| 126 |
% draft mode. The |\putimage| command does not test a required graphics |
| 127 |
% file on existence and puts the filename at the center of bounding |
| 128 |
% rectangle. But the |\includegraphics| searches the graphics file |
| 129 |
% and puts the filename at the left top corner of bounding rectangle. |
| 130 |
% |
| 131 |
% In version 1.04 of this package, we add a patch to the |graphics| package. |
| 132 |
% The reason of this patch is the following. |
| 133 |
% In latest versions of the MiKTeX, graphics rules |
| 134 |
% are specified for many graphics formats. As a result, if a bounding |
| 135 |
% box is not specified in parameters of the |\includegraphics| command, |
| 136 |
% a file with |.bb| extension is tested on the ps-like bounding box |
| 137 |
% specification. If such file does not exist, the |\includegraphics| command |
| 138 |
% fails even if its parameters exactly specify the graphics width and height. |
| 139 |
% We have changed the unconditional testing of the bounding box |
| 140 |
% to the conditional one: testing is applied if the required file exists, |
| 141 |
% otherwise, this operation is ignored. |
| 142 |
% \StopEventually{} |
| 143 |
% |
| 144 |
% \section{The Implementation} |
| 145 |
% |
| 146 |
% Load required packages. We use some features of the |nccboxes| package |
| 147 |
% in the |\putimage| command: the |\Strut| and |\jvbox| commands. |
| 148 |
% \begin{macrocode} |
| 149 |
%<*package> |
| 150 |
\RequirePackageWithOptions{graphicx}[1999/02/16] |
| 151 |
\RequirePackage{nccboxes}[2002/01/09] |
| 152 |
% \end{macrocode} |
| 153 |
% |
| 154 |
% Customize extension lists for |dvips| and |dvipdf|% drivers. |
| 155 |
% \begin{macrocode} |
| 156 |
\def\@tempa{dvips.def} |
| 157 |
\ifx\Gin@driver\@tempa |
| 158 |
\DeclareGraphicsExtensions{.eps,.ps,.eps.gz,.ps.gz,.eps.Z,% |
| 159 |
.bmp,.msp,.pcx,.pict,.pntg} |
| 160 |
\else |
| 161 |
\def\@tempa{dvipdf.def} |
| 162 |
\ifx\Gin@driver\@tempa |
| 163 |
\DeclareGraphicsExtensions{.eps,.ps,.eps.gz,.ps.gz,.eps.Z,% |
| 164 |
.bmp,.msp,.jpg} |
| 165 |
\fi |
| 166 |
\fi |
| 167 |
% \end{macrocode} |
| 168 |
% |
| 169 |
% Set the path list for search graphics files. It is not necessary to |
| 170 |
% set the base directory in the list, because it is always searched |
| 171 |
% first and the search in the graphics path list is applied only if |
| 172 |
% the search in the base directory fails. |
| 173 |
% \begin{macrocode} |
| 174 |
\graphicspath{{graphics/}} |
| 175 |
% \end{macrocode} |
| 176 |
% |
| 177 |
% \begin{macro}{\draftgraphics} |
| 178 |
% \begin{macro}{\finalgraphics} |
| 179 |
% Specify graphics mode control commands: |
| 180 |
% \begin{macrocode} |
| 181 |
\newcommand\draftgraphics{\Gin@drafttrue} |
| 182 |
\newcommand\finalgraphics{\Gin@draftfalse} |
| 183 |
% \end{macrocode} |
| 184 |
% \end{macro} |
| 185 |
% \end{macro} |
| 186 |
% |
| 187 |
% \begin{macro}{\ipic} |
| 188 |
% The |\ipic|\marg{filename} command is equivalent to |
| 189 |
% |\input{|\meta{filename}|.pic}| command with search in |
| 190 |
% the directory list specified by the |\graphicspath|. |
| 191 |
% The file is opened within a group and the beginning and |
| 192 |
% final spaces are removed in it. |
| 193 |
% \begin{macrocode} |
| 194 |
\newcommand*{\ipic}[1]{% |
| 195 |
\begingroup \let\input@path\Ginput@path |
| 196 |
\ignorespaces\input{#1.pic}\unskip |
| 197 |
\endgroup |
| 198 |
} |
| 199 |
% \end{macrocode} |
| 200 |
% \end{macro} |
| 201 |
% |
| 202 |
% \begin{macro}{\putimage} |
| 203 |
% Introduce the |\putimage| command. Using the empty definition |
| 204 |
% we ensure the command was undefined before. |
| 205 |
% \begin{macrocode} |
| 206 |
\newcommand{\putimage}{} |
| 207 |
\def\putimage(#1,#2){% |
| 208 |
\@ifnextchar[{\NCC@Gim(#1,#2)}{\NCC@Gim(#1,#2)[#1,#2]}% |
| 209 |
} |
| 210 |
\def\NCC@Gim(#1,#2)[#3,#4]{% |
| 211 |
\ifGin@draft |
| 212 |
\def\NCC@temp(##1,##2)##3{% |
| 213 |
\edef\@tempa{##3}% |
| 214 |
\put(0,0){% |
| 215 |
\framebox(#1,#2){\ttfamily\expandafter\strip@prefix\meaning\@tempa}% |
| 216 |
}% |
| 217 |
}% |
| 218 |
\else |
| 219 |
\def\NCC@temp(##1,##2)##3{% |
| 220 |
\put(##1,##2){% |
| 221 |
\includegraphics[width=#3\unitlength,height=#4\unitlength]{##3}% |
| 222 |
}% |
| 223 |
}% |
| 224 |
\fi |
| 225 |
\@ifnextchar({\NCC@Gim@(#1,#2)}{\NCC@Gim@(#1,#2)(0,0)}% |
| 226 |
} |
| 227 |
\def\NCC@Gim@(#1,#2)(#3,#4)#5{% |
| 228 |
\jvbox{\Strut}[t]{% |
| 229 |
\begin{picture}(#1,#2)\NCC@temp(#3,#4){#5}\end{picture}% |
| 230 |
}% |
| 231 |
} |
| 232 |
% \end{macrocode} |
| 233 |
% \end{macro} |
| 234 |
% |
| 235 |
% \begin{macro}{\Gin@setfile} |
| 236 |
% The patch to the |\Gin@setfile| command slightly |
| 237 |
% changes its behaviour: if bounding box calculations are |
| 238 |
% required and the corresponding graphics rule contains an extension |
| 239 |
% of file for reading the bounding box info, we skip the reading |
| 240 |
% of given file if it does not exist. |
| 241 |
% \begin{macrocode} |
| 242 |
\let\NCC@Ginsetfile\Gin@setfile |
| 243 |
\def\Gin@setfile#1#2{% |
| 244 |
\ifGin@bbox\else |
| 245 |
\ifx\\#2\\\else |
| 246 |
\IfFileExists{\Gin@base#2}{}{\Gread@false}% |
| 247 |
\fi |
| 248 |
\fi |
| 249 |
\NCC@Ginsetfile{#1}{#2}% |
| 250 |
} |
| 251 |
%</package> |
| 252 |
% \end{macrocode} |
| 253 |
% \end{macro} |
| 254 |
\endinput |