lispref/two-volume-cross-refs.txt

   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!