Debian Codegraph @

texmf-dist/source/latex/ncctools/nccpic.dtx

raw
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