Mercurial > emacs
annotate lispref/two-volume-cross-refs.txt @ 63022:5e1ac4f79779
(eval-expression-print-level)
(eval-expression-print-length, eval-expression-debug-on-error): Doc fixes.
author | Luc Teirlinck <teirllm@auburn.edu> |
---|---|
date | Sat, 04 Jun 2005 22:04:29 +0000 |
parents | 23a1cea22d13 |
children | 9f4849fee703 |
rev | line source |
---|---|
41193 | 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 | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
31 find this *very* helpful. |
41193 | 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 | |
41 Here are the steps in detail: | |
42 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
43 % tex vol1.texi |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
44 % texindex vol1.?? |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
45 % tex vol1.texi |
41193 | 46 |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
47 % tex vol2.texi |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
48 % texindex vol2.?? |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
49 % tex vol2.texi |
41193 | 50 |
51 ### Create .aux files with volume numbers for other volume. | |
52 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
53 % cp vol1.aux elisp1-aux |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
54 % cp vol2.aux elisp2-aux |
41193 | 55 |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
56 % cp vol1.aux elisp1-aux-vol-number-added |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
57 % cp vol2.aux elisp2-aux-vol-number-added |
41193 | 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 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
67 insert elisp2-aux-vol-number-added into vol1.aux (append) |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
68 insert elisp1-aux-vol-number-added into vol2.aux (prepend) |
41193 | 69 |
70 (so you dont have to do it again) | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
71 % cp vol1.aux elisp1-aux-2vol-ready |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
72 % cp vol2.aux elisp2-aux-2vol-ready |
41193 | 73 |
74 | |
75 ### Create .fn files with volume numbers for other volume. | |
76 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
77 % cp vol1.fn elisp1-fn |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
78 % cp vol2.fn elisp2-fn |
41193 | 79 |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
80 % cp vol1.fn elisp1-fn-vol-number-added |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
81 % cp vol2.fn elisp2-fn-vol-number-added |
41193 | 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 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
91 insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
92 insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' |
41193 | 93 |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
94 % cat elisp2-fn-vol-number-added >> vol1.fn |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
95 % cat elisp1-fn-vol-number-added >> vol2.fn |
41193 | 96 |
97 Be sure to handle special case entries by hand. | |
98 Be sure that .fn file has no blank lines. | |
99 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
100 % texindex vol1.fn |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
101 % texindex vol2.fn |
41193 | 102 |
103 (so you dont have to do it again) | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
104 % cp vol1.fns elisp1-fns-2vol-ready |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
105 % cp vol2.fns elisp2-fns-2vol-ready |
41193 | 106 |
107 ### Create merged .toc file with volume number headings. | |
108 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
109 append vol2.toc to vol1.toc with following `cat' |
41193 | 110 |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
111 % cat vol1.toc vol2.toc > elisp-toc-2vol.toc |
41193 | 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 | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
129 Use keyboard macro to put I: in first half of elisp1-toc.toc and |
41193 | 130 II: in first half of elisp2-toc.toc |
131 | |
132 Copy the tocs to something you can remember more easily | |
133 | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
134 % cp elisp2-toc.toc elisp1-toc-ready.toc |
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
135 % cp elisp1-toc.toc elisp2-toc-ready.toc |
41193 | 136 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
137 Then, edit vol1.texi to input elisp1-toc-ready.toc |
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
138 and vol2.texi to input elisp2-toc-ready.toc |
41193 | 139 |
140 | |
141 ### Now format the two volumes: | |
142 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
143 % cp elisp1-aux-2vol-ready vol1.aux |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
144 % cp elisp2-aux-2vol-ready vol2.aux |
41193 | 145 |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
146 % tex vol1.texi |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
147 % tex vol2.texi |
41193 | 148 |
149 | |
150 | |
151 For every additional run: | |
152 | |
153 ### recopy aux files so the correct ones are read: | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
154 % cp elisp1-aux-2vol-ready vol1.aux |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
155 % cp elisp2-aux-2vol-ready vol2.aux |
41193 | 156 |
157 Do not run texindex. Then proper sorted index will stay. | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
158 else do: % cp elisp2-fns-2vol-ready vol2.fns |
41193 | 159 |
160 Do not change the .texi files; they will call the elisp-toc-2vol.toc file. | |
161 | |
41199
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
162 % tex vol1.texi |
bdecbfc5cb92
Replace elisp-vol? with vol?, per renamed files.
Eli Zaretskii <eliz@gnu.org>
parents:
41193
diff
changeset
|
163 % tex vol2.texi |
41193 | 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 | |
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. | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
220 Apply only to unsorted index file, |
41193 | 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 | |
233 | |
234 The steps: | |
235 | |
236 1. Run TeX, texindex and TeX on file1. | |
237 2. Run TeX, texindex and TeX on file2. | |
238 | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
239 3. Copy both .aux files into specially named files |
41193 | 240 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
241 4. In the case of the elisp ref manual, |
41193 | 242 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
243 copy the *unsorted* function index files into specially named files |
41193 | 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 | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
41199
diff
changeset
|
252 i.e., convert |
41193 | 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 | |
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! |