doc/lispref/two-volume-cross-refs.txt

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