This is Info file texinfo, produced by Makeinfo version 1.68 from the input file ../texi/texinfo.texi. index (arbitrarily chosen to be the concept index). INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Updating info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. END-INFO-DIR-ENTRY This file documents Texinfo, a documentation system that can produce both on-line information and a printed manual from a single source file. Copyright (C) 1988, 90, 91, 92, 93, 95, 1996 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: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Format/Print Hardcopy Format using `tex' and `texindex' ================================= Format the Texinfo file with the shell command `tex' followed by the name of the Texinfo file. This command produces a formatted DVI file as well as several auxiliary files containing indices, cross references, etc. The DVI file (for "DeVice Independent" file) can be printed on a wide variety of printers. The `tex' formatting command itself does not sort the indices; it writes an output file of unsorted index data. This is a misfeature of TeX. (The `texi2dvi' command automatically generates indices; see *Note Format using `texi2dvi': Format with texi2dvi.) To generate a printed index after running the `tex' command, you first need a sorted index to work from. The `texindex' command sorts indices. (The source file `texindex.c' comes as part of the standard GNU distribution and is usually installed when Emacs is installed.) The `tex' formatting command outputs unsorted index files under names that obey a standard convention. These names are the name of your main input file to the `tex' formatting command, with everything after the first period thrown away, and the two letter names of indices added at the end. For example, the raw index output files for the input file `foo.texinfo' would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'. Those are exactly the arguments to give to `texindex'. Or else, you can use `??' as "wild-cards" and give the command in this form: texindex foo.?? This command will run `texindex' on all the unsorted index files, including any that you have defined yourself using `@defindex' or `@defcodeindex'. (You may execute `texindex foo.??' even if there are similarly named files with two letter extensions that are not index files, such as `foo.el'. The `texindex' command reports but otherwise ignores such files.) For each file specified, `texindex' generates a sorted index file whose name is made by appending `s' to the input file name. The `@printindex' command knows to look for a file of that name. `texindex' does not alter the raw index output file. After you have sorted the indices, you need to rerun the `tex' formatting command on the Texinfo file. This regenerates a formatted DVI file with up-to-date index entries.(1) (*note Format with tex/texindex-Footnotes::) To summarize, this is a three step process: 1. Run the `tex' formatting command on the Texinfo file. This generates the formatted DVI file as well as the raw index files with two letter extensions. 2. Run the shell command `texindex' on the raw index files to sort them. This creates the corresponding sorted index files. 3. Rerun the `tex' formatting command on the Texinfo file. This regenerates a formatted DVI file with the index entries in the correct order. This second run also corrects the page numbers for the cross references. (The tables of contents are always correct.) You need not run `texindex' each time after you run the `tex' formatting. If you do not, on the next run, the `tex' formatting command will use whatever sorted index files happen to exist from the previous use of `texindex'. This is usually OK while you are debugging.  File: texinfo, Node: Format with tex/texindex-Footnotes, Up: Format with tex/texindex (1) If you use more than one index and have cross references to an index other than the first, you must run `tex' *three times* to get correct output: once to generate raw index data; again (after `texindex') to output the text of the indices and determine their true page numbers; and a third time to output correct page numbers in cross references to them. However, cross references to indices are rare.  File: texinfo, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Format/Print Hardcopy Format using `texi2dvi' ======================= The `texi2dvi' command is a shell script that automatically runs both `tex' and `texindex' as many times as necessary to produce a DVI file with up-to-date, sorted indices. It simplifies the `tex'--`texindex'--`tex' sequence described in the previous section. The syntax for `texi2dvi' is like this (where `prompt$' is the shell prompt): prompt$ texi2dvi FILENAME...  File: texinfo, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Format/Print Hardcopy Shell Print Using `lpr -d' ========================== You can print a DVI file with the DVI print command. The precise printing command to use depends on your system; `lpr -d' is common. The DVI print command may require a file name without any extension or with a `.dvi' extension. The following commands, for example, sort the indices, format, and print the `Bison Manual' (where `%' is the shell prompt): % tex bison.texinfo % texindex bison.?? % tex bison.texinfo % lpr -d bison.dvi (Remember that the shell commands may be different at your site; but these are commonly used versions.) Using the `texi2dvi' shell script, you simply need type: % texi2dvi bison.texinfo % lpr -d bison.dvi  File: texinfo, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Format/Print Hardcopy From an Emacs Shell ... ======================= You can give formatting and printing commands from a shell within GNU Emacs. To create a shell within Emacs, type `M-x shell'. In this shell, you can format and print the document. *Note Format and Print Hardcopy: Format/Print Hardcopy, for details. You can switch to and from the shell buffer while `tex' is running and do other editing. If you are formatting a long document on a slow machine, this can be very convenient. You can also use `texi2dvi' from an Emacs shell. For example, here is how to use `texi2dvi' to format and print `Using and Porting GNU CC' from a shell within Emacs (where `%' is the shell prompt): % texi2dvi gcc.texinfo % lpr -d gcc.dvi *Note Texinfo Mode Printing::, for more information about formatting and printing in Texinfo mode.  File: texinfo, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Format/Print Hardcopy Formatting and Printing in Texinfo Mode ======================================= Texinfo mode provides several predefined key commands for TeX formatting and printing. These include commands for sorting indices, looking at the printer queue, killing the formatting job, and recentering the display of the buffer in which the operations occur. `C-c C-t C-b' `M-x texinfo-tex-buffer' Run `texi2dvi' on the current buffer. `C-c C-t C-r' `M-x texinfo-tex-region' Run TeX on the current region. `C-c C-t C-i' `M-x texinfo-texindex' Sort the indices of a Texinfo file formatted with `texinfo-tex-region'. `C-c C-t C-p' `M-x texinfo-tex-print' Print a DVI file that was made with `texinfo-tex-region' or `texinfo-tex-buffer'. `C-c C-t C-q' `M-x tex-show-print-queue' Show the print queue. `C-c C-t C-d' `M-x texinfo-delete-from-print-queue' Delete a job from the print queue; you will be prompted for the job number shown by a preceding `C-c C-t C-q' command (`texinfo-show-tex-print-queue'). `C-c C-t C-k' `M-x tex-kill-job' Kill the currently running TeX job started by `texinfo-tex-region' or `texinfo-tex-buffer', or any other process running in the Texinfo shell buffer. `C-c C-t C-x' `M-x texinfo-quit-job' Quit a TeX formatting job that has stopped because of an error by sending an to it. When you do this, TeX preserves a record of what it did in a `.log' file. `C-c C-t C-l' `M-x tex-recenter-output-buffer' Redisplay the shell buffer in which the TeX printing and formatting commands are run to show its most recent output. Thus, the usual sequence of commands for formatting a buffer is as follows (with comments to the right): C-c C-t C-b Run `texi2dvi' on the buffer. C-c C-t C-p Print the DVI file. C-c C-t C-q Display the printer queue. The Texinfo mode TeX formatting commands start a subshell in Emacs called the `*tex-shell*'. The `texinfo-tex-command', `texinfo-texindex-command', and `tex-dvi-print-command' commands are all run in this shell. You can watch the commands operate in the `*tex-shell*' buffer, and you can switch to and from and use the `*tex-shell*' buffer as you would any other shell buffer. The formatting and print commands depend on the values of several variables. The default values are: Variable Default value texinfo-texi2dvi-command "texi2dvi" texinfo-tex-command "tex" texinfo-texindex-command "texindex" texinfo-delete-from-print-queue-command "lprm" texinfo-tex-trailer "@bye" tex-start-of-header "%**start" tex-end-of-header "%**end" tex-dvi-print-command "lpr -d" tex-show-queue-command "lpq" You can change the values of these variables with the `M-x edit-options' command (*note Editing Variable Values: (emacs)Edit Options.), with the `M-x set-variable' command (*note Examining and Setting Variables: (emacs)Examining.), or with your `.emacs' initialization file (*note Init File: (emacs)Init File.).  File: texinfo, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Format/Print Hardcopy Using the Local Variables List ============================== Yet another way to apply the TeX formatting command to a Texinfo file is to put that command in a "local variables list" at the end of the Texinfo file. You can then specify the `tex' or `texi2dvi' commands as a `compile-command' and have Emacs run it by typing `M-x compile'. This creates a special shell called the `*compilation*' buffer in which Emacs runs the compile command. For example, at the end of the `gdb.texinfo' file, after the `@bye', you could put the following: @c Local Variables: @c compile-command: "texi2dvi gdb.texinfo" @c End: This technique is most often used by programmers who also compile programs this way; see *Note Compilation: (emacs)Compilation.  File: texinfo, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Format/Print Hardcopy TeX Formatting Requirements Summary =================================== Every Texinfo file that is to be input to TeX must begin with a `\input' command and must contain an `@setfilename' command and an `@settitle' command: \input texinfo @setfilename ARG-NOT-USED-BY-TEX @settitle NAME-OF-MANUAL The first command instructs TeX to load the macros it needs to process a Texinfo file, the second command opens auxiliary files, and the third specifies the title of printed manual. Every Texinfo file must end with a line that terminates TeX processing and forces out unfinished pages: @bye Strictly speaking, these four lines are all a Texinfo file needs for TeX, besides the body. (The `@setfilename' line is the only line that a Texinfo file needs for Info formatting.) Usually, the file's first line contains an `@c -*-texinfo-*-' comment that causes Emacs to switch to Texinfo mode when you edit the file. In addition, the beginning usually includes an `@setchapternewpage' command, a title page, a copyright page, and permissions. Besides an `@bye', the end of a file usually includes indices and a table of contents. For more information, see *Note `@setchapternewpage': setchapternewpage, *Note Page Headings: Headings, *Note Titlepage & Copyright Page::, *Note Printing Indices & Menus::, and *Note Contents::.  File: texinfo, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Format/Print Hardcopy Preparing to Use TeX ==================== TeX needs to know where to find the `texinfo.tex' file that you have told it to input with the `\input texinfo' command at the beginning of the first line. The `texinfo.tex' file tells TeX how to handle @-commands. (`texinfo.tex' is included in the standard GNU distributions.) Usually, the `texinfo.tex' file is put in the default directory that contains TeX macros (the `/usr/lib/tex/macros' directory) when GNU Emacs or other GNU software is installed. In this case, TeX will find the file and you do not need to do anything special. Alternatively, you can put `texinfo.tex' in the directory in which the Texinfo source file is located, and TeX will find it there. However, you may want to specify the location of the `\input' file yourself. One way to do this is to write the complete path for the file after the `\input' command. Another way is to set the `TEXINPUTS' environment variable in your `.cshrc' or `.profile' file. The `TEXINPUTS' environment variable will tell TeX where to find the `texinfo.tex' file and any other file that you might want TeX to use. Whether you use a `.cshrc' or `.profile' file depends on whether you use `csh', `sh', or `bash' for your shell command interpreter. When you use `csh', it looks to the `.cshrc' file for initialization information, and when you use `sh' or `bash', it looks to the `.profile' file. In a `.cshrc' file, you could use the following `csh' command sequence: setenv TEXINPUTS .:/usr/me/mylib:/usr/lib/tex/macros In a `.profile' file, you could use the following `sh' command sequence: TEXINPUTS=.:/usr/me/mylib:/usr/lib/tex/macros export TEXINPUTS This would cause TeX to look for `\input' file first in the current directory, indicated by the `.', then in a hypothetical user's `me/mylib' directory, and finally in the system library.  File: texinfo, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Format/Print Hardcopy Overfull "hboxes" ================= TeX is sometimes unable to typeset a line without extending it into the right margin. This can occur when TeX comes upon what it interprets as a long word that it cannot hyphenate, such as an electronic mail network address or a very long title. When this happens, TeX prints an error message like this: Overfull \hbox (20.76302pt too wide) (In TeX, lines are in "horizontal boxes", hence the term, "hbox". The backslash, `\', is the TeX equivalent of `@'.) TeX also provides the line number in the Texinfo source file and the text of the offending line, which is marked at all the places that TeX knows how to hyphenate words. *Note Catching Errors with TeX Formatting: Debugging with TeX, for more information about typesetting errors. If the Texinfo file has an overfull hbox, you can rewrite the sentence so the overfull hbox does not occur, or you can decide to leave it. A small excursion into the right margin often does not matter and may not even be noticeable. However, unless told otherwise, TeX will print a large, ugly, black rectangle beside the line that contains the overfull hbox. This is so you will notice the location of the problem if you are correcting a draft. To prevent such a monstrosity from marring your final printout, write the following in the beginning of the Texinfo file on a line of its own, before the `@titlepage' command: @finalout  File: texinfo, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Format/Print Hardcopy Printing "Small" Books ====================== By default, TeX typesets pages for printing in an 8.5 by 11 inch format. However, you can direct TeX to typeset a document in a 7 by 9.25 inch format that is suitable for bound books by inserting the following command on a line by itself at the beginning of the Texinfo file, before the title page: @smallbook (Since regular sized books are often about 7 by 9.25 inches, this command might better have been called the `@regularbooksize' command, but it came to be called the `@smallbook' command by comparison to the 8.5 by 11 inch format.) If you write the `@smallbook' command between the start-of-header and end-of-header lines, the Texinfo mode TeX region formatting command, `texinfo-tex-region', will format the region in "small" book size (*note Start of Header::.). The Free Software Foundation distributes printed copies of `The GNU Emacs Manual' and other manuals in the "small" book size. *Note `@smallexample' and `@smalllisp': smallexample & smalllisp, for information about commands that make it easier to produce examples for a smaller manual.  File: texinfo, Node: A4 Paper, Next: Cropmarks and Magnification, Prev: smallbook, Up: Format/Print Hardcopy Printing on A4 Paper ==================== You can tell TeX to typeset a document for printing on European size A4 paper with the `@afourpaper' command. Write the command on a line by itself between `@iftex' and `@end iftex' lines near the beginning of the Texinfo file, before the title page: For example, this is how you would write the header for this manual: \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename texinfo @settitle Texinfo @syncodeindex vr fn @iftex @afourpaper @end iftex @c %**end of header  File: texinfo, Node: Cropmarks and Magnification, Prev: A4 Paper, Up: Format/Print Hardcopy Cropmarks and Magnification =========================== You can attempt to direct TeX to print cropmarks at the corners of pages with the `@cropmarks' command. Write the `@cropmarks' command on a line by itself between `@iftex' and `@end iftex' lines near the beginning of the Texinfo file, before the title page, like this: @iftex @cropmarks @end iftex This command is mainly for printers that typeset several pages on one sheet of film; but you can attempt to use it to mark the corners of a book set to 7 by 9.25 inches with the `@smallbook' command. (Printers will not produce cropmarks for regular sized output that is printed on regular sized paper.) Since different printing machines work in different ways, you should explore the use of this command with a spirit of adventure. You may have to redefine the command in the `texinfo.tex' definitions file. You can attempt to direct TeX to typeset pages larger or smaller than usual with the `\mag' TeX command. Everything that is typeset is scaled proportionally larger or smaller. (`\mag' stands for "magnification".) This is *not* a Texinfo @-command, but is a plain TeX command that is prefixed with a backslash. You have to write this command between `@tex' and `@end tex' (*note Using Ordinary TeX Commands: Using Ordinary TeX Commands.). Follow the `\mag' command with an `=' and then a number that is 1000 times the magnification you desire. For example, to print pages at 1.2 normal size, write the following near the beginning of the Texinfo file, before the title page: @tex \mag=1200 @end tex With some printing technologies, you can print normal-sized copies that look better than usual by using a larger-than-normal master. Depending on your system, `\mag' may not work or may work only at certain magnifications. Be prepared to experiment.  File: texinfo, Node: Create an Info File, Next: Install an Info File, Prev: Format/Print Hardcopy, Up: Top Creating an Info File ********************* `makeinfo' is a utility that converts a Texinfo file into an Info file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs functions that do the same. A Texinfo file must possess an `@setfilename' line near its beginning, otherwise the Info formatting commands will fail. For information on installing the Info file in the Info system, see *Note Install an Info File::. * Menu: * makeinfo advantages:: `makeinfo' provides better error checking. * Invoking makeinfo:: How to run `makeinfo' from a shell. * makeinfo options:: Specify fill-column and other options. * Pointer Validation:: How to check that pointers point somewhere. * makeinfo in Emacs:: How to run `makeinfo' from Emacs. * texinfo-format commands:: Two Info formatting commands written in Emacs Lisp are an alternative to `makeinfo'. * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better.  File: texinfo, Node: makeinfo advantages, Next: Invoking makeinfo, Prev: Create an Info File, Up: Create an Info File `makeinfo' Preferred ==================== The `makeinfo' utility creates an Info file from a Texinfo source file more quickly than either of the Emacs formatting commands and provides better error messages. We recommend it. `makeinfo' is a C program that is independent of Emacs. You do not need to run Emacs to use `makeinfo', which means you can use `makeinfo' on machines that are too small to run Emacs. You can run `makeinfo' in any one of three ways: from an operating system shell, from a shell inside Emacs, or by typing a key command in Texinfo mode in Emacs. The `texinfo-format-region' and the `texinfo-format-buffer' commands are useful if you cannot run `makeinfo'. Also, in some circumstances, they format short regions or buffers more quickly than `makeinfo'.  File: texinfo, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Create an Info File Running `makeinfo' from a Shell =============================== To create an Info file from a Texinfo file, type `makeinfo' followed by the name of the Texinfo file. Thus, to create the Info file for Bison, type the following at the shell prompt (where `%' is the prompt): % makeinfo bison.texinfo (You can run a shell inside Emacs by typing `M-x shell'.) Sometimes you will want to specify options. For example, if you wish to discover which version of `makeinfo' you are using, type: % makeinfo --version *Note makeinfo options::, for more information.  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 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. * Installing Dir Entries:: How to specify what menu entry to add to the Info directory. * Invoking install-info:: `install-info' options.  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, you must write a menu entry to add to the menu in the `dir' file in 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. The name of an Info file often has a `.info' extension. Thus, the Info file for GDB might be called either `gdb' or `gdb.info'. The Info reader programs automatically try the file name both with and without `.info'; so it is better to avoid clutter and not to write `.info' explicitly in the menu entry. For example, the GDB menu entry should use just `gdb' for the file name, not `gdb.info'.  File: texinfo, Node: Other Info Directories, Next: Installing Dir Entries, 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 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 the `INFOPATH' 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: (/home/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 '("/home/bob/manuals" "/usr/local/emacs/info")) This tells Emacs to merge the `dir' file from the `/home/bob/manuals' directory with the `dir' file from the `"/usr/local/emacs/info'" directory. Info will list the `/home/bob/manuals/info-test' file as a menu entry in the `/home/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 use 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.  File: texinfo, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Install an Info File Installing Info Directory Files =============================== When you install an Info file onto your system, you can use the program `install-info' to update the Info directory file `dir'. Normally the makefile for the package runs `install-info', just after copying the Info file into its proper installed location. In order for the Info file to work with `install-info', you should use the commands `@dircategory' and `@direntry' in the Texinfo source file. Use `@direntry' to specify the menu entry to add to the Info directory file, and use `@dircategory' to specify which part of the Info directory to put it in. Here is how these commands are used in this manual: @dircategory Texinfo documentation system @direntry * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. ... ... @end direntry Here's what this produces in the Info file: INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. ... ... END-INFO-DIR-ENTRY The `install-info' program sees these lines in the Info file, and that is how it knows what to do. Always use the `@direntry' and `@dircategory' commands near the beginning of the Texinfo input, before the first `@node' command. If you use them later on in the input, `install-info' will not notice them. If you use `@dircategory' more than once in the Texinfo source, each usage specifies one category; the new menu entry is added to the Info directory file in each of the categories you specify. If you use `@direntry' more than once, each usage specifies one menu entry; each of these menu entries is added to the directory in each of the specified categories.  File: texinfo, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Install an Info File Invoking install-info ===================== `install-info' inserts menu entries from an Info file into the top-level `dir' file in the Info system (see the previous sections for an explanation of how the `dir' file works). It's most often run as part of software installation, or when constructing a dir file for all manuals on a system. Synopsis: install-info [OPTION]... [INFO-FILE [DIR-FILE]] If INFO-FILE or DIR-FILE are not specified, the various options (described below) that define them must be. There are no compile-time defaults, and standard input is never used. `install-info' can read only one info file and write only one dir file per invocation. Options: `--delete' Only delete existing entries in INFO-FILE; don't insert any new entries. `--dir-file=NAME' Specify file name of the Info directory file. This is equivalent to using the DIR-FILE argument. `--entry=TEXT' Insert TEXT as an Info directory entry; TEXT should have the form of an Info menu item line plus zero or more extra lines starting with whitespace. If you specify more than one entry, they are all added. If you don't specify any entries, they are determined from information in the Info file itself. `--help' Display a usage message listing basic usage and all available options, then exit successfully. `--info-file=FILE' Specify Info file to install in the directory. This is equivalent to using the INFO-FILE argument. `--info-dir=DIR' Equivalent to `--dir-file=DIR/dir'. `--item=TEXT' Same as -entry=TEXT. An Info directory entry is actually a menu item. `--quiet' Suppress warnings. `--remove' Same as -delete. `--section=SEC' Put this file's entries in section SEC of the directory. If you specify more than one section, all the entries are added in each of the sections. If you don't specify any sections, they are determined from information in the Info file itself. `--version' Display version information and exit successfully.