1 This is ../info/texinfo.info, produced by makeinfo version 4.0 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: Short Sample, Next: Acknowledgements, Prev: Six Parts, Up: Overview
38 A Short Sample Texinfo File
39 ===========================
41 Here is a complete but very short Texinfo file, in six parts. The
42 first three parts of the file, from `\input texinfo' through to `@end
43 titlepage', look more intimidating than they are. Most of the material
44 is standard boilerplate; when you write a manual, simply insert the
45 names for your own manual in this segment. (*Note Beginning a File::.)
47 In the following, the sample text is _indented_; comments on it are
48 not. The complete file, without any comments, is shown in *Note Sample
54 The header does not appear in either the Info file or the printed
55 output. It sets various parameters, including the name of the Info
56 file and the title used in the header.
58 \input texinfo @c -*-texinfo-*-
60 @setfilename sample.info
61 @settitle Sample Document
64 @setchapternewpage odd
66 Part 2: Summary Description and Copyright
67 -----------------------------------------
69 The summary description and copyright segment does not appear in the
73 This is a short example of a complete Texinfo file.
75 Copyright @copyright{} 1990 Free Software Foundation, Inc.
78 Part 3: Titlepage and Copyright
79 -------------------------------
81 The titlepage segment does not appear in the Info file.
85 @comment The title is printed in a large font.
86 @center @titlefont{Sample Title}
88 @c The following two commands start the copyright page.
90 @vskip 0pt plus 1filll
91 Copyright @copyright{} 1990 Free Software Foundation, Inc.
94 Part 4: `Top' Node and Master Menu
95 ----------------------------------
97 The `Top' node contains the master menu for the Info file. Since a
98 printed manual uses a table of contents rather than a menu, the master
99 menu appears only in the Info file.
101 @node Top, First Chapter, , (dir)
102 @comment node-name, next, previous, up
105 * First Chapter:: The first chapter is the
106 only chapter in this sample.
107 * Concept Index:: This index has two entries.
110 Part 5: The Body of the Document
111 ---------------------------------
113 The body segment contains all the text of the document, but not the
114 indices or table of contents. This example illustrates a node and a
115 chapter containing an enumerated list.
117 @node First Chapter, Concept Index, Top, Top
118 @comment node-name, next, previous, up
119 @chapter First Chapter
120 @cindex Sample index entry
122 This is the contents of the first chapter.
123 @cindex Another sample index entry
125 Here is a numbered list.
129 This is the first item.
132 This is the second item.
135 The @code{makeinfo} and @code{texinfo-format-buffer}
136 commands transform a Texinfo file such as this into
137 an Info file; and @TeX{} typesets it for a printed
140 Part 6: The End of the Document
141 -------------------------------
143 The end segment contains commands both for generating an index in a node
144 and unnumbered chapter of its own and for generating the table of
145 contents; and it contains the `@bye' command that marks the end of the
148 @node Concept Index, , First Chapter, Top
149 @comment node-name, next, previous, up
150 @unnumbered Concept Index
160 Here is what the contents of the first chapter of the sample look
164 This is the contents of the first chapter.
166 Here is a numbered list.
168 1. This is the first item.
170 2. This is the second item.
172 The `makeinfo' and `texinfo-format-buffer' commands transform a
173 Texinfo file such as this into an Info file; and TeX typesets it
174 for a printed manual.
177 File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview
182 Richard M. Stallman wrote Edition 1.0 of this manual.
183 Robert J. Chassell revised and extended it, starting with Edition 1.1.
184 Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
185 starting with Edition 2.22.
187 Our thanks go out to all who helped improve this work, particularly to
188 Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
189 reported mistakes and obscurities; our special thanks go to Melissa
190 Weisshaus for her frequent and often tedious reviews of nearly similar
191 editions. Our mistakes are our own.
193 Please send suggestions and corrections to:
198 Please include the manual's edition number and update date in your
202 File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
207 You may edit a Texinfo file with any text editor you choose. A
208 Texinfo file is no different from any other ASCII file. However, GNU
209 Emacs comes with a special mode, called Texinfo mode, that provides
210 Emacs commands and tools to help ease your work.
212 This chapter describes features of GNU Emacs' Texinfo mode but not any
213 features of the Texinfo formatting language. If you are reading this
214 manual straight through from the beginning, you may want to skim through
215 this chapter briefly and come back to it after reading succeeding
216 chapters which describe the Texinfo formatting language in detail.
220 * Texinfo Mode Overview:: How Texinfo mode can help you.
221 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
222 purpose editing features.
223 * Inserting:: How to insert frequently used @-commands.
224 * Showing the Structure:: How to show the structure of a file.
225 * Updating Nodes and Menus:: How to update or create new nodes and menus.
226 * Info Formatting:: How to format for Info.
227 * Printing:: How to format and print part or all of a file.
228 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
231 File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode
233 Texinfo Mode Overview
234 =====================
236 Texinfo mode provides special features for working with Texinfo files:
238 * Insert frequently used @-commands.
240 * Automatically create `@node' lines.
242 * Show the structure of a Texinfo source file.
244 * Automatically create or update the `Next', `Previous', and `Up'
247 * Automatically create or update menus.
249 * Automatically create a master menu.
251 * Format a part or all of a file for Info.
253 * Typeset and print part or all of a file.
255 Perhaps the two most helpful features are those for inserting
256 frequently used @-commands and for creating node pointers and menus.
259 File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode
261 The Usual GNU Emacs Editing Commands
262 ====================================
264 In most cases, the usual Text mode commands work the same in Texinfo
265 mode as they do in Text mode. Texinfo mode adds new editing commands
266 and tools to GNU Emacs' general purpose editing features. The major
267 difference concerns filling. In Texinfo mode, the paragraph separation
268 variable and syntax table are redefined so that Texinfo commands that
269 should be on lines of their own are not inadvertently included in
270 paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a
271 paragraph but not mix an indexing command on a line adjacent to it into
274 In addition, Texinfo mode sets the `page-delimiter' variable to the
275 value of `texinfo-chapter-level-regexp'; by default, this is a regular
276 expression matching the commands for chapters and their equivalents,
277 such as appendices. With this value for the page delimiter, you can
278 jump from chapter title to chapter title with the `C-x ]'
279 (`forward-page') and `C-x [' (`backward-page') commands and narrow to a
280 chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages:
281 (xemacs)Pages, for details about the page commands.)
283 You may name a Texinfo file however you wish, but the convention is to
284 end a Texinfo file name with one of the three extensions `.texinfo',
285 `.texi', or `.tex'. A longer extension is preferred, since it is
286 explicit, but a shorter extension may be necessary for operating
287 systems that limit the length of file names. GNU Emacs automatically
288 enters Texinfo mode when you visit a file with a `.texinfo' or `.texi'
289 extension. Also, Emacs switches to Texinfo mode when you visit a file
290 that has `-*-texinfo-*-' in its first line. If ever you are in another
291 mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
293 Like all other Emacs features, you can customize or enhance Texinfo
294 mode as you wish. In particular, the keybindings are very easy to
295 change. The keybindings described here are the default or standard
299 File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode
301 Inserting Frequently Used Commands
302 ==================================
304 Texinfo mode provides commands to insert various frequently used
305 @-commands into the buffer. You can use these commands to save
308 The insert commands are invoked by typing `C-c' twice and then the
309 first letter of the @-command:
312 `M-x texinfo-insert-@code'
313 Insert `@code{}' and put the cursor between the braces.
316 `M-x texinfo-insert-@dfn'
317 Insert `@dfn{}' and put the cursor between the braces.
320 `M-x texinfo-insert-@end'
321 Insert `@end' and attempt to insert the correct following word,
322 such as `example' or `table'. (This command does not handle
323 nested lists correctly, but inserts the word appropriate to the
324 immediately preceding list.)
327 `M-x texinfo-insert-@item'
328 Insert `@item' and put the cursor at the beginning of the next
332 `M-x texinfo-insert-@kbd'
333 Insert `@kbd{}' and put the cursor between the braces.
336 `M-x texinfo-insert-@node'
337 Insert `@node' and a comment line listing the sequence for the
338 `Next', `Previous', and `Up' nodes. Leave point after the `@node'.
341 `M-x texinfo-insert-@noindent'
342 Insert `@noindent' and put the cursor at the beginning of the next
346 `M-x texinfo-insert-@samp'
347 Insert `@samp{}' and put the cursor between the braces.
350 `M-x texinfo-insert-@table'
351 Insert `@table' followed by a <SPC> and leave the cursor after the
355 `M-x texinfo-insert-@var'
356 Insert `@var{}' and put the cursor between the braces.
359 `M-x texinfo-insert-@example'
360 Insert `@example' and put the cursor at the beginning of the next
364 `M-x texinfo-insert-braces'
365 Insert `{}' and put the cursor between the braces.
370 Move from between a pair of braces forward past the closing brace.
371 Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
372 however, more mnemonic; hence the two keybindings. (Also, you can
373 move out from between braces by typing `C-f'.)
375 To put a command such as `@code{...}' around an _existing_ word,
376 position the cursor in front of the word and type `C-u 1 C-c C-c c'.
377 This makes it easy to edit existing plain text. The value of the
378 prefix argument tells Emacs how many words following point to include
379 between braces--`1' for one word, `2' for two words, and so on. Use a
380 negative argument to enclose the previous word or words. If you do not
381 specify a prefix argument, Emacs inserts the @-command string and
382 positions the cursor between the braces. This feature works only for
383 those @-commands that operate on a word or words within one line, such
384 as `@kbd' and `@var'.
386 This set of insert commands was created after analyzing the frequency
387 with which different @-commands are used in the `GNU Emacs Manual' and
388 the `GDB Manual'. If you wish to add your own insert commands, you can
389 bind a keyboard macro to a key, use abbreviations, or extend the code
392 `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
393 that works differently from the other insert commands. It inserts a
394 node's section or chapter title in the space for the description in a
395 menu entry line. (A menu entry has three parts, the entry name, the
396 node name, and the description. Only the node name is required, but a
397 description helps explain what the node is about. *Note The Parts of a
400 To use `texinfo-start-menu-description', position point in a menu
401 entry line and type `C-c C-c C-d'. The command looks for and copies
402 the title that goes with the node name, and inserts the title as a
403 description; it positions point at beginning of the inserted text so you
404 can edit it. The function does not insert the title if the menu entry
405 line already contains a description.
407 This command is only an aid to writing descriptions; it does not do
408 the whole job. You must edit the inserted text since a title tends to
409 use the same words as a node name but a useful description uses
413 File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode
415 Showing the Section Structure of a File
416 =======================================
418 You can show the section structure of a Texinfo file by using the
419 `C-c C-s' command (`texinfo-show-structure'). This command shows the
420 section structure of a Texinfo file by listing the lines that begin
421 with the @-commands for `@chapter', `@section', and the like. It
422 constructs what amounts to a table of contents. These lines are
423 displayed in another buffer called the `*Occur*' buffer. In that
424 buffer, you can position the cursor over one of the lines and use the
425 `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
426 corresponding spot in the Texinfo file.
429 `M-x texinfo-show-structure'
430 Show the `@chapter', `@section', and such lines of a Texinfo file.
433 `M-x occur-mode-goto-occurrence'
434 Go to the line in the Texinfo file corresponding to the line under
435 the cursor in the `*Occur*' buffer.
437 If you call `texinfo-show-structure' with a prefix argument by typing
438 `C-u C-c C-s', it will list not only those lines with the @-commands
439 for `@chapter', `@section', and the like, but also the `@node' lines.
440 (This is how the `texinfo-show-structure' command worked without an
441 argument in the first version of Texinfo. It was changed because
442 `@node' lines clutter up the `*Occur*' buffer and are usually not
443 needed.) You can use `texinfo-show-structure' with a prefix argument
444 to check whether the `Next', `Previous', and `Up' pointers of an
445 `@node' line are correct.
447 Often, when you are working on a manual, you will be interested only
448 in the structure of the current chapter. In this case, you can mark
449 off the region of the buffer that you are interested in by using the
450 `C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
451 will work on only that region. To see the whole buffer again, use
452 `C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more
453 information about the narrowing commands.)
455 In addition to providing the `texinfo-show-structure' command,
456 Texinfo mode sets the value of the page delimiter variable to match the
457 chapter-level @-commands. This enables you to use the `C-x ]'
458 (`forward-page') and `C-x [' (`backward-page') commands to move forward
459 and backward by chapter, and to use the `C-x p' (`narrow-to-page')
460 command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more
461 information about the page commands.
464 File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode
466 Updating Nodes and Menus
467 ========================
469 Texinfo mode provides commands for automatically creating or updating
470 menus and node pointers. The commands are called "update" commands
471 because their most frequent use is for updating a Texinfo file after
472 you have worked on it; but you can use them to insert the `Next',
473 `Previous', and `Up' pointers into an `@node' line that has none and to
474 create menus in a file that has none.
476 If you do not use the updating commands, you need to write menus and
477 node pointers by hand, which is a tedious task.
481 * Updating Commands:: Five major updating commands.
482 * Updating Requirements:: How to structure a Texinfo file for
483 using the updating command.
484 * Other Updating Commands:: How to indent descriptions, insert
485 missing nodes lines, and update
489 File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus
491 The Updating Commands
492 ---------------------
494 You can use the updating commands
496 * to insert or update the `Next', `Previous', and `Up' pointers of a
499 * to insert or update the menu for a section, and
501 * to create a master menu for a Texinfo source file.
503 You can also use the commands to update all the nodes and menus in a
504 region or in a whole Texinfo file.
506 The updating commands work only with conventional Texinfo files, which
507 are structured hierarchically like books. In such files, a structuring
508 command line must follow closely after each `@node' line, except for
509 the `Top' `@node' line. (A "structuring command line" is a line
510 beginning with `@chapter', `@section', or other similar command.)
512 You can write the structuring command line on the line that follows
513 immediately after an `@node' line or else on the line that follows
514 after a single `@comment' line or a single `@ifinfo' line. You cannot
515 interpose more than one line between the `@node' line and the
516 structuring command line; and you may interpose only an `@comment' line
517 or an `@ifinfo' line.
519 Commands which work on a whole buffer require that the `Top' node be
520 followed by a node with an `@chapter' or equivalent-level command.
521 Note that the menu updating commands will not create a main or master
522 menu for a Texinfo file that has only `@chapter'-level nodes! The menu
523 updating commands only create menus _within_ nodes for lower level
524 nodes. To create a menu of chapters, you must provide a `Top' node.
526 The menu updating commands remove menu entries that refer to other
527 Info files since they do not refer to nodes within the current buffer.
528 This is a deficiency. Rather than use menu entries, you can use cross
529 references to refer to other Info files. None of the updating commands
530 affect cross references.
532 Texinfo mode has five updating commands that are used most often: two
533 are for updating the node pointers or menu of a single node (or a
534 region); two are for updating every node pointer and menu in a file;
535 and one, the `texinfo-master-menu' command, is for creating a master
536 menu for a complete file, and optionally, for updating every node and
537 menu in the whole Texinfo file.
539 The `texinfo-master-menu' command is the primary command:
542 `M-x texinfo-master-menu'
543 Create or update a master menu that includes all the other menus
544 (incorporating the descriptions from pre-existing menus, if any).
546 With an argument (prefix argument, `C-u,' if interactive), first
547 create or update all the nodes and all the regular menus in the
548 buffer before constructing the master menu. (*Note The Top Node
549 and Master Menu: The Top Node, for more about a master menu.)
551 For `texinfo-master-menu' to work, the Texinfo file must have a
552 `Top' node and at least one subsequent node.
554 After extensively editing a Texinfo file, you can type the
557 C-u M-x texinfo-master-menu
561 This updates all the nodes and menus completely and all at once.
563 The other major updating commands do smaller jobs and are designed for
564 the person who updates nodes and menus as he or she writes a Texinfo
570 `M-x texinfo-update-node'
571 Insert the `Next', `Previous', and `Up' pointers for the node that
572 point is within (i.e., for the `@node' line preceding point). If
573 the `@node' line has pre-existing `Next', `Previous', or `Up'
574 pointers in it, the old pointers are removed and new ones inserted.
575 With an argument (prefix argument, `C-u', if interactive), this
576 command updates all `@node' lines in the region (which is the text
577 between point and mark).
580 `M-x texinfo-make-menu'
581 Create or update the menu in the node that point is within. With
582 an argument (`C-u' as prefix argument, if interactive), the
583 command makes or updates menus for the nodes which are either
584 within or a part of the region.
586 Whenever `texinfo-make-menu' updates an existing menu, the
587 descriptions from that menu are incorporated into the new menu.
588 This is done by copying descriptions from the existing menu to the
589 entries in the new menu that have the same node names. If the
590 node names are different, the descriptions are not copied to the
594 `M-x texinfo-every-node-update'
595 Insert or update the `Next', `Previous', and `Up' pointers for
596 every node in the buffer.
599 `M-x texinfo-all-menus-update'
600 Create or update all the menus in the buffer. With an argument
601 (`C-u' as prefix argument, if interactive), first insert or update
602 all the node pointers before working on the menus.
604 If a master menu exists, the `texinfo-all-menus-update' command
605 updates it; but the command does not create a new master menu if
606 none already exists. (Use the `texinfo-master-menu' command for
609 When working on a document that does not merit a master menu, you
610 can type the following:
614 C-u M-x texinfo-all-menus-update
616 This updates all the nodes and menus.
618 The `texinfo-column-for-description' variable specifies the column to
619 which menu descriptions are indented. By default, the value is 32
620 although it is often useful to reduce it to as low as 24. You can set
621 the variable with the `M-x edit-options' command (*note Editing
622 Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
623 command (*note Examining and Setting Variables: (xemacs)Examining.).
625 Also, the `texinfo-indent-menu-description' command may be used to
626 indent existing menu descriptions to a specified column. Finally, if
627 you wish, you can use the `texinfo-insert-node-lines' command to insert
628 missing `@node' lines into a file. (*Note Other Updating Commands::,
629 for more information.)
632 File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus
634 Updating Requirements
635 ---------------------
637 To use the updating commands, you must organize the Texinfo file
638 hierarchically with chapters, sections, subsections, and the like.
639 When you construct the hierarchy of the manual, do not `jump down' more
640 than one level at a time: you can follow the `Top' node with a chapter,
641 but not with a section; you can follow a chapter with a section, but
642 not with a subsection. However, you may `jump up' any number of levels
643 at one time--for example, from a subsection to a chapter.
645 Each `@node' line, with the exception of the line for the `Top' node,
646 must be followed by a line with a structuring command such as
647 `@chapter', `@section', or `@unnumberedsubsec'.
649 Each `@node' line/structuring-command line combination must look
652 @node Comments, Minimum, Conventions, Overview
653 @comment node-name, next, previous, up
656 or like this (without the `@comment' line):
658 @node Comments, Minimum, Conventions, Overview
661 In this example, `Comments' is the name of both the node and the
662 section. The next node is called `Minimum' and the previous node is
663 called `Conventions'. The `Comments' section is within the `Overview'
664 node, which is specified by the `Up' pointer. (Instead of an
665 `@comment' line, you can write an `@ifinfo' line.)
667 If a file has a `Top' node, it must be called `top' or `Top' and be
668 the first node in the file.
670 The menu updating commands create a menu of sections within a chapter,
671 a menu of subsections within a section, and so on. This means that you
672 must have a `Top' node if you want a menu of chapters.
674 Incidentally, the `makeinfo' command will create an Info file for a
675 hierarchically organized Texinfo file that lacks `Next', `Previous' and
676 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
677 formatted with `makeinfo', you have no need for the `update node'
678 commands. (*Note Creating an Info File: Create an Info File, for more
679 information about `makeinfo'.) However, both `makeinfo' and the
680 `texinfo-format-...' commands require that you insert menus in the file.
683 File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus
685 Other Updating Commands
686 -----------------------
688 In addition to the five major updating commands, Texinfo mode
689 possesses several less frequently used updating commands:
691 `M-x texinfo-insert-node-lines'
692 Insert `@node' lines before the `@chapter', `@section', and other
693 sectioning commands wherever they are missing throughout a region
696 With an argument (`C-u' as prefix argument, if interactive), the
697 `texinfo-insert-node-lines' command not only inserts `@node' lines
698 but also inserts the chapter or section titles as the names of the
699 corresponding nodes. In addition, it inserts the titles as node
700 names in pre-existing `@node' lines that lack names. Since node
701 names should be more concise than section or chapter titles, you
702 must manually edit node names so inserted.
704 For example, the following marks a whole buffer as a region and
705 inserts `@node' lines and titles throughout:
707 C-x h C-u M-x texinfo-insert-node-lines
709 (Note that this command inserts titles as node names in `@node'
710 lines; the `texinfo-start-menu-description' command (*note
711 Inserting Frequently Used Commands: Inserting.) inserts titles as
712 descriptions in menu entries, a different action. However, in both
713 cases, you need to edit the inserted text.)
715 `M-x texinfo-multiple-files-update'
716 Update nodes and menus in a document built from several separate
717 files. With `C-u' as a prefix argument, create and insert a
718 master menu in the outer file. With a numeric prefix argument,
719 such as `C-u 2', first update all the menus and all the `Next',
720 `Previous', and `Up' pointers of all the included files before
721 creating and inserting a master menu in the outer file. The
722 `texinfo-multiple-files-update' command is described in the
723 appendix on `@include' files. *Note
724 texinfo-multiple-files-update::.
726 `M-x texinfo-indent-menu-description'
727 Indent every description in the menu following point to the
728 specified column. You can use this command to give yourself more
729 space for descriptions. With an argument (`C-u' as prefix
730 argument, if interactive), the `texinfo-indent-menu-description'
731 command indents every description in every menu in the region.
732 However, this command does not indent the second and subsequent
733 lines of a multi-line description.
735 `M-x texinfo-sequential-node-update'
736 Insert the names of the nodes immediately following and preceding
737 the current node as the `Next' or `Previous' pointers regardless
738 of those nodes' hierarchical level. This means that the `Next'
739 node of a subsection may well be the next chapter. Sequentially
740 ordered nodes are useful for novels and other documents that you
741 read through sequentially. (However, in Info, the `g *' command
742 lets you look through the file sequentially, so sequentially
743 ordered nodes are not strictly necessary.) With an argument
744 (prefix argument, if interactive), the
745 `texinfo-sequential-node-update' command sequentially updates all
746 the nodes in the region.
749 File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode
754 Texinfo mode provides several commands for formatting part or all of a
755 Texinfo file for Info. Often, when you are writing a document, you
756 want to format only part of a file--that is, a region.
758 You can use either the `texinfo-format-region' or the
759 `makeinfo-region' command to format a region:
762 `M-x texinfo-format-region'
764 `M-x makeinfo-region'
765 Format the current region for Info.
767 You can use either the `texinfo-format-buffer' or the
768 `makeinfo-buffer' command to format a whole buffer:
771 `M-x texinfo-format-buffer'
773 `M-x makeinfo-buffer'
774 Format the current buffer for Info.
776 For example, after writing a Texinfo file, you can type the following:
780 C-u M-x texinfo-master-menu
782 This updates all the nodes and menus. Then type the following to create
789 For TeX or the Info formatting commands to work, the file _must_
790 include a line that has `@setfilename' in its header.
792 *Note Create an Info File::, for details about Info formatting.
795 File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode
797 Formatting and Printing
798 =======================
800 Typesetting and printing a Texinfo file is a multi-step process in
801 which you first create a file for printing (called a DVI file), and then
802 print the file. Optionally, you may also create indices. To do this,
803 you must run the `texindex' command after first running the `tex'
804 typesetting command; and then you must run the `tex' command again. Or
805 else run the `texi2dvi' command which automatically creates indices as
806 needed (*note Format with texi2dvi::).
808 Often, when you are writing a document, you want to typeset and print
809 only part of a file to see what it will look like. You can use the
810 `texinfo-tex-region' and related commands for this purpose. Use the
811 `texinfo-tex-buffer' command to format all of a buffer.
814 `M-x texinfo-tex-buffer'
815 Run `texi2dvi' on the buffer. In addition to running TeX on the
816 buffer, this command automatically creates or updates indices as
820 `M-x texinfo-tex-region'
821 Run TeX on the region.
824 `M-x texinfo-texindex'
825 Run `texindex' to sort the indices of a Texinfo file formatted with
826 `texinfo-tex-region'. The `texinfo-tex-region' command does not
827 run `texindex' automatically; it only runs the `tex' typesetting
828 command. You must run the `texinfo-tex-region' command a second
829 time after sorting the raw index files with the `texindex'
830 command. (Usually, you do not format an index when you format a
831 region, only when you format a buffer. Now that the `texi2dvi'
832 command exists, there is little or no need for this command.)
835 `M-x texinfo-tex-print'
836 Print the file (or the part of the file) previously formatted with
837 `texinfo-tex-buffer' or `texinfo-tex-region'.
839 For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
840 _must_ start with a `\input texinfo' line and must include an
841 `@settitle' line. The file must end with `@bye' on a line by itself.
842 (When you use `texinfo-tex-region', you must surround the `@settitle'
843 line with start-of-header and end-of-header lines.)
845 *Note Format/Print Hardcopy::, for a description of the other TeX
846 related commands, such as `tex-show-print-queue'.
849 File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode
854 In Texinfo mode, each set of commands has default keybindings that
855 begin with the same keys. All the commands that are custom-created for
856 Texinfo mode begin with `C-c'. The keys are somewhat mnemonic.
861 The insert commands are invoked by typing `C-c' twice and then the
862 first letter of the @-command to be inserted. (It might make more
863 sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
866 C-c C-c c Insert `@code'.
867 C-c C-c d Insert `@dfn'.
868 C-c C-c e Insert `@end'.
869 C-c C-c i Insert `@item'.
870 C-c C-c n Insert `@node'.
871 C-c C-c s Insert `@samp'.
872 C-c C-c v Insert `@var'.
873 C-c C-c { Insert braces.
875 C-c C-c } Move out of enclosing braces.
877 C-c C-c C-d Insert a node's section title
878 in the space for the description
879 in a menu entry line.
884 The `texinfo-show-structure' command is often used within a narrowed
887 C-c C-s List all the headings.
889 The Master Update Command
890 -------------------------
892 The `texinfo-master-menu' command creates a master menu; and can be
893 used to update every node and menu in a file as well.
896 M-x texinfo-master-menu
897 Create or update a master menu.
899 C-u C-c C-u m With `C-u' as a prefix argument, first
900 create or update all nodes and regular
901 menus, and then create a master menu.
906 The update pointer commands are invoked by typing `C-c C-u' and then
907 either `C-n' for `texinfo-update-node' or `C-e' for
908 `texinfo-every-node-update'.
910 C-c C-u C-n Update a node.
911 C-c C-u C-e Update every node in the buffer.
916 Invoke the update menu commands by typing `C-c C-u' and then either
917 `C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
918 To update both nodes and menus at the same time, precede `C-c C-u C-a'
921 C-c C-u C-m Make or update a menu.
923 C-c C-u C-a Make or update all
926 C-u C-c C-u C-a With `C-u' as a prefix argument,
927 first create or update all nodes and
928 then create or update all menus.
933 The Info formatting commands that are written in Emacs Lisp are
934 invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b'
935 for the whole buffer.
937 The Info formatting commands that are written in C and based on the
938 `makeinfo' program are invoked by typing `C-c C-m' and then either
939 `C-r' for a region or `C-b' for the whole buffer.
941 Use the `texinfo-format...' commands:
943 C-c C-e C-r Format the region.
944 C-c C-e C-b Format the buffer.
948 C-c C-m C-r Format the region.
949 C-c C-m C-b Format the buffer.
950 C-c C-m C-l Recenter the `makeinfo' output buffer.
951 C-c C-m C-k Kill the `makeinfo' formatting job.
956 The TeX typesetting and printing commands are invoked by typing `C-c
957 C-t' and then another control command: `C-r' for `texinfo-tex-region',
958 `C-b' for `texinfo-tex-buffer', and so on.
960 C-c C-t C-r Run TeX on the region.
961 C-c C-t C-b Run `texi2dvi' on the buffer.
962 C-c C-t C-i Run `texindex'.
963 C-c C-t C-p Print the DVI file.
964 C-c C-t C-q Show the print queue.
965 C-c C-t C-d Delete a job from the print queue.
966 C-c C-t C-k Kill the current TeX formatting job.
967 C-c C-t C-x Quit a currently stopped TeX formatting job.
968 C-c C-t C-l Recenter the output buffer.
970 Other Updating Commands
971 -----------------------
973 The `other updating commands' do not have standard keybindings because
974 they are rarely used.
976 M-x texinfo-insert-node-lines
977 Insert missing `@node' lines in region.
978 With `C-u' as a prefix argument,
979 use section titles as node names.
981 M-x texinfo-multiple-files-update
982 Update a multi-file document.
983 With `C-u 2' as a prefix argument,
984 create or update all nodes and menus
985 in all included files first.
987 M-x texinfo-indent-menu-description
990 M-x texinfo-sequential-node-update
991 Insert node pointers in strict sequence.
994 File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
996 Beginning a Texinfo File
997 ************************
999 Certain pieces of information must be provided at the beginning of a
1000 Texinfo file, such as the name of the file and the title of the
1005 * Four Parts:: Four parts begin a Texinfo file.
1006 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
1007 * Header:: The very beginning of a Texinfo file.
1008 * Info Summary and Permissions:: Summary and copying permissions for Info.
1009 * Titlepage & Copyright Page:: Creating the title and copyright pages.
1010 * The Top Node:: Creating the `Top' node and master menu.
1011 * Software Copying Permissions:: Ensure that you and others continue to
1012 have the right to use and share software.
1015 File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File
1017 Four Parts Begin a File
1018 =======================
1020 Generally, the beginning of a Texinfo file has four parts:
1022 1. The header, delimited by special comment lines, that includes the
1023 commands for naming the Texinfo file and telling TeX what
1024 definitions file to use when processing the Texinfo file.
1026 2. A short statement of what the file is about, with a copyright
1027 notice and copying permissions. This is enclosed in `@ifinfo' and
1028 `@end ifinfo' commands so that the formatters place it only in the
1031 3. A title page and copyright page, with a copyright notice and
1032 copying permissions. This is enclosed between `@titlepage' and
1033 `@end titlepage' commands. The title and copyright page appear
1034 only in the printed manual.
1036 4. The `Top' node that contains a menu for the whole Info file. The
1037 contents of this node appear only in the Info file.
1039 Also, optionally, you may include the copying conditions for a program
1040 and a warranty disclaimer. The copying section will be followed by an
1041 introduction or else by the first chapter of the manual.
1043 Since the copyright notice and copying permissions for the Texinfo
1044 document (in contrast to the copying permissions for a program) are in
1045 parts that appear only in the Info file or only in the printed manual,
1046 this information must be given twice.
1049 File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File
1051 Sample Texinfo File Beginning
1052 =============================
1054 The following sample shows what is needed.
1056 \input texinfo @c -*-texinfo-*-
1057 @c %**start of header
1058 @setfilename NAME-OF-INFO-FILE
1059 @settitle NAME-OF-MANUAL
1060 @setchapternewpage odd
1064 This file documents ...
1066 Copyright YEAR COPYRIGHT-OWNER
1068 Permission is granted to ...
1071 @c This title page illustrates only one of the
1072 @c two methods of forming a title page.
1075 @title NAME-OF-MANUAL-WHEN-PRINTED
1076 @subtitle SUBTITLE-IF-ANY
1077 @subtitle SECOND-SUBTITLE
1080 @c The following two commands
1081 @c start the copyright page.
1083 @vskip 0pt plus 1filll
1084 Copyright @copyright{} YEAR COPYRIGHT-OWNER
1088 Permission is granted to ...
1091 @node Top, Overview, , (dir)
1094 This document describes ...
1096 This document applies to version ...
1097 of the program named ...
1101 * Copying:: Your rights and freedoms.
1102 * First Chapter:: Getting started ...
1103 * Second Chapter:: ...
1108 @node First Chapter, Second Chapter, top, top
1109 @comment node-name, next, previous, up
1110 @chapter First Chapter
1111 @cindex Index entry for First Chapter
1114 File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File
1116 The Texinfo File Header
1117 =======================
1119 Texinfo files start with at least three lines that provide Info and
1120 TeX with necessary information. These are the `\input texinfo' line,
1121 the `@settitle' line, and the `@setfilename' line. If you want to run
1122 TeX on just a part of the Texinfo File, you must write the `@settitle'
1123 and `@setfilename' lines between start-of-header and end-of-header
1126 Thus, the beginning of a Texinfo file looks like this:
1128 \input texinfo @c -*-texinfo-*-
1129 @setfilename sample.info
1130 @settitle Sample Document
1134 \input texinfo @c -*-texinfo-*-
1135 @c %**start of header
1136 @setfilename sample.info
1137 @settitle Sample Document
1142 * First Line:: The first line of a Texinfo file.
1143 * Start of Header:: Formatting a region requires this.
1144 * setfilename:: Tell Info the name of the Info file.
1145 * settitle:: Create a title for the printed work.
1146 * setchapternewpage:: Start chapters on right-hand pages.
1147 * paragraphindent:: An option to specify paragraph indentation.
1148 * End of Header:: Formatting a region requires this.
1151 File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header
1153 The First Line of a Texinfo File
1154 --------------------------------
1156 Every Texinfo file that is to be the top-level input to TeX must begin
1157 with a line that looks like this:
1159 \input texinfo @c -*-texinfo-*-
1161 This line serves two functions:
1163 1. When the file is processed by TeX, the `\input texinfo' command
1164 tells TeX to load the macros needed for processing a Texinfo file.
1165 These are in a file called `texinfo.tex', which is usually located
1166 in the `/usr/lib/tex/macros' directory. TeX uses the backslash,
1167 `\', to mark the beginning of a command, just as Texinfo uses `@'.
1168 The `texinfo.tex' file causes the switch from `\' to `@'; before
1169 the switch occurs, TeX requires `\', which is why it appears at
1170 the beginning of the file.
1172 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
1173 specification tells Emacs to use Texinfo mode.
1176 File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header
1181 Write a start-of-header line on the second line of a Texinfo file.
1182 Follow the start-of-header line with `@setfilename' and `@settitle'
1183 lines and, optionally, with other command lines, such as `@smallbook'
1184 or `@footnotestyle'; and then by an end-of-header line (*note End of
1187 With these lines, you can format part of a Texinfo file for Info or
1188 typeset part for printing.
1190 A start-of-header line looks like this:
1192 @c %**start of header
1194 The odd string of characters, `%**', is to ensure that no other
1195 comment is accidentally taken for a start-of-header line.
1198 File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header
1203 In order to serve as the primary input file for either `makeinfo' or
1204 TeX, a Texinfo file must contain a line that looks like this:
1206 @setfilename INFO-FILE-NAME
1208 Write the `@setfilename' command at the beginning of a line and
1209 follow it on the same line by the Info file name. Do not write anything
1210 else on the line; anything on the line after the command is considered
1211 part of the file name, including what would otherwise be a comment.
1213 The `@setfilename' line specifies the name of the Info file to be
1214 generated. This name should be different from the name of the Texinfo
1215 file. There are two conventions for choosing the name: you can either
1216 remove the `.texi' extension from the input file name, or replace it
1217 with the `.info' extension.
1219 Some operating systems cannot handle long file names. You can run
1220 into a problem even when the file name you specify is itself short
1221 enough. This occurs because the Info formatters split a long Info file
1222 into short indirect subfiles, and name them by appending `-1', `-2',
1223 ..., `-10', `-11', and so on, to the original file name. (*Note Tag
1224 Files and Split Files: Tag and Split Files.) The subfile name
1225 `texinfo.info-10', for example, is too long for some systems; so the
1226 Info file name for this document is `texinfo' rather than
1229 The Info formatting commands ignore everything written before the
1230 `@setfilename' line, which is why the very first line of the file (the
1231 `\input' line) does not show up in the output.
1233 The `@setfilename' line produces no output when you typeset a manual
1234 with TeX, but it nevertheless is essential: it opens the index,
1235 cross-reference, and other auxiliary files used by Texinfo, and also
1236 reads `texinfo.cnf' if that file is present on your system (*note
1237 Preparing to Use TeX: Preparing for TeX.).
1240 File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header
1245 In order to be made into a printed manual, a Texinfo file must contain
1246 a line that looks like this:
1250 Write the `@settitle' command at the beginning of a line and follow
1251 it on the same line by the title. This tells TeX the title to use in a
1252 header or footer. Do not write anything else on the line; anything on
1253 the line after the command is considered part of the title, including a
1256 Conventionally, when TeX formats a Texinfo file for double-sided
1257 output, the title is printed in the left-hand (even-numbered) page
1258 headings and the current chapter title is printed in the right-hand
1259 (odd-numbered) page headings. (TeX learns the title of each chapter
1260 from each `@chapter' command.) Page footers are not printed.
1262 Even if you are printing in a single-sided style, TeX looks for an
1263 `@settitle' command line, in case you include the manual title in the
1266 The `@settitle' command should precede everything that generates
1267 actual output in TeX.
1269 Although the title in the `@settitle' command is usually the same as
1270 the title on the title page, it does not affect the title as it appears
1271 on the title page. Thus, the two do not need not match exactly; and
1272 the title in the `@settitle' command can be a shortened or expanded
1273 version of the title as it appears on the title page. (*Note
1274 `@titlepage': titlepage.)
1276 TeX prints page headings only for that text that comes after the
1277 `@end titlepage' command in the Texinfo file, or that comes after an
1278 `@headings' command that turns on headings. (*Note The `@headings'
1279 Command: headings on off, for more information.)
1281 You may, if you wish, create your own, customized headings and
1282 footings. *Note Page Headings: Headings, for a detailed discussion of