This is Info file texinfo.info, produced by Makeinfo version 1.67 from the input file /ade-src/fsf/texinfo/texinfo.texi. index (arbitrarily chosen to be the concept index). INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Updating info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation. * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files. END-INFO-DIR-ENTRY This file documents Texinfo, a documentation system that can produce both on-line information and a printed manual from a single source file. Copyright (C) 1988, 90, 91, 92, 93, 95, 1996 Free Software Foundation, Inc. This is the second edition of the Texinfo documentation, and is consistent with version 2 of `texinfo.tex'. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  File: texinfo.info, Node: Def Cmd Template, Next: Optional Arguments, Prev: Definition Commands, Up: Definition Commands The Template for a Definition ============================= The `@deffn' command is used for definitions of entities that resemble functions. To write a definition using the `@deffn' command, write the `@deffn' command at the beginning of a line and follow it on the same line by the category of the entity, the name of the entity itself, and its arguments (if any). Then write the body of the definition on succeeding lines. (You may embed examples in the body.) Finally, end the definition with an `@end deffn' command written on a line of its own. (The other definition commands follow the same format.) The template for a definition looks like this: @deffn CATEGORY NAME ARGUMENTS... BODY-OF-DEFINITION @end deffn For example, @deffn Command forward-word count This command moves point forward @var{count} words (or backward if @var{count} is negative). ... @end deffn produces - Command: forward-word COUNT This function moves point forward COUNT words (or backward if COUNT is negative). ... Capitalize the category name like a title. If the name of the category contains spaces, as in the phrase `Interactive Command', write braces around it. For example: @deffn {Interactive Command} isearch-forward ... @end deffn Otherwise, the second word will be mistaken for the name of the entity. Some of the definition commands are more general than others. The `@deffn' command, for example, is the general definition command for functions and the like--for entities that may take arguments. When you use this command, you specify the category to which the entity belongs. The `@deffn' command possesses three predefined, specialized variations, `@defun', `@defmac', and `@defspec', that specify the category for you: "Function", "Macro", and "Special Form" respectively. The `@defvr' command also is accompanied by several predefined, specialized variations for describing particular kinds of variables. The template for a specialized definition, such as `@defun', is similar to the template for a generalized definition, except that you do not need to specify the category: @defun NAME ARGUMENTS... BODY-OF-DEFINITION @end defun Thus, @defun buffer-end flag This function returns @code{(point-min)} if @var{flag} is less than 1, @code{(point-max)} otherwise. ... @end defun produces - Function: buffer-end FLAG This function returns `(point-min)' if FLAG is less than 1, `(point-max)' otherwise. ... *Note Sample Function Definition: Sample Function Definition, for a more detailed example of a function definition, including the use of `@example' inside the definition. The other specialized commands work like `@defun'.  File: texinfo.info, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Template, Up: Definition Commands Optional and Repeated Arguments =============================== Some entities take optional or repeated arguments, which may be specified by a distinctive glyph that uses square brackets and ellipses. For example, a special form often breaks its argument list into separate arguments in more complicated ways than a straightforward function. An argument enclosed within square brackets is optional. Thus, [OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument followed by an ellipsis is optional and may be repeated more than once. Thus, REPEATED-ARGS... stands for zero or more arguments. Parentheses are used when several arguments are grouped into additional levels of list structure in Lisp. Here is the `@defspec' line of an example of an imaginary special form: - Special Form: foobar (VAR [FROM TO [INC]]) BODY... In this example, the arguments FROM and TO are optional, but must both be present or both absent. If they are present, INC may optionally be specified as well. These arguments are grouped with the argument VAR into a list, to distinguish them from BODY, which includes all remaining elements of the form. In a Texinfo source file, this `@defspec' line is written like this (except it would not be split over two lines, as it is in this example). @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} The function is listed in the Command and Variable Index under `foobar'.  File: texinfo.info, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands Two or More `First' Lines ========================= To create two or more `first' or header lines for a definition, follow the first `@deffn' line by a line beginning with `@deffnx'. The `@deffnx' command works exactly like `@deffn' except that it does not generate extra vertical white space between it and the preceding line. For example, @deffn {Interactive Command} isearch-forward @deffnx {Interactive Command} isearch-backward These two search commands are similar except ... @end deffn produces - Interactive Command: isearch-forward - Interactive Command: isearch-backward These two search commands are similar except ... Each of the other definition commands has an `x' form: `@defunx', `@defvrx', `@deftypefunx', etc. The `x' forms work just like `@itemx'; see *Note `@itemx': itemx..  File: texinfo.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands The Definition Commands ======================= Texinfo provides more than a dozen definition commands, all of which are described in this section. The definition commands automatically enter the name of the entity in the appropriate index: for example, `@deffn', `@defun', and `@defmac' enter function names in the index of functions; `@defvr' and `@defvar' enter variable names in the index of variables. Although the examples that follow mostly illustrate Lisp, the commands can be used for other programming languages. * Menu: * Functions Commands:: Commands for functions and similar entities. * Variables Commands:: Commands for variables and similar entities. * Typed Functions:: Commands for functions in typed languages. * Typed Variables:: Commands for variables in typed languages. * Abstract Objects:: Commands for object-oriented programming. * Data Types:: The definition command for data types.  File: texinfo.info, Node: Functions Commands, Next: Variables Commands, Prev: Def Cmds in Detail, Up: Def Cmds in Detail Functions and Similar Entities ------------------------------ This section describes the commands for describing functions and similar entities: `@deffn CATEGORY NAME ARGUMENTS...' The `@deffn' command is the general definition command for functions, interactive commands, and similar entities that may take arguments. You must choose a term to describe the category of entity being defined; for example, "Function" could be used if the entity is a function. The `@deffn' command is written at the beginning of a line and is followed on the same line by the category of entity being described, the name of this particular entity, and its arguments, if any. Terminate the definition with `@end deffn' on a line of its own. For example, here is a definition: @deffn Command forward-char nchars Move point forward @var{nchars} characters. @end deffn This shows a rather terse definition for a "command" named `forward-char' with one argument, NCHARS. `@deffn' prints argument names such as NCHARS in italics or upper case, as if `@var' had been used, because we think of these names as metasyntactic variables--they stand for the actual argument values. Within the text of the description, write an argument name explicitly with `@var' to refer to the value of the argument. In the example above, we used `@var{nchars}' in this way. The template for `@deffn' is: @deffn CATEGORY NAME ARGUMENTS... BODY-OF-DEFINITION @end deffn `@defun NAME ARGUMENTS...' The `@defun' command is the definition command for functions. `@defun' is equivalent to `@deffn Function ...'. For example, @defun set symbol new-value Change the value of the symbol @var{symbol} to @var{new-value}. @end defun shows a rather terse definition for a function `set' whose arguments are SYMBOL and NEW-VALUE. The argument names on the `@defun' line automatically appear in italics or upper case as if they were enclosed in `@var'. Terminate the definition with `@end defun' on a line of its own. The template is: @defun FUNCTION-NAME ARGUMENTS... BODY-OF-DEFINITION @end defun `@defun' creates an entry in the index of functions. `@defmac NAME ARGUMENTS...' The `@defmac' command is the definition command for macros. `@defmac' is equivalent to `@deffn Macro ...' and works like `@defun'. `@defspec NAME ARGUMENTS...' The `@defspec' command is the definition command for special forms. (In Lisp, a special form is an entity much like a function.) `@defspec' is equivalent to `@deffn {Special Form} ...' and works like `@defun'.  File: texinfo.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail Variables and Similar Entities ------------------------------ Here are the commands for defining variables and similar entities: `@defvr CATEGORY NAME' The `@defvr' command is a general definition command for something like a variable--an entity that records a value. You must choose a term to describe the category of entity being defined; for example, "Variable" could be used if the entity is a variable. Write the `@defvr' command at the beginning of a line and followed it on the same line by the category of the entity and the name of the entity. Capitalize the category name like a title. If the name of the category contains spaces, as in the name `User Option', write braces around it. Otherwise, the second word will be mistaken for the name of the entity, for example: @defvr {User Option} fill-column This buffer-local variable specifies the maximum width of filled lines. ... @end defvr Terminate the definition with `@end defvr' on a line of its own. The template is: @defvr CATEGORY NAME BODY-OF-DEFINITION @end defvr `@defvr' creates an entry in the index of variables for NAME. `@defvar NAME' The `@defvar' command is the definition command for variables. `@defvar' is equivalent to `@defvr Variable ...'. For example: @defvar kill-ring ... @end defvar The template is: @defvar NAME BODY-OF-DEFINITION @end defvar `@defvar' creates an entry in the index of variables for NAME. `@defopt NAME' The `@defopt' command is the definition command for user options. `@defopt' is equivalent to `@defvr {User Option} ...' and works like `@defvar'.  File: texinfo.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail Functions in Typed Languages ---------------------------- The `@deftypefn' command and its variations are for describing functions in C or any other language in which you must declare types of variables and functions. `@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...' The `@deftypefn' command is the general definition command for functions and similar entities that may take arguments and that are typed. The `@deftypefn' command is written at the beginning of a line and is followed on the same line by the category of entity being described, the type of the returned value, the name of this particular entity, and its arguments, if any. For example, @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) ... @end deftypefn (where the text before the "...", shown above as two lines, would actually be a single line in a real Texinfo file) produces the following in Info: -- Library Function: int foobar (int FOO, float BAR) ... This means that `foobar' is a "library function" that returns an `int', and its arguments are FOO (an `int') and BAR (a `float'). The argument names that you write in `@deftypefn' are not subject to an implicit `@var'--since the actual names of the arguments in `@deftypefn' are typically scattered among data type names and keywords, Texinfo cannot find them without help. Instead, you must write `@var' explicitly around the argument names. In the example above, the argument names are `foo' and `bar'. The template for `@deftypefn' is: @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ... BODY-OF-DESCRIPTION @end deftypefn Note that if the CATEGORY or DATA TYPE is more than one word then it must be enclosed in braces to make it a single argument. If you are describing a procedure in a language that has packages, such as Ada, you might consider using `@deftypefn' in a manner somewhat contrary to the convention described in the preceding paragraphs. For example: @deftypefn stacks private push (@var{s}:in out stack; @var{n}:in integer) ... @end deftypefn (The `@deftypefn' arguments are shown split into three lines, but would be a single line in a real Texinfo file.) In this instance, the procedure is classified as belonging to the package `stacks' rather than classified as a `procedure' and its data type is described as `private'. (The name of the procedure is `push', and its arguments are S and N.) `@deftypefn' creates an entry in the index of functions for NAME. `@deftypefun DATA-TYPE NAME ARGUMENTS...' The `@deftypefun' command is the specialized definition command for functions in typed languages. The command is equivalent to `@deftypefn Function ...'. Thus, @deftypefun int foobar (int @var{foo}, float @var{bar}) ... @end deftypefun produces the following in Info: -- Function: int foobar (int FOO, float BAR) ... The template is: @deftypefun TYPE NAME ARGUMENTS... BODY-OF-DESCRIPTION @end deftypefun `@deftypefun' creates an entry in the index of functions for NAME.  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 fubar ... @end deftypevar produces the following in Info: -- Variable: int fubar ... 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: 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.info, 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.info, Node: Footnote Commands, Next: Footnote Styles, Prev: Footnotes, 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.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands (1) Here is the sample footnote.  File: texinfo.info, 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.info, Node: Conditionals, Next: Macros, 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 HTML, 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.info, 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. Likewise for `@ifhtml' and `@end ifhtml', which specify text to appear only in HTML output. 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.info, 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 plain TeX 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 plain TeX will not work, as they are overridden by features of Texinfo. You can enter plain TeX 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 plain TeX: @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.info, 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.info, 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.info, 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.info, 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.info, Node: Macros, Next: Format/Print Hardcopy, Prev: Conditionals, Up: Top Macros: Defining New Texinfo Commands ************************************* A Texinfo "macro" allows you to define a new Texinfo command as any sequence of text and/or existing commands (including other macros). The macro can have any number of "parameters"--text you supply each time you use the macro. (This has nothing to do with the `@defmac' command, which is for documenting macros in the subject of the manual; *note Def Cmd Template::..) * Menu: * Defining Macros:: Both defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it.  File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Prev: Macros, Up: Macros Defining Macros =============== You use the Texinfo `@macro' command to define a macro. For example: @macro MACRO-NAME{PARAM1, PARAM2, ...} TEXT ... \PARAM1\ ... @end macro The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied when the macro is subsequently used in the document (see the next section). If a macro needs no parameters, you can define it either with an empty list (`@macro foo {}') or with no braces at all (`@macro foo'). The definition or "body" of the macro can contain any Texinfo commands, including previously-defined macros. (It is not possible to have mutually recursive Texinfo macros.) In the body, instances of a parameter name surrounded by backslashes, as in `\PARAM1\' in the example above, are replaced by the corresponding argument from the macro invocation. You can undefine a macro FOO with `@unmacro FOO'. It is not an error to undefine a macro that is already undefined. For example: @unmacro foo  File: texinfo.info, Node: Invoking Macros, Prev: Defining Macros, Up: Macros Invoking Macros =============== After a macro is defined (see the previous section), you can use ("invoke") it in your document like this: @MACRO-NAME {ARG1, ARG2, ...} and the result will be just as if you typed the body of MACRO-NAME at that spot. For example: @macro foo {p, q} Together: \p\ & \q\. @end macro @foo{a, b} produces: Together: a & b. Thus, the arguments and parameters are separated by commas and delimited by braces; any whitespace after (but not before) a comma is ignored. To insert a comma, brace, or backslash in an argument, prepend a backslash, as in @MACRO-NAME {\\\{\}\,} which will pass the (almost certainly error-producing) argument `\{},' to MACRO-NAME. If the macro is defined to take a single argument, and is invoked without any braces, the entire rest of the line after the macro name is supplied as the argument. For example: @macro bar {p} Twice: \p\, \p\. @end macro @bar aah produces: Twice: aah, aah.  File: texinfo.info, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Macros, 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.info, 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::..