This is Info file texinfo, produced by Makeinfo-1.64 from the input file texinfo.texi. This file documents Texinfo, a documentation system that uses a single source file to produce both on-line information and a printed manual. Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software Foundation, Inc. This is the second edition of the Texinfo documentation, and is consistent with version 2 of `texinfo.tex'. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  File: texinfo, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Create an Info File Options for `makeinfo' ====================== The `makeinfo' command takes a number of options. Most often, options are used to set the value of the fill column and specify the footnote style. Each command line option is a word preceded by `--'(1) (*note makeinfo options-Footnotes::) or a letter preceded by `-'. You can use abbreviations for the option names as long as they are unique. For example, you could use the following command to create an Info file for `bison.texinfo' in which each line is filled to only 68 columns (where `%' is the prompt): % makeinfo --fill-column=68 bison.texinfo You can write two or more options in sequence, like this: % makeinfo --no-split --fill-column=70 ... This would keep the Info file together as one possibly very long file and would also set the fill column to 70. The options are: `-D VAR' Cause VAR to be defined. This is equivalent to `@set VAR' in the Texinfo file. `--error-limit LIMIT' Set the maximum number of errors that `makeinfo' will report before exiting (on the assumption that continuing would be useless). The default number of errors that can be reported before `makeinfo' gives up is 100. `--fill-column WIDTH' Specify the maximum number of columns in a line; this is the right-hand edge of a line. Paragraphs that are filled will be filled to this width. (Filling is the process of breaking up and connecting lines so that lines are the same length as or shorter than the number specified as the fill column. Lines are broken between words.) The default value for `fill-column' is 72. `--footnote-style STYLE' Set the footnote style to STYLE, either `end' for the end node style or `separate' for the separate node style. The value set by this option overrides the value set in a Texinfo file by an `@footnotestyle' command. When the footnote style is `separate', `makeinfo' makes a new node containing the footnotes found in the current node. When the footnote style is `end', `makeinfo' places the footnote references at the end of the current node. `-I DIR' Add `dir' to the directory search list for finding files that are included using the `@include' command. By default, `makeinfo' searches only the current directory. `--no-headers' Do not include menus or node lines in the output. This results in an ASCII file that you cannot read in Info since it does not contain the requisite nodes or menus; but you can print such a file in a single, typewriter-like font and produce acceptable output. `--no-split' Suppress the splitting stage of `makeinfo'. Normally, large output files (where the size is greater than 70k bytes) are split into smaller subfiles, each one approximately 50k bytes. If you specify `--no-split', `makeinfo' will not split up the output file. `--no-pointer-validate' `--no-validate' Suppress the pointer-validation phase of `makeinfo'. Normally, after a Texinfo file is processed, some consistency checks are made to ensure that cross references can be resolved, etc. *Note Pointer Validation::. `--no-warn' Suppress the output of warning messages. This does *not* suppress the output of error messages, only warnings. You might want this if the file you are creating has examples of Texinfo cross references within it, and the nodes that are referenced do not actually exist. `--no-number-footnotes' Suppress automatic footnote numbering. By default, `makeinfo' numbers each footnote sequentially in a single node, resetting the current footnote number to 1 at the start of each node. `--output FILE' `-o FILE' Specify that the output should be directed to FILE and not to the file name specified in the `@setfilename' command found in the Texinfo source. FILE can be the special token `-', which specifies standard output. `--paragraph-indent INDENT' Set the paragraph indentation style to INDENT. The value set by this option overrides the value set in a Texinfo file by an `@paragraphindent' command. The value of INDENT is interpreted as follows: * If the value of INDENT is `asis', do not change the existing indentation at the starts of paragraphs. * If the value of INDENT is zero, delete any existing indentation. * If the value of INDENT is greater than zero, indent each paragraph by that number of spaces. `--reference-limit LIMIT' Set the value of the number of references to a node that `makeinfo' will make without reporting a warning. If a node has more than this number of references in it, `makeinfo' will make the references but also report a warning. `-U VAR' Cause VAR to be undefined. This is equivalent to `@clear VAR' in the Texinfo file. `--verbose' Cause `makeinfo' to display messages saying what it is doing. Normally, `makeinfo' only outputs messages if there are errors or warnings. `--version' Report the version number of this copy of `makeinfo'.  File: texinfo, Node: makeinfo options-Footnotes, Up: makeinfo options (1) `--' has replaced `+', the old introductory character, to maintain POSIX.2 compatibility without losing long-named options.  File: texinfo, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Create an Info File Pointer Validation ================== If you do not suppress pointer-validation, `makeinfo' will check the validity of the final Info file. Mostly, this means ensuring that nodes you have referenced really exist. Here is a complete list of what is checked: 1. If a `Next', `Previous', or `Up' node reference is a reference to a node in the current file and is not an external reference such as to `(dir)', then the referenced node must exist. 2. In every node, if the `Previous' node is different from the `Up' node, then the `Previous' node must also be pointed to by a `Next' node. 3. Every node except the `Top' node must have an `Up' pointer. 4. The node referenced by an `Up' pointer must contain a reference to the current node in some manner other than through a `Next' reference. This includes menu entries and cross references. 5. If the `Next' reference of a node is not the same as the `Next' reference of the `Up' reference, then the node referenced by the `Next' pointer must have a `Previous' pointer that points back to the current node. This rule allows the last node in a section to point to the first node of the next chapter.  File: texinfo, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Create an Info File Running `makeinfo' inside Emacs =============================== You can run `makeinfo' in GNU Emacs Texinfo mode by using either the `makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode, the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default. `C-c C-m C-r' `M-x makeinfo-region' Format the current region for Info. `C-c C-m C-b' `M-x makeinfo-buffer' Format the current buffer for Info. When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs prompts for a file name, offering the name of the visited file as the default. You can edit the default file name in the minibuffer if you wish, before typing RET to start the `makeinfo' process. The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the `makeinfo' program in a temporary shell buffer. If `makeinfo' finds any errors, Emacs displays the error messages in the temporary buffer. You can parse the error messages by typing `C-x `' (`next-error'). This causes Emacs to go to and position the cursor on the line in the Texinfo source that `makeinfo' thinks caused the error. *Note Running `make' or Compilers Generally: (emacs)Compilation, for more information about using the `next-error' command. In addition, you can kill the shell in which the `makeinfo' command is running or make the shell buffer display its most recent output. `C-c C-m C-k' `M-x makeinfo-kill-job' Kill the current running `makeinfo' job created by `makeinfo-region' or `makeinfo-buffer'. `C-c C-m C-l' `M-x makeinfo-recenter-output-buffer' Redisplay the `makeinfo' shell buffer to display its most recent output. (Note that the parallel commands for killing and recentering a TeX job are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.) You can specify options for `makeinfo' by setting the `makeinfo-options' variable with either the `M-x edit-options' or the `M-x set-variable' command, or by setting the variable in your `.emacs' initialization file. For example, you could write the following in your `.emacs' file: (setq makeinfo-options "--paragraph-indent=0 --no-split --fill-column=70 --verbose") For more information, see *Note Editing Variable Values: (emacs)Edit Options, *Note Examining and Setting Variables: (emacs)Examining, *Note Init File: (emacs)Init File, and *Note Options for `makeinfo': makeinfo options.  File: texinfo, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Create an Info File The `texinfo-format...' Commands ================================ In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo file with the `texinfo-format-region' command. This formats the current region and displays the formatted text in a temporary buffer called `*Info Region*'. Similarly, you can format a buffer with the `texinfo-format-buffer' command. This command creates a new buffer and generates the Info file in it. Typing `C-x C-s' will save the Info file under the name specified by the `@setfilename' line which must be near the beginning of the Texinfo file. `C-c C-e C-r' ``texinfo-format-region'' Format the current region for Info. `C-c C-e C-b' ``texinfo-format-buffer'' Format the current buffer for Info. The `texinfo-format-region' and `texinfo-format-buffer' commands provide you with some error checking, and other functions can provide you with further help in finding formatting errors. These procedures are described in an appendix; see *Note Catching Mistakes::. However, the `makeinfo' program is often faster and provides better error checking (*note makeinfo in Emacs::.).  File: texinfo, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Create an Info File Batch Formatting ================ You can format Texinfo files for Info using `batch-texinfo-format' and Emacs Batch mode. You can run Emacs in Batch mode from any shell, including a shell inside of Emacs. (*Note Command Line Switches and Arguments: (emacs)Command Switches.) Here is the command to format all the files that end in `.texinfo' in the current directory (where `%' is the shell prompt): % emacs -batch -funcall batch-texinfo-format *.texinfo Emacs processes all the files listed on the command line, even if an error occurs while attempting to format some of them. Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it is not interactive. It kills the Batch mode Emacs on completion. `batch-texinfo-format' is convenient if you lack `makeinfo' and want to format several Texinfo files at once. When you use Batch mode, you create a new Emacs process. This frees your current Emacs, so you can continue working in it. (When you run `texinfo-format-region' or `texinfo-format-buffer', you cannot use that Emacs for anything else until the command finishes.)  File: texinfo, Node: Tag and Split Files, Prev: Batch Formatting, Up: Create an Info File Tag Files and Split Files ========================= If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer' automatically creates a tag table for its Info file; `makeinfo' always creates a tag table. With a "tag table", Info can jump to new nodes more quickly than it can otherwise. In addition, if the Texinfo file contains more than about 70,000 bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file into shorter "indirect" subfiles of about 50,000 bytes each. Big files are split into smaller files so that Emacs does not need to make a large buffer to hold the whole of a large Info file; instead, Emacs allocates just enough memory for the small, split off file that is needed at the time. This way, Emacs avoids wasting memory when you run Info. (Before splitting was implemented, Info files were always kept short and "include files" were designed as a way to create a single, large printed manual out of the smaller Info files. *Note Include Files::, for more information. Include files are still used for very large documents, such as `The Emacs Lisp Reference Manual', in which each chapter is a separate file.) When a file is split, Info itself makes use of a shortened version of the original file that contains just the tag table and references to the files that were split off. The split off files are called "indirect" files. The split off files have names that are created by appending `-1', `-2', `-3' and so on to the file name specified by the `@setfilename' command. The shortened version of the original file continues to have the name specified by `@setfilename'. At one stage in writing this document, for example, the Info file was saved as `test-texinfo' and that file looked like this: Info file: test-texinfo, -*-Text-*- produced by texinfo-format-buffer from file: new-texinfo-manual.texinfo ^_ Indirect: test-texinfo-1: 102 test-texinfo-2: 50422 test-texinfo-3: 101300 ^_^L Tag table: (Indirect) Node: overview^?104 Node: info file^?1271 Node: printed manual^?4853 Node: conventions^?6855 ... (But `test-texinfo' had far more nodes than are shown here.) Each of the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and `test-texinfo-3', is listed in this file after the line that says `Indirect:'. The tag table is listed after the line that says `Tag table:'. In the list of indirect files, the number following the file name records the cumulative number of bytes in the preceding indirect files, not counting the file list itself, the tag table, or the permissions text in each file. In the tag table, the number following the node name records the location of the beginning of the node, in bytes from the beginning. If you are using `texinfo-format-buffer' to create Info files, you may want to run the `Info-validate' command. (The `makeinfo' command does such a good job on its own, you do not need `Info-validate'.) However, you cannot run the `M-x Info-validate' node-checking command on indirect files. For information on how to prevent files from being split and how to validate the structure of the nodes, see *Note Using Info-validate::.  File: texinfo, Node: Install an Info File, Next: Command List, Prev: Create an Info File, Up: Top Installing an Info File *********************** Info files are usually kept in the `info' directory. You can read Info files using the standalone Info program or the Info reader built into Emacs. (*note info: (info)Top, for an introduction to Info.) * Menu: * Directory file:: The top level menu for all Info files. * New Info File:: Listing a new info file. * Other Info Directories:: How to specify Info files that are located in other directories.  File: texinfo, Node: Directory file, Next: New Info File, Prev: Install an Info File, Up: Install an Info File The `dir' File ============== For Info to work, the `info' directory must contain a file that serves as a top level directory for the Info system. By convention, this file is called `dir'. (You can find the location of this file within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f' to see the pathname to the `info' directory.) The `dir' file is itself an Info file. It contains the top level menu for all the Info files in the system. The menu looks like this: * Menu: * Info: (info). Documentation browsing system. * Emacs: (emacs). The extensible, self-documenting text editor. * Texinfo: (texinfo). With one source file, make either a printed manual using TeX or an Info file. ... Each of these menu entries points to the `Top' node of the Info file that is named in parentheses. (The menu entry does not need to specify the `Top' node, since Info goes to the `Top' node if no node name is mentioned. *Note Nodes in Other Info Files: Other Info Files.) Thus, the `Info' entry points to the `Top' node of the `info' file and the `Emacs' entry points to the `Top' node of the `emacs' file. In each of the Info files, the `Up' pointer of the `Top' node refers back to the `dir' file. For example, the line for the `Top' node of the Emacs manual looks like this in Info: File: emacs Node: Top, Up: (DIR), Next: Distrib (Note that in this case, the `dir' file name is written in upper case letters--it can be written in either upper or lower case. Info has a feature that it will change the case of the file name to lower case if it cannot find the name as written.)  File: texinfo, Node: New Info File, Next: Other Info Directories, Prev: Directory file, Up: Install an Info File Listing a New Info File ======================= To add a new Info file to your system, write a menu entry for it in the menu in the `dir' file in the `info' directory. Also, move the new Info file itself to the `info' directory. For example, if you were adding documentation for GDB, you would write the following new entry: * GDB: (gdb). The source-level C debugger. The first part of the menu entry is the menu entry name, followed by a colon. The second part is the name of the Info file, in parentheses, followed by a period. The third part is the description. Conventionally, the name of an Info file has a `.info' extension. Thus, you might list the name of the file like this: * GDB: (gdb.info). The source-level C debugger. However, Info will look for a file with a `.info' extension if it does not find the file under the name given in the menu. This means that you can refer to the file `gdb.info' as `gdb', as shown in the first example. This looks better.  File: texinfo, Node: Other Info Directories, Prev: New Info File, Up: Install an Info File Info Files in Other Directories =============================== If an Info file is not in the `info' directory, there are three ways to specify its location: * Write the pathname in the `dir' file as the second part of the menu. * If you are using Emacs, list the name of the file in a second `dir' file, in its directory; and then add the name of that directory to the `Info-directory-list' variable in your personal or site initialization file. This tells Emacs's Info reader reader where to look for `dir' files. Emacs merges the files named `dir' from each of the listed directories. (In Emacs Version 18, you can set the `Info-directory' variable to the name of only one directory.) * Specify the `info' directory name in an environment variable in your `.profile' or `.cshrc' initialization file. (Only you and others who set this environment variable will be able to find Info files whose location is specified this way.) For example, to reach a test file in the `~bob/manuals' directory, you could add an entry like this to the menu in the `dir' file: * Test: (/usr/bob/manuals/info-test). Bob's own test file. In this case, the absolute file name of the `info-test' file is written as the second part of the menu entry. Alternatively, you could write the following in your `.emacs' file: (setq Info-directory-list '("/usr/bob/manuals" "/usr/local/emacs/info")) This tells Emacs to merge the `dir' file from the `/usr/bob/manuals' directory with the `dir' file from the `"/usr/local/emacs/info'" directory. Info will list the `/usr/bob/manuals/info-test' file as a menu entry in the `/usr/bob/manuals/dir' file. Finally, you can tell Info where to look by setting the `INFOPATH' environment variable in your `.cshrc' or `.profile' file. If you use `sh' or `bash' for your shell command interpreter, you must set the `INFOPATH' environment variable in the `.profile' initialization file; but if you use `csh', you must set the variable in the `.cshrc' initialization file. The two files require slightly different command formats. * In a `.cshrc' file, you could set the `INFOPATH' variable as follows: setenv INFOPATH .:~bob/manuals:/usr/local/emacs/info * In a `.profile' file, you would achieve the same effect by writing: INFOPATH=.:~bob/manuals:/usr/local/emacs/info export INFOPATH The `.' indicates the current directory. Emacs uses the `INFOPATH' environment variable to initialize the value of Emacs's own `Info-directory-list' variable.