This is Info file texinfo, produced by Makeinfo-1.64 from the input file texinfo.texi. This file documents Texinfo, a documentation system that uses a single source file to produce both on-line information and a printed manual. Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995 Free Software Foundation, Inc. This is the second edition of the Texinfo documentation, and is consistent with version 2 of `texinfo.tex'. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  File: texinfo, Node: Abstract Objects, Next: Data Types, Prev: Typed Variables, Up: Def Cmds in Detail Object-Oriented Programming --------------------------- Here are the commands for formatting descriptions about abstract objects, such as are used in object-oriented programming. A class is a defined type of abstract object. An instance of a class is a particular object that has the type of the class. An instance variable is a variable that belongs to the class but for which each instance has its own value. In a definition, if the name of a class is truly a name defined in the programming system for a class, then you should write an `@code' around it. Otherwise, it is printed in the usual text font. `@defcv CATEGORY CLASS NAME' The `@defcv' command is the general definition command for variables associated with classes in object-oriented programming. The `@defcv' command is followed by three arguments: the category of thing being defined, the class to which it belongs, and its name. Thus, @defcv {Class Option} Window border-pattern ... @end defcv illustrates how you would write the first line of a definition of the `border-pattern' class option of the class `Window'. The template is @defcv CATEGORY CLASS NAME ... @end defcv `@defcv' creates an entry in the index of variables. `@defivar CLASS NAME' The `@defivar' command is the definition command for instance variables in object-oriented programming. `@defivar' is equivalent to `@defcv {Instance Variable} ...' The template is: @defivar CLASS INSTANCE-VARIABLE-NAME BODY-OF-DEFINITION @end defivar `@defivar' creates an entry in the index of variables. `@defop CATEGORY CLASS NAME ARGUMENTS...' The `@defop' command is the general definition command for entities that may resemble methods in object-oriented programming. These entities take arguments, as functions do, but are associated with particular classes of objects. For example, some systems have constructs called "wrappers" that are associated with classes as methods are, but that act more like macros than like functions. You could use `@defop Wrapper' to describe one of these. Sometimes it is useful to distinguish methods and "operations". You can think of an operation as the specification for a method. Thus, a window system might specify that all window classes have a method named `expose'; we would say that this window system defines an `expose' operation on windows in general. Typically, the operation has a name and also specifies the pattern of arguments; all methods that implement the operation must accept the same arguments, since applications that use the operation do so without knowing which method will implement it. Often it makes more sense to document operations than methods. For example, window application developers need to know about the `expose' operation, but need not be concerned with whether a given class of windows has its own method to implement this operation. To describe this operation, you would write: @defop Operation windows expose The `@defop' command is written at the beginning of a line and is followed on the same line by the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any. The template is: @defop CATEGORY CLASS NAME ARGUMENTS... BODY-OF-DEFINITION @end defop `@defop' creates an entry, such as ``expose' on `windows'', in the index of functions. `@defmethod CLASS NAME ARGUMENTS...' The `@defmethod' command is the definition command for methods in object-oriented programming. A method is a kind of function that implements an operation for a particular class of objects and its subclasses. In the Lisp Machine, methods actually were functions, but they were usually defined with `defmethod'. `@defmethod' is equivalent to `@defop Method ...'. The command is written at the beginning of a line and is followed by the name of the class of the method, the name of the method, and its arguments, if any. For example, @defmethod `bar-class' bar-method argument ... @end defmethod illustrates the definition for a method called `bar-method' of the class `bar-class'. The method takes an argument. The template is: @defmethod CLASS METHOD-NAME ARGUMENTS... BODY-OF-DEFINITION @end defmethod `@defmethod' creates an entry, such as ``bar-method' on `bar-class'', in the index of functions.  File: texinfo, Node: Data Types, Prev: Abstract Objects, Up: Def Cmds in Detail Data Types ---------- Here is the command for data types: `@deftp CATEGORY NAME ATTRIBUTES...' The `@deftp' command is the generic definition command for data types. The command is written at the beginning of a line and is followed on the same line by the category, by the name of the type (which is a word like `int' or `float'), and then by names of attributes of objects of that type. Thus, you could use this command for describing `int' or `float', in which case you could use `data type' as the category. (A data type is a category of certain objects for purposes of deciding which operations can be performed on them.) In Lisp, for example, "pair" names a particular data type, and an object of that type has two slots called the CAR and the CDR. Here is how you would write the first line of a definition of `pair'. @deftp {Data type} pair car cdr ... @end deftp The template is: @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES... BODY-OF-DEFINITION @end deftp `@deftp' creates an entry in the index of data types.  File: texinfo, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands Conventions for Writing Definitions =================================== When you write a definition using `@deffn', `@defun', or one of the other definition commands, please take care to use arguments that indicate the meaning, as with the COUNT argument to the `forward-word' function. Also, if the name of an argument contains the name of a type, such as INTEGER, take care that the argument actually is of that type.  File: texinfo, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands A Sample Function Definition ============================ A function definition uses the `@defun' and `@end defun' commands. The name of the function follows immediately after the `@defun' command and it is followed, on the same line, by the parameter list. Here is a definition from `The GNU Emacs Lisp Reference Manual'. (*Note Calling Functions: (elisp)Calling Functions.) - Function: apply FUNCTION &rest ARGUMENTS `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but with one difference: the last of ARGUMENTS is a list of arguments to give to FUNCTION, rather than a single argument. We also say that this list is "appended" to the other arguments. `apply' returns the result of calling FUNCTION. As with `funcall', FUNCTION must either be a Lisp function or a primitive function; special forms and macros do not make sense in `apply'. (setq f 'list) => list (apply f 'x 'y 'z) error--> Wrong type argument: listp, z (apply '+ 1 2 '(3 4)) => 10 (apply '+ '(1 2 3 4)) => 10 (apply 'append '((a b c) nil (x y z) nil)) => (a b c x y z) An interesting example of using `apply' is found in the description of `mapcar'. In the Texinfo source file, this example looks like this: @defun apply function &rest arguments @code{apply} calls @var{function} with @var{arguments}, just like @code{funcall} but with one difference: the last of @var{arguments} is a list of arguments to give to @var{function}, rather than a single argument. We also say that this list is @dfn{appended} to the other arguments. @code{apply} returns the result of calling @var{function}. As with @code{funcall}, @var{function} must either be a Lisp function or a primitive function; special forms and macros do not make sense in @code{apply}. @example (setq f 'list) @result{} list (apply f 'x 'y 'z) @error{} Wrong type argument: listp, z (apply '+ 1 2 '(3 4)) @result{} 10 (apply '+ '(1 2 3 4)) @result{} 10 (apply 'append '((a b c) nil (x y z) nil)) @result{} (a b c x y z) @end example An interesting example of using @code{apply} is found in the description of @code{mapcar}.@refill @end defun In this manual, this function is listed in the Command and Variable Index under `apply'. Ordinary variables and user options are described using a format like that for functions except that variables do not take arguments.  File: texinfo, Node: Footnotes, Next: Conditionals, Prev: Definition Commands, Up: Top Footnotes ********* A "footnote" is for a reference that documents or elucidates the primary text.(1) (*note Footnotes-Footnotes::) * Menu: * Footnote Commands:: How to write a footnote in Texinfo. * Footnote Styles:: Controlling how footnotes appear in Info.  File: texinfo, Node: Footnotes-Footnotes, Up: Footnotes (1) A footnote should complement or expand upon the primary text, but a reader should not need to read a footnote to understand the primary text. For a thorough discussion of footnotes, see `The Chicago Manual of Style', which is published by the University of Chicago Press.  File: texinfo, Node: Footnote Commands, Next: Footnote Styles, Up: Footnotes Footnote Commands ================= In Texinfo, footnotes are created with the `@footnote' command. This command is followed immediately by a left brace, then by the text of the footnote, and then by a terminating right brace. The template is: @footnote{TEXT} Footnotes may be of any length, but are usually short. For example, this clause is followed by a sample footnote(1) (*note Footnote Commands-Footnotes::); in the Texinfo source, it looks like this: ...a sample footnote @footnote{Here is the sample footnote.}; in the Texinfo source... *Warning:* Don't use footnotes in the argument of the `@item' command for a `@table' table. This doesn't work; because of limitations of TeX, there is no way to fix it. To avoid the problem, move the footnote into the body text of the table. In a printed manual or book, the reference mark for a footnote is a small, superscripted number; the text of the footnote appears at the bottom of the page, below a horizontal line. In Info, the reference mark for a footnote is a pair of parentheses with the footnote number between them, like this: `(1)'.  File: texinfo, Node: Footnote Commands-Footnotes, Up: Footnote Commands (1) Here is the sample footnote.  File: texinfo, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes Footnote Styles =============== Info has two footnote styles, which determine where the text of the footnote is located: * In the `End' node style, all the footnotes for a single node are placed at the end of that node. The footnotes are separated from the rest of the node by a line of dashes with the word `Footnotes' within it. Each footnote begins with an `(N)' reference mark. Here is an example of a single footnote in the end of node style: --------- Footnotes --------- (1) Here is a sample footnote. * In the `Separate' node style, all the footnotes for a single node are placed in an automatically constructed node of their own. In this style, a "footnote reference" follows each `(N)' reference mark in the body of the node. The footnote reference is actually a cross reference which you use to reach the footnote node. The name of the node containing the footnotes is constructed by appending `-Footnotes' to the name of the node that contains the footnotes. (Consequently, the footnotes' node for the `Footnotes' node is `Footnotes-Footnotes'!) The footnotes' node has an `Up' node pointer that leads back to its parent node. Here is how the first footnote in this manual looks after being formatted for Info in the separate node style: File: texinfo.info Node: Overview-Footnotes, Up: Overview (1) Note that the first syllable of "Texinfo" is pronounced like "speck", not "hex". ... A Texinfo file may be formatted into an Info file with either footnote style. Use the `@footnotestyle' command to specify an Info file's footnote style. Write this command at the beginning of a line followed by an argument, either `end' for the end node style or `separate' for the separate node style. For example, @footnotestyle end or @footnotestyle separate Write an `@footnotestyle' command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you include the `@footnotestyle' command between the start-of-header and end-of-header lines, the region formatting commands will format footnotes as specified.) If you do not specify a footnote style, the formatting commands use their default style. Currently, `texinfo-format-buffer' and `texinfo-format-region' use the `separate' style and `makeinfo' uses the `end' style. This chapter contains two footnotes.  File: texinfo, Node: Conditionals, Next: Format/Print Hardcopy, Prev: Footnotes, Up: Top Conditionally Visible Text ************************** Sometimes it is good to use different text for a printed manual and its corresponding Info file. In this case, you can use the "conditional commands" to specify which text is for the printed manual and which is for the Info file. * Menu: * Conditional Commands:: How to specify text for Info or TeX. * Using Ordinary TeX Commands:: You can use any and all TeX commands. * set clear value:: How to designate which text to format (for both Info and TeX); and how to set a flag to a string that you can insert.  File: texinfo, Node: Conditional Commands, Next: Using Ordinary TeX Commands, Prev: Conditionals, Up: Conditionals Using `@ifinfo' and `@iftex' ============================ `@ifinfo' begins segments of text that should be ignored by TeX when it typesets the printed manual. The segment of text appears only in the Info file. The `@ifinfo' command should appear on a line by itself; end the Info-only text with a line containing `@end ifinfo' by itself. At the beginning of a Texinfo file, the Info permissions are contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note Info Summary and Permissions::.) The `@iftex' and `@end iftex' commands are similar to the `@ifinfo' and `@end ifinfo' commands, except that they specify text that will appear in the printed manual but not in the Info file. For example, @iftex This text will appear only in the printed manual. @end iftex @ifinfo However, this text will appear only in Info. @end ifinfo The preceding example produces the following line: However, this text will appear only in Info. Note how you only see one of the two lines, depending on whether you are reading the Info version or the printed version of this manual. The `@titlepage' command is a special variant of `@iftex' that is used for making the title and copyright pages of the printed manual. (*Note `@titlepage': titlepage.)  File: texinfo, Node: Using Ordinary TeX Commands, Next: set clear value, Prev: Conditional Commands, Up: Conditionals Using Ordinary TeX Commands =========================== Inside a region delineated by `@iftex' and `@end iftex', you can embed some PlainTeX commands. Info will ignore these commands since they are only in that part of the file which is seen by TeX. You can write the TeX commands as you would write them in a normal TeX file, except that you must replace the `\' used by TeX with an `@'. For example, in the `@titlepage' section of a Texinfo file, you can use the TeX command `@vskip' to format the copyright page. (The `@titlepage' command causes Info to ignore the region automatically, as it does with the `@iftex' command.) However, many features of PlainTeX will not work, as they are overridden by features of Texinfo. You can enter PlainTeX completely, and use `\' in the TeX commands, by delineating a region with the `@tex' and `@end tex' commands. (The `@tex' command also causes Info to ignore the region, like the `@iftex' command.) For example, here is a mathematical expression written in PlainTeX: @tex $$ \chi^2 = \sum_{i=1}^N \left (y_i - (a + b x_i) \over \sigma_i\right)^2 $$ @end tex The output of this example will appear only in a printed manual. If you are reading this in Info, you will not see anything after this paragraph.  File: texinfo, Node: set clear value, Prev: Using Ordinary TeX Commands, Up: Conditionals `@set', `@clear', and `@value' ============================== You can direct the Texinfo formatting commands to format or ignore parts of a Texinfo file with the `@set', `@clear', `@ifset', and `@ifclear' commands. In addition, you can use the `@set FLAG' command to set the value of FLAG to a string of characters; and use `@value{FLAG}' to insert that string. You can use `@set', for example, to set a date and use `@value' to insert the date in several places in the Texinfo file. * Menu: * ifset ifclear:: Format a region if a flag is set. * value:: Replace a flag with a string. * value Example:: An easy way to update edition information.  File: texinfo, Node: ifset ifclear, Next: value, Prev: set clear value, Up: set clear value `@ifset' and `@ifclear' ----------------------- When a FLAG is set, the Texinfo formatting commands format text between subsequent pairs of `@ifset FLAG' and `@end ifset' commands. When the FLAG is cleared, the Texinfo formatting commands do *not* format the text. Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag" can be any single word. The format for the command looks like this: @set FLAG Write the conditionally formatted text between `@ifset FLAG' and `@end ifset' commands, like this: @ifset FLAG CONDITIONAL-TEXT @end ifset For example, you can create one document that has two variants, such as a manual for a `large' and `small' model: You can use this machine to dig up shrubs without hurting them. @set large @ifset large It can also dig up fully grown trees. @end ifset Remember to replant promptly ... In the example, the formatting commands will format the text between `@ifset large' and `@end ifset' because the `large' flag is set. Use the `@clear FLAG' command to turn off, or "clear", a flag. Clearing a flag is the opposite of setting a flag. The command looks like this: @clear FLAG Write the command on a line of its own. When FLAG is cleared, the Texinfo formatting commands do *not* format the text between `@ifset FLAG' and `@end ifset'; that text is ignored and does not appear in either printed or Info output. For example, if you clear the flag of the preceding example by writing an `@clear large' command after the `@set large' command (but before the conditional text), then the Texinfo formatting commands ignore the text between the `@ifset large' and `@end ifset' commands. In the formatted output, that text does not appear; in both printed and Info output, you see only the lines that say, "You can use this machine to dig up shrubs without hurting them. Remember to replant promptly ...". If a flag is cleared with an `@clear FLAG' command, then the formatting commands format text between subsequent pairs of `@ifclear' and `@end ifclear' commands. But if the flag is set with `@set FLAG', then the formatting commands do *not* format text between an `@ifclear' and an `@end ifclear' command; rather, they ignore that text. An `@ifclear' command looks like this: @ifclear FLAG In brief, the commands are: `@set FLAG' Tell the Texinfo formatting commands that FLAG is set. `@clear FLAG' Tell the Texinfo formatting commands that FLAG is cleared. `@ifset FLAG' If FLAG is set, tell the Texinfo formatting commands to format the text up to the following `@end ifset' command. If FLAG is cleared, tell the Texinfo formatting commands to ignore text up to the following `@end ifset' command. `@ifclear FLAG' If FLAG is set, tell the Texinfo formatting commands to ignore the text up to the following `@end ifclear' command. If FLAG is cleared, tell the Texinfo formatting commands to format the text up to the following `@end ifclear' command.  File: texinfo, Node: value, Next: value Example, Prev: ifset ifclear, Up: set clear value `@value' -------- You can use the `@set' command to specify a value for a flag, which is expanded by the `@value' command. The value is a string a characters. Write the `@set' command like this: @set foo This is a string. This sets the value of `foo' to "This is a string." The Texinfo formatters replace an `@value{FLAG}' command with the string to which FLAG is set. Thus, when `foo' is set as shown above, the Texinfo formatters convert @value{foo} to This is a string. You can write an `@value' command within a paragraph; but you must write an `@set' command on a line of its own. If you write the `@set' command like this: @set foo without specifying a string, the value of `foo' is an empty string. If you clear a previously set flag with an `@clear FLAG' command, a subsequent `@value{flag}' command is invalid and the string is replaced with an error message that says `{No value for "FLAG"}'. For example, if you set `foo' as follows: @set how-much very, very, very then the formatters transform It is a @value{how-much} wet day. into It is a very, very, very wet day. If you write @clear how-much then the formatters transform It is a @value{how-much} wet day. into It is a {No value for "how-much"} wet day.  File: texinfo, Node: value Example, Prev: value, Up: set clear value `@value' Example ---------------- You can use the `@value' command to limit the number of places you need to change when you record an update to a manual. Here is how it is done in `The GNU Make Manual': Set the flags: @set EDITION 0.35 Beta @set VERSION 3.63 Beta @set UPDATED 14 August 1992 @set UPDATE-MONTH August 1992 Write text for the first `@ifinfo' section, for people reading the Texinfo file: This is Edition @value{EDITION}, last updated @value{UPDATED}, of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}. Write text for the title page, for people reading the printed manual: @title GNU Make @subtitle A Program for Directing Recompilation @subtitle Edition @value{EDITION}, ... @subtitle @value{UPDATE-MONTH} (On a printed cover, a date listing the month and the year looks less fussy than a date listing the day as well as the month and year.) Write text for the Top node, for people reading the Info file: This is Edition @value{EDITION} of the @cite{GNU Make Manual}, last updated @value{UPDATED} for @code{make} Version @value{VERSION}. After you format the manual, the text in the first `@ifinfo' section looks like this: This is Edition 0.35 Beta, last updated 14 August 1992, of `The GNU Make Manual', for `make', Version 3.63 Beta. When you update the manual, change only the values of the flags; you do not need to rewrite the three sections.  File: texinfo, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Conditionals, Up: Top Format and Print Hardcopy ************************* There are three major shell commands for making a printed manual from a Texinfo file: one for converting the Texinfo file into a file that will be printed, a second for sorting indices, and a third for printing the formatted document. When you use the shell commands, you can either work directly in the operating system shell or work within a shell inside GNU Emacs. If you are using GNU Emacs, you can use commands provided by Texinfo mode instead of shell commands. In addition to the three commands to format a file, sort the indices, and print the result, Texinfo mode offers key bindings for commands to recenter the output buffer, show the print queue, and delete a job from the print queue. * Menu: * Use TeX:: Use TeX to format for hardcopy. * Format with tex/texindex:: How to format in a shell. * Format with texi2dvi:: A simpler way to use the shell. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: TeX formatting requirements summary. * Preparing for TeX:: What you need to do to use TeX. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on European A4 paper. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output.  File: texinfo, Node: Use TeX, Next: Format with tex/texindex, Prev: Format/Print Hardcopy, Up: Format/Print Hardcopy Use TeX ======= The typesetting program called TeX is used for formatting a Texinfo file. TeX is a very powerful typesetting program and, if used right, does an exceptionally good job. *Note How to Obtain TeX: Obtaining TeX, for information on how to obtain TeX. The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer' commands read the very same @-commands in the Texinfo file as does TeX, but process them differently to make an Info file; see *Note Create an Info File::.  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 needed 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 `%' is the shell 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 x 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 contain an `@settitle' command: \input texinfo @settitle NAME-OF-MANUAL The first command instructs TeX to load the macros it needs to process a Texinfo file and the second command 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 three 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 `@setfilename' for Info formatting, 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 overful 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 PlainTeX 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.