Mercurial > emacs
annotate doc/lispref/two-volume-cross-refs.txt @ 97484:ed4b73533ff6
(eshell-ls-files): List one per line in a pipeline, unless at the end
of the pipeline. (Bug#699).
author | Glenn Morris <rgm@gnu.org> |
---|---|
date | Fri, 15 Aug 2008 06:55:37 +0000 |
parents | fde6f792a832 |
children | cb5d2387102c |
rev | line source |
---|---|
87649 | 1 Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 |
84106 | 2 Free Software Foundation, Inc. |
3 See end for copying conditions. | |
4 | |
5 Two Volume Cross References | |
6 =========================== | |
7 | |
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) | |
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 | |
52 find this *very* helpful. | |
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 | |
62 Here are the steps in detail: | |
63 | |
64 % tex vol1.texi | |
65 % texindex vol1.?? | |
66 % tex vol1.texi | |
67 | |
68 % tex vol2.texi | |
69 % texindex vol2.?? | |
70 % tex vol2.texi | |
71 | |
72 ### Create .aux files with volume numbers for other volume. | |
73 | |
74 % cp vol1.aux elisp1-aux | |
75 % cp vol2.aux elisp2-aux | |
76 | |
77 % cp vol1.aux elisp1-aux-vol-added | |
78 % cp vol2.aux elisp2-aux-vol-added | |
79 | |
80 on elisp1-aux-vol-number-added | |
81 (volume-aux-markup 1) see defun for volume-aux-markup below. | |
82 to create elisp1-aux-vol-added | |
83 | |
84 on elisp2-aux-vol-number-added | |
85 (volume-aux-markup 2) | |
86 to create elisp2-aux-vol-added | |
87 | |
88 insert elisp2-aux-vol-added into vol1.aux (append) | |
89 insert elisp1-aux-vol-added into vol2.aux (prepend) | |
90 | |
91 (so you dont have to do it again) | |
92 % cp vol1.aux elisp1-aux-ready | |
93 % cp vol2.aux elisp2-aux-ready | |
94 | |
95 | |
96 ### Create .fn files with volume numbers for other volume. | |
97 | |
98 % cp vol1.fn elisp1-fn | |
99 % cp vol2.fn elisp2-fn | |
100 | |
101 % cp vol1.fn elisp1-fn-vol-number-added | |
102 % cp vol2.fn elisp2-fn-vol-number-added | |
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 | |
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' | |
114 | |
115 % cat elisp2-fn-vol-number-added >> vol1.fn | |
116 % cat elisp1-fn-vol-number-added >> vol2.fn | |
117 | |
118 Be sure to handle special case entries by hand. | |
119 Be sure that .fn file has no blank lines. | |
120 | |
121 % texindex vol1.fn | |
122 % texindex vol2.fn | |
123 | |
124 (so you dont have to do it again) | |
125 % cp vol1.fns elisp1-fns-2vol-ready | |
126 % cp vol2.fns elisp2-fns-2vol-ready | |
127 | |
128 ### Create merged .toc file with volume number headings. | |
129 | |
130 append vol2.toc to vol1.toc with following `cat' | |
131 | |
132 % cat vol1.toc vol2.toc > elisp-toc-2vol.toc | |
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 | |
150 Use keyboard macro to put I: in first half of elisp1-toc.toc and | |
151 II: in first half of elisp2-toc.toc | |
152 | |
153 Copy the tocs to something you can remember more easily | |
154 | |
155 % cp elisp2-toc.toc elisp1-toc-ready.toc | |
156 % cp elisp1-toc.toc elisp2-toc-ready.toc | |
157 | |
158 Then, edit vol1.texi to input elisp1-toc-ready.toc | |
159 and vol2.texi to input elisp2-toc-ready.toc | |
160 | |
161 | |
162 ### Now format the two volumes: | |
163 | |
164 % cp elisp1-aux-2vol-ready vol1.aux | |
165 % cp elisp2-aux-2vol-ready vol2.aux | |
166 | |
167 % tex vol1.texi | |
168 % tex vol2.texi | |
169 | |
170 | |
171 | |
172 For every additional run: | |
173 | |
174 ### recopy aux files so the correct ones are read: | |
175 % cp elisp1-aux-2vol-ready vol1.aux | |
176 % cp elisp2-aux-2vol-ready vol2.aux | |
177 | |
178 Do not run texindex. Then proper sorted index will stay. | |
179 else do: % cp elisp2-fns-2vol-ready vol2.fns | |
180 | |
181 Do not change the .texi files; they will call the elisp-toc-2vol.toc file. | |
182 | |
183 % tex vol1.texi | |
184 % tex vol2.texi | |
185 | |
186 ================================================================ | |
187 | |
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. | |
202 Apply only to unsorted index file, | |
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 | |
215 | |
216 The steps: | |
217 | |
218 1. Run TeX, texindex and TeX on file1. | |
219 2. Run TeX, texindex and TeX on file2. | |
220 | |
221 3. Copy both .aux files into specially named files | |
222 | |
223 4. In the case of the elisp ref manual, | |
224 | |
225 copy the *unsorted* function index files into specially named files | |
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 | |
234 i.e., convert | |
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 | |
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! | |
305 | |
306 | |
307 COPYING CONDITIONS | |
308 | |
95035
fde6f792a832
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
309 This file is free software: you can redistribute it and/or modify |
84106 | 310 it under the terms of the GNU General Public License as published by |
95035
fde6f792a832
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
311 the Free Software Foundation, either version 3 of the License, or |
fde6f792a832
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
312 (at your option) any later version. |
84106 | 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 | |
95035
fde6f792a832
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
87649
diff
changeset
|
320 along with this file. If not, see <http://www.gnu.org/licenses/>. |