Commit | Line | Data |
---|---|---|
9f8bbf0f EZ |
1 | Two Volume Cross References |
2 | =========================== | |
3 | ||
4 | 18 March 1992 | |
5 | ||
6 | This enables you to create manuals in *two* volumes, with tables of | |
7 | contents, cross references, and indices in each volume referring to | |
8 | *both* volumes. | |
9 | ||
10 | The procedure is tedious. However, the resulting two volumes are | |
11 | conveniently organized. Each has an index of the whole two volumes. | |
12 | Each volume starts with page 1. (I don't like multi-volume works | |
13 | where each volume starts with a higher page number since I find it | |
14 | harder to go to the right place in the volume.) | |
15 | ||
16 | References to the same volume are just the page number; references to | |
17 | the other volume are a volumne number (in Roman numerals) preceding | |
18 | the page number. | |
19 | ||
20 | For example, in Volume I: | |
21 | ||
22 | list length ......... 90 | |
23 | list motion ......II:117 | |
24 | ||
25 | and in Volume II: | |
26 | ||
27 | list length ....... I:90 | |
28 | list motion .........117 | |
29 | ||
30 | All other references and the table of contents work the same way. I | |
31 | find this *very* helpful. | |
32 | ||
33 | ||
34 | In brief: you run tex on a .texi file with | |
35 | ||
36 | a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file | |
37 | b. redone .aux file | |
38 | c. redone .fns file | |
39 | ||
40 | \f | |
41 | Here are the steps in detail: | |
42 | ||
c976c1d4 EZ |
43 | % tex vol1.texi |
44 | % texindex vol1.?? | |
45 | % tex vol1.texi | |
9f8bbf0f | 46 | |
c976c1d4 EZ |
47 | % tex vol2.texi |
48 | % texindex vol2.?? | |
49 | % tex vol2.texi | |
9f8bbf0f EZ |
50 | |
51 | ### Create .aux files with volume numbers for other volume. | |
52 | ||
c976c1d4 EZ |
53 | % cp vol1.aux elisp1-aux |
54 | % cp vol2.aux elisp2-aux | |
9f8bbf0f | 55 | |
c976c1d4 EZ |
56 | % cp vol1.aux elisp1-aux-vol-number-added |
57 | % cp vol2.aux elisp2-aux-vol-number-added | |
9f8bbf0f EZ |
58 | |
59 | on elisp1-aux-vol-number-added | |
60 | (volume-aux-markup 1) see defun for volum-aux-markup below. | |
61 | to create elisp1-aux-vol-number-added | |
62 | ||
63 | on elisp2-aux-vol-number-added | |
64 | (volume-aux-markup 2) | |
65 | to create elisp2-aux-vol-number-added | |
66 | ||
c976c1d4 EZ |
67 | insert elisp2-aux-vol-number-added into vol1.aux (append) |
68 | insert elisp1-aux-vol-number-added into vol2.aux (prepend) | |
9f8bbf0f EZ |
69 | |
70 | (so you dont have to do it again) | |
c976c1d4 EZ |
71 | % cp vol1.aux elisp1-aux-2vol-ready |
72 | % cp vol2.aux elisp2-aux-2vol-ready | |
9f8bbf0f EZ |
73 | |
74 | ||
75 | ### Create .fn files with volume numbers for other volume. | |
76 | ||
c976c1d4 EZ |
77 | % cp vol1.fn elisp1-fn |
78 | % cp vol2.fn elisp2-fn | |
9f8bbf0f | 79 | |
c976c1d4 EZ |
80 | % cp vol1.fn elisp1-fn-vol-number-added |
81 | % cp vol2.fn elisp2-fn-vol-number-added | |
9f8bbf0f EZ |
82 | |
83 | on elisp1-fn-vol-number-added | |
84 | (volume-index-markup "I") | |
85 | to create elisp1-fn-vol-number-added | |
86 | ||
87 | on elisp2-fn-vol-number-added | |
88 | (volume-index-markup "II") | |
89 | to create elisp2-fn-vol-number-added | |
90 | ||
c976c1d4 EZ |
91 | insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' |
92 | insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' | |
9f8bbf0f | 93 | |
c976c1d4 EZ |
94 | % cat elisp2-fn-vol-number-added >> vol1.fn |
95 | % cat elisp1-fn-vol-number-added >> vol2.fn | |
9f8bbf0f EZ |
96 | |
97 | Be sure to handle special case entries by hand. | |
98 | Be sure that .fn file has no blank lines. | |
99 | ||
c976c1d4 EZ |
100 | % texindex vol1.fn |
101 | % texindex vol2.fn | |
9f8bbf0f EZ |
102 | |
103 | (so you dont have to do it again) | |
c976c1d4 EZ |
104 | % cp vol1.fns elisp1-fns-2vol-ready |
105 | % cp vol2.fns elisp2-fns-2vol-ready | |
9f8bbf0f EZ |
106 | |
107 | ### Create merged .toc file with volume number headings. | |
108 | ||
c976c1d4 | 109 | append vol2.toc to vol1.toc with following `cat' |
9f8bbf0f | 110 | |
c976c1d4 | 111 | % cat vol1.toc vol2.toc > elisp-toc-2vol.toc |
9f8bbf0f EZ |
112 | |
113 | and edit in Volume titles | |
114 | ||
115 | \unnumbchapentry {Volume 1}{} | |
116 | \unnumbchapentry {}{} | |
117 | ||
118 | \unnumbchapentry {Index}{295} | |
119 | \unnumbchapentry {}{} | |
120 | \unnumbchapentry {Volume 2}{} | |
121 | \unnumbchapentry {}{} | |
122 | ||
123 | If you want to put in volume numbers for TOC, then do this: | |
124 | Create volume specific .toc files with volume numbers in them. | |
125 | ||
126 | % cp elisp-toc-2vol.toc elisp1-toc.toc | |
127 | % cp elisp-toc-2vol.toc elisp2-toc.toc | |
128 | ||
129 | Use keyboard macro to put I: in first half of elisp1-toc.toc and | |
130 | II: in first half of elisp2-toc.toc | |
131 | ||
132 | Copy the tocs to something you can remember more easily | |
133 | ||
134 | % cp elisp2-toc.toc elisp1-toc-ready.toc | |
135 | % cp elisp1-toc.toc elisp2-toc-ready.toc | |
136 | ||
c976c1d4 EZ |
137 | Then, edit vol1.texi to input elisp1-toc-ready.toc |
138 | and vol2.texi to input elisp2-toc-ready.toc | |
9f8bbf0f EZ |
139 | |
140 | ||
141 | ### Now format the two volumes: | |
142 | ||
c976c1d4 EZ |
143 | % cp elisp1-aux-2vol-ready vol1.aux |
144 | % cp elisp2-aux-2vol-ready vol2.aux | |
9f8bbf0f | 145 | |
c976c1d4 EZ |
146 | % tex vol1.texi |
147 | % tex vol2.texi | |
9f8bbf0f EZ |
148 | |
149 | ||
150 | \f | |
151 | For every additional run: | |
152 | ||
153 | ### recopy aux files so the correct ones are read: | |
c976c1d4 EZ |
154 | % cp elisp1-aux-2vol-ready vol1.aux |
155 | % cp elisp2-aux-2vol-ready vol2.aux | |
9f8bbf0f EZ |
156 | |
157 | Do not run texindex. Then proper sorted index will stay. | |
c976c1d4 | 158 | else do: % cp elisp2-fns-2vol-ready vol2.fns |
9f8bbf0f EZ |
159 | |
160 | Do not change the .texi files; they will call the elisp-toc-2vol.toc file. | |
161 | ||
c976c1d4 EZ |
162 | % tex vol1.texi |
163 | % tex vol2.texi | |
9f8bbf0f EZ |
164 | |
165 | ================================================================ | |
166 | ||
167 | @c ================================================================ | |
168 | @tex | |
169 | % Special @contents command | |
170 | % This inputs fixed up table of contents file rather than create new one. | |
171 | \global\def\contents{% | |
172 | \startcontents{Table of Contents}% | |
173 | \input elisp-toc-2vol.toc | |
174 | \endgroup | |
175 | \vfill \eject | |
176 | } | |
177 | ||
178 | % Special @summarycontents command | |
179 | % This inputs fixed up table of contents file rather than create new one. | |
180 | \outer\def\summarycontents{% | |
181 | \startcontents{Short Contents}% | |
182 | % | |
183 | \let\chapentry = \shortchapentry | |
184 | \let\unnumbchapentry = \shortunnumberedentry | |
185 | % We want a true roman here for the page numbers. | |
186 | \secfonts | |
187 | \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl | |
188 | \rm | |
189 | \advance\baselineskip by 1pt % Open it up a little. | |
190 | \def\secentry ##1##2##3##4{} | |
191 | \def\unnumbsecentry ##1##2{} | |
192 | \def\subsecentry ##1##2##3##4##5{} | |
193 | \def\unnumbsubsecentry ##1##2{} | |
194 | \def\subsubsecentry ##1##2##3##4##5##6{} | |
195 | \def\unnumbsubsubsecentry ##1##2{} | |
196 | \input elisp-toc-2vol.toc | |
197 | \endgroup | |
198 | \vfill \eject | |
199 | } | |
200 | @end tex | |
201 | @c ================================================================ | |
202 | ||
203 | ||
204 | ================================================================ | |
205 | \f | |
206 | ||
207 | (defun volume-aux-markup (arg) | |
208 | "Append `vol. NUMBER' to page number. | |
209 | Apply to aux file that you save. | |
210 | Then insert marked file into other volume's .aux file." | |
211 | (interactive "sType volume number, 1 or 2: " ) | |
212 | (goto-char (point-min)) | |
213 | (while (search-forward "-pg" nil t) | |
214 | (end-of-line 1) | |
215 | (delete-backward-char 1 nil) | |
216 | (insert ", vol.'tie" arg "}"))) | |
217 | ||
218 | (defun volume-index-markup (arg) | |
219 | "Prepend `NUMBER:' to page number. Use Roman Numeral. | |
220 | Apply only to unsorted index file, | |
221 | Then insert marked file into other volume's unsorted index file. | |
222 | Then run texindex on that file and save." | |
223 | (interactive | |
224 | "sType volume number, roman number I or II: " ) | |
225 | (goto-char (point-min)) | |
226 | (while (search-forward "\\entry" nil t) | |
227 | (search-forward "}{" (save-excursion (end-of-line) (point)) nil) | |
228 | (insert arg ":"))) | |
229 | ||
230 | ||
231 | ================================================================ | |
232 | \f | |
233 | ||
234 | The steps: | |
235 | ||
236 | 1. Run TeX, texindex and TeX on file1. | |
237 | 2. Run TeX, texindex and TeX on file2. | |
238 | ||
239 | 3. Copy both .aux files into specially named files | |
240 | ||
241 | 4. In the case of the elisp ref manual, | |
242 | ||
243 | copy the *unsorted* function index files into specially named files | |
244 | (no other index used in elisp ref manual) | |
245 | ||
246 | ||
247 | 5. For aux files: | |
248 | ||
249 | Run a function on the specially named .aux files to label each | |
250 | entry according to volume. Save these files. | |
251 | ||
252 | i.e., convert | |
253 | 'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1} | |
254 | ||
255 | 5a.Insert each specially named .aux file into the regular .aux file of | |
256 | the other volume. | |
257 | ||
258 | 6. For index files: | |
259 | ||
260 | Run a function on the specially named unsorted index files to label | |
261 | each entry according to volume. Save these files. | |
262 | ||
263 | 6b.Insert each specially named marked unsorted index file into the | |
264 | regular unsorted file of the other volume. Run texindex on this | |
265 | ||
266 | 7. Insert the other volumes .toc file into the .toc, edit, and rename to | |
267 | elisp-toc-2vol.toc | |
268 | ||
269 | 7a. insert special @contents and @summarycontents defs into .texi files. | |
270 | ||
271 | 8. Run TeX on each .texi file. | |
272 | ||
273 | ================ | |
274 | ||
275 | ||
276 | \f | |
277 | Here is the discursive commentary: | |
278 | ||
279 | I've been running some small test files, called test1.texi and | |
280 | test2.texi. As far as I can see, if we run tex on the two test files, | |
281 | tex creates a .aux for each that includes the names of all the nodes | |
282 | in that file. The node names are used for cross references. | |
283 | ||
284 | If you insert the .aux file for the second test file, test2.aux, into | |
285 | the .aux file for the first test file, test1.aux, then when you next | |
286 | run TeX on the first test file, test1.texi, the second volume cross | |
287 | references are inserted. | |
288 | ||
289 | You can edit the text of the cross reference in test2.aux to include | |
290 | the volume number. | |
291 | ||
292 | For example, you can take the following two lines from test1.texi and | |
293 | insert them into test2.texi: | |
294 | ||
295 | 'xrdef {Special-pg}{7} | |
296 | 'xrdef {Special-snt}{Section'tie1.6} | |
297 | ||
298 | You can re-edit this to show that the page is in volume 1: | |
299 | ||
300 | 'xrdef {Special-pg}{7, vol.'tie1} | |
301 | 'xrdef {Special-snt}{Section'tie1.6} | |
302 | ||
303 | (The 'tie is a TeX special command to keep the number tied on one | |
304 | line to the previous word. I don't know if it works after a period in | |
305 | the "vol." but figure it is worth trying. {The ' is the @ of .aux files.} | |
306 | Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the | |
307 | definition for 'tie is the following: | |
308 | ||
309 | \def\tie{\penalty 10000\ } % Save plain tex definition of ~. | |
310 | ||
311 | ) | |
312 | ||
313 | After running tex on the test2.texi file with the augmented test2.aux | |
314 | file, you can see the following in the resulting DVI file: | |
315 | ||
316 | See Section 1.6 [Special], page 7, vol. 1 | |
317 | ||
318 | Note that TeX rewrites the .aux file each time TeX is run, so after | |
319 | running Tex using an .aux file augmented with the .aux file from the | |
320 | other volume, the new .aux file will *lack* the other volumes cross | |
321 | references. Save your augmented .aux file in some other name for | |
322 | another run! |