Debian Codegraph @

texmf-dist/source/latex/graphicxbox/graphicxbox.dtx

raw
1 % \iffalse
2 %<*copyright>
3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4 %% aeb_envelope.sty package, 2014-01-10 %%
5 %% Copyright (C) 2014 D. P. Story %%
6 %% [email protected] %%
7 %% [email protected] %%
8 %% %%
9 %% This program can redistributed and/or modified under %%
10 %% the terms of the LaTeX Project Public License %%
11 %% Distributed from CTAN archives in directory %%
12 %% macros/latex/base/lppl.txt; either version 1 of the %%
13 %% License, or (at your option) any later version. %%
14 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15 %</copyright>
16 %<package>\NeedsTeXFormat{LaTeX2e}
17 %<package>\ProvidesPackage{graphicxbox}
18 %<package> [2014/01/10 v1.0 Provides graphic backgrounds for parboxes (dps)]
19 %<*driver>
20 \documentclass{ltxdoc}
21 \usepackage[colorlinks,hyperindex]{hyperref}
22 \pdfstringdefDisableCommands{\let\\\textbackslash}%
23 \EnableCrossrefs \CodelineIndex
24 \OnlyDescription % comment out for implementation details
25 \begin{document}
26 \GetFileInfo{graphicxbox.sty}
27 \title{The \textsf{graphicxbox} Package}
28 \author{D. P. Story\\
29 Email: \texttt{[email protected]}}
30 \date{processed \today}
31 \maketitle
32 \tableofcontents
33 \let\Email\texttt
34 \DocInput{graphicxbox.dtx}
35 \PrintIndex
36 \end{document}
37 %</driver>
38 % \fi
39 % \begin{macrocode}
40 %<*package>
41 % \end{macrocode}
42 %\section{Introduction}
43 % This is a short package that provides two new commands \cs{graphicxbox} and \cs{fgraphicxbox}, which
44 % are companion commands to \cs{colorbox} and \cs{fcolorbox} of \textsf{color.dtx}, by D. P. Carlisle.
45 % The \cs{graphicxbox} inserts a graphical image as a background rather than a background color,
46 % while \cs{fgraphcxbox} does the same thing, but also draws a colored frame around the box.
47 %
48 % This package requires either \textsf{graphicx} or \textsf{graphicxsp} package (the latter calls the first).
49 % The \textsf{graphicxsp} allows you to embed graphic images once and use them many times, this is ideal for
50 % this current package. Either of these commands should be loaded before this package. If you are using the
51 % \textsf{web} package and want to use \textsf{graphicxsp}, you should load \textsf{graphicxsp} before
52 % the \textsf{web} package. I will not use the \cs{RequirePackage} command to require either of these
53 % graphics packages, the reason for this is that \textsf{graphicxsp} contains options the user might
54 % want to access and I don't want to make this package unduly complicated by adding options to this
55 % package only to pass them to another.
56 %
57 %\section{Example files} We provide three sample files with this distribution.
58 %\begin{enumerate}
59 %\item \texttt{grfxbox\_tst.tex} illustrates the basic features available to
60 % all users of \textsf{dvips}, \textsf{dvipsone}, \textsf{pdflatex}, and \textsf{xelatex}.
61 %\item \texttt{grfxbox\_tst\_sp.tex} same as \texttt{grfxbox\_tst.tex}, but uses \texttt{graphicxsp}.
62 % The drivers \textsf{dvips} or \textsf{dvipsone} are required, and \textsf{Adobe Distiller} required as the PDF creator.
63 %\item \texttt{grfxbox\_tst\_indians.tex} uses \texttt{graphicxsp} again, but illustrates transparency.
64 % Distill the file with \texttt{Standard\_transparency.joboptions} which accompanie the \texttt{graphicsp} package.
65 %\end{enumerate}
66 % Though we don't have a \cs{RequirePackage} for the required graphics package, we will test for their
67 % presence and emit a package error.
68 % \begin{macrocode}
69 \@ifpackageloaded{graphicxsp}{}
70 {%
71 \@ifpackageloaded{graphicx}{}
72 {%
73 \PackageError{graphicxbox}{%
74 Neither the graphicx nor graphicxsp packages are loaded.}%
75 {Load the graphicx or graphicxsp package before this one.}%
76 }%
77 }
78 % \end{macrocode}
79 %\section{Definitions of the two main commands}
80 % \begin{macro}{\graphicxbox}
81 % This command provides a background graphic for a box, similar to \cs{colorbox}.
82 % The syntax is
83 %\begin{verbatim}
84 % \graphicxbox[<Graphicx(SP)options>]{<graphic>}{<box content>}
85 %\end{verbatim}
86 % When \textsf{graphicx} is loaded (and not \textsf{graphicxsp}) the syntax, in example
87 % form is
88 %\begin{verbatim}
89 % \graphicxbox{mycoolgraphic}{\Huge Hello World!}
90 %\end{verbatim}
91 % The first parameter is optional and is passed to the \cs{includegraphics}
92 % command. Do not use the \texttt{scale}, \texttt{width} or \texttt{height} parameters of
93 % \cs{includegraphics}. This package uses \texttt{width} and \texttt{height} to set the dimensions
94 % of the graphic to fit the box.
95 %
96 % When \textsf{graphicxsp} (distiller required) is loaded, the optional parameter is used to specify
97 % the name of the embedded graphic to be used, in this case, the second argument \verb!{<graphic>}!
98 % is not used. For example,
99 % \begin{verbatim}
100 % \embedEPS{indianblanket}{IndianBlnkt}
101 % ...
102 % ...
103 % \graphicxbox[name=indianblanket]{}{\Huge Hello World!}
104 %\end{verbatim}
105 % The \texttt{indianblanket} graphic can be used and reused many time without increasing the file size
106 % significantly. The other advantage of using the \textsf{graphicxsp} package is that it supports
107 % transparency. See the demo files that accompany this package.
108 % \begin{macrocode}
109 \newcommand{\graphicxbox}[2][]{\graphicx@b@x\relax{#1}{#2}}
110 % \end{macrocode}
111 % \end{macro}
112 % \begin{macro}{\fgraphicxbox}
113 % This command does the same as \cs{graphicxbox}, but additionally, adds a colored
114 % rule framing the box, similar to what \cs{fcolorbox} does. The syntax is
115 %\begin{verbatim}
116 % \fgraphicxbox[<model>]{<specification>}[<Graphicx(SP)options>]
117 % {<graphic>}{<box content>}
118 %\end{verbatim}
119 % The first two parameters are the same ones used by \cs{fcolorbox}, the color specification.
120 % The next three parameters are the same as \cs{graphicxbox}. The comments made above
121 % for the \cs{graphicxbox} hold here as well.
122 %
123 % Here is an example for the \textsf{graphicxsp} package:
124 %\begin{verbatim}
125 % \graphicxbox{blue}[name=indianblanket]{}{\Huge Hello World!}
126 %\end{verbatim}
127 %
128 % As with \cs{colorbox} and \cs{fcolorbox}, the lengths \cs{fboxsep} and \cs{fboxrule}. For example,
129 % if we set
130 % \begin{verbatim}
131 % \setlength{\fboxsep}{10pt}
132 % \setlength{\fboxrule}{2pt}
133 % \graphicxbox{blue}[name=indianblanket]{}{\Huge Hello World!}
134 %\end{verbatim}
135 % we would make the separation between the content and the frame of
136 % the to be \texttt{10pt} and the rule with to be \texttt{2pt}.
137 % \begin{macrocode}
138 \newcommand{\fgraphicxbox}[2][]{\fgraphicx@box{#1}{#2}}
139 % \end{macrocode}
140 % \end{macro}
141 %\section{Internal, supporting commands}
142 %\DescribeMacro{\fgraphicx@box} continues the flow from \cs{fgraphicxbox}.
143 % The parameters of \cs{fgraphicx@@box} are
144 %\begin{verbatim}
145 % \fgraphicx@box{model}{color spec}[options for graphicx(sp)]{filename}
146 %\end{verbatim}
147 % \begin{macrocode}
148 \def\fgraphicx@box#1#2{\@ifnextchar[{\fgraphicx@@box{#1}{#2}}%
149 {\fgraphicx@@box{#1}{#2}[]}}
150 % \end{macrocode}
151 % \begin{macrocode}
152 \def\fgraphicx@@box#1#2[#3]#4{%
153 \graphicx@b@x{\fboxsep\z@\color#1{#2}\fbox}{#3}{#4}}
154 % \end{macrocode}
155 % \DescribeMacro{\graphicx@b@x}\cs{graphicx@b@x} is the low-level command that does all the work
156 % now that the parameters have been set. This code is a modification
157 % of \cs{color@b@x} from the \textsf{color.dtx} package.
158 % \begin{macrocode}
159 \long\def\graphicx@b@x#1#2#3#4{\leavevmode
160 \setbox\z@\hbox{\kern\fboxsep{\set@color#4}\kern\fboxsep}%
161 \dimen@\ht\z@\advance\dimen@\fboxsep\ht\z@\dimen@
162 \dimen@\dp\z@\advance\dimen@\fboxsep\dp\z@\dimen@
163 {%\color@block{\wd\z@}{\ht\z@}{\dp\z@}%
164 % \dimen@ii\dp\z@\advance\dimen@ii\ht\z@
165 \dimen@\dp\z@\advance\dimen@\ht\z@
166 \edef\gfxb@totalheight{\the\dimen@}%
167 {#1{\lower\dp\z@\rlap{%
168 \includegraphics[#2,width=\wd\z@,height=\gfxb@totalheight]{#3}}%
169 \box\z@}}}%
170 }
171 %</package>
172 % \end{macrocode}
173 % \Finale
174 \endinput