home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / gnu / info / texi.info-8 (.txt) < prev    next >
GNU Info File  |  1994-02-24  |  43KB  |  822 lines
  1. This is Info file texi.info, produced by Makeinfo-1.55 from the input
  2. file texi.texi.
  3.    This file documents Texinfo, a documentation system that uses a
  4. single source file to produce both on-line information and a printed
  5. manual.
  6.    Copyright (C) 1988, 1990, 1991, 1992, 1993 Free Software Foundation,
  7.    This is the second edition of the Texinfo documentation,
  8. and is consistent with version 2 of `texinfo.tex'.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Free Software Foundation.
  20. File: texi.info,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Create an Info File
  21. Batch Formatting
  22. ================
  23.    You can format Texinfo files for Info using `batch-texinfo-format'
  24. and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
  25. including a shell inside of Emacs.  (*Note Command Line Switches and
  26. Arguments: (emacs)Command Switches.)
  27.    Here is the command to format all the files that end in `.texinfo'
  28. in the current directory (where `%' is the shell prompt):
  29.      % emacs -batch -funcall batch-texinfo-format *.texinfo
  30. Emacs processes all the files listed on the command line, even if an
  31. error occurs while attempting to format some of them.
  32.    Run `batch-texinfo-format' only with Emacs in Batch mode as shown;
  33. it is not interactive.  It kills the Batch mode Emacs on completion.
  34.    `batch-texinfo-format' is convenient if you lack `makeinfo' and want
  35. to format several Texinfo files at once.  When you use Batch mode, you
  36. create a new Emacs process.  This frees your current Emacs, so you can
  37. continue working in it.  (When you run `texinfo-format-region' or
  38. `texinfo-format-buffer', you cannot use that Emacs for anything else
  39. until the command finishes.)
  40. File: texi.info,  Node: Tag and Split Files,  Prev: Batch Formatting,  Up: Create an Info File
  41. Tag Files and Split Files
  42. =========================
  43.    If a Texinfo file has more than 30,000 bytes,
  44. `texinfo-format-buffer' automatically creates a tag table for its Info
  45. file;  `makeinfo' always creates a tag table.  With a "tag table", Info
  46. can jump to new nodes more quickly than it can otherwise.
  47.    In addition, if the Texinfo file contains more than about 70,000
  48. bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
  49. into shorter "indirect" subfiles of about 50,000 bytes each.  Big files
  50. are split into smaller files so that Emacs does not need to make a
  51. large buffer to hold the whole of a large Info file; instead, Emacs
  52. allocates just enough memory for the small, split off file that is
  53. needed at the time.  This way, Emacs avoids wasting memory when you run
  54. Info.  (Before splitting was implemented, Info files were always kept
  55. short and "include files" were designed as a way to create a single,
  56. large printed manual out of the smaller Info files.  *Note Include
  57. Files::, for more information.  Include files are still used for very
  58. large documents, such as `The Emacs Lisp Reference Manual', in which
  59. each chapter is a separate file.)
  60.    When a file is split, Info itself makes use of a shortened version of
  61. the original file that contains just the tag table and references to
  62. the files that were split off.  The split off files are called
  63. "indirect" files.
  64.    The split off files have names that are created by appending `-1',
  65. `-2', `-3' and so on to the file name specified by the `@setfilename'
  66. command.  The shortened version of the original file continues to have
  67. the name specified by `@setfilename'.
  68.    At one stage in writing this document, for example, the Info file
  69. was saved as `test-texinfo' and that file looked like this:
  70.      Info file: test-texinfo,    -*-Text-*-
  71.      produced by texinfo-format-buffer
  72.      from file: new-texinfo-manual.texinfo
  73.      
  74.      ^_
  75.      Indirect:
  76.      test-texinfo-1: 102
  77.      test-texinfo-2: 50422
  78.      test-texinfo-3: 101300
  79.      ^_^L
  80.      Tag table:
  81.      (Indirect)
  82.      Node: overview^?104
  83.      Node: info file^?1271
  84.      Node: printed manual^?4853
  85.      Node: conventions^?6855
  86.      ...
  87. (But `test-texinfo' had far more nodes than are shown here.)  Each of
  88. the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
  89. `test-texinfo-3', is listed in this file after the line that says
  90. `Indirect:'.  The tag table is listed after the line that says `Tag
  91. table:'.
  92.    In the list of indirect files, the number following the file name
  93. records the cumulative number of bytes in the preceding indirect files,
  94. not counting the file list itself, the tag table, or the permissions
  95. text in each file.  In the tag table, the number following the node name
  96. records the location of the beginning of the node, in bytes from the
  97. beginning.
  98.    If you are using `texinfo-format-buffer' to create Info files, you
  99. may want to run the `Info-validate' command.  (The `makeinfo' command
  100. does such a good job on its own, you do not need `Info-validate'.)
  101. However, you cannot run the `M-x Info-validate' node-checking command
  102. on indirect files.  For information on how to prevent files from being
  103. split and how to validate the structure of the nodes, see *Note Using
  104. Info-validate::.
  105. File: texi.info,  Node: Install an Info File,  Next: Command List,  Prev: Create an Info File,  Up: Top
  106. Installing an Info File
  107. ***********************
  108.    Info files are usually kept in the `info' directory.  (You can find
  109. the location of this directory within Emacs by typing `C-h i' to enter
  110. Info and then typing `C-x C-f' to see the full pathname to the `info'
  111. directory.)
  112. * Menu:
  113. * Directory file::              The top level menu for all Info files.
  114. * New Info File::               Listing a new info file.
  115. * Other Info Directories::      How to specify Info files that are
  116.                                   located in other directories.
  117. File: texi.info,  Node: Directory file,  Next: New Info File,  Up: Install an Info File
  118. The `dir' File
  119. ==============
  120.    For Info to work, the `info' directory must contain a file that
  121. serves as a top level directory for the Info system.  By convention,
  122. this file is called `dir'.  The `dir' file is itself an Info file.  It
  123. contains the top level menu for all the Info files in the system.  The
  124. menu looks like this:
  125.      * Menu:
  126.      
  127.      * Info:    (info).     Documentation browsing system.
  128.      * Emacs:   (emacs).    The extensible, self-documenting
  129.                             text editor.
  130.      * Texinfo: (texinfo).  With one source file, make
  131.                             either a printed manual using
  132.                             TeX or an Info file.
  133.      ...
  134.    Each of these menu entries points to the `Top' node of the Info file
  135. that is named in parentheses.  (The menu entry does not need to specify
  136. the `Top' node, since Info goes to the `Top' node if no node name is
  137. mentioned.  *Note Nodes in Other Info Files: Other Info Files.)
  138.    Thus, the `Info' entry points to the `Top' node of the `info' file
  139. and the `Emacs' entry points to the `Top' node of the `emacs' file.
  140.    In each of the Info files, the `Up' pointer of the `Top' node refers
  141. back to the `dir' file.  For example, the line for the `Top' node of
  142. the Emacs manual looks like this in Info:
  143.      File: emacs  Node: Top, Up: (DIR), Next: Distrib
  144. (Note that in this case, the `dir' file name is written in upper case
  145. letters--it can be written in either upper or lower case.  Info has a
  146. feature that it will change the case of the file name to lower case if
  147. it cannot find the name as written.)
  148. File: texi.info,  Node: New Info File,  Next: Other Info Directories,  Prev: Directory file,  Up: Install an Info File
  149. Listing a New Info File
  150. =======================
  151.    To add a new Info file to your system, write a