summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ncctools/source/nccpic.dtx
blob: 0fd12072fcc4c3d957f3c2e46032047039e75340 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
% \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