1 This is ../info/texinfo.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
19 This edition is for Texinfo version 3.12.
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
36 File: texinfo.info, Node: Invoking Macros, Prev: Defining Macros, Up: Macros
41 After a macro is defined (see the previous section), you can use
42 ("invoke") it in your document like this:
44 @MACRO-NAME {ARG1, ARG2, ...}
46 and the result will be just as if you typed the body of MACRO-NAME at
47 that spot. For example:
58 Thus, the arguments and parameters are separated by commas and
59 delimited by braces; any whitespace after (but not before) a comma is
60 ignored. To insert a comma, brace, or backslash in an argument,
61 prepend a backslash, as in
63 @MACRO-NAME {\\\{\}\,}
65 which will pass the (almost certainly error-producing) argument `\{},'
68 If the macro is defined to take a single argument, and is invoked
69 without any braces, the entire rest of the line after the macro name is
70 supplied as the argument. For example:
82 File: texinfo.info, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Macros, Up: Top
84 Format and Print Hardcopy
85 *************************
87 There are three major shell commands for making a printed manual from
88 a Texinfo file: one for converting the Texinfo file into a file that
89 will be printed, a second for sorting indices, and a third for printing
90 the formatted document. When you use the shell commands, you can either
91 work directly in the operating system shell or work within a shell
94 If you are using GNU Emacs, you can use commands provided by Texinfo
95 mode instead of shell commands. In addition to the three commands to
96 format a file, sort the indices, and print the result, Texinfo mode
97 offers key bindings for commands to recenter the output buffer, show the
98 print queue, and delete a job from the print queue.
102 * Use TeX:: Use TeX to format for hardcopy.
103 * Format with tex/texindex:: How to format in a shell.
104 * Format with texi2dvi:: A simpler way to use the shell.
105 * Print with lpr:: How to print.
106 * Within Emacs:: How to format and print from an Emacs shell.
107 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
108 * Compile-Command:: How to print using Emacs's compile command.
109 * Requirements Summary:: TeX formatting requirements summary.
110 * Preparing for TeX:: What you need to do to use TeX.
111 * Overfull hboxes:: What are and what to do with overfull hboxes.
112 * smallbook:: How to print small format books and manuals.
113 * A4 Paper:: How to print on European A4 paper.
114 * Cropmarks and Magnification:: How to print marks to indicate the size
115 of pages and how to print scaled up output.
118 File: texinfo.info, Node: Use TeX, Next: Format with tex/texindex, Prev: Format/Print Hardcopy, Up: Format/Print Hardcopy
123 The typesetting program called TeX is used for formatting a Texinfo
124 file. TeX is a very powerful typesetting program and, if used right,
125 does an exceptionally good job. (*Note How to Obtain TeX: Obtaining
126 TeX, for information on how to obtain TeX.)
128 The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer'
129 commands read the very same @-commands in the Texinfo file as does TeX,
130 but process them differently to make an Info file; see *Note Create an
134 File: texinfo.info, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Format/Print Hardcopy
136 Format using `tex' and `texindex'
137 =================================
139 Format the Texinfo file with the shell command `tex' followed by the
140 name of the Texinfo file. For example:
144 TeX will produce a "DVI file" as well as several auxiliary files
145 containing information for indices, cross references, etc. The DVI
146 file (for "DeVice Independent" file) can be printed on virtually any
147 printe (see the following sections).
149 The `tex' formatting command itself does not sort the indices; it
150 writes an output file of unsorted index data. (The `texi2dvi' command
151 automatically generates indices; see *Note Format using `texi2dvi':
152 Format with texi2dvi.) To generate a printed index after running the
153 `tex' command, you first need a sorted index to work from. The
154 `texindex' command sorts indices. (The source file `texindex.c' comes
155 as part of the standard Texinfo distribution, among other places.)
157 The `tex' formatting command outputs unsorted index files under names
158 that obey a standard convention: the name of your main input file with
159 any `.tex' (or similar, *note tex invocation: (web2c)tex invocation.)
160 extension removed, followed by the two letter names of indices. For
161 example, the raw index output files for the input file `foo.texinfo'
162 would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.
163 Those are exactly the arguments to give to `texindex'.
165 Instead of specifying all the unsorted index file names explicitly,
166 you can use `??' as shell wildcards and give the command in this form:
170 This command will run `texindex' on all the unsorted index files,
171 including any that you have defined yourself using `@defindex' or
172 `@defcodeindex'. (You may execute `texindex foo.??' even if there are
173 similarly named files with two letter extensions that are not index
174 files, such as `foo.el'. The `texindex' command reports but otherwise
177 For each file specified, `texindex' generates a sorted index file
178 whose name is made by appending `s' to the input file name. The
179 `@printindex' command knows to look for a file of that name (*note
180 Printing Indices & Menus::). `texindex' does not alter the raw index
183 After you have sorted the indices, you need to rerun the `tex'
184 formatting command on the Texinfo file. This regenerates the DVI file,
185 this time with up-to-date index entries.
187 Finally, you may need to run `tex' one more time, to get the page
188 numbers in the cross-references correct.
190 To summarize, this is a four step process:
192 1. Run `tex' on your Texinfo file. This generates a DVI file (with
193 undefined cross-references and no indices), and the raw index files
194 (with two letter extensions).
196 2. Run `texindex' on the raw index files. This creates the
197 corresponding sorted index files (with three letter extensions).
199 3. Run `tex' again on your Texinfo file. This regenerates the DVI
200 file, this time with indices and defined cross-references, but
201 with page numbers for the cross-references from last time,
204 4. Run `tex' one last time. This time the correct page numbers are
205 written for the cross-references.
207 Alternatively, it's a one-step process: run `texi2dvi'.
209 You need not run `texindex' each time after you run `tex'. If you do
210 not, on the next run, the `tex' formatting command will use whatever
211 sorted index files happen to exist from the previous use of `texindex'.
212 This is usually ok while you are debugging.
215 File: texinfo.info, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Format/Print Hardcopy
217 Format using `texi2dvi'
218 =======================
220 The `texi2dvi' command automatically runs both `tex' and `texindex'
221 as many times as necessary to produce a DVI file with up-to-date,
222 sorted indices. It simplifies the `tex'--`texindex'--`tex' sequence
223 described in the previous section.
225 The syntax for `texi2dvi' is like this (where `prompt$' is your shell
228 prompt$ texi2dvi FILENAME...
230 For a list of options, run `texi2dvi --help'.
233 File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Format/Print Hardcopy
235 Shell Print Using `lpr -d'
236 ==========================
238 The precise command to print a DVI file depends on your system
239 installation, but `lpr -d' is common. The command may require the DVI
240 file name without any extension or with a `.dvi' extension. (If it is
241 `lpr', you must include the `.dvi'.)
243 The following commands, for example, will (probably) suffice to sort
244 the indices, format, and print the `Bison Manual':
251 (Remember that the shell commands may be different at your site; but
252 these are commonly used versions.)
254 Using the `texi2dvi' shell script, you simply need type:
256 texi2dvi bison.texinfo
260 File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Format/Print Hardcopy
265 You can give formatting and printing commands from a shell within GNU
266 Emacs. To create a shell within Emacs, type `M-x shell'. In this
267 shell, you can format and print the document. *Note Format and Print
268 Hardcopy: Format/Print Hardcopy, for details.
270 You can switch to and from the shell buffer while `tex' is running
271 and do other editing. If you are formatting a long document on a slow
272 machine, this can be very convenient.
274 You can also use `texi2dvi' from an Emacs shell. For example, here
275 is how to use `texi2dvi' to format and print `Using and Porting GNU CC'
276 from a shell within Emacs:
281 *Note Texinfo Mode Printing::, for more information about formatting
282 and printing in Texinfo mode.
285 File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Format/Print Hardcopy
287 Formatting and Printing in Texinfo Mode
288 =======================================
290 Texinfo mode provides several predefined key commands for TeX
291 formatting and printing. These include commands for sorting indices,
292 looking at the printer queue, killing the formatting job, and
293 recentering the display of the buffer in which the operations occur.
296 `M-x texinfo-tex-buffer'
297 Run `texi2dvi' on the current buffer.
300 `M-x texinfo-tex-region'
301 Run TeX on the current region.
304 `M-x texinfo-texindex'
305 Sort the indices of a Texinfo file formatted with
306 `texinfo-tex-region'.
309 `M-x texinfo-tex-print'
310 Print a DVI file that was made with `texinfo-tex-region' or
311 `texinfo-tex-buffer'.
314 `M-x tex-show-print-queue'
315 Show the print queue.
318 `M-x texinfo-delete-from-print-queue'
319 Delete a job from the print queue; you will be prompted for the job
320 number shown by a preceding `C-c C-t C-q' command
321 (`texinfo-show-tex-print-queue').
325 Kill the currently running TeX job started by `texinfo-tex-region'
326 or `texinfo-tex-buffer', or any other process running in the
327 Texinfo shell buffer.
330 `M-x texinfo-quit-job'
331 Quit a TeX formatting job that has stopped because of an error by
332 sending an <x> to it. When you do this, TeX preserves a record of
333 what it did in a `.log' file.
336 `M-x tex-recenter-output-buffer'
337 Redisplay the shell buffer in which the TeX printing and formatting
338 commands are run to show its most recent output.
340 Thus, the usual sequence of commands for formatting a buffer is as
341 follows (with comments to the right):
343 C-c C-t C-b Run `texi2dvi' on the buffer.
344 C-c C-t C-p Print the DVI file.
345 C-c C-t C-q Display the printer queue.
347 The Texinfo mode TeX formatting commands start a subshell in Emacs
348 called the `*tex-shell*'. The `texinfo-tex-command',
349 `texinfo-texindex-command', and `tex-dvi-print-command' commands are
350 all run in this shell.
352 You can watch the commands operate in the `*tex-shell*' buffer, and
353 you can switch to and from and use the `*tex-shell*' buffer as you
354 would any other shell buffer.
356 The formatting and print commands depend on the values of several
357 variables. The default values are:
359 Variable Default value
361 texinfo-texi2dvi-command "texi2dvi"
362 texinfo-tex-command "tex"
363 texinfo-texindex-command "texindex"
364 texinfo-delete-from-print-queue-command "lprm"
365 texinfo-tex-trailer "@bye"
366 tex-start-of-header "%**start"
367 tex-end-of-header "%**end"
368 tex-dvi-print-command "lpr -d"
369 tex-show-queue-command "lpq"
371 You can change the values of these variables with the `M-x
372 edit-options' command (*note Editing Variable Values: (xemacs)Edit
373 Options.), with the `M-x set-variable' command (*note Examining and
374 Setting Variables: (xemacs)Examining.), or with your `.emacs'
375 initialization file (*note Init File: (xemacs)Init File.).
378 File: texinfo.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Format/Print Hardcopy
380 Using the Local Variables List
381 ==============================
383 Yet another way to apply the TeX formatting command to a Texinfo file
384 is to put that command in a "local variables list" at the end of the
385 Texinfo file. You can then specify the `tex' or `texi2dvi' commands as
386 a `compile-command' and have Emacs run it by typing `M-x compile'.
387 This creates a special shell called the `*compilation*' buffer in which
388 Emacs runs the compile command. For example, at the end of the
389 `gdb.texinfo' file, after the `@bye', you could put the following:
392 compile-command: "texi2dvi gdb.texinfo"
395 This technique is most often used by programmers who also compile
396 programs this way; see *Note Compilation: (xemacs)Compilation.
399 File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Format/Print Hardcopy
401 TeX Formatting Requirements Summary
402 ===================================
404 Every Texinfo file that is to be input to TeX must begin with a
405 `\input' command and must contain an `@setfilename' command:
408 @setfilename ARG-NOT-USED-BY-@TEX{}
410 The first command instructs TeX to load the macros it needs to process
411 a Texinfo file and the second command opens auxiliary files.
413 Every Texinfo file must end with a line that terminates TeX's
414 processing and forces out unfinished pages:
418 Strictly speaking, these lines are all a Texinfo file needs to be
419 processed successfully by TeX.
421 Usually, however, the beginning includes an `@settitle' command to
422 define the title of the printed manual, an `@setchapternewpage'
423 command, a title page, a copyright page, and permissions. Besides an
424 `@bye', the end of a file usually includes indices and a table of
425 contents. (And of course most manuals contain a body of text as well.)
427 For more information, see
428 *Note `@settitle': settitle,
429 *Note `@setchapternewpage': setchapternewpage,
430 *Note Page Headings: Headings,
431 *Note Titlepage & Copyright Page::,
432 *Note Printing Indices & Menus::, and
436 File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Format/Print Hardcopy
441 TeX needs to know where to find the `texinfo.tex' file that you have
442 told it to input with the `\input texinfo' command at the beginning of
443 the first line. The `texinfo.tex' file tells TeX how to handle
444 @-commands; it is included in all standard GNU distributions.
446 Usually, the `texinfo.tex' file is put under the default directory
447 that contains TeX macros
448 (`/usr/local/share/texmf/tex/texinfo/texinfo.tex' by default) when GNU
449 Emacs or other GNU software is installed. In this case, TeX will find
450 the file and you do not need to do anything special. Alternatively,
451 you can put `texinfo.tex' in the current directory when you run TeX,
452 and TeX will find it there.
454 Also, you should install `epsf.tex' in the same place as
455 `texinfo.tex', if it is not already installed from another
456 distribution. This file is needed to support the `@image' command
459 Optionally, you may create an additional `texinfo.cnf', and install
460 it as well. This file is read by TeX at the `@setfilename' command
461 (*note `@setfilename': setfilename.). You can put any commands you
462 like there according to local site-wide conventions, and they will be
463 read by TeX when processing any Texinfo document. For example, if
464 `texinfo.cnf' contains the a single line `@afourpaper' (*note A4
465 Paper::), then all Texinfo documents will be processed with that page
466 size in effect. If you have nothing to put in `texinfo.cnf', you do
467 not need to create it.
469 If neither of the above locations for these system files suffice for
470 you, you can specify the directories explicitly. For `texinfo.tex',
471 you can do this by writing the complete path for the file after the
472 `\input' command. Another way, that works for both `texinfo.tex' and
473 `texinfo.cnf' (and any other file TeX might read), is to set the
474 `TEXINPUTS' environment variable in your `.cshrc' or `.profile' file.
476 Which you use of `.cshrc' or `.profile' depends on whether you use a
477 Bourne shell-compatible (`sh', `bash', `ksh', ...) or C
478 shell-compatible (`csh', `tcsh') command interpreter. The latter read
479 the `.cshrc' file for initialization information, and the former read
482 In a `.cshrc' file, you could use the following `csh' command
485 setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
487 In a `.profile' file, you could use the following `sh' command
490 TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
493 This would cause TeX to look for `\input' file first in the current
494 directory, indicated by the `.', then in a hypothetical user's
495 `me/mylib' directory, and finally in a system directory.
498 File: texinfo.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Format/Print Hardcopy
503 TeX is sometimes unable to typeset a line without extending it into
504 the right margin. This can occur when TeX comes upon what it
505 interprets as a long word that it cannot hyphenate, such as an
506 electronic mail network address or a very long title. When this
507 happens, TeX prints an error message like this:
509 Overfull \hbox (20.76302pt too wide)
511 (In TeX, lines are in "horizontal boxes", hence the term, "hbox". The
512 backslash, `\', is the TeX equivalent of `@'.)
514 TeX also provides the line number in the Texinfo source file and the
515 text of the offending line, which is marked at all the places that TeX
516 knows how to hyphenate words. *Note Catching Errors with TeX
517 Formatting: Debugging with TeX, for more information about typesetting
520 If the Texinfo file has an overfull hbox, you can rewrite the sentence
521 so the overfull hbox does not occur, or you can decide to leave it. A
522 small excursion into the right margin often does not matter and may not
525 However, unless told otherwise, TeX will print a large, ugly, black
526 rectangle beside the line that contains the overfull hbox. This is so
527 you will notice the location of the problem if you are correcting a
530 To prevent such a monstrosity from marring your final printout, write
531 the following in the beginning of the Texinfo file on a line of its own,
532 before the `@titlepage' command:
537 File: texinfo.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Format/Print Hardcopy
539 Printing "Small" Books
540 ======================
542 By default, TeX typesets pages for printing in an 8.5 by 11 inch
543 format. However, you can direct TeX to typeset a document in a 7 by
544 9.25 inch format that is suitable for bound books by inserting the
545 following command on a line by itself at the beginning of the Texinfo
546 file, before the title page:
550 (Since regular sized books are often about 7 by 9.25 inches, this
551 command might better have been called the `@regularbooksize' command,
552 but it came to be called the `@smallbook' command by comparison to the
553 8.5 by 11 inch format.)
555 If you write the `@smallbook' command between the start-of-header and
556 end-of-header lines, the Texinfo mode TeX region formatting command,
557 `texinfo-tex-region', will format the region in "small" book size
558 (*note Start of Header::).
560 The Free Software Foundation distributes printed copies of `The GNU
561 Emacs Manual' and other manuals in the "small" book size. *Note
562 `@smallexample' and `@smalllisp': smallexample & smalllisp, for
563 information about commands that make it easier to produce examples for
566 Alternatively, to avoid embedding this physical paper size in your
567 document, use `texi2dvi' to format your document (*note Format with
568 texi2dvi::), and supply `-t @smallbook' as an argument. Then other
569 people do not have to change the document source file to format it
573 File: texinfo.info, Node: A4 Paper, Next: Cropmarks and Magnification, Prev: smallbook, Up: Format/Print Hardcopy
578 You can tell TeX to typeset a document for printing on European size
579 A4 paper with the `@afourpaper' command. Write the command on a line
580 by itself between `@iftex' and `@end iftex' lines near the beginning of
581 the Texinfo file, before the title page:
583 For example, this is how you would write the header for this manual:
585 \input texinfo @c -*-texinfo-*-
586 @c %**start of header
595 Alternatively, to avoid embedding this physical paper size in your
596 document, use `texi2dvi' to format your document (*note Format with
597 texi2dvi::), and supply `-t @afourpaper' as an argument. Then other
598 people do not have to change the document source file to format it
601 Another alternative: put the `@afourpaper' command in the file
602 `texinfo.cnf' that TeX will read. (No need for `@iftex' there.) This
603 will automatically typeset all the Texinfo documents at your site with
604 that paper size in effect.
607 File: texinfo.info, Node: Cropmarks and Magnification, Prev: A4 Paper, Up: Format/Print Hardcopy
609 Cropmarks and Magnification
610 ===========================
612 You can attempt to direct TeX to print cropmarks at the corners of
613 pages with the `@cropmarks' command. Write the `@cropmarks' command on
614 a line by itself between `@iftex' and `@end iftex' lines near the
615 beginning of the Texinfo file, before the title page, like this:
621 This command is mainly for printers that typeset several pages on one
622 sheet of film; but you can attempt to use it to mark the corners of a
623 book set to 7 by 9.25 inches with the `@smallbook' command. (Printers
624 will not produce cropmarks for regular sized output that is printed on
625 regular sized paper.) Since different printing machines work in
626 different ways, you should explore the use of this command with a
627 spirit of adventure. You may have to redefine the command in the
628 `texinfo.tex' definitions file.
630 You can attempt to direct TeX to typeset pages larger or smaller than
631 usual with the `\mag' TeX command. Everything that is typeset is
632 scaled proportionally larger or smaller. (`\mag' stands for
633 "magnification".) This is _not_ a Texinfo @-command, but is a plain
634 TeX command that is prefixed with a backslash. You have to write this
635 command between `@tex' and `@end tex' (*note Raw Formatter Commands::).
637 Follow the `\mag' command with an `=' and then a number that is 1000
638 times the magnification you desire. For example, to print pages at 1.2
639 normal size, write the following near the beginning of the Texinfo
640 file, before the title page:
646 With some printing technologies, you can print normal-sized copies
647 that look better than usual by using a larger-than-normal master.
649 Depending on your system, `\mag' may not work or may work only at
650 certain magnifications. Be prepared to experiment.
653 File: texinfo.info, Node: Create an Info File, Next: Install an Info File, Prev: Format/Print Hardcopy, Up: Top
655 Creating an Info File
656 *********************
658 `makeinfo' is a utility that converts a Texinfo file into an Info
659 file; `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs
660 functions that do the same.
662 A Texinfo file must contain an `@setfilename' line near its
663 beginning, otherwise the Info formatting commands will fail.
665 For information on installing the Info file in the Info system, see
666 *Note Install an Info File::.
670 * makeinfo advantages:: `makeinfo' provides better error checking.
671 * Invoking makeinfo:: How to run `makeinfo' from a shell.
672 * makeinfo options:: Specify fill-column and other options.
673 * Pointer Validation:: How to check that pointers point somewhere.
674 * makeinfo in Emacs:: How to run `makeinfo' from Emacs.
675 * texinfo-format commands:: Two Info formatting commands written
676 in Emacs Lisp are an alternative
678 * Batch Formatting:: How to format for Info in Emacs Batch mode.
679 * Tag and Split Files:: How tagged and split files help Info
683 File: texinfo.info, Node: makeinfo advantages, Next: Invoking makeinfo, Prev: Create an Info File, Up: Create an Info File
688 The `makeinfo' utility creates an Info file from a Texinfo source
689 file more quickly than either of the Emacs formatting commands and
690 provides better error messages. We recommend it. `makeinfo' is a C
691 program that is independent of Emacs. You do not need to run Emacs to
692 use `makeinfo', which means you can use `makeinfo' on machines that are
693 too small to run Emacs. You can run `makeinfo' in any one of three
694 ways: from an operating system shell, from a shell inside Emacs, or by
695 typing a key command in Texinfo mode in Emacs.
697 The `texinfo-format-region' and the `texinfo-format-buffer' commands
698 are useful if you cannot run `makeinfo'. Also, in some circumstances,
699 they format short regions or buffers more quickly than `makeinfo'.
702 File: texinfo.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Create an Info File
704 Running `makeinfo' from a Shell
705 ===============================
707 To create an Info file from a Texinfo file, type `makeinfo' followed
708 by the name of the Texinfo file. Thus, to create the Info file for
709 Bison, type the following to the shell: is the prompt):
711 makeinfo bison.texinfo
713 (You can run a shell inside Emacs by typing `M-x shell'.)
715 Sometimes you will want to specify options. For example, if you wish
716 to discover which version of `makeinfo' you are using, type:
720 *Note makeinfo options::, for more information.
723 File: texinfo.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Create an Info File
725 Options for `makeinfo'
726 ======================
728 The `makeinfo' command takes a number of options. Most often,
729 options are used to set the value of the fill column and specify the
730 footnote style. Each command line option is a word preceded by `--' or
731 a letter preceded by `-'. You can use abbreviations for the long
732 option names as long as they are unique.
734 For example, you could use the following shell command to create an
735 Info file for `bison.texinfo' in which each line is filled to only 68
738 makeinfo --fill-column=68 bison.texinfo
740 You can write two or more options in sequence, like this:
742 makeinfo --no-split --fill-column=70 ...
744 This would keep the Info file together as one possibly very long file
745 and would also set the fill column to 70.
750 Cause the variable VAR to be defined. This is equivalent to `@set
751 VAR' in the Texinfo file (*note set clear value::).
753 `--error-limit=LIMIT'
754 Set the maximum number of errors that `makeinfo' will report
755 before exiting (on the assumption that continuing would be
756 useless); default 100.
758 `--fill-column=WIDTH'
759 Specify the maximum number of columns in a line; this is the
760 right-hand edge of a line. Paragraphs that are filled will be
761 filled to this width. (Filling is the process of breaking up and
762 connecting lines so that lines are the same length as or shorter
763 than the number specified as the fill column. Lines are broken
764 between words.) The default value is 72.
766 `--footnote-style=STYLE'
767 Set the footnote style to STYLE, either `end' for the end node
768 style (the default) or `separate' for the separate node style.
769 The value set by this option overrides the value set in a Texinfo
770 file by an `@footnotestyle' command (*note Footnotes::). When the
771 footnote style is `separate', `makeinfo' makes a new node
772 containing the footnotes found in the current node. When the
773 footnote style is `end', `makeinfo' places the footnote references
774 at the end of the current node.
777 Ordinarily, if the input file has errors, the output files are not
778 created. With this option, they are preserved.
781 Print a usage message listing all available options, then exit
785 Add `dir' to the directory search list for finding files that are
786 included using the `@include' command. By default, `makeinfo'
787 searches only the current directory.
790 Do not include menus or node lines in the output. This results in
791 an ASCII file that you cannot read in Info since it does not
792 contain the requisite nodes or menus. It is primarily useful to
793 extract certain pieces of a manual into separate files to be
794 included in a distribution, such as `INSTALL' files.
797 Suppress the splitting stage of `makeinfo'. By default, large
798 output files (where the size is greater than 70k bytes) are split
799 into smaller subfiles, each one approximately 50k bytes.
801 `--no-pointer-validate'
803 Suppress the pointer-validation phase of `makeinfo'. Normally,
804 after a Texinfo file is processed, some consistency checks are
805 made to ensure that cross references can be resolved, etc. *Note
806 Pointer Validation::.
809 Suppress warning messages (but _not_ error messages). You might
810 want this if the file you are creating has examples of Texinfo
811 cross references within it, and the nodes that are referenced do
814 `--no-number-footnotes'
815 Suppress automatic footnote numbering. By default, `makeinfo'
816 numbers each footnote sequentially in a single node, resetting the
817 current footnote number to 1 at the start of each node.
821 Specify that the output should be directed to FILE and not to the
822 file name specified in the `@setfilename' command found in the
823 Texinfo source (*note setfilename::). If FILE is `-', output goes
824 to standard output and `--no-split' is implied.
827 Prepend `dir' to the directory search list for `@include'. See
828 `-I' for more details.
830 `--paragraph-indent=INDENT'
831 Set the paragraph indentation style to INDENT. The value set by
832 this option overrides the value set in a Texinfo file by an
833 `@paragraphindent' command (*note paragraphindent::). The value
834 of INDENT is interpreted as follows:
837 Preserve any existing indentation at the starts of paragraphs.
840 Delete any existing indentation.
843 Indent each paragraph by that number of spaces.
845 `--reference-limit=LIMIT'
846 Set the value of the number of references to a node that
847 `makeinfo' will make without reporting a warning. If a node has
848 more than this number of references in it, `makeinfo' will make the
849 references but also report a warning. The default is 1000.
852 Cause VAR to be undefined. This is equivalent to `@clear VAR' in
853 the Texinfo file (*note set clear value::).
856 Cause `makeinfo' to display messages saying what it is doing.
857 Normally, `makeinfo' only outputs messages if there are errors or
861 Print the version number, then exit successfully.
864 File: texinfo.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Create an Info File
869 If you do not suppress pointer-validation, `makeinfo' will check the
870 validity of the final Info file. Mostly, this means ensuring that
871 nodes you have referenced really exist. Here is a complete list of what
874 1. If a `Next', `Previous', or `Up' node reference is a reference to a
875 node in the current file and is not an external reference such as
876 to `(dir)', then the referenced node must exist.
878 2. In every node, if the `Previous' node is different from the `Up'
879 node, then the `Previous' node must also be pointed to by a `Next'
882 3. Every node except the `Top' node must have an `Up' pointer.
884 4. The node referenced by an `Up' pointer must contain a reference to
885 the current node in some manner other than through a `Next'
886 reference. This includes menu entries and cross references.
888 5. If the `Next' reference of a node is not the same as the `Next'
889 reference of the `Up' reference, then the node referenced by the
890 `Next' pointer must have a `Previous' pointer that points back to
891 the current node. This rule allows the last node in a section to
892 point to the first node of the next chapter.
895 File: texinfo.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Create an Info File
897 Running `makeinfo' inside Emacs
898 ===============================
900 You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
901 `makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode,
902 the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
905 `M-x makeinfo-region'
906 Format the current region for Info.
909 `M-x makeinfo-buffer'
910 Format the current buffer for Info.
912 When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
913 prompts for a file name, offering the name of the visited file as the
914 default. You can edit the default file name in the minibuffer if you
915 wish, before pressing <RET> to start the `makeinfo' process.
917 The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
918 `makeinfo' program in a temporary shell buffer. If `makeinfo' finds
919 any errors, Emacs displays the error messages in the temporary buffer.
921 You can parse the error messages by typing `C-x `' (`next-error').
922 This causes Emacs to go to and position the cursor on the line in the
923 Texinfo source that `makeinfo' thinks caused the error. *Note Running
924 `make' or Compilers Generally: (xemacs)Compilation, for more
925 information about using the `next-error' command.
927 In addition, you can kill the shell in which the `makeinfo' command
928 is running or make the shell buffer display its most recent output.
931 `M-x makeinfo-kill-job'
932 Kill the current running `makeinfo' job created by
933 `makeinfo-region' or `makeinfo-buffer'.
936 `M-x makeinfo-recenter-output-buffer'
937 Redisplay the `makeinfo' shell buffer to display its most recent
940 (Note that the parallel commands for killing and recentering a TeX job
941 are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.)
943 You can specify options for `makeinfo' by setting the
944 `makeinfo-options' variable with either the `M-x edit-options' or the
945 `M-x set-variable' command, or by setting the variable in your `.emacs'
948 For example, you could write the following in your `.emacs' file:
950 (setq makeinfo-options
951 "--paragraph-indent=0 --no-split
952 --fill-column=70 --verbose")
954 For more information, see
955 *Note Editing Variable Values: (xemacs)Edit Options,
956 *Note Examining and Setting Variables: (xemacs)Examining,
957 *Note Init File: (xemacs)Init File, and
958 *Note Options for `makeinfo': makeinfo options.
961 File: texinfo.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Create an Info File
963 The `texinfo-format...' Commands
964 ================================
966 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
967 file with the `texinfo-format-region' command. This formats the
968 current region and displays the formatted text in a temporary buffer
969 called `*Info Region*'.
971 Similarly, you can format a buffer with the `texinfo-format-buffer'
972 command. This command creates a new buffer and generates the Info file
973 in it. Typing `C-x C-s' will save the Info file under the name
974 specified by the `@setfilename' line which must be near the beginning
978 ``texinfo-format-region''
979 Format the current region for Info.
982 ``texinfo-format-buffer''
983 Format the current buffer for Info.
985 The `texinfo-format-region' and `texinfo-format-buffer' commands
986 provide you with some error checking, and other functions can provide
987 you with further help in finding formatting errors. These procedures
988 are described in an appendix; see *Note Catching Mistakes::. However,
989 the `makeinfo' program is often faster and provides better error
990 checking (*note makeinfo in Emacs::).
993 File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Create an Info File
998 You can format Texinfo files for Info using `batch-texinfo-format'
999 and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
1000 including a shell inside of Emacs. (*Note Command Line Switches and
1001 Arguments: (xemacs)Command Switches.)
1003 Here is a shell command to format all the files that end in
1004 `.texinfo' in the current directory:
1006 emacs -batch -funcall batch-texinfo-format *.texinfo
1008 Emacs processes all the files listed on the command line, even if an
1009 error occurs while attempting to format some of them.
1011 Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it
1012 is not interactive. It kills the Batch mode Emacs on completion.
1014 `batch-texinfo-format' is convenient if you lack `makeinfo' and want
1015 to format several Texinfo files at once. When you use Batch mode, you
1016 create a new Emacs process. This frees your current Emacs, so you can
1017 continue working in it. (When you run `texinfo-format-region' or
1018 `texinfo-format-buffer', you cannot use that Emacs for anything else
1019 until the command finishes.)
1022 File: texinfo.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Create an Info File
1024 Tag Files and Split Files
1025 =========================
1027 If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
1028 automatically creates a tag table for its Info file; `makeinfo' always
1029 creates a tag table. With a "tag table", Info can jump to new nodes
1030 more quickly than it can otherwise.
1032 In addition, if the Texinfo file contains more than about 70,000
1033 bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
1034 into shorter "indirect" subfiles of about 50,000 bytes each. Big files
1035 are split into smaller files so that Emacs does not need to make a
1036 large buffer to hold the whole of a large Info file; instead, Emacs
1037 allocates just enough memory for the small, split off file that is
1038 needed at the time. This way, Emacs avoids wasting memory when you run
1039 Info. (Before splitting was implemented, Info files were always kept
1040 short and "include files" were designed as a way to create a single,
1041 large printed manual out of the smaller Info files. *Note Include
1042 Files::, for more information. Include files are still used for very
1043 large documents, such as `The XEmacs Lisp Reference Manual', in which
1044 each chapter is a separate file.)
1046 When a file is split, Info itself makes use of a shortened version of
1047 the original file that contains just the tag table and references to
1048 the files that were split off. The split off files are called
1051 The split off files have names that are created by appending `-1',
1052 `-2', `-3' and so on to the file name specified by the `@setfilename'
1053 command. The shortened version of the original file continues to have
1054 the name specified by `@setfilename'.
1056 At one stage in writing this document, for example, the Info file was
1057 saved as `test-texinfo' and that file looked like this:
1059 Info file: test-texinfo, -*-Text-*-
1060 produced by texinfo-format-buffer
1061 from file: new-texinfo-manual.texinfo
1066 test-texinfo-2: 50422
1067 test-texinfo-3: 101300
1072 Node: info file^?1271
1073 Node: printed manual^?4853
1074 Node: conventions^?6855
1077 (But `test-texinfo' had far more nodes than are shown here.) Each of
1078 the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
1079 `test-texinfo-3', is listed in this file after the line that says
1080 `Indirect:'. The tag table is listed after the line that says `Tag
1083 In the list of indirect files, the number following the file name
1084 records the cumulative number of bytes in the preceding indirect files,
1085 not counting the file list itself, the tag table, or the permissions
1086 text in each file. In the tag table, the number following the node name
1087 records the location of the beginning of the node, in bytes from the
1090 If you are using `texinfo-format-buffer' to create Info files, you
1091 may want to run the `Info-validate' command. (The `makeinfo' command
1092 does such a good job on its own, you do not need `Info-validate'.)
1093 However, you cannot run the `M-x Info-validate' node-checking command
1094 on indirect files. For information on how to prevent files from being
1095 split and how to validate the structure of the nodes, see *Note Using
1099 File: texinfo.info, Node: Install an Info File, Next: Command List, Prev: Create an Info File, Up: Top
1101 Installing an Info File
1102 ***********************
1104 Info files are usually kept in the `info' directory. You can read
1105 Info files using the standalone Info program or the Info reader built
1106 into Emacs. (*note info: (info)Top, for an introduction to Info.)
1110 * Directory file:: The top level menu for all Info files.
1111 * New Info File:: Listing a new info file.
1112 * Other Info Directories:: How to specify Info files that are
1113 located in other directories.
1114 * Installing Dir Entries:: How to specify what menu entry to add
1115 to the Info directory.
1116 * Invoking install-info:: `install-info' options.
1119 File: texinfo.info, Node: Directory file, Next: New Info File, Prev: Install an Info File, Up: Install an Info File
1124 For Info to work, the `info' directory must contain a file that
1125 serves as a top level directory for the Info system. By convention,
1126 this file is called `dir'. (You can find the location of this file
1127 within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
1128 to see the pathname to the `info' directory.)
1130 The `dir' file is itself an Info file. It contains the top level
1131 menu for all the Info files in the system. The menu looks like this:
1135 * Info: (info). Documentation browsing system.
1136 * Emacs: (emacs). The extensible, self-documenting
1138 * Texinfo: (texinfo). With one source file, make
1139 either a printed manual using
1140 TeX or an Info file.
1143 Each of these menu entries points to the `Top' node of the Info file
1144 that is named in parentheses. (The menu entry does not need to specify
1145 the `Top' node, since Info goes to the `Top' node if no node name is
1146 mentioned. *Note Nodes in Other Info Files: Other Info Files.)
1148 Thus, the `Info' entry points to the `Top' node of the `info' file
1149 and the `Emacs' entry points to the `Top' node of the `emacs' file.
1151 In each of the Info files, the `Up' pointer of the `Top' node refers
1152 back to the `dir' file. For example, the line for the `Top' node of
1153 the Emacs manual looks like this in Info:
1155 File: emacs Node: Top, Up: (DIR), Next: Distrib
1157 (Note that in this case, the `dir' file name is written in upper case
1158 letters--it can be written in either upper or lower case. Info has a
1159 feature that it will change the case of the file name to lower case if
1160 it cannot find the name as written.)
1163 File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory file, Up: Install an Info File
1165 Listing a New Info File
1166 =======================
1168 To add a new Info file to your system, you must write a menu entry to
1169 add to the menu in the `dir' file in the `info' directory. For
1170 example, if you were adding documentation for GDB, you would write the
1171 following new entry:
1173 * GDB: (gdb). The source-level C debugger.
1175 The first part of the menu entry is the menu entry name, followed by a
1176 colon. The second part is the name of the Info file, in parentheses,
1177 followed by a period. The third part is the description.
1179 The name of an Info file often has a `.info' extension. Thus, the
1180 Info file for GDB might be called either `gdb' or `gdb.info'. The Info
1181 reader programs automatically try the file name both with and without
1182 `.info'; so it is better to avoid clutter and not to write `.info'
1183 explicitly in the menu entry. For example, the GDB menu entry should
1184 use just `gdb' for the file name, not `gdb.info'.
1187 File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Install an Info File
1189 Info Files in Other Directories
1190 ===============================
1192 If an Info file is not in the `info' directory, there are three ways
1193 to specify its location:
1195 * Write the pathname in the `dir' file as the second part of the
1198 * If you are using Emacs, list the name of the file in a second `dir'
1199 file, in its directory; and then add the name of that directory to
1200 the `Info-directory-list' variable in your personal or site
1201 initialization file.
1203 This tells Emacs where to look for `dir' files. Emacs merges the
1204 files named `dir' from each of the listed directories. (In Emacs
1205 version 18, you can set the `Info-directory' variable to the name
1206 of only one directory.)
1208 * Specify the Info directory name in the `INFOPATH' environment
1209 variable in your `.profile' or `.cshrc' initialization file.
1210 (Only you and others who set this environment variable will be
1211 able to find Info files whose location is specified this way.)
1213 For example, to reach a test file in the `/home/bob/manuals'
1214 directory, you could add an entry like this to the menu in the `dir'
1217 * Test: (/home/bob/manuals/info-test). Bob's own test file.
1219 In this case, the absolute file name of the `info-test' file is written
1220 as the second part of the menu entry.
1222 Alternatively, you could write the following in your `.emacs' file:
1224 (setq Info-directory-list
1225 '("/home/bob/manuals"
1228 This tells Emacs to merge the `dir' file from the `/home/bob/manuals'
1229 directory with the `dir' file from the `/usr/local/info' directory.
1230 Info will list the `/home/bob/manuals/info-test' file as a menu entry
1231 in the `/home/bob/manuals/dir' file.
1233 Finally, you can tell Info where to look by setting the `INFOPATH'
1234 environment variable in your `.cshrc' or `.profile' file. If you use a
1235 Bourne-compatible shell such as `sh' or `bash' for your shell command
1236 interpreter, you set the `INFOPATH' environment variable in the
1237 `.profile' initialization file; but if you use `csh' or `tcsh', you
1238 must set the variable in the `.cshrc' initialization file. The two
1239 types of shells use different syntax.
1241 * In a `.cshrc' file, you could set the `INFOPATH' variable as
1244 setenv INFOPATH .:~/manuals:/usr/local/emacs/info
1246 * In a `.profile' file, you would achieve the same effect by writing:
1248 INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
1251 The `.' indicates the current directory as usual. Emacs uses the
1252 `INFOPATH' environment variable to initialize the value of Emacs's own
1253 `Info-directory-list' variable.
1255 However you set `INFOPATH', if its last character is a colon, this is
1256 replaced by the default (compiled-in) path. This gives you a way to
1257 augment the default path with new directories without having to list all
1258 the standard places. For example (using `sh' syntax:
1260 INFOPATH=/local/info:
1263 will search `/local/info' first, then the standard directories.
1264 Leading or doubled colons are not treated specially.