1 This is ../info/texinfo.info, produced by makeinfo version 4.6 from
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
19 This edition is for Texinfo version 3.12.
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
36 File: texinfo.info, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Template, Up: Definition Commands
38 Optional and Repeated Arguments
39 ===============================
41 Some entities take optional or repeated arguments, which may be
42 specified by a distinctive glyph that uses square brackets and
43 ellipses. For example, a special form often breaks its argument list
44 into separate arguments in more complicated ways than a straightforward
47 An argument enclosed within square brackets is optional. Thus,
48 [OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument
49 followed by an ellipsis is optional and may be repeated more than once.
50 Thus, REPEATED-ARGS... stands for zero or more arguments. Parentheses
51 are used when several arguments are grouped into additional levels of
52 list structure in Lisp.
54 Here is the `@defspec' line of an example of an imaginary special
57 - Special Form: foobar (VAR [FROM TO [INC]]) BODY...
59 In this example, the arguments FROM and TO are optional, but must both
60 be present or both absent. If they are present, INC may optionally be
61 specified as well. These arguments are grouped with the argument VAR
62 into a list, to distinguish them from BODY, which includes all
63 remaining elements of the form.
65 In a Texinfo source file, this `@defspec' line is written like this
66 (except it would not be split over two lines, as it is in this example).
68 @defspec foobar (@var{var} [@var{from} @var{to}
69 [@var{inc}]]) @var{body}@dots{}
71 The function is listed in the Command and Variable Index under `foobar'.
74 File: texinfo.info, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands
76 Two or More `First' Lines
77 =========================
79 To create two or more `first' or header lines for a definition, follow
80 the first `@deffn' line by a line beginning with `@deffnx'. The
81 `@deffnx' command works exactly like `@deffn' except that it does not
82 generate extra vertical white space between it and the preceding line.
86 @deffn {Interactive Command} isearch-forward
87 @deffnx {Interactive Command} isearch-backward
88 These two search commands are similar except ...
93 - Interactive Command: isearch-forward
94 - Interactive Command: isearch-backward
95 These two search commands are similar except ...
97 Each of the other definition commands has an `x' form: `@defunx',
98 `@defvrx', `@deftypefunx', etc.
100 The `x' forms work just like `@itemx'; see *Note `@itemx': itemx.
103 File: texinfo.info, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands
105 The Definition Commands
106 =======================
108 Texinfo provides more than a dozen definition commands, all of which
109 are described in this section.
111 The definition commands automatically enter the name of the entity in
112 the appropriate index: for example, `@deffn', `@defun', and `@defmac'
113 enter function names in the index of functions; `@defvr' and `@defvar'
114 enter variable names in the index of variables.
116 Although the examples that follow mostly illustrate Lisp, the commands
117 can be used for other programming languages.
121 * Functions Commands:: Commands for functions and similar entities.
122 * Variables Commands:: Commands for variables and similar entities.
123 * Typed Functions:: Commands for functions in typed languages.
124 * Typed Variables:: Commands for variables in typed languages.
125 * Abstract Objects:: Commands for object-oriented programming.
126 * Data Types:: The definition command for data types.
129 File: texinfo.info, Node: Functions Commands, Next: Variables Commands, Prev: Def Cmds in Detail, Up: Def Cmds in Detail
131 Functions and Similar Entities
132 ------------------------------
134 This section describes the commands for describing functions and similar
137 `@deffn CATEGORY NAME ARGUMENTS...'
138 The `@deffn' command is the general definition command for
139 functions, interactive commands, and similar entities that may take
140 arguments. You must choose a term to describe the category of
141 entity being defined; for example, "Function" could be used if the
142 entity is a function. The `@deffn' command is written at the
143 beginning of a line and is followed on the same line by the
144 category of entity being described, the name of this particular
145 entity, and its arguments, if any. Terminate the definition with
146 `@end deffn' on a line of its own.
148 For example, here is a definition:
150 @deffn Command forward-char nchars
151 Move point forward @var{nchars} characters.
154 This shows a rather terse definition for a "command" named
155 `forward-char' with one argument, NCHARS.
157 `@deffn' prints argument names such as NCHARS in italics or upper
158 case, as if `@var' had been used, because we think of these names
159 as metasyntactic variables--they stand for the actual argument
160 values. Within the text of the description, write an argument name
161 explicitly with `@var' to refer to the value of the argument. In
162 the example above, we used `@var{nchars}' in this way.
164 The template for `@deffn' is:
166 @deffn CATEGORY NAME ARGUMENTS...
170 `@defun NAME ARGUMENTS...'
171 The `@defun' command is the definition command for functions.
172 `@defun' is equivalent to `@deffn Function ...'.
176 @defun set symbol new-value
177 Change the value of the symbol @var{symbol}
181 shows a rather terse definition for a function `set' whose
182 arguments are SYMBOL and NEW-VALUE. The argument names on the
183 `@defun' line automatically appear in italics or upper case as if
184 they were enclosed in `@var'. Terminate the definition with `@end
185 defun' on a line of its own.
189 @defun FUNCTION-NAME ARGUMENTS...
193 `@defun' creates an entry in the index of functions.
195 `@defmac NAME ARGUMENTS...'
196 The `@defmac' command is the definition command for macros.
197 `@defmac' is equivalent to `@deffn Macro ...' and works like
200 `@defspec NAME ARGUMENTS...'
201 The `@defspec' command is the definition command for special
202 forms. (In Lisp, a special form is an entity much like a function,
203 *note Special Forms: (lispref)Special Forms..) `@defspec' is
204 equivalent to `@deffn {Special Form} ...' and works like `@defun'.
207 File: texinfo.info, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail
209 Variables and Similar Entities
210 ------------------------------
212 Here are the commands for defining variables and similar entities:
214 `@defvr CATEGORY NAME'
215 The `@defvr' command is a general definition command for something
216 like a variable--an entity that records a value. You must choose
217 a term to describe the category of entity being defined; for
218 example, "Variable" could be used if the entity is a variable.
219 Write the `@defvr' command at the beginning of a line and followed
220 it on the same line by the category of the entity and the name of
223 Capitalize the category name like a title. If the name of the
224 category contains spaces, as in the name "User Option", enclose it
225 in braces. Otherwise, the second word will be mistaken for the
226 name of the entity. For example,
228 @defvr {User Option} fill-column
229 This buffer-local variable specifies
230 the maximum width of filled lines.
234 Terminate the definition with `@end defvr' on a line of its own.
242 `@defvr' creates an entry in the index of variables for NAME.
245 The `@defvar' command is the definition command for variables.
246 `@defvar' is equivalent to `@defvr Variable ...'.
260 `@defvar' creates an entry in the index of variables for NAME.
263 The `@defopt' command is the definition command for "user
264 options", i.e., variables intended for users to change according to
265 taste; Emacs has many such (*note Variables: (xemacs)Variables.).
266 `@defopt' is equivalent to `@defvr {User Option} ...' and works
270 File: texinfo.info, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail
272 Functions in Typed Languages
273 ----------------------------
275 The `@deftypefn' command and its variations are for describing
276 functions in languages in which you must declare types of variables and
277 functions, such as C and C++.
279 `@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...'
280 The `@deftypefn' command is the general definition command for
281 functions and similar entities that may take arguments and that are
282 typed. The `@deftypefn' command is written at the beginning of a
283 line and is followed on the same line by the category of entity
284 being described, the type of the returned value, the name of this
285 particular entity, and its arguments, if any.
289 @deftypefn {Library Function} int foobar
290 (int @var{foo}, float @var{bar})
294 (where the text before the "...", shown above as two lines, would
295 actually be a single line in a real Texinfo file) produces the
298 -- Library Function: int foobar (int FOO, float BAR)
301 This means that `foobar' is a "library function" that returns an
302 `int', and its arguments are FOO (an `int') and BAR (a `float').
304 The argument names that you write in `@deftypefn' are not subject
305 to an implicit `@var'--since the actual names of the arguments in
306 `@deftypefn' are typically scattered among data type names and
307 keywords, Texinfo cannot find them without help. Instead, you
308 must write `@var' explicitly around the argument names. In the
309 example above, the argument names are `foo' and `bar'.
311 The template for `@deftypefn' is:
313 @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ...
317 Note that if the CATEGORY or DATA TYPE is more than one word then
318 it must be enclosed in braces to make it a single argument.
320 If you are describing a procedure in a language that has packages,
321 such as Ada, you might consider using `@deftypefn' in a manner
322 somewhat contrary to the convention described in the preceding
327 @deftypefn stacks private push
328 (@var{s}:in out stack;
333 (The `@deftypefn' arguments are shown split into three lines, but
334 would be a single line in a real Texinfo file.)
336 In this instance, the procedure is classified as belonging to the
337 package `stacks' rather than classified as a `procedure' and its
338 data type is described as `private'. (The name of the procedure
339 is `push', and its arguments are S and N.)
341 `@deftypefn' creates an entry in the index of functions for NAME.
343 `@deftypefun DATA-TYPE NAME ARGUMENTS...'
344 The `@deftypefun' command is the specialized definition command
345 for functions in typed languages. The command is equivalent to
346 `@deftypefn Function ...'.
350 @deftypefun int foobar (int @var{foo}, float @var{bar})
354 produces the following in Info:
356 -- Function: int foobar (int FOO, float BAR)
361 @deftypefun TYPE NAME ARGUMENTS...
365 `@deftypefun' creates an entry in the index of functions for NAME.
369 File: texinfo.info, Node: Typed Variables, Next: Abstract Objects, Prev: Typed Functions, Up: Def Cmds in Detail
371 Variables in Typed Languages
372 ----------------------------
374 Variables in typed languages are handled in a manner similar to
375 functions in typed languages. *Note Typed Functions::. The general
376 definition command `@deftypevr' corresponds to `@deftypefn' and the
377 specialized definition command `@deftypevar' corresponds to
380 `@deftypevr CATEGORY DATA-TYPE NAME'
381 The `@deftypevr' command is the general definition command for
382 something like a variable in a typed language--an entity that
383 records a value. You must choose a term to describe the category
384 of the entity being defined; for example, "Variable" could be used
385 if the entity is a variable.
387 The `@deftypevr' command is written at the beginning of a line and
388 is followed on the same line by the category of the entity being
389 described, the data type, and the name of this particular entity.
393 @deftypevr {Global Flag} int enable
397 produces the following in Info:
399 -- Global Flag: int enable
404 @deftypevr CATEGORY DATA-TYPE NAME
408 `@deftypevr' creates an entry in the index of variables for NAME.
410 `@deftypevar DATA-TYPE NAME'
411 The `@deftypevar' command is the specialized definition command
412 for variables in typed languages. `@deftypevar' is equivalent to
413 `@deftypevr Variable ...'.
417 @deftypevar int fubar
421 produces the following in Info:
423 -- Variable: int fubar
428 @deftypevar DATA-TYPE NAME
432 `@deftypevar' creates an entry in the index of variables for NAME.
435 File: texinfo.info, Node: Abstract Objects, Next: Data Types, Prev: Typed Variables, Up: Def Cmds in Detail
437 Object-Oriented Programming
438 ---------------------------
440 Here are the commands for formatting descriptions about abstract
441 objects, such as are used in object-oriented programming. A class is a
442 defined type of abstract object. An instance of a class is a
443 particular object that has the type of the class. An instance variable
444 is a variable that belongs to the class but for which each instance has
447 In a definition, if the name of a class is truly a name defined in the
448 programming system for a class, then you should write an `@code' around
449 it. Otherwise, it is printed in the usual text font.
451 `@defcv CATEGORY CLASS NAME'
452 The `@defcv' command is the general definition command for
453 variables associated with classes in object-oriented programming.
454 The `@defcv' command is followed by three arguments: the category
455 of thing being defined, the class to which it belongs, and its
458 @defcv {Class Option} Window border-pattern
462 illustrates how you would write the first line of a definition of
463 the `border-pattern' class option of the class `Window'.
467 @defcv CATEGORY CLASS NAME
471 `@defcv' creates an entry in the index of variables.
473 `@defivar CLASS NAME'
474 The `@defivar' command is the definition command for instance
475 variables in object-oriented programming. `@defivar' is
476 equivalent to `@defcv {Instance Variable} ...'
480 @defivar CLASS INSTANCE-VARIABLE-NAME
484 `@defivar' creates an entry in the index of variables.
486 `@defop CATEGORY CLASS NAME ARGUMENTS...'
487 The `@defop' command is the general definition command for
488 entities that may resemble methods in object-oriented programming.
489 These entities take arguments, as functions do, but are associated
490 with particular classes of objects.
492 For example, some systems have constructs called "wrappers" that
493 are associated with classes as methods are, but that act more like
494 macros than like functions. You could use `@defop Wrapper' to
495 describe one of these.
497 Sometimes it is useful to distinguish methods and "operations".
498 You can think of an operation as the specification for a method.
499 Thus, a window system might specify that all window classes have a
500 method named `expose'; we would say that this window system
501 defines an `expose' operation on windows in general. Typically,
502 the operation has a name and also specifies the pattern of
503 arguments; all methods that implement the operation must accept
504 the same arguments, since applications that use the operation do
505 so without knowing which method will implement it.
507 Often it makes more sense to document operations than methods. For
508 example, window application developers need to know about the
509 `expose' operation, but need not be concerned with whether a given
510 class of windows has its own method to implement this operation.
511 To describe this operation, you would write:
513 @defop Operation windows expose
515 The `@defop' command is written at the beginning of a line and is
516 followed on the same line by the overall name of the category of
517 operation, the name of the class of the operation, the name of the
518 operation, and its arguments, if any.
522 @defop CATEGORY CLASS NAME ARGUMENTS...
526 `@defop' creates an entry, such as ``expose' on `windows'', in the
529 `@defmethod CLASS NAME ARGUMENTS...'
530 The `@defmethod' command is the definition command for methods in
531 object-oriented programming. A method is a kind of function that
532 implements an operation for a particular class of objects and its
533 subclasses. In the Lisp Machine, methods actually were functions,
534 but they were usually defined with `defmethod'.
536 `@defmethod' is equivalent to `@defop Method ...'. The command is
537 written at the beginning of a line and is followed by the name of
538 the class of the method, the name of the method, and its
543 @defmethod `bar-class' bar-method argument
547 illustrates the definition for a method called `bar-method' of the
548 class `bar-class'. The method takes an argument.
552 @defmethod CLASS METHOD-NAME ARGUMENTS...
556 `@defmethod' creates an entry, such as ``bar-method' on
557 `bar-class'', in the index of functions.
559 `@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...'
560 The `@deftypemethod' command is the definition command for methods
561 in object-oriented typed languages, such as C++ and Java. It is
562 similar to the `@defmethod' command with the addition of the
563 DATA-TYPE parameter to specify the return type of the method.
567 File: texinfo.info, Node: Data Types, Prev: Abstract Objects, Up: Def Cmds in Detail
572 Here is the command for data types:
574 `@deftp CATEGORY NAME ATTRIBUTES...'
575 The `@deftp' command is the generic definition command for data
576 types. The command is written at the beginning of a line and is
577 followed on the same line by the category, by the name of the type
578 (which is a word like `int' or `float'), and then by names of
579 attributes of objects of that type. Thus, you could use this
580 command for describing `int' or `float', in which case you could
581 use `data type' as the category. (A data type is a category of
582 certain objects for purposes of deciding which operations can be
585 In Lisp, for example, "pair" names a particular data type, and an
586 object of that type has two slots called the CAR and the CDR.
587 Here is how you would write the first line of a definition of
590 @deftp {Data type} pair car cdr
596 @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...
600 `@deftp' creates an entry in the index of data types.
603 File: texinfo.info, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands
605 Conventions for Writing Definitions
606 ===================================
608 When you write a definition using `@deffn', `@defun', or one of the
609 other definition commands, please take care to use arguments that
610 indicate the meaning, as with the COUNT argument to the `forward-word'
611 function. Also, if the name of an argument contains the name of a
612 type, such as INTEGER, take care that the argument actually is of that
616 File: texinfo.info, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands
618 A Sample Function Definition
619 ============================
621 A function definition uses the `@defun' and `@end defun' commands. The
622 name of the function follows immediately after the `@defun' command and
623 it is followed, on the same line, by the parameter list.
625 Here is a definition from *Note Calling Functions: (lispref)Calling
628 - Function: apply function &rest arguments
629 `apply' calls FUNCTION with ARGUMENTS, just like `funcall'
630 but with one difference: the last of ARGUMENTS is a list of
631 arguments to give to FUNCTION, rather than a single argument.
632 We also say that this list is "appended" to the other
635 `apply' returns the result of calling FUNCTION. As with
636 `funcall', FUNCTION must either be a Lisp function or a
637 primitive function; special forms and macros do not make
643 error--> Wrong type argument: listp, z
644 (apply '+ 1 2 '(3 4))
646 (apply '+ '(1 2 3 4))
649 (apply 'append '((a b c) nil (x y z) nil))
652 An interesting example of using `apply' is found in the
653 description of `mapcar'.
655 In the Texinfo source file, this example looks like this:
657 @defun apply function &rest arguments
659 @code{apply} calls @var{function} with
660 @var{arguments}, just like @code{funcall} but with one
661 difference: the last of @var{arguments} is a list of
662 arguments to give to @var{function}, rather than a single
663 argument. We also say that this list is @dfn{appended}
664 to the other arguments.
666 @code{apply} returns the result of calling
667 @var{function}. As with @code{funcall},
668 @var{function} must either be a Lisp function or a
669 primitive function; special forms and macros do not make
670 sense in @code{apply}.
676 @error{} Wrong type argument: listp, z
677 (apply '+ 1 2 '(3 4))
679 (apply '+ '(1 2 3 4))
682 (apply 'append '((a b c) nil (x y z) nil))
683 @result{} (a b c x y z)
686 An interesting example of using @code{apply} is found
687 in the description of @code{mapcar}.@refill
690 In this manual, this function is listed in the Command and Variable
693 Ordinary variables and user options are described using a format like
694 that for functions except that variables do not take arguments.
697 File: texinfo.info, Node: Footnotes, Next: Conditionals, Prev: Definition Commands, Up: Top
702 A "footnote" is for a reference that documents or elucidates the
703 primary text.(1) (*note Footnotes-Footnote-1::)
707 * Footnote Commands:: How to write a footnote in Texinfo.
708 * Footnote Styles:: Controlling how footnotes appear in Info.
711 File: texinfo.info, Node: Footnotes-Footnotes, Up: Footnotes
713 (1) A footnote should complement or expand upon the primary text, but
714 a reader should not need to read a footnote to understand the primary
715 text. For a thorough discussion of footnotes, see `The Chicago Manual
716 of Style', which is published by the University of Chicago Press.
719 File: texinfo.info, Node: Footnote Commands, Next: Footnote Styles, Prev: Footnotes, Up: Footnotes
724 In Texinfo, footnotes are created with the `@footnote' command. This
725 command is followed immediately by a left brace, then by the text of
726 the footnote, and then by a terminating right brace. Footnotes may be
727 of any length (they will be broken across pages if necessary), but are
728 usually short. The template is:
730 ordinary text@footnote{TEXT OF FOOTNOTE}
732 As shown here, the `@footnote' command should come right after the
733 text being footnoted, with no intervening space; otherwise, the
734 formatters the footnote mark might end up starting up a line.
736 For example, this clause is followed by a sample footnote(1) (*note
737 Footnote Commands-Footnote-1::); in the Texinfo source, it looks like
740 ...a sample footnote@footnote{Here is the sample
741 footnote.}; in the Texinfo source...
743 *Warning:* Don't use footnotes in the argument of the `@item' command
744 for a `@table' table. This doesn't work, and because of limitations of
745 TeX, there is no way to fix it. You must put the footnote into the
746 body text of the table.
748 In a printed manual or book, the reference mark for a footnote is a
749 small, superscripted number; the text of the footnote appears at the
750 bottom of the page, below a horizontal line.
752 In Info, the reference mark for a footnote is a pair of parentheses
753 with the footnote number between them, like this: `(1)'.
756 File: texinfo.info, Node: Footnote Commands-Footnotes, Up: Footnote Commands
758 (1) Here is the sample footnote.
761 File: texinfo.info, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes
766 Info has two footnote styles, which determine where the text of the
769 * In the `End' node style, all the footnotes for a single node are
770 placed at the end of that node. The footnotes are separated from
771 the rest of the node by a line of dashes with the word `Footnotes'
772 within it. Each footnote begins with an `(N)' reference mark.
774 Here is an example of a single footnote in the end of node style:
776 --------- Footnotes ---------
778 (1) Here is a sample footnote.
780 * In the `Separate' node style, all the footnotes for a single node
781 are placed in an automatically constructed node of their own. In
782 this style, a "footnote reference" follows each `(N)' reference
783 mark in the body of the node. The footnote reference is actually
784 a cross reference which you use to reach the footnote node.
786 The name of the node containing the footnotes is constructed by
787 appending `-Footnotes' to the name of the node that contains the
788 footnotes. (Consequently, the footnotes' node for the `Footnotes'
789 node is `Footnotes-Footnotes'!) The footnotes' node has an `Up'
790 node pointer that leads back to its parent node.
792 Here is how the first footnote in this manual looks after being
793 formatted for Info in the separate node style:
795 File: texinfo.info Node: Overview-Footnotes, Up: Overview
797 (1) Note that the first syllable of "Texinfo" is
798 pronounced like "speck", not "hex". ...
800 A Texinfo file may be formatted into an Info file with either footnote
803 Use the `@footnotestyle' command to specify an Info file's footnote
804 style. Write this command at the beginning of a line followed by an
805 argument, either `end' for the end node style or `separate' for the
813 @footnotestyle separate
815 Write an `@footnotestyle' command before or shortly after the
816 end-of-header line at the beginning of a Texinfo file. (If you include
817 the `@footnotestyle' command between the start-of-header and
818 end-of-header lines, the region formatting commands will format
819 footnotes as specified.)
821 If you do not specify a footnote style, the formatting commands use
822 their default style. Currently, `texinfo-format-buffer' and
823 `texinfo-format-region' use the `separate' style and `makeinfo' uses
826 This chapter contains two footnotes.
829 File: texinfo.info, Node: Conditionals, Next: Macros, Prev: Footnotes, Up: Top
831 Conditionally Visible Text
832 **************************
834 Sometimes it is good to use different text for a printed manual and its
835 corresponding Info file. In this case, you can use the "conditional
836 commands" to specify which text is for the printed manual and which is
841 * Conditional Commands:: Specifying text for HTML, Info, or TeX.
842 * Conditional Not Commands:: Specifying text for not HTML, Info, or TeX.
843 * Raw Formatter Commands:: Using raw TeX or HTML commands.
844 * set clear value:: Designating which text to format (for
845 all output formats); and how to set a
846 flag to a string that you can insert.
849 File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Prev: Conditionals, Up: Conditionals
854 `@ifinfo' begins segments of text that should be ignored by TeX when
855 it typesets the printed manual. The segment of text appears only in
856 the Info file. The `@ifinfo' command should appear on a line by
857 itself; end the Info-only text with a line containing `@end ifinfo' by
858 itself. At the beginning of a Texinfo file, the Info permissions are
859 contained within a region marked by `@ifinfo' and `@end ifinfo'. (*Note
860 Info Summary and Permissions::.)
862 The `@iftex' and `@end iftex' commands are similar to the `@ifinfo'
863 and `@end ifinfo' commands, except that they specify text that will
864 appear in the printed manual but not in the Info file. Likewise for
865 `@ifhtml' and `@end ifhtml', which specify text to appear only in HTML
871 This text will appear only in the printed manual.
874 However, this text will appear only in Info.
877 The preceding example produces the following line: However, this text
878 will appear only in Info.
880 Note how you only see one of the two lines, depending on whether you
881 are reading the Info version or the printed version of this manual.
883 The `@titlepage' command is a special variant of `@iftex' that is
884 used for making the title and copyright pages of the printed manual.
885 (*Note `@titlepage': titlepage.)
888 File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals
890 Conditional Not Commands
891 ========================
893 You can specify text to be included in any output format _other_ than
894 some given one with the `@ifnot...' commands:
895 @ifnothtml ... @end ifnothtml
896 @ifnotinfo ... @end ifnotinfo
897 @ifnottex ... @end ifnottex
899 (The `@ifnot...' command and the `@end' command must actually appear on
900 lines by themselves.)
902 If the output file is not being made for the given format, the region
903 is included. Otherwise, it is ignored.
905 The regions delimited by these commands are ordinary Texinfo source as
906 with `@iftex', not raw formatter source as with `@tex'.
909 File: texinfo.info, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals
911 Raw Formatter Commands
912 ======================
914 Inside a region delineated by `@iftex' and `@end iftex', you can embed
915 some raw TeX commands. Info will ignore these commands since they are
916 only in that part of the file which is seen by TeX. You can write the
917 TeX commands as you would write them in a normal TeX file, except that
918 you must replace the `\' used by TeX with an `@'. For example, in the
919 `@titlepage' section of a Texinfo file, you can use the TeX command
920 `@vskip' to format the copyright page. (The `@titlepage' command
921 causes Info to ignore the region automatically, as it does with the
924 However, many features of plain TeX will not work, as they are
925 overridden by Texinfo features.
927 You can enter plain TeX completely, and use `\' in the TeX commands,
928 by delineating a region with the `@tex' and `@end tex' commands. (The
929 `@tex' command also causes Info to ignore the region, like the `@iftex'
930 command.) The sole exception is that `@' chracter still introduces a
931 command, so that `@end tex' can be recognized properly.
933 For example, here is a mathematical expression written in plain TeX:
936 $$ \chi^2 = \sum_{i=1}^N
937 \left (y_i - (a + b x_i)
938 \over \sigma_i\right)^2 $$
941 The output of this example will appear only in a printed manual. If
942 you are reading this in Info, you will not see the equation that appears
943 in the printed manual.
945 Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a
946 region to be included in HTML output only, and `@html ... @end ifhtml'
947 for a region of raw HTML (again, except that `@' is still the escape
948 character, so the `@end' command can be recognized.)
951 File: texinfo.info, Node: set clear value, Prev: Raw Formatter Commands, Up: Conditionals
953 `@set', `@clear', and `@value'
954 ==============================
956 You can direct the Texinfo formatting commands to format or ignore parts
957 of a Texinfo file with the `@set', `@clear', `@ifset', and `@ifclear'
960 In addition, you can use the `@set FLAG' command to set the value of
961 FLAG to a string of characters; and use `@value{FLAG}' to insert that
962 string. You can use `@set', for example, to set a date and use
963 `@value' to insert the date in several places in the Texinfo file.
967 * ifset ifclear:: Format a region if a flag is set.
968 * value:: Replace a flag with a string.
969 * value Example:: An easy way to update edition information.
972 File: texinfo.info, Node: ifset ifclear, Next: value, Prev: set clear value, Up: set clear value
974 `@ifset' and `@ifclear'
975 -----------------------
977 When a FLAG is set, the Texinfo formatting commands format text between
978 subsequent pairs of `@ifset FLAG' and `@end ifset' commands. When the
979 FLAG is cleared, the Texinfo formatting commands do _not_ format the
982 Use the `@set FLAG' command to turn on, or "set", a FLAG; a "flag"
983 can be any single word. The format for the command looks like this:
987 Write the conditionally formatted text between `@ifset FLAG' and
988 `@end ifset' commands, like this:
994 For example, you can create one document that has two variants, such
995 as a manual for a `large' and `small' model:
997 You can use this machine to dig up shrubs
998 without hurting them.
1003 It can also dig up fully grown trees.
1006 Remember to replant promptly ...
1008 In the example, the formatting commands will format the text between
1009 `@ifset large' and `@end ifset' because the `large' flag is set.
1011 Use the `@clear FLAG' command to turn off, or "clear", a flag.
1012 Clearing a flag is the opposite of setting a flag. The command looks
1017 Write the command on a line of its own.
1019 When FLAG is cleared, the Texinfo formatting commands do _not_ format
1020 the text between `@ifset FLAG' and `@end ifset'; that text is ignored
1021 and does not appear in either printed or Info output.
1023 For example, if you clear the flag of the preceding example by writing
1024 an `@clear large' command after the `@set large' command (but before
1025 the conditional text), then the Texinfo formatting commands ignore the
1026 text between the `@ifset large' and `@end ifset' commands. In the
1027 formatted output, that text does not appear; in both printed and Info
1028 output, you see only the lines that say, "You can use this machine to
1029 dig up shrubs without hurting them. Remember to replant promptly ...".
1031 If a flag is cleared with an `@clear FLAG' command, then the
1032 formatting commands format text between subsequent pairs of `@ifclear'
1033 and `@end ifclear' commands. But if the flag is set with `@set FLAG',
1034 then the formatting commands do _not_ format text between an `@ifclear'
1035 and an `@end ifclear' command; rather, they ignore that text. An
1036 `@ifclear' command looks like this:
1040 In brief, the commands are:
1043 Tell the Texinfo formatting commands that FLAG is set.
1046 Tell the Texinfo formatting commands that FLAG is cleared.
1049 If FLAG is set, tell the Texinfo formatting commands to format the
1050 text up to the following `@end ifset' command.
1052 If FLAG is cleared, tell the Texinfo formatting commands to ignore
1053 text up to the following `@end ifset' command.
1056 If FLAG is set, tell the Texinfo formatting commands to ignore the
1057 text up to the following `@end ifclear' command.
1059 If FLAG is cleared, tell the Texinfo formatting commands to format
1060 the text up to the following `@end ifclear' command.
1063 File: texinfo.info, Node: value, Next: value Example, Prev: ifset ifclear, Up: set clear value
1068 You can use the `@set' command to specify a value for a flag, which is
1069 expanded by the `@value' command. The value is a string a characters.
1071 Write the `@set' command like this:
1073 @set foo This is a string.
1075 This sets the value of `foo' to "This is a string."
1077 The Texinfo formatters replace an `@value{FLAG}' command with the
1078 string to which FLAG is set.
1080 Thus, when `foo' is set as shown above, the Texinfo formatters convert
1086 You can write an `@value' command within a paragraph; but you must
1087 write an `@set' command on a line of its own.
1089 If you write the `@set' command like this:
1093 without specifying a string, the value of `foo' is an empty string.
1095 If you clear a previously set flag with an `@clear FLAG' command, a
1096 subsequent `@value{flag}' command is invalid and the string is replaced
1097 with an error message that says `{No value for "FLAG"}'.
1099 For example, if you set `foo' as follows:
1101 @set how-much very, very, very
1103 then the formatters transform
1105 It is a @value{how-much} wet day.
1107 It is a very, very, very wet day.
1113 then the formatters transform
1115 It is a @value{how-much} wet day.
1117 It is a {No value for "how-much"} wet day.
1120 File: texinfo.info, Node: value Example, Prev: value, Up: set clear value
1125 You can use the `@value' command to limit the number of places you need
1126 to change when you record an update to a manual. Here is how it is
1127 done in `The GNU Make Manual':
1131 @set EDITION 0.35 Beta
1132 @set VERSION 3.63 Beta
1133 @set UPDATED 14 August 1992
1134 @set UPDATE-MONTH August 1992
1136 Write text for the first `@ifinfo' section, for people reading the
1139 This is Edition @value{EDITION},
1140 last updated @value{UPDATED},
1141 of @cite{The GNU Make Manual},
1142 for @code{make}, Version @value{VERSION}.
1144 Write text for the title page, for people reading the printed manual:
1147 @subtitle A Program for Directing Recompilation
1148 @subtitle Edition @value{EDITION}, ...
1149 @subtitle @value{UPDATE-MONTH}
1151 (On a printed cover, a date listing the month and the year looks less
1152 fussy than a date listing the day as well as the month and year.)
1154 Write text for the Top node, for people reading the Info file:
1156 This is Edition @value{EDITION}
1157 of the @cite{GNU Make Manual},
1158 last updated @value{UPDATED}
1159 for @code{make} Version @value{VERSION}.
1161 After you format the manual, the text in the first `@ifinfo' section
1164 This is Edition 0.35 Beta, last updated 14 August 1992,
1165 of `The GNU Make Manual', for `make', Version 3.63 Beta.
1167 When you update the manual, change only the values of the flags; you
1168 do not need to rewrite the three sections.
1171 File: texinfo.info, Node: Macros, Next: Format/Print Hardcopy, Prev: Conditionals, Up: Top
1173 Macros: Defining New Texinfo Commands
1174 *************************************
1176 A Texinfo "macro" allows you to define a new Texinfo command as any
1177 sequence of text and/or existing commands (including other macros). The
1178 macro can have any number of "parameters"--text you supply each time
1179 you use the macro. (This has nothing to do with the `@defmac' command,
1180 which is for documenting macros in the subject of the manual; *note Def
1185 * Defining Macros:: Both defining and undefining new commands.
1186 * Invoking Macros:: Using a macro, once you've defined it.
1189 File: texinfo.info, Node: Defining Macros, Next: Invoking Macros, Prev: Macros, Up: Macros
1194 You use the Texinfo `@macro' command to define a macro. For example:
1196 @macro MACRO-NAME{PARAM1, PARAM2, ...}
1197 TEXT ... \PARAM1\ ...
1200 The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
1201 when the macro is subsequently used in the document (see the next
1204 If a macro needs no parameters, you can define it either with an empty
1205 list (`@macro foo {}') or with no braces at all (`@macro foo').
1207 The definition or "body" of the macro can contain any Texinfo
1208 commands, including previously-defined macros. (It is not possible to
1209 have mutually recursive Texinfo macros.) In the body, instances of a
1210 parameter name surrounded by backslashes, as in `\PARAM1\' in the
1211 example above, are replaced by the corresponding argument from the
1214 You can undefine a macro FOO with `@unmacro FOO'. It is not an error
1215 to undefine a macro that is already undefined. For example:
1220 File: texinfo.info, Node: Invoking Macros, Prev: Defining Macros, Up: Macros
1225 After a macro is defined (see the previous section), you can use
1226 ("invoke") it in your document like this:
1228 @MACRO-NAME {ARG1, ARG2, ...}
1230 and the result will be just as if you typed the body of MACRO-NAME at
1231 that spot. For example:
1234 Together: \p\ & \q\.
1242 Thus, the arguments and parameters are separated by commas and
1243 delimited by braces; any whitespace after (but not before) a comma is
1244 ignored. To insert a comma, brace, or backslash in an argument,
1245 prepend a backslash, as in
1247 @MACRO-NAME {\\\{\}\,}
1249 which will pass the (almost certainly error-producing) argument `\{},'
1252 If the macro is defined to take a single argument, and is invoked
1253 without any braces, the entire rest of the line after the macro name is
1254 supplied as the argument. For example:
1266 File: texinfo.info, Node: Format/Print Hardcopy, Next: Create an Info File, Prev: Macros, Up: Top
1268 Format and Print Hardcopy
1269 *************************
1271 There are three major shell commands for making a printed manual from a
1272 Texinfo file: one for converting the Texinfo file into a file that will
1273 be printed, a second for sorting indices, and a third for printing the
1274 formatted document. When you use the shell commands, you can either
1275 work directly in the operating system shell or work within a shell
1278 If you are using GNU Emacs, you can use commands provided by Texinfo
1279 mode instead of shell commands. In addition to the three commands to
1280 format a file, sort the indices, and print the result, Texinfo mode
1281 offers key bindings for commands to recenter the output buffer, show the
1282 print queue, and delete a job from the print queue.
1286 * Use TeX:: Use TeX to format for hardcopy.
1287 * Format with tex/texindex:: How to format in a shell.
1288 * Format with texi2dvi:: A simpler way to use the shell.
1289 * Print with lpr:: How to print.
1290 * Within Emacs:: How to format and print from an Emacs shell.
1291 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
1292 * Compile-Command:: How to print using Emacs's compile command.
1293 * Requirements Summary:: TeX formatting requirements summary.
1294 * Preparing for TeX:: What you need to do to use TeX.
1295 * Overfull hboxes:: What are and what to do with overfull hboxes.
1296 * smallbook:: How to print small format books and manuals.
1297 * A4 Paper:: How to print on European A4 paper.
1298 * Cropmarks and Magnification:: How to print marks to indicate the size
1299 of pages and how to print scaled up output.
1302 File: texinfo.info, Node: Use TeX, Next: Format with tex/texindex, Prev: Format/Print Hardcopy, Up: Format/Print Hardcopy
1307 The typesetting program called TeX is used for formatting a Texinfo
1308 file. TeX is a very powerful typesetting program and, if used right,
1309 does an exceptionally good job. (*Note How to Obtain TeX: Obtaining
1310 TeX, for information on how to obtain TeX.)
1312 The `makeinfo', `texinfo-format-region', and `texinfo-format-buffer'
1313 commands read the very same @-commands in the Texinfo file as does TeX,
1314 but process them differently to make an Info file; see *Note Create an
1318 File: texinfo.info, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Format/Print Hardcopy
1320 Format using `tex' and `texindex'
1321 =================================
1323 Format the Texinfo file with the shell command `tex' followed by the
1324 name of the Texinfo file. For example:
1328 TeX will produce a "DVI file" as well as several auxiliary files
1329 containing information for indices, cross references, etc. The DVI
1330 file (for "DeVice Independent" file) can be printed on virtually any
1331 printe (see the following sections).
1333 The `tex' formatting command itself does not sort the indices; it
1334 writes an output file of unsorted index data. (The `texi2dvi' command
1335 automatically generates indices; see *Note Format using `texi2dvi':
1336 Format with texi2dvi.) To generate a printed index after running the
1337 `tex' command, you first need a sorted index to work from. The
1338 `texindex' command sorts indices. (The source file `texindex.c' comes
1339 as part of the standard Texinfo distribution, among other places.)
1341 The `tex' formatting command outputs unsorted index files under names
1342 that obey a standard convention: the name of your main input file with
1343 any `.tex' (or similar, *note tex invocation: (web2c)tex invocation.)
1344 extension removed, followed by the two letter names of indices. For
1345 example, the raw index output files for the input file `foo.texinfo'
1346 would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'.
1347 Those are exactly the arguments to give to `texindex'.
1349 Instead of specifying all the unsorted index file names explicitly,
1350 you can use `??' as shell wildcards and give the command in this form:
1354 This command will run `texindex' on all the unsorted index files,
1355 including any that you have defined yourself using `@defindex' or
1356 `@defcodeindex'. (You may execute `texindex foo.??' even if there are
1357 similarly named files with two letter extensions that are not index
1358 files, such as `foo.el'. The `texindex' command reports but otherwise
1359 ignores such files.)
1361 For each file specified, `texindex' generates a sorted index file
1362 whose name is made by appending `s' to the input file name. The
1363 `@printindex' command knows to look for a file of that name (*note
1364 Printing Indices & Menus::). `texindex' does not alter the raw index
1367 After you have sorted the indices, you need to rerun the `tex'
1368 formatting command on the Texinfo file. This regenerates the DVI file,
1369 this time with up-to-date index entries.
1371 Finally, you may need to run `tex' one more time, to get the page
1372 numbers in the cross-references correct.
1374 To summarize, this is a four step process:
1376 1. Run `tex' on your Texinfo file. This generates a DVI file (with
1377 undefined cross-references and no indices), and the raw index files
1378 (with two letter extensions).
1380 2. Run `texindex' on the raw index files. This creates the
1381 corresponding sorted index files (with three letter extensions).
1383 3. Run `tex' again on your Texinfo file. This regenerates the DVI
1384 file, this time with indices and defined cross-references, but
1385 with page numbers for the cross-references from last time,
1386 generally incorrect.
1388 4. Run `tex' one last time. This time the correct page numbers are
1389 written for the cross-references.
1391 Alternatively, it's a one-step process: run `texi2dvi'.
1393 You need not run `texindex' each time after you run `tex'. If you do
1394 not, on the next run, the `tex' formatting command will use whatever
1395 sorted index files happen to exist from the previous use of `texindex'.
1396 This is usually ok while you are debugging.
1399 File: texinfo.info, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Format/Print Hardcopy
1401 Format using `texi2dvi'
1402 =======================
1404 The `texi2dvi' command automatically runs both `tex' and `texindex' as
1405 many times as necessary to produce a DVI file with up-to-date, sorted
1406 indices. It simplifies the `tex'--`texindex'--`tex' sequence described
1407 in the previous section.
1409 The syntax for `texi2dvi' is like this (where `prompt$' is your shell
1412 prompt$ texi2dvi FILENAME...
1414 For a list of options, run `texi2dvi --help'.
1417 File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Format/Print Hardcopy
1419 Shell Print Using `lpr -d'
1420 ==========================
1422 The precise command to print a DVI file depends on your system
1423 installation, but `lpr -d' is common. The command may require the DVI
1424 file name without any extension or with a `.dvi' extension. (If it is
1425 `lpr', you must include the `.dvi'.)
1427 The following commands, for example, will (probably) suffice to sort
1428 the indices, format, and print the `Bison Manual':
1435 (Remember that the shell commands may be different at your site; but
1436 these are commonly used versions.)
1438 Using the `texi2dvi' shell script, you simply need type:
1440 texi2dvi bison.texinfo
1444 File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Format/Print Hardcopy
1449 You can give formatting and printing commands from a shell within GNU
1450 Emacs. To create a shell within Emacs, type `M-x shell'. In this
1451 shell, you can format and print the document. *Note Format and Print
1452 Hardcopy: Format/Print Hardcopy, for details.
1454 You can switch to and from the shell buffer while `tex' is running
1455 and do other editing. If you are formatting a long document on a slow
1456 machine, this can be very convenient.
1458 You can also use `texi2dvi' from an Emacs shell. For example, here
1459 is how to use `texi2dvi' to format and print `Using and Porting GNU CC'
1460 from a shell within Emacs:
1462 texi2dvi gcc.texinfo
1465 *Note Texinfo Mode Printing::, for more information about formatting
1466 and printing in Texinfo mode.
1469 File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Format/Print Hardcopy
1471 Formatting and Printing in Texinfo Mode
1472 =======================================
1474 Texinfo mode provides several predefined key commands for TeX
1475 formatting and printing. These include commands for sorting indices,
1476 looking at the printer queue, killing the formatting job, and
1477 recentering the display of the buffer in which the operations occur.
1480 `M-x texinfo-tex-buffer'
1481 Run `texi2dvi' on the current buffer.
1484 `M-x texinfo-tex-region'
1485 Run TeX on the current region.
1488 `M-x texinfo-texindex'
1489 Sort the indices of a Texinfo file formatted with
1490 `texinfo-tex-region'.
1493 `M-x texinfo-tex-print'
1494 Print a DVI file that was made with `texinfo-tex-region' or
1495 `texinfo-tex-buffer'.
1498 `M-x tex-show-print-queue'
1499 Show the print queue.
1502 `M-x texinfo-delete-from-print-queue'
1503 Delete a job from the print queue; you will be prompted for the job
1504 number shown by a preceding `C-c C-t C-q' command
1505 (`texinfo-show-tex-print-queue').
1509 Kill the currently running TeX job started by `texinfo-tex-region'
1510 or `texinfo-tex-buffer', or any other process running in the
1511 Texinfo shell buffer.
1514 `M-x texinfo-quit-job'
1515 Quit a TeX formatting job that has stopped because of an error by
1516 sending an <x> to it. When you do this, TeX preserves a record of
1517 what it did in a `.log' file.
1520 `M-x tex-recenter-output-buffer'
1521 Redisplay the shell buffer in which the TeX printing and formatting
1522 commands are run to show its most recent output.
1524 Thus, the usual sequence of commands for formatting a buffer is as
1525 follows (with comments to the right):
1527 C-c C-t C-b Run `texi2dvi' on the buffer.
1528 C-c C-t C-p Print the DVI file.
1529 C-c C-t C-q Display the printer queue.
1531 The Texinfo mode TeX formatting commands start a subshell in Emacs
1532 called the `*tex-shell*'. The `texinfo-tex-command',
1533 `texinfo-texindex-command', and `tex-dvi-print-command' commands are
1534 all run in this shell.
1536 You can watch the commands operate in the `*tex-shell*' buffer, and
1537 you can switch to and from and use the `*tex-shell*' buffer as you
1538 would any other shell buffer.
1540 The formatting and print commands depend on the values of several
1541 variables. The default values are:
1543 Variable Default value
1545 texinfo-texi2dvi-command "texi2dvi"
1546 texinfo-tex-command "tex"
1547 texinfo-texindex-command "texindex"
1548 texinfo-delete-from-print-queue-command "lprm"
1549 texinfo-tex-trailer "@bye"
1550 tex-start-of-header "%**start"
1551 tex-end-of-header "%**end"
1552 tex-dvi-print-command "lpr -d"
1553 tex-show-queue-command "lpq"
1555 You can change the values of these variables with the `M-x
1556 edit-options' command (*note Editing Variable Values: (xemacs)Edit
1557 Options.), with the `M-x set-variable' command (*note Examining and
1558 Setting Variables: (xemacs)Examining.), or with your `.emacs'
1559 initialization file (*note Init File: (xemacs)Init File.).
1562 File: texinfo.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Format/Print Hardcopy
1564 Using the Local Variables List
1565 ==============================
1567 Yet another way to apply the TeX formatting command to a Texinfo file
1568 is to put that command in a "local variables list" at the end of the
1569 Texinfo file. You can then specify the `tex' or `texi2dvi' commands as
1570 a `compile-command' and have Emacs run it by typing `M-x compile'.
1571 This creates a special shell called the `*compilation*' buffer in which
1572 Emacs runs the compile command. For example, at the end of the
1573 `gdb.texinfo' file, after the `@bye', you could put the following:
1576 compile-command: "texi2dvi gdb.texinfo"
1579 This technique is most often used by programmers who also compile
1580 programs this way; see *Note Compilation: (xemacs)Compilation.
1583 File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Format/Print Hardcopy
1585 TeX Formatting Requirements Summary
1586 ===================================
1588 Every Texinfo file that is to be input to TeX must begin with a
1589 `\input' command and must contain an `@setfilename' command:
1592 @setfilename ARG-NOT-USED-BY-@TEX{}
1594 The first command instructs TeX to load the macros it needs to process
1595 a Texinfo file and the second command opens auxiliary files.
1597 Every Texinfo file must end with a line that terminates TeX's
1598 processing and forces out unfinished pages:
1602 Strictly speaking, these lines are all a Texinfo file needs to be
1603 processed successfully by TeX.
1605 Usually, however, the beginning includes an `@settitle' command to
1606 define the title of the printed manual, an `@setchapternewpage'
1607 command, a title page, a copyright page, and permissions. Besides an
1608 `@bye', the end of a file usually includes indices and a table of
1609 contents. (And of course most manuals contain a body of text as well.)
1611 For more information, see
1612 *Note `@settitle': settitle,
1613 *Note `@setchapternewpage': setchapternewpage,
1614 *Note Page Headings: Headings,
1615 *Note Titlepage & Copyright Page::,
1616 *Note Printing Indices & Menus::, and
1620 File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Format/Print Hardcopy
1622 Preparing to Use TeX
1623 ====================
1625 TeX needs to know where to find the `texinfo.tex' file that you have
1626 told it to input with the `\input texinfo' command at the beginning of
1627 the first line. The `texinfo.tex' file tells TeX how to handle
1628 @-commands; it is included in all standard GNU distributions.
1630 Usually, the `texinfo.tex' file is put under the default directory
1631 that contains TeX macros
1632 (`/usr/local/share/texmf/tex/texinfo/texinfo.tex' by default) when GNU
1633 Emacs or other GNU software is installed. In this case, TeX will find
1634 the file and you do not need to do anything special. Alternatively,
1635 you can put `texinfo.tex' in the current directory when you run TeX,
1636 and TeX will find it there.
1638 Also, you should install `epsf.tex' in the same place as
1639 `texinfo.tex', if it is not already installed from another
1640 distribution. This file is needed to support the `@image' command
1643 Optionally, you may create an additional `texinfo.cnf', and install
1644 it as well. This file is read by TeX at the `@setfilename' command
1645 (*note `@setfilename': setfilename.). You can put any commands you
1646 like there according to local site-wide conventions, and they will be
1647 read by TeX when processing any Texinfo document. For example, if
1648 `texinfo.cnf' contains the a single line `@afourpaper' (*note A4
1649 Paper::), then all Texinfo documents will be processed with that page
1650 size in effect. If you have nothing to put in `texinfo.cnf', you do
1651 not need to create it.
1653 If neither of the above locations for these system files suffice for
1654 you, you can specify the directories explicitly. For `texinfo.tex',
1655 you can do this by writing the complete path for the file after the
1656 `\input' command. Another way, that works for both `texinfo.tex' and
1657 `texinfo.cnf' (and any other file TeX might read), is to set the
1658 `TEXINPUTS' environment variable in your `.cshrc' or `.profile' file.
1660 Which you use of `.cshrc' or `.profile' depends on whether you use a
1661 Bourne shell-compatible (`sh', `bash', `ksh', ...) or C
1662 shell-compatible (`csh', `tcsh') command interpreter. The latter read
1663 the `.cshrc' file for initialization information, and the former read
1666 In a `.cshrc' file, you could use the following `csh' command
1669 setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
1671 In a `.profile' file, you could use the following `sh' command
1674 TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
1677 This would cause TeX to look for `\input' file first in the current
1678 directory, indicated by the `.', then in a hypothetical user's
1679 `me/mylib' directory, and finally in a system directory.
1682 File: texinfo.info, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Format/Print Hardcopy
1687 TeX is sometimes unable to typeset a line without extending it into the
1688 right margin. This can occur when TeX comes upon what it interprets as
1689 a long word that it cannot hyphenate, such as an electronic mail
1690 network address or a very long title. When this happens, TeX prints an
1691 error message like this:
1693 Overfull \hbox (20.76302pt too wide)
1695 (In TeX, lines are in "horizontal boxes", hence the term, "hbox". The
1696 backslash, `\', is the TeX equivalent of `@'.)
1698 TeX also provides the line number in the Texinfo source file and the
1699 text of the offending line, which is marked at all the places that TeX
1700 knows how to hyphenate words. *Note Catching Errors with TeX
1701 Formatting: Debugging with TeX, for more information about typesetting
1704 If the Texinfo file has an overfull hbox, you can rewrite the sentence
1705 so the overfull hbox does not occur, or you can decide to leave it. A
1706 small excursion into the right margin often does not matter and may not
1709 However, unless told otherwise, TeX will print a large, ugly, black
1710 rectangle beside the line that contains the overfull hbox. This is so
1711 you will notice the location of the problem if you are correcting a
1714 To prevent such a monstrosity from marring your final printout, write
1715 the following in the beginning of the Texinfo file on a line of its own,
1716 before the `@titlepage' command:
1721 File: texinfo.info, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Format/Print Hardcopy
1723 Printing "Small" Books
1724 ======================
1726 By default, TeX typesets pages for printing in an 8.5 by 11 inch
1727 format. However, you can direct TeX to typeset a document in a 7 by
1728 9.25 inch format that is suitable for bound books by inserting the
1729 following command on a line by itself at the beginning of the Texinfo
1730 file, before the title page:
1734 (Since regular sized books are often about 7 by 9.25 inches, this
1735 command might better have been called the `@regularbooksize' command,
1736 but it came to be called the `@smallbook' command by comparison to the
1737 8.5 by 11 inch format.)
1739 If you write the `@smallbook' command between the start-of-header and
1740 end-of-header lines, the Texinfo mode TeX region formatting command,
1741 `texinfo-tex-region', will format the region in "small" book size
1742 (*note Start of Header::).
1744 The Free Software Foundation distributes printed copies of `The GNU
1745 Emacs Manual' and other manuals in the "small" book size. *Note
1746 `@smallexample' and `@smalllisp': smallexample & smalllisp, for
1747 information about commands that make it easier to produce examples for
1750 Alternatively, to avoid embedding this physical paper size in your
1751 document, use `texi2dvi' to format your document (*note Format with
1752 texi2dvi::), and supply `-t @smallbook' as an argument. Then other
1753 people do not have to change the document source file to format it
1757 File: texinfo.info, Node: A4 Paper, Next: Cropmarks and Magnification, Prev: smallbook, Up: Format/Print Hardcopy
1759 Printing on A4 Paper
1760 ====================
1762 You can tell TeX to typeset a document for printing on European size A4
1763 paper with the `@afourpaper' command. Write the command on a line by
1764 itself between `@iftex' and `@end iftex' lines near the beginning of
1765 the Texinfo file, before the title page:
1767 For example, this is how you would write the header for this manual:
1769 \input texinfo @c -*-texinfo-*-
1770 @c %**start of header
1771 @setfilename texinfo
1779 Alternatively, to avoid embedding this physical paper size in your
1780 document, use `texi2dvi' to format your document (*note Format with
1781 texi2dvi::), and supply `-t @afourpaper' as an argument. Then other
1782 people do not have to change the document source file to format it
1785 Another alternative: put the `@afourpaper' command in the file
1786 `texinfo.cnf' that TeX will read. (No need for `@iftex' there.) This
1787 will automatically typeset all the Texinfo documents at your site with
1788 that paper size in effect.
1791 File: texinfo.info, Node: Cropmarks and Magnification, Prev: A4 Paper, Up: Format/Print Hardcopy
1793 Cropmarks and Magnification
1794 ===========================
1796 You can attempt to direct TeX to print cropmarks at the corners of
1797 pages with the `@cropmarks' command. Write the `@cropmarks' command on
1798 a line by itself between `@iftex' and `@end iftex' lines near the
1799 beginning of the Texinfo file, before the title page, like this:
1805 This command is mainly for printers that typeset several pages on one
1806 sheet of film; but you can attempt to use it to mark the corners of a
1807 book set to 7 by 9.25 inches with the `@smallbook' command. (Printers
1808 will not produce cropmarks for regular sized output that is printed on
1809 regular sized paper.) Since different printing machines work in
1810 different ways, you should explore the use of this command with a
1811 spirit of adventure. You may have to redefine the command in the
1812 `texinfo.tex' definitions file.
1814 You can attempt to direct TeX to typeset pages larger or smaller than
1815 usual with the `\mag' TeX command. Everything that is typeset is
1816 scaled proportionally larger or smaller. (`\mag' stands for
1817 "magnification".) This is _not_ a Texinfo @-command, but is a plain
1818 TeX command that is prefixed with a backslash. You have to write this
1819 command between `@tex' and `@end tex' (*note Raw Formatter Commands::).
1821 Follow the `\mag' command with an `=' and then a number that is 1000
1822 times the magnification you desire. For example, to print pages at 1.2
1823 normal size, write the following near the beginning of the Texinfo
1824 file, before the title page:
1830 With some printing technologies, you can print normal-sized copies
1831 that look better than usual by using a larger-than-normal master.
1833 Depending on your system, `\mag' may not work or may work only at
1834 certain magnifications. Be prepared to experiment.
1837 File: texinfo.info, Node: Create an Info File, Next: Install an Info File, Prev: Format/Print Hardcopy, Up: Top
1839 Creating an Info File
1840 *********************
1842 `makeinfo' is a utility that converts a Texinfo file into an Info file;
1843 `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs
1844 functions that do the same.
1846 A Texinfo file must contain an `@setfilename' line near its
1847 beginning, otherwise the Info formatting commands will fail.
1849 For information on installing the Info file in the Info system, see
1850 *Note Install an Info File::.
1854 * makeinfo advantages:: `makeinfo' provides better error checking.
1855 * Invoking makeinfo:: How to run `makeinfo' from a shell.
1856 * makeinfo options:: Specify fill-column and other options.
1857 * Pointer Validation:: How to check that pointers point somewhere.
1858 * makeinfo in Emacs:: How to run `makeinfo' from Emacs.
1859 * texinfo-format commands:: Two Info formatting commands written
1860 in Emacs Lisp are an alternative
1862 * Batch Formatting:: How to format for Info in Emacs Batch mode.
1863 * Tag and Split Files:: How tagged and split files help Info
1867 File: texinfo.info, Node: makeinfo advantages, Next: Invoking makeinfo, Prev: Create an Info File, Up: Create an Info File
1869 `makeinfo' Preferred
1870 ====================
1872 The `makeinfo' utility creates an Info file from a Texinfo source
1873 file more quickly than either of the Emacs formatting commands and
1874 provides better error messages. We recommend it. `makeinfo' is a C
1875 program that is independent of Emacs. You do not need to run Emacs to
1876 use `makeinfo', which means you can use `makeinfo' on machines that are
1877 too small to run Emacs. You can run `makeinfo' in any one of three
1878 ways: from an operating system shell, from a shell inside Emacs, or by
1879 typing a key command in Texinfo mode in Emacs.
1881 The `texinfo-format-region' and the `texinfo-format-buffer' commands
1882 are useful if you cannot run `makeinfo'. Also, in some circumstances,
1883 they format short regions or buffers more quickly than `makeinfo'.
1886 File: texinfo.info, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Create an Info File
1888 Running `makeinfo' from a Shell
1889 ===============================
1891 To create an Info file from a Texinfo file, type `makeinfo' followed by
1892 the name of the Texinfo file. Thus, to create the Info file for Bison,
1893 type the following to the shell: is the prompt):
1895 makeinfo bison.texinfo
1897 (You can run a shell inside Emacs by typing `M-x shell'.)
1899 Sometimes you will want to specify options. For example, if you wish
1900 to discover which version of `makeinfo' you are using, type:
1904 *Note makeinfo options::, for more information.
1907 File: texinfo.info, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Create an Info File
1909 Options for `makeinfo'
1910 ======================
1912 The `makeinfo' command takes a number of options. Most often, options
1913 are used to set the value of the fill column and specify the footnote
1914 style. Each command line option is a word preceded by `--' or a letter
1915 preceded by `-'. You can use abbreviations for the long option names
1916 as long as they are unique.
1918 For example, you could use the following shell command to create an
1919 Info file for `bison.texinfo' in which each line is filled to only 68
1922 makeinfo --fill-column=68 bison.texinfo
1924 You can write two or more options in sequence, like this:
1926 makeinfo --no-split --fill-column=70 ...
1928 This would keep the Info file together as one possibly very long file
1929 and would also set the fill column to 70.
1934 Cause the variable VAR to be defined. This is equivalent to `@set
1935 VAR' in the Texinfo file (*note set clear value::).
1937 `--error-limit=LIMIT'
1938 Set the maximum number of errors that `makeinfo' will report
1939 before exiting (on the assumption that continuing would be
1940 useless); default 100.
1942 `--fill-column=WIDTH'
1943 Specify the maximum number of columns in a line; this is the
1944 right-hand edge of a line. Paragraphs that are filled will be
1945 filled to this width. (Filling is the process of breaking up and
1946 connecting lines so that lines are the same length as or shorter
1947 than the number specified as the fill column. Lines are broken
1948 between words.) The default value is 72.
1950 `--footnote-style=STYLE'
1951 Set the footnote style to STYLE, either `end' for the end node
1952 style (the default) or `separate' for the separate node style.
1953 The value set by this option overrides the value set in a Texinfo
1954 file by an `@footnotestyle' command (*note Footnotes::). When the
1955 footnote style is `separate', `makeinfo' makes a new node
1956 containing the footnotes found in the current node. When the
1957 footnote style is `end', `makeinfo' places the footnote references
1958 at the end of the current node.
1961 Ordinarily, if the input file has errors, the output files are not
1962 created. With this option, they are preserved.
1965 Print a usage message listing all available options, then exit
1969 Add `dir' to the directory search list for finding files that are
1970 included using the `@include' command. By default, `makeinfo'
1971 searches only the current directory.
1974 Do not include menus or node lines in the output. This results in
1975 an ASCII file that you cannot read in Info since it does not
1976 contain the requisite nodes or menus. It is primarily useful to
1977 extract certain pieces of a manual into separate files to be
1978 included in a distribution, such as `INSTALL' files.
1981 Suppress the splitting stage of `makeinfo'. By default, large
1982 output files (where the size is greater than 70k bytes) are split
1983 into smaller subfiles, each one approximately 50k bytes.
1985 `--no-pointer-validate'
1987 Suppress the pointer-validation phase of `makeinfo'. Normally,
1988 after a Texinfo file is processed, some consistency checks are
1989 made to ensure that cross references can be resolved, etc. *Note
1990 Pointer Validation::.
1993 Suppress warning messages (but _not_ error messages). You might
1994 want this if the file you are creating has examples of Texinfo
1995 cross references within it, and the nodes that are referenced do
1998 `--no-number-footnotes'
1999 Suppress automatic footnote numbering. By default, `makeinfo'
2000 numbers each footnote sequentially in a single node, resetting the
2001 current footnote number to 1 at the start of each node.
2005 Specify that the output should be directed to FILE and not to the
2006 file name specified in the `@setfilename' command found in the
2007 Texinfo source (*note setfilename::). If FILE is `-', output goes
2008 to standard output and `--no-split' is implied.
2011 Prepend `dir' to the directory search list for `@include'. See
2012 `-I' for more details.
2014 `--paragraph-indent=INDENT'
2015 Set the paragraph indentation style to INDENT. The value set by
2016 this option overrides the value set in a Texinfo file by an
2017 `@paragraphindent' command (*note paragraphindent::). The value
2018 of INDENT is interpreted as follows:
2021 Preserve any existing indentation at the starts of paragraphs.
2024 Delete any existing indentation.
2027 Indent each paragraph by that number of spaces.
2029 `--reference-limit=LIMIT'
2030 Set the value of the number of references to a node that
2031 `makeinfo' will make without reporting a warning. If a node has
2032 more than this number of references in it, `makeinfo' will make the
2033 references but also report a warning. The default is 1000.
2036 Cause VAR to be undefined. This is equivalent to `@clear VAR' in
2037 the Texinfo file (*note set clear value::).
2040 Cause `makeinfo' to display messages saying what it is doing.
2041 Normally, `makeinfo' only outputs messages if there are errors or
2045 Print the version number, then exit successfully.
2049 File: texinfo.info, Node: Pointer Validation, Next: makeinfo in Emacs, Prev: makeinfo options, Up: Create an Info File
2054 If you do not suppress pointer-validation, `makeinfo' will check the
2055 validity of the final Info file. Mostly, this means ensuring that
2056 nodes you have referenced really exist. Here is a complete list of what
2059 1. If a `Next', `Previous', or `Up' node reference is a reference to a
2060 node in the current file and is not an external reference such as
2061 to `(dir)', then the referenced node must exist.
2063 2. In every node, if the `Previous' node is different from the `Up'
2064 node, then the `Previous' node must also be pointed to by a `Next'
2067 3. Every node except the `Top' node must have an `Up' pointer.
2069 4. The node referenced by an `Up' pointer must contain a reference to
2070 the current node in some manner other than through a `Next'
2071 reference. This includes menu entries and cross references.
2073 5. If the `Next' reference of a node is not the same as the `Next'
2074 reference of the `Up' reference, then the node referenced by the
2075 `Next' pointer must have a `Previous' pointer that points back to
2076 the current node. This rule allows the last node in a section to
2077 point to the first node of the next chapter.
2080 File: texinfo.info, Node: makeinfo in Emacs, Next: texinfo-format commands, Prev: Pointer Validation, Up: Create an Info File
2082 Running `makeinfo' inside Emacs
2083 ===============================
2085 You can run `makeinfo' in GNU Emacs Texinfo mode by using either the
2086 `makeinfo-region' or the `makeinfo-buffer' commands. In Texinfo mode,
2087 the commands are bound to `C-c C-m C-r' and `C-c C-m C-b' by default.
2090 `M-x makeinfo-region'
2091 Format the current region for Info.
2094 `M-x makeinfo-buffer'
2095 Format the current buffer for Info.
2097 When you invoke either `makeinfo-region' or `makeinfo-buffer', Emacs
2098 prompts for a file name, offering the name of the visited file as the
2099 default. You can edit the default file name in the minibuffer if you
2100 wish, before pressing <RET> to start the `makeinfo' process.
2102 The Emacs `makeinfo-region' and `makeinfo-buffer' commands run the
2103 `makeinfo' program in a temporary shell buffer. If `makeinfo' finds
2104 any errors, Emacs displays the error messages in the temporary buffer.
2106 You can parse the error messages by typing `C-x `' (`next-error').
2107 This causes Emacs to go to and position the cursor on the line in the
2108 Texinfo source that `makeinfo' thinks caused the error. *Note Running
2109 `make' or Compilers Generally: (xemacs)Compilation, for more
2110 information about using the `next-error' command.
2112 In addition, you can kill the shell in which the `makeinfo' command
2113 is running or make the shell buffer display its most recent output.
2116 `M-x makeinfo-kill-job'
2117 Kill the current running `makeinfo' job created by
2118 `makeinfo-region' or `makeinfo-buffer'.
2121 `M-x makeinfo-recenter-output-buffer'
2122 Redisplay the `makeinfo' shell buffer to display its most recent
2125 (Note that the parallel commands for killing and recentering a TeX job
2126 are `C-c C-t C-k' and `C-c C-t C-l'. *Note Texinfo Mode Printing::.)
2128 You can specify options for `makeinfo' by setting the
2129 `makeinfo-options' variable with either the `M-x edit-options' or the
2130 `M-x set-variable' command, or by setting the variable in your `.emacs'
2131 initialization file.
2133 For example, you could write the following in your `.emacs' file:
2135 (setq makeinfo-options
2136 "--paragraph-indent=0 --no-split
2137 --fill-column=70 --verbose")
2139 For more information, see
2140 *Note Editing Variable Values: (xemacs)Edit Options,
2141 *Note Examining and Setting Variables: (xemacs)Examining,
2142 *Note Init File: (xemacs)Init File, and
2143 *Note Options for `makeinfo': makeinfo options.
2146 File: texinfo.info, Node: texinfo-format commands, Next: Batch Formatting, Prev: makeinfo in Emacs, Up: Create an Info File
2148 The `texinfo-format...' Commands
2149 ================================
2151 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
2152 file with the `texinfo-format-region' command. This formats the
2153 current region and displays the formatted text in a temporary buffer
2154 called `*Info Region*'.
2156 Similarly, you can format a buffer with the `texinfo-format-buffer'
2157 command. This command creates a new buffer and generates the Info file
2158 in it. Typing `C-x C-s' will save the Info file under the name
2159 specified by the `@setfilename' line which must be near the beginning
2160 of the Texinfo file.
2163 ``texinfo-format-region''
2164 Format the current region for Info.
2167 ``texinfo-format-buffer''
2168 Format the current buffer for Info.
2170 The `texinfo-format-region' and `texinfo-format-buffer' commands
2171 provide you with some error checking, and other functions can provide
2172 you with further help in finding formatting errors. These procedures
2173 are described in an appendix; see *Note Catching Mistakes::. However,
2174 the `makeinfo' program is often faster and provides better error
2175 checking (*note makeinfo in Emacs::).
2178 File: texinfo.info, Node: Batch Formatting, Next: Tag and Split Files, Prev: texinfo-format commands, Up: Create an Info File
2183 You can format Texinfo files for Info using `batch-texinfo-format' and
2184 Emacs Batch mode. You can run Emacs in Batch mode from any shell,
2185 including a shell inside of Emacs. (*Note Command Line Switches and
2186 Arguments: (xemacs)Command Switches.)
2188 Here is a shell command to format all the files that end in
2189 `.texinfo' in the current directory:
2191 emacs -batch -funcall batch-texinfo-format *.texinfo
2193 Emacs processes all the files listed on the command line, even if an
2194 error occurs while attempting to format some of them.
2196 Run `batch-texinfo-format' only with Emacs in Batch mode as shown; it
2197 is not interactive. It kills the Batch mode Emacs on completion.
2199 `batch-texinfo-format' is convenient if you lack `makeinfo' and want
2200 to format several Texinfo files at once. When you use Batch mode, you
2201 create a new Emacs process. This frees your current Emacs, so you can
2202 continue working in it. (When you run `texinfo-format-region' or
2203 `texinfo-format-buffer', you cannot use that Emacs for anything else
2204 until the command finishes.)
2207 File: texinfo.info, Node: Tag and Split Files, Prev: Batch Formatting, Up: Create an Info File
2209 Tag Files and Split Files
2210 =========================
2212 If a Texinfo file has more than 30,000 bytes, `texinfo-format-buffer'
2213 automatically creates a tag table for its Info file; `makeinfo' always
2214 creates a tag table. With a "tag table", Info can jump to new nodes
2215 more quickly than it can otherwise.
2217 In addition, if the Texinfo file contains more than about 70,000
2218 bytes, `texinfo-format-buffer' and `makeinfo' split the large Info file
2219 into shorter "indirect" subfiles of about 50,000 bytes each. Big files
2220 are split into smaller files so that Emacs does not need to make a
2221 large buffer to hold the whole of a large Info file; instead, Emacs
2222 allocates just enough memory for the small, split off file that is
2223 needed at the time. This way, Emacs avoids wasting memory when you run
2224 Info. (Before splitting was implemented, Info files were always kept
2225 short and "include files" were designed as a way to create a single,
2226 large printed manual out of the smaller Info files. *Note Include
2227 Files::, for more information. Include files are still used for very
2228 large documents, such as `The XEmacs Lisp Reference Manual', in which
2229 each chapter is a separate file.)
2231 When a file is split, Info itself makes use of a shortened version of
2232 the original file that contains just the tag table and references to
2233 the files that were split off. The split off files are called
2236 The split off files have names that are created by appending `-1',
2237 `-2', `-3' and so on to the file name specified by the `@setfilename'
2238 command. The shortened version of the original file continues to have
2239 the name specified by `@setfilename'.
2241 At one stage in writing this document, for example, the Info file was
2242 saved as `test-texinfo' and that file looked like this:
2244 Info file: test-texinfo, -*-Text-*-
2245 produced by texinfo-format-buffer
2246 from file: new-texinfo-manual.texinfo
2251 test-texinfo-2: 50422
2252 test-texinfo-3: 101300
2257 Node: info file^?1271
2258 Node: printed manual^?4853
2259 Node: conventions^?6855
2262 (But `test-texinfo' had far more nodes than are shown here.) Each of
2263 the split off, indirect files, `test-texinfo-1', `test-texinfo-2', and
2264 `test-texinfo-3', is listed in this file after the line that says
2265 `Indirect:'. The tag table is listed after the line that says `Tag
2268 In the list of indirect files, the number following the file name
2269 records the cumulative number of bytes in the preceding indirect files,
2270 not counting the file list itself, the tag table, or the permissions
2271 text in each file. In the tag table, the number following the node name
2272 records the location of the beginning of the node, in bytes from the
2275 If you are using `texinfo-format-buffer' to create Info files, you
2276 may want to run the `Info-validate' command. (The `makeinfo' command
2277 does such a good job on its own, you do not need `Info-validate'.)
2278 However, you cannot run the `M-x Info-validate' node-checking command
2279 on indirect files. For information on how to prevent files from being
2280 split and how to validate the structure of the nodes, see *Note Using
2284 File: texinfo.info, Node: Install an Info File, Next: Command List, Prev: Create an Info File, Up: Top
2286 Installing an Info File
2287 ***********************
2289 Info files are usually kept in the `info' directory. You can read Info
2290 files using the standalone Info program or the Info reader built into
2291 Emacs. (*note info: (info)Top, for an introduction to Info.)
2295 * Directory file:: The top level menu for all Info files.
2296 * New Info File:: Listing a new info file.
2297 * Other Info Directories:: How to specify Info files that are
2298 located in other directories.
2299 * Installing Dir Entries:: How to specify what menu entry to add
2300 to the Info directory.
2301 * Invoking install-info:: `install-info' options.
2304 File: texinfo.info, Node: Directory file, Next: New Info File, Prev: Install an Info File, Up: Install an Info File
2309 For Info to work, the `info' directory must contain a file that
2310 serves as a top level directory for the Info system. By convention,
2311 this file is called `dir'. (You can find the location of this file
2312 within Emacs by typing `C-h i' to enter Info and then typing `C-x C-f'
2313 to see the pathname to the `info' directory.)
2315 The `dir' file is itself an Info file. It contains the top level
2316 menu for all the Info files in the system. The menu looks like this:
2320 * Info: (info). Documentation browsing system.
2321 * Emacs: (emacs). The extensible, self-documenting
2323 * Texinfo: (texinfo). With one source file, make
2324 either a printed manual using
2325 TeX or an Info file.
2328 Each of these menu entries points to the `Top' node of the Info file
2329 that is named in parentheses. (The menu entry does not need to specify
2330 the `Top' node, since Info goes to the `Top' node if no node name is
2331 mentioned. *Note Nodes in Other Info Files: Other Info Files.)
2333 Thus, the `Info' entry points to the `Top' node of the `info' file
2334 and the `Emacs' entry points to the `Top' node of the `emacs' file.
2336 In each of the Info files, the `Up' pointer of the `Top' node refers
2337 back to the `dir' file. For example, the line for the `Top' node of
2338 the Emacs manual looks like this in Info:
2340 File: emacs Node: Top, Up: (DIR), Next: Distrib
2342 (Note that in this case, the `dir' file name is written in upper case
2343 letters--it can be written in either upper or lower case. Info has a
2344 feature that it will change the case of the file name to lower case if
2345 it cannot find the name as written.)
2348 File: texinfo.info, Node: New Info File, Next: Other Info Directories, Prev: Directory file, Up: Install an Info File
2350 Listing a New Info File
2351 =======================
2353 To add a new Info file to your system, you must write a menu entry to
2354 add to the menu in the `dir' file in the `info' directory. For
2355 example, if you were adding documentation for GDB, you would write the
2356 following new entry:
2358 * GDB: (gdb). The source-level C debugger.
2360 The first part of the menu entry is the menu entry name, followed by a
2361 colon. The second part is the name of the Info file, in parentheses,
2362 followed by a period. The third part is the description.
2364 The name of an Info file often has a `.info' extension. Thus, the
2365 Info file for GDB might be called either `gdb' or `gdb.info'. The Info
2366 reader programs automatically try the file name both with and without
2367 `.info'; so it is better to avoid clutter and not to write `.info'
2368 explicitly in the menu entry. For example, the GDB menu entry should
2369 use just `gdb' for the file name, not `gdb.info'.
2372 File: texinfo.info, Node: Other Info Directories, Next: Installing Dir Entries, Prev: New Info File, Up: Install an Info File
2374 Info Files in Other Directories
2375 ===============================
2377 If an Info file is not in the `info' directory, there are three ways to
2378 specify its location:
2380 * Write the pathname in the `dir' file as the second part of the
2383 * If you are using Emacs, list the name of the file in a second `dir'
2384 file, in its directory; and then add the name of that directory to
2385 the `Info-directory-list' variable in your personal or site
2386 initialization file.
2388 This tells Emacs where to look for `dir' files. Emacs merges the
2389 files named `dir' from each of the listed directories. (In Emacs
2390 version 18, you can set the `Info-directory' variable to the name
2391 of only one directory.)
2393 * Specify the Info directory name in the `INFOPATH' environment
2394 variable in your `.profile' or `.cshrc' initialization file.
2395 (Only you and others who set this environment variable will be
2396 able to find Info files whose location is specified this way.)
2398 For example, to reach a test file in the `/home/bob/manuals'
2399 directory, you could add an entry like this to the menu in the `dir'
2402 * Test: (/home/bob/manuals/info-test). Bob's own test file.
2404 In this case, the absolute file name of the `info-test' file is written
2405 as the second part of the menu entry.
2407 Alternatively, you could write the following in your `.emacs' file:
2409 (setq Info-directory-list
2410 '("/home/bob/manuals"
2413 This tells Emacs to merge the `dir' file from the `/home/bob/manuals'
2414 directory with the `dir' file from the `/usr/local/info' directory.
2415 Info will list the `/home/bob/manuals/info-test' file as a menu entry
2416 in the `/home/bob/manuals/dir' file.
2418 Finally, you can tell Info where to look by setting the `INFOPATH'
2419 environment variable in your `.cshrc' or `.profile' file. If you use a
2420 Bourne-compatible shell such as `sh' or `bash' for your shell command
2421 interpreter, you set the `INFOPATH' environment variable in the
2422 `.profile' initialization file; but if you use `csh' or `tcsh', you
2423 must set the variable in the `.cshrc' initialization file. The two
2424 types of shells use different syntax.
2426 * In a `.cshrc' file, you could set the `INFOPATH' variable as
2429 setenv INFOPATH .:~/manuals:/usr/local/emacs/info
2431 * In a `.profile' file, you would achieve the same effect by writing:
2433 INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
2436 The `.' indicates the current directory as usual. Emacs uses the
2437 `INFOPATH' environment variable to initialize the value of Emacs's own
2438 `Info-directory-list' variable.
2440 However you set `INFOPATH', if its last character is a colon, this is
2441 replaced by the default (compiled-in) path. This gives you a way to
2442 augment the default path with new directories without having to list all
2443 the standard places. For example (using `sh' syntax:
2445 INFOPATH=/local/info:
2448 will search `/local/info' first, then the standard directories.
2449 Leading or doubled colons are not treated specially.
2452 File: texinfo.info, Node: Installing Dir Entries, Next: Invoking install-info, Prev: Other Info Directories, Up: Install an Info File
2454 Installing Info Directory Files
2455 ===============================
2457 When you install an Info file onto your system, you can use the program
2458 `install-info' to update the Info directory file `dir'. Normally the
2459 makefile for the package runs `install-info', just after copying the
2460 Info file into its proper installed location.
2462 In order for the Info file to work with `install-info', you should
2463 use the commands `@dircategory' and `@direntry' in the Texinfo source
2464 file. Use `@direntry' to specify the menu entry to add to the Info
2465 directory file, and use `@dircategory' to specify which part of the
2466 Info directory to put it in. Here is how these commands are used in
2469 @dircategory Texinfo documentation system
2471 * Texinfo: (texinfo). The GNU documentation format.
2472 * install-info: (texinfo)Invoking install-info. ...
2476 Here's what this produces in the Info file:
2478 INFO-DIR-SECTION Texinfo documentation system
2479 START-INFO-DIR-ENTRY
2480 * Texinfo: (texinfo). The GNU documentation format.
2481 * install-info: (texinfo)Invoking install-info. ...
2485 The `install-info' program sees these lines in the Info file, and that
2486 is how it knows what to do.
2488 Always use the `@direntry' and `@dircategory' commands near the
2489 beginning of the Texinfo input, before the first `@node' command. If
2490 you use them later on in the input, `install-info' will not notice them.
2492 If you use `@dircategory' more than once in the Texinfo source, each
2493 usage specifies one category; the new menu entry is added to the Info
2494 directory file in each of the categories you specify. If you use
2495 `@direntry' more than once, each usage specifies one menu entry; each
2496 of these menu entries is added to the directory in each of the
2497 specified categories.
2500 File: texinfo.info, Node: Invoking install-info, Prev: Installing Dir Entries, Up: Install an Info File
2502 Invoking install-info
2503 =====================
2505 `install-info' inserts menu entries from an Info file into the
2506 top-level `dir' file in the Info system (see the previous sections for
2507 an explanation of how the `dir' file works). It's most often run as
2508 part of software installation, or when constructing a dir file for all
2509 manuals on a system. Synopsis:
2511 install-info [OPTION]... [INFO-FILE [DIR-FILE]]
2513 If INFO-FILE or DIR-FILE are not specified, the various options
2514 (described below) that define them must be. There are no compile-time
2515 defaults, and standard input is never used. `install-info' can read
2516 only one info file and write only one dir file per invocation.
2518 If DIR-FILE (however specified) does not exist, `install-info'
2519 creates it if possible (with no entries).
2524 Delete the entries in INFO-FILE from DIR-FILE. The file name in
2525 the entry in DIR-FILE must be INFO-FILE (except for an optional
2526 `.info' in either one). Don't insert any new entries.
2529 Specify file name of the Info directory file. This is equivalent
2530 to using the DIR-FILE argument.
2533 Insert TEXT as an Info directory entry; TEXT should have the form
2534 of an Info menu item line plus zero or more extra lines starting
2535 with whitespace. If you specify more than one entry, they are all
2536 added. If you don't specify any entries, they are determined from
2537 information in the Info file itself.
2540 Display a usage message listing basic usage and all available
2541 options, then exit successfully.
2544 Specify Info file to install in the directory. This is equivalent
2545 to using the INFO-FILE argument.
2548 Equivalent to `--dir-file=DIR/dir'.
2551 Same as `--entry=TEXT'. An Info directory entry is actually a
2561 Put this file's entries in section SEC of the directory. If you
2562 specify more than one section, all the entries are added in each
2563 of the sections. If you don't specify any sections, they are
2564 determined from information in the Info file itself.
2567 Display version information and exit successfully.
2571 File: texinfo.info, Node: Command List, Next: Tips, Prev: Install an Info File, Up: Top
2576 Here is an alphabetical list of the @-commands in Texinfo. Square
2577 brackets, [ ], indicate optional arguments; an ellipsis, `...',
2578 indicates repeated text.
2582 An `@' followed by a space, tab, or newline produces a normal,
2583 stretchable, interword space. *Note Multiple Spaces::.
2586 Generate an exclamation point that really does end a sentence
2587 (usually after an end-of-sentence capital letter). *Note Ending a
2592 Generate an umlaut or acute accent, respectively, over the next
2593 character, as in o" and o'. *Note Inserting Accents::.
2596 Force a line break. Do not end a paragraph that uses `@*' with an
2597 `@refill' command. *Note Line Breaks::.
2600 Generate a cedilla accent under C, as in c,. *Note Inserting
2604 Insert a discretionary hyphenation point. *Note - and
2608 Produce a period that really does end a sentence (usually after an
2609 end-of-sentence capital letter). *Note Ending a Sentence::.
2612 Indicate to TeX that an immediately preceding period, question
2613 mark, exclamation mark, or colon does not end a sentence. Prevent
2614 TeX from inserting extra whitespace as it does at the end of a
2615 sentence. The command has no effect on the Info file output.
2616 *Note Not Ending a Sentence::.
2619 Generate a macro (bar) accent over the next character, as in o=.
2620 *Note Inserting Accents::.
2623 Generate a question mark that really does end a sentence (usually
2624 after an end-of-sentence capital letter). *Note Ending a
2628 Stands for an at sign, `@'. *Note Inserting @ and braces: Braces
2633 Generate a circumflex (hat) or grave accent, respectively, over
2634 the next character, as in o^. *Note Inserting Accents::.
2637 Stands for a left brace, `{'. *Note Inserting @ and braces:
2641 Stands for a right-hand brace, `}'.
2642 *Note Inserting @ and braces: Braces Atsigns.
2645 Generate a tilde accent over the next character, as in N~. *Note
2646 Inserting Accents::.
2650 Generate the uppercase and lowercase Scandinavian A-ring letters,
2651 respectively: AA, aa. *Note Inserting Accents::.
2655 Generate the uppercase and lowercase AE ligatures, respectively:
2656 AE, ae. *Note Inserting Accents::.
2659 Change page dimensions for the A4 paper size. Only allowed inside
2660 `@iftex' ... `@end iftex'. *Note A4 Paper::.
2663 Begin an appendix. The title appears in the table of contents of
2664 a printed manual. In Info, the title is underlined with
2665 asterisks. *Note The `@unnumbered' and `@appendix' Commands:
2666 unnumbered & appendix.
2668 `@appendixsec TITLE'
2669 `@appendixsection TITLE'
2670 Begin an appendix section within an appendix. The section title
2671 appears in the table of contents of a printed manual. In Info,
2672 the title is underlined with equal signs. `@appendixsection' is a
2673 longer spelling of the `@appendixsec' command. *Note Section
2674 Commands: unnumberedsec appendixsec heading.
2676 `@appendixsubsec TITLE'
2677 Begin an appendix subsection within an appendix. The title appears
2678 in the table of contents of a printed manual. In Info, the title
2679 is underlined with hyphens. *Note Subsection Commands:
2680 unnumberedsubsec appendixsubsec subheading.
2682 `@appendixsubsubsec TITLE'
2683 Begin an appendix subsubsection within an appendix subsection. The
2684 title appears in the table of contents of a printed manual. In
2685 Info, the title is underlined with periods. *Note The `subsub'
2686 Commands: subsubsection.
2689 Used following `@table', `@ftable', and `@vtable' to print the
2690 table's first column without highlighting ("as is"). *Note Making
2691 a Two-column Table: Two-column Tables.
2694 Typeset AUTHOR flushleft and underline it. *Note The `@title' and
2695 `@author' Commands: title subtitle author.
2698 Print TEXT in bold font. No effect in Info. *Note Fonts::.
2701 Generate a large round dot, or the closest possible thing to one.
2702 *Note `@bullet': bullet.
2705 Stop formatting a file. The formatters do not see the contents of
2706 a file following an `@bye' command. *Note Ending a File::.
2709 Begin a comment in Texinfo. The rest of the line does not appear
2710 in either the Info file or the printed manual. A synonym for
2711 `@comment'. *Note Comments: Comments.
2714 Highlight an example or quotation by drawing a box with rounded
2715 corners around it. Pair with `@end cartouche'. No effect in
2716 Info. *Note Drawing Cartouches Around Examples: cartouche.)
2718 `@center LINE-OF-TEXT'
2719 Center the line of text following the command. *Note `@center':
2720 titlefont center sp.
2722 `@centerchap LINE-OF-TEXT'
2723 Like `@chapter', but centers the chapter title. *Note `@chapter':
2726 `@chapheading TITLE'
2727 Print a chapter-like heading in the text, but not in the table of
2728 contents of a printed manual. In Info, the title is underlined
2729 with asterisks. *Note `@majorheading' and `@chapheading':
2730 majorheading & chapheading.
2733 Begin a chapter. The chapter title appears in the table of
2734 contents of a printed manual. In Info, the title is underlined
2735 with asterisks. *Note `@chapter': chapter.
2738 Add ENTRY to the index of concepts. *Note Defining the Entries of
2739 an Index: Index Entries.
2742 Highlight the name of a book or other reference that lacks a
2743 companion Info file. *Note `@cite': cite.
2746 Unset FLAG, preventing the Texinfo formatting commands from
2747 formatting text between subsequent pairs of `@ifset FLAG' and
2748 `@end ifset' commands, and preventing `@value{FLAG}' from
2749 expanding to the value to which FLAG is set. *Note `@set'
2750 `@clear' `@value': set clear value.
2752 `@code{SAMPLE-CODE}'
2753 Highlight text that is an expression, a syntactically complete
2754 token of a program, or a program name. *Note `@code': code.
2757 Begin a comment in Texinfo. The rest of the line does not appear
2758 in either the Info file or the printed manual. A synonym for `@c'.
2759 *Note Comments: Comments.
2762 Print a complete table of contents. Has no effect in Info, which
2763 uses menus instead. *Note Generating a Table of Contents:
2767 Generate a copyright symbol. *Note `@copyright': copyright symbol.
2769 `@defcodeindex INDEX-NAME'
2770 Define a new index and its indexing command. Print entries in an
2771 `@code' font. *Note Defining New Indices: New Indices.
2773 `@defcv CATEGORY CLASS NAME'
2774 `@defcvx CATEGORY CLASS NAME'
2775 Format a description for a variable associated with a class in
2776 object-oriented programming. Takes three arguments: the category
2777 of thing being defined, the class to which it belongs, and its
2778 name. *Note Definition Commands::, and *Note Def Cmds in Detail:
2781 `@deffn CATEGORY NAME ARGUMENTS...'
2782 `@deffnx CATEGORY NAME ARGUMENTS...'
2783 Format a description for a function, interactive command, or
2784 similar entity that may take arguments. `@deffn' takes as
2785 arguments the category of entity being described, the name of this
2786 particular entity, and its arguments, if any. *Note Definition
2789 `@defindex INDEX-NAME'
2790 Define a new index and its indexing command. Print entries in a
2791 roman font. *Note Defining New Indices: New Indices.
2793 `@definfoenclose NEW-COMMAND, BEFORE, AFTER,'
2794 Create new @-command for Info that marks text by enclosing it in
2795 strings that precede and follow the text. Write definition inside
2796 of `@ifinfo' ... `@end ifinfo'. *Note Customized Highlighting::.
2798 `@defivar CLASS INSTANCE-VARIABLE-NAME'
2799 `@defivarx CLASS INSTANCE-VARIABLE-NAME'
2800 This command formats a description for an instance variable in
2801 object-oriented programming. The command is equivalent to `@defcv
2802 {Instance Variable} ...'. *Note Definition Commands::, and *Note
2803 Def Cmds in Detail: deffnx.
2805 `@defmac MACRO-NAME ARGUMENTS...'
2806 `@defmacx MACRO-NAME ARGUMENTS...'
2807 Format a description for a macro. The command is equivalent to
2808 `@deffn Macro ...'. *Note Definition Commands::, and *Note Def
2809 Cmds in Detail: deffnx.
2811 `@defmethod CLASS METHOD-NAME ARGUMENTS...'
2812 `@defmethodx CLASS METHOD-NAME ARGUMENTS...'
2813 Format a description for a method in object-oriented programming.
2814 The command is equivalent to `@defop Method ...'. Takes as
2815 arguments the name of the class of the method, the name of the
2816 method, and its arguments, if any. *Note Definition Commands::,
2817 and *Note Def Cmds in Detail: deffnx.
2819 `@defop CATEGORY CLASS NAME ARGUMENTS...'
2820 `@defopx CATEGORY CLASS NAME ARGUMENTS...'
2821 Format a description for an operation in object-oriented
2822 programming. `@defop' takes as arguments the overall name of the
2823 category of operation, the name of the class of the operation, the
2824 name of the operation, and its arguments, if any. *Note
2825 Definition Commands::, and *Note Def Cmds in Detail: deffnx.
2827 `@defopt OPTION-NAME'
2828 `@defoptx OPTION-NAME'
2829 Format a description for a user option. The command is equivalent
2830 to `@defvr {User Option} ...'. *Note Definition Commands::, and
2831 *Note Def Cmds in Detail: deffnx.
2833 `@defspec SPECIAL-FORM-NAME ARGUMENTS...'
2834 `@defspecx SPECIAL-FORM-NAME ARGUMENTS...'
2835 Format a description for a special form. The command is
2836 equivalent to `@deffn {Special Form} ...'. *Note Definition
2837 Commands::, and *Note Def Cmds in Detail: deffnx.
2839 `@deftp CATEGORY NAME-OF-TYPE ATTRIBUTES...'
2840 `@deftpx CATEGORY NAME-OF-TYPE ATTRIBUTES...'
2841 Format a description for a data type. `@deftp' takes as arguments
2842 the category, the name of the type (which is a word like `int' or
2843 `float'), and then the names of attributes of objects of that type.
2844 *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
2846 `@deftypefn CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
2847 `@deftypefnx CLASSIFICATION DATA-TYPE NAME ARGUMENTS...'
2848 Format a description for a function or similar entity that may take
2849 arguments and that is typed. `@deftypefn' takes as arguments the
2850 classification of entity being described, the type, the name of the
2851 entity, and its arguments, if any. *Note Definition Commands::,
2852 and *Note Def Cmds in Detail: deffnx.
2854 `@deftypefun DATA-TYPE FUNCTION-NAME ARGUMENTS...'
2855 `@deftypefunx DATA-TYPE FUNCTION-NAME ARGUMENTS...'
2856 Format a description for a function in a typed language. The
2857 command is equivalent to `@deftypefn Function ...'. *Note
2858 Definition Commands::, and *Note Def Cmds in Detail: deffnx.
2860 `@deftypemethod CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
2861 `@deftypemethodx CLASS DATA-TYPE METHOD-NAME ARGUMENTS...'
2862 Format a description for a typed method in object-oriented
2863 programming. Takes as arguments the name of the class of the
2864 method, the return type of the method, the name of the method, and
2865 its arguments, if any. *Note Definition Commands::, and *Note Def
2866 Cmds in Detail: deffnx.
2868 `@deftypevr CLASSIFICATION DATA-TYPE NAME'
2869 `@deftypevrx CLASSIFICATION DATA-TYPE NAME'
2870 Format a description for something like a variable in a typed
2871 language--an entity that records a value. Takes as arguments the
2872 classification of entity being described, the type, and the name
2873 of the entity. *Note Definition Commands::, and *Note Def Cmds in
2876 `@deftypevar DATA-TYPE VARIABLE-NAME'
2877 `@deftypevarx DATA-TYPE VARIABLE-NAME'
2878 Format a description for a variable in a typed language. The
2879 command is equivalent to `@deftypevr Variable ...'. *Note
2880 Definition Commands::, and *Note Def Cmds in Detail: deffnx.
2882 `@defun FUNCTION-NAME ARGUMENTS...'
2883 `@defunx FUNCTION-NAME ARGUMENTS...'
2884 Format a description for functions. The command is equivalent to
2885 `@deffn Function ...'. *Note Definition Commands::, and *Note Def
2886 Cmds in Detail: deffnx.
2888 `@defvar VARIABLE-NAME'
2889 `@defvarx VARIABLE-NAME'
2890 Format a description for variables. The command is equivalent to
2891 `@defvr Variable ...'. *Note Definition Commands::, and *Note Def
2892 Cmds in Detail: deffnx.
2894 `@defvr CATEGORY NAME'
2895 `@defvrx CATEGORY NAME'
2896 Format a description for any kind of variable. `@defvr' takes as
2897 arguments the category of the entity and the name of the entity.
2898 *Note Definition Commands::, and *Note Def Cmds in Detail: deffnx.
2901 Avoid `makeinfo' confusion stemming from the detailed node listing
2902 in a master menu. *Note Master Menu Parts::.
2905 Highlight the introductory or defining use of a term. *Note
2908 `@dircategory DIRPART'
2909 Specify a part of the Info directory menu where this file's entry
2910 should go. *Note Installing Dir Entries::.
2913 Begin the Info directory menu entry for this file. *Note
2914 Installing Dir Entries::.
2917 Begin a kind of example. Indent text, do not fill, do not select a
2918 new font. Pair with `@end display'. *Note `@display': display.
2921 Format a unit of measure, as in 12pt. Causes TeX to insert a thin
2922 space before DIMENSION. No effect in Info. *Note `@dmn': dmn.
2925 Generate a dot accent over the character C, as in oo.. *Note
2926 Inserting Accents::.
2929 Insert an ellipsis: `...'. *Note `@dots{}': dots.
2931 `@email{ADDRESS[, DISPLAYED-TEXT]}'
2932 Indicate an electronic mail address. *Note `@email': email.
2935 Highlight TEXT; text is displayed in _italics_ in printed output,
2936 and surrounded by asterisks in Info. *Note Emphasizing Text:
2940 Ends ENVIRONMENT, as in `@end example'. *Note @-commands:
2941 Formatting Commands.
2944 Generate an end-of-sentence of ellipsis, like this .... *Note
2947 `@enumerate [NUMBER-OR-LETTER]'
2948 Begin a numbered list, using `@item' for each entry. Optionally,
2949 start list with NUMBER-OR-LETTER. Pair with `@end enumerate'.
2950 *Note `@enumerate': enumerate.
2953 Indicate to the reader the exact equivalence of two forms with a
2954 glyph: `=='. *Note Equivalence::.
2957 Indicate to the reader with a glyph that the following text is an
2958 error message: `error-->'. *Note Error Glyph::.
2960 `@evenfooting [LEFT] @| [CENTER] @| [RIGHT]'
2961 `@evenheading [LEFT] @| [CENTER] @| [RIGHT]'
2962 Specify page footings resp. headings for even-numbered (left-hand)
2963 pages. Only allowed inside `@iftex'. *Note How to Make Your Own
2964 Headings: Custom Headings.
2966 `@everyfooting [LEFT] @| [CENTER] @| [RIGHT]'
2967 `@everyheading [LEFT] @| [CENTER] @| [RIGHT]'
2968 Specify page footings resp. headings for every page. Not relevant
2969 to Info. *Note How to Make Your Own Headings: Custom Headings.
2972 Begin an example. Indent text, do not fill, and select
2973 fixed-width font. Pair with `@end example'. *Note `@example':
2977 Produce an upside-down exclamation point. *Note Inserting
2980 `@exdent LINE-OF-TEXT'
2981 Remove any indentation a line might have. *Note Undoing the
2982 Indentation of a Line: exdent.
2985 Indicate the result of a macro expansion to the reader with a
2986 special glyph: `==>'. *Note ==> Indicating an Expansion:
2990 Highlight the name of a file, buffer, node, or directory. *Note
2994 Prevent TeX from printing large black warning rectangles beside
2995 over-wide lines. *Note Overfull hboxes::.
2998 Add ENTRY to the index of functions. *Note Defining the Entries
2999 of an Index: Index Entries.
3003 Left justify every line but leave the right end ragged. Leave
3004 font as is. Pair with `@end flushleft'. `@flushright' analogous.
3005 *Note `@flushleft' and `@flushright': flushleft & flushright.
3007 `@footnote{TEXT-OF-FOOTNOTE}'
3008 Enter a footnote. Footnote text is printed at the bottom of the
3009 page by TeX; Info may format in either `End' node or `Separate'
3010 node style. *Note Footnotes::.
3012 `@footnotestyle STYLE'
3013 Specify an Info file's footnote style, either `end' for the end
3014 node style or `separate' for the separate node style. *Note
3018 Begin a kind of example. Like `@example' or `@display', but do
3019 not narrow the margins and do not select the fixed-width font.
3020 Pair with `@end format'. *Note `@example': example.
3022 `@ftable FORMATTING-COMMAND'
3023 Begin a two-column table, using `@item' for each entry.
3024 Automatically enter each of the items in the first column into the
3025 index of functions. Pair with `@end ftable'. The same as
3026 `@table', except for indexing. *Note `@ftable' and `@vtable':
3030 Hold text together that must appear on one printed page. Pair with
3031 `@end group'. Not relevant to Info. *Note `@group': group.
3034 Generate the long Hungarian umlaut accent over C, as in o''.
3037 Print an unnumbered section-like heading in the text, but not in
3038 the table of contents of a printed manual. In Info, the title is
3039 underlined with equal signs. *Note Section Commands:
3040 unnumberedsec appendixsec heading.
3042 `@headings ON-OFF-SINGLE-DOUBLE'
3043 Turn page headings on or off, and/or specify single-sided or
3044 double-sided page headings for printing. *Note The `@headings'
3045 Command: headings on off.
3048 Enter HTML completely. Pair with `@end html'. *Note Raw
3049 Formatter Commands::.
3051 `@hyphenation{HY-PHEN-A-TED WORDS}'
3052 Explicitly define hyphenation points. *Note `@-' and
3053 `@hyphenation': - and hyphenation.
3056 Print TEXT in italic font. No effect in Info. *Note Fonts::.
3059 If FLAG is cleared, the Texinfo formatting commands format text
3060 between `@ifclear FLAG' and the following `@end ifclear' command.
3061 *Note `@set' `@clear' `@value': set clear value.
3065 Begin a stretch of text that will be ignored by TeX when it
3066 typesets the printed manual. The text appears only in the HTML
3067 resp. Info file. Pair with `@end ifhtml' resp. `@end ifinfo'.
3068 *Note Conditionals::.
3073 Begin a stretch of text that will be ignored in one output format
3074 but not the others. The text appears only in the format not
3075 specified. Pair with `@end ifnothtml' resp. `@end ifnotinfo' resp.
3076 `@end ifnotinfo'. *Note Conditionals::.
3079 If FLAG is set, the Texinfo formatting commands format text
3080 between `@ifset FLAG' and the following `@end ifset' command.
3081 *Note `@set' `@clear' `@value': set clear value.
3084 Begin a stretch of text that will not appear in the Info file, but
3085 will be processed only by TeX. Pair with `@end iftex'. *Note
3086 Conditionally Visible Text: Conditionals.
3089 Begin a stretch of text that will not appear in either the Info
3090 file or the printed output. Pair with `@end ignore'. *Note
3091 Comments and Ignored Text: Comments.
3093 `@image{FILENAME, [WIDTH], [HEIGHT]}'
3094 Include graphics image in external FILENAME scaled to the given
3095 WIDTH and/or HEIGHT. *Note Images::.
3098 Incorporate the contents of the file FILENAME into the Info file
3099 or printed document. *Note Include Files::.
3101 `@inforef{NODE-NAME, [ENTRY-NAME], INFO-FILE-NAME}'
3102 Make a cross reference to an Info file for which there is no
3103 printed manual. *Note Cross references using `@inforef': inforef.
3105 `\input MACRO-DEFINITIONS-FILE'
3106 Use the specified macro definitions file. This command is used
3107 only in the first line of a Texinfo file to cause TeX to make use
3108 of the `texinfo' macro definitions file. The backslash in `\input'
3109 is used instead of an `@' because TeX does not recognize `@' until
3110 after it has read the definitions file. *Note The Texinfo File
3114 Indicate the beginning of a marked paragraph for `@itemize' and
3115 `@enumerate'; indicate the beginning of the text of a first column
3116 entry for `@table', `@ftable', and `@vtable'. *Note Lists and
3119 `@itemize MARK-GENERATING-CHARACTER-OR-COMMAND'
3120 Produce a sequence of indented paragraphs, with a mark inside the
3121 left margin at the beginning of each paragraph. Pair with `@end
3122 itemize'. *Note `@itemize': itemize.
3125 Like `@item' but do not generate extra vertical space above the
3126 item text. *Note `@itemx': itemx.
3128 `@kbd{KEYBOARD-CHARACTERS}'
3129 Indicate text that is characters of input to be typed by users.
3132 `@kbdinputstyle STYLE'
3133 Specify when `@kbd' should use a font distinct from `@code'.
3137 Indicate a name for a key on a keyboard. *Note `@key': key.
3140 Add ENTRY to the index of keys. *Note Defining the Entries of an
3141 Index: Index Entries.
3145 Generate the uppercase and lowercase Polish suppressed-L letters,
3146 respectively: /L, /l.
3149 Begin an example of Lisp code. Indent text, do not fill, and
3150 select fixed-width font. Pair with `@end lisp'. *Note `@lisp':
3154 Change subsequent chapters to sections, sections to subsections,
3155 and so on. *Note `@raisesections' and `@lowersections':
3156 Raise/lower sections.
3158 `@macro MACRO-NAME {PARAMS}'
3159 Define a new Texinfo command `@MACRO-NAME{PARAMS}'. Only
3160 supported by `makeinfo' and `texi2dvi'. *Note Defining Macros::.
3162 `@majorheading TITLE'
3163 Print a chapter-like heading in the text, but not in the table of
3164 contents of a printed manual. Generate more vertical whitespace
3165 before the heading than the `@chapheading' command. In Info, the
3166 chapter heading line is underlined with asterisks. *Note
3167 `@majorheading' and `@chapheading': majorheading & chapheading.
3169 `@math{MATHEMATICAL-EXPRESSION}'
3170 Format a mathematical expression. *Note `@math' - Inserting
3171 Mathematical Expressions: math.
3174 Mark the beginning of a menu of nodes in Info. No effect in a
3175 printed manual. Pair with `@end menu'. *Note Menus::.
3178 Generate a minus sign, `-'. *Note `@minus': minus.
3180 `@multitable COLUMN-WIDTH-SPEC'
3181 Begin a multi-column table. Pair with `@end multitable'. *Note
3182 Multitable Column Widths::.
3185 Start a new page in a printed manual if fewer than N mils
3186 (thousandths of an inch) remain on the current page. *Note
3189 `@node NAME, NEXT, PREVIOUS, UP'
3190 Define the beginning of a new node in Info, and serve as a locator
3191 for references for TeX. *Note `@node': node.
3194 Prevent text from being indented as if it were a new paragraph.
3195 *Note `@noindent': noindent.
3199 Generate the uppercase and lowercase O-with-slash letters,
3200 respectively: /O, /o.
3202 `@oddfooting [LEFT] @| [CENTER] @| [RIGHT]'
3203 `@oddheading [LEFT] @| [CENTER] @| [RIGHT]'
3204 Specify page footings resp. headings for odd-numbered (right-hand)
3205 pages. Only allowed inside `@iftex'. *Note How to Make Your Own
3206 Headings: Custom Headings.
3210 Generate the uppercase and lowercase OE ligatures, respectively:
3211 OE, oe. *Note Inserting Accents::.
3214 Start a new page in a printed manual. No effect in Info. *Note
3217 `@paragraphindent INDENT'
3218 Indent paragraphs by INDENT number of spaces; delete indentation
3219 if the value of INDENT is 0; and do not change indentation if
3220 INDENT is `asis'. *Note Paragraph Indenting: paragraphindent.
3223 Add ENTRY to the index of programs. *Note Defining the Entries of
3224 an Index: Index Entries.
3227 Indicate the position of point in a buffer to the reader with a
3228 glyph: `-!-'. *Note Indicating Point in a Buffer: Point Glyph.
3231 Generate the pounds sterling currency sign. *Note `@pounds{}':
3235 Indicate printed output to the reader with a glyph: `-|'. *Note
3238 `@printindex INDEX-NAME'
3239 Print an alphabetized two-column index in a printed manual or
3240 generate an alphabetized menu of index entries for Info. *Note
3241 Printing Indices & Menus::.
3243 `@pxref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
3244 Make a reference that starts with a lower case `see' in a printed
3245 manual. Use within parentheses only. Do not follow command with a
3246 punctuation mark--the Info formatting commands automatically insert
3247 terminating punctuation as needed. Only the first argument is
3248 mandatory. *Note `@pxref': pxref.
3251 Generate an upside-down question mark. *Note Inserting Accents::.
3254 Narrow the margins to indicate text that is quoted from another
3255 real or imaginary work. Write command on a line of its own. Pair
3256 with `@end quotation'. *Note `@quotation': quotation.
3259 Print TEXT in roman font. No effect in Info. *Note Fonts::.
3262 Change subsequent sections to chapters, subsections to sections,
3263 and so on. *Note `@raisesections' and `@lowersections':
3264 Raise/lower sections.
3266 `@ref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
3267 Make a reference. In a printed manual, the reference does not
3268 start with a `See'. Follow command with a punctuation mark. Only
3269 the first argument is mandatory. *Note `@ref': ref.
3272 In Info, refill and indent the paragraph after all the other
3273 processing has been done. No effect on TeX, which always refills.
3274 This command is no longer needed, since all formatters now
3275 automatically refill. *Note Refilling Paragraphs::.
3278 Indicate the result of an expression to the reader with a special
3279 glyph: `=>'. *Note `@result': result.
3282 Generate a ring accent over the next character, as in o*. *Note
3283 Inserting Accents::.
3286 Highlight TEXT that is a literal example of a sequence of
3287 characters. Used for single characters, for statements, and often
3288 for entire shell commands. *Note `@samp': samp.
3291 Set TEXT in a printed output in THE SMALL CAPS FONT and set text
3292 in the Info file in uppercase letters. *Note Smallcaps::.
3295 Begin a section within a chapter. In a printed manual, the section
3296 title is numbered and appears in the table of contents. In Info,
3297 the title is underlined with equal signs. *Note `@section':
3300 `@set FLAG [STRING]'
3301 Make FLAG active, causing the Texinfo formatting commands to
3302 format text between subsequent pairs of `@ifset FLAG' and `@end
3303 ifset' commands. Optionally, set value of FLAG to STRING. *Note
3304 `@set' `@clear' `@value': set clear value.
3306 `@setchapternewpage ON-OFF-ODD'
3307 Specify whether chapters start on new pages, and if so, whether on
3308 odd-numbered (right-hand) new pages. *Note `@setchapternewpage':
3311 `@setfilename INFO-FILE-NAME'
3312 Provide a name to be used by the Info file. This command is
3313 essential for TeX formatting as well, even though it produces no
3314 output. *Note `@setfilename': setfilename.
3317 Provide a title for page headers in a printed manual. *Note
3318 `@settitle': settitle.
3321 Print a short table of contents. Not relevant to Info, which uses
3322 menus rather than tables of contents. A synonym for
3323 `@summarycontents'. *Note Generating a Table of Contents:
3326 `@shorttitlepage{TITLE}'
3327 Generate a minimal title page. *Note `@titlepage': titlepage.
3330 Cause TeX to produce a printed manual in a 7 by 9.25 inch format
3331 rather than the regular 8.5 by 11 inch format. *Note Printing
3332 Small Books: smallbook. Also, see *Note `@smallexample' and
3333 `@smalllisp': smallexample & smalllisp.
3336 Indent text to indicate an example. Do not fill, select
3337 fixed-width font. In `@smallbook' format, print text in a smaller
3338 font than with `@example'. Pair with `@end smallexample'. *Note
3339 `@smallexample' and `@smalllisp': smallexample & smalllisp.
3342 Begin an example of Lisp code. Indent text, do not fill, select
3343 fixed-width font. In `@smallbook' format, print text in a smaller
3344 font. Pair with `@end smalllisp'. *Note `@smallexample' and
3345 `@smalllisp': smallexample & smalllisp.
3348 Skip N blank lines. *Note `@sp': sp.
3351 Generate the German sharp-S es-zet letter, ss. *Note Inserting
3355 Emphasize TEXT by typesetting it in a *bold* font for the printed
3356 manual and by surrounding it with asterisks for Info. *Note
3357 Emphasizing Text: emph & strong.
3360 Print an unnumbered subsection-like heading in the text, but not in
3361 the table of contents of a printed manual. In Info, the title is
3362 underlined with hyphens. *Note `@unnumberedsubsec'
3363 `@appendixsubsec' `@subheading': unnumberedsubsec appendixsubsec
3367 Begin a subsection within a section. In a printed manual, the
3368 subsection title is numbered and appears in the table of contents.
3369 In Info, the title is underlined with hyphens. *Note
3370 `@subsection': subsection.
3372 `@subsubheading TITLE'
3373 Print an unnumbered subsubsection-like heading in the text, but
3374 not in the table of contents of a printed manual. In Info, the
3375 title is underlined with periods. *Note The `subsub' Commands:
3378 `@subsubsection TITLE'
3379 Begin a subsubsection within a subsection. In a printed manual,
3380 the subsubsection title is numbered and appears in the table of
3381 contents. In Info, the title is underlined with periods. *Note
3382 The `subsub' Commands: subsubsection.
3385 In a printed manual, set a subtitle in a normal sized font flush to
3386 the right-hand side of the page. Not relevant to Info, which does
3387 not have title pages. *Note `@title' `@subtitle' and `@author'
3388 Commands: title subtitle author.
3391 Print a short table of contents. Not relevant to Info, which uses
3392 menus rather than tables of contents. A synonym for
3393 `@shortcontents'. *Note Generating a Table of Contents: Contents.
3395 `@syncodeindex FROM-INDEX INTO-INDEX'
3396 Merge the index named in the first argument into the index named in
3397 the second argument, printing the entries from the first index in
3398 `@code' font. *Note Combining Indices::.
3400 `@synindex FROM-INDEX INTO-INDEX'
3401 Merge the index named in the first argument into the index named in
3402 the second argument. Do not change the font of FROM-INDEX
3403 entries. *Note Combining Indices::.
3406 Print TEXT in a fixed-width, typewriter-like font. No effect in
3407 Info. *Note Fonts::.
3410 Separate columns in a multitable. *Note Multitable Rows::.
3412 `@table FORMATTING-COMMAND'
3413 Begin a two-column table, using `@item' for each entry. Write
3414 each first column entry on the same line as `@item'. First column
3415 entries are printed in the font resulting from FORMATTING-COMMAND.
3416 Pair with `@end table'. *Note Making a Two-column Table:
3417 Two-column Tables. Also see *Note `@ftable' and `@vtable': ftable
3418 vtable, and *Note `@itemx': itemx.
3421 Insert the logo TeX. *Note Inserting TeX and (C): TeX and
3425 Enter TeX completely. Pair with `@end tex'. *Note Raw Formatter
3433 Only allowed in a heading or footing. Stands for the number and
3434 name of the current chapter (in the format `Chapter 1: Title'),
3435 the chapter name only, the filename, the current page number, and
3436 the title of the document, respectively. *Note How to Make Your
3437 Own Headings: Custom Headings.
3440 Generate a tie-after accent over the next two characters CC, as in
3441 `oo['. *Note Inserting Accents::.
3444 Add ENTRY to the index of data types. *Note Defining the Entries
3445 of an Index: Index Entries.
3448 In a printed manual, set a title flush to the left-hand side of the
3449 page in a larger than normal font and underline it with a black
3450 rule. Not relevant to Info, which does not have title pages.
3451 *Note The `@title' `@subtitle' and `@author' Commands: title
3455 In a printed manual, print TEXT in a larger than normal font. Not
3456 relevant to Info, which does not have title pages. *Note The
3457 `@titlefont' `@center' and `@sp' Commands: titlefont center sp.
3460 Indicate to Texinfo the beginning of the title page. Write
3461 command on a line of its own. Pair with `@end titlepage'.
3462 Nothing between `@titlepage' and `@end titlepage' appears in Info.
3463 *Note `@titlepage': titlepage.
3466 Insert the current date, in `1 Jan 1900' style. *Note How to Make
3467 Your Own Headings: Custom Headings.
3470 In a Texinfo file to be formatted with `makeinfo', identify the
3471 topmost `@node' line in the file, which must be written on the line
3472 immediately preceding the `@top' command. Used for `makeinfo''s
3473 node pointer insertion feature. The title is underlined with
3474 asterisks. Both the `@node' line and the `@top' line normally
3475 should be enclosed by `@ifinfo' and `@end ifinfo'. In TeX and
3476 `texinfo-format-buffer', the `@top' command is merely a synonym
3477 for `@unnumbered'. *Note Creating Pointers with `makeinfo':
3478 makeinfo Pointer Creation.
3483 Generate a breve, underbar, or underdot accent, respectively, over
3484 or under the character C, as in o(, o_, .o. *Note Inserting
3488 In a printed manual, begin a chapter that appears without chapter
3489 numbers of any kind. The title appears in the table of contents
3490 of a printed manual. In Info, the title is underlined with
3491 asterisks. *Note `@unnumbered' and `@appendix': unnumbered &
3494 `@unnumberedsec TITLE'
3495 In a printed manual, begin a section that appears without section
3496 numbers of any kind. The title appears in the table of contents
3497 of a printed manual. In Info, the title is underlined with equal
3498 signs. *Note Section Commands: unnumberedsec appendixsec heading.
3500 `@unnumberedsubsec TITLE'
3501 In a printed manual, begin an unnumbered subsection within a
3502 chapter. The title appears in the table of contents of a printed
3503 manual. In Info, the title is underlined with hyphens. *Note
3504 `@unnumberedsubsec' `@appendixsubsec' `@subheading':
3505 unnumberedsubsec appendixsubsec subheading.
3507 `@unnumberedsubsubsec TITLE'
3508 In a printed manual, begin an unnumbered subsubsection within a
3509 chapter. The title appears in the table of contents of a printed
3510 manual. In Info, the title is underlined with periods. *Note The
3511 `subsub' Commands: subsubsection.
3513 `@uref{URL[, DISPLAYED-TEXT}'
3514 Define a cross reference to an external uniform resource locator
3515 for the World Wide Web. *Note `@url': url.
3518 Indicate text that is a uniform resource locator for the World Wide
3519 Web. *Note `@url': url.
3522 Generate check accent over the character C, as in o<. *Note
3523 Inserting Accents::.
3526 Replace FLAG with the value to which it is set by `@set FLAG'.
3527 *Note `@set' `@clear' `@value': set clear value.
3529 `@var{METASYNTACTIC-VARIABLE}'
3530 Highlight a metasyntactic variable, which is something that stands
3531 for another piece of text. *Note Indicating Metasyntactic
3535 Add ENTRY to the index of variables. *Note Defining the Entries
3536 of an Index: Index Entries.
3539 In a printed manual, insert whitespace so as to push text on the
3540 remainder of the page towards the bottom of the page. Used in
3541 formatting the copyright page with the argument `0pt plus 1filll'.
3542 (Note spelling of `filll'.) `@vskip' may be used only in
3543 contexts ignored for Info. *Note The Copyright Page and Printed
3544 Permissions: Copyright & Permissions.
3546 `@vtable FORMATTING-COMMAND'
3547 Begin a two-column table, using `@item' for each entry.
3548 Automatically enter each of the items in the first column into the
3549 index of variables. Pair with `@end vtable'. The same as
3550 `@table', except for indexing. *Note `@ftable' and `@vtable':
3554 Prevent TEXT from being split across two lines. Do not end a
3555 paragraph that uses `@w' with an `@refill' command. *Note `@w': w.
3557 `@xref{NODE-NAME, [ENTRY], [TOPIC-OR-TITLE], [INFO-FILE], [MANUAL]}'
3558 Make a reference that starts with `See' in a printed manual.
3559 Follow command with a punctuation mark. Only the first argument is
3560 mandatory. *Note `@xref': xref.
3563 File: texinfo.info, Node: Tips, Next: Sample Texinfo File, Prev: Command List, Up: Top
3568 Here are some tips for writing Texinfo documentation:
3570 * Write in the present tense, not in the past or the future.
3572 * Write actively! For example, write "We recommend that ..." rather
3573 than "It is recommended that ...".
3575 * Use 70 or 72 as your fill column. Longer lines are hard to read.
3577 * Include a copyright notice and copying permissions.
3579 Index, Index, Index!
3580 ....................
3582 Write many index entries, in different ways. Readers like indices;
3583 they are helpful and convenient.
3585 Although it is easiest to write index entries as you write the body of
3586 the text, some people prefer to write entries afterwards. In either
3587 case, write an entry before the paragraph to which it applies. This
3588 way, an index entry points to the first page of a paragraph that is
3591 Here are more hints we have found valuable:
3593 * Write each index entry differently, so each entry refers to a
3594 different place in the document.
3596 * Write index entries only where a topic is discussed significantly.
3597 For example, it is not useful to index "debugging information" in
3598 a chapter on reporting bugs. Someone who wants to know about
3599 debugging information will certainly not find it in that chapter.
3601 * Consistently capitalize the first word of every concept index
3602 entry, or else consistently use lower case. Terse entries often
3603 call for lower case; longer entries for capitalization. Whichever
3604 case convention you use, please use one or the other consistently!
3605 Mixing the two styles looks bad.
3607 * Always capitalize or use upper case for those words in an index for
3608 which this is proper, such as names of countries or acronyms.
3609 Always use the appropriate case for case-sensitive names, such as
3612 * Write the indexing commands that refer to a whole section
3613 immediately after the section command, and write the indexing
3614 commands that refer to the paragraph before the paragraph.
3616 In the example that follows, a blank line comes after the index
3617 entry for "Leaping":
3619 @section The Dog and the Fox
3620 @cindex Jumping, in general
3623 @cindex Dog, lazy, jumped over
3624 @cindex Lazy dog jumped over
3625 @cindex Fox, jumps over dog
3626 @cindex Quick fox jumps over dog
3627 The quick brown fox jumps over the lazy dog.
3629 (Note that the example shows entries for the same concept that are
3630 written in different ways--`Lazy dog', and `Dog, lazy'--so readers
3631 can look up the concept in different ways.)
3636 * Insert a blank line between a sectioning command and the first
3637 following sentence or paragraph, or between the indexing commands
3638 associated with the sectioning command and the first following
3639 sentence or paragraph, as shown in the tip on indexing.
3640 Otherwise, a formatter may fold title and paragraph together.
3642 * Always insert a blank line before an `@table' command and after an
3643 `@end table' command; but never insert a blank line after an
3644 `@table' command or before an `@end table' command.
3652 Jump over lazy dogs.
3655 Also jump over lazy dogs.
3658 On the other hand, ...
3660 Insert blank lines before and after `@itemize' ... `@end itemize'
3661 and `@enumerate' ... `@end enumerate' in the same way.
3666 Complete phrases are easier to read than ...
3668 * Write entries in an itemized list as complete sentences; or at
3669 least, as complete phrases. Incomplete expressions ... awkward
3672 * Write the prefatory sentence or phrase for a multi-item list or
3673 table as a complete expression. Do not write "You can set:";
3674 instead, write "You can set these variables:". The former
3675 expression sounds cut off.
3677 Editions, Dates and Versions
3678 ............................
3680 Write the edition and version numbers and date in three places in every
3683 1. In the first `@ifinfo' section, for people reading the Texinfo
3686 2. In the `@titlepage' section, for people reading the printed manual.
3688 3. In the `Top' node, for people reading the Info file.
3690 Also, it helps to write a note before the first `@ifinfo' section to
3691 explain what you are doing.
3696 @c Specify the edition and version numbers and date
3697 @c in *three* places:
3698 @c 1. First ifinfo section 2. title page 3. top node
3699 @c To find the locations, search for !!set
3702 @c !!set edition, date, version
3703 This is Edition 4.03, January 1992,
3704 of the @cite{GDB Manual} for GDB Version 4.3.
3707 --or use `@set' and `@value' (*note `@value' Example: value Example.).
3712 Definition commands are `@deffn', `@defun', `@defmac', and the like,
3713 and enable you to write descriptions in a uniform format.
3715 * Write just one definition command for each entity you define with a
3716 definition command. The automatic indexing feature creates an
3717 index entry that leads the reader to the definition.
3719 * Use `@table' ... `@end table' in an appendix that contains a
3720 summary of functions, not `@deffn' or other definition commands.
3725 * Capitalize "Texinfo"; it is a name. Do not write the `x' or `i'
3728 * Capitalize "Info"; it is a name.
3730 * Write TeX using the `@TeX{}' command. Note the uppercase `T' and
3731 `X'. This command causes the formatters to typeset the name
3732 according to the wishes of Donald Knuth, who wrote TeX.
3737 Do not use spaces to format a Texinfo file, except inside of `@example'
3738 ... `@end example' and similar commands.
3740 For example, TeX fills the following:
3743 @kbd{M-x vc-next-action}
3744 Perform the next logical operation
3745 on the version-controlled file
3746 corresponding to the current buffer.
3748 so it looks like this:
3750 `C-x v' `M-x vc-next-action' Perform the next logical operation on
3751 the version-controlled file corresponding to the current buffer.
3753 In this case, the text should be formatted with `@table', `@item', and
3754 `@itemx', to create a table.
3756 @code, @samp, @var, and `---'
3757 .............................
3759 * Use `@code' around Lisp symbols, including command names. For
3762 The main function is @code{vc-next-action}, ...
3764 * Avoid putting letters such as `s' immediately after an `@code'.
3765 Such letters look bad.
3767 * Use `@var' around meta-variables. Do not write angle brackets
3770 * Use three hyphens in a row, `---', to indicate a long dash. TeX
3771 typesets these as a long dash and the Info formatters reduce three
3774 Periods Outside of Quotes
3775 .........................
3777 Place periods and other punctuation marks _outside_ of quotations,
3778 unless the punctuation is part of the quotation. This practice goes
3779 against publishing conventions in the United States, but enables the
3780 reader to distinguish between the contents of the quotation and the
3783 For example, you should write the following sentence with the period
3784 outside the end quotation marks:
3786 Evidently, `au' is an abbreviation for ``author''.
3788 since `au' does _not_ serve as an abbreviation for `author.' (with a
3789 period following the word).
3791 Introducing New Terms
3792 .....................
3794 * Introduce new terms so that a reader who does not know them can
3795 understand them from context; or write a definition for the term.
3797 For example, in the following, the terms "check in", "register" and
3798 "delta" are all appearing for the first time; the example sentence
3799 should be rewritten so they are understandable.
3801 The major function assists you in checking in a file to your
3802 version control system and registering successive sets of
3803 changes to it as deltas.
3805 * Use the `@dfn' command around a word being introduced, to indicate
3806 that the reader should not expect to know the meaning already, and
3807 should expect to learn the meaning from this passage.
3812 Absolutely never use `@pxref' except in the special context for which
3813 it is designed: inside parentheses, with the closing parenthesis
3814 following immediately after the closing brace. One formatter
3815 automatically inserts closing punctuation and the other does not. This
3816 means that the output looks right both in printed output and in an Info
3817 file, but only when the command is used inside parentheses.
3819 Invoking from a Shell
3820 .....................
3822 You can invoke programs such as Emacs, GCC, and `gawk' from a shell.
3823 The documentation for each program should contain a section that
3824 describes this. Unfortunately, if the node names and titles for these
3825 sections are all different, readers find it hard to search for the
3828 Name such sections with a phrase beginning with the word
3829 `Invoking ...', as in `Invoking Emacs'; this way users can find the
3835 When you use `@example' to describe a C function's calling conventions,
3836 use the ANSI C syntax, like this:
3838 void dld_init (char *@var{path});
3840 And in the subsequent discussion, refer to the argument values by
3841 writing the same argument names, again highlighted with `@var'.
3843 Avoid the obsolete style that looks like this:
3850 Also, it is best to avoid writing `#include' above the declaration
3851 just to indicate that the function is declared in a header file. The
3852 practice may give the misimpression that the `#include' belongs near
3853 the declaration of the function. Either state explicitly which header
3854 file holds the declaration or, better yet, name the header file used
3855 for a group of functions at the beginning of the section that describes
3861 Here are several examples of bad writing to avoid:
3863 In this example, say, " ... you must `@dfn'{check in} the new
3864 version." That flows better.
3866 When you are done editing the file, you must perform a
3869 In the following example, say, "... makes a unified interface such as
3872 SCCS, RCS and other version-control systems all perform similar
3873 functions in broadly similar ways (it is this resemblance which
3874 makes a unified control mode like this possible).
3876 And in this example, you should specify what `it' refers to:
3878 If you are working with other people, it assists in coordinating
3879 everyone's changes so they do not step on each other.
3884 * Pronounce TeX as if the `X' were a Greek `chi', as the last sound
3885 in the name `Bach'. But pronounce Texinfo as in `speck':
3888 * Write notes for yourself at the very end of a Texinfo file after
3889 the `@bye'. None of the formatters process text after the `@bye';
3890 it is as if the text were within `@ignore' ... `@end ignore'.
3893 File: texinfo.info, Node: Sample Texinfo File, Next: Sample Permissions, Prev: Tips, Up: Top
3895 A Sample Texinfo File
3896 *********************
3898 Here is a complete, short sample Texinfo file, without any commentary.
3899 You can see this file, with comments, in the first chapter. *Note A
3900 Short Sample Texinfo File: Short Sample.
3903 \input texinfo @c -*-texinfo-*-
3904 @c %**start of header
3905 @setfilename sample.info
3906 @settitle Sample Document
3909 @setchapternewpage odd
3912 This is a short example of a complete Texinfo file.
3914 Copyright 1990 Free Software Foundation, Inc.
3919 @comment The title is printed in a large font.
3920 @center @titlefont{Sample Title}
3922 @c The following two commands start the copyright page.
3924 @vskip 0pt plus 1filll
3925 Copyright @copyright{} 1990 Free Software Foundation, Inc.
3928 @node Top, First Chapter, , (dir)
3929 @comment node-name, next, previous, up
3932 * First Chapter:: The first chapter is the
3933 only chapter in this sample.
3934 * Concept Index:: This index has two entries.
3937 @node First Chapter, Concept Index, Top, Top
3938 @comment node-name, next, previous, up
3939 @chapter First Chapter
3940 @cindex Sample index entry
3942 This is the contents of the first chapter.
3943 @cindex Another sample index entry
3945 Here is a numbered list.
3949 This is the first item.
3952 This is the second item.
3955 The @code{makeinfo} and @code{texinfo-format-buffer}
3956 commands transform a Texinfo file such as this into
3957 an Info file; and @TeX{} typesets it for a printed
3960 @node Concept Index, , First Chapter, Top
3961 @comment node-name, next, previous, up
3962 @unnumbered Concept Index
3970 File: texinfo.info, Node: Sample Permissions, Next: Include Files, Prev: Sample Texinfo File, Up: Top
3975 Texinfo files should contain sections that tell the readers that they
3976 have the right to copy and distribute the Texinfo file, the Info file,
3977 and the printed manual.
3979 Also, if you are writing a manual about software, you should explain
3980 that the software is free and either include the GNU General Public
3981 License (GPL) or provide a reference to it. *Note Distribution:
3982 (xemacs)Distrib, for an example of the text that could be used in the
3983 software "Distribution", "General Public License", and "NO WARRANTY"
3984 sections of a document. *Note Texinfo Copying Conditions: Copying, for
3985 an example of a brief explanation of how the copying conditions provide
3990 * Inserting Permissions:: How to put permissions in your document.
3991 * ifinfo Permissions:: Sample `ifinfo' copying permissions.
3992 * Titlepage Permissions:: Sample Titlepage copying permissions.
3995 File: texinfo.info, Node: Inserting Permissions, Next: ifinfo Permissions, Prev: Sample Permissions, Up: Sample Permissions
3997 Inserting Permissions
3998 =====================
4000 In a Texinfo file, the first `@ifinfo' section usually begins with a
4001 line that says what the file documents. This is what a person reading
4002 the unprocessed Texinfo file or using the advanced Info command `g *'
4003 sees first. *note Advanced Info commands: (info)Expert, for more
4004 information. (A reader using the regular Info commands usually starts
4005 reading at the first node and skips this first section, which is not in
4008 In the `@ifinfo' section, the summary sentence is followed by a
4009 copyright notice and then by the copying permission notice. One of the
4010 copying permission paragraphs is enclosed in `@ignore' and `@end
4011 ignore' commands. This paragraph states that the Texinfo file can be
4012 processed through TeX and printed, provided the printed manual carries
4013 the proper copying permission notice. This paragraph is not made part
4014 of the Info file since it is not relevant to the Info file; but it is a
4015 mandatory part of the Texinfo file since it permits people to process
4016 the Texinfo file in TeX and print the results.
4018 In the printed manual, the Free Software Foundation copying permission
4019 notice follows the copyright notice and publishing information and is
4020 located within the region delineated by the `@titlepage' and `@end
4021 titlepage' commands. The copying permission notice is exactly the same
4022 as the notice in the `@ifinfo' section except that the paragraph
4023 enclosed in `@ignore' and `@end ignore' commands is not part of the
4026 To make it simple to insert a permission notice into each section of
4027 the Texinfo file, sample permission notices for each section are
4028 reproduced in full below.
4030 Note that you may need to specify the correct name of a section
4031 mentioned in the permission notice. For example, in `The GDB Manual',
4032 the name of the section referring to the General Public License is
4033 called the "GDB General Public License", but in the sample shown below,
4034 that section is referred to generically as the "GNU General Public
4035 License". If the Texinfo file does not carry a copy of the General
4036 Public License, leave out the reference to it, but be sure to include
4037 the rest of the sentence.
4040 File: texinfo.info, Node: ifinfo Permissions, Next: Titlepage Permissions, Prev: Inserting Permissions, Up: Sample Permissions
4042 `ifinfo' Copying Permissions
4043 ============================
4045 In the `@ifinfo' section of a Texinfo file, the standard Free Software
4046 Foundation permission notice reads as follows:
4048 This file documents ...
4050 Copyright 1998 Free Software Foundation, Inc.
4052 Permission is granted to make and distribute verbatim
4053 copies of this manual provided the copyright notice and
4054 this permission notice are preserved on all copies.
4057 Permission is granted to process this file through TeX
4058 and print the results, provided the printed document
4059 carries a copying permission notice identical to this
4060 one except for the removal of this paragraph (this
4061 paragraph not being relevant to the printed manual).
4064 Permission is granted to copy and distribute modified
4065 versions of this manual under the conditions for
4066 verbatim copying, provided also that the sections
4067 entitled ``Copying'' and ``GNU General Public License''
4068 are included exactly as in the original, and provided
4069 that the entire resulting derived work is distributed
4070 under the terms of a permission notice identical to this
4073 Permission is granted to copy and distribute
4074 translations of this manual into another language,
4075 under the above conditions for modified versions,
4076 except that this permission notice may be stated in a
4077 translation approved by the Free Software Foundation.
4080 File: texinfo.info, Node: Titlepage Permissions, Prev: ifinfo Permissions, Up: Sample Permissions
4082 Titlepage Copying Permissions
4083 =============================
4085 In the `@titlepage' section of a Texinfo file, the standard Free
4086 Software Foundation copying permission notice follows the copyright
4087 notice and publishing information. The standard phrasing is as follows:
4089 Permission is granted to make and distribute verbatim
4090 copies of this manual provided the copyright notice and
4091 this permission notice are preserved on all copies.
4093 Permission is granted to copy and distribute modified
4094 versions of this manual under the conditions for
4095 verbatim copying, provided also that the sections
4096 entitled ``Copying'' and ``GNU General Public License''
4097 are included exactly as in the original, and provided
4098 that the entire resulting derived work is distributed
4099 under the terms of a permission notice identical to this
4102 Permission is granted to copy and distribute
4103 translations of this manual into another language,
4104 under the above conditions for modified versions,
4105 except that this permission notice may be stated in a
4106 translation approved by the Free Software Foundation.
4109 File: texinfo.info, Node: Include Files, Next: Headings, Prev: Sample Permissions, Up: Top
4114 When TeX or an Info formatting command sees an `@include' command in a
4115 Texinfo file, it processes the contents of the file named by the
4116 command and incorporates them into the DVI or Info file being created.
4117 Index entries from the included file are incorporated into the indices
4120 Include files let you keep a single large document as a collection of
4121 conveniently small parts.
4125 * Using Include Files:: How to use the `@include' command.
4126 * texinfo-multiple-files-update:: How to create and update nodes and
4127 menus when using included files.
4128 * Include File Requirements:: What `texinfo-multiple-files-update' expects.
4129 * Sample Include File:: A sample outer file with included files
4130 within it; and a sample included file.
4131 * Include Files Evolution:: How use of the `@include' command
4132 has changed over time.
4135 File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Prev: Include Files, Up: Include Files
4137 How to Use Include Files
4138 ========================
4140 To include another file within a Texinfo file, write the `@include'
4141 command at the beginning of a line and follow it on the same line by
4142 the name of a file to be included. For example:
4144 @include buffers.texi
4146 An included file should simply be a segment of text that you expect to
4147 be included as is into the overall or "outer" Texinfo file; it should
4148 not contain the standard beginning and end parts of a Texinfo file. In
4149 particular, you should not start an included file with a line saying
4150 `\input texinfo'; if you do, that phrase is inserted into the output
4151 file as is. Likewise, you should not end an included file with an
4152 `@bye' command; nothing after `@bye' is formatted.
4154 In the past, you were required to write an `@setfilename' line at the
4155 beginning of an included file, but no longer. Now, it does not matter
4156 whether you write such a line. If an `@setfilename' line exists in an
4157 included file, it is ignored.
4159 Conventionally, an included file begins with an `@node' line that is
4160 followed by an `@chapter' line. Each included file is one chapter.
4161 This makes it easy to use the regular node and menu creating and
4162 updating commands to create the node pointers and menus within the
4163 included file. However, the simple Emacs node and menu creating and
4164 updating commands do not work with multiple Texinfo files. Thus you
4165 cannot use these commands to fill in the `Next', `Previous', and `Up'
4166 pointers of the `@node' line that begins the included file. Also, you
4167 cannot use the regular commands to create a master menu for the whole
4168 file. Either you must insert the menus and the `Next', `Previous', and
4169 `Up' pointers by hand, or you must use the GNU Emacs Texinfo mode
4170 command, `texinfo-multiple-files-update', that is designed for
4174 File: texinfo.info, Node: texinfo-multiple-files-update, Next: Include File Requirements, Prev: Using Include Files, Up: Include Files
4176 `texinfo-multiple-files-update'
4177 ===============================
4179 GNU Emacs Texinfo mode provides the `texinfo-multiple-files-update'
4180 command. This command creates or updates `Next', `Previous', and `Up'
4181 pointers of included files as well as those in the outer or overall
4182 Texinfo file, and it creates or updates a main menu in the outer file.
4183 Depending whether you call it with optional arguments, the command
4184 updates only the pointers in the first `@node' line of the included
4185 files or all of them:
4187 `M-x texinfo-multiple-files-update'
4188 Called without any arguments:
4190 - Create or update the `Next', `Previous', and `Up' pointers of
4191 the first `@node' line in each file included in an outer or
4192 overall Texinfo file.
4194 - Create or update the `Top' level node pointers of the outer or
4197 - Create or update a main menu in the outer file.
4199 `C-u M-x texinfo-multiple-files-update'
4200 Called with `C-u' as a prefix argument:
4202 - Create or update pointers in the first `@node' line in each
4205 - Create or update the `Top' level node pointers of the outer
4208 - Create and insert a master menu in the outer file. The
4209 master menu is made from all the menus in all the included
4212 `C-u 8 M-x texinfo-multiple-files-update'
4213 Called with a numeric prefix argument, such as `C-u 8':
4215 - Create or update *all* the `Next', `Previous', and `Up'
4216 pointers of all the included files.
4218 - Create or update *all* the menus of all the included files.
4220 - Create or update the `Top' level node pointers of the outer or
4223 - And then create a master menu in the outer file. This is
4224 similar to invoking `texinfo-master-menu' with an argument
4225 when you are working with just one file.
4227 Note the use of the prefix argument in interactive use: with a regular
4228 prefix argument, just `C-u', the `texinfo-multiple-files-update'
4229 command inserts a master menu; with a numeric prefix argument, such as
4230 `C-u 8', the command updates *every* pointer and menu in *all* the
4231 files and then inserts a master menu.
4234 File: texinfo.info, Node: Include File Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files
4236 Include File Requirements
4237 =========================
4239 If you plan to use the `texinfo-multiple-files-update' command, the
4240 outer Texinfo file that lists included files within it should contain
4241 nothing but the beginning and end parts of a Texinfo file, and a number
4242 of `@include' commands listing the included files. It should not even
4243 include indices, which should be listed in an included file of their
4246 Moreover, each of the included files must contain exactly one highest
4247 level node (conventionally, `@chapter' or equivalent), and this node
4248 must be the first node in the included file. Furthermore, each of
4249 these highest level nodes in each included file must be at the same
4250 hierarchical level in the file structure. Usually, each is an
4251 `@chapter', an `@appendix', or an `@unnumbered' node. Thus, normally,
4252 each included file contains one, and only one, chapter or
4253 equivalent-level node.
4255 The outer file should contain only _one_ node, the `Top' node. It
4256 should _not_ contain any nodes besides the single `Top' node. The
4257 `texinfo-multiple-files-update' command will not process them.
4260 File: texinfo.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include File Requirements, Up: Include Files
4262 Sample File with `@include'
4263 ===========================
4265 Here is an example of a complete outer Texinfo file with `@include'
4266 files within it before running `texinfo-multiple-files-update', which
4267 would insert a main or master menu:
4269 \input texinfo @c -*-texinfo-*-
4270 @setfilename include-example.info
4271 @settitle Include Example
4273 @setchapternewpage odd
4276 @center @titlefont{Include Example}
4278 @center by Whom Ever
4281 @vskip 0pt plus 1filll
4282 Copyright @copyright{} 1998 Free Software Foundation, Inc.
4286 @node Top, First, , (dir)
4290 @include foo.texinfo
4291 @include bar.texinfo
4292 @include concept-index.texinfo
4299 An included file, such as `foo.texinfo', might look like this:
4301 @node First, Second, , Top
4302 @chapter First Chapter
4304 Contents of first chapter ...
4306 The full contents of `concept-index.texinfo' might be as simple as
4309 @node Concept Index, , Second, Top
4310 @unnumbered Concept Index
4314 The outer Texinfo source file for `The XEmacs Lisp Reference Manual'
4315 is named `elisp.texi'. This outer file contains a master menu with 417
4316 entries and a list of 41 `@include' files.
4319 File: texinfo.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files
4321 Evolution of Include Files
4322 ==========================
4324 When Info was first created, it was customary to create many small Info
4325 files on one subject. Each Info file was formatted from its own
4326 Texinfo source file. This custom meant that Emacs did not need to make
4327 a large buffer to hold the whole of a large Info file when someone
4328 wanted information; instead, Emacs allocated just enough memory for the
4329 small Info file that contained the particular information sought. This
4330 way, Emacs could avoid wasting memory.
4332 References from one file to another were made by referring to the file
4333 name as well as the node name. (*Note Referring to Other Info Files:
4334 Other Info Files. Also, see *Note `@xref' with Four and Five
4335 Arguments: Four and Five Arguments.)
4337 Include files were designed primarily as a way to create a single,
4338 large printed manual out of several smaller Info files. In a printed
4339 manual, all the references were within the same document, so TeX could
4340 automatically determine the references' page numbers. The Info
4341 formatting commands used include files only for creating joint indices;
4342 each of the individual Texinfo files had to be formatted for Info
4343 individually. (Each, therefore, required its own `@setfilename' line.)
4345 However, because large Info files are now split automatically, it is
4346 no longer necessary to keep them small.
4348 Nowadays, multiple Texinfo files are used mostly for large documents,
4349 such as `The XEmacs Lisp Reference Manual', and for projects in which
4350 several different people write different sections of a document
4353 In addition, the Info formatting commands have been extended to work
4354 with the `@include' command so as to create a single large Info file
4355 that is split into smaller files if necessary. This means that you can
4356 write menus and cross references without naming the different Texinfo
4360 File: texinfo.info, Node: Headings, Next: Catching Mistakes, Prev: Include Files, Up: Top
4365 Most printed manuals contain headings along the top of every page
4366 except the title and copyright pages. Some manuals also contain
4367 footings. (Headings and footings have no meaning to Info, which is not
4372 * Headings Introduced:: Conventions for using page headings.
4373 * Heading Format:: Standard page heading formats.
4374 * Heading Choice:: How to specify the type of page heading.
4375 * Custom Headings:: How to create your own headings and footings.
4378 File: texinfo.info, Node: Headings Introduced, Next: Heading Format, Prev: Headings, Up: Headings
4383 Texinfo provides standard page heading formats for manuals that are
4384 printed on one side of each sheet of paper and for manuals that are
4385 printed on both sides of the paper. Typically, you will use these
4386 formats, but you can specify your own format if you wish.
4388 In addition, you can specify whether chapters should begin on a new
4389 page, or merely continue the same page as the previous chapter; and if
4390 chapters begin on new pages, you can specify whether they must be
4393 By convention, a book is printed on both sides of each sheet of paper.
4394 When you open a book, the right-hand page is odd-numbered, and chapters
4395 begin on right-hand pages--a preceding left-hand page is left blank if
4396 necessary. Reports, however, are often printed on just one side of
4397 paper, and chapters begin on a fresh page immediately following the end
4398 of the preceding chapter. In short or informal reports, chapters often
4399 do not begin on a new page at all, but are separated from the preceding
4400 text by a small amount of whitespace.
4402 The `@setchapternewpage' command controls whether chapters begin on
4403 new pages, and whether one of the standard heading formats is used. In
4404 addition, Texinfo has several heading and footing commands that you can
4405 use to generate your own heading and footing formats.
4407 In Texinfo, headings and footings are single lines at the tops and
4408 bottoms of pages; you cannot create multiline headings or footings.
4409 Each header or footer line is divided into three parts: a left part, a
4410 middle part, and a right part. Any part, or a whole line, may be left
4411 blank. Text for the left part of a header or footer line is set
4412 flushleft; text for the middle part is centered; and, text for the
4413 right part is set flushright.
4416 File: texinfo.info, Node: Heading Format, Next: Heading Choice, Prev: Headings Introduced, Up: Headings
4418 Standard Heading Formats
4419 ========================
4421 Texinfo provides two standard heading formats, one for manuals printed
4422 on one side of each sheet of paper, and the other for manuals printed
4423 on both sides of the paper.
4425 By default, nothing is specified for the footing of a Texinfo file,
4426 so the footing remains blank.
4428 The standard format for single-sided printing consists of a header
4429 line in which the left-hand part contains the name of the chapter, the
4430 central part is blank, and the right-hand part contains the page number.
4432 A single-sided page looks like this:
4434 _______________________
4436 | chapter page number |
4438 | Start of text ... |
4442 The standard format for two-sided printing depends on whether the page
4443 number is even or odd. By convention, even-numbered pages are on the
4444 left- and odd-numbered pages are on the right. (TeX will adjust the
4445 widths of the left- and right-hand margins. Usually, widths are
4446 correct, but during double-sided printing, it is wise to check that
4447 pages will bind properly--sometimes a printer will produce output in
4448 which the even-numbered pages have a larger right-hand margin than the
4449 odd-numbered pages.)
4451 In the standard double-sided format, the left part of the left-hand
4452 (even-numbered) page contains the page number, the central part is
4453 blank, and the right part contains the title (specified by the
4454 `@settitle' command). The left part of the right-hand (odd-numbered)
4455 page contains the name of the chapter, the central part is blank, and
4456 the right part contains the page number.
4458 Two pages, side by side as in an open book, look like this:
4460 _______________________ _______________________
4462 | page number title | | chapter page number |
4464 | Start of text ... | | More text ... |
4468 The chapter name is preceded by the word "Chapter", the chapter number
4469 and a colon. This makes it easier to keep track of where you are in the
4473 File: texinfo.info, Node: Heading Choice, Next: Custom Headings, Prev: Heading Format, Up: Headings
4475 Specifying the Type of Heading
4476 ==============================
4478 TeX does not begin to generate page headings for a standard Texinfo
4479 file until it reaches the `@end titlepage' command. Thus, the title
4480 and copyright pages are not numbered. The `@end titlepage' command
4481 causes TeX to begin to generate page headings according to a standard
4482 format specified by the `@setchapternewpage' command that precedes the
4483 `@titlepage' section.
4485 There are four possibilities:
4487 No `@setchapternewpage' command
4488 Cause TeX to specify the single-sided heading format, with chapters
4489 on new pages. This is the same as `@setchapternewpage on'.
4491 `@setchapternewpage on'
4492 Specify the single-sided heading format, with chapters on new
4495 `@setchapternewpage off'
4496 Cause TeX to start a new chapter on the same page as the last page
4497 of the preceding chapter, after skipping some vertical whitespace.
4498 Also cause TeX to typeset for single-sided printing. (You can
4499 override the headers format with the `@headings double' command;
4500 see *Note The `@headings' Command: headings on off.)
4502 `@setchapternewpage odd'
4503 Specify the double-sided heading format, with chapters on new
4506 Texinfo lacks an `@setchapternewpage even' command.
4509 File: texinfo.info, Node: Custom Headings, Prev: Heading Choice, Up: Headings
4511 How to Make Your Own Headings
4512 =============================
4514 You can use the standard headings provided with Texinfo or specify your
4515 own. By default, Texinfo has no footers, so if you specify them, the
4516 available page size for the main text will be slightly reduced.
4518 Texinfo provides six commands for specifying headings and footings.
4519 The `@everyheading' command and `@everyfooting' command generate page
4520 headers and footers that are the same for both even- and odd-numbered
4521 pages. The `@evenheading' command and `@evenfooting' command generate
4522 headers and footers for even-numbered (left-hand) pages; and the
4523 `@oddheading' command and `@oddfooting' command generate headers and
4524 footers for odd-numbered (right-hand) pages.
4526 Write custom heading specifications in the Texinfo file immediately
4527 after the `@end titlepage' command. Enclose your specifications
4528 between `@iftex' and `@end iftex' commands since the
4529 `texinfo-format-buffer' command may not recognize them. Also, you must
4530 cancel the predefined heading commands with the `@headings off' command
4531 before defining your own specifications.
4533 Here is how to tell TeX to place the chapter name at the left, the
4534 page number in the center, and the date at the right of every header
4535 for both even- and odd-numbered pages:
4539 @everyheading @thischapter @| @thispage @| @today{}
4542 You need to divide the left part from the central part and the central
4543 part from the right part by inserting `@|' between parts. Otherwise,
4544 the specification command will not be able to tell where the text for
4545 one part ends and the next part begins.
4547 Each part can contain text or @-commands. The text is printed as if
4548 the part were within an ordinary paragraph in the body of the page.
4549 The @-commands replace themselves with the page number, date, chapter
4552 Here are the six heading and footing commands:
4554 `@everyheading LEFT @| CENTER @| RIGHT'
4555 `@everyfooting LEFT @| CENTER @| RIGHT'
4556 The `every' commands specify the format for both even- and
4557 odd-numbered pages. These commands are for documents that are
4558 printed on one side of each sheet of paper, or for documents in
4559 which you want symmetrical headers or footers.
4561 `@evenheading LEFT @| CENTER @| RIGHT'
4562 `@oddheading LEFT @| CENTER @| RIGHT'
4563 `@evenfooting LEFT @| CENTER @| RIGHT'
4564 `@oddfooting LEFT @| CENTER @| RIGHT'
4565 The `even' and `odd' commands specify the format for even-numbered
4566 pages and odd-numbered pages. These commands are for books and
4567 manuals that are printed on both sides of each sheet of paper.
4569 Use the `@this...' series of @-commands to provide the names of
4570 chapters and sections and the page number. You can use the `@this...'
4571 commands in the left, center, or right portions of headers and footers,
4572 or anywhere else in a Texinfo file so long as they are between `@iftex'
4573 and `@end iftex' commands.
4575 Here are the `@this...' commands:
4578 Expands to the current page number.
4581 Expands to the name of the current chapter.
4584 Expands to the number and name of the current chapter, in the
4585 format `Chapter 1: Title'.
4588 Expands to the name of the document, as specified by the
4589 `@settitle' command.
4592 For `@include' files only: expands to the name of the current
4593 `@include' file. If the current Texinfo source file is not an
4594 `@include' file, this command has no effect. This command does
4595 _not_ provide the name of the current Texinfo source file unless
4596 it is an `@include' file. (*Note Include Files::, for more
4597 information about `@include' files.)
4599 You can also use the `@today{}' command, which expands to the current
4600 date, in `1 Jan 1900' format.
4602 Other @-commands and text are printed in a header or footer just as
4603 if they were in the body of a page. It is useful to incorporate text,
4604 particularly when you are writing drafts:
4608 @everyheading @emph{Draft!} @| @thispage @| @thischapter
4609 @everyfooting @| @| Version: 0.27: @today{}
4612 Beware of overlong titles: they may overlap another part of the
4613 header or footer and blot it out.
4616 File: texinfo.info, Node: Catching Mistakes, Next: Refilling Paragraphs, Prev: Headings, Up: Top
4621 Besides mistakes in the content of your documentation, there are two
4622 kinds of mistake you can make with Texinfo: you can make mistakes with
4623 @-commands, and you can make mistakes with the structure of the nodes
4626 Emacs has two tools for catching the @-command mistakes and two for
4627 catching structuring mistakes.
4629 For finding problems with @-commands, you can run TeX or a region
4630 formatting command on the region that has a problem; indeed, you can
4631 run these commands on each region as you write it.
4633 For finding problems with the structure of nodes and chapters, you
4634 can use `C-c C-s' (`texinfo-show-structure') and the related `occur'
4635 command and you can use the `M-x Info-validate' command.
4639 * makeinfo Preferred:: `makeinfo' finds errors.
4640 * Debugging with Info:: How to catch errors with Info formatting.
4641 * Debugging with TeX:: How to catch errors with TeX formatting.
4642 * Using texinfo-show-structure:: How to use `texinfo-show-structure'.
4643 * Using occur:: How to list all lines containing a pattern.
4644 * Running Info-Validate:: How to find badly referenced nodes.
4647 File: texinfo.info, Node: makeinfo Preferred, Next: Debugging with Info, Prev: Catching Mistakes, Up: Catching Mistakes
4649 `makeinfo' Find Errors
4650 ======================
4652 The `makeinfo' program does an excellent job of catching errors and
4653 reporting them--far better than `texinfo-format-region' or
4654 `texinfo-format-buffer'. In addition, the various functions for
4655 automatically creating and updating node pointers and menus remove many
4656 opportunities for human error.
4658 If you can, use the updating commands to create and insert pointers
4659 and menus. These prevent many errors. Then use `makeinfo' (or its
4660 Texinfo mode manifestations, `makeinfo-region' and `makeinfo-buffer')
4661 to format your file and check for other errors. This is the best way
4662 to work with Texinfo. But if you cannot use `makeinfo', or your
4663 problem is very puzzling, then you may want to use the tools described
4667 File: texinfo.info, Node: Debugging with Info, Next: Debugging with TeX, Prev: makeinfo Preferred, Up: Catching Mistakes
4669 Catching Errors with Info Formatting
4670 ====================================
4672 After you have written part of a Texinfo file, you can use the
4673 `texinfo-format-region' or the `makeinfo-region' command to see whether
4674 the region formats properly.
4676 Most likely, however, you are reading this section because for some
4677 reason you cannot use the `makeinfo-region' command; therefore, the
4678 rest of this section presumes that you are using
4679 `texinfo-format-region'.
4681 If you have made a mistake with an @-command, `texinfo-format-region'
4682 will stop processing at or after the error and display an error
4683 message. To see where in the buffer the error occurred, switch to the
4684 `*Info Region*' buffer; the cursor will be in a position that is after
4685 the location of the error. Also, the text will not be formatted after
4686 the place where the error occurred (or more precisely, where it was
4689 For example, if you accidentally end a menu with the command `@end
4690 menus' with an `s' on the end, instead of with `@end menu', you will
4691 see an error message that says:
4693 @end menus is not handled by texinfo
4695 The cursor will stop at the point in the buffer where the error occurs,
4696 or not long after it. The buffer will look like this:
4698 ---------- Buffer: *Info Region* ----------
4701 * Using texinfo-show-structure:: How to use
4702 `texinfo-show-structure'
4704 * Running Info-Validate:: How to check for
4708 ---------- Buffer: *Info Region* ----------
4710 The `texinfo-format-region' command sometimes provides slightly odd
4711 error messages. For example, the following cross reference fails to
4714 (@xref{Catching Mistakes, for more info.)
4716 In this case, `texinfo-format-region' detects the missing closing brace
4717 but displays a message that says `Unbalanced parentheses' rather than
4718 `Unbalanced braces'. This is because the formatting command looks for
4719 mismatches between braces as if they were parentheses.
4721 Sometimes `texinfo-format-region' fails to detect mistakes. For
4722 example, in the following, the closing brace is swapped with the
4723 closing parenthesis:
4725 (@xref{Catching Mistakes), for more info.}
4727 Formatting produces:
4728 (*Note for more info.: Catching Mistakes)
4730 The only way for you to detect this error is to realize that the
4731 reference should have looked like this:
4733 (*Note Catching Mistakes::, for more info.)
4735 Incidentally, if you are reading this node in Info and type `f <RET>'
4736 (`Info-follow-reference'), you will generate an error message that says:
4738 No such node: "Catching Mistakes) The only way ...
4740 This is because Info perceives the example of the error as the first
4741 cross reference in this node and if you type a <RET> immediately after
4742 typing the Info `f' command, Info will attempt to go to the referenced
4743 node. If you type `f catch <TAB> <RET>', Info will complete the node
4744 name of the correctly written example and take you to the `Catching
4745 Mistakes' node. (If you try this, you can return from the `Catching
4746 Mistakes' node by typing `l' (`Info-last').)
4749 File: texinfo.info, Node: Debugging with TeX, Next: Using texinfo-show-structure, Prev: Debugging with Info, Up: Catching Mistakes
4751 Catching Errors with TeX Formatting
4752 ===================================
4754 You can also catch mistakes when you format a file with TeX.
4756 Usually, you will want to do this after you have run
4757 `texinfo-format-buffer' (or, better, `makeinfo-buffer') on the same
4758 file, because `texinfo-format-buffer' sometimes displays error messages
4759 that make more sense than TeX. (*Note Debugging with Info::, for more
4762 For example, TeX was run on a Texinfo file, part of which is shown
4765 ---------- Buffer: texinfo.texi ----------
4766 name of the Texinfo file as an extension. The
4767 @samp{??} are `wildcards' that cause the shell to
4768 substitute all the raw index files. (@xref{sorting
4769 indices, for more information about sorting
4771 ---------- Buffer: texinfo.texi ----------
4773 (The cross reference lacks a closing brace.) TeX produced the
4774 following output, after which it stopped:
4776 ---------- Buffer: *tex-shell* ----------
4778 {sorting indices, for more information about sorting
4779 indices.) @refill @ETC.
4780 ! Paragraph ended before @xref was complete.
4786 ---------- Buffer: *tex-shell* ----------
4788 In this case, TeX produced an accurate and understandable error
4791 Paragraph ended before @xref was complete.
4793 `@par' is an internal TeX command of no relevance to Texinfo. `l.27'
4794 means that TeX detected the problem on line 27 of the Texinfo file.
4795 The `?' is the prompt TeX uses in this circumstance.
4797 Unfortunately, TeX is not always so helpful, and sometimes you must
4798 truly be a Sherlock Holmes to discover what went wrong.
4800 In any case, if you run into a problem like this, you can do one of
4803 1. You can tell TeX to continue running and ignore just this error by
4804 typing <RET> at the `?' prompt.
4806 2. You can tell TeX to continue running and to ignore all errors as
4807 best it can by typing `r <RET>' at the `?' prompt.
4809 This is often the best thing to do. However, beware: the one error
4810 may produce a cascade of additional error messages as its
4811 consequences are felt through the rest of the file. To stop TeX
4812 when it is producing such an avalanche of error messages, type
4813 `C-c' (or `C-c C-c', if you are running a shell inside Emacs).
4815 3. You can tell TeX to stop this run by typing `x <RET>' at the `?'
4818 Please note that if you are running TeX inside Emacs, you need to
4819 switch to the shell buffer and line at which TeX offers the `?' prompt.
4821 Sometimes TeX will format a file without producing error messages even
4822 though there is a problem. This usually occurs if a command is not
4823 ended but TeX is able to continue processing anyhow. For example, if
4824 you fail to end an itemized list with the `@end itemize' command, TeX
4825 will write a DVI file that you can print out. The only error message
4826 that TeX will give you is the somewhat mysterious comment that
4828 (@end occurred inside a group at level 1)
4830 However, if you print the DVI file, you will find that the text of the
4831 file that follows the itemized list is entirely indented as if it were
4832 part of the last item in the itemized list. The error message is the
4833 way TeX says that it expected to find an `@end' command somewhere in
4834 the file; but that it could not determine where it was needed.
4836 Another source of notoriously hard-to-find errors is a missing `@end
4837 group' command. If you ever are stumped by incomprehensible errors,
4838 look for a missing `@end group' command first.
4840 If the Texinfo file lacks header lines, TeX may stop in the beginning
4841 of its run and display output that looks like the following. The `*'
4842 indicates that TeX is waiting for input.
4844 This is TeX, Version 3.14159 (Web2c 7.0)
4848 In this case, simply type `\end <RET>' after the asterisk. Then write
4849 the header lines in the Texinfo file and run the TeX command again.
4850 (Note the use of the backslash, `\'. TeX uses `\' instead of `@'; and
4851 in this circumstance, you are working directly with TeX, not with
4855 File: texinfo.info, Node: Using texinfo-show-structure, Next: Using occur, Prev: Debugging with TeX, Up: Catching Mistakes
4857 Using `texinfo-show-structure'
4858 ==============================
4860 It is not always easy to keep track of the nodes, chapters, sections,
4861 and subsections of a Texinfo file. This is especially true if you are
4862 revising or adding to a Texinfo file that someone else has written.
4864 In GNU Emacs, in Texinfo mode, the `texinfo-show-structure' command
4865 lists all the lines that begin with the @-commands that specify the
4866 structure: `@chapter', `@section', `@appendix', and so on. With an
4867 argument (`C-u' as prefix argument, if interactive), the command also
4868 shows the `@node' lines. The `texinfo-show-structure' command is bound
4869 to `C-c C-s' in Texinfo mode, by default.
4871 The lines are displayed in a buffer called the `*Occur*' buffer,
4872 indented by hierarchical level. For example, here is a part of what was
4873 produced by running `texinfo-show-structure' on this manual:
4875 Lines matching "^@\\(chapter \\|sect\\|subs\\|subh\\|
4876 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
4877 in buffer texinfo.texi.
4880 4198: @heading Two Paths
4881 4231: @section Node and Menu Illustration
4882 4337: @section The @code{@@node} Command
4883 4393: @subheading Choosing Node and Pointer Names
4884 4417: @subsection How to Write an @code{@@node} Line
4885 4469: @subsection @code{@@node} Line Tips
4888 This says that lines 4337, 4393, and 4417 of `texinfo.texi' begin
4889 with the `@section', `@subheading', and `@subsection' commands
4890 respectively. If you move your cursor into the `*Occur*' window, you
4891 can position the cursor over one of the lines and use the `C-c C-c'
4892 command (`occur-mode-goto-occurrence'), to jump to the corresponding
4893 spot in the Texinfo file. *Note Using Occur: (xemacs)Other Repeating
4894 Search, for more information about `occur-mode-goto-occurrence'.
4896 The first line in the `*Occur*' window describes the "regular
4897 expression" specified by TEXINFO-HEADING-PATTERN. This regular
4898 expression is the pattern that `texinfo-show-structure' looks for.
4899 *Note Using Regular Expressions: (xemacs)Regexps, for more information.
4901 When you invoke the `texinfo-show-structure' command, Emacs will
4902 display the structure of the whole buffer. If you want to see the
4903 structure of just a part of the buffer, of one chapter, for example,
4904 use the `C-x n n' (`narrow-to-region') command to mark the region.
4905 (*Note Narrowing: (xemacs)Narrowing.) This is how the example used
4906 above was generated. (To see the whole buffer again, use `C-x n w'
4909 If you call `texinfo-show-structure' with a prefix argument by typing
4910 `C-u C-c C-s', it will list lines beginning with `@node' as well as the
4911 lines beginning with the @-sign commands for `@chapter', `@section',
4914 You can remind yourself of the structure of a Texinfo file by looking
4915 at the list in the `*Occur*' window; and if you have mis-named a node
4916 or left out a section, you can correct the mistake.
4919 File: texinfo.info, Node: Using occur, Next: Running Info-Validate, Prev: Using texinfo-show-structure, Up: Catching Mistakes
4924 Sometimes the `texinfo-show-structure' command produces too much
4925 information. Perhaps you want to remind yourself of the overall
4926 structure of a Texinfo file, and are overwhelmed by the detailed list
4927 produced by `texinfo-show-structure'. In this case, you can use the
4928 `occur' command directly. To do this, type
4932 and then, when prompted, type a "regexp", a regular expression for the
4933 pattern you want to match. (*Note Regular Expressions:
4934 (xemacs)Regexps.) The `occur' command works from the current location
4935 of the cursor in the buffer to the end of the buffer. If you want to
4936 run `occur' on the whole buffer, place the cursor at the beginning of
4939 For example, to see all the lines that contain the word `@chapter' in
4940 them, just type `@chapter'. This will produce a list of the chapters.
4941 It will also list all the sentences with `@chapter' in the middle of
4944 If you want to see only those lines that start with the word
4945 `@chapter', type `^@chapter' when prompted by `occur'. If you want to
4946 see all the lines that end with a word or phrase, end the last word
4947 with a `$'; for example, `catching mistakes$'. This can be helpful
4948 when you want to see all the nodes that are part of the same chapter or
4949 section and therefore have the same `Up' pointer.
4951 *Note Using Occur: (xemacs)Other Repeating Search, for more
4955 File: texinfo.info, Node: Running Info-Validate, Prev: Using occur, Up: Catching Mistakes
4957 Finding Badly Referenced Nodes
4958 ==============================
4960 You can use the `Info-validate' command to check whether any of the
4961 `Next', `Previous', `Up' or other node pointers fail to point to a
4962 node. This command checks that every node pointer points to an
4963 existing node. The `Info-validate' command works only on Info files,
4964 not on Texinfo files.
4966 The `makeinfo' program validates pointers automatically, so you do
4967 not need to use the `Info-validate' command if you are using
4968 `makeinfo'. You only may need to use `Info-validate' if you are unable
4969 to run `makeinfo' and instead must create an Info file using
4970 `texinfo-format-region' or `texinfo-format-buffer', or if you write an
4971 Info file from scratch.
4975 * Using Info-validate:: How to run `Info-validate'.
4976 * Unsplit:: How to create an unsplit file.
4977 * Tagifying:: How to tagify a file.
4978 * Splitting:: How to split a file manually.
4981 File: texinfo.info, Node: Using Info-validate, Next: Unsplit, Prev: Running Info-Validate, Up: Running Info-Validate
4983 Running `Info-validate'
4984 -----------------------
4986 To use `Info-validate', visit the Info file you wish to check and type:
4990 (Note that the `Info-validate' command requires an upper case `I'. You
4991 may also need to create a tag table before running `Info-validate'.
4994 If your file is valid, you will receive a message that says "File
4995 appears valid". However, if you have a pointer that does not point to
4996 a node, error messages will be displayed in a buffer called `*problems
4999 For example, `Info-validate' was run on a test file that contained
5000 only the first node of this manual. One of the messages said:
5002 In node "Overview", invalid Next: Texinfo Mode
5004 This meant that the node called `Overview' had a `Next' pointer that
5005 did not point to anything (which was true in this case, since the test
5006 file had only one node in it).
5008 Now suppose we add a node named `Texinfo Mode' to our test case but
5009 we do not specify a `Previous' for this node. Then we will get the
5010 following error message:
5012 In node "Texinfo Mode", should have Previous: Overview
5014 This is because every `Next' pointer should be matched by a `Previous'
5015 (in the node where the `Next' points) which points back.
5017 `Info-validate' also checks that all menu entries and cross references
5018 point to actual nodes.
5020 Note that `Info-validate' requires a tag table and does not work with
5021 files that have been split. (The `texinfo-format-buffer' command
5022 automatically splits large files.) In order to use `Info-validate' on
5023 a large file, you must run `texinfo-format-buffer' with an argument so
5024 that it does not split the Info file; and you must create a tag table
5025 for the unsplit file.
5028 File: texinfo.info, Node: Unsplit, Next: Tagifying, Prev: Using Info-validate, Up: Running Info-Validate
5030 Creating an Unsplit File
5031 ------------------------
5033 You can run `Info-validate' only on a single Info file that has a tag
5034 table. The command will not work on the indirect subfiles that are
5035 generated when a master file is split. If you have a large file
5036 (longer than 70,000 bytes or so), you need to run the
5037 `texinfo-format-buffer' or `makeinfo-buffer' command in such a way that
5038 it does not create indirect subfiles. You will also need to create a
5039 tag table for the Info file. After you have done this, you can run
5040 `Info-validate' and look for badly referenced nodes.
5042 The first step is to create an unsplit Info file. To prevent
5043 `texinfo-format-buffer' from splitting a Texinfo file into smaller Info
5044 files, give a prefix to the `M-x texinfo-format-buffer' command:
5046 C-u M-x texinfo-format-buffer
5052 When you do this, Texinfo will not split the file and will not create a
5056 File: texinfo.info, Node: Tagifying, Next: Splitting, Prev: Unsplit, Up: Running Info-Validate
5061 After creating an unsplit Info file, you must create a tag table for
5062 it. Visit the Info file you wish to tagify and type:
5066 (Note the upper case `I' in `Info-tagify'.) This creates an Info file
5067 with a tag table that you can validate.
5069 The third step is to validate the Info file:
5073 (Note the upper case `I' in `Info-validate'.) In brief, the steps are:
5075 C-u M-x texinfo-format-buffer
5079 After you have validated the node structure, you can rerun
5080 `texinfo-format-buffer' in the normal way so it will construct a tag
5081 table and split the file automatically, or you can make the tag table
5082 and split the file manually.
5085 File: texinfo.info, Node: Splitting, Prev: Tagifying, Up: Running Info-Validate
5087 Splitting a File Manually
5088 -------------------------
5090 You should split a large file or else let the `texinfo-format-buffer'
5091 or `makeinfo-buffer' command do it for you automatically. (Generally
5092 you will let one of the formatting commands do this job for you. *Note
5093 Create an Info File::.)
5095 The split-off files are called the indirect subfiles.
5097 Info files are split to save memory. With smaller files, Emacs does
5098 not have make such a large buffer to hold the information.
5100 If an Info file has more than 30 nodes, you should also make a tag
5101 table for it. *Note Using Info-validate::, for information about
5102 creating a tag table. (Again, tag tables are usually created
5103 automatically by the formatting command; you only need to create a tag
5104 table yourself if you are doing the job manually. Most likely, you
5105 will do this for a large, unsplit file on which you have run
5108 Visit the Info file you wish to tagify and split and type the two
5114 (Note that the `I' in `Info' is upper case.)
5116 When you use the `Info-split' command, the buffer is modified into a
5117 (small) Info file which lists the indirect subfiles. This file should
5118 be saved in place of the original visited file. The indirect subfiles
5119 are written in the same directory the original file is in, with names
5120 generated by appending `-' and a number to the original file name.
5122 The primary file still functions as an Info file, but it contains just
5123 the tag table and a directory of subfiles.
5126 File: texinfo.info, Node: Refilling Paragraphs, Next: Command Syntax, Prev: Catching Mistakes, Up: Top
5128 Refilling Paragraphs
5129 ********************
5131 The `@refill' command refills and, optionally, indents the first line
5132 of a paragraph.(1) (*note Refilling Paragraphs-Footnote-1::) The
5133 `@refill' command is no longer important, but we describe it here
5134 because you once needed it. You will see it in many old Texinfo files.
5136 Without refilling, paragraphs containing long @-constructs may look
5137 bad after formatting because the formatter removes @-commands and
5138 shortens some lines more than others. In the past, neither the
5139 `texinfo-format-region' command nor the `texinfo-format-buffer' command
5140 refilled paragraphs automatically. The `@refill' command had to be
5141 written at the end of every paragraph to cause these formatters to fill
5142 them. (Both TeX and `makeinfo' have always refilled paragraphs
5143 automatically.) Now, all the Info formatters automatically fill and
5144 indent those paragraphs that need to be filled and indented.
5146 The `@refill' command causes `texinfo-format-region' and
5147 `texinfo-format-buffer' to refill a paragraph in the Info file _after_
5148 all the other processing has been done. For this reason, you can not
5149 use `@refill' with a paragraph containing either `@*' or `@w{ ... }'
5150 since the refilling action will override those two commands.
5152 The `texinfo-format-region' and `texinfo-format-buffer' commands now
5153 automatically append `@refill' to the end of each paragraph that should
5154 be filled. They do not append `@refill' to the ends of paragraphs that
5155 contain `@*' or `@w{ ...}' and therefore do not refill or indent them.
5158 File: texinfo.info, Node: Refilling Paragraphs-Footnotes, Up: Refilling Paragraphs
5160 (1) Perhaps the command should have been called the
5161 `@refillandindent' command, but `@refill' is shorter and the name was
5162 chosen before indenting was possible.
5165 File: texinfo.info, Node: Command Syntax, Next: Obtaining TeX, Prev: Refilling Paragraphs, Up: Top
5170 The character `@' is used to start special Texinfo commands. (It has
5171 the same meaning that `\' has in plain TeX.) Texinfo has four types of
5174 1. Non-alphabetic commands.
5175 These commands consist of an @ followed by a punctuation mark or
5176 other character that is not part of the alphabet. Non-alphabetic
5177 commands are almost always part of the text within a paragraph,
5178 and never take any argument. The two characters (@ and the other
5179 one) are complete in themselves; none is followed by braces. The
5180 non-alphabetic commands are: `@.', `@:', `@*', `@SPACE', `@TAB',
5181 `@NL', `@@', `@{', and `@}'.
5183 2. Alphabetic commands that do not require arguments.
5184 These commands start with @ followed by a word followed by left-
5185 and right-hand braces. These commands insert special symbols in
5186 the document; they do not require arguments. For example,
5187 `@dots{}' => `...', `@equiv{}' => `==', `@TeX{}' => `TeX', and
5190 3. Alphabetic commands that require arguments within braces.
5191 These commands start with @ followed by a letter or a word,
5192 followed by an argument within braces. For example, the command
5193 `@dfn' indicates the introductory or defining use of a term; it is
5194 used as follows: `In Texinfo, @@-commands are @dfn{mark-up}
5197 4. Alphabetic commands that occupy an entire line.
5198 These commands occupy an entire line. The line starts with @,
5199 followed by the name of the command (a word); for example,
5200 `@center' or `@cindex'. If no argument is needed, the word is
5201 followed by the end of the line. If there is an argument, it is
5202 separated from the command name by a space. Braces are not used.
5204 Thus, the alphabetic commands fall into classes that have different
5205 argument syntaxes. You cannot tell to which class a command belongs by
5206 the appearance of its name, but you can tell by the command's meaning:
5207 if the command stands for a glyph, it is in class 2 and does not
5208 require an argument; if it makes sense to use the command together with
5209 other text as part of a paragraph, the command is in class 3 and must
5210 be followed by an argument in braces; otherwise, it is in class 4 and
5211 uses the rest of the line as its argument.
5213 The purpose of having a different syntax for commands of classes 3 and
5214 4 is to make Texinfo files easier to read, and also to help the GNU
5215 Emacs paragraph and filling commands work properly. There is only one
5216 exception to this rule: the command `@refill', which is always used at
5217 the end of a paragraph immediately following the final period or other
5218 punctuation character. `@refill' takes no argument and does _not_
5219 require braces. `@refill' never confuses the Emacs paragraph commands
5220 because it cannot appear at the beginning of a line.
5223 File: texinfo.info, Node: Obtaining TeX, Next: Command and Variable Index, Prev: Command Syntax, Up: Top
5228 TeX is freely redistributable. You can obtain TeX for Unix systems via
5229 anonymous ftp or on physical media. The core material consists of the
5230 Web2c TeX distribution (`http://tug.org/web2c').
5232 Instructions for retrieval by anonymous ftp and information on other
5233 available distributions:
5234 `ftp://tug.org/tex/unixtex.ftp'
5235 `http://tug.org/unixtex.ftp'
5237 The Free Software Foundation provides a core distribution on its
5238 Source Code CD-ROM suitable for printing Texinfo manuals; the
5239 University of Washington maintains and supports a tape distribution;
5240 the TeX Users Group co-sponsors a complete CD-ROM TeX distribution.
5242 * For the FSF Source Code CD-ROM, please contact:
5244 Free Software Foundation, Inc.
5245 59 Temple Place Suite 330
5246 Boston, MA 02111-1307
5249 Telephone: +1-617-542-5942
5250 Fax: (including Japan) +1-617-542-2652
5251 Free Dial Fax (in Japan):
5253 0066-3382-0158 (IDC)
5254 Electronic mail: `gnu@gnu.org'
5256 * To order a complete distribution on CD-ROM, please see
5257 `http://tug.org/tex-live.html'. (This distribution is also
5258 available by FTP; see the URL's above.)
5260 * To order a full distribution from the University of Washington on
5261 either a 1/4in 4-track QIC-24 cartridge or a 4mm DAT cartridge,
5265 Denny Hall, Mail Stop DH-10
5266 University of Washington
5269 Telephone: +1-206-543-2268
5270 Electronic mail: `mackay@cs.washington.edu'
5272 Please make checks payable to the University of Washington.
5273 Checks must be in U.S. dollars, drawn on a U.S. bank. Overseas
5274 sites: please add to the base cost, if desired, $20.00 for
5275 shipment via air parcel post, or $30.00 for shipment via courier.
5278 Many other TeX distributions are available; see `http://tug.org/'.
5281 File: texinfo.info, Node: Command and Variable Index, Next: Concept Index, Prev: Obtaining TeX, Up: Top
5283 Command and Variable Index
5284 **************************
5286 This is an alphabetical list of all the @-commands, assorted Emacs Lisp
5287 functions, and several variables. To make the list easier to use, the
5288 commands are listed without their preceding `@'.
5292 * ! (end of sentence): Ending a Sentence.
5293 * ": Inserting Accents.
5294 * ': Inserting Accents.
5295 * (newline): Multiple Spaces.
5296 * (space): Multiple Spaces.
5297 * (tab): Multiple Spaces.
5298 * * (force line break): Line Breaks.
5299 * ,: Inserting Accents.
5300 * -: - and hyphenation.
5301 * . (end of sentence): Ending a Sentence.
5302 * : (suppress widening): Not Ending a Sentence.
5303 * =: Inserting Accents.
5304 * ? (end of sentence): Ending a Sentence.
5305 * @ (single @): Inserting An Atsign.
5306 * ^: Inserting Accents.
5307 * `: Inserting Accents.
5308 * AA: Inserting Accents.
5309 * aa: Inserting Accents.
5310 * AE: Inserting Accents.
5311 * ae: Inserting Accents.
5312 * afourpaper: A4 Paper.
5313 * appendix: unnumbered & appendix.
5314 * appendixsec: unnumberedsec appendixsec heading.
5315 * appendixsection: unnumberedsec appendixsec heading.
5316 * appendixsubsec: unnumberedsubsec appendixsubsec subheading.
5317 * appendixsubsubsec: subsubsection.
5318 * apply: Sample Function Definition.
5320 * author: title subtitle author.
5321 * b (bold font): Fonts.
5322 * buffer-end: Def Cmd Template.
5324 * bye <1>: File End.
5325 * bye: Ending a File.
5326 * c (comment): Comments.
5327 * cartouche: cartouche.
5328 * center: titlefont center sp.
5329 * centerchap: chapter.
5330 * chapheading: majorheading & chapheading.
5332 * cindex: Indexing Commands.
5334 * clear: ifset ifclear.
5336 * columnfractions: Multitable Column Widths.
5337 * comment: Comments.
5338 * contents: Contents.
5339 * copyright <1>: copyright symbol.
5340 * copyright: Copyright & Permissions.
5341 * cropmarks: Cropmarks and Magnification.
5342 * defcodeindex: New Indices.
5343 * defcv: Abstract Objects.
5344 * deffn: Functions Commands.
5346 * defindex: New Indices.
5347 * definfoenclose: Customized Highlighting.
5348 * defivar: Abstract Objects.
5349 * defmac: Functions Commands.
5350 * defmethod: Abstract Objects.
5351 * defop: Abstract Objects.
5352 * defopt: Variables Commands.
5353 * defspec: Functions Commands.
5354 * deftp: Data Types.
5355 * deftypefn: Typed Functions.
5356 * deftypefun: Typed Functions.
5357 * deftypevar: Typed Variables.
5358 * deftypevr: Typed Variables.
5359 * defun: Functions Commands.
5360 * defvar: Variables Commands.
5361 * defvr: Variables Commands.
5363 * dircategory: Installing Dir Entries.
5364 * direntry: Installing Dir Entries.
5367 * dotaccent: Inserting Accents.
5368 * dotless: Inserting Accents.
5371 * emph: emph & strong.
5372 * end <1>: Introducing Lists.
5373 * end: Quotations and Examples.
5374 * end titlepage: end titlepage.
5375 * enumerate: enumerate.
5376 * evenfooting: Custom Headings.
5377 * evenheading: Custom Headings.
5378 * everyfooting: Custom Headings.
5379 * everyheading: Custom Headings.
5381 * exclamdown: Inserting Accents.
5384 * filll: Copyright & Permissions.
5385 * finalout: Overfull hboxes.
5386 * findex: Indexing Commands.
5387 * flushleft: flushleft & flushright.
5388 * flushright: flushleft & flushright.
5389 * foobar: Optional Arguments.
5390 * footnote: Footnotes.
5391 * footnotestyle: Footnote Styles.
5393 * forward-word: Def Cmd Template.
5394 * ftable: ftable vtable.
5396 * H: Inserting Accents.
5397 * heading: unnumberedsec appendixsec heading.
5398 * headings: headings on off.
5399 * html: Raw Formatter Commands.
5400 * hyphenation: - and hyphenation.
5401 * i (italic font): Fonts.
5402 * ifclear: ifset ifclear.
5403 * ifhtml <1>: Raw Formatter Commands.
5404 * ifhtml: Conditional Commands.
5405 * ifinfo: Conditional Commands.
5406 * ifnothtml: Conditional Not Commands.
5407 * ifnotinfo: Conditional Not Commands.
5408 * ifnottex: Conditional Not Commands.
5409 * ifset: ifset ifclear.
5410 * iftex: Conditional Commands.
5413 * include: Using Include Files.
5414 * Info-validate: Running Info-Validate.
5416 * input (TeX command): Minimum.
5417 * isearch-backward: deffnx.
5418 * isearch-forward: deffnx.
5419 * item <1>: Multitable Rows.
5425 * kbdinputstyle: kbd.
5427 * kindex: Indexing Commands.
5428 * L: Inserting Accents.
5429 * l: Inserting Accents.
5430 * lisp: Lisp Example.
5431 * lowersections: Raise/lower sections.
5432 * macro: Defining Macros.
5433 * mag (TeX command): Cropmarks and Magnification.
5434 * majorheading: majorheading & chapheading.
5435 * makeinfo-buffer: makeinfo in Emacs.
5436 * makeinfo-kill-job: makeinfo in Emacs.
5437 * makeinfo-recenter-output-buffer: makeinfo in Emacs.
5438 * makeinfo-region: makeinfo in Emacs.
5442 * multitable: Multi-column Tables.
5444 * next-error: makeinfo in Emacs.
5445 * noindent: noindent.
5446 * O: Inserting Accents.
5447 * o: Inserting Accents.
5448 * occur: Using occur.
5449 * occur-mode-goto-occurrence: Showing the Structure.
5450 * oddfooting: Custom Headings.
5451 * oddheading: Custom Headings.
5452 * OE: Inserting Accents.
5453 * oe: Inserting Accents.
5455 * paragraphindent: paragraphindent.
5456 * pindex: Indexing Commands.
5458 * printindex: Printing Indices & Menus.
5460 * questiondown: Inserting Accents.
5461 * quotation: quotation.
5462 * r (Roman font): Fonts.
5463 * raisesections: Raise/lower sections.
5465 * refill: Refilling Paragraphs.
5466 * ringaccent: Inserting Accents.
5468 * sc (small caps font): Smallcaps.
5470 * set: ifset ifclear.
5471 * setchapternewpage: setchapternewpage.
5472 * setfilename: setfilename.
5473 * settitle: settitle.
5474 * shortcontents: Contents.
5475 * shorttitlepage: titlepage.
5476 * smallbook: smallbook.
5477 * smallexample: smallexample & smalllisp.
5478 * smalllisp: smallexample & smalllisp.
5479 * sp (line spacing): sp.
5480 * sp (titlepage line spacing): titlefont center sp.
5481 * ss: Inserting Accents.
5482 * strong: emph & strong.
5483 * subheading: unnumberedsubsec appendixsubsec subheading.
5484 * subsection: subsection.
5485 * subsubheading: subsubsection.
5486 * subsubsection: subsubsection.
5487 * subtitle: title subtitle author.
5488 * summarycontents: Contents.
5489 * syncodeindex: syncodeindex.
5490 * synindex: synindex.
5491 * t (typewriter font): Fonts.
5492 * table: Two-column Tables.
5493 * tex: Raw Formatter Commands.
5494 * tex (command): tex.
5495 * texinfo-all-menus-update: Updating Commands.
5496 * texinfo-every-node-update: Updating Commands.
5497 * texinfo-format-buffer <1>: texinfo-format commands.
5498 * texinfo-format-buffer: Info Formatting.
5499 * texinfo-format-region <1>: texinfo-format commands.
5500 * texinfo-format-region: Info Formatting.
5501 * texinfo-indent-menu-description: Other Updating Commands.
5502 * texinfo-insert-@code: Inserting.
5503 * texinfo-insert-@dfn: Inserting.
5504 * texinfo-insert-@end: Inserting.
5505 * texinfo-insert-@example: Inserting.
5506 * texinfo-insert-@item: Inserting.
5507 * texinfo-insert-@kbd: Inserting.
5508 * texinfo-insert-@node: Inserting.
5509 * texinfo-insert-@noindent: Inserting.
5510 * texinfo-insert-@samp: Inserting.
5511 * texinfo-insert-@table: Inserting.
5512 * texinfo-insert-@var: Inserting.
5513 * texinfo-insert-braces: Inserting.
5514 * texinfo-insert-node-lines: Other Updating Commands.
5515 * texinfo-make-menu: Updating Commands.
5516 * texinfo-master-menu: Updating Commands.
5517 * texinfo-multiple-files-update: texinfo-multiple-files-update.
5518 * texinfo-multiple-files-update (in brief): Other Updating Commands.
5519 * texinfo-sequential-node-update: Other Updating Commands.
5520 * texinfo-show-structure <1>: Using texinfo-show-structure.
5521 * texinfo-show-structure: Showing the Structure.
5522 * texinfo-start-menu-description: Inserting.
5523 * texinfo-tex-buffer: Printing.
5524 * texinfo-tex-print: Printing.
5525 * texinfo-tex-region: Printing.
5526 * texinfo-update-node: Updating Commands.
5527 * thischapter: Custom Headings.
5528 * thischaptername: Custom Headings.
5529 * thisfile: Custom Headings.
5530 * thispage: Custom Headings.
5531 * thistitle: Custom Headings.
5532 * tieaccent: Inserting Accents.
5533 * tindex: Indexing Commands.
5534 * title: title subtitle author.
5535 * titlefont: titlefont center sp.
5536 * titlepage: titlepage.
5537 * today: Custom Headings.
5538 * top (@-command): makeinfo top command.
5539 * u: Inserting Accents.
5540 * ubaraccent: Inserting Accents.
5541 * udotaccent: Inserting Accents.
5542 * unmacro: Defining Macros.
5543 * unnumbered: unnumbered & appendix.
5544 * unnumberedsec: unnumberedsec appendixsec heading.
5545 * unnumberedsubsec: unnumberedsubsec appendixsubsec subheading.
5546 * unnumberedsubsubsec: subsubsection.
5547 * up-list: Inserting.
5550 * v: Inserting Accents.
5553 * vindex: Indexing Commands.
5554 * vskip: Copyright & Permissions.
5555 * vtable: ftable vtable.
5556 * w (prevent line break): w.
5558 * { (single {): Inserting Braces.
5559 * } (single }): Inserting Braces.
5560 * ~: Inserting Accents.
5563 File: texinfo.info, Node: Concept Index, Prev: Command and Variable Index, Up: Top
5570 * !: Inserting Accents.
5571 * (dir) as Up node of Top node: First Node.
5572 * --delete: Invoking install-info.
5573 * --dir-file=NAME: Invoking install-info.
5574 * --entry=TEXT: Invoking install-info.
5575 * --error-limit=LIMIT: makeinfo options.
5576 * --fill-column=WIDTH: makeinfo options.
5577 * --footnote-style=STYLE: makeinfo options.
5578 * --force: makeinfo options.
5579 * --help <1>: Invoking install-info.
5580 * --help: makeinfo options.
5581 * --info-dir=DIR: Invoking install-info.
5582 * --info-file=FILE: Invoking install-info.
5583 * --item=TEXT: Invoking install-info.
5584 * --no-headers: makeinfo options.
5585 * --no-number-footnotes: makeinfo options.
5586 * --no-pointer-validate: makeinfo options.
5587 * --no-split: makeinfo options.
5588 * --no-validate: makeinfo options.
5589 * --no-warn: makeinfo options.
5590 * --output=FILE: makeinfo options.
5591 * --paragraph-indent=INDENT: makeinfo options.
5592 * --quiet: Invoking install-info.
5593 * --reference-limit=LIMIT: makeinfo options.
5594 * --remove: Invoking install-info.
5595 * --section=SEC: Invoking install-info.
5596 * --verbose: makeinfo options.
5597 * --version <1>: Invoking install-info.
5598 * --version: makeinfo options.
5599 * -D VAR: makeinfo options.
5600 * -I DIR: makeinfo options.
5601 * -o FILE: makeinfo options.
5602 * -P DIR: makeinfo options.
5603 * .cshrc initialization file: Preparing for TeX.
5604 * .profile initialization file: Preparing for TeX.
5605 * /L: Inserting Accents.
5606 * /l: Inserting Accents.
5607 * /O: Inserting Accents.
5608 * /o: Inserting Accents.
5609 * ?: Inserting Accents.
5610 * @-command in nodename: Node Line Requirements.
5611 * @-command list: Command List.
5612 * @-command syntax: Command Syntax.
5613 * @-commands: Formatting Commands.
5614 * @include file sample: Sample Include File.
5615 * @menu parts: Menu Parts.
5616 * @node line writing: Writing a Node.
5617 * A4 paper, printing on: A4 Paper.
5618 * AA: Inserting Accents.
5619 * aa: Inserting Accents.
5620 * Abbreviations for keys: key.
5621 * Accents, inserting: Inserting Accents.
5622 * Acute accent: Inserting Accents.
5623 * Adding a new info file: New Info File.
5624 * AE: Inserting Accents.
5625 * ae: Inserting Accents.
5626 * Alphabetical @-command list: Command List.
5627 * Another Info directory: Other Info Directories.
5628 * Apostrophe in nodename: Node Line Requirements.
5629 * Arguments, repeated and optional: Optional Arguments.
5630 * Aspect ratio of images: Images.
5631 * Automatic pointer creation with makeinfo: makeinfo Pointer Creation.
5632 * Automatically insert nodes, menus: Updating Nodes and Menus.
5633 * Backslash, and macros: Invoking Macros.
5634 * Badly referenced nodes: Running Info-Validate.
5635 * Batch formatting for Info: Batch Formatting.
5636 * Beginning a Texinfo file: Beginning a File.
5637 * Beginning line of a Texinfo file: First Line.
5638 * Berry, Karl: Acknowledgements.
5639 * Big points: Images.
5640 * Black rectangle in hardcopy: Overfull hboxes.
5642 * Body of a macro: Defining Macros.
5643 * Book characteristics, printed: Printed Books.
5644 * Book, printing small: smallbook.
5645 * Box with rounded corners: cartouche.
5646 * Braces and argument syntax: Command Syntax.
5647 * Braces, inserting: Braces Atsigns.
5648 * Braces, when to use: Formatting Commands.
5649 * Breaks in a line: Line Breaks.
5650 * Breve accent: Inserting Accents.
5651 * Buffer formatting and printing: Printing.
5652 * Bullets, inserting: Dots Bullets.
5653 * Case in nodename: Node Line Requirements.
5654 * Catching errors with Info formatting: Debugging with Info.
5655 * Catching errors with TeX formatting: Debugging with TeX.
5656 * Catching mistakes: Catching Mistakes.
5657 * Cedilla accent: Inserting Accents.
5658 * Centimeters: Images.
5659 * Chapter structuring: Structuring.
5660 * Characteristics, printed books or manuals: Printed Books.
5661 * Chassell, Robert J.: Acknowledgements.
5662 * Check accent: Inserting Accents.
5663 * Checking for badly referenced nodes: Running Info-Validate.
5665 * Circumflex accent: Inserting Accents.
5666 * code, arg to @kbdinputstyle: kbd.
5667 * colon last in INFOPATH: Other Info Directories.
5668 * Column widths, defining for multitables: Multitable Column Widths.
5669 * Combining indices: Combining Indices.
5670 * Comma in nodename: Node Line Requirements.
5671 * Command definitions: Sample Function Definition.
5672 * Commands to insert special characters: Braces Atsigns.
5673 * Commands using raw HTML: Raw Formatter Commands.
5674 * Commands using raw TeX: Raw Formatter Commands.
5675 * Commands, inserting them: Inserting.
5676 * Comments: Comments.
5677 * Compile command for formatting: Compile-Command.
5678 * Conditionally visible text: Conditionals.
5679 * Conditions for copying Texinfo: Copying.
5680 * Contents, Table of: Contents.
5681 * Contents-like outline of file structure: Showing the Structure.
5682 * Conventions for writing definitions: Def Cmd Conventions.
5683 * Conventions, syntactic: Conventions.
5684 * Copying conditions: Copying.
5685 * Copying permissions: Sample Permissions.
5686 * Copying software: Software Copying Permissions.
5687 * Copyright page: Copyright & Permissions.
5688 * Correcting mistakes: Catching Mistakes.
5689 * Create nodes, menus automatically: Updating Nodes and Menus.
5690 * Creating an Info file: Create an Info File.
5691 * Creating an unsplit file: Unsplit.
5692 * Creating index entries: Indexing Commands.
5693 * Creating indices: Indices.
5694 * Creating pointers with makeinfo: makeinfo Pointer Creation.
5695 * Cropmarks for printing: Cropmarks and Magnification.
5696 * Cross reference parts: Cross Reference Parts.
5697 * Cross references: Cross References.
5698 * Cross references using @inforef: inforef.
5699 * Cross references using @pxref: pxref.
5700 * Cross references using @ref: ref.
5701 * Cross references using @xref: xref.
5702 * Customized highlighting: Customized Highlighting.
5703 * Customizing of TeX for Texinfo: Preparing for TeX.
5704 * Debugging the Texinfo structure: Catching Mistakes.
5705 * Debugging with Info formatting: Debugging with Info.
5706 * Debugging with TeX formatting: Debugging with TeX.
5707 * Defining indexing entries: Indexing Commands.
5708 * Defining macros: Defining Macros.
5709 * Defining new indices: New Indices.
5710 * Defining new Texinfo commands: Macros.
5711 * Definition commands: Definition Commands.
5712 * Definition conventions: Def Cmd Conventions.
5713 * Definition template: Def Cmd Template.
5714 * Definitions grouped together: deffnx.
5715 * Description for menu, start: Inserting.
5716 * Dido^t points: Images.
5717 * Different cross reference commands: Cross Reference Commands.
5718 * Dimension formatting: dmn.
5719 * Dimensions and image sizes: Images.
5720 * dir directory for Info installation: Install an Info File.
5721 * dir file listing: New Info File.
5722 * dir, created by install-info: Invoking install-info.
5723 * Display formatting: display.
5724 * distinct, arg to @kbdinputstyle: kbd.
5725 * Distorting images: Images.
5726 * Distribution: Software Copying Permissions.
5727 * Dot accent: Inserting Accents.
5728 * Dotless i, j: Inserting Accents.
5729 * Dots, inserting <1>: dots.
5730 * Dots, inserting: Dots Bullets.
5731 * Double-colon menu entries: Less Cluttered Menu Entry.
5732 * DVI file: Format with tex/texindex.
5733 * Ellipsis, inserting: Dots Bullets.
5734 * Emacs: Texinfo Mode.
5735 * Emacs shell, format, print from: Within Emacs.
5736 * Emphasizing text: Emphasis.
5737 * Emphasizing text, font for: emph & strong.
5738 * Enclosure command for Info: Customized Highlighting.
5739 * End node footnote style: Footnote Styles.
5740 * End of header line: End of Header.
5741 * End titlepage starts headings: end titlepage.
5742 * Ending a Sentence: Ending a Sentence.
5743 * Ending a Texinfo file: Ending a File.
5744 * Entries for an index: Indexing Commands.
5745 * Entries, making index: Index Entries.
5746 * Enumeration: enumerate.
5748 * epsf.tex, installing: Preparing for TeX.
5749 * Equivalence, indicating it: Equivalence.
5750 * Error message, indicating it: Error Glyph.
5751 * Errors, parsing: makeinfo in Emacs.
5752 * Es-zet: Inserting Accents.
5753 * European A4 paper: A4 Paper.
5754 * Evaluation glyph: result.
5755 * Example for a small book: smallexample & smalllisp.
5756 * Example menu: Menu Example.
5757 * example, arg to @kbdinputstyle: kbd.
5758 * Examples, formatting them: example.
5759 * Expansion, indicating it: expansion.
5760 * File beginning: Beginning a File.
5761 * File ending: Ending a File.
5762 * File section structure, showing it: Showing the Structure.
5763 * Filling paragraphs: Refilling Paragraphs.
5764 * Final output: Overfull hboxes.
5765 * Finding badly referenced nodes: Running Info-Validate.
5766 * Fine-tuning, and hyphenation: - and hyphenation.
5767 * First line of a Texinfo file: First Line.
5768 * First node: First Node.
5769 * Floating accents, inserting: Inserting Accents.
5770 * Fonts for indices: syncodeindex.
5771 * Fonts for printing, not for Info: Fonts.
5772 * Footings: Headings.
5773 * Footnotes: Footnotes.
5774 * Format a dimension: dmn.
5775 * Format and print hardcopy: Format/Print Hardcopy.
5776 * Format and print in Texinfo mode: Texinfo Mode Printing.
5777 * Format with the compile command: Compile-Command.
5778 * Format, print from Emacs shell: Within Emacs.
5779 * Formats for images: Images.
5780 * Formatting a file for Info: Create an Info File.
5781 * Formatting commands: Formatting Commands.
5782 * Formatting examples: example.
5783 * Formatting for Info: Info Formatting.
5784 * Formatting for printing: Printing.
5785 * Formatting headings and footings: Headings.
5786 * Formatting requirements: Requirements Summary.
5787 * Formatting with tex and texindex: Format with tex/texindex.
5788 * Frequently used commands, inserting: Inserting.
5789 * Function definitions: Sample Function Definition.
5790 * General syntactic conventions: Conventions.
5791 * Generating menus with indices: Printing Indices & Menus.
5792 * German S: Inserting Accents.
5793 * Globbing: Format with tex/texindex.
5795 * GNU Emacs: Texinfo Mode.
5796 * GNU Emacs shell, format, print from: Within Emacs.
5797 * Going to other Info files' nodes: Other Info Files.
5798 * Grave accent: Inserting Accents.
5799 * Group (hold text together vertically): group.
5800 * Grouping two definitions together: deffnx.
5801 * Hardcopy, printing it: Format/Print Hardcopy.
5802 * hboxes, overfull: Overfull hboxes.
5803 * Header for Texinfo files: Header.
5804 * Header of a Texinfo file: First Line.
5805 * Headings: Headings.
5806 * Headings, page, begin to appear: end titlepage.
5807 * Height of images: Images.
5808 * Highlighting text: Indicating.
5809 * Highlighting, customized: Customized Highlighting.
5811 * Holding text together vertically: group.
5812 * HTML commands, using ordinary: Raw Formatter Commands.
5813 * Hungariam umlaut accent: Inserting Accents.
5814 * Hyphenation, helping TeX do: - and hyphenation.
5815 * Hyphenation, preventing: w.
5816 * i: Inserting Accents.
5817 * If text conditionally visible: Conditionals.
5818 * ifinfo permissions: ifinfo Permissions.
5819 * Ignored before @setfilename: setfilename.
5820 * Ignored text: Comments.
5821 * Image formats: Images.
5822 * Images, inserting: Images.
5824 * Include file requirements: Include File Requirements.
5825 * Include file sample: Sample Include File.
5826 * Include files: Include Files.
5827 * Include files, and section levels: Raise/lower sections.
5828 * Indentation undoing: exdent.
5829 * Indenting paragraphs: paragraphindent.
5830 * Index entries: Indexing Commands.
5831 * Index entries, making: Index Entries.
5832 * Index entry writing: Indexing Commands.
5833 * Index font types: Indexing Commands.
5834 * Indexing commands, predefined: Indexing Commands.
5835 * Indexing table entries automatically: ftable vtable.
5836 * Indicating commands, definitions, etc.: Indicating.
5837 * Indicating evaluation: result.
5839 * Indices, combining them: Combining Indices.
5840 * Indices, defining new: New Indices.
5841 * Indices, printing and menus: Printing Indices & Menus.
5842 * Indices, sorting: Format/Print Hardcopy.
5843 * Indices, two letter names: syncodeindex.
5844 * Indirect subfiles: Tag and Split Files.
5845 * Info batch formatting: Batch Formatting.
5846 * Info file installation: Install an Info File.
5847 * Info file requires @setfilename: setfilename.
5848 * Info file, listing new one: New Info File.
5849 * Info file, splitting manually: Splitting.
5850 * Info files: Info Files.
5851 * Info formatting: Info Formatting.
5852 * Info installed in another directory: Other Info Directories.
5853 * Info validating a large file: Using Info-validate.
5854 * Info, creating an on-line file: Create an Info File.
5855 * Info-directory-list: Other Info Directories.
5856 * Info; other files' nodes: Other Info Files.
5857 * INFOPATH: Other Info Directories.
5858 * Initialization file for TeX input: Preparing for TeX.
5859 * Insert nodes, menus automatically: Updating Nodes and Menus.
5860 * Inserting @, braces: Braces Atsigns.
5861 * Inserting accents: Inserting Accents.
5862 * Inserting dots <1>: dots.
5863 * Inserting dots: Dots Bullets.
5864 * Inserting ellipsis: Dots Bullets.
5865 * Inserting frequently used commands: Inserting.
5866 * Inserting space: Inserting Space.
5867 * Inserting special characters and symbols: Insertions.
5868 * install-info: Invoking install-info.
5869 * Installing an Info file: Install an Info File.
5870 * Installing Info in another directory: Other Info Directories.
5871 * Introduction, as part of file: Software Copying Permissions.
5872 * Invoking macros: Invoking Macros.
5873 * Itemization: itemize.
5874 * j: Inserting Accents.
5875 * keyboard input: kbd.
5876 * Keys, recommended names: key.
5877 * Knuth, Donald: Printed Books.
5878 * Larger or smaller pages: Cropmarks and Magnification.
5879 * Less cluttered menu entry: Less Cluttered Menu Entry.
5880 * License agreement: Software Copying Permissions.
5881 * Line breaks: Line Breaks.
5882 * Line breaks, preventing: w.
5883 * Line length, column widths as fraction of: Multitable Column Widths.
5885 * Lisp example: Lisp Example.
5886 * Lisp example for a small book: smallexample & smalllisp.
5887 * List of @-commands: Command List.
5888 * Listing a new info file: New Info File.
5889 * Lists and tables, making: Lists and Tables.
5890 * Local variables: Compile-Command.
5891 * Location of menus: Menu Location.
5892 * Looking for badly referenced nodes: Running Info-Validate.
5893 * lpr (DVI print command): Print with lpr.
5894 * Macro definitions <1>: Defining Macros.
5895 * Macro definitions: Sample Function Definition.
5896 * Macro invocation: Invoking Macros.
5897 * Macron accent: Inserting Accents.
5899 * Macros, undefining: Defining Macros.
5900 * Magnified printing: Cropmarks and Magnification.
5901 * mailto link: email.
5902 * makeinfo inside Emacs: makeinfo in Emacs.
5903 * makeinfo options: makeinfo options.
5904 * Making a printed manual: Format/Print Hardcopy.
5905 * Making a tag table automatically: Tag and Split Files.
5906 * Making a tag table manually: Unsplit.
5907 * Making cross references: Cross References.
5908 * Making line and page breaks: Breaks.
5909 * Making lists and tables: Lists and Tables.
5910 * Manual characteristics, printed: Printed Books.
5911 * Marking text within a paragraph: Marking Text.
5912 * Marking words and phrases: Marking Text.
5913 * Master menu: The Top Node.
5914 * Master menu parts: Master Menu Parts.
5915 * Mathematical expressions <1>: Raw Formatter Commands.
5916 * Mathematical expressions: math.
5917 * Menu description, start: Inserting.
5918 * Menu entries with two colons: Less Cluttered Menu Entry.
5919 * Menu example: Menu Example.
5920 * Menu location: Menu Location.
5921 * Menu parts: Menu Parts.
5922 * Menu writing: Writing a Menu.
5924 * Menus generated with indices: Printing Indices & Menus.
5926 * Meta-syntactic chars for arguments: Optional Arguments.
5927 * Millimeters: Images.
5928 * Minimal requirements for formatting: Requirements Summary.
5929 * Minimal Texinfo file (requirements): Minimum.
5930 * Mistakes, catching: Catching Mistakes.
5931 * Mode, using Texinfo: Texinfo Mode.
5932 * Multiple spaces: Multiple Spaces.
5933 * Multitable column widths: Multitable Column Widths.
5934 * Multitable rows: Multitable Rows.
5935 * Must have in Texinfo file: Minimum.
5936 * Mutually recursive macros: Defining Macros.
5937 * Names for indices: syncodeindex.
5938 * Names of index files: Format with tex/texindex.
5939 * Names recommended for keys: key.
5940 * Naming a `Top' Node in references: Top Node Naming.
5941 * Need space at page bottom: need.
5942 * New index defining: New Indices.
5943 * New info file, listing it in dir file: New Info File.
5944 * New Texinfo commands, defining: Macros.
5945 * Node line requirements: Node Line Requirements.
5946 * Node line writing: Writing a Node.
5947 * Node, `Top': The Top Node.
5948 * Node, defined: node.
5949 * Nodename must be unique: Node Line Requirements.
5950 * Nodename, cannot contain: Node Line Requirements.
5951 * Nodes for menus are short: Menu Location.
5952 * Nodes in other Info files: Other Info Files.
5953 * Nodes, catching mistakes: Catching Mistakes.
5954 * Nodes, checking for badly referenced: Running Info-Validate.
5955 * Not ending a sentence: Not Ending a Sentence.
5956 * Obtaining TeX: Obtaining TeX.
5957 * Occurrences, listing with @occur: Using occur.
5958 * OE: Inserting Accents.
5959 * oe: Inserting Accents.
5960 * Optional and repeated arguments: Optional Arguments.
5961 * Options for makeinfo: makeinfo options.
5962 * Ordinary HTML commands, using: Raw Formatter Commands.
5963 * Ordinary TeX commands, using: Raw Formatter Commands.
5964 * Other Info files' nodes: Other Info Files.
5965 * Outline of file structure, showing it: Showing the Structure.
5966 * Overfull hboxes: Overfull hboxes.
5967 * Overview of Texinfo: Overview.
5968 * Page breaks: page.
5969 * Page delimiter in Texinfo mode: Showing the Structure.
5970 * Page headings: Headings.
5971 * Page numbering: Headings.
5972 * Page sizes for books: smallbook.
5973 * page-delimiter: Showing the Structure.
5974 * Pages, starting odd: setchapternewpage.
5975 * Paper size, European A4: A4 Paper.
5976 * Paragraph indentation: paragraphindent.
5977 * Paragraph, marking text within: Marking Text.
5978 * Parsing errors: makeinfo in Emacs.
5979 * Part of file formatting and printing: Printing.
5980 * Parts of a cross reference: Cross Reference Parts.
5981 * Parts of a master menu: Master Menu Parts.
5982 * Parts of a menu: Menu Parts.
5983 * Periods, inserting: Not Ending a Sentence.
5984 * Permissions: Sample Permissions.
5985 * Permissions, printed: Copyright & Permissions.
5987 * Pictures, inserting: Images.
5988 * Pinard, Franc,ois: Acknowledgements.
5989 * plain TeX: Raw Formatter Commands.
5990 * Point, indicating it in a buffer: Point Glyph.
5991 * Pointer creation with makeinfo: makeinfo Pointer Creation.
5992 * Pointer validation with makeinfo: Pointer Validation.
5993 * Points (dimension): Images.
5994 * Predefined indexing commands: Indexing Commands.
5995 * Predefined names for indices: syncodeindex.
5996 * Preparing to use TeX: Preparing for TeX.
5997 * Preventing line and page breaks: Breaks.
5998 * Previous node of Top node: First Node.
5999 * Print and format in Texinfo mode: Texinfo Mode Printing.
6000 * Print, format from Emacs shell: Within Emacs.
6001 * Printed book and manual characteristics: Printed Books.
6002 * Printed output, indicating it: Print Glyph.
6003 * Printed permissions: Copyright & Permissions.
6004 * Printing a region or buffer: Printing.
6005 * Printing an index: Printing Indices & Menus.
6006 * Printing cropmarks: Cropmarks and Magnification.
6007 * Problems, catching: Catching Mistakes.
6008 * Prototype row, column widths defined by: Multitable Column Widths.
6009 * Quotations: quotation.
6010 * Raising and lowering sections: Raise/lower sections.
6011 * Raw formatter commands: Raw Formatter Commands.
6012 * Recommended names for keys: key.
6013 * Rectangle, ugly, black in hardcopy: Overfull hboxes.
6014 * Recursion, mutual: Defining Macros.
6015 * References: Cross References.
6016 * References using @inforef: inforef.
6017 * References using @pxref: pxref.
6018 * References using @ref: ref.
6019 * References using @xref: xref.
6020 * Referring to other Info files: Other Info Files.
6021 * Refilling paragraphs: Refilling Paragraphs.
6022 * Region formatting and printing: Printing.
6023 * Region printing in Texinfo mode: Texinfo Mode Printing.
6024 * Repeated and optional arguments: Optional Arguments.
6025 * Required in Texinfo file: Minimum.
6026 * Requirements for formatting: Requirements Summary.
6027 * Requirements for include files: Include File Requirements.
6028 * Requirements for updating commands: Updating Requirements.
6029 * Result of an expression: result.
6031 * Ring accent: Inserting Accents.
6032 * Rows, of a multitable: Multitable Rows.
6033 * Running an Info formatter: Info Formatting.
6034 * Running Info-validate: Using Info-validate.
6035 * Running makeinfo in Emacs: makeinfo in Emacs.
6036 * Sample @include file: Sample Include File.
6037 * Sample function definition: Sample Function Definition.
6038 * Sample Texinfo file: Short Sample.
6039 * Sample Texinfo file, no comments: Sample Texinfo File.
6040 * Scaled points: Images.
6041 * Section structure of a file, showing it: Showing the Structure.
6042 * Sections, raising and lowering: Raise/lower sections.
6043 * Sentence ending punctuation: Ending a Sentence.
6044 * Sentence non-ending punctuation: Not Ending a Sentence.
6045 * Separate footnote style: Footnote Styles.
6046 * Sharp S: Inserting Accents.
6047 * Shell formatting with tex and texindex: Format with tex/texindex.
6048 * Shell, format, print from: Within Emacs.
6049 * Shell, running makeinfo in: makeinfo in Emacs.
6050 * Short nodes for menus: Menu Location.
6051 * Showing the section structure of a file: Showing the Structure.
6052 * Showing the structure of a file: Using texinfo-show-structure.
6053 * Site-wide Texinfo configuration file: Preparing for TeX.
6054 * Size of printed book: smallbook.
6055 * slanted typewriter font, for @kbd: kbd.
6056 * Small book example: smallexample & smalllisp.
6057 * Small book size: smallbook.
6058 * Small caps font: Smallcaps.
6059 * Software copying permissions: Software Copying Permissions.
6060 * Sorting indices: Format/Print Hardcopy.
6061 * Spaces (blank lines): sp.
6062 * Spacing, inserting: Inserting Space.
6063 * Special characters, commands to insert: Braces Atsigns.
6064 * Special insertions: Insertions.
6065 * Special typesetting commands: Dots Bullets.
6066 * Specifying index entries: Indexing Commands.
6067 * Splitting an Info file manually: Splitting.
6068 * ss: Inserting Accents.
6069 * Stallman, Richard M.: Acknowledgements.
6070 * Start of header line: Start of Header.
6071 * Starting chapters: setchapternewpage.
6072 * Structure of a file, showing it: Showing the Structure.
6073 * Structure, catching mistakes in: Catching Mistakes.
6074 * Structuring of chapters: Structuring.
6075 * Subsection-like commands: unnumberedsubsec appendixsubsec subheading.
6076 * Subsub commands: subsubsection.
6077 * Syntactic conventions: Conventions.
6078 * Syntax, optional & repeated arguments: Optional Arguments.
6079 * tab: Multitable Rows.
6080 * Table of contents: Contents.
6081 * Tables and lists, making: Lists and Tables.
6082 * Tables with indexes: ftable vtable.
6083 * Tables, making multi-column: Multi-column Tables.
6084 * Tables, making two-column: Two-column Tables.
6085 * Tabs; don't use!: Conventions.
6086 * Tag table, making automatically: Tag and Split Files.
6087 * Tag table, making manually: Unsplit.
6088 * Template for a definition: Def Cmd Template.
6089 * TeX commands, using ordinary: Raw Formatter Commands.
6090 * TeX index sorting: Format/Print Hardcopy.
6091 * TeX input initialization: Preparing for TeX.
6092 * TeX, how to obtain: Obtaining TeX.
6093 * texi2dvi: Format with tex/texindex.
6094 * texi2dvi (shell script): Format with texi2dvi.
6095 * texindex <1>: Format with tex/texindex.
6096 * texindex: Format/Print Hardcopy.
6097 * Texinfo commands, defining new: Macros.
6098 * Texinfo file beginning: Beginning a File.
6099 * Texinfo file ending: Ending a File.
6100 * Texinfo file header: Header.
6101 * Texinfo file minimum: Minimum.
6102 * Texinfo file section structure, showing it: Showing the Structure.
6103 * Texinfo mode: Texinfo Mode.
6104 * Texinfo overview: Overview.
6105 * Texinfo printed book characteristics: Printed Books.
6106 * texinfo.cnf <1>: A4 Paper.
6107 * texinfo.cnf: setfilename.
6108 * texinfo.cnf installation: Preparing for TeX.
6109 * texinfo.tex, installing: Preparing for TeX.
6110 * TEXINPUTS: Preparing for TeX.
6111 * TEXINPUTS environment variable: Preparing for TeX.
6112 * Text, conditionally visible: Conditionals.
6113 * Thin space between number, dimension: dmn.
6114 * Tie-after accent: Inserting Accents.
6115 * Tilde accent: Inserting Accents.
6117 * Title page: titlepage.
6118 * Titlepage end starts headings: end titlepage.
6119 * Titlepage permissions: Titlepage Permissions.
6120 * Top node: The Top Node.
6121 * Top node is first: First Node.
6122 * Top node naming for references: Top Node Naming.
6123 * Top node summary: Top Node Summary.
6124 * Tree structuring: Tree Structuring.
6125 * Two `First' Lines for @deffn: deffnx.
6126 * Two letter names for indices: syncodeindex.
6127 * Two named items for @table: itemx.
6128 * Two part menu entry: Less Cluttered Menu Entry.
6129 * Typesetting commands for dots, etc.: Dots Bullets.
6130 * Umlaut accent: Inserting Accents.
6131 * Uncluttered menu entry: Less Cluttered Menu Entry.
6132 * Undefining macros: Defining Macros.
6133 * Underbar accent: Inserting Accents.
6134 * Underdot accent: Inserting Accents.
6135 * Uniform resource locator, indicating: url.
6136 * Uniform resource locator, referring to: uref.
6137 * Unique nodename requirement: Node Line Requirements.
6138 * Unprocessed text: Comments.
6139 * Unsplit file creation: Unsplit.
6140 * Up node of Top node: First Node.
6141 * Updating nodes and menus: Updating Nodes and Menus.
6142 * Updating requirements: Updating Requirements.
6143 * URL, indicating: url.
6144 * URL, referring to: uref.
6147 * User options, marking: Variables Commands.
6148 * User-defined Texinfo commands: Macros.
6149 * Validating a large file: Using Info-validate.
6150 * Validation of pointers: Pointer Validation.
6151 * Value of an expression, indicating: result.
6152 * version number, finding: Invoking install-info.
6153 * Vertical whitespace (vskip): Copyright & Permissions.
6154 * Vertically holding text together: group.
6155 * Visibility of conditional text: Conditionals.
6156 * Weisshaus, Melissa: Acknowledgements.
6157 * Whitespace, inserting <1>: Multiple Spaces.
6158 * Whitespace, inserting: Inserting Space.
6159 * Width of images: Images.
6160 * Widths, defining multitable column: Multitable Column Widths.
6161 * Wildcards: Format with tex/texindex.
6162 * Words and phrases, marking them: Marking Text.
6163 * Writing a menu: Writing a Menu.
6164 * Writing an @node line: Writing a Node.
6165 * Writing index entries: Indexing Commands.
6166 * Zuhn, David D.: Acknowledgements.