Contents in 1999-06-04-13 of release-21-2.
[chise/xemacs-chise.git.1] / man / texinfo.texi
1 \input texinfo.tex    @c -*-texinfo-*-
2 @c $Id: texinfo.texi,v 1.8.2.1 1999/03/04 15:48:24 steveb Exp $
3 @c %**start of header
4
5 @c All text is ignored before the setfilename.
6 @setfilename ../info/texinfo
7 @settitle Texinfo @value{edition}
8
9 @c Edition number is now the same as the Texinfo distribution version number.
10 @set edition 3.12
11 @set update-month February 1998
12 @set update-date 27 @value{update-month}
13
14 @c Define a new index for options.
15 @defcodeindex op
16 @c Put everything except function (command, in this case) names in one
17 @c index (arbitrarily chosen to be the concept index).
18 @syncodeindex op cp
19 @syncodeindex vr cp
20 @syncodeindex pg cp
21
22 @footnotestyle separate
23 @paragraphindent 2
24 @finalout
25 @comment %**end of header
26
27 @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
28 @c prefix arg).  This updates the node pointers, which texinfmt.el needs.
29
30 @dircategory Texinfo documentation system
31 @direntry
32 * Texinfo: (texinfo).           The GNU documentation format.
33 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
34 * texi2dvi: (texinfo)Format with texi2dvi.      Printing Texinfo documentation.
35 * texindex: (texinfo)Format with tex/texindex.  Sorting Texinfo index files.
36 * makeinfo: (texinfo)makeinfo Preferred.        Translate Texinfo source.
37 @end direntry
38
39 @c Set smallbook if printing in smallbook format so the example of the
40 @c smallbook font is actually written using smallbook; in bigbook, a kludge
41 @c is used for TeX output.  Do this through the -t option to texi2dvi,
42 @c so this same source can be used for other paper sizes as well.
43 @c smallbook
44 @c set smallbook
45 @c @@clear smallbook
46
47 @c Currently undocumented command, 5 December 1993:
48 @c nwnode          (Same as node, but no warnings; for `makeinfo'.)
49
50 @ifinfo
51 This file documents Texinfo, a documentation system that can produce
52 both on-line information and a printed manual from a single source file.
53
54 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98
55 Free Software Foundation, Inc.
56
57 This edition is for Texinfo version @value{edition}.
58
59 Permission is granted to make and distribute verbatim copies of
60 this manual provided the copyright notice and this permission notice
61 are preserved on all copies.
62
63 @ignore
64 Permission is granted to process this file through TeX and print the
65 results, provided the printed document carries copying permission
66 notice identical to this one except for the removal of this paragraph
67 (this paragraph not being relevant to the printed manual).
68
69 @end ignore
70 Permission is granted to copy and distribute modified versions of this
71 manual under the conditions for verbatim copying, provided that the entire
72 resulting derived work is distributed under the terms of a permission
73 notice identical to this one.
74
75 Permission is granted to copy and distribute translations of this manual
76 into another language, under the above conditions for modified versions,
77 except that this permission notice may be stated in a translation approved
78 by the Free Software Foundation.
79 @end ifinfo
80
81 @setchapternewpage odd
82
83 @shorttitlepage Texinfo
84
85 @titlepage
86 @c use the new format for titles
87 @title Texinfo
88 @subtitle The GNU Documentation Format
89 @subtitle for Texinfo version @value{edition}
90 @subtitle @value{update-month}
91
92 @author Robert J.@: Chassell
93 @author Richard M.@: Stallman
94
95 @c Include the Distribution inside the titlepage so
96 @c that headings are turned off.
97
98 @page
99 @vskip 0pt plus 1filll
100 Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98
101 Free Software Foundation, Inc.
102
103 Published by the Free Software Foundation @*
104 59 Temple Place Suite 330 @*
105 Boston, MA 02111-1307 @*
106 USA @*
107 ISBN 1-882114-65-5
108 @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
109 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
110
111 Permission is granted to make and distribute verbatim copies of
112 this manual provided the copyright notice and this permission notice
113 are preserved on all copies.
114
115 Permission is granted to copy and distribute modified versions of this
116 manual under the conditions for verbatim copying, provided that the entire
117 resulting derived work is distributed under the terms of a permission
118 notice identical to this one.
119
120 Permission is granted to copy and distribute translations of this manual
121 into another language, under the above conditions for modified versions,
122 except that this permission notice may be stated in a translation approved
123 by the Free Software Foundation.
124 @sp 2
125 Cover art by Etienne Suvasa.
126 @end titlepage
127
128 @ifinfo
129 @node Top, Copying, (dir), (dir)
130 @top Texinfo
131
132 Texinfo is a documentation system that uses a single source file to
133 produce both on-line information and printed output.@refill
134
135 The first part of this master menu lists the major nodes in this Info
136 document, including the @@-command and concept indices.  The rest of
137 the menu lists all the lower level nodes in the document.@refill
138
139 This is Edition @value{edition} of the Texinfo documentation,
140 @w{@value{update-date}}.
141 @end ifinfo
142
143 @c Here is a spare copy of the chapter menu entry descriptions,
144 @c in case they are accidently deleted
145 @ignore
146 Your rights.
147 Texinfo in brief.
148 How to use Texinfo mode.
149 What is at the beginning of a Texinfo file?
150 What is at the end of a Texinfo file?
151 How to create chapters, sections, subsections,
152   appendices, and other parts.
153 How to provide structure for a document.
154 How to write nodes.
155 How to write menus.
156 How to write cross references.
157 How to mark words and phrases as code,
158   keyboard input, meta-syntactic
159   variables, and the like.
160 How to write quotations, examples, etc.
161 How to write lists and tables.
162 How to create indices.
163 How to insert @@-signs, braces, etc.
164 How to indicate results of evaluation,
165   expansion of macros, errors, etc.
166 How to force and prevent line and page breaks.
167 How to describe functions and the like in a uniform manner.
168 How to write footnotes.
169 How to specify text for either @TeX{} or Info.
170 How to print hardcopy.
171 How to create an Info file.
172 How to install an Info file
173 A list of all the Texinfo @@-commands.
174 Hints on how to write a Texinfo document.
175 A sample Texinfo file to look at.
176 Tell readers they have the right to copy
177   and distribute.
178 How to incorporate other Texinfo files.
179 How to write page headings and footings.
180 How to find formatting mistakes.
181 All about paragraph refilling.
182 A description of @@-Command syntax.
183 Texinfo second edition features.
184 A menu containing commands and variables.
185 A menu covering many topics.
186 @end ignore
187
188 @menu
189 * Copying::                     Your rights.
190 * Overview::                    Texinfo in brief.
191 * Texinfo Mode::                How to use Texinfo mode.
192 * Beginning a File::            What is at the beginning of a Texinfo file?
193 * Ending a File::               What is at the end of a Texinfo file?
194 * Structuring::                 How to create chapters, sections, subsections,
195                                   appendices, and other parts.
196 * Nodes::                       How to write nodes.
197 * Menus::                       How to write menus.
198 * Cross References::            How to write cross references.
199 * Marking Text::                How to mark words and phrases as code,
200                                   keyboard input, meta-syntactic
201                                   variables, and the like.
202 * Quotations and Examples::     How to write quotations, examples, etc.
203 * Lists and Tables::            How to write lists and tables.
204 * Indices::                     How to create indices.
205 * Insertions::                  How to insert @@-signs, braces, etc.
206 * Breaks::                      How to force and prevent line and page breaks.
207 * Definition Commands::         How to describe functions and the like
208                                   in a uniform manner.
209 * Footnotes::                   How to write footnotes.
210 * Conditionals::                How to specify text for either @TeX{} or Info.
211 * Macros::                      Defining new Texinfo commands.
212 * Format/Print Hardcopy::       How to convert a Texinfo file to a file
213                                   for printing and how to print that file.
214 * Create an Info File::         Convert a Texinfo file into an Info file.
215 * Install an Info File::        Make an Info file accessible to users.
216 * Command List::                All the Texinfo @@-commands.
217 * Tips::                        Hints on how to write a Texinfo document.
218 * Sample Texinfo File::         A sample Texinfo file to look at.
219 * Sample Permissions::          Tell readers they have the right to copy
220                                   and distribute.
221 * Include Files::               How to incorporate other Texinfo files.
222 * Headings::                    How to write page headings and footings.
223 * Catching Mistakes::           How to find formatting mistakes.
224 * Refilling Paragraphs::        All about paragraph refilling.
225 * Command Syntax::              A description of @@-Command syntax.
226 * Obtaining TeX::               How to Obtain @TeX{}.
227 * Command and Variable Index::  A menu containing commands and variables.
228 * Concept Index::               A menu covering many topics.
229
230 @detailmenu
231
232  --- The Detailed Node Listing ---
233
234 Overview of Texinfo
235
236 * Using Texinfo::               Create a conventional printed book
237                                   or an Info file.
238 * Info Files::                  What is an Info file?
239 * Printed Books::               Characteristics of a printed book or manual.
240 * Formatting Commands::         @@-commands are used for formatting.
241 * Conventions::                 General rules for writing a Texinfo file.
242 * Comments::                    How to write comments and mark regions that
243                                   the formatting commands will ignore.
244 * Minimum::                     What a Texinfo file must have.
245 * Six Parts::                   Usually, a Texinfo file has six parts.
246 * Short Sample::                A short sample Texinfo file.
247 * Acknowledgements::            
248
249 Using Texinfo Mode
250
251 * Texinfo Mode Overview::       How Texinfo mode can help you.
252 * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
253                                   purpose editing features.
254 * Inserting::                   How to insert frequently used @@-commands.
255 * Showing the Structure::       How to show the structure of a file.
256 * Updating Nodes and Menus::    How to update or create new nodes and menus.
257 * Info Formatting::             How to format for Info.
258 * Printing::                    How to format and print part or all of a file.
259 * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
260
261 Updating Nodes and Menus
262
263 * Updating Commands::           Five major updating commands.
264 * Updating Requirements::       How to structure a Texinfo file for
265                                   using the updating command.
266 * Other Updating Commands::     How to indent descriptions, insert
267                                   missing nodes lines, and update
268                                   nodes in sequence.
269
270 Beginning a Texinfo File
271
272 * Four Parts::                  Four parts begin a Texinfo file.
273 * Sample Beginning::            Here is a sample beginning for a Texinfo file.
274 * Header::                      The very beginning of a Texinfo file.
275 * Info Summary and Permissions::  Summary and copying permissions for Info.
276 * Titlepage & Copyright Page::  Creating the title and copyright pages.
277 * The Top Node::                Creating the `Top' node and master menu.
278 * Software Copying Permissions::  Ensure that you and others continue to
279                                   have the right to use and share software.
280
281 The Texinfo File Header
282
283 * First Line::                  The first line of a Texinfo file.
284 * Start of Header::             Formatting a region requires this.
285 * setfilename::                 Tell Info the name of the Info file.
286 * settitle::                    Create a title for the printed work.
287 * setchapternewpage::           Start chapters on right-hand pages.
288 * paragraphindent::             An option to specify paragraph indentation.
289 * End of Header::               Formatting a region requires this.
290
291 The Title and Copyright Pages
292
293 * titlepage::                   Create a title for the printed document.
294 * titlefont center sp::         The @code{@@titlefont}, @code{@@center},
295                                   and @code{@@sp} commands.
296 * title subtitle author::       The @code{@@title}, @code{@@subtitle},
297                                   and @code{@@author} commands.
298 * Copyright & Permissions::     How to write the copyright notice and
299                                   include copying permissions.
300 * end titlepage::               Turn on page headings after the title and
301                                   copyright pages.
302 * headings on off::             An option for turning headings on and off
303                                   and double or single sided printing.
304
305 The `Top' Node and Master Menu
306
307 * Title of Top Node::           Sketch what the file is about.
308 * Master Menu Parts::           A master menu has three or more parts.
309
310 Ending a Texinfo File
311
312 * Printing Indices & Menus::    How to print an index in hardcopy and
313                                   generate index menus in Info.
314 * Contents::                    How to create a table of contents.
315 * File End::                    How to mark the end of a file.
316
317 Chapter Structuring
318
319 * Tree Structuring::            A manual is like an upside down tree @dots{}
320 * Structuring Command Types::   How to divide a manual into parts.
321 * makeinfo top::                The @code{@@top} command, part of the `Top' node.
322 * chapter::                     
323 * unnumbered & appendix::       
324 * majorheading & chapheading::  
325 * section::                     
326 * unnumberedsec appendixsec heading::  
327 * subsection::                  
328 * unnumberedsubsec appendixsubsec subheading::  
329 * subsubsection::               Commands for the lowest level sections.
330 * Raise/lower sections::        How to change commands' hierarchical level.
331
332 Nodes
333
334 * Two Paths::                   Different commands to structure
335                                   Info output and printed output.
336 * Node Menu Illustration::      A diagram, and sample nodes and menus.
337 * node::                        How to write a node, in detail.
338 * makeinfo Pointer Creation::   How to create node pointers with @code{makeinfo}.
339
340 The @code{@@node} Command
341
342 * Node Names::                  How to choose node and pointer names.
343 * Writing a Node::              How to write an @code{@@node} line.
344 * Node Line Tips::              Keep names short.
345 * Node Line Requirements::      Keep names unique, without @@-commands.
346 * First Node::                  How to write a `Top' node.
347 * makeinfo top command::        How to use the @code{@@top} command.
348 * Top Node Summary::            Write a brief description for readers.
349
350 Menus
351
352 * Menu Location::               Put a menu in a short node.
353 * Writing a Menu::              What is a menu?
354 * Menu Parts::                  A menu entry has three parts.
355 * Less Cluttered Menu Entry::   Two part menu entry.
356 * Menu Example::                Two and three part menu entries.
357 * Other Info Files::            How to refer to a different Info file.
358
359 Cross References
360
361 * References::                  What cross references are for.
362 * Cross Reference Commands::    A summary of the different commands.
363 * Cross Reference Parts::       A cross reference has several parts.
364 * xref::                        Begin a reference with `See' @dots{}
365 * Top Node Naming::             How to refer to the beginning of another file.
366 * ref::                         A reference for the last part of a sentence.
367 * pxref::                       How to write a parenthetical cross reference.
368 * inforef::                     How to refer to an Info-only file.
369 * uref::                        How to refer to a uniform resource locator.
370
371 @code{@@xref}
372
373 * Reference Syntax::            What a reference looks like and requires.
374 * One Argument::                @code{@@xref} with one argument.
375 * Two Arguments::               @code{@@xref} with two arguments.
376 * Three Arguments::             @code{@@xref} with three arguments.
377 * Four and Five Arguments::     @code{@@xref} with four and five arguments.
378
379 Marking Words and Phrases
380
381 * Indicating::                  How to indicate definitions, files, etc.
382 * Emphasis::                    How to emphasize text.
383
384 Indicating Definitions, Commands, etc.
385
386 * Useful Highlighting::         Highlighting provides useful information.
387 * code::                        How to indicate code.
388 * kbd::                         How to show keyboard input.
389 * key::                         How to specify keys.
390 * samp::                        How to show a literal sequence of characters.
391 * var::                         How to indicate a metasyntactic variable.
392 * file::                        How to indicate the name of a file.
393 * dfn::                         How to specify a definition.
394 * cite::                        How to refer to a book that is not in Info.
395 * url::                         How to indicate a world wide web reference.
396 * email::                       How to indicate an electronic mail address.
397
398 Emphasizing Text
399
400 * emph & strong::               How to emphasize text in Texinfo.
401 * Smallcaps::                   How to use the small caps font.
402 * Fonts::                       Various font commands for printed output.
403 * Customized Highlighting::     How to define highlighting commands.
404
405 Quotations and Examples
406
407 * Block Enclosing Commands::    Use different constructs for
408                                   different purposes.
409 * quotation::                   How to write a quotation.
410 * example::                     How to write an example in a fixed-width font.
411 * noindent::                    How to prevent paragraph indentation.
412 * Lisp Example::                How to illustrate Lisp code.
413 * smallexample & smalllisp::    Forms for the @code{@@smallbook} option.
414 * display::                     How to write an example in the current font.
415 * format::                      How to write an example that does not narrow
416                                   the margins.
417 * exdent::                      How to undo the indentation of a line.
418 * flushleft & flushright::      How to push text flushleft or flushright.
419 * cartouche::                   How to draw cartouches around examples.
420
421 Lists and Tables
422
423 * Introducing Lists::           Texinfo formats lists for you.
424 * itemize::                     How to construct a simple list.
425 * enumerate::                   How to construct a numbered list.
426 * Two-column Tables::           How to construct a two-column table.
427 * Multi-column Tables::         How to construct generalized tables.
428
429 Making a Two-column Table
430
431 * table::                       How to construct a two-column table.
432 * ftable vtable::               Automatic indexing for two-column tables.
433 * itemx::                       How to put more entries in the first column.
434
435 Multi-column Tables
436
437 * Multitable Column Widths::    Defining multitable column widths.
438 * Multitable Rows::             Defining multitable rows, with examples.
439
440 Creating Indices
441
442 * Index Entries::               Choose different words for index entries.
443 * Predefined Indices::          Use different indices for different kinds
444                                   of entry.
445 * Indexing Commands::           How to make an index entry.
446 * Combining Indices::           How to combine indices.
447 * New Indices::                 How to define your own indices.
448
449 Combining Indices
450
451 * syncodeindex::                How to merge two indices, using @code{@@code}
452                                   font for the merged-from index.
453 * synindex::                    How to merge two indices, using the
454                                   default font of the merged-to index.
455
456 Special Insertions
457
458 * Braces Atsigns::              How to insert braces, @samp{@@}.
459 * Inserting Space::             How to insert the right amount of space
460                                   within a sentence.
461 * Inserting Accents::           How to insert accents and special characters.
462 * Dots Bullets::                How to insert dots and bullets.
463 * TeX and copyright::           How to insert the @TeX{} logo
464                                   and the copyright symbol.
465 * pounds::                      How to insert the pounds currency symbol.
466 * minus::                       How to insert a minus sign.
467 * math::                        How to format a mathematical expression.
468 * Glyphs::                      How to indicate results of evaluation,
469                                   expansion of macros, errors, etc.
470 * Images::                      How to include graphics.
471
472 Inserting @@ and Braces
473
474 * Inserting An Atsign::         How to insert @samp{@@}.
475 * Inserting Braces::            How to insert @samp{@{} and @samp{@}}.
476
477 Inserting Space
478
479 * Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
480 * Ending a Sentence::           Sometimes it does.
481 * Multiple Spaces::             Inserting multiple spaces.
482 * dmn::                         How to format a dimension.
483
484 Inserting Ellipsis, Dots, and Bullets
485
486 * dots::                        How to insert dots @dots{}
487 * bullet::                      How to insert a bullet.
488
489 Inserting @TeX{} and the Copyright Symbol
490
491 * tex::                         How to insert the @TeX{} logo.
492 * copyright symbol::            How to use @code{@@copyright}@{@}.
493
494 Glyphs for Examples
495
496 * Glyphs Summary::              
497 * result::                      How to show the result of expression.
498 * expansion::                   How to indicate an expansion.
499 * Print Glyph::                 How to indicate printed output.
500 * Error Glyph::                 How to indicate an error message.
501 * Equivalence::                 How to indicate equivalence.
502 * Point Glyph::                 How to indicate the location of point.
503
504 Glyphs Summary
505
506 * result::                      
507 * expansion::                   
508 * Print Glyph::                 
509 * Error Glyph::                 
510 * Equivalence::                 
511 * Point Glyph::                 
512
513 Making and Preventing Breaks
514
515 * Break Commands::              Cause and prevent splits.
516 * Line Breaks::                 How to force a single line to use two lines.
517 * - and hyphenation::           How to tell TeX about hyphenation points.
518 * w::                           How to prevent unwanted line breaks.
519 * sp::                          How to insert blank lines.
520 * page::                        How to force the start of a new page.
521 * group::                       How to prevent unwanted page breaks.
522 * need::                        Another way to prevent unwanted page breaks.
523
524 Definition Commands
525
526 * Def Cmd Template::            How to structure a description using a
527                                   definition command.
528 * Optional Arguments::          How to handle optional and repeated arguments.
529 * deffnx::                      How to group two or more `first' lines.
530 * Def Cmds in Detail::          All the definition commands.
531 * Def Cmd Conventions::         Conventions for writing definitions.
532 * Sample Function Definition::  
533
534 The Definition Commands
535
536 * Functions Commands::          Commands for functions and similar entities.
537 * Variables Commands::          Commands for variables and similar entities.
538 * Typed Functions::             Commands for functions in typed languages.
539 * Typed Variables::             Commands for variables in typed languages.
540 * Abstract Objects::            Commands for object-oriented programming.
541 * Data Types::                  The definition command for data types.
542
543 Footnotes
544
545 * Footnote Commands::           How to write a footnote in Texinfo.
546 * Footnote Styles::             Controlling how footnotes appear in Info.
547
548 Conditionally Visible Text
549
550 * Conditional Commands::        Specifying text for HTML, Info, or @TeX{}.
551 * Conditional Not Commands::    Specifying text for not HTML, Info, or @TeX{}.
552 * Raw Formatter Commands::      Using raw @TeX{} or HTML commands.
553 * set clear value::             Designating which text to format (for
554                                   all output formats); and how to set a
555                                   flag to a string that you can insert.
556
557 @code{@@set}, @code{@@clear}, and @code{@@value}
558
559 * ifset ifclear::               Format a region if a flag is set.
560 * value::                       Replace a flag with a string.
561 * value Example::               An easy way to update edition information.
562
563 Macros: Defining New Texinfo Commands
564
565 * Defining Macros::             Both defining and undefining new commands.
566 * Invoking Macros::             Using a macro, once you've defined it.
567
568 Format and Print Hardcopy
569
570 * Use TeX::                     Use @TeX{} to format for hardcopy.
571 * Format with tex/texindex::    How to format in a shell.
572 * Format with texi2dvi::        A simpler way to use the shell.
573 * Print with lpr::              How to print.
574 * Within Emacs::                How to format and print from an Emacs shell.
575 * Texinfo Mode Printing::       How to format and print in Texinfo mode.
576 * Compile-Command::             How to print using Emacs's compile command.
577 * Requirements Summary::        @TeX{} formatting requirements summary.
578 * Preparing for TeX::           What you need to do to use @TeX{}.
579 * Overfull hboxes::             What are and what to do with overfull hboxes.
580 * smallbook::                   How to print small format books and manuals.
581 * A4 Paper::                    How to print on European A4 paper.
582 * Cropmarks and Magnification::  How to print marks to indicate the size
583                                 of pages and how to print scaled up output.
584
585 Creating an Info File
586
587 * makeinfo advantages::         @code{makeinfo} provides better error checking.
588 * Invoking makeinfo::           How to run @code{makeinfo} from a shell.
589 * makeinfo options::            Specify fill-column and other options.
590 * Pointer Validation::          How to check that pointers point somewhere.
591 * makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
592 * texinfo-format commands::     Two Info formatting commands written
593                                   in Emacs Lisp are an alternative
594                                   to @code{makeinfo}.
595 * Batch Formatting::            How to format for Info in Emacs Batch mode.
596 * Tag and Split Files::         How tagged and split files help Info
597                                   to run better.
598
599 Installing an Info File
600
601 * Directory file::              The top level menu for all Info files.
602 * New Info File::               Listing a new info file.
603 * Other Info Directories::      How to specify Info files that are
604                                   located in other directories.
605 * Installing Dir Entries::      How to specify what menu entry to add
606                                   to the Info directory.
607 * Invoking install-info::       @code{install-info} options.
608
609 Sample Permissions
610
611 * Inserting Permissions::       How to put permissions in your document.
612 * ifinfo Permissions::          Sample @samp{ifinfo} copying permissions.
613 * Titlepage Permissions::       Sample Titlepage copying permissions.
614
615 Include Files
616
617 * Using Include Files::         How to use the @code{@@include} command.
618 * texinfo-multiple-files-update::  How to create and update nodes and
619                                   menus when using included files.
620 * Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
621 * Sample Include File::         A sample outer file with included files
622                                   within it; and a sample included file.
623 * Include Files Evolution::     How use of the @code{@@include} command
624                                   has changed over time.
625
626 Page Headings
627
628 * Headings Introduced::         Conventions for using page headings.
629 * Heading Format::              Standard page heading formats.
630 * Heading Choice::              How to specify the type of page heading.
631 * Custom Headings::             How to create your own headings and footings.
632
633 Formatting Mistakes
634
635 * makeinfo Preferred::          @code{makeinfo} finds errors.
636 * Debugging with Info::         How to catch errors with Info formatting.
637 * Debugging with TeX::          How to catch errors with @TeX{} formatting.
638 * Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
639 * Using occur::                 How to list all lines containing a pattern.
640 * Running Info-Validate::       How to find badly referenced nodes.
641
642 Finding Badly Referenced Nodes
643
644 * Using Info-validate::         How to run @code{Info-validate}.
645 * Unsplit::                     How to create an unsplit file.
646 * Tagifying::                   How to tagify a file.
647 * Splitting::                   How to split a file manually.
648
649 How to Obtain @TeX{}
650
651 @c * New Texinfo Mode Commands::   The updating commands are especially useful.
652 @c * New Commands::                Many newly described @@-commands.
653 @end detailmenu
654 @end menu
655
656 @node Copying, Overview, Top, Top
657 @comment  node-name, next, previous,  up
658 @unnumbered Texinfo Copying Conditions
659 @cindex Copying conditions
660 @cindex Conditions for copying Texinfo
661
662 The programs currently being distributed that relate to Texinfo include
663 portions of GNU Emacs, plus other separate programs (including
664 @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
665 These programs are @dfn{free}; this means that everyone is free to use
666 them and free to redistribute them on a free basis.  The Texinfo-related
667 programs are not in the public domain; they are copyrighted and there
668 are restrictions on their distribution, but these restrictions are
669 designed to permit everything that a good cooperating citizen would want
670 to do.  What is not allowed is to try to prevent others from further
671 sharing any version of these programs that they might get from
672 you.@refill
673
674   Specifically, we want to make sure that you have the right to give
675 away copies of the programs that relate to Texinfo, that you receive
676 source code or else can get it if you want it, that you can change these
677 programs or use pieces of them in new free programs, and that you know
678 you can do these things.@refill
679
680   To make sure that everyone has such rights, we have to forbid you to
681 deprive anyone else of these rights.  For example, if you distribute
682 copies of the Texinfo related programs, you must give the recipients all
683 the rights that you have.  You must make sure that they, too, receive or
684 can get the source code.  And you must tell them their rights.@refill
685
686   Also, for our own protection, we must make certain that everyone finds
687 out that there is no warranty for the programs that relate to Texinfo.
688 If these programs are modified by someone else and passed on, we want
689 their recipients to know that what they have is not what we distributed,
690 so that any problems introduced by others will not reflect on our
691 reputation.@refill
692
693   The precise conditions of the licenses for the programs currently
694 being distributed that relate to Texinfo are found in the General Public
695 Licenses that accompany them.@refill
696
697 @node Overview, Texinfo Mode, Copying, Top
698 @comment  node-name,  next,  previous,  up
699 @chapter Overview of Texinfo
700 @cindex Overview of Texinfo
701 @cindex Texinfo overview
702
703 @dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is
704 pronounced like ``speck'', not ``hex''.  This odd pronunciation is
705 derived from, but is not the same as, the pronunciation of @TeX{}.  In
706 the word @TeX{}, the @samp{X} is actually the Greek letter ``chi''
707 rather than the English letter ``ex''.  Pronounce @TeX{} as if the
708 @samp{X} were the last sound in the name `Bach'; but pronounce Texinfo
709 as if the @samp{x} were a `k'.  Spell ``Texinfo'' with a capital ``T''
710 and write the other letters in lower case.}
711 is a documentation system that uses a single source file to produce both
712 on-line information and printed output.  This means that instead of
713 writing two different documents, one for the on-line help or other on-line
714 information and the other for a typeset manual or other printed work, you
715 need write only one document.  When the work is revised, you need revise
716 only one document.  (You can read the on-line information, known as an
717 @dfn{Info file}, with an Info documentation-reading program.)@refill
718
719 @menu
720 * Using Texinfo::               Create a conventional printed book
721                                   or an Info file.
722 * Info Files::                  What is an Info file?
723 * Printed Books::               Characteristics of a printed book or manual.
724 * Formatting Commands::         @@-commands are used for formatting.
725 * Conventions::                 General rules for writing a Texinfo file.
726 * Comments::                    How to write comments and mark regions that
727                                   the formatting commands will ignore.
728 * Minimum::                     What a Texinfo file must have.
729 * Six Parts::                   Usually, a Texinfo file has six parts.
730 * Short Sample::                A short sample Texinfo file.
731 * Acknowledgements::            
732 @end menu
733
734 @node Using Texinfo, Info Files, Overview, Overview
735 @ifinfo
736 @heading Using Texinfo
737 @end ifinfo
738
739 Using Texinfo, you can create a printed document with the normal
740 features of a book, including chapters, sections, cross references,
741 and indices.  From the same Texinfo source file, you can create a
742 menu-driven, on-line Info file with nodes, menus, cross references,
743 and indices.  You can, if you wish, make the chapters and sections of
744 the printed document correspond to the nodes of the on-line
745 information; and you use the same cross references and indices for
746 both the Info file and the printed work.  @cite{The GNU
747 Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill
748
749 To make a printed document, you process a Texinfo source file with the
750 @TeX{} typesetting program.  This creates a DVI file that you can
751 typeset and print as a book or report.  (Note that the Texinfo language
752 is completely different from @TeX{}'s usual language, plain @TeX{}.)  If
753 you do not have @TeX{}, but do have @code{troff} or @code{nroff}, you
754 can use the @code{texi2roff} program instead.@refill
755
756 To make an Info file, you process a Texinfo source file with the
757 @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command;
758 this creates an Info file that you can install on-line.@refill
759
760 @TeX{} and @code{texi2roff} work with many types of printers; similarly,
761 Info works with almost every type of computer terminal.  This power
762 makes Texinfo a general purpose system, but brings with it a constraint,
763 which is that a Texinfo file may contain only the customary
764 ``typewriter'' characters (letters, numbers, spaces, and punctuation
765 marks) but no special graphics.@refill
766
767 A Texinfo file is a plain @sc{ascii} file containing text and
768 @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
769 typesetting and formatting programs what to do.  You may edit a
770 Texinfo file with any text editor; but it is especially convenient to
771 use GNU Emacs since that editor has a special mode, called Texinfo
772 mode, that provides various Texinfo-related features.  (@xref{Texinfo
773 Mode}.)@refill
774
775 Before writing a Texinfo source file, you should become familiar with
776 the Info documentation reading program and learn about nodes,
777 menus, cross references, and the rest.  (@inforef{Top, info, info},
778 for more information.)@refill
779
780 You can use Texinfo to create both on-line help and printed manuals;
781 moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
782 is the format in which documentation for GNU utilities and libraries is
783 written.@refill
784
785 @node Info Files, Printed Books, Using Texinfo, Overview
786 @comment  node-name,  next,  previous,  up
787 @section Info files
788 @cindex Info files
789
790 An Info file is a Texinfo file formatted so that the Info documentation
791 reading program can operate on it.  (@code{makeinfo}
792 and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
793 into an Info file.)@refill
794
795 Info files are divided into pieces called @dfn{nodes}, each of which
796 contains the discussion of one topic.  Each node has a name, and
797 contains both text for the user to read and pointers to other nodes,
798 which are identified by their names.  The Info program displays one node
799 at a time, and provides commands with which the user can move to other
800 related nodes.@refill
801
802 @ifinfo
803 @inforef{Top, info, info}, for more information about using Info.@refill
804 @end ifinfo
805
806 Each node of an Info file may have any number of child nodes that
807 describe subtopics of the node's topic.  The names of child
808 nodes are listed in a @dfn{menu} within the parent node; this
809 allows you to use certain Info commands to move to one of the child
810 nodes.  Generally, an Info file is organized like a book.  If a node
811 is at the logical level of a chapter, its child nodes are at the level
812 of sections; likewise, the child nodes of sections are at the level
813 of subsections.@refill
814
815 All the children of any one parent are linked together in a
816 bidirectional chain of `Next' and `Previous' pointers.  The `Next'
817 pointer provides a link to the next section, and the `Previous' pointer
818 provides a link to the previous section.  This means that all the nodes
819 that are at the level of sections within a chapter are linked together.
820 Normally the order in this chain is the same as the order of the
821 children in the parent's menu.  Each child node records the parent node
822 name as its `Up' pointer.  The last child has no `Next' pointer, and the
823 first child has the parent both as its `Previous' and as its `Up'
824 pointer.@footnote{In some documents, the first child has no `Previous'
825 pointer.  Occasionally, the last child has the node name of the next
826 following higher level node as its `Next' pointer.}@refill
827
828 The book-like structuring of an Info file into nodes that correspond
829 to chapters, sections, and the like is a matter of convention, not a
830 requirement.  The `Up', `Previous', and `Next' pointers of a node can
831 point to any other nodes, and a menu can contain any other nodes.
832 Thus, the node structure can be any directed graph.  But it is usually
833 more comprehensible to follow a structure that corresponds to the
834 structure of chapters and sections in a printed book or report.@refill
835
836 In addition to menus and to `Next', `Previous', and `Up' pointers, Info
837 provides pointers of another kind, called references, that can be
838 sprinkled throughout the text.  This is usually the best way to
839 represent links that do not fit a hierarchical structure.@refill
840
841 Usually, you will design a document so that its nodes match the
842 structure of chapters and sections in the printed output.  But
843 occasionally there are times when this is not right for the material
844 being discussed.  Therefore, Texinfo uses separate commands to specify
845 the node structure for the Info file and the section structure for the
846 printed output.@refill
847
848 Generally, you enter an Info file through a node that by convention is
849 named `Top'.  This node normally contains just a brief summary of the
850 file's purpose, and a large menu through which the rest of the file is
851 reached.  From this node, you can either traverse the file
852 systematically by going from node to node, or you can go to a specific
853 node listed in the main menu, or you can search the index menus and then
854 go directly to the node that has the information you want.  Alternatively,
855 with the standalone Info program, you can specify specific menu items on
856 the command line (@pxref{Top,,, info, Info}).
857
858 If you want to read through an Info file in sequence, as if it were a
859 printed manual, you can hit @key{SPC} repeatedly, or you get the whole
860 file with the advanced Info command @kbd{g *}.  (@inforef{Expert,
861 Advanced Info commands, info}.)@refill
862
863 @c !!! dir file may be located in one of many places:
864 @c     /usr/local/emacs/info            mentioned in info.c DEFAULT_INFOPATH
865 @c     /usr/local/lib/emacs/info        mentioned in info.c DEFAULT_INFOPATH
866 @c     /usr/gnu/info                    mentioned in info.c DEFAULT_INFOPATH
867 @c     /usr/local/info
868 @c     /usr/local/lib/info
869 The @file{dir} file in the @file{info} directory serves as the
870 departure point for the whole Info system.  From it, you can reach the
871 `Top' nodes of each of the documents in a complete Info system.@refill
872
873 @node Printed Books, Formatting Commands, Info Files, Overview
874 @comment  node-name,  next,  previous,  up
875 @section Printed Books
876 @cindex Printed book and manual characteristics
877 @cindex Manual characteristics, printed
878 @cindex Book characteristics, printed
879 @cindex Texinfo printed book characteristics
880 @cindex Characteristics, printed books or manuals
881
882 @cindex Knuth, Donald
883 A Texinfo file can be formatted and typeset as a printed book or manual.
884 To do this, you need @TeX{}, a powerful, sophisticated typesetting
885 program written by Donald Knuth.@footnote{You can also use the
886 @code{texi2roff} program if you do not have @TeX{}; since Texinfo is
887 designed for use with @TeX{}, @code{texi2roff} is not described here.
888 @code{texi2roff} is not part of the standard GNU distribution.}
889
890 A Texinfo-based book is similar to any other typeset, printed work: it
891 can have a title page, copyright page, table of contents, and preface,
892 as well as chapters, numbered or unnumbered sections and subsections,
893 page headers, cross references, footnotes, and indices.@refill
894
895 You can use Texinfo to write a book without ever having the intention
896 of converting it into on-line information.  You can use Texinfo for
897 writing a printed novel, and even to write a printed memo, although
898 this latter application is not recommended since electronic mail is so
899 much easier.@refill
900
901 @TeX{} is a general purpose typesetting program.  Texinfo provides a
902 file called @file{texinfo.tex} that contains information (definitions or
903 @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
904 (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
905 to @TeX{} commands, which @TeX{} can then process to create the typeset
906 document.)  @file{texinfo.tex} contains the specifications for printing
907 a document.@refill
908
909 Most often, documents are printed on 8.5 inch by 11 inch
910 pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you
911 can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
912 235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper
913 (@code{@@afourpaper}).  (@xref{smallbook, , Printing ``Small'' Books}.
914 Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill
915
916 By changing the parameters in @file{texinfo.tex}, you can change the
917 size of the printed document.  In addition, you can change the style in
918 which the printed document is formatted; for example, you can change the
919 sizes and fonts used, the amount of indentation for each paragraph, the
920 degree to which words are hyphenated, and the like.  By changing the
921 specifications, you can make a book look dignified, old and serious, or
922 light-hearted, young and cheery.@refill
923
924 @TeX{} is freely distributable.  It is written in a superset of Pascal
925 called WEB and can be compiled either in Pascal or (by using a
926 conversion program that comes with the @TeX{} distribution) in C.
927 (@xref{TeX Mode, ,@TeX{} Mode, xemacs, XEmacs User's Manual}, for information
928 about @TeX{}.)@refill
929
930 @TeX{} is very powerful and has a great many features.  Because a
931 Texinfo file must be able to present information both on a
932 character-only terminal in Info form and in a typeset book, the
933 formatting commands that Texinfo supports are necessarily
934 limited.@refill
935
936 @xref{Obtaining TeX, , How to Obtain @TeX{}}.
937
938
939 @node Formatting Commands, Conventions, Printed Books, Overview
940 @comment  node-name,  next,  previous,  up
941 @section @@-commands
942 @cindex @@-commands
943 @cindex Formatting commands
944
945 In a Texinfo file, the commands that tell @TeX{} how to typeset the
946 printed manual and tell @code{makeinfo} and
947 @code{texinfo-format-buffer} how to create an Info file are preceded
948 by @samp{@@}; they are called @dfn{@@-commands}.  For example,
949 @code{@@node} is the command to indicate a node and @code{@@chapter}
950 is the command to indicate the start of a chapter.@refill
951
952 @quotation
953 @strong{Please note:} All the @@-commands, with the exception of the
954 @code{@@TeX@{@}} command, must be written entirely in lower
955 case.@refill
956 @end quotation
957
958 The Texinfo @@-commands are a strictly limited set of constructs.  The
959 strict limits make it possible for Texinfo files to be understood both
960 by @TeX{} and by the code that converts them into Info files.  You can
961 display Info files on any terminal that displays alphabetic and
962 numeric characters.  Similarly, you can print the output generated by
963 @TeX{} on a wide variety of printers.@refill
964
965 Depending on what they do or what arguments@footnote{The word
966 @dfn{argument} comes from the way it is used in mathematics and does
967 not refer to a disputation between two people; it refers to the
968 information presented to the command.  According to the @cite{Oxford
969 English Dictionary}, the word derives from the Latin for @dfn{to make
970 clear, prove}; thus it came to mean `the evidence offered as proof',
971 which is to say, `the information offered', which led to its
972 mathematical meaning.  In its other thread of derivation, the word
973 came to mean `to assert in a manner against which others may make
974 counter assertions', which led to the meaning of `argument' as a
975 disputation.} they take, you need to write @@-commands on lines of
976 their own or as part of sentences:@refill
977
978 @itemize @bullet
979 @item
980 Write a command such as @code{@@noindent} at the beginning of a line as
981 the only text on the line.  (@code{@@noindent} prevents the beginning of
982 the next line from being indented as the beginning of a
983 paragraph.)@refill
984
985 @item
986 Write a command such as @code{@@chapter} at the beginning of a line
987 followed by the command's arguments, in this case the chapter title, on
988 the rest of the line.  (@code{@@chapter} creates chapter titles.)@refill
989
990 @item
991 Write a command such as @code{@@dots@{@}} wherever you wish but usually
992 within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
993
994 @item
995 Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
996 wish (but usually within a sentence) with its argument,
997 @var{sample-code} in this example, between the braces.  (@code{@@code}
998 marks text as being code.)@refill
999
1000 @item
1001 Write a command such as @code{@@example} at the beginning of a line of
1002 its own; write the body-text on following lines; and write the matching
1003 @code{@@end} command, @code{@@end example} in this case, at the
1004 beginning of a line of its own after the body-text. (@code{@@example}
1005 @dots{} @code{@@end example} indents and typesets body-text as an
1006 example.)@refill
1007 @end itemize
1008
1009 @noindent
1010 @cindex Braces, when to use
1011 As a general rule, a command requires braces if it mingles among other
1012 text; but it does not need braces if it starts a line of its own.  The
1013 non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1014 they do not need braces.@refill
1015
1016 As you gain experience with Texinfo, you will rapidly learn how to
1017 write the different commands: the different ways to write commands
1018 make it easier to write and read Texinfo files than if all commands
1019 followed exactly the same syntax.  (For details about @@-command
1020 syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1021
1022 @node Conventions, Comments, Formatting Commands, Overview
1023 @comment  node-name,  next,  previous,  up
1024 @section General Syntactic Conventions
1025 @cindex General syntactic conventions
1026 @cindex Syntactic conventions
1027 @cindex Conventions, syntactic
1028
1029 All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1030 @samp{@}} can appear in a Texinfo file and stand for themselves.
1031 @samp{@@} is the escape character which introduces commands.
1032 @samp{@{} and @samp{@}} should be used only to surround arguments to
1033 certain commands.  To put one of these special characters into the
1034 document, put an @samp{@@} character in front of it, like this:
1035 @samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
1036
1037 @ifinfo
1038 It is customary in @TeX{} to use doubled single-quote characters to
1039 begin and end quotations: ` ` and ' ' (but without a space between the
1040 two single-quote characters).  This convention should be followed in
1041 Texinfo files.  @TeX{} converts doubled single-quote characters to
1042 left- and right-hand doubled quotation marks and Info converts doubled
1043 single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
1044 @end ifinfo
1045 @iftex
1046 It is customary in @TeX{} to use doubled single-quote characters to
1047 begin and end quotations: @w{@tt{ `` }} and @w{@tt{ '' }}.  This
1048 convention should be followed in Texinfo files.  @TeX{} converts
1049 doubled single-quote characters to left- and right-hand doubled
1050 quotation marks, ``like this'', and Info converts doubled single-quote
1051 characters to @sc{ascii} double-quotes: @w{@tt{ `` }} and
1052 @w{@tt{ '' }} to @w{@tt{ " }}.@refill
1053 @end iftex
1054
1055 Use three hyphens in a row, @samp{---}, for a dash---like this.  In
1056 @TeX{}, a single or double hyphen produces a printed dash that is
1057 shorter than the usual typeset dash. Info reduces three hyphens to two
1058 for display on the screen.
1059
1060 To prevent a paragraph from being indented in the printed manual, put
1061 the command @code{@@noindent} on a line by itself before the
1062 paragraph.@refill
1063
1064 If you mark off a region of the Texinfo file with the @code{@@iftex}
1065 and @w{@code{@@end iftex}} commands, that region will appear only in
1066 the printed copy; in that region, you can use certain commands
1067 borrowed from plain @TeX{} that you cannot use in Info.  Likewise, if
1068 you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
1069 commands, that region will appear only in the Info file; in that
1070 region, you can use Info commands that you cannot use in @TeX{}.
1071 Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
1072 @code{@@ifnothtml @dots{} @@end ifnothtml},
1073 @code{@@ifnotinfo @dots{} @@end ifnotinfo},
1074 @code{@@ifnottex @dots{} @@end ifnottex},
1075 @xref{Conditionals}.
1076
1077 @cindex Tabs; don't use!
1078 @quotation
1079 @strong{Caution:} Do not use tabs in a Texinfo file!  @TeX{} uses
1080 variable-width fonts, which means that it cannot predefine a tab to work
1081 in all circumstances.  Consequently, @TeX{} treats tabs like single
1082 spaces, and that is not what they look like.  Furthermore,
1083 @code{makeinfo} does nothing special with tabs, and thus a tab character
1084 in your input file may appear differently in the output.
1085
1086 @noindent
1087 To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1088 spaces when you press the @key{TAB} key.@refill
1089
1090 @noindent
1091 Also, you can run @code{untabify} in Emacs to convert tabs in a region
1092 to multiple spaces.@refill
1093
1094 @noindent
1095 Don't use tabs.
1096 @end quotation
1097
1098 @node Comments, Minimum, Conventions, Overview
1099 @comment  node-name,  next,  previous,  up
1100 @section Comments
1101
1102 You can write comments in a Texinfo file that will not appear in
1103 either the Info file or the printed manual by using the
1104 @code{@@comment} command (which may be abbreviated to @code{@@c}).
1105 Such comments are for the person who reads the Texinfo file.  All the
1106 text on a line that follows either @code{@@comment} or @code{@@c} is a
1107 comment; the rest of the line does not appear in either the Info file
1108 or the printed manual. (Often, you can write the @code{@@comment} or
1109 @code{@@c} in the middle of a line, and only the text that follows after
1110 the @code{@@comment} or @code{@@c} command does not appear; but some
1111 commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
1112 whole line.  You cannot use @code{@@comment} or @code{@@c} in a line
1113 beginning with such a command.)@refill
1114 @cindex Comments
1115 @findex comment
1116 @findex c @r{(comment)}
1117
1118 You can write long stretches of text that will not appear in either
1119 the Info file or the printed manual by using the @code{@@ignore} and
1120 @code{@@end ignore} commands.  Write each of these commands on a line
1121 of its own, starting each command at the beginning of the line.  Text
1122 between these two commands does not appear in the processed output.
1123 You can use @code{@@ignore} and @code{@@end ignore} for writing
1124 comments.  Often, @code{@@ignore} and @code{@@end ignore} is used
1125 to enclose a part of the copying permissions that applies to the
1126 Texinfo source file of a document, but not to the Info or printed
1127 version of the document.@refill
1128 @cindex Ignored text
1129 @cindex Unprocessed text
1130 @findex ignore
1131 @c !!! Perhaps include this comment about ignore and ifset:
1132 @ignore
1133 Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1134 @code{@@ifclear} conditions is ignored in the sense that it will not
1135 contribute to the formatted output.  However, TeX and makeinfo must
1136 still parse the ignored text, in order to understand when to
1137 @emph{stop} ignoring text from the source file; that means that you
1138 will still get error messages if you have invalid Texinfo markup
1139 within ignored text.
1140 @end ignore
1141
1142 @node Minimum, Six Parts, Comments, Overview
1143 @comment  node-name,  next,  previous,  up
1144 @section What a Texinfo File Must Have
1145 @cindex Minimal Texinfo file (requirements)
1146 @cindex Must have in Texinfo file
1147 @cindex Required in Texinfo file
1148 @cindex Texinfo file minimum
1149
1150 By convention, the names of Texinfo files end with one of the
1151 extensions @file{.texinfo}, @file{.texi}, or @file{.tex}.  The longer
1152 extension is preferred since it describes more clearly to a human
1153 reader the nature of the file.  The shorter extensions are for
1154 operating systems that cannot handle long file names.@refill
1155
1156 In order to be made into a printed manual and an Info file, a Texinfo
1157 file @strong{must} begin with lines like this:@refill
1158
1159 @example
1160 @group
1161 \input texinfo
1162 @@setfilename @var{info-file-name}
1163 @@settitle @var{name-of-manual}
1164 @end group
1165 @end example
1166
1167 @noindent
1168 The contents of the file follow this beginning, and then you @strong{must} end
1169 a Texinfo file with a line like this:@refill
1170
1171 @example
1172 @@bye
1173 @end example
1174
1175 @findex input @r{(@TeX{} command)}
1176 @noindent
1177 The @samp{\input texinfo} line tells @TeX{} to use the
1178 @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1179 @@-commands into @TeX{} typesetting commands.  (Note the use of the
1180 backslash, @samp{\}; this is correct for @TeX{}.)  The
1181 @samp{@@setfilename} line provides a name for the Info file and tells
1182 @TeX{} to open auxiliary files.  The @samp{@@settitle} line specifies a
1183 title for the page headers (or footers) of the printed manual.@refill
1184
1185 The @code{@@bye} line at the end of the file on a line of its own tells
1186 the formatters that the file is ended and to stop formatting.@refill
1187
1188 Usually, you will not use quite such a spare format, but will include
1189 mode setting and start-of-header and end-of-header lines at the
1190 beginning of a Texinfo file, like this:@refill
1191
1192 @example
1193 @group
1194 \input texinfo   @@c -*-texinfo-*-
1195 @@c %**start of header
1196 @@setfilename @var{info-file-name}
1197 @@settitle @var{name-of-manual}
1198 @@c %**end of header
1199 @end group
1200 @end example
1201
1202 @noindent
1203 In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1204 Texinfo mode when you edit the file.
1205
1206 The @code{@@c} lines which surround the @samp{@@setfilename} and
1207 @samp{@@settitle} lines are optional, but you need them in order to
1208 run @TeX{} or Info on just part of the file.  (@xref{Start of Header},
1209 for more information.)@refill
1210
1211 Furthermore, you will usually provide a Texinfo file with a title
1212 page, indices, and the like.  But the minimum, which can be useful
1213 for short documents, is just the three lines at the beginning and the
1214 one line at the end.@refill
1215
1216 @node Six Parts, Short Sample, Minimum, Overview
1217 @comment  node-name,  next,  previous,  up
1218 @section Six Parts of a Texinfo File
1219
1220 Generally, a Texinfo file contains more than the minimal
1221 beginning and end---it usually contains six parts:@refill
1222
1223 @table @r
1224 @item 1. Header
1225 The @dfn{Header} names the file, tells @TeX{} which definitions' file to
1226 use, and performs other ``housekeeping'' tasks.@refill
1227
1228 @item 2. Summary Description and Copyright
1229 The @dfn{Summary Description and Copyright} segment describes the document
1230 and contains the copyright notice and copying permissions for the Info
1231 file.  The segment must be enclosed between @code{@@ifinfo} and
1232 @code{@@end ifinfo} commands so that the formatters place it only in the Info
1233 file.@refill
1234
1235 @item 3. Title and Copyright
1236 The @dfn{Title and Copyright} segment contains the title and copyright pages
1237 and copying permissions for the printed manual.  The segment must be
1238 enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
1239 The title and copyright page appear only in the printed @w{manual}.@refill
1240
1241 @item 4. `Top' Node and Master Menu
1242 The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
1243 Info file.  It appears only in the Info file, in the `Top' node.@refill
1244
1245 @item 5. Body
1246 The @dfn{Body} of the document may be structured like a traditional book or
1247 encyclopedia or it may be free form.@refill
1248
1249 @item 6. End
1250 The @dfn{End} contains commands for printing indices and generating
1251 the table of contents, and the @code{@@bye} command on a line of its
1252 own.@refill
1253 @end table
1254
1255 @node Short Sample, Acknowledgements, Six Parts, Overview
1256 @comment  node-name,  next,  previous,  up
1257 @section A Short Sample Texinfo File
1258 @cindex Sample Texinfo file
1259
1260 Here is a complete but very short Texinfo file, in six parts.  The first
1261 three parts of the file, from @samp{\input texinfo} through to
1262 @samp{@@end titlepage}, look more intimidating than they are.  Most of
1263 the material is standard boilerplate; when you write a manual, simply
1264 insert the names for your own manual in this segment. (@xref{Beginning a
1265 File}.)@refill
1266
1267 @noindent
1268 In the following, the sample text is @emph{indented}; comments on it are
1269 not.  The complete file, without any comments, is shown in
1270 @ref{Sample Texinfo File}.
1271
1272 @subheading Part 1: Header
1273
1274 @noindent
1275 The header does not appear in either the Info file or the
1276 printed output.  It sets various parameters, including the
1277 name of the Info file and the title used in the header.
1278
1279 @example
1280 @group
1281 \input texinfo   @@c -*-texinfo-*-
1282 @@c %**start of header
1283 @@setfilename sample.info
1284 @@settitle Sample Document
1285 @@c %**end of header
1286
1287 @@setchapternewpage odd
1288 @end group
1289 @end example
1290
1291 @subheading Part 2: Summary Description and Copyright
1292
1293 @noindent
1294 The summary description and copyright segment does not
1295 appear in the printed document.
1296
1297 @example
1298 @group
1299 @@ifinfo
1300 This is a short example of a complete Texinfo file.
1301
1302 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
1303 @@end ifinfo
1304 @end group
1305 @end example
1306
1307 @subheading Part 3: Titlepage and Copyright
1308
1309 @noindent
1310 The titlepage segment does not appear in the Info file.
1311
1312 @example
1313 @group
1314 @@titlepage
1315 @@sp 10
1316 @@comment The title is printed in a large font.
1317 @@center @@titlefont@{Sample Title@}
1318 @end group
1319
1320 @group
1321 @@c The following two commands start the copyright page.
1322 @@page
1323 @@vskip 0pt plus 1filll
1324 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
1325 @@end titlepage
1326 @end group
1327 @end example
1328
1329 @subheading Part 4: `Top' Node and Master Menu
1330
1331 @noindent
1332 The `Top' node contains the master menu for the Info file.
1333 Since a printed manual uses a table of contents rather than
1334 a menu, the master menu appears only in the Info file.
1335
1336 @example
1337 @group
1338 @@node    Top,       First Chapter, ,         (dir)
1339 @@comment node-name, next,          previous, up
1340 @end group
1341 @end example
1342
1343 @example
1344 @group
1345 @@menu
1346 * First Chapter::    The first chapter is the
1347                      only chapter in this sample.
1348 * Concept Index::    This index has two entries.
1349 @@end menu
1350 @end group
1351 @end example
1352
1353 @subheading Part 5:  The Body of the Document
1354
1355 @noindent
1356 The body segment contains all the text of the document, but not the
1357 indices or table of contents.  This example illustrates a node and a
1358 chapter containing an enumerated list.@refill
1359
1360 @example
1361 @group
1362 @@node    First Chapter, Concept Index, Top,      Top
1363 @@comment node-name,     next,          previous, up
1364 @@chapter First Chapter
1365 @@cindex Sample index entry
1366 @end group
1367
1368 @group
1369 This is the contents of the first chapter.
1370 @@cindex Another sample index entry
1371 @end group
1372
1373 @group
1374 Here is a numbered list.
1375
1376 @@enumerate
1377 @@item
1378 This is the first item.
1379
1380 @@item
1381 This is the second item.
1382 @@end enumerate
1383 @end group
1384
1385 @group
1386 The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
1387 commands transform a Texinfo file such as this into
1388 an Info file; and @@TeX@{@} typesets it for a printed
1389 manual.
1390 @end group
1391 @end example
1392
1393 @subheading Part 6: The End of the Document
1394
1395 @noindent
1396 The end segment contains commands both for generating an index in a node
1397 and unnumbered chapter of its own and for generating the table of
1398 contents; and it contains the @code{@@bye} command that marks the end of
1399 the document.@refill
1400
1401 @example
1402 @group
1403 @@node    Concept Index,    ,  First Chapter, Top
1404 @@comment node-name,    next,  previous,      up
1405 @@unnumbered Concept Index
1406 @end group
1407
1408 @group
1409 @@printindex cp
1410
1411 @@contents
1412 @@bye
1413 @end group
1414 @end example
1415
1416 @subheading The Results
1417
1418 Here is what the contents of the first chapter of the sample look like:
1419
1420 @sp 1
1421 @need 700
1422 @quotation
1423 This is the contents of the first chapter.
1424
1425 Here is a numbered list.
1426
1427 @enumerate
1428 @item
1429 This is the first item.
1430
1431 @item
1432 This is the second item.
1433 @end enumerate
1434
1435 The @code{makeinfo} and @code{texinfo-format-buffer}
1436 commands transform a Texinfo file such as this into
1437 an Info file; and @TeX{} typesets it for a printed
1438 manual.
1439 @end quotation
1440
1441 @node Acknowledgements,  , Short Sample, Overview
1442 @comment  node-name,  next,  previous,  up
1443 @section Acknowledgements
1444
1445 @cindex Stallman, Richard M.
1446 @cindex Chassell, Robert J.
1447 @cindex Berry, Karl
1448 Richard M.@: Stallman wrote Edition 1.0 of this manual.  @w{Robert J.@:
1449 Chassell} revised and extended it, starting with Edition 1.1.  Karl
1450 Berry made updates for the Texinfo 3.8 and subsequent releases, starting
1451 with Edition 2.22.
1452
1453 @cindex Pinard, Fran@,{c}ois
1454 @cindex Zuhn, David D.
1455 @cindex Weisshaus, Melissa
1456 Our thanks go out to all who helped improve this work, particularly to
1457 Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
1458 reported mistakes and obscurities; our special thanks go to Melissa
1459 Weisshaus for her frequent and often tedious reviews of nearly similar
1460 editions.  Our mistakes are our own.
1461
1462 Please send suggestions and corrections to:
1463
1464 @example
1465 @group
1466 @r{Internet address:}
1467     bug-texinfo@@gnu.org
1468 @end group
1469 @end example
1470
1471 @noindent
1472 Please include the manual's edition number and update date in your messages.
1473
1474 @node Texinfo Mode, Beginning a File, Overview, Top
1475 @comment  node-name,  next,  previous,  up
1476 @chapter Using Texinfo Mode
1477 @cindex Texinfo mode
1478 @cindex Mode, using Texinfo
1479 @cindex GNU Emacs
1480 @cindex Emacs
1481
1482 You may edit a Texinfo file with any text editor you choose.  A Texinfo
1483 file is no different from any other @sc{ascii} file.  However, GNU Emacs
1484 comes with a special mode, called Texinfo
1485 mode, that provides  Emacs commands and tools to help ease your work.@refill
1486
1487 This chapter describes features of GNU Emacs' Texinfo mode but not any
1488 features of the Texinfo formatting language.  If you are reading this
1489 manual straight through from the beginning, you may want to skim through
1490 this chapter briefly and come back to it after reading succeeding
1491 chapters which describe the Texinfo formatting language in
1492 detail.@refill
1493
1494 @menu
1495 * Texinfo Mode Overview::       How Texinfo mode can help you.
1496 * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
1497                                   purpose editing features.
1498 * Inserting::                   How to insert frequently used @@-commands.
1499 * Showing the Structure::       How to show the structure of a file.
1500 * Updating Nodes and Menus::    How to update or create new nodes and menus.
1501 * Info Formatting::             How to format for Info.
1502 * Printing::                    How to format and print part or all of a file.
1503 * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
1504 @end menu
1505
1506 @node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
1507 @ifinfo
1508 @heading Texinfo Mode Overview
1509 @end ifinfo
1510
1511 Texinfo mode provides special features for working with Texinfo
1512 files:@refill
1513
1514 @itemize @bullet
1515 @item
1516 Insert frequently used @@-commands. @refill
1517
1518 @item
1519 Automatically create @code{@@node} lines.
1520
1521 @item
1522 Show the structure of a Texinfo source file.@refill
1523
1524 @item
1525 Automatically create or update the `Next',
1526 `Previous', and `Up' pointers of a node.
1527
1528 @item
1529 Automatically create or update menus.@refill
1530
1531 @item
1532 Automatically create a master menu.@refill
1533
1534 @item
1535 Format a part or all of a file for Info.@refill
1536
1537 @item
1538 Typeset and print part or all of a file.@refill
1539 @end itemize
1540
1541 Perhaps the two most helpful features are those for inserting frequently
1542 used @@-commands and for creating node pointers and menus.@refill
1543
1544 @node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
1545 @section The Usual GNU Emacs Editing Commands
1546
1547 In most cases, the usual Text mode commands work the same in Texinfo
1548 mode as they do in Text mode.  Texinfo mode adds new editing commands
1549 and tools to GNU Emacs' general purpose editing features.  The major
1550 difference concerns filling.  In Texinfo mode, the paragraph
1551 separation variable and syntax table are redefined so that Texinfo
1552 commands that should be on lines of their own are not inadvertently
1553 included in paragraphs.  Thus, the @kbd{M-q} (@code{fill-paragraph})
1554 command will refill a paragraph but not mix an indexing command on a
1555 line adjacent to it into the paragraph.@refill
1556
1557 In addition, Texinfo mode sets the @code{page-delimiter} variable to
1558 the value of @code{texinfo-chapter-level-regexp}; by default, this is
1559 a regular expression matching the commands for chapters and their
1560 equivalents, such as appendices.  With this value for the page
1561 delimiter, you can jump from chapter title to chapter title with the
1562 @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1563 (@code{backward-page}) commands and narrow to a chapter with the
1564 @kbd{C-x p} (@code{narrow-to-page}) command.  (@xref{Pages, , , xemacs,
1565 XEmacs User's Manual}, for details about the page commands.)@refill
1566
1567 You may name a Texinfo file however you wish, but the convention is to
1568 end a Texinfo file name with one of the three extensions
1569 @file{.texinfo}, @file{.texi}, or @file{.tex}.  A longer extension is
1570 preferred, since it is explicit, but a shorter extension may be
1571 necessary for operating systems that limit the length of file names.
1572 GNU Emacs automatically enters Texinfo mode when you visit a file with
1573 a @file{.texinfo} or  @file{.texi}
1574 extension.  Also, Emacs switches to Texinfo mode
1575 when you visit a
1576 file that has @samp{-*-texinfo-*-} in its first line.  If ever you are
1577 in another mode and wish to switch to Texinfo mode, type @code{M-x
1578 texinfo-mode}.@refill
1579
1580 Like all other Emacs features, you can customize or enhance Texinfo
1581 mode as you wish.  In particular, the keybindings are very easy to
1582 change.  The keybindings described here are the default or standard
1583 ones.@refill
1584
1585 @node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
1586 @comment  node-name,  next,  previous,  up
1587 @section Inserting Frequently Used Commands
1588 @cindex Inserting frequently used commands
1589 @cindex Frequently used commands, inserting
1590 @cindex Commands, inserting them
1591
1592 Texinfo mode provides commands to insert various frequently used
1593 @@-commands into the buffer.  You can use these commands to save
1594 keystrokes.@refill
1595
1596 The insert commands are invoked by typing @kbd{C-c} twice and then the
1597 first letter of the @@-command:@refill
1598
1599 @table @kbd
1600 @item  C-c C-c c
1601 @itemx M-x texinfo-insert-@@code
1602 @findex texinfo-insert-@@code
1603 Insert @code{@@code@{@}} and put the
1604 cursor between the braces.@refill
1605
1606 @item  C-c C-c d
1607 @itemx M-x texinfo-insert-@@dfn
1608 @findex texinfo-insert-@@dfn
1609 Insert @code{@@dfn@{@}} and put the
1610 cursor between the braces.@refill
1611
1612 @item  C-c C-c e
1613 @itemx M-x texinfo-insert-@@end
1614 @findex texinfo-insert-@@end
1615 Insert @code{@@end} and attempt to insert the correct following word,
1616 such as @samp{example} or @samp{table}.  (This command does not handle
1617 nested lists correctly, but inserts the word appropriate to the
1618 immediately preceding list.)@refill
1619
1620 @item  C-c C-c i
1621 @itemx M-x texinfo-insert-@@item
1622 @findex texinfo-insert-@@item
1623 Insert @code{@@item} and put the
1624 cursor at the beginning of the next line.@refill
1625
1626 @item  C-c C-c k
1627 @itemx M-x texinfo-insert-@@kbd
1628 @findex texinfo-insert-@@kbd
1629 Insert @code{@@kbd@{@}} and put the
1630 cursor between the braces.@refill
1631
1632 @item  C-c C-c n
1633 @itemx M-x texinfo-insert-@@node
1634 @findex texinfo-insert-@@node
1635 Insert @code{@@node} and a comment line
1636 listing the sequence for the `Next',
1637 `Previous', and `Up' nodes.
1638 Leave point after the @code{@@node}.@refill
1639
1640 @item  C-c C-c o
1641 @itemx M-x texinfo-insert-@@noindent
1642 @findex texinfo-insert-@@noindent
1643 Insert @code{@@noindent} and put the
1644 cursor at the beginning of the next line.@refill
1645
1646 @item  C-c C-c s
1647 @itemx M-x texinfo-insert-@@samp
1648 @findex texinfo-insert-@@samp
1649 Insert @code{@@samp@{@}} and put the
1650 cursor between the braces.@refill
1651
1652 @item  C-c C-c t
1653 @itemx M-x texinfo-insert-@@table
1654 @findex texinfo-insert-@@table
1655 Insert @code{@@table} followed by a @key{SPC}
1656 and leave the cursor after the @key{SPC}.@refill
1657
1658 @item  C-c C-c v
1659 @itemx M-x texinfo-insert-@@var
1660 @findex texinfo-insert-@@var
1661 Insert @code{@@var@{@}} and put the
1662 cursor between the braces.@refill
1663
1664 @item  C-c C-c x
1665 @itemx M-x texinfo-insert-@@example
1666 @findex texinfo-insert-@@example
1667 Insert @code{@@example} and put the
1668 cursor at the beginning of the next line.@refill
1669
1670 @c M-@{  was the binding for texinfo-insert-braces;
1671 @c in Emacs 19, backward-paragraph will take this binding.
1672 @item C-c C-c @{
1673 @itemx M-x texinfo-insert-braces
1674 @findex texinfo-insert-braces
1675 Insert @code{@{@}} and put the cursor between the braces.@refill
1676
1677 @item C-c C-c @}
1678 @itemx C-c C-c ]
1679 @itemx M-x up-list
1680 @findex up-list
1681 Move from between a pair of braces forward past the closing brace.
1682 Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
1683 is, however, more mnemonic; hence the two keybindings.  (Also, you can
1684 move out from between braces by typing @kbd{C-f}.)@refill
1685 @end table
1686
1687 To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1688 @emph{existing} word, position the cursor in front of the word and type
1689 @kbd{C-u 1 C-c C-c c}.  This makes it easy to edit existing plain text.
1690 The value of the prefix argument tells Emacs how many words following
1691 point to include between braces---@samp{1} for one word, @samp{2} for
1692 two words, and so on.  Use a negative argument to enclose the previous
1693 word or words.  If you do not specify a prefix argument, Emacs inserts
1694 the @@-command string and positions the cursor between the braces.  This
1695 feature works only for those @@-commands that operate on a word or words
1696 within one line, such as @code{@@kbd} and @code{@@var}.@refill
1697
1698 This set of insert commands was created after analyzing the frequency
1699 with which different @@-commands are used in the @cite{GNU Emacs
1700 Manual} and the @cite{GDB Manual}.  If you wish to add your own insert
1701 commands, you can bind a keyboard macro to a key, use abbreviations,
1702 or extend the code in @file{texinfo.el}.@refill
1703
1704 @findex texinfo-start-menu-description
1705 @cindex Menu description, start
1706 @cindex Description for menu, start
1707 @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1708 command that works differently from the other insert commands.  It
1709 inserts a node's section or chapter title in the space for the
1710 description in a menu entry line.  (A menu entry has three parts, the
1711 entry name, the node name, and the description.  Only the node name is
1712 required, but a description helps explain what the node is about.
1713 @xref{Menu Parts, , The Parts of a Menu}.)@refill
1714
1715 To use @code{texinfo-start-menu-description}, position point in a menu
1716 entry line and type @kbd{C-c C-c C-d}.  The command looks for and copies
1717 the title that goes with the node name, and inserts the title as a
1718 description; it positions point at beginning of the inserted text so you
1719 can edit it.  The function does not insert the title if the menu entry
1720 line already contains a description.@refill
1721
1722 This command is only an aid to writing descriptions; it does not do the
1723 whole job.  You must edit the inserted text since a title tends to use
1724 the same words as a node name but a useful description uses different
1725 words.@refill
1726
1727 @node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
1728 @comment  node-name,  next,  previous,  up
1729 @section Showing the Section Structure of a File
1730 @cindex Showing the section structure of a file
1731 @cindex Section structure of a file, showing it
1732 @cindex Structure of a file, showing it
1733 @cindex Outline of file structure, showing it
1734 @cindex Contents-like outline of file structure
1735 @cindex File section structure, showing it
1736 @cindex Texinfo file section structure, showing it
1737
1738 You can show the section structure of a Texinfo file by using the
1739 @kbd{C-c C-s} command (@code{texinfo-show-structure}).  This command
1740 shows the section structure of a Texinfo file by listing the lines
1741 that begin with the @@-commands for @code{@@chapter},
1742 @code{@@section}, and the like.  It constructs what amounts
1743 to a table of contents.  These lines are displayed in another buffer
1744 called the @samp{*Occur*} buffer.  In that buffer, you can position
1745 the cursor over one of the lines and use the @kbd{C-c C-c} command
1746 (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1747 in the Texinfo file.@refill
1748
1749 @table @kbd
1750 @item  C-c C-s
1751 @itemx M-x texinfo-show-structure
1752 @findex texinfo-show-structure
1753 Show the @code{@@chapter}, @code{@@section}, and such lines of a
1754 Texinfo file.@refill
1755
1756 @item  C-c C-c
1757 @itemx M-x occur-mode-goto-occurrence
1758 @findex occur-mode-goto-occurrence
1759 Go to the line in the Texinfo file corresponding to the line under the
1760 cursor in the @file{*Occur*} buffer.@refill
1761 @end table
1762
1763 If you call @code{texinfo-show-structure} with a prefix argument by
1764 typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1765 @@-commands for @code{@@chapter}, @code{@@section}, and the like,
1766 but also the @code{@@node} lines.  (This is how the
1767 @code{texinfo-show-structure} command worked without an argument in
1768 the first version of Texinfo.  It was changed because @code{@@node}
1769 lines clutter up the @samp{*Occur*} buffer and are usually not
1770 needed.)  You can use @code{texinfo-show-structure} with a prefix
1771 argument to check whether the `Next', `Previous', and `Up' pointers of
1772 an @code{@@node} line are correct.@refill
1773
1774 Often, when you are working on a manual, you will be interested only
1775 in the structure of the current chapter.  In this case, you can mark
1776 off the region of the buffer that you are interested in by using the
1777 @kbd{C-x n n} (@code{narrow-to-region}) command and
1778 @code{texinfo-show-structure} will work on only that region.  To see
1779 the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
1780 (@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more
1781 information about the narrowing commands.)@refill
1782
1783 @vindex page-delimiter
1784 @cindex Page delimiter in Texinfo mode
1785 In addition to providing the @code{texinfo-show-structure} command,
1786 Texinfo mode sets the value of the page delimiter variable to match
1787 the chapter-level @@-commands.  This enables you to use the @kbd{C-x
1788 ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
1789 commands to move forward and backward by chapter, and to use the
1790 @kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
1791 @xref{Pages, , , xemacs, XEmacs User's Manual}, for more information
1792 about the page commands.@refill
1793
1794 @node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
1795 @comment  node-name,  next,  previous,  up
1796 @section Updating Nodes and Menus
1797 @cindex Updating nodes and menus
1798 @cindex Create nodes, menus automatically
1799 @cindex Insert nodes, menus automatically
1800 @cindex Automatically insert nodes, menus
1801
1802 Texinfo mode provides commands for automatically creating or updating
1803 menus and node pointers.  The commands are called ``update'' commands
1804 because their most frequent use is for updating a Texinfo file after
1805 you have worked on it; but you can use them to insert the `Next',
1806 `Previous', and `Up' pointers into an @code{@@node} line that has none and to
1807 create menus in a file that has none.@refill
1808
1809 If you do not use the updating commands, you need to write menus and
1810 node pointers by hand, which is a tedious task.@refill
1811
1812 @menu
1813 * Updating Commands::           Five major updating commands.
1814 * Updating Requirements::       How to structure a Texinfo file for
1815                                   using the updating command.
1816 * Other Updating Commands::     How to indent descriptions, insert
1817                                   missing nodes lines, and update
1818                                   nodes in sequence.
1819 @end menu
1820
1821 @node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
1822 @ifinfo
1823 @subheading The Updating Commands
1824 @end ifinfo
1825
1826 You can use the updating commands@refill
1827
1828 @itemize @bullet
1829 @item
1830 to insert or update the `Next', `Previous', and `Up' pointers of a
1831 node,@refill
1832
1833 @item
1834 to insert or update the menu for a section, and@refill
1835
1836 @item
1837 to create a master menu for a Texinfo source file.@refill
1838 @end itemize
1839
1840 You can also use the commands to update all the nodes and menus in a
1841 region or in a whole Texinfo file.@refill
1842
1843 The updating commands work only with conventional Texinfo files, which
1844 are structured hierarchically like books.  In such files, a structuring
1845 command line must follow closely after each @code{@@node} line, except
1846 for the `Top' @code{@@node} line.  (A @dfn{structuring command line} is
1847 a line beginning with @code{@@chapter}, @code{@@section}, or other
1848 similar command.)
1849
1850 You can write the structuring command line on the line that follows
1851 immediately after an @code{@@node} line or else on the line that
1852 follows after a single @code{@@comment} line or a single
1853 @code{@@ifinfo} line.  You cannot interpose more than one line between
1854 the @code{@@node} line and the structuring command line; and you may
1855 interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
1856
1857 Commands which work on a whole buffer require that the `Top' node be
1858 followed by a node with an @code{@@chapter} or equivalent-level command.
1859 Note that the menu updating commands will not create a main or master
1860 menu for a Texinfo file that has only @code{@@chapter}-level nodes!  The
1861 menu updating commands only create menus @emph{within} nodes for lower level
1862 nodes.  To create a menu of chapters, you must provide a `Top'
1863 node.@refill
1864
1865 The menu updating commands remove menu entries that refer to other Info
1866 files since they do not refer to nodes within the current buffer.  This
1867 is a deficiency.  Rather than use menu entries, you can use cross
1868 references to refer to other Info files.  None of the updating commands
1869 affect cross references.@refill
1870
1871 Texinfo mode has five updating commands that are used most often: two
1872 are for updating the node pointers or menu of a single node (or a
1873 region); two are for updating every node pointer and menu in a file;
1874 and one, the @code{texinfo-master-menu} command, is for creating a
1875 master menu for a complete file, and optionally, for updating every
1876 node and menu in the whole Texinfo file.@refill
1877
1878 The @code{texinfo-master-menu} command is the primary command:@refill
1879
1880 @table @kbd
1881 @item C-c C-u m
1882 @itemx M-x texinfo-master-menu
1883 @findex texinfo-master-menu
1884 Create or update a master menu that includes all the other menus
1885 (incorporating the descriptions from pre-existing menus, if
1886 any).@refill
1887
1888 With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
1889 update all the nodes and all the regular menus in the buffer before
1890 constructing the master menu.  (@xref{The Top Node, , The Top Node and
1891 Master Menu}, for more about a master menu.)@refill
1892
1893 For @code{texinfo-master-menu} to work, the Texinfo file must have a
1894 `Top' node and at least one subsequent node.@refill
1895
1896 After extensively editing a Texinfo file, you can type the following:
1897
1898 @example
1899 C-u M-x texinfo-master-menu
1900 @exdent or
1901 C-u C-c C-u m
1902 @end example
1903
1904 @noindent
1905 This updates all the nodes and menus completely and all at once.@refill
1906 @end table
1907
1908 The other major updating commands do smaller jobs and are designed for
1909 the person  who updates nodes and menus as he or she writes a Texinfo
1910 file.@refill
1911
1912 @need 1000
1913 The commands are:@refill
1914
1915 @table @kbd
1916 @item C-c C-u C-n
1917 @itemx M-x texinfo-update-node
1918 @findex texinfo-update-node
1919 Insert the `Next', `Previous', and `Up' pointers for the node that point is
1920 within (i.e., for the @code{@@node} line preceding point).  If the
1921 @code{@@node} line has pre-existing `Next', `Previous', or `Up'
1922 pointers in it, the old pointers are removed and new ones inserted.
1923 With an argument (prefix argument, @kbd{C-u}, if interactive), this command
1924 updates all @code{@@node} lines in the region (which is the text
1925 between point and mark).@refill
1926
1927 @item C-c C-u C-m
1928 @itemx M-x texinfo-make-menu
1929 @findex texinfo-make-menu
1930 Create or update the menu in the node that point is within.
1931 With an argument (@kbd{C-u} as prefix argument, if
1932 interactive), the command makes or updates menus for the
1933 nodes which are either within or a part of the
1934 region.@refill
1935
1936 Whenever @code{texinfo-make-menu} updates an existing menu, the
1937 descriptions from that menu are incorporated into the new menu.  This
1938 is done by copying descriptions from the existing menu to the entries
1939 in the new menu that have the same node names.  If the node names are
1940 different, the descriptions are not copied to the new menu.@refill
1941
1942 @item C-c C-u C-e
1943 @itemx M-x texinfo-every-node-update
1944 @findex texinfo-every-node-update
1945 Insert or update the `Next', `Previous', and `Up' pointers for every
1946 node in the buffer.@refill
1947
1948 @item C-c C-u C-a
1949 @itemx M-x texinfo-all-menus-update
1950 @findex texinfo-all-menus-update
1951 Create or update all the menus in the buffer.  With an argument
1952 (@kbd{C-u} as prefix argument, if interactive), first insert
1953 or update all the node
1954 pointers before working on the menus.@refill
1955
1956 If a master menu exists, the @code{texinfo-all-menus-update} command
1957 updates it; but the command does not create a new master menu if none
1958 already exists.  (Use the @code{texinfo-master-menu} command for
1959 that.)@refill
1960
1961 When working on a document that does not merit a master menu, you can
1962 type the following:
1963
1964 @example
1965 C-u C-c C-u C-a
1966 @exdent or
1967 C-u M-x texinfo-all-menus-update
1968 @end example
1969
1970 @noindent
1971 This updates all the nodes and menus.@refill
1972 @end table
1973
1974 The @code{texinfo-column-for-description} variable specifies the
1975 column to which menu descriptions are indented.  By default, the value
1976 is 32 although it is often useful to reduce it to as low as 24.  You
1977 can set the variable with the @kbd{M-x edit-options} command
1978 (@pxref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's
1979 Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining, ,
1980 Examining and Setting Variables, xemacs, XEmacs User's Manual}).@refill
1981
1982 Also, the @code{texinfo-indent-menu-description} command may be used to
1983 indent existing menu descriptions to a specified column.  Finally, if
1984 you wish, you can use the @code{texinfo-insert-node-lines} command to
1985 insert missing @code{@@node} lines into a file.  (@xref{Other Updating
1986 Commands}, for more information.)@refill
1987
1988 @node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
1989 @comment  node-name,  next,  previous,  up
1990 @subsection Updating Requirements
1991 @cindex Updating requirements
1992 @cindex Requirements for updating commands
1993
1994 To use the updating commands, you must organize the Texinfo file
1995 hierarchically with chapters, sections, subsections, and the like.
1996 When you construct the hierarchy of the manual, do not `jump down'
1997 more than one level at a time: you can follow the `Top' node with a
1998 chapter, but not with a section; you can follow a chapter with a
1999 section, but not with a subsection.  However, you may `jump up' any
2000 number of levels at one time---for example, from a subsection to a
2001 chapter.@refill
2002
2003 Each @code{@@node} line, with the exception of the line for the `Top'
2004 node, must be followed by a line with a structuring command such as
2005 @code{@@chapter}, @code{@@section}, or
2006 @code{@@unnumberedsubsec}.@refill
2007
2008 Each @code{@@node} line/structuring-command line combination
2009 must look either like this:@refill
2010
2011 @example
2012 @group
2013 @@node     Comments,  Minimum, Conventions, Overview
2014 @@comment  node-name, next,    previous,    up
2015 @@section Comments
2016 @end group
2017 @end example
2018
2019 or like this (without the @code{@@comment} line):
2020
2021 @example
2022 @group
2023 @@node Comments, Minimum, Conventions, Overview
2024 @@section Comments
2025 @end group
2026 @end example
2027
2028 @noindent
2029 In this example, `Comments' is the name of both the node and the
2030 section.  The next node is called `Minimum' and the previous node is
2031 called `Conventions'.  The `Comments' section is within the `Overview'
2032 node, which is specified by the `Up' pointer.  (Instead of an
2033 @code{@@comment} line, you can write an @code{@@ifinfo} line.)@refill
2034
2035 If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2036 and be the first node in the file.@refill
2037
2038 The menu updating commands create a menu of sections within a chapter,
2039 a menu of subsections within a section, and so on.  This means that
2040 you must have a `Top' node if you want a menu of chapters.@refill
2041
2042 Incidentally, the @code{makeinfo} command will create an Info file for
2043 a hierarchically organized Texinfo file that lacks `Next', `Previous'
2044 and `Up' pointers.  Thus, if you can be sure that your Texinfo file
2045 will be formatted with @code{makeinfo}, you have no need for the
2046 `update node' commands.  (@xref{Create an Info File, , Creating an
2047 Info File}, for more information about @code{makeinfo}.)  However,
2048 both @code{makeinfo} and the @code{texinfo-format-@dots{}} commands
2049 require that you insert menus in the file.@refill
2050
2051 @node Other Updating Commands,  , Updating Requirements, Updating Nodes and Menus
2052 @comment  node-name,  next,  previous,  up
2053 @subsection Other Updating Commands
2054
2055 In addition to the five major updating commands, Texinfo mode
2056 possesses several less frequently used updating commands:@refill
2057
2058 @table @kbd
2059 @item M-x texinfo-insert-node-lines
2060 @findex texinfo-insert-node-lines
2061 Insert @code{@@node} lines before the @code{@@chapter},
2062 @code{@@section}, and other sectioning commands wherever they are
2063 missing throughout a region in a Texinfo file.@refill
2064
2065 With an argument (@kbd{C-u} as prefix argument, if interactive), the
2066 @code{texinfo-insert-node-lines} command not only inserts
2067 @code{@@node} lines but also inserts the chapter or section titles as
2068 the names of the corresponding nodes.  In addition, it inserts the
2069 titles as node names in pre-existing @code{@@node} lines that lack
2070 names.  Since node names should be more concise than section or
2071 chapter titles, you must manually edit node names so inserted.@refill
2072
2073 For example, the following marks a whole buffer as a region and inserts
2074 @code{@@node} lines and titles throughout:@refill
2075
2076 @example
2077 C-x h C-u M-x texinfo-insert-node-lines
2078 @end example
2079
2080 (Note that this command inserts titles as node names in @code{@@node}
2081 lines; the @code{texinfo-start-menu-description} command
2082 (@pxref{Inserting, Inserting Frequently Used Commands}) inserts titles
2083 as descriptions in menu entries, a different action.  However, in both
2084 cases, you need to edit the inserted text.)@refill
2085
2086 @item M-x texinfo-multiple-files-update
2087 @findex texinfo-multiple-files-update @r{(in brief)}
2088 Update nodes and menus in a document built from several separate files.
2089 With @kbd{C-u} as a prefix argument, create and insert a master menu in
2090 the outer file.  With a numeric prefix argument, such as @kbd{C-u 2}, first
2091 update all the menus and all the `Next', `Previous', and `Up' pointers
2092 of all the included files before creating and inserting a master menu in
2093 the outer file.  The @code{texinfo-multiple-files-update} command is
2094 described in the appendix on @code{@@include} files.
2095 @ifinfo
2096 @xref{texinfo-multiple-files-update}.@refill
2097 @end ifinfo
2098 @iftex
2099 @xref{texinfo-multiple-files-update, ,
2100 @code{texinfo-multiple-files-update}}.@refill
2101 @end iftex
2102
2103 @item M-x texinfo-indent-menu-description
2104 @findex texinfo-indent-menu-description
2105 Indent every description in the menu following point to the specified
2106 column.  You can use this command to give yourself more space for
2107 descriptions.  With an argument (@kbd{C-u} as prefix argument, if
2108 interactive), the @code{texinfo-indent-menu-description} command indents
2109 every description in every menu in the region.  However, this command
2110 does not indent the second and subsequent lines of a multi-line
2111 description.@refill
2112
2113 @item M-x texinfo-sequential-node-update
2114 @findex texinfo-sequential-node-update
2115 Insert the names of the nodes immediately following and preceding the
2116 current node as the `Next' or `Previous' pointers regardless of those
2117 nodes' hierarchical level.  This means that the `Next' node of a
2118 subsection may well be the next chapter.  Sequentially ordered nodes are
2119 useful for novels and other documents that you read through
2120 sequentially.  (However, in Info, the @kbd{g *} command lets
2121 you look through the file sequentially, so sequentially ordered nodes
2122 are not strictly necessary.)  With an argument (prefix argument, if
2123 interactive), the @code{texinfo-sequential-node-update} command
2124 sequentially updates all the nodes in the region.@refill
2125 @end table
2126
2127 @node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
2128 @comment  node-name,  next,  previous,  up
2129 @section Formatting for Info
2130 @cindex Formatting for Info
2131 @cindex Running an Info formatter
2132 @cindex Info formatting
2133
2134 Texinfo mode provides several commands for formatting part or all of a
2135 Texinfo file for Info.  Often, when you are writing a document, you
2136 want to format only part of a file---that is, a region.@refill
2137
2138 You can use either the @code{texinfo-format-region} or the
2139 @code{makeinfo-region} command to format a region:@refill
2140
2141 @table @kbd
2142 @findex texinfo-format-region
2143 @item  C-c C-e C-r
2144 @itemx M-x texinfo-format-region
2145 @itemx C-c C-m C-r
2146 @itemx M-x makeinfo-region
2147 Format the current region for Info.@refill
2148 @end table
2149
2150 You can use either the @code{texinfo-format-buffer} or the
2151 @code{makeinfo-buffer} command to format a whole buffer:@refill
2152
2153 @table @kbd
2154 @findex texinfo-format-buffer
2155 @item  C-c C-e C-b
2156 @itemx M-x texinfo-format-buffer
2157 @itemx C-c C-m C-b
2158 @itemx M-x makeinfo-buffer
2159 Format the current buffer for Info.@refill
2160 @end table
2161
2162 @need 1000
2163 For example, after writing a Texinfo file, you can type the following:
2164
2165 @example
2166 C-u C-c C-u m
2167 @exdent or
2168 C-u M-x texinfo-master-menu
2169 @end example
2170
2171 @noindent
2172 This updates all the nodes and menus.  Then type the following to create
2173 an Info file:
2174
2175 @example
2176 C-c C-m C-b
2177 @exdent or
2178 M-x makeinfo-buffer
2179 @end example
2180
2181 For @TeX{} or the Info formatting commands to work, the file @emph{must}
2182 include a line that has @code{@@setfilename} in its header.@refill
2183
2184 @xref{Create an Info File}, for details about Info formatting.@refill
2185
2186 @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2187 @comment node-name,  next,  previous,  up
2188 @section Formatting and Printing
2189 @cindex Formatting for printing
2190 @cindex Printing a region or buffer
2191 @cindex Region formatting and printing
2192 @cindex Buffer formatting and printing
2193 @cindex Part of file formatting and printing
2194
2195 Typesetting and printing a Texinfo file is a multi-step process in which
2196 you first create a file for printing (called a DVI file), and then
2197 print the file.  Optionally, you may also create indices.  To do this,
2198 you must run the @code{texindex} command after first running the
2199 @code{tex} typesetting command; and then you must run the @code{tex}
2200 command again.  Or else run the @code{texi2dvi} command which
2201 automatically creates indices as needed (@pxref{Format with texi2dvi}).
2202
2203 Often, when you are writing a document, you want to typeset and print
2204 only part of a file to see what it will look like.  You can use the
2205 @code{texinfo-tex-region} and related commands for this purpose.  Use
2206 the @code{texinfo-tex-buffer} command to format all of a
2207 buffer.@refill
2208
2209 @table @kbd
2210 @item  C-c C-t C-b
2211 @itemx M-x texinfo-tex-buffer
2212 @findex texinfo-tex-buffer
2213 Run @code{texi2dvi} on the buffer.  In addition to running @TeX{} on the
2214 buffer, this command automatically creates or updates indices as
2215 needed.@refill
2216
2217 @item  C-c C-t C-r
2218 @itemx M-x texinfo-tex-region
2219 @findex texinfo-tex-region
2220 Run @TeX{} on the region.@refill
2221
2222 @item C-c C-t C-i
2223 @itemx M-x texinfo-texindex
2224 Run @code{texindex} to sort the indices of a Texinfo file formatted with
2225 @code{texinfo-tex-region}.  The @code{texinfo-tex-region} command does
2226 not run @code{texindex} automatically; it only runs the @code{tex}
2227 typesetting command.  You must run the @code{texinfo-tex-region} command
2228 a second time after sorting the raw index files with the @code{texindex}
2229 command.  (Usually, you do not format an index when you format a region,
2230 only when you format a buffer.  Now that the @code{texi2dvi} command
2231 exists, there is little or no need for this command.)@refill
2232
2233 @item C-c C-t C-p
2234 @itemx M-x texinfo-tex-print
2235 @findex texinfo-tex-print
2236 Print the file (or the part of the file) previously formatted with
2237 @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2238 @end table
2239
2240 For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2241 file @emph{must} start with a @samp{\input texinfo} line and must
2242 include an @code{@@settitle} line.  The file must end with @code{@@bye}
2243 on a line by itself.  (When you use @code{texinfo-tex-region}, you must
2244 surround the @code{@@settitle} line with start-of-header and
2245 end-of-header lines.)@refill
2246
2247 @xref{Format/Print Hardcopy}, for a description of the other @TeX{} related
2248 commands, such as @code{tex-show-print-queue}.@refill
2249
2250 @node Texinfo Mode Summary,  , Printing, Texinfo Mode
2251 @comment  node-name,  next,  previous,  up
2252 @section Texinfo Mode Summary
2253
2254 In Texinfo mode, each set of commands has default keybindings that
2255 begin with the same keys.  All the commands that are custom-created
2256 for Texinfo mode begin with @kbd{C-c}.  The keys are somewhat
2257 mnemonic.@refill
2258
2259 @subheading Insert Commands
2260
2261 The insert commands are invoked by typing @kbd{C-c} twice and then the
2262 first letter of the @@-command to be inserted.  (It might make more
2263 sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2264 @kbd{C-c C-c} is quick to type.)@refill
2265
2266 @example
2267 C-c C-c c       @r{Insert} @samp{@@code}.
2268 C-c C-c d       @r{Insert} @samp{@@dfn}.
2269 C-c C-c e       @r{Insert} @samp{@@end}.
2270 C-c C-c i       @r{Insert} @samp{@@item}.
2271 C-c C-c n       @r{Insert} @samp{@@node}.
2272 C-c C-c s       @r{Insert} @samp{@@samp}.
2273 C-c C-c v       @r{Insert} @samp{@@var}.
2274 C-c C-c @{       @r{Insert braces.}
2275 C-c C-c ]
2276 C-c C-c @}       @r{Move out of enclosing braces.}
2277
2278 @group
2279 C-c C-c C-d     @r{Insert a node's section title}
2280                 @r{in the space for the description}
2281                 @r{in a menu entry line.}
2282 @end group
2283 @end example
2284
2285 @subheading Show Structure
2286
2287 The @code{texinfo-show-structure} command is often used within a
2288 narrowed region.@refill
2289
2290 @example
2291 C-c C-s         @r{List all the headings.}
2292 @end example
2293
2294 @subheading The Master Update Command
2295
2296 The @code{texinfo-master-menu} command creates a master menu; and can
2297 be used to update every node and menu in a file as well.@refill
2298
2299 @example
2300 @group
2301 C-c C-u m
2302 M-x texinfo-master-menu
2303                 @r{Create or update a master menu.}
2304 @end group
2305
2306 @group
2307 C-u C-c C-u m   @r{With @kbd{C-u} as a prefix argument, first}
2308                 @r{create or update all nodes and regular}
2309                 @r{menus, and then create a master menu.}
2310 @end group
2311 @end example
2312
2313 @subheading Update Pointers
2314
2315 The update pointer commands are invoked by typing @kbd{C-c C-u} and
2316 then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2317 @code{texinfo-every-node-update}.@refill
2318
2319 @example
2320 C-c C-u C-n     @r{Update a node.}
2321 C-c C-u C-e     @r{Update every node in the buffer.}
2322 @end example
2323
2324 @subheading Update Menus
2325
2326 Invoke the  update menu commands by typing @kbd{C-c C-u}
2327 and then either @kbd{C-m} for @code{texinfo-make-menu} or
2328 @kbd{C-a} for @code{texinfo-all-menus-update}.  To update
2329 both nodes and menus at the same time, precede @kbd{C-c C-u
2330 C-a} with @kbd{C-u}.@refill
2331
2332 @example
2333 C-c C-u C-m     @r{Make or update a menu.}
2334
2335 @group
2336 C-c C-u C-a     @r{Make or update all}
2337                 @r{menus in a buffer.}
2338 @end group
2339
2340 @group
2341 C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2342                 @r{first create or update all nodes and}
2343                 @r{then create or update all menus.}
2344 @end group
2345 @end example
2346
2347 @subheading Format for Info
2348
2349 The Info formatting commands that are written in Emacs Lisp are
2350 invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2351 or @kbd{C-b} for the whole buffer.@refill
2352
2353 The Info formatting commands that are written in C and based on the
2354 @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2355 either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2356
2357 @need 800
2358 @noindent
2359 Use the @code{texinfo-format@dots{}} commands:
2360
2361 @example
2362 @group
2363 C-c C-e C-r     @r{Format the region.}
2364 C-c C-e C-b     @r{Format the buffer.}
2365 @end group
2366 @end example
2367
2368 @need 750
2369 @noindent
2370 Use @code{makeinfo}:
2371
2372 @example
2373 C-c C-m C-r     @r{Format the region.}
2374 C-c C-m C-b     @r{Format the buffer.}
2375 C-c C-m C-l     @r{Recenter the @code{makeinfo} output buffer.}
2376 C-c C-m C-k     @r{Kill the @code{makeinfo} formatting job.}
2377 @end example
2378
2379 @subheading Typeset and Print
2380
2381 The @TeX{} typesetting and printing commands are invoked by typing
2382 @kbd{C-c C-t} and then another control command: @kbd{C-r} for
2383 @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2384 and so on.@refill
2385
2386 @example
2387 C-c C-t C-r     @r{Run @TeX{} on the region.}
2388 C-c C-t C-b     @r{Run} @code{texi2dvi} @r{on the buffer.}
2389 C-c C-t C-i     @r{Run} @code{texindex}.
2390 C-c C-t C-p     @r{Print the DVI file.}
2391 C-c C-t C-q     @r{Show the print queue.}
2392 C-c C-t C-d     @r{Delete a job from the print queue.}
2393 C-c C-t C-k     @r{Kill the current @TeX{} formatting job.}
2394 C-c C-t C-x     @r{Quit a currently stopped @TeX{} formatting job.}
2395 C-c C-t C-l     @r{Recenter the output buffer.}
2396 @end example
2397
2398 @subheading Other Updating Commands
2399
2400 The `other updating commands' do not have standard keybindings because
2401 they are rarely used.
2402
2403 @example
2404 @group
2405 M-x texinfo-insert-node-lines
2406                 @r{Insert missing @code{@@node} lines in region.}
2407                 @r{With @kbd{C-u} as a prefix argument,}
2408                 @r{use section titles as node names.}
2409 @end group
2410
2411 @group
2412 M-x texinfo-multiple-files-update
2413                 @r{Update a multi-file document.}
2414                 @r{With @kbd{C-u 2} as a prefix argument,}
2415                 @r{create or update all nodes and menus}
2416                 @r{in all included files first.}
2417 @end group
2418
2419 @group
2420 M-x texinfo-indent-menu-description
2421                 @r{Indent descriptions.}
2422 @end group
2423
2424 @group
2425 M-x texinfo-sequential-node-update
2426                 @r{Insert node pointers in strict sequence.}
2427 @end group
2428 @end example
2429
2430 @node Beginning a File, Ending a File, Texinfo Mode, Top
2431 @comment  node-name,  next,  previous,  up
2432 @chapter Beginning a Texinfo File
2433 @cindex Beginning a Texinfo file
2434 @cindex Texinfo file beginning
2435 @cindex File beginning
2436
2437 Certain pieces of information must be provided at the beginning of a
2438 Texinfo file, such as the name of the file and the title of the
2439 document.@refill
2440
2441 @menu
2442 * Four Parts::                  Four parts begin a Texinfo file.
2443 * Sample Beginning::            Here is a sample beginning for a Texinfo file.
2444 * Header::                      The very beginning of a Texinfo file.
2445 * Info Summary and Permissions::  Summary and copying permissions for Info.
2446 * Titlepage & Copyright Page::  Creating the title and copyright pages.
2447 * The Top Node::                Creating the `Top' node and master menu.
2448 * Software Copying Permissions::  Ensure that you and others continue to
2449                                   have the right to use and share software.
2450 @end menu
2451
2452 @node Four Parts, Sample Beginning, Beginning a File, Beginning a File
2453 @ifinfo
2454 @heading Four Parts Begin a File
2455 @end ifinfo
2456
2457 Generally, the beginning of a Texinfo file has four parts:@refill
2458
2459 @enumerate
2460 @item
2461 The header, delimited by special comment lines, that includes the
2462 commands for naming the Texinfo file and telling @TeX{} what
2463 definitions file to use when processing the Texinfo file.@refill
2464
2465 @item
2466 A short statement of what the file is about, with a copyright notice
2467 and copying permissions.  This is enclosed in @code{@@ifinfo} and
2468 @code{@@end ifinfo} commands so that the formatters place it only
2469 in the Info file.@refill
2470
2471 @item
2472 A title page and copyright page, with a copyright notice and copying
2473 permissions.  This is enclosed between @code{@@titlepage} and
2474 @code{@@end titlepage} commands.  The title and copyright page appear
2475 only in the printed @w{manual}.@refill
2476
2477 @item
2478 The `Top' node that contains a menu for the whole Info file.  The
2479 contents of this node appear only in the Info file.@refill
2480 @end enumerate
2481
2482 Also, optionally, you may include the copying conditions for a program
2483 and a warranty disclaimer.  The copying section will be followed by an
2484 introduction or else by the first chapter of the manual.@refill
2485
2486 Since the copyright notice and copying permissions for the Texinfo
2487 document (in contrast to the copying permissions for a program) are in
2488 parts that appear only in the Info file or only in the printed manual,
2489 this information must be given twice.@refill
2490
2491 @node Sample Beginning, Header, Four Parts, Beginning a File
2492 @comment  node-name,  next,  previous,  up
2493 @section Sample Texinfo File Beginning
2494
2495 The following sample shows what is needed.@refill
2496
2497 @example
2498 \input texinfo   @@c -*-texinfo-*-
2499 @@c %**start of header
2500 @@setfilename @var{name-of-info-file}
2501 @@settitle @var{name-of-manual}
2502 @@setchapternewpage odd
2503 @@c %**end of header
2504
2505 @@ifinfo
2506 This file documents @dots{}
2507
2508 Copyright @var{year} @var{copyright-owner}
2509
2510 @group
2511 Permission is granted to @dots{}
2512 @@end ifinfo
2513 @end group
2514
2515 @group
2516 @@c  This title page illustrates only one of the
2517 @@c  two methods of forming a title page.
2518 @end group
2519
2520 @group
2521 @@titlepage
2522 @@title @var{name-of-manual-when-printed}
2523 @@subtitle @var{subtitle-if-any}
2524 @@subtitle @var{second-subtitle}
2525 @@author @var{author}
2526 @end group
2527
2528 @group
2529 @@c  The following two commands
2530 @@c  start the copyright page.
2531 @@page
2532 @@vskip 0pt plus 1filll
2533 Copyright @@copyright@{@} @var{year} @var{copyright-owner}
2534 @end group
2535
2536 Published by @dots{}
2537
2538 Permission is granted to @dots{}
2539 @@end titlepage
2540
2541 @@node Top, Overview, , (dir)
2542
2543 @@ifinfo
2544 This document describes @dots{}
2545
2546 This document applies to version @dots{}
2547 of the program named @dots{}
2548 @@end ifinfo
2549
2550 @group
2551 @@menu
2552 * Copying::          Your rights and freedoms.
2553 * First Chapter::    Getting started @dots{}
2554 * Second Chapter::              @dots{}
2555   @dots{}
2556   @dots{}
2557 @@end menu
2558 @end group
2559
2560 @group
2561 @@node    First Chapter, Second Chapter, top,      top
2562 @@comment node-name,     next,           previous, up
2563 @@chapter First Chapter
2564 @@cindex Index entry for First Chapter
2565 @end group
2566 @end example
2567
2568 @node Header, Info Summary and Permissions, Sample Beginning, Beginning a File
2569 @comment  node-name,  next,  previous,  up
2570 @section The Texinfo File Header
2571 @cindex Header for Texinfo files
2572 @cindex Texinfo file header
2573
2574 Texinfo files start with at least three lines that provide Info and
2575 @TeX{} with necessary information.  These are the @code{\input
2576 texinfo} line, the @code{@@settitle} line, and the
2577 @code{@@setfilename} line.  If you want to run @TeX{} on just a part
2578 of the Texinfo File, you must write the @code{@@settitle}
2579 and @code{@@setfilename} lines between start-of-header and end-of-header
2580 lines.@refill
2581
2582 Thus, the beginning of a Texinfo file looks like this:
2583
2584 @example
2585 @group
2586 \input texinfo   @@c -*-texinfo-*-
2587 @@setfilename sample.info
2588 @@settitle Sample Document
2589 @end group
2590 @end example
2591
2592 @noindent
2593 or else like this:
2594
2595 @example
2596 @group
2597 \input texinfo   @@c -*-texinfo-*-
2598 @@c %**start of header
2599 @@setfilename sample.info
2600 @@settitle Sample Document
2601 @@c %**end of header
2602 @end group
2603 @end example
2604
2605 @menu
2606 * First Line::                  The first line of a Texinfo file.
2607 * Start of Header::             Formatting a region requires this.
2608 * setfilename::                 Tell Info the name of the Info file.
2609 * settitle::                    Create a title for the printed work.
2610 * setchapternewpage::           Start chapters on right-hand pages.
2611 * paragraphindent::             An option to specify paragraph indentation.
2612 * End of Header::               Formatting a region requires this.
2613 @end menu
2614
2615 @node First Line, Start of Header, Header, Header
2616 @comment  node-name,  next,  previous,  up
2617 @subsection The First Line of a Texinfo File
2618 @cindex First line of a Texinfo file
2619 @cindex Beginning line of a Texinfo file
2620 @cindex Header of a Texinfo file
2621
2622 Every Texinfo file that is to be the top-level input to @TeX{} must begin
2623 with a line that looks like this:@refill
2624
2625 @example
2626 \input texinfo   @@c -*-texinfo-*-
2627 @end example
2628
2629 @noindent
2630 This line serves two functions:
2631
2632 @enumerate
2633 @item
2634 When the file is processed by @TeX{}, the @samp{\input texinfo} command
2635 tells @TeX{} to load the macros needed for processing a Texinfo file.
2636 These are in a file called @file{texinfo.tex}, which is usually located
2637 in the @file{/usr/lib/tex/macros} directory.  @TeX{} uses the backslash,
2638 @samp{\}, to mark the beginning of a command, just as Texinfo uses
2639 @samp{@@}.  The @file{texinfo.tex} file causes the switch from @samp{\}
2640 to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
2641 is why it appears at the beginning of the file.@refill
2642
2643 @item
2644 When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2645 specification tells Emacs to use Texinfo mode.@refill
2646 @end enumerate
2647
2648 @node Start of Header, setfilename, First Line, Header
2649 @comment  node-name,  next,  previous,  up
2650 @subsection Start of Header
2651 @cindex Start of header line
2652
2653 Write a start-of-header line on the second line of a Texinfo file.
2654 Follow the start-of-header line with @code{@@setfilename} and
2655 @code{@@settitle} lines and, optionally, with other command lines, such
2656 as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
2657 end-of-header line (@pxref{End of Header}).@refill
2658
2659 With these lines, you can format part of a Texinfo file for Info or
2660 typeset part for printing.@refill
2661
2662 A start-of-header line looks like this:@refill
2663
2664 @example
2665 @@c %**start of header
2666 @end example
2667
2668 The odd string of characters, @samp{%**}, is to ensure that no other
2669 comment is accidentally taken for a start-of-header line.@refill
2670
2671 @node setfilename, settitle, Start of Header, Header
2672 @comment  node-name,  next,  previous,  up
2673 @subsection @code{@@setfilename}
2674 @cindex Info file requires @code{@@setfilename}
2675 @findex setfilename
2676
2677 In order to serve as the primary input file for either @code{makeinfo}
2678 or @TeX{}, a Texinfo file must contain a line that looks like this:
2679
2680 @example
2681 @@setfilename @var{info-file-name}
2682 @end example
2683
2684 Write the @code{@@setfilename} command at the beginning of a line and
2685 follow it on the same line by the Info file name.  Do not write anything
2686 else on the line; anything on the line after the command is considered
2687 part of the file name, including what would otherwise be a
2688 comment.
2689
2690 The @code{@@setfilename} line specifies the name of the Info file to be
2691 generated.  This name should be different from the name of the Texinfo
2692 file.  There are two conventions for choosing the name: you can either
2693 remove the @samp{.texi} extension from the input file name, or replace
2694 it with the @samp{.info} extension.
2695
2696 Some operating systems cannot handle long file names.  You can run into
2697 a problem even when the file name you specify is itself short enough.
2698 This occurs because the Info formatters split a long Info file into
2699 short indirect subfiles, and name them by appending @samp{-1},
2700 @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2701 file name.  (@xref{Tag and Split Files, , Tag Files and Split Files}.)
2702 The subfile name @file{texinfo.info-10}, for example, is too long for
2703 some systems; so the Info file name for this document is @file{texinfo}
2704 rather than @file{texinfo.info}.
2705
2706 @cindex Ignored before @code{@@setfilename}
2707 The Info formatting commands ignore everything written before the
2708 @code{@@setfilename} line, which is why the very first line of
2709 the file (the @code{\input} line) does not show up in the output.
2710
2711 @pindex texinfo.cnf
2712 The @code{@@setfilename} line produces no output when you typeset a
2713 manual with @TeX{}, but it nevertheless is essential: it opens the
2714 index, cross-reference, and other auxiliary files used by Texinfo, and
2715 also reads @file{texinfo.cnf} if that file is present on your system
2716 (@pxref{Preparing for TeX,, Preparing to Use @TeX{}}).
2717
2718
2719 @node settitle, setchapternewpage, setfilename, Header
2720 @comment  node-name,  next,  previous,  up
2721 @subsection @code{@@settitle}
2722 @findex settitle
2723
2724 In order to be made into a printed manual, a Texinfo file must contain
2725 a line that looks like this:@refill
2726
2727 @example
2728 @@settitle @var{title}
2729 @end example
2730
2731 Write the @code{@@settitle} command at the beginning of a line and
2732 follow it on the same line by the title.  This tells @TeX{} the title
2733 to use in a header or footer.  Do not write anything else on the line;
2734 anything on the line after the command is considered part of the
2735 title, including a comment.@refill
2736
2737 Conventionally, when @TeX{} formats a Texinfo file for double-sided
2738 output, the title is printed in the left-hand (even-numbered) page
2739 headings and the current chapter title is printed in the right-hand
2740 (odd-numbered) page headings.  (@TeX{} learns the title of each chapter
2741 from each @code{@@chapter} command.)  Page footers are not
2742 printed.@refill
2743
2744 Even if you are printing in a single-sided style, @TeX{} looks for an
2745 @code{@@settitle} command line, in case you include the manual title
2746 in the heading. @refill
2747
2748 The @code{@@settitle} command should precede everything that generates
2749 actual output in @TeX{}.@refill
2750
2751 Although the title in the @code{@@settitle} command is usually the
2752 same as the title on the title page, it does not affect the title as
2753 it appears on the title page.  Thus, the two do not need not match
2754 exactly;  and the title in the @code{@@settitle} command can be a
2755 shortened or expanded version of the title as it appears on the title
2756 page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
2757
2758 @TeX{} prints page headings only for that text that comes after the
2759 @code{@@end titlepage} command in the Texinfo file, or that comes
2760 after an @code{@@headings} command that turns on headings.
2761 (@xref{headings on off, , The @code{@@headings} Command}, for more
2762 information.)@refill
2763
2764 You may, if you wish, create your own, customized headings and
2765 footings.  @xref{Headings, , Page Headings}, for a detailed discussion
2766 of this process.@refill
2767
2768 @node setchapternewpage, paragraphindent, settitle, Header
2769 @comment  node-name,  next,  previous,  up
2770 @subsection @code{@@setchapternewpage}
2771 @cindex Starting chapters
2772 @cindex Pages, starting odd
2773 @findex setchapternewpage
2774
2775 In a book or a manual, text is usually printed on both sides of the
2776 paper, chapters start on right-hand pages, and right-hand pages have
2777 odd numbers.  But in short reports, text often is printed only on one
2778 side of the paper.  Also in short reports, chapters sometimes do not
2779 start on new pages, but are printed on the same page as the end of the
2780 preceding chapter, after a small amount of vertical whitespace.@refill
2781
2782 You can use the @code{@@setchapternewpage} command with various
2783 arguments to specify how @TeX{} should start chapters and whether it
2784 should typeset pages for printing on one or both sides of the paper
2785 (single-sided or double-sided printing).@refill
2786
2787 Write the @code{@@setchapternewpage} command at the beginning of a
2788 line followed by its argument.@refill
2789
2790 For example, you would write the following to cause each chapter to
2791 start on a fresh odd-numbered page:@refill
2792
2793 @example
2794 @@setchapternewpage odd
2795 @end example
2796
2797 You can specify one of three alternatives with the
2798 @code{@@setchapternewpage} command:@refill
2799
2800 @table @asis
2801 @ignore
2802 @item No @code{@@setchapternewpage} command
2803 If the Texinfo file does not contain an @code{@@setchapternewpage}
2804 command before the @code{@@titlepage} command, @TeX{} automatically
2805 begins chapters on new pages and prints headings in the standard
2806 format for single-sided printing.  This is the conventional format for
2807 single-sided printing.@refill
2808
2809 The result is exactly the same as when you write
2810 @code{@@setchapternewpage on}.@refill
2811 @end ignore
2812 @item @code{@@setchapternewpage off}
2813 Cause @TeX{} to typeset a new chapter on the same page as the last
2814 chapter, after skipping some vertical whitespace.  Also, cause @TeX{} to
2815 format page headers for single-sided printing. (You can override the
2816 headers format with the @code{@@headings double} command; see
2817 @ref{headings on off, , The @code{@@headings} Command}.)@refill
2818
2819 @item @code{@@setchapternewpage on}
2820 Cause @TeX{} to start new chapters on new pages and to typeset page
2821 headers for single-sided printing.  This is the form most often
2822 used for short reports.@refill
2823
2824 This alternative is the default.@refill
2825
2826 @item @code{@@setchapternewpage odd}
2827 Cause @TeX{} to start new chapters on new, odd-numbered pages
2828 (right-handed pages) and to typeset for double-sided printing.  This is
2829 the form most often used for books and manuals.@refill
2830 @end table
2831
2832 @noindent
2833 Texinfo does not have an @code{@@setchapternewpage even} command.@refill
2834
2835 @noindent
2836 (You can countermand or modify an @code{@@setchapternewpage} command
2837 with an @code{@@headings} command.  @xref{headings on off, , The
2838 @code{@@headings} Command}.)@refill
2839
2840 At the beginning of a manual or book, pages are not numbered---for
2841 example, the title and copyright pages of a book are not numbered.
2842 By convention, table of contents pages are numbered with roman
2843 numerals and not in sequence with the rest of the document.@refill
2844
2845 Since an Info file does not have pages, the @code{@@setchapternewpage}
2846 command has no effect on it.@refill
2847
2848 Usually, you do not write an @code{@@setchapternewpage} command for
2849 single-sided printing, but accept the default which is to typeset for
2850 single-sided printing and to start new chapters on new pages.  Usually,
2851 you write an @code{@@setchapternewpage odd} command for double-sided
2852 printing.@refill
2853
2854 @node paragraphindent, End of Header, setchapternewpage, Header
2855 @comment  node-name,  next,  previous,  up
2856 @subsection Paragraph Indenting
2857 @cindex Indenting paragraphs
2858 @cindex Paragraph indentation
2859 @findex paragraphindent
2860
2861 The Info formatting commands may insert spaces at the beginning of the
2862 first line of each paragraph, thereby indenting that paragraph.  You
2863 can use the @code{@@paragraphindent} command to specify the
2864 indentation.  Write an @code{@@paragraphindent} command at the
2865 beginning of a line followed by either @samp{asis} or a number.  The
2866 template is:@refill
2867
2868 @example
2869 @@paragraphindent @var{indent}
2870 @end example
2871
2872 The Info formatting commands indent according to the value of
2873 @var{indent}:@refill
2874
2875 @itemize @bullet
2876 @item
2877 If the value of @var{indent} is @samp{asis}, the Info formatting
2878 commands do not change the existing indentation.@refill
2879
2880 @item
2881 If the value of @var{indent} is zero, the Info formatting commands delete
2882 existing indentation.@refill
2883
2884 @item
2885 If the value of @var{indent} is greater than zero, the Info formatting
2886 commands indent the paragraph by that number of spaces.@refill
2887 @end itemize
2888
2889 The default value of @var{indent} is @samp{asis}.@refill
2890
2891 Write the @code{@@paragraphindent} command before or shortly after the
2892 end-of-header line at the beginning of a Texinfo file.  (If you write
2893 the command between the start-of-header and end-of-header lines, the
2894 region formatting commands indent paragraphs as specified.)@refill
2895
2896 A peculiarity of the @code{texinfo-format-buffer} and
2897 @code{texinfo-format-region} commands is that they do not indent (nor
2898 fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
2899 @xref{Refilling Paragraphs}, for a detailed description of what goes
2900 on.@refill
2901
2902 @node End of Header,  , paragraphindent, Header
2903 @comment  node-name,  next,  previous,  up
2904 @subsection End of Header
2905 @cindex End of header line
2906
2907 Follow the header lines with an @w{end-of-header} line.
2908 An end-of-header line looks like this:@refill
2909
2910 @example
2911 @@c %**end of header
2912 @end example
2913
2914 If you include the @code{@@setchapternewpage} command between the
2915 start-of-header and end-of-header lines, @TeX{} will typeset a region as
2916 that command specifies.  Similarly, if you include an @code{@@smallbook}
2917 command between the start-of-header and end-of-header lines, @TeX{} will
2918 typeset a region in the ``small'' book format.@refill
2919
2920 @ifinfo
2921 The reason for the odd string of characters (@samp{%**}) is so that the
2922 @code{texinfo-tex-region} command does not accidentally find
2923 something that it should not when it is looking for the header.@refill
2924
2925 The start-of-header line and the end-of-header line are Texinfo mode
2926 variables that you can change.@refill
2927 @end ifinfo
2928
2929 @iftex
2930 @xref{Start of Header}.
2931 @end iftex
2932
2933 @node Info Summary and Permissions, Titlepage & Copyright Page, Header, Beginning a File
2934 @comment  node-name,  next,  previous,  up
2935 @section Summary and Copying Permissions for Info
2936
2937 The title page and the copyright page appear only in the printed copy of
2938 the manual; therefore, the same information must be inserted in a
2939 section that appears only in the Info file.  This section usually
2940 contains a brief description of the contents of the Info file, a
2941 copyright notice, and copying permissions.@refill
2942
2943 The copyright notice should read:@refill
2944
2945 @example
2946 Copyright @var{year} @var{copyright-owner}
2947 @end example
2948
2949 @noindent
2950 and be put on a line by itself.@refill
2951
2952 Standard text for the copyright permissions is contained in an appendix
2953 to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying
2954 Permissions}, for the complete text.@refill
2955
2956 The permissions text appears in an Info file @emph{before} the first
2957 node.  This mean that a reader does @emph{not} see this text when
2958 reading the file using Info, except when using the advanced Info command
2959 @kbd{g *}.
2960
2961 @node Titlepage & Copyright Page, The Top Node, Info Summary and Permissions, Beginning a File
2962 @comment  node-name,  next,  previous,  up
2963 @section The Title and Copyright Pages
2964
2965 A manual's name and author are usually printed on a title page.
2966 Sometimes copyright information is printed on the title page as well;
2967 more often, copyright information is printed on the back of the title
2968 page.
2969
2970 The title and copyright pages appear in the printed manual, but not in the
2971 Info file.  Because of this, it is possible to use several slightly
2972 obscure @TeX{} typesetting commands that cannot be used in an Info file.
2973 In addition, this part of the beginning of a Texinfo file contains the text
2974 of the copying permissions that will appear in the printed manual.@refill
2975
2976 @xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the
2977 standard text for the copyright permissions.@refill
2978
2979 @menu
2980 * titlepage::                   Create a title for the printed document.
2981 * titlefont center sp::         The @code{@@titlefont}, @code{@@center},
2982                                   and @code{@@sp} commands.
2983 * title subtitle author::       The @code{@@title}, @code{@@subtitle},
2984                                   and @code{@@author} commands.
2985 * Copyright & Permissions::     How to write the copyright notice and
2986                                   include copying permissions.
2987 * end titlepage::               Turn on page headings after the title and
2988                                   copyright pages.
2989 * headings on off::             An option for turning headings on and off
2990                                   and double or single sided printing.
2991 @end menu
2992
2993 @node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
2994 @comment  node-name,  next,  previous,  up
2995 @subsection @code{@@titlepage}
2996 @cindex Title page
2997 @findex titlepage
2998
2999 Start the material for the title page and following copyright page
3000 with @code{@@titlepage} on a line by itself and end it with
3001 @code{@@end titlepage} on a line by itself.@refill
3002
3003 The @code{@@end titlepage} command starts a new page and turns on page
3004 numbering.  (@xref{Headings, , Page Headings}, for details about how to
3005 generate page headings.)  All the material that you want to
3006 appear on unnumbered pages should be put between the
3007 @code{@@titlepage} and @code{@@end titlepage} commands.  By using the
3008 @code{@@page} command you can force a page break within the region
3009 delineated by the @code{@@titlepage} and @code{@@end titlepage}
3010 commands and thereby create more than one unnumbered page.  This is
3011 how the copyright page is produced.  (The @code{@@titlepage} command
3012 might perhaps have been better named the
3013 @code{@@titleandadditionalpages} command, but that would have been
3014 rather long!)@refill
3015
3016 @c !!! append refill to footnote when makeinfo can handle it.
3017 When you write a manual about a computer program, you should write the
3018 version of the program to which the manual applies on the title
3019 page.  If the manual changes more frequently than the program or is
3020 independent of it, you should also include an edition
3021 number@footnote{We have found that it is helpful to refer to versions
3022 of manuals as `editions' and versions of programs as `versions';
3023 otherwise, we find we are liable to confuse each other in conversation
3024 by referring to both the documentation and the software with the same
3025 words.} for the manual.  This helps readers keep track of which manual
3026 is for which version of the program.  (The `Top' node
3027 should also contain this information; see @ref{makeinfo top, ,
3028 @code{@@top}}.)@refill
3029
3030 Texinfo provides two main methods for creating a title page.  One method
3031 uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3032 to generate a title page in which the words on the page are
3033 centered.@refill
3034
3035 The second method uses the @code{@@title}, @code{@@subtitle}, and
3036 @code{@@author} commands to create a title page with black rules under
3037 the title and author lines and the subtitle text set flush to the
3038 right hand side of the page.  With this method, you do not specify any
3039 of the actual formatting of the title page.  You specify the text
3040 you want, and Texinfo does the formatting.  You may use either
3041 method.@refill
3042
3043 @findex shorttitlepage
3044 For extremely simple applications, Texinfo also provides a command
3045 @code{@@shorttitlepage} which takes a single argument as the title.
3046 The argument is typeset on a page by itself and followed by a blank
3047 page.
3048
3049
3050 @node titlefont center sp, title subtitle author, titlepage, Titlepage & Copyright Page
3051 @comment  node-name,  next,  previous,  up
3052 @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3053 @findex titlefont
3054 @findex center
3055 @findex sp @r{(titlepage line spacing)}
3056
3057 You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3058 commands to create a title page for a printed document.  (This is the
3059 first of the two methods for creating a title page in Texinfo.)@refill
3060
3061 Use the @code{@@titlefont} command to select a large font suitable for
3062 the title itself.@refill
3063
3064 @need 700
3065 For example:
3066
3067 @example
3068 @@titlefont@{Texinfo@}
3069 @end example
3070
3071 Use the @code{@@center} command at the beginning of a line to center
3072 the remaining text on that line.  Thus,@refill
3073
3074 @example
3075 @@center @@titlefont@{Texinfo@}
3076 @end example
3077
3078 @noindent
3079 centers the title, which in this example is ``Texinfo'' printed
3080 in the title font.@refill
3081
3082 Use the @code{@@sp} command to insert vertical space.  For example:@refill
3083
3084 @example
3085 @@sp 2
3086 @end example
3087
3088 @noindent
3089 This inserts two blank lines on the printed page.  (@xref{sp, ,
3090 @code{@@sp}}, for more information about the @code{@@sp}
3091 command.)@refill
3092
3093 A template for this method looks like this:@refill
3094
3095 @example
3096 @group
3097 @@titlepage
3098 @@sp 10
3099 @@center @@titlefont@{@var{name-of-manual-when-printed}@}
3100 @@sp 2
3101 @@center @var{subtitle-if-any}
3102 @@sp 2
3103 @@center @var{author}
3104 @dots{}
3105 @@end titlepage
3106 @end group
3107 @end example
3108
3109 The spacing of the example fits an 8 1/2 by 11 inch manual.@refill
3110
3111 @node title subtitle author, Copyright & Permissions, titlefont center sp, Titlepage & Copyright Page
3112 @comment  node-name,  next,  previous,  up
3113 @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3114 @findex title
3115 @findex subtitle
3116 @findex author
3117
3118 You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3119 commands to create a title page in which the vertical and horizontal
3120 spacing is done for you automatically.  This contrasts with the method
3121 described in
3122 the previous section, in which the @code{@@sp} command is needed to
3123 adjust vertical spacing.@refill
3124
3125 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3126 commands at the beginning of a line followed by the title, subtitle,
3127 or author.@refill
3128
3129 The @code{@@title} command produces a line in which the title is set
3130 flush to the left-hand side of the page in a larger than normal font.
3131 The title is underlined with a black rule.@refill
3132
3133 The @code{@@subtitle} command sets subtitles in a normal-sized font
3134 flush to the right-hand side of the page.@refill
3135
3136 The @code{@@author} command sets the names of the author or authors in
3137 a middle-sized font flush to the left-hand side of the page on a line
3138 near the bottom of the title page.  The names are underlined with a
3139 black rule that is thinner than the rule that underlines the title.
3140 (The black rule only occurs if the @code{@@author} command line is
3141 followed by an @code{@@page} command line.)@refill
3142
3143 There are two ways to use the @code{@@author} command: you can write
3144 the name or names on the remaining part of the line that starts with
3145 an @code{@@author} command:@refill
3146
3147 @example
3148 @@author by Jane Smith and John Doe
3149 @end example
3150
3151 @noindent
3152 or you can write the names one above each other by using two (or more)
3153 @code{@@author} commands:@refill
3154
3155 @example
3156 @group
3157 @@author Jane Smith
3158 @@author John Doe
3159 @end group
3160 @end example
3161
3162 @noindent
3163 (Only the bottom name is underlined with a black rule.)@refill
3164
3165 @need 950
3166 A template for this method looks like this:@refill
3167
3168 @example
3169 @group
3170 @@titlepage
3171 @@title @var{name-of-manual-when-printed}
3172 @@subtitle @var{subtitle-if-any}
3173 @@subtitle @var{second-subtitle}
3174 @@author @var{author}
3175 @@page
3176 @dots{}
3177 @@end titlepage
3178 @end group
3179 @end example
3180
3181 @ifinfo
3182 @noindent
3183 Contrast this form with the form of a title page written using the
3184 @code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill
3185
3186 @example
3187 @@titlepage
3188 @@sp 10
3189 @@center @@titlefont@{Name of Manual When Printed@}
3190 @@sp 2
3191 @@center Subtitle, If Any
3192 @@sp 1
3193 @@center Second subtitle
3194 @@sp 2
3195 @@center Author
3196 @@page
3197 @dots{}
3198 @@end titlepage
3199 @end example
3200 @end ifinfo
3201
3202 @node Copyright & Permissions, end titlepage, title subtitle author, Titlepage & Copyright Page
3203 @comment  node-name,  next,  previous,  up
3204 @subsection Copyright Page and Permissions
3205 @cindex Copyright page
3206 @cindex Printed permissions
3207 @cindex Permissions, printed
3208
3209 By international treaty, the copyright notice for a book should be
3210 either on the title page or on the back of the title page.  The
3211 copyright notice should include the year followed by the name of the
3212 organization or person who owns the copyright.@refill
3213
3214 When the copyright notice is on the back of the title page, that page
3215 is customarily not numbered.  Therefore, in Texinfo, the information
3216 on the copyright page should be within @code{@@titlepage} and
3217 @code{@@end titlepage} commands.@refill
3218
3219 @findex vskip
3220 @findex filll
3221 @cindex Vertical whitespace (@samp{vskip})
3222 Use the @code{@@page} command to cause a page break.  To push the
3223 copyright notice and the other text on the copyright page towards the
3224 bottom of the page, you can write a somewhat mysterious line after the
3225 @code{@@page} command that reads like this:@refill
3226
3227 @example
3228 @@vskip 0pt plus 1filll
3229 @end example
3230
3231 @noindent
3232 This is a @TeX{} command that is not supported by the Info formatting
3233 commands.  The @code{@@vskip} command inserts whitespace.  The
3234 @samp{0pt plus 1filll} means to put in zero points of mandatory whitespace,
3235 and as much optional whitespace as needed to push the
3236 following text to the bottom of the page.  Note the use of three
3237 @samp{l}s in the word @samp{filll}; this is the correct usage in
3238 @TeX{}.@refill
3239
3240 @findex copyright
3241 In a printed manual, the @code{@@copyright@{@}} command generates a
3242 @samp{c} inside a circle.  (In Info, it generates @samp{(C)}.)  The
3243 copyright notice itself has the following legally defined sequence:@refill
3244
3245 @example
3246 Copyright @copyright{} @var{year} @var{copyright-owner}
3247 @end example
3248
3249 It is customary to put information on how to get a manual after the
3250 copyright notice, followed by the copying permissions for the
3251 manual.@refill
3252
3253 Note that permissions must be given here as well as in the summary
3254 segment within @code{@@ifinfo} and @code{@@end ifinfo} that
3255 immediately follows the header since this text appears only in the
3256 printed manual and the @samp{ifinfo} text appears only in the Info
3257 file.@refill
3258
3259 @xref{Sample Permissions}, for the standard text.@refill
3260
3261 @node end titlepage, headings on off, Copyright & Permissions, Titlepage & Copyright Page
3262 @comment  node-name,  next,  previous,  up
3263 @subsection Heading Generation
3264 @findex end titlepage
3265 @cindex Headings, page, begin to appear
3266 @cindex Titlepage end starts headings
3267 @cindex End titlepage starts headings
3268
3269 An @code{@@end titlepage} command on a line by itself not only marks
3270 the end of the title and copyright pages, but also causes @TeX{} to start
3271 generating page headings and page numbers.
3272
3273 To repeat what is said elsewhere,  Texinfo has two standard page heading
3274 formats, one for documents which are printed on one side of each sheet of paper
3275 (single-sided printing), and the other for documents which are printed on both
3276 sides of each sheet (double-sided printing).
3277 (@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
3278 You can specify these formats in different ways:@refill
3279
3280 @itemize @bullet
3281 @item
3282 The conventional way is to write an @code{@@setchapternewpage} command
3283 before the title page commands, and then have the @code{@@end
3284 titlepage} command start generating page headings in the manner desired.
3285 (@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
3286
3287 @item
3288 Alternatively, you can use the @code{@@headings} command to prevent page
3289 headings from being generated or to start them for either single or
3290 double-sided printing.  (Write an @code{@@headings} command immediately
3291 after the @code{@@end titlepage} command.  @xref{headings on off, , The
3292 @code{@@headings} Command}, for more information.)@refill
3293
3294 @item
3295 Or, you may specify your own page heading and footing format.
3296 @xref{Headings, , Page Headings}, for detailed
3297 information about page headings and footings.@refill
3298 @end itemize
3299
3300 Most documents are formatted with the standard single-sided or
3301 double-sided format, using @code{@@setchapternewpage odd} for
3302 double-sided printing and no @code{@@setchapternewpage} command for
3303 single-sided printing.@refill
3304
3305 @node headings on off,  , end titlepage, Titlepage & Copyright Page
3306 @comment  node-name,  next,  previous,  up
3307 @subsection The @code{@@headings} Command
3308 @findex headings
3309
3310 The @code{@@headings} command is rarely used.  It specifies what kind of
3311 page headings and footings to print on each page.  Usually, this is
3312 controlled by the @code{@@setchapternewpage} command.  You need the
3313 @code{@@headings} command only if the @code{@@setchapternewpage} command
3314 does not do what you want, or if you want to turn off pre-defined page
3315 headings prior to defining your own.  Write an @code{@@headings} command
3316 immediately after the @code{@@end titlepage} command.@refill
3317
3318 You can use @code{@@headings} as follows:@refill
3319
3320 @table @code
3321 @item @@headings off
3322 Turn off printing of page headings.@refill
3323
3324 @item @@headings single
3325 Turn on page headings appropriate for single-sided printing.
3326 @refill
3327
3328 @item @@headings double
3329 Turn on page headings appropriate for double-sided printing.  The two
3330 commands, @code{@@headings on} and @code{@@headings double}, are
3331 synonymous.@refill
3332
3333 @item @@headings singleafter
3334 @itemx @@headings doubleafter
3335 Turn on @code{single} or @code{double} headings, respectively, after the
3336 current page is output.
3337
3338 @item @@headings on
3339 Turn on page headings: @code{single} if @samp{@@setchapternewpage
3340 on}, @code{double} otherwise.
3341 @end table
3342
3343 For example, suppose you write @code{@@setchapternewpage off} before the
3344 @code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3345 same page as the end of the last chapter.  This command also causes
3346 @TeX{} to typeset page headers for single-sided printing.  To cause
3347 @TeX{} to typeset for double sided printing, write @code{@@headings
3348 double} after the @code{@@end titlepage} command.
3349
3350 You can stop @TeX{} from generating any page headings at all by
3351 writing @code{@@headings off} on a line of its own immediately after the
3352 line containing the @code{@@end titlepage} command, like this:@refill
3353
3354 @example
3355 @@end titlepage
3356 @@headings off
3357 @end example
3358
3359 @noindent
3360 The @code{@@headings off} command overrides the @code{@@end titlepage}
3361 command, which would otherwise cause @TeX{} to print page
3362 headings.@refill
3363
3364 You can also specify your own style of page heading and footing.
3365 @xref{Headings, , Page Headings}, for more information.@refill
3366
3367 @node The Top Node, Software Copying Permissions, Titlepage & Copyright Page, Beginning a File
3368 @comment  node-name,  next,  previous,  up
3369 @section The `Top' Node and Master Menu
3370 @cindex @samp{@r{Top}} node
3371 @cindex Master menu
3372 @cindex Node, `Top'
3373
3374 The `Top' node is the node from which you enter an Info file.@refill
3375
3376 A `Top' node should contain a brief description of the Info file and an
3377 extensive, master menu for the whole Info file.
3378 This helps the reader understand what the Info file is
3379 about.  Also, you should write the version number of the program to
3380 which the Info file applies; or, at least, the edition number.@refill
3381
3382 The contents of the `Top' node should appear only in the Info file; none
3383 of it should appear in printed output, so enclose it between
3384 @code{@@ifinfo} and @code{@@end ifinfo} commands.  (@TeX{} does not
3385 print either an @code{@@node} line or a menu; they appear only in Info;
3386 strictly speaking, you are not required to enclose these parts between
3387 @code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
3388 @xref{Conditionals, , Conditionally Visible Text}.)@refill
3389
3390 @menu
3391 * Title of Top Node::           Sketch what the file is about.
3392 * Master Menu Parts::           A master menu has three or more parts.
3393 @end menu
3394
3395 @node Title of Top Node, Master Menu Parts, The Top Node, The Top Node
3396 @ifinfo
3397 @subheading `Top' Node Title
3398 @end ifinfo
3399
3400 Sometimes, you will want to place an @code{@@top} sectioning command
3401 line containing the title of the document immediately after the
3402 @code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
3403 Sectioning Command}, for more information).@refill
3404
3405 For example, the beginning of the Top node of this manual contains an
3406 @code{@@top} sectioning command, a short description, and edition and
3407 version information.  It looks like this:@refill
3408
3409 @example
3410 @group
3411 @dots{}
3412 @@end titlepage
3413
3414 @@ifinfo
3415 @@node Top, Copying, , (dir)
3416 @@top Texinfo
3417
3418 Texinfo is a documentation system@dots{}
3419 @end group
3420
3421 @group
3422 This is edition@dots{}
3423 @dots{}
3424 @@end ifinfo
3425 @end group
3426
3427 @group
3428 @@menu
3429 * Copying::                 Texinfo is freely
3430                               redistributable.
3431 * Overview::                What is Texinfo?
3432 @dots{}
3433 @end group
3434 @@end menu
3435 @end example
3436
3437 In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
3438 level directory of the whole Info system, which is called @samp{(dir)}.
3439 The `Next' node refers to the first node that follows the main or master
3440 menu, which is usually the copying permissions, introduction, or first
3441 chapter.@refill
3442
3443 @node Master Menu Parts,  , Title of Top Node, The Top Node
3444 @subsection Parts of a Master Menu
3445 @cindex Master menu parts
3446 @cindex Parts of a master menu
3447
3448 A @dfn{master menu} is a detailed main menu listing all the nodes in a
3449 file.
3450
3451 A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3452 commands and does not appear in the printed document.@refill
3453
3454 Generally, a master menu is divided into parts.@refill
3455
3456 @itemize @bullet
3457 @item
3458 The first part contains the major nodes in the Texinfo file: the nodes
3459 for the chapters, chapter-like sections, and the appendices.@refill
3460
3461 @item
3462 The second part contains nodes for the indices.@refill
3463
3464 @item
3465 The third and subsequent parts contain a listing of the other, lower
3466 level nodes, often ordered by chapter.  This way, rather than go
3467 through an intermediary menu, an inquirer can go directly to a
3468 particular node when searching for specific information.  These menu
3469 items are not required; add them if you think they are a
3470 convenience.  If you do use them, put @code{@@detailmenu} before the
3471 first one, and @code{@@end detailmenu} after the last; otherwise,
3472 @code{makeinfo} will get confused.
3473 @end itemize
3474
3475 Each section in the menu can be introduced by a descriptive line.  So
3476 long as the line does not begin with an asterisk, it will not be
3477 treated as a menu entry.  (@xref{Writing a Menu}, for more
3478 information.)@refill
3479
3480 For example, the master menu for this manual looks like the following
3481 (but has many more entries):@refill
3482
3483 @example
3484 @group
3485 @@menu
3486 * Copying::             Texinfo is freely
3487                           redistributable.
3488 * Overview::            What is Texinfo?
3489 * Texinfo Mode::        Special features in GNU Emacs.
3490 @dots{}
3491 @dots{}
3492 @end group
3493 @group
3494 * Command and Variable Index::
3495                         An entry for each @@-command.
3496 * Concept Index::       An entry for each concept.
3497 @end group
3498
3499 @group
3500 @@detailmenu
3501  --- The Detailed Node Listing ---
3502
3503 Overview of Texinfo
3504
3505 * Info Files::          What is an Info file?
3506 * Printed Manuals::     Characteristics of
3507                           a printed manual.
3508 @dots{}
3509 @dots{}
3510 @end group
3511
3512 @group
3513 Using Texinfo Mode
3514
3515 * Info on a Region::    Formatting part of a file
3516                           for Info.
3517 @dots{}
3518 @dots{}
3519 @@end detailmenu
3520 @@end menu
3521 @end group
3522 @end example
3523
3524 @node Software Copying Permissions,  , The Top Node, Beginning a File
3525 @comment  node-name,  next,  previous,  up
3526 @section Software Copying Permissions
3527 @cindex Software copying permissions
3528 @cindex Copying software
3529 @cindex Distribution
3530 @cindex License agreement
3531
3532 If the Texinfo file has a section containing the ``General Public
3533 License'' and the distribution information and a warranty disclaimer
3534 for the software that is documented, this section usually follows the
3535 `Top' node.  The General Public License is very important to Project
3536 GNU software.  It ensures that you and others will continue to have a
3537 right to use and share the software.@refill
3538
3539 The copying and distribution information and the disclaimer are
3540 followed by an introduction or else by the first chapter of the
3541 manual.@refill
3542
3543 @cindex Introduction, as part of file
3544 Although an introduction is not a required part of a Texinfo file, it
3545 is very helpful.  Ideally, it should state clearly and concisely what
3546 the file is about and who would be interested in reading it.  In
3547 general, an introduction would follow the licensing and distribution
3548 information, although sometimes people put it earlier in the document.
3549 Usually, an introduction is put in an @code{@@unnumbered} section.
3550 (@xref{unnumbered & appendix, , The @code{@@unnumbered} and
3551 @code{@@appendix} Commands}.)@refill
3552
3553 @node Ending a File, Structuring, Beginning a File, Top
3554 @comment  node-name,  next,  previous,  up
3555 @chapter Ending a Texinfo File
3556 @cindex Ending a Texinfo file
3557 @cindex Texinfo file ending
3558 @cindex File ending
3559 @findex bye
3560
3561 The end of a Texinfo file should include the commands that create
3562 indices and generate detailed and summary tables of contents.
3563 And it must include the @code{@@bye} command that marks the last line
3564 processed by @TeX{}.@refill
3565
3566 @need 700
3567 For example:
3568
3569 @example
3570 @@node    Concept Index,     , Variables Index, Top
3571 @@c        node-name,    next, previous,        up
3572 @@unnumbered Concept Index
3573
3574 @@printindex cp
3575
3576 @@contents
3577 @@bye
3578 @end example
3579
3580 @menu
3581 * Printing Indices & Menus::    How to print an index in hardcopy and
3582                                   generate index menus in Info.
3583 * Contents::                    How to create a table of contents.
3584 * File End::                    How to mark the end of a file.
3585 @end menu
3586
3587 @node Printing Indices & Menus, Contents, Ending a File, Ending a File
3588 @comment  node-name,  next,  previous,  up
3589 @section Index Menus and Printing an Index
3590 @findex printindex
3591 @cindex Printing an index
3592 @cindex Indices, printing and menus
3593 @cindex Generating menus with indices
3594 @cindex Menus generated with indices
3595
3596 To print an index means to include it as part of a manual or Info
3597 file.  This does not happen automatically just because you use
3598 @code{@@cindex} or other index-entry generating commands in the
3599 Texinfo file; those just cause the raw data for the index to be
3600 accumulated.  To generate an index, you must include the
3601 @code{@@printindex} command at the place in the document where you
3602 want the index to appear.  Also, as part of the process of creating a
3603 printed manual, you must run a program called @code{texindex}
3604 (@pxref{Format/Print Hardcopy}) to sort the raw data to produce a sorted
3605 index file.  The sorted index file is what is actually used to
3606 print the index.@refill
3607
3608 Texinfo offers six different types of predefined index: the concept
3609 index, the function index, the variables index, the keystroke index, the
3610 program index, and the data type index (@pxref{Predefined Indices}).  Each
3611 index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
3612 @samp{ky}, @samp{pg}, and @samp{tp}.  You may merge indices, or put them
3613 into separate sections (@pxref{Combining Indices}); or you may define
3614 your own indices (@pxref{New Indices, , Defining New Indices}).@refill
3615
3616 The @code{@@printindex} command takes a two-letter index name, reads
3617 the corresponding sorted index file and formats it appropriately into
3618 an index.@refill
3619
3620 @ignore
3621 The two-letter index names are:
3622
3623 @table @samp
3624 @item cp
3625 concept index
3626 @item fn
3627 function index
3628 @item vr
3629 variable index
3630 @item ky
3631 key index
3632 @item pg
3633 program index
3634 @item tp
3635 data type index
3636 @end table
3637 @end ignore
3638 The @code{@@printindex} command does not generate a chapter heading
3639 for the index.  Consequently, you should precede the
3640 @code{@@printindex} command with a suitable section or chapter command
3641 (usually @code{@@unnumbered}) to supply the chapter heading and put
3642 the index into the table of contents.  Precede the @code{@@unnumbered}
3643 command with an @code{@@node} line.@refill
3644
3645 @need 1200
3646 For example:
3647
3648 @smallexample
3649 @group
3650 @@node Variable Index, Concept Index, Function Index, Top
3651 @@comment    node-name,         next,       previous, up
3652 @@unnumbered Variable Index
3653
3654 @@printindex vr
3655 @end group
3656
3657 @group
3658 @@node     Concept Index,     , Variable Index, Top
3659 @@comment      node-name, next,       previous, up
3660 @@unnumbered Concept Index
3661
3662 @@printindex cp
3663 @end group
3664
3665 @group
3666 @@summarycontents
3667 @@contents
3668 @@bye
3669 @end group
3670 @end smallexample
3671
3672 @noindent
3673 (Readers often prefer that the concept index come last in a book,
3674 since that makes it easiest to find.)@refill
3675
3676 @ignore
3677 @c TeX can do sorting, just not conveniently enough to handle sorting
3678 @c Texinfo indexes. --karl, 5may97.
3679 In @TeX{}, the @code{@@printindex} command needs a sorted index file
3680 to work from.  @TeX{} does not know how to do sorting; this is a
3681 deficiency.  @TeX{} writes output files of raw index data; use the
3682 @code{texindex} program to convert these files to sorted index files.
3683 (@xref{Format/Print Hardcopy}, for more information.)@refill
3684 @end ignore
3685
3686
3687 @node Contents, File End, Printing Indices & Menus, Ending a File
3688 @comment  node-name,  next,  previous,  up
3689 @section Generating a Table of Contents
3690 @cindex Table of contents
3691 @cindex Contents, Table of
3692 @findex contents
3693 @findex summarycontents
3694 @findex shortcontents
3695
3696 The @code{@@chapter}, @code{@@section}, and other structuring commands
3697 supply the information to make up a table of contents, but they do not
3698 cause an actual table to appear in the manual.  To do this, you must
3699 use the @code{@@contents} and @code{@@summarycontents}
3700 commands:@refill
3701
3702 @table @code
3703 @item @@contents
3704 Generate a table of contents in a printed manual, including all
3705 chapters, sections, subsections, etc., as well as appendices and
3706 unnumbered chapters.  (Headings generated by the @code{@@heading}
3707 series of commands do not appear in the table of contents.)  The
3708 @code{@@contents} command should be written on a line by
3709 itself.@refill
3710
3711 @item @@shortcontents
3712 @itemx @@summarycontents
3713 (@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
3714 two commands are exactly the same.)@refill
3715
3716 Generate a short or summary table of contents that lists only the
3717 chapters (and appendices and unnumbered chapters).  Omit sections, subsections
3718 and subsubsections.  Only a long manual needs a short table
3719 of contents in addition to the full table of contents.@refill
3720
3721 Write the @code{@@shortcontents} command on a line by itself right
3722 @emph{before} the @code{@@contents} command.@refill
3723 @end table
3724
3725 The table of contents commands automatically generate a chapter-like
3726 heading at the top of the first table of contents page.  Write the table
3727 of contents commands at the very end of a Texinfo file, just before the
3728 @code{@@bye} command, following any index sections---anything in the
3729 Texinfo file after the table of contents commands will be omitted from
3730 the table of contents.@refill
3731
3732 When you print a manual with a table of contents, the table of
3733 contents are printed last and numbered with roman numerals.  You need
3734 to place those pages in their proper place, after the title page,
3735 yourself.  (This is the only collating you need to do for a printed
3736 manual.  The table of contents is printed last because it is generated
3737 after the rest of the manual is typeset.)@refill
3738
3739 @need 700
3740 Here is an example of where to write table of contents commands:@refill
3741
3742 @example
3743 @group
3744 @var{indices}@dots{}
3745 @@shortcontents
3746 @@contents
3747 @@bye
3748 @end group
3749 @end example
3750
3751 Since an Info file uses menus instead of tables of contents, the Info
3752 formatting commands ignore the @code{@@contents} and
3753 @code{@@shortcontents} commands.@refill
3754
3755 @node File End,  , Contents, Ending a File
3756 @comment  node-name,  next,  previous,  up
3757 @section @code{@@bye} File Ending
3758 @findex bye
3759
3760 An @code{@@bye} command terminates @TeX{} or Info formatting.  None of
3761 the formatting commands see any of the file following @code{@@bye}.
3762 The @code{@@bye} command should be on a line by itself.@refill
3763
3764 If you wish, you may follow the @code{@@bye} line with notes. These notes
3765 will not be formatted and will not appear in either Info or a printed
3766 manual; it is as if text after @code{@@bye} were within @code{@@ignore}
3767 @dots{} @code{@@end ignore}.  Also, you may follow the @code{@@bye} line
3768 with a local variables list.  @xref{Compile-Command, , Using Local
3769 Variables and the Compile Command}, for more information.@refill
3770
3771 @node Structuring, Nodes, Ending a File, Top
3772 @comment  node-name,  next,  previous,  up
3773 @chapter Chapter Structuring
3774 @cindex Chapter structuring
3775 @cindex Structuring of chapters
3776
3777 The @dfn{chapter structuring} commands divide a document into a hierarchy of
3778 chapters, sections, subsections, and subsubsections.  These commands
3779 generate large headings; they also provide information for the table
3780 of contents of a printed manual (@pxref{Contents, , Generating a Table
3781 of Contents}).@refill
3782
3783 The chapter structuring commands do not create an Info node structure,
3784 so normally you should put an @code{@@node} command immediately before
3785 each chapter structuring command (@pxref{Nodes}).  The only time you
3786 are likely to use the chapter structuring commands without using the
3787 node structuring commands is if you are writing a document that
3788 contains no cross references and will never be transformed into Info
3789 format.@refill
3790
3791 It is unlikely that you will ever write a Texinfo file that is
3792 intended only as an Info file and not as a printable document.  If you
3793 do, you might still use chapter structuring commands to create a
3794 heading at the top of each node---but you don't need to.@refill
3795
3796 @menu
3797 * Tree Structuring::            A manual is like an upside down tree @dots{}
3798 * Structuring Command Types::   How to divide a manual into parts.
3799 * makeinfo top::                The @code{@@top} command, part of the `Top' node.
3800 * chapter::                     
3801 * unnumbered & appendix::       
3802 * majorheading & chapheading::  
3803 * section::                     
3804 * unnumberedsec appendixsec heading::  
3805 * subsection::                  
3806 * unnumberedsubsec appendixsubsec subheading::  
3807 * subsubsection::               Commands for the lowest level sections.
3808 * Raise/lower sections::        How to change commands' hierarchical level.
3809 @end menu
3810
3811 @node Tree Structuring, Structuring Command Types, Structuring, Structuring
3812 @comment  node-name,  next,  previous,  up
3813 @section Tree Structure of Sections
3814 @cindex Tree structuring
3815
3816 A Texinfo file is usually structured like a book with chapters,
3817 sections, subsections, and the like.  This structure can be visualized
3818 as a tree (or rather as an upside-down tree) with the root at the top
3819 and the levels corresponding to chapters, sections, subsection, and
3820 subsubsections.@refill
3821
3822 Here is a diagram that shows a Texinfo file with three chapters,
3823 each of which has two sections.@refill
3824
3825 @example
3826 @group
3827                           Top
3828                            |
3829          -------------------------------------
3830         |                  |                  |
3831      Chapter 1          Chapter 2          Chapter 3
3832         |                  |                  |
3833      --------           --------           --------
3834     |        |         |        |         |        |
3835  Section  Section   Section  Section   Section  Section
3836    1.1      1.2       2.1      2.2       3.1      3.2
3837
3838 @end group
3839 @end example
3840
3841 In a Texinfo file that has this structure, the beginning of Chapter 2
3842 looks like this:@refill
3843
3844 @example
3845 @group
3846 @@node    Chapter 2,  Chapter 3, Chapter 1, top
3847 @@chapter Chapter 2
3848 @end group
3849 @end example
3850
3851 The chapter structuring commands are described in the sections that
3852 follow; the @code{@@node} and @code{@@menu} commands are described in
3853 following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
3854
3855 @node Structuring Command Types, makeinfo top, Tree Structuring, Structuring
3856 @comment  node-name,  next,  previous,  up
3857 @section Types of Structuring Commands
3858
3859 The chapter structuring commands fall into four groups or series, each
3860 of which contains structuring commands corresponding to the
3861 hierarchical levels of chapters, sections, subsections, and
3862 subsubsections.@refill
3863
3864 The four groups are the @code{@@chapter} series, the
3865 @code{@@unnumbered} series, the @code{@@appendix} series, and the
3866 @code{@@heading} series.@refill
3867
3868 Each command produces titles that have a different appearance on the
3869 printed page or Info file; only some of the commands produce
3870 titles that are listed in the table of contents of a printed book or
3871 manual.@refill
3872
3873 @itemize @bullet
3874 @item
3875 The @code{@@chapter} and @code{@@appendix} series of commands produce
3876 numbered or lettered entries both in the body of a printed work and in
3877 its table of contents.@refill
3878
3879 @item
3880 The @code{@@unnumbered} series of commands produce unnumbered entries
3881 both in the body of a printed work and in its table of contents.  The
3882 @code{@@top} command, which has a special use, is a member of this
3883 series (@pxref{makeinfo top, , @code{@@top}}).@refill
3884
3885 @item
3886 The @code{@@heading} series of commands produce unnumbered headings
3887 that do not appear in a table of contents.  The heading commands never
3888 start a new page.@refill
3889
3890 @item
3891 The @code{@@majorheading} command produces results similar to using
3892 the @code{@@chapheading} command but generates a larger vertical
3893 whitespace before the heading.@refill
3894
3895 @item
3896 When an @code{@@setchapternewpage} command says to do so, the
3897 @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
3898 start new pages in the printed manual; the @code{@@heading} commands
3899 do not.@refill
3900 @end itemize
3901
3902 @need 1000
3903 Here are the four groups of chapter structuring commands:@refill
3904
3905 @c Slightly different formatting for regular sized books and smallbooks.
3906 @ifset smallbook
3907 @sp 1
3908 @tex
3909 {\let\rm=\indrm \let\tt=\indtt
3910 \halign{\hskip\itemindent#\hfil&  \hskip.5em#\hfil&  \hskip.5em#\hfil&
3911 \hskip.5em#\hfil\cr
3912
3913 & & &                                                \rm No new pages\cr
3914 \rm Numbered&    \rm Unnumbered&  \rm Lettered and numbered& \rm Unnumbered\cr
3915 \rm In contents&  \rm In contents&  \rm In contents&  \rm Not in contents\cr
3916
3917 & & & \cr
3918  &              \tt  @@top&            &               \tt @@majorheading\cr
3919 \tt @@chapter& \tt @@unnumbered&    \tt @@appendix&     \tt @@chapheading\cr
3920 \tt @@section&   \tt @@unnumberedsec&   \tt @@appendixsec&   \tt @@heading\cr
3921 \tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
3922 \tt @@subheading\cr
3923 \tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
3924 \tt @@subsubheading\cr}}
3925 @end tex
3926 @end ifset
3927 @ifclear smallbook
3928 @sp 1
3929 @tex
3930 \vbox{
3931 \halign{\hskip\itemindent\hskip.5em#\hfil&  \hskip.5em#\hfil&
3932 \hskip.5em#\hfil& \hskip.5em #\hfil\cr
3933
3934 & & & \cr
3935 & & &                                                \rm No new pages\cr
3936 \rm Numbered&    \rm Unnumbered&  \rm Lettered and numbered& \rm Unnumbered\cr
3937 \rm In contents&  \rm In contents&  \rm In contents&  \rm Not in contents\cr
3938
3939 & & & \cr
3940  &              \tt  @@top&            &               \tt @@majorheading\cr
3941 \tt @@chapter& \tt @@unnumbered&    \tt @@appendix&     \tt @@chapheading\cr
3942 \tt @@section&   \tt @@unnumberedsec&   \tt @@appendixsec&   \tt @@heading\cr
3943 \tt @@subsection&\tt @@unnumberedsubsec&\tt @@appendixsubsec&
3944 \tt @@subheading\cr
3945 \tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
3946 \tt @@subsubheading\cr}}
3947 @end tex
3948 @end ifclear
3949 @ifinfo
3950 @example
3951 @group
3952                                                        @r{No new pages}
3953 @r{Numbered}       @r{Unnumbered}       @r{Lettered and numbered}  @r{Unnumbered}
3954 @r{In contents}    @r{In contents}          @r{In contents}        @r{Not in contents}
3955
3956                @@top                                    @@majorheading
3957 @@chapter       @@unnumbered          @@appendix          @@chapheading
3958 @@section       @@unnumberedsec       @@appendixsec       @@heading
3959 @@subsection    @@unnumberedsubsec    @@appendixsubsec    @@subheading
3960 @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
3961 @end group
3962 @end example
3963 @end ifinfo
3964
3965 @c Cannot line up columns properly inside of an example because of roman
3966 @c proportional fonts.
3967 @ignore
3968 @ifset smallbook
3969 @iftex
3970 @smallexample
3971 @group
3972                                                        @r{No new pages}
3973 @r{Numbered}      @r{Unnumbered}       @r{Lettered and numbered}  @r{Unnumbered}
3974 @r{In contents}      @r{In contents}           @r{In contents}         @r{Not in contents}
3975
3976                @@top                                    @@majorheading
3977 @@chapter       @@unnumbered          @@appendix          @@chapheading
3978 @@section       @@unnumberedsec       @@appendixsec       @@heading
3979 @@subsection    @@unnumberedsubsec    @@appendixsubsec    @@subheading
3980 @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
3981 @end group
3982 @end smallexample
3983 @end iftex
3984 @end ifset
3985 @ifclear smallbook
3986 @iftex
3987 @smallexample
3988 @group
3989                                                       @r{No new pages}
3990 @r{Numbered}      @r{Unnumbered}       @r{Lettered and numbered}  @r{Unnumbered}
3991 @r{In contents}      @r{In contents}           @r{In contents}         @r{Not in contents}
3992
3993                @@top                                    @@majorheading
3994 @@chapter       @@unnumbered          @@appendix          @@chapheading
3995 @@section       @@unnumberedsec       @@appendixsec       @@heading
3996 @@subsection    @@unnumberedsubsec    @@appendixsubsec    @@subheading
3997 @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
3998 @end group
3999 @end smallexample
4000 @end iftex
4001 @end ignore
4002
4003 @node makeinfo top, chapter, Structuring Command Types, Structuring
4004 @comment  node-name,  next,  previous,  up
4005 @section @code{@@top}
4006
4007 The @code{@@top} command is a special sectioning command that you use
4008 only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4009 The @code{@@top} command tells the @code{makeinfo} formatter
4010 which node is the `Top'
4011 node.  It has the same typesetting effect as @code{@@unnumbered}
4012 (@pxref{unnumbered & appendix, , @code{@@unnumbered}, @code{@@appendix}}).
4013 For detailed information, see
4014 @ref{makeinfo top command, , The @code{@@top} Command}.@refill
4015
4016 @node chapter, unnumbered & appendix, makeinfo top, Structuring
4017 @comment  node-name,  next,  previous,  up
4018 @section @code{@@chapter}
4019 @findex chapter
4020
4021 @code{@@chapter} identifies a chapter in the document.  Write the
4022 command at the beginning of a line and follow it on the same line by
4023 the title of the chapter.@refill
4024
4025 For example, this chapter in this manual is entitled ``Chapter
4026 Structuring''; the @code{@@chapter} line looks like this:@refill
4027
4028 @example
4029 @@chapter Chapter Structuring
4030 @end example
4031
4032 In @TeX{}, the @code{@@chapter} command creates a chapter in the
4033 document, specifying the chapter title.  The chapter is numbered
4034 automatically.@refill
4035
4036 In Info, the @code{@@chapter} command causes the title to appear on a
4037 line by itself, with a line of asterisks inserted underneath.  Thus,
4038 in Info, the above example produces the following output:@refill
4039
4040 @example
4041 Chapter Structuring
4042 *******************
4043 @end example
4044
4045 @findex centerchap
4046 Texinfo also provides a command @code{@@centerchap}, which is analogous
4047 to @code{@@unnumbered}, but centers its argument in the printed output.
4048 This kind of stylistic choice is not usually offered by Texinfo.
4049 @c but the Hacker's Dictionary wanted it ...
4050
4051
4052 @node unnumbered & appendix, majorheading & chapheading, chapter, Structuring
4053 @comment  node-name,  next,  previous,  up
4054 @section @code{@@unnumbered}, @code{@@appendix}
4055 @findex unnumbered
4056 @findex appendix
4057
4058 Use the @code{@@unnumbered} command to create a chapter that appears
4059 in a printed manual without chapter numbers of any kind.  Use the
4060 @code{@@appendix} command to create an appendix in a printed manual
4061 that is labelled by letter instead of by number.@refill
4062
4063 For Info file output, the @code{@@unnumbered} and @code{@@appendix}
4064 commands are equivalent to @code{@@chapter}: the title is printed on a
4065 line by itself with a line of asterisks underneath.  (@xref{chapter, ,
4066 @code{@@chapter}}.)@refill
4067
4068 To create an appendix or an unnumbered chapter, write an
4069 @code{@@appendix} or @code{@@unnumbered} command at the beginning of a
4070 line and follow it on the same line by the title, as you would if you
4071 were creating a chapter.@refill
4072
4073
4074 @node majorheading & chapheading, section, unnumbered & appendix, Structuring
4075 @section @code{@@majorheading}, @code{@@chapheading}
4076 @findex majorheading
4077 @findex chapheading
4078
4079 The @code{@@majorheading} and @code{@@chapheading} commands put
4080 chapter-like headings in the body of a document.@refill
4081
4082 However, neither command causes @TeX{} to produce a numbered heading
4083 or an entry in the table of contents; and neither command causes
4084 @TeX{} to start a new page in a printed manual.@refill
4085
4086 In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4087 whitespace before the heading than an @code{@@chapheading} command but
4088 is otherwise the same.@refill
4089
4090 In Info,
4091 the @code{@@majorheading} and
4092 @code{@@chapheading} commands are equivalent to
4093 @code{@@chapter}: the title is printed on a line by itself with a line
4094 of asterisks underneath.  (@xref{chapter, , @code{@@chapter}}.)@refill
4095
4096 @node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
4097 @comment  node-name,  next,  previous,  up
4098 @section @code{@@section}
4099 @findex section
4100
4101 In a printed manual, an @code{@@section} command identifies a
4102 numbered section within a chapter.  The section title appears in the
4103 table of contents.  In Info, an @code{@@section} command provides a
4104 title for a segment of text, underlined with @samp{=}.@refill
4105
4106 This section is headed with an @code{@@section} command and looks like
4107 this in the Texinfo file:@refill
4108
4109 @example
4110 @@section @@code@{@@@@section@}
4111 @end example
4112
4113 To create a section, write the @code{@@section} command at the
4114 beginning of a line and follow it on the same line by the section
4115 title.@refill
4116
4117 Thus,
4118
4119 @example
4120 @@section This is a section
4121 @end example
4122
4123 @noindent
4124 produces
4125
4126 @example
4127 @group
4128 This is a section
4129 =================
4130 @end group
4131 @end example
4132
4133 @noindent
4134 in Info.
4135
4136 @node unnumberedsec appendixsec heading, subsection, section, Structuring
4137 @comment  node-name,  next,  previous,  up
4138 @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}