summaryrefslogtreecommitdiff
path: root/dviware/dvipaste/dvipaste.doc
blob: 10934333a4077e2f5bcaa10ac08cd405dd657f98 (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
The dvipaste program was first described in the article

      HI-TeX Cutting & Pasting

in TUGboat, Volume 10 (1989), No. 2, pages 164--165.  Consult this article
for further details. (``TUGboat, The Communications of the TeX Users Group'',
is published by TeX Users Group, P. O. Box 9506, Providence, RI 02940.)

The dvipaste program is designed to produce files that conform to the TeX
specifications for .dvi files, even though they may actually be too big to be
produced with normal implementations of TeX (because of limitations on memory
size).  More particularly, it allows the material appearing on individual
pages of a `secondary' file to be inserted into a `main' file.

The `secondary' file, say `extra.tex', should be of the form

      \input dvipaste
      \input <macro packages>

      <define a control sequence, say \csq, to stand for a complicated object>
             or
      <store some complicated object in a TeX box, say in \box0 >

      \sendout{\csq}   or   \sendout{\box0 }

      <store another object>
      \sendout{...}
        . . .
      \end

The main file, say `big.tex', should have

      \input dvipaste

at the beginning, and then

      \paste{extra}{<number>}

at any point, to indicate that the material on page <number> of `extra.dvi'
is to be pasted in at that point.

The secondary file `extra.tex' must be TeX'ed before the main file, because
the \paste commands use information from a file `extra.dat' that is created
when the secondary file is TeX'ed.

When the main file is TeX'ed, blank spaces of the proper size will appear at
the points where the \paste commands were placed.  After using the dvipaste
program,

      dvipaste big 

the new big.dvi file will actually have the proper material from the
secondary file pasted in, and will give the desired result when printed out.

[You can also type

      dvipaste big newbig

if you want to save the big.dvi file, and create a new .dvi file, newbig.dvi.
(With TeXtures you MUST choose a new name, because TeXtures won't allow you
to make a TeXtures document out of a different big.dvi when the first one
already exists as a resource to big.tex.)]

The dvipaste.tex macro package will not allow both a \sendout and a \paste to
occur in the same file, so that a file must be used either as a main file or
as a secondary file.  However, an arbitrary number of secondary files can be
used in a main file, and the <number>'s appearing in \paste commands do not
have to be consecutive.

                              * * *

The lamstex.tex macro package essentially includes the part of the
dvipaste.tex macro packages that is used to make \paste be defined.

The lamstbl.tex macro package essentially includes the part of the
dvipaste.tex macro package that is used to make \sendout be defined.
However, \sendout is never actually used in LamS-TeX because an \endtable in
a LamS-TeX tables file essentially does the \sendout.

                              * * * 

One possible use for dvipaste.tex is for files produced by PiCTeX.  The
.dvi files that PiCTeX produces for a figure are often so large that
although the figure alone can be printed, it cannot be combined with other
text on that page, because TeX doesn't have enough memory to store such a
large .dvi file (especially when it has to store all the macros being
used). For such situations, one could create a secondary file for the
pictures,

      \input dvipaste
      \input pictex
      <store a picture in a box or a control sequence>
      \sendout{the picture}
        . . .

and then \paste the pictures into the main file at the appropriate point.

This should be applicable with LamS-TeX also. The secondary file, say
`pictures.tex', should be treated as an ordinary TeX file, NOT as a LamS-TeX
file (if the pictures include some text, new fonts can be introduced after
the \input pictex line, if necessary).  Then in the main LamS-TeX file,

      \paste{pictures}{<number>}

can be inserted at any point.  For example, you might use such a \paste
instead of an \hbyw{...}{...} construction in a \figure ... \endfigure.

                              * * * * * *

                     EXAMPLE OF THE USE OF DVIPASTE
 
The files boxes1.tex, boxes2.tex, and join.tex all begin with 

      \input dvipaste

and illustrate the general use of the dvipaste program.  To see it action,

(1) First do

      tex boxes1
and
      tex boxes2

This will produce boxes1.dvi and boxes2.dvi, which you can print or view,
as well as boxes1.dat and boxes2.dat.

(2) Then, once boxes1.dat and boxes2.dat have been produced, do

      tex join

producing join.dvi, which you can print or view. 

(3) Finally, do

      dvipaste join newjoin

to produce a newjoin.dvi.  When you view or print this, the boxes will have
been pasted in.

(4) You can also simply do

	dvipaste join

if you want the old join.dvi to be replaced by a new one, with the boxes 
pasted in (not possible with TeXtures).