summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ncctools/source/nccpic.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/ncctools/source/nccpic.dtx')
-rw-r--r--macros/latex/contrib/ncctools/source/nccpic.dtx254
1 files changed, 254 insertions, 0 deletions
diff --git a/macros/latex/contrib/ncctools/source/nccpic.dtx b/macros/latex/contrib/ncctools/source/nccpic.dtx
new file mode 100644
index 0000000000..0fd12072fc
--- /dev/null
+++ b/macros/latex/contrib/ncctools/source/nccpic.dtx
@@ -0,0 +1,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