lispref/two-volume-cross-refs.txt

   1 Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
   2   Free Software Foundation, Inc.
   3   See end for copying conditions.
   4
   5 Two Volume Cross References
   6 ===========================
   7
   8 18 March 1992
   9
  10 This enables you to create manuals in *two* volumes, with tables of
  11 contents, cross references, and indices in each volume referring to
  12 *both* volumes.
  13
  14 The procedure is tedious.  However, the resulting two volumes are
  15 conveniently organized.  Each has an index of the whole two volumes.
  16 Each volume starts with page 1.  (I don't like multi-volume works
  17 where each volume starts with a higher page number since I find it
  18 harder to go to the right place in the volume.)
  19
  20 References to the same volume are just the page number; references to
  21 the other volume are a volumne number (in Roman numerals) preceding
  22 the page number.
  23
  24 For example, in Volume I:
  25
  26     list length ......... 90
  27     list motion ......II:117
  28
  29 and in Volume II:
  30
  31     list length ....... I:90
  32     list motion .........117
  33
  34 All other references and the table of contents work the same way.  I
  35 find this *very* helpful.
  36
  37
  38 In brief: you run tex on a .texi file with
  39
  40   a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file
  41   b. redone .aux file
  42   c. redone .fns file
  43
  44 \f
  45 Here are the steps in detail:
  46
  47 % tex vol1.texi
  48 % texindex vol1.??
  49 % tex vol1.texi
  50
  51 % tex vol2.texi
  52 % texindex vol2.??
  53 % tex vol2.texi
  54
  55 ### Create .aux files with volume numbers for other volume.
  56
  57 % cp vol1.aux elisp1-aux
  58 % cp vol2.aux elisp2-aux
  59
  60 % cp vol1.aux elisp1-aux-vol-number-added
  61 % cp vol2.aux elisp2-aux-vol-number-added
  62
  63 on elisp1-aux-vol-number-added
  64 (volume-aux-markup 1)           see defun for volum-aux-markup below.
  65 to create             elisp1-aux-vol-number-added
  66
  67 on elisp2-aux-vol-number-added
  68 (volume-aux-markup 2)
  69 to create             elisp2-aux-vol-number-added
  70
  71 insert elisp2-aux-vol-number-added into vol1.aux  (append)
  72 insert elisp1-aux-vol-number-added into vol2.aux  (prepend)
  73
  74 (so you dont have to do it again)
  75 % cp vol1.aux elisp1-aux-2vol-ready
  76 % cp vol2.aux elisp2-aux-2vol-ready
  77
  78
  79 ### Create .fn files with volume numbers for other volume.
  80
  81 % cp vol1.fn elisp1-fn
  82 % cp vol2.fn elisp2-fn
  83
  84 % cp vol1.fn elisp1-fn-vol-number-added
  85 % cp vol2.fn elisp2-fn-vol-number-added
  86
  87 on elisp1-fn-vol-number-added
  88 (volume-index-markup "I")
  89 to create             elisp1-fn-vol-number-added
  90
  91 on elisp2-fn-vol-number-added
  92 (volume-index-markup "II")
  93 to create             elisp2-fn-vol-number-added
  94
  95 insert elisp2-fn-vol-number-added into vol1.fn: do following `cat'
  96 insert elisp1-fn-vol-number-added into vol2.fn: do following `cat'
  97
  98 % cat elisp2-fn-vol-number-added >> vol1.fn
  99 % cat elisp1-fn-vol-number-added >> vol2.fn
 100
 101 Be sure to handle special case entries by hand.
 102 Be sure that .fn file has no blank lines.
 103
 104 % texindex vol1.fn
 105 % texindex vol2.fn
 106
 107 (so you dont have to do it again)
 108 % cp vol1.fns elisp1-fns-2vol-ready
 109 % cp vol2.fns elisp2-fns-2vol-ready
 110
 111 ### Create merged .toc file with volume number headings.
 112
 113 append vol2.toc to vol1.toc  with following `cat'
 114
 115 % cat vol1.toc vol2.toc > elisp-toc-2vol.toc
 116
 117 and edit in Volume titles
 118
 119 \unnumbchapentry {Volume 1}{}
 120 \unnumbchapentry {}{}
 121
 122 \unnumbchapentry {Index}{295}
 123 \unnumbchapentry {}{}
 124 \unnumbchapentry {Volume 2}{}
 125 \unnumbchapentry {}{}
 126
 127 If you want to put in volume numbers for TOC, then do this:
 128 Create volume specific .toc files with volume numbers in them.
 129
 130 % cp elisp-toc-2vol.toc elisp1-toc.toc
 131 % cp elisp-toc-2vol.toc elisp2-toc.toc
 132
 133 Use keyboard macro to put I: in first half of elisp1-toc.toc and
 134 II: in first half of elisp2-toc.toc
 135
 136 Copy the tocs to something you can remember more easily
 137
 138 % cp elisp2-toc.toc elisp1-toc-ready.toc
 139 % cp elisp1-toc.toc elisp2-toc-ready.toc
 140
 141 Then, edit vol1.texi to input elisp1-toc-ready.toc
 142 and vol2.texi to input elisp2-toc-ready.toc
 143
 144
 145 ### Now format the two volumes:
 146
 147 % cp elisp1-aux-2vol-ready vol1.aux
 148 % cp elisp2-aux-2vol-ready vol2.aux
 149
 150 % tex vol1.texi
 151 % tex vol2.texi
 152
 153
 154 \f
 155 For every additional run:
 156
 157 ### recopy aux files so the correct ones are read:
 158 % cp elisp1-aux-2vol-ready vol1.aux
 159 % cp elisp2-aux-2vol-ready vol2.aux
 160
 161 Do not run texindex.  Then proper sorted index will stay.
 162  else do: % cp elisp2-fns-2vol-ready vol2.fns
 163
 164 Do not change the .texi files; they will call the elisp-toc-2vol.toc file.
 165
 166 % tex vol1.texi
 167 % tex vol2.texi
 168
 169 ================================================================
 170
 171 @c ================================================================
 172 @tex
 173 % Special @contents  command
 174 % This inputs fixed up table of contents file rather than create new one.
 175 \global\def\contents{%
 176    \startcontents{Table of Contents}%
 177       \input elisp-toc-2vol.toc
 178    \endgroup
 179    \vfill \eject
 180 }
 181
 182 % Special @summarycontents  command
 183 % This inputs fixed up table of contents file rather than create new one.
 184 \outer\def\summarycontents{%
 185    \startcontents{Short Contents}%
 186       %
 187       \let\chapentry = \shortchapentry
 188       \let\unnumbchapentry = \shortunnumberedentry
 189       % We want a true roman here for the page numbers.
 190       \secfonts
 191       \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl
 192       \rm
 193       \advance\baselineskip by 1pt % Open it up a little.
 194       \def\secentry ##1##2##3##4{}
 195       \def\unnumbsecentry ##1##2{}
 196       \def\subsecentry ##1##2##3##4##5{}
 197       \def\unnumbsubsecentry ##1##2{}
 198       \def\subsubsecentry ##1##2##3##4##5##6{}
 199       \def\unnumbsubsubsecentry ##1##2{}
 200       \input elisp-toc-2vol.toc
 201    \endgroup
 202    \vfill \eject
 203 }
 204 @end tex
 205 @c ================================================================
 206
 207
 208 ================================================================
 209 \f
 210
 211 (defun volume-aux-markup (arg)
 212   "Append `vol. NUMBER' to page number.
 213 Apply to aux file that you save.
 214 Then insert marked file into other volume's .aux file."
 215   (interactive "sType volume number, 1 or 2: " )
 216   (goto-char (point-min))
 217   (while (search-forward "-pg" nil t)
 218     (end-of-line 1)
 219     (delete-backward-char 1 nil)
 220     (insert ", vol.'tie" arg "}")))
 221
 222 (defun volume-index-markup (arg)
 223   "Prepend  `NUMBER:' to page number.  Use Roman Numeral.
 224 Apply only to unsorted index file,
 225 Then insert marked file into other volume's unsorted index file.
 226 Then run texindex on that file and save."
 227   (interactive
 228    "sType volume number,  roman number I or II: " )
 229   (goto-char (point-min))
 230   (while (search-forward "\\entry" nil t)
 231     (search-forward "}{" (save-excursion (end-of-line) (point)) nil)
 232     (insert arg ":")))
 233
 234
 235 ================================================================
 236 \f
 237
 238 The steps:
 239
 240 1. Run TeX, texindex and TeX on file1.
 241 2. Run TeX, texindex and TeX on file2.
 242
 243 3. Copy both .aux files into specially named files
 244
 245 4. In the case of the elisp ref manual,
 246
 247    copy the *unsorted* function index files into specially named files
 248    (no other index used in elisp ref manual)
 249
 250
 251 5. For aux files:
 252
 253    Run a function on the specially named .aux files to label each
 254    entry according to volume.  Save these files.
 255
 256    i.e., convert
 257    'xrdef {Special-pg}{7}  to 'xrdef {Special-pg}{7, vol.'tie1}
 258
 259 5a.Insert each specially named .aux file into the regular .aux file of
 260    the other volume.
 261
 262 6. For index files:
 263
 264    Run a function on the specially named unsorted index files to label
 265    each entry according to volume.  Save these files.
 266
 267 6b.Insert each specially named marked unsorted index file into the
 268    regular unsorted file of the other volume.  Run texindex on this
 269
 270 7. Insert the other volumes .toc file into the .toc, edit, and rename to
 271    elisp-toc-2vol.toc
 272
 273 7a. insert special @contents and @summarycontents defs into .texi files.
 274
 275 8. Run TeX on each .texi file.
 276
 277 ================
 278
 279
 280 \f
 281 Here is the discursive commentary:
 282
 283 I've been running some small test files, called test1.texi and
 284 test2.texi.  As far as I can see, if we run tex on the two test files,
 285 tex creates a .aux for each that includes the names of all the nodes
 286 in that file.  The node names are used for cross references.
 287
 288 If you insert the .aux file for the second test file, test2.aux, into
 289 the .aux file for the first test file, test1.aux, then when you next
 290 run TeX on the first test file, test1.texi, the second volume cross
 291 references are inserted.
 292
 293 You can edit the text of the cross reference in test2.aux to include
 294 the volume number.
 295
 296 For example, you can take the following two lines from test1.texi and
 297 insert them into test2.texi:
 298
 299     'xrdef {Special-pg}{7}
 300     'xrdef {Special-snt}{Section'tie1.6}
 301
 302 You can re-edit this to show that the page is in volume 1:
 303
 304     'xrdef {Special-pg}{7, vol.'tie1}
 305     'xrdef {Special-snt}{Section'tie1.6}
 306
 307 (The  'tie  is a TeX special command to keep the number tied on one
 308 line to the previous word.  I don't know if it works after a period in
 309 the "vol." but figure it is worth trying.  {The  ' is the @  of  .aux files.}
 310 Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the
 311 definition for 'tie is the following:
 312
 313     \def\tie{\penalty 10000\ }     % Save plain tex definition of ~.
 314
 315 )
 316
 317 After running tex on the test2.texi file with the augmented test2.aux
 318 file, you can see the following in the resulting DVI file:
 319
 320     See Section 1.6 [Special], page 7, vol. 1
 321
 322 Note that TeX rewrites the .aux file each time TeX is run, so after
 323 running Tex using an .aux file augmented with the .aux file from the
 324 other volume, the new .aux file will *lack* the other volumes cross
 325 references.  Save your augmented .aux file in some other name for
 326 another run!
 327
 328
 329 COPYING CONDITIONS
 330
 331 This file is free software; you can redistribute it and/or modify
 332 it under the terms of the GNU General Public License as published by
 333 the Free Software Foundation; either version 2, or (at your option)
 334 any later version.
 335
 336 This file is distributed in the hope that it will be useful,
 337 but WITHOUT ANY WARRANTY; without even the implied warranty of
 338 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 339 GNU General Public License for more details.
 340
 341 You should have received a copy of the GNU General Public License
 342 along with this file; see the file COPYING.  If not, write to
 343 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 344 Boston, MA 02110-1301, USA.