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