This is Info file texinfo.info, produced by Makeinfo-1.43 from the input file texinfo2.texi. This file documents Texinfo, a documentation system that uses a single source file to produce both on-line information and a printed manual. This is edition 2.14 of the Texinfo documentation, 14 February 1992, for Texinfo version 2. Copyright (C) 1988, 1990, 1991, 1992 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 Foundation.  File: texinfo.info, Node: Typed Variables, Next: Abstract Objects, Prev: Typed Functions, Up: Def Cmds in Detail Variables in Typed Languages ---------------------------- Variables in typed languages are handled in a manner similar to functions in typed languages. *Note Typed Functions::. The general definition command `@deftypevr' corresponds to `@deftypefn' and the specialized definition command `@deftypevar' corresponds to `@deftypefun'. `@deftypevr CATEGORY DATA-TYPE NAME' The `@deftypevr' command is the general definition command for something like a variable in a typed language--an entity that records a value. You must choose a term to describe the category of the entity being defined; for example, "Variable" could be used if the entity is a variable. The `@deftypevr' command is written at the beginning of a line and is followed on the same line by the category of the entity being described, the data type, and the name of this particular entity. For example: @deftypevr {Global Flag} int enable ... @end deftypevr produces the following in Info: -- Global Flag: int enable ... The template is: @deftypevr CATEGORY DATA-TYPE NAME BODY-OF-DESCRIPTION @end deftypevr `@deftypevr' creates an entry in the index of variables for NAME. `@deftypevar DATA-TYPE NAME' The `@deftypevar' command is the specialized definition command for variables in typed languages. `@deftypevar' is equivalent to `@deftypevr Variable ...'. For example, @deftypevar int foobar ... @end deftypevar produces the following in Info: -- Variable: int foobar ... The template is: @deftypevar DATA-TYPE NAME BODY-OF-DESCRIPTION @end deftypevar `@deftypevar' creates an entry in the index of variables for NAME.  File: texinfo.info, 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.info, 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.info, 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.info, 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.info, Node: Footnotes, Next: Indices, Prev: Definition Commands, Up: Top Footnotes ********* A "footnote" is for a reference that documents or elucidates the primary text.(1) 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(2); in the Texinfo source, it looks like this: ...a sample footnote @footnote{Here is the sample footnote.}; in the Texinfo source... In a printed manual or book, the reference mark for a footnote is a small, superscripted number; the text of the footnote is written 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)'. Info has two footnote styles, which determine where the text of the footnote is located: * In the "end" of 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" 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 and you use it to reach the footnote node. The name of the footnotes' node 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 will chose a default style. This chapter contains two footnotes. ---------- 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. (2) Here is the sample footnote.  File: texinfo.info, Node: Indices, Next: Breaks, Prev: Footnotes, Up: Top Creating Indices **************** Using Texinfo, you can generate indices without having to sort and collate entries manually. In an index, the entries are listed in alphabetical order, together with information on how to find the discussion of each entry. In a printed manual, this information consists of page numbers. In an Info file, this information is a menu item leading to the first node referenced. Texinfo provides several predefined kinds of index: an index for functions, an index for variables, an index for concepts, and so on. You can combine indices or use them for other than their canonical purpose. If you wish, you can define your own indices. * Menu: * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds of entry. * Indexing Commands:: How to make an index entry. * Combining Indices:: How to combine indices. * New Indices:: How to define your own indices.  File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: Indices, Up: Indices Making Index Entries ==================== When you are making index entries, it is good practice to think of the different ways people may look for something. Different people *do not* think of the same words when they look something up. A helpful index will have items indexed under all the different words that people may use. For example, someone might think it obvious that the two-letter names for indices should be listed under "Indices, two-letter names", since the word "Index" is the general concept. But another reader may remember the specific concept of two-letter names and search for the entry listed as "Two letter names for indices". A good index will have both entries and will help both kinds of user. Like typesetting, the construction of an index is a highly skilled, professional art, the subtleties of which are not appreciated until you have to do it yourself. *Note Printing an Index and Generating Index Menus: Printing Indices & Menus, for information about printing an index at the end of a book or creating an index menu in an Info file.  File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices Predefined Indices ================== Texinfo provides six predefined indices: * A "concept index" listing concepts that are discussed. * A "function index" listing functions (such as, entry points of libraries). * A "variables index" listing variables (such as, global variables of libraries). * A "keystroke index" listing keyboard commands. * A "program index" listing names of programs. * A "data type index" listing data types (such as, structures defined in header files). Not every manual needs all of these. This manual has two indices: a concept index and an @-command index (that is actually the function index but is called a command index in the chapter heading). Two or more indices can be combined into one using the `@synindex' or `@syncodeindex' commands. *Note Combining Indices::.  File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices Defining the Entries of an Index ================================ The data to make an index comes from many individual indexing commands scattered throughout the Texinfo source file. Each command says to add one entry to a particular index; after processing, it will give the current page number or node name as the reference. An index entry consists of an indexing command at the beginning of a line followed, on the rest of the line, by the entry. For example, this section begins with the following five entries for the concept index: @cindex Defining indexing entries @cindex Index entries @cindex Entries for an index @cindex Specifying index entries @cindex Creating index entries Each predefined index has its own indexing command--`@cindex' for the concept index, `@findex' for the function index, and so on. The usual convention is to capitalize the first word of each index entry, unless that word is the name of a function, variable, or other such entity that should not be capitalized. Thus, if you are documenting Emacs Lisp, your concept index entries are usually capitalized, but not your function index entries. However, if your concept index entries are consistently short (one or two words each) it may look better for each regular entry to start with a lower case letter. Which ever convention you adapt, please be consistent! By default, entries for a concept index are printed in a small roman font and entries for the other indices are printed in a small `@code' font. You may change the way part of an entry is printed with the usual Texinfo commands, such as `@file' for file names and `@emph' for emphasis (*note Marking Text::.). The six indexing commands for predefined indices are: `@cindex CONCEPT' Make an entry in the concept index for CONCEPT. `@findex FUNCTION' Make an entry in the function index for FUNCTION. `@vindex VARIABLE' Make an entry in the variable index for VARIABLE. `@kindex KEY' Make an entry in the key index for KEY. `@pindex PROGRAM' Make an entry in the program index for PROGRAM. `@tindex DATA TYPE' Make an entry in the data type index for DATA TYPE. *Caution:* Do not use a colon in an index entry. In Info, a colon separates the menu item name from the node name. An extra colon confuses Info. *Note Writing a Menu Item: Menu Item, for more information about the structure of a menu entry. If the same name is indexed on several pages, all the pages are listed in the printed manual's index. However, *only* the *first* node referenced will appear in the index of an Info file. This means that it is best to write indices in which each entry will refer to only one place in the Texinfo file. Fortunately, this constraint is a feature rather than a loss since it means that the index will be easy to use. Otherwise, it can be easy to create an index which has many pages listed for an entry and you don't know which one you need. If you have two entries for one topic, change the topics slightly, or qualify them to indicate the difference. You are not actually required to use the predefined indices for their canonical purposes. For example, suppose you wish to index some C preprocessor macros. You could put them in the function index along with actual functions, just by writing `@findex' commands for them; then, when you print the "function index" as an unnumbered chapter, you could give it the title `Function and Macro Index' and all will be consistent for the reader. Or you could put the macros in with the data types by writing `@tindex' commands for them, and give that index a suitable title so the reader will understand. (*Note Printing Indices & Menus::.)  File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices Combining Indices ================= Sometimes you will want to combine two disparate indices such as functions and concepts, perhaps because you have few enough of one of them that a separate index for them would look silly. You could put functions into the concept index by writing `@cindex' commands for them instead of `@findex' commands, and produce a consistent manual by printing the concept index with the title `Function and Concept Index' and not printing the `Function Index' at all; but this is not a robust procedure. It works only if your document is never included in part of or together with another document that is designed to have a separate function index; if your document were to be included with such a document, the functions from your document and those from the other would not end up together. Also, to make your function names appear in the right font in the concept index, you would have to enclose every one of them between `@code' and `@end code'. What you should do instead when you want functions and concepts in one index is to index the functions with `@findex' as they should be, but use the `@syncodeindex' command to redirect these `@findex' commands to the concept index. The `@syncodeindex' command takes two arguments: the name of an index to redirect, and the name of an index to redirect it to: @syncodeindex FROM TO For this purpose, the indices are given two-letter names: `cp' the concept index `vr' the variable index `fn' the function index `ky' the key index `pg' the program index `tp' the data type index Write an `@syncodeindex' command before or shortly after the end of header line at the beginning of a Texinfo file. For example, to merge a function index with a concept index, write the following: @syncodeindex fn cp This will cause all entries designated for the function index to go to the concept index instead. The `@syncodeindex' command puts all the entries from the redirected index into the `@code' font, overriding whatever default font is used by the index to which the entries are redirected. This way, if you redirect function names from a function index into a concept index, all the function names are printed the `@code' font as you would expect. The `@synindex' command is nearly the same as the `@syncodeindex' command, except that it does not put the redirected index into the `@code' font, but puts it in the roman font. *Note Printing an Index and Generating Index Menus: Printing Indices & Menus, for information about printing an index at the end of a book or creating an index menu in an Info file.  File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices Defining New Indices ==================== In addition to the predefined indices, you may use the `@defindex' and `@defcodeindex' commands to define new indices. These commands create new indexing @-commands with which you mark index entries. The `@defindex 'command is used like this: @defindex NAME The name of an index should be a two letter word, such as `au'. For example, @defindex au This defines a new index, called the `au' index. At the same time, it creates a new indexing command, `@auindex', that you can use to make index entries. Use the new indexing command just as you would use a predefined indexing command. For example, here is a section heading followed by a concept index entry and two `au' index entries. @section Cognitive Semantics @cindex kinesthetic image schemas @auindex Johnson, Mark @auindex Lakoff, George (Evidently, `au' serves here as an abbreviation for "author".) Texinfo constructs the new indexing command by concatenating the name of the index with `index'; thus, defining an `au' index leads to the automatic creation of an `@auindex' command. Use the `@printindex' command to print the index, as you do with the predefined indices. For example, @node Author Index, Subject Index, , Top @unnumbered Author Index @printindex au The `@defcodeindex' is like the `@defindex' command, except that in the printed output, it prints entries in an `@code' font, like the `@findex' command, rather than in a roman font, like the `@cindex' command. You should define new indices within or right after the end-of-header line of a Texinfo file, before any `@synindex' or `@syncodeindex' commands (*note Header::.).  File: texinfo.info, Node: Breaks, Next: Conditionals, Prev: Indices, Up: Top Making and Preventing Breaks **************************** Usually, a Texinfo file is processed both by TeX and by one of the Info formatting commands. Sometimes line, paragraph, or page breaks occur in the `wrong' place in one or other form of output. You must ensure that text looks right both in the printed manual and in the Info file. For example, in a printed manual, page breaks may occur awkwardly in the middle of an example; to prevent this, you can hold text together using a grouping command that keeps the text from being split across two pages. Conversely, you may want to force a page break where none would occur normally. Fortunately, problems like these do not often arise. When they do, use the following commands. * Menu: * Break Commands:: Introducing the break commands. * Line Breaks:: How to force lines breaks. * w:: How to prevent unwanted line breaks. * sp:: How to insert blank lines. * page:: How to force the start of a new page. * group:: How to prevent unwanted page breaks. * need:: Another way to prevent unwanted page breaks.  File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks The Break Commands ================== The break commands create line and paragraph breaks: `@*' Force a line break. `@sp N' Skip N blank lines. The line-break-prevention command holds text together all on one line. `@w{TEXT}' Prevent TEXT from being split across two lines. The pagination commands apply only to printed output, since Info files do not have pages. `@page' Start a new page in the printed manual. `@group' Hold text together that must appear on one printed page. `@need MILS' Start a new printed page if not enough space on this one.  File: texinfo.info, Node: Line Breaks, Next: w, Prev: Break Commands, Up: Breaks `@*': Generate Line Breaks ========================== The `@*' command forces a line break in both the printed manual and in Info. For example, This line @* is broken @*in two places. produces This line is broken in two places. (Note that the space after the first `@*' command is faithfully carried down to the next line.) The `@*' command is often used in a file's copyright page: This is version 2.0 of the Texinfo documentation,@* and is for ... In this case, the `@*' command keeps TeX from stretching the line across the whole page in an ugly manner. Do not write braces after an `@*' command; they are not needed. Do not write an `@refill' command at the end of a paragraph containing an `@*' command; it will cause the paragraph to be refilled after the line break occurs, negating the effect of the line break.  File: texinfo.info, Node: w, Next: sp, Prev: Line Breaks, Up: Breaks `@w'{TEXT}: Prevent Line Breaks =============================== `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT. You can use the `@w' command to prevent TeX from automatically hyphenating a long name or phrase that accidentally falls near the end of a line. You can copy GNU software from @w{@file{prep.ai.mit.edu}}. produces You can copy GNU software from `prep.ai.mit.edu'. In the Texinfo file, you must write the `@w' command and its argument (all the affected text) all on one line. Do not write an `@refill' command at the end of a paragraph containing an `@w' command; it will cause the paragraph to be refilled and may thereby negate the effect of the `@w' command.  File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks `@sp' N: Insert Blank Lines =========================== A line beginning with and containing only `@sp N' generates N blank lines of space in both the printed manual and the Info file. `@sp' also forces a paragraph break. For example, @sp 2 generates two blank lines. The `@sp' command is most often used in the title page.  File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks `@page': Start a New Page ========================= A line containing only `@page' starts a new page in a printed manual. The command has no effect on Info files since they are not paginated. An `@page' command is often used in the title section of a Texinfo file to start the copyright page.  File: texinfo.info, Node: group, Next: need, Prev: page, Up: Breaks `@group': Prevent Page Breaks ============================= The `@group' command (on a line by itself) is used inside an `@example' or similar construct to begin an unsplittable vertical group, which will appear entirely on one page in the printed output. The group is terminated by a line containing only `@end group'. These two lines produce no output of their own, and in the Info file output they have no effect at all. Although `@group' would make sense conceptually in a wide variety of contexts, its current implementation works reliably only within `@example' and variants, and within `@quotation', `@display', `@format', `@flushleft' and `@flushright'. (What all these commands have in common is that they turn off vertical spacing between "paragraphs".) In other contexts, `@group' can cause anomalous vertical spacing. *Note Quotations and Examples::. with the `@group' and `@end group' command inside the `@example' and `@end example' commands. The `@group' command is most often used to hold an example together on one page. In this Texinfo manual, about 100 examples contain text that is enclosed between `@group' and `@end group'. If you forget to end a group, you may get strange and unfathomable error messages when you run TeX. This is because TeX keeps trying to put the rest of the Texinfo file onto the one page and does not start to generate error messages until it has processed considerable text. It is a good rule of thumb to look for a missing `@end group' if you get incomprehensible error messages in TeX.  File: texinfo.info, Node: need, Prev: group, Up: Breaks `@need MILS': Prevent Page Breaks ================================= A line containing only `@need N' starts a new page in a printed manual if fewer than N mils (thousandths of an inch) remain on the current page. Do not use braces around the argument N. The `@need' command has no effect on Info files since they are not paginated. This paragraph is preceded by an `@need' command that tells TeX to start a new page if fewer than 300 mils (nearly one-third inch) remain on the page. It looks like this: @need 300 This paragraph is preceded by ... The `@need' command is useful for preventing orphans (single lines at the bottoms of printed pages).  File: texinfo.info, Node: Conditionals, Next: Printing Hardcopy, Prev: Breaks, 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:: Specifying text for Info or TeX. * Using Ordinary TeX Commands:: You can use any and all TeX commands. * set and clear:: Designating which text to format (for both Info and TeX).  File: texinfo.info, Node: Conditional Commands, Next: Using Ordinary TeX Commands, Prev: Conditionals, Up: Conditionals Using `@ifinfo' and `@iftex' ============================ `@ifinfo' begins text that should be ignored by TeX when it typesets the printed manual. The 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 used similarly but to delimit 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. 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. However, this text will appear only in Info. 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.info, Node: Using Ordinary TeX Commands, Next: set and clear, 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 that is seen by TeX. The TeX commands are the same as any TeX commands except that an `@' replaces the `\' used by TeX. For example, in the `@titlepage' section of a Texinfo file, the TeX command `@vskip' is used 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 overriden 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 some mathematics: @tex $\bigl(x\in A(n)\bigm|x\in B(n)\bigr)$ @end tex The output of this example will appear only in the printed manual. If you are reading this in Info, you will not see anything after this paragraph.  File: texinfo.info, Node: set and clear, Prev: Using Ordinary TeX Commands, Up: Conditionals `@set' and `@clear' =================== You can direct the Texinfo formatting commands to format or ignore parts of a Texinfo file with the `@set', `@clear' and related commands. For example, you can use this option to create one document that has two variants. To create such a document, write a Texinfo file that specifies some text for one version, some text for the other version, and some text for both versions. The Texinfo formatting commands will only affect the version you designate. Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag" can be any word. The format for the command looks like this: @set FLAG When a FLAG is set, the Texinfo formatting commands will format text between subsequent pairs of `@ifset FLAG' and `@end ifset' commands. For example, here is an extract from a Texinfo file: Unless you have good surge suppressors on your power line, you should turn off your computer before a thunderstorm. @set enough-time-before-storm @ifset enough-time-before-storm Save all your files, type @kbd{sync} to ensure that the operating system copies all data in memory to the hard disk, type @kbd{halt}, and then turn off the machine. @end ifset Pull the electric plug from the wall. In the example, the formatting commands will format the text between `@ifset enough-time-before-storm' and `@end ifset' because the `enough-time-before-storm' 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 When FLAG is cleared, then 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. Thus, if you clear the `enough-time-before-storm' flag of the preceding example with `@clear FLAG', the Texinfo formatting commands ignore the text between the `@ifset enough-time-before-storm' and `@end ifset' commands. In the formatted output, that text does not appear; you see only the line that says, "Pull the electric plug from the wall", in both printed and Info output. 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. Write each of these commands on a line of its own.  File: texinfo.info, Node: Printing Hardcopy, Next: Creating an Info File, Prev: Conditionals, Up: Top Printing Hardcopy ***************** There are three major shell commands for printing hardcopy of a Texinfo file. One is for formatting the file, the second is for sorting the index, and the third is 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. Instead of shell commands, you can use commands provided by Texinfo mode. In addition to 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. * How to Print:: How to print a hardcopy manual with shell commands. * Printing from Emacs:: How to 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:: Preparing for Use of TeX * Overfull Hboxes:: What are and what to do with overfull hboxes. * smallbook:: Printing small format books and manuals.  File: texinfo.info, Node: Use TeX, Next: How to Print, Prev: Printing Hardcopy, Up: Printing Hardcopy Use TeX ======= The typesetting program TeX is used for formatting a Texinfo file.(1) TeX is a very powerful typesetting program and, if used right, does an exceptionally good job. 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. (*Note Creating an Info File::.) ---------- Footnotes ---------- (1) If you do not have TeX, you can use the `texi2roff' program for formatting.  File: texinfo.info, Node: How to Print, Next: Printing from Emacs, Prev: Use TeX, Up: Printing Hardcopy How to Print Using Shell Commands ================================= Format the Texinfo file with the shell command `tex' followed by the name of the Texinfo file. This 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. Hence, to generate a printed index, you first need a sorted index to work from. The `texindex' command sorts indices.(1) 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.(2) 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 makes all the cross references correct as well. (The tables of contents are always correct.) You need not run `texindex' each time after you run the `tex' formatting. If you don't, 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. Rather than type the `tex' and `texindex' commands yourself, you can use `texi2dvi'. This shell script is designed to simplify the `tex'--`texindex'--`tex' sequence by figuring out whether index files and DVI files are up-to-date. It runs `texindex' and `tex' only when necessary. The syntax for `texi2dvi' is like this (where `%' is the shell prompt): % texi2dvi FILENAMES... Finally, you can print a DVI file with the DVI print command. The precise command to use depends on the 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.) ---------- Footnotes ---------- (1) The source file `texindex.c' comes as part of the standard GNU distribution and is usually installed when Emacs is installed. (2) 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.info, Node: Printing from Emacs, Next: Texinfo Mode Printing, Prev: How to Print, Up: Printing Hardcopy Printing 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 How to Print Using Shell Commands: How to Print, 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. (*Note How to Print Using Shell Commands: How to Print.) *Note Texinfo Mode Printing::, for more information about formatting and printing in Texinfo mode.