| 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 | |
| 43 | % tex vol1.texi |
| 44 | % texindex vol1.?? |
| 45 | % tex vol1.texi |
| 46 | |
| 47 | % tex vol2.texi |
| 48 | % texindex vol2.?? |
| 49 | % tex vol2.texi |
| 50 | |
| 51 | ### Create .aux files with volume numbers for other volume. |
| 52 | |
| 53 | % cp vol1.aux elisp1-aux |
| 54 | % cp vol2.aux elisp2-aux |
| 55 | |
| 56 | % cp vol1.aux elisp1-aux-vol-number-added |
| 57 | % cp vol2.aux elisp2-aux-vol-number-added |
| 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 | |
| 67 | insert elisp2-aux-vol-number-added into vol1.aux (append) |
| 68 | insert elisp1-aux-vol-number-added into vol2.aux (prepend) |
| 69 | |
| 70 | (so you dont have to do it again) |
| 71 | % cp vol1.aux elisp1-aux-2vol-ready |
| 72 | % cp vol2.aux elisp2-aux-2vol-ready |
| 73 | |
| 74 | |
| 75 | ### Create .fn files with volume numbers for other volume. |
| 76 | |
| 77 | % cp vol1.fn elisp1-fn |
| 78 | % cp vol2.fn elisp2-fn |
| 79 | |
| 80 | % cp vol1.fn elisp1-fn-vol-number-added |
| 81 | % cp vol2.fn elisp2-fn-vol-number-added |
| 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 | |
| 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' |
| 93 | |
| 94 | % cat elisp2-fn-vol-number-added >> vol1.fn |
| 95 | % cat elisp1-fn-vol-number-added >> vol2.fn |
| 96 | |
| 97 | Be sure to handle special case entries by hand. |
| 98 | Be sure that .fn file has no blank lines. |
| 99 | |
| 100 | % texindex vol1.fn |
| 101 | % texindex vol2.fn |
| 102 | |
| 103 | (so you dont have to do it again) |
| 104 | % cp vol1.fns elisp1-fns-2vol-ready |
| 105 | % cp vol2.fns elisp2-fns-2vol-ready |
| 106 | |
| 107 | ### Create merged .toc file with volume number headings. |
| 108 | |
| 109 | append vol2.toc to vol1.toc with following `cat' |
| 110 | |
| 111 | % cat vol1.toc vol2.toc > elisp-toc-2vol.toc |
| 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 | |
| 137 | Then, edit vol1.texi to input elisp1-toc-ready.toc |
| 138 | and vol2.texi to input elisp2-toc-ready.toc |
| 139 | |
| 140 | |
| 141 | ### Now format the two volumes: |
| 142 | |
| 143 | % cp elisp1-aux-2vol-ready vol1.aux |
| 144 | % cp elisp2-aux-2vol-ready vol2.aux |
| 145 | |
| 146 | % tex vol1.texi |
| 147 | % tex vol2.texi |
| 148 | |
| 149 | |
| 150 | \f |
| 151 | For every additional run: |
| 152 | |
| 153 | ### recopy aux files so the correct ones are read: |
| 154 | % cp elisp1-aux-2vol-ready vol1.aux |
| 155 | % cp elisp2-aux-2vol-ready vol2.aux |
| 156 | |
| 157 | Do not run texindex. Then proper sorted index will stay. |
| 158 | else do: % cp elisp2-fns-2vol-ready vol2.fns |
| 159 | |
| 160 | Do not change the .texi files; they will call the elisp-toc-2vol.toc file. |
| 161 | |
| 162 | % tex vol1.texi |
| 163 | % tex vol2.texi |
| 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! |