diff lispref/two-volume-cross-refs.txt @ 41193:1377d461b09c

*** empty log message ***

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lispref/two-volume-cross-refs.txt	Sat Nov 17 09:38:14 2001 +0000
@@ -0,0 +1,322 @@
+Two Volume Cross References
+===========================
+
+18 March 1992
+
+This enables you to create manuals in *two* volumes, with tables of
+contents, cross references, and indices in each volume referring to
+*both* volumes.
+
+The procedure is tedious.  However, the resulting two volumes are
+conveniently organized.  Each has an index of the whole two volumes.
+Each volume starts with page 1.  (I don't like multi-volume works
+where each volume starts with a higher page number since I find it
+harder to go to the right place in the volume.)
+
+References to the same volume are just the page number; references to
+the other volume are a volumne number (in Roman numerals) preceding
+the page number.
+
+For example, in Volume I:
+
+    list length ......... 90
+    list motion ......II:117
+
+and in Volume II:
+
+    list length ....... I:90
+    list motion .........117
+
+All other references and the table of contents work the same way.  I
+find this *very* helpful. 
+
+
+In brief: you run tex on a .texi file with
+
+  a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file
+  b. redone .aux file
+  c. redone .fns file
+
+
+Here are the steps in detail:
+
+% tex elisp-vol1.texi
+% texindex elisp-vol1.??
+% tex elisp-vol1.texi
+
+% tex elisp-vol2.texi
+% texindex elisp-vol2.??
+% tex elisp-vol2.texi
+
+### Create .aux files with volume numbers for other volume.
+
+% cp elisp-vol1.aux elisp1-aux
+% cp elisp-vol2.aux elisp2-aux
+
+% cp elisp-vol1.aux elisp1-aux-vol-number-added
+% cp elisp-vol2.aux elisp2-aux-vol-number-added
+
+on elisp1-aux-vol-number-added
+(volume-aux-markup 1)           see defun for volum-aux-markup below.
+to create             elisp1-aux-vol-number-added
+
+on elisp2-aux-vol-number-added
+(volume-aux-markup 2)
+to create             elisp2-aux-vol-number-added
+
+insert elisp2-aux-vol-number-added into elisp-vol1.aux  (append)
+insert elisp1-aux-vol-number-added into elisp-vol2.aux  (prepend)
+
+(so you dont have to do it again)
+% cp elisp-vol1.aux elisp1-aux-2vol-ready
+% cp elisp-vol2.aux elisp2-aux-2vol-ready
+
+
+### Create .fn files with volume numbers for other volume.
+
+% cp elisp-vol1.fn elisp1-fn
+% cp elisp-vol2.fn elisp2-fn
+
+% cp elisp-vol1.fn elisp1-fn-vol-number-added
+% cp elisp-vol2.fn elisp2-fn-vol-number-added
+
+on elisp1-fn-vol-number-added
+(volume-index-markup "I")
+to create             elisp1-fn-vol-number-added
+
+on elisp2-fn-vol-number-added
+(volume-index-markup "II")
+to create             elisp2-fn-vol-number-added
+
+insert elisp2-fn-vol-number-added into elisp-vol1.fn: do following `cat'
+insert elisp1-fn-vol-number-added into elisp-vol2.fn: do following `cat'
+
+% cat elisp2-fn-vol-number-added >> elisp-vol1.fn
+% cat elisp1-fn-vol-number-added >> elisp-vol2.fn
+
+Be sure to handle special case entries by hand.
+Be sure that .fn file has no blank lines.
+
+% texindex elisp-vol1.fn
+% texindex elisp-vol2.fn
+
+(so you dont have to do it again)
+% cp elisp-vol1.fns elisp1-fns-2vol-ready
+% cp elisp-vol2.fns elisp2-fns-2vol-ready
+
+### Create merged .toc file with volume number headings.
+
+append elisp-vol2.toc to elisp-vol1.toc  with following `cat'
+
+% cat elisp-vol1.toc elisp-vol2.toc > elisp-toc-2vol.toc
+
+and edit in Volume titles
+
+\unnumbchapentry {Volume 1}{}
+\unnumbchapentry {}{}
+
+\unnumbchapentry {Index}{295}
+\unnumbchapentry {}{}
+\unnumbchapentry {Volume 2}{}
+\unnumbchapentry {}{}
+
+If you want to put in volume numbers for TOC, then do this:
+Create volume specific .toc files with volume numbers in them.
+
+% cp elisp-toc-2vol.toc elisp1-toc.toc
+% cp elisp-toc-2vol.toc elisp2-toc.toc
+
+Use keyboard macro to put I: in first half of elisp1-toc.toc and 
+II: in first half of elisp2-toc.toc
+
+Copy the tocs to something you can remember more easily
+
+% cp elisp2-toc.toc elisp1-toc-ready.toc 
+% cp elisp1-toc.toc elisp2-toc-ready.toc 
+
+Then, edit elisp-vol1.texi to input elisp1-toc-ready.toc 
+and elisp-vol2.texi to input elisp2-toc-ready.toc 
+
+
+### Now format the two volumes:
+
+% cp elisp1-aux-2vol-ready elisp-vol1.aux
+% cp elisp2-aux-2vol-ready elisp-vol2.aux
+
+% tex elisp-vol1.texi
+% tex elisp-vol2.texi
+
+
+
+For every additional run:
+
+### recopy aux files so the correct ones are read:
+% cp elisp1-aux-2vol-ready elisp-vol1.aux
+% cp elisp2-aux-2vol-ready elisp-vol2.aux
+
+Do not run texindex.  Then proper sorted index will stay.
+ else do: % cp elisp2-fns-2vol-ready elisp-vol2.fns
+
+Do not change the .texi files; they will call the elisp-toc-2vol.toc file.
+
+% tex elisp-vol1.texi
+% tex elisp-vol2.texi
+
+================================================================
+
+@c ================================================================
+@tex
+% Special @contents  command
+% This inputs fixed up table of contents file rather than create new one.
+\global\def\contents{%
+   \startcontents{Table of Contents}%
+      \input elisp-toc-2vol.toc
+   \endgroup
+   \vfill \eject
+}
+
+% Special @summarycontents  command
+% This inputs fixed up table of contents file rather than create new one.
+\outer\def\summarycontents{%
+   \startcontents{Short Contents}%
+      %
+      \let\chapentry = \shortchapentry
+      \let\unnumbchapentry = \shortunnumberedentry
+      % We want a true roman here for the page numbers.
+      \secfonts
+      \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl
+      \rm
+      \advance\baselineskip by 1pt % Open it up a little.
+      \def\secentry ##1##2##3##4{}
+      \def\unnumbsecentry ##1##2{}
+      \def\subsecentry ##1##2##3##4##5{}
+      \def\unnumbsubsecentry ##1##2{}
+      \def\subsubsecentry ##1##2##3##4##5##6{}
+      \def\unnumbsubsubsecentry ##1##2{}
+      \input elisp-toc-2vol.toc
+   \endgroup
+   \vfill \eject
+}
+@end tex
+@c ================================================================
+
+
+================================================================
+
+
+(defun volume-aux-markup (arg)
+  "Append `vol. NUMBER' to page number.
+Apply to aux file that you save.
+Then insert marked file into other volume's .aux file."
+  (interactive "sType volume number, 1 or 2: " )
+  (goto-char (point-min))
+  (while (search-forward "-pg" nil t)
+    (end-of-line 1)
+    (delete-backward-char 1 nil)
+    (insert ", vol.'tie" arg "}")))
+
+(defun volume-index-markup (arg)
+  "Prepend  `NUMBER:' to page number.  Use Roman Numeral.
+Apply only to unsorted index file, 
+Then insert marked file into other volume's unsorted index file.
+Then run texindex on that file and save."
+  (interactive
+   "sType volume number,  roman number I or II: " )
+  (goto-char (point-min))
+  (while (search-forward "\\entry" nil t)
+    (search-forward "}{" (save-excursion (end-of-line) (point)) nil)
+    (insert arg ":")))
+
+
+================================================================
+
+
+The steps:
+
+1. Run TeX, texindex and TeX on file1.
+2. Run TeX, texindex and TeX on file2.
+
+3. Copy both .aux files into specially named files 
+
+4. In the case of the elisp ref manual, 
+
+   copy the *unsorted* function index files into specially named files 
+   (no other index used in elisp ref manual)
+
+
+5. For aux files:
+
+   Run a function on the specially named .aux files to label each
+   entry according to volume.  Save these files.
+
+   i.e., convert     
+   'xrdef {Special-pg}{7}  to 'xrdef {Special-pg}{7, vol.'tie1}
+
+5a.Insert each specially named .aux file into the regular .aux file of
+   the other volume.
+
+6. For index files:
+
+   Run a function on the specially named unsorted index files to label
+   each entry according to volume.  Save these files.
+
+6b.Insert each specially named marked unsorted index file into the
+   regular unsorted file of the other volume.  Run texindex on this
+
+7. Insert the other volumes .toc file into the .toc, edit, and rename to
+   elisp-toc-2vol.toc
+
+7a. insert special @contents and @summarycontents defs into .texi files.
+
+8. Run TeX on each .texi file.
+
+================
+
+
+
+Here is the discursive commentary:
+
+I've been running some small test files, called test1.texi and
+test2.texi.  As far as I can see, if we run tex on the two test files,
+tex creates a .aux for each that includes the names of all the nodes
+in that file.  The node names are used for cross references.
+
+If you insert the .aux file for the second test file, test2.aux, into
+the .aux file for the first test file, test1.aux, then when you next
+run TeX on the first test file, test1.texi, the second volume cross
+references are inserted.
+
+You can edit the text of the cross reference in test2.aux to include
+the volume number.
+
+For example, you can take the following two lines from test1.texi and
+insert them into test2.texi:
+
+    'xrdef {Special-pg}{7}
+    'xrdef {Special-snt}{Section'tie1.6}
+
+You can re-edit this to show that the page is in volume 1:
+
+    'xrdef {Special-pg}{7, vol.'tie1}
+    'xrdef {Special-snt}{Section'tie1.6}
+
+(The  'tie  is a TeX special command to keep the number tied on one
+line to the previous word.  I don't know if it works after a period in
+the "vol." but figure it is worth trying.  {The  ' is the @  of  .aux files.}
+Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the
+definition for 'tie is the following:
+
+    \def\tie{\penalty 10000\ }     % Save plain tex definition of ~.
+
+)
+
+After running tex on the test2.texi file with the augmented test2.aux
+file, you can see the following in the resulting DVI file:
+
+    See Section 1.6 [Special], page 7, vol. 1
+
+Note that TeX rewrites the .aux file each time TeX is run, so after
+running Tex using an .aux file augmented with the .aux file from the
+other volume, the new .aux file will *lack* the other volumes cross
+references.  Save your augmented .aux file in some other name for
+another run!