"Fossies" - the Fresh Open Source Software Archive

Member "emacs-26.1/doc/lispref/two-volume-cross-refs.txt" (23 Apr 2018, 9476 Bytes) of package /linux/misc/emacs-26.1.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "two-volume-cross-refs.txt": 25.3_vs_26.1.

    1 Copyright (C) 2001-2018 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 
   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 
  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 
  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 
  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 
  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 <https://www.gnu.org/licenses/>.