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