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. Update info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
9 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both online information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software
19 This edition is for Texinfo version 4.0, 28 September 1999.
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: Minimum, Next: Six Parts, Prev: Comments, Up: Overview
38 What a Texinfo File Must Have
39 =============================
41 By convention, the names of Texinfo files end with one of the
42 extensions `.texinfo', `.texi', `.txi', or `.tex'. The longer
43 extension is preferred since it describes more clearly to a human
44 reader the nature of the file. The shorter extensions are for
45 operating systems that cannot handle long file names.
47 In order to be made into a printed manual and an Info file, a Texinfo
48 file *must* begin with lines like this:
51 @setfilename INFO-FILE-NAME
52 @settitle NAME-OF-MANUAL
54 The contents of the file follow this beginning, and then you *must* end
55 a Texinfo file with a line like this:
59 The `\input texinfo' line tells TeX to use the `texinfo.tex' file,
60 which tells TeX how to translate the Texinfo @-commands into TeX
61 typesetting commands. (Note the use of the backslash, `\'; this is
62 correct for TeX.) The `@setfilename' line provides a name for the Info
63 file and tells TeX to open auxiliary files. The `@settitle' line
64 specifies a title for the page headers (or footers) of the printed
67 The `@bye' line at the end of the file on a line of its own tells the
68 formatters that the file is ended and to stop formatting.
70 Usually, you will not use quite such a spare format, but will include
71 mode setting and start-of-header and end-of-header lines at the
72 beginning of a Texinfo file, like this:
74 \input texinfo @c -*-texinfo-*-
76 @setfilename INFO-FILE-NAME
77 @settitle NAME-OF-MANUAL
80 In the first line, `-*-texinfo-*-' causes Emacs to switch into Texinfo
81 mode when you edit the file.
83 The `@c' lines which surround the `@setfilename' and `@settitle'
84 lines are optional, but you need them in order to run TeX or Info on
85 just part of the file. (*Note Start of Header::, for more information.)
87 Furthermore, you will usually provide a Texinfo file with a title
88 page, indices, and the like. But the minimum, which can be useful for
89 short documents, is just the three lines at the beginning and the one
93 File: texinfo.info, Node: Six Parts, Next: Short Sample, Prev: Minimum, Up: Overview
95 Six Parts of a Texinfo File
96 ===========================
98 Generally, a Texinfo file contains more than the minimal beginning
99 and end--it usually contains six parts:
102 The "Header" names the file, tells TeX which definitions' file to
103 use, and performs other "housekeeping" tasks.
105 2. Summary Description and Copyright
106 The "Summary Description and Copyright" segment describes the
107 document and contains the copyright notice and copying permissions
108 for the Info file. The segment must be enclosed between `@ifinfo'
109 and `@end ifinfo' commands so that the formatters place it only in
112 3. Title and Copyright
113 The "Title and Copyright" segment contains the title and copyright
114 pages and copying permissions for the printed manual. The segment
115 must be enclosed between `@titlepage' and `@end titlepage'
116 commands. The title and copyright page appear only in the printed
119 4. `Top' Node and Master Menu
120 The "Master Menu" contains a complete menu of all the nodes in the
121 whole Info file. It appears only in the Info file, in the `Top'
125 The "Body" of the document may be structured like a traditional
126 book or encyclopedia or it may be free form.
129 The "End" contains commands for printing indices and generating
130 the table of contents, and the `@bye' command on a line of its own.
133 File: texinfo.info, Node: Short Sample, Next: Acknowledgements and History, Prev: Six Parts, Up: Overview
135 A Short Sample Texinfo File
136 ===========================
138 Here is a complete but very short Texinfo file, in six parts. The
139 first three parts of the file, from `\input texinfo' through to `@end
140 titlepage', look more intimidating than they are. Most of the material
141 is standard boilerplate; when you write a manual, simply insert the
142 names for your own manual in this segment. (*Note Beginning a File::.)
144 In the following, the sample text is _indented_; comments on it are
145 not. The complete file, without any comments, is shown in *Note Sample
151 The header does not appear in either the Info file or the printed
152 output. It sets various parameters, including the name of the Info
153 file and the title used in the header.
155 \input texinfo @c -*-texinfo-*-
156 @c %**start of header
157 @setfilename sample.info
158 @settitle Sample Document
159 @setchapternewpage odd
162 Part 2: Summary Description and Copyright
163 -----------------------------------------
165 The summary description and copyright segment does not appear in the
169 This is a short example of a complete Texinfo file.
171 Copyright @copyright{} 1990 Free Software Foundation, Inc.
174 Part 3: Titlepage and Copyright
175 -------------------------------
177 The titlepage segment does not appear in the Info file.
181 @comment The title is printed in a large font.
182 @center @titlefont{Sample Title}
184 @c The following two commands start the copyright page.
186 @vskip 0pt plus 1filll
187 Copyright @copyright{} 1990 Free Software Foundation, Inc.
190 Part 4: `Top' Node and Master Menu
191 ----------------------------------
193 The `Top' node contains the master menu for the Info file. Since a
194 printed manual uses a table of contents rather than a menu, the master
195 menu appears only in the Info file.
197 @node Top, First Chapter, , (dir)
198 @comment node-name, next, previous, up
201 * First Chapter:: The first chapter is the
202 only chapter in this sample.
203 * Concept Index:: This index has two entries.
206 Part 5: The Body of the Document
207 ---------------------------------
209 The body segment contains all the text of the document, but not the
210 indices or table of contents. This example illustrates a node and a
211 chapter containing an enumerated list.
213 @node First Chapter, Concept Index, Top, Top
214 @comment node-name, next, previous, up
215 @chapter First Chapter
216 @cindex Sample index entry
218 This is the contents of the first chapter.
219 @cindex Another sample index entry
221 Here is a numbered list.
225 This is the first item.
228 This is the second item.
231 The @code{makeinfo} and @code{texinfo-format-buffer}
232 commands transform a Texinfo file such as this into
233 an Info file; and @TeX{} typesets it for a printed
236 Part 6: The End of the Document
237 -------------------------------
239 The end segment contains commands for generating an index in a node and
240 unnumbered chapter of its own, (usually) for generating the table of
241 contents, and the `@bye' command that marks the end of the document.
243 @node Concept Index, , First Chapter, Top
244 @unnumbered Concept Index
254 Here is what the contents of the first chapter of the sample look
258 This is the contents of the first chapter.
260 Here is a numbered list.
262 1. This is the first item.
264 2. This is the second item.
266 The `makeinfo' and `texinfo-format-buffer' commands transform a
267 Texinfo file such as this into an Info file; and TeX typesets it
268 for a printed manual.
271 File: texinfo.info, Node: Acknowledgements and History, Prev: Short Sample, Up: Overview
273 Acknowledgements and History
274 ============================
276 Richard M. Stallman invented the Texinfo format, wrote the initial
277 processors, and created Edition 1.0 of this manual. Robert J. Chassell
278 greatly revised and extended the manual, starting with Edition 1.1.
279 Brian Fox was responsible for the standalone Texinfo distribution until
280 version 3.8, and wrote the standalone `makeinfo' and `info'. Karl
281 Berry has made the updates since Texinfo 3.8 and subsequent releases,
282 starting with Edition 2.22 of the manual.
284 Our thanks go out to all who helped improve this work, particularly to
285 Franc,ois Pinard and David D. Zuhn, who tirelessly recorded and
286 reported mistakes and obscurities; our special thanks go to Melissa
287 Weisshaus for her frequent and often tedious reviews of nearly similar
288 editions. The indefatigable Eli Zaretskii and Andreas Schwab have
289 provided patches beyond counting. Zack Weinberg did the impossible by
290 implementing the macro syntax in `texinfo.tex'. Dozens of others have
291 contributed patches and suggestions, they are gratefully acknowledged
292 in the `ChangeLog' file. Our mistakes are our own.
294 A bit of history: in the 1970's at CMU, Brian Reid developed a program
295 and format named Scribe to mark up documents for printing. It used the
296 `@' character to introduce commands as Texinfo does and strived to
297 describe document contents rather than formatting.
299 Meanwhile, people at MIT developed another, not too dissimilar format
300 called Bolio. This then was converted to using TeX as its typesetting
303 BoTeX could only be used as a markup language for documents to be
304 printed, not for online documents. Richard Stallman (RMS) worked on
305 both Bolio and BoTeX. He also developed a nifty on-line help format
306 called Info, and then combined BoTeX and Info to create Texinfo, a mark
307 up language for text that is intended to be read both on line and as
311 File: texinfo.info, Node: Texinfo Mode, Next: Beginning a File, Prev: Overview, Up: Top
316 You may edit a Texinfo file with any text editor you choose. A
317 Texinfo file is no different from any other ASCII file. However, GNU
318 Emacs comes with a special mode, called Texinfo mode, that provides
319 Emacs commands and tools to help ease your work.
321 This chapter describes features of GNU Emacs' Texinfo mode but not any
322 features of the Texinfo formatting language. If you are reading this
323 manual straight through from the beginning, you may want to skim through
324 this chapter briefly and come back to it after reading succeeding
325 chapters which describe the Texinfo formatting language in detail.
329 * Texinfo Mode Overview:: How Texinfo mode can help you.
330 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
331 purpose editing features.
332 * Inserting:: How to insert frequently used @-commands.
333 * Showing the Structure:: How to show the structure of a file.
334 * Updating Nodes and Menus:: How to update or create new nodes and menus.
335 * Info Formatting:: How to format for Info.
336 * Printing:: How to format and print part or all of a file.
337 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
340 File: texinfo.info, Node: Texinfo Mode Overview, Next: Emacs Editing, Prev: Texinfo Mode, Up: Texinfo Mode
342 Texinfo Mode Overview
343 =====================
345 Texinfo mode provides special features for working with Texinfo files.
348 * Insert frequently used @-commands.
350 * Automatically create `@node' lines.
352 * Show the structure of a Texinfo source file.
354 * Automatically create or update the `Next', `Previous', and `Up'
357 * Automatically create or update menus.
359 * Automatically create a master menu.
361 * Format a part or all of a file for Info.
363 * Typeset and print part or all of a file.
365 Perhaps the two most helpful features are those for inserting
366 frequently used @-commands and for creating node pointers and menus.
369 File: texinfo.info, Node: Emacs Editing, Next: Inserting, Prev: Texinfo Mode Overview, Up: Texinfo Mode
371 The Usual GNU Emacs Editing Commands
372 ====================================
374 In most cases, the usual Text mode commands work the same in Texinfo
375 mode as they do in Text mode. Texinfo mode adds new editing commands
376 and tools to GNU Emacs' general purpose editing features. The major
377 difference concerns filling. In Texinfo mode, the paragraph separation
378 variable and syntax table are redefined so that Texinfo commands that
379 should be on lines of their own are not inadvertently included in
380 paragraphs. Thus, the `M-q' (`fill-paragraph') command will refill a
381 paragraph but not mix an indexing command on a line adjacent to it into
384 In addition, Texinfo mode sets the `page-delimiter' variable to the
385 value of `texinfo-chapter-level-regexp'; by default, this is a regular
386 expression matching the commands for chapters and their equivalents,
387 such as appendices. With this value for the page delimiter, you can
388 jump from chapter title to chapter title with the `C-x ]'
389 (`forward-page') and `C-x [' (`backward-page') commands and narrow to a
390 chapter with the `C-x p' (`narrow-to-page') command. (*Note Pages:
391 (emacs)Pages, for details about the page commands.)
393 You may name a Texinfo file however you wish, but the convention is to
394 end a Texinfo file name with one of the extensions `.texinfo', `.texi',
395 `.txi', or `.tex'. A longer extension is preferred, since it is
396 explicit, but a shorter extension may be necessary for operating
397 systems that limit the length of file names. GNU Emacs automatically
398 enters Texinfo mode when you visit a file with a `.texinfo', `.texi' or
399 `.txi' extension. Also, Emacs switches to Texinfo mode when you visit a
400 file that has `-*-texinfo-*-' in its first line. If ever you are in
401 another mode and wish to switch to Texinfo mode, type `M-x
404 Like all other Emacs features, you can customize or enhance Texinfo
405 mode as you wish. In particular, the keybindings are very easy to
406 change. The keybindings described here are the default or standard
410 File: texinfo.info, Node: Inserting, Next: Showing the Structure, Prev: Emacs Editing, Up: Texinfo Mode
412 Inserting Frequently Used Commands
413 ==================================
415 Texinfo mode provides commands to insert various frequently used
416 @-commands into the buffer. You can use these commands to save
419 The insert commands are invoked by typing `C-c' twice and then the
420 first letter of the @-command:
423 `M-x texinfo-insert-@code'
424 Insert `@code{}' and put the cursor between the braces.
427 `M-x texinfo-insert-@dfn'
428 Insert `@dfn{}' and put the cursor between the braces.
431 `M-x texinfo-insert-@end'
432 Insert `@end' and attempt to insert the correct following word,
433 such as `example' or `table'. (This command does not handle
434 nested lists correctly, but inserts the word appropriate to the
435 immediately preceding list.)
438 `M-x texinfo-insert-@item'
439 Insert `@item' and put the cursor at the beginning of the next
443 `M-x texinfo-insert-@kbd'
444 Insert `@kbd{}' and put the cursor between the braces.
447 `M-x texinfo-insert-@node'
448 Insert `@node' and a comment line listing the sequence for the
449 `Next', `Previous', and `Up' nodes. Leave point after the `@node'.
452 `M-x texinfo-insert-@noindent'
453 Insert `@noindent' and put the cursor at the beginning of the next
457 `M-x texinfo-insert-@samp'
458 Insert `@samp{}' and put the cursor between the braces.
461 `M-x texinfo-insert-@table'
462 Insert `@table' followed by a <SPC> and leave the cursor after the
466 `M-x texinfo-insert-@var'
467 Insert `@var{}' and put the cursor between the braces.
470 `M-x texinfo-insert-@example'
471 Insert `@example' and put the cursor at the beginning of the next
475 `M-x texinfo-insert-braces'
476 Insert `{}' and put the cursor between the braces.
481 Move from between a pair of braces forward past the closing brace.
482 Typing `C-c C-c ]' is easier than typing `C-c C-c }', which is,
483 however, more mnemonic; hence the two keybindings. (Also, you can
484 move out from between braces by typing `C-f'.)
486 To put a command such as `@code{...}' around an _existing_ word,
487 position the cursor in front of the word and type `C-u 1 C-c C-c c'.
488 This makes it easy to edit existing plain text. The value of the
489 prefix argument tells Emacs how many words following point to include
490 between braces--`1' for one word, `2' for two words, and so on. Use a
491 negative argument to enclose the previous word or words. If you do not
492 specify a prefix argument, Emacs inserts the @-command string and
493 positions the cursor between the braces. This feature works only for
494 those @-commands that operate on a word or words within one line, such
495 as `@kbd' and `@var'.
497 This set of insert commands was created after analyzing the frequency
498 with which different @-commands are used in the `GNU Emacs Manual' and
499 the `GDB Manual'. If you wish to add your own insert commands, you can
500 bind a keyboard macro to a key, use abbreviations, or extend the code
503 `C-c C-c C-d' (`texinfo-start-menu-description') is an insert command
504 that works differently from the other insert commands. It inserts a
505 node's section or chapter title in the space for the description in a
506 menu entry line. (A menu entry has three parts, the entry name, the
507 node name, and the description. Only the node name is required, but a
508 description helps explain what the node is about. *Note The Parts of a
511 To use `texinfo-start-menu-description', position point in a menu
512 entry line and type `C-c C-c C-d'. The command looks for and copies
513 the title that goes with the node name, and inserts the title as a
514 description; it positions point at beginning of the inserted text so you
515 can edit it. The function does not insert the title if the menu entry
516 line already contains a description.
518 This command is only an aid to writing descriptions; it does not do
519 the whole job. You must edit the inserted text since a title tends to
520 use the same words as a node name but a useful description uses
524 File: texinfo.info, Node: Showing the Structure, Next: Updating Nodes and Menus, Prev: Inserting, Up: Texinfo Mode
526 Showing the Section Structure of a File
527 =======================================
529 You can show the section structure of a Texinfo file by using the
530 `C-c C-s' command (`texinfo-show-structure'). This command shows the
531 section structure of a Texinfo file by listing the lines that begin
532 with the @-commands for `@chapter', `@section', and the like. It
533 constructs what amounts to a table of contents. These lines are
534 displayed in another buffer called the `*Occur*' buffer. In that
535 buffer, you can position the cursor over one of the lines and use the
536 `C-c C-c' command (`occur-mode-goto-occurrence'), to jump to the
537 corresponding spot in the Texinfo file.
540 `M-x texinfo-show-structure'
541 Show the `@chapter', `@section', and such lines of a Texinfo file.
544 `M-x occur-mode-goto-occurrence'
545 Go to the line in the Texinfo file corresponding to the line under
546 the cursor in the `*Occur*' buffer.
548 If you call `texinfo-show-structure' with a prefix argument by typing
549 `C-u C-c C-s', it will list not only those lines with the @-commands
550 for `@chapter', `@section', and the like, but also the `@node' lines.
551 You can use `texinfo-show-structure' with a prefix argument to check
552 whether the `Next', `Previous', and `Up' pointers of an `@node' line
555 Often, when you are working on a manual, you will be interested only
556 in the structure of the current chapter. In this case, you can mark
557 off the region of the buffer that you are interested in by using the
558 `C-x n n' (`narrow-to-region') command and `texinfo-show-structure'
559 will work on only that region. To see the whole buffer again, use
560 `C-x n w' (`widen'). (*Note Narrowing: (emacs)Narrowing, for more
561 information about the narrowing commands.)
563 In addition to providing the `texinfo-show-structure' command,
564 Texinfo mode sets the value of the page delimiter variable to match the
565 chapter-level @-commands. This enables you to use the `C-x ]'
566 (`forward-page') and `C-x [' (`backward-page') commands to move forward
567 and backward by chapter, and to use the `C-x p' (`narrow-to-page')
568 command to narrow to a chapter. *Note Pages: (emacs)Pages, for more
569 information about the page commands.
572 File: texinfo.info, Node: Updating Nodes and Menus, Next: Info Formatting, Prev: Showing the Structure, Up: Texinfo Mode
574 Updating Nodes and Menus
575 ========================
577 Texinfo mode provides commands for automatically creating or updating
578 menus and node pointers. The commands are called "update" commands
579 because their most frequent use is for updating a Texinfo file after
580 you have worked on it; but you can use them to insert the `Next',
581 `Previous', and `Up' pointers into an `@node' line that has none and to
582 create menus in a file that has none.
584 If you do not use the updating commands, you need to write menus and
585 node pointers by hand, which is a tedious task.
589 * Updating Commands:: Five major updating commands.
590 * Updating Requirements:: How to structure a Texinfo file for
591 using the updating command.
592 * Other Updating Commands:: How to indent descriptions, insert
593 missing nodes lines, and update
597 File: texinfo.info, Node: Updating Commands, Next: Updating Requirements, Prev: Updating Nodes and Menus, Up: Updating Nodes and Menus
599 The Updating Commands
600 ---------------------
602 You can use the updating commands to:
604 * insert or update the `Next', `Previous', and `Up' pointers of a
607 * insert or update the menu for a section, and
609 * create a master menu for a Texinfo source file.
611 You can also use the commands to update all the nodes and menus in a
612 region or in a whole Texinfo file.
614 The updating commands work only with conventional Texinfo files, which
615 are structured hierarchically like books. In such files, a structuring
616 command line must follow closely after each `@node' line, except for
617 the `Top' `@node' line. (A "structuring command line" is a line
618 beginning with `@chapter', `@section', or other similar command.)
620 You can write the structuring command line on the line that follows
621 immediately after an `@node' line or else on the line that follows
622 after a single `@comment' line or a single `@ifinfo' line. You cannot
623 interpose more than one line between the `@node' line and the
624 structuring command line; and you may interpose only an `@comment' line
625 or an `@ifinfo' line.
627 Commands which work on a whole buffer require that the `Top' node be
628 followed by a node with an `@chapter' or equivalent-level command. The
629 menu updating commands will not create a main or master menu for a
630 Texinfo file that has only `@chapter'-level nodes! The menu updating
631 commands only create menus _within_ nodes for lower level nodes. To
632 create a menu of chapters, you must provide a `Top' node.
634 The menu updating commands remove menu entries that refer to other
635 Info files since they do not refer to nodes within the current buffer.
636 This is a deficiency. Rather than use menu entries, you can use cross
637 references to refer to other Info files. None of the updating commands
638 affect cross references.
640 Texinfo mode has five updating commands that are used most often: two
641 are for updating the node pointers or menu of a single node (or a
642 region); two are for updating every node pointer and menu in a file;
643 and one, the `texinfo-master-menu' command, is for creating a master
644 menu for a complete file, and optionally, for updating every node and
645 menu in the whole Texinfo file.
647 The `texinfo-master-menu' command is the primary command:
650 `M-x texinfo-master-menu'
651 Create or update a master menu that includes all the other menus
652 (incorporating the descriptions from pre-existing menus, if any).
654 With an argument (prefix argument, `C-u,' if interactive), first
655 create or update all the nodes and all the regular menus in the
656 buffer before constructing the master menu. (*Note The Top Node
657 and Master Menu: The Top Node, for more about a master menu.)
659 For `texinfo-master-menu' to work, the Texinfo file must have a
660 `Top' node and at least one subsequent node.
662 After extensively editing a Texinfo file, you can type the
665 C-u M-x texinfo-master-menu
669 This updates all the nodes and menus completely and all at once.
671 The other major updating commands do smaller jobs and are designed for
672 the person who updates nodes and menus as he or she writes a Texinfo
678 `M-x texinfo-update-node'
679 Insert the `Next', `Previous', and `Up' pointers for the node that
680 point is within (i.e., for the `@node' line preceding point). If
681 the `@node' line has pre-existing `Next', `Previous', or `Up'
682 pointers in it, the old pointers are removed and new ones inserted.
683 With an argument (prefix argument, `C-u', if interactive), this
684 command updates all `@node' lines in the region (which is the text
685 between point and mark).
688 `M-x texinfo-make-menu'
689 Create or update the menu in the node that point is within. With
690 an argument (`C-u' as prefix argument, if interactive), the
691 command makes or updates menus for the nodes which are either
692 within or a part of the region.
694 Whenever `texinfo-make-menu' updates an existing menu, the
695 descriptions from that menu are incorporated into the new menu.
696 This is done by copying descriptions from the existing menu to the
697 entries in the new menu that have the same node names. If the
698 node names are different, the descriptions are not copied to the
702 `M-x texinfo-every-node-update'
703 Insert or update the `Next', `Previous', and `Up' pointers for
704 every node in the buffer.
707 `M-x texinfo-all-menus-update'
708 Create or update all the menus in the buffer. With an argument
709 (`C-u' as prefix argument, if interactive), first insert or update
710 all the node pointers before working on the menus.
712 If a master menu exists, the `texinfo-all-menus-update' command
713 updates it; but the command does not create a new master menu if
714 none already exists. (Use the `texinfo-master-menu' command for
717 When working on a document that does not merit a master menu, you
718 can type the following:
722 C-u M-x texinfo-all-menus-update
724 This updates all the nodes and menus.
726 The `texinfo-column-for-description' variable specifies the column to
727 which menu descriptions are indented. By default, the value is 32
728 although it is often useful to reduce it to as low as 24. You can set
729 the variable with the `M-x edit-options' command (*note Editing
730 Variable Values: (emacs)Edit Options.) or with the `M-x set-variable'
731 command (*note Examining and Setting Variables: (emacs)Examining.).
733 Also, the `texinfo-indent-menu-description' command may be used to
734 indent existing menu descriptions to a specified column. Finally, if
735 you wish, you can use the `texinfo-insert-node-lines' command to insert
736 missing `@node' lines into a file. (*Note Other Updating Commands::,
737 for more information.)
740 File: texinfo.info, Node: Updating Requirements, Next: Other Updating Commands, Prev: Updating Commands, Up: Updating Nodes and Menus
742 Updating Requirements
743 ---------------------
745 To use the updating commands, you must organize the Texinfo file
746 hierarchically with chapters, sections, subsections, and the like.
747 When you construct the hierarchy of the manual, do not `jump down' more
748 than one level at a time: you can follow the `Top' node with a chapter,
749 but not with a section; you can follow a chapter with a section, but
750 not with a subsection. However, you may `jump up' any number of levels
751 at one time--for example, from a subsection to a chapter.
753 Each `@node' line, with the exception of the line for the `Top' node,
754 must be followed by a line with a structuring command such as
755 `@chapter', `@section', or `@unnumberedsubsec'.
757 Each `@node' line/structuring-command line combination must look
760 @node Comments, Minimum, Conventions, Overview
761 @comment node-name, next, previous, up
764 or like this (without the `@comment' line):
766 @node Comments, Minimum, Conventions, Overview
769 In this example, `Comments' is the name of both the node and the
770 section. The next node is called `Minimum' and the previous node is
771 called `Conventions'. The `Comments' section is within the `Overview'
772 node, which is specified by the `Up' pointer. (Instead of an
773 `@comment' line, you may also write an `@ifinfo' line.)
775 If a file has a `Top' node, it must be called `top' or `Top' and be
776 the first node in the file.
778 The menu updating commands create a menu of sections within a chapter,
779 a menu of subsections within a section, and so on. This means that you
780 must have a `Top' node if you want a menu of chapters.
782 Incidentally, the `makeinfo' command will create an Info file for a
783 hierarchically organized Texinfo file that lacks `Next', `Previous' and
784 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
785 formatted with `makeinfo', you have no need for the update node
786 commands. (*Note Creating an Info File::, for more information about
787 `makeinfo'.) However, both `makeinfo' and the `texinfo-format-...'
788 commands require that you insert menus in the file.
791 File: texinfo.info, Node: Other Updating Commands, Prev: Updating Requirements, Up: Updating Nodes and Menus
793 Other Updating Commands
794 -----------------------
796 In addition to the five major updating commands, Texinfo mode
797 possesses several less frequently used updating commands:
799 `M-x texinfo-insert-node-lines'
800 Insert `@node' lines before the `@chapter', `@section', and other
801 sectioning commands wherever they are missing throughout a region
804 With an argument (`C-u' as prefix argument, if interactive), the
805 `texinfo-insert-node-lines' command not only inserts `@node' lines
806 but also inserts the chapter or section titles as the names of the
807 corresponding nodes. In addition, it inserts the titles as node
808 names in pre-existing `@node' lines that lack names. Since node
809 names should be more concise than section or chapter titles, you
810 must manually edit node names so inserted.
812 For example, the following marks a whole buffer as a region and
813 inserts `@node' lines and titles throughout:
815 C-x h C-u M-x texinfo-insert-node-lines
817 This command inserts titles as node names in `@node' lines; the
818 `texinfo-start-menu-description' command (*note Inserting
819 Frequently Used Commands: Inserting.) inserts titles as
820 descriptions in menu entries, a different action. However, in
821 both cases, you need to edit the inserted text.
823 `M-x texinfo-multiple-files-update'
824 Update nodes and menus in a document built from several separate
825 files. With `C-u' as a prefix argument, create and insert a
826 master menu in the outer file. With a numeric prefix argument,
827 such as `C-u 2', first update all the menus and all the `Next',
828 `Previous', and `Up' pointers of all the included files before
829 creating and inserting a master menu in the outer file. The
830 `texinfo-multiple-files-update' command is described in the
831 appendix on `@include' files. *Note
832 texinfo-multiple-files-update::.
834 `M-x texinfo-indent-menu-description'
835 Indent every description in the menu following point to the
836 specified column. You can use this command to give yourself more
837 space for descriptions. With an argument (`C-u' as prefix
838 argument, if interactive), the `texinfo-indent-menu-description'
839 command indents every description in every menu in the region.
840 However, this command does not indent the second and subsequent
841 lines of a multi-line description.
843 `M-x texinfo-sequential-node-update'
844 Insert the names of the nodes immediately following and preceding
845 the current node as the `Next' or `Previous' pointers regardless
846 of those nodes' hierarchical level. This means that the `Next'
847 node of a subsection may well be the next chapter. Sequentially
848 ordered nodes are useful for novels and other documents that you
849 read through sequentially. (However, in Info, the `g *' command
850 lets you look through the file sequentially, so sequentially
851 ordered nodes are not strictly necessary.) With an argument
852 (prefix argument, if interactive), the
853 `texinfo-sequential-node-update' command sequentially updates all
854 the nodes in the region.
857 File: texinfo.info, Node: Info Formatting, Next: Printing, Prev: Updating Nodes and Menus, Up: Texinfo Mode
862 Texinfo mode provides several commands for formatting part or all of a
863 Texinfo file for Info. Often, when you are writing a document, you
864 want to format only part of a file--that is, a region.
866 You can use either the `texinfo-format-region' or the
867 `makeinfo-region' command to format a region:
870 `M-x texinfo-format-region'
872 `M-x makeinfo-region'
873 Format the current region for Info.
875 You can use either the `texinfo-format-buffer' or the
876 `makeinfo-buffer' command to format a whole buffer:
879 `M-x texinfo-format-buffer'
881 `M-x makeinfo-buffer'
882 Format the current buffer for Info.
884 For example, after writing a Texinfo file, you can type the following:
888 C-u M-x texinfo-master-menu
890 This updates all the nodes and menus. Then type the following to create
897 For TeX or the Info formatting commands to work, the file _must_
898 include a line that has `@setfilename' in its header.
900 *Note Creating an Info File::, for details about Info formatting.
903 File: texinfo.info, Node: Printing, Next: Texinfo Mode Summary, Prev: Info Formatting, Up: Texinfo Mode
905 Formatting and Printing
906 =======================
908 Typesetting and printing a Texinfo file is a multi-step process in
909 which you first create a file for printing (called a DVI file), and then
910 print the file. Optionally, you may also create indices. To do this,
911 you must run the `texindex' command after first running the `tex'
912 typesetting command; and then you must run the `tex' command again. Or
913 else run the `texi2dvi' command which automatically creates indices as
914 needed (*note Format with texi2dvi::).
916 Often, when you are writing a document, you want to typeset and print
917 only part of a file to see what it will look like. You can use the
918 `texinfo-tex-region' and related commands for this purpose. Use the
919 `texinfo-tex-buffer' command to format all of a buffer.
922 `M-x texinfo-tex-buffer'
923 Run `texi2dvi' on the buffer. In addition to running TeX on the
924 buffer, this command automatically creates or updates indices as
928 `M-x texinfo-tex-region'
929 Run TeX on the region.
932 `M-x texinfo-texindex'
933 Run `texindex' to sort the indices of a Texinfo file formatted with
934 `texinfo-tex-region'. The `texinfo-tex-region' command does not
935 run `texindex' automatically; it only runs the `tex' typesetting
936 command. You must run the `texinfo-tex-region' command a second
937 time after sorting the raw index files with the `texindex'
938 command. (Usually, you do not format an index when you format a
939 region, only when you format a buffer. Now that the `texi2dvi'
940 command exists, there is little or no need for this command.)
943 `M-x texinfo-tex-print'
944 Print the file (or the part of the file) previously formatted with
945 `texinfo-tex-buffer' or `texinfo-tex-region'.
947 For `texinfo-tex-region' or `texinfo-tex-buffer' to work, the file
948 _must_ start with a `\input texinfo' line and must include an
949 `@settitle' line. The file must end with `@bye' on a line by itself.
950 (When you use `texinfo-tex-region', you must surround the `@settitle'
951 line with start-of-header and end-of-header lines.)
953 *Note Hardcopy::, for a description of the other TeX related
954 commands, such as `tex-show-print-queue'.
957 File: texinfo.info, Node: Texinfo Mode Summary, Prev: Printing, Up: Texinfo Mode
962 In Texinfo mode, each set of commands has default keybindings that
963 begin with the same keys. All the commands that are custom-created for
964 Texinfo mode begin with `C-c'. The keys are somewhat mnemonic.
969 The insert commands are invoked by typing `C-c' twice and then the
970 first letter of the @-command to be inserted. (It might make more
971 sense mnemonically to use `C-c C-i', for `custom insert', but `C-c C-c'
974 C-c C-c c Insert `@code'.
975 C-c C-c d Insert `@dfn'.
976 C-c C-c e Insert `@end'.
977 C-c C-c i Insert `@item'.
978 C-c C-c n Insert `@node'.
979 C-c C-c s Insert `@samp'.
980 C-c C-c v Insert `@var'.
981 C-c C-c { Insert braces.
983 C-c C-c } Move out of enclosing braces.
985 C-c C-c C-d Insert a node's section title
986 in the space for the description
987 in a menu entry line.
992 The `texinfo-show-structure' command is often used within a narrowed
995 C-c C-s List all the headings.
997 The Master Update Command
998 -------------------------
1000 The `texinfo-master-menu' command creates a master menu; and can be
1001 used to update every node and menu in a file as well.
1004 M-x texinfo-master-menu
1005 Create or update a master menu.
1007 C-u C-c C-u m With `C-u' as a prefix argument, first
1008 create or update all nodes and regular
1009 menus, and then create a master menu.
1014 The update pointer commands are invoked by typing `C-c C-u' and then
1015 either `C-n' for `texinfo-update-node' or `C-e' for
1016 `texinfo-every-node-update'.
1018 C-c C-u C-n Update a node.
1019 C-c C-u C-e Update every node in the buffer.
1024 Invoke the update menu commands by typing `C-c C-u' and then either
1025 `C-m' for `texinfo-make-menu' or `C-a' for `texinfo-all-menus-update'.
1026 To update both nodes and menus at the same time, precede `C-c C-u C-a'
1029 C-c C-u C-m Make or update a menu.
1031 C-c C-u C-a Make or update all
1034 C-u C-c C-u C-a With `C-u' as a prefix argument,
1035 first create or update all nodes and
1036 then create or update all menus.
1041 The Info formatting commands that are written in Emacs Lisp are
1042 invoked by typing `C-c C-e' and then either `C-r' for a region or `C-b'
1043 for the whole buffer.
1045 The Info formatting commands that are written in C and based on the
1046 `makeinfo' program are invoked by typing `C-c C-m' and then either
1047 `C-r' for a region or `C-b' for the whole buffer.
1049 Use the `texinfo-format...' commands:
1051 C-c C-e C-r Format the region.
1052 C-c C-e C-b Format the buffer.
1056 C-c C-m C-r Format the region.
1057 C-c C-m C-b Format the buffer.
1058 C-c C-m C-l Recenter the `makeinfo' output buffer.
1059 C-c C-m C-k Kill the `makeinfo' formatting job.
1064 The TeX typesetting and printing commands are invoked by typing `C-c
1065 C-t' and then another control command: `C-r' for `texinfo-tex-region',
1066 `C-b' for `texinfo-tex-buffer', and so on.
1068 C-c C-t C-r Run TeX on the region.
1069 C-c C-t C-b Run `texi2dvi' on the buffer.
1070 C-c C-t C-i Run `texindex'.
1071 C-c C-t C-p Print the DVI file.
1072 C-c C-t C-q Show the print queue.
1073 C-c C-t C-d Delete a job from the print queue.
1074 C-c C-t C-k Kill the current TeX formatting job.
1075 C-c C-t C-x Quit a currently stopped TeX formatting job.
1076 C-c C-t C-l Recenter the output buffer.
1078 Other Updating Commands
1079 -----------------------
1081 The remaining updating commands do not have standard keybindings
1082 because they are rarely used.
1084 M-x texinfo-insert-node-lines
1085 Insert missing `@node' lines in region.
1086 With `C-u' as a prefix argument,
1087 use section titles as node names.
1089 M-x texinfo-multiple-files-update
1090 Update a multi-file document.
1091 With `C-u 2' as a prefix argument,
1092 create or update all nodes and menus
1093 in all included files first.
1095 M-x texinfo-indent-menu-description
1096 Indent descriptions.
1098 M-x texinfo-sequential-node-update
1099 Insert node pointers in strict sequence.
1102 File: texinfo.info, Node: Beginning a File, Next: Ending a File, Prev: Texinfo Mode, Up: Top
1104 Beginning a Texinfo File
1105 ************************
1107 Certain pieces of information must be provided at the beginning of a
1108 Texinfo file, such as the name of the file and the title of the
1113 * Four Parts:: Four parts begin a Texinfo file.
1114 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
1115 * Header:: The very beginning of a Texinfo file.
1116 * Info Summary and Permissions:: Summary and copying permissions for Info.
1117 * Titlepage & Copyright Page:: Creating the title and copyright pages.
1118 * The Top Node:: Creating the `Top' node and master menu.
1119 * Software Copying Permissions:: Ensure that you and others continue to
1120 have the right to use and share software.
1123 File: texinfo.info, Node: Four Parts, Next: Sample Beginning, Prev: Beginning a File, Up: Beginning a File
1125 Four Parts Begin a File
1126 =======================
1128 Generally, the beginning of a Texinfo file has four parts:
1130 1. The header, delimited by special comment lines, that includes the
1131 commands for naming the Texinfo file and telling TeX what
1132 definitions file to use when processing the Texinfo file.
1134 2. A short statement of what the file is about, with a copyright
1135 notice and copying permissions. This is enclosed in `@ifinfo' and
1136 `@end ifinfo' commands so that the formatters place it only in the
1139 3. A title page and copyright page, with a copyright notice and
1140 copying permissions. This is enclosed between `@titlepage' and
1141 `@end titlepage' commands. The title and copyright page appear
1142 only in the printed manual.
1144 4. The `Top' node that contains a menu for the whole Info file. The
1145 contents of this node appear only in the Info file.
1147 Also, optionally, you may include the copying conditions for a program
1148 and a warranty disclaimer. The copying section will be followed by an
1149 introduction or else by the first chapter of the manual.
1151 Since the copyright notice and copying permissions for the Texinfo
1152 document (in contrast to the copying permissions for a program) are in
1153 parts that appear only in the Info file or only in the printed manual,
1154 this information must be given twice.
1157 File: texinfo.info, Node: Sample Beginning, Next: Header, Prev: Four Parts, Up: Beginning a File
1159 Sample Texinfo File Beginning
1160 =============================
1162 The following sample shows what is needed.
1164 \input texinfo @c -*-texinfo-*-
1165 @c %**start of header
1166 @setfilename NAME-OF-INFO-FILE
1167 @settitle NAME-OF-MANUAL
1168 @setchapternewpage odd
1172 This file documents ...
1174 Copyright YEAR COPYRIGHT-OWNER
1176 Permission is granted to ...
1179 @c This title page illustrates only one of the
1180 @c two methods of forming a title page.
1183 @title NAME-OF-MANUAL-WHEN-PRINTED
1184 @subtitle SUBTITLE-IF-ANY
1185 @subtitle SECOND-SUBTITLE
1188 @c The following two commands
1189 @c start the copyright page.
1191 @vskip 0pt plus 1filll
1192 Copyright @copyright{} YEAR COPYRIGHT-OWNER
1196 Permission is granted to ...
1199 @node Top, Overview, , (dir)
1202 This document describes ...
1204 This document applies to version ...
1205 of the program named ...
1209 * Copying:: Your rights and freedoms.
1210 * First Chapter:: Getting started ...
1211 * Second Chapter:: ...
1216 @node First Chapter, Second Chapter, top, top
1217 @comment node-name, next, previous, up
1218 @chapter First Chapter
1219 @cindex Index entry for First Chapter
1222 File: texinfo.info, Node: Header, Next: Info Summary and Permissions, Prev: Sample Beginning, Up: Beginning a File
1224 The Texinfo File Header
1225 =======================
1227 Texinfo files start with at least three lines that provide Info and
1228 TeX with necessary information. These are the `\input texinfo' line,
1229 the `@settitle' line, and the `@setfilename' line. If you want to run
1230 TeX on just a part of the Texinfo File, you must write the `@settitle'
1231 and `@setfilename' lines between start-of-header and end-of-header
1234 Thus, the beginning of a Texinfo file looks like this:
1236 \input texinfo @c -*-texinfo-*-
1237 @setfilename sample.info
1238 @settitle Sample Document
1242 \input texinfo @c -*-texinfo-*-
1243 @c %**start of header
1244 @setfilename sample.info
1245 @settitle Sample Document
1250 * First Line:: The first line of a Texinfo file.
1251 * Start of Header:: Formatting a region requires this.
1252 * setfilename:: Tell Info the name of the Info file.
1253 * settitle:: Create a title for the printed work.
1254 * setchapternewpage:: Start chapters on right-hand pages.
1255 * paragraphindent:: Specify paragraph indentation.
1256 * exampleindent:: Specify environment indentation.
1257 * End of Header:: Formatting a region requires this.
1260 File: texinfo.info, Node: First Line, Next: Start of Header, Up: Header
1262 The First Line of a Texinfo File
1263 --------------------------------
1265 Every Texinfo file that is to be the top-level input to TeX must begin
1266 with a line that looks like this:
1268 \input texinfo @c -*-texinfo-*-
1270 This line serves two functions:
1272 1. When the file is processed by TeX, the `\input texinfo' command
1273 tells TeX to load the macros needed for processing a Texinfo file.
1274 These are in a file called `texinfo.tex', which is usually located
1275 in the `/usr/lib/tex/macros' directory. TeX uses the backslash,
1276 `\', to mark the beginning of a command, just as Texinfo uses `@'.
1277 The `texinfo.tex' file causes the switch from `\' to `@'; before
1278 the switch occurs, TeX requires `\', which is why it appears at
1279 the beginning of the file.
1281 2. When the file is edited in GNU Emacs, the `-*-texinfo-*-' mode
1282 specification tells Emacs to use Texinfo mode.
1285 File: texinfo.info, Node: Start of Header, Next: setfilename, Prev: First Line, Up: Header
1290 Write a start-of-header line on the second line of a Texinfo file.
1291 Follow the start-of-header line with `@setfilename' and `@settitle'
1292 lines and, optionally, with other command lines, such as `@smallbook'
1293 or `@footnotestyle'; and then by an end-of-header line (*note End of
1296 With these lines, you can format part of a Texinfo file for Info or
1297 typeset part for printing.
1299 A start-of-header line looks like this:
1301 @c %**start of header
1303 The odd string of characters, `%**', is to ensure that no other
1304 comment is accidentally taken for a start-of-header line.