1 This is Info file ../info/texinfo.info, produced by Makeinfo version
2 1.68 from the input file texinfo.texi.
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
163 This is the contents of the first chapter.
165 Here is a numbered list.
167 1. This is the first item.
169 2. This is the second item.
171 The `makeinfo' and `texinfo-format-buffer' commands transform a
172 Texinfo file such as this into an Info file; and TeX typesets it
173 for a printed manual.
176 File: texinfo.info, Node: Acknowledgements, Prev: Short Sample, Up: Overview
181 Richard M. Stallman wrote Edition 1.0 of this manual.
182 Robert J. Chassell revised and extended it, starting with Edition 1.1.
183 Karl Berry made updates for the Texinfo 3.8 and subsequent releases,
184 starting with Edition 2.22.
186 Our thanks go out to all who helped improve this work, particularly to
187 Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
188 reported mistakes and obscurities; our special thanks go to Melissa
189 Weisshaus for her frequent and often tedious reviews of nearly similar
190 editions. Our mistakes are our own.
192 Please send suggestions and corrections to:
197 Please include the manual's edition number and update date in your
201 File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
206 You may edit a Texinfo file with any text editor you choose. A
207 Texinfo file is no different from any other ASCII file. However, GNU
208 Emacs comes with a special mode, called Texinfo mode, that provides
209 Emacs commands and tools to help ease your work.
211 This chapter describes features of GNU Emacs' Texinfo mode but not any
212 features of the Texinfo formatting language. If you are reading this
213 manual straight through from the beginning, you may want to skim through
214 this chapter briefly and come back to it after reading succeeding
215 chapters which describe the Texinfo formatting language in detail.
219 * Texinfo Mode Overview:: How Texinfo mode can help you.
220 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
221 purpose editing features.
222 * Inserting:: How to insert frequently used @-commands.
223 * Showing the Structure:: How to show the structure of a file.
224 * Updating Nodes and Menus:: How to update or create new nodes and menus.
225 * Info Formatting:: How to format for Info.
226 * Printing:: How to format and print part or all of a file.
227 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
230 File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode
232 Texinfo Mode Overview
233 =====================
235 Texinfo mode provides special features for working with Texinfo files:
237 * Insert frequently used @-commands.
239 * Automatically create `@node' lines.
241 * Show the structure of a Texinfo source file.
243 * Automatically create or update the `Next', `Previous', and `Up'
246 * Automatically create or update menus.
248 * Automatically create a master menu.
250 * Format a part or all of a file for Info.
252 * Typeset and print part or all of a file.
254 Perhaps the two most helpful features are those for inserting
255 frequently used @-commands and for creating node pointers and menus.
258 File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode
260 The Usual GNU Emacs Editing Commands
261 ====================================
263 In most cases, the usual Text mode commands work the same in Texinfo
264 mode as they do in Text mode. Texinfo mode adds new editing commands
265 and tools to GNU Emacs' general purpose editing features. The major
266 difference concerns filling. In Texinfo mode, the paragraph separation
267 variable and syntax table are redefined so that Texinfo commands that
268 should be on lines of their own are not inadvertently included in
269 paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a
270 paragraph but not mix an indexing command on a line adjacent to it into
273 In addition, Texinfo mode sets the `page-delimiter' variable to the
274 value of `texinfo-chapter-level-regexp'; by default, this is a regular
275 expression matching the commands for chapters and their equivalents,
276 such as appendices. With this value for the page delimiter, you can
277 jump from chapter title to chapter title with the `C-x ]'
278 (`forward-page') and `C-x [' (`backward-page') commands and narrow to a
279 chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages:
280 (xemacs)Pages, for details about the page commands.)
282 You may name a Texinfo file however you wish, but the convention is to
283 end a Texinfo file name with one of the three extensions `.texinfo',
284 `.texi', or `.tex'. A longer extension is preferred, since it is
285 explicit, but a shorter extension may be necessary for operating
286 systems that limit the length of file names. GNU Emacs automatically
287 enters Texinfo mode when you visit a file with a `.texinfo' or `.texi'
288 extension. Also, Emacs switches to Texinfo mode when you visit a file
289 that has `-*-texinfo-*-' in its first line. If ever you are in another
290 mode and wish to switch to Texinfo mode, type `M-x texinfo-mode'.
292 Like all other Emacs features, you can customize or enhance Texinfo
293 mode as you wish. In particular, the keybindings are very easy to
294 change. The keybindings described here are the default or standard
298 File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode
300 Inserting Frequently Used Commands
301 ==================================
303 Texinfo mode provides commands to insert various frequently used
304 @-commands into the buffer. You can use these commands to save
307 The insert commands are invoked by typing `C-c' twice and then the
308 first letter of the @-command:
311 `M-x texinfo-insert-@code'
312 Insert `@code{}' and put the cursor between the braces.
315 `M-x texinfo-insert-@dfn'
316 Insert `@dfn{}' and put the cursor between the braces.
319 `M-x texinfo-insert-@end'
320 Insert `@end' and attempt to insert the correct following word,
321 such as `example' or `table'. (This command does not handle
322 nested lists correctly, but inserts the word appropriate to the
323 immediately preceding list.)
326 `M-x texinfo-insert-@item'
327 Insert `@item' and put the cursor at the beginning of the next
331 `M-x texinfo-insert-@kbd'
332 Insert `@kbd{}' and put the cursor between the braces.
335 `M-x texinfo-insert-@node'
336 Insert `@node' and a comment line listing the sequence for the
337 `Next', `Previous', and `Up' nodes. Leave point after the `@node'.
340 `M-x texinfo-insert-@noindent'
341 Insert `@noindent' and put the cursor at the beginning of the next
345 `M-x texinfo-insert-@samp'
346 Insert `@samp{}' and put the cursor between the braces.
349 `M-x texinfo-insert-@table'
350 Insert `@table' followed by a <SPC> and leave the cursor after the
354 `M-x texinfo-insert-@var'
355 Insert `@var{}' and put the cursor between the braces.
358 `M-x texinfo-insert-@example'
359 Insert `@example' and put the cursor at the beginning of the next
363 `M-x texinfo-insert-braces'
364 Insert `{}' and put the cursor between the braces.
369 Move from between a pair of braces forward past the closing brace.
370 Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
371 however, more mnemonic; hence the two keybindings. (Also, you can
372 move out from between braces by typing `C-f'.)
374 To put a command such as `@code{...}' around an *existing* word,
375 position the cursor in front of the word and type `C-u 1 C-c C-c c'.
376 This makes it easy to edit existing plain text. The value of the
377 prefix argument tells Emacs how many words following point to include
378 between braces--`1' for one word, `2' for two words, and so on. Use a
379 negative argument to enclose the previous word or words. If you do not
380 specify a prefix argument, Emacs inserts the @-command string and
381 positions the cursor between the braces. This feature works only for
382 those @-commands that operate on a word or words within one line, such
383 as `@kbd' and `@var'.
385 This set of insert commands was created after analyzing the frequency
386 with which different @-commands are used in the `GNU Emacs Manual' and
387 the `GDB Manual'. If you wish to add your own insert commands, you can
388 bind a keyboard macro to a key, use abbreviations, or extend the code
391 `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
392 that works differently from the other insert commands. It inserts a
393 node's section or chapter title in the space for the description in a
394 menu entry line. (A menu entry has three parts, the entry name, the
395 node name, and the description. Only the node name is required, but a
396 description helps explain what the node is about. *Note The Parts of a
399 To use `texinfo-start-menu-description', position point in a menu
400 entry line and type `C-c C-c C-d'. The command looks for and copies
401 the title that goes with the node name, and inserts the title as a
402 description; it positions point at beginning of the inserted text so you
403 can edit it. The function does not insert the title if the menu entry
404 line already contains a description.
406 This command is only an aid to writing descriptions; it does not do
407 the whole job. You must edit the inserted text since a title tends to
408 use the same words as a node name but a useful description uses
412 File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode
414 Showing the Section Structure of a File
415 =======================================
417 You can show the section structure of a Texinfo file by using the
418 `C-c C-s' command (`texinfo-show-structure'). This command shows the
419 section structure of a Texinfo file by listing the lines that begin
420 with the @-commands for `@chapter', `@section', and the like. It
421 constructs what amounts to a table of contents. These lines are
422 displayed in another buffer called the `*Occur*' buffer. In that
423 buffer, you can position the cursor over one of the lines and use the
424 `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
425 corresponding spot in the Texinfo file.
428 `M-x texinfo-show-structure'
429 Show the `@chapter', `@section', and such lines of a Texinfo file.
432 `M-x occur-mode-goto-occurrence'
433 Go to the line in the Texinfo file corresponding to the line under
434 the cursor in the `*Occur*' buffer.
436 If you call `texinfo-show-structure' with a prefix argument by typing
437 `C-u C-c C-s', it will list not only those lines with the @-commands
438 for `@chapter', `@section', and the like, but also the `@node' lines.
439 (This is how the `texinfo-show-structure' command worked without an
440 argument in the first version of Texinfo. It was changed because
441 `@node' lines clutter up the `*Occur*' buffer and are usually not
442 needed.) You can use `texinfo-show-structure' with a prefix argument
443 to check whether the `Next', `Previous', and `Up' pointers of an
444 `@node' line are correct.
446 Often, when you are working on a manual, you will be interested only
447 in the structure of the current chapter. In this case, you can mark
448 off the region of the buffer that you are interested in by using the
449 `C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
450 will work on only that region. To see the whole buffer again, use
451 `C-x n w' (`widen'). (*Note Narrowing: (xemacs)Narrowing, for more
452 information about the narrowing commands.)
454 In addition to providing the `texinfo-show-structure' command,
455 Texinfo mode sets the value of the page delimiter variable to match the
456 chapter-level @-commands. This enables you to use the `C-x ]'
457 (`forward-page') and `C-x [' (`backward-page') commands to move forward
458 and backward by chapter, and to use the `C-x p' (`narrow-to-page')
459 command to narrow to a chapter. *Note Pages: (xemacs)Pages, for more
460 information about the page commands.
463 File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode
465 Updating Nodes and Menus
466 ========================
468 Texinfo mode provides commands for automatically creating or updating
469 menus and node pointers. The commands are called "update" commands
470 because their most frequent use is for updating a Texinfo file after
471 you have worked on it; but you can use them to insert the `Next',
472 `Previous', and `Up' pointers into an `@node' line that has none and to
473 create menus in a file that has none.
475 If you do not use the updating commands, you need to write menus and
476 node pointers by hand, which is a tedious task.
480 * Updating Commands:: Five major updating commands.
481 * Updating Requirements:: How to structure a Texinfo file for
482 using the updating command.
483 * Other Updating Commands:: How to indent descriptions, insert
484 missing nodes lines, and update
488 File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus
490 The Updating Commands
491 ---------------------
493 You can use the updating commands
495 * to insert or update the `Next', `Previous', and `Up' pointers of a
498 * to insert or update the menu for a section, and
500 * to create a master menu for a Texinfo source file.
502 You can also use the commands to update all the nodes and menus in a
503 region or in a whole Texinfo file.
505 The updating commands work only with conventional Texinfo files, which
506 are structured hierarchically like books. In such files, a structuring
507 command line must follow closely after each `@node' line, except for
508 the `Top' `@node' line. (A "structuring command line" is a line
509 beginning with `@chapter', `@section', or other similar command.)
511 You can write the structuring command line on the line that follows
512 immediately after an `@node' line or else on the line that follows
513 after a single `@comment' line or a single `@ifinfo' line. You cannot
514 interpose more than one line between the `@node' line and the
515 structuring command line; and you may interpose only an `@comment' line
516 or an `@ifinfo' line.
518 Commands which work on a whole buffer require that the `Top' node be
519 followed by a node with an `@chapter' or equivalent-level command.
520 Note that the menu updating commands will not create a main or master
521 menu for a Texinfo file that has only `@chapter'-level nodes! The menu
522 updating commands only create menus *within* nodes for lower level
523 nodes. To create a menu of chapters, you must provide a `Top' node.
525 The menu updating commands remove menu entries that refer to other
526 Info files since they do not refer to nodes within the current buffer.
527 This is a deficiency. Rather than use menu entries, you can use cross
528 references to refer to other Info files. None of the updating commands
529 affect cross references.
531 Texinfo mode has five updating commands that are used most often: two
532 are for updating the node pointers or menu of a single node (or a
533 region); two are for updating every node pointer and menu in a file;
534 and one, the `texinfo-master-menu' command, is for creating a master
535 menu for a complete file, and optionally, for updating every node and
536 menu in the whole Texinfo file.
538 The `texinfo-master-menu' command is the primary command:
541 `M-x texinfo-master-menu'
542 Create or update a master menu that includes all the other menus
543 (incorporating the descriptions from pre-existing menus, if any).
545 With an argument (prefix argument, `C-u,' if interactive), first
546 create or update all the nodes and all the regular menus in the
547 buffer before constructing the master menu. (*Note The Top Node
548 and Master Menu: The Top Node, for more about a master menu.)
550 For `texinfo-master-menu' to work, the Texinfo file must have a
551 `Top' node and at least one subsequent node.
553 After extensively editing a Texinfo file, you can type the
556 C-u M-x texinfo-master-menu
560 This updates all the nodes and menus completely and all at once.
562 The other major updating commands do smaller jobs and are designed for
563 the person who updates nodes and menus as he or she writes a Texinfo
569 `M-x texinfo-update-node'
570 Insert the `Next', `Previous', and `Up' pointers for the node that
571 point is within (i.e., for the `@node' line preceding point). If
572 the `@node' line has pre-existing `Next', `Previous', or `Up'
573 pointers in it, the old pointers are removed and new ones inserted.
574 With an argument (prefix argument, `C-u', if interactive), this
575 command updates all `@node' lines in the region (which is the text
576 between point and mark).
579 `M-x texinfo-make-menu'
580 Create or update the menu in the node that point is within. With
581 an argument (`C-u' as prefix argument, if interactive), the
582 command makes or updates menus for the nodes which are either
583 within or a part of the region.
585 Whenever `texinfo-make-menu' updates an existing menu, the
586 descriptions from that menu are incorporated into the new menu.
587 This is done by copying descriptions from the existing menu to the
588 entries in the new menu that have the same node names. If the
589 node names are different, the descriptions are not copied to the
593 `M-x texinfo-every-node-update'
594 Insert or update the `Next', `Previous', and `Up' pointers for
595 every node in the buffer.
598 `M-x texinfo-all-menus-update'
599 Create or update all the menus in the buffer. With an argument
600 (`C-u' as prefix argument, if interactive), first insert or update
601 all the node pointers before working on the menus.
603 If a master menu exists, the `texinfo-all-menus-update' command
604 updates it; but the command does not create a new master menu if
605 none already exists. (Use the `texinfo-master-menu' command for
608 When working on a document that does not merit a master menu, you
609 can type the following:
613 C-u M-x texinfo-all-menus-update
615 This updates all the nodes and menus.
617 The `texinfo-column-for-description' variable specifies the column to
618 which menu descriptions are indented. By default, the value is 32
619 although it is often useful to reduce it to as low as 24. You can set
620 the variable with the `M-x edit-options' command (*note Editing
621 Variable Values: (xemacs)Edit Options.) or with the `M-x set-variable'
622 command (*note Examining and Setting Variables: (xemacs)Examining.).
624 Also, the `texinfo-indent-menu-description' command may be used to
625 indent existing menu descriptions to a specified column. Finally, if
626 you wish, you can use the `texinfo-insert-node-lines' command to insert
627 missing `@node' lines into a file. (*Note Other Updating Commands::,
628 for more information.)
631 File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus
633 Updating Requirements
634 ---------------------
636 To use the updating commands, you must organize the Texinfo file
637 hierarchically with chapters, sections, subsections, and the like.
638 When you construct the hierarchy of the manual, do not `jump down' more
639 than one level at a time: you can follow the `Top' node with a chapter,
640 but not with a section; you can follow a chapter with a section, but
641 not with a subsection. However, you may `jump up' any number of levels
642 at one time--for example, from a subsection to a chapter.
644 Each `@node' line, with the exception of the line for the `Top' node,
645 must be followed by a line with a structuring command such as
646 `@chapter', `@section', or `@unnumberedsubsec'.
648 Each `@node' line/structuring-command line combination must look
651 @node Comments, Minimum, Conventions, Overview
652 @comment node-name, next, previous, up
655 or like this (without the `@comment' line):
657 @node Comments, Minimum, Conventions, Overview
660 In this example, `Comments' is the name of both the node and the
661 section. The next node is called `Minimum' and the previous node is
662 called `Conventions'. The `Comments' section is within the `Overview'
663 node, which is specified by the `Up' pointer. (Instead of an
664 `@comment' line, you can write an `@ifinfo' line.)
666 If a file has a `Top' node, it must be called `top' or `Top' and be
667 the first node in the file.
669 The menu updating commands create a menu of sections within a chapter,
670 a menu of subsections within a section, and so on. This means that you
671 must have a `Top' node if you want a menu of chapters.
673 Incidentally, the `makeinfo' command will create an Info file for a
674 hierarchically organized Texinfo file that lacks `Next', `Previous' and
675 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
676 formatted with `makeinfo', you have no need for the `update node'
677 commands. (*Note Creating an Info File: Create an Info File, for more
678 information about `makeinfo'.) However, both `makeinfo' and the
679 `texinfo-format-...' commands require that you insert menus in the file.
682 File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus
684 Other Updating Commands
685 -----------------------
687 In addition to the five major updating commands, Texinfo mode
688 possesses several less frequently used updating commands:
690 `M-x texinfo-insert-node-lines'
691 Insert `@node' lines before the `@chapter', `@section', and other
692 sectioning commands wherever they are missing throughout a region
695 With an argument (`C-u' as prefix argument, if interactive), the
696 `texinfo-insert-node-lines' command not only inserts `@node' lines
697 but also inserts the chapter or section titles as the names of the
698 corresponding nodes. In addition, it inserts the titles as node
699 names in pre-existing `@node' lines that lack names. Since node
700 names should be more concise than section or chapter titles, you
701 must manually edit node names so inserted.
703 For example, the following marks a whole buffer as a region and
704 inserts `@node' lines and titles throughout:
706 C-x h C-u M-x texinfo-insert-node-lines
708 (Note that this command inserts titles as node names in `@node'
709 lines; the `texinfo-start-menu-description' command (*note
710 Inserting Frequently Used Commands: Inserting.) inserts titles as
711 descriptions in menu entries, a different action. However, in both
712 cases, you need to edit the inserted text.)
714 `M-x texinfo-multiple-files-update'
715 Update nodes and menus in a document built from several separate
716 files. With `C-u' as a prefix argument, create and insert a
717 master menu in the outer file. With a numeric prefix argument,
718 such as `C-u 2', first update all the menus and all the `Next',
719 `Previous', and `Up' pointers of all the included files before
720 creating and inserting a master menu in the outer file. The
721 `texinfo-multiple-files-update' command is described in the
722 appendix on `@include' files. *Note
723 texinfo-multiple-files-update::.
725 `M-x texinfo-indent-menu-description'
726 Indent every description in the menu following point to the
727 specified column. You can use this command to give yourself more
728 space for descriptions. With an argument (`C-u' as prefix
729 argument, if interactive), the `texinfo-indent-menu-description'
730 command indents every description in every menu in the region.
731 However, this command does not indent the second and subsequent
732 lines of a multi-line description.
734 `M-x texinfo-sequential-node-update'
735 Insert the names of the nodes immediately following and preceding
736 the current node as the `Next' or `Previous' pointers regardless
737 of those nodes' hierarchical level. This means that the `Next'
738 node of a subsection may well be the next chapter. Sequentially
739 ordered nodes are useful for novels and other documents that you
740 read through sequentially. (However, in Info, the `g *' command
741 lets you look through the file sequentially, so sequentially
742 ordered nodes are not strictly necessary.) With an argument
743 (prefix argument, if interactive), the
744 `texinfo-sequential-node-update' command sequentially updates all
745 the nodes in the region.
748 File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode
753 Texinfo mode provides several commands for formatting part or all of a
754 Texinfo file for Info. Often, when you are writing a document, you
755 want to format only part of a file--that is, a region.
757 You can use either the `texinfo-format-region' or the
758 `makeinfo-region' command to format a region:
761 `M-x texinfo-format-region'
763 `M-x makeinfo-region'
764 Format the current region for Info.
766 You can use either the `texinfo-format-buffer' or the
767 `makeinfo-buffer' command to format a whole buffer:
770 `M-x texinfo-format-buffer'
772 `M-x makeinfo-buffer'
773 Format the current buffer for Info.
775 For example, after writing a Texinfo file, you can type the following:
779 C-u M-x texinfo-master-menu
781 This updates all the nodes and menus. Then type the following to create
788 For TeX or the Info formatting commands to work, the file *must*
789 include a line that has `@setfilename' in its header.
791 *Note Create an Info File::, for details about Info formatting.
794 File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode
796 Formatting and Printing
797 =======================
799 Typesetting and printing a Texinfo file is a multi-step process in
800 which you first create a file for printing (called a DVI file), and then
801 print the file. Optionally, you may also create indices. To do this,
802 you must run the `texindex' command after first running the `tex'
803 typesetting command; and then you must run the `tex' command again. Or
804 else run the `texi2dvi' command which automatically creates indices as
805 needed (*note Format with texi2dvi::.).
807 Often, when you are writing a document, you want to typeset and print
808 only part of a file to see what it will look like. You can use the
809 `texinfo-tex-region' and related commands for this purpose. Use the
810 `texinfo-tex-buffer' command to format all of a buffer.
813 `M-x texinfo-tex-buffer'
814 Run `texi2dvi' on the buffer. In addition to running TeX on the
815 buffer, this command automatically creates or updates indices as
819 `M-x texinfo-tex-region'
820 Run TeX on the region.
823 `M-x texinfo-texindex'
824 Run `texindex' to sort the indices of a Texinfo file formatted with
825 `texinfo-tex-region'. The `texinfo-tex-region' command does not
826 run `texindex' automatically; it only runs the `tex' typesetting
827 command. You must run the `texinfo-tex-region' command a second
828 time after sorting the raw index files with the `texindex'
829 command. (Usually, you do not format an index when you format a
830 region, only when you format a buffer. Now that the `texi2dvi'
831 command exists, there is little or no need for this command.)
834 `M-x texinfo-tex-print'
835 Print the file (or the part of the file) previously formatted with
836 `texinfo-tex-buffer' or `texinfo-tex-region'.
838 For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
839 *must* start with a `\input texinfo' line and must include an
840 `@settitle' line. The file must end with `@bye' on a line by itself.
841 (When you use `texinfo-tex-region', you must surround the `@settitle'
842 line with start-of-header and end-of-header lines.)
844 *Note Format/Print Hardcopy::, for a description of the other TeX
845 related commands, such as `tex-show-print-queue'.
848 File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode
853 In Texinfo mode, each set of commands has default keybindings that
854 begin with the same keys. All the commands that are custom-created for
855 Texinfo mode begin with `C-c'. The keys are somewhat mnemonic.
860 The insert commands are invoked by typing `C-c' twice and then the
861 first letter of the @-command to be inserted. (It might make more
862 sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
865 C-c C-c c Insert `@code'.
866 C-c C-c d Insert `@dfn'.
867 C-c C-c e Insert `@end'.
868 C-c C-c i Insert `@item'.
869 C-c C-c n Insert `@node'.
870 C-c C-c s Insert `@samp'.
871 C-c C-c v Insert `@var'.
872 C-c C-c { Insert braces.
874 C-c C-c } Move out of enclosing braces.
876 C-c C-c C-d Insert a node's section title
877 in the space for the description
878 in a menu entry line.
883 The `texinfo-show-structure' command is often used within a narrowed
886 C-c C-s List all the headings.
888 The Master Update Command
889 -------------------------
891 The `texinfo-master-menu' command creates a master menu; and can be
892 used to update every node and menu in a file as well.
895 M-x texinfo-master-menu
896 Create or update a master menu.
898 C-u C-c C-u m With `C-u' as a prefix argument, first
899 create or update all nodes and regular
900 menus, and then create a master menu.
905 The update pointer commands are invoked by typing `C-c C-u' and then
906 either `C-n' for `texinfo-update-node' or `C-e' for
907 `texinfo-every-node-update'.
909 C-c C-u C-n Update a node.
910 C-c C-u C-e Update every node in the buffer.
915 Invoke the update menu commands by typing `C-c C-u' and then either
916 `C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
917 To update both nodes and menus at the same time, precede `C-c C-u C-a'
920 C-c C-u C-m Make or update a menu.
922 C-c C-u C-a Make or update all
925 C-u C-c C-u C-a With `C-u' as a prefix argument,
926 first create or update all nodes and
927 then create or update all menus.
932 The Info formatting commands that are written in Emacs Lisp are
933 invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b'
934 for the whole buffer.
936 The Info formatting commands that are written in C and based on the
937 `makeinfo' program are invoked by typing `C-c C-m' and then either
938 `C-r' for a region or `C-b' for the whole buffer.
940 Use the `texinfo-format...' commands:
942 C-c C-e C-r Format the region.
943 C-c C-e C-b Format the buffer.
947 C-c C-m C-r Format the region.
948 C-c C-m C-b Format the buffer.
949 C-c C-m C-l Recenter the `makeinfo' output buffer.
950 C-c C-m C-k Kill the `makeinfo' formatting job.
955 The TeX typesetting and printing commands are invoked by typing `C-c
956 C-t' and then another control command: `C-r' for `texinfo-tex-region',
957 `C-b' for `texinfo-tex-buffer', and so on.
959 C-c C-t C-r Run TeX on the region.
960 C-c C-t C-b Run `texi2dvi' on the buffer.
961 C-c C-t C-i Run `texindex'.
962 C-c C-t C-p Print the DVI file.
963 C-c C-t C-q Show the print queue.
964 C-c C-t C-d Delete a job from the print queue.
965 C-c C-t C-k Kill the current TeX formatting job.
966 C-c C-t C-x Quit a currently stopped TeX formatting job.
967 C-c C-t C-l Recenter the output buffer.
969 Other Updating Commands
970 -----------------------
972 The `other updating commands' do not have standard keybindings because
973 they are rarely used.
975 M-x texinfo-insert-node-lines
976 Insert missing `@node' lines in region.
977 With `C-u' as a prefix argument,
978 use section titles as node names.
980 M-x texinfo-multiple-files-update
981 Update a multi-file document.
982 With `C-u 2' as a prefix argument,
983 create or update all nodes and menus
984 in all included files first.
986 M-x texinfo-indent-menu-description
989 M-x texinfo-sequential-node-update
990 Insert node pointers in strict sequence.
993 File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
995 Beginning a Texinfo File
996 ************************
998 Certain pieces of information must be provided at the beginning of a
999 Texinfo file, such as the name of the file and the title of the
1004 * Four Parts:: Four parts begin a Texinfo file.
1005 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
1006 * Header:: The very beginning of a Texinfo file.
1007 * Info Summary and Permissions:: Summary and copying permissions for Info.
1008 * Titlepage & Copyright Page:: Creating the title and copyright pages.
1009 * The Top Node:: Creating the `Top' node and master menu.
1010 * Software Copying Permissions:: Ensure that you and others continue to
1011 have the right to use and share software.
1014 File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File
1016 Four Parts Begin a File
1017 =======================
1019 Generally, the beginning of a Texinfo file has four parts:
1021 1. The header, delimited by special comment lines, that includes the
1022 commands for naming the Texinfo file and telling TeX what
1023 definitions file to use when processing the Texinfo file.
1025 2. A short statement of what the file is about, with a copyright
1026 notice and copying permissions. This is enclosed in `@ifinfo' and
1027 `@end ifinfo' commands so that the formatters place it only in the
1030 3. A title page and copyright page, with a copyright notice and
1031 copying permissions. This is enclosed between `@titlepage' and
1032 `@end titlepage' commands. The title and copyright page appear
1033 only in the printed manual.
1035 4. The `Top' node that contains a menu for the whole Info file. The
1036 contents of this node appear only in the Info file.
1038 Also, optionally, you may include the copying conditions for a program
1039 and a warranty disclaimer. The copying section will be followed by an
1040 introduction or else by the first chapter of the manual.
1042 Since the copyright notice and copying permissions for the Texinfo
1043 document (in contrast to the copying permissions for a program) are in
1044 parts that appear only in the Info file or only in the printed manual,
1045 this information must be given twice.
1048 File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File
1050 Sample Texinfo File Beginning
1051 =============================
1053 The following sample shows what is needed.
1055 \input texinfo @c -*-texinfo-*-
1056 @c %**start of header
1057 @setfilename NAME-OF-INFO-FILE
1058 @settitle NAME-OF-MANUAL
1059 @setchapternewpage odd
1063 This file documents ...
1065 Copyright YEAR COPYRIGHT-OWNER
1067 Permission is granted to ...
1070 @c This title page illustrates only one of the
1071 @c two methods of forming a title page.
1074 @title NAME-OF-MANUAL-WHEN-PRINTED
1075 @subtitle SUBTITLE-IF-ANY
1076 @subtitle SECOND-SUBTITLE
1079 @c The following two commands
1080 @c start the copyright page.
1082 @vskip 0pt plus 1filll
1083 Copyright @copyright{} YEAR COPYRIGHT-OWNER
1087 Permission is granted to ...
1090 @node Top, Overview, , (dir)
1093 This document describes ...
1095 This document applies to version ...
1096 of the program named ...
1100 * Copying:: Your rights and freedoms.
1101 * First Chapter:: Getting started ...
1102 * Second Chapter:: ...
1107 @node First Chapter, Second Chapter, top, top
1108 @comment node-name, next, previous, up
1109 @chapter First Chapter
1110 @cindex Index entry for First Chapter
1113 File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File
1115 The Texinfo File Header
1116 =======================
1118 Texinfo files start with at least three lines that provide Info and
1119 TeX with necessary information. These are the `\input texinfo' line,
1120 the `@settitle' line, and the `@setfilename' line. If you want to run
1121 TeX on just a part of the Texinfo File, you must write the `@settitle'
1122 and `@setfilename' lines between start-of-header and end-of-header
1125 Thus, the beginning of a Texinfo file looks like this:
1127 \input texinfo @c -*-texinfo-*-
1128 @setfilename sample.info
1129 @settitle Sample Document
1133 \input texinfo @c -*-texinfo-*-
1134 @c %**start of header
1135 @setfilename sample.info
1136 @settitle Sample Document
1141 * First Line:: The first line of a Texinfo file.
1142 * Start of Header:: Formatting a region requires this.
1143 * setfilename:: Tell Info the name of the Info file.
1144 * settitle:: Create a title for the printed work.
1145 * setchapternewpage:: Start chapters on right-hand pages.
1146 * paragraphindent:: An option to specify paragraph indentation.
1147 * End of Header:: Formatting a region requires this.
1150 File: texinfo.info, Node: First Line, Next: Start of Header, Prev: Header, Up: Header
1152 The First Line of a Texinfo File
1153 --------------------------------
1155 Every Texinfo file that is to be the top-level input to TeX must begin
1156 with a line that looks like this:
1158 \input texinfo @c -*-texinfo-*-
1160 This line serves two functions:
1162 1. When the file is processed by TeX, the `\input texinfo' command
1163 tells TeX to load the macros needed for processing a Texinfo file.
1164 These are in a file called `texinfo.tex', which is usually located
1165 in the `/usr/lib/tex/macros' directory. TeX uses the backslash,
1166 `\', to mark the beginning of a command, just as Texinfo uses `@'.
1167 The `texinfo.tex' file causes the switch from `\' to `@'; before
1168 the switch occurs, TeX requires `\', which is why it appears at
1169 the beginning of the file.
1171 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
1172 specification tells Emacs to use Texinfo mode.
1175 File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header
1180 Write a start-of-header line on the second line of a Texinfo file.
1181 Follow the start-of-header line with `@setfilename' and `@settitle'
1182 lines and, optionally, with other command lines, such as `@smallbook'
1183 or `@footnotestyle'; and then by an end-of-header line (*note End of
1186 With these lines, you can format part of a Texinfo file for Info or
1187 typeset part for printing.
1189 A start-of-header line looks like this:
1191 @c %**start of header
1193 The odd string of characters, `%**', is to ensure that no other
1194 comment is accidentally taken for a start-of-header line.
1197 File: texinfo.info, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header
1202 In order to serve as the primary input file for either `makeinfo' or
1203 TeX, a Texinfo file must contain a line that looks like this:
1205 @setfilename INFO-FILE-NAME
1207 Write the `@setfilename' command at the beginning of a line and
1208 follow it on the same line by the Info file name. Do not write anything
1209 else on the line; anything on the line after the command is considered
1210 part of the file name, including what would otherwise be a comment.
1212 The `@setfilename' line specifies the name of the Info file to be
1213 generated. This name should be different from the name of the Texinfo
1214 file. There are two conventions for choosing the name: you can either
1215 remove the `.texi' extension from the input file name, or replace it
1216 with the `.info' extension.
1218 Some operating systems cannot handle long file names. You can run
1219 into a problem even when the file name you specify is itself short
1220 enough. This occurs because the Info formatters split a long Info file
1221 into short indirect subfiles, and name them by appending `-1', `-2',
1222 ..., `-10', `-11', and so on, to the original file name. (*Note Tag
1223 Files and Split Files: Tag and Split Files.) The subfile name
1224 `texinfo.info-10', for example, is too long for some systems; so the
1225 Info file name for this document is `texinfo' rather than
1228 The Info formatting commands ignore everything written before the
1229 `@setfilename' line, which is why the very first line of the file (the
1230 `\input' line) does not show up in the output.
1232 The `@setfilename' line produces no output when you typeset a manual
1233 with TeX, but it nevertheless is essential: it opens the index,
1234 cross-reference, and other auxiliary files used by Texinfo, and also
1235 reads `texinfo.cnf' if that file is present on your system (*note
1236 Preparing to Use TeX: Preparing for TeX.).
1239 File: texinfo.info, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header
1244 In order to be made into a printed manual, a Texinfo file must contain
1245 a line that looks like this:
1249 Write the `@settitle' command at the beginning of a line and follow
1250 it on the same line by the title. This tells TeX the title to use in a
1251 header or footer. Do not write anything else on the line; anything on
1252 the line after the command is considered part of the title, including a
1255 Conventionally, when TeX formats a Texinfo file for double-sided
1256 output, the title is printed in the left-hand (even-numbered) page
1257 headings and the current chapter title is printed in the right-hand
1258 (odd-numbered) page headings. (TeX learns the title of each chapter
1259 from each `@chapter' command.) Page footers are not printed.
1261 Even if you are printing in a single-sided style, TeX looks for an
1262 `@settitle' command line, in case you include the manual title in the
1265 The `@settitle' command should precede everything that generates
1266 actual output in TeX.
1268 Although the title in the `@settitle' command is usually the same as
1269 the title on the title page, it does not affect the title as it appears
1270 on the title page. Thus, the two do not need not match exactly; and
1271 the title in the `@settitle' command can be a shortened or expanded
1272 version of the title as it appears on the title page. (*Note
1273 `@titlepage': titlepage.)
1275 TeX prints page headings only for that text that comes after the
1276 `@end titlepage' command in the Texinfo file, or that comes after an
1277 `@headings' command that turns on headings. (*Note The `@headings'
1278 Command: headings on off, for more information.)
1280 You may, if you wish, create your own, customized headings and
1281 footings. *Note Page Headings: Headings, for a detailed discussion of