Mercurial > emacs
annotate doc/lispref/two-volume-cross-refs.txt @ 97366:d2c211c8ceda
(w32_list_system_processes, w32_system_process_attributes): Add prototypes.
(Qeuid, Qegid, Qcomm, Qstate, Qppid, Qpgrp, Qsess, Qttname)
(Qminflt, Qmajflt, Qcminflt, Qcmajflt, Qutime, Qstime, Qcutime)
(Qpri, Qnice, Qthcount, Qstart, Qvsize, Qrss, Qargs, Quser, Qgroup)
(Qetime, Qpcpu, Qpmem, Qtpgid, Qcstime): Add extern declarations.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 09 Aug 2008 17:53:30 +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/>. |