Reformatted.
[chise/xemacs-chise.git.1] / man / texinfo.texi
1 \input texinfo.tex    @c -*-texinfo-*-
2 @c $Id: texinfo.texi,v 1.14.4.1 2002/07/09 08:36:53 stephent Exp $
3 @c %**start of header
4
5 @c All text is ignored before the setfilename.
6 @setfilename ../info/texinfo.info
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 XEmacs User's
747 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}
4139 @findex unnumberedsec
4140 @findex appendixsec
4141 @findex heading
4142
4143 The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4144 commands are, respectively, the unnumbered, appendix-like, and
4145 heading-like equivalents of the @code{@@section} command.
4146 (@xref{section, , @code{@@section}}.)@refill
4147
4148 @table @code
4149 @item @@unnumberedsec
4150 The @code{@@unnumberedsec} command may be used within an
4151 unnumbered chapter or within a regular chapter or appendix to
4152 provide an unnumbered section.@refill
4153
4154 @item @@appendixsec
4155 @itemx @@appendixsection
4156 @code{@@appendixsection} is a longer spelling of the
4157 @code{@@appendixsec} command; the two are synonymous.@refill
4158 @findex appendixsection
4159
4160 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4161 command is used only within appendices.@refill
4162
4163 @item @@heading
4164 You may use the @code{@@heading} command anywhere you wish for a
4165 section-style heading that will not appear in the table of contents.@refill
4166 @end table
4167
4168 @node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
4169 @comment  node-name,  next,  previous,  up
4170 @section The @code{@@subsection} Command
4171 @findex subsection
4172
4173 Subsections are to sections as sections are to chapters.
4174 (@xref{section, , @code{@@section}}.)  In Info, subsection titles are
4175 underlined with @samp{-}.  For example,@refill
4176
4177 @example
4178 @@subsection This is a subsection
4179 @end example
4180
4181 @noindent
4182 produces
4183
4184 @example
4185 @group
4186 This is a subsection
4187 --------------------
4188 @end group
4189 @end example
4190
4191 In a printed manual, subsections are listed in the table of contents
4192 and are numbered three levels deep.@refill
4193
4194 @node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
4195 @comment  node-name,  next,  previous,  up
4196 @section The @code{@@subsection}-like Commands
4197 @cindex Subsection-like commands
4198 @findex unnumberedsubsec
4199 @findex appendixsubsec
4200 @findex subheading
4201
4202 The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4203 @code{@@subheading} commands are, respectively, the unnumbered,
4204 appendix-like, and heading-like equivalents of the @code{@@subsection}
4205 command.  (@xref{subsection, , @code{@@subsection}}.)@refill
4206
4207 In Info, the @code{@@subsection}-like commands generate a title
4208 underlined with hyphens.  In a printed manual, an @code{@@subheading}
4209 command produces a heading like that of a subsection except that it is
4210 not numbered and does not appear in the table of contents.  Similarly,
4211 an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4212 that of a subsection and an @code{@@appendixsubsec} command produces a
4213 subsection-like heading labelled with a letter and numbers; both of
4214 these commands produce headings that appear in the table of
4215 contents.@refill
4216
4217 @node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
4218 @comment  node-name,  next,  previous,  up
4219 @section The `subsub' Commands
4220 @cindex Subsub commands
4221 @findex subsubsection
4222 @findex unnumberedsubsubsec
4223 @findex appendixsubsubsec
4224 @findex subsubheading
4225
4226 The fourth and lowest level sectioning commands in Texinfo are the
4227 `subsub' commands.  They are:@refill
4228
4229 @table @code
4230 @item @@subsubsection
4231 Subsubsections are to subsections as subsections are to sections.
4232 (@xref{subsection, , @code{@@subsection}}.)  In a printed manual,
4233 subsubsection titles appear in the table of contents and are numbered
4234 four levels deep.@refill
4235
4236 @item @@unnumberedsubsubsec
4237 Unnumbered subsubsection titles appear in the table of contents of a
4238 printed manual, but lack numbers.  Otherwise, unnumbered
4239 subsubsections are the same as subsubsections.  In Info, unnumbered
4240 subsubsections look exactly like ordinary subsubsections.@refill
4241
4242 @item @@appendixsubsubsec
4243 Conventionally, appendix commands are used only for appendices and are
4244 lettered and numbered appropriately in a printed manual.  They also
4245 appear in the table of contents.  In Info, appendix subsubsections look
4246 exactly like ordinary subsubsections.@refill
4247
4248 @item @@subsubheading
4249 The @code{@@subsubheading} command may be used anywhere that you need
4250 a small heading that will not appear in the table of contents.  In
4251 Info, subsubheadings look exactly like ordinary subsubsection
4252 headings.@refill
4253 @end table
4254
4255 In Info,  `subsub' titles are underlined with periods.
4256 For example,@refill
4257
4258 @example
4259 @@subsubsection This is a subsubsection
4260 @end example
4261
4262 @noindent
4263 produces
4264
4265 @example
4266 @group
4267 This is a subsubsection
4268 .......................
4269 @end group
4270 @end example
4271
4272 @node Raise/lower sections,  , subsubsection, Structuring
4273 @comment  node-name,  next,  previous,  up
4274 @section @code{@@raisesections} and @code{@@lowersections}
4275 @findex raisesections
4276 @findex lowersections
4277 @cindex Raising and lowering sections
4278 @cindex Sections, raising and lowering
4279
4280 The @code{@@raisesections} and @code{@@lowersections} commands raise and
4281 lower the hierarchical level of chapters, sections, subsections and the
4282 like.  The @code{@@raisesections} command changes sections to chapters,
4283 subsections to sections, and so on.  The @code{@@lowersections} command
4284 changes chapters to sections, sections to subsections, and so on.
4285
4286 @cindex Include files, and section levels
4287 An @code{@@lowersections} command is useful if you wish to include text
4288 that is written as an outer or standalone Texinfo file in another
4289 Texinfo file as an inner, included file.  If you write the command at
4290 the beginning of the file, all your @code{@@chapter} commands are
4291 formatted as if they were @code{@@section} commands, all your
4292 @code{@@section} command are formatted as if they were
4293 @code{@@subsection} commands, and so on.
4294
4295 @need 1000
4296 @code{@@raisesections} raises a command one level in the chapter
4297 structuring hierarchy:@refill
4298
4299 @example
4300 @group
4301   @r{Change}           @r{To}
4302
4303 @@subsection     @@section,
4304 @@section        @@chapter,
4305 @@heading        @@chapheading,
4306           @r{etc.}
4307 @end group
4308 @end example
4309
4310 @need 1000
4311 @code{@@lowersections} lowers a command one level in the chapter
4312 structuring hierarchy:@refill
4313
4314 @example
4315 @group
4316   @r{Change}           @r{To}
4317
4318 @@chapter        @@section,
4319 @@subsection     @@subsubsection,
4320 @@heading        @@subheading,
4321           @r{etc.}
4322 @end group
4323 @end example
4324
4325 An @code{@@raisesections} or @code{@@lowersections} command changes only
4326 those structuring commands that follow the command in the Texinfo file.
4327 Write an @code{@@raisesections} or @code{@@lowersections} command on a
4328 line of its own.
4329
4330 An @code{@@lowersections} command cancels an @code{@@raisesections}
4331 command, and vice versa.  Typically, the commands are used like this:
4332
4333 @example
4334 @@lowersections
4335 @@include somefile.texi
4336 @@raisesections
4337 @end example
4338
4339 Without the @code{@@raisesections}, all the subsequent sections in your
4340 document will be lowered.
4341
4342 Repeated use of the commands continue to raise or lower the hierarchical
4343 level a step at a time.
4344
4345 An attempt to raise above `chapters' reproduces chapter commands; an
4346 attempt to lower below `subsubsections' reproduces subsubsection
4347 commands.
4348
4349 @node Nodes, Menus, Structuring, Top
4350 @comment  node-name,  next,  previous,  up
4351 @chapter Nodes
4352
4353 @dfn{Nodes} are the primary segments of a Texinfo file.  They do not
4354 themselves impose a hierarchic or any other kind of structure on a file.
4355 Nodes contain @dfn{node pointers} that name other nodes, and can contain
4356 @dfn{menus} which are lists of nodes.  In Info, the movement commands
4357 can carry you to a pointed-to node or to a node listed in a menu.  Node
4358 pointers and menus provide structure for Info files just as chapters,
4359 sections, subsections, and the like, provide structure for printed
4360 books.@refill
4361
4362 @menu
4363 * Two Paths::                   Different commands to structure
4364                                   Info output and printed output.
4365 * Node Menu Illustration::      A diagram, and sample nodes and menus.
4366 * node::                        How to write a node, in detail.
4367 * makeinfo Pointer Creation::   How to create node pointers with @code{makeinfo}.
4368 @end menu
4369
4370 @node Two Paths, Node Menu Illustration, Nodes, Nodes
4371 @ifinfo
4372 @heading Two Paths
4373 @end ifinfo
4374
4375 The node and menu commands and the chapter structuring commands are
4376 independent of each other:
4377
4378 @itemize @bullet
4379 @item
4380 In Info, node and menu commands provide structure.  The chapter
4381 structuring commands generate headings with different kinds of
4382 underlining---asterisks for chapters, hyphens for sections, and so on;
4383 they do nothing else.@refill
4384
4385 @item
4386 In @TeX{}, the chapter structuring commands generate chapter and section
4387 numbers and tables of contents.  The node and menu commands provide
4388 information for cross references; they do nothing else.@refill
4389 @end itemize
4390
4391 You can use node pointers and menus to structure an Info file any way
4392 you want; and you can write a Texinfo file so that its Info output has a
4393 different structure than its printed output.  However, most Texinfo
4394 files are written such that the structure for the Info output
4395 corresponds to the structure for the printed output.  It is not
4396 convenient to do otherwise.@refill
4397
4398 Generally, printed output is structured in a tree-like hierarchy in
4399 which the chapters are the major limbs from which the sections branch
4400 out.  Similarly, node pointers and menus are organized to create a
4401 matching structure in the Info output.@refill
4402
4403 @node Node Menu Illustration, node, Two Paths, Nodes
4404 @comment  node-name,  next,  previous,  up
4405 @section Node and Menu Illustration
4406
4407 Here is a copy of the diagram shown earlier that illustrates a Texinfo
4408 file with three chapters, each of which contains two sections.@refill
4409
4410 Note that the ``root'' is at the top of the diagram and the ``leaves''
4411 are at the bottom.  This is how such a diagram is drawn conventionally;
4412 it illustrates an upside-down tree.  For this reason, the root node is
4413 called the `Top' node, and `Up' node pointers carry you closer to the
4414 root.@refill
4415
4416 @example
4417 @group
4418                           Top
4419                            |
4420          -------------------------------------
4421         |                  |                  |
4422      Chapter 1          Chapter 2          Chapter 3
4423         |                  |                  |
4424      --------           --------           --------
4425     |        |         |        |         |        |
4426  Section  Section   Section  Section   Section  Section
4427    1.1      1.2       2.1      2.2       3.1      3.2
4428
4429 @end group
4430 @end example
4431
4432 Write the beginning of the node for Chapter 2 like this:@refill
4433
4434 @example
4435 @group
4436 @@node     Chapter 2,  Chapter 3, Chapter 1, top
4437 @@comment  node-name,  next,      previous,  up
4438 @end group
4439 @end example
4440
4441 @noindent
4442 This @code{@@node} line says that the name of this node is ``Chapter 2'', the
4443 name of the `Next' node is ``Chapter 3'', the name of the `Previous'
4444 node is ``Chapter 1'', and the name of the `Up' node is ``Top''.
4445
4446 @quotation
4447 @strong{Please Note:} `Next' refers to the next node at the same
4448 hierarchical level in the manual, not necessarily to the next node
4449 within the Texinfo file.  In the Texinfo file, the subsequent node may
4450 be at a lower level---a section-level node may follow a chapter-level
4451 node, and a subsection-level node may follow a section-level node.
4452 `Next' and `Previous' refer to nodes at the @emph{same} hierarchical
4453 level.  (The `Top' node contains the exception to this rule.  Since the
4454 `Top' node is the only node at that level, `Next' refers to the first
4455 following node, which is almost always a chapter or chapter-level
4456 node.)@refill
4457 @end quotation
4458
4459 To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
4460 2.  (@xref{Menus}.)  You would write the menu just
4461 before the beginning of Section 2.1, like this:@refill
4462
4463 @example
4464 @group
4465     @@menu
4466     * Sect. 2.1::    Description of this section.
4467     * Sect. 2.2::
4468     @@end menu
4469 @end group
4470 @end example
4471
4472 Write the node for Sect. 2.1 like this:@refill
4473
4474 @example
4475 @group
4476     @@node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4477     @@comment  node-name, next,      previous,  up
4478 @end group
4479 @end example
4480
4481 In Info format, the `Next' and `Previous' pointers of a node usually
4482 lead to other nodes at the same level---from chapter to chapter or from
4483 section to section (sometimes, as shown, the `Previous' pointer points
4484 up); an `Up' pointer usually leads to a node at the level above (closer
4485 to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4486 to `leaves').  (A cross reference can point to a node at any level;
4487 see @ref{Cross References}.)@refill
4488
4489 Usually, an @code{@@node} command and a chapter structuring command are
4490 used in sequence, along with indexing commands.  (You may follow the
4491 @code{@@node} line with a comment line that reminds you which pointer is
4492 which.)@refill
4493
4494 Here is the beginning of the chapter in this manual called ``Ending a
4495 Texinfo File''.  This shows an @code{@@node} line followed by a comment
4496 line, an @code{@@chapter} line, and then by indexing lines.@refill
4497
4498 @example
4499 @group
4500 @@node    Ending a File, Structuring, Beginning a File, Top
4501 @@comment node-name,     next,        previous,         up
4502 @@chapter Ending a Texinfo File
4503 @@cindex Ending a Texinfo file
4504 @@cindex Texinfo file ending
4505 @@cindex File ending
4506 @end group
4507 @end example
4508
4509 @node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes
4510 @comment  node-name,  next,  previous,  up
4511 @section The @code{@@node} Command
4512
4513 @cindex Node, defined
4514 A @dfn{node} is a segment of text that begins at an @code{@@node}
4515 command and continues until the next @code{@@node} command.  The
4516 definition of node is different from that for chapter or section.  A
4517 chapter may contain sections and a section may contain subsections;
4518 but a node cannot contain subnodes; the text of a node continues only
4519 until the next @code{@@node} command in the file.  A node usually
4520 contains only one chapter structuring command, the one that follows
4521 the @code{@@node} line.  On the other hand, in printed output nodes
4522 are used only for cross references, so a chapter or section may
4523 contain any number of nodes.  Indeed, a chapter usually contains
4524 several nodes, one for each section, subsection, and
4525 subsubsection.@refill
4526
4527 To create a node, write an @code{@@node} command at the beginning of a
4528 line, and follow it with four arguments, separated by commas, on the
4529 rest of the same line.  These arguments are the name of the node, and
4530 the names of the `Next', `Previous', and `Up' pointers, in that order.
4531 You may insert spaces before each pointer if you wish; the spaces are
4532 ignored.  You must write the name of the node, and the names of the
4533 `Next', `Previous', and `Up' pointers, all on the same line.  Otherwise,
4534 the formatters fail.  (@inforef{Top, info, info}, for more information
4535 about nodes in Info.)@refill
4536
4537 Usually, you write one of the chapter-structuring command lines
4538 immediately after an @code{@@node} line---for example, an
4539 @code{@@section} or @code{@@subsection} line.  (@xref{Structuring
4540 Command Types, , Types of Structuring Commands}.)@refill
4541
4542 @quotation
4543 @strong{Please note:} The GNU Emacs Texinfo mode updating commands work
4544 only with Texinfo files in which @code{@@node} lines are followed by chapter
4545 structuring lines.  @xref{Updating Requirements}.@refill
4546 @end quotation
4547
4548 @TeX{} uses @code{@@node} lines to identify the names to use for cross
4549 references.  For this reason, you must write @code{@@node} lines in a
4550 Texinfo file that you intend to format for printing, even if you do not
4551 intend to format it for Info.  (Cross references, such as the one at the
4552 end of this sentence, are made with @code{@@xref} and its related
4553 commands; see @ref{Cross References}.)@refill
4554
4555 @menu
4556 * Node Names::                  How to choose node and pointer names.
4557 * Writing a Node::              How to write an @code{@@node} line.
4558 * Node Line Tips::              Keep names short.
4559 * Node Line Requirements::      Keep names unique, without @@-commands.
4560 * First Node::                  How to write a `Top' node.
4561 * makeinfo top command::        How to use the @code{@@top} command.
4562 * Top Node Summary::            Write a brief description for readers.
4563 @end menu
4564
4565 @node Node Names, Writing a Node, node, node
4566 @ifinfo
4567 @subheading Choosing Node and Pointer Names
4568 @end ifinfo
4569
4570 The name of a node identifies the node.  The pointers enable
4571 you to reach other nodes and consist of the names of those nodes.@refill
4572
4573 Normally, a node's `Up' pointer contains the name of the node whose menu
4574 mentions that node.  The node's `Next' pointer contains the name of the
4575 node that follows that node in that menu and its `Previous' pointer
4576 contains the name of the node that precedes it in that menu.  When a
4577 node's `Previous' node is the same as its `Up' node, both node pointers
4578 name the same node.@refill
4579
4580 Usually, the first node of a Texinfo file is the `Top' node, and its
4581 `Up' and `Previous' pointers point to the @file{dir} file, which
4582 contains the main menu for all of Info.@refill
4583
4584 The `Top' node itself contains the main or master menu for the manual.
4585 Also, it is helpful to include a brief description of the manual in the
4586 `Top' node.  @xref{First Node}, for information on how to write the
4587 first node of a Texinfo file.@refill
4588
4589 @node Writing a Node, Node Line Tips, Node Names, node
4590 @comment  node-name,  next,  previous,  up
4591 @subsection How to Write an @code{@@node} Line
4592 @cindex Writing an @code{@@node} line
4593 @cindex @code{@@node} line writing
4594 @cindex Node line writing
4595
4596 The easiest way to write an @code{@@node} line is to write @code{@@node}
4597 at the beginning of a line and then the name of the node, like
4598 this:@refill
4599
4600 @example
4601 @@node @var{node-name}
4602 @end example
4603
4604 If you are using GNU Emacs, you can use the update node commands
4605 provided by Texinfo mode to insert the names of the pointers; or you
4606 can leave the pointers out of the Texinfo file and let @code{makeinfo}
4607 insert node pointers into the Info file it creates.  (@xref{Texinfo
4608 Mode}, and @ref{makeinfo Pointer Creation}.)@refill
4609
4610 Alternatively, you can insert the `Next', `Previous', and `Up'
4611 pointers yourself.  If you do this, you may find it helpful to use the
4612 Texinfo mode keyboard command @kbd{C-c C-c n}.  This command inserts
4613 @samp{@@node} and a comment line listing the names of the pointers in
4614 their proper order.  The comment line helps you keep track of which
4615 arguments are for which pointers.  This comment line is especially useful
4616 if you are not familiar with Texinfo.@refill
4617
4618 The template for a node line with `Next', `Previous', and `Up' pointers
4619 looks like this:@refill
4620
4621 @example
4622 @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4623 @end example
4624
4625 If you wish, you can ignore @code{@@node} lines altogether in your first
4626 draft and then use the @code{texinfo-insert-node-lines} command to
4627 create @code{@@node} lines for you.  However, we do not
4628 recommend this practice.  It is better to name the node itself
4629 at the same time that you
4630 write a segment so you can easily make cross references.  A large number
4631 of cross references are an especially important feature of a good Info
4632 file.@refill
4633
4634 After you have inserted an @code{@@node} line, you should immediately
4635 write an @@-command for the chapter or section and insert its name.
4636 Next (and this is important!), put in several index entries.  Usually,
4637 you will find at least two and often as many as four or five ways of
4638 referring to the node in the index.  Use them all.  This will make it
4639 much easier for people to find the node.@refill
4640
4641 @node Node Line Tips, Node Line Requirements, Writing a Node, node
4642 @comment  node-name,  next,  previous,  up
4643 @subsection @code{@@node} Line Tips
4644
4645 Here are three suggestions:
4646
4647 @itemize @bullet
4648 @item
4649 Try to pick node names that are informative but short.@refill
4650
4651 In the Info file, the file name, node name, and pointer names are all
4652 inserted on one line, which may run into the right edge of the window.
4653 (This does not cause a problem with Info, but is ugly.)@refill
4654
4655 @item
4656 Try to pick node names that differ from each other near the beginnings
4657 of their names.  This way, it is easy to use automatic name completion in
4658 Info.@refill
4659
4660 @item
4661 By convention, node names are capitalized just as they would be for
4662 section or chapter titles---initial and significant words are
4663 capitalized; others are not.@refill
4664 @end itemize
4665
4666 @node Node Line Requirements, First Node, Node Line Tips, node
4667 @comment  node-name,  next,  previous,  up
4668 @subsection @code{@@node} Line Requirements
4669
4670 @cindex Node line requirements
4671 Here are several requirements for @code{@@node} lines:
4672
4673 @itemize @bullet
4674 @cindex Unique nodename requirement
4675 @cindex Nodename must be unique
4676 @item
4677 All the node names for a single Info file must be unique.@refill
4678
4679 Duplicates confuse the Info movement commands.  This means, for
4680 example, that if you end every chapter with a summary, you must name
4681 each summary node differently.  You cannot just call each one
4682 ``Summary''.  You may, however, duplicate the titles of chapters, sections,
4683 and the like.  Thus you can end each chapter in a book with a section
4684 called ``Summary'', so long as the node names for those sections are all
4685 different.@refill
4686
4687 @item
4688 A pointer name must be the name of a node.@refill
4689
4690 The node to which a pointer points may come before or after the
4691 node containing the pointer.@refill
4692
4693 @cindex @@-command in nodename
4694 @cindex Nodename, cannot contain
4695 @item
4696 You cannot use any of the Texinfo @@-commands in a node name;
4697 @w{@@-commands} confuse Info.@refill
4698
4699 @need 750
4700 Thus, the beginning of the section called @code{@@chapter} looks like
4701 this:@refill
4702
4703 @smallexample
4704 @group
4705 @@node  chapter, unnumbered & appendix, makeinfo top, Structuring
4706 @@comment  node-name,  next,  previous,  up
4707 @@section @@code@{@@@@chapter@}
4708 @@findex chapter
4709 @end group
4710 @end smallexample
4711
4712 @cindex Comma in nodename
4713 @cindex Apostrophe in nodename
4714 @item
4715 You cannot use commas or apostrophes within a node name; these
4716 confuse @TeX{} or the Info formatters.@refill
4717
4718 @need 700
4719 For example, the following is a section title:
4720
4721 @smallexample
4722 @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
4723 @end smallexample
4724
4725 @noindent
4726 The corresponding node name is:
4727
4728 @smallexample
4729 unnumberedsec appendixsec heading
4730 @end smallexample
4731
4732 @cindex Case in nodename
4733 @item
4734 Case is significant.
4735 @end itemize
4736
4737
4738 @node First Node, makeinfo top command, Node Line Requirements, node
4739 @comment  node-name,  next,  previous,  up
4740 @subsection The First Node
4741 @cindex Top node is first
4742 @cindex First node
4743
4744 The first node of a Texinfo file is the @dfn{Top} node, except in an
4745 included file (@pxref{Include Files}).  The Top node contains the main
4746 or master menu for the document, and a short summary of the document
4747 (@pxref{Top Node Summary}).
4748
4749 @cindex Up node of Top node
4750 @cindex (dir) as Up node of Top node
4751 The Top node (which must be named @samp{top} or @samp{Top}) should have
4752 as its `Up' node the name of a node in another file, where there is a
4753 menu that leads to this file.  Specify the file name in parentheses.  If
4754 the file is to be installed directly in the Info directory file, use
4755 @samp{(dir)} as the parent of the Top node; this is short for
4756 @samp{(dir)top}, and specifies the Top node in the @file{dir} file,
4757 which contains the main menu for the Info system as a whole.  For
4758 example, the @code{@@node Top} line of this manual looks like this:
4759
4760 @example
4761 @@node Top, Copying, , (dir)
4762 @end example
4763
4764 @noindent
4765 (You can use the Texinfo updating commands or the @code{makeinfo}
4766 utility to insert these pointers automatically.)
4767
4768 @cindex Previous node of Top node
4769 Do not define the `Previous' node of the Top node to be @samp{(dir)}, as
4770 it causes confusing behavior for users: if you are in the Top node and
4771 hit @key{DEL} to go backwards, you wind up in the middle of some other
4772 entry in the @file{dir} file, which has nothing to do with what you were
4773 reading.
4774
4775 @xref{Install an Info File}, for more information about installing
4776 an Info file in the @file{info} directory.
4777
4778
4779 @node makeinfo top command, Top Node Summary, First Node, node
4780 @comment  node-name,  next,  previous,  up
4781 @subsection The @code{@@top} Sectioning Command
4782 @findex top @r{(@@-command)}
4783
4784 A special sectioning command, @code{@@top}, has been created for use
4785 with the @code{@@node Top} line.  The @code{@@top} sectioning command tells
4786 @code{makeinfo} that it marks the `Top' node in the file.  It provides
4787 the information that @code{makeinfo} needs to insert node
4788 pointers automatically.  Write the @code{@@top} command at the
4789 beginning of the line immediately following the @code{@@node Top}
4790 line.  Write the title on the remaining part of the same line as the
4791 @code{@@top} command.@refill
4792
4793 In Info, the @code{@@top} sectioning command causes the title to appear on a
4794 line by itself, with a line of asterisks inserted underneath.@refill
4795
4796 In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4797 sectioning command is merely a synonym for @code{@@unnumbered}.
4798 Neither of these formatters require an @code{@@top} command, and do
4799 nothing special with it.  You can use @code{@@chapter} or
4800 @code{@@unnumbered} after the @code{@@node Top} line when you use
4801 these formatters.  Also, you can use @code{@@chapter} or
4802 @code{@@unnumbered} when you use the Texinfo updating commands to
4803 create or update pointers and menus.@refill
4804
4805
4806 @node Top Node Summary,  , makeinfo top command, node
4807 @subsection The `Top' Node Summary
4808 @cindex @samp{@r{Top}} node summary
4809
4810 You can help readers by writing a summary in the `Top' node, after the
4811 @code{@@top} line, before the main or master menu.  The summary should
4812 briefly describe the document.  In Info, this summary will appear just
4813 before the master menu.  In a printed manual, this summary will appear
4814 on a page of its own.@refill
4815
4816 If you do not want the summary to appear on a page of its own in a
4817 printed manual, you can enclose the whole of the `Top' node, including
4818 the @code{@@node Top} line and the @code{@@top} sectioning command line
4819 or other sectioning command line between @code{@@ifinfo} and @code{@@end
4820 ifinfo}.  This prevents any of the text from appearing in the printed
4821 output. (@pxref{Conditionals, , Conditionally Visible Text}).  You can
4822 repeat the brief description from the `Top' node within @code{@@iftex}
4823 @dots{} @code{@@end iftex} at the beginning of the first chapter, for
4824 those who read the printed manual.  This saves paper and may look
4825 neater.@refill
4826
4827 You should write the version number of the program to which the manual
4828 applies in the summary.  This helps the reader keep track of which
4829 manual is for which version of the program.  If the manual changes more
4830 frequently than the program or is independent of it, you should also
4831 include an edition number for the manual.  (The title page should also
4832 contain this information: see @ref{titlepage, ,
4833 @code{@@titlepage}}.)@refill
4834
4835 @node makeinfo Pointer Creation,  , node, Nodes
4836 @section Creating Pointers with @code{makeinfo}
4837 @cindex Creating pointers with @code{makeinfo}
4838 @cindex Pointer creation with @code{makeinfo}
4839 @cindex Automatic pointer creation with @code{makeinfo}
4840
4841 The @code{makeinfo} program has a feature for automatically creating
4842 node pointers for a hierarchically organized file that lacks
4843 them.@refill
4844
4845 When you take advantage of this feature, you do not need to write the
4846 `Next', `Previous', and `Up' pointers after the name of a node.
4847 However, you must write a sectioning command, such as @code{@@chapter}
4848 or @code{@@section}, on the line immediately following each truncated
4849 @code{@@node} line.  You cannot write a comment line after a node
4850 line; the section line must follow it immediately.@refill
4851
4852 In addition, you must follow the `Top' @code{@@node} line with a line beginning
4853 with @code{@@top} to mark the `Top' node in the file. @xref{makeinfo
4854 top, , @code{@@top}}.
4855
4856 Finally, you must write the name of each node (except for the `Top'
4857 node) in a menu that is one or more hierarchical levels above the
4858 node's hierarchical level.@refill
4859
4860 This node pointer insertion feature in @code{makeinfo} is an
4861 alternative to the menu and pointer creation and update commands in
4862 Texinfo mode.  (@xref{Updating Nodes and Menus}.)  It is especially
4863 helpful to people who do not use GNU Emacs for writing Texinfo
4864 documents.@refill
4865
4866 @node Menus, Cross References, Nodes, Top
4867 @comment  node-name,  next,  previous,          up
4868 @chapter Menus
4869 @cindex Menus
4870 @findex menu
4871
4872 @dfn{Menus} contain pointers to subordinate
4873 nodes.@footnote{Menus can carry you to any node, regardless
4874 of the hierarchical structure; even to nodes in a different
4875 Info file.  However, the GNU Emacs Texinfo mode updating
4876 commands work only to create menus of subordinate nodes.
4877 Conventionally, cross references are used to refer to other
4878 nodes.} In Info, you use menus to go to such nodes.  Menus
4879 have no effect in printed manuals and do not appear in
4880 them.@refill
4881
4882 By convention, a menu is put at the end of a node since a reader who
4883 uses the menu may not see text that follows it.@refill
4884
4885 @ifinfo
4886 A node that has a menu should @emph{not} contain much text.  If you
4887 have a lot of text and a menu, move most of the text into a new
4888 subnode---all but a few lines.@refill
4889 @end ifinfo
4890 @iftex
4891 @emph{A node that has a menu should not contain much text.} If you
4892 have a lot of text and a menu, move most of the text into a new
4893 subnode---all but a few lines.  Otherwise, a reader with a terminal
4894 that displays only a few lines may miss the menu and its associated
4895 text.  As a practical matter, you should locate a menu within 20 lines
4896 of the beginning of the node.@refill
4897 @end iftex
4898
4899 @menu
4900 * Menu Location::               Put a menu in a short node.
4901 * Writing a Menu::              What is a menu?
4902 * Menu Parts::                  A menu entry has three parts.
4903 * Less Cluttered Menu Entry::   Two part menu entry.
4904 * Menu Example::                Two and three part menu entries.
4905 * Other Info Files::            How to refer to a different Info file.
4906 @end menu
4907
4908 @node Menu Location, Writing a Menu, Menus, Menus
4909 @ifinfo
4910 @heading Menus Need Short Nodes
4911 @end ifinfo
4912 @cindex Menu location
4913 @cindex Location of menus
4914 @cindex Nodes for menus are short
4915 @cindex Short nodes for menus
4916
4917 @ifinfo
4918 A reader can easily see a menu that is close to the beginning of the
4919 node.  The node should be short.  As a practical matter, you should
4920 locate a menu within 20 lines of the beginning of the node.
4921 Otherwise, a reader with a terminal that displays only a few lines may
4922 miss the menu and its associated text.@refill
4923 @end ifinfo
4924
4925 The short text before a menu may look awkward in a printed manual.  To
4926 avoid this, you can write a menu near the beginning of its node and
4927 follow the menu by an @code{@@node} line, and then an @code{@@heading}
4928 line located within @code{@@ifinfo} and @code{@@end ifinfo}.  This way,
4929 the menu, @code{@@node} line, and title appear only in the Info file,
4930 not the printed document.@refill
4931
4932 For example, the preceding two paragraphs follow an Info-only menu,
4933 @code{@@node} line, and heading, and look like this:@refill
4934
4935 @example
4936 @group
4937 @@menu
4938 * Menu Location::             Put a menu in a short node.
4939 * Writing a Menu::            What is a menu?
4940 * Menu Parts::                A menu entry has three parts.
4941 * Less Cluttered Menu Entry:: Two part menu entry.
4942 * Menu Example::              Two and three part entries.
4943 * Other Info Files::          How to refer to a different
4944                                 Info file.
4945 @@end menu
4946
4947 @@node Menu Location, Writing a Menu, , Menus
4948 @@ifinfo
4949 @@heading Menus Need Short Nodes
4950 @@end ifinfo
4951 @end group
4952 @end example
4953
4954 The Texinfo file for this document contains more than a dozen
4955 examples of this procedure.  One is at the beginning of this chapter;
4956 another is at the beginning of the ``Cross References'' chapter.@refill
4957
4958 @node Writing a Menu, Menu Parts, Menu Location, Menus
4959 @section Writing a Menu
4960 @cindex Writing a menu
4961 @cindex Menu writing
4962
4963 A menu consists of an @code{@@menu} command on a line by
4964 itself followed by menu entry lines or menu comment lines
4965 and then by an @code{@@end menu} command on a line by
4966 itself.@refill
4967
4968 A menu looks like this:@refill
4969
4970 @example
4971 @group
4972 @@menu
4973 Larger Units of Text
4974
4975 * Files::                       All about handling files.
4976 * Multiples: Buffers.           Multiple buffers; editing
4977                                   several files at once.
4978 @@end menu
4979 @end group
4980 @end example
4981
4982 In a menu, every line that begins with an @w{@samp{* }} is a
4983 @dfn{menu entry}.  (Note the space after the asterisk.)  A
4984 line that does not start with an @w{@samp{* }} may also
4985 appear in a menu.  Such a line is not a menu entry but is a
4986 menu comment line that appears in the Info file.  In
4987 the example above, the line @samp{Larger Units of Text} is a
4988 menu comment line; the two lines starting with @w{@samp{* }}
4989 are menu entries.
4990
4991 @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
4992 @section The Parts of a Menu
4993 @cindex Parts of a menu
4994 @cindex Menu parts
4995 @cindex @code{@@menu} parts
4996
4997 A menu entry has three parts, only the second of which is required:
4998
4999 @enumerate
5000 @item
5001 The menu entry name (optional).
5002
5003 @item
5004 The name of the node (required).
5005
5006 @item
5007 A description of the item (optional).
5008 @end enumerate
5009
5010 The template for a menu entry looks like this:@refill
5011
5012 @example
5013 * @var{menu-entry-name}: @var{node-name}.   @var{description}
5014 @end example
5015
5016 Follow the menu entry name with a single colon and follow the node name
5017 with tab, comma, period, or newline.@refill
5018
5019 In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5020 command.  The menu entry name is what the user types after the @kbd{m}
5021 command.@refill
5022
5023 The third part of a menu entry is a descriptive phrase or sentence.
5024 Menu entry names and node names are often short; the description
5025 explains to the reader what the node is about.  A useful description
5026 complements the node name rather than repeats it.  The description,
5027 which is optional, can spread over two or more lines; if it does, some
5028 authors prefer to indent the second line while others prefer to align it
5029 with the first (and all others).  It's up to you.
5030
5031
5032 @node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
5033 @comment  node-name,  next,  previous,  up
5034 @section Less Cluttered Menu Entry
5035 @cindex Two part menu entry
5036 @cindex Double-colon menu entries
5037 @cindex Menu entries with two colons
5038 @cindex Less cluttered menu entry
5039 @cindex Uncluttered menu entry
5040
5041 When the menu entry name and node name are the same, you can write
5042 the name immediately after the asterisk and space at the beginning of
5043 the line and follow the name with two colons.@refill
5044
5045 @need 800
5046 For example, write
5047
5048 @example
5049 * Name::                                    @var{description}
5050 @end example
5051
5052 @need 800
5053 @noindent
5054 instead of
5055
5056 @example
5057 * Name: Name.                               @var{description}
5058 @end example
5059
5060 You should use the node name for the menu entry name whenever possible,
5061 since it reduces visual clutter in the menu.@refill
5062
5063 @node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
5064 @comment  node-name,  next,  previous,  up
5065 @section A Menu Example
5066 @cindex Menu example
5067 @cindex Example menu
5068
5069 A menu looks like this in Texinfo:@refill
5070
5071 @example
5072 @group
5073 @@menu
5074 * menu entry name: Node name.   A short description.
5075 * Node name::                   This form is preferred.
5076 @@end menu
5077 @end group
5078 @end example
5079
5080 @need 800
5081 @noindent
5082 This produces:
5083
5084 @example
5085 @group
5086 * menu:
5087
5088 * menu entry name: Node name.   A short description.
5089 * Node name::                   This form is preferred.
5090 @end group
5091 @end example
5092
5093 @need 700
5094 Here is an example as you might see it in a Texinfo file:@refill
5095
5096 @example
5097 @group
5098 @@menu
5099 Larger Units of Text
5100
5101 * Files::                       All about handling files.
5102 * Multiples: Buffers.           Multiple buffers; editing
5103                                   several files at once.
5104 @@end menu
5105 @end group
5106 @end example
5107
5108 @need 800
5109 @noindent
5110 This produces:
5111
5112 @example
5113 @group
5114 * menu:
5115 Larger Units of Text
5116
5117 * Files::                       All about handling files.
5118 * Multiples: Buffers.           Multiple buffers; editing
5119                                   several files at once.
5120 @end group
5121 @end example
5122
5123 In this example, the menu has two entries.  @samp{Files} is both a menu
5124 entry name and the name of the node referred to by that name.
5125 @samp{Multiples} is the menu entry name; it refers to the node named
5126 @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5127 appears in the menu, but is not an entry.@refill
5128
5129 Since no file name is specified with either @samp{Files} or
5130 @samp{Buffers}, they must be the names of nodes in the same Info file
5131 (@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5132
5133 @node Other Info Files,  , Menu Example, Menus
5134 @comment  node-name,  next,  previous,  up
5135 @section Referring to Other Info Files
5136 @cindex Referring to other Info files
5137 @cindex Nodes in other Info files
5138 @cindex Other Info files' nodes
5139 @cindex Going to other Info files' nodes
5140 @cindex Info; other files' nodes
5141
5142 You can create a menu entry that enables a reader in Info to go to a
5143 node in another Info file by writing the file name in parentheses just
5144 before the node name.  In this case, you should use the three-part menu
5145 entry format, which saves the reader from having to type the file
5146 name.@refill
5147
5148 @need 800
5149 The format looks like this:@refill
5150
5151 @example
5152 @group
5153 @@menu
5154 * @var{first-entry-name}:(@var{filename})@var{nodename}.     @var{description}
5155 * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5156 @@end menu
5157 @end group
5158 @end example
5159
5160 For example, to refer directly to the @samp{Outlining} and
5161 @samp{Rebinding} nodes in the @cite{XEmacs User's Manual}, you would
5162 write a menu like this:@refill
5163
5164 @example
5165 @group
5166 @@menu
5167 * Outlining: (xemacs)Outline Mode. The major mode for
5168                                    editing outlines.
5169 * Rebinding: (xemacs)Rebinding.    How to redefine the
5170                                    meaning of a key.
5171 @@end menu
5172 @end group
5173 @end example
5174
5175 If you do not list the node name, but only name the file, then Info
5176 presumes that you are referring to the `Top' node.@refill
5177
5178 The @file{dir} file that contains the main menu for Info has menu
5179 entries that list only file names.  These take you directly to the `Top'
5180 nodes of each Info document.  (@xref{Install an Info File}.)@refill
5181
5182 @need 700
5183 For example:
5184
5185 @example
5186 @group
5187 * Info: (info).         Documentation browsing system.
5188 * Emacs: (emacs).       The extensible, self-documenting
5189                         text editor.
5190 @end group
5191 @end example
5192
5193 @noindent
5194 (The @file{dir} top level directory for the Info system is an Info file,
5195 not a Texinfo file, but a menu entry looks the same in both types of
5196 file.)@refill
5197
5198 Note that the GNU Emacs Texinfo mode menu updating commands only work
5199 with nodes within the current buffer, so you cannot use them to create
5200 menus that refer to other files.  You must write such menus by hand.@refill
5201
5202 @node Cross References, Marking Text, Menus, Top
5203 @comment  node-name,  next,  previous,  up
5204 @chapter Cross References
5205 @cindex Making cross references
5206 @cindex Cross references
5207 @cindex References
5208
5209 @dfn{Cross references} are used to refer the reader to other parts of the
5210 same or different Texinfo files.  In Texinfo, nodes are the
5211 places to which cross references can refer.@refill
5212
5213 @menu
5214 * References::                  What cross references are for.
5215 * Cross Reference Commands::    A summary of the different commands.
5216 * Cross Reference Parts::       A cross reference has several parts.
5217 * xref::                        Begin a reference with `See' @dots{}
5218 * Top Node Naming::             How to refer to the beginning of another file.
5219 * ref::                         A reference for the last part of a sentence.
5220 * pxref::                       How to write a parenthetical cross reference.
5221 * inforef::                     How to refer to an Info-only file.
5222 * uref::                        How to refer to a uniform resource locator.
5223 @end menu
5224
5225 @node References, Cross Reference Commands, Cross References, Cross References
5226 @ifinfo
5227 @heading What References Are For
5228 @end ifinfo
5229
5230 Often, but not always, a printed document should be designed so that
5231 it can be read sequentially.  People tire of flipping back and forth
5232 to find information that should be presented to them as they need
5233 it.@refill
5234
5235 However, in any document, some information will be too detailed for
5236 the current context, or incidental to it; use cross references to
5237 provide access to such information.  Also, an on-line help system or a
5238 reference manual is not like a novel; few read such documents in
5239 sequence from beginning to end.  Instead, people look up what they
5240 need.  For this reason, such creations should contain many cross
5241 references to help readers find other information that they may not
5242 have read.@refill
5243
5244 In a printed manual, a cross reference results in a page reference,
5245 unless it is to another manual altogether, in which case the cross
5246 reference names that manual.@refill
5247
5248 In Info, a cross reference results in an entry that you can follow using
5249 the Info @samp{f} command.  (@inforef{Help-Adv, Some advanced Info
5250 commands, info}.)@refill
5251
5252 The various cross reference commands use nodes to define cross
5253 reference locations.  This is evident in Info, in which a cross
5254 reference takes you to the specified node.  @TeX{} also uses nodes to
5255 define cross reference locations, but the action is less obvious.  When
5256 @TeX{} generates a DVI file, it records nodes' page numbers and
5257 uses the page numbers in making references.  Thus, if you are writing
5258 a manual that will only be printed, and will not be used on-line, you
5259 must nonetheless write @code{@@node} lines to name the places to which
5260 you make cross references.@refill
5261
5262 @need 800
5263 @node Cross Reference Commands, Cross Reference Parts, References, Cross References
5264 @comment  node-name,  next,  previous,  up
5265 @section Different Cross Reference Commands
5266 @cindex Different cross reference commands
5267
5268 There are four different cross reference commands:@refill
5269
5270 @table @code
5271 @item @@xref
5272 Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5273 or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5274
5275 @item @@ref
5276 Used within or, more often, at the end of a sentence; same as
5277 @code{@@xref} for Info; produces just the reference in the printed
5278 manual without a preceding `See'.@refill
5279
5280 @item @@pxref
5281 Used within parentheses to make a reference that suits both an Info
5282 file and a printed book.  Starts with a lower case `see' within the
5283 printed manual. (@samp{p} is for `parenthesis'.)@refill
5284
5285 @item @@inforef
5286 Used to make a reference to an Info file for which there is no printed
5287 manual.@refill
5288 @end table
5289
5290 @noindent
5291 (The @code{@@cite} command is used to make references to books and
5292 manuals for which there is no corresponding Info file and, therefore,
5293 no node to which to point.   @xref{cite, , @code{@@cite}}.)@refill
5294
5295 @node Cross Reference Parts, xref, Cross Reference Commands, Cross References
5296 @comment  node-name,  next,  previous,  up
5297 @section Parts of a Cross Reference
5298 @cindex Cross reference parts
5299 @cindex Parts of a cross reference
5300
5301 A cross reference command requires only one argument, which is the
5302 name of the node to which it refers.  But a cross reference command
5303 may contain up to four additional arguments.  By using these
5304 arguments, you can provide a cross reference name for Info, a topic
5305 description or section title for the printed output, the name of a
5306 different Info file, and the name of a different printed
5307 manual.@refill
5308
5309 Here is a simple cross reference example:@refill
5310
5311 @example
5312 @@xref@{Node name@}.
5313 @end example
5314
5315 @noindent
5316 which produces
5317
5318 @example
5319 *Note Node name::.
5320 @end example
5321
5322 @noindent
5323 and
5324
5325 @quotation
5326 See Section @var{nnn} [Node name], page @var{ppp}.
5327 @end quotation
5328
5329 @need 700
5330 Here is an example of a full five-part cross reference:@refill
5331
5332 @example
5333 @group
5334 @@xref@{Node name, Cross Reference Name, Particular Topic,
5335 info-file-name, A Printed Manual@}, for details.
5336 @end group
5337 @end example
5338
5339 @noindent
5340 which produces
5341
5342 @example
5343 *Note Cross Reference Name: (info-file-name)Node name,
5344 for details.
5345 @end example
5346
5347 @noindent
5348 in Info and
5349
5350 @quotation
5351 See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5352 @end quotation
5353
5354 @noindent
5355 in a printed book.
5356
5357 The five possible arguments for a cross reference are:@refill
5358
5359 @enumerate
5360 @item
5361 The node name (required).  This is the node to which the
5362 cross reference takes you.  In a printed document, the location of the
5363 node provides the page reference only for references within the same
5364 document.@refill
5365
5366 @item
5367 The cross reference name for the Info reference, if it is to be different
5368 from the node name.  If you include this argument, it becomes
5369 the first part of the cross reference.  It is usually omitted.@refill
5370
5371 @item
5372 A topic description or section name.  Often, this is the title of the
5373 section.  This is used as the name of the reference in the printed
5374 manual.  If omitted, the node name is used.@refill
5375
5376 @item
5377 The name of the Info file in which the reference is located, if it is
5378 different from the current file.  You need not include any @samp{.info}
5379 suffix on the file name, since Info readers try appending it
5380 automatically.
5381
5382 @item
5383 The name of a printed manual from a different Texinfo file.@refill
5384 @end enumerate
5385
5386 The template for a full five argument cross reference looks like
5387 this:@refill
5388
5389 @example
5390 @group
5391 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5392 @var{info-file-name}, @var{printed-manual-title}@}.
5393 @end group
5394 @end example
5395
5396 Cross references with one, two, three, four, and five arguments are
5397 described separately following the description of @code{@@xref}.@refill
5398
5399 Write a node name in a cross reference in exactly the same way as in
5400 the @code{@@node} line, including the same capitalization; otherwise, the
5401 formatters may not find the reference.@refill
5402
5403 You can write cross reference commands within a paragraph, but note
5404 how Info and @TeX{} format the output of each of the various commands:
5405 write @code{@@xref} at the beginning of a sentence; write
5406 @code{@@pxref} only within parentheses, and so on.@refill
5407
5408 @node xref, Top Node Naming, Cross Reference Parts, Cross References
5409 @comment  node-name,  next,  previous,  up
5410 @section @code{@@xref}
5411 @findex xref
5412 @cindex Cross references using @code{@@xref}
5413 @cindex References using @code{@@xref}
5414
5415 The @code{@@xref} command generates a cross reference for the
5416 beginning of a sentence.  The Info formatting commands convert it into
5417 an Info cross reference, which the Info @samp{f} command can use to
5418 bring you directly to another node.  The @TeX{} typesetting commands
5419 convert it into a page reference, or a reference to another book or
5420 manual.@refill
5421
5422 @menu
5423 * Reference Syntax::            What a reference looks like and requires.
5424 * One Argument::                @code{@@xref} with one argument.
5425 * Two Arguments::               @code{@@xref} with two arguments.
5426 * Three Arguments::             @code{@@xref} with three arguments.
5427 * Four and Five Arguments::     @code{@@xref} with four and five arguments.
5428 @end menu
5429
5430 @node Reference Syntax, One Argument, xref, xref
5431 @ifinfo
5432 @subheading What a Reference Looks Like and Requires
5433 @end ifinfo
5434
5435 Most often, an Info cross reference looks like this:@refill
5436
5437 @example
5438 *Note @var{node-name}::.
5439 @end example
5440
5441 @noindent
5442 or like this
5443
5444 @example
5445 *Note @var{cross-reference-name}: @var{node-name}.
5446 @end example
5447
5448 @noindent
5449 In @TeX{}, a cross reference looks like this:
5450
5451 @example
5452 See Section @var{section-number} [@var{node-name}], page @var{page}.
5453 @end example
5454
5455 @noindent
5456 or like this
5457
5458 @example
5459 See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5460 @end example
5461
5462 The @code{@@xref} command does not generate a period or comma to end
5463 the cross reference in either the Info file or the printed output.
5464 You must write that period or comma yourself; otherwise, Info will not
5465 recognize the end of the reference.  (The @code{@@pxref} command works
5466 differently.  @xref{pxref, , @code{@@pxref}}.)@refill
5467
5468 @quotation
5469 @strong{Please note:} A period or comma @strong{must} follow the closing
5470 brace of an @code{@@xref}.  It is required to terminate the cross
5471 reference.  This period or comma will appear in the output, both in
5472 the Info file and in the printed manual.@refill
5473 @end quotation
5474
5475 @code{@@xref} must refer to an Info node by name.  Use @code{@@node}
5476 to define the node (@pxref{Writing a Node}).@refill
5477
5478 @code{@@xref} is followed by several arguments inside braces, separated by
5479 commas.  Whitespace before and after these commas is ignored.@refill
5480
5481 A cross reference requires only the name of a node; but it may contain
5482 up to four additional arguments.  Each of these variations produces a
5483 cross reference that looks somewhat different.@refill
5484
5485 @quotation
5486 @strong{Please note:} Commas separate arguments in a cross reference;
5487 avoid including them in the title or other part lest the formatters
5488 mistake them for separators.@refill
5489 @end quotation
5490
5491 @node One Argument, Two Arguments, Reference Syntax, xref
5492 @subsection @code{@@xref} with One Argument
5493
5494 The simplest form of @code{@@xref} takes one argument, the name of
5495 another node in the same Info file.    The Info formatters produce
5496 output that the Info readers can use to jump to the reference; @TeX{}
5497 produces output that specifies the page and section number for you.@refill
5498
5499 @need 700
5500 @noindent
5501 For example,
5502
5503 @example
5504 @@xref@{Tropical Storms@}.
5505 @end example
5506
5507 @noindent
5508 produces
5509
5510 @example
5511 *Note Tropical Storms::.
5512 @end example
5513
5514 @noindent
5515 and
5516
5517 @quotation
5518 See Section 3.1 [Tropical Storms], page 24.
5519 @end quotation
5520
5521 @noindent
5522 (Note that in the preceding example the closing brace is followed by a
5523 period.)@refill
5524
5525 You can write a clause after the cross reference, like this:@refill
5526
5527 @example
5528 @@xref@{Tropical Storms@}, for more info.
5529 @end example
5530
5531 @noindent
5532 which produces
5533
5534 @example
5535 *Note Tropical Storms::, for more info.
5536 @end example
5537
5538 @quotation
5539 See Section 3.1 [Tropical Storms], page 24, for more info.
5540 @end quotation
5541
5542 @noindent
5543 (Note that in the preceding example the closing brace is followed by a
5544 comma, and then by the clause, which is followed by a period.)@refill
5545
5546 @node Two Arguments, Three Arguments, One Argument, xref
5547 @subsection @code{@@xref} with Two Arguments
5548
5549 With two arguments, the second is used as the name of the Info cross
5550 reference, while the first is still the name of the node to which the
5551 cross reference points.@refill
5552
5553 @need 750
5554 @noindent
5555 The template is like this:
5556
5557 @example
5558 @@xref@{@var{node-name}, @var{cross-reference-name}@}.
5559 @end example
5560
5561 @need 700
5562 @noindent
5563 For example,
5564
5565 @example
5566 @@xref@{Electrical Effects, Lightning@}.
5567 @end example
5568
5569 @noindent
5570 produces:
5571
5572 @example
5573 *Note Lightning: Electrical Effects.
5574 @end example
5575
5576 @noindent
5577 and
5578
5579 @quotation
5580 See Section 5.2 [Electrical Effects], page 57.
5581 @end quotation
5582
5583 @noindent
5584 (Note that in the preceding example the closing brace is followed by a
5585 period; and that the node name is printed, not the cross reference name.)@refill
5586
5587 You can write a clause after the cross reference, like this:@refill
5588
5589 @example
5590 @@xref@{Electrical Effects, Lightning@}, for more info.
5591 @end example
5592
5593 @noindent
5594 which produces
5595 @example
5596 *Note Lightning: Electrical Effects, for more info.
5597 @end example
5598
5599 @noindent
5600 and
5601
5602 @quotation
5603 See Section 5.2 [Electrical Effects], page 57, for more info.
5604 @end quotation
5605
5606 @noindent
5607 (Note that in the preceding example the closing brace is followed by a
5608 comma, and then by the clause, which is followed by a period.)@refill
5609
5610 @node Three Arguments, Four and Five Arguments, Two Arguments, xref
5611 @subsection @code{@@xref} with Three Arguments
5612
5613 A third argument replaces the node name in the @TeX{} output.  The third
5614 argument should be the name of the section in the printed output, or
5615 else state the topic discussed by that section.  Often, you will want to
5616 use initial upper case letters so it will be easier to read when the
5617 reference is printed.  Use a third argument when the node name is
5618 unsuitable because of syntax or meaning.@refill
5619
5620 Remember to avoid placing a comma within the title or topic section of
5621 a cross reference, or within any other section.  The formatters divide
5622 cross references into arguments according to the commas; a comma
5623 within a title or other section will divide it into two arguments.  In
5624 a reference, you need to write a title such as ``Clouds, Mist, and
5625 Fog'' without the commas.@refill
5626
5627 Also, remember to write a comma or period after the closing brace of a
5628 @code{@@xref} to terminate the cross reference.  In the following
5629 examples, a clause follows a terminating comma.@refill
5630
5631
5632 @need 750
5633 @noindent
5634 The template is like this:
5635
5636 @example
5637 @group
5638 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
5639 @end group
5640 @end example
5641
5642 @need 700
5643 @noindent
5644 For example,
5645
5646 @example
5647 @group
5648 @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
5649 for details.
5650 @end group
5651 @end example
5652
5653 @noindent
5654 produces
5655
5656 @example
5657 *Note Lightning: Electrical Effects, for details.
5658 @end example
5659
5660 @noindent
5661 and
5662
5663 @quotation
5664 See Section 5.2 [Thunder and Lightning], page 57, for details.
5665 @end quotation
5666
5667 If a third argument is given and the second one is empty, then the
5668 third argument serves both.  (Note how two commas, side by side, mark
5669 the empty second argument.)@refill
5670
5671 @example
5672 @group
5673 @@xref@{Electrical Effects, , Thunder and Lightning@},
5674 for details.
5675 @end group
5676 @end example
5677
5678 @noindent
5679 produces
5680
5681 @example
5682 *Note Thunder and Lightning: Electrical Effects, for details.
5683 @end example
5684
5685 @noindent
5686 and
5687
5688 @quotation
5689 See Section 5.2 [Thunder and Lightning], page 57, for details.
5690 @end quotation
5691
5692 As a practical matter, it is often best to write cross references with
5693 just the first argument if the node name and the section title are the
5694 same, and with the first and third arguments if the node name and title
5695 are different.@refill
5696
5697 Here are several examples from @cite{The GNU Awk User's Guide}:@refill
5698
5699 @smallexample
5700 @@xref@{Sample Program@}.
5701 @@xref@{Glossary@}.
5702 @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
5703 @@xref@{Close Output, , Closing Output Files and Pipes@},
5704    for more information.
5705 @@xref@{Regexp, , Regular Expressions as Patterns@}.
5706 @end smallexample
5707
5708 @node Four and Five Arguments,  , Three Arguments, xref
5709 @subsection @code{@@xref} with Four and Five Arguments
5710
5711 In a cross reference, a fourth argument specifies the name of another
5712 Info file, different from the file in which the reference appears, and
5713 a fifth argument specifies its title as a printed manual.@refill
5714
5715 Remember that a comma or period must follow the closing brace of an
5716 @code{@@xref} command to terminate the cross reference.  In the
5717 following examples, a clause follows a terminating comma.@refill
5718
5719 @need 800
5720 @noindent
5721 The template is:
5722
5723 @example
5724 @group
5725 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5726 @var{info-file-name}, @var{printed-manual-title}@}.
5727 @end group
5728 @end example
5729
5730 @need 700
5731 @noindent
5732 For example,
5733
5734 @example
5735 @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
5736 weather, An Introduction to Meteorology@}, for details.
5737 @end example
5738
5739 @noindent
5740 produces
5741
5742 @example
5743 *Note Lightning: (weather)Electrical Effects, for details.
5744 @end example
5745
5746 @noindent
5747 The name of the Info file is enclosed in parentheses and precedes
5748 the name of the node.
5749
5750 @noindent
5751 In a printed manual, the reference looks like this:@refill
5752
5753 @quotation
5754 See section ``Thunder and Lightning'' in @i{An Introduction to
5755 Meteorology}, for details.
5756 @end quotation
5757
5758 @noindent
5759 The title of the printed manual is typeset in italics; and the
5760 reference lacks a page number since @TeX{} cannot know to which page a
5761 reference refers when that reference is to another manual.@refill
5762
5763 Often, you will leave out the second argument when you use the long
5764 version of @code{@@xref}.  In this case, the third argument, the topic
5765 description, will be used as the cross reference name in Info.@refill
5766
5767 @noindent
5768 The template looks like this:
5769
5770 @example
5771 @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
5772 @var{printed-manual-title}@}, for details.
5773 @end example
5774
5775 @noindent
5776 which produces
5777
5778 @example
5779 *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
5780 @end example
5781
5782 @noindent
5783 and
5784
5785 @quotation
5786 See section @var{title-or-topic} in @var{printed-manual-title}, for details.
5787 @end quotation
5788
5789 @need 700
5790 @noindent
5791 For example,
5792
5793 @example
5794 @@xref@{Electrical Effects, , Thunder and Lightning,
5795 weather, An Introduction to Meteorology@}, for details.
5796 @end example
5797
5798 @noindent
5799 produces
5800
5801 @example
5802 @group
5803 *Note Thunder and Lightning: (weather)Electrical Effects,
5804 for details.
5805 @end group
5806 @end example
5807
5808 @noindent
5809 and
5810
5811 @quotation
5812 See section ``Thunder and Lightning'' in @i{An Introduction to
5813 Meteorology}, for details.
5814 @end quotation
5815
5816 On rare occasions, you may want to refer to another Info file that
5817 is within a single printed manual---when multiple Texinfo files are
5818 incorporated into the same @TeX{} run but make separate Info files.
5819 In this case, you need to specify only the fourth argument, and not
5820 the fifth.@refill
5821
5822 @node Top Node Naming, ref, xref, Cross References
5823 @section Naming a `Top' Node
5824 @cindex Naming a `Top' Node in references
5825 @cindex @samp{@r{Top}} node naming for references
5826
5827 In a cross reference, you must always name a node.  This means that in
5828 order to refer to a whole manual, you must identify the `Top' node by
5829 writing it as the first argument to the @code{@@xref} command.  (This
5830 is different from the way you write a menu entry; see @ref{Other Info
5831 Files, , Referring to Other Info Files}.)  At the same time, to
5832 provide a meaningful section topic or title in the printed cross
5833 reference (instead of the word `Top'), you must write an appropriate
5834 entry for the third argument to the @code{@@xref} command.
5835 @refill
5836
5837 @noindent
5838 Thus, to make a cross reference to @cite{The GNU Make Manual},
5839 write:@refill
5840
5841 @example
5842 @@xref@{Top, , Overview, make, The GNU Make Manual@}.
5843 @end example
5844
5845 @noindent
5846 which produces
5847
5848 @example
5849 *Note Overview: (make)Top.
5850 @end example
5851
5852 @noindent
5853 and
5854
5855 @quotation
5856 See section ``Overview'' in @i{The GNU Make Manual}.
5857 @end quotation
5858
5859 @noindent
5860 In this example, @samp{Top} is the name of the first node, and
5861 @samp{Overview} is the name of the first section of the manual.@refill
5862 @node ref, pxref, Top Node Naming, Cross References
5863 @comment  node-name,  next,  previous,  up
5864 @section @code{@@ref}
5865 @cindex Cross references using @code{@@ref}
5866 @cindex References using @code{@@ref}
5867 @findex ref
5868
5869 @code{@@ref} is nearly the same as @code{@@xref} except that it does
5870 not generate a `See' in the printed output, just the reference itself.
5871 This makes it useful as the last part of a sentence.@refill
5872
5873 @need 700
5874 @noindent
5875 For example,
5876
5877 @example
5878 For more information, see @@ref@{Hurricanes@}.
5879 @end example
5880
5881 @noindent
5882 produces
5883
5884 @example
5885 For more information, see *Note Hurricanes::.
5886 @end example
5887
5888 @noindent
5889 and
5890
5891 @quotation
5892 For more information, see Section 8.2 [Hurricanes], page 123.
5893 @end quotation
5894
5895 The @code{@@ref} command sometimes leads writers to express themselves
5896 in a manner that is suitable for a printed manual but looks awkward
5897 in the Info format.  Bear in mind that your audience will be using
5898 both the printed and the Info format.@refill
5899
5900 @need 800
5901 @noindent
5902 For example,
5903
5904 @example
5905 @group
5906 Sea surges are described in @@ref@{Hurricanes@}.
5907 @end group
5908 @end example
5909
5910 @need 800
5911 @noindent
5912 produces
5913
5914 @quotation
5915 Sea surges are described in Section 6.7 [Hurricanes], page 72.
5916 @end quotation
5917
5918 @need 800
5919 @noindent
5920 in a printed document, and the following in Info:
5921
5922 @example
5923 Sea surges are described in *Note Hurricanes::.
5924 @end example
5925
5926 @quotation
5927 @strong{Caution:} You @emph{must} write a period or comma immediately
5928 after an @code{@@ref} command with two or more arguments.  Otherwise,
5929 Info will not find the end of the cross reference entry and its
5930 attempt to follow the cross reference will fail.  As a general rule,
5931 you should write a period or comma after every @code{@@ref} command.
5932 This looks best in both the printed and the Info output.@refill
5933 @end quotation
5934
5935 @node pxref, inforef, ref, Cross References
5936 @comment  node-name,  next,  previous,  up
5937 @section @code{@@pxref}
5938 @cindex Cross references using @code{@@pxref}
5939 @cindex References using @code{@@pxref}
5940 @findex pxref
5941
5942 The parenthetical reference command, @code{@@pxref}, is nearly the
5943 same as @code{@@xref}, but you use it @emph{only} inside parentheses
5944 and you do @emph{not} type a comma or period after the command's
5945 closing brace.  The command differs from @code{@@xref} in two
5946 ways:@refill
5947
5948 @enumerate
5949 @item
5950 @TeX{} typesets the reference for the printed manual with a lower case
5951 `see' rather than an upper case `See'.@refill
5952
5953 @item
5954 The Info formatting commands automatically end the reference with a
5955 closing colon or period.@refill
5956 @end enumerate
5957
5958 Because one type of formatting automatically inserts closing
5959 punctuation and the other does not, you should use @code{@@pxref}
5960 @emph{only} inside parentheses as part of another sentence.  Also, you
5961 yourself should not insert punctuation after the reference, as you do
5962 with @code{@@xref}.@refill
5963
5964 @code{@@pxref} is designed so that the output looks right and works
5965 right between parentheses both in printed output and in an Info file.
5966 In a printed manual, a closing comma or period should not follow a
5967 cross reference within parentheses; such punctuation is wrong.  But in
5968 an Info file, suitable closing punctuation must follow the cross
5969 reference so Info can recognize its end.  @code{@@pxref} spares you
5970 the need to use complicated methods to put a terminator into one form
5971 of the output and not the other.@refill
5972
5973 @noindent
5974 With one argument, a parenthetical cross reference looks like
5975 this:@refill
5976
5977 @example
5978 @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
5979 @end example
5980
5981 @need 800
5982 @noindent
5983 which produces
5984
5985 @example
5986 @group
5987 @dots{} storms cause flooding (*Note Hurricanes::) @dots{}
5988 @end group
5989 @end example
5990
5991 @noindent
5992 and
5993
5994 @quotation
5995 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
5996 @end quotation
5997
5998 With two arguments, a parenthetical cross reference has this
5999 template:@refill
6000
6001 @example
6002 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6003 @end example
6004
6005 @noindent
6006 which produces
6007
6008 @example
6009 @dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
6010 @end example
6011
6012 @noindent
6013 and
6014
6015 @need 1500
6016 @quotation
6017 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6018 @end quotation
6019
6020 @code{@@pxref} can be used with up to five arguments just like
6021 @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
6022
6023 @quotation
6024 @strong{Please note:} Use @code{@@pxref} only as a parenthetical
6025 reference.  Do not try to use @code{@@pxref} as a clause in a sentence.
6026 It will look bad in either the Info file, the printed output, or
6027 both.@refill
6028
6029 Also, parenthetical cross references look best at the ends of sentences.
6030 Although you may write them in the middle of a sentence, that location
6031 breaks up the flow of text.@refill
6032 @end quotation
6033
6034 @node inforef, uref, pxref, Cross References
6035 @section @code{@@inforef}
6036 @cindex Cross references using @code{@@inforef}
6037 @cindex References using @code{@@inforef}
6038 @findex inforef
6039
6040 @code{@@inforef} is used for cross references to Info files for which
6041 there are no printed manuals.  Even in a printed manual,
6042 @code{@@inforef} generates a reference directing the user to look in
6043 an Info file.@refill
6044
6045 The command takes either two or three arguments, in the following
6046 order:@refill
6047
6048 @enumerate
6049 @item
6050 The node name.
6051
6052 @item
6053 The cross reference name (optional).
6054
6055 @item
6056 The Info file name.
6057 @end enumerate
6058
6059 @noindent
6060 Separate the arguments with commas, as with @code{@@xref}.  Also, you
6061 must terminate the reference with a comma or period after the
6062 @samp{@}}, as you do with @code{@@xref}.@refill
6063
6064 @noindent
6065 The template is:
6066
6067 @example
6068 @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6069 @end example
6070
6071 @need 800
6072 @noindent
6073 Thus,
6074
6075 @example
6076 @group
6077 @@inforef@{Expert, Advanced Info commands, info@},
6078 for more information.
6079 @end group
6080 @end example
6081
6082 @need 800
6083 @noindent
6084 produces
6085
6086 @example
6087 @group
6088 *Note Advanced Info commands: (info)Expert,
6089 for more information.
6090 @end group
6091 @end example
6092
6093 @need 800
6094 @noindent
6095 and
6096
6097 @quotation
6098 See Info file @file{info}, node @samp{Expert}, for more information.
6099 @end quotation
6100
6101 @need 800
6102 @noindent
6103 Similarly,
6104
6105 @example
6106 @group
6107 @@inforef@{Expert, , info@}, for more information.
6108 @end group
6109 @end example
6110
6111 @need 800
6112 @noindent
6113 produces
6114
6115 @example
6116 *Note (info)Expert::, for more information.
6117 @end example
6118
6119 @need 800
6120 @noindent
6121 and
6122
6123 @quotation
6124 See Info file @file{info}, node @samp{Expert}, for more information.
6125 @end quotation
6126
6127 The converse of @code{@@inforef} is @code{@@cite}, which is used to
6128 refer to printed works for which no Info form exists.  @xref{cite, ,
6129 @code{@@cite}}.@refill
6130
6131
6132 @node uref,  , inforef, Cross References
6133 @section @code{@@uref@{@var{url}[, @var{displayed-text}]@}}
6134 @findex uref
6135 @cindex Uniform resource locator, referring to
6136 @cindex URL, referring to
6137
6138 @code{@@uref} produces a reference to a uniform resource locator (URL).
6139 It takes one mandatory argument, the URL, and one optional argument, the
6140 text to display (the default is the URL itself).  In HTML output,
6141 @code{@@uref} produces a link you can follow.  For example:
6142
6143 @example
6144 The official GNU ftp site is
6145 @@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@}
6146 @end example
6147
6148 @noindent
6149 produces (in text):
6150 @display
6151 The official GNU ftp site is
6152 @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
6153 @end display
6154
6155 @noindent
6156 whereas
6157 @example
6158 The official
6159 @@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
6160   GNU ftp site@} holds programs and texts.
6161 @end example
6162
6163 @noindent
6164 produces (in text):
6165 @display
6166 The official @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, GNU ftp site} holds
6167 programs and texts.
6168 @end display
6169
6170 @noindent
6171 and (in HTML):
6172 @example
6173 The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
6174 site</A> holds programs and texts.
6175 @end example
6176
6177 To merely indicate a URL, use @code{@@url} (@pxref{url, @code{@@url}}).
6178
6179
6180 @node Marking Text, Quotations and Examples, Cross References, Top
6181 @comment  node-name,  next,  previous,  up
6182 @chapter Marking Words and Phrases
6183 @cindex Paragraph, marking text within
6184 @cindex Marking words and phrases
6185 @cindex Words and phrases, marking them
6186 @cindex Marking text within a paragraph
6187
6188 In Texinfo, you can mark words and phrases in a variety of ways.
6189 The Texinfo formatters use this information to determine how to
6190 highlight the text.
6191 You can specify, for example, whether a word or phrase is a
6192 defining occurrence, a metasyntactic variable, or a symbol used in a
6193 program.  Also, you can emphasize text.@refill
6194
6195 @menu
6196 * Indicating::                  How to indicate definitions, files, etc.
6197 * Emphasis::                    How to emphasize text.
6198 @end menu
6199
6200 @node Indicating, Emphasis, Marking Text, Marking Text
6201 @comment  node-name,  next,  previous,  up
6202 @section Indicating Definitions, Commands, etc.
6203 @cindex Highlighting text
6204 @cindex Indicating commands, definitions, etc.
6205
6206 Texinfo has commands for indicating just what kind of object a piece of
6207 text refers to.  For example, metasyntactic variables are marked by
6208 @code{@@var}, and code by @code{@@code}.  Since the pieces of text are
6209 labelled by commands that tell what kind of object they are, it is easy
6210 to change the way the Texinfo formatters prepare such text.  (Texinfo is
6211 an @emph{intentional} formatting language rather than a @emph{typesetting}
6212 formatting language.)@refill
6213
6214 For example, in a printed manual,
6215 code is usually illustrated in a typewriter font;
6216 @code{@@code} tells @TeX{} to typeset this text in this font.  But it
6217 would be easy to change the way @TeX{} highlights code to use another
6218 font, and this change would not effect how keystroke examples are
6219 highlighted.  If straight typesetting commands were used in the body
6220 of the file and you wanted to make a change, you would need to check
6221 every single occurrence to make sure that you were changing code and
6222 not something else that should not be changed.@refill
6223
6224 @menu
6225 * Useful Highlighting::         Highlighting provides useful information.
6226 * code::                        How to indicate code.
6227 * kbd::                         How to show keyboard input.
6228 * key::                         How to specify keys.
6229 * samp::                        How to show a literal sequence of characters.
6230 * var::                         How to indicate a metasyntactic variable.
6231 * file::                        How to indicate the name of a file.
6232 * dfn::                         How to specify a definition.
6233 * cite::                        How to refer to a book that is not in Info.
6234 * url::                         How to indicate a world wide web reference.
6235 * email::                       How to indicate an electronic mail address.
6236 @end menu
6237
6238 @node Useful Highlighting, code, Indicating, Indicating
6239 @ifinfo
6240 @subheading Highlighting Commands are Useful
6241 @end ifinfo
6242
6243 The highlighting commands can be used to generate useful information
6244 from the file, such as lists of functions or file names.  It is
6245 possible, for example, to write a program in Emacs Lisp (or a keyboard
6246 macro) to insert an index entry after every paragraph that contains
6247 words or phrases marked by a specified command.  You could do this to
6248 construct an index of functions if you had not already made the
6249 entries.@refill
6250
6251 The commands serve a variety of purposes:@refill
6252
6253 @table @code
6254 @item @@code@{@var{sample-code}@}
6255 Indicate text that is a literal example of a piece of a program.@refill
6256
6257 @item @@kbd@{@var{keyboard-characters}@}
6258 Indicate keyboard input.@refill
6259
6260 @item @@key@{@var{key-name}@}
6261 Indicate the conventional name for a key on a keyboard.@refill
6262
6263 @item @@samp@{@var{text}@}
6264 Indicate text that is a literal example of a sequence of characters.@refill
6265
6266 @item @@var@{@var{metasyntactic-variable}@}
6267 Indicate a metasyntactic variable.@refill
6268
6269 @item @@url@{@var{uniform-resource-locator}@}
6270 Indicate a uniform resource locator for the World Wide Web.
6271
6272 @item @@file@{@var{file-name}@}
6273 Indicate the name of a file.@refill
6274
6275 @item @@email@{@var{email-address}[, @var{displayed-text}]@}
6276 Indicate an electronic mail address.
6277
6278 @item @@dfn@{@var{term}@}
6279 Indicate the introductory or defining use of a term.@refill
6280
6281 @item @@cite@{@var{reference}@}
6282 Indicate the name of a book.@refill
6283
6284 @ignore
6285 @item @@ctrl@{@var{ctrl-char}@}
6286 Use for an @sc{ascii} control character.@refill
6287 @end ignore
6288 @end table
6289
6290 @node code, kbd, Useful Highlighting, Indicating
6291 @comment  node-name,  next,  previous,  up
6292 @subsection @code{@@code}@{@var{sample-code}@}
6293 @findex code
6294
6295 Use the @code{@@code} command to indicate text that is a piece of a
6296 program and which consists of entire syntactic tokens.  Enclose the
6297 text in braces.@refill
6298
6299 Thus, you should use @code{@@code} for an expression in a program, for
6300 the name of a variable or function used in a program, or for a
6301 keyword.  Also, you should use @code{@@code} for the name of a
6302 program, such as @code{diff}, that is a name used in the machine. (You
6303 should write the name of a program in the ordinary text font if you
6304 regard it as a new English word, such as `Emacs' or `Bison'.)@refill
6305
6306 Use @code{@@code} for environment variables such as @code{TEXINPUTS},
6307 and other variables.@refill
6308
6309 Use @code{@@code} for command names in command languages that
6310 resemble programming languages, such as Texinfo or the shell.
6311 For example, @code{@@code} and @code{@@samp} are produced by writing
6312 @samp{@@code@{@@@@code@}} and @samp{@@code@{@@@@samp@}} in the Texinfo
6313 source, respectively.@refill
6314
6315 Note, however, that you should not use @code{@@code} for shell options
6316 such as @samp{-c} when such options stand alone. (Use @code{@@samp}.)
6317 Also, an entire shell command often looks better if written using
6318 @code{@@samp} rather than @code{@@code}.  In this case, the rule is to
6319 choose the more pleasing format.@refill
6320
6321 It is incorrect to alter the case of a word inside an @code{@@code}
6322 command when it appears at the beginning of a sentence.  Most computer
6323 languages are case sensitive.  In C, for example, @code{Printf} is
6324 different from the identifier @code{printf}, and most likely is a
6325 misspelling of it.  Even in languages which are not case sensitive, it
6326 is confusing to a human reader to see identifiers spelled in different
6327 ways.  Pick one spelling and always use that.  If you do not want to
6328 start a sentence with a command written all in lower case, you should
6329 rearrange the sentence.@refill
6330
6331 Do not use the @code{@@code} command for a string of characters shorter
6332 than a syntactic token.  If you are writing about @samp{TEXINPU}, which
6333 is just a part of the name for the @code{TEXINPUTS} environment
6334 variable, you should use @code{@@samp}.@refill
6335
6336 In particular, you should not use the @code{@@code} command when writing
6337 about the characters used in a token; do not, for example, use
6338 @code{@@code} when you are explaining what letters or printable symbols
6339 can be used in the names of functions.  (Use @code{@@samp}.)  Also, you
6340 should not use @code{@@code} to mark text that is considered input to
6341 programs unless the input is written in a language that is like a
6342 programming language.  For example, you should not use @code{@@code} for
6343 the keystroke commands of GNU Emacs (use @code{@@kbd} instead) although
6344 you may use @code{@@code} for the names of the Emacs Lisp functions that
6345 the keystroke commands invoke.@refill
6346
6347 In the printed manual, @code{@@code} causes @TeX{} to typeset the
6348 argument in a typewriter face.  In the Info file, it causes the Info
6349 formatting commands to use single quotation marks around the text.
6350
6351 @need 700
6352 For example,
6353
6354 @example
6355 Use @@code@{diff@} to compare two files.
6356 @end example
6357
6358 @noindent
6359 produces this in the printed manual:@refill
6360
6361 @quotation
6362 Use @code{diff} to compare two files.
6363 @end quotation
6364 @iftex
6365
6366 @noindent
6367 and this in the Info file:@refill
6368
6369 @example
6370 Use `diff' to compare two files.
6371 @end example
6372 @end iftex
6373
6374
6375 @node kbd, key, code, Indicating
6376 @subsection @code{@@kbd}@{@var{keyboard-characters}@}
6377 @findex kbd
6378 @cindex keyboard input
6379
6380 Use the @code{@@kbd} command for characters of input to be typed by
6381 users.  For example, to refer to the characters @kbd{M-a},
6382 write@refill
6383
6384 @example
6385 @@kbd@{M-a@}
6386 @end example
6387
6388 @noindent
6389 and to refer to the characters @kbd{M-x shell}, write@refill
6390
6391 @example
6392 @@kbd@{M-x shell@}
6393 @end example
6394
6395 @cindex user input
6396 @cindex slanted typewriter font, for @code{@@kbd}
6397 The @code{@@kbd} command has the same effect as @code{@@code} in Info,
6398 but by default produces a different font (slanted typewriter instead of
6399 normal typewriter) in the printed manual, so users can distinguish the
6400 characters they are supposed to type from those the computer outputs.
6401
6402 @findex kbdinputstyle
6403 Since the usage of @code{@@kbd} varies from manual to manual, you can
6404 control the font switching with the @code{@@kbdinputstyle} command.
6405 This command has no effect on Info output.  Write this command at the
6406 beginning of a line with a single word as an argument, one of the
6407 following:
6408 @vindex distinct@r{, arg to @@kbdinputstyle}
6409 @vindex example@r{, arg to @@kbdinputstyle}
6410 @vindex code@r{, arg to @@kbdinputstyle}
6411 @table @samp
6412 @item code
6413 Always use the same font for @code{@@kbd} as @code{@@code}.
6414 @item example
6415 Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6416 and similar environments.
6417 @item example
6418 (the default) Always use the distinguishing font for @code{@@kbd}.
6419 @end table
6420
6421 You can embed another @@-command inside the braces of an @code{@@kbd}
6422 command.  Here, for example, is the way to describe a command that
6423 would be described more verbosely as ``press an @samp{r} and then
6424 press the @key{RET} key'':@refill
6425
6426 @example
6427 @@kbd@{r @@key@{RET@}@}
6428 @end example
6429
6430 @noindent
6431 This produces: @kbd{r @key{RET}}
6432
6433 You also use the @code{@@kbd} command if you are spelling out the letters
6434 you type; for example:@refill
6435
6436 @example
6437 To give the @@code@{logout@} command,
6438 type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6439 @end example
6440
6441 @noindent
6442 This produces:
6443
6444 @quotation
6445 To give the @code{logout} command,
6446 type the characters @kbd{l o g o u t @key{RET}}.
6447 @end quotation
6448
6449 (Also, this example shows that you can add spaces for clarity.  If you
6450 really want to mention a space character as one of the characters of
6451 input, write @kbd{@@key@{SPC@}} for it.)@refill
6452
6453
6454 @node key, samp, kbd, Indicating
6455 @comment  node-name,  next,  previous,  up
6456 @subsection @code{@@key}@{@var{key-name}@}
6457 @findex key
6458
6459 Use the @code{@@key} command for the conventional name for a key on a
6460 keyboard, as in:@refill
6461
6462 @example
6463 @@key@{RET@}
6464 @end example
6465
6466 You can use the @code{@@key} command within the argument of an
6467 @code{@@kbd} command when the sequence of characters to be typed
6468 includes one or more keys that are described by name.@refill
6469
6470 @need 700
6471 For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
6472
6473 @example
6474 @@kbd@{C-x @@key@{ESC@}@}
6475 @end example
6476
6477 Here is a list of the recommended names for keys:
6478 @cindex Recommended names for keys
6479 @cindex Keys, recommended names
6480 @cindex Names recommended for keys
6481 @cindex Abbreviations for keys
6482
6483 @quotation
6484 @table @t
6485 @item SPC
6486 Space
6487 @item RET
6488 Return
6489 @item LFD
6490 Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
6491 it might be better to call this character @kbd{C-j}.
6492 @item TAB
6493 Tab
6494 @item BS
6495 Backspace
6496 @item ESC
6497 Escape
6498 @item DEL
6499 Delete
6500 @item SHIFT
6501 Shift
6502 @item CTRL
6503 Control
6504 @item META
6505 Meta
6506 @end table
6507 @end quotation
6508
6509 @cindex META key
6510 There are subtleties to handling words like `meta' or `ctrl' that are
6511 names of modifier keys.  When mentioning a character in which the
6512 modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
6513 alone; do not use the @code{@@key} command; but when you are referring
6514 to the modifier key in isolation, use the @code{@@key} command.  For
6515 example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
6516 @samp{@@key@{META@}} to produce @key{META}.
6517
6518 @c I don't think this is a good explanation.
6519 @c I think it will puzzle readers more than it clarifies matters.  -- rms.
6520 @c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
6521 @c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
6522 @c the beginning of the sentence.  The @code{@@key@{META@}} key is often in
6523 @c the lower left of the keyboard.''@refill
6524
6525 @node samp, var, key, Indicating
6526 @comment  node-name,  next,  previous,  up
6527 @subsection @code{@@samp}@{@var{text}@}
6528 @findex samp
6529
6530 Use the @code{@@samp} command to indicate text that is a literal example
6531 or `sample' of a sequence of characters in a file, string, pattern, etc.
6532 Enclose the text in braces.  The argument appears within single
6533 quotation marks in both the Info file and the printed manual; in
6534 addition, it is printed in a fixed-width font.@refill
6535
6536 @example
6537 To match @@samp@{foo@} at the end of the line,
6538 use the regexp @@samp@{foo$@}.
6539 @end example
6540
6541 @noindent
6542 produces
6543
6544 @quotation
6545 To match @samp{foo} at the end of the line, use the regexp
6546 @samp{foo$}.@refill
6547 @end quotation
6548
6549 Any time you are referring to single characters, you should use
6550 @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
6551 Use @code{@@samp} for the names of command-line options (except in an
6552 @code{@@table}, where @code{@@code} seems to read more easily).  Also,
6553 you may use @code{@@samp} for entire statements in C and for entire
6554 shell commands---in this case, @code{@@samp} often looks better than
6555 @code{@@code}.  Basically, @code{@@samp} is a catchall for whatever is
6556 not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
6557
6558 Only include punctuation marks within braces if they are part of the
6559 string you are specifying.  Write punctuation marks outside the braces
6560 if those punctuation marks are part of the English text that surrounds
6561 the string.  In the following sentence, for example, the commas and
6562 period are outside of the braces:@refill
6563
6564 @example
6565 @group
6566 In English, the vowels are @@samp@{a@}, @@samp@{e@},
6567 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
6568 @@samp@{y@}.
6569 @end group
6570 @end example
6571
6572 @noindent
6573 This produces:
6574
6575 @quotation
6576 In English, the vowels are @samp{a}, @samp{e},
6577 @samp{i}, @samp{o}, @samp{u},  and sometimes
6578 @samp{y}.
6579 @end quotation
6580
6581 @node var, file, samp, Indicating
6582 @comment  node-name,  next,  previous,  up
6583 @subsection @code{@@var}@{@var{metasyntactic-variable}@}
6584 @findex var
6585
6586 Use the @code{@@var} command to indicate metasyntactic variables.  A
6587 @dfn{metasyntactic variable} is something that stands for another piece of
6588 text.  For example, you should use a metasyntactic variable in the
6589 documentation of a function to describe the arguments that are passed
6590 to that function.@refill
6591
6592 Do not use @code{@@var} for the names of particular variables in
6593 programming languages.  These are specific names from a program, so
6594 @code{@@code} is correct for them.  For example, the Emacs Lisp variable
6595 @code{texinfo-tex-command} is not a metasyntactic variable; it is
6596 properly formatted using @code{@@code}.@refill
6597
6598 The effect of @code{@@var} in the Info file is to change the case of
6599 the argument to all upper case; in the printed manual, to italicize it.
6600
6601 @need 700
6602 For example,
6603
6604 @example
6605 To delete file @@var@{filename@},
6606 type @@code@{rm @@var@{filename@}@}.
6607 @end example
6608
6609 @noindent
6610 produces
6611
6612 @quotation
6613 To delete file @var{filename}, type @code{rm @var{filename}}.
6614 @end quotation
6615
6616 @noindent
6617 (Note that @code{@@var} may appear inside @code{@@code},
6618 @code{@@samp}, @code{@@file}, etc.)@refill
6619
6620 Write a metasyntactic variable all in lower case without spaces, and
6621 use hyphens to make it more readable.  Thus, the Texinfo source for
6622 the illustration of how to begin a Texinfo manual looks like
6623 this:@refill
6624
6625 @example
6626 @group
6627 \input texinfo
6628 @@@@setfilename @@var@{info-file-name@}
6629 @@@@settitle @@var@{name-of-manual@}
6630 @end group
6631 @end example
6632
6633 @noindent
6634 This produces:
6635
6636 @example
6637 @group
6638 \input texinfo
6639 @@setfilename @var{info-file-name}
6640 @@settitle @var{name-of-manual}
6641 @end group
6642 @end example
6643
6644 In some documentation styles, metasyntactic variables are shown with
6645 angle brackets, for example:@refill
6646
6647 @example
6648 @dots{}, type rm <filename>
6649 @end example
6650
6651 @noindent
6652 However, that is not the style that Texinfo uses.  (You can, of
6653 course, modify the sources to @TeX{} and the Info formatting commands
6654 to output the @code{<@dots{}>} format if you wish.)@refill
6655
6656 @node file, dfn, var, Indicating
6657 @comment  node-name,  next,  previous,  up
6658 @subsection @code{@@file}@{@var{file-name}@}
6659 @findex file
6660
6661 Use the @code{@@file} command to indicate text that is the name of a
6662 file, buffer, or directory, or is the name of a node in Info.  You can
6663 also use the command for file name suffixes.  Do not use @code{@@file}
6664 for symbols in a programming language; use @code{@@code}.
6665
6666 Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
6667 For example,@refill
6668
6669 @example
6670 The @@file@{.el@} files are in
6671 the @@file@{/usr/local/emacs/lisp@} directory.
6672 @end example
6673
6674 @noindent
6675 produces
6676
6677 @quotation
6678 The @file{.el} files are in
6679 the @file{/usr/local/emacs/lisp} directory.
6680 @end quotation
6681
6682 @node dfn, cite, file, Indicating
6683 @comment  node-name,  next,  previous,  up
6684 @subsection @code{@@dfn}@{@var{term}@}
6685 @findex dfn
6686
6687 Use the @code{@@dfn} command to identify the introductory or defining
6688 use of a technical term.  Use the command only in passages whose
6689 purpose is to introduce a term which will be used again or which the
6690 reader ought to know.  Mere passing mention of a term for the first
6691 time does not deserve @code{@@dfn}.  The command generates italics in
6692 the printed manual, and double quotation marks in the Info file.  For
6693 example:@refill
6694
6695 @example
6696 Getting rid of a file is called @@dfn@{deleting@} it.
6697 @end example
6698
6699 @noindent
6700 produces
6701
6702 @quotation
6703 Getting rid of a file is called @dfn{deleting} it.
6704 @end quotation
6705
6706 As a general rule, a sentence containing the defining occurrence of a
6707 term should be a definition of the term.  The sentence does not need
6708 to say explicitly that it is a definition, but it should contain the
6709 information of a definition---it should make the meaning clear.
6710
6711 @node cite, url, dfn, Indicating
6712 @comment  node-name,  next,  previous,  up
6713 @subsection @code{@@cite}@{@var{reference}@}
6714 @findex cite
6715
6716 Use the @code{@@cite} command for the name of a book that lacks a
6717 companion Info file. The command produces italics in the printed
6718 manual, and quotation marks in the Info file.@refill
6719
6720 (If a book is written in Texinfo, it is better to use a cross reference
6721 command since a reader can easily follow such a reference in Info.
6722 @xref{xref, , @code{@@xref}}.)@refill
6723
6724 @ignore
6725 @c node ctrl, , cite, Indicating
6726 @comment  node-name,  next,  previous,  up
6727 @c subsection @code{@@ctrl}@{@var{ctrl-char}@}
6728 @findex ctrl
6729
6730 The @code{@@ctrl} command is seldom used.  It describes an @sc{ascii}
6731 control character by inserting the actual character into the Info
6732 file.
6733
6734 Usually, in Texinfo, you talk what you type as keyboard entry by
6735 describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
6736 @kbd{C-a}.  Use @code{@@kbd} in this way when talking about a control
6737 character that is typed on the keyboard by the user.  When talking
6738 about a control character appearing in a file or a string, do not use
6739 @code{@@kbd} since the control character is not typed.  Also, do not
6740 use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
6741 to make it easier for a reader to understand.@refill
6742
6743 @code{@@ctrl} is an idea from the beginnings of Texinfo which may not
6744 really fit in to the scheme of things.  But there may be times when
6745 you want to use the command.  The pattern is
6746 @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character
6747 whose control-equivalent is wanted.  For example, to specify
6748 @samp{control-f}, you would enter@refill
6749
6750 @example
6751 @@ctrl@{f@}
6752 @end example
6753
6754 @noindent
6755 produces
6756
6757 @quotation
6758 @ctrl{f}
6759 @end quotation
6760
6761 In the Info file, this generates the specified control character, output
6762 literally into the file.  This is done so a user can copy the specified
6763 control character (along with whatever else he or she wants) into another
6764 Emacs buffer and use it.  Since the `control-h',`control-i', and
6765 `control-j' characters are formatting characters, they should not be
6766 indicated with @code{@@ctrl}.@refill
6767
6768 In a printed manual, @code{@@ctrl} generates text to describe or
6769 identify that control character: an uparrow followed by the character
6770 @var{ch}.@refill
6771 @end ignore
6772
6773
6774 @node url, email, cite, Indicating
6775 @subsection @code{@@url}@{@var{uniform-resource-locator}@}
6776 @findex url
6777 @cindex Uniform resource locator, indicating
6778 @cindex URL, indicating
6779
6780 Use the @code{@@url} to indicate a uniform resource locator on the World
6781 Wide Web.  This is analogous to @code{@@file}, @code{@@var}, etc., and
6782 is purely for markup purposes.  It does not produce a link you can
6783 follow in HTML output (the @code{@@uref} command does, @pxref{uref,,
6784 @code{@@uref}}).  It is useful for example URL's which do not actually
6785 exist.  For example:
6786
6787 @c Two lines because one is too long for smallbook format.
6788 @example
6789 For example, the url might be
6790 @@url@{http://host.domain.org/path@}.
6791 @end example
6792
6793
6794 @node email,  , url, Indicating
6795 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
6796 @findex email
6797
6798 Use the @code{@@email} command to indicate an electronic mail address.
6799 It takes one mandatory argument, the address, and one optional argument, the
6800 text to display (the default is the address itself).
6801
6802 @cindex mailto link
6803 In Info and @TeX{}, the address is shown in angle brackets, preceded by
6804 the text to display if any.  In HTML output, @code{@@email} produces a
6805 @samp{mailto} link that usually brings up a mail composition window.
6806 For example:
6807
6808 @example
6809 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}.
6810 Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
6811 @end example
6812 @noindent
6813 produces
6814 @example
6815 Send bug reports to @email{bug-texinfo@@gnu.org}.
6816 Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
6817 @end example
6818
6819
6820 @node Emphasis,  , Indicating, Marking Text
6821 @comment node-name,  next,  previous,  up
6822 @section Emphasizing Text
6823 @cindex Emphasizing text
6824
6825 Usually, Texinfo changes the font to mark words in the text according to
6826 what category the words belong to; an example is the @code{@@code} command.
6827 Most often, this is the best way to mark words.
6828 However, sometimes you will want to emphasize text without indicating a
6829 category.  Texinfo has two commands to do this.  Also, Texinfo has
6830 several commands that specify the font in which @TeX{} will typeset
6831 text.  These commands have no affect on Info and only one of them,
6832 the @code{@@r} command, has any regular use.@refill
6833
6834 @menu
6835 * emph & strong::               How to emphasize text in Texinfo.
6836 * Smallcaps::                   How to use the small caps font.
6837 * Fonts::                       Various font commands for printed output.
6838 * Customized Highlighting::     How to define highlighting commands.
6839 @end menu
6840
6841 @node emph & strong, Smallcaps, Emphasis, Emphasis
6842 @comment  node-name,  next,  previous,  up
6843 @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
6844 @cindex Emphasizing text, font for
6845 @findex emph
6846 @findex strong
6847
6848 The @code{@@emph} and @code{@@strong} commands are for emphasis;
6849 @code{@@strong} is stronger.  In printed output, @code{@@emph}
6850 produces @emph{italics} and @code{@@strong} produces
6851 @strong{bold}.@refill
6852
6853 @need 800
6854 For example,
6855
6856 @example
6857 @group
6858 @@quotation
6859 @@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
6860 files in the directory.
6861 @@end quotation
6862 @end group
6863 @end example
6864
6865 @iftex
6866 @noindent
6867 produces the following in printed output:
6868
6869 @quotation
6870 @strong{Caution}: @code{rm * .[^.]*} removes @emph{all}
6871 files in the directory.
6872 @end quotation
6873
6874 @noindent
6875 and the following in Info:
6876 @end iftex
6877 @ifinfo
6878 @noindent
6879 produces:
6880 @end ifinfo
6881
6882 @example
6883      *Caution*: `rm * .[^.]*' removes *all*
6884      files in the directory.
6885 @end example
6886
6887 The @code{@@strong} command is seldom used except to mark what is, in
6888 effect, a typographical element, such as the word `Caution' in the
6889 preceding example.
6890
6891 In the Info file, both @code{@@emph} and @code{@@strong} put asterisks
6892 around the text.@refill
6893
6894 @quotation
6895 @strong{Caution:} Do not use @code{@@emph} or @code{@@strong} with the
6896 word @samp{Note}; Info will mistake the combination for a cross
6897 reference.  Use a phrase such as @strong{Please note} or
6898 @strong{Caution} instead.@refill
6899 @end quotation
6900
6901 @node Smallcaps, Fonts, emph & strong, Emphasis
6902 @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
6903 @cindex Small caps font
6904 @findex sc @r{(small caps font)}
6905
6906 @iftex
6907 Use the @samp{@@sc} command to set text in the printed output in @sc{a
6908 small caps font} and set text in the Info file in upper case letters.@refill
6909 @end iftex
6910 @ifinfo
6911 Use the @samp{@@sc} command to set text in the printed output in a
6912 small caps font and set text in the Info file in upper case letters.@refill
6913 @end ifinfo
6914
6915 Write the text between braces in lower case, like this:@refill
6916
6917 @example
6918 The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
6919 @end example
6920
6921 @noindent
6922 This produces:
6923
6924 @display
6925 The @sc{acm} and @sc{ieee} are technical societies.
6926 @end display
6927
6928 @TeX{} typesets the small caps font in a manner that prevents the
6929 letters from `jumping out at you on the page'.  This makes small caps
6930 text easier to read than text in all upper case.  The Info formatting
6931 commands set all small caps text in upper case.@refill
6932
6933 @ifinfo
6934 If the text between the braces of an @code{@@sc} command is upper case,
6935 @TeX{} typesets in full-size capitals.  Use full-size capitals
6936 sparingly.@refill
6937 @end ifinfo
6938 @iftex
6939 If the text between the braces of an @code{@@sc} command is upper case,
6940 @TeX{} typesets in @sc{FULL-SIZE CAPITALS}.  Use full-size capitals
6941 sparingly.@refill
6942 @end iftex
6943
6944 You may also use the small caps font for a jargon word such as
6945 @sc{ato} (a @sc{nasa} word meaning `abort to orbit').@refill
6946
6947 There are subtleties to using the small caps font with a jargon word
6948 such as @sc{cdr}, a word used in Lisp programming.  In this case, you
6949 should use the small caps font when the word refers to the second and
6950 subsequent elements of a list (the @sc{cdr} of the list), but you
6951 should use @samp{@@code} when the word refers to the Lisp function of
6952 the same spelling.@refill
6953
6954 @node Fonts, Customized Highlighting, Smallcaps, Emphasis
6955 @comment node-name,  next,  previous,  up
6956 @subsection Fonts for Printing, Not Info
6957 @cindex Fonts for printing, not for Info
6958 @findex i @r{(italic font)}
6959 @findex b @r{(bold font)}
6960 @findex t @r{(typewriter font)}
6961 @findex r @r{(Roman font)}
6962
6963 Texinfo provides four font commands that specify font changes in the
6964 printed manual but have no effect in the Info file.  @code{@@i}
6965 requests @i{italic} font (in some versions of @TeX{}, a slanted font
6966 is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
6967 @t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
6968 @r{roman} font, which is the usual font in which text is printed.  All
6969 four commands apply to an argument that follows, surrounded by
6970 braces.@refill
6971
6972 Only the @code{@@r} command has much use: in example programs, you
6973 can use the @code{@@r} command to convert code comments from the
6974 fixed-width font to a roman font.  This looks better in printed
6975 output.@refill
6976
6977 @need 700
6978 For example,
6979
6980 @example
6981 @group
6982 @@lisp
6983 (+ 2 2)    ; @@r@{Add two plus two.@}
6984 @@end lisp
6985 @end group
6986 @end example
6987
6988 @noindent
6989 produces
6990
6991 @lisp
6992 (+ 2 2)    ; @r{Add two plus two.}
6993 @end lisp
6994
6995 If possible, you should avoid using the other three font commands.  If
6996 you need to use one, it probably indicates a gap in the Texinfo
6997 language.@refill
6998
6999 @node Customized Highlighting,  , Fonts, Emphasis
7000 @comment node-name,  next,  previous,  up
7001 @subsection Customized Highlighting
7002 @cindex Highlighting, customized
7003 @cindex Customized highlighting
7004
7005 @c I think this whole section is obsolete with the advent of macros
7006 @c --karl, 15sep96.
7007 You can use regular @TeX{} commands inside of @code{@@iftex} @dots{}
7008 @code{@@end iftex} to create your own customized highlighting commands
7009 for Texinfo.  The easiest way to do this is to equate your customized
7010 commands with pre-existing commands, such as those for italics.  Such
7011 new commands work only with @TeX{}.@refill
7012
7013 @findex definfoenclose
7014 @cindex Enclosure command for Info
7015 You can use the @code{@@definfoenclose} command inside of
7016 @code{@@ifinfo} @dots{} @code{@@end ifinfo} to define commands for Info
7017 with the same names as new commands for @TeX{}.
7018 @code{@@definfoenclose} creates new commands for Info that mark text by
7019 enclosing it in strings that precede and follow the text.
7020 @footnote{Currently, @code{@@definfoenclose} works only with
7021 @code{texinfo-format-buffer} and @code{texinfo-format-region}, not with
7022 @code{makeinfo}.}@refill
7023
7024 Here is how to create a new @@-command called @code{@@phoo} that causes
7025 @TeX{} to typeset its argument in italics and causes Info to display the
7026 argument between @samp{//} and @samp{\\}.@refill
7027
7028 @need 1300
7029 For @TeX{}, write the following to equate the @code{@@phoo} command with
7030 the existing @code{@@i} italics command:@refill
7031
7032 @example
7033 @group
7034 @@iftex
7035 @@global@@let@@phoo=@@i
7036 @@end iftex
7037 @end group
7038 @end example
7039
7040 @noindent
7041 This defines @code{@@phoo} as a command that causes @TeX{} to typeset
7042 the argument to @code{@@phoo} in italics.  @code{@@global@@let} tells
7043 @TeX{} to equate the next argument with the argument that follows the
7044 equals sign.
7045
7046 @need 1300
7047 For Info, write the following to tell the Info formatters to enclose the
7048 argument between @samp{//} and @samp{\\}:
7049
7050 @example
7051 @group
7052 @@ifinfo
7053 @@definfoenclose phoo, //, \\
7054 @@end ifinfo
7055 @end group
7056 @end example
7057
7058 @noindent
7059 Write the @code{@@definfoenclose} command on a line and follow it with
7060 three arguments separated by commas (commas are used as separators in an
7061 @code{@@node} line in the same way).@refill
7062
7063 @itemize @bullet
7064 @item
7065 The first argument to @code{@@definfoenclose} is the @@-command name
7066 @strong{without} the @samp{@@};
7067
7068 @item
7069 the second argument is the Info start delimiter string; and,
7070
7071 @item
7072 the third argument is the Info end delimiter string.
7073 @end itemize
7074
7075 @noindent
7076 The latter two arguments enclose the highlighted text in the Info file.
7077 A delimiter string may contain spaces.  Neither the start nor end
7078 delimiter is required.  However, if you do not provide a start
7079 delimiter, you must follow the command name with two commas in a row;
7080 otherwise, the Info formatting commands will misinterpret the end
7081 delimiter string as a start delimiter string.@refill
7082
7083 After you have defined @code{@@phoo} both for @TeX{} and for Info, you
7084 can then write @code{@@phoo@{bar@}} to see @samp{//bar\\}
7085 in Info and see
7086 @ifinfo
7087 @samp{bar} in italics in printed output.
7088 @end ifinfo
7089 @iftex
7090 @i{bar} in italics in printed output.
7091 @end iftex
7092
7093 Note that each definition applies to its own formatter: one for @TeX{},
7094 the other for Info.
7095
7096 @need 1200
7097 Here is another example:
7098
7099 @example
7100 @group
7101 @@ifinfo
7102 @@definfoenclose headword, , :
7103 @@end ifinfo
7104 @@iftex
7105 @@global@@let@@headword=@@b
7106 @@end iftex
7107 @end group
7108 @end example
7109
7110 @noindent
7111 This defines @code{@@headword} as an Info formatting command that
7112 inserts nothing before and a colon after the argument and as a @TeX{}
7113 formatting command to typeset its argument in bold.
7114
7115 @node Quotations and Examples, Lists and Tables, Marking Text, Top
7116 @comment  node-name,  next,  previous,  up
7117 @chapter Quotations and Examples
7118
7119 Quotations and examples are blocks of text consisting of one or more
7120 whole paragraphs that are set off from the bulk of the text and
7121 treated differently.  They are usually indented.@refill
7122
7123 In Texinfo, you always begin a quotation or example by writing an
7124 @@-command at the beginning of a line by itself, and end it by writing
7125 an @code{@@end} command that is also at the beginning of a line by
7126 itself.  For instance, you begin an example by writing @code{@@example}
7127 by itself at the beginning of a line and end the example by writing
7128 @code{@@end example} on a line by itself, at the beginning of that
7129 line.@refill
7130 @findex end
7131
7132 @menu
7133 * Block Enclosing Commands::    Use different constructs for
7134                                   different purposes.
7135 * quotation::                   How to write a quotation.
7136 * example::                     How to write an example in a fixed-width font.
7137 * noindent::                    How to prevent paragraph indentation.
7138 * Lisp Example::                How to illustrate Lisp code.
7139 * smallexample & smalllisp::    Forms for the @code{@@smallbook} option.
7140 * display::                     How to write an example in the current font.
7141 * format::                      How to write an example that does not narrow
7142                                   the margins.
7143 * exdent::                      How to undo the indentation of a line.
7144 * flushleft & flushright::      How to push text flushleft or flushright.
7145 * cartouche::                   How to draw cartouches around examples.
7146 @end menu
7147
7148 @node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples
7149 @section The Block Enclosing Commands
7150
7151 Here are commands for quotations and examples:@refill
7152
7153 @table @code
7154 @item @@quotation
7155 Indicate text that is quoted. The text is filled, indented, and
7156 printed in a roman font by default.@refill
7157
7158 @item @@example
7159 Illustrate code, commands, and the like. The text is printed
7160 in a fixed-width font, and indented but not filled.@refill
7161
7162 @item @@lisp
7163 Illustrate Lisp code. The text is printed in a fixed-width font,
7164 and indented but not filled.@refill
7165
7166 @item @@smallexample
7167 Illustrate code, commands, and the like.  Similar to
7168 @code{@@example}, except that in @TeX{} this command typesets text in
7169 a smaller font for the smaller @code{@@smallbook} format than for the
7170 8.5 by 11 inch format.@refill
7171
7172 @item @@smalllisp
7173 Illustrate Lisp code.  Similar to @code{@@lisp}, except that
7174 in @TeX{} this command typesets text in a smaller font for the smaller
7175 @code{@@smallbook} format than for the 8.5 by 11 inch format.@refill
7176
7177 @item @@display
7178 Display illustrative text.  The text is indented but not filled, and
7179 no font is specified (so, by default, the font is roman).@refill
7180
7181 @item @@format
7182 Print illustrative text.  The text is not indented and not filled
7183 and no font is specified (so, by default, the font is roman).@refill
7184 @end table
7185
7186 The @code{@@exdent} command is used within the above constructs to
7187 undo the indentation of a line.
7188
7189 The @code{@@flushleft} and @code{@@flushright} commands are used to line
7190 up the left or right margins of unfilled text.@refill
7191
7192 The @code{@@noindent} command may be used after one of the above
7193 constructs to prevent the following text from being indented as a new
7194 paragraph.@refill
7195
7196 You can use the @code{@@cartouche} command within one of the above
7197 constructs to highlight the example or quotation by drawing a box with
7198 rounded corners around it.  (The @code{@@cartouche} command affects
7199 only the printed manual; it has no effect in the Info file; see
7200 @ref{cartouche, , Drawing Cartouches Around Examples}.)@refill
7201
7202 @node quotation, example, Block Enclosing Commands, Quotations and Examples
7203 @comment  node-name,  next,  previous,  up
7204 @section @code{@@quotation}
7205 @cindex Quotations
7206 @findex quotation
7207
7208 The text of a quotation is
7209 processed normally except that:@refill
7210
7211 @itemize @bullet
7212 @item
7213 the margins are closer to the center of the page, so the whole of the
7214 quotation is indented;@refill
7215
7216 @item
7217 the first lines of paragraphs are indented no more than other
7218 lines;@refill
7219
7220 @item
7221 in the printed output, interparagraph spacing is reduced.@refill
7222 @end itemize
7223
7224 @quotation
7225 This is an example of text written between an @code{@@quotation}
7226 command and an @code{@@end quotation} command.  An @code{@@quotation}
7227 command is most often used to indicate text that is excerpted from
7228 another (real or hypothetical) printed work.@refill
7229 @end quotation
7230
7231 Write an @code{@@quotation} command as text on a line by itself.  This
7232 line will disappear from the output.  Mark the end of the quotation
7233 with a line beginning with and containing only @code{@@end quotation}.
7234 The @code{@@end quotation} line will likewise disappear from the
7235 output.  Thus, the following,@refill
7236
7237 @example
7238 @@quotation
7239 This is
7240 a foo.
7241 @@end quotation
7242 @end example
7243
7244 @noindent
7245 produces
7246
7247 @quotation
7248 This is a foo.
7249 @end quotation
7250
7251 @node example, noindent, quotation, Quotations and Examples
7252 @comment  node-name,  next,  previous,  up
7253 @section @code{@@example}
7254 @cindex Examples, formatting them
7255 @cindex Formatting examples
7256 @findex example
7257
7258 The @code{@@example} command is used to indicate an example that is
7259 not part of the running text, such as computer input or output.@refill
7260
7261 @example
7262 @group
7263 This is an example of text written between an
7264 @code{@@example} command
7265 and an @code{@@end example} command.
7266 The text is indented but not filled.
7267 @end group
7268
7269 @group
7270 In the printed manual, the text is typeset in a
7271 fixed-width font, and extra spaces and blank lines are
7272 significant.  In the Info file, an analogous result is
7273 obtained by indenting each line with five spaces.
7274 @end group
7275 @end example
7276
7277 Write an @code{@@example} command at the beginning of a line by itself.
7278 This line will disappear from the output.  Mark the end of the example
7279 with an @code{@@end example} command, also written at the beginning of a
7280 line by itself.  The @code{@@end example} will disappear from the
7281 output.@refill
7282
7283 @need 700
7284 For example,
7285
7286 @example
7287 @@example
7288 mv foo bar
7289 @@end example
7290 @end example
7291
7292 @noindent
7293 produces
7294
7295 @example
7296 mv foo bar
7297 @end example
7298
7299 Since the lines containing @code{@@example} and @code{@@end example}
7300 will disappear, you should put a blank line before the
7301 @code{@@example} and another blank line after the @code{@@end
7302 example}.  (Remember that blank lines between the beginning
7303 @code{@@example} and the ending @code{@@end example} will appear in
7304 the output.)@refill
7305
7306 @quotation
7307 @strong{Caution:} Do not use tabs in the lines of an example (or anywhere
7308 else in Texinfo, for that matter)!  @TeX{} treats tabs as single
7309 spaces, and that is not what they look like.  This is a problem with
7310 @TeX{}.  (If necessary, in Emacs, you can use @kbd{M-x untabify} to
7311 convert tabs in a region to multiple spaces.)@refill
7312 @end quotation
7313
7314 Examples are often, logically speaking, ``in the middle'' of a
7315 paragraph, and the text continues after an example should not be
7316 indented.  The @code{@@noindent} command prevents a piece of text from
7317 being indented as if it were a new paragraph.
7318 @ifinfo
7319 (@xref{noindent}.)
7320 @end ifinfo
7321
7322 (The @code{@@code} command is used for examples of code that are
7323 embedded within sentences, not set off from preceding and following
7324 text.  @xref{code, , @code{@@code}}.)
7325
7326 @node noindent, Lisp Example, example, Quotations and Examples
7327 @comment  node-name,  next,  previous,  up
7328 @section @code{@@noindent}
7329 @findex noindent
7330
7331 An example or other inclusion can break a paragraph into segments.
7332 Ordinarily, the formatters indent text that follows an example as a new
7333 paragraph.  However, you can prevent this by writing @code{@@noindent}
7334 at the beginning of a line by itself preceding the continuation
7335 text.@refill
7336
7337 @need 1500
7338 For example:
7339
7340 @example
7341 @group
7342 @@example
7343 This is an example
7344 @@end example
7345
7346 @@noindent
7347 This line is not indented.  As you can see, the
7348 beginning of the line is fully flush left with the line
7349 that follows after it.  (This whole example is between
7350 @@code@{@@@@display@} and @@code@{@@@@end display@}.)
7351 @end group
7352 @end example
7353
7354 @noindent
7355 produces
7356
7357 @display
7358 @example
7359 This is an example
7360 @end example
7361 @tex
7362 % Remove extra vskip; this is a kludge to counter the effect of display
7363 \vskip-3.5\baselineskip
7364 @end tex
7365
7366 @noindent
7367 This line is not indented.  As you can see, the
7368 beginning of the line is fully flush left with the line
7369 that follows after it.  (This whole example is between
7370 @code{@@display} and @code{@@end display}.)
7371 @end display
7372
7373 To adjust the number of blank lines properly in the Info file output,
7374 remember that the line containing @code{@@noindent} does not generate a
7375 blank line, and neither does the @code{@@end example} line.@refill
7376
7377 In the Texinfo source file for this manual, each line that says
7378 `produces' is preceded by a line containing @code{@@noindent}.@refill
7379
7380 Do not put braces after an @code{@@noindent} command; they are not
7381 necessary, since @code{@@noindent} is a command used outside of
7382 paragraphs (@pxref{Command Syntax}).@refill
7383
7384 @node Lisp Example, smallexample & smalllisp, noindent, Quotations and Examples
7385 @comment  node-name,  next,  previous,  up
7386 @section @code{@@lisp}
7387 @cindex Lisp example
7388 @findex lisp
7389
7390 The @code{@@lisp} command is used for Lisp code.  It is synonymous
7391 with the @code{@@example} command.
7392
7393 @lisp
7394 This is an example of text written between an
7395 @code{@@lisp} command and an @code{@@end lisp} command.
7396 @end lisp
7397
7398 Use @code{@@lisp} instead of @code{@@example} to preserve information
7399 regarding the nature of the example.  This is useful, for example, if
7400 you write a function that evaluates only and all the Lisp code in a
7401 Texinfo file.  Then you can use the Texinfo file as a Lisp
7402 library.@footnote{It would be straightforward to extend Texinfo to work
7403 in a similar fashion for C, Fortran, or other languages.}@refill
7404
7405 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
7406 itself.@refill
7407
7408 @node smallexample & smalllisp, display, Lisp Example, Quotations and Examples
7409 @comment  node-name,  next,  previous,  up
7410 @section @code{@@smallexample} and @code{@@smalllisp}
7411 @cindex Small book example
7412 @cindex Example for a small book
7413 @cindex Lisp example for a small book
7414 @findex smallexample
7415 @findex smalllisp
7416
7417 In addition to the regular @code{@@example} and @code{@@lisp} commands,
7418 Texinfo has two other ``example-style'' commands.  These are the
7419 @code{@@smallexample} and @code{@@smalllisp} commands.  Both these
7420 commands are designed for use with the @code{@@smallbook} command that
7421 causes @TeX{} to produce a printed manual in a 7 by 9.25 inch format
7422 rather than the regular 8.5 by 11 inch format.@refill
7423
7424 In @TeX{}, the @code{@@smallexample} and @code{@@smalllisp} commands
7425 typeset text in a smaller font for the smaller @code{@@smallbook}
7426 format than for the 8.5 by 11 inch format.  Consequently, many examples
7427 containing long lines fit in a narrower, @code{@@smallbook} page
7428 without needing to be shortened.  Both commands typeset in the normal
7429 font size when you format for the 8.5 by 11 inch size; indeed,
7430 in this situation, the @code{@@smallexample} and @code{@@smalllisp}
7431 commands are defined to be the @code{@@example} and @code{@@lisp}
7432 commands.@refill
7433
7434 In Info, the @code{@@smallexample} and @code{@@smalllisp} commands are
7435 equivalent to the @code{@@example} and @code{@@lisp} commands, and work
7436 exactly the same.@refill
7437
7438 Mark the end of @code{@@smallexample} or @code{@@smalllisp} with
7439 @code{@@end smallexample} or @code{@@end smalllisp},
7440 respectively.@refill
7441
7442 @iftex
7443 Here is an example written in the small font used by the
7444 @code{@@smallexample} and @code{@@smalllisp} commands:
7445
7446 @ifclear smallbook
7447 @display
7448 @tex
7449 % Remove extra vskip; this is a kludge to counter the effect of display
7450 \vskip-3\baselineskip
7451 @end tex
7452 @end display
7453 @end ifclear
7454 @end iftex
7455 @ifset smallbook
7456 @iftex
7457 @smallexample
7458 This is an example of text written between @code{@@smallexample} and
7459 @code{@@end smallexample}.  In Info and in an 8.5 by 11 inch manual,
7460 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7461 this text appears in a smaller font.
7462 @end smallexample
7463 @end iftex
7464 @end ifset
7465 @ifinfo
7466 @smallexample
7467 This is an example of text written between @code{@@smallexample} and
7468 @code{@@end smallexample}.  In Info and in an 8.5 by 11 inch manual,
7469 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7470 this text appears in a smaller font.
7471 @end smallexample
7472 @end ifinfo
7473
7474 The @code{@@smallexample} and @code{@@smalllisp} commands make it
7475 easier to prepare smaller format manuals without forcing you to edit
7476 examples by hand to fit them onto narrower pages.@refill
7477
7478 As a general rule, a printed document looks better if you write all the
7479 examples in a chapter consistently in @code{@@example} or in
7480 @code{@@smallexample}.  Only occasionally should you mix the two
7481 formats.@refill
7482
7483 @xref{smallbook, , Printing ``Small'' Books}, for more information
7484 about the @code{@@smallbook} command.@refill
7485
7486 @node display, format, smallexample & smalllisp, Quotations and Examples
7487 @comment  node-name,  next,  previous,  up
7488 @section @code{@@display}
7489 @cindex Display formatting
7490 @findex display
7491
7492 The @code{@@display} command begins a kind of example.  It is like the
7493 @code{@@example} command
7494 except that, in
7495 a printed manual, @code{@@display} does not select the fixed-width
7496 font.  In fact, it does not specify the font at all, so that the text
7497 appears in the same font it would have appeared in without the
7498 @code{@@display} command.@refill
7499
7500 @display
7501 This is an example of text written between an @code{@@display} command
7502 and an @code{@@end display} command.  The @code{@@display} command
7503 indents the text, but does not fill it.
7504 @end display
7505
7506 @node format, exdent, display, Quotations and Examples
7507 @comment  node-name,  next,  previous,  up
7508 @section @code{@@format}
7509 @findex format
7510
7511 The @code{@@format} command is similar to @code{@@example} except
7512 that, in the printed manual, @code{@@format} does not select the
7513 fixed-width font and does not narrow the margins.@refill
7514
7515 @format
7516 This is an example of text written between an @code{@@format} command
7517 and an @code{@@end format} command.  As you can see
7518 from this example,
7519 the @code{@@format} command does not fill the text.
7520 @end format
7521
7522 @node exdent, flushleft & flushright, format, Quotations and Examples
7523 @section @code{@@exdent}: Undoing a Line's Indentation
7524 @cindex Indentation undoing
7525 @findex exdent
7526
7527 The @code{@@exdent} command removes any indentation a line might have.
7528 The command is written at the beginning of a line and applies only to
7529 the text that follows the command that is on the same line.  Do not use
7530 braces around the text.  In a printed manual, the text on an
7531 @code{@@exdent} line is printed in the roman font.@refill
7532
7533 @code{@@exdent} is usually used within examples.  Thus,@refill
7534
7535 @example
7536 @group
7537 @@example
7538 This line follows an @@@@example command.
7539 @@exdent This line is exdented.
7540 This line follows the exdented line.
7541 The @@@@end example comes on the next line.
7542 @@end group
7543 @end group
7544 @end example
7545
7546 @noindent
7547 produces
7548
7549 @example
7550 @group
7551 This line follows an @@example command.
7552 @exdent This line is exdented.
7553 This line follows the exdented line.
7554 The @@end example comes on the next line.
7555 @end group
7556 @end example
7557
7558 In practice, the @code{@@exdent} command is rarely used.
7559 Usually, you un-indent text by ending the example and
7560 returning the page to its normal width.@refill
7561
7562 @node flushleft & flushright, cartouche, exdent, Quotations and Examples
7563 @section @code{@@flushleft} and @code{@@flushright}
7564 @findex flushleft
7565 @findex flushright
7566
7567 The @code{@@flushleft} and @code{@@flushright} commands line up the
7568 ends of lines on the left and right margins of a page,
7569 but do not fill the text.  The commands are written on lines of their
7570 own, without braces.  The @code{@@flushleft} and @code{@@flushright}
7571 commands are ended by @code{@@end flushleft} and @code{@@end
7572 flushright} commands on lines of their own.@refill
7573
7574 @need 1500
7575 For example,
7576
7577 @example
7578 @group
7579 @@flushleft
7580 This text is
7581 written flushleft.
7582 @@end flushleft
7583 @end group
7584 @end example
7585
7586 @noindent
7587 produces
7588
7589 @quotation
7590 @flushleft
7591 This text is
7592 written flushleft.
7593 @end flushleft
7594 @end quotation
7595
7596
7597 @code{@@flushright} produces the type of indentation often used in the
7598 return address of letters.  For example,
7599
7600 @example
7601 @group
7602 @@flushright
7603 Here is an example of text written
7604 flushright.  The @@code@{@@flushright@} command
7605 right justifies every line but leaves the
7606 left end ragged.
7607 @@end flushright
7608 @end group
7609 @end example
7610
7611 @noindent
7612 produces
7613
7614 @flushright
7615 Here is an example of text written
7616 flushright.  The @code{@@flushright} command
7617 right justifies every line but leaves the
7618 left end ragged.
7619 @end flushright
7620
7621 @node cartouche,  , flushleft & flushright, Quotations and Examples
7622 @section Drawing Cartouches Around Examples
7623 @findex cartouche
7624 @cindex Box with rounded corners
7625
7626 In a printed manual, the @code{@@cartouche} command draws a box with
7627 rounded corners around its contents.  You can use this command to
7628 further highlight an example or quotation.  For instance, you could
7629 write a manual in which one type of example is surrounded by a cartouche
7630 for emphasis.@refill
7631
7632 The @code{@@cartouche} command affects only the printed manual; it has
7633 no effect in the Info file.@refill
7634
7635 @need 1500
7636 For example,
7637
7638 @example
7639 @group
7640 @@example
7641 @@cartouche
7642 % pwd
7643 /usr/local/share/emacs
7644 @@end cartouche
7645 @@end example
7646 @end group
7647 @end example
7648
7649 @noindent
7650 surrounds the two-line example with a box with rounded corners, in the
7651 printed manual.
7652
7653 @iftex
7654 In a printed manual, the example looks like this:@refill
7655
7656 @example
7657 @group
7658 @cartouche
7659 % pwd
7660 /usr/local/lib/emacs/info
7661 @end cartouche
7662 @end group
7663 @end example
7664 @end iftex
7665
7666
7667 @node Lists and Tables, Indices, Quotations and Examples, Top
7668 @chapter Lists and Tables
7669 @cindex Making lists and tables
7670 @cindex Lists and tables, making
7671 @cindex Tables and lists, making
7672
7673 Texinfo has several ways of making lists and tables.  Lists can be
7674 bulleted or numbered; two-column tables can highlight the items in
7675 the first column; multi-column tables are also supported.
7676
7677 @menu
7678 * Introducing Lists::           Texinfo formats lists for you.
7679 * itemize::                     How to construct a simple list.
7680 * enumerate::                   How to construct a numbered list.
7681 * Two-column Tables::           How to construct a two-column table.
7682 * Multi-column Tables::         How to construct generalized tables.
7683 @end menu
7684
7685 @ifinfo
7686 @node Introducing Lists, itemize, Lists and Tables, Lists and Tables
7687 @heading Introducing Lists
7688 @end ifinfo
7689
7690 Texinfo automatically indents the text in lists or tables, and numbers
7691 an enumerated list.  This last feature is useful if you modify the
7692 list, since you do not need to renumber it yourself.@refill
7693
7694 Numbered lists and tables begin with the appropriate @@-command at the
7695 beginning of a line, and end with the corresponding @code{@@end}
7696 command on a line by itself.  The table and itemized-list commands
7697 also require that you write formatting information on the same line as
7698 the beginning @@-command.@refill
7699
7700 Begin an enumerated list, for example, with an @code{@@enumerate}
7701 command and end the list with an @code{@@end enumerate} command.
7702 Begin an itemized list with an @code{@@itemize} command, followed on
7703 the same line by a formatting command such as @code{@@bullet}, and end
7704 the list with an @code{@@end itemize} command.@refill
7705 @findex end
7706
7707 Precede each element of a list with an @code{@@item} or @code{@@itemx}
7708 command.@refill
7709
7710 @sp 1
7711 @noindent
7712 Here is an itemized list of the different kinds of table and lists:@refill
7713
7714 @itemize @bullet
7715 @item
7716 Itemized lists with and without bullets.
7717
7718 @item
7719 Enumerated lists, using numbers or letters.
7720
7721 @item
7722 Two-column tables with highlighting.
7723 @end itemize
7724
7725 @sp 1
7726 @noindent
7727 Here is an enumerated list with the same items:@refill
7728
7729 @enumerate
7730 @item
7731 Itemized lists with and without bullets.
7732
7733 @item
7734 Enumerated lists, using numbers or letters.
7735
7736 @item
7737 Two-column tables with highlighting.
7738 @end enumerate
7739
7740 @sp 1
7741 @noindent
7742 And here is a two-column table with the same items and their
7743 @w{@@-commands}:@refill
7744
7745 @table @code
7746 @item @@itemize
7747 Itemized lists with and without bullets.
7748
7749 @item @@enumerate
7750 Enumerated lists, using numbers or letters.
7751
7752 @item @@table
7753 @itemx @@ftable
7754 @itemx @@vtable
7755 Two-column tables with indexing.
7756 @end table
7757
7758 @node itemize, enumerate, Introducing Lists, Lists and Tables
7759 @comment  node-name,  next,  previous,  up
7760 @section Making an Itemized List
7761 @cindex Itemization
7762 @findex itemize
7763
7764 The @code{@@itemize} command produces sequences of indented
7765 paragraphs, with a bullet or other mark inside the left margin
7766 at the beginning of each paragraph for which such a mark is desired.@refill
7767
7768 Begin an itemized list by writing @code{@@itemize} at the beginning of
7769 a line.  Follow the command, on the same line, with a character or a
7770 Texinfo command that generates a mark.  Usually, you will write
7771 @code{@@bullet} after @code{@@itemize}, but you can use
7772 @code{@@minus}, or any character or any special symbol that results in
7773 a single character in the Info file.  (When you write @code{@@bullet}
7774 or @code{@@minus} after an @code{@@itemize} command, you may omit the
7775 @samp{@{@}}.)@refill
7776
7777 Write the text of the indented paragraphs themselves after the
7778 @code{@@itemize}, up to another line that says @code{@@end
7779 itemize}.@refill
7780
7781 Before each paragraph for which a mark in the margin is desired, write
7782 a line that says just @code{@@item}.  Do not write any other text on this
7783 line.@refill
7784 @findex item
7785
7786 Usually, you should put a blank line before an @code{@@item}.  This
7787 puts a blank line in the Info file. (@TeX{} inserts the proper
7788 interline whitespace in either case.)  Except when the entries are
7789 very brief, these blank lines make the list look better.@refill
7790
7791 Here is an example of the use of @code{@@itemize}, followed by the
7792 output it produces.  Note that @code{@@bullet} produces a @samp{*} in
7793 Info and a round dot in @TeX{}.@refill
7794
7795 @example
7796 @group
7797 @@itemize @@bullet
7798 @@item
7799 Some text for foo.
7800
7801 @@item
7802 Some text
7803 for bar.
7804 @@end itemize
7805 @end group
7806 @end example
7807
7808 @noindent
7809 This produces:
7810
7811 @quotation
7812 @itemize @bullet
7813 @item
7814 Some text for foo.
7815
7816 @item
7817 Some text
7818 for bar.
7819 @end itemize
7820 @end quotation
7821
7822 Itemized lists may be embedded within other itemized lists.  Here is a
7823 list marked with dashes embedded in a list marked with bullets:@refill
7824
7825 @example
7826 @group
7827 @@itemize @@bullet
7828 @@item
7829 First item.
7830
7831 @@itemize @@minus
7832 @@item
7833 Inner item.
7834
7835 @@item
7836 Second inner item.
7837 @@end itemize
7838
7839 @@item
7840 Second outer item.
7841 @@end itemize
7842 @end group
7843 @end example
7844
7845 @noindent
7846 This produces:
7847
7848 @quotation
7849 @itemize @bullet
7850 @item
7851 First item.
7852
7853 @itemize @minus
7854 @item
7855 Inner item.
7856
7857 @item
7858 Second inner item.
7859 @end itemize
7860
7861 @item
7862 Second outer item.
7863 @end itemize
7864 @end quotation
7865
7866 @node enumerate, Two-column Tables, itemize, Lists and Tables
7867 @comment  node-name,  next,  previous,  up
7868 @section Making a Numbered or Lettered List
7869 @cindex Enumeration
7870 @findex enumerate
7871
7872 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
7873 @code{@@itemize}}), except that the labels on the items are
7874 successive integers or letters instead of bullets.
7875
7876 Write the @code{@@enumerate} command at the beginning of a line.  The
7877 command does not require an argument, but accepts either a number or a
7878 letter as an option.  Without an argument, @code{@@enumerate} starts the
7879 list with the number @samp{1}.  With a numeric argument, such as
7880 @samp{3}, the command starts the list with that number.  With an upper
7881 or lower case letter, such as @samp{a} or @samp{A}, the command starts
7882 the list with that letter.@refill
7883
7884 Write the text of the enumerated list in the same way you write an
7885 itemized list: put @code{@@item} on a line of its own before the start
7886 of each paragraph that you want enumerated.  Do not write any other text
7887 on the line beginning with @code{@@item}.@refill
7888
7889 You should put a blank line between entries in the list.
7890 This generally makes it easier to read the Info file.@refill
7891
7892 @need 1500
7893 Here is an example of @code{@@enumerate} without an argument:@refill
7894
7895 @example
7896 @group
7897 @@enumerate
7898 @@item
7899 Underlying causes.
7900
7901 @@item
7902 Proximate causes.
7903 @@end enumerate
7904 @end group
7905 @end example
7906
7907 @noindent
7908 This produces:
7909
7910 @enumerate
7911 @item
7912 Underlying causes.
7913
7914 @item
7915 Proximate causes.
7916 @end enumerate
7917 @sp 1
7918 Here is an example with an argument of @kbd{3}:@refill
7919 @sp 1
7920 @example
7921 @group
7922 @@enumerate 3
7923 @@item
7924 Predisposing causes.
7925
7926 @@item
7927 Precipitating causes.
7928
7929 @@item
7930 Perpetuating causes.
7931 @@end enumerate
7932 @end group
7933 @end example
7934
7935 @noindent
7936 This produces:
7937
7938 @enumerate 3
7939 @item
7940 Predisposing causes.
7941
7942 @item
7943 Precipitating causes.
7944
7945 @item
7946 Perpetuating causes.
7947 @end enumerate
7948 @sp 1
7949 Here is a brief summary of the alternatives.  The summary is constructed
7950 using @code{@@enumerate} with an argument of @kbd{a}.@refill
7951 @sp 1
7952 @enumerate a
7953 @item
7954 @code{@@enumerate}
7955
7956 Without an argument, produce a numbered list, starting with the number
7957 1.@refill
7958
7959 @item
7960 @code{@@enumerate @var{positive-integer}}
7961
7962 With a (positive) numeric argument, start a numbered list with that
7963 number.  You can use this to continue a list that you interrupted with
7964 other text.@refill
7965
7966 @item
7967 @code{@@enumerate @var{upper-case-letter}}
7968
7969 With an upper case letter as argument, start a list
7970 in which each item is marked
7971 by a letter, beginning with that upper case letter.@refill
7972
7973 @item
7974 @code{@@enumerate @var{lower-case-letter}}
7975
7976 With a lower case letter as argument, start a list
7977 in which each item is marked by
7978 a letter, beginning with that lower case letter.@refill
7979 @end enumerate
7980
7981 You can also nest enumerated lists, as in an outline.@refill
7982
7983 @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
7984 @section Making a Two-column Table
7985 @cindex Tables, making two-column
7986 @findex table
7987
7988 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
7989 @code{@@itemize}}), but allows you to specify a name or heading line for
7990 each item.  The @code{@@table} command is used to produce two-column
7991 tables, and is especially useful for glossaries, explanatory
7992 exhibits, and command-line option summaries.
7993
7994 @menu
7995 * table::                       How to construct a two-column table.
7996 * ftable vtable::               Automatic indexing for two-column tables.
7997 * itemx::                       How to put more entries in the first column.
7998 @end menu
7999
8000 @ifinfo
8001 @node table, ftable vtable, Two-column Tables, Two-column Tables
8002 @subheading Using the @code{@@table} Command
8003
8004 Use the @code{@@table} command to produce two-column tables.@refill
8005 @end ifinfo
8006
8007 Write the @code{@@table} command at the beginning of a line and follow
8008 it on the same line with an argument that is a Texinfo ``indicating''
8009 command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8010 @code{@@kbd} (@pxref{Indicating}).  Although these commands are usually
8011 followed by arguments in braces, in this case you use the command name
8012 without an argument because @code{@@item} will supply the argument.
8013 This command will be applied to the text that goes into the first column
8014 of each item and determines how it will be highlighted.  For example,
8015 @code{@@code} will cause the text in the first column to be highlighted
8016 with an @code{@@code} command.  (We recommend @code{@@code} for
8017 @code{@@table}'s of command-line options.)
8018
8019 @findex asis
8020 You may also choose to use the @code{@@asis} command as an argument to
8021 @code{@@table}.  @code{@@asis} is a command that does nothing; if you
8022 use this command after @code{@@table}, @TeX{} and the Info formatting
8023 commands output the first column entries without added highlighting
8024 (``as is'').@refill
8025
8026 (The @code{@@table} command may work with other commands besides those
8027 listed here.  However, you can only use commands that normally take
8028 arguments in braces.)@refill
8029
8030 Begin each table entry with an @code{@@item} command at the beginning
8031 of a line.  Write the first column text on the same line as the
8032 @code{@@item} command.  Write the second column text on the line
8033 following the @code{@@item} line and on subsequent lines.  (You do not
8034 need to type anything for an empty second column entry.)  You may
8035 write as many lines of supporting text as you wish, even several
8036 paragraphs.  But only text on the same line as the @code{@@item} will
8037 be placed in the first column.@refill
8038 @findex item
8039
8040 Normally, you should put a blank line before an @code{@@item} line.
8041 This puts a blank like in the Info file.  Except when the entries are
8042 very brief, a blank line looks better.@refill
8043
8044 @need 1500
8045 The following table, for example, highlights the text in the first
8046 column with an @code{@@samp} command:@refill
8047
8048 @example
8049 @group
8050 @@table @@samp
8051 @@item foo
8052 This is the text for
8053 @@samp@{foo@}.
8054
8055 @@item bar
8056 Text for @@samp@{bar@}.
8057 @@end table
8058 @end group
8059 @end example
8060
8061 @noindent
8062 This produces:
8063
8064 @table @samp
8065 @item foo
8066 This is the text for
8067 @samp{foo}.
8068 @item bar
8069 Text for @samp{bar}.
8070 @end table
8071
8072 If you want to list two or more named items with a single block of
8073 text, use the @code{@@itemx} command.  (@xref{itemx, ,
8074 @code{@@itemx}}.)@refill
8075
8076 @node ftable vtable, itemx, table, Two-column Tables
8077 @comment  node-name,  next,  previous,  up
8078 @subsection @code{@@ftable} and @code{@@vtable}
8079 @cindex Tables with indexes
8080 @cindex Indexing table entries automatically
8081 @findex ftable
8082 @findex vtable
8083
8084 The @code{@@ftable} and @code{@@vtable} commands are the same as the
8085 @code{@@table} command except that @code{@@ftable} automatically enters
8086 each of the items in the first column of the table into the index of
8087 functions and @code{@@vtable} automatically enters each of the items in
8088 the first column of the table into the index of variables.  This
8089 simplifies the task of creating indices.  Only the items on the same
8090 line as the @code{@@item} commands are indexed, and they are indexed in
8091 exactly the form that they appear on that line.  @xref{Indices, ,
8092 Creating Indices}, for more information about indices.@refill
8093
8094 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8095 writing the @@-command at the beginning of a line, followed on the same
8096 line by an argument that is a Texinfo command such as @code{@@code},
8097 exactly as you would for an @code{@@table} command; and end the table
8098 with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8099 itself.
8100
8101 See the example for @code{@@table} in the previous section.
8102
8103 @node itemx,  , ftable vtable, Two-column Tables
8104 @comment  node-name,  next,  previous,  up
8105 @subsection @code{@@itemx}
8106 @cindex Two named items for @code{@@table}
8107 @findex itemx
8108
8109 Use the @code{@@itemx} command inside a table when you have two or more
8110 first column entries for the same item, each of which should appear on a
8111 line of its own.  Use @code{@@itemx} for all but the first entry;
8112 @code{@@itemx} should always follow an @code{@@item} command.  The
8113 @code{@@itemx} command works exactly like @code{@@item} except that it
8114 does not generate extra vertical space above the first column text.
8115
8116 @need 1000
8117 For example,
8118
8119 @example
8120 @group
8121 @@table @@code
8122 @@item upcase
8123 @@itemx downcase
8124 These two functions accept a character or a string as
8125 argument, and return the corresponding upper case (lower
8126 case) character or string.
8127 @@end table
8128 @end group
8129 @end example
8130
8131 @noindent
8132 This produces:
8133
8134 @table @code
8135 @item upcase
8136 @itemx downcase
8137 These two functions accept a character or a string as
8138 argument, and return the corresponding upper case (lower
8139 case) character or string.@refill
8140 @end table
8141
8142 @noindent
8143 (Note also that this example illustrates multi-line supporting text in
8144 a two-column table.)@refill
8145
8146
8147 @node Multi-column Tables,  , Two-column Tables, Lists and Tables
8148 @section Multi-column Tables
8149 @cindex Tables, making multi-column
8150 @findex multitable
8151
8152 @code{@@multitable} allows you to construct tables with any number of
8153 columns, with each column having any width you like.
8154
8155 You define the column widths on the @code{@@multitable} line itself, and
8156 write each row of the actual table following an @code{@@item} command,
8157 with columns separated by an @code{@@tab} command.  Finally, @code{@@end
8158 multitable} completes the table.  Details in the sections below.
8159
8160 @menu
8161 * Multitable Column Widths::    Defining multitable column widths.
8162 * Multitable Rows::             Defining multitable rows, with examples.
8163 @end menu
8164
8165 @node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables
8166 @subsection Multitable Column Widths
8167 @cindex Multitable column widths
8168 @cindex Column widths, defining for multitables
8169 @cindex Widths, defining multitable column
8170
8171 You can define the column widths for a multitable in two ways: as
8172 fractions of the line length; or with a prototype row.  Mixing the two
8173 methods is not supported.  In either case, the widths are defined
8174 entirely on the same line as the @code{@@multitable} command.
8175
8176 @enumerate
8177 @item
8178 @findex columnfractions
8179 @cindex Line length, column widths as fraction of
8180 To specify column widths as fractions of the line length, write
8181 @code{@@columnfractions} and the decimal numbers (presumably less than
8182 1) after the @code{@@multitable} command, as in:
8183
8184 @example
8185 @@multitable @@columnfractions .33 .33 .33
8186 @end example
8187
8188 @noindent
8189 The fractions need not add up exactly to 1.0, as these do
8190 not.  This allows you to produce tables that do not need the full line
8191 length.
8192
8193 @item
8194 @cindex Prototype row, column widths defined by
8195 To specify a prototype row, write the longest entry for each column
8196 enclosed in braces after the @code{@@multitable} command.  For example:
8197
8198 @example
8199 @@multitable @{some text for column one@} @{for column two@}
8200 @end example
8201
8202 @noindent
8203 The first column will then have the width of the typeset `some text for
8204 column one', and the second column the width of `for column two'.
8205
8206 The prototype entries need not appear in the table itself.
8207
8208 Although we used simple text in this example, the prototype entries can
8209 contain Texinfo commands; markup commands such as @code{@@code} are
8210 particularly likely to be useful.
8211
8212 @end enumerate
8213
8214
8215 @node Multitable Rows,  , Multitable Column Widths, Multi-column Tables
8216 @subsection Multitable Rows
8217 @cindex Multitable rows
8218 @cindex Rows, of a multitable
8219
8220 @findex item
8221 @cindex tab
8222 After the @code{@@multitable} command defining the column widths (see
8223 the previous section), you begin each row in the body of a multitable
8224 with @code{@@item}, and separate the column entries with @code{@@tab}.
8225 Line breaks are not special within the table body, and you may break
8226 input lines in your source file as necessary.
8227
8228 Here is a complete example of a multi-column table (the text is from
8229 @cite{The XEmacs Users' Manual}, @pxref{Split Window,, Splitting Windows,
8230 xemacs, XEmacs User's Manual}):
8231
8232 @example
8233 @@multitable @@columnfractions .15 .45 .4
8234 @@item Key @@tab Command @@tab Description
8235 @@item C-x 2
8236 @@tab @@code@{split-window-vertically@}
8237 @@tab Split the selected window into two windows,
8238 with one above the other.
8239 @@item C-x 3
8240 @@tab @@code@{split-window-horizontally@}
8241 @@tab Split the selected window into two windows
8242 positioned side by side.
8243 @@item C-Mouse-2
8244 @@tab
8245 @@tab In the mode line or scroll bar of a window,
8246 split that window.
8247 @@end multitable
8248 @end example
8249
8250 @noindent
8251 produces:
8252
8253 @multitable @columnfractions .15 .45 .4
8254 @item Key @tab Command @tab Description
8255 @item C-x 2
8256 @tab @code{split-window-vertically}
8257 @tab Split the selected window into two windows,
8258 with one above the other.
8259 @item C-x 3
8260 @tab @code{split-window-horizontally}
8261 @tab Split the selected window into two windows
8262 positioned side by side.
8263 @item C-Mouse-2
8264 @tab
8265 @tab In the mode line or scroll bar of a window,
8266 split that window.
8267 @end multitable
8268
8269
8270 @node Indices, Insertions, Lists and Tables, Top
8271 @comment node-name,  next,  previous,  up
8272 @chapter Creating Indices
8273 @cindex Indices
8274 @cindex Creating indices
8275
8276 Using Texinfo, you can generate indices without having to sort and
8277 collate entries manually.  In an index, the entries are listed in
8278 alphabetical order, together with information on how to find the
8279 discussion of each entry.  In a printed manual, this information
8280 consists of page numbers.  In an Info file, this information is a menu
8281 entry leading to the first node referenced.@refill
8282
8283 Texinfo provides several predefined kinds of index: an index
8284 for functions, an index for variables, an index for concepts, and so
8285 on.  You can combine indices or use them for other than their
8286 canonical purpose.  If you wish, you can define your own indices.@refill
8287
8288 @menu
8289 * Index Entries::               Choose different words for index entries.
8290 * Predefined Indices::          Use different indices for different kinds
8291                                   of entry.
8292 * Indexing Commands::           How to make an index entry.
8293 * Combining Indices::           How to combine indices.
8294 * New Indices::                 How to define your own indices.
8295 @end menu
8296
8297 @node Index Entries, Predefined Indices, Indices, Indices
8298 @comment  node-name,  next,  previous,  up
8299 @section Making Index Entries
8300 @cindex Index entries, making
8301 @cindex Entries, making index
8302
8303 When you are making index entries, it is good practice to think of the
8304 different ways people may look for something.  Different people
8305 @emph{do not} think of the same words when they look something up.  A
8306 helpful index will have items indexed under all the different words
8307 that people may use.  For example, one reader may think it obvious that
8308 the two-letter names for indices should be listed under ``Indices,
8309 two-letter names'', since the word ``Index'' is the general concept.
8310 But another reader may remember the specific concept of two-letter
8311 names and search for the entry listed as ``Two letter names for
8312 indices''.  A good index will have both entries and will help both
8313 readers.@refill
8314
8315 Like typesetting, the construction of an index is a highly skilled,
8316 professional art, the subtleties of which are not appreciated until you
8317 need to do it yourself.@refill
8318
8319 @xref{Printing Indices & Menus}, for information about printing an index
8320 at the end of a book or creating an index menu in an Info file.@refill
8321
8322 @node Predefined Indices, Indexing Commands, Index Entries, Indices
8323 @comment  node-name,  next,  previous,  up
8324 @section Predefined Indices
8325
8326 Texinfo provides six predefined indices:@refill
8327
8328 @itemize @bullet
8329 @item
8330 A @dfn{concept index} listing concepts that are discussed.@refill
8331
8332 @item
8333 A @dfn{function index} listing functions (such as entry points of
8334 libraries).@refill
8335
8336 @item
8337 A @dfn{variables index} listing variables (such as global variables
8338 of libraries).@refill
8339
8340 @item
8341 A @dfn{keystroke index} listing keyboard commands.@refill
8342
8343 @item
8344 A @dfn{program index} listing names of programs.@refill
8345
8346 @item
8347 A @dfn{data type index} listing data types (such as structures defined in
8348 header files).@refill
8349 @end itemize
8350
8351 @noindent
8352 Not every manual needs all of these, and most manuals use two or three
8353 of them.  This manual has two indices: a
8354 concept index and an @@-command index (that is actually the function
8355 index but is called a command index in the chapter heading).  Two or
8356 more indices can be combined into one using the @code{@@synindex} or
8357 @code{@@syncodeindex} commands.  @xref{Combining Indices}.@refill
8358
8359 @node Indexing Commands, Combining Indices, Predefined Indices, Indices
8360 @comment  node-name,  next,  previous,  up
8361 @section Defining the Entries of an Index
8362 @cindex Defining indexing entries
8363 @cindex Index entries
8364 @cindex Entries for an index
8365 @cindex Specifying index entries
8366 @cindex Creating index entries
8367
8368 The data to make an index come from many individual indexing commands
8369 scattered throughout the Texinfo source file.  Each command says to add
8370 one entry to a particular index; after formatting, the index will give
8371 the current page number or node name as the reference.@refill
8372
8373 An index entry consists of an indexing command at the beginning of a
8374 line followed, on the rest of the line, by the entry.@refill
8375
8376 For example, this section begins with the following five entries for
8377 the concept index:@refill
8378
8379 @example
8380 @@cindex Defining indexing entries
8381 @@cindex Index entries
8382 @@cindex Entries for an index
8383 @@cindex Specifying index entries
8384 @@cindex Creating index entries
8385 @end example
8386
8387 Each predefined index has its own indexing command---@code{@@cindex}
8388 for the concept index, @code{@@findex} for the function index, and so
8389 on.@refill
8390
8391 @cindex Writing index entries
8392 @cindex Index entry writing
8393 Concept index entries consist of text.  The best way to write an index
8394 is to choose entries that are terse yet clear.  If you can do this,
8395 the index often looks better if the entries are not capitalized, but
8396 written just as they would appear in the middle of a sentence.
8397 (Capitalize proper names and acronyms that always call for upper case
8398 letters.)  This is the case convention we use in most GNU manuals'
8399 indices.
8400
8401 If you don't see how to make an entry terse yet clear, make it longer
8402 and clear---not terse and confusing.  If many of the entries are several
8403 words long, the index may look better if you use a different convention:
8404 to capitalize the first word of each entry.  But do not capitalize a
8405 case-sensitive name such as a C or Lisp function name or a shell
8406 command; that would be a spelling error.
8407
8408 Whichever case convention you use, please use it consistently!
8409
8410 @ignore
8411 Concept index entries consist of English text.  The usual convention
8412 is to capitalize the first word of each such index entry, unless that
8413 word is the name of a function, variable, or other such entity that
8414 should not be capitalized.  However, if your concept index entries are
8415 consistently short (one or two words each) it may look better for each
8416 regular entry to start with a lower case letter, aside from proper
8417 names and acronyms that always call for upper case letters.  Whichever
8418 convention you adapt, please be consistent!
8419 @end ignore
8420
8421 Entries in indices other than the concept index are symbol names in
8422 programming languages, or program names; these names are usually
8423 case-sensitive, so use upper and lower case as required for them.
8424
8425 By default, entries for a concept index are printed in a small roman
8426 font and entries for the other indices are printed in a small
8427 @code{@@code} font.  You may change the way part of an entry is
8428 printed with the usual Texinfo commands, such as @code{@@file} for
8429 file names and @code{@@emph} for emphasis (@pxref{Marking
8430 Text}).@refill
8431 @cindex Index font types
8432
8433 @cindex Predefined indexing commands
8434 @cindex Indexing commands, predefined
8435 The six indexing commands for predefined indices are:
8436
8437 @table @code
8438 @item @@cindex @var{concept}
8439 @findex cindex
8440 Make an entry in the concept index for @var{concept}.@refill
8441
8442 @item @@findex @var{function}
8443 @findex findex
8444 Make an entry in the function index for @var{function}.@refill
8445
8446 @item @@vindex @var{variable}
8447 @findex vindex
8448 Make an entry in the variable index for @var{variable}.@refill
8449
8450 @item @@kindex @var{keystroke}
8451 @findex kindex
8452 Make an entry in the key index for @var{keystroke}.@refill
8453
8454 @item @@pindex @var{program}
8455 @findex pindex
8456 Make an entry in the program index for @var{program}.@refill
8457
8458 @item @@tindex @var{data type}
8459 @findex tindex
8460 Make an entry in the data type index for @var{data type}.@refill
8461 @end table
8462
8463 @quotation
8464 @strong{Caution:} Do not use a colon in an index entry.  In Info, a
8465 colon separates the menu entry name from the node name.  An extra
8466 colon confuses Info.
8467 @xref{Menu Parts, , The Parts of a Menu},
8468 for more information about the structure of a menu entry.@refill
8469 @end quotation
8470
8471 If you write several identical index entries in different places in a
8472 Texinfo file, the index in the printed manual will list all the pages to
8473 which those entries refer.  However, the index in the Info file will
8474 list @strong{only} the node that references the @strong{first} of those
8475 index entries.  Therefore, it is best to write indices in which each
8476 entry refers to only one place in the Texinfo file.  Fortunately, this
8477 constraint is a feature rather than a loss since it means that the index
8478 will be easy to use.  Otherwise, you could create an index that lists
8479 several pages for one entry and your reader would not know to which page
8480 to turn.  If you have two identical entries for one topic, change the
8481 topics slightly, or qualify them to indicate the difference.@refill
8482
8483 You are not actually required to use the predefined indices for their
8484 canonical purposes.  For example, suppose you wish to index some C
8485 preprocessor macros.  You could put them in the function index along
8486 with actual functions, just by writing @code{@@findex} commands for
8487 them; then, when you print the ``Function Index'' as an unnumbered
8488 chapter, you could give it the title `Function and Macro Index' and
8489 all will be consistent for the reader.  Or you could put the macros in
8490 with the data types by writing @code{@@tindex} commands for them, and
8491 give that index a suitable title so the reader will understand.
8492 (@xref{Printing Indices & Menus}.)@refill
8493
8494 @node Combining Indices, New Indices, Indexing Commands, Indices
8495 @comment node-name,  next,  previous,  up
8496 @section Combining Indices
8497 @cindex Combining indices
8498 @cindex Indices, combining them
8499
8500 Sometimes you will want to combine two disparate indices such as functions
8501 and concepts, perhaps because you have few enough of one of them that
8502 a separate index for them would look silly.@refill
8503
8504 You could put functions into the concept index by writing
8505 @code{@@cindex} commands for them instead of @code{@@findex} commands,
8506 and produce a consistent manual by printing the concept index with the
8507 title `Function and Concept Index' and not printing the `Function
8508 Index' at all; but this is not a robust procedure.  It works only if
8509 your document is never included as part of another
8510 document that is designed to have a separate function index; if your
8511 document were to be included with such a document, the functions from
8512 your document and those from the other would not end up together.
8513 Also, to make your function names appear in the right font in the
8514 concept index, you would need to enclose every one of them between
8515 the braces of @code{@@code}.@refill
8516
8517 @menu
8518 * syncodeindex::                How to merge two indices, using @code{@@code}
8519                                   font for the merged-from index.
8520 * synindex::                    How to merge two indices, using the
8521                                   default font of the merged-to index.
8522 @end menu
8523
8524 @node syncodeindex, synindex, Combining Indices, Combining Indices
8525 @subsection @code{@@syncodeindex}
8526 @findex syncodeindex
8527
8528 When you want to combine functions and concepts into one index, you
8529 should index the functions with @code{@@findex} and index the concepts
8530 with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8531 redirect the function index entries into the concept index.@refill
8532 @findex syncodeindex
8533
8534 The @code{@@syncodeindex} command takes two arguments; they are the name
8535 of the index to redirect, and the name of the index to redirect it to.
8536 The template looks like this:@refill
8537
8538 @example
8539 @@syncodeindex @var{from} @var{to}
8540 @end example
8541
8542 @cindex Predefined names for indices
8543 @cindex Two letter names for indices
8544 @cindex Indices, two letter names
8545 @cindex Names for indices
8546 For this purpose, the indices are given two-letter names:@refill
8547
8548 @table @samp
8549 @item cp
8550 concept index
8551 @item fn
8552 function index
8553 @item vr
8554 variable index
8555 @item ky
8556 key index
8557 @item pg
8558 program index
8559 @item tp
8560 data type index
8561 @end table
8562
8563 Write an @code{@@syncodeindex} command before or shortly after the
8564 end-of-header line at the beginning of a Texinfo file.  For example,
8565 to merge a function index with a concept index, write the
8566 following:@refill
8567
8568 @example
8569 @@syncodeindex fn cp
8570 @end example
8571
8572 @noindent
8573 This will cause all entries designated for the function index to merge
8574 in with the concept index instead.@refill
8575
8576 To merge both a variables index and a function index into a concept
8577 index, write the following:@refill
8578
8579 @example
8580 @group
8581 @@syncodeindex vr cp
8582 @@syncodeindex fn cp
8583 @end group
8584 @end example
8585
8586 @cindex Fonts for indices
8587 The @code{@@syncodeindex} command puts all the entries from the `from'
8588 index (the redirected index) into the @code{@@code} font, overriding
8589 whatever default font is used by the index to which the entries are
8590 now directed.  This way, if you direct function names from a function
8591 index into a concept index, all the function names are printed in the
8592 @code{@@code} font as you would expect.@refill
8593
8594 @node synindex,  , syncodeindex, Combining Indices
8595 @subsection @code{@@synindex}
8596 @findex synindex
8597
8598 The @code{@@synindex} command is nearly the same as the
8599 @code{@@syncodeindex} command, except that it does not put the
8600 `from' index  entries into the @code{@@code} font; rather it puts
8601 them in the roman font.  Thus, you use @code{@@synindex} when you
8602 merge a concept index into a function index.@refill
8603
8604 @xref{Printing Indices & Menus}, for information about printing an index
8605 at the end of a book or creating an index menu in an Info file.@refill
8606
8607 @node New Indices,  , Combining Indices, Indices
8608 @section Defining New Indices
8609 @cindex Defining new indices
8610 @cindex Indices, defining new
8611 @cindex New index defining
8612 @findex defindex
8613 @findex defcodeindex
8614
8615 In addition to the predefined indices, you may use the
8616 @code{@@defindex} and @code{@@defcodeindex} commands to define new
8617 indices.  These commands create new indexing @@-commands with which
8618 you mark index entries.  The @code{@@defindex }command is used like
8619 this:@refill
8620
8621 @example
8622 @@defindex @var{name}
8623 @end example
8624
8625 The name of an index should be a two letter word, such as @samp{au}.
8626 For example:@refill
8627
8628 @example
8629 @@defindex au
8630 @end example
8631
8632 This defines a new index, called the @samp{au} index.  At the same
8633 time, it creates a new indexing command, @code{@@auindex}, that you
8634 can use to make index entries.  Use the new indexing command just as
8635 you would use a predefined indexing command.@refill
8636
8637 For example, here is a section heading followed by a concept index
8638 entry and two @samp{au} index entries.@refill
8639
8640 @example
8641 @@section Cognitive Semantics
8642 @@cindex kinesthetic image schemas
8643 @@auindex Johnson, Mark
8644 @@auindex Lakoff, George
8645 @end example
8646
8647 @noindent
8648 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
8649 Texinfo constructs the new indexing command by concatenating the name
8650 of the index with @samp{index}; thus, defining an @samp{au} index
8651 leads to the automatic creation of an @code{@@auindex} command.@refill
8652
8653 Use the @code{@@printindex} command to print the index, as you do with
8654 the predefined indices.  For example:@refill
8655
8656 @example
8657 @group
8658 @@node Author Index, Subject Index, , Top
8659 @@unnumbered Author Index
8660
8661 @@printindex au
8662 @end group
8663 @end example
8664
8665 The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8666 that, in the printed output, it prints entries in an @code{@@code} font
8667 instead of a roman font.  Thus, it parallels the @code{@@findex} command
8668 rather than the @code{@@cindex} command.@refill
8669
8670 You should define new indices within or right after the end-of-header
8671 line of a Texinfo file, before any @code{@@synindex} or
8672 @code{@@syncodeindex} commands (@pxref{Header}).@refill
8673
8674 @node Insertions, Breaks, Indices, Top
8675 @comment  node-name,  next,  previous,  up
8676 @chapter Special Insertions
8677 @cindex Inserting special characters and symbols
8678 @cindex Special insertions
8679
8680 Texinfo provides several commands for inserting characters that have
8681 special meaning in Texinfo, such as braces, and for other graphic
8682 elements that do not correspond to simple characters you can type.
8683
8684 @iftex
8685 These are:
8686
8687 @itemize @bullet
8688 @item Braces, @samp{@@} and periods.
8689 @item Whitespace within and around a sentence.
8690 @item Accents.
8691 @item Dots and bullets.
8692 @item The @TeX{} logo and the copyright symbol.
8693 @item Mathematical expressions.
8694 @end itemize
8695 @end iftex
8696
8697 @menu
8698 * Braces Atsigns::              How to insert braces, @samp{@@}.
8699 * Inserting Space::             How to insert the right amount of space
8700                                   within a sentence.
8701 * Inserting Accents::           How to insert accents and special characters.
8702 * Dots Bullets::                How to insert dots and bullets.
8703 * TeX and copyright::           How to insert the @TeX{} logo
8704                                   and the copyright symbol.
8705 * pounds::                      How to insert the pounds currency symbol.
8706 * minus::                       How to insert a minus sign.
8707 * math::                        How to format a mathematical expression.
8708 * Glyphs::                      How to indicate results of evaluation,
8709                                   expansion of macros, errors, etc.
8710 * Images::                      How to include graphics.
8711 @end menu
8712
8713
8714 @node Braces Atsigns, Inserting Space, Insertions, Insertions
8715 @section Inserting @@ and Braces
8716 @cindex Inserting @@, braces
8717 @cindex Braces, inserting
8718 @cindex Special characters, commands to insert
8719 @cindex Commands to insert special characters
8720
8721 @samp{@@} and curly braces are special characters in Texinfo.  To insert
8722 these characters so they appear in text, you must put an @samp{@@} in
8723 front of these characters to prevent Texinfo from misinterpreting
8724 them.
8725
8726 Do not put braces after any of these commands; they are not
8727 necessary.
8728
8729 @menu
8730 * Inserting An Atsign::         How to insert @samp{@@}.
8731 * Inserting Braces::            How to insert @samp{@{} and @samp{@}}.
8732 @end menu
8733
8734 @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
8735 @subsection Inserting @samp{@@} with @@@@
8736 @findex @@ @r{(single @samp{@@})}
8737
8738 @code{@@@@} stands for a single @samp{@@} in either printed or Info
8739 output.
8740
8741 Do not put braces after an @code{@@@@} command.
8742
8743 @node Inserting Braces,  , Inserting An Atsign, Braces Atsigns
8744 @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
8745 @findex @{ @r{(single @samp{@{})}
8746 @findex @} @r{(single @samp{@}})}
8747
8748 @code{@@@{} stands for a single @samp{@{} in either printed or Info
8749 output.
8750
8751 @code{@@@}} stands for a single @samp{@}} in either printed or Info
8752 output.
8753
8754 Do not put braces after either an @code{@@@{} or an @code{@@@}}
8755 command.
8756
8757
8758 @node Inserting Space, Inserting Accents, Braces Atsigns, Insertions
8759 @section Inserting Space
8760
8761 @cindex Inserting space
8762 @cindex Spacing, inserting
8763 @cindex Whitespace, inserting
8764 The following sections describe commands that control spacing of various
8765 kinds within and after sentences.
8766
8767 @menu
8768 * Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
8769 * Ending a Sentence::           Sometimes it does.
8770 * Multiple Spaces::             Inserting multiple spaces.
8771 * dmn::                         How to format a dimension.
8772 @end menu
8773
8774 @node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space
8775 @subsection Not Ending a Sentence
8776
8777 @cindex Not ending a sentence
8778 @cindex Sentence non-ending punctuation
8779 @cindex Periods, inserting
8780 Depending on whether a period or exclamation point or question mark is
8781 inside or at the end of a sentence, less or more space is inserted after
8782 a period in a typeset manual.  Since it is not always possible for
8783 Texinfo to determine when a period ends a sentence and when it is used
8784 in an abbreviation, special commands are needed in some circumstances.
8785 (Usually, Texinfo can guess how to handle periods, so you do not need to
8786 use the special commands; you just enter a period as you would if you
8787 were using a typewriter, which means you put two spaces after the
8788 period, question mark, or exclamation mark that ends a sentence.)
8789
8790 @findex : @r{(suppress widening)}
8791 Use the @code{@@:}@: command after a period, question mark,
8792 exclamation mark, or colon that should not be followed by extra space.
8793 For example, use @code{@@:}@: after periods that end abbreviations
8794 which are not at the ends of sentences.
8795
8796 @need 700
8797 For example,
8798
8799 @example
8800 The s.o.p.@@: has three parts @dots{}
8801 The s.o.p. has three parts @dots{}
8802 @end example
8803
8804 @noindent
8805 @ifinfo
8806 produces
8807 @end ifinfo
8808 @iftex
8809 produces the following.  If you look carefully at this printed output,
8810 you will see a little more whitespace after @samp{s.o.p.} in the second
8811 line.@refill
8812 @end iftex
8813
8814 @quotation
8815 The s.o.p.@: has three parts @dots{}@*
8816 The s.o.p. has three parts @dots{}
8817 @end quotation
8818
8819 @noindent
8820 (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
8821 Procedure''.)
8822
8823 @code{@@:} has no effect on the Info output.  Do not put braces after
8824 @code{@@:}.
8825
8826
8827 @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
8828 @subsection Ending a Sentence
8829
8830 @cindex Ending a Sentence
8831 @cindex Sentence ending punctuation
8832
8833 @findex .  @r{(end of sentence)}
8834 @findex ! @r{(end of sentence)}
8835 @findex ? @r{(end of sentence)}
8836 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
8837 exclamation point, and @code{@@?}@: instead of a question mark at the end
8838 of a sentence that ends with a single capital letter.  Otherwise, @TeX{}
8839 will think the letter is an abbreviation and will not insert the correct
8840 end-of-sentence spacing.  Here is an example:
8841
8842 @example
8843 Give it to M.I.B. and to M.E.W@@.  Also, give it to R.J.C@@.
8844 Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
8845 @end example
8846
8847 @noindent
8848 @ifinfo
8849 produces
8850 @end ifinfo
8851 @iftex
8852 produces the following.  If you look carefully at this printed output,
8853 you will see a little more whitespace after the @samp{W} in the first
8854 line.
8855 @end iftex
8856
8857 @quotation
8858 Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.@*
8859 Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
8860 @end quotation
8861
8862 In the Info file output, @code{@@.}@: is equivalent to a simple
8863 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
8864
8865 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
8866 work well with the Emacs sentence motion commands (@pxref{Sentences,,,
8867 xemacs, XEmacs User's Manual}).  This made it necessary for them to be
8868 incompatible with some other formatting systems that use @@-commands.
8869
8870 Do not put braces after any of these commands.
8871
8872
8873 @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
8874 @subsection Multiple Spaces
8875
8876 @cindex Multiple spaces
8877 @cindex Whitespace, inserting
8878 @findex (space)
8879 @findex (tab)
8880 @findex (newline)
8881
8882 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
8883 and newline) into a single space.  Info output, on the other hand,
8884 preserves whitespace as you type it, except for changing a newline into
8885 a space; this is why it is important to put two spaces at the end of
8886 sentences in Texinfo documents.
8887
8888 Occasionally, you may want to actually insert several consecutive
8889 spaces, either for purposes of example (what your program does with
8890 multiple spaces as input), or merely for purposes of appearance in
8891 headings or lists.  Texinfo supports three commands:
8892 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
8893 which insert a single space into the output.  (Here,
8894 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
8895 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
8896 character and end-of-line, i.e., when @samp{@@} is the last character on
8897 a line.)
8898
8899 For example,
8900 @example
8901 Spacey@@ @@ @@ @@
8902 example.
8903 @end example
8904
8905 @noindent
8906 produces
8907
8908 @example
8909 Spacey@ @ @ @
8910 example.
8911 @end example
8912
8913 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
8914 @code{@@multitable} (@pxref{Multi-column Tables}).
8915
8916 Do not follow any of these commands with braces.
8917
8918
8919 @node dmn,  , Multiple Spaces, Inserting Space
8920 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
8921 @cindex Thin space between number, dimension
8922 @cindex Dimension formatting
8923 @cindex Format a dimension
8924 @findex dmn
8925
8926 At times, you may want to write @samp{12@dmn{pt}} or
8927 @samp{8.5@dmn{in}} with little or no space between the number and the
8928 abbreviation for the dimension.  You can use the @code{@@dmn} command
8929 to do this.  On seeing the command, @TeX{} inserts just enough space
8930 for proper typesetting; the Info formatting commands insert no space
8931 at all, since the Info file does not require it.@refill
8932
8933 To use the @code{@@dmn} command, write the number and then follow it
8934 immediately, with no intervening space, by @code{@@dmn}, and then by
8935 the dimension within braces.  For example,
8936
8937 @example
8938 A4 paper is 8.27@@dmn@{in@} wide.
8939 @end example
8940
8941 @noindent
8942 produces
8943
8944 @quotation
8945 A4 paper is 8.27@dmn{in} wide.
8946 @end quotation
8947
8948 Not everyone uses this style.  Some people prefer @w{@samp{8.27 in.@@:}}
8949 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
8950 In these cases, however, the formatters may insert a line break between
8951 the number and the dimension, so use @code{@@w} (@pxref{w}).  Also, if
8952 you write a period after an abbreviation within a sentence, you should
8953 write @samp{@@:} after the period to prevent @TeX{} from inserting extra
8954 whitespace, as shown here.  @xref{Inserting Space}.
8955
8956
8957 @node Inserting Accents, Dots Bullets, Inserting Space, Insertions
8958 @section Inserting Accents
8959
8960 @cindex Inserting accents
8961 @cindex Accents, inserting
8962 @cindex Floating accents, inserting
8963
8964 Here is a table with the commands Texinfo provides for inserting
8965 floating accents.  The commands with non-alphabetic names do not take
8966 braces around their argument (which is taken to be the next character).
8967 (Exception: @code{@@,} @emph{does} take braces around its argument.)
8968 This is so as to make the source as convenient to type and read as
8969 possible, since accented characters are very common in some languages.
8970
8971 @findex "
8972 @cindex Umlaut accent
8973 @findex '
8974 @cindex Acute accent
8975 @findex =
8976 @cindex Macron accent
8977 @findex ^
8978 @cindex Circumflex accent
8979 @findex `
8980 @cindex Grave accent
8981 @findex ~
8982 @cindex Tilde accent
8983 @findex ,
8984 @cindex Cedilla accent
8985 @findex dotaccent
8986 @cindex Dot accent
8987 @findex H
8988 @cindex Hungariam umlaut accent
8989 @findex ringaccent
8990 @cindex Ring accent
8991 @findex tieaccent
8992 @cindex Tie-after accent
8993 @findex u
8994 @cindex Breve accent
8995 @findex ubaraccent
8996 @cindex Underbar accent
8997 @findex udotaccent
8998 @cindex Underdot accent
8999 @findex v
9000 @cindex Check accent
9001 @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9002 @item Command               @tab Output         @tab What
9003 @item @t{@@"o}              @tab @"o            @tab umlaut accent
9004 @item @t{@@'o}              @tab @'o            @tab acute accent
9005 @item @t{@@,@{c@}}          @tab @,{c}          @tab cedilla accent
9006 @item @t{@@=o}              @tab @=o            @tab macron/overbar accent
9007 @item @t{@@^o}              @tab @^o            @tab circumflex accent
9008 @item @t{@@`o}              @tab @`o            @tab grave accent
9009 @item @t{@@~o}              @tab @~o            @tab tilde accent
9010 @item @t{@@dotaccent@{o@}}  @tab @dotaccent{o}  @tab overdot accent
9011 @item @t{@@H@{o@}}          @tab @H{o}          @tab long Hungarian umlaut
9012 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9013 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9014 @item @t{@@u@{o@}}          @tab @u{o}          @tab breve accent
9015 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9016 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9017 @item @t{@@v@{o@}}          @tab @v{o}          @tab hacek or check accent
9018 @end multitable
9019
9020 This table lists the Texinfo commands for inserting other characters
9021 commonly used in languages other than English.
9022
9023 @findex questiondown
9024 @cindex @questiondown{}
9025 @findex exclamdown
9026 @cindex @exclamdown{}
9027 @findex aa
9028 @cindex @aa{}
9029 @findex AA
9030 @cindex @AA{}
9031 @findex ae
9032 @cindex @ae{}
9033 @findex AE
9034 @cindex @AE{}
9035 @findex dotless
9036 @cindex @dotless{i}
9037 @cindex @dotless{j}
9038 @cindex Dotless i, j
9039 @findex l
9040 @cindex @l{}
9041 @findex L
9042 @cindex @L{}
9043 @findex o
9044 @cindex @o{}
9045 @findex O
9046 @cindex @O{}
9047 @findex oe
9048 @cindex @oe{}
9049 @findex OE
9050 @cindex @OE{}
9051 @findex ss
9052 @cindex @ss{}
9053 @cindex Es-zet
9054 @cindex Sharp S
9055 @cindex German S
9056 @multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
9057 @item @t{@@exclamdown@{@}}   @tab @exclamdown{}   @tab upside-down !
9058 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9059 @item @t{@@aa@{@},@@AA@{@}}  @tab @aa{},@AA{}     @tab A,a with circle
9060 @item @t{@@ae@{@},@@AE@{@}}  @tab @ae{},@AE{}     @tab ae,AE ligatures
9061 @item @t{@@dotless@{i@}}     @tab @dotless{i}     @tab dotless i
9062 @item @t{@@dotless@{j@}}     @tab @dotless{j}     @tab dotless j
9063 @item @t{@@l@{@},@@L@{@}}    @tab @l{},@L{}       @tab suppressed-L,l
9064 @item @t{@@o@{@},@@O@{@}}    @tab @o{},@O{}       @tab O,o with slash
9065 @item @t{@@oe@{@},@@OE@{@}}  @tab @oe{},@OE{}     @tab OE,oe ligatures
9066 @item @t{@@ss@{@}}           @tab @ss{}           @tab es-zet or sharp S
9067 @end multitable
9068
9069
9070 @node Dots Bullets, TeX and copyright, Inserting Accents, Insertions
9071 @section Inserting Ellipsis, Dots, and Bullets
9072 @cindex Dots, inserting
9073 @cindex Bullets, inserting
9074 @cindex Ellipsis, inserting
9075 @cindex Inserting ellipsis
9076 @cindex Inserting dots
9077 @cindex Special typesetting commands
9078 @cindex Typesetting commands for dots, etc.
9079
9080 An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9081 periods, so a special command is used for ellipsis in Texinfo.  The
9082 @code{@@bullet} command is special, too.  Each of these commands is
9083 followed by a pair of braces, @samp{@{@}}, without any whitespace
9084 between the name of the command and the braces.  (You need to use braces
9085 with these commands because you can use them next to other text; without
9086 the braces, the formatters would be confused.  @xref{Command Syntax, ,
9087 @@-Command Syntax}, for further information.)@refill
9088
9089 @menu
9090 * dots::                        How to insert dots @dots{}
9091 * bullet::                      How to insert a bullet.
9092 @end menu
9093
9094
9095 @node dots, bullet, Dots Bullets, Dots Bullets
9096 @subsection @code{@@dots}@{@} (@dots{})
9097 @findex dots
9098 @cindex Inserting dots
9099 @cindex Dots, inserting
9100
9101 Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9102 three dots in a row, appropriately spaced, like this: `@dots{}'.  Do
9103 not simply write three periods in the input file; that would work for
9104 the Info file output, but would produce the wrong amount of space
9105 between the periods in the printed manual.
9106
9107 Similarly, the @code{@@enddots@{@}} command generates an
9108 end-of-sentence ellipsis (four dots) @enddots{}
9109
9110 @iftex
9111 Here is an ellipsis: @dots{}
9112 Here are three periods in a row: ...
9113
9114 In printed output, the three periods in a row are closer together than
9115 the dots in the ellipsis.
9116 @end iftex
9117
9118
9119 @node bullet,  , dots, Dots Bullets
9120 @subsection @code{@@bullet}@{@} (@bullet{})
9121 @findex bullet
9122
9123 Use the @code{@@bullet@{@}} command to generate a large round dot, or
9124 the closest possible thing to one.  In Info, an asterisk is used.@refill
9125
9126 Here is a bullet: @bullet{}
9127
9128 When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9129 type the braces, because @code{@@itemize} supplies them.
9130 (@xref{itemize, , @code{@@itemize}}.)@refill
9131
9132
9133 @node TeX and copyright, pounds, Dots Bullets, Insertions
9134 @section Inserting @TeX{} and the Copyright Symbol
9135
9136 The logo `@TeX{}' is typeset in a special fashion and it needs an
9137 @@-command.  The copyright symbol, `@copyright{}', is also special.
9138 Each of these commands is followed by a pair of braces, @samp{@{@}},
9139 without any whitespace between the name of the command and the
9140 braces.@refill
9141
9142 @menu
9143 * tex::                         How to insert the @TeX{} logo.
9144 * copyright symbol::            How to use @code{@@copyright}@{@}.
9145 @end menu
9146
9147
9148 @node tex, copyright symbol, TeX and copyright, TeX and copyright
9149 @subsection @code{@@TeX}@{@} (@TeX{})
9150 @findex tex (command)
9151
9152 Use the @code{@@TeX@{@}} command to generate `@TeX{}'.  In a printed
9153 manual, this is a special logo that is different from three ordinary
9154 letters.  In Info, it just looks like @samp{TeX}.  The
9155 @code{@@TeX@{@}} command is unique among Texinfo commands in that the
9156 @kbd{T} and the @kbd{X} are in upper case.@refill
9157
9158
9159 @node copyright symbol,  , tex, TeX and copyright
9160 @subsection @code{@@copyright}@{@} (@copyright{})
9161 @findex copyright
9162
9163 Use the @code{@@copyright@{@}} command to generate `@copyright{}'.  In
9164 a printed manual, this is a @samp{c} inside a circle, and in Info,
9165 this is @samp{(C)}.@refill
9166
9167
9168 @node pounds, minus, TeX and copyright, Insertions
9169 @section @code{@@pounds@{@}} (@pounds{}): Pounds Sterling
9170 @findex pounds
9171
9172 Use the @code{@@pounds@{@}} command to generate `@pounds{}'.  In a
9173 printed manual, this is the symbol for the currency pounds sterling.
9174 In Info, it is a @samp{#}.  Other currency symbols are unfortunately not
9175 available.
9176
9177
9178 @node minus, math, pounds, Insertions
9179 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9180 @findex minus
9181
9182 Use the @code{@@minus@{@}} command to generate a minus sign.  In a
9183 fixed-width font, this is a single hyphen, but in a proportional font,
9184 the symbol is the customary length for a minus sign---a little longer
9185 than a hyphen, shorter than an em-dash:
9186
9187 @display
9188 @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9189
9190 `-' is a hyphen generated with the character @samp{-},
9191
9192 `---' is an em-dash for text.
9193 @end display
9194
9195 @noindent
9196 In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9197 as a hyphen.
9198
9199 You should not use @code{@@minus@{@}} inside @code{@@code} or
9200 @code{@@example} because the width distinction is not made in the
9201 fixed-width font they use.
9202
9203 When you use @code{@@minus} to specify the mark beginning each entry in
9204 an itemized list, you do not need to type the braces
9205 (@pxref{itemize, , @code{@@itemize}}.)
9206
9207
9208 @node math, Glyphs, minus, Insertions
9209 @section @code{@@math} - Inserting Mathematical Expressions
9210 @findex math
9211 @cindex Mathematical expressions
9212
9213 You can write a short mathematical expression with the @code{@@math}
9214 command.  Write the mathematical expression between braces, like this:
9215
9216 @example
9217 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9218 @end example
9219
9220 @iftex
9221 @need 1000
9222 @noindent
9223 This produces the following in @TeX{}:
9224
9225 @display
9226 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
9227 @end display
9228
9229 @noindent
9230 and the following in Info:
9231 @end iftex
9232 @ifinfo
9233 @noindent
9234 This produces the following in Info:
9235 @end ifinfo
9236
9237 @example
9238 (a + b)(a + b) = a^2 + 2ab + b^2
9239 @end example
9240
9241 Thus, the @code{@@math} command has no effect on the Info output.
9242
9243 For complex mathematical expressions, you can also use @TeX{} directly
9244 (@pxref{Raw Formatter Commands}).  When you use @TeX{} directly,
9245 remember to write the mathematical expression between one or two
9246 @samp{$} (dollar-signs) as appropriate.
9247
9248
9249 @node Glyphs, Images, math, Insertions
9250 @section Glyphs for Examples
9251 @cindex Glyphs
9252
9253 In Texinfo, code is often illustrated in examples that are delimited
9254 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9255 @code{@@end lisp}.  In such examples, you can indicate the results of
9256 evaluation or an expansion using @samp{@result{}} or
9257 @samp{@expansion{}}.  Likewise, there are commands to insert glyphs
9258 to indicate
9259 printed output, error messages, equivalence of expressions, and the
9260 location of point.@refill
9261
9262 The glyph-insertion commands do not need to be used within an example, but
9263 most often they are.  Every  glyph-insertion command is followed by a pair of
9264 left- and right-hand braces.@refill
9265
9266 @menu
9267 * Glyphs Summary::              
9268 * result::                      How to show the result of expression.
9269 * expansion::                   How to indicate an expansion.
9270 * Print Glyph::                 How to indicate printed output.
9271 * Error Glyph::                 How to indicate an error message.
9272 * Equivalence::                 How to indicate equivalence.
9273 * Point Glyph::                 How to indicate the location of point.
9274 @end menu
9275
9276 @node Glyphs Summary, result, Glyphs, Glyphs
9277 @ifinfo
9278 @subheading Glyphs Summary
9279
9280 Here are the different glyph commands:@refill
9281 @end ifinfo
9282
9283 @table @asis
9284 @item @result{}
9285 @code{@@result@{@}} points to the result of an expression.@refill
9286
9287 @item @expansion{}
9288 @code{@@expansion@{@}} shows the results of a macro expansion.@refill
9289
9290 @item @print{}
9291 @code{@@print@{@}} indicates printed output.@refill
9292
9293 @item @error{}
9294 @code{@@error@{@}} indicates that the following text is an error
9295 message.@refill
9296
9297 @item @equiv{}
9298 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9299
9300 @item @point{}
9301 @code{@@point@{@}} shows the location of point.@refill
9302 @end table
9303
9304
9305 @menu
9306 * result::                      
9307 * expansion::                   
9308 * Print Glyph::                 
9309 * Error Glyph::                 
9310 * Equivalence::                 
9311 * Point Glyph::                 
9312 @end menu
9313
9314 @node result, expansion, Glyphs Summary, Glyphs
9315 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9316 @cindex Result of an expression
9317 @cindex Indicating evaluation
9318 @cindex Evaluation glyph
9319 @cindex Value of an expression, indicating
9320
9321 Use the @code{@@result@{@}} command to indicate the result of
9322 evaluating an expression.@refill
9323
9324 @iftex
9325 The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
9326 as @samp{@result{}} in the printed output.
9327 @end iftex
9328 @ifinfo
9329 The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9330 and as a double stemmed arrow in the printed output.@refill
9331 @end ifinfo
9332
9333 Thus, the following,
9334
9335 @lisp
9336 (cdr '(1 2 3))
9337      @result{} (2 3)
9338 @end lisp
9339
9340 @noindent
9341 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9342
9343
9344 @node expansion, Print Glyph, result, Glyphs
9345 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9346 @cindex Expansion, indicating it
9347
9348 When an expression is a macro call, it expands into a new expression.
9349 You can indicate the result of the expansion with the
9350 @code{@@expansion@{@}} command.@refill
9351
9352 @iftex
9353 The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
9354 as @samp{@expansion{}} in the printed output.
9355 @end iftex
9356 @ifinfo
9357 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9358 in Info and as a long arrow with a flat base in the printed output.@refill
9359 @end ifinfo
9360
9361 @need 700
9362 For example, the following
9363
9364 @example
9365 @group
9366 @@lisp
9367 (third '(a b c))
9368      @@expansion@{@} (car (cdr (cdr '(a b c))))
9369      @@result@{@} c
9370 @@end lisp
9371 @end group
9372 @end example
9373
9374 @noindent
9375 produces
9376
9377 @lisp
9378 @group
9379 (third '(a b c))
9380      @expansion{} (car (cdr (cdr '(a b c))))
9381      @result{} c
9382 @end group
9383 @end lisp
9384
9385 @noindent
9386 which may be read as:
9387
9388 @quotation
9389 @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9390 the result of evaluating the expression is @code{c}.
9391 @end quotation
9392
9393 @noindent
9394 Often, as in this case, an example looks better if the
9395 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9396 five spaces.@refill
9397
9398
9399 @node Print Glyph, Error Glyph, expansion, Glyphs
9400 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9401 @cindex Printed output, indicating it
9402
9403 Sometimes an expression will print output during its execution.  You
9404 can indicate the printed output with the @code{@@print@{@}} command.@refill
9405
9406 @iftex
9407 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
9408 as @samp{@print{}} in the printed output.
9409 @end iftex
9410 @ifinfo
9411 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9412 and similarly, as a horizontal dash butting against a vertical bar, in
9413 the printed output.@refill
9414 @end ifinfo
9415
9416 In the following example, the printed text is indicated with
9417 @samp{@print{}}, and the value of the expression follows on the
9418 last line.@refill
9419
9420 @lisp
9421 @group
9422 (progn (print 'foo) (print 'bar))
9423      @print{} foo
9424      @print{} bar
9425      @result{} bar
9426 @end group
9427 @end lisp
9428
9429 @noindent
9430 In a Texinfo source file, this example is written as follows:
9431
9432 @lisp
9433 @group
9434 @@lisp
9435 (progn (print 'foo) (print 'bar))
9436      @@print@{@} foo
9437      @@print@{@} bar
9438      @@result@{@} bar
9439 @@end lisp
9440 @end group
9441 @end lisp
9442
9443
9444 @node Error Glyph, Equivalence, Print Glyph, Glyphs
9445 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9446 @cindex Error message, indicating it
9447
9448 A piece of code may cause an error when you evaluate it.  You can
9449 designate the error message with the @code{@@error@{@}} command.@refill
9450
9451 @iftex
9452 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
9453 and as @samp{@error{}} in the printed output.
9454 @end iftex
9455 @ifinfo
9456 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9457 and as the word `error' in a box in the printed output.@refill
9458 @end ifinfo
9459
9460 @need 700
9461 Thus,
9462
9463 @example
9464 @@lisp
9465 (+ 23 'x)
9466 @@error@{@} Wrong type argument: integer-or-marker-p, x
9467 @@end lisp
9468 @end example
9469
9470 @noindent
9471 produces
9472
9473 @lisp
9474 (+ 23 'x)
9475 @error{} Wrong type argument: integer-or-marker-p, x
9476 @end lisp
9477
9478 @noindent
9479 This indicates that the following error message is printed
9480 when you evaluate the expression:
9481
9482 @lisp
9483 Wrong type argument: integer-or-marker-p, x
9484 @end lisp
9485
9486 @samp{@error{}} itself is not part of the error message.
9487
9488
9489 @node Equivalence, Point Glyph, Error Glyph, Glyphs
9490 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9491 @cindex Equivalence, indicating it
9492
9493 Sometimes two expressions produce identical results.  You can indicate the
9494 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9495
9496 @iftex
9497 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
9498 as @samp{@equiv{}} in the printed output.
9499 @end iftex
9500 @ifinfo
9501 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9502 and as a three parallel horizontal lines in the printed output.@refill
9503 @end ifinfo
9504
9505 Thus,
9506
9507 @example
9508 @@lisp
9509 (make-sparse-keymap) @@equiv@{@} (list 'keymap)
9510 @@end lisp
9511 @end example
9512
9513 @noindent
9514 produces
9515
9516 @lisp
9517 (make-sparse-keymap) @equiv{} (list 'keymap)
9518 @end lisp
9519
9520 @noindent
9521 This indicates that evaluating @code{(make-sparse-keymap)} produces
9522 identical results to evaluating @code{(list 'keymap)}.
9523
9524
9525 @node Point Glyph,  , Equivalence, Glyphs
9526 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9527 @cindex Point, indicating it in a buffer
9528
9529 Sometimes you need to show an example of text in an Emacs buffer.  In
9530 such examples, the convention is to include the entire contents of the
9531 buffer in question between two lines of dashes containing the buffer
9532 name.@refill
9533
9534 You can use the @samp{@@point@{@}} command to show the location of point
9535 in the text in the buffer.  (The symbol for point, of course, is not
9536 part of the text in the buffer; it indicates the place @emph{between}
9537 two characters where point is located.)@refill
9538
9539 @iftex
9540 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
9541 as @samp{@point{}} in the printed output.
9542 @end iftex
9543 @ifinfo
9544 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9545 and as a small five pointed star in the printed output.@refill
9546 @end ifinfo
9547
9548 The following example shows the contents of buffer @file{foo} before
9549 and after evaluating a Lisp command to insert the word @code{changed}.@refill
9550
9551 @example
9552 @group
9553 ---------- Buffer: foo ----------
9554 This is the @point{}contents of foo.
9555 ---------- Buffer: foo ----------
9556
9557 @end group
9558 @end example
9559
9560 @example
9561 @group
9562 (insert "changed ")
9563      @result{} nil
9564 ---------- Buffer: foo ----------
9565 This is the changed @point{}contents of foo.
9566 ---------- Buffer: foo ----------
9567
9568 @end group
9569 @end example
9570
9571 In a Texinfo source file, the example is written like this:@refill
9572
9573 @example
9574 @@example
9575 ---------- Buffer: foo ----------
9576 This is the @@point@{@}contents of foo.
9577 ---------- Buffer: foo ----------
9578
9579 (insert "changed ")
9580      @@result@{@} nil
9581 ---------- Buffer: foo ----------
9582 This is the changed @@point@{@}contents of foo.
9583 ---------- Buffer: foo ----------
9584 @@end example
9585 @end example
9586
9587
9588 @c this should be described with figures when we have them
9589 @c perhaps in the quotation/example chapter.
9590 @node Images,  , Glyphs, Insertions
9591 @section Inserting Images
9592
9593 @cindex Images, inserting
9594 @cindex Pictures, inserting
9595 @findex image
9596
9597 You can insert an image in an external file with the @code{@@image}
9598 command:
9599
9600 @example
9601 @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@}
9602 @end example
9603
9604 @cindex Formats for images
9605 @cindex Image formats
9606 The @var{filename} argument is mandatory, and must not have an
9607 extension, because the different processors support different formats:
9608 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
9609 format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
9610 Info output (more or less as if it was an @code{@@example}).  HTML
9611 output requires @file{@var{filename}.jpg}.
9612
9613 @cindex Width of images
9614 @cindex Height of images
9615 @cindex Aspect ratio of images
9616 @cindex Distorting images
9617 The optional @var{width} and @var{height} arguments specify the size to
9618 scale the image to (they are ignored for Info output).  If they are both
9619 specified, the image is presented in its natural size (given in the
9620 file); if only one is specified, the other is scaled proportionately;
9621 and if both are specified, both are respected, thus possibly distorting
9622 the original image by changing its aspect ratio.
9623
9624 @cindex Dimensions and image sizes
9625 The @var{width} and @var{height} may be specified using any valid @TeX{}
9626 dimension, namely:
9627
9628 @table @asis
9629 @item pt
9630 @cindex Points (dimension)
9631 point (72.27pt = 1in)
9632 @item pc
9633 @cindex Picas
9634 pica (1pc = 12pt)
9635 @item bp
9636 @cindex Big points
9637 big point (72bp = 1in)
9638 @item in
9639 @cindex Inches
9640 inch
9641 @item cm
9642 @cindex Centimeters
9643 centimeter (2.54cm = 1in)
9644 @item mm
9645 @cindex Millimeters
9646 millimeter (10mm = 1cm)
9647 @item dd
9648 @cindex Did@^ot points
9649 did@^ot point (1157dd = 1238pt)
9650 @item cc
9651 @cindex Ciceros
9652 cicero (1cc = 12dd)
9653 @item sp
9654 @cindex Scaled points
9655 scaled point (65536sp = 1pt)
9656 @end table
9657
9658 @pindex ridt.eps
9659 For example, the following will scale a file @file{ridt.eps} to one
9660 inch vertically, with the width scaled proportionately:
9661
9662 @example
9663 @@image@{ridt,,1in@}
9664 @end example
9665
9666 @pindex epsf.tex
9667 For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
9668 installed somewhere that @TeX{} can find it.  This file is included in
9669 the Texinfo distribution and is available from
9670 @uref{ftp://ftp.tug.org/tex/epsf.tex}.
9671
9672
9673 @node Breaks, Definition Commands, Insertions, Top
9674 @chapter Making and Preventing Breaks
9675 @cindex Making line and page breaks
9676 @cindex Preventing line and page breaks
9677
9678 Usually, a Texinfo file is processed both by @TeX{} and by one of the
9679 Info formatting commands.  Line, paragraph, or page breaks sometimes
9680 occur in the `wrong' place in one or other form of output.  You must
9681 ensure that text looks right both in the printed manual and in the
9682 Info file.@refill
9683
9684 For example, in a printed manual, page breaks may occur awkwardly in
9685 the middle of an example; to prevent this, you can hold text together
9686 using a grouping command that keeps the text from being split across
9687 two pages.  Conversely, you may want to force a page break where none
9688 would occur normally.  Fortunately, problems like these do not often
9689 arise.  When they do, use the break, break prevention, or pagination
9690 commands.@refill
9691
9692 @menu
9693 * Break Commands::              Cause and prevent splits.
9694 * Line Breaks::                 How to force a single line to use two lines.
9695 * - and hyphenation::           How to tell TeX about hyphenation points.
9696 * w::                           How to prevent unwanted line breaks.
9697 * sp::                          How to insert blank lines.
9698 * page::                        How to force the start of a new page.
9699 * group::                       How to prevent unwanted page breaks.
9700 * need::                        Another way to prevent unwanted page breaks.
9701 @end menu
9702
9703 @ifinfo
9704 @node Break Commands, Line Breaks, Breaks, Breaks
9705 @heading The Break Commands
9706 @end ifinfo
9707 @iftex
9708 @sp 1
9709 @end iftex
9710
9711 The break commands create or allow line and paragraph breaks:@refill
9712
9713 @table @code
9714 @item @@*
9715 Force a line break.
9716
9717 @item @@sp @var{n}
9718 Skip @var{n} blank lines.@refill
9719
9720 @item @@-
9721 Insert a discretionary hyphen.
9722
9723 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
9724 Define hyphen points in @var{hy-phen-a-ted words}.
9725 @end table
9726
9727 The line-break-prevention command holds text together all on one
9728 line:@refill
9729
9730 @table @code
9731 @item @@w@{@var{text}@}
9732 Prevent @var{text} from being split and hyphenated across two lines.@refill
9733 @end table
9734 @iftex
9735 @sp 1
9736 @end iftex
9737
9738 The pagination commands apply only to printed output, since Info
9739 files do not have pages.@refill
9740
9741 @table @code
9742 @item @@page
9743 Start a new page in the printed manual.@refill
9744
9745 @item @@group
9746 Hold text together that must appear on one printed page.@refill
9747
9748 @item @@need @var{mils}
9749 Start a new printed page if not enough space on this one.@refill
9750 @end table
9751
9752 @node Line Breaks, - and hyphenation, Break Commands, Breaks
9753 @comment  node-name,  next,  previous,  up
9754 @section @code{@@*}: Generate Line Breaks
9755 @findex * @r{(force line break)}
9756 @cindex Line breaks
9757 @cindex Breaks in a line
9758
9759 The @code{@@*} command forces a line break in both the printed manual and
9760 in Info.@refill
9761
9762 @need 700
9763 For example,
9764
9765 @example
9766 This line @@* is broken @@*in two places.
9767 @end example
9768
9769 @noindent
9770 produces
9771
9772 @example
9773 @group
9774 This line
9775  is broken
9776 in two places.
9777 @end group
9778 @end example
9779
9780 @noindent
9781 (Note that the space after the first @code{@@*} command is faithfully
9782 carried down to the next line.)@refill
9783
9784 @need 800
9785 The @code{@@*} command is often used in a file's copyright page:@refill
9786
9787 @example
9788 @group
9789 This is edition 2.0 of the Texinfo documentation,@@*
9790 and is for @dots{}
9791 @end group
9792 @end example
9793
9794 @noindent
9795 In this case, the @code{@@*} command keeps @TeX{} from stretching the
9796 line across the whole page in an ugly manner.@refill
9797
9798 @quotation
9799 @strong{Please note:} Do not write braces after an @code{@@*} command;
9800 they are not needed.@refill
9801
9802 Do not write an @code{@@refill} command at the end of a paragraph
9803 containing an @code{@@*} command; it will cause the paragraph to be
9804 refilled after the line break occurs, negating the effect of the line
9805 break.@refill
9806 @end quotation
9807
9808 @node - and hyphenation, w, Line Breaks, Breaks
9809 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
9810
9811 @findex -
9812 @findex hyphenation
9813 @cindex Hyphenation, helping @TeX{} do
9814 @cindex Fine-tuning, and hyphenation
9815
9816 Although @TeX{}'s hyphenation algorithm is generally pretty good, it
9817 does miss useful hyphenation points from time to time.  (Or, far more
9818 rarely, insert an incorrect hyphenation.)  So, for documents with an
9819 unusual vocabulary or when fine-tuning for a printed edition, you may
9820 wish to help @TeX{} out.  Texinfo supports two commands for this:
9821
9822 @table @code
9823 @item @@-
9824 Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
9825 not have to) hyphenate.  This is especially useful when you notice
9826 an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
9827 hboxes}).  @TeX{} will not insert any hyphenation points in a word
9828 containing @code{@@-}.
9829
9830 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
9831 Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}.  As shown, you
9832 put a @samp{-} at each hyphenation point.  For example:
9833 @example
9834 @@hyphenation@{man-u-script man-u-scripts@}
9835 @end example
9836 @noindent
9837 @TeX{} only uses the specified hyphenation points when the
9838 words match exactly, so give all necessary variants.
9839 @end table
9840
9841 Info output is not hyphenated, so these commands have no effect there.
9842
9843 @node w, sp, - and hyphenation, Breaks
9844 @comment  node-name,  next,  previous,  up
9845 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
9846 @findex w @r{(prevent line break)}
9847 @cindex Line breaks, preventing
9848 @cindex Hyphenation, preventing
9849
9850 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
9851 within @var{text}.@refill
9852
9853 You can use the @code{@@w} command to prevent @TeX{} from automatically
9854 hyphenating a long name or phrase that happens to fall near the end of a
9855 line.@refill
9856
9857 @example
9858 You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}.
9859 @end example
9860
9861 @noindent
9862 produces
9863
9864 @quotation
9865 You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
9866 @end quotation
9867
9868 @quotation
9869 @strong{Caution:} Do not write an @code{@@refill} command at the end
9870 of a paragraph containing an @code{@@w} command; it will cause the
9871 paragraph to be refilled and may thereby negate the effect of the
9872 @code{@@w} command.@refill
9873 @end quotation
9874
9875 @node sp, page, w, Breaks
9876 @comment  node-name,  next,  previous,  up
9877 @section @code{@@sp} @var{n}: Insert Blank Lines
9878 @findex sp @r{(line spacing)}
9879 @cindex Spaces (blank lines)
9880 @cindex Blank lines
9881 @cindex Line spacing
9882
9883 A line beginning with and containing only @code{@@sp @var{n}}
9884 generates @var{n} blank lines of space in both the printed manual and
9885 the Info file.  @code{@@sp} also forces a paragraph break.  For
9886 example,@refill
9887
9888 @example
9889 @@sp 2
9890 @end example
9891
9892 @noindent
9893 generates two blank lines.
9894
9895 The @code{@@sp} command is most often used in the title page.@refill
9896
9897 @ignore
9898 @c node br, page, sp, Breaks
9899 @comment  node-name,  next,  previous,  up
9900 @c section @code{@@br}: Generate Paragraph Breaks
9901 @findex br @r{(paragraph breaks)}
9902 @cindex Paragraph breaks
9903 @cindex Breaks in a paragraph
9904
9905 The @code{@@br} command forces a paragraph break.  It inserts a blank
9906 line.  You can use the command within or at the end of a line.  If
9907 used within a line, the @code{@@br@{@}} command must be followed by
9908 left and right braces (as shown here) to mark the end of the
9909 command.@refill
9910
9911 @need 700
9912 For example,
9913
9914 @example
9915 @group
9916 This line @@br@{@}contains and is ended by paragraph breaks@@br
9917 and is followed by another line.
9918 @end group
9919 @end example
9920
9921 @noindent
9922 produces
9923
9924 @example
9925 @group
9926 This line
9927
9928 contains and is ended by paragraph breaks
9929
9930 and is followed by another line.
9931 @end group
9932 @end example
9933
9934 The @code{@@br} command is seldom used.
9935 @end ignore
9936
9937 @node page, group, sp, Breaks
9938 @comment  node-name,  next,  previous,  up
9939 @section @code{@@page}: Start a New Page
9940 @cindex Page breaks
9941 @findex page
9942
9943 A line containing only @code{@@page} starts a new page in a printed
9944 manual.  The command has no effect on Info files since they are not
9945 paginated.  An @code{@@page} command is often used in the @code{@@titlepage}
9946 section of a Texinfo file to start the copyright page.@refill
9947
9948 @node group, need, page, Breaks
9949 @comment  node-name,  next,  previous,  up
9950 @section @code{@@group}: Prevent Page Breaks
9951 @cindex Group (hold text together vertically)
9952 @cindex Holding text together vertically
9953 @cindex Vertically holding text together
9954 @findex group
9955
9956 The @code{@@group} command (on a line by itself) is used inside an
9957 @code{@@example} or similar construct to begin an unsplittable vertical
9958 group, which will appear entirely on one page in the printed output.
9959 The group is terminated by a line containing only @code{@@end group}.
9960 These two lines produce no output of their own, and in the Info file
9961 output they have no effect at all.@refill
9962
9963 @c Once said that these environments
9964 @c turn off vertical spacing between ``paragraphs''.
9965 @c Also, quotation used to work, but doesn't in texinfo-2.72
9966 Although @code{@@group} would make sense conceptually in a wide
9967 variety of contexts, its current implementation works reliably only
9968 within @code{@@example} and variants, and within @code{@@display},
9969 @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
9970 @xref{Quotations and Examples}.  (What all these commands have in
9971 common is that each line of input produces a line of output.)  In
9972 other contexts, @code{@@group} can cause anomalous vertical
9973 spacing.@refill
9974
9975 @need 750
9976 This formatting requirement means that you should write:
9977
9978 @example
9979 @group
9980 @@example
9981 @@group
9982 @dots{}
9983 @@end group
9984 @@end example
9985 @end group
9986 @end example
9987
9988 @noindent
9989 with the @code{@@group} and @code{@@end group} commands inside the
9990 @code{@@example} and @code{@@end example} commands.
9991
9992 The @code{@@group} command is most often used to hold an example
9993 together on one page.  In this Texinfo manual, more than 100 examples
9994 contain text that is enclosed between @code{@@group} and @code{@@end
9995 group}.
9996
9997 If you forget to end a group, you may get strange and unfathomable
9998 error messages when you run @TeX{}.  This is because @TeX{} keeps
9999 trying to put the rest of the Texinfo file onto the one page and does
10000 not start to generate error messages until it has processed
10001 considerable text.  It is a good rule of thumb to look for a missing
10002 @code{@@end group} if you get incomprehensible error messages in
10003 @TeX{}.@refill
10004
10005 @node need,  , group, Breaks
10006 @comment  node-name,  next,  previous,  up
10007 @section @code{@@need @var{mils}}: Prevent Page Breaks
10008 @cindex Need space at page bottom
10009 @findex need
10010
10011 A line containing only @code{@@need @var{n}} starts
10012 a new page in a printed manual if fewer than @var{n} mils (thousandths
10013 of an inch) remain on the current page.  Do not use
10014 braces around the argument @var{n}.  The @code{@@need} command has no
10015 effect on Info files since they are not paginated.@refill
10016
10017 @need 800
10018 This paragraph is preceded by an @code{@@need} command that tells
10019 @TeX{} to start a new page if fewer than 800 mils (eight-tenths
10020 inch) remain on the page.  It looks like this:@refill
10021
10022 @example
10023 @group
10024 @@need 800
10025 This paragraph is preceded by @dots{}
10026 @end group
10027 @end example
10028
10029 The @code{@@need} command is useful for preventing orphans (single
10030 lines at the bottoms of printed pages).@refill
10031
10032 @node Definition Commands, Footnotes, Breaks, Top
10033 @chapter Definition Commands
10034 @cindex Definition commands
10035
10036 The @code{@@deffn} command and the other @dfn{definition commands}
10037 enable you to describe functions, variables, macros, commands, user
10038 options, special forms and other such artifacts in a uniform
10039 format.@refill
10040
10041 In the Info file, a definition causes the entity
10042 category---`Function', `Variable', or whatever---to appear at the
10043 beginning of the first line of the definition, followed by the
10044 entity's name and arguments.  In the printed manual, the command
10045 causes @TeX{} to print the entity's name and its arguments on the left
10046 margin and print the category next to the right margin.  In both
10047 output formats, the body of the definition is indented.  Also, the
10048 name of the entity is entered into the appropriate index:
10049 @code{@@deffn} enters the name into the index of functions,
10050 @code{@@defvr} enters it into the index of variables, and so
10051 on.@refill
10052
10053 A manual need not and should not contain more than one definition for
10054 a given name.  An appendix containing a summary should use
10055 @code{@@table} rather than the definition commands.@refill
10056
10057 @menu
10058 * Def Cmd Template::            How to structure a description using a
10059                                   definition command.
10060 * Optional Arguments::          How to handle optional and repeated arguments.
10061 * deffnx::                      How to group two or more `first' lines.
10062 * Def Cmds in Detail::          All the definition commands.
10063 * Def Cmd Conventions::         Conventions for writing definitions.
10064 * Sample Function Definition::  
10065 @end menu
10066
10067 @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10068 @section The Template for a Definition
10069 @cindex Definition template
10070 @cindex Template for a definition
10071
10072 The @code{@@deffn} command is used for definitions of entities that
10073 resemble functions.  To write a definition using the @code{@@deffn}
10074 command, write the @code{@@deffn} command at the beginning of a line
10075 and follow it on the same line by the category of the entity, the name
10076 of the entity itself, and its arguments (if any).  Then write the body
10077 of the definition on succeeding lines.  (You may embed examples in the
10078 body.)  Finally, end the definition with an @code{@@end deffn} command
10079 written on a line of its own.  (The other definition commands follow
10080 the same format.)@refill
10081
10082 The template for a definition looks like this:
10083
10084 @example
10085 @group
10086 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10087 @var{body-of-definition}
10088 @@end deffn
10089 @end group
10090 @end example
10091
10092 @need 700
10093 @noindent
10094 For example,
10095
10096 @example
10097 @group
10098 @@deffn Command forward-word count
10099 This command moves point forward @@var@{count@} words
10100 (or backward if @@var@{count@} is negative). @dots{}
10101 @@end deffn
10102 @end group
10103 @end example
10104
10105 @noindent
10106 produces
10107
10108 @quotation
10109 @deffn Command forward-word count
10110 This function moves point forward @var{count} words
10111 (or backward if @var{count} is negative). @dots{}
10112 @end deffn
10113 @end quotation
10114
10115 Capitalize the category name like a title.  If the name of the
10116 category contains spaces, as in the phrase `Interactive Command',
10117 write braces around it.  For example:@refill
10118
10119 @example
10120 @group
10121 @@deffn @{Interactive Command@} isearch-forward
10122 @dots{}
10123 @@end deffn
10124 @end group
10125 @end example
10126
10127 @noindent
10128 Otherwise, the second word will be mistaken for the name of the
10129 entity.@refill
10130
10131 Some of the definition commands are more general than others.  The
10132 @code{@@deffn} command, for example, is the general definition command
10133 for functions and the like---for entities that may take arguments.  When
10134 you use this command, you specify the category to which the entity
10135 belongs.  The @code{@@deffn} command possesses three predefined,
10136 specialized variations, @code{@@defun}, @code{@@defmac}, and
10137 @code{@@defspec}, that specify the category for you: ``Function'',
10138 ``Macro'', and ``Special Form'' respectively.  (In Lisp, a special form
10139 is an entity much like a function.)  The @code{@@defvr} command also is
10140 accompanied by several predefined, specialized variations for describing
10141 particular kinds of variables.@refill
10142
10143 The template for a specialized definition, such as @code{@@defun}, is
10144 similar to the template for a generalized definition, except that you
10145 do not need to specify the category:@refill
10146
10147 @example
10148 @group
10149 @@defun @var{name} @var{arguments}@dots{}
10150 @var{body-of-definition}
10151 @@end defun
10152 @end group
10153 @end example
10154
10155 @noindent
10156 Thus,
10157
10158 @example
10159 @group
10160 @@defun buffer-end flag
10161 This function returns @@code@{(point-min)@} if @@var@{flag@}
10162 is less than 1, @@code@{(point-max)@} otherwise.
10163 @dots{}
10164 @@end defun
10165 @end group
10166 @end example
10167
10168 @noindent
10169 produces
10170
10171 @quotation
10172 @defun buffer-end flag
10173 This function returns @code{(point-min)} if @var{flag} is less than 1,
10174 @code{(point-max)} otherwise.  @dots{}
10175 @end defun
10176 @end quotation
10177
10178 @noindent
10179 @xref{Sample Function Definition, Sample Function Definition, A Sample
10180 Function Definition}, for a more detailed example of a function
10181 definition, including the use of @code{@@example} inside the
10182 definition.@refill
10183
10184 The other specialized commands work like @code{@@defun}.@refill
10185
10186 @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10187 @section Optional and Repeated Arguments
10188 @cindex Optional and repeated arguments
10189 @cindex Repeated and optional arguments
10190 @cindex Arguments, repeated and optional
10191 @cindex Syntax, optional & repeated arguments
10192 @cindex Meta-syntactic chars for arguments
10193
10194 Some entities take optional or repeated arguments, which may be
10195 specified by a distinctive glyph that uses square brackets and
10196 ellipses.  For @w{example}, a special form often breaks its argument list
10197 into separate arguments in more complicated ways than a
10198 straightforward function.@refill
10199
10200 @iftex
10201 An argument enclosed within square brackets is optional.
10202 Thus, the phrase
10203 @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
10204 @var{optional-arg} is optional.
10205 An argument followed by an ellipsis is optional
10206 and may be repeated more than once.
10207 @c This is consistent with Emacs Lisp Reference manual
10208 Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
10209 Parentheses are used when several arguments are grouped
10210 into additional levels of list structure in Lisp.
10211 @end iftex
10212 @c The following looks better in Info (no `r', `samp' and `code'):
10213 @ifinfo
10214 An argument enclosed within square brackets is optional.
10215 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10216 An argument followed by an ellipsis is optional
10217 and may be repeated more than once.
10218 @c This is consistent with Emacs Lisp Reference manual
10219 Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10220 Parentheses are used when several arguments are grouped
10221 into additional levels of list structure in Lisp.
10222 @end ifinfo
10223
10224 Here is the @code{@@defspec} line of an example of an imaginary
10225 special form:@refill
10226
10227 @quotation
10228 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10229 @end defspec
10230 @tex
10231 \vskip \parskip
10232 @end tex
10233 @end quotation
10234
10235 @noindent
10236 In this example, the arguments @var{from} and @var{to} are optional,
10237 but must both be present or both absent.  If they are present,
10238 @var{inc} may optionally be specified as well.  These arguments are
10239 grouped with the argument @var{var} into a list, to distinguish them
10240 from @var{body}, which includes all remaining elements of the
10241 form.@refill
10242
10243 In a Texinfo source file, this @code{@@defspec} line is written like
10244 this (except it would not be split over two lines, as it is in this
10245 example).@refill
10246
10247 @example
10248 @group
10249 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10250      [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10251 @end group
10252 @end example
10253
10254 @noindent
10255 The function is listed in the Command and Variable Index under
10256 @samp{foobar}.@refill
10257
10258 @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10259 @section Two or More `First' Lines
10260 @cindex Two `First' Lines for @code{@@deffn}
10261 @cindex Grouping two definitions together
10262 @cindex Definitions grouped together
10263 @findex deffnx
10264
10265 To create two or more `first' or header lines for a definition, follow
10266 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10267 The @code{@@deffnx} command works exactly like @code{@@deffn}
10268 except that it does not generate extra vertical white space between it
10269 and the preceding line.@refill
10270
10271 @need 1000
10272 For example,
10273
10274 @example
10275 @group
10276 @@deffn @{Interactive Command@} isearch-forward
10277 @@deffnx @{Interactive Command@} isearch-backward
10278 These two search commands are similar except @dots{}
10279 @@end deffn
10280 @end group
10281 @end example
10282
10283 @noindent
10284 produces
10285
10286 @deffn {Interactive Command} isearch-forward
10287 @deffnx {Interactive Command} isearch-backward
10288 These two search commands are similar except @dots{}
10289 @end deffn
10290
10291 Each of the other definition commands has an `x' form: @code{@@defunx},
10292 @code{@@defvrx}, @code{@@deftypefunx}, etc.
10293
10294 The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10295
10296 @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10297 @section The Definition Commands
10298
10299 Texinfo provides more than a dozen definition commands, all of which
10300 are described in this section.@refill
10301
10302 The definition commands automatically enter the name of the entity in
10303 the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10304 and @code{@@defmac} enter function names in the index of functions;
10305 @code{@@defvr} and @code{@@defvar} enter variable names in the index
10306 of variables.@refill
10307
10308 Although the examples that follow mostly illustrate Lisp, the commands
10309 can be used for other programming languages.@refill
10310
10311 @menu
10312 * Functions Commands::          Commands for functions and similar entities.
10313 * Variables Commands::          Commands for variables and similar entities.
10314 * Typed Functions::             Commands for functions in typed languages.
10315 * Typed Variables::             Commands for variables in typed languages.
10316 * Abstract Objects::            Commands for object-oriented programming.
10317 * Data Types::                  The definition command for data types.
10318 @end menu
10319
10320 @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10321 @subsection Functions and Similar Entities
10322
10323 This section describes the commands for describing functions and similar
10324 entities:@refill
10325
10326 @table @code
10327 @findex deffn
10328 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10329 The @code{@@deffn} command is the general definition command for
10330 functions, interactive commands, and similar entities that may take
10331 arguments.  You must choose a term to describe the category of entity
10332 being defined; for example, ``Function'' could be used if the entity is
10333 a function.  The @code{@@deffn} command is written at the beginning of a
10334 line and is followed on the same line by the category of entity being
10335 described, the name of this particular entity, and its arguments, if
10336 any.  Terminate the definition with @code{@@end deffn} on a line of its
10337 own.@refill
10338
10339 @need 750
10340 For example, here is a definition:
10341
10342 @example
10343 @group
10344 @@deffn Command forward-char nchars
10345 Move point forward @@var@{nchars@} characters.
10346 @@end deffn
10347 @end group
10348 @end example
10349
10350 @noindent
10351 This shows a rather terse definition for a ``command'' named
10352 @code{forward-char} with one argument, @var{nchars}.
10353
10354 @code{@@deffn} prints argument names such as @var{nchars} in italics or
10355 upper case, as if @code{@@var} had been used, because we think of these
10356 names as metasyntactic variables---they stand for the actual argument
10357 values.  Within the text of the description, write an argument name
10358 explicitly with @code{@@var} to refer to the value of the argument.  In
10359 the example above, we used @samp{@@var@{nchars@}} in this way.
10360
10361 The template for @code{@@deffn} is:
10362
10363 @example
10364 @group
10365 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10366 @var{body-of-definition}
10367 @@end deffn
10368 @end group
10369 @end example
10370
10371 @findex defun
10372 @item @@defun @var{name} @var{arguments}@dots{}
10373 The @code{@@defun} command is the definition command for functions.
10374 @code{@@defun} is equivalent to @samp{@@deffn Function
10375 @dots{}}.@refill
10376
10377 @need 800
10378 @noindent
10379 For example,
10380
10381 @example
10382 @group
10383 @@defun set symbol new-value
10384 Change the value of the symbol @@var@{symbol@}
10385 to @@var@{new-value@}.
10386 @@end defun
10387 @end group
10388 @end example
10389
10390 @noindent
10391 shows a rather terse definition for a function @code{set} whose
10392 arguments are @var{symbol} and @var{new-value}.  The argument names on
10393 the @code{@@defun} line automatically appear in italics or upper case as
10394 if they were enclosed in @code{@@var}.  Terminate the definition with
10395 @code{@@end defun} on a line of its own.@refill
10396
10397 The template is:
10398
10399 @example
10400 @group
10401 @@defun @var{function-name} @var{arguments}@dots{}
10402 @var{body-of-definition}
10403 @@end defun
10404 @end group
10405 @end example
10406
10407 @code{@@defun} creates an entry in the index of functions.
10408
10409 @findex defmac
10410 @item @@defmac @var{name} @var{arguments}@dots{}
10411 The @code{@@defmac} command is the definition command for macros.
10412 @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
10413 works like @code{@@defun}.@refill
10414
10415 @findex defspec
10416 @item @@defspec @var{name} @var{arguments}@dots{}
10417 The @code{@@defspec} command is the definition command for special
10418 forms.  (In Lisp, a special form is an entity much like a function,
10419 @pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.)
10420 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
10421 @dots{}} and works like @code{@@defun}.@refill
10422 @end table
10423
10424 @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
10425 @subsection Variables and Similar Entities
10426
10427 Here are the commands for defining variables and similar
10428 entities:@refill
10429
10430 @table @code
10431 @findex defvr
10432 @item @@defvr @var{category} @var{name}
10433 The @code{@@defvr} command is a general definition command for
10434 something like a variable---an entity that records a value.  You must
10435 choose a term to describe the category of entity being defined; for
10436 example, ``Variable'' could be used if the entity is a variable.
10437 Write the @code{@@defvr} command at the beginning of a line and
10438 followed it on the same line by the category of the entity and the
10439 name of the entity.@refill
10440
10441 Capitalize the category name like a title.  If the name of the category
10442 contains spaces, as in the name ``User Option'', enclose it in braces.
10443 Otherwise, the second word will be mistaken for the name of the entity.
10444 For example,
10445
10446 @example
10447 @group
10448 @@defvr @{User Option@} fill-column
10449 This buffer-local variable specifies
10450 the maximum width of filled lines.
10451 @dots{}
10452 @@end defvr
10453 @end group
10454 @end example
10455
10456 Terminate the definition with @code{@@end defvr} on a line of its
10457 own.@refill
10458
10459 The template is:
10460
10461 @example
10462 @group
10463 @@defvr @var{category} @var{name}
10464 @var{body-of-definition}
10465 @@end defvr
10466 @end group
10467 @end example
10468
10469 @code{@@defvr} creates an entry in the index of variables for @var{name}.
10470
10471 @findex defvar
10472 @item @@defvar @var{name}
10473 The @code{@@defvar} command is the definition command for variables.
10474 @code{@@defvar} is equivalent to @samp{@@defvr Variable
10475 @dots{}}.@refill
10476
10477 @need 750
10478 For example:
10479
10480 @example
10481 @group
10482 @@defvar kill-ring
10483 @dots{}
10484 @@end defvar
10485 @end group
10486 @end example
10487
10488 The template is:
10489
10490 @example
10491 @group
10492 @@defvar @var{name}
10493 @var{body-of-definition}
10494 @@end defvar
10495 @end group
10496 @end example
10497
10498 @code{@@defvar} creates an entry in the index of variables for
10499 @var{name}.@refill
10500
10501 @findex defopt
10502 @item @@defopt @var{name}
10503 @cindex User options, marking
10504 The @code{@@defopt} command is the definition command for @dfn{user
10505 options}, i.e., variables intended for users to change according to
10506 taste; Emacs has many such (@pxref{Variables,,, xemacs, XEmacs User's
10507 Manual}).  @code{@@defopt} is equivalent to @samp{@@defvr @{User
10508 Option@} @dots{}} and works like @code{@@defvar}.@refill
10509 @end table
10510
10511
10512 @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
10513 @subsection Functions in Typed Languages
10514
10515 The @code{@@deftypefn} command and its variations are for describing
10516 functions in languages in which you must declare types of variables and
10517 functions, such as C and C++.
10518
10519 @table @code
10520 @findex deftypefn
10521 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
10522 The @code{@@deftypefn} command is the general definition command for
10523 functions and similar entities that may take arguments and that are
10524 typed.  The @code{@@deftypefn} command is written at the beginning of
10525 a line and is followed on the same line by the category of entity
10526 being described, the type of the returned value, the name of this
10527 particular entity, and its arguments, if any.@refill
10528
10529 @need 800
10530 @noindent
10531 For example,
10532
10533 @example
10534 @group
10535 @@deftypefn @{Library Function@} int foobar
10536    (int @@var@{foo@}, float @@var@{bar@})
10537 @dots{}
10538 @@end deftypefn
10539 @end group
10540 @end example
10541
10542 @need 1000
10543 @noindent
10544 (where the text before the ``@dots{}'', shown above as two lines, would
10545 actually be a single line in a real Texinfo file) produces the following
10546 in Info:
10547
10548 @smallexample
10549 @group
10550 -- Library Function: int foobar (int FOO, float BAR)
10551 @dots{}
10552 @end group
10553 @end smallexample
10554 @iftex
10555
10556 In a printed manual, it produces:
10557
10558 @quotation
10559 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
10560 @dots{}
10561 @end deftypefn
10562 @end quotation
10563 @end iftex
10564
10565 This means that @code{foobar} is a ``library function'' that returns an
10566 @code{int}, and its arguments are @var{foo} (an @code{int}) and
10567 @var{bar} (a @code{float}).@refill
10568
10569 The argument names that you write in @code{@@deftypefn} are not subject
10570 to an implicit @code{@@var}---since the actual names of the arguments in
10571 @code{@@deftypefn} are typically scattered among data type names and
10572 keywords, Texinfo cannot find them without help.  Instead, you must write
10573 @code{@@var} explicitly around the argument names.  In the example
10574 above, the argument names are @samp{foo} and @samp{bar}.@refill
10575
10576 The template for @code{@@deftypefn} is:@refill
10577
10578 @example
10579 @group
10580 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
10581 @var{body-of-description}
10582 @@end deftypefn
10583 @end group
10584 @end example
10585
10586 @noindent
10587 Note that if the @var{category} or @var{data type} is more than one
10588 word then it must be enclosed in braces to make it a single argument.@refill
10589
10590 If you are describing a procedure in a language that has packages,
10591 such as Ada, you might consider using @code{@@deftypefn} in a manner
10592 somewhat contrary to the convention described in the preceding
10593 paragraphs.@refill
10594
10595 @need 800
10596 @noindent
10597 For example:
10598
10599 @example
10600 @group
10601 @@deftypefn stacks private push
10602         (@@var@{s@}:in out stack;
10603         @@var@{n@}:in integer)
10604 @dots{}
10605 @@end deftypefn
10606 @end group
10607 @end example
10608
10609 @noindent
10610 (The @code{@@deftypefn} arguments are shown split into three lines, but
10611 would be a single line in a real Texinfo file.)
10612
10613 In this instance, the procedure is classified as belonging to the
10614 package @code{stacks} rather than classified as a `procedure' and its
10615 data type is described as @code{private}.  (The name of the procedure
10616 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
10617
10618 @code{@@deftypefn} creates an entry in the index of functions for
10619 @var{name}.@refill
10620
10621 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
10622 @findex deftypefun
10623 The @code{@@deftypefun} command is the specialized definition command
10624 for functions in typed languages.  The command is equivalent to
10625 @samp{@@deftypefn Function @dots{}}.@refill
10626
10627 @need 800
10628 @noindent
10629 Thus,
10630
10631 @smallexample
10632 @group
10633 @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
10634 @dots{}
10635 @@end deftypefun
10636 @end group
10637 @end smallexample
10638
10639 @noindent
10640 produces the following in Info:
10641
10642 @example
10643 @group
10644 -- Function: int foobar (int FOO, float BAR)
10645 @dots{}
10646 @end group
10647 @end example
10648 @iftex
10649
10650 @need 800
10651 @noindent
10652 and the following in a printed manual:
10653
10654 @quotation
10655 @deftypefun int foobar (int @var{foo}, float @var{bar})
10656 @dots{}
10657 @end deftypefun
10658 @end quotation
10659 @end iftex
10660
10661 @need 800
10662 The template is:
10663
10664 @example
10665 @group
10666 @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
10667 @var{body-of-description}
10668 @@end deftypefun
10669 @end group
10670 @end example
10671
10672 @code{@@deftypefun} creates an entry in the index of functions for
10673 @var{name}.@refill
10674
10675 @end table
10676
10677
10678 @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
10679 @subsection Variables in Typed Languages
10680
10681 Variables in typed languages are handled in a manner similar to
10682 functions in typed languages.  @xref{Typed Functions}.  The general
10683 definition command @code{@@deftypevr} corresponds to
10684 @code{@@deftypefn} and the specialized definition command
10685 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
10686
10687 @table @code
10688 @findex deftypevr
10689 @item @@deftypevr @var{category} @var{data-type} @var{name}
10690 The @code{@@deftypevr} command is the general definition command for
10691 something like a variable in a typed language---an entity that records
10692 a value.  You must choose a term to describe the category of the
10693 entity being defined; for example, ``Variable'' could be used if the
10694 entity is a variable.@refill
10695
10696 The @code{@@deftypevr} command is written at the beginning of a line
10697 and is followed on the same line by the category of the entity
10698 being described, the data type, and the name of this particular
10699 entity.@refill
10700
10701 @need 800
10702 @noindent
10703 For example:
10704
10705 @example
10706 @group
10707 @@deftypevr @{Global Flag@} int enable
10708 @dots{}
10709 @@end deftypevr
10710 @end group
10711 @end example
10712
10713 @noindent
10714 produces the following in Info:
10715
10716 @example
10717 @group
10718 -- Global Flag: int enable
10719 @dots{}
10720 @end group
10721 @end example
10722 @iftex
10723
10724 @noindent
10725 and the following in a printed manual:
10726
10727 @quotation
10728 @deftypevr {Global Flag} int enable
10729 @dots{}
10730 @end deftypevr
10731 @end quotation
10732 @end iftex
10733
10734 @need 800
10735 The template is:
10736
10737 @example
10738 @@deftypevr @var{category} @var{data-type} @var{name}
10739 @var{body-of-description}
10740 @@end deftypevr
10741 @end example
10742
10743 @code{@@deftypevr} creates an entry in the index of variables for
10744 @var{name}.@refill
10745
10746 @findex deftypevar
10747 @item @@deftypevar @var{data-type} @var{name}
10748 The @code{@@deftypevar} command is the specialized definition command
10749 for variables in typed languages.  @code{@@deftypevar} is equivalent
10750 to @samp{@@deftypevr Variable @dots{}}.@refill
10751
10752 @need 800
10753 @noindent
10754 For example:
10755
10756 @example
10757 @group
10758 @@deftypevar int fubar
10759 @dots{}
10760 @@end deftypevar
10761 @end group
10762 @end example
10763
10764 @noindent
10765 produces the following in Info:
10766
10767 @example
10768 @group
10769 -- Variable: int fubar
10770 @dots{}
10771 @end group
10772 @end example
10773 @iftex
10774
10775 @need 800
10776 @noindent
10777 and the following in a printed manual:
10778
10779 @quotation
10780 @deftypevar int fubar
10781 @dots{}
10782 @end deftypevar
10783 @end quotation
10784 @end iftex
10785
10786 @need 800
10787 @noindent
10788 The template is:
10789
10790 @example
10791 @group
10792 @@deftypevar @var{data-type} @var{name}
10793 @var{body-of-description}
10794 @@end deftypevar
10795 @end group
10796 @end example
10797
10798 @code{@@deftypevar} creates an entry in the index of variables for
10799 @var{name}.@refill
10800 @end table
10801
10802 @node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail
10803 @subsection Object-Oriented Programming
10804
10805 Here are the commands for formatting descriptions about abstract
10806 objects, such as are used in object-oriented programming.  A class is
10807 a defined type of abstract object.  An instance of a class is a
10808 particular object that has the type of the class.  An instance
10809 variable is a variable that belongs to the class but for which each
10810 instance has its own value.@refill
10811
10812 In a definition, if the name of a class is truly a name defined in the
10813 programming system for a class, then you should write an @code{@@code}
10814 around it.  Otherwise, it is printed in the usual text font.@refill
10815
10816 @table @code
10817 @findex defcv
10818 @item @@defcv @var{category} @var{class} @var{name}
10819 The @code{@@defcv} command is the general definition command for
10820 variables associated with classes in object-oriented programming.  The
10821 @code{@@defcv} command is followed by three arguments: the category of
10822 thing being defined, the class to which it belongs, and its
10823 name.  Thus,@refill
10824
10825 @example
10826 @group
10827 @@defcv @{Class Option@} Window border-pattern
10828 @dots{}
10829 @@end defcv
10830 @end group
10831 @end example
10832
10833 @noindent
10834 illustrates how you would write the first line of a definition of the
10835 @code{border-pattern} class option of the class @code{Window}.@refill
10836
10837 The template is
10838
10839 @example
10840 @group
10841 @@defcv @var{category} @var{class} @var{name}
10842 @dots{}
10843 @@end defcv
10844 @end group
10845 @end example
10846
10847 @code{@@defcv} creates an entry in the index of variables.
10848
10849 @findex defivar
10850 @item @@defivar @var{class} @var{name}
10851 The @code{@@defivar} command is the definition command for instance
10852 variables in object-oriented programming.  @code{@@defivar} is
10853 equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
10854
10855 The template is:
10856
10857 @example
10858 @group
10859 @@defivar @var{class} @var{instance-variable-name}
10860 @var{body-of-definition}
10861 @@end defivar
10862 @end group
10863 @end example
10864
10865 @code{@@defivar} creates an entry in the index of variables.
10866
10867 @findex defop
10868 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
10869 The @code{@@defop} command is the general definition command for
10870 entities that may resemble methods in object-oriented programming.
10871 These entities take arguments, as functions do, but are associated
10872 with particular classes of objects.@refill
10873
10874 For example, some systems have constructs called @dfn{wrappers} that
10875 are associated with classes as methods are, but that act more like
10876 macros than like functions.  You could use @code{@@defop Wrapper} to
10877 describe one of these.@refill
10878
10879 Sometimes it is useful to distinguish methods and @dfn{operations}.
10880 You can think of an operation as the specification for a method.
10881 Thus, a window system might specify that all window classes have a
10882 method named @code{expose}; we would say that this window system
10883 defines an @code{expose} operation on windows in general.  Typically,
10884 the operation has a name and also specifies the pattern of arguments;
10885 all methods that implement the operation must accept the same
10886 arguments, since applications that use the operation do so without
10887 knowing which method will implement it.@refill
10888
10889 Often it makes more sense to document operations than methods.  For
10890 example, window application developers need to know about the
10891 @code{expose} operation, but need not be concerned with whether a
10892 given class of windows has its own method to implement this operation.
10893 To describe this operation, you would write:@refill
10894
10895 @example
10896 @@defop Operation windows expose
10897 @end example
10898
10899 The @code{@@defop} command is written at the beginning of a line and
10900 is followed on the same line by the overall name of the category of
10901 operation, the name of the class of the operation, the name of the
10902 operation, and its arguments, if any.@refill
10903
10904 @need 800
10905 @noindent
10906 The template is:
10907
10908 @example
10909 @group
10910 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
10911 @var{body-of-definition}
10912 @@end defop
10913 @end group
10914 @end example
10915
10916 @code{@@defop} creates an entry, such as `@code{expose} on
10917 @code{windows}', in the index of functions.@refill
10918
10919 @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
10920 @findex defmethod
10921 The @code{@@defmethod} command is the definition command for methods
10922 in object-oriented programming.  A method is a kind of function that
10923 implements an operation for a particular class of objects and its
10924 subclasses.  In the Lisp Machine, methods actually were functions, but
10925 they were usually defined with @code{defmethod}.
10926
10927 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
10928 The command is written at the beginning of a line and is followed by
10929 the name of the class of the method, the name of the method, and its
10930 arguments, if any.@refill
10931
10932 @need 800
10933 @noindent
10934 For example,
10935
10936 @example
10937 @group
10938 @@defmethod @code{bar-class} bar-method argument
10939 @dots{}
10940 @@end defmethod
10941 @end group
10942 @end example
10943
10944 @noindent
10945 illustrates the definition for a method called @code{bar-method} of
10946 the class @code{bar-class}.  The method takes an argument.@refill
10947
10948 The template is:
10949
10950 @example
10951 @group
10952 @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
10953 @var{body-of-definition}
10954 @@end defmethod
10955 @end group
10956 @end example
10957
10958 @code{@@defmethod} creates an entry, such as `@code{bar-method} on
10959 @code{bar-class}', in the index of functions.@refill
10960
10961 @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
10962 @findex defmethod
10963 The @code{@@deftypemethod} command is the definition command for methods
10964 in object-oriented typed languages, such as C++ and Java.  It is similar
10965 to the @code{@@defmethod} command with the addition of the
10966 @var{data-type} parameter to specify the return type of the method.
10967
10968 @end table
10969
10970
10971 @node Data Types,  , Abstract Objects, Def Cmds in Detail
10972 @subsection Data Types
10973
10974 Here is the command for data types:@refill
10975
10976 @table @code
10977 @findex deftp
10978 @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
10979 The @code{@@deftp} command is the generic definition command for data
10980 types.  The command is written at the beginning of a line and is
10981 followed on the same line by the category, by the name of the type
10982 (which is a word like @code{int} or @code{float}), and then by names of
10983 attributes of objects of that type.  Thus, you could use this command
10984 for describing @code{int} or @code{float}, in which case you could use
10985 @code{data type} as the category.  (A data type is a category of
10986 certain objects for purposes of deciding which operations can be
10987 performed on them.)@refill
10988
10989 In Lisp, for example,  @dfn{pair} names a particular data
10990 type, and an object of that type has two slots called the
10991 @sc{car} and the @sc{cdr}.  Here is how you would write the first line
10992 of a definition of @code{pair}.@refill
10993
10994 @example
10995 @group
10996 @@deftp @{Data type@} pair car cdr
10997 @dots{}
10998 @@end deftp
10999 @end group
11000 @end example
11001
11002 @need 950
11003 The template is:
11004
11005 @example
11006 @group
11007 @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11008 @var{body-of-definition}
11009 @@end deftp
11010 @end group
11011 @end example
11012
11013 @code{@@deftp} creates an entry in the index of data types.
11014 @end table
11015
11016 @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11017 @section Conventions for Writing Definitions
11018 @cindex Definition conventions
11019 @cindex Conventions for writing definitions
11020
11021 When you write a definition using @code{@@deffn}, @code{@@defun}, or
11022 one of the other definition commands, please take care to use
11023 arguments that indicate the meaning, as with the @var{count} argument
11024 to the @code{forward-word} function.  Also, if the name of an argument
11025 contains the name of a type, such as @var{integer}, take care that the
11026 argument actually is of that type.@refill
11027
11028 @node Sample Function Definition,  , Def Cmd Conventions, Definition Commands
11029 @section A Sample Function Definition
11030 @cindex Function definitions
11031 @cindex Command definitions
11032 @cindex Macro definitions
11033 @cindex Sample function definition
11034
11035 A function definition uses the @code{@@defun} and @code{@@end defun}
11036 commands.  The name of the function follows immediately after the
11037 @code{@@defun} command and it is followed, on the same line, by the
11038 parameter list.@refill
11039
11040 Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp
11041 Reference Manual}.
11042
11043 @quotation
11044 @defun apply function &rest arguments
11045 @code{apply} calls @var{function} with @var{arguments}, just
11046 like @code{funcall} but with one difference: the last of
11047 @var{arguments} is a list of arguments to give to
11048 @var{function}, rather than a single argument.  We also say
11049 that this list is @dfn{appended} to the other arguments.
11050
11051 @code{apply} returns the result of calling @var{function}.
11052 As with @code{funcall}, @var{function} must either be a Lisp
11053 function or a primitive function; special forms and macros
11054 do not make sense in @code{apply}.
11055
11056 @example
11057 (setq f 'list)
11058      @result{} list
11059 (apply f 'x 'y 'z)
11060 @error{} Wrong type argument: listp, z
11061 (apply '+ 1 2 '(3 4))
11062      @result{} 10
11063 (apply '+ '(1 2 3 4))
11064      @result{} 10
11065
11066 (apply 'append '((a b c) nil (x y z) nil))
11067      @result{} (a b c x y z)
11068 @end example
11069
11070 An interesting example of using @code{apply} is found in the description
11071 of @code{mapcar}.@refill
11072 @end defun
11073 @end quotation
11074
11075 @need 1200
11076 In the Texinfo source file, this example looks like this:
11077
11078 @example
11079 @group
11080 @@defun apply function &rest arguments
11081
11082 @@code@{apply@} calls @@var@{function@} with
11083 @@var@{arguments@}, just like @@code@{funcall@} but with one
11084 difference: the last of @@var@{arguments@} is a list of
11085 arguments to give to @@var@{function@}, rather than a single
11086 argument.  We also say that this list is @@dfn@{appended@}
11087 to the other arguments.
11088 @end group
11089
11090 @group
11091 @@code@{apply@} returns the result of calling
11092 @@var@{function@}.  As with @@code@{funcall@},
11093 @@var@{function@} must either be a Lisp function or a
11094 primitive function; special forms and macros do not make
11095 sense in @@code@{apply@}.
11096 @end group
11097
11098 @group
11099 @@example
11100 (setq f 'list)
11101      @@result@{@} list
11102 (apply f 'x 'y 'z)
11103 @@error@{@} Wrong type argument: listp, z
11104 (apply '+ 1 2 '(3 4))
11105      @@result@{@} 10
11106 (apply '+ '(1 2 3 4))
11107      @@result@{@} 10
11108
11109 (apply 'append '((a b c) nil (x y z) nil))
11110      @@result@{@} (a b c x y z)
11111 @@end example
11112 @end group
11113
11114 @group
11115 An interesting example of using @@code@{apply@} is found
11116 in the description of @@code@{mapcar@}.@@refill
11117 @@end defun
11118 @end group
11119 @end example
11120
11121 @noindent
11122 In this manual, this function is listed in the Command and Variable
11123 Index under @code{apply}.@refill
11124
11125 Ordinary variables and user options are described using a format like
11126 that for functions except that variables do not take arguments.
11127
11128
11129 @node Footnotes, Conditionals, Definition Commands, Top
11130 @chapter Footnotes
11131 @cindex Footnotes
11132 @findex footnote
11133
11134 A @dfn{footnote} is for a reference that documents or elucidates the
11135 primary text.@footnote{A footnote should complement or expand upon
11136 the primary text, but a reader should not need to read a footnote to
11137 understand the primary text.  For a thorough discussion of footnotes,
11138 see @cite{The Chicago Manual of Style}, which is published by the
11139 University of Chicago Press.}@refill
11140
11141 @menu
11142 * Footnote Commands::           How to write a footnote in Texinfo.
11143 * Footnote Styles::             Controlling how footnotes appear in Info.
11144 @end menu
11145
11146 @node Footnote Commands, Footnote Styles, Footnotes, Footnotes
11147 @section Footnote Commands
11148
11149 In Texinfo, footnotes are created with the @code{@@footnote} command.
11150 This command is followed immediately by a left brace, then by the text
11151 of the footnote, and then by a terminating right brace.  Footnotes may
11152 be of any length (they will be broken across pages if necessary), but
11153 are usually short.  The template is:
11154
11155 @example
11156 ordinary text@@footnote@{@var{text of footnote}@}
11157 @end example
11158
11159 As shown here, the @code{@@footnote} command should come right after the
11160 text being footnoted, with no intervening space; otherwise, the
11161 formatters the footnote mark might end up starting up a line.
11162
11163 For example, this clause is followed by a sample
11164 footnote@footnote{Here is the sample footnote.}; in the Texinfo
11165 source, it looks like this:@refill
11166
11167 @example
11168 @dots{}a sample footnote@@footnote@{Here is the sample
11169 footnote.@}; in the Texinfo source@dots{}
11170 @end example
11171
11172 @strong{Warning:} Don't use footnotes in the argument of the
11173 @code{@@item} command for a @code{@@table} table.  This doesn't work, and
11174 because of limitations of @TeX{}, there is no way to fix it.  You must
11175 put the footnote into the body text of the table.
11176
11177 In a printed manual or book, the reference mark for a footnote is a
11178 small, superscripted number; the text of the footnote appears at the
11179 bottom of the page, below a horizontal line.@refill
11180
11181 In Info, the reference mark for a footnote is a pair of parentheses
11182 with the footnote number between them, like this: @samp{(1)}.@refill
11183
11184
11185 @node Footnote Styles,  , Footnote Commands, Footnotes
11186 @section Footnote Styles
11187
11188 Info has two footnote styles, which determine where the text of the
11189 footnote is located:@refill
11190
11191 @itemize @bullet
11192 @cindex @samp{@r{End}} node footnote style
11193 @item
11194 In the `End' node style, all the footnotes for a single node
11195 are placed at the end of that node.  The footnotes are separated from
11196 the rest of the node by a line of dashes with the word
11197 @samp{Footnotes} within it.  Each footnote begins with an
11198 @samp{(@var{n})} reference mark.@refill
11199
11200 @need 700
11201 @noindent
11202 Here is an example of a single footnote in the end of node style:@refill
11203
11204 @example
11205 @group
11206  --------- Footnotes ---------
11207
11208 (1)  Here is a sample footnote.
11209 @end group
11210 @end example
11211
11212 @cindex @samp{@r{Separate}} footnote style
11213 @item
11214 In the `Separate' node style, all the footnotes for a single
11215 node are placed in an automatically constructed node of
11216 their own.  In this style, a ``footnote reference'' follows
11217 each @samp{(@var{n})} reference mark in the body of the
11218 node.  The footnote reference is actually a cross reference
11219 which you use to reach the footnote node.@refill
11220
11221 The name of the node containing the footnotes is constructed
11222 by appending @w{@samp{-Footnotes}} to the name of the node
11223 that contains the footnotes. (Consequently, the footnotes'
11224 node for the @file{Footnotes} node is
11225 @w{@file{Footnotes-Footnotes}}!)  The footnotes' node has an
11226 `Up' node pointer that leads back to its parent node.@refill
11227
11228 @noindent
11229 Here is how the first footnote in this manual looks after being
11230 formatted for Info in the separate node style:@refill
11231
11232 @smallexample
11233 @group
11234 File: texinfo.info  Node: Overview-Footnotes, Up: Overview
11235
11236 (1) Note that the first syllable of "Texinfo" is
11237 pronounced like "speck", not "hex". @dots{}
11238 @end group
11239 @end smallexample
11240 @end itemize
11241
11242 A Texinfo file may be formatted into an Info file with either footnote
11243 style.@refill
11244
11245 @findex footnotestyle
11246 Use the @code{@@footnotestyle} command to specify an Info file's
11247 footnote style.  Write this command at the beginning of a line followed
11248 by an argument, either @samp{end} for the end node style or
11249 @samp{separate} for the separate node style.
11250
11251 @need 700
11252 For example,
11253
11254 @example
11255 @@footnotestyle end
11256 @end example
11257 @noindent
11258 or
11259 @example
11260 @@footnotestyle separate
11261 @end example
11262
11263 Write an @code{@@footnotestyle} command before or shortly after the
11264 end-of-header line at the beginning of a Texinfo file.  (If you
11265 include the @code{@@footnotestyle} command between the start-of-header
11266 and end-of-header lines, the region formatting commands will format
11267 footnotes as specified.)@refill
11268
11269 If you do not specify a footnote style, the formatting commands use
11270 their default style.  Currently, @code{texinfo-format-buffer} and
11271 @code{texinfo-format-region} use the `separate' style and
11272 @code{makeinfo} uses the `end' style.@refill
11273
11274 @c !!! note: makeinfo's --footnote-style option overrides footnotestyle
11275 @ignore
11276 If you use @code{makeinfo} to create the Info file, the
11277 @samp{--footnote-style} option determines which style is used,
11278 @samp{end} for the end of node style or @samp{separate} for the
11279 separate node style.  Thus, to format the Texinfo manual in the
11280 separate node style, you would use the following shell command:@refill
11281
11282 @example
11283 makeinfo --footnote-style=separate texinfo.texi
11284 @end example
11285
11286 @noindent
11287 To format the Texinfo manual in the end of node style, you would
11288 type:@refill
11289
11290 @example
11291 makeinfo --footnote-style=end texinfo.texi
11292 @end example
11293 @end ignore
11294 @ignore
11295 If you use @code{texinfo-format-buffer} or
11296 @code{texinfo-format-region} to create the Info file, the value of the
11297 @code{texinfo-footnote-style} variable controls the footnote style.
11298 It can be either @samp{"separate"} for the separate node style or
11299 @samp{"end"} for the end of node style.  (You can change the value of
11300 this variable with the @kbd{M-x edit-options} command (@pxref{Edit
11301 Options, , Editing Variable Values, xemacs, XEmacs User's Manual}), or
11302 with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
11303 and Setting Variables, xemacs, XEmacs User's Manual}).@refill
11304
11305 The @code{texinfo-footnote-style} variable also controls the style if
11306 you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
11307 command in Emacs.@refill
11308 @end ignore
11309 This chapter contains two footnotes.@refill
11310
11311
11312 @node Conditionals, Macros, Footnotes, Top
11313 @comment  node-name,  next,  previous,  up
11314 @chapter Conditionally Visible Text
11315 @cindex Conditionally visible text
11316 @cindex Text, conditionally visible
11317 @cindex Visibility of conditional text
11318 @cindex If text conditionally visible
11319
11320 Sometimes it is good to use different text for a printed manual and
11321 its corresponding Info file.  In this case, you can use the
11322 @dfn{conditional commands} to specify which text is for the printed manual
11323 and which is for the Info file.@refill
11324
11325 @menu
11326 * Conditional Commands::        Specifying text for HTML, Info, or @TeX{}.
11327 * Conditional Not Commands::    Specifying text for not HTML, Info, or @TeX{}.
11328 * Raw Formatter Commands::      Using raw @TeX{} or HTML commands.
11329 * set clear value::             Designating which text to format (for
11330                                   all output formats); and how to set a
11331                                   flag to a string that you can insert.
11332 @end menu
11333
11334 @node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals
11335 @ifinfo
11336 @heading Conditional Commands
11337 @end ifinfo
11338
11339 @findex ifinfo
11340 @code{@@ifinfo} begins segments of text that should be ignored
11341 by @TeX{} when it
11342 typesets the printed manual.  The segment of text appears only
11343 in the Info file.
11344 The @code{@@ifinfo} command should appear on a line by itself;  end
11345 the Info-only text with a line containing @code{@@end ifinfo} by
11346 itself.  At the beginning of a Texinfo file, the Info permissions are
11347 contained within a region marked by @code{@@ifinfo} and @code{@@end
11348 ifinfo}. (@xref{Info Summary and Permissions}.)@refill
11349
11350 @findex iftex
11351 @findex ifhtml
11352 The @code{@@iftex} and @code{@@end iftex} commands are similar to the
11353 @code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
11354 specify text that will appear in the printed manual but not in the Info
11355 file.  Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
11356 specify text to appear only in HTML output.@refill
11357
11358 For example,
11359
11360 @example
11361 @@iftex
11362 This text will appear only in the printed manual.
11363 @@end iftex
11364 @@ifinfo
11365 However, this text will appear only in Info.
11366 @@end ifinfo
11367 @end example
11368
11369 @noindent
11370 The preceding example produces the following line:
11371 @iftex
11372 This text will appear only in the printed manual.
11373 @end iftex
11374 @ifinfo
11375 However, this text will appear only in Info.
11376 @end ifinfo
11377
11378 @noindent
11379 Note how you only see one of the two lines, depending on whether you
11380 are reading the Info version or the printed version of this
11381 manual.@refill
11382
11383 The @code{@@titlepage} command is a special variant of @code{@@iftex} that
11384 is used for making the title and copyright pages of the printed
11385 manual.  (@xref{titlepage, , @code{@@titlepage}}.) @refill
11386
11387
11388 @node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals
11389 @section Conditional Not Commands
11390 @findex ifnothtml
11391 @findex ifnotinfo
11392 @findex ifnottex
11393
11394 You can specify text to be included in any output format @emph{other}
11395 than some given one with the @code{@@ifnot@dots{}} commands:
11396 @example
11397 @@ifnothtml @dots{} @@end ifnothtml
11398 @@ifnotinfo @dots{} @@end ifnotinfo
11399 @@ifnottex @dots{} @@end ifnottex
11400 @end example
11401 @noindent
11402 (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11403 actually appear on lines by themselves.)
11404
11405 If the output file is not being made for the given format, the region is
11406 included.  Otherwise, it is ignored.
11407
11408 The regions delimited by these commands are ordinary Texinfo source as
11409 with @code{@@iftex}, not raw formatter source as with @code{@@tex}.
11410
11411
11412 @node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals
11413 @section Raw Formatter Commands
11414 @cindex @TeX{} commands, using ordinary
11415 @cindex HTML commands, using ordinary
11416 @cindex Raw formatter commands
11417 @cindex Ordinary @TeX{} commands, using
11418 @cindex Ordinary HTML commands, using
11419 @cindex Commands using raw @TeX{}
11420 @cindex Commands using raw HTML
11421 @cindex plain @TeX{}
11422
11423 Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11424 can embed some raw @TeX{} commands.  Info will ignore these commands
11425 since they are only in that part of the file which is seen by @TeX{}.
11426 You can write the @TeX{} commands as you would write them in a normal
11427 @TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11428 with an @samp{@@}.  For example, in the @code{@@titlepage} section of a
11429 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11430 the copyright page.  (The @code{@@titlepage} command causes Info to
11431 ignore the region automatically, as it does with the @code{@@iftex}
11432 command.)
11433
11434 However, many features of plain @TeX{} will not work, as they are
11435 overridden by Texinfo features.
11436
11437 @findex tex
11438 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11439 commands, by delineating a region with the @code{@@tex} and @code{@@end
11440 tex} commands.  (The @code{@@tex} command also causes Info to ignore the
11441 region, like the @code{@@iftex} command.)  The sole exception is that
11442 @code{@@} chracter still introduces a command, so that @code{@@end tex}
11443 can be recognized properly.
11444
11445 @cindex Mathematical expressions
11446 For example, here is a mathematical expression written in
11447 plain @TeX{}:
11448
11449 @example
11450 @@tex
11451 $$ \chi^2 = \sum_@{i=1@}^N
11452           \left (y_i - (a + b x_i)
11453           \over \sigma_i\right)^2 $$
11454 @@end tex
11455 @end example
11456
11457 @noindent
11458 The output of this example will appear only in a printed manual.  If
11459 you are reading this in Info, you will not see the equation that appears
11460 in the printed manual.
11461 @iftex
11462 In a printed manual, the above expression looks like
11463 this:
11464 @end iftex
11465
11466 @tex
11467 $$ \chi^2 = \sum_{i=1}^N
11468           \left(y_i - (a + b x_i)
11469           \over \sigma_i\right)^2 $$
11470 @end tex
11471
11472 @findex ifhtml
11473 @findex html
11474 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11475 a region to be included in HTML output only, and @code{@@html @dots{}
11476 @@end ifhtml} for a region of raw HTML (again, except that @code{@@} is
11477 still the escape character, so the @code{@@end} command can be
11478 recognized.)
11479
11480
11481 @node set clear value,  , Raw Formatter Commands, Conditionals
11482 @comment  node-name,  next,  previous,  up
11483 @section @code{@@set}, @code{@@clear}, and @code{@@value}
11484
11485 You can direct the Texinfo formatting commands to format or ignore parts
11486 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11487 and @code{@@ifclear} commands.@refill
11488
11489 In addition, you can use the @code{@@set @var{flag}} command to set the
11490 value of @var{flag} to a string of characters; and use
11491 @code{@@value@{@var{flag}@}} to insert that string.  You can use
11492 @code{@@set}, for example, to set a date and use @code{@@value} to
11493 insert the date in several places in the Texinfo file.@refill
11494
11495 @menu
11496 * ifset ifclear::               Format a region if a flag is set.
11497 * value::                       Replace a flag with a string.
11498 * value Example::               An easy way to update edition information.
11499 @end menu
11500
11501
11502 @node ifset ifclear, value, set clear value, set clear value
11503 @subsection @code{@@ifset} and @code{@@ifclear}
11504
11505 @findex ifset
11506 When a @var{flag} is set, the Texinfo formatting commands format text
11507 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
11508 ifset} commands.  When the @var{flag} is cleared, the Texinfo formatting
11509 commands do @emph{not} format the text.
11510
11511 Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a
11512 @var{flag}; a @dfn{flag} can be any single word.  The format for the
11513 command looks like this:@refill
11514 @findex set
11515
11516 @example
11517 @@set @var{flag}
11518 @end example
11519
11520 Write the conditionally formatted text between @code{@@ifset @var{flag}}
11521 and @code{@@end ifset} commands, like this:@refill
11522
11523 @example
11524 @group
11525 @@ifset @var{flag}
11526 @var{conditional-text}
11527 @@end ifset
11528 @end group
11529 @end example
11530
11531 For example, you can create one document that has two variants, such as
11532 a manual for a `large' and `small' model:@refill
11533
11534 @example
11535 You can use this machine to dig up shrubs
11536 without hurting them.
11537
11538 @@set large
11539
11540 @@ifset large
11541 It can also dig up fully grown trees.
11542 @@end ifset
11543
11544 Remember to replant promptly @dots{}
11545 @end example
11546
11547 @noindent
11548 In the example, the formatting commands will format the text between
11549 @code{@@ifset large} and @code{@@end ifset} because the @code{large}
11550 flag is set.@refill
11551
11552 @findex clear
11553 Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear},
11554 a flag.  Clearing a flag is the opposite of setting a flag.  The
11555 command looks like this:@refill
11556
11557 @example
11558 @@clear @var{flag}
11559 @end example
11560
11561 @noindent
11562 Write the command on a line of its own.
11563
11564 When @var{flag} is cleared, the Texinfo formatting commands do
11565 @emph{not} format the text between @code{@@ifset @var{flag}} and
11566 @code{@@end ifset}; that text is ignored and does not appear in either
11567 printed or Info output.@refill
11568
11569 For example, if you clear the flag of the preceding example by writing
11570 an @code{@@clear large} command after the @code{@@set large} command
11571 (but before the conditional text), then the Texinfo formatting commands
11572 ignore the text between the @code{@@ifset large} and @code{@@end ifset}
11573 commands.  In the formatted output, that text does not appear; in both
11574 printed and Info output, you see only the lines that say, ``You can use
11575 this machine to dig up shrubs without hurting them.  Remember to replant
11576 promptly @dots{}''.
11577
11578 @findex ifclear
11579 If a flag is cleared with an @code{@@clear @var{flag}} command, then
11580 the formatting commands format text between subsequent pairs of
11581 @code{@@ifclear} and @code{@@end ifclear} commands.  But if the flag
11582 is set with @code{@@set @var{flag}}, then the formatting commands do
11583 @emph{not} format text between an @code{@@ifclear} and an @code{@@end
11584 ifclear} command; rather, they ignore that text.  An @code{@@ifclear}
11585 command looks like this:@refill
11586
11587 @example
11588 @@ifclear @var{flag}
11589 @end example
11590
11591 @need 700
11592 In brief, the commands are:@refill
11593
11594 @table @code
11595 @item @@set @var{flag}
11596 Tell the Texinfo formatting commands that @var{flag} is set.@refill
11597
11598 @item @@clear @var{flag}
11599 Tell the Texinfo formatting commands that @var{flag} is cleared.@refill
11600
11601 @item @@ifset @var{flag}
11602 If @var{flag} is set, tell the Texinfo formatting commands to format
11603 the text up to the following @code{@@end ifset} command.@refill
11604
11605 If @var{flag} is cleared, tell the Texinfo formatting commands to
11606 ignore text up to the following @code{@@end ifset} command.@refill
11607
11608 @item @@ifclear @var{flag}
11609 If @var{flag} is set, tell the Texinfo formatting commands to ignore
11610 the text up to the following @code{@@end ifclear} command.@refill
11611
11612 If @var{flag} is cleared, tell the Texinfo formatting commands to
11613 format the text up to the following @code{@@end ifclear}
11614 command.@refill
11615 @end table
11616
11617 @node value, value Example, ifset ifclear, set clear value
11618 @subsection @code{@@value}
11619 @findex value
11620
11621 You can use the @code{@@set} command to specify a value for a flag,
11622 which is expanded by the @code{@@value} command.  The value is a string
11623 a characters.
11624
11625 Write the @code{@@set} command like this:
11626
11627 @example
11628 @@set foo This is a string.
11629 @end example
11630
11631 @noindent
11632 This sets the value of @code{foo} to ``This is a string.''
11633
11634 The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with
11635 the string to which @var{flag} is set.@refill
11636
11637 Thus, when @code{foo} is set as shown above, the Texinfo formatters convert
11638
11639 @example
11640 @group
11641 @@value@{foo@}
11642 @exdent @r{to}
11643 This is a string.
11644 @end group
11645 @end example
11646
11647 You can write an @code{@@value} command within a paragraph; but you
11648 must write an @code{@@set} command on a line of its own.
11649
11650 If you write the @code{@@set} command like this:
11651
11652 @example
11653 @@set foo
11654 @end example
11655
11656 @noindent
11657 without specifying a string, the value of @code{foo} is an empty string.
11658
11659 If you clear a previously set flag with an @code{@@clear @var{flag}}
11660 command, a subsequent @code{@@value@{flag@}} command is invalid and the
11661 string is replaced with an error message that says @samp{@{No value for
11662 "@var{flag}"@}}.
11663
11664 For example, if you set @code{foo} as follows:@refill
11665
11666 @example
11667 @@set how-much very, very, very
11668 @end example
11669
11670 @noindent
11671 then the formatters transform
11672
11673 @example
11674 @group
11675 It is a @@value@{how-much@} wet day.
11676 @exdent @r{into}
11677 It is a very, very, very wet day.
11678 @end group
11679 @end example
11680
11681 If you write
11682
11683 @example
11684 @@clear how-much
11685 @end example
11686
11687 @noindent
11688 then the formatters transform
11689
11690 @example
11691 @group
11692 It is a @@value@{how-much@} wet day.
11693 @exdent @r{into}
11694 It is a @{No value for "how-much"@} wet day.
11695 @end group
11696 @end example
11697
11698 @node value Example,  , value, set clear value
11699 @subsection @code{@@value} Example
11700
11701 You can use the @code{@@value} command to limit the number of places you
11702 need to change when you record an update to a manual.
11703 Here is how it is done in @cite{The GNU Make Manual}:
11704
11705 @need 1000
11706 @noindent
11707 Set the flags:
11708
11709 @example
11710 @group
11711 @@set EDITION 0.35 Beta
11712 @@set VERSION 3.63 Beta
11713 @@set UPDATED 14 August 1992
11714 @@set UPDATE-MONTH August 1992
11715 @end group
11716 @end example
11717
11718 @need 750
11719 @noindent
11720 Write text for the first @code{@@ifinfo} section, for people reading the
11721 Texinfo file:
11722
11723 @example
11724 @group
11725 This is Edition @@value@{EDITION@},
11726 last updated @@value@{UPDATED@},
11727 of @@cite@{The GNU Make Manual@},
11728 for @@code@{make@}, Version @@value@{VERSION@}.
11729 @end group
11730 @end example
11731
11732 @need 1000
11733 @noindent
11734 Write text for the title page, for people reading the printed manual:
11735 @c List only the month and the year since that looks less fussy on a
11736 @c printed cover than a date that lists the day as well.
11737
11738 @example
11739 @group
11740 @@title GNU Make
11741 @@subtitle A Program for Directing Recompilation
11742 @@subtitle Edition @@value@{EDITION@}, @dots{}
11743 @@subtitle @@value@{UPDATE-MONTH@}
11744 @end group
11745 @end example
11746
11747 @noindent
11748 (On a printed cover, a date listing the month and the year looks less
11749 fussy than a date listing the day as well as the month and year.)
11750
11751 @need 750
11752 @noindent
11753 Write text for the Top node, for people reading the Info file:
11754
11755 @example
11756 @group
11757 This is Edition @@value@{EDITION@}
11758 of the @@cite@{GNU Make Manual@},
11759 last updated @@value@{UPDATED@}
11760 for @@code@{make@} Version @@value@{VERSION@}.
11761 @end group
11762 @end example
11763
11764 @need 950
11765 After you format the manual, the text in the first @code{@@ifinfo}
11766 section looks like this:
11767
11768 @example
11769 @group
11770 This is Edition 0.35 Beta, last updated 14 August 1992,
11771 of `The GNU Make Manual', for `make', Version 3.63 Beta.
11772 @end group
11773 @end example
11774
11775 When you update the manual, change only the values of the flags; you do
11776 not need to rewrite the three sections.
11777
11778
11779 @node Macros, Format/Print Hardcopy, Conditionals, Top
11780 @chapter Macros: Defining New Texinfo Commands
11781 @cindex Macros
11782 @cindex Defining new Texinfo commands
11783 @cindex New Texinfo commands, defining
11784 @cindex Texinfo commands, defining new
11785 @cindex User-defined Texinfo commands
11786
11787 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
11788 sequence of text and/or existing commands (including other macros).  The
11789 macro can have any number of @dfn{parameters}---text you supply each
11790 time you use the macro.  (This has nothing to do with the
11791 @code{@@defmac} command, which is for documenting macros in the subject
11792 of the manual; @pxref{Def Cmd Template}.)
11793
11794 @menu
11795 * Defining Macros::             Both defining and undefining new commands.
11796 * Invoking Macros::             Using a macro, once you've defined it.
11797 @end menu
11798
11799
11800 @node Defining Macros, Invoking Macros, Macros, Macros
11801 @section Defining Macros
11802 @cindex Defining macros
11803 @cindex Macro definitions
11804
11805 @findex macro
11806 You use the Texinfo @code{@@macro} command to define a macro.  For example:
11807
11808 @example
11809 @@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@}
11810 @var{text} @dots{} \@var{param1}\ @dots{}
11811 @@end macro
11812 @end example
11813
11814 The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
11815 arguments supplied when the macro is subsequently used in the document
11816 (see the next section).
11817
11818 If a macro needs no parameters, you can define it either with an empty
11819 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
11820 foo}).
11821
11822 @cindex Body of a macro
11823 @cindex Mutually recursive macros
11824 @cindex Recursion, mutual
11825 The definition or @dfn{body} of the macro can contain any Texinfo
11826 commands, including previously-defined macros.  (It is not possible to
11827 have mutually recursive Texinfo macros.)  In the body, instances of a
11828 parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in
11829 the example above, are replaced by the corresponding argument from the
11830 macro invocation.
11831
11832 @findex unmacro
11833 @cindex Macros, undefining
11834 @cindex Undefining macros
11835 You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
11836 It is not an error to undefine a macro that is already undefined.
11837 For example:
11838
11839 @example
11840 @@unmacro foo
11841 @end example
11842
11843
11844 @node Invoking Macros,  , Defining Macros, Macros
11845 @section Invoking Macros
11846 @cindex Invoking macros
11847 @cindex Macro invocation
11848
11849 After a macro is defined (see the previous section), you can use
11850 (@dfn{invoke}) it in your document like this:
11851
11852 @example
11853 @@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@}
11854 @end example
11855
11856 @noindent
11857 and the result will be just as if you typed the body of
11858 @var{macro-name} at that spot.  For example:
11859
11860 @example
11861 @@macro foo @{p, q@}
11862 Together: \p\ & \q\.
11863 @@end macro
11864 @@foo@{a, b@}
11865 @end example
11866
11867 @noindent
11868 produces:
11869
11870 @display
11871 Together: a & b.
11872 @end display
11873
11874 @cindex Backslash, and macros
11875 Thus, the arguments and parameters are separated by commas and delimited
11876 by braces; any whitespace after (but not before) a comma is ignored.  To
11877 insert a comma, brace, or backslash in an argument, prepend a backslash,
11878 as in
11879
11880 @example
11881 @@@var{macro-name} @{\\\@{\@}\,@}
11882 @end example
11883
11884 @noindent
11885 which will pass the (almost certainly error-producing) argument
11886 @samp{\@{@},} to @var{macro-name}.
11887
11888 If the macro is defined to take a single argument, and is invoked
11889 without any braces, the entire rest of the line after the macro name is
11890 supplied as the argument.  For example:
11891
11892 @example
11893 @@macro bar @{p@}
11894 Twice: \p\, \p\.
11895 @@end macro
11896 @@bar aah
11897 @end example
11898
11899 @noindent
11900 produces:
11901
11902 @display
11903 Twice: aah, aah.
11904 @end display
11905
11906
11907 @node Format/Print Hardcopy, Create an Info File, Macros, Top
11908 @comment  node-name,  next,  previous,  up
11909 @chapter Format and Print Hardcopy
11910 @cindex Format and print hardcopy
11911 @cindex Hardcopy, printing it
11912 @cindex Making a printed manual
11913 @cindex Sorting indices
11914 @cindex Indices, sorting
11915 @cindex @TeX{} index sorting
11916 @pindex texindex
11917
11918 There are three major shell commands for making a printed manual from a
11919 Texinfo file: one for converting the Texinfo file into a file that will be
11920 printed, a second for sorting indices, and a third for printing the
11921 formatted document.  When you use the shell commands, you can either
11922 work directly in the operating system shell or work within a shell
11923 inside GNU Emacs.@refill
11924
11925 If you are using GNU Emacs, you can use commands provided by Texinfo
11926 mode instead of shell commands.  In addition to the three commands to
11927 format a file, sort the indices, and print the result, Texinfo mode
11928 offers key bindings for commands to recenter the output buffer, show the
11929 print queue, and delete a job from the print queue.@refill
11930
11931 @menu
11932 * Use TeX::                     Use @TeX{} to format for hardcopy.
11933 * Format with tex/texindex::    How to format in a shell.
11934 * Format with texi2dvi::        A simpler way to use the shell.
11935 * Print with lpr::              How to print.
11936 * Within Emacs::                How to format and print from an Emacs shell.
11937 * Texinfo Mode Printing::       How to format and print in Texinfo mode.
11938 * Compile-Command::             How to print using Emacs's compile command.
11939 * Requirements Summary::        @TeX{} formatting requirements summary.
11940 * Preparing for TeX::           What you need to do to use @TeX{}.
11941 * Overfull hboxes::             What are and what to do with overfull hboxes.
11942 * smallbook::                   How to print small format books and manuals.
11943 * A4 Paper::                    How to print on European A4 paper.
11944 * Cropmarks and Magnification::  How to print marks to indicate the size
11945                                 of pages and how to print scaled up output.
11946 @end menu
11947
11948 @node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy
11949 @ifinfo
11950 @heading Use @TeX{}
11951 @end ifinfo
11952
11953 The typesetting program called @TeX{} is used for formatting a Texinfo
11954 file.  @TeX{} is a very powerful typesetting program and, if used right,
11955 does an exceptionally good job.  (@xref{Obtaining TeX, , How to Obtain
11956 @TeX{}}, for information on how to obtain @TeX{}.)
11957
11958 The @code{makeinfo}, @code{texinfo-format-region}, and
11959 @code{texinfo-format-buffer} commands read the very same @@-commands
11960 in the Texinfo file as does @TeX{}, but process them differently to
11961 make an Info file; see @ref{Create an Info File}.@refill
11962
11963 @node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy
11964 @comment  node-name,  next,  previous,  up
11965 @section Format using @code{tex} and @code{texindex}
11966 @cindex Shell formatting with @code{tex} and @code{texindex}
11967 @cindex Formatting with @code{tex} and @code{texindex}
11968 @cindex DVI file
11969
11970 Format the Texinfo file with the shell command @code{tex} followed by
11971 the name of the Texinfo file.  For example:
11972
11973 @example
11974 tex foo.texi
11975 @end example
11976
11977 @noindent
11978 @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
11979 files containing information for indices, cross references, etc.  The
11980 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
11981 any printe (see the following sections).
11982
11983 @pindex texindex
11984 The @code{tex} formatting command itself does not sort the indices; it
11985 writes an output file of unsorted index data.  (The @code{texi2dvi}
11986 command automatically generates indices; see @ref{Format with texi2dvi,,
11987 Format using @code{texi2dvi}}.)  To generate a printed index after
11988 running the @code{tex} command, you first need a sorted index to work
11989 from.  The @code{texindex} command sorts indices.  (The source file
11990 @file{texindex.c} comes as part of the standard Texinfo distribution,
11991 among other places.)@refill
11992
11993 @cindex Names of index files
11994 The @code{tex} formatting command outputs unsorted index files under
11995 names that obey a standard convention: the name of your main input file
11996 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
11997 Web2c}) extension removed, followed by the two letter names of indices.
11998 For example, the raw index output files for the input file
11999 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
12000 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}.  Those are exactly the
12001 arguments to give to @code{texindex}.@refill
12002
12003 @need 1000
12004 @cindex Wildcards
12005 @cindex Globbing
12006 Instead of specifying all the unsorted index file names explicitly, you
12007 can use @samp{??} as shell wildcards and give the command in this
12008 form:@refill
12009
12010 @example
12011 texindex foo.??
12012 @end example
12013
12014 @noindent
12015 This command will run @code{texindex} on all the unsorted index files,
12016 including any that you have defined yourself using @code{@@defindex}
12017 or @code{@@defcodeindex}.  (You may execute @samp{texindex foo.??}
12018 even if there are similarly named files with two letter extensions
12019 that are not index files, such as @samp{foo.el}.  The @code{texindex}
12020 command reports but otherwise ignores such files.)@refill
12021
12022 For each file specified, @code{texindex} generates a sorted index file
12023 whose name is made by appending @samp{s} to the input file name.  The
12024 @code{@@printindex} command knows to look for a file of that name
12025 (@pxref{Printing Indices & Menus}).  @code{texindex} does not alter the
12026 raw index output file.@refill
12027
12028 After you have sorted the indices, you need to rerun the @code{tex}
12029 formatting command on the Texinfo file.  This regenerates the DVI file,
12030 this time with up-to-date index entries.
12031
12032 Finally, you may need to run @code{tex} one more time, to get the page
12033 numbers in the cross-references correct.
12034
12035 To summarize, this is a four step process:
12036
12037 @enumerate
12038 @item
12039 Run @code{tex} on your Texinfo file.  This generates a DVI file (with
12040 undefined cross-references and no indices), and the raw index files
12041 (with two letter extensions).
12042
12043 @item
12044 Run @code{texindex} on the raw index files.  This creates the
12045 corresponding sorted index files (with three letter extensions).
12046
12047 @item
12048 Run @code{tex} again on your Texinfo file.  This regenerates the DVI
12049 file, this time with indices and defined cross-references, but with page
12050 numbers for the cross-references from last time, generally incorrect.
12051
12052 @item
12053 Run @code{tex} one last time.  This time the correct page numbers are
12054 written for the cross-references.
12055 @end enumerate
12056
12057 @pindex texi2dvi
12058 Alternatively, it's a one-step process: run @code{texi2dvi}.
12059
12060 You need not run @code{texindex} each time after you run @code{tex}.  If
12061 you do not, on the next run, the @code{tex} formatting command will use
12062 whatever sorted index files happen to exist from the previous use of
12063 @code{texindex}.  This is usually ok while you are
12064 debugging.@refill
12065
12066
12067 @node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy
12068 @comment  node-name,  next,  previous,  up
12069 @section Format using @code{texi2dvi}
12070 @pindex texi2dvi @r{(shell script)}
12071
12072 The @code{texi2dvi} command automatically runs both @code{tex} and
12073 @code{texindex} as many times as necessary to produce a DVI file with
12074 up-to-date, sorted indices.  It simplifies the
12075 @code{tex}---@code{texindex}---@code{tex} sequence described in the
12076 previous section.
12077
12078 The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is your
12079 shell prompt):@refill
12080
12081 @example
12082 prompt$ @kbd{texi2dvi @var{filename}@dots{}}
12083 @end example
12084
12085 For a list of options, run @samp{texi2dvi --help}.
12086
12087
12088 @node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy
12089 @comment  node-name,  next,  previous,  up
12090 @section Shell Print Using @code{lpr -d}
12091 @pindex lpr @r{(DVI print command)}
12092
12093 The precise command to print a DVI file depends on your system
12094 installation, but @samp{lpr -d} is common.  The command may require the
12095 DVI file name without any extension or with a @samp{.dvi}
12096 extension.  (If it is @samp{lpr}, you must include the @samp{.dvi}.)
12097
12098 The following commands, for example, will (probably) suffice to sort the
12099 indices, format, and print the @cite{Bison Manual}:
12100
12101 @example
12102 @group
12103 tex bison.texinfo
12104 texindex bison.??
12105 tex bison.texinfo
12106 lpr -d bison.dvi
12107 @end group
12108 @end example
12109
12110 @noindent
12111 (Remember that the shell commands may be different at your site; but
12112 these are commonly used versions.)@refill
12113
12114 @need 1000
12115 Using the @code{texi2dvi} shell script, you simply need type:@refill
12116
12117 @example
12118 @group
12119 texi2dvi bison.texinfo
12120 lpr -d bison.dvi
12121 @end group
12122 @end example
12123
12124 @node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy
12125 @comment  node-name,  next,  previous,  up
12126 @section From an Emacs Shell
12127 @cindex Print, format from Emacs shell
12128 @cindex Format, print from Emacs shell
12129 @cindex Shell, format, print from
12130 @cindex Emacs shell, format, print from
12131 @cindex GNU Emacs shell, format, print from
12132
12133 You can give formatting and printing commands from a shell within GNU
12134 Emacs.  To create a shell within Emacs, type @kbd{M-x shell}.  In this
12135 shell, you can format and print the document.  @xref{Format/Print
12136 Hardcopy, , Format and Print Hardcopy}, for details.@refill
12137
12138 You can switch to and from the shell buffer while @code{tex} is
12139 running and do other editing.  If you are formatting a long document
12140 on a slow machine, this can be very convenient.@refill
12141
12142 You can also use @code{texi2dvi} from an Emacs shell.  For example,
12143 here is how to use @code{texi2dvi} to format and print @cite{Using and
12144 Porting GNU CC} from a shell within Emacs:
12145
12146 @example
12147 @group
12148 texi2dvi gcc.texinfo
12149 lpr -d gcc.dvi
12150 @end group
12151 @end example
12152 @ifinfo
12153
12154 @xref{Texinfo Mode Printing}, for more information about formatting
12155 and printing in Texinfo mode.@refill
12156 @end ifinfo
12157
12158 @node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy
12159 @section Formatting and Printing in Texinfo Mode
12160 @cindex Region printing in Texinfo mode
12161 @cindex Format and print in Texinfo mode
12162 @cindex Print and format in Texinfo mode
12163
12164 Texinfo mode provides several predefined key commands for @TeX{}
12165 formatting and printing.  These include commands for sorting indices,
12166 looking at the printer queue, killing the formatting job, and
12167 recentering the display of the buffer in which the operations
12168 occur.@refill
12169
12170 @table @kbd
12171 @item C-c C-t C-b
12172 @itemx M-x texinfo-tex-buffer
12173 Run @code{texi2dvi} on the current buffer.@refill
12174
12175 @item C-c C-t C-r
12176 @itemx M-x texinfo-tex-region
12177 Run @TeX{} on the current region.@refill
12178
12179 @item C-c C-t C-i
12180 @itemx M-x texinfo-texindex
12181 Sort the indices of a Texinfo file formatted with
12182 @code{texinfo-tex-region}.@refill
12183
12184 @item C-c C-t C-p
12185 @itemx M-x texinfo-tex-print
12186 Print a DVI file that was made with @code{texinfo-tex-region} or
12187 @code{texinfo-tex-buffer}.@refill
12188
12189 @item C-c C-t C-q
12190 @itemx M-x tex-show-print-queue
12191 Show the print queue.@refill
12192
12193 @item C-c C-t C-d
12194 @itemx M-x texinfo-delete-from-print-queue
12195 Delete a job from the print queue; you will be prompted for the job
12196 number shown by a preceding @kbd{C-c C-t C-q} command
12197 (@code{texinfo-show-tex-print-queue}).@refill
12198
12199 @item C-c C-t C-k
12200 @itemx M-x tex-kill-job
12201 Kill the currently running @TeX{} job started by
12202 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
12203 process running in the Texinfo shell buffer.@refill
12204
12205 @item C-c C-t C-x
12206 @itemx M-x texinfo-quit-job
12207 Quit a @TeX{} formatting job that has stopped because of an error by
12208 sending an @key{x} to it.  When you do this, @TeX{} preserves a record
12209 of what it did in a @file{.log} file.@refill
12210
12211 @item C-c C-t C-l
12212 @itemx M-x tex-recenter-output-buffer
12213 Redisplay the shell buffer in which the @TeX{} printing and formatting
12214 commands are run to show its most recent output.@refill
12215 @end table
12216
12217 @need 1000
12218 Thus, the usual sequence of commands for formatting a buffer is as
12219 follows (with comments to the right):@refill
12220
12221 @example
12222 @group
12223 C-c C-t C-b             @r{Run @code{texi2dvi} on the buffer.}
12224 C-c C-t C-p             @r{Print the DVI file.}
12225 C-c C-t C-q             @r{Display the printer queue.}
12226 @end group
12227 @end example
12228
12229 The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
12230 called the @file{*tex-shell*}.  The @code{texinfo-tex-command},
12231 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
12232 commands are all run in this shell.
12233
12234 You can watch the commands operate in the @samp{*tex-shell*} buffer,
12235 and you can switch to and from and use the @samp{*tex-shell*} buffer
12236 as you would any other shell buffer.@refill
12237
12238 @need 1500
12239 The formatting and print commands depend on the values of several variables.
12240 The default values are:@refill
12241
12242 @example
12243 @group
12244      @r{Variable}                              @r{Default value}
12245
12246 texinfo-texi2dvi-command                  "texi2dvi"
12247 texinfo-tex-command                       "tex"
12248 texinfo-texindex-command                  "texindex"
12249 texinfo-delete-from-print-queue-command   "lprm"
12250 texinfo-tex-trailer                       "@@bye"
12251 tex-start-of-header                       "%**start"
12252 tex-end-of-header                         "%**end"
12253 tex-dvi-print-command                     "lpr -d"
12254 tex-show-queue-command                    "lpq"
12255 @end group
12256 @end example
12257
12258 You can change the values of these variables with the @kbd{M-x
12259 edit-options} command (@pxref{Edit Options, , Editing Variable Values,
12260 xemacs, XEmacs User's Manual}), with the @kbd{M-x set-variable} command
12261 (@pxref{Examining, , Examining and Setting Variables, xemacs, XEmacs
12262 User's Manual}), or with your @file{.emacs} initialization file
12263 (@pxref{Init File, , , xemacs, XEmacs User's Manual}).@refill
12264
12265 @node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy
12266 @comment  node-name,  next,  previous,  up
12267 @section Using the Local Variables List
12268 @cindex Local variables
12269 @cindex Compile command for formatting
12270 @cindex Format with the compile command
12271
12272 Yet another way to apply the @TeX{} formatting command to a Texinfo file
12273 is to put that command in a @dfn{local variables list} at the end of the
12274 Texinfo file.  You can then specify the @code{tex} or @code{texi2dvi}
12275 commands as a @code{compile-command} and have Emacs run it by typing
12276 @kbd{M-x compile}.  This creates a special shell called the
12277 @file{*compilation*} buffer in which Emacs runs the compile command.
12278 For example, at the end of the @file{gdb.texinfo} file, after the
12279 @code{@@bye}, you could put the following:@refill
12280
12281 @example
12282 @group
12283 Local Variables:
12284 compile-command: "texi2dvi gdb.texinfo"
12285 End:
12286 @end group
12287 @end example
12288
12289 @noindent
12290 This technique is most often used by programmers who also compile programs
12291 this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill
12292
12293
12294 @node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy
12295 @comment  node-name,  next,  previous,  up
12296 @section @TeX{} Formatting Requirements Summary
12297 @cindex Requirements for formatting
12298 @cindex Minimal requirements for formatting
12299 @cindex Formatting requirements
12300
12301 Every Texinfo file that is to be input to @TeX{} must begin with a
12302 @code{\input} command and must contain an @code{@@setfilename} command:
12303
12304 @example
12305 \input texinfo
12306 @@setfilename @var{arg-not-used-by-@@TeX@{@}}
12307 @end example
12308
12309 @noindent
12310 The first command instructs @TeX{} to load the macros it needs to
12311 process a Texinfo file and the second command opens auxiliary files.
12312
12313 Every Texinfo file must end with a line that terminates @TeX{}'s
12314 processing and forces out unfinished pages:
12315
12316 @example
12317 @@bye
12318 @end example
12319
12320 Strictly speaking, these lines are all a Texinfo file needs to be
12321 processed successfully by @TeX{}.  
12322
12323 Usually, however, the beginning includes an @code{@@settitle} command to
12324 define the title of the printed manual, an @code{@@setchapternewpage}
12325 command, a title page, a copyright page, and permissions.  Besides an
12326 @code{@@bye}, the end of a file usually includes indices and a table of
12327 contents.  (And of course most manuals contain a body of text as well.)
12328
12329 @iftex
12330 For more information, see
12331 @ref{settitle, , @code{@@settitle}},
12332 @ref{setchapternewpage, , @code{@@setchapternewpage}},
12333 @ref{Headings, ,Page Headings},
12334 @ref{Titlepage & Copyright Page},
12335 @ref{Printing Indices & Menus}, and
12336 @ref{Contents}.
12337 @end iftex
12338 @noindent
12339 @ifinfo
12340 For more information, see@*
12341 @ref{settitle, , @code{@@settitle}},@*
12342 @ref{setchapternewpage, , @code{@@setchapternewpage}},@*
12343 @ref{Headings, ,Page Headings},@*
12344 @ref{Titlepage & Copyright Page},@*
12345 @ref{Printing Indices & Menus}, and@*
12346 @ref{Contents}.
12347 @end ifinfo
12348
12349
12350 @node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy
12351 @comment  node-name,  next,  previous,  up
12352 @section Preparing to Use @TeX{}
12353 @cindex Preparing to use @TeX{}
12354 @cindex @TeX{} input initialization
12355 @cindex @code{TEXINPUTS} environment variable
12356 @vindex TEXINPUTS
12357 @cindex @b{.profile} initialization file
12358 @cindex @b{.cshrc} initialization file
12359 @cindex Initialization file for @TeX{} input
12360
12361 @TeX{} needs to know where to find the @file{texinfo.tex} file that you
12362 have told it to input with the @samp{\input texinfo} command at the
12363 beginning of the first line.  The @file{texinfo.tex} file tells @TeX{}
12364 how to handle @@-commands; it is included in all standard GNU
12365 distributions.
12366
12367 @pindex texinfo.tex@r{, installing}
12368 Usually, the @file{texinfo.tex} file is put under the default directory
12369 that contains @TeX{} macros
12370 (@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when
12371 GNU Emacs or other GNU software is installed.  In this case, @TeX{} will
12372 find the file and you do not need to do anything special.
12373 Alternatively, you can put @file{texinfo.tex} in the current directory
12374 when you run @TeX{}, and @TeX{} will find it there.
12375
12376 @pindex epsf.tex@r{, installing}
12377 Also, you should install @file{epsf.tex} in the same place as
12378 @file{texinfo.tex}, if it is not already installed from another
12379 distribution.  This file is needed to support the @code{@@image} command
12380 (@pxref{Images}).
12381
12382 @pindex texinfo.cnf @r{installation}
12383 @cindex Customizing of @TeX{} for Texinfo
12384 @cindex Site-wide Texinfo configuration file
12385 Optionally, you may create an additional @file{texinfo.cnf}, and install
12386 it as well.  This file is read by @TeX{} at the @code{@@setfilename}
12387 command (@pxref{setfilename,, @code{@@setfilename}}).  You can put any
12388 commands you like there according to local site-wide conventions, and
12389 they will be read by @TeX{} when processing any Texinfo document.  For
12390 example, if @file{texinfo.cnf} contains the a single line
12391 @samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will
12392 be processed with that page size in effect.  If you have nothing to put
12393 in @file{texinfo.cnf}, you do not need to create it.
12394
12395 @vindex TEXINPUTS
12396 If neither of the above locations for these system files suffice for
12397 you, you can specify the directories explicitly.  For
12398 @file{texinfo.tex}, you can do this by writing the complete path for the
12399 file after the @code{\input} command.  Another way, that works for both
12400 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
12401 might read), is to set the @code{TEXINPUTS} environment variable in your
12402 @file{.cshrc} or @file{.profile} file.
12403
12404 Which you use of @file{.cshrc} or @file{.profile} depends on
12405 whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
12406 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
12407 command interpreter.  The latter read the @file{.cshrc} file for
12408 initialization information, and the former read @file{.profile}.
12409
12410 In a @file{.cshrc} file, you could use the following @code{csh} command
12411 sequence:
12412
12413 @example
12414 setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
12415 @end example
12416
12417 @need 1000
12418 In a @file{.profile} file, you could use the following @code{sh} command
12419 sequence:
12420
12421 @example
12422 @group
12423 TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
12424 export TEXINPUTS
12425 @end group
12426 @end example
12427
12428 @noindent
12429 This would cause @TeX{} to look for @file{\input} file first in the current
12430 directory, indicated by the @samp{.}, then in a hypothetical user's
12431 @file{me/mylib} directory, and finally in a system directory.
12432
12433
12434 @node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy
12435 @comment  node-name,  next,  previous,  up
12436 @section Overfull ``hboxes''
12437 @cindex Overfull @samp{hboxes}
12438 @cindex @samp{hboxes}, overfull
12439 @cindex Final output
12440
12441 @TeX{} is sometimes unable to typeset a line without extending it into
12442 the right margin.  This can occur when @TeX{} comes upon what it
12443 interprets as a long word that it cannot hyphenate, such as an
12444 electronic mail network address or a very long title.  When this
12445 happens, @TeX{} prints an error message like this:@refill
12446
12447 @example
12448 Overfull \hbox (20.76302pt too wide)
12449 @end example
12450
12451 @noindent
12452 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
12453 The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill
12454
12455 @TeX{} also provides the line number in the Texinfo source file and
12456 the text of the offending line, which is marked at all the places that
12457 @TeX{} knows how to hyphenate words.
12458 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
12459 for more information about typesetting errors.@refill
12460
12461 If the Texinfo file has an overfull hbox, you can rewrite the sentence
12462 so the overfull hbox does not occur, or you can decide to leave it.  A
12463 small excursion into the right margin often does not matter and may not
12464 even be noticeable.@refill
12465
12466 @cindex Black rectangle in hardcopy
12467 @cindex Rectangle, ugly, black in hardcopy
12468 However, unless told otherwise, @TeX{} will print a large, ugly, black
12469 rectangle beside the line that contains the overfull hbox.  This is so
12470 you will notice the location of the problem if you are correcting a
12471 draft.@refill
12472
12473 @need 1000
12474 @findex finalout
12475 To prevent such a monstrosity from marring your final printout, write
12476 the following in the beginning of the Texinfo file on a line of its own,
12477 before the @code{@@titlepage} command:@refill
12478
12479 @example
12480 @@finalout
12481 @end example
12482
12483 @node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy
12484 @comment  node-name,  next,  previous,  up
12485 @section Printing ``Small'' Books
12486 @findex smallbook
12487 @cindex Small book size
12488 @cindex Book, printing small
12489 @cindex Page sizes for books
12490 @cindex Size of printed book
12491
12492 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
12493 format.  However, you can direct @TeX{} to typeset a document in a 7 by
12494 9.25 inch format that is suitable for bound books by inserting the
12495 following command on a line by itself at the beginning of the Texinfo
12496 file, before the title page:@refill
12497
12498 @example
12499 @@smallbook
12500 @end example
12501
12502 @noindent
12503 (Since regular sized books are often about 7 by 9.25 inches, this
12504 command might better have been called the @code{@@regularbooksize}
12505 command, but it came to be called the @code{@@smallbook} command by
12506 comparison to the 8.5 by 11 inch format.)@refill
12507
12508 If you write the @code{@@smallbook} command between the
12509 start-of-header and end-of-header lines, the Texinfo mode @TeX{}
12510 region formatting command, @code{texinfo-tex-region}, will format the
12511 region in ``small'' book size (@pxref{Start of Header}).@refill
12512
12513 The Free Software Foundation distributes printed copies of @cite{The GNU
12514 Emacs Manual} and other manuals in the ``small'' book size.
12515 @xref{smallexample & smalllisp, , @code{@@smallexample} and
12516 @code{@@smalllisp}}, for information about commands that make it easier
12517 to produce examples for a smaller manual.@refill
12518
12519 Alternatively, to avoid embedding this physical paper size in your
12520 document, use @code{texi2dvi} to format your document (@pxref{Format
12521 with texi2dvi}), and supply @samp{-t @@smallbook} as an argument.  Then
12522 other people do not have to change the document source file to format it
12523 differently.
12524
12525
12526 @node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy
12527 @comment  node-name,  next,  previous,  up
12528 @section Printing on A4 Paper
12529 @cindex A4 paper, printing on
12530 @cindex Paper size, European A4
12531 @cindex European A4 paper
12532 @findex afourpaper
12533
12534 You can tell @TeX{} to typeset a document for printing on European size
12535 A4 paper with the @code{@@afourpaper} command.  Write the command on a
12536 line by itself between @code{@@iftex} and @code{@@end iftex} lines near
12537 the beginning of the Texinfo file, before the title page:@refill
12538
12539 For example, this is how you would write the header for this manual:@refill
12540
12541 @example
12542 @group
12543 \input texinfo    @@c -*-texinfo-*-
12544 @@c %**start of header
12545 @@setfilename texinfo
12546 @@settitle Texinfo
12547 @@syncodeindex vr fn
12548 @@iftex
12549 @@afourpaper
12550 @@end iftex
12551 @@c %**end of header
12552 @end group
12553 @end example
12554
12555 Alternatively, to avoid embedding this physical paper size in your
12556 document, use @code{texi2dvi} to format your document (@pxref{Format
12557 with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument.  Then
12558 other people do not have to change the document source file to format it
12559 differently.
12560
12561 @pindex texinfo.cnf
12562 Another alternative: put the @code{@@afourpaper} command in the file
12563 @file{texinfo.cnf} that @TeX{} will read.  (No need for @code{@@iftex}
12564 there.)  This will automatically typeset all the Texinfo documents at
12565 your site with that paper size in effect.
12566
12567
12568 @node Cropmarks and Magnification,  , A4 Paper, Format/Print Hardcopy
12569 @comment  node-name,  next,  previous,  up
12570 @section Cropmarks and Magnification
12571
12572 @findex cropmarks
12573 @cindex Cropmarks for printing
12574 @cindex Printing cropmarks
12575 You can attempt to direct @TeX{} to print cropmarks at the corners of
12576 pages with the @code{@@cropmarks} command.  Write the @code{@@cropmarks}
12577 command on a line by itself between @code{@@iftex} and @code{@@end
12578 iftex} lines near the beginning of the Texinfo file, before the title
12579 page, like this:@refill
12580
12581 @example
12582 @group
12583 @@iftex
12584 @@cropmarks
12585 @@end iftex
12586 @end group
12587 @end example
12588
12589 This command is mainly for printers that typeset several pages on one
12590 sheet of film; but you can attempt to use it to mark the corners of a
12591 book set to 7 by 9.25 inches with the @code{@@smallbook} command.
12592 (Printers will not produce cropmarks for regular sized output that is
12593 printed on regular sized paper.)  Since different printing machines work
12594 in different ways, you should explore the use of this command with a
12595 spirit of adventure.  You may have to redefine the command in the
12596 @file{texinfo.tex} definitions file.@refill
12597
12598 @findex mag @r{(@TeX{} command)}
12599 @cindex Magnified printing
12600 @cindex Larger or smaller pages
12601 You can attempt to direct @TeX{} to typeset pages larger or smaller than
12602 usual with the @code{\mag} @TeX{} command.  Everything that is typeset
12603 is scaled proportionally larger or smaller.  (@code{\mag} stands for
12604 ``magnification''.)  This is @emph{not} a Texinfo @@-command, but is a
12605 plain @TeX{} command that is prefixed with a backslash.  You have to
12606 write this command between @code{@@tex} and @code{@@end tex}
12607 (@pxref{Raw Formatter Commands}).
12608
12609 Follow the @code{\mag} command with an @samp{=} and then a number that
12610 is 1000 times the magnification you desire.  For example, to print pages
12611 at 1.2 normal size, write the following near the beginning of the
12612 Texinfo file, before the title page:@refill
12613
12614 @example
12615 @group
12616 @@tex
12617 \mag=1200
12618 @@end tex
12619 @end group
12620 @end example
12621
12622 With some printing technologies, you can print normal-sized copies that
12623 look better than usual by using a larger-than-normal master.@refill
12624
12625 Depending on your system, @code{\mag} may not work or may work only at
12626 certain magnifications.  Be prepared to experiment.@refill
12627
12628 @node Create an Info File, Install an Info File, Format/Print Hardcopy, Top
12629 @comment  node-name,  next,  previous,  up
12630 @chapter Creating an Info File
12631 @cindex Creating an Info file
12632 @cindex Info, creating an on-line file
12633 @cindex Formatting a file for Info
12634
12635 @code{makeinfo} is a utility that converts a Texinfo file into an Info
12636 file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
12637 GNU Emacs functions that do the same.@refill
12638
12639 A Texinfo file must contain an @code{@@setfilename} line near its
12640 beginning, otherwise the Info formatting commands will fail.
12641
12642 For information on installing the Info file in the Info system, see
12643 @ref{Install an Info File}.@refill
12644
12645 @menu
12646 * makeinfo advantages::         @code{makeinfo} provides better error checking.
12647 * Invoking makeinfo::           How to run @code{makeinfo} from a shell.
12648 * makeinfo options::            Specify fill-column and other options.
12649 * Pointer Validation::          How to check that pointers point somewhere.
12650 * makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
12651 * texinfo-format commands::     Two Info formatting commands written
12652                                   in Emacs Lisp are an alternative
12653                                   to @code{makeinfo}.
12654 * Batch Formatting::            How to format for Info in Emacs Batch mode.
12655 * Tag and Split Files::         How tagged and split files help Info
12656                                   to run better.
12657 @end menu
12658
12659 @node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File
12660 @ifinfo
12661 @heading @code{makeinfo} Preferred
12662 @end ifinfo
12663
12664 The @code{makeinfo} utility creates an Info file from a Texinfo source
12665 file more quickly than either of the Emacs formatting commands and
12666 provides better error messages.  We recommend it.  @code{makeinfo} is a
12667 C program that is independent of Emacs.  You do not need to run Emacs to
12668 use @code{makeinfo}, which means you can use @code{makeinfo} on machines
12669 that are too small to run Emacs. You can run @code{makeinfo} in
12670 any one of three ways: from an operating system shell, from a shell
12671 inside Emacs, or by typing a key command in Texinfo mode in Emacs.
12672 @refill
12673
12674 The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
12675 commands are useful if you cannot run @code{makeinfo}.  Also, in some
12676 circumstances, they format short regions or buffers more quickly than
12677 @code{makeinfo}.@refill
12678
12679 @node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File
12680 @section Running @code{makeinfo} from a Shell
12681
12682 To create an Info file from a Texinfo file, type @code{makeinfo}
12683 followed by the name of the Texinfo file.  Thus, to create the Info
12684 file for Bison, type the following to the shell:
12685 is the prompt):@refill
12686
12687 @example
12688 makeinfo bison.texinfo
12689 @end example
12690
12691 (You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
12692
12693 @ifinfo
12694 Sometimes you will want to specify options.  For example, if you wish
12695 to discover which version of @code{makeinfo} you are using,
12696 type:@refill
12697
12698 @example
12699 makeinfo --version
12700 @end example
12701
12702 @xref{makeinfo options}, for more information.
12703 @end ifinfo
12704
12705
12706 @node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File
12707 @comment  node-name,  next,  previous,  up
12708 @section Options for @code{makeinfo}
12709 @cindex @code{makeinfo} options
12710 @cindex Options for @code{makeinfo}
12711
12712 The @code{makeinfo} command takes a number of options.  Most often,
12713 options are used to set the value of the fill column and specify the
12714 footnote style.  Each command line option is a word preceded by
12715 @samp{--} or a letter preceded by @samp{-}.  You can use abbreviations
12716 for the long option names as long as they are unique.@refill
12717
12718 For example, you could use the following shell command to create an Info
12719 file for @file{bison.texinfo} in which each line is filled to only 68
12720 columns:@refill
12721
12722 @example
12723 makeinfo --fill-column=68 bison.texinfo
12724 @end example
12725
12726 You can write two or more options in sequence, like this:@refill
12727
12728 @example
12729 makeinfo --no-split --fill-column=70 @dots{}
12730 @end example
12731
12732 @noindent
12733 This would keep the Info file together as one possibly very long
12734 file and would also set the fill column to 70.@refill
12735
12736 The options are:
12737
12738 @table @code
12739
12740 @item -D @var{var}
12741 @opindex -D @var{var}
12742 Cause the variable @var{var} to be defined.  This is equivalent to
12743 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
12744
12745 @item --error-limit=@var{limit}
12746 @opindex --error-limit=@var{limit}
12747 Set the maximum number of errors that @code{makeinfo} will report
12748 before exiting (on the assumption that continuing would be useless);
12749 default 100.
12750
12751 @need 150
12752 @item --fill-column=@var{width}
12753 @opindex --fill-column=@var{width}
12754 Specify the maximum number of columns in a line; this is the right-hand
12755 edge of a line.  Paragraphs that are filled will be filled to this
12756 width.  (Filling is the process of breaking up and connecting lines so
12757 that lines are the same length as or shorter than the number specified
12758 as the fill column.  Lines are broken between words.) The default value
12759 is 72.
12760
12761 @item --footnote-style=@var{style}
12762 @opindex --footnote-style=@var{style}
12763 Set the footnote style to @var{style}, either @samp{end} for the end
12764 node style (the default) or @samp{separate} for the separate node style.
12765 The value set by this option overrides the value set in a Texinfo file
12766 by an @code{@@footnotestyle} command (@pxref{Footnotes}).  When the
12767 footnote style is @samp{separate}, @code{makeinfo} makes a new node
12768 containing the footnotes found in the current node.  When the footnote
12769 style is @samp{end}, @code{makeinfo} places the footnote references at
12770 the end of the current node.
12771
12772 @item --force
12773 @opindex --force
12774 Ordinarily, if the input file has errors, the output files are not
12775 created.  With this option, they are preserved.
12776
12777 @item --help
12778 @opindex --help
12779 Print a usage message listing all available options, then exit successfully.
12780
12781 @item -I @var{dir}
12782 @opindex -I @var{dir}
12783 Add @code{dir} to the directory search list for finding files that are
12784 included using the @code{@@include} command.  By default,
12785 @code{makeinfo} searches only the current directory.
12786
12787 @item --no-headers
12788 @opindex --no-headers
12789 Do not include menus or node lines in the output.  This results in an
12790 @sc{ascii} file that you cannot read in Info since it does not contain
12791 the requisite nodes or menus. It is primarily useful to extract certain
12792 pieces of a manual into separate files to be included in a distribution,
12793 such as @file{INSTALL} files.
12794
12795 @item --no-split
12796 @opindex --no-split
12797 Suppress the splitting stage of @code{makeinfo}.  By default, large
12798 output files (where the size is greater than 70k bytes) are split into
12799 smaller subfiles, each one approximately 50k bytes.
12800
12801 @item --no-pointer-validate
12802 @itemx --no-validate
12803 @opindex --no-pointer-validate
12804 @opindex --no-validate
12805 Suppress the pointer-validation phase of @code{makeinfo}.  Normally,
12806 after a Texinfo file is processed, some consistency checks are made to
12807 ensure that cross references can be resolved, etc.
12808 @xref{Pointer Validation}.@refill
12809
12810 @item --no-warn
12811 @opindex --no-warn
12812 Suppress warning messages (but @emph{not} error messages).  You might
12813 want this if the file you are creating has examples of Texinfo cross
12814 references within it, and the nodes that are referenced do not actually
12815 exist.
12816
12817 @item --no-number-footnotes
12818 @opindex --no-number-footnotes
12819 Suppress automatic footnote numbering.  By default, @code{makeinfo}
12820 numbers each footnote sequentially in a single node, resetting the
12821 current footnote number to 1 at the start of each node.
12822
12823 @item --output=@var{file}
12824 @itemx -o @var{file}
12825 @opindex --output=@var{file}
12826 @opindex -o @var{file}
12827 Specify that the output should be directed to @var{file} and not to the
12828 file name specified in the @code{@@setfilename} command found in the
12829 Texinfo source (@pxref{setfilename}).  If @var{file} is @samp{-}, output
12830 goes to standard output and @samp{--no-split} is implied.
12831
12832 @item -P @var{dir}
12833 @opindex -P @var{dir}
12834 Prepend @code{dir} to the directory search list for @code{@@include}.
12835 See @samp{-I} for more details.
12836
12837 @item --paragraph-indent=@var{indent}
12838 @opindex --paragraph-indent=@var{indent}
12839 Set the paragraph indentation style to @var{indent}.  The value set by
12840 this option overrides the value set in a Texinfo file by an
12841 @code{@@paragraphindent} command (@pxref{paragraphindent}).  The value
12842 of @var{indent} is interpreted as follows:
12843
12844 @table @asis
12845 @item @samp{asis}
12846 Preserve any existing indentation at the starts of paragraphs.
12847
12848 @item @samp{0} or @samp{none}
12849 Delete any existing indentation.
12850
12851 @item @var{num}
12852 Indent each paragraph by that number of spaces.
12853 @end table
12854
12855 @item --reference-limit=@var{limit}
12856 @opindex --reference-limit=@var{limit}
12857 Set the value of the number of references to a node that
12858 @code{makeinfo} will make without reporting a warning.  If a node has more
12859 than this number of references in it, @code{makeinfo} will make the
12860 references but also report a warning.  The default is 1000.
12861
12862 @item -U @var{var}
12863 Cause @var{var} to be undefined.  This is equivalent to
12864 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
12865
12866 @item --verbose
12867 @opindex --verbose
12868 Cause @code{makeinfo} to display messages saying what it is doing.
12869 Normally, @code{makeinfo} only outputs messages if there are errors or
12870 warnings.
12871
12872 @item --version
12873 @opindex --version
12874 Print the version number, then exit successfully.
12875
12876 @end table
12877
12878
12879 @node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File
12880 @section Pointer Validation
12881 @cindex Pointer validation with @code{makeinfo}
12882 @cindex Validation of pointers
12883
12884 If you do not suppress pointer-validation, @code{makeinfo} will check
12885 the validity of the final Info file.  Mostly, this means ensuring that
12886 nodes you have referenced really exist.  Here is a complete list of what
12887 is checked:@refill
12888
12889 @enumerate
12890 @item
12891 If a `Next', `Previous', or `Up' node reference is a reference to a
12892 node in the current file and is not an external reference such as to
12893 @file{(dir)}, then the referenced node must exist.@refill
12894
12895 @item
12896 In every node, if the `Previous' node is different from the `Up' node,
12897 then the `Previous' node must also be pointed to by a `Next' node.@refill
12898
12899 @item
12900 Every node except the `Top' node must have an `Up' pointer.@refill
12901
12902 @item
12903 The node referenced by an `Up' pointer must contain a reference to the
12904 current node in some manner other than through a `Next' reference.
12905 This includes menu entries and cross references.@refill
12906
12907 @item
12908 If the `Next' reference of a node is not the same as the `Next' reference
12909 of the `Up' reference, then the node referenced by the `Next' pointer
12910 must have a `Previous' pointer that points back to the current node.
12911 This rule allows the last node in a section to point to the first node
12912 of the next chapter.@refill
12913 @end enumerate
12914
12915 @node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File
12916 @section Running @code{makeinfo} inside Emacs
12917 @cindex Running @code{makeinfo} in Emacs
12918 @cindex @code{makeinfo} inside Emacs
12919 @cindex Shell, running @code{makeinfo} in
12920
12921 You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
12922 @code{makeinfo-region} or the @code{makeinfo-buffer} commands.  In
12923 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
12924 C-m C-b} by default.@refill
12925
12926 @table @kbd
12927 @item C-c C-m C-r
12928 @itemx M-x makeinfo-region
12929 Format the current region for Info.@refill
12930 @findex makeinfo-region
12931
12932 @item C-c C-m C-b
12933 @itemx M-x makeinfo-buffer
12934 Format the current buffer for Info.@refill
12935 @findex makeinfo-buffer
12936 @end table
12937
12938 When you invoke either @code{makeinfo-region} or
12939 @code{makeinfo-buffer}, Emacs prompts for a file name, offering the
12940 name of the visited file as the default.  You can edit the default
12941 file name in the minibuffer if you wish, before pressing @key{RET} to
12942 start the @code{makeinfo} process.@refill
12943
12944 The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
12945 run the @code{makeinfo} program in a temporary shell buffer.  If
12946 @code{makeinfo} finds any errors, Emacs displays the error messages in
12947 the temporary buffer.@refill
12948
12949 @cindex Errors, parsing
12950 @cindex Parsing errors
12951 @findex next-error
12952 You can parse the error messages by typing @kbd{C-x `}
12953 (@code{next-error}).  This causes Emacs to go to and position the
12954 cursor on the line in the Texinfo source that @code{makeinfo} thinks
12955 caused the error.  @xref{Compilation, , Running @code{make} or
12956 Compilers Generally, xemacs, XEmacs User's Manual}, for more
12957 information about using the @code{next-error} command.@refill
12958
12959 In addition, you can kill the shell in which the @code{makeinfo}
12960 command is running or make the shell buffer display its most recent
12961 output.@refill
12962
12963 @table @kbd
12964 @item C-c C-m C-k
12965 @itemx M-x makeinfo-kill-job
12966 @findex makeinfo-kill-job
12967 Kill the current running @code{makeinfo} job created by
12968 @code{makeinfo-region} or @code{makeinfo-buffer}.@refill
12969
12970 @item C-c C-m C-l
12971 @itemx M-x makeinfo-recenter-output-buffer
12972 @findex makeinfo-recenter-output-buffer
12973 Redisplay the @code{makeinfo} shell buffer to display its most recent
12974 output.@refill
12975 @end table
12976
12977 @noindent
12978 (Note that the parallel commands for killing and recentering a @TeX{}
12979 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}.  @xref{Texinfo Mode
12980 Printing}.)@refill
12981
12982 You can specify options for @code{makeinfo} by setting the
12983 @code{makeinfo-options} variable with either the @kbd{M-x
12984 edit-options} or the @kbd{M-x set-variable} command, or by setting the
12985 variable in your @file{.emacs} initialization file.@refill
12986
12987 For example, you could write the following in your @file{.emacs} file:@refill
12988
12989 @example
12990 @group
12991 (setq makeinfo-options
12992       "--paragraph-indent=0 --no-split
12993        --fill-column=70 --verbose")
12994 @end group
12995 @end example
12996
12997 @c If you write these three cross references using xref, you see
12998 @c three references to the same named manual, which looks strange.
12999 @iftex
13000 For more information, see @ref{makeinfo options, , Options for
13001 @code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and
13002 Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs
13003 Manual}.
13004 @end iftex
13005 @noindent
13006 @ifinfo
13007 For more information, see@*
13008 @ref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's Manual},@*
13009 @ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@*
13010 @ref{Init File, , , xemacs, XEmacs User's Manual}, and@*
13011 @ref{makeinfo options, , Options for @code{makeinfo}}.
13012 @end ifinfo
13013
13014 @node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File
13015 @comment  node-name,  next,  previous,  up
13016 @section The @code{texinfo-format@dots{}} Commands
13017 @findex texinfo-format-region
13018 @findex texinfo-format-buffer
13019
13020 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
13021 file with the @code{texinfo-format-region} command.  This formats the
13022 current region and displays the formatted text in a temporary buffer
13023 called @samp{*Info Region*}.@refill
13024
13025 Similarly, you can format a buffer with the
13026 @code{texinfo-format-buffer} command.  This command creates a new
13027 buffer and generates the Info file in it.  Typing @kbd{C-x C-s} will
13028 save the Info file under the name specified by the
13029 @code{@@setfilename} line which must be near the beginning of the
13030 Texinfo file.@refill
13031
13032 @table @kbd
13033 @item C-c C-e C-r
13034 @itemx @code{texinfo-format-region}
13035 Format the current region for Info.
13036 @findex texinfo-format-region
13037
13038 @item C-c C-e C-b
13039 @itemx @code{texinfo-format-buffer}
13040 Format the current buffer for Info.
13041 @findex texinfo-format-buffer
13042 @end table
13043
13044 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
13045 commands provide you with some error checking, and other functions can
13046 provide you with further help in finding formatting errors.  These
13047 procedures are described in an appendix; see @ref{Catching Mistakes}.
13048 However, the @code{makeinfo} program is often faster and
13049 provides better error checking (@pxref{makeinfo in Emacs}).@refill
13050
13051 @node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File
13052 @comment  node-name,  next,  previous,  up
13053 @section Batch Formatting
13054 @cindex Batch formatting for Info
13055 @cindex Info batch formatting
13056
13057 You can format Texinfo files for Info using @code{batch-texinfo-format}
13058 and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
13059 including a shell inside of Emacs.  (@xref{Command Switches, , Command
13060 Line Switches and Arguments, xemacs, XEmacs User's Manual}.)@refill
13061
13062 Here is a shell command to format all the files that end in
13063 @file{.texinfo} in the current directory:
13064
13065 @example
13066 emacs -batch -funcall batch-texinfo-format *.texinfo
13067 @end example
13068
13069 @noindent
13070 Emacs processes all the files listed on the command line, even if an
13071 error occurs while attempting to format some of them.@refill
13072
13073 Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
13074 it is not interactive.  It kills the Batch mode Emacs on completion.@refill
13075
13076 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
13077 and want to format several Texinfo files at once.  When you use Batch
13078 mode, you create a new Emacs process.  This frees your current Emacs, so
13079 you can continue working in it.  (When you run
13080 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
13081 use that Emacs for anything else until the command finishes.)@refill
13082
13083 @node Tag and Split Files,  , Batch Formatting, Create an Info File
13084 @comment  node-name,  next,  previous,  up
13085 @section Tag Files and Split Files
13086 @cindex Making a tag table automatically
13087 @cindex Tag table, making automatically
13088
13089 If a Texinfo file has more than 30,000 bytes,
13090 @code{texinfo-format-buffer} automatically creates a tag table
13091 for its Info file;  @code{makeinfo} always creates a tag table.  With
13092 a @dfn{tag table}, Info can jump to new nodes more quickly than it can
13093 otherwise.@refill
13094
13095 @cindex Indirect subfiles
13096 In addition, if the Texinfo file contains more than about 70,000
13097 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
13098 large Info file into shorter @dfn{indirect} subfiles of about 50,000
13099 bytes each.  Big files are split into smaller files so that Emacs does
13100 not need to make a large buffer to hold the whole of a large Info
13101 file; instead, Emacs allocates just enough memory for the small, split
13102 off file that is needed at the time.  This way, Emacs avoids wasting
13103 memory when you run Info.  (Before splitting was implemented, Info
13104 files were always kept short and @dfn{include files} were designed as
13105 a way to create a single, large printed manual out of the smaller Info
13106 files.  @xref{Include Files}, for more information.  Include files are
13107 still used for very large documents, such as @cite{The XEmacs Lisp
13108 Reference Manual}, in which each chapter is a separate file.)@refill
13109
13110 When a file is split, Info itself makes use of a shortened version of
13111 the original file that contains just the tag table and references to
13112 the files that were split off.  The split off files are called
13113 @dfn{indirect} files.@refill
13114
13115 The split off files have names that are created by appending @w{@samp{-1}},
13116 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
13117 @code{@@setfilename} command.  The shortened version of the original file
13118 continues to have the name specified by @code{@@setfilename}.@refill
13119
13120 At one stage in writing this document, for example, the Info file was saved
13121 as @file{test-texinfo} and that file looked like this:@refill
13122
13123 @example
13124 @group
13125 Info file: test-texinfo,    -*-Text-*-
13126 produced by texinfo-format-buffer
13127 from file: new-texinfo-manual.texinfo
13128
13129 ^_
13130 Indirect:
13131 test-texinfo-1: 102
13132 test-texinfo-2: 50422
13133 @end group
13134 @group
13135 test-texinfo-3: 101300
13136 ^_^L
13137 Tag table:
13138 (Indirect)
13139 Node: overview^?104
13140 Node: info file^?1271
13141 @end group
13142 @group
13143 Node: printed manual^?4853
13144 Node: conventions^?6855
13145 @dots{}
13146 @end group
13147 @end example
13148
13149 @noindent
13150 (But @file{test-texinfo} had far more nodes than are shown here.)  Each of
13151 the split off, indirect files, @file{test-texinfo-1},
13152 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
13153 after the line that says @samp{Indirect:}.  The tag table is listed after
13154 the line that says @samp{Tag table:}. @refill
13155
13156 In the list of indirect files, the number following the file name
13157 records the cumulative number of bytes in the preceding indirect files,
13158 not counting the file list itself, the tag table, or the permissions
13159 text in each file.  In the tag table, the number following the node name
13160 records the location of the beginning of the node, in bytes from the
13161 beginning.@refill
13162
13163 If you are using @code{texinfo-format-buffer} to create Info files,
13164 you may want to run the @code{Info-validate} command.  (The
13165 @code{makeinfo} command does such a good job on its own, you do not
13166 need @code{Info-validate}.)  However, you cannot run the @kbd{M-x
13167 Info-validate} node-checking command on indirect files.  For
13168 information on how to prevent files from being split and how to
13169 validate the structure of the nodes, see @ref{Using
13170 Info-validate}.@refill
13171
13172
13173 @node Install an Info File, Command List, Create an Info File, Top
13174 @comment  node-name,  next,  previous,  up
13175 @chapter Installing an Info File
13176 @cindex Installing an Info file
13177 @cindex Info file installation
13178 @cindex @file{dir} directory for Info installation
13179
13180 Info files are usually kept in the @file{info} directory.  You can read
13181 Info files using the standalone Info program or the Info reader built
13182 into Emacs.  (@inforef{Top, info, info}, for an introduction to Info.)
13183
13184 @menu
13185 * Directory file::              The top level menu for all Info files.
13186 * New Info File::               Listing a new info file.
13187 * Other Info Directories::      How to specify Info files that are
13188                                   located in other directories.
13189 * Installing Dir Entries::      How to specify what menu entry to add
13190                                   to the Info directory.
13191 * Invoking install-info::       @code{install-info} options.
13192 @end menu
13193
13194 @node Directory file, New Info File, Install an Info File, Install an Info File
13195 @ifinfo
13196 @heading The @file{dir} File
13197 @end ifinfo
13198
13199 For Info to work, the @file{info} directory must contain a file that
13200 serves as a top level directory for the Info system.  By convention,
13201 this file is called @file{dir}.  (You can find the location of this file
13202 within Emacs by typing @kbd{C-h i} to enter Info and then typing
13203 @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
13204
13205 The @file{dir} file is itself an Info file.  It contains the top level
13206 menu for all the Info files in the system.  The menu looks like
13207 this:@refill
13208
13209 @example
13210 @group
13211 * Menu:
13212
13213 * Info:    (info).     Documentation browsing system.
13214 * Emacs:   (emacs).    The extensible, self-documenting
13215                        text editor.
13216 * Texinfo: (texinfo).  With one source file, make
13217                        either a printed manual using
13218                        TeX or an Info file.
13219 @dots{}
13220 @end group
13221 @end example
13222
13223 Each of these menu entries points to the `Top' node of the Info file
13224 that is named in parentheses.  (The menu entry does not need to
13225 specify the `Top' node, since Info goes to the `Top' node if no node
13226 name is mentioned.  @xref{Other Info Files, , Nodes in Other Info
13227 Files}.)@refill
13228
13229 Thus, the @samp{Info} entry points to the `Top' node of the
13230 @file{info} file and the @samp{Emacs} entry points to the `Top' node
13231 of the @file{emacs} file.@refill
13232
13233 In each of the Info files, the `Up' pointer of the `Top' node refers
13234 back to the @code{dir} file.  For example, the line for the `Top'
13235 node of the Emacs manual looks like this in Info:@refill
13236
13237 @example
13238 File: emacs  Node: Top, Up: (DIR), Next: Distrib
13239 @end example
13240
13241 @noindent
13242 (Note that in this case, the @file{dir} file name is written in upper
13243 case letters---it can be written in either upper or lower case.  Info
13244 has a feature that it will change the case of the file name to lower
13245 case if it cannot find the name as written.)@refill
13246 @c !!! Can any file name be written in upper or lower case,
13247 @c     or is dir a special case?
13248 @c     Yes, apparently so, at least with Gillespie's Info.  --rjc 24mar92
13249
13250
13251 @node New Info File, Other Info Directories, Directory file, Install an Info File
13252 @section Listing a New Info File
13253 @cindex Adding a new info file
13254 @cindex Listing a new info file
13255 @cindex New info file, listing it in @file{dir} file
13256 @cindex Info file, listing new one
13257 @cindex @file{dir} file listing
13258
13259 To add a new Info file to your system, you must write a menu entry to
13260 add to the menu in the @file{dir} file in the @file{info} directory.
13261 For example, if you were adding documentation for GDB, you would write
13262 the following new entry:@refill
13263
13264 @example
13265 * GDB: (gdb).           The source-level C debugger.
13266 @end example
13267
13268 @noindent
13269 The first part of the menu entry is the menu entry name, followed by a
13270 colon.  The second part is the name of the Info file, in parentheses,
13271 followed by a period.  The third part is the description.
13272
13273 The name of an Info file often has a @file{.info} extension.  Thus, the
13274 Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
13275 The Info reader programs automatically try the file name both with and
13276 without @file{.info}; so it is better to avoid clutter and not to write
13277 @samp{.info} explicitly in the menu entry.  For example, the GDB menu
13278 entry should use just @samp{gdb} for the file name, not @samp{gdb.info}.
13279
13280
13281 @node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File
13282 @comment  node-name,  next,  previous,  up
13283 @section Info Files in Other Directories
13284 @cindex Installing Info in another directory
13285 @cindex Info installed in another directory
13286 @cindex Another Info directory
13287
13288 If an Info file is not in the @file{info} directory, there are three
13289 ways to specify its location:@refill
13290
13291 @itemize @bullet
13292 @item
13293 Write the pathname in the @file{dir} file as the second part of the
13294 menu.@refill
13295
13296 @item
13297 If you are using Emacs, list the name of the file in a second @file{dir}
13298 file, in its directory; and then add the name of that directory to the
13299 @code{Info-directory-list} variable in your personal or site
13300 initialization file.
13301
13302 This tells Emacs where to look for @file{dir} files.  Emacs merges the
13303 files named @file{dir} from each of the listed directories.  (In Emacs
13304 version 18, you can set the @code{Info-directory} variable to the name
13305 of only one directory.)@refill
13306
13307 @item
13308 Specify the Info directory name in the @code{INFOPATH} environment
13309 variable in your @file{.profile} or @file{.cshrc} initialization file.
13310 (Only you and others who set this environment variable will be able to
13311 find Info files whose location is specified this way.)@refill
13312 @end itemize
13313
13314 For example, to reach a test file in the @file{/home/bob/manuals}
13315 directory, you could add an entry like this to the menu in the
13316 @file{dir} file:@refill
13317
13318 @example
13319 * Test: (/home/bob/manuals/info-test).  Bob's own test file.
13320 @end example
13321
13322 @noindent
13323 In this case, the absolute file name of the @file{info-test} file is
13324 written as the second part of the menu entry.@refill
13325
13326 @vindex Info-directory-list
13327 Alternatively, you could write the following in your @file{.emacs}
13328 file:@refill
13329
13330 @example
13331 @group
13332 (setq Info-directory-list
13333       '("/home/bob/manuals"
13334         "/usr/local/info"))
13335 @end group
13336 @end example
13337
13338 @c reworded to avoid overfill hbox
13339 This tells Emacs to merge the @file{dir} file from the
13340 @file{/home/bob/manuals} directory with the @file{dir} file from the
13341 @file{/usr/local/info} directory.  Info will list the
13342 @file{/home/bob/manuals/info-test} file as a menu entry in the
13343 @file{/home/bob/manuals/dir} file.@refill
13344
13345 @vindex INFOPATH
13346 Finally, you can tell Info where to look by setting the @code{INFOPATH}
13347 environment variable in your @file{.cshrc} or @file{.profile} file.  If
13348 you use a Bourne-compatible shell such as @code{sh} or @code{bash} for
13349 your shell command interpreter, you set the @code{INFOPATH} environment
13350 variable in the @file{.profile} initialization file; but if you use
13351 @code{csh} or @code{tcsh}, you must set the variable in the
13352 @file{.cshrc} initialization file.  The two types of shells use
13353 different syntax.
13354
13355 @itemize @bullet
13356 @item
13357 In a @file{.cshrc} file, you could set the @code{INFOPATH}
13358 variable as follows:@refill
13359
13360 @smallexample
13361 setenv INFOPATH .:~/manuals:/usr/local/emacs/info
13362 @end smallexample
13363
13364 @item
13365 In a @file{.profile} file, you would achieve the same effect by
13366 writing:@refill
13367
13368 @smallexample
13369 INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
13370 export INFOPATH
13371 @end smallexample
13372 @end itemize
13373
13374 @noindent
13375 The @samp{.} indicates the current directory as usual.  Emacs uses the
13376 @code{INFOPATH} environment variable to initialize the value of Emacs's
13377 own @code{Info-directory-list} variable.
13378
13379 @cindex colon @r{last in @code{INFOPATH}}
13380 However you set @code{INFOPATH}, if its last character is a colon, this
13381 is replaced by the default (compiled-in) path.  This gives you a way to
13382 augment the default path with new directories without having to list all
13383 the standard places.  For example (using @code{sh} syntax:
13384
13385 @example
13386 INFOPATH=/local/info:
13387 export INFOPATH
13388 @end example
13389
13390 @noindent
13391 will search @file{/local/info} first, then the standard directories.
13392 Leading or doubled colons are not treated specially.
13393
13394
13395 @node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File
13396 @section Installing Info Directory Files
13397
13398 When you install an Info file onto your system, you can use the program
13399 @code{install-info} to update the Info directory file @file{dir}.
13400 Normally the makefile for the package runs @code{install-info}, just
13401 after copying the Info file into its proper installed location.
13402
13403 @findex dircategory
13404 @findex direntry
13405 In order for the Info file to work with @code{install-info}, you should
13406 use the commands @code{@@dircategory} and @code{@@direntry} in the
13407 Texinfo source file.  Use @code{@@direntry} to specify the menu entry to
13408 add to the Info directory file, and use @code{@@dircategory} to specify
13409 which part of the Info directory to put it in.  Here is how these
13410 commands are used in this manual:
13411
13412 @smallexample
13413 @@dircategory Texinfo documentation system
13414 @@direntry
13415 * Texinfo: (texinfo).           The GNU documentation format.
13416 * install-info: (texinfo)Invoking install-info. @dots{}
13417 @dots{}
13418 @@end direntry
13419 @end smallexample
13420
13421 Here's what this produces in the Info file:
13422
13423 @smallexample
13424 INFO-DIR-SECTION Texinfo documentation system
13425 START-INFO-DIR-ENTRY
13426 * Texinfo: (texinfo).           The GNU documentation format.
13427 * install-info: (texinfo)Invoking install-info. @dots{}
13428 @dots{}
13429 END-INFO-DIR-ENTRY
13430 @end smallexample
13431
13432 @noindent
13433 The @code{install-info} program sees these lines in the Info file, and
13434 that is how it knows what to do.
13435
13436 Always use the @code{@@direntry} and @code{@@dircategory} commands near
13437 the beginning of the Texinfo input, before the first @code{@@node}
13438 command.  If you use them later on in the input, @code{install-info}
13439 will not notice them.
13440
13441 If you use @code{@@dircategory} more than once in the Texinfo source,
13442 each usage specifies one category; the new menu entry is added to the
13443 Info directory file in each of the categories you specify.  If you use
13444 @code{@@direntry} more than once, each usage specifies one menu entry;
13445 each of these menu entries is added to the directory in each of the
13446 specified categories.
13447
13448
13449 @node Invoking install-info,  , Installing Dir Entries, Install an Info File
13450 @section Invoking install-info
13451
13452 @pindex install-info
13453
13454 @code{install-info} inserts menu entries from an Info file into the
13455 top-level @file{dir} file in the Info system (see the previous sections
13456 for an explanation of how the @file{dir} file works).  It's most often
13457 run as part of software installation, or when constructing a dir file
13458 for all manuals on a system.  Synopsis:
13459
13460 @example
13461 install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
13462 @end example
13463
13464 If @var{info-file} or @var{dir-file} are not specified, the various
13465 options (described below) that define them must be.  There are no
13466 compile-time defaults, and standard input is never used.
13467 @code{install-info} can read only one info file and write only one dir
13468 file per invocation.
13469
13470 @cindex @file{dir}, created by @code{install-info}
13471 If @var{dir-file} (however specified) does not exist,
13472 @code{install-info} creates it if possible (with no entries).
13473
13474 Options:
13475
13476 @table @code
13477 @item --delete
13478 @opindex --delete
13479 Delete the entries in @var{info-file} from @var{dir-file}.  The file
13480 name in the entry in @var{dir-file} must be @var{info-file} (except for
13481 an optional @samp{.info} in either one).  Don't insert any new entries.
13482
13483 @item --dir-file=@var{name}
13484 @opindex --dir-file=@var{name}
13485 Specify file name of the Info directory file.  This is equivalent to
13486 using the @var{dir-file} argument.
13487
13488 @item --entry=@var{text}
13489 @opindex --entry=@var{text}
13490 Insert @var{text} as an Info directory entry; @var{text} should have the
13491 form of an Info menu item line plus zero or more extra lines starting
13492 with whitespace.  If you specify more than one entry, they are all
13493 added.  If you don't specify any entries, they are determined from
13494 information in the Info file itself.
13495
13496 @item --help
13497 @opindex --help
13498 Display a usage message listing basic usage and all available options,
13499 then exit successfully.
13500
13501 @item --info-file=@var{file}
13502 @opindex --info-file=@var{file}
13503 Specify Info file to install in the directory.
13504 This is equivalent to using the @var{info-file} argument.
13505
13506 @item --info-dir=@var{dir}
13507 @opindex --info-dir=@var{dir}
13508 Equivalent to @samp{--dir-file=@var{dir}/dir}.
13509
13510 @item --item=@var{text}
13511 @opindex --item=@var{text}
13512 Same as @samp{--entry=@var{text}}.  An Info directory entry is actually
13513 a menu item.
13514
13515 @item --quiet
13516 @opindex --quiet
13517 Suppress warnings.
13518
13519 @item --remove
13520 @opindex --remove
13521 Same as @samp{--delete}.
13522
13523 @item --section=@var{sec}
13524 @opindex --section=@var{sec}
13525 Put this file's entries in section @var{sec} of the directory.  If you
13526 specify more than one section, all the entries are added in each of the
13527 sections.  If you don't specify any sections, they are determined from
13528 information in the Info file itself.
13529
13530 @item --version
13531 @opindex --version
13532 @cindex version number, finding
13533 Display version information and exit successfully.
13534
13535 @end table
13536
13537
13538 @node Command List, Tips, Install an Info File, Top
13539 @appendix @@-Command List
13540 @cindex Alphabetical @@-command list
13541 @cindex List of  @@-commands
13542 @cindex @@-command list
13543
13544 Here is an alphabetical list of the @@-commands in Texinfo.  Square
13545 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
13546 @samp{@dots{}}, indicates repeated text.@refill
13547
13548 @sp 1
13549 @table @code
13550 @item @@@var{whitespace}
13551 An @code{@@} followed by a space, tab, or newline produces a normal,
13552 stretchable, interword space.  @xref{Multiple Spaces}.
13553
13554 @item @@!
13555 Generate an exclamation point that really does end a sentence (usually
13556 after an end-of-sentence capital letter).  @xref{Ending a Sentence}.
13557
13558 @item @@"
13559 @itemx @@'
13560 Generate an umlaut or acute accent, respectively, over the next
13561 character, as in @"o and @'o.  @xref{Inserting Accents}.
13562
13563 @item @@*
13564 Force a line break. Do not end a paragraph that uses @code{@@*} with
13565 an @code{@@refill} command.  @xref{Line Breaks}.@refill
13566
13567 @item @@,@{@var{c}@}
13568 Generate a cedilla accent under @var{c}, as in @,{c}.  @xref{Inserting
13569 Accents}.
13570
13571 @item @@-
13572 Insert a discretionary hyphenation point.  @xref{- and hyphenation}.
13573
13574 @item @@.
13575 Produce a period that really does end a sentence (usually after an
13576 end-of-sentence capital letter).  @xref{Ending a Sentence}.
13577
13578 @item @@:
13579 Indicate to @TeX{} that an immediately preceding period, question
13580 mark, exclamation mark, or colon does not end a sentence.  Prevent
13581 @TeX{} from inserting extra whitespace as it does at the end of a
13582 sentence.  The command has no effect on the Info file output.
13583 @xref{Not Ending a Sentence}.@refill
13584
13585 @item @@=
13586 Generate a macro (bar) accent over the next character, as in @=o.
13587 @xref{Inserting Accents}.
13588
13589 @item @@?
13590 Generate a question mark that really does end a sentence (usually after
13591 an end-of-sentence capital letter).  @xref{Ending a Sentence}.
13592
13593 @item @@@@
13594 Stands for an at sign, @samp{@@}.
13595 @xref{Braces Atsigns, , Inserting @@ and braces}.
13596
13597 @item @@^
13598 @itemx @@`
13599 Generate a circumflex (hat) or grave accent, respectively, over the next
13600 character, as in @^o.
13601 @xref{Inserting Accents}.
13602
13603 @item @@@{
13604 Stands for a left brace, @samp{@{}.
13605 @xref{Braces Atsigns, , Inserting @@ and braces}.
13606
13607 @item @@@}
13608 Stands for a right-hand brace, @samp{@}}.@*
13609 @xref{Braces Atsigns, , Inserting @@ and braces}.
13610
13611 @item @@=
13612 Generate a tilde accent over the next character, as in @~N.
13613 @xref{Inserting Accents}.
13614
13615 @item @@AA@{@}
13616 @itemx @@aa@{@}
13617 Generate the uppercase and lowercase Scandinavian A-ring letters,
13618 respectively: @AA{}, @aa{}.  @xref{Inserting Accents}.
13619
13620 @item @@AE@{@}
13621 @itemx @@ae@{@}
13622 Generate the uppercase and lowercase AE ligatures, respectively:
13623 @AE{}, @ae{}.  @xref{Inserting Accents}.
13624
13625 @item @@afourpaper
13626 Change page dimensions for the A4 paper size.  
13627 Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}.  
13628 @xref{A4 Paper}.
13629
13630 @item @@appendix @var{title}
13631 Begin an appendix.  The title appears in the table
13632 of contents of a printed manual.  In Info, the title is
13633 underlined with asterisks.  @xref{unnumbered & appendix, , The
13634 @code{@@unnumbered} and @code{@@appendix} Commands}.@refill
13635
13636 @item @@appendixsec @var{title}
13637 @itemx @@appendixsection @var{title}
13638 Begin an appendix section within an appendix.  The section title appears
13639 in the table of contents of a printed manual.  In Info, the title is
13640 underlined with equal signs.  @code{@@appendixsection} is a longer
13641 spelling of the @code{@@appendixsec} command.  @xref{unnumberedsec
13642 appendixsec heading, , Section Commands}.@refill
13643
13644 @item @@appendixsubsec @var{title}
13645 Begin an appendix subsection within an appendix.  The title appears
13646 in the table of contents of a printed manual.  In Info, the title is
13647 underlined with hyphens.  @xref{unnumberedsubsec appendixsubsec
13648 subheading, , Subsection Commands}.@refill
13649
13650 @item @@appendixsubsubsec @var{title}
13651 Begin an appendix subsubsection within an appendix subsection.  The
13652 title appears in the table of contents of a printed manual.  In Info,
13653 the title is underlined with periods.  @xref{subsubsection,, The
13654 `subsub' Commands}.@refill
13655
13656 @item @@asis
13657 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
13658 print the table's first column without highlighting (``as is'').
13659 @xref{Two-column Tables, , Making a Two-column Table}.@refill
13660
13661 @item @@author @var{author}
13662 Typeset @var{author} flushleft and underline it.  @xref{title
13663 subtitle author, , The @code{@@title} and @code{@@author}
13664 Commands}.@refill
13665
13666 @item @@b@{@var{text}@}
13667 Print @var{text} in @b{bold} font.  No effect in Info.  @xref{Fonts}.@refill
13668
13669 @ignore
13670 @item @@br
13671 Force a paragraph break.  If used within a line, follow @code{@@br}
13672 with braces.  @xref{br, , @code{@@br}}.@refill
13673 @end ignore
13674
13675 @item @@bullet@{@}
13676 Generate a large round dot, or the closest possible
13677 thing to one.  @xref{bullet, , @code{@@bullet}}.@refill
13678
13679 @item @@bye
13680 Stop formatting a file.  The formatters do not see the contents of a
13681 file following an @code{@@bye} command.  @xref{Ending a File}.@refill
13682
13683 @item @@c @var{comment}
13684 Begin a comment in Texinfo.  The rest of the line does not appear in
13685 either the Info file or the printed manual.  A synonym for
13686 @code{@@comment}.  @xref{Comments, , Comments}.@refill
13687
13688 @item @@cartouche
13689 Highlight an example or quotation by drawing a box with rounded
13690 corners around it.  Pair with @code{@@end cartouche}.  No effect in
13691 Info.  @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
13692
13693 @item @@center @var{line-of-text}
13694 Center the line of text following the command.
13695 @xref{titlefont center sp, , @code{@@center}}.@refill
13696
13697 @item @@centerchap @var{line-of-text}
13698 Like @code{@@chapter}, but centers the chapter title.  @xref{chapter,,
13699 @code{@@chapter}}.
13700
13701 @item @@chapheading @var{title}
13702 Print a chapter-like heading in the text, but not in the table of
13703 contents of a printed manual.  In Info, the title is underlined with
13704 asterisks.  @xref{majorheading & chapheading, , @code{@@majorheading}
13705 and @code{@@chapheading}}.@refill
13706
13707 @item @@chapter @var{title}
13708 Begin a chapter.  The chapter title appears in the table of
13709 contents of a printed manual.  In Info, the title is underlined with
13710 asterisks.  @xref{chapter, , @code{@@chapter}}.@refill
13711
13712 @item @@cindex @var{entry}
13713 Add @var{entry} to the index of concepts.  @xref{Index Entries, ,
13714 Defining the Entries of an Index}.@refill
13715
13716 @item @@cite@{@var{reference}@}
13717 Highlight the name of a book or other reference that lacks a
13718 companion Info file.  @xref{cite, , @code{@@cite}}.@refill
13719
13720 @item @@clear @var{flag}
13721 Unset @var{flag}, preventing the Texinfo formatting commands from
13722 formatting text between subsequent pairs of @code{@@ifset @var{flag}}
13723 and @code{@@end ifset} commands, and preventing
13724 @code{@@value@{@var{flag}@}} from expanding to the value to which
13725 @var{flag} is set.
13726 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
13727
13728 @item @@code@{@var{sample-code}@}
13729 Highlight text that is an expression, a syntactically complete token
13730 of a program, or a program name.  @xref{code, , @code{@@code}}.@refill
13731
13732 @item @@comment @var{comment}
13733 Begin a comment in Texinfo.  The rest of the line does not appear in
13734 either the Info file or the printed manual.  A synonym for @code{@@c}.
13735 @xref{Comments, , Comments}.@refill
13736
13737 @item @@contents
13738 Print a complete table of contents.  Has no effect in Info, which uses
13739 menus instead.  @xref{Contents, , Generating a Table of
13740 Contents}.@refill
13741
13742 @item @@copyright@{@}
13743 Generate a copyright symbol.  @xref{copyright symbol, ,
13744 @code{@@copyright}}.@refill
13745
13746 @ignore
13747 @item @@ctrl@{@var{ctrl-char}@}
13748 Describe an @sc{ascii} control character.  Insert actual control character
13749 into Info file.  @xref{ctrl, , @code{@@ctrl}}.@refill
13750 @end ignore
13751
13752 @item @@defcodeindex @var{index-name}
13753 Define a new index and its indexing command.  Print entries in an
13754 @code{@@code} font.  @xref{New Indices, , Defining New
13755 Indices}.@refill
13756
13757 @item @@defcv @var{category} @var{class} @var{name}
13758 @itemx @@defcvx @var{category} @var{class} @var{name}
13759 Format a description for a variable associated with a class in
13760 object-oriented programming.  Takes three arguments: the category of
13761 thing being defined, the class to which it belongs, and its name.
13762 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13763
13764 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
13765 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
13766 Format a description for a function, interactive command, or similar
13767 entity that may take arguments.  @code{@@deffn} takes as arguments the
13768 category of entity being described, the name of this particular
13769 entity, and its arguments, if any.  @xref{Definition Commands}.@refill
13770
13771 @item @@defindex @var{index-name}
13772 Define a new index and its indexing command.  Print entries in a roman
13773 font.  @xref{New Indices, , Defining New Indices}.@refill
13774
13775 @c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96.
13776 @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
13777 Create new @@-command for Info that marks text by enclosing it in
13778 strings that precede and follow the text.  Write definition inside of
13779 @code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized
13780 Highlighting}.@refill
13781
13782 @item @@defivar @var{class} @var{instance-variable-name}
13783 @itemx @@defivarx @var{class} @var{instance-variable-name}
13784 This command formats a description for an instance variable in
13785 object-oriented programming.  The command is equivalent to @samp{@@defcv
13786 @{Instance Variable@} @dots{}}.  @xref{Definition Commands}, and
13787 @ref{deffnx,, Def Cmds in Detail}.
13788
13789 @item @@defmac @var{macro-name} @var{arguments}@dots{}
13790 @itemx @@defmacx @var{macro-name} @var{arguments}@dots{}
13791 Format a description for a macro.  The command is equivalent to
13792 @samp{@@deffn Macro @dots{}}.  @xref{Definition Commands}, and
13793 @ref{deffnx,, Def Cmds in Detail}.
13794
13795 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
13796 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
13797 Format a description for a method in object-oriented programming.  The
13798 command is equivalent to @samp{@@defop Method @dots{}}.  Takes as
13799 arguments the name of the class of the method, the name of the
13800 method, and its arguments, if any.  @xref{Definition Commands}, and
13801 @ref{deffnx,, Def Cmds in Detail}.
13802
13803 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
13804 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
13805 Format a description for an operation in object-oriented programming.
13806 @code{@@defop} takes as arguments the overall name of the category of
13807 operation, the name of the class of the operation, the name of the
13808 operation, and its arguments, if any.  @xref{Definition
13809 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13810
13811 @item @@defopt @var{option-name}
13812 @itemx @@defoptx @var{option-name}
13813 Format a description for a user option.  The command is equivalent to
13814 @samp{@@defvr @{User Option@} @dots{}}.  @xref{Definition Commands}, and
13815 @ref{deffnx,, Def Cmds in Detail}.
13816
13817 @item @@defspec @var{special-form-name} @var{arguments}@dots{}
13818 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
13819 Format a description for a special form.  The command is equivalent to
13820 @samp{@@deffn @{Special Form@} @dots{}}.  @xref{Definition Commands},
13821 and @ref{deffnx,, Def Cmds in Detail}.
13822
13823 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
13824 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
13825 Format a description for a data type.  @code{@@deftp} takes as arguments
13826 the category, the name of the type (which is a word like @samp{int} or
13827 @samp{float}), and then the names of attributes of objects of that type.
13828 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13829
13830 @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
13831 @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
13832 Format a description for a function or similar entity that may take
13833 arguments and that is typed.  @code{@@deftypefn} takes as arguments the
13834 classification of entity being described, the type, the name of the
13835 entity, and its arguments, if any.  @xref{Definition Commands}, and
13836 @ref{deffnx,, Def Cmds in Detail}.
13837
13838 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
13839 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
13840 Format a description for a function in a typed language.
13841 The command is equivalent to @samp{@@deftypefn Function @dots{}}.
13842 @xref{Definition Commands},
13843 and @ref{deffnx,, Def Cmds in Detail}.
13844
13845 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
13846 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
13847 Format a description for a typed method in object-oriented programming.
13848 Takes as arguments the name of the class of the method, the return type
13849 of the method, the name of the method, and its arguments, if any.
13850 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13851
13852 @item @@deftypevr @var{classification} @var{data-type} @var{name}
13853 @itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
13854 Format a description for something like a variable in a typed
13855 language---an entity that records a value.  Takes as arguments the
13856 classification of entity being described, the type, and the name of the
13857 entity.  @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
13858 Detail}.
13859
13860 @item @@deftypevar @var{data-type} @var{variable-name}
13861 @itemx @@deftypevarx @var{data-type} @var{variable-name}
13862 Format a description for a variable in a typed language.  The command is
13863 equivalent to @samp{@@deftypevr Variable @dots{}}.  @xref{Definition
13864 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13865
13866 @item @@defun @var{function-name} @var{arguments}@dots{}
13867 @itemx @@defunx @var{function-name} @var{arguments}@dots{}
13868 Format a description for functions.  The command is equivalent to
13869 @samp{@@deffn Function @dots{}}.  @xref{Definition Commands}, and
13870 @ref{deffnx,, Def Cmds in Detail}.
13871
13872 @item @@defvar @var{variable-name}
13873 @itemx @@defvarx @var{variable-name}
13874 Format a description for variables.  The command is equivalent to
13875 @samp{@@defvr Variable @dots{}}.  @xref{Definition Commands}, and
13876 @ref{deffnx,, Def Cmds in Detail}.
13877
13878 @item @@defvr @var{category} @var{name}
13879 @itemx @@defvrx @var{category} @var{name}
13880 Format a description for any kind of variable.  @code{@@defvr} takes
13881 as arguments the category of the entity and the name of the entity.
13882 @xref{Definition Commands},
13883 and @ref{deffnx,, Def Cmds in Detail}.
13884
13885 @item @@detailmenu@{@}
13886 Avoid @code{makeinfo} confusion stemming from the detailed node listing
13887 in a master menu.  @xref{Master Menu Parts}.
13888
13889 @item @@dfn@{@var{term}@}
13890 Highlight the introductory or defining use of a term.
13891 @xref{dfn, , @code{@@dfn}}.@refill
13892
13893 @item @@dircategory @var{dirpart}
13894 Specify a part of the Info directory menu where this file's entry should
13895 go.  @xref{Installing Dir Entries}.
13896
13897 @item @@direntry
13898 Begin the Info directory menu entry for this file.
13899 @xref{Installing Dir Entries}.
13900
13901 @need 100
13902 @item @@display
13903 Begin a kind of example.  Indent text, do not fill, do not select a
13904 new font.  Pair with @code{@@end display}.  @xref{display, ,
13905 @code{@@display}}.@refill
13906
13907 @item @@dmn@{@var{dimension}@}
13908 Format a unit of measure, as in 12@dmn{pt}.  Causes @TeX{} to insert a
13909 thin space before @var{dimension}.  No effect in Info.
13910 @xref{dmn, , @code{@@dmn}}.@refill
13911
13912 @item @@dotaccent@{@var{c}@}
13913 Generate a dot accent over the character @var{c}, as in @dotaccent{oo}.
13914 @xref{Inserting Accents}.
13915
13916 @item @@dots@{@}
13917 Insert an ellipsis: @samp{@dots{}}.
13918 @xref{dots, , @code{@@dots@{@}}}.@refill
13919
13920 @item @@email@{@var{address}[, @var{displayed-text}]@}
13921 Indicate an electronic mail address.
13922 @xref{email, , @code{@@email}}.@refill
13923
13924 @need 100
13925 @item @@emph@{@var{text}@}
13926 Highlight @var{text}; text is displayed in @emph{italics} in printed
13927 output, and surrounded by asterisks in Info.  @xref{Emphasis, ,
13928 Emphasizing Text}.
13929
13930 @item @@end @var{environment}
13931 Ends @var{environment}, as in @samp{@@end example}.  @xref{Formatting
13932 Commands,,@@-commands}.
13933
13934 @item @@enddots@{@}
13935 Generate an end-of-sentence of ellipsis, like this @enddots{}
13936 @xref{dots,,@code{@@dots@{@}}}.
13937
13938 @need 100
13939 @item @@enumerate [@var{number-or-letter}]
13940 Begin a numbered list, using @code{@@item} for each entry.
13941 Optionally, start list with @var{number-or-letter}.  Pair with
13942 @code{@@end enumerate}.  @xref{enumerate, ,
13943 @code{@@enumerate}}.@refill
13944
13945 @need 100
13946 @item @@equiv@{@}
13947 Indicate to the reader the exact equivalence of two forms with a
13948 glyph: @samp{@equiv{}}.  @xref{Equivalence}.@refill
13949
13950 @item @@error@{@}
13951 Indicate to the reader with a glyph that the following text is
13952 an error message: @samp{@error{}}.  @xref{Error Glyph}.@refill
13953
13954 @item  @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
13955 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
13956 Specify page footings resp.@: headings for even-numbered (left-hand)
13957 pages.  Only allowed inside @code{@@iftex}.  @xref{Custom Headings, ,
13958 How to Make Your Own Headings}.@refill
13959
13960 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
13961 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
13962 Specify page footings resp.@: headings for every page.  Not relevant to
13963 Info.  @xref{Custom Headings, , How to Make Your Own Headings}.@refill
13964
13965 @item @@example
13966 Begin an example.  Indent text, do not fill, and select fixed-width font.
13967 Pair with @code{@@end example}.  @xref{example, ,
13968 @code{@@example}}.@refill
13969
13970 @item @@exclamdown@{@}
13971 Produce an upside-down exclamation point.  @xref{Inserting Accents}.
13972
13973 @item @@exdent @var{line-of-text}
13974 Remove any indentation a line might have.  @xref{exdent, ,
13975 Undoing the Indentation of a Line}.@refill
13976
13977 @item @@expansion@{@}
13978 Indicate the result of a macro expansion to the reader with a special
13979 glyph: @samp{@expansion{}}.
13980 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
13981
13982 @item @@file@{@var{filename}@}
13983 Highlight the name of a file, buffer, node, or directory.  @xref{file, ,
13984 @code{@@file}}.@refill
13985
13986 @item @@finalout
13987 Prevent @TeX{} from printing large black warning rectangles beside
13988 over-wide lines.  @xref{Overfull hboxes}.@refill
13989
13990 @need 100
13991 @item @@findex @var{entry}
13992 Add @var{entry} to the index of functions.  @xref{Index Entries, ,
13993 Defining the Entries of an Index}.@refill
13994
13995 @need 200
13996 @item @@flushleft
13997 @itemx @@flushright
13998 Left justify every line but leave the right end ragged.
13999 Leave font as is.  Pair with @code{@@end flushleft}.
14000 @code{@@flushright} analogous.
14001 @xref{flushleft & flushright, , @code{@@flushleft} and
14002 @code{@@flushright}}.@refill
14003
14004 @need 200
14005 @item @@footnote@{@var{text-of-footnote}@}
14006 Enter a footnote.  Footnote text is printed at the bottom of the page
14007 by @TeX{}; Info may format in either `End' node or `Separate' node style.
14008 @xref{Footnotes}.@refill
14009
14010 @item @@footnotestyle @var{style}
14011 Specify an Info file's footnote style, either @samp{end} for the end
14012 node style or @samp{separate} for the separate node style.
14013 @xref{Footnotes}.@refill
14014
14015 @item @@format
14016 Begin a kind of example.  Like @code{@@example} or @code{@@display},
14017 but do not narrow the margins and do not select the fixed-width font.
14018 Pair with @code{@@end format}.  @xref{example, ,
14019 @code{@@example}}.@refill
14020
14021 @item @@ftable @var{formatting-command}
14022 Begin a two-column table, using @code{@@item} for each entry.
14023 Automatically enter each of the items in the first column into the
14024 index of functions.  Pair with @code{@@end ftable}.  The same as
14025 @code{@@table}, except for indexing.  @xref{ftable vtable, ,
14026 @code{@@ftable} and @code{@@vtable}}.@refill
14027
14028 @item @@group
14029 Hold text together that must appear on one printed page.  Pair with
14030 @code{@@end group}.  Not relevant to Info.  @xref{group, ,
14031 @code{@@group}}.@refill
14032
14033 @item @@H@{@var{c}@}
14034 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
14035
14036 @item @@heading @var{title}
14037 Print an unnumbered section-like heading in the text, but not in the
14038 table of contents of a printed manual.  In Info, the title is
14039 underlined with equal signs.  @xref{unnumberedsec appendixsec heading,
14040 , Section Commands}.@refill
14041
14042 @item @@headings @var{on-off-single-double}
14043 Turn page headings on or off, and/or specify single-sided or double-sided
14044 page headings for printing.  @xref{headings on off, , The
14045 @code{@@headings} Command}.
14046
14047 @item @@html
14048 Enter HTML completely.  Pair with @code{@@end html}.  @xref{Raw
14049 Formatter Commands}.
14050
14051 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
14052 Explicitly define hyphenation points.  @xref{- and hyphenation,,
14053 @code{@@-} and @code{@@hyphenation}}.
14054
14055 @item @@i@{@var{text}@}
14056 Print @var{text} in @i{italic} font.  No effect in Info.
14057 @xref{Fonts}.@refill
14058
14059 @item @@ifclear @var{flag}
14060 If @var{flag} is cleared, the Texinfo formatting commands format text
14061 between @code{@@ifclear @var{flag}} and the following @code{@@end
14062 ifclear} command.
14063 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14064
14065 @item @@ifhtml
14066 @itemx @@ifinfo
14067 Begin a stretch of text that will be ignored by @TeX{} when it typesets
14068 the printed manual.  The text appears only in the HTML resp.@: Info
14069 file.  Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
14070 @xref{Conditionals}.
14071
14072 @item @@ifnothtml
14073 @itemx @@ifnotinfo
14074 @itemx @@ifnottex
14075 Begin a stretch of text that will be ignored in one output format but
14076 not the others.  The text appears only in the format not specified.
14077 Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
14078 @code{@@end ifnotinfo}.  @xref{Conditionals}.
14079
14080 @item @@ifset @var{flag}
14081 If @var{flag} is set, the Texinfo formatting commands format text
14082 between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
14083 command.
14084 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14085
14086 @item @@iftex
14087 Begin a stretch of text that will not appear in the Info file, but
14088 will be processed only by @TeX{}.  Pair with @code{@@end iftex}.
14089 @xref{Conditionals, , Conditionally Visible Text}.@refill
14090
14091 @item @@ignore
14092 Begin a stretch of text that will not appear in either the Info file
14093 or the printed output.  Pair with @code{@@end ignore}.
14094 @xref{Comments, , Comments and Ignored Text}.@refill
14095
14096 @item @@image@{@var{filename}, [@var{width}], [@var{height}]@}
14097 Include graphics image in external @var{filename} scaled to the given
14098 @var{width} and/or @var{height}.  @xref{Images}.
14099
14100 @item @@include @var{filename}
14101 Incorporate the contents of the file @var{filename} into the Info file
14102 or printed document.  @xref{Include Files}.@refill
14103
14104 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
14105 Make a cross reference to an Info file for which there is no printed
14106 manual.  @xref{inforef, , Cross references using
14107 @code{@@inforef}}.@refill
14108
14109 @item \input @var{macro-definitions-file}
14110 Use the specified macro definitions file.  This command is used only
14111 in the first line of a Texinfo file to cause @TeX{} to make use of the
14112 @file{texinfo} macro definitions file.  The backslash in @code{\input}
14113 is used instead of an @code{@@} because @TeX{} does not
14114 recognize @code{@@} until after it has read the definitions file.
14115 @xref{Header, , The Texinfo File Header}.@refill
14116
14117 @item @@item
14118 Indicate the beginning of a marked paragraph for @code{@@itemize} and
14119 @code{@@enumerate}; indicate the beginning of the text of a first column
14120 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
14121 @xref{Lists and Tables}.@refill
14122
14123 @item @@itemize  @var{mark-generating-character-or-command}
14124 Produce a sequence of indented paragraphs, with a mark inside the left
14125 margin at the beginning of each paragraph.  Pair with @code{@@end
14126 itemize}.  @xref{itemize, , @code{@@itemize}}.@refill
14127
14128 @item @@itemx
14129 Like @code{@@item} but do not generate extra vertical space above the
14130 item text.  @xref{itemx, , @code{@@itemx}}.@refill
14131
14132 @item @@kbd@{@var{keyboard-characters}@}
14133 Indicate text that is characters of input to be typed by
14134 users.  @xref{kbd, , @code{@@kbd}}.@refill
14135
14136 @item @@kbdinputstyle @var{style}
14137 Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
14138 @xref{kbd, , @code{@@kbd}}.@refill
14139
14140 @item @@key@{@var{key-name}@}
14141 Indicate a name for a key on a keyboard.
14142 @xref{key, , @code{@@key}}.@refill
14143
14144 @item @@kindex @var{entry}
14145 Add @var{entry} to the index of keys.
14146 @xref{Index Entries, , Defining the Entries of an Index}.@refill
14147
14148 @item @@L@{@}
14149 @itemx @@l@{@}
14150 Generate the uppercase and lowercase Polish suppressed-L letters,
14151 respectively: @L{}, @l{}.
14152
14153 @c Possibly this can be tossed now that we have macros.  --karl, 16sep96.
14154 @c Yes, let's toss it, it's pretty weird.  --karl, 15jun97.
14155 @c @item @@global@@let@var{new-command}=@var{existing-command}
14156 @c Equate a new highlighting command with an existing one.  Only for
14157 @c @TeX{}.  Write definition inside of @code{@@iftex} @dots{} @code{@@end
14158 @c iftex}.  @xref{Customized Highlighting}.@refill
14159
14160 @item @@lisp
14161 Begin an example of Lisp code.  Indent text, do not fill, and select
14162 fixed-width font.  Pair with @code{@@end lisp}.  @xref{Lisp Example, ,
14163 @code{@@lisp}}.@refill
14164
14165 @item @@lowersections
14166 Change subsequent chapters to sections, sections to subsections, and so
14167 on. @xref{Raise/lower sections, , @code{@@raisesections} and
14168 @code{@@lowersections}}.@refill
14169
14170 @item @@macro @var{macro-name} @{@var{params}@}
14171 Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}.
14172 Only supported by @code{makeinfo} and @code{texi2dvi}.  @xref{Defining
14173 Macros}.
14174
14175 @item @@majorheading @var{title}
14176 Print a chapter-like heading in the text, but not in the table of
14177 contents of a printed manual.  Generate more vertical whitespace before
14178 the heading than the @code{@@chapheading} command.  In Info, the chapter
14179 heading line is underlined with asterisks.  @xref{majorheading &
14180 chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
14181
14182 @item @@math@{@var{mathematical-expression}@}
14183 Format a mathematical expression.
14184 @xref{math, , @code{@@math} - Inserting Mathematical Expressions}.
14185
14186 @item @@menu
14187 Mark the beginning of a menu of nodes in Info.  No effect in a printed
14188 manual.  Pair with @code{@@end menu}.  @xref{Menus}.@refill
14189
14190 @item @@minus@{@}
14191 Generate a minus sign, `@minus{}'.  @xref{minus, , @code{@@minus}}.@refill
14192
14193 @item @@multitable @var{column-width-spec}
14194 Begin a multi-column table.  Pair with @code{@@end multitable}.
14195 @xref{Multitable Column Widths}.
14196
14197 @item @@need @var{n}
14198 Start a new page in a printed manual if fewer than @var{n} mils
14199 (thousandths of an inch) remain on the current page.  @xref{need, ,
14200 @code{@@need}}.@refill
14201
14202 @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
14203 Define the beginning of a new node in Info, and serve as a locator for
14204 references for @TeX{}.  @xref{node, , @code{@@node}}.@refill
14205
14206 @item @@noindent
14207 Prevent text from being indented as if it were a new paragraph.
14208 @xref{noindent, , @code{@@noindent}}.@refill
14209
14210 @item @@O@{@}
14211 @itemx @@o@{@}
14212 Generate the uppercase and lowercase O-with-slash letters, respectively:
14213 @O{}, @o{}.
14214
14215 @item  @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
14216 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
14217 Specify page footings resp.@: headings for odd-numbered (right-hand)
14218 pages.  Only allowed inside @code{@@iftex}.  @xref{Custom Headings, ,
14219 How to Make Your Own Headings}.@refill
14220
14221 @item @@OE@{@}
14222 @itemx @@oe@{@}
14223 Generate the uppercase and lowercase OE ligatures, respectively:
14224 @OE{}, @oe{}.  @xref{Inserting Accents}.
14225
14226 @item @@page
14227 Start a new page in a printed manual.  No effect in Info.
14228 @xref{page, , @code{@@page}}.@refill
14229
14230 @item @@paragraphindent @var{indent}
14231 Indent paragraphs by @var{indent} number of spaces; delete indentation
14232 if the value of @var{indent} is 0; and do not change indentation if
14233 @var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph
14234 Indenting}.@refill
14235
14236 @item @@pindex @var{entry}
14237 Add @var{entry} to the index of programs.  @xref{Index Entries, , Defining
14238 the Entries of an Index}.@refill
14239
14240 @item @@point@{@}
14241 Indicate the position of point in a buffer to the reader with a
14242 glyph: @samp{@point{}}.  @xref{Point Glyph, , Indicating
14243 Point in a Buffer}.@refill
14244
14245 @item @@pounds@{@}
14246 Generate the pounds sterling currency sign.
14247 @xref{pounds,,@code{@@pounds@{@}}}.
14248
14249 @item @@print@{@}
14250 Indicate printed output to the reader with a glyph:
14251 @samp{@print{}}.  @xref{Print Glyph}.@refill
14252
14253 @item @@printindex @var{index-name}
14254 Print an alphabetized two-column index in a printed manual or generate
14255 an alphabetized menu of index entries for Info.  @xref{Printing
14256 Indices & Menus}.@refill
14257
14258 @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14259 Make a reference that starts with a lower case `see' in a printed
14260 manual.  Use within parentheses only.  Do not follow command with a
14261 punctuation mark---the Info formatting commands automatically insert
14262 terminating punctuation as needed.  Only the first argument is mandatory.
14263 @xref{pxref, , @code{@@pxref}}.@refill
14264
14265 @item @@questiondown@{@}
14266 Generate an upside-down question mark.  @xref{Inserting Accents}.
14267
14268 @item @@quotation
14269 Narrow the margins to indicate text that is quoted from another real
14270 or imaginary work.  Write command on a line of its own.  Pair with
14271 @code{@@end quotation}.  @xref{quotation, ,
14272 @code{@@quotation}}.@refill
14273
14274 @need 100
14275 @item @@r@{@var{text}@}
14276 Print @var{text} in @r{roman} font.  No effect in Info.
14277 @xref{Fonts}.@refill
14278
14279 @item @@raisesections
14280 Change subsequent sections to chapters, subsections to sections, and so
14281 on.  @xref{Raise/lower sections, , @code{@@raisesections} and
14282 @code{@@lowersections}}.@refill
14283
14284 @need 300
14285 @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14286 Make a reference.  In a printed manual, the reference does not start
14287 with a `See'.  Follow command with a punctuation mark.  Only the first
14288 argument is mandatory.  @xref{ref, , @code{@@ref}}.@refill
14289
14290 @need 300
14291 @item @@refill
14292 In Info, refill and indent the paragraph after all the other processing
14293 has been done.  No effect on @TeX{}, which always refills.  This command
14294 is no longer needed, since all formatters now automatically refill.
14295 @xref{Refilling Paragraphs}.@refill
14296
14297 @need 300
14298 @item @@result@{@}
14299 Indicate the result of an expression to the reader with a special
14300 glyph: @samp{@result{}}.  @xref{result, , @code{@@result}}.@refill
14301
14302 @item @@ringaccent@{@var{c}@}
14303 Generate a ring accent over the next character, as in @ringaccent{o}.
14304 @xref{Inserting Accents}.
14305
14306 @item @@samp@{@var{text}@}
14307 Highlight @var{text} that is a literal example of a sequence of
14308 characters.  Used for single characters, for statements, and often for
14309 entire shell commands.  @xref{samp, , @code{@@samp}}.@refill
14310
14311 @item @@sc@{@var{text}@}
14312 Set @var{text} in a printed output in @sc{the small caps font} and
14313 set text in the Info file in uppercase letters.
14314 @xref{Smallcaps}.@refill
14315
14316 @item @@section @var{title}
14317 Begin a section within a chapter.  In a printed manual, the section
14318 title is numbered and appears in the table of contents.  In Info, the
14319 title is underlined with equal signs.  @xref{section, ,
14320 @code{@@section}}.@refill
14321
14322 @item @@set @var{flag} [@var{string}]
14323 Make @var{flag} active, causing the Texinfo formatting commands to
14324 format text between subsequent pairs of @code{@@ifset @var{flag}} and
14325 @code{@@end ifset} commands.  Optionally, set value of @var{flag} to
14326 @var{string}.
14327 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14328
14329 @item @@setchapternewpage @var{on-off-odd}
14330 Specify whether chapters start on new pages, and if so, whether on
14331 odd-numbered (right-hand) new pages.  @xref{setchapternewpage, ,
14332 @code{@@setchapternewpage}}.@refill
14333
14334 @item @@setfilename @var{info-file-name}
14335 Provide a name to be used by the Info file.  This command is essential
14336 for @TeX{} formatting as well, even though it produces no output.
14337 @xref{setfilename, , @code{@@setfilename}}.@refill
14338
14339 @item @@settitle @var{title}
14340 Provide a title for page headers in a printed manual.
14341 @xref{settitle, , @code{@@settitle}}.@refill
14342
14343 @item @@shortcontents
14344 Print a short table of contents.  Not relevant to Info, which uses
14345 menus rather than tables of contents.  A synonym for
14346 @code{@@summarycontents}.  @xref{Contents, , Generating a Table of
14347 Contents}.@refill
14348
14349 @item @@shorttitlepage@{@var{title}@}
14350 Generate a minimal title page.  @xref{titlepage,,@code{@@titlepage}}.
14351
14352 @need 400
14353 @item @@smallbook
14354 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
14355 rather than the regular 8.5 by 11 inch format.  @xref{smallbook, ,
14356 Printing Small Books}.  Also, see @ref{smallexample & smalllisp, ,
14357 @code{@@smallexample} and @code{@@smalllisp}}.@refill
14358
14359 @need 400
14360 @item @@smallexample
14361 Indent text to indicate an example.  Do not fill, select fixed-width
14362 font.  In @code{@@smallbook} format, print text in a smaller font than
14363 with @code{@@example}.  Pair with @code{@@end smallexample}.
14364 @xref{smallexample & smalllisp, , @code{@@smallexample} and
14365 @code{@@smalllisp}}.@refill
14366
14367 @need 400
14368 @item @@smalllisp
14369 Begin an example of Lisp code.  Indent text, do not fill, select
14370 fixed-width font.  In @code{@@smallbook} format, print text in a
14371 smaller font.  Pair with @code{@@end smalllisp}.  @xref{smallexample &
14372 smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill
14373
14374 @need 700
14375 @item @@sp @var{n}
14376 Skip @var{n} blank lines.  @xref{sp, , @code{@@sp}}.@refill
14377
14378 @item @@ss@{@}
14379 Generate the German sharp-S es-zet letter, @ss{}.  @xref{Inserting Accents}.
14380
14381 @need 700
14382 @item @@strong @var{text}
14383 Emphasize @var{text} by typesetting it in a @strong{bold} font for the
14384 printed manual and by surrounding it with asterisks for Info.
14385 @xref{emph & strong, , Emphasizing Text}.@refill
14386
14387 @item @@subheading @var{title}
14388 Print an unnumbered subsection-like heading in the text, but not in
14389 the table of contents of a printed manual.  In Info, the title is
14390 underlined with hyphens.  @xref{unnumberedsubsec appendixsubsec
14391 subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
14392 @code{@@subheading}}.@refill
14393
14394 @item @@subsection @var{title}
14395 Begin a subsection within a section.  In a printed manual, the
14396 subsection title is numbered and appears in the table of contents.  In
14397 Info, the title is underlined with hyphens.  @xref{subsection, ,
14398 @code{@@subsection}}.@refill
14399
14400 @item @@subsubheading @var{title}
14401 Print an unnumbered subsubsection-like heading in the text, but not in
14402 the table of contents of a printed manual.  In Info, the title is
14403 underlined with periods.  @xref{subsubsection, , The `subsub'
14404 Commands}.@refill
14405
14406 @item @@subsubsection @var{title}
14407 Begin a subsubsection within a subsection.  In a printed manual,
14408 the subsubsection title is numbered and appears in the table of
14409 contents.  In Info, the title is underlined with periods.
14410 @xref{subsubsection, , The `subsub' Commands}.@refill
14411
14412 @item @@subtitle @var{title}
14413 In a printed manual, set a subtitle in a normal sized font flush to
14414 the right-hand side of the page.  Not relevant to Info, which does not
14415 have title pages.  @xref{title subtitle author, , @code{@@title}
14416 @code{@@subtitle} and @code{@@author} Commands}.@refill
14417
14418 @item @@summarycontents
14419 Print a short table of contents.  Not relevant to Info, which uses
14420 menus rather than tables of contents.  A synonym for
14421 @code{@@shortcontents}.  @xref{Contents, , Generating a Table of
14422 Contents}.@refill
14423
14424 @need 300
14425 @item @@syncodeindex @var{from-index} @var{into-index}
14426 Merge the index named in the first argument into the index named in
14427 the second argument, printing the entries from the first index in
14428 @code{@@code} font.  @xref{Combining Indices}.@refill
14429
14430 @need 300
14431 @item @@synindex @var{from-index} @var{into-index}
14432 Merge the index named in the first argument into the index named in
14433 the second argument.  Do not change the font of @var{from-index}
14434 entries.  @xref{Combining Indices}.@refill
14435
14436 @need 100
14437 @item @@t@{@var{text}@}
14438 Print @var{text} in a @t{fixed-width}, typewriter-like font.
14439 No effect in Info.  @xref{Fonts}.@refill
14440
14441 @item @@tab
14442 Separate columns in a multitable.  @xref{Multitable Rows}.
14443
14444 @need 400
14445 @item @@table @var{formatting-command}
14446 Begin a two-column table, using @code{@@item} for each entry.  Write
14447 each first column entry on the same line as @code{@@item}.  First
14448 column entries are printed in the font resulting from
14449 @var{formatting-command}.  Pair with @code{@@end table}.
14450 @xref{Two-column Tables, , Making a Two-column Table}.
14451 Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
14452 and @ref{itemx, , @code{@@itemx}}.@refill
14453
14454 @item @@TeX@{@}
14455 Insert the logo @TeX{}.  @xref{TeX and copyright, , Inserting @TeX{}
14456 and @copyright{}}.@refill
14457
14458 @item @@tex
14459 Enter @TeX{} completely.  Pair with @code{@@end tex}.  @xref{Raw
14460 Formatter Commands}.
14461
14462 @item @@thischapter
14463 @itemx @@thischaptername
14464 @itemx @@thisfile
14465 @itemx @@thispage
14466 @itemx @@thistitle
14467 Only allowed in a heading or footing.  Stands for the number and name of
14468 the current chapter (in the format `Chapter 1: Title'), the chapter name
14469 only, the filename, the current page number, and the title of the
14470 document, respectively.  @xref{Custom Headings, , How to Make Your Own
14471 Headings}.@refill
14472
14473 @item @@tieaccent@{@var{cc}@}
14474 Generate a tie-after accent over the next two characters @var{cc}, as in
14475 `@tieaccent{oo}'.  @xref{Inserting Accents}.
14476
14477 @item @@tindex @var{entry}
14478 Add @var{entry} to the index of data types.  @xref{Index Entries, ,
14479 Defining the Entries of an Index}.@refill
14480
14481 @item @@title @var{title}
14482 In a printed manual, set a title flush to the left-hand side of the
14483 page in a larger than normal font and underline it with a black rule.
14484 Not relevant to Info, which does not have title pages.  @xref{title
14485 subtitle author, , The @code{@@title} @code{@@subtitle} and
14486 @code{@@author} Commands}.@refill
14487
14488 @need 400
14489 @item @@titlefont@{@var{text}@}
14490 In a printed manual, print @var{text} in a larger than normal font.
14491 Not relevant to Info, which does not have title pages.
14492 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
14493 and @code{@@sp} Commands}.@refill
14494
14495 @need 300
14496 @item @@titlepage
14497 Indicate to Texinfo the beginning of the title page.  Write command on
14498 a line of its own.  Pair with @code{@@end titlepage}.  Nothing between
14499 @code{@@titlepage} and @code{@@end titlepage} appears in Info.
14500 @xref{titlepage, , @code{@@titlepage}}.@refill
14501
14502 @need 150
14503 @item @@today@{@}
14504 Insert the current date, in `1 Jan 1900' style.  @xref{Custom
14505 Headings, , How to Make Your Own Headings}.@refill
14506
14507 @item @@top @var{title}
14508 In a Texinfo file to be formatted with @code{makeinfo}, identify the
14509 topmost @code{@@node} line in the file, which must be written on the line
14510 immediately preceding the @code{@@top} command.  Used for
14511 @code{makeinfo}'s node pointer insertion feature.  The title is
14512 underlined with asterisks.  Both the @code{@@node} line and the @code{@@top}
14513 line normally should be enclosed by @code{@@ifinfo} and @code{@@end
14514 ifinfo}.  In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
14515 command is merely a synonym for @code{@@unnumbered}.  @xref{makeinfo
14516 Pointer Creation, , Creating Pointers with @code{makeinfo}}.
14517
14518 @item @@u@{@var{c}@}
14519 @itemx @@ubaraccent@{@var{c}@}
14520 @itemx @@udotaccent@{@var{c}@}
14521 Generate a breve, underbar, or underdot accent, respectively, over or
14522 under the character @var{c}, as in @u{o}, @ubaraccent{o},
14523 @udotaccent{o}.  @xref{Inserting Accents}.
14524
14525 @item @@unnumbered @var{title}
14526 In a printed manual, begin a chapter that appears without chapter
14527 numbers of any kind.  The title appears in the table of contents of a
14528 printed manual.  In Info, the title is underlined with asterisks.
14529 @xref{unnumbered & appendix, , @code{@@unnumbered} and
14530 @code{@@appendix}}.@refill
14531
14532 @item @@unnumberedsec @var{title}
14533 In a printed manual, begin a section that appears without section
14534 numbers of any kind.  The title appears in the table of contents of a
14535 printed manual.  In Info, the title is underlined with equal signs.
14536 @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
14537
14538 @item @@unnumberedsubsec @var{title}
14539 In a printed manual, begin an unnumbered subsection within a
14540 chapter.  The title appears in the table of contents of a printed
14541 manual.  In Info, the title is underlined with hyphens.
14542 @xref{unnumberedsubsec appendixsubsec subheading, ,
14543 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
14544 @code{@@subheading}}.@refill
14545
14546 @item @@unnumberedsubsubsec @var{title}
14547 In a printed manual, begin an unnumbered subsubsection within a
14548 chapter.  The title appears in the table of contents of a printed
14549 manual.  In Info, the title is underlined with periods.
14550 @xref{subsubsection, , The `subsub' Commands}.@refill
14551
14552 @item @@uref@{@var{url}[, @var{displayed-text}@}
14553 Define a cross reference to an external uniform resource locator for the
14554 World Wide Web.  @xref{url, , @code{@@url}}.@refill
14555
14556 @item @@url@{@var{url}@}
14557 Indicate text that is a uniform resource locator for the World Wide
14558 Web.  @xref{url, , @code{@@url}}.@refill
14559
14560 @item @@v@{@var{c}@}
14561 Generate check accent over the character @var{c}, as in @v{o}.
14562 @xref{Inserting Accents}.
14563
14564 @item @@value@{@var{flag}@}
14565 Replace @var{flag} with the value to which it is set by @code{@@set
14566 @var{flag}}.
14567 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14568
14569 @item @@var@{@var{metasyntactic-variable}@}
14570 Highlight a metasyntactic variable, which is something that stands for
14571 another piece of text.  @xref{var, , Indicating Metasyntactic
14572 Variables}.@refill
14573
14574 @need 400
14575 @item @@vindex @var{entry}
14576 Add @var{entry} to the index of variables.  @xref{Index Entries, ,
14577 Defining the Entries of an Index}.@refill
14578
14579 @need 400
14580 @item @@vskip @var{amount}
14581 In a printed manual, insert whitespace so as to push text on the
14582 remainder of the page towards the bottom of the page.  Used in
14583 formatting the copyright page with the argument @samp{0pt plus
14584 1filll}.  (Note spelling of @samp{filll}.)  @code{@@vskip} may be used
14585 only in contexts ignored for Info.  @xref{Copyright & Permissions, ,
14586 The Copyright Page and Printed Permissions}.@refill
14587
14588 @need 400
14589 @item @@vtable @var{formatting-command}
14590 Begin a two-column table, using @code{@@item} for each entry.
14591 Automatically enter each of the items in the first column into the
14592 index of variables.  Pair with @code{@@end vtable}.  The same as
14593 @code{@@table}, except for indexing.  @xref{ftable vtable, ,
14594 @code{@@ftable} and @code{@@vtable}}.@refill
14595
14596 @need 400
14597 @item @@w@{@var{text}@}
14598 Prevent @var{text} from being split across two lines.  Do not end a
14599 paragraph that uses @code{@@w} with an @code{@@refill} command.
14600 @xref{w, , @code{@@w}}.@refill
14601
14602 @need 400
14603 @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14604 Make a reference that starts with `See' in a printed manual.  Follow
14605 command with a punctuation mark.  Only the first argument is
14606 mandatory.  @xref{xref, , @code{@@xref}}.@refill
14607 @end table
14608
14609
14610 @node Tips, Sample Texinfo File, Command List, Top
14611 @appendix Tips and Hints
14612
14613 Here are some tips for writing Texinfo documentation:@refill
14614
14615 @cindex Tips
14616 @cindex Usage tips
14617 @cindex Hints
14618 @itemize @bullet
14619 @item
14620 Write in the present tense, not in the past or the future.
14621
14622 @item
14623 Write actively!  For example, write ``We recommend that @dots{}'' rather
14624 than ``It is recommended that @dots{}''.
14625
14626 @item
14627 Use 70 or 72 as your fill column.  Longer lines are hard to read.
14628
14629 @item
14630 Include a copyright notice and copying permissions.
14631 @end itemize
14632
14633 @subsubheading Index, Index, Index!
14634
14635 Write many index entries, in different ways.
14636 Readers like indices; they are helpful and convenient.
14637
14638 Although it is easiest to write index entries as you write the body of
14639 the text, some people prefer to write entries afterwards.  In either
14640 case, write an entry before the paragraph to which it applies.  This
14641 way, an index entry points to the first page of a paragraph that is
14642 split across pages.
14643
14644 Here are more hints we have found valuable:
14645
14646 @itemize @bullet
14647 @item
14648 Write each index entry differently, so each entry refers to a different
14649 place in the document.
14650
14651 @item
14652 Write index entries only where a topic is discussed significantly.  For
14653 example, it is not useful to index ``debugging information'' in a
14654 chapter on reporting bugs.  Someone who wants to know about debugging
14655 information will certainly not find it in that chapter.
14656
14657 @item
14658 Consistently capitalize the first word of every concept index entry,
14659 or else consistently use lower case.  Terse entries often call for
14660 lower case; longer entries for capitalization.  Whichever case
14661 convention you use, please use one or the other consistently!  Mixing
14662 the two styles looks bad.
14663
14664 @item
14665 Always capitalize or use upper case for those words in an index for
14666 which this is proper, such as names of countries or acronyms.  Always
14667 use the appropriate case for case-sensitive names, such as those in C or
14668 Lisp.
14669
14670 @item
14671 Write the indexing commands that refer to a whole section immediately
14672 after the section command, and write the indexing commands that refer to
14673 the paragraph before the paragraph.
14674
14675 @need 1000
14676 In the example that follows, a blank line comes after the index
14677 entry for ``Leaping'':
14678
14679 @example
14680 @group
14681 @@section The Dog and the Fox
14682 @@cindex Jumping, in general
14683 @@cindex Leaping
14684
14685 @@cindex Dog, lazy, jumped over
14686 @@cindex Lazy dog jumped over
14687 @@cindex Fox, jumps over dog
14688 @@cindex Quick fox jumps over dog
14689 The quick brown fox jumps over the lazy dog.
14690 @end group
14691 @end example
14692
14693 @noindent
14694 (Note that the example shows entries for the same concept that are
14695 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
14696 readers can look up the concept in different ways.)
14697 @end itemize
14698
14699 @subsubheading Blank Lines
14700
14701 @itemize @bullet
14702 @item
14703 Insert a blank line between a sectioning command and the first following
14704 sentence or paragraph, or between the indexing commands associated with
14705 the sectioning command and the first following sentence or paragraph, as
14706 shown in the tip on indexing.  Otherwise, a formatter may fold title and
14707 paragraph together.
14708
14709 @item
14710 Always insert a blank line before an @code{@@table} command and after an
14711 @code{@@end table} command; but never insert a blank line after an
14712 @code{@@table} command or before an @code{@@end table} command.
14713
14714 @need 1000
14715 For example,
14716
14717 @example
14718 @group
14719 Types of fox:
14720
14721 @@table @@samp
14722 @@item Quick
14723 Jump over lazy dogs.
14724 @end group
14725
14726 @group
14727 @@item Brown
14728 Also jump over lazy dogs.
14729 @@end table
14730
14731 @end group
14732 @group
14733 @@noindent
14734 On the other hand, @dots{}
14735 @end group
14736 @end example
14737
14738 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
14739 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
14740 same way.
14741 @end itemize
14742
14743 @subsubheading Complete Phrases
14744
14745 Complete phrases are easier to read than @dots{}
14746
14747 @itemize @bullet
14748 @item
14749 Write entries in an itemized list as complete sentences; or at least, as
14750 complete phrases.  Incomplete expressions @dots{} awkward @dots{} like
14751 this.
14752
14753 @item
14754 Write the prefatory sentence or phrase for a multi-item list or table as
14755 a complete expression.  Do not write ``You can set:''; instead, write
14756 ``You can set these variables:''.  The former expression sounds cut off.
14757 @end itemize
14758
14759 @subsubheading Editions, Dates and Versions
14760
14761 Write the edition and version numbers and date in three places in every
14762 manual:
14763
14764 @enumerate
14765 @item
14766 In the first @code{@@ifinfo} section, for people reading the Texinfo file.
14767
14768 @item
14769 In the @code{@@titlepage} section, for people reading the printed manual.
14770
14771 @item
14772 In the `Top' node, for people reading the Info file.
14773 @end enumerate
14774
14775 @noindent
14776 Also, it helps to write a note before the first @code{@@ifinfo}
14777 section to explain what you are doing.
14778
14779 @need 800
14780 @noindent
14781 For example:
14782
14783 @example
14784 @group
14785 @@c ===> NOTE! <==
14786 @@c Specify the edition and version numbers and date
14787 @@c in *three* places:
14788 @@c   1. First ifinfo section  2. title page  3. top node
14789 @@c To find the locations, search for !!set
14790 @end group
14791
14792 @group
14793 @@ifinfo
14794 @@c !!set edition, date, version
14795 This is Edition 4.03, January 1992,
14796 of the @@cite@{GDB Manual@} for GDB Version 4.3.
14797 @dots{}
14798 @end group
14799 @end example
14800
14801 @noindent
14802 ---or use @code{@@set} and @code{@@value}
14803 (@pxref{value Example, , @code{@@value} Example}).
14804
14805 @subsubheading Definition Commands
14806
14807 Definition commands are @code{@@deffn}, @code{@@defun},
14808 @code{@@defmac}, and the like, and enable you to write descriptions in
14809 a uniform format.@refill
14810
14811 @itemize @bullet
14812 @item
14813 Write just one definition command for each entity you define with a
14814 definition command.  The automatic indexing feature creates an index
14815 entry that leads the reader to the definition.
14816
14817 @item
14818 Use @code{@@table} @dots{} @code{@@end table} in an appendix that
14819 contains a summary of functions, not @code{@@deffn} or other definition
14820 commands.
14821 @end itemize
14822
14823 @subsubheading Capitalization
14824
14825 @itemize @bullet
14826 @item
14827 Capitalize ``Texinfo''; it is a name.  Do not write the @samp{x} or
14828 @samp{i} in upper case.
14829
14830 @item
14831 Capitalize ``Info''; it is a name.
14832
14833 @item
14834 Write @TeX{} using the @code{@@TeX@{@}} command.  Note the uppercase
14835 @samp{T} and @samp{X}.  This command causes the formatters to
14836 typeset the name according to the wishes of Donald Knuth, who wrote
14837 @TeX{}.
14838 @end itemize
14839
14840 @subsubheading Spaces
14841
14842 Do not use spaces to format a Texinfo file, except inside of
14843 @code{@@example} @dots{} @code{@@end example} and similar commands.
14844
14845 @need 700
14846 For example, @TeX{} fills the following:
14847
14848 @example
14849 @group
14850     @@kbd@{C-x v@}
14851     @@kbd@{M-x vc-next-action@}
14852        Perform the next logical operation
14853        on the version-controlled file
14854        corresponding to the current buffer.
14855 @end group
14856 @end example
14857
14858 @need 950
14859 @noindent
14860 so it looks like this:
14861
14862 @iftex
14863 @quotation
14864     @kbd{C-x v}
14865     @kbd{M-x vc-next-action}
14866        Perform the next logical operation on the version-controlled file
14867        corresponding to the current buffer.
14868 @end quotation
14869 @end iftex
14870 @ifinfo
14871 @quotation
14872 `C-x v' `M-x vc-next-action' Perform the next logical operation on the
14873 version-controlled file corresponding to the current buffer.
14874 @end quotation
14875 @end ifinfo
14876
14877 @noindent
14878 In this case, the text should be formatted with
14879 @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
14880
14881 @subsubheading @@code, @@samp, @@var, and @samp{---}
14882
14883 @itemize @bullet
14884 @item
14885 Use @code{@@code} around Lisp symbols, including command names.
14886 For example,
14887
14888 @example
14889 The main function is @@code@{vc-next-action@}, @dots{}
14890 @end example
14891
14892 @item
14893 Avoid putting letters such as @samp{s} immediately after an
14894 @samp{@@code}.  Such letters look bad.
14895
14896 @item
14897 Use @code{@@var} around meta-variables.  Do not write angle brackets
14898 around them.
14899
14900 @item
14901 Use three hyphens in a row, @samp{---}, to indicate a long dash.  @TeX{}
14902 typesets these as a long dash and the Info formatters reduce three
14903 hyphens to two.
14904 @end itemize
14905
14906 @subsubheading Periods Outside of Quotes
14907
14908 Place periods and other punctuation marks @emph{outside} of quotations,
14909 unless the punctuation is part of the quotation.  This practice goes
14910 against publishing conventions in the United States, but enables the
14911 reader to distinguish between the contents of the quotation and the
14912 whole passage.
14913
14914 For example, you should write the following sentence with the period
14915 outside the end quotation marks:
14916
14917 @example
14918 Evidently, @samp{au} is an abbreviation for ``author''.
14919 @end example
14920
14921 @noindent
14922 since @samp{au} does @emph{not} serve as an abbreviation for
14923 @samp{author.} (with a period following the word).
14924
14925 @subsubheading Introducing New Terms
14926
14927 @itemize @bullet
14928 @item
14929 Introduce new terms so that a reader who does not know them can
14930 understand them from context; or write a definition for the term.
14931
14932 For example, in the following, the terms ``check in'', ``register'' and
14933 ``delta'' are all appearing for the first time; the example sentence should be
14934 rewritten so they are understandable.
14935
14936 @quotation
14937 The major function assists you in checking in a file to your
14938 version control system and registering successive sets of changes to
14939 it as deltas.
14940 @end quotation
14941
14942 @item
14943 Use the @code{@@dfn} command around a word being introduced, to indicate
14944 that the reader should not expect to know the meaning already, and
14945 should expect to learn the meaning from this passage.
14946 @end itemize
14947
14948 @subsubheading @@pxref
14949
14950 @c !!! maybe include this in the tips on pxref
14951 @ignore
14952 By the way, it is okay to use pxref with something else in front of
14953 it within the parens, as long as the pxref is followed by the close
14954 paren, and the material inside the parens is not part of a larger
14955 sentence.  Also, you can use xref inside parens as part of a complete
14956 sentence so long as you terminate the cross reference with punctuation.
14957 @end ignore
14958 Absolutely never use @code{@@pxref} except in the special context for
14959 which it is designed: inside parentheses, with the closing parenthesis
14960 following immediately after the closing brace.  One formatter
14961 automatically inserts closing punctuation and the other does not.  This
14962 means that the output looks right both in printed output and in an Info
14963 file, but only when the command is used inside parentheses.
14964
14965 @subsubheading Invoking from a Shell
14966
14967 You can invoke programs such as Emacs, GCC, and @code{gawk} from a
14968 shell.  The documentation for each program should contain a section that
14969 describes this.  Unfortunately, if the node names and titles for these
14970 sections are all different, readers find it hard to search for the
14971 section.@refill
14972
14973 Name such sections with a phrase beginning with the word
14974 @w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way
14975 users can find the section easily.
14976
14977 @subsubheading ANSI C Syntax
14978
14979 When you use @code{@@example} to describe a C function's calling
14980 conventions, use the ANSI C syntax, like this:@refill
14981
14982 @example
14983 void dld_init (char *@@var@{path@});
14984 @end example
14985
14986 @noindent
14987 And in the subsequent discussion, refer to the argument values by
14988 writing the same argument names, again highlighted with
14989 @code{@@var}.@refill
14990
14991 @need 800
14992 Avoid the obsolete style that looks like this:@refill
14993
14994 @example
14995 #include <dld.h>
14996
14997 dld_init (path)
14998 char *path;
14999 @end example
15000
15001 Also, it is best to avoid writing @code{#include} above the
15002 declaration just to indicate that the function is declared in a
15003 header file.  The practice may give the misimpression that the
15004 @code{#include} belongs near the declaration of the function.  Either
15005 state explicitly which header file holds the declaration or, better
15006 yet, name the header file used for a group of functions at the
15007 beginning of the section that describes the functions.@refill
15008
15009 @subsubheading Bad Examples
15010
15011 Here are several examples of bad writing to avoid:
15012
15013 In this example, say, `` @dots{} you must @code{@@dfn}@{check
15014 in@} the new version.''  That flows better.
15015
15016 @quotation
15017 When you are done editing the file, you must perform a
15018 @code{@@dfn}@{check in@}.
15019 @end quotation
15020
15021 In the following example, say, ``@dots{} makes a unified interface such as VC
15022 mode possible.''
15023
15024 @quotation
15025 SCCS, RCS and other version-control systems all perform similar
15026 functions in broadly similar ways (it is this resemblance which makes
15027 a unified control mode like this possible).
15028 @end quotation
15029
15030 And in this example, you should specify what `it' refers to:
15031
15032 @quotation
15033 If you are working with other people, it assists in coordinating
15034 everyone's changes so they do not step on each other.
15035 @end quotation
15036
15037 @subsubheading And Finally @dots{}
15038
15039 @itemize @bullet
15040 @item
15041 Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
15042 sound in the name `Bach'.  But pronounce Texinfo as in `speck':
15043 ``teckinfo''.
15044
15045 @item
15046 Write notes for yourself at the very end of a Texinfo file after the
15047 @code{@@bye}.  None of the formatters process text after the
15048 @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
15049 @code{@@end ignore}.
15050 @end itemize
15051
15052
15053 @node Sample Texinfo File, Sample Permissions, Tips, Top
15054 @appendix A Sample Texinfo File
15055 @cindex Sample Texinfo file, no comments
15056
15057 Here is a complete, short sample Texinfo file, without any commentary.
15058 You can see this file, with comments, in the first chapter.
15059 @xref{Short Sample, , A Short Sample Texinfo File}.
15060
15061 @sp 1
15062 @example
15063 \input texinfo   @@c -*-texinfo-*-
15064 @@c %**start of header
15065 @@setfilename sample.info
15066 @@settitle Sample Document
15067 @@c %**end of header
15068
15069 @@setchapternewpage odd
15070
15071 @@ifinfo
15072 This is a short example of a complete Texinfo file.
15073
15074 Copyright 1990 Free Software Foundation, Inc.
15075 @@end ifinfo
15076
15077 @@titlepage
15078 @@sp 10
15079 @@comment The title is printed in a large font.
15080 @@center @@titlefont@{Sample Title@}
15081
15082 @@c The following two commands start the copyright page.
15083 @@page
15084 @@vskip 0pt plus 1filll
15085 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
15086 @@end titlepage
15087
15088 @@node    Top,       First Chapter,         , (dir)
15089 @@comment node-name, next,          previous, up
15090
15091 @@menu
15092 * First Chapter::    The first chapter is the
15093                      only chapter in this sample.
15094 * Concept Index::    This index has two entries.
15095 @@end menu
15096
15097 @@node    First Chapter, Concept Index, Top,      Top
15098 @@comment node-name,     next,          previous, up
15099 @@chapter First Chapter
15100 @@cindex Sample index entry
15101
15102 This is the contents of the first chapter.
15103 @@cindex Another sample index entry
15104
15105 Here is a numbered list.
15106
15107 @@enumerate
15108 @@item
15109 This is the first item.
15110
15111 @@item
15112 This is the second item.
15113 @@end enumerate
15114
15115 The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
15116 commands transform a Texinfo file such as this into
15117 an Info file; and @@TeX@{@} typesets it for a printed
15118 manual.
15119
15120 @@node    Concept Index,    ,  First Chapter, Top
15121 @@comment node-name,    next,  previous,      up
15122 @@unnumbered Concept Index
15123
15124 @@printindex cp
15125
15126 @@contents
15127 @@bye
15128 @end example
15129
15130
15131 @node Sample Permissions, Include Files, Sample Texinfo File, Top
15132 @appendix Sample Permissions
15133 @cindex Permissions
15134 @cindex Copying permissions
15135
15136 Texinfo files should contain sections that tell the readers that they
15137 have the right to copy and distribute the Texinfo file, the Info file,
15138 and the printed manual.@refill
15139
15140 Also, if you are writing a manual about software, you should explain
15141 that the software is free and either include the GNU General Public
15142 License (GPL) or provide a reference to it.  @xref{Distrib, ,
15143 Distribution, xemacs, XEmacs User's Manual}, for an example of the text
15144 that could be used in the software ``Distribution'', ``General Public
15145 License'', and ``NO WARRANTY'' sections of a document.  @xref{Copying,
15146 , Texinfo Copying Conditions}, for an example of a brief explanation
15147 of how the copying conditions provide you with rights. @refill
15148
15149 @menu
15150 * Inserting Permissions::       How to put permissions in your document.
15151 * ifinfo Permissions::          Sample @samp{ifinfo} copying permissions.
15152 * Titlepage Permissions::       Sample Titlepage copying permissions.
15153 @end menu
15154
15155 @node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions
15156 @ifinfo
15157 @appendixsec Inserting Permissions
15158 @end ifinfo
15159
15160 In a Texinfo file, the first @code{@@ifinfo} section usually begins
15161 with a line that says what the file documents.  This is what a person
15162 reading the unprocessed Texinfo file or using the advanced Info
15163 command @kbd{g *} sees first.  @inforef{Expert, Advanced Info
15164 commands, info}, for more information. (A reader using the regular
15165 Info commands usually starts reading at the first node and skips
15166 this first section, which is not in a node.)@refill
15167
15168 In the @code{@@ifinfo} section, the summary sentence is followed by a
15169 copyright notice and then by the copying permission notice.  One of
15170 the copying permission paragraphs is enclosed in @code{@@ignore} and
15171 @code{@@end ignore} commands.  This paragraph states that the Texinfo
15172 file can be processed through @TeX{} and printed, provided the printed
15173 manual carries the proper copying permission notice.  This paragraph
15174 is not made part of the Info file since it is not relevant to the Info
15175 file; but it is a mandatory part of the Texinfo file since it permits
15176 people to process the Texinfo file in @TeX{} and print the
15177 results.@refill
15178
15179 In the printed manual, the Free Software Foundation copying permission
15180 notice follows the copyright notice and publishing information and is
15181 located within the region delineated by the @code{@@titlepage} and
15182 @code{@@end titlepage} commands.  The copying permission notice is exactly
15183 the same as the notice in the @code{@@ifinfo} section except that the
15184 paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
15185 not part of the notice.@refill
15186
15187 To make it simple to insert a permission notice into each section of
15188 the Texinfo file, sample permission notices for each section are
15189 reproduced in full below.@refill
15190
15191 Note that you may need to specify the correct name of a section
15192 mentioned in the permission notice.  For example, in @cite{The GDB
15193 Manual}, the name of the section referring to the General Public
15194 License is called the ``GDB General Public License'', but in the
15195 sample shown below, that section is referred to generically as the
15196 ``GNU General Public License''.  If the Texinfo file does not carry a
15197 copy of the General Public License, leave out the reference to it, but
15198 be sure to include the rest of the sentence.@refill
15199
15200 @node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions
15201 @comment  node-name,  next,  previous,  up
15202 @appendixsec @samp{ifinfo} Copying Permissions
15203 @cindex @samp{ifinfo} permissions
15204
15205 In the @code{@@ifinfo} section of a Texinfo file, the standard Free
15206 Software Foundation permission notice reads as follows:@refill
15207
15208 @example
15209 This file documents @dots{}
15210
15211 Copyright 1998 Free Software Foundation, Inc.
15212
15213 Permission is granted to make and distribute verbatim
15214 copies of this manual provided the copyright notice and
15215 this permission notice are preserved on all copies.
15216
15217 @@ignore
15218 Permission is granted to process this file through TeX
15219 and print the results, provided the printed document
15220 carries a copying permission notice identical to this
15221 one except for the removal of this paragraph (this
15222 paragraph not being relevant to the printed manual).
15223
15224 @@end ignore
15225 Permission is granted to copy and distribute modified
15226 versions of this manual under the conditions for
15227 verbatim copying, provided also that the sections
15228 entitled ``Copying'' and ``GNU General Public License''
15229 are included exactly as in the original, and provided
15230 that the entire resulting derived work is distributed
15231 under the terms of a permission notice identical to this
15232 one.
15233
15234 Permission is granted to copy and distribute
15235 translations of this manual into another language,
15236 under the above conditions for modified versions,
15237 except that this permission notice may be stated in a
15238 translation approved by the Free Software Foundation.
15239 @end example
15240
15241 @node Titlepage Permissions,  , ifinfo Permissions, Sample Permissions
15242 @comment  node-name,  next,  previous,  up
15243 @appendixsec Titlepage Copying Permissions
15244 @cindex Titlepage permissions
15245
15246 In the @code{@@titlepage} section of a Texinfo file, the standard Free
15247 Software Foundation copying permission notice follows the copyright
15248 notice and publishing information.  The standard phrasing is as
15249 follows:@refill
15250
15251 @example
15252 Permission is granted to make and distribute verbatim
15253 copies of this manual provided the copyright notice and
15254 this permission notice are preserved on all copies.
15255
15256 Permission is granted to copy and distribute modified
15257 versions of this manual under the conditions for
15258 verbatim copying, provided also that the sections
15259 entitled ``Copying'' and ``GNU General Public License''
15260 are included exactly as in the original, and provided
15261 that the entire resulting derived work is distributed
15262 under the terms of a permission notice identical to this
15263 one.
15264
15265 Permission is granted to copy and distribute
15266 translations of this manual into another language,
15267 under the above conditions for modified versions,
15268 except that this permission notice may be stated in a
15269 translation approved by the Free Software Foundation.
15270 @end example
15271
15272
15273 @node Include Files, Headings, Sample Permissions, Top
15274 @appendix Include Files
15275 @cindex Include files
15276
15277 When @TeX{} or an Info formatting command sees an @code{@@include}
15278 command in a Texinfo file, it processes the contents of the file named
15279 by the command and incorporates them into the DVI or Info file being
15280 created.  Index entries from the included file are incorporated into
15281 the indices of the output file.@refill
15282
15283 Include files let you keep a single large document as a collection of
15284 conveniently small parts.@refill
15285
15286 @menu
15287 * Using Include Files::         How to use the @code{@@include} command.
15288 * texinfo-multiple-files-update::  How to create and update nodes and
15289                                   menus when using included files.
15290 * Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
15291 * Sample Include File::         A sample outer file with included files
15292                                   within it; and a sample included file.
15293 * Include Files Evolution::     How use of the @code{@@include} command
15294                                   has changed over time.
15295 @end menu
15296
15297 @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
15298 @appendixsec How to Use Include Files
15299 @findex include
15300
15301 To include another file within a Texinfo file, write the
15302 @code{@@include} command at the beginning of a line and follow it on
15303 the same line by the name of a file to be included.  For
15304 example:@refill
15305
15306 @example
15307 @@include buffers.texi
15308 @end example
15309
15310 An included file should simply be a segment of text that you expect to
15311 be included as is into the overall or @dfn{outer} Texinfo file; it
15312 should not contain the standard beginning and end parts of a Texinfo
15313 file.  In particular, you should not start an included file with a
15314 line saying @samp{\input texinfo}; if you do, that phrase is inserted
15315 into the output file as is.  Likewise, you should not end an included
15316 file with an @code{@@bye} command; nothing after @code{@@bye} is
15317 formatted.@refill
15318
15319 In the past, you were required to write an @code{@@setfilename} line at the
15320 beginning of an included file, but no longer.  Now, it does not matter
15321 whether you write such a line.  If an @code{@@setfilename} line exists
15322 in an included file, it is ignored.@refill
15323
15324 Conventionally, an included file begins with an @code{@@node} line that
15325 is followed by an @code{@@chapter} line.  Each included file is one
15326 chapter.  This makes it easy to use the regular node and menu creating
15327 and updating commands to create the node pointers and menus within the
15328 included file.  However, the simple Emacs node and menu creating and
15329 updating commands do not work with multiple Texinfo files.  Thus you
15330 cannot use these commands to fill in the `Next', `Previous', and `Up'
15331 pointers of the @code{@@node} line that begins the included file.  Also,
15332 you cannot use the regular commands to create a master menu for the
15333 whole file.  Either you must insert the menus and the `Next',
15334 `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
15335 Texinfo mode command, @code{texinfo-multiple-files-update}, that is
15336 designed for @code{@@include} files.@refill
15337
15338 @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
15339 @appendixsec @code{texinfo-multiple-files-update}
15340 @findex texinfo-multiple-files-update
15341
15342 GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
15343 command.  This command creates or updates `Next', `Previous', and `Up'
15344 pointers of included files as well as those in the outer or overall
15345 Texinfo file, and it creates or updates a main menu in the outer file.
15346 Depending whether you call it with optional arguments, the command
15347 updates only the pointers in the first @code{@@node} line of the
15348 included files or all of them:@refill
15349
15350 @table @kbd
15351 @item M-x texinfo-multiple-files-update
15352 Called without any arguments:@refill
15353
15354 @itemize @minus
15355 @item
15356 Create or update the `Next', `Previous', and `Up' pointers of the
15357 first @code{@@node} line in each file included in an outer or overall
15358 Texinfo file.@refill
15359
15360 @item
15361 Create or update the `Top' level node pointers of the outer or
15362 overall file.@refill
15363
15364 @item
15365 Create or update a main menu in the outer file.@refill
15366 @end itemize
15367
15368 @item C-u M-x texinfo-multiple-files-update
15369 Called with @kbd{C-u} as a prefix argument:
15370
15371 @itemize @minus{}
15372 @item
15373 Create or update pointers in the first @code{@@node} line in each
15374 included file.
15375
15376 @item
15377 Create or update the `Top' level node pointers of the outer file.
15378
15379 @item
15380 Create and insert a master menu in the outer file.  The master menu
15381 is made from all the menus in all the included files.@refill
15382 @end itemize
15383
15384 @item C-u 8 M-x texinfo-multiple-files-update
15385 Called with a numeric prefix argument, such as @kbd{C-u 8}:
15386
15387 @itemize @minus
15388 @item
15389 Create or update @strong{all} the `Next', `Previous', and `Up' pointers
15390 of all the included files.@refill
15391
15392 @item
15393 Create or update @strong{all} the menus of all the included
15394 files.@refill
15395
15396 @item
15397 Create or update the `Top' level node pointers of the outer or
15398 overall file.@refill
15399
15400 @item
15401 And then create a master menu in the outer file.  This is similar to
15402 invoking @code{texinfo-master-menu} with an argument when you are
15403 working with just one file.@refill
15404 @end itemize
15405 @end table
15406
15407 Note the use of the prefix argument in interactive use: with a regular
15408 prefix argument, just @w{@kbd{C-u}}, the
15409 @code{texinfo-multiple-files-update} command inserts a master menu;
15410 with a numeric prefix argument, such as @kbd{C-u 8}, the command
15411 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
15412 master menu.@refill
15413
15414 @node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files
15415 @appendixsec Include File Requirements
15416 @cindex Include file requirements
15417 @cindex Requirements for include files
15418
15419 If you plan to use the @code{texinfo-multiple-files-update} command,
15420 the outer Texinfo file that lists included files within it should
15421 contain nothing but the beginning and end parts of a Texinfo file, and
15422 a number of @code{@@include} commands listing the included files.  It
15423 should not even include indices, which should be listed in an included
15424 file of their own.@refill
15425
15426 Moreover, each of the included files must contain exactly one highest
15427 level node (conventionally, @code{@@chapter} or equivalent),
15428 and this node must be the first node in the included file.
15429 Furthermore, each of these highest level nodes in each included file
15430 must be at the same hierarchical level in the file structure.
15431 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
15432 @code{@@unnumbered} node.  Thus, normally, each included file contains
15433 one, and only one, chapter or equivalent-level node.@refill
15434
15435 The outer file should contain only @emph{one} node, the `Top' node.  It
15436 should @emph{not} contain any nodes besides the single `Top' node.  The
15437 @code{texinfo-multiple-files-update} command will not process
15438 them.@refill
15439
15440 @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
15441 @appendixsec Sample File with @code{@@include}
15442 @cindex Sample @code{@@include} file
15443 @cindex Include file sample
15444 @cindex @code{@@include} file sample
15445
15446 Here is an example of a complete outer Texinfo file with @code{@@include} files
15447 within it before running @code{texinfo-multiple-files-update}, which
15448 would insert a main or master menu:@refill
15449
15450 @example
15451 @group
15452 \input texinfo @@c -*-texinfo-*-
15453 @c %**start of header
15454 @@setfilename  include-example.info
15455 @@settitle Include Example
15456 @c %**end of header
15457 @end group
15458
15459 @group
15460 @@setchapternewpage odd
15461 @@titlepage
15462 @@sp 12
15463 @@center @@titlefont@{Include Example@}
15464 @@sp 2
15465 @@center by Whom Ever
15466 @end group
15467
15468 @group
15469 @@page
15470 @@vskip 0pt plus 1filll
15471 Copyright @@copyright@{@} 1998 Free Software Foundation, Inc.
15472 @@end titlepage
15473 @end group
15474
15475 @group
15476 @@ifinfo
15477 @@node Top, First, , (dir)
15478 @@top Master Menu
15479 @@end ifinfo
15480 @end group
15481
15482 @group
15483 @@include foo.texinfo
15484 @@include bar.texinfo
15485 @@include concept-index.texinfo
15486 @end group
15487
15488 @group
15489 @@summarycontents
15490 @@contents
15491
15492 @@bye
15493 @end group
15494 @end example
15495
15496 An included file, such as @file{foo.texinfo}, might look like
15497 this:@refill
15498
15499 @example
15500 @group
15501 @@node First, Second, , Top
15502 @@chapter First Chapter
15503
15504 Contents of first chapter @dots{}
15505 @end group
15506 @end example
15507
15508 The full contents of @file{concept-index.texinfo} might be as simple as this:
15509
15510 @example
15511 @group
15512 @@node Concept Index, , Second, Top
15513 @@unnumbered Concept Index
15514
15515 @@printindex cp
15516 @end group
15517 @end example
15518
15519 The outer Texinfo source file for @cite{The XEmacs Lisp Reference
15520 Manual} is named @file{elisp.texi}.  This outer file contains a master
15521 menu with 417 entries and a list of 41 @code{@@include}
15522 files.@refill
15523
15524 @node Include Files Evolution,  , Sample Include File, Include Files
15525 @comment  node-name,  next,  previous,  up
15526 @appendixsec Evolution of Include Files
15527
15528 When Info was first created, it was customary to create many small
15529 Info files on one subject.  Each Info file was formatted from its own
15530 Texinfo source file.  This custom meant that Emacs did not need to
15531 make a large buffer to hold the whole of a large Info file when
15532 someone wanted information; instead, Emacs allocated just enough
15533 memory for the small Info file that contained the particular
15534 information sought.  This way, Emacs could avoid wasting memory.@refill
15535
15536 References from one file to another were made by referring to the file
15537 name as well as the node name. (@xref{Other Info Files, , Referring to
15538 Other Info Files}.  Also, see @ref{Four and Five Arguments, ,
15539 @code{@@xref} with Four and Five Arguments}.)@refill
15540
15541 Include files were designed primarily as a way to create a single,
15542 large printed manual out of several smaller Info files.  In a printed
15543 manual, all the references were within the same document, so @TeX{}
15544 could automatically determine the references' page numbers.  The Info
15545 formatting commands used include files only for creating joint
15546 indices; each of the individual Texinfo files had to be formatted for
15547 Info individually.  (Each, therefore, required its own
15548 @code{@@setfilename} line.)@refill
15549
15550 However, because large Info files are now split automatically, it is
15551 no longer necessary to keep them small.@refill
15552
15553 Nowadays, multiple Texinfo files are used mostly for large documents,
15554 such as @cite{The XEmacs Lisp Reference Manual}, and for projects
15555 in which several different people write different sections of a
15556 document simultaneously.@refill
15557
15558 In addition, the Info formatting commands have been extended to work
15559 with the @code{@@include} command so as to create a single large Info
15560 file that is split into smaller files if necessary.  This means that
15561 you can write menus and cross references without naming the different
15562 Texinfo files.@refill
15563
15564
15565 @node Headings, Catching Mistakes, Include Files, Top
15566 @appendix Page Headings
15567 @cindex Headings
15568 @cindex Footings
15569 @cindex Page numbering
15570 @cindex Page headings
15571 @cindex Formatting headings and footings
15572
15573 Most printed manuals contain headings along the top of every page
15574 except the title and copyright pages.  Some manuals also contain
15575 footings.  (Headings and footings have no meaning to Info, which is
15576 not paginated.)@refill
15577
15578 @menu
15579 * Headings Introduced::         Conventions for using page headings.
15580 * Heading Format::              Standard page heading formats.
15581 * Heading Choice::              How to specify the type of page heading.
15582 * Custom Headings::             How to create your own headings and footings.
15583 @end menu
15584
15585 @node Headings Introduced, Heading Format, Headings, Headings
15586 @ifinfo
15587 @heading Headings Introduced
15588 @end ifinfo
15589
15590 Texinfo provides standard page heading formats for manuals that are
15591 printed on one side of each sheet of paper and for manuals that are
15592 printed on both sides of the paper.  Typically, you will use these
15593 formats, but you can specify your own format if you wish.@refill
15594
15595 In addition, you can specify whether chapters should begin on a new
15596 page, or merely continue the same page as the previous chapter; and if
15597 chapters begin on new pages, you can specify whether they must be
15598 odd-numbered pages.@refill
15599
15600 By convention, a book is printed on both sides of each sheet of paper.
15601 When you open a book, the right-hand page is odd-numbered, and
15602 chapters begin on right-hand pages---a preceding left-hand page is
15603 left blank if necessary.  Reports, however, are often printed on just
15604 one side of paper, and chapters begin on a fresh page immediately
15605 following the end of the preceding chapter.  In short or informal
15606 reports, chapters often do not begin on a new page at all, but are
15607 separated from the preceding text by a small amount of whitespace.@refill
15608
15609 The @code{@@setchapternewpage} command controls whether chapters begin
15610 on new pages, and whether one of the standard heading formats is used.
15611 In addition, Texinfo has several heading and footing commands that you
15612 can use to generate your own heading and footing formats.@refill
15613
15614 In Texinfo, headings and footings are single lines at the tops and
15615 bottoms of pages; you cannot create multiline headings or footings.
15616 Each header or footer line is divided into three parts: a left part, a
15617 middle part, and a right part.  Any part, or a whole line, may be left
15618 blank.  Text for the left part of a header or footer line is set
15619 flushleft; text for the middle part is centered; and, text for the
15620 right part is set flushright.@refill
15621
15622 @node Heading Format, Heading Choice, Headings Introduced, Headings
15623 @comment  node-name,  next,  previous,  up
15624 @appendixsec Standard Heading Formats
15625
15626 Texinfo provides two standard heading formats, one for manuals printed
15627 on one side of each sheet of paper, and the other for manuals printed
15628 on both sides of the paper.
15629
15630 By default, nothing is specified for the footing of a Texinfo file,
15631 so the footing remains blank.@refill
15632
15633 The standard format for single-sided printing consists of a header
15634 line in which the left-hand part contains the name of the chapter, the
15635 central part is blank, and the right-hand part contains the page
15636 number.@refill
15637
15638 @need 950
15639 A single-sided page looks like this:
15640
15641 @example
15642 @group
15643    _______________________
15644   |                       |
15645   | chapter   page number |
15646   |                       |
15647   | Start of text ...     |
15648   | ...                   |
15649   |                       |
15650
15651 @end group
15652 @end example
15653
15654 The standard format for two-sided printing depends on whether the page
15655 number is even or odd.  By convention, even-numbered pages are on the
15656 left- and odd-numbered pages are on the right.  (@TeX{} will adjust the
15657 widths of the left- and right-hand margins.  Usually, widths are
15658 correct, but during double-sided printing, it is wise to check that
15659 pages will bind properly---sometimes a printer will produce output in
15660 which the even-numbered pages have a larger right-hand margin than the
15661 odd-numbered pages.)@refill
15662
15663 In the standard double-sided format, the left part of the left-hand
15664 (even-numbered) page contains the page number, the central part is
15665 blank, and the right part contains the title (specified by the
15666 @code{@@settitle} command).  The left part of the right-hand
15667 (odd-numbered) page contains the name of the chapter, the central part
15668 is blank, and the right part contains the page number.@refill
15669
15670 @need 750
15671 Two pages, side by side as in an open book, look like this:@refill
15672
15673 @example
15674 @group
15675    _______________________     _______________________
15676   |                       |   |                       |
15677   | page number     title |   | chapter   page number |
15678   |                       |   |                       |
15679   | Start of text ...     |   | More  text ...        |
15680   | ...                   |   | ...                   |
15681   |                       |   |                       |
15682
15683 @end group
15684 @end example
15685
15686 @noindent
15687 The chapter name is preceded by the word ``Chapter'', the chapter number
15688 and a colon.  This makes it easier to keep track of where you are in the
15689 manual.@refill
15690
15691 @node Heading Choice, Custom Headings, Heading Format, Headings
15692 @comment  node-name,  next,  previous,  up
15693 @appendixsec Specifying the Type of Heading
15694
15695 @TeX{} does not begin to generate page headings for a standard Texinfo
15696 file until it reaches the @code{@@end titlepage} command.  Thus, the
15697 title and copyright pages are not numbered.  The @code{@@end
15698 titlepage} command causes @TeX{} to begin to generate page headings
15699 according to a standard format specified by the
15700 @code{@@setchapternewpage} command that precedes the
15701 @code{@@titlepage} section.@refill
15702
15703 @need 1000
15704 There are four possibilities:@refill
15705
15706 @table @asis
15707 @item No @code{@@setchapternewpage} command
15708 Cause @TeX{} to specify the single-sided heading format, with chapters
15709 on new pages. This is the same as @code{@@setchapternewpage on}.@refill
15710
15711 @item @code{@@setchapternewpage on}
15712 Specify the single-sided heading format, with chapters on new pages.@refill
15713
15714 @item @code{@@setchapternewpage off}
15715 Cause @TeX{} to start a new chapter on the same page as the last page of
15716 the preceding chapter, after skipping some vertical whitespace.  Also
15717 cause @TeX{} to typeset for single-sided printing.  (You can override
15718 the headers format with the @code{@@headings double} command; see
15719 @ref{headings on off, , The @code{@@headings} Command}.)@refill
15720
15721 @item @code{@@setchapternewpage odd}
15722 Specify the double-sided heading format, with chapters on new pages.@refill
15723 @end table
15724
15725 @noindent
15726 Texinfo lacks an @code{@@setchapternewpage even} command.@refill
15727
15728 @node Custom Headings,  , Heading Choice, Headings
15729 @comment  node-name,  next,  previous,  up
15730 @appendixsec How to Make Your Own Headings
15731
15732 You can use the standard headings provided with Texinfo or specify
15733 your own.  By default, Texinfo has no footers, so if you specify them,
15734 the available page size for the main text will be slightly reduced.
15735
15736 @c Following paragraph is verbose to prevent overfull hboxes.
15737 Texinfo provides six commands for specifying headings and
15738 footings.  The @code{@@everyheading} command and
15739 @code{@@everyfooting} command generate page headers and footers
15740 that are the same for both even- and odd-numbered pages.
15741 The @code{@@evenheading} command and @code{@@evenfooting}
15742 command generate headers and footers for even-numbered
15743 (left-hand) pages; and the @code{@@oddheading} command and
15744 @code{@@oddfooting} command generate headers and footers for
15745 odd-numbered (right-hand) pages.@refill
15746
15747 Write custom heading specifications in the Texinfo file immediately
15748 after the @code{@@end titlepage} command.  Enclose your specifications
15749 between @code{@@iftex} and @code{@@end iftex} commands since the
15750 @code{texinfo-format-buffer} command may not recognize them.  Also,
15751 you must cancel the predefined heading commands with the
15752 @code{@@headings off} command before defining your own
15753 specifications.@refill
15754
15755 @need 1000
15756 Here is how to tell @TeX{} to place the chapter name at the left, the
15757 page number in the center, and the date at the right of every header
15758 for both even- and odd-numbered pages:@refill
15759
15760 @example
15761 @group
15762 @@iftex
15763 @@headings off
15764 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
15765 @@end iftex
15766 @end group
15767 @end example
15768
15769 @noindent
15770 You need to divide the left part from the central part and the central
15771 part from the right part by inserting @samp{@@|} between parts.
15772 Otherwise, the specification command will not be able to tell where
15773 the text for one part ends and the next part begins.@refill
15774
15775 Each part can contain text or @@-commands.  The text
15776 is printed as if the part were within an ordinary paragraph in the
15777 body of the page.  The @@-commands replace
15778 themselves with the page number, date, chapter name, or
15779 whatever.@refill
15780
15781 @need 950
15782 Here are the six heading and footing commands:@refill
15783
15784 @findex everyheading
15785 @findex everyfooting
15786 @table @code
15787 @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
15788 @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
15789
15790 The `every' commands specify the format for both even- and odd-numbered
15791 pages.  These commands are for documents that are printed on one side
15792 of each sheet of paper, or for documents in which you want symmetrical
15793 headers or footers.@refill
15794
15795 @findex evenheading
15796 @findex evenfooting
15797 @findex oddheading
15798 @findex oddfooting
15799 @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
15800 @itemx @@oddheading  @var{left} @@| @var{center} @@| @var{right}
15801
15802 @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
15803 @itemx @@oddfooting  @var{left} @@| @var{center} @@| @var{right}
15804
15805 The `even' and `odd' commands specify the format for even-numbered
15806 pages and odd-numbered pages.  These commands are for books and
15807 manuals that are printed on both sides of each sheet of paper.
15808 @end table
15809
15810 Use the @samp{@@this@dots{}} series of @@-commands to
15811 provide the names of chapters
15812 and sections and the page number.  You can use the
15813 @samp{@@this@dots{}} commands in the left, center, or right portions
15814 of headers and footers, or anywhere else in a Texinfo file so long as
15815 they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
15816
15817 @need 1000
15818 Here are the @samp{@@this@dots{}} commands:@refill
15819
15820 @table @code
15821 @findex thispage
15822 @item @@thispage
15823 Expands to the current page number.@refill
15824 @c !!! Karl Berry says that `thissection' can fail on page breaks.
15825 @ignore
15826 @item @@thissection
15827 Expands to the name of the current section.@refill
15828 @end ignore
15829
15830 @findex thischaptername
15831 @item @@thischaptername
15832 Expands to the name of the current chapter.@refill
15833
15834 @findex thischapter
15835 @item @@thischapter
15836 Expands to the number and name of the current
15837 chapter, in the format `Chapter 1: Title'.@refill
15838
15839 @findex thistitle
15840 @item @@thistitle
15841 Expands to the name of the document, as specified by the
15842 @code{@@settitle} command.@refill
15843
15844 @findex thisfile
15845 @item @@thisfile
15846 For @code{@@include} files only: expands to the name of the current
15847 @code{@@include} file.  If the current Texinfo source file is not an
15848 @code{@@include} file, this command has no effect.  This command does
15849 @emph{not} provide the name of the current Texinfo source file unless
15850 it is an @code{@@include} file.  (@xref{Include Files}, for more
15851 information about @code{@@include} files.)@refill
15852 @end table
15853
15854 @noindent
15855 You can also use the @code{@@today@{@}} command, which expands to the
15856 current date, in `1 Jan 1900' format.@refill
15857 @findex today
15858
15859 Other @@-commands and text are printed in a header or footer just as
15860 if they were in the body of a page.  It is useful to incorporate text,
15861 particularly when you are writing drafts:@refill
15862
15863 @example
15864 @group
15865 @@iftex
15866 @@headings off
15867 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
15868 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
15869 @@end iftex
15870 @end group
15871 @end example
15872
15873 Beware of overlong titles: they may overlap another part of the
15874 header or footer and blot it out.@refill
15875
15876
15877 @node Catching Mistakes, Refilling Paragraphs, Headings, Top
15878 @appendix Formatting Mistakes
15879 @cindex Structure, catching mistakes in
15880 @cindex Nodes, catching mistakes
15881 @cindex Catching mistakes
15882 @cindex Correcting mistakes
15883 @cindex Mistakes, catching
15884 @cindex Problems, catching
15885 @cindex Debugging the Texinfo structure
15886
15887 Besides mistakes in the content of your documentation, there
15888 are two kinds of mistake you can make with Texinfo:  you can make mistakes
15889 with @@-commands, and you can make mistakes with the structure of the
15890 nodes and chapters.@refill
15891
15892 Emacs has two tools for catching the @@-command mistakes and two for
15893 catching structuring mistakes.@refill
15894
15895 For finding problems with @@-commands, you can run @TeX{} or a region
15896 formatting command on the region that has a problem; indeed, you can
15897 run these commands on each region as you write it.@refill
15898
15899 For finding problems with the structure of nodes and chapters, you can use
15900 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
15901 command and you can use the @kbd{M-x Info-validate} command.@refill
15902
15903 @menu
15904 * makeinfo Preferred::          @code{makeinfo} finds errors.
15905 * Debugging with Info::         How to catch errors with Info formatting.
15906 * Debugging with TeX::          How to catch errors with @TeX{} formatting.
15907 * Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
15908 * Using occur::                 How to list all lines containing a pattern.
15909 * Running Info-Validate::       How to find badly referenced nodes.
15910 @end menu
15911
15912 @node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
15913 @ifinfo
15914 @heading @code{makeinfo} Find Errors
15915 @end ifinfo
15916
15917 The @code{makeinfo} program does an excellent job of catching errors
15918 and reporting them---far better than @code{texinfo-format-region} or
15919 @code{texinfo-format-buffer}.  In addition, the various functions for
15920 automatically creating and updating node pointers and menus remove
15921 many opportunities for human error.@refill
15922
15923 If you can, use the updating commands to create and insert pointers
15924 and menus.  These prevent many errors.  Then use @code{makeinfo} (or
15925 its Texinfo mode manifestations, @code{makeinfo-region} and
15926 @code{makeinfo-buffer}) to format your file and check for other
15927 errors.  This is the best way to work with Texinfo.  But if you
15928 cannot use @code{makeinfo}, or your problem is very puzzling, then you
15929 may want to use the tools described in this appendix.@refill
15930
15931 @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
15932 @comment  node-name,  next,  previous,  up
15933 @appendixsec Catching Errors with Info Formatting
15934 @cindex Catching errors with Info formatting
15935 @cindex Debugging with Info formatting
15936
15937 After you have written part of a Texinfo file, you can use the
15938 @code{texinfo-format-region} or the @code{makeinfo-region} command to
15939 see whether the region formats properly.@refill
15940
15941 Most likely, however, you are reading this section because for some
15942 reason you cannot use the @code{makeinfo-region} command; therefore, the
15943 rest of this section presumes that you are using
15944 @code{texinfo-format-region}.@refill
15945
15946 If you have made a mistake with an @@-command,
15947 @code{texinfo-format-region} will stop processing at or after the
15948 error and display an error message.  To see where in the buffer the
15949 error occurred, switch to the @samp{*Info Region*} buffer; the cursor
15950 will be in a position that is after the location of the error.  Also,
15951 the text will not be formatted after the place where the error
15952 occurred (or more precisely, where it was detected).@refill
15953
15954 For example, if you accidentally end a menu with the command @code{@@end
15955 menus} with an `s' on the end, instead of with @code{@@end menu}, you
15956 will see an error message that says:@refill
15957
15958 @example
15959 @@end menus is not handled by texinfo
15960 @end example
15961
15962 @noindent
15963 The cursor will stop at the point in the buffer where the error
15964 occurs, or not long after it.  The buffer will look like this:@refill
15965
15966 @example
15967 @group
15968 ---------- Buffer: *Info Region* ----------
15969 * Menu:
15970
15971 * Using texinfo-show-structure::  How to use
15972                                   `texinfo-show-structure'
15973                                   to catch mistakes.
15974 * Running Info-Validate::         How to check for
15975                                   unreferenced nodes.
15976 @@end menus
15977 @point{}
15978 ---------- Buffer: *Info Region* ----------
15979 @end group
15980 @end example
15981
15982 The @code{texinfo-format-region} command sometimes provides slightly
15983 odd error messages.  For example, the following cross reference fails to format:@refill
15984
15985 @example
15986 (@@xref@{Catching Mistakes, for more info.)
15987 @end example
15988
15989 @noindent
15990 In this case, @code{texinfo-format-region} detects the missing closing
15991 brace but displays a message that says @samp{Unbalanced parentheses}
15992 rather than @samp{Unbalanced braces}.  This is because the formatting
15993 command looks for mismatches between braces as if they were
15994 parentheses.@refill
15995
15996 Sometimes @code{texinfo-format-region} fails to detect mistakes.  For
15997 example, in the following, the closing brace is swapped with the
15998 closing parenthesis:@refill
15999
16000 @example
16001 (@@xref@{Catching Mistakes), for more info.@}
16002 @end example
16003
16004 @noindent
16005 Formatting produces:
16006 @example
16007 (*Note for more info.: Catching Mistakes)
16008 @end example
16009
16010 The only way for you to detect this error is to realize that the
16011 reference should have looked like this:@refill
16012
16013 @example
16014 (*Note Catching Mistakes::, for more info.)
16015 @end example
16016
16017 Incidentally, if you are reading this node in Info and type @kbd{f
16018 @key{RET}} (@code{Info-follow-reference}), you will generate an error
16019 message that says:
16020
16021 @example
16022 No such node: "Catching Mistakes) The only way @dots{}
16023 @end example
16024
16025 @noindent
16026 This is because Info perceives the example of the error as the first
16027 cross reference in this node and if you type a @key{RET} immediately
16028 after typing the Info @kbd{f} command, Info will attempt to go to the
16029 referenced node.  If you type @kbd{f catch @key{TAB} @key{RET}}, Info
16030 will complete the node name of the correctly written example and take
16031 you to the `Catching Mistakes' node.  (If you try this, you can return
16032 from the `Catching Mistakes' node by typing @kbd{l}
16033 (@code{Info-last}).)
16034
16035 @c !!! section on using Elisp debugger ignored.
16036 @ignore
16037 Sometimes @code{texinfo-format-region} will stop long after the
16038 original error; this is because it does not discover the problem until
16039 then.  In this case, you will need to backtrack.@refill
16040
16041 @c menu
16042 @c * Using the Emacs Lisp Debugger::  How to use the Emacs Lisp debugger.
16043 @c end menu
16044
16045 @c node Using the Emacs Lisp Debugger
16046 @c appendixsubsec Using the Emacs Lisp Debugger
16047 @c index Using the Emacs Lisp debugger
16048 @c index Emacs Lisp debugger
16049 @c index Debugger, using the Emacs Lisp
16050
16051 If an error is especially elusive, you can turn on the Emacs Lisp
16052 debugger and look at the backtrace; this tells you where in the
16053 @code{texinfo-format-region} function the problem occurred.  You can
16054 turn on the debugger with the command:@refill
16055
16056 @example
16057 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
16058 @end example
16059
16060 @noindent
16061 and turn it off with
16062
16063 @example
16064 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
16065 @end example
16066
16067 Often, when you are using the debugger, it is easier to follow what is
16068 going on if you use the Emacs Lisp files that are not byte-compiled.
16069 The byte-compiled sources send octal numbers to the debugger that may
16070 look mysterious.  To use the uncompiled source files, load
16071 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
16072 command.@refill
16073
16074 The debugger will not catch an error if @code{texinfo-format-region}
16075 does not detect one.  In the example shown above,
16076 @code{texinfo-format-region} did not find the error when the whole
16077 list was formatted, but only when part of the list was formatted.
16078 When @code{texinfo-format-region} did not find an error, the debugger
16079 did not find one either. @refill
16080
16081 However, when @code{texinfo-format-region} did report an error, it
16082 invoked the debugger.  This is the backtrace it produced:@refill
16083
16084 @example
16085 ---------- Buffer: *Backtrace* ----------
16086 Signalling: (search-failed "[@},]")
16087   re-search-forward("[@},]")
16088   (while ...)
16089   (let ...)
16090   texinfo-format-parse-args()
16091   (let ...)
16092   texinfo-format-xref()
16093   funcall(texinfo-format-xref)
16094   (if ...)
16095   (let ...)
16096   (if ...)
16097   (while ...)
16098   texinfo-format-scan()
16099   (save-excursion ...)
16100   (let ...)
16101   texinfo-format-region(103370 103631)
16102 * call-interactively(texinfo-format-region)
16103 ---------- Buffer: *Backtrace* ----------
16104 @end example
16105
16106 The backtrace is read from the bottom up.
16107 @code{texinfo-format-region} was called interactively; and it, in
16108 turn, called various functions, including @code{texinfo-format-scan},
16109 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
16110 Inside the function @code{texinfo-format-parse-args}, the function
16111 @code{re-search-forward} was called; it was this function that could
16112 not find the missing right-hand brace.@refill
16113
16114 @xref{Lisp Debug, , Debugging Emacs Lisp, xemacs, XEmacs User's Manual},
16115 for more information.@refill
16116 @end ignore
16117
16118 @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
16119 @comment  node-name,  next,  previous,  up
16120 @appendixsec Catching Errors with @TeX{} Formatting
16121 @cindex Catching errors with @TeX{} formatting
16122 @cindex Debugging with @TeX{} formatting
16123
16124 You can also catch mistakes when you format a file with @TeX{}.@refill
16125
16126 Usually, you will want to do this after you have run
16127 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
16128 the same file, because @code{texinfo-format-buffer} sometimes displays
16129 error messages that make more sense than @TeX{}.  (@xref{Debugging
16130 with Info}, for more information.)@refill
16131
16132 For example, @TeX{} was run on a Texinfo file, part of which is shown
16133 here:@refill
16134
16135 @example
16136 ---------- Buffer: texinfo.texi ----------
16137 name of the Texinfo file as an extension.  The
16138 @@samp@{??@} are `wildcards' that cause the shell to
16139 substitute all the raw index files.  (@@xref@{sorting
16140 indices, for more information about sorting
16141 indices.)@@refill
16142 ---------- Buffer: texinfo.texi ----------
16143 @end example
16144
16145 @noindent
16146 (The cross reference lacks a closing brace.)
16147 @TeX{} produced the following output, after which it stopped:@refill
16148
16149 @example
16150 ---------- Buffer: *tex-shell* ----------
16151 Runaway argument?
16152 @{sorting indices, for more information about sorting
16153 indices.) @@refill @@ETC.
16154 ! Paragraph ended before @@xref was complete.
16155 <to be read again>
16156                    @@par
16157 l.27
16158
16159 ?
16160 ---------- Buffer: *tex-shell* ----------
16161 @end example
16162
16163 In this case, @TeX{} produced an accurate and
16164 understandable error message:
16165
16166 @example
16167 Paragraph ended before @@xref was complete.
16168 @end example
16169
16170 @noindent
16171 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
16172 @samp{l.27} means that @TeX{} detected the problem on line 27 of the
16173 Texinfo file.  The @samp{?} is the prompt @TeX{} uses in this
16174 circumstance.@refill
16175
16176 Unfortunately, @TeX{} is not always so helpful, and sometimes you must
16177 truly be a Sherlock Holmes to discover what went wrong.@refill
16178
16179 In any case, if you run into a problem like this, you can do one of three
16180 things.@refill
16181
16182 @enumerate
16183 @item
16184 You can tell @TeX{} to continue running and ignore just this error by
16185 typing @key{RET} at the @samp{?} prompt.@refill
16186
16187 @item
16188 You can tell @TeX{} to continue running and to ignore all errors as best
16189 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
16190
16191 This is often the best thing to do.  However, beware: the one error
16192 may produce a cascade of additional error messages as its consequences
16193 are felt through the rest of the file.  To stop @TeX{} when it is
16194 producing such an avalanche of error messages, type @kbd{C-c} (or
16195 @kbd{C-c C-c}, if you are running a shell inside Emacs).
16196
16197 @item
16198 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
16199 at the @samp{?} prompt.@refill
16200 @end enumerate
16201
16202 Please note that if you are running @TeX{} inside Emacs, you need to
16203 switch to the shell buffer and line at which @TeX{} offers the @samp{?}
16204 prompt.@refill
16205
16206 Sometimes @TeX{} will format a file without producing error messages even
16207 though there is a problem.  This usually occurs if a command is not ended
16208 but @TeX{} is able to continue processing anyhow.  For example, if you fail
16209 to end an itemized list with the @code{@@end itemize} command, @TeX{} will
16210 write a DVI file that you can print out.  The only error message that
16211 @TeX{} will give you is the somewhat mysterious comment that@refill
16212
16213 @example
16214 (@@end occurred inside a group at level 1)
16215 @end example
16216
16217 @noindent
16218 However, if you print the DVI file, you will find that the text
16219 of the file that follows the itemized list is entirely indented as if
16220 it were part of the last item in the itemized list.  The error message
16221 is the way @TeX{} says that it expected to find an @code{@@end}
16222 command somewhere in the file; but that it could not determine where
16223 it was needed.@refill
16224
16225 Another source of notoriously hard-to-find errors is a missing
16226 @code{@@end group} command.  If you ever are stumped by
16227 incomprehensible errors, look for a missing @code{@@end group} command
16228 first.@refill
16229
16230 If the Texinfo file lacks header lines,
16231 @TeX{} may stop in the
16232 beginning of its run and display output that looks like the following.
16233 The @samp{*} indicates that @TeX{} is waiting for input.@refill
16234
16235 @example
16236 This is TeX, Version 3.14159 (Web2c 7.0)
16237 (test.texinfo [1])
16238 *
16239 @end example
16240
16241 @noindent
16242 In this case, simply type @kbd{\end @key{RET}} after the asterisk.  Then
16243 write the header lines in the Texinfo file and run the @TeX{} command
16244 again. (Note the use of the backslash, @samp{\}.  @TeX{} uses @samp{\}
16245 instead of @samp{@@}; and in this circumstance, you are working
16246 directly with @TeX{}, not with Texinfo.)@refill
16247
16248 @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
16249 @comment  node-name,  next,  previous,  up
16250 @appendixsec Using @code{texinfo-show-structure}
16251 @cindex Showing the structure of a file
16252 @findex texinfo-show-structure
16253
16254 It is not always easy to keep track of the nodes, chapters, sections, and
16255 subsections of a Texinfo file.  This is especially true if you are revising
16256 or adding to a Texinfo file that someone else has written.@refill
16257
16258 In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
16259 command lists all the lines that begin with the @@-commands that
16260 specify the structure: @code{@@chapter}, @code{@@section},
16261 @code{@@appendix}, and so on.  With an argument (@w{@kbd{C-u}}
16262 as prefix argument, if interactive),
16263 the command also shows the @code{@@node} lines.  The
16264 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
16265 Texinfo mode, by default.@refill
16266
16267 The lines are displayed in a buffer called the @samp{*Occur*} buffer,
16268 indented by hierarchical level.  For example, here is a part of what was
16269 produced by running @code{texinfo-show-structure} on this manual:@refill
16270
16271 @example
16272 @group
16273  Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
16274  unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
16275  in buffer texinfo.texi.
16276  @dots{}
16277  4177:@@chapter Nodes
16278  4198:    @@heading Two Paths
16279  4231:    @@section Node and Menu Illustration
16280  4337:    @@section The @@code@{@@@@node@} Command
16281  4393:        @@subheading Choosing Node and Pointer Names
16282  4417:        @@subsection How to Write an @@code@{@@@@node@} Line
16283  4469:        @@subsection @@code@{@@@@node@} Line Tips
16284  @dots{}
16285 @end group
16286 @end example
16287
16288 This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
16289 with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
16290 commands respectively.  If you move your cursor into the @samp{*Occur*}
16291 window, you can position the cursor over one of the lines and use the
16292 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
16293 the corresponding spot in the Texinfo file.  @xref{Other Repeating
16294 Search, , Using Occur, xemacs, XEmacs User's Manual}, for more
16295 information about @code{occur-mode-goto-occurrence}.@refill
16296
16297 The first line in the @samp{*Occur*} window describes the @dfn{regular
16298 expression} specified by @var{texinfo-heading-pattern}.  This regular
16299 expression is the pattern that @code{texinfo-show-structure} looks for.
16300 @xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual},
16301 for more information.@refill
16302
16303 When you invoke the @code{texinfo-show-structure} command, Emacs will
16304 display the structure of the whole buffer.  If you want to see the
16305 structure of just a part of the buffer, of one chapter, for example,
16306 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
16307 region.  (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.)  This is
16308 how the example used above was generated.  (To see the whole buffer
16309 again, use @kbd{C-x n w} (@code{widen}).)@refill
16310
16311 If you call @code{texinfo-show-structure} with a prefix argument by
16312 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
16313 @code{@@node} as well as the lines beginning with the @@-sign commands
16314 for @code{@@chapter}, @code{@@section}, and the like.@refill
16315
16316 You can remind yourself of the structure of a Texinfo file by looking at
16317 the list in the @samp{*Occur*} window; and if you have mis-named a node
16318 or left out a section, you can correct the mistake.@refill
16319
16320 @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
16321 @comment  node-name,  next,  previous,  up
16322 @appendixsec Using @code{occur}
16323 @cindex Occurrences, listing with @code{@@occur}
16324 @findex occur
16325
16326 Sometimes the @code{texinfo-show-structure} command produces too much
16327 information.  Perhaps you want to remind yourself of the overall structure
16328 of a Texinfo file, and are overwhelmed by the detailed list produced by
16329 @code{texinfo-show-structure}.  In this case, you can use the @code{occur}
16330 command directly.  To do this, type@refill
16331
16332 @example
16333 @kbd{M-x occur}
16334 @end example
16335
16336 @noindent
16337 and then, when prompted, type a @dfn{regexp}, a regular expression for
16338 the pattern you want to match.  (@xref{Regexps, , Regular Expressions,
16339 xemacs, XEmacs User's Manual}.)  The @code{occur} command works from the
16340 current location of the cursor in the buffer to the end of the buffer.
16341 If you want to run @code{occur} on the whole buffer, place the cursor at
16342 the beginning of the buffer.@refill
16343
16344 For example, to see all the lines that contain the word
16345 @samp{@@chapter} in them, just type @samp{@@chapter}.  This will
16346 produce a list of the chapters.  It will also list all the sentences
16347 with @samp{@@chapter} in the middle of the line.@refill
16348
16349 If you want to see only those lines that start with the word
16350 @samp{@@chapter}, type @samp{^@@chapter} when prompted by
16351 @code{occur}.  If you want to see all the lines that end with a word
16352 or phrase, end the last word with a @samp{$}; for example,
16353 @samp{catching mistakes$}.  This can be helpful when you want to see
16354 all the nodes that are part of the same chapter or section and
16355 therefore have the same `Up' pointer.@refill
16356
16357 @xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual},
16358 for more information.@refill
16359
16360 @node Running Info-Validate,  , Using occur, Catching Mistakes
16361 @comment  node-name,  next,  previous,  up
16362 @appendixsec Finding Badly Referenced Nodes
16363 @findex Info-validate
16364 @cindex Nodes, checking for badly referenced
16365 @cindex Checking for badly referenced nodes
16366 @cindex Looking for badly referenced nodes
16367 @cindex Finding badly referenced nodes
16368 @cindex Badly referenced nodes
16369
16370 You can use the @code{Info-validate} command to check whether any of
16371 the `Next', `Previous', `Up' or other node pointers fail to point to a
16372 node.  This command checks that every node pointer points to an
16373 existing node.  The @code{Info-validate} command works only on Info
16374 files, not on Texinfo files.@refill
16375
16376 The @code{makeinfo} program validates pointers automatically, so you
16377 do not need to use the @code{Info-validate} command if you are using
16378 @code{makeinfo}.  You only may need to use @code{Info-validate} if you
16379 are unable to run @code{makeinfo} and instead must create an Info file
16380 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
16381 if you write an Info file from scratch.@refill
16382
16383 @menu
16384 * Using Info-validate::         How to run @code{Info-validate}.
16385 * Unsplit::                     How to create an unsplit file.
16386 * Tagifying::                   How to tagify a file.
16387 * Splitting::                   How to split a file manually.
16388 @end menu
16389
16390 @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
16391 @appendixsubsec Running @code{Info-validate}
16392 @cindex Running @code{Info-validate}
16393 @cindex Info validating a large file
16394 @cindex Validating a large file
16395
16396 To use @code{Info-validate}, visit the Info file you wish to check and
16397 type:@refill
16398
16399 @example
16400 M-x Info-validate
16401 @end example
16402
16403 @noindent
16404 (Note that the @code{Info-validate} command requires an upper case
16405 `I'.  You may also need to create a tag table before running
16406 @code{Info-validate}.  @xref{Tagifying}.)@refill
16407
16408 If your file is valid, you will receive a message that says ``File appears
16409 valid''.  However, if you have a pointer that does not point to a node,
16410 error messages will be displayed in a buffer called @samp{*problems in
16411 info file*}.@refill
16412
16413 For example, @code{Info-validate} was run on a test file that contained
16414 only the first node of this manual.  One of the messages said:@refill
16415
16416 @example
16417 In node "Overview", invalid Next: Texinfo Mode
16418 @end example
16419
16420 @noindent
16421 This meant that the node called @samp{Overview} had a `Next' pointer that
16422 did not point to anything (which was true in this case, since the test file
16423 had only one node in it).@refill
16424
16425 Now suppose we add a node named @samp{Texinfo Mode} to our test case
16426 but we do not specify a `Previous' for this node.  Then we will get
16427 the following error message:@refill
16428
16429 @example
16430 In node "Texinfo Mode", should have Previous: Overview
16431 @end example
16432
16433 @noindent
16434 This is because every `Next' pointer should be matched by a
16435 `Previous' (in the node where the `Next' points) which points back.@refill
16436
16437 @code{Info-validate} also checks that all menu entries and cross references
16438 point to actual nodes.@refill
16439
16440 Note that @code{Info-validate} requires a tag table and does not work
16441 with files that have been split.  (The @code{texinfo-format-buffer}
16442 command automatically splits large files.)  In order to use
16443 @code{Info-validate} on a large file, you must run
16444 @code{texinfo-format-buffer} with an argument so that it does not split
16445 the Info file; and you must create a tag table for the unsplit
16446 file.@refill
16447
16448 @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
16449 @comment  node-name,  next,  previous,  up
16450 @appendixsubsec Creating an Unsplit File
16451 @cindex Creating an unsplit file
16452 @cindex Unsplit file creation
16453
16454 You can run @code{Info-validate} only on a single Info file that has a
16455 tag table.  The command will not work on the indirect subfiles that
16456 are generated when a master file is split.  If you have a large file
16457 (longer than 70,000 bytes or so), you need to run the
16458 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
16459 a way that it does not create indirect subfiles.  You will also need
16460 to create a tag table for the Info file.  After you have done this,
16461 you can run @code{Info-validate} and look for badly referenced
16462 nodes.@refill
16463
16464 The first step is to create an unsplit Info file.  To prevent
16465 @code{texinfo-format-buffer} from splitting a Texinfo file into
16466 smaller Info files, give a prefix to the @kbd{M-x
16467 texinfo-format-buffer} command:@refill
16468
16469 @example
16470 C-u M-x texinfo-format-buffer
16471 @end example
16472
16473 @noindent
16474 or else
16475
16476 @example
16477 C-u C-c C-e C-b
16478 @end example
16479
16480 @noindent
16481 When you do this, Texinfo will not split the file and will not create
16482 a tag table for it. @refill
16483 @cindex Making a tag table manually
16484 @cindex Tag table, making manually
16485
16486 @node Tagifying, Splitting, Unsplit, Running Info-Validate
16487 @appendixsubsec Tagifying a File
16488
16489 After creating an unsplit Info file, you must create a tag table for
16490 it.  Visit the Info file you wish to tagify and type:@refill
16491
16492 @example
16493 M-x Info-tagify
16494 @end example
16495
16496 @noindent
16497 (Note the upper case @samp{I} in @code{Info-tagify}.)  This creates an
16498 Info file with a tag table that you can validate.@refill
16499
16500 The third step is to validate the Info file:@refill
16501
16502 @example
16503 M-x Info-validate
16504 @end example
16505
16506 @noindent
16507 (Note the upper case @samp{I} in @code{Info-validate}.)
16508 In brief, the steps are:@refill
16509
16510 @example
16511 @group
16512 C-u M-x texinfo-format-buffer
16513 M-x Info-tagify
16514 M-x Info-validate
16515 @end group
16516 @end example
16517
16518 After you have validated the node structure, you can rerun
16519 @code{texinfo-format-buffer} in the normal way so it will construct a
16520 tag table and split the file automatically, or you can make the tag
16521 table and split the file manually.@refill
16522
16523 @node Splitting,  , Tagifying, Running Info-Validate
16524 @comment  node-name,  next,  previous,  up
16525 @appendixsubsec Splitting a File Manually
16526 @cindex Splitting an Info file manually
16527 @cindex Info file, splitting manually
16528
16529 You should split a large file or else let the
16530 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
16531 for you automatically.  (Generally you will let one of the formatting
16532 commands do this job for you.  @xref{Create an Info File}.)@refill
16533
16534 The split-off files are called the indirect subfiles.@refill
16535
16536 Info files are split to save memory.  With smaller files, Emacs does not
16537 have make such a large buffer to hold the information.@refill
16538
16539 If an Info file has more than 30 nodes, you should also make a tag
16540 table for it. @xref{Using Info-validate}, for information
16541 about creating a tag table.  (Again, tag tables are usually created
16542 automatically by the formatting command; you only need to create a tag
16543 table yourself if you are doing the job manually.  Most likely, you
16544 will do this for a large, unsplit file on which you have run
16545 @code{Info-validate}.)@refill
16546
16547 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
16548 @ignore
16549 Before running @code{Info-split}, you need to load the @code{info} library
16550 into Emacs by giving the command @kbd{M-x load-library @key{RET} info
16551 @key{RET}}.
16552 @end ignore
16553
16554 Visit the Info file you wish to tagify and split and type the two
16555 commands:@refill
16556
16557 @example
16558 M-x Info-tagify
16559 M-x Info-split
16560 @end example
16561
16562 @noindent
16563 (Note that the @samp{I} in @samp{Info} is upper case.)@refill
16564
16565 When you use the @code{Info-split} command, the buffer is modified into a
16566 (small) Info file which lists the indirect subfiles.  This file should be
16567 saved in place of the original visited file.  The indirect subfiles are
16568 written in the same directory the original file is in, with names generated
16569 by appending @samp{-} and a number to the original file name.@refill
16570
16571 The primary file still functions as an Info file, but it contains just
16572 the tag table and a directory of subfiles.@refill
16573
16574
16575 @node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top
16576 @appendix Refilling Paragraphs
16577 @cindex Refilling paragraphs
16578 @cindex Filling paragraphs
16579 @findex refill
16580
16581 The @code{@@refill} command refills and, optionally, indents the first
16582 line of a paragraph.@footnote{Perhaps the command should have been
16583 called the @code{@@refillandindent} command, but @code{@@refill} is
16584 shorter and the name was chosen before indenting was possible.} The
16585 @code{@@refill} command is no longer important, but we describe it here
16586 because you once needed it.  You will see it in many old Texinfo
16587 files.@refill
16588
16589 Without refilling, paragraphs containing long @@-constructs may look
16590 bad after formatting because the formatter removes @@-commands and
16591 shortens some lines more than others.  In the past, neither the
16592 @code{texinfo-format-region} command nor the
16593 @code{texinfo-format-buffer} command refilled paragraphs
16594 automatically.  The @code{@@refill} command had to be written at the
16595 end of every paragraph to cause these formatters to fill them.  (Both
16596 @TeX{} and @code{makeinfo} have always refilled paragraphs
16597 automatically.)  Now, all the Info formatters automatically fill and
16598 indent those paragraphs that need to be filled and indented.@refill
16599
16600 The @code{@@refill} command causes @code{texinfo-format-region} and
16601 @code{texinfo-format-buffer} to refill a paragraph in the Info file
16602 @emph{after} all the other processing has been done.  For this reason,
16603 you can not use @code{@@refill} with a paragraph containing either
16604 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
16605 override those two commands.@refill
16606
16607 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
16608 commands now automatically append @code{@@refill} to the end of each
16609 paragraph that should be filled.  They do not append @code{@@refill} to
16610 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
16611 and therefore do not refill or indent them.@refill
16612
16613
16614 @node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top
16615 @comment node-name,  next,  previous,  up
16616 @appendix @@-Command Syntax
16617 @cindex @@-command syntax
16618
16619 The character @samp{@@} is used to start special Texinfo commands.
16620 (It has the same meaning that @samp{\} has in plain @TeX{}.)  Texinfo
16621 has four types of @@-command:@refill
16622
16623 @table @asis
16624 @item 1. Non-alphabetic commands.
16625 These commands consist of an @@ followed by a punctuation mark or other
16626 character that is not part of the alphabet.  Non-alphabetic commands are
16627 almost always part of the text within a paragraph, and never take any
16628 argument.  The two characters (@@ and the other one) are complete in
16629 themselves; none is followed by braces.  The non-alphabetic commands
16630 are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
16631 @code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
16632 @code{@@@}}.@refill
16633
16634 @item 2. Alphabetic commands that do not require arguments.
16635 These commands start with @@ followed by a word followed by left- and
16636 right-hand braces.  These commands insert special symbols in the
16637 document; they do not require arguments.  For example,
16638 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
16639 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
16640 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
16641
16642 @item 3. Alphabetic commands that require arguments within braces.
16643 These commands start with @@ followed by a letter or a word, followed by an
16644 argument within braces.  For example, the command @code{@@dfn} indicates
16645 the introductory or defining use of a term; it is used as follows: @samp{In
16646 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
16647
16648 @item 4. Alphabetic commands that occupy an entire line.
16649 These commands occupy an entire line.  The line starts with @@,
16650 followed by the name of the command (a word); for example, @code{@@center}
16651 or @code{@@cindex}.  If no argument is needed, the word is followed by
16652 the end of the line.  If there is an argument, it is separated from
16653 the command name by a space.  Braces are not used.@refill
16654 @end table
16655
16656 @cindex Braces and argument syntax
16657 Thus, the alphabetic commands fall into classes that have
16658 different argument syntaxes.  You cannot tell to which class a command
16659 belongs by the appearance of its name, but you can tell by the
16660 command's meaning: if the command stands for a glyph, it is in
16661 class 2 and does not require an argument; if it makes sense to use the
16662 command together with other text as part of a paragraph, the command
16663 is in class 3 and must be followed by an argument in braces;
16664 otherwise, it is in class 4 and uses the rest of the line as its
16665 argument.@refill
16666
16667 The purpose of having a different syntax for commands of classes 3 and
16668 4 is to make Texinfo files easier to read, and also to help the GNU
16669 Emacs paragraph and filling commands work properly.  There is only one
16670 exception to this rule: the command @code{@@refill}, which is always
16671 used at the end of a paragraph immediately following the final period
16672 or other punctuation character.  @code{@@refill} takes no argument and
16673 does @emph{not} require braces.  @code{@@refill} never confuses the
16674 Emacs paragraph commands because it cannot appear at the beginning of
16675 a line.@refill
16676
16677
16678 @node Obtaining TeX, Command and Variable Index, Command Syntax, Top
16679 @appendix How to Obtain @TeX{}
16680 @cindex Obtaining @TeX{}
16681 @cindex @TeX{}, how to obtain
16682
16683 @c !!! Here is information about obtaining TeX.  Update it whenever.
16684 @c !!! Also consider updating TeX.README on ftp.gnu.org.
16685 @c     Updated by RJC on 1 March 1995, conversation with MacKay.
16686 @c     Updated by kb@cs.umb.edu on 29 July 1996.
16687 @c     Updated by kb@cs.umb.edu on 25 April 1997.
16688 @c     Updated by kb@cs.umb.edu on 27 February 1998.
16689 @TeX{} is freely redistributable.  You can obtain @TeX{} for Unix
16690 systems via anonymous ftp or on physical media.  The core material
16691 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
16692
16693 Instructions for retrieval by anonymous ftp and information on other
16694 available distributions:
16695 @example
16696 @uref{ftp://tug.org/tex/unixtex.ftp}
16697 @uref{http://tug.org/unixtex.ftp}
16698 @end example
16699
16700 The Free Software Foundation provides a core distribution on its Source
16701 Code CD-ROM suitable for printing Texinfo manuals; the University of
16702 Washington maintains and supports a tape distribution; the @TeX{} Users
16703 Group co-sponsors a complete CD-ROM @TeX{} distribution.
16704
16705 @itemize @bullet
16706
16707 @item
16708 For the FSF Source Code CD-ROM, please contact:
16709
16710 @iftex
16711 @display
16712 @group
16713 Free Software Foundation, Inc.
16714 59 Temple Place Suite 330
16715 Boston, MA @ @ 02111-1307
16716 USA
16717 Telephone: @w{+1-617-542-5942}
16718 Fax: (including Japan) @w{+1-617-542-2652}
16719 Free Dial Fax (in Japan):
16720 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
16721 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
16722 Electronic mail: @code{gnu@@gnu.org}
16723 @end group
16724 @end display
16725 @end iftex
16726 @ifinfo
16727 @display
16728 @group
16729 Free Software Foundation, Inc.
16730 59 Temple Place Suite 330
16731 Boston, MA @w{ } 02111-1307
16732 USA
16733
16734 Telephone: @w{+1-617-542-5942}
16735 Fax: (including Japan) @w{+1-617-542-2652}
16736 Free Dial Fax (in Japan):
16737 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
16738 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
16739 Electronic mail: @code{gnu@@gnu.org}
16740 @end group
16741 @end display
16742 @end ifinfo
16743
16744 @item
16745 To order a complete distribution on CD-ROM, please see
16746 @uref{http://tug.org/tex-live.html}.  (This distribution is also
16747 available by FTP; see the URL's above.)
16748
16749 @item
16750 To order a full distribution from the University of Washington on either
16751 a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge,
16752 send $210 to:
16753
16754 @display
16755 @group
16756 Pierre A. MacKay
16757 Denny Hall, Mail Stop DH-10
16758 University of Washington
16759 Seattle, WA @w{ } 98195
16760 USA
16761 Telephone: +1-206-543-2268
16762 Electronic mail: @code{mackay@@cs.washington.edu}
16763 @end group
16764 @end display
16765
16766 @noindent
16767 Please make checks payable to the University of Washington.
16768 Checks must be in U.S.@: dollars, drawn on a U.S.@: bank.  Overseas
16769 sites: please add to the base cost, if desired, $20.00 for shipment via
16770 air parcel post, or $30.00 for shipment via courier.
16771
16772 @end itemize
16773
16774 Many other @TeX{} distributions are available; see
16775 @uref{http://tug.org/}.
16776
16777
16778 @c These are no longer ``new'', and the explanations
16779 @c are all given elsewhere anyway, I think.  --karl, 25apr97.
16780 @ignore (the entire appendix)
16781 @c node New Features, Command and Variable Index, Obtaining TeX, Top
16782 @c appendix Second Edition Features
16783
16784 @tex
16785 % Widen the space for the first column so three control-character
16786 % strings fit in the first column.  Switched back to default .8in
16787 % value at end of chapter.
16788 \global\tableindent=1.0in
16789 @end tex
16790
16791 The second edition of the Texinfo manual describes more than 20 new
16792 Texinfo mode commands and more than 50 previously undocumented Texinfo
16793 @@-commands.  This edition is more than twice the length of the first
16794 edition.@refill
16795
16796 Here is a brief description of the new commands.@refill
16797
16798 @menu
16799 * New Texinfo Mode Commands::   The updating commands are especially useful.
16800 * New Commands::                Many newly described @@-commands.
16801 @end menu
16802
16803 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
16804 @c appendixsec New Texinfo Mode Commands
16805
16806 Texinfo mode provides commands and features especially designed for
16807 working with Texinfo files.  More than 20 new commands have been
16808 added, including commands for automatically creating and updating
16809 both nodes and menus.  This is a tedious task when done by hand.@refill
16810
16811 The keybindings are intended to be somewhat mnemonic.@refill
16812
16813 @c subheading Update all nodes and menus
16814
16815 The @code{texinfo-master-menu} command is the primary command:
16816
16817 @table @kbd
16818 @item C-c C-u m
16819 @itemx M-x texinfo-master-menu
16820 Create or update a master menu.
16821 With @kbd{C-u} as a prefix argument,
16822 first create or update all nodes
16823 and regular menus.
16824 @end table
16825
16826 @c subheading Update Pointers
16827
16828 @noindent
16829 Create or update `Next', `Previous', and `Up' node pointers.@refill
16830
16831 @noindent
16832 @xref{Updating Nodes and Menus}.
16833
16834 @table @kbd
16835 @item C-c C-u C-n
16836 @itemx M-x texinfo-update-node
16837 Update a node.
16838
16839 @item C-c C-u C-e
16840 @itemx M-x texinfo-every-node-update
16841 Update every node in the buffer.
16842 @end table
16843
16844 @c subheading Update Menus
16845
16846 @noindent
16847 Create or update menus.@refill
16848
16849 @noindent
16850 @xref{Updating Nodes and Menus}.
16851
16852 @table @kbd
16853 @item C-c C-u C-m
16854 @itemx M-x texinfo-make-menu
16855 Make or update a menu.
16856
16857 @item C-c C-u C-a
16858 @itemx M-x texinfo-all-menus-update
16859 Make or update all the menus in a buffer.
16860 With @kbd{C-u} as a prefix argument,
16861 first update all the nodes.
16862 @end table
16863
16864 @c subheading Insert Title as Description
16865
16866 @noindent
16867 Insert a node's chapter or section title in the space for the
16868 description in a menu entry line; position point so you can edit the
16869 insert.  (This command works somewhat differently than the other
16870 insertion commands, which insert only a predefined string.)@refill
16871
16872 @noindent
16873 @xref{Inserting, Inserting Frequently Used Commands}.
16874
16875 @table @kbd
16876 @item C-c C-c C-d
16877 Insert title.
16878 @end table
16879
16880 @c subheading Format for Info
16881
16882 @noindent
16883 Provide keybindings both for the Info formatting commands that are
16884 written in Emacs Lisp and for @code{makeinfo} that is written in
16885 C.@refill
16886
16887 @noindent
16888 @xref{Info Formatting}.
16889
16890 @noindent
16891 Use the Emacs lisp @code{texinfo-format@dots{}} commands:
16892
16893 @table @kbd
16894 @item C-c C-e C-r
16895 Format the region.
16896
16897 @item C-c C-e C-b
16898 Format the buffer.
16899 @end table
16900
16901 @noindent
16902 Use @code{makeinfo}:
16903
16904 @table @kbd
16905 @item C-c C-m C-r
16906 Format the region.
16907
16908 @item C-c C-m C-b
16909 Format the buffer.
16910
16911 @item C-c C-m C-l
16912 Recenter the @code{makeinfo} output buffer.
16913
16914 @item C-c C-m C-k
16915 Kill the @code{makeinfo} formatting job.
16916 @end table
16917
16918 @c subheading Typeset and Print
16919
16920 @noindent
16921 Typeset and print Texinfo documents from within Emacs.@refill
16922
16923 @ifinfo
16924 @noindent
16925 @xref{Printing}.
16926 @end ifinfo
16927 @iftex
16928 @noindent
16929 @xref{Printing, , Formatting and Printing}.
16930 @end iftex
16931
16932 @table @kbd
16933 @item C-c C-t C-b
16934 Run @code{texi2dvi} on the buffer.
16935
16936 @item C-c C-t C-r
16937 Run @TeX{} on the region.
16938
16939 @item C-c C-t C-i
16940 Run @code{texindex}.
16941
16942 @item C-c C-t C-p
16943 Print the DVI file.
16944
16945 @item C-c C-t C-q
16946 Show the print queue.
16947
16948 @item C-c C-t C-d
16949 Delete a job from the print queue.
16950
16951 @item C-c C-t C-k
16952 Kill the current @TeX{} formatting job.
16953
16954 @item C-c C-t C-x
16955 Quit a currently stopped @TeX{} formatting job.
16956
16957 @item C-c C-t C-l
16958 Recenter the output buffer.
16959 @end table
16960
16961 @c subheading Other Updating Commands
16962
16963 @noindent
16964 The ``other updating commands'' do not have standard keybindings because
16965 they are used less frequently.@refill
16966
16967 @noindent
16968 @xref{Other Updating Commands}.
16969
16970 @table @kbd
16971 @item M-x texinfo-insert-node-lines
16972 Insert missing @code{@@node} lines using
16973 section titles as node names.
16974
16975 @item M-x texinfo-multiple-files-update
16976 Update a multi-file document.
16977 With a numeric prefix, such as @kbd{C-u 8},
16978 update  @strong{every} pointer and
16979 menu in @strong{all} the files and
16980 then insert a master menu.
16981
16982 @item M-x texinfo-indent-menu-description
16983 Indent descriptions in menus.
16984
16985 @item M-x texinfo-sequential-node-update
16986 Insert node pointers in strict sequence.
16987 @end table
16988
16989 @c node New Commands,  , New Texinfo Mode Commands, Obtaining TeX
16990 @c appendixsec New Texinfo @@-Commands
16991
16992 The second edition of the Texinfo manual describes more than 50
16993 commands that were not described in the first edition.  A third or so
16994 of these commands existed in Texinfo but were not documented in the
16995 manual; the others are new.  Here is a listing, with brief
16996 descriptions of them:@refill
16997
16998 @c subheading Indexing
16999
17000 @noindent
17001 Create your own index, and merge indices.@refill
17002
17003 @noindent
17004 @xref{Indices}.
17005
17006 @table @kbd
17007 @item @@defindex @var{index-name}
17008 Define a new index and its indexing command.
17009 See also the @code{@@defcodeindex} command.
17010
17011 @c written verbosely to avoid overfull hbox
17012 @item @@synindex @var{from-index} @var{into-index}
17013 Merge the @var{from-index} index into the @var{into-index} index.
17014 See also the @code{@@syncodeindex} command.
17015 @end table
17016
17017 @c subheading Definitions
17018
17019 @noindent
17020 Describe functions, variables, macros,
17021 commands, user options, special forms, and other such artifacts in a
17022 uniform format.@refill
17023
17024 @noindent
17025 @xref{Definition Commands}.
17026
17027 @table @kbd
17028 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
17029 Format a description for functions, interactive
17030 commands, and similar entities.
17031
17032 @item @@defvr, @@defop, @dots{}
17033 15 other related commands.
17034 @end table
17035
17036 @c subheading Glyphs
17037
17038 @noindent
17039 Indicate the results of evaluation, expansion,
17040 printed output, an error message, equivalence of expressions, and the
17041 location of point.@refill
17042
17043 @noindent
17044 @xref{Glyphs}.
17045
17046 @table @kbd
17047 @item @@equiv@{@}
17048 @itemx @equiv{}
17049 Equivalence:
17050
17051 @item @@error@{@}
17052 @itemx @error{}
17053 Error message
17054
17055 @item @@expansion@{@}
17056 @itemx @expansion{}
17057 Macro expansion
17058
17059 @item @@point@{@}
17060 @itemx @point{}
17061 Position of point
17062
17063 @item @@print@{@}
17064 @itemx @print{}
17065 Printed output
17066
17067 @item @@result@{@}
17068 @itemx @result{}
17069 Result of an expression
17070 @end table
17071
17072 @c subheading Page Headings
17073
17074 @noindent
17075 Customize page headings.
17076
17077 @noindent
17078 @xref{Headings}.
17079
17080 @table @kbd
17081 @item @@headings @var{on-off-single-double}
17082 Headings on or off, single, or double-sided.
17083
17084 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
17085 Footings for even-numbered (left-hand) pages.
17086
17087 @item @@evenheading, @@everyheading, @@oddheading, @dots{}
17088 Five other related commands.
17089
17090 @item @@thischapter
17091 Insert name of chapter and chapter number.
17092
17093 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
17094 Related commands.
17095 @end table
17096
17097 @c subheading Formatting
17098
17099 @noindent
17100 Format blocks of text.
17101
17102 @noindent
17103 @xref{Quotations and Examples}, and@*
17104 @ref{Lists and Tables, , Making Lists and Tables}.
17105
17106 @table @kbd
17107 @item @@cartouche
17108 Draw rounded box surrounding text (not in Info).
17109
17110 @item @@enumerate @var{optional-arg}
17111 Enumerate a list with letters or numbers.
17112
17113 @item @@exdent @var{line-of-text}
17114 Remove indentation.
17115
17116 @item @@flushleft
17117 Left justify.
17118
17119 @item @@flushright
17120 Right justify.
17121
17122 @item @@format
17123 Do not narrow nor change font.
17124
17125 @item @@ftable @var{formatting-command}
17126 @itemx @@vtable @var{formatting-command}
17127 Two-column table with indexing.
17128
17129 @item @@lisp
17130 For an example of Lisp code.
17131
17132 @item @@smallexample
17133 @itemx @@smalllisp
17134 Like @@table and @@lisp @r{but for} @@smallbook.
17135 @end table
17136
17137 @c subheading Conditionals
17138
17139 @noindent
17140 Conditionally format text.
17141
17142 @noindent
17143 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
17144
17145 @table @kbd
17146 @item @@set @var{flag} [@var{string}]
17147 Set a flag.  Optionally, set value
17148 of @var{flag} to @var{string}.
17149
17150 @item @@clear @var{flag}
17151 Clear a flag.
17152
17153 @item @@value@{@var{flag}@}
17154 Replace with value to which @var{flag} is set.
17155
17156 @item @@ifset @var{flag}
17157 Format, if @var{flag} is set.
17158
17159 @item @@ifclear @var{flag}
17160 Ignore, if @var{flag} is set.
17161 @end table
17162
17163 @c subheading @@heading series for Titles
17164
17165 @noindent
17166 Produce unnumbered headings that do not appear in a table of contents.
17167
17168 @noindent
17169 @xref{Structuring}.
17170
17171 @table @kbd
17172 @item @@heading @var{title}
17173 Unnumbered section-like heading not listed
17174 in the table of contents of a printed manual.
17175
17176 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
17177 Related commands.
17178 @end table
17179
17180 @need 1000
17181 @c subheading Font commands
17182
17183 @need 1000
17184 @noindent
17185 @xref{Smallcaps}, and @*
17186 @ref{Fonts}.
17187
17188 @table @kbd
17189 @item @@r@{@var{text}@}
17190 Print in roman font.
17191
17192 @item @@sc@{@var{text}@}
17193 Print in @sc{small caps} font.
17194 @end table
17195
17196 @c subheading Miscellaneous
17197
17198 @noindent
17199 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
17200 see @ref{Customized Highlighting},@*
17201 see @ref{Overfull hboxes},@*
17202 see @ref{Footnotes},@*
17203 see @ref{dmn, , Format a Dimension},@*
17204 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
17205 see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@*
17206 see @ref{minus, , Inserting a Minus Sign},@*
17207 see @ref{paragraphindent, , Paragraph Indenting},@*
17208 see @ref{Cross Reference Commands},@*
17209 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
17210 see @ref{Custom Headings, , How to Make Your Own Headings}.
17211
17212 @table @kbd
17213 @item @@author @var{author}
17214 Typeset author's name.
17215
17216 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
17217 @c Define a highlighting command for Info.  (Info only.)
17218
17219 @item @@finalout
17220 Produce cleaner printed output.
17221
17222 @item @@footnotestyle @var{end-or-separate}
17223 Specify footnote style.
17224
17225 @item @@dmn@{@var{dimension}@}
17226 Format a dimension.
17227
17228 @item @@global@@let@var{new-cmd}=@var{existing-cmd}
17229 Define a highlighting command for @TeX{}. (@TeX{} only.)
17230
17231 @item @@lowersections
17232 Reduce hierarchical level of sectioning commands.
17233
17234 @item @@math@{@var{mathematical-expression}@}
17235 Format a mathematical expression.
17236
17237 @item @@minus@{@}
17238 Generate a minus sign.
17239
17240 @item @@paragraphindent @var{asis-or-number}
17241 Specify paragraph indentation.
17242
17243 @item @@raisesections
17244 Raise hierarchical level of sectioning commands.
17245
17246 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
17247 Make a reference.  In the printed manual, the
17248 reference does not start with the word `see'.
17249
17250 @item @@title @var{title}
17251 Typeset @var{title} in the alternative
17252 title page format.
17253
17254 @item @@subtitle @var{subtitle}
17255 Typeset @var{subtitle} in the alternative
17256 title page format.
17257
17258 @item @@today@{@}
17259 Insert the current date.
17260 @end table
17261 @tex
17262 % Switch width of first column of tables back to default value
17263 \global\tableindent=.8in
17264 @end tex
17265 @end ignore
17266
17267 @node Command and Variable Index, Concept Index, Obtaining TeX, Top
17268 @comment  node-name,  next,  previous,  up
17269 @unnumbered Command and Variable Index
17270
17271 This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
17272 functions, and several variables.  To make the list easier to use, the
17273 commands are listed without their preceding @samp{@@}.@refill
17274
17275 @printindex fn
17276
17277
17278 @node Concept Index,  , Command and Variable Index, Top
17279 @unnumbered Concept Index
17280
17281 @printindex cp
17282
17283
17284 @summarycontents
17285 @contents
17286 @bye