summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/grfpaste/doc/grfpaste.tex
blob: 070ddb2b1d3e7f1a818352d18a9d4913e0d94bde (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
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
\documentclass[numbers=noenddot, pagesize=auto]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{etoolbox}
\usepackage{xspace}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage[svgnames]{xcolor}
\usepackage{listings}
\usepackage{microtype}
\usepackage[unicode=true]{hyperref}

\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\opt}[1]{\texttt{#1}}
\newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle}
\newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}}

\renewcommand*{\thesubsection}{\thesection\,\alph{subsection}}
\renewcommand*{\theenumi}{\alph{enumi}}
\renewcommand*{\labelenumi}{\theenumi)}
\addtokomafont{title}{\rmfamily}

% fix bug in listings package, see http://groups.google.de/group/comp.text.tex/browse_thread/thread/b004ec97fd72613a
\makeatletter
\preto\lstlisting{\global\@noskipsectrue}
\makeatother

\lstset{%
  language=[LaTeX]TeX,%
  columns=fullflexible,%
  upquote=true,%
  numbers=left,%
  basicstyle=\small\ttfamily,%
  keywordstyle=\color{Navy},%
  commentstyle=\color{DimGray},%
  stringstyle=\color{SeaGreen},%
  numberstyle=\scriptsize\color{SlateGray}%
}


\title{The \pkg{grfpaste} package\thanks{This manual corresponds to \pkg{grfpaste}~v0.2, dated~1997/07/18.}}
\subtitle{\LaTeX\ support for \TeX plorators / M. Spivak \texttt{dvipaste} program}
\author{David Carlisle}
\date{1997/07/18}


\begin{document}

\maketitle

\tableofcontents

\begin{quote}
  \footnotesize
  This package can redistributed and/or modified under the terms
  of the \LaTeX\ Project Public License Distributed from CTAN
  archives in directory \texttt{macros/latex/base/lppl.txt}; either
  version~1 of the License, or (at your option) any later version.
\end{quote}

\noindent
\texttt{Dvipaste} comes with a plain~\TeX\ based set of macros in a file
\texttt{dvipaste.tex} that provide an interface to the \texttt{dvipaste} program. That
file works perfectly well in \LaTeX\ with only minor modifications
(specifically using \cmd{\@@line} instead of \cmd{\line}, and \cmd{\c@page} instead of
\cmd{\pageno}). A \texttt{dvipaste.sty} constructed by just such modifications may be
found distributed with Jean-Pierre Drucbert's `\pkg{export'} package on \textsc{ctan}.
However I thought that it would be more in the `\LaTeX\ spirit'
to provide an interface via the existing \LaTeX\ graphics package.

The files produced by this \pkg{grfpaste} package should be fully compatible
with \texttt{dvi\-paste.tex} or \texttt{dvipaste.sty}. That is, if \textsc{dvi} fragments are
created using the plain~\TeX\ interface they may be included using
\cmd{\includegraphics} via this package, and conversely if this package is
used with the \opt{[write]} or \opt{[writepages]} options to produce a file of \textsc{dvi}
fragments for including in another file, then the \textsc{dvi} file (and it's
accompanying `\texttt{.dat}' file of size information) may be included either
with this package, or via the original \texttt{dvipaste.tex} interface.

Currently the \LaTeX\ interface uses the \pkg{graphicx} package, it would be
possible to also provide an interface to the more basic \pkg{graphics}
package, but that is not done here.

The package is used in one of two forms.



\section{Producing DVI Fragments}

\subsection{Writing out boxes.}

\begin{lstlisting}
\documentclass{article}

\usepackage[write]{grfpaste}

\begin{document}

\sendout{\parbox[b]{2cm}{one \sf two three \tt four \it five}}

\sendout[abc]{hello}

\sendout{\parbox[t]{2cm}{one \sf two three \tt four \it five}}

\end{document}
\end{lstlisting}
%
If the package is used with the \opt{[write]} option then the document should
just consist of \cmd{\sendout} commands, the argument of each will be marked
as a `fragment' that may be pasted into another DVI file by the \texttt{dvipaste}
program. An auxiliary file with extension \texttt{.dat} will be created which
contains the size of each of these fragments. Normally the fragments
will be accessed by their number, starting from~1, but you may
optionally supply a label, as in `\texttt{abc}' above which allows fragments to
be referenced more easily. The above example forms the example
document \texttt{grfp1.tex} in this distribution.


\subsection{Writing out whole pages.}

\begin{lstlisting}
\documentclass{article}

\usepackage[writepages]{grfpaste}

\begin{document}
...
\end{document}
\end{lstlisting}
%
If the package is used with the \opt{[writepages]} option then each
indivdual page will be marked as a `fragment' for later processing by
\texttt{dvipaste}. The fragments will be numbered consecutively, starting from~%
1, whatever the value of the page counter.  See the example document
\texttt{grfp2.tex}.



\section{Using DVI Fragments}

\begin{lstlisting}
\documentclass{article}

\usepackage{grfpaste}

\begin{document}

aaa\fbox{\includegraphics
        [num=1,natheight=19,natdepth=2pt,natwidth=57]{grfp1.dvi}}bbb

xxx\fbox{\includegraphics[num=2]{grfp1.dvi}}yyy

xxx\fbox{\includegraphics[ref=abc]{grfp1.dvi}}yyy

Page 3 of grfp2.dvi:
aaa\fbox{\includegraphics[num=3]{grfp2}}bbb

\end{document}
\end{lstlisting}
%
To use the fragments then load the package with no option (or
equivalently with the \opt{[include]} option). You may also use any options
understood by the \pkg{graphicx} package, these will be passed on to \pkg{graphicx}
which is loaded by this package.

To load the first fragment of a given \textsc{dvi} file you just need
\cmd{\include\-graphics}\marg{file\-name} or \cmd{\include\-graphics}\texttt{\{}\meta{file\-name}\texttt{.dvi\}}
(\texttt{.dvi} is added as one of the default extensions by this package)

To access later fragments then you use the new \texttt{num=}\meta{??} key to specify
the fragment number, as demonstrated above. If there are a lot of
fragments maintaining the correct number may be inconvenient so you
may instead use the \texttt{ref=} key to refer to a label previously supplied
by the \cmd{\sendout} command. Note this label information is added to the
\texttt{.dat} file in the form of a comment (after \texttt{\%}) and so the \texttt{.dat} file is
still compatible with  \texttt{dvipaste.tex}, but if that is used, then the
numeric form must be used. Thus the two examples above with \texttt{num=2}
and \texttt{ref=abc} include the same fragment from the file \texttt{grfp1.dvi}.

Normally the size of the graphic is read from the `\texttt{.dat}' file which is
the `read file' for the \textsc{dvi} graphic type, in the terminoligy of the
\pkg{graphics} package documentation.  If you have lost the \texttt{.dat} file, or
wish to override it with altered sizes, you may specify the natural
size using the \texttt{natheight}, \texttt{natwidth} and \texttt{natdepth} keys. As usual these
take a dimension but the units may be omitted in which case \texttt{bp} are
assumed.  \texttt{natheight} and \texttt{natwidth} are standard \pkg{graphicx} keys, but
\texttt{natdepth} is new, as these fragments are \TeX\ boxes, so have height and
depth, unlike most other graphic formats that may be included, which
always have zero depth.

The \cmd{\sendout} command defined by the \opt{[write]} option matches that used
in the plain~\TeX\ support, but the plain~\TeX\ version does not use
\cmd{\includegraphics} to include the fragment. It defines a command \cmd{\paste}
to achieve this. In order to help move documents between the two
versions, a \opt{[defpaste]} option is provided for this package which
specifies that a compatible \cmd{\paste} command should be defined. It is
defined to be the equivalent call to \cmd{\includegraphics},
\verb+\includegraphics[num=#2]{#1}+.

See the example file \texttt{grfp3.tex} to see examples of including \textsc{dvi}
fragments.



\section{Putting it all together}

\begin{enumerate}
\item Produce one or more files of fragments using
  \LaTeX\ and this package with the \opt{[write]} or \opt{[writepages]} options.
  (or plain~\TeX\ using \texttt{dvipaste.tex}).
  
\item \LaTeX\ your master document, including this package and using
  \cmd{\includegraphics} to include the fragments at the appropriate points.
  
  At this stage the file will have blank spaces (but if the correct
  size) at the points where the \textsc{dvi} fragments should appear
  
\item  Run \texttt{dvipaste} on the master \textsc{dvi} file. It will incorporate the
  fragments and re-write the file.
  
\item  Preview or print the modified \textsc{dvi} file in your usual manner.
\end{enumerate}



\section{Running the examples}

\lstset{language=bash}

\begin{itemize}
\item \texttt{grfp1.tex} is an example of using the \opt{[write]} option
\item \texttt{grfp2.tex} is an example of using the \opt{[writepages]} option
\item \texttt{grfp3.tex} is an example of using the \opt{[include]} option
\end{itemize}
%
To process the final document (\texttt{grfp3.dvi}) the following steps need be
taken.
%
\begin{lstlisting}
latex grfp1
latex grfp2
latex grfp2
latex grfp3
dvipaste grfp3
\end{lstlisting}
%
Note that \texttt{grfp2} needs to be processed twice to generate a full table of
contents. After \texttt{grfp3.tex} is processed by \LaTeX\ the \textsc{dvi} file will show
blank spaces at the points that the fragments are to be included. These
will be filled in by running \texttt{dvipaste}, after which the \texttt{grfp3.dvi} may be
processed by your driver in the normal way.



\section{Compiling \texttt{dvipaste.c}}

\lstset{language=C}

\begin{lstlisting}
/* config.h for LINUX machines for dvipaste.c (DPC) */


#define ANSI
#undef MICROSOFTC
#define LITTLENDIAN

/* I guess this is what was meant. */
/* (dvipaste.c defines strcmp to itself */
/* leaving stricmp undefined) .*/
#ifndef MICROSOFTC
#define strnicmp strncmp
#define stricmp strcmp
#endif

#ifdef ANSI
/* Other things in ANSI C are good, but this is a crock */
#define READ_BINARY "rb"
#define WRITE_BINARY "wb"
#else
/* The good old simple and logical K&R I/O */
#define READ_BINARY "r"
#define WRITE_BINARY "w"
#endif
\end{lstlisting}
%
When I tried compiling \texttt{dvipaste.c} I got error due to the function
\texttt{stricmp} being undefined. The file has a circular definition of \texttt{strcmp}
to itself which looks like a typo, so I corrected that by making 
\texttt{stricmp} an alias for \texttt{strcmp} by altering \texttt{config.h} as above (which also
sets \texttt{LITTLENDIAN} for Linux. It seems to work for me, but no promises.

The above suggested \texttt{config.h} leaves \texttt{stricmp} meaning the same thing as
\texttt{strcmp} (string comparison). Jean-Pierre Drucbert points out that
\texttt{stricmp} is (on systems that it is defined) a case-insensitive
comparison function, and that rather than the crude substitution above
one may define it as follows.
%
\begin{quote}
  \texttt{str\{n\}icmp} is not available on all systems. So I got the
  following code in \texttt{ci.c}~:
  %
\begin{lstlisting}
#include <ctype.h>
#include "config.h"
/*
* str{n}icmp - case-insensitive flavors of strcmp(), strncmp()
*/
#ifdef PROTOS
int stricmp(register char *s1,
register char *s2)
#else
int stricmp(s1, s2)
register char *s1, *s2;
#endif
{
  register char c1, c2;
  
  for ( ; (c1 = TOLOWER(*s1)) == (c2 = TOLOWER(*s2)); s1++, s2++)
  if (c1 == '\0')
  return 0;
  
  return c1 - c2;
}


#ifdef PROTOS
int strnicmp(register char *s1,
register char *s2,
int n)
#else
int strnicmp(s1, s2, n)
register char *s1, *s2;
int n;
#endif
{
  register char c1, c2;
  
  for ( ; --n >= 0 &&
  (c1 = TOLOWER(*s1)) == (c2 = TOLOWER(*s2)); s1++, s2++)
  if (c1 == '\0')
  return 0;
  
  return n < 0 ? 0 : c1 - c2;
}
\end{lstlisting}
\end{quote}

By default \texttt{dvipaste.c} has
%
\begin{lstlisting}
#define STRINGSIZE (5124)       /* maximum string size */
\end{lstlisting}
%
Jean-Pierre Drucbert commented:
%
\begin{quote}
  it is necessary to increase \texttt{STRINGSIZE} if you paste a lot of \textsc{dvi}
  pieces (I~increased it from 40592 to 2597888)\@. In practice, do
  not export more than~\textasciitilde 100 pieces from one file. You can import a
  lot more into one file. So it is preferable to import from
  several files if you have more than 100 pieces to import.
\end{quote}

\end{document}