home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / texinfo-3.7-bin.lha / info / texinfo.info-8 (.txt) < prev    next >
GNU Info File  |  1996-10-12  |  23KB  |  415 lines
  1. This is Info file texinfo.info, produced by Makeinfo-1.64 from the
  2. input file /ade-src/fsf/texinfo/texinfo.texi.
  3.   This file documents Texinfo, a documentation system that uses a single
  4. source file to produce both on-line information and a printed manual.
  5.   Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software
  6. Foundation, Inc.
  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 this
  13. manual under the conditions for verbatim copying, provided that the
  14. 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: texinfo.info,  Node: makeinfo options,  Next: Pointer Validation,  Prev: Invoking makeinfo,  Up: Create an Info File
  21. Options for `makeinfo'
  22. ======================
  23.   The `makeinfo' command takes a number of options.  Most often,
  24. options are used to set the value of the fill column and specify the
  25. footnote style.  Each command line option is a word preceded by `--'(1)
  26. (*note makeinfo options-Footnotes::) or a letter preceded by `-'.  You
  27. can use abbreviations for the option names as long as they are unique.
  28.   For example, you could use the following command to create an Info
  29. file for `bison.texinfo' in which each line is filled to only 68
  30. columns (where `%' is the prompt):
  31.      % makeinfo --fill-column=68 bison.texinfo
  32.   You can write two or more options in sequence, like this:
  33.      % makeinfo --no-split --fill-column=70 ...
  34. This would keep the Info file together as one possibly very long file
  35. and would also set the fill column to 70.
  36.   The options are:
  37. `-D VAR'
  38.      Cause VAR to be defined.  This is equivalent to `@set VAR' in the
  39.      Texinfo file.
  40. `--error-limit LIMIT'
  41.      Set the maximum number of errors that `makeinfo' will report
  42.      before exiting (on the assumption that continuing would be
  43.      useless).  The default number of errors that can be reported before
  44.      `makeinfo' gives up is 100.
  45. `--fill-column WIDTH'
  46.      Specify the maximum number of columns in a line; this is the
  47.      right-hand edge of a line.  Paragraphs that are filled will be
  48.      filled to this width.  (Filling is the process of breaking up and
  49.      connecting lines so that lines are the same length as or shorter
  50.      than the number specified as the fill column.  Lines are broken
  51.      between words.) The default value for `fill-column' is 72.
  52. `--footnote-style STYLE'
  53.      Set the footnote style to STYLE, either `end' for the end node
  54.      style or `separate' for the separate node style.  The value set by
  55.      this option overrides the value set in a Texinfo file by an
  56.      `@footnotestyle' command.  When the footnote style is `separate',
  57.      `makeinfo' makes a new node containing the footnotes found in the
  58.      current node.  When the footnote style is `end', `makeinfo' places
  59.      the footnote references at the end of the current node.
  60. `-I DIR'
  61.      Add `dir' to the directory search list for finding files that are
  62.      included using the `@include' command.  By default, `makeinfo'
  63.      searches only the current directory.
  64. `--no-headers'
  65.      Do not include menus or node lines in the output.  This results in
  66.      an ASCII file that you cannot read in Info since it does not
  67.      contain the requisite nodes or menus; but you can print such a
  68.      file in a single, typewriter-like font and produce acceptable
  69.      output.
  70. `--no-split'
  71.      Suppress the splitting stage of `makeinfo'.  Normally, large
  72.      output files (where the size is greater than 70k bytes) are split
  73.      into smaller subfiles, each one approximately 50k bytes.  If you
  74.      specify `--no-split', `makeinfo' will not split up the output file.
  75. `--no-pointer-validate'
  76. `--no-validate'
  77.      Suppress the pointer-validation phase of `makeinfo'.  Normally,
  78.      after a Texinfo file is processed, some consistency checks are
  79.      made to ensure that cross references can be resolved, etc.  *Note
  80.      Pointer Validation::.
  81. `--no-warn'
  82.      Suppress the output of warning messages.  This does *not* suppress
  83.      the output of error messages, only warnings.  You might want this
  84.      if the file you are creating has examples of Texinfo cross
  85.      references within it, and the nodes that are referenced do not
  86.      actually exist.
  87. `--no-number-footnotes'
  88.      Suppress automatic footnote numbering.  By default, `makeinfo'
  89.      numbers each footnote sequentially in a single node, resetting the
  90.      current footnote number to 1 at the start of each node.
  91. `--output FILE'
  92. `-o FILE'
  93.      Specify that the output should be directed to FILE and not to the
  94.      file name specified in the `@setfilename' command found in the
  95.      Texinfo source.  FILE can be the special token `-', which specifies
  96.      standard output.
  97. `--paragraph-indent INDENT'
  98.      Set the paragraph indentation style to INDENT.  The value set by
  99.      this option overrides the value set in a Texinfo file by an
  100.      `@paragraphindent' command.  The value of INDENT is interpreted as
  101.      follows:
  102.         * If the value of INDENT is `asis', do not change the existing
  103.           indentation at the starts of paragraphs.
  104.         * If the value of INDENT is zero, delete any existing
  105.           indentation.
  106.         * If the value of INDENT is greater than zero, indent each
  107.           paragraph by that number of spaces.
  108. `--reference-limit LIMIT'
  109.      Set the value of the number of references to a node that
  110.      `makeinfo' will make without reporting a warning.  If a node has
  111.      more than this number of references in it, `makeinfo' will make the
  112.      references but also report a warning.
  113. `-U VAR'
  114.      Cause VAR to be undefined.  This is equivalent to `@clear VAR' in
  115.      the Texinfo file.
  116. `--verbose'
  117.      Cause `makeinfo' to display messages saying what it is doing.
  118.      Normally, `makeinfo' only outputs messages if there are errors or
  119.      warnings.
  120. `--version'
  121.      Report the version number of this copy of `makeinfo'.
  122. File: texinfo.info,  Node: makeinfo options-Footnotes,  Up: makeinfo options
  123.   (1)  `--' has replaced `+', the old introductory character, to
  124. maintain POSIX.2 compatibility without losing long-named options.
  125. File: texinfo.info,  Node: Pointer Validation,  Next: makeinfo in Emacs,  Prev: makeinfo options,  Up: Create an Info File
  126. Pointer Validation
  127. ==================
  128.   If you do not suppress pointer-validation, `makeinfo' will check the
  129. validity of the final Info file.  Mostly, this means ensuring that
  130. nodes you have referenced really exist.  Here is a complete list of what
  131. is checked:
  132.   1. If a `Next', `Previous', or `Up' node reference is a reference to a
  133.      node in the current file and is not an external reference such as
  134.      to `(dir)', then the referenced node must exist.
  135.   2. In every node, if the `Previous' node is different from the `Up'
  136.      node, then the `Previous' node must also be pointed to by a `Next'
  137.      node.
  138.   3. Every node except the `Top' node must have an `Up' pointer.
  139.   4. The node referenced by an `Up' pointer must contain a reference to
  140.      the current node in some manner other than through a `Next'
  141.      reference.  This includes menu entries and cross references.
  142.   5. If the `Next' reference of a node is not the same as the `Next'
  143.      reference of the `Up' reference, then the node referenced by the
  144.      `Next' pointer must have a `Previous' pointer that points back to
  145.      the current node.  This rule allows the last node in a section to
  146.      point to the first node of the next chapter.
  147. File: texinfo.info,  Node: makeinfo in Emacs,  Next: texinfo-format commands,  Prev: Pointer Validation,  Up: Create an Info File
  148. Running `makeinfo' inside Emacs
  149. ===============================
  150.   You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
  151. `makeinfo-region' or the `makeinfo-buffer' commands.  In Texinfo mode,
  152. the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
  153. `C-c C-m C-r'
  154. `M-x makeinfo-region'
  155.      Format the current region for Info.
  156. `C-c C-m C-b'
  157. `M-x makeinfo-buffer'
  158.      Format the current buffer for Info.
  159.   When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
  160. prompts for a file name, offering the name of the visited file as the
  161. default.  You can edit the default file name in the minibuffer if you
  162. wish, before typing RET to start the `makeinfo' process.
  163.   The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
  164. `makeinfo' program in a temporary shell buffer.  If `makeinfo' finds
  165. any errors, Emacs displays the error messages in the temporary buffer.
  166.   You can parse the error messages by typing `C-x `' (`next-error').
  167. This causes Emacs to go to and position the cursor on the line in the
  168. Texinfo source that `makeinfo' thinks caused the error.  *Note Running
  169. `make' or Compilers Generally: (emacs)Compilation, for more information
  170. about using the `next-error' command.
  171.   In addition, you can kill the shell in which the `makeinfo' command
  172. is running or make the shell buffer display its most recent output.
  173. `C-c C-m C-k'
  174. `M-x makeinfo-kill-job'
  175.      Kill the current running `makeinfo' job created by
  176.      `makeinfo-region' or `makeinfo-buffer'.
  177. `C-c C-m C-l'
  178. `M-x makeinfo-recenter-output-buffer'
  179.      Redisplay the `makeinfo' shell buffer to display its most recent
  180.      output.
  181. (Note that the parallel commands for killing and recentering a TeX job
  182. are `C-c C-t C-k' and `C-c C-t C-l'.  *Note Texinfo Mode Printing::.)
  183.   You can specify options for `makeinfo' by setting the
  184. `makeinfo-options' variable with either the `M-x edit-options' or the
  185. `M-x set-variable' command, or by setting the variable in your `.emacs'
  186. initialization file.
  187.   For example, you could write the following in your `.emacs' file:
  188.      (setq makeinfo-options
  189.            "--paragraph-indent=0 --no-split
  190.             --fill-column=70 --verbose")
  191. For more information, see
  192. *Note Editing Variable Values: (emacs)Edit Options,
  193. *Note Examining and Setting Variables: (emacs)Examining,
  194. *Note Init File: (emacs)Init File, and
  195. *Note Options for `makeinfo': makeinfo options.
  196. File: texinfo.info,  Node: texinfo-format commands,  Next: Batch Formatting,  Prev: makeinfo in Emacs,  Up: Create an Info File
  197. The `texinfo-format...' Commands
  198. ================================
  199. In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
  200. file with the `texinfo-format-region' command.  This formats the
  201. current region and displays the formatted text in a temporary buffer
  202. called `*Info Region*'.
  203.   Similarly, you can format a buffer with the `texinfo-format-buffer'
  204. command.  This command creates a new buffer and generates the Info file
  205. in it.  Typing `C-x C-s' will save the Info file under the name
  206. specified by the `@setfilename' line which must be near the beginning
  207. of the Texinfo file.
  208. `C-c C-e C-r'
  209. ``texinfo-format-region''
  210.      Format the current region for Info.
  211. `C-c C-e C-b'
  212. ``texinfo-format-buffer''
  213.      Format the current buffer for Info.
  214.   The `texinfo-format-region' and `texinfo-format-buffer' commands
  215. provide you with some error checking, and other functions can provide
  216. you with further help in finding formatting errors.  These procedures
  217. are described in an appendix; see *Note Catching Mistakes::.  However,
  218. the `makeinfo' program is often faster and provides better error
  219. checking (*note makeinfo in Emacs::.).
  220. File: texinfo.info,  Node: Batch Formatting,  Next: Tag and Split Files,  Prev: texinfo-format commands,  Up: Create an Info File
  221. Batch Formatting
  222. ================
  223.   You can format Texinfo files for Info using `batch-texinfo-format'
  224. and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
  225. including a shell inside of Emacs.  (*Note Command Line Switches and
  226. Arguments: (emacs)Command Switches.)
  227.   Here is the command to format all the files that end in `.texinfo' in
  228. the current directory (where `%' is the shell prompt):
  229.      % emacs -batch -funcall batch-texinfo-format *.texinfo
  230. Emacs processes all the files listed on the command line, even if an
  231. error occurs while attempting to format some of them.
  232.   Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it
  233. is not interactive.  It kills the Batch mode Emacs on completion.
  234.   `batch-texinfo-format' is convenient if you lack `makeinfo' and want
  235. to format several Texinfo files at once.  When you use Batch mode, you
  236. create a new Emacs process.  This frees your current Emacs, so you can
  237. continue working in it.  (When you run `texinfo-format-region' or
  238. `texinfo-format-buffer', you cannot use that Emacs for anything else
  239. until the command finishes.)
  240. File: texinfo.info,  Node: Tag and Split Files,  Prev: Batch Formatting,  Up: Create an Info File
  241. Tag Files and Split Files
  242. =========================
  243.   If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
  244. automatically creates a tag table for its Info file;  `makeinfo' always
  245. creates a tag table.  With a "tag table", Info can jump to new nodes
  246. more quickly than it can otherwise.
  247.   In addition, if the Texinfo file contains more than about 70,000
  248. bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
  249. into shorter "indirect" subfiles of about 50,000 bytes each.  Big files
  250. are split into smaller files so that Emacs does not need to make a
  251. large buffer to hold the whole of a large Info file; instead, Emacs
  252. allocates just enough memory for the small, split off file that is
  253. needed at the time.  This way, Emacs avoids wasting memory when you run
  254. Info.  (Before splitting was implemented, Info files were always kept
  255. short and "include files" were designed as a way to create a single,
  256. large printed manual out of the smaller Info files.  *Note Include
  257. Files::, for more information.  Include files are still used for very
  258. large documents, such as `The Emacs Lisp Reference Manual', in which
  259. each chapter is a separate file.)
  260.   When a file is split, Info itself makes use of a shortened version of
  261. the original file that contains just the tag table and references to
  262. the files that were split off.  The split off files are called
  263. "indirect" files.
  264.   The split off files have names that are created by appending `-1',
  265. `-2', `-3' and so on to the file name specified by the `@setfilename'
  266. command.  The shortened version of the original file continues to have
  267. the name specified by `@setfilename'.
  268.   At one stage in writing this document, for example, the Info file was
  269. saved as `test-texinfo' and that file looked like this:
  270.      Info file: test-texinfo,    -*-Text-*-
  271.      produced by texinfo-format-buffer
  272.      from file: new-texinfo-manual.texinfo
  273.      
  274.      ^_
  275.      Indirect:
  276.      test-texinfo-1: 102
  277.      test-texinfo-2: 50422
  278.      test-texinfo-3: 101300
  279.      ^_^L
  280.      Tag table:
  281.      (Indirect)
  282.      Node: overview^?104
  283.      Node: info file^?1271
  284.      Node: printed manual^?4853
  285.      Node: conventions^?6855
  286.      ...
  287. (But `test-texinfo' had far more nodes than are shown here.)  Each of
  288. the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
  289. `test-texinfo-3', is listed in this file after the line that says
  290. `Indirect:'.  The tag table is listed after the line that says `Tag
  291. table:'.
  292.   In the list of indirect files, the number following the file name
  293. records the cumulative number of bytes in the preceding indirect files,
  294. not counting the file list itself, the tag table, or the permissions
  295. text in each file.  In the tag table, the number following the node name
  296. records the location of the beginning of the node, in bytes from the
  297. beginning.
  298.   If you are using `texinfo-format-buffer' to create Info files, you
  299. may want to run the `Info-validate' command.  (The `makeinfo' command
  300. does such a good job on its own, you do not need `Info-validate'.)
  301. However, you cannot run the `M-x Info-validate' node-checking command
  302. on indirect files.  For information on how to prevent files from being
  303. split and how to validate the structure of the nodes, see *Note Using
  304. Info-validate::.
  305. File: texinfo.info,  Node: Install an Info File,  Next: Command List,  Prev: Create an Info File,  Up: Top
  306. Installing an Info File
  307. ***********************
  308.   Info files are usually kept in the `info' directory.  You can read
  309. Info files using the standalone Info program or the Info reader built
  310. into Emacs.  (*note info: (info)Top, for an introduction to Info.)
  311. * Menu:
  312. * Directory file::              The top level menu for all Info files.
  313. * New Info File::               Listing a new info file.
  314. * Other Info Directories::      How to specify Info files that are
  315.                                   located in other directories.
  316. File: texinfo.info,  Node: Directory file,  Next: New Info File,  Prev: Install an Info File,  Up: Install an Info File
  317. The `dir' File
  318. ==============
  319.   For Info to work, the `info' directory must contain a file that
  320. serves as a top level directory for the Info system.  By convention,
  321. this file is called `dir'.  (You can find the location of this file
  322. within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
  323. to see the pathname to the `info' directory.)
  324.   The `dir' file is itself an Info file.  It contains the top level
  325. menu for all the Info files in the system.  The menu looks like this:
  326.      * Menu:
  327.      
  328.      * Info:    (info).     Documentation browsing system.
  329.      * Emacs:   (emacs).    The extensible, self-documenting
  330.                             text editor.
  331.      * Texinfo: (texinfo).  With one source file, make
  332.                             either a printed manual using
  333.                             TeX or an Info file.
  334.      ...
  335.   Each of these menu entries points to the `Top' node of the Info file
  336. that is named in parentheses.  (The menu entry does not need to specify
  337. the `Top' node, since Info goes to the `Top' node if no node name is
  338. mentioned.  *Note Nodes in Other Info Files: Other Info Files.)
  339.   Thus, the `Info' entry points to the `Top' node of the `info' file
  340. and the `Emacs' entry points to the `Top' node of the `emacs' file.
  341.   In each of the Info files, the `Up' pointer of the `Top' node refers
  342. back to the `dir' file.  For example, the line for the `Top' node of
  343. the Emacs manual looks like this in Info:
  344.      File: emacs  Node: Top, Up: (DIR), Next: Distrib
  345. (Note that in this case, the `dir' file name is written in upper case
  346. letters--it can be written in either upper or lower case.  Info has a
  347. feature that it will change the case of the file name to lower case if
  348. it cannot find the name as written.)
  349. File: texinfo.info,  Node: New Info File,  Next: Other Info Directories,  Prev: Directory file,  Up: Install an Info File
  350. Listing a New Info File
  351. =======================
  352.   To add a new Info file to your system, write a menu entry for it in
  353. the menu in the `dir' file in the `info' directory.  Also, move the new
  354. Info file itself to the `info' directory.  For example, if you were
  355. adding documentation for GDB, you would write the following new entry:
  356.      * GDB: (gdb).           The source-level C debugger.
  357. The first part of the menu entry is the menu entry name, followed by a
  358. colon.  The second part is the name of the Info file, in parentheses,
  359. followed by a period.  The third part is the description.
  360.   Conventionally, the name of an Info file has a `.info' extension.
  361. Thus, you might list the name of the file like this:
  362.      * GDB: (gdb.info).           The source-level C debugger.
  363. However, Info will look for a file with a `.info' extension if it does
  364. not find the file under the name given in the menu.  This means that
  365. you can refer to the file `gdb.info' as `gdb', as shown in the first
  366. example.  This looks better.
  367. File: texinfo.info,  Node: Other Info Directories,  Prev: New Info File,  Up: Install an Info File
  368. Info Files in Other Directories
  369. ===============================
  370.   If an Info file is not in the `info' directory, there are three ways
  371. to specify its location:
  372.    * Write the pathname in the `dir' file as the second part of the
  373.      menu.
  374.    * If you are using Emacs, list the name of the file in a second `dir'
  375.      file, in its directory; and then add the name of that directory to
  376.      the `Info-directory-list' variable in your personal or site
  377.      initialization file.
  378.      This tells Emacs's Info reader reader where to look for `dir'
  379.      files.  Emacs merges the files named `dir' from each of the listed
  380.      directories.  (In Emacs Version 18, you can set the
  381.      `Info-directory' variable to the name of only one directory.)
  382.    * Specify the `info' directory name in an environment variable in
  383.      your `.profile' or `.cshrc' initialization file.  (Only you and
  384.      others who set this environment variable will be able to find Info
  385.      files whose location is specified this way.)
  386.   For example, to reach a test file in the `~bob/manuals' directory,
  387. you could add an entry like this to the menu in the `dir' file:
  388.      * Test: (/usr/bob/manuals/info-test).  Bob's own test file.
  389. In this case, the absolute file name of the `info-test' file is written
  390. as the second part of the menu entry.
  391.   Alternatively, you could write the following in your `.emacs' file:
  392.      (setq Info-directory-list
  393.            '("/usr/bob/manuals"
  394.              "/usr/local/emacs/info"))
  395.   This tells Emacs to merge the `dir' file from the `/usr/bob/manuals'
  396. directory with the `dir' file from the `"/usr/local/emacs/info'"
  397. directory.  Info will list the `/usr/bob/manuals/info-test' file as a
  398. menu entry in the `/usr/bob/manuals/dir' file.
  399.   Finally, you can tell Info where to look by setting the `INFOPATH'
  400. environment variable in your `.cshrc' or `.profile' file.
  401.   If you use `sh' or `bash' for your shell command interpreter, you
  402. must set the `INFOPATH' environment variable in the `.profile'
  403. initialization file; but if you use `csh', you must set the variable in
  404. the `.cshrc' initialization file.  The two files require slightly
  405. different command formats.
  406.    * In a `.cshrc' file, you could set the `INFOPATH' variable as
  407.      follows:
  408.           setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info
  409.    * In a `.profile' file, you would achieve the same effect by writing:
  410.           INFOPATH=.:~bob/manuals:/usr/local/emacs/info
  411.           export INFOPATH
  412. The `.'  indicates the current directory.  Emacs uses the `INFOPATH'
  413. environment variable to initialize the value of Emacs's own
  414. `Info-directory-list' variable.
  415.