1 \input texinfo.tex @c -*-texinfo-*-
2 @c $Id: texinfo.txi,v 1.50 1998/02/27 21:21:34 karl Exp $
5 @c All text is ignored before the setfilename.
6 @setfilename ../info/texinfo
7 @settitle Texinfo @value{edition}
9 @c Edition number is now the same as the Texinfo distribution version number.
11 @set update-month February 1998
12 @set update-date 27 @value{update-month}
14 @c Define a new index for options.
16 @c Put everything except function (command, in this case) names in one
17 @c index (arbitrarily chosen to be the concept index).
22 @footnotestyle separate
25 @comment %**end of header
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.
30 @dircategory Texinfo documentation system
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.
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.
47 @c Currently undocumented command, 5 December 1993:
48 @c nwnode (Same as node, but no warnings; for `makeinfo'.)
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.
54 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98
55 Free Software Foundation, Inc.
57 This edition is for Texinfo version @value{edition}.
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.
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).
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.
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.
81 @setchapternewpage odd
83 @shorttitlepage Texinfo
86 @c use the new format for titles
88 @subtitle The GNU Documentation Format
89 @subtitle for Texinfo version @value{edition}
90 @subtitle @value{update-month}
92 @author Robert J.@: Chassell
93 @author Richard M.@: Stallman
95 @c Include the Distribution inside the titlepage so
96 @c that headings are turned off.
99 @vskip 0pt plus 1filll
100 Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98
101 Free Software Foundation, Inc.
103 Published by the Free Software Foundation @*
104 59 Temple Place Suite 330 @*
105 Boston, MA 02111-1307 @*
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.
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.
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.
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.
125 Cover art by Etienne Suvasa.
129 @node Top, Copying, (dir), (dir)
132 Texinfo is a documentation system that uses a single source file to
133 produce both on-line information and printed output.@refill
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
139 This is Edition @value{edition} of the Texinfo documentation,
140 @w{@value{update-date}}.
143 @c Here is a spare copy of the chapter menu entry descriptions,
144 @c in case they are accidently deleted
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.
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
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.
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
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
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.
232 --- The Detailed Node Listing ---
236 * Using Texinfo:: Create a conventional printed book
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.
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.
261 Updating Nodes and Menus
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
270 Beginning a Texinfo File
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.
281 The Texinfo File Header
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.
291 The Title and Copyright Pages
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
302 * headings on off:: An option for turning headings on and off
303 and double or single sided printing.
305 The `Top' Node and Master Menu
307 * Title of Top Node:: Sketch what the file is about.
308 * Master Menu Parts:: A master menu has three or more parts.
310 Ending a Texinfo File
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.
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.
323 * unnumbered & appendix::
324 * majorheading & chapheading::
326 * unnumberedsec appendixsec heading::
328 * unnumberedsubsec appendixsubsec subheading::
329 * subsubsection:: Commands for the lowest level sections.
330 * Raise/lower sections:: How to change commands' hierarchical level.
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}.
340 The @code{@@node} Command
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.
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.
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.
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.
379 Marking Words and Phrases
381 * Indicating:: How to indicate definitions, files, etc.
382 * Emphasis:: How to emphasize text.
384 Indicating Definitions, Commands, etc.
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.
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.
405 Quotations and Examples
407 * Block Enclosing Commands:: Use different constructs for
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
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.
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.
429 Making a Two-column Table
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.
437 * Multitable Column Widths:: Defining multitable column widths.
438 * Multitable Rows:: Defining multitable rows, with examples.
442 * Index Entries:: Choose different words for index entries.
443 * Predefined Indices:: Use different indices for different kinds
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.
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.
458 * Braces Atsigns:: How to insert braces, @samp{@@}.
459 * Inserting Space:: How to insert the right amount of space
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.
472 Inserting @@ and Braces
474 * Inserting An Atsign:: How to insert @samp{@@}.
475 * Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
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.
484 Inserting Ellipsis, Dots, and Bullets
486 * dots:: How to insert dots @dots{}
487 * bullet:: How to insert a bullet.
489 Inserting @TeX{} and the Copyright Symbol
491 * tex:: How to insert the @TeX{} logo.
492 * copyright symbol:: How to use @code{@@copyright}@{@}.
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.
513 Making and Preventing Breaks
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.
526 * Def Cmd Template:: How to structure a description using a
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::
534 The Definition Commands
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.
545 * Footnote Commands:: How to write a footnote in Texinfo.
546 * Footnote Styles:: Controlling how footnotes appear in Info.
548 Conditionally Visible Text
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.
557 @code{@@set}, @code{@@clear}, and @code{@@value}
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.
563 Macros: Defining New Texinfo Commands
565 * Defining Macros:: Both defining and undefining new commands.
566 * Invoking Macros:: Using a macro, once you've defined it.
568 Format and Print Hardcopy
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.
585 Creating an Info File
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
595 * Batch Formatting:: How to format for Info in Emacs Batch mode.
596 * Tag and Split Files:: How tagged and split files help Info
599 Installing an Info File
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.
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.
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.
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.
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.
642 Finding Badly Referenced Nodes
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.
651 @c * New Texinfo Mode Commands:: The updating commands are especially useful.
652 @c * New Commands:: Many newly described @@-commands.
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
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
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
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
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
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
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
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
720 * Using Texinfo:: Create a conventional printed book
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.
734 @node Using Texinfo, Info Files, Overview, Overview
736 @heading Using Texinfo
739 Using Texinfo, you can create a printed document with the normal
740 features of a book, including chapters, sections, cross references,
741 and indices. From the same Texinfo source file, you can create a
742 menu-driven, on-line Info file with nodes, menus, cross references,
743 and indices. You can, if you wish, make the chapters and sections of
744 the printed document correspond to the nodes of the on-line
745 information; and you use the same cross references and indices for
746 both the Info file and the printed work. @cite{The GNU
747 Emacs Manual} is a good example of a Texinfo file, as is this manual.@refill
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
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
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
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
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
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
785 @node Info Files, Printed Books, Using Texinfo, Overview
786 @comment node-name, next, previous, up
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
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
803 @inforef{Top, info, info}, for more information about using Info.@refill
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
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
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
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
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
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}).
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
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
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
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
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.}
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
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
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
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
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
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
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
936 @xref{Obtaining TeX, , How to Obtain @TeX{}}.
939 @node Formatting Commands, Conventions, Printed Books, Overview
940 @comment node-name, next, previous, up
943 @cindex Formatting commands
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
953 @strong{Please note:} All the @@-commands, with the exception of the
954 @code{@@TeX@{@}} command, must be written entirely in lower
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
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
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
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
991 Write a command such as @code{@@dots@{@}} wherever you wish but usually
992 within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
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
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
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
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
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
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
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
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
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.
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
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}.
1077 @cindex Tabs; don't use!
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.
1087 To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1088 spaces when you press the @key{TAB} key.@refill
1091 Also, you can run @code{untabify} in Emacs to convert tabs in a region
1092 to multiple spaces.@refill
1098 @node Comments, Minimum, Conventions, Overview
1099 @comment node-name, next, previous, up
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
1116 @findex c @r{(comment)}
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
1131 @c !!! Perhaps include this comment about ignore and ifset:
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.
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
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
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
1162 @@setfilename @var{info-file-name}
1163 @@settitle @var{name-of-manual}
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
1175 @findex input @r{(@TeX{} command)}
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
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
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
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
1203 In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1204 Texinfo mode when you edit the file.
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
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
1216 @node Six Parts, Short Sample, Minimum, Overview
1217 @comment node-name, next, previous, up
1218 @section Six Parts of a Texinfo File
1220 Generally, a Texinfo file contains more than the minimal
1221 beginning and end---it usually contains six parts:@refill
1225 The @dfn{Header} names the file, tells @TeX{} which definitions' file to
1226 use, and performs other ``housekeeping'' tasks.@refill
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
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
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
1246 The @dfn{Body} of the document may be structured like a traditional book or
1247 encyclopedia or it may be free form.@refill
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
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
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
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}.
1272 @subheading Part 1: Header
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.
1281 \input texinfo @@c -*-texinfo-*-
1282 @@c %**start of header
1283 @@setfilename sample.info
1284 @@settitle Sample Document
1285 @@c %**end of header
1287 @@setchapternewpage odd
1291 @subheading Part 2: Summary Description and Copyright
1294 The summary description and copyright segment does not
1295 appear in the printed document.
1300 This is a short example of a complete Texinfo file.
1302 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
1307 @subheading Part 3: Titlepage and Copyright
1310 The titlepage segment does not appear in the Info file.
1316 @@comment The title is printed in a large font.
1317 @@center @@titlefont@{Sample Title@}
1321 @@c The following two commands start the copyright page.
1323 @@vskip 0pt plus 1filll
1324 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
1329 @subheading Part 4: `Top' Node and Master Menu
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.
1338 @@node Top, First Chapter, , (dir)
1339 @@comment node-name, next, previous, up
1346 * First Chapter:: The first chapter is the
1347 only chapter in this sample.
1348 * Concept Index:: This index has two entries.
1353 @subheading Part 5: The Body of the Document
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
1362 @@node First Chapter, Concept Index, Top, Top
1363 @@comment node-name, next, previous, up
1364 @@chapter First Chapter
1365 @@cindex Sample index entry
1369 This is the contents of the first chapter.
1370 @@cindex Another sample index entry
1374 Here is a numbered list.
1378 This is the first item.
1381 This is the second item.
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
1393 @subheading Part 6: The End of the Document
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
1403 @@node Concept Index, , First Chapter, Top
1404 @@comment node-name, next, previous, up
1405 @@unnumbered Concept Index
1416 @subheading The Results
1418 Here is what the contents of the first chapter of the sample look like:
1423 This is the contents of the first chapter.
1425 Here is a numbered list.
1429 This is the first item.
1432 This is the second item.
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
1441 @node Acknowledgements, , Short Sample, Overview
1442 @comment node-name, next, previous, up
1443 @section Acknowledgements
1445 @cindex Stallman, Richard M.
1446 @cindex Chassell, Robert J.
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
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.
1462 Please send suggestions and corrections to:
1466 @r{Internet address:}
1467 bug-texinfo@@gnu.org
1472 Please include the manual's edition number and update date in your messages.
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
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
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
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.
1506 @node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
1508 @heading Texinfo Mode Overview
1511 Texinfo mode provides special features for working with Texinfo
1516 Insert frequently used @@-commands. @refill
1519 Automatically create @code{@@node} lines.
1522 Show the structure of a Texinfo source file.@refill
1525 Automatically create or update the `Next',
1526 `Previous', and `Up' pointers of a node.
1529 Automatically create or update menus.@refill
1532 Automatically create a master menu.@refill
1535 Format a part or all of a file for Info.@refill
1538 Typeset and print part or all of a file.@refill
1541 Perhaps the two most helpful features are those for inserting frequently
1542 used @@-commands and for creating node pointers and menus.@refill
1544 @node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
1545 @section The Usual GNU Emacs Editing Commands
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
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
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
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
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
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
1592 Texinfo mode provides commands to insert various frequently used
1593 @@-commands into the buffer. You can use these commands to save
1596 The insert commands are invoked by typing @kbd{C-c} twice and then the
1597 first letter of the @@-command:@refill
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
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
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
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
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
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
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
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
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
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
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
1670 @c M-@{ was the binding for texinfo-insert-braces;
1671 @c in Emacs 19, backward-paragraph will take this binding.
1673 @itemx M-x texinfo-insert-braces
1674 @findex texinfo-insert-braces
1675 Insert @code{@{@}} and put the cursor between the braces.@refill
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
1821 @node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
1823 @subheading The Updating Commands
1826 You can use the updating commands@refill
1830 to insert or update the `Next', `Previous', and `Up' pointers of a
1834 to insert or update the menu for a section, and@refill
1837 to create a master menu for a Texinfo source file.@refill
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
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
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.
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'
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
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
1878 The @code{texinfo-master-menu} command is the primary command:@refill
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
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
1893 For @code{texinfo-master-menu} to work, the Texinfo file must have a
1894 `Top' node and at least one subsequent node.@refill
1896 After extensively editing a Texinfo file, you can type the following:
1899 C-u M-x texinfo-master-menu
1905 This updates all the nodes and menus completely and all at once.@refill
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
1913 The commands are:@refill
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
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
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
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
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
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
1961 When working on a document that does not merit a master menu, you can
1967 C-u M-x texinfo-all-menus-update
1971 This updates all the nodes and menus.@refill
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
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
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
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
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
2008 Each @code{@@node} line/structuring-command line combination
2009 must look either like this:@refill
2013 @@node Comments, Minimum, Conventions, Overview
2014 @@comment node-name, next, previous, up
2019 or like this (without the @code{@@comment} line):
2023 @@node Comments, Minimum, Conventions, Overview
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
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
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
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
2051 @node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
2052 @comment node-name, next, previous, up
2053 @subsection Other Updating Commands
2055 In addition to the five major updating commands, Texinfo mode
2056 possesses several less frequently used updating commands:@refill
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
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
2073 For example, the following marks a whole buffer as a region and inserts
2074 @code{@@node} lines and titles throughout:@refill
2077 C-x h C-u M-x texinfo-insert-node-lines
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
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.
2096 @xref{texinfo-multiple-files-update}.@refill
2099 @xref{texinfo-multiple-files-update, ,
2100 @code{texinfo-multiple-files-update}}.@refill
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
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
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
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
2138 You can use either the @code{texinfo-format-region} or the
2139 @code{makeinfo-region} command to format a region:@refill
2142 @findex texinfo-format-region
2144 @itemx M-x texinfo-format-region
2146 @itemx M-x makeinfo-region
2147 Format the current region for Info.@refill
2150 You can use either the @code{texinfo-format-buffer} or the
2151 @code{makeinfo-buffer} command to format a whole buffer:@refill
2154 @findex texinfo-format-buffer
2156 @itemx M-x texinfo-format-buffer
2158 @itemx M-x makeinfo-buffer
2159 Format the current buffer for Info.@refill
2163 For example, after writing a Texinfo file, you can type the following:
2168 C-u M-x texinfo-master-menu
2172 This updates all the nodes and menus. Then type the following to create
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
2184 @xref{Create an Info File}, for details about Info formatting.@refill
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
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}).
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
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
2218 @itemx M-x texinfo-tex-region
2219 @findex texinfo-tex-region
2220 Run @TeX{} on the region.@refill
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
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
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
2247 @xref{Format/Print Hardcopy}, for a description of the other @TeX{} related
2248 commands, such as @code{tex-show-print-queue}.@refill
2250 @node Texinfo Mode Summary, , Printing, Texinfo Mode
2251 @comment node-name, next, previous, up
2252 @section Texinfo Mode Summary
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
2259 @subheading Insert Commands
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
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.}
2276 C-c C-c @} @r{Move out of enclosing braces.}
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.}
2285 @subheading Show Structure
2287 The @code{texinfo-show-structure} command is often used within a
2288 narrowed region.@refill
2291 C-c C-s @r{List all the headings.}
2294 @subheading The Master Update Command
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
2302 M-x texinfo-master-menu
2303 @r{Create or update a master menu.}
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.}
2313 @subheading Update Pointers
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
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.}
2324 @subheading Update Menus
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
2333 C-c C-u C-m @r{Make or update a menu.}
2336 C-c C-u C-a @r{Make or update all}
2337 @r{menus in a buffer.}
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.}
2347 @subheading Format for Info
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
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
2359 Use the @code{texinfo-format@dots{}} commands:
2363 C-c C-e C-r @r{Format the region.}
2364 C-c C-e C-b @r{Format the buffer.}
2370 Use @code{makeinfo}:
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.}
2379 @subheading Typeset and Print
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},
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.}
2398 @subheading Other Updating Commands
2400 The `other updating commands' do not have standard keybindings because
2401 they are rarely used.
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.}
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.}
2420 M-x texinfo-indent-menu-description
2421 @r{Indent descriptions.}
2425 M-x texinfo-sequential-node-update
2426 @r{Insert node pointers in strict sequence.}
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
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
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.
2452 @node Four Parts, Sample Beginning, Beginning a File, Beginning a File
2454 @heading Four Parts Begin a File
2457 Generally, the beginning of a Texinfo file has four parts:@refill
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
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
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
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
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
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
2491 @node Sample Beginning, Header, Four Parts, Beginning a File
2492 @comment node-name, next, previous, up
2493 @section Sample Texinfo File Beginning
2495 The following sample shows what is needed.@refill
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
2506 This file documents @dots{}
2508 Copyright @var{year} @var{copyright-owner}
2511 Permission is granted to @dots{}
2516 @@c This title page illustrates only one of the
2517 @@c two methods of forming a title page.
2522 @@title @var{name-of-manual-when-printed}
2523 @@subtitle @var{subtitle-if-any}
2524 @@subtitle @var{second-subtitle}
2525 @@author @var{author}
2529 @@c The following two commands
2530 @@c start the copyright page.
2532 @@vskip 0pt plus 1filll
2533 Copyright @@copyright@{@} @var{year} @var{copyright-owner}
2536 Published by @dots{}
2538 Permission is granted to @dots{}
2541 @@node Top, Overview, , (dir)
2544 This document describes @dots{}
2546 This document applies to version @dots{}
2547 of the program named @dots{}
2552 * Copying:: Your rights and freedoms.
2553 * First Chapter:: Getting started @dots{}
2554 * Second Chapter:: @dots{}
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
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
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
2582 Thus, the beginning of a Texinfo file looks like this:
2586 \input texinfo @@c -*-texinfo-*-
2587 @@setfilename sample.info
2588 @@settitle Sample Document
2597 \input texinfo @@c -*-texinfo-*-
2598 @@c %**start of header
2599 @@setfilename sample.info
2600 @@settitle Sample Document
2601 @@c %**end of header
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.
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
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
2626 \input texinfo @@c -*-texinfo-*-
2630 This line serves two functions:
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
2644 When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2645 specification tells Emacs to use Texinfo mode.@refill
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
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
2659 With these lines, you can format part of a Texinfo file for Info or
2660 typeset part for printing.@refill
2662 A start-of-header line looks like this:@refill
2665 @@c %**start of header
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
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}
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:
2681 @@setfilename @var{info-file-name}
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
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.
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}.
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.
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{}}).
2719 @node settitle, setchapternewpage, setfilename, Header
2720 @comment node-name, next, previous, up
2721 @subsection @code{@@settitle}
2724 In order to be made into a printed manual, a Texinfo file must contain
2725 a line that looks like this:@refill
2728 @@settitle @var{title}
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
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
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
2748 The @code{@@settitle} command should precede everything that generates
2749 actual output in @TeX{}.@refill
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
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
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
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
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
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
2787 Write the @code{@@setchapternewpage} command at the beginning of a
2788 line followed by its argument.@refill
2790 For example, you would write the following to cause each chapter to
2791 start on a fresh odd-numbered page:@refill
2794 @@setchapternewpage odd
2797 You can specify one of three alternatives with the
2798 @code{@@setchapternewpage} command:@refill
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
2809 The result is exactly the same as when you write
2810 @code{@@setchapternewpage on}.@refill
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
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
2824 This alternative is the default.@refill
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
2833 Texinfo does not have an @code{@@setchapternewpage even} command.@refill
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
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
2845 Since an Info file does not have pages, the @code{@@setchapternewpage}
2846 command has no effect on it.@refill
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
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
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
2869 @@paragraphindent @var{indent}
2872 The Info formatting commands indent according to the value of
2873 @var{indent}:@refill
2877 If the value of @var{indent} is @samp{asis}, the Info formatting
2878 commands do not change the existing indentation.@refill
2881 If the value of @var{indent} is zero, the Info formatting commands delete
2882 existing indentation.@refill
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
2889 The default value of @var{indent} is @samp{asis}.@refill
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
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
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
2907 Follow the header lines with an @w{end-of-header} line.
2908 An end-of-header line looks like this:@refill
2911 @@c %**end of header
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
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
2925 The start-of-header line and the end-of-header line are Texinfo mode
2926 variables that you can change.@refill
2930 @xref{Start of Header}.
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
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
2943 The copyright notice should read:@refill
2946 Copyright @var{year} @var{copyright-owner}
2950 and be put on a line by itself.@refill
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
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
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
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
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
2976 @xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the
2977 standard text for the copyright permissions.@refill
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
2989 * headings on off:: An option for turning headings on and off
2990 and double or single sided printing.
2993 @node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
2994 @comment node-name, next, previous, up
2995 @subsection @code{@@titlepage}
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
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
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
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
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
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
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}
3055 @findex sp @r{(titlepage line spacing)}
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
3061 Use the @code{@@titlefont} command to select a large font suitable for
3062 the title itself.@refill
3068 @@titlefont@{Texinfo@}
3071 Use the @code{@@center} command at the beginning of a line to center
3072 the remaining text on that line. Thus,@refill
3075 @@center @@titlefont@{Texinfo@}
3079 centers the title, which in this example is ``Texinfo'' printed
3080 in the title font.@refill
3082 Use the @code{@@sp} command to insert vertical space. For example:@refill
3089 This inserts two blank lines on the printed page. (@xref{sp, ,
3090 @code{@@sp}}, for more information about the @code{@@sp}
3093 A template for this method looks like this:@refill
3099 @@center @@titlefont@{@var{name-of-manual-when-printed}@}
3101 @@center @var{subtitle-if-any}
3103 @@center @var{author}
3109 The spacing of the example fits an 8 1/2 by 11 inch manual.@refill
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}
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
3122 the previous section, in which the @code{@@sp} command is needed to
3123 adjust vertical spacing.@refill
3125 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3126 commands at the beginning of a line followed by the title, subtitle,
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
3133 The @code{@@subtitle} command sets subtitles in a normal-sized font
3134 flush to the right-hand side of the page.@refill
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
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
3148 @@author by Jane Smith and John Doe
3152 or you can write the names one above each other by using two (or more)
3153 @code{@@author} commands:@refill
3163 (Only the bottom name is underlined with a black rule.)@refill
3166 A template for this method looks like this:@refill
3171 @@title @var{name-of-manual-when-printed}
3172 @@subtitle @var{subtitle-if-any}
3173 @@subtitle @var{second-subtitle}
3174 @@author @var{author}
3183 Contrast this form with the form of a title page written using the
3184 @code{@@sp}, @code{@@center}, and @code{@@titlefont} commands:@refill
3189 @@center @@titlefont@{Name of Manual When Printed@}
3191 @@center Subtitle, If Any
3193 @@center Second subtitle
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
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
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
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
3228 @@vskip 0pt plus 1filll
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
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
3246 Copyright @copyright{} @var{year} @var{copyright-owner}
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
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
3259 @xref{Sample Permissions}, for the standard text.@refill
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
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.
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
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
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
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
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
3305 @node headings on off, , end titlepage, Titlepage & Copyright Page
3306 @comment node-name, next, previous, up
3307 @subsection The @code{@@headings} Command
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
3318 You can use @code{@@headings} as follows:@refill
3321 @item @@headings off
3322 Turn off printing of page headings.@refill
3324 @item @@headings single
3325 Turn on page headings appropriate for single-sided printing.
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
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.
3339 Turn on page headings: @code{single} if @samp{@@setchapternewpage
3340 on}, @code{double} otherwise.
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.
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
3360 The @code{@@headings off} command overrides the @code{@@end titlepage}
3361 command, which would otherwise cause @TeX{} to print page
3364 You can also specify your own style of page heading and footing.
3365 @xref{Headings, , Page Headings}, for more information.@refill
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
3374 The `Top' node is the node from which you enter an Info file.@refill
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
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
3391 * Title of Top Node:: Sketch what the file is about.
3392 * Master Menu Parts:: A master menu has three or more parts.
3395 @node Title of Top Node, Master Menu Parts, The Top Node, The Top Node
3397 @subheading `Top' Node Title
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
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
3415 @@node Top, Copying, , (dir)
3418 Texinfo is a documentation system@dots{}
3422 This is edition@dots{}
3429 * Copying:: Texinfo is freely
3431 * Overview:: What is Texinfo?
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
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
3448 A @dfn{master menu} is a detailed main menu listing all the nodes in a
3451 A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3452 commands and does not appear in the printed document.@refill
3454 Generally, a master menu is divided into parts.@refill
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
3462 The second part contains nodes for the indices.@refill
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.
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
3480 For example, the master menu for this manual looks like the following
3481 (but has many more entries):@refill
3486 * Copying:: Texinfo is freely
3488 * Overview:: What is Texinfo?
3489 * Texinfo Mode:: Special features in GNU Emacs.
3494 * Command and Variable Index::
3495 An entry for each @@-command.
3496 * Concept Index:: An entry for each concept.
3501 --- The Detailed Node Listing ---
3505 * Info Files:: What is an Info file?
3506 * Printed Manuals:: Characteristics of
3515 * Info on a Region:: Formatting part of a file
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
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
3539 The copying and distribution information and the disclaimer are
3540 followed by an introduction or else by the first chapter of the
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
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
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
3570 @@node Concept Index, , Variables Index, Top
3571 @@c node-name, next, previous, up
3572 @@unnumbered Concept Index
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.
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
3591 @cindex Printing an index
3592 @cindex Indices, printing and menus
3593 @cindex Generating menus with indices
3594 @cindex Menus generated with indices
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
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
3616 The @code{@@printindex} command takes a two-letter index name, reads
3617 the corresponding sorted index file and formats it appropriately into
3621 The two-letter index names are:
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
3650 @@node Variable Index, Concept Index, Function Index, Top
3651 @@comment node-name, next, previous, up
3652 @@unnumbered Variable Index
3658 @@node Concept Index, , Variable Index, Top
3659 @@comment node-name, next, previous, up
3660 @@unnumbered Concept Index
3673 (Readers often prefer that the concept index come last in a book,
3674 since that makes it easiest to find.)@refill
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
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
3693 @findex summarycontents
3694 @findex shortcontents
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}
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
3711 @item @@shortcontents
3712 @itemx @@summarycontents
3713 (@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
3714 two commands are exactly the same.)@refill
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
3721 Write the @code{@@shortcontents} command on a line by itself right
3722 @emph{before} the @code{@@contents} command.@refill
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
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
3740 Here is an example of where to write table of contents commands:@refill
3744 @var{indices}@dots{}
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
3755 @node File End, , Contents, Ending a File
3756 @comment node-name, next, previous, up
3757 @section @code{@@bye} File Ending
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
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
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
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
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
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
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.
3801 * unnumbered & appendix::
3802 * majorheading & chapheading::
3804 * unnumberedsec appendixsec heading::
3806 * unnumberedsubsec appendixsubsec subheading::
3807 * subsubsection:: Commands for the lowest level sections.
3808 * Raise/lower sections:: How to change commands' hierarchical level.
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
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
3822 Here is a diagram that shows a Texinfo file with three chapters,
3823 each of which has two sections.@refill
3829 -------------------------------------
3831 Chapter 1 Chapter 2 Chapter 3
3833 -------- -------- --------
3835 Section Section Section Section Section Section
3836 1.1 1.2 2.1 2.2 3.1 3.2
3841 In a Texinfo file that has this structure, the beginning of Chapter 2
3842 looks like this:@refill
3846 @@node Chapter 2, Chapter 3, Chapter 1, top
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
3855 @node Structuring Command Types, makeinfo top, Tree Structuring, Structuring
3856 @comment node-name, next, previous, up
3857 @section Types of Structuring Commands
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
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
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
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
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
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
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
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
3903 Here are the four groups of chapter structuring commands:@refill
3905 @c Slightly different formatting for regular sized books and smallbooks.
3909 {\let\rm=\indrm \let\tt=\indtt
3910 \halign{\hskip\itemindent#\hfil& \hskip.5em#\hfil& \hskip.5em#\hfil&
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
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&
3923 \tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
3924 \tt @@subsubheading\cr}}
3931 \halign{\hskip\itemindent\hskip.5em#\hfil& \hskip.5em#\hfil&
3932 \hskip.5em#\hfil& \hskip.5em #\hfil\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
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&
3945 \tt @@subsubsection& \tt @@unnumberedsubsubsec& \tt @@appendixsubsubsec&
3946 \tt @@subsubheading\cr}}
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}
3956 @@top @@majorheading
3957 @@chapter @@unnumbered @@appendix @@chapheading
3958 @@section @@unnumberedsec @@appendixsec @@heading
3959 @@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
3960 @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
3965 @c Cannot line up columns properly inside of an example because of roman
3966 @c proportional fonts.
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}
3976 @@top @@majorheading
3977 @@chapter @@unnumbered @@appendix @@chapheading
3978 @@section @@unnumberedsec @@appendixsec @@heading
3979 @@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
3980 @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
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}
3993 @@top @@majorheading
3994 @@chapter @@unnumbered @@appendix @@chapheading
3995 @@section @@unnumberedsec @@appendixsec @@heading
3996 @@subsection @@unnumberedsubsec @@appendixsubsec @@subheading
3997 @@subsubsection @@unnumberedsubsubsec @@appendixsubsubsec @@subsubheading
4003 @node makeinfo top, chapter, Structuring Command Types, Structuring
4004 @comment node-name, next, previous, up
4005 @section @code{@@top}
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
4016 @node chapter, unnumbered & appendix, makeinfo top, Structuring
4017 @comment node-name, next, previous, up
4018 @section @code{@@chapter}
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
4025 For example, this chapter in this manual is entitled ``Chapter
4026 Structuring''; the @code{@@chapter} line looks like this:@refill
4029 @@chapter Chapter Structuring
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
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
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 ...
4052 @node unnumbered & appendix, majorheading & chapheading, chapter, Structuring
4053 @comment node-name, next, previous, up
4054 @section @code{@@unnumbered}, @code{@@appendix}
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
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
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
4074 @node majorheading & chapheading, section, unnumbered & appendix, Structuring
4075 @section @code{@@majorheading}, @code{@@chapheading}
4076 @findex majorheading
4079 The @code{@@majorheading} and @code{@@chapheading} commands put
4080 chapter-like headings in the body of a document.@refill
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
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
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
4096 @node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
4097 @comment node-name, next, previous, up
4098 @section @code{@@section}
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
4106 This section is headed with an @code{@@section} command and looks like
4107 this in the Texinfo file:@refill
4110 @@section @@code@{@@@@section@}
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
4120 @@section This is a section
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
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
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
4155 @itemx @@appendixsection
4156 @code{@@appendixsection} is a longer spelling of the
4157 @code{@@appendixsec} command; the two are synonymous.@refill
4158 @findex appendixsection
4160 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4161 command is used only within appendices.@refill
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
4168 @node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
4169 @comment node-name, next, previous, up
4170 @section The @code{@@subsection} Command
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
4178 @@subsection This is a subsection
4186 This is a subsection
4187 --------------------
4191 In a printed manual, subsections are listed in the table of contents
4192 and are numbered three levels deep.@refill
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
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
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
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
4226 The fourth and lowest level sectioning commands in Texinfo are the
4227 `subsub' commands. They are:@refill
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
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
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
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
4255 In Info, `subsub' titles are underlined with periods.
4259 @@subsubsection This is a subsubsection
4267 This is a subsubsection
4268 .......................
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
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.
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.
4296 @code{@@raisesections} raises a command one level in the chapter
4297 structuring hierarchy:@refill
4303 @@subsection @@section,
4304 @@section @@chapter,
4305 @@heading @@chapheading,
4311 @code{@@lowersections} lowers a command one level in the chapter
4312 structuring hierarchy:@refill
4318 @@chapter @@section,
4319 @@subsection @@subsubsection,
4320 @@heading @@subheading,
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
4330 An @code{@@lowersections} command cancels an @code{@@raisesections}
4331 command, and vice versa. Typically, the commands are used like this:
4335 @@include somefile.texi
4339 Without the @code{@@raisesections}, all the subsequent sections in your
4340 document will be lowered.
4342 Repeated use of the commands continue to raise or lower the hierarchical
4343 level a step at a time.
4345 An attempt to raise above `chapters' reproduces chapter commands; an
4346 attempt to lower below `subsubsections' reproduces subsubsection
4349 @node Nodes, Menus, Structuring, Top
4350 @comment node-name, next, previous, up
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
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}.
4370 @node Two Paths, Node Menu Illustration, Nodes, Nodes
4375 The node and menu commands and the chapter structuring commands are
4376 independent of each other:
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
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
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
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
4403 @node Node Menu Illustration, node, Two Paths, Nodes
4404 @comment node-name, next, previous, up
4405 @section Node and Menu Illustration
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
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
4420 -------------------------------------
4422 Chapter 1 Chapter 2 Chapter 3
4424 -------- -------- --------
4426 Section Section Section Section Section Section
4427 1.1 1.2 2.1 2.2 3.1 3.2
4432 Write the beginning of the node for Chapter 2 like this:@refill
4436 @@node Chapter 2, Chapter 3, Chapter 1, top
4437 @@comment node-name, next, previous, up
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''.
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
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
4466 * Sect. 2.1:: Description of this section.
4472 Write the node for Sect. 2.1 like this:@refill
4476 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4477 @@comment node-name, next, previous, up
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
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
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
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
4509 @node node, makeinfo Pointer Creation, Node Menu Illustration, Nodes
4510 @comment node-name, next, previous, up
4511 @section The @code{@@node} Command
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
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
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
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
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
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.
4565 @node Node Names, Writing a Node, node, node
4567 @subheading Choosing Node and Pointer Names
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
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
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
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
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
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
4601 @@node @var{node-name}
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
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
4618 The template for a node line with `Next', `Previous', and `Up' pointers
4619 looks like this:@refill
4622 @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
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
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
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
4645 Here are three suggestions:
4649 Try to pick node names that are informative but short.@refill
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
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
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
4666 @node Node Line Requirements, First Node, Node Line Tips, node
4667 @comment node-name, next, previous, up
4668 @subsection @code{@@node} Line Requirements
4670 @cindex Node line requirements
4671 Here are several requirements for @code{@@node} lines:
4674 @cindex Unique nodename requirement
4675 @cindex Nodename must be unique
4677 All the node names for a single Info file must be unique.@refill
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
4688 A pointer name must be the name of a node.@refill
4690 The node to which a pointer points may come before or after the
4691 node containing the pointer.@refill
4693 @cindex @@-command in nodename
4694 @cindex Nodename, cannot contain
4696 You cannot use any of the Texinfo @@-commands in a node name;
4697 @w{@@-commands} confuse Info.@refill
4700 Thus, the beginning of the section called @code{@@chapter} looks like
4705 @@node chapter, unnumbered & appendix, makeinfo top, Structuring
4706 @@comment node-name, next, previous, up
4707 @@section @@code@{@@@@chapter@}
4712 @cindex Comma in nodename
4713 @cindex Apostrophe in nodename
4715 You cannot use commas or apostrophes within a node name; these
4716 confuse @TeX{} or the Info formatters.@refill
4719 For example, the following is a section title:
4722 @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
4726 The corresponding node name is:
4729 unnumberedsec appendixsec heading
4732 @cindex Case in nodename
4734 Case is significant.
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
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}).
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:
4761 @@node Top, Copying, , (dir)
4765 (You can use the Texinfo updating commands or the @code{makeinfo}
4766 utility to insert these pointers automatically.)
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 hits @key{DEL} to go backwards, you wind up in the middle of the
4772 some other entry in the @file{dir} file, which has nothing to do with
4773 what you were reading.
4775 @xref{Install an Info File}, for more information about installing
4776 an Info file in the @file{info} directory.
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)}
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
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
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
4806 @node Top Node Summary, , makeinfo top command, node
4807 @subsection The `Top' Node Summary
4808 @cindex @samp{@r{Top}} node summary
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
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
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
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}
4841 The @code{makeinfo} program has a feature for automatically creating
4842 node pointers for a hierarchically organized file that lacks
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
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}}.
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
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
4866 @node Menus, Cross References, Nodes, Top
4867 @comment node-name, next, previous, up
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
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
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
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
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.
4908 @node Menu Location, Writing a Menu, Menus, Menus
4910 @heading Menus Need Short Nodes
4912 @cindex Menu location
4913 @cindex Location of menus
4914 @cindex Nodes for menus are short
4915 @cindex Short nodes for menus
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
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
4932 For example, the preceding two paragraphs follow an Info-only menu,
4933 @code{@@node} line, and heading, and look like this:@refill
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
4947 @@node Menu Location, Writing a Menu, , Menus
4949 @@heading Menus Need Short Nodes
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
4958 @node Writing a Menu, Menu Parts, Menu Location, Menus
4959 @section Writing a Menu
4960 @cindex Writing a menu
4961 @cindex Menu writing
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
4968 A menu looks like this:@refill
4973 Larger Units of Text
4975 * Files:: All about handling files.
4976 * Multiples: Buffers. Multiple buffers; editing
4977 several files at once.
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{* }}
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
4995 @cindex @code{@@menu} parts
4997 A menu entry has three parts, only the second of which is required:
5001 The menu entry name (optional).
5004 The name of the node (required).
5007 A description of the item (optional).
5010 The template for a menu entry looks like this:@refill
5013 * @var{menu-entry-name}: @var{node-name}. @var{description}
5016 Follow the menu entry name with a single colon and follow the node name
5017 with tab, comma, period, or newline.@refill
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}
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.
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
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
5049 * Name:: @var{description}
5057 * Name: Name. @var{description}
5060 You should use the node name for the menu entry name whenever possible,
5061 since it reduces visual clutter in the menu.@refill
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
5069 A menu looks like this in Texinfo:@refill
5074 * menu entry name: Node name. A short description.
5075 * Node name:: This form is preferred.
5088 * menu entry name: Node name. A short description.
5089 * Node name:: This form is preferred.
5094 Here is an example as you might see it in a Texinfo file:@refill
5099 Larger Units of Text
5101 * Files:: All about handling files.
5102 * Multiples: Buffers. Multiple buffers; editing
5103 several files at once.
5115 Larger Units of Text
5117 * Files:: All about handling files.
5118 * Multiples: Buffers. Multiple buffers; editing
5119 several files at once.
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
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
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
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
5149 The format looks like this:@refill
5154 * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
5155 * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5160 For example, to refer directly to the @samp{Outlining} and
5161 @samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
5162 menu like this:@refill
5167 * Outlining: (emacs)Outline Mode. The major mode for
5169 * Rebinding: (emacs)Rebinding. How to redefine the
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
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
5187 * Info: (info). Documentation browsing system.
5188 * Emacs: (emacs). The extensible, self-documenting
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
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
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
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
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.
5225 @node References, Cross Reference Commands, Cross References, Cross References
5227 @heading What References Are For
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
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
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
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
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
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
5268 There are four different cross reference commands:@refill
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}.}.
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
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
5286 Used to make a reference to an Info file for which there is no printed
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
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
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
5309 Here is a simple cross reference example:@refill
5312 @@xref@{Node name@}.
5326 See Section @var{nnn} [Node name], page @var{ppp}.
5330 Here is an example of a full five-part cross reference:@refill
5334 @@xref@{Node name, Cross Reference Name, Particular Topic,
5335 info-file-name, A Printed Manual@}, for details.
5343 *Note Cross Reference Name: (info-file-name)Node name,
5351 See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5357 The five possible arguments for a cross reference are:@refill
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
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
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
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
5383 The name of a printed manual from a different Texinfo file.@refill
5386 The template for a full five argument cross reference looks like
5391 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5392 @var{info-file-name}, @var{printed-manual-title}@}.
5396 Cross references with one, two, three, four, and five arguments are
5397 described separately following the description of @code{@@xref}.@refill
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
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
5408 @node xref, Top Node Naming, Cross Reference Parts, Cross References
5409 @comment node-name, next, previous, up
5410 @section @code{@@xref}
5412 @cindex Cross references using @code{@@xref}
5413 @cindex References using @code{@@xref}
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
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.
5430 @node Reference Syntax, One Argument, xref, xref
5432 @subheading What a Reference Looks Like and Requires
5435 Most often, an Info cross reference looks like this:@refill
5438 *Note @var{node-name}::.
5445 *Note @var{cross-reference-name}: @var{node-name}.
5449 In @TeX{}, a cross reference looks like this:
5452 See Section @var{section-number} [@var{node-name}], page @var{page}.
5459 See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
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
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
5475 @code{@@xref} must refer to an Info node by name. Use @code{@@node}
5476 to define the node (@pxref{Writing a Node}).@refill
5478 @code{@@xref} is followed by several arguments inside braces, separated by
5479 commas. Whitespace before and after these commas is ignored.@refill
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
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
5491 @node One Argument, Two Arguments, Reference Syntax, xref
5492 @subsection @code{@@xref} with One Argument
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
5504 @@xref@{Tropical Storms@}.
5511 *Note Tropical Storms::.
5518 See Section 3.1 [Tropical Storms], page 24.
5522 (Note that in the preceding example the closing brace is followed by a
5525 You can write a clause after the cross reference, like this:@refill
5528 @@xref@{Tropical Storms@}, for more info.
5535 *Note Tropical Storms::, for more info.
5539 See Section 3.1 [Tropical Storms], page 24, for more info.
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
5546 @node Two Arguments, Three Arguments, One Argument, xref
5547 @subsection @code{@@xref} with Two Arguments
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
5555 The template is like this:
5558 @@xref@{@var{node-name}, @var{cross-reference-name}@}.
5566 @@xref@{Electrical Effects, Lightning@}.
5573 *Note Lightning: Electrical Effects.
5580 See Section 5.2 [Electrical Effects], page 57.
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
5587 You can write a clause after the cross reference, like this:@refill
5590 @@xref@{Electrical Effects, Lightning@}, for more info.
5596 *Note Lightning: Electrical Effects, for more info.
5603 See Section 5.2 [Electrical Effects], page 57, for more info.
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
5610 @node Three Arguments, Four and Five Arguments, Two Arguments, xref
5611 @subsection @code{@@xref} with Three Arguments
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
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
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
5634 The template is like this:
5638 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
5648 @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
5657 *Note Lightning: Electrical Effects, for details.
5664 See Section 5.2 [Thunder and Lightning], page 57, for details.
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
5673 @@xref@{Electrical Effects, , Thunder and Lightning@},
5682 *Note Thunder and Lightning: Electrical Effects, for details.
5689 See Section 5.2 [Thunder and Lightning], page 57, for details.
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
5697 Here are several examples from @cite{The GNU Awk User's Guide}:@refill
5700 @@xref@{Sample Program@}.
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@}.
5708 @node Four and Five Arguments, , Three Arguments, xref
5709 @subsection @code{@@xref} with Four and Five Arguments
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
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
5725 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5726 @var{info-file-name}, @var{printed-manual-title}@}.
5735 @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
5736 weather, An Introduction to Meteorology@}, for details.
5743 *Note Lightning: (weather)Electrical Effects, for details.
5747 The name of the Info file is enclosed in parentheses and precedes
5748 the name of the node.
5751 In a printed manual, the reference looks like this:@refill
5754 See section ``Thunder and Lightning'' in @i{An Introduction to
5755 Meteorology}, for details.
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
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
5768 The template looks like this:
5771 @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
5772 @var{printed-manual-title}@}, for details.
5779 *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
5786 See section @var{title-or-topic} in @var{printed-manual-title}, for details.
5794 @@xref@{Electrical Effects, , Thunder and Lightning,
5795 weather, An Introduction to Meteorology@}, for details.
5803 *Note Thunder and Lightning: (weather)Electrical Effects,
5812 See section ``Thunder and Lightning'' in @i{An Introduction to
5813 Meteorology}, for details.
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
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
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.
5838 Thus, to make a cross reference to @cite{The GNU Make Manual},
5842 @@xref@{Top, , Overview, make, The GNU Make Manual@}.
5849 *Note Overview: (make)Top.
5856 See section ``Overview'' in @i{The GNU Make Manual}.
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}
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
5878 For more information, see @@ref@{Hurricanes@}.
5885 For more information, see *Note Hurricanes.
5892 For more information, see Section 8.2 [Hurricanes], page 123.
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
5906 Sea surges are described in @@ref@{Hurricanes@}.
5915 Sea surges are described in Section 6.7 [Hurricanes], page 72.
5920 in a printed document, and the following in Info:
5923 Sea surges are described in *Note Hurricanes::.
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
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}
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
5950 @TeX{} typesets the reference for the printed manual with a lower case
5951 `see' rather than an upper case `See'.@refill
5954 The Info formatting commands automatically end the reference with a
5955 closing colon or period.@refill
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
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
5974 With one argument, a parenthetical cross reference looks like
5978 @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
5987 @dots{} storms cause flooding (*Note Hurricanes::) @dots{}
5995 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
5998 With two arguments, a parenthetical cross reference has this
6002 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6009 @dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
6017 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6020 @code{@@pxref} can be used with up to five arguments just like
6021 @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
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
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
6034 @node inforef, uref, pxref, Cross References
6035 @section @code{@@inforef}
6036 @cindex Cross references using @code{@@inforef}
6037 @cindex References using @code{@@inforef}
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
6045 The command takes either two or three arguments, in the following
6053 The cross reference name (optional).
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
6068 @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6077 @@inforef@{Expert, Advanced Info commands, info@},
6078 for more information.
6088 *Note Advanced Info commands: (info)Expert,
6089 for more information.
6098 See Info file @file{info}, node @samp{Expert}, for more information.
6107 @@inforef@{Expert, , info@}, for more information.
6116 *Note (info)Expert::, for more information.
6124 See Info file @file{info}, node @samp{Expert}, for more information.
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
6132 @node uref, , inforef, Cross References
6133 @section @code{@@uref@{@var{url}[, @var{displayed-text}]@}}
6135 @cindex Uniform resource locator, referring to
6136 @cindex URL, referring to
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:
6144 The official GNU ftp site is
6145 @@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu@}
6151 The official GNU ftp site is
6152 @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu}
6159 @@uref@{ftp://ftp.gnu.ai.mit.edu/pub/gnu,
6160 GNU ftp site@} holds programs and texts.
6166 The official @uref{ftp://ftp.gnu.ai.mit.edu/pub/gnu, GNU ftp site} holds
6173 The official <A HREF="ftp://ftp.gnu.ai.mit.edu/pub/gnu">GNU ftp
6174 site</A> holds programs and texts.
6177 To merely indicate a URL, use @code{@@url} (@pxref{url, @code{@@url}}).
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
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
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
6196 * Indicating:: How to indicate definitions, files, etc.
6197 * Emphasis:: How to emphasize text.
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.
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
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
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.
6238 @node Useful Highlighting, code, Indicating, Indicating
6240 @subheading Highlighting Commands are Useful
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
6251 The commands serve a variety of purposes:@refill
6254 @item @@code@{@var{sample-code}@}
6255 Indicate text that is a literal example of a piece of a program.@refill
6257 @item @@kbd@{@var{keyboard-characters}@}
6258 Indicate keyboard input.@refill
6260 @item @@key@{@var{key-name}@}
6261 Indicate the conventional name for a key on a keyboard.@refill
6263 @item @@samp@{@var{text}@}
6264 Indicate text that is a literal example of a sequence of characters.@refill
6266 @item @@var@{@var{metasyntactic-variable}@}
6267 Indicate a metasyntactic variable.@refill
6269 @item @@url@{@var{uniform-resource-locator}@}
6270 Indicate a uniform resource locator for the World Wide Web.
6272 @item @@file@{@var{file-name}@}
6273 Indicate the name of a file.@refill
6275 @item @@email@{@var{email-address}[, @var{displayed-text}]@}
6276 Indicate an electronic mail address.
6278 @item @@dfn@{@var{term}@}
6279 Indicate the introductory or defining use of a term.@refill
6281 @item @@cite@{@var{reference}@}
6282 Indicate the name of a book.@refill
6285 @item @@ctrl@{@var{ctrl-char}@}
6286 Use for an @sc{ascii} control character.@refill
6290 @node code, kbd, Useful Highlighting, Indicating
6291 @comment node-name, next, previous, up
6292 @subsection @code{@@code}@{@var{sample-code}@}
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
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
6306 Use @code{@@code} for environment variables such as @code{TEXINPUTS},
6307 and other variables.@refill
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
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
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
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
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
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.
6355 Use @@code@{diff@} to compare two files.
6359 produces this in the printed manual:@refill
6362 Use @code{diff} to compare two files.
6367 and this in the Info file:@refill
6370 Use `diff' to compare two files.
6375 @node kbd, key, code, Indicating
6376 @subsection @code{@@kbd}@{@var{keyboard-characters}@}
6378 @cindex keyboard input
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},
6389 and to refer to the characters @kbd{M-x shell}, write@refill
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.
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
6408 @vindex distinct@r{, arg to @@kbdinputstyle}
6409 @vindex example@r{, arg to @@kbdinputstyle}
6410 @vindex code@r{, arg to @@kbdinputstyle}
6413 Always use the same font for @code{@@kbd} as @code{@@code}.
6415 Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6416 and similar environments.
6418 (the default) Always use the distinguishing font for @code{@@kbd}.
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
6427 @@kbd@{r @@key@{RET@}@}
6431 This produces: @kbd{r @key{RET}}
6433 You also use the @code{@@kbd} command if you are spelling out the letters
6434 you type; for example:@refill
6437 To give the @@code@{logout@} command,
6438 type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6445 To give the @code{logout} command,
6446 type the characters @kbd{l o g o u t @key{RET}}.
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
6454 @node key, samp, kbd, Indicating
6455 @comment node-name, next, previous, up
6456 @subsection @code{@@key}@{@var{key-name}@}
6459 Use the @code{@@key} command for the conventional name for a key on a
6460 keyboard, as in:@refill
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
6471 For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
6474 @@kbd@{C-x @@key@{ESC@}@}
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
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}.
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}.
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
6525 @node samp, var, key, Indicating
6526 @comment node-name, next, previous, up
6527 @subsection @code{@@samp}@{@var{text}@}
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
6537 To match @@samp@{foo@} at the end of the line,
6538 use the regexp @@samp@{foo$@}.
6545 To match @samp{foo} at the end of the line, use the regexp
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
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
6566 In English, the vowels are @@samp@{a@}, @@samp@{e@},
6567 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
6576 In English, the vowels are @samp{a}, @samp{e},
6577 @samp{i}, @samp{o}, @samp{u}, and sometimes
6581 @node var, file, samp, Indicating
6582 @comment node-name, next, previous, up
6583 @subsection @code{@@var}@{@var{metasyntactic-variable}@}
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
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
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.
6605 To delete file @@var@{filename@},
6606 type @@code@{rm @@var@{filename@}@}.
6613 To delete file @var{filename}, type @code{rm @var{filename}}.
6617 (Note that @code{@@var} may appear inside @code{@@code},
6618 @code{@@samp}, @code{@@file}, etc.)@refill
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
6628 @@@@setfilename @@var@{info-file-name@}
6629 @@@@settitle @@var@{name-of-manual@}
6639 @@setfilename @var{info-file-name}
6640 @@settitle @var{name-of-manual}
6644 In some documentation styles, metasyntactic variables are shown with
6645 angle brackets, for example:@refill
6648 @dots{}, type rm <filename>
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
6656 @node file, dfn, var, Indicating
6657 @comment node-name, next, previous, up
6658 @subsection @code{@@file}@{@var{file-name}@}
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}.
6666 Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
6670 The @@file@{.el@} files are in
6671 the @@file@{/usr/local/emacs/lisp@} directory.
6678 The @file{.el} files are in
6679 the @file{/usr/local/emacs/lisp} directory.
6682 @node dfn, cite, file, Indicating
6683 @comment node-name, next, previous, up
6684 @subsection @code{@@dfn}@{@var{term}@}
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
6696 Getting rid of a file is called @@dfn@{deleting@} it.
6703 Getting rid of a file is called @dfn{deleting} it.
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.
6711 @node cite, url, dfn, Indicating
6712 @comment node-name, next, previous, up
6713 @subsection @code{@@cite}@{@var{reference}@}
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
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
6725 @c node ctrl, , cite, Indicating
6726 @comment node-name, next, previous, up
6727 @c subsection @code{@@ctrl}@{@var{ctrl-char}@}
6730 The @code{@@ctrl} command is seldom used. It describes an @sc{ascii}
6731 control character by inserting the actual character into the Info
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
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
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
6768 In a printed manual, @code{@@ctrl} generates text to describe or
6769 identify that control character: an uparrow followed by the character
6774 @node url, email, cite, Indicating
6775 @subsection @code{@@url}@{@var{uniform-resource-locator}@}
6777 @cindex Uniform resource locator, indicating
6778 @cindex URL, indicating
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
6787 @c Two lines because one is too long for smallbook format.
6789 For example, the url might be
6790 @@url@{http://host.domain.org/path@}.
6794 @node email, , url, Indicating
6795 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
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).
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.
6809 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}.
6810 Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
6815 Send bug reports to @email{bug-texinfo@@gnu.org}.
6816 Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
6820 @node Emphasis, , Indicating, Marking Text
6821 @comment node-name, next, previous, up
6822 @section Emphasizing Text
6823 @cindex Emphasizing text
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
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.
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
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
6859 @@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
6860 files in the directory.
6867 produces the following in printed output:
6870 @strong{Caution}: @code{rm * .[^.]*} removes @emph{all}
6871 files in the directory.
6875 and the following in Info:
6883 *Caution*: `rm * .[^.]*' removes *all*
6884 files in the directory.
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
6891 In the Info file, both @code{@@emph} and @code{@@strong} put asterisks
6892 around the text.@refill
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
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)}
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
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
6915 Write the text between braces in lower case, like this:@refill
6918 The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
6925 The @sc{acm} and @sc{ieee} are technical societies.
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
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
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
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
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
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)}
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
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
6983 (+ 2 2) ; @@r@{Add two plus two.@}
6992 (+ 2 2) ; @r{Add two plus two.}
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
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
7005 @c I think this whole section is obsolete with the advent of macros
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
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
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
7029 For @TeX{}, write the following to equate the @code{@@phoo} command with
7030 the existing @code{@@i} italics command:@refill
7035 @@global@@let@@phoo=@@i
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
7047 For Info, write the following to tell the Info formatters to enclose the
7048 argument between @samp{//} and @samp{\\}:
7053 @@definfoenclose phoo, //, \\
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
7065 The first argument to @code{@@definfoenclose} is the @@-command name
7066 @strong{without} the @samp{@@};
7069 the second argument is the Info start delimiter string; and,
7072 the third argument is the Info end delimiter string.
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
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\\}
7087 @samp{bar} in italics in printed output.
7090 @i{bar} in italics in printed output.
7093 Note that each definition applies to its own formatter: one for @TeX{},
7097 Here is another example:
7102 @@definfoenclose headword, , :
7105 @@global@@let@@headword=@@b
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.
7115 @node Quotations and Examples, Lists and Tables, Marking Text, Top
7116 @comment node-name, next, previous, up
7117 @chapter Quotations and Examples
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
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
7133 * Block Enclosing Commands:: Use different constructs for
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
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.
7148 @node Block Enclosing Commands, quotation, Quotations and Examples, Quotations and Examples
7149 @section The Block Enclosing Commands
7151 Here are commands for quotations and examples:@refill
7155 Indicate text that is quoted. The text is filled, indented, and
7156 printed in a roman font by default.@refill
7159 Illustrate code, commands, and the like. The text is printed
7160 in a fixed-width font, and indented but not filled.@refill
7163 Illustrate Lisp code. The text is printed in a fixed-width font,
7164 and indented but not filled.@refill
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
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
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
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
7186 The @code{@@exdent} command is used within the above constructs to
7187 undo the indentation of a line.
7189 The @code{@@flushleft} and @code{@@flushright} commands are used to line
7190 up the left or right margins of unfilled text.@refill
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
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
7202 @node quotation, example, Block Enclosing Commands, Quotations and Examples
7203 @comment node-name, next, previous, up
7204 @section @code{@@quotation}
7208 The text of a quotation is
7209 processed normally except that:@refill
7213 the margins are closer to the center of the page, so the whole of the
7214 quotation is indented;@refill
7217 the first lines of paragraphs are indented no more than other
7221 in the printed output, interparagraph spacing is reduced.@refill
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
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
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
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
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.
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.
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
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
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
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.
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}}.)
7326 @node noindent, Lisp Example, example, Quotations and Examples
7327 @comment node-name, next, previous, up
7328 @section @code{@@noindent}
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
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@}.)
7362 % Remove extra vskip; this is a kludge to counter the effect of display
7363 \vskip-3.5\baselineskip
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}.)
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
7377 In the Texinfo source file for this manual, each line that says
7378 `produces' is preceded by a line containing @code{@@noindent}.@refill
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
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
7390 The @code{@@lisp} command is used for Lisp code. It is synonymous
7391 with the @code{@@example} command.
7394 This is an example of text written between an
7395 @code{@@lisp} command and an @code{@@end lisp} command.
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
7405 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
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
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
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}
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
7438 Mark the end of @code{@@smallexample} or @code{@@smalllisp} with
7439 @code{@@end smallexample} or @code{@@end smalllisp},
7440 respectively.@refill
7443 Here is an example written in the small font used by the
7444 @code{@@smallexample} and @code{@@smalllisp} commands:
7449 % Remove extra vskip; this is a kludge to counter the effect of display
7450 \vskip-3\baselineskip
7452 \dots{} to make sure that you have the freedom to
7453 distribute copies of free software (and charge for
7454 this service if you wish), that you receive source
7455 code or can get it if you want it, that you can
7456 change the software or use pieces of it in new free
7457 programs; and that you know you can do these things.}
7465 This is an example of text written between @code{@@smallexample} and
7466 @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
7467 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7468 this text appears in a smaller font.
7474 This is an example of text written between @code{@@smallexample} and
7475 @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
7476 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7477 this text appears in a smaller font.
7481 The @code{@@smallexample} and @code{@@smalllisp} commands make it
7482 easier to prepare smaller format manuals without forcing you to edit
7483 examples by hand to fit them onto narrower pages.@refill
7485 As a general rule, a printed document looks better if you write all the
7486 examples in a chapter consistently in @code{@@example} or in
7487 @code{@@smallexample}. Only occasionally should you mix the two
7490 @xref{smallbook, , Printing ``Small'' Books}, for more information
7491 about the @code{@@smallbook} command.@refill
7493 @node display, format, smallexample & smalllisp, Quotations and Examples
7494 @comment node-name, next, previous, up
7495 @section @code{@@display}
7496 @cindex Display formatting
7499 The @code{@@display} command begins a kind of example. It is like the
7500 @code{@@example} command
7502 a printed manual, @code{@@display} does not select the fixed-width
7503 font. In fact, it does not specify the font at all, so that the text
7504 appears in the same font it would have appeared in without the
7505 @code{@@display} command.@refill
7508 This is an example of text written between an @code{@@display} command
7509 and an @code{@@end display} command. The @code{@@display} command
7510 indents the text, but does not fill it.
7513 @node format, exdent, display, Quotations and Examples
7514 @comment node-name, next, previous, up
7515 @section @code{@@format}
7518 The @code{@@format} command is similar to @code{@@example} except
7519 that, in the printed manual, @code{@@format} does not select the
7520 fixed-width font and does not narrow the margins.@refill
7523 This is an example of text written between an @code{@@format} command
7524 and an @code{@@end format} command. As you can see
7526 the @code{@@format} command does not fill the text.
7529 @node exdent, flushleft & flushright, format, Quotations and Examples
7530 @section @code{@@exdent}: Undoing a Line's Indentation
7531 @cindex Indentation undoing
7534 The @code{@@exdent} command removes any indentation a line might have.
7535 The command is written at the beginning of a line and applies only to
7536 the text that follows the command that is on the same line. Do not use
7537 braces around the text. In a printed manual, the text on an
7538 @code{@@exdent} line is printed in the roman font.@refill
7540 @code{@@exdent} is usually used within examples. Thus,@refill
7545 This line follows an @@@@example command.
7546 @@exdent This line is exdented.
7547 This line follows the exdented line.
7548 The @@@@end example comes on the next line.
7558 This line follows an @@example command.
7559 @exdent This line is exdented.
7560 This line follows the exdented line.
7561 The @@end example comes on the next line.
7565 In practice, the @code{@@exdent} command is rarely used.
7566 Usually, you un-indent text by ending the example and
7567 returning the page to its normal width.@refill
7569 @node flushleft & flushright, cartouche, exdent, Quotations and Examples
7570 @section @code{@@flushleft} and @code{@@flushright}
7574 The @code{@@flushleft} and @code{@@flushright} commands line up the
7575 ends of lines on the left and right margins of a page,
7576 but do not fill the text. The commands are written on lines of their
7577 own, without braces. The @code{@@flushleft} and @code{@@flushright}
7578 commands are ended by @code{@@end flushleft} and @code{@@end
7579 flushright} commands on lines of their own.@refill
7604 @code{@@flushright} produces the type of indentation often used in the
7605 return address of letters. For example,
7610 Here is an example of text written
7611 flushright. The @@code@{@@flushright@} command
7612 right justifies every line but leaves the
7622 Here is an example of text written
7623 flushright. The @code{@@flushright} command
7624 right justifies every line but leaves the
7628 @node cartouche, , flushleft & flushright, Quotations and Examples
7629 @section Drawing Cartouches Around Examples
7631 @cindex Box with rounded corners
7633 In a printed manual, the @code{@@cartouche} command draws a box with
7634 rounded corners around its contents. You can use this command to
7635 further highlight an example or quotation. For instance, you could
7636 write a manual in which one type of example is surrounded by a cartouche
7637 for emphasis.@refill
7639 The @code{@@cartouche} command affects only the printed manual; it has
7640 no effect in the Info file.@refill
7650 /usr/local/share/emacs
7657 surrounds the two-line example with a box with rounded corners, in the
7661 In a printed manual, the example looks like this:@refill
7667 /usr/local/lib/emacs/info
7674 @node Lists and Tables, Indices, Quotations and Examples, Top
7675 @chapter Lists and Tables
7676 @cindex Making lists and tables
7677 @cindex Lists and tables, making
7678 @cindex Tables and lists, making
7680 Texinfo has several ways of making lists and tables. Lists can be
7681 bulleted or numbered; two-column tables can highlight the items in
7682 the first column; multi-column tables are also supported.
7685 * Introducing Lists:: Texinfo formats lists for you.
7686 * itemize:: How to construct a simple list.
7687 * enumerate:: How to construct a numbered list.
7688 * Two-column Tables:: How to construct a two-column table.
7689 * Multi-column Tables:: How to construct generalized tables.
7693 @node Introducing Lists, itemize, Lists and Tables, Lists and Tables
7694 @heading Introducing Lists
7697 Texinfo automatically indents the text in lists or tables, and numbers
7698 an enumerated list. This last feature is useful if you modify the
7699 list, since you do not need to renumber it yourself.@refill
7701 Numbered lists and tables begin with the appropriate @@-command at the
7702 beginning of a line, and end with the corresponding @code{@@end}
7703 command on a line by itself. The table and itemized-list commands
7704 also require that you write formatting information on the same line as
7705 the beginning @@-command.@refill
7707 Begin an enumerated list, for example, with an @code{@@enumerate}
7708 command and end the list with an @code{@@end enumerate} command.
7709 Begin an itemized list with an @code{@@itemize} command, followed on
7710 the same line by a formatting command such as @code{@@bullet}, and end
7711 the list with an @code{@@end itemize} command.@refill
7714 Precede each element of a list with an @code{@@item} or @code{@@itemx}
7719 Here is an itemized list of the different kinds of table and lists:@refill
7723 Itemized lists with and without bullets.
7726 Enumerated lists, using numbers or letters.
7729 Two-column tables with highlighting.
7734 Here is an enumerated list with the same items:@refill
7738 Itemized lists with and without bullets.
7741 Enumerated lists, using numbers or letters.
7744 Two-column tables with highlighting.
7749 And here is a two-column table with the same items and their
7750 @w{@@-commands}:@refill
7754 Itemized lists with and without bullets.
7757 Enumerated lists, using numbers or letters.
7762 Two-column tables with indexing.
7765 @node itemize, enumerate, Introducing Lists, Lists and Tables
7766 @comment node-name, next, previous, up
7767 @section Making an Itemized List
7771 The @code{@@itemize} command produces sequences of indented
7772 paragraphs, with a bullet or other mark inside the left margin
7773 at the beginning of each paragraph for which such a mark is desired.@refill
7775 Begin an itemized list by writing @code{@@itemize} at the beginning of
7776 a line. Follow the command, on the same line, with a character or a
7777 Texinfo command that generates a mark. Usually, you will write
7778 @code{@@bullet} after @code{@@itemize}, but you can use
7779 @code{@@minus}, or any character or any special symbol that results in
7780 a single character in the Info file. (When you write @code{@@bullet}
7781 or @code{@@minus} after an @code{@@itemize} command, you may omit the
7782 @samp{@{@}}.)@refill
7784 Write the text of the indented paragraphs themselves after the
7785 @code{@@itemize}, up to another line that says @code{@@end
7788 Before each paragraph for which a mark in the margin is desired, write
7789 a line that says just @code{@@item}. Do not write any other text on this
7793 Usually, you should put a blank line before an @code{@@item}. This
7794 puts a blank line in the Info file. (@TeX{} inserts the proper
7795 interline whitespace in either case.) Except when the entries are
7796 very brief, these blank lines make the list look better.@refill
7798 Here is an example of the use of @code{@@itemize}, followed by the
7799 output it produces. Note that @code{@@bullet} produces an @samp{*} in
7800 Info and a round dot in @TeX{}.@refill
7829 Itemized lists may be embedded within other itemized lists. Here is a
7830 list marked with dashes embedded in a list marked with bullets:@refill
7873 @node enumerate, Two-column Tables, itemize, Lists and Tables
7874 @comment node-name, next, previous, up
7875 @section Making a Numbered or Lettered List
7879 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
7880 @code{@@itemize}}), except that the labels on the items are
7881 successive integers or letters instead of bullets.
7883 Write the @code{@@enumerate} command at the beginning of a line. The
7884 command does not require an argument, but accepts either a number or a
7885 letter as an option. Without an argument, @code{@@enumerate} starts the
7886 list with the number @samp{1}. With a numeric argument, such as
7887 @samp{3}, the command starts the list with that number. With an upper
7888 or lower case letter, such as @samp{a} or @samp{A}, the command starts
7889 the list with that letter.@refill
7891 Write the text of the enumerated list in the same way you write an
7892 itemized list: put @code{@@item} on a line of its own before the start
7893 of each paragraph that you want enumerated. Do not write any other text
7894 on the line beginning with @code{@@item}.@refill
7896 You should put a blank line between entries in the list.
7897 This generally makes it easier to read the Info file.@refill
7900 Here is an example of @code{@@enumerate} without an argument:@refill
7925 Here is an example with an argument of @kbd{3}:@refill
7931 Predisposing causes.
7934 Precipitating causes.
7937 Perpetuating causes.
7947 Predisposing causes.
7950 Precipitating causes.
7953 Perpetuating causes.
7956 Here is a brief summary of the alternatives. The summary is constructed
7957 using @code{@@enumerate} with an argument of @kbd{a}.@refill
7963 Without an argument, produce a numbered list, starting with the number
7967 @code{@@enumerate @var{positive-integer}}
7969 With a (positive) numeric argument, start a numbered list with that
7970 number. You can use this to continue a list that you interrupted with
7974 @code{@@enumerate @var{upper-case-letter}}
7976 With an upper case letter as argument, start a list
7977 in which each item is marked
7978 by a letter, beginning with that upper case letter.@refill
7981 @code{@@enumerate @var{lower-case-letter}}
7983 With a lower case letter as argument, start a list
7984 in which each item is marked by
7985 a letter, beginning with that lower case letter.@refill
7988 You can also nest enumerated lists, as in an outline.@refill
7990 @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
7991 @section Making a Two-column Table
7992 @cindex Tables, making two-column
7995 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
7996 @code{@@itemize}}), but allows you to specify a name or heading line for
7997 each item. The @code{@@table} command is used to produce two-column
7998 tables, and is especially useful for glossaries, explanatory
7999 exhibits, and command-line option summaries.
8002 * table:: How to construct a two-column table.
8003 * ftable vtable:: Automatic indexing for two-column tables.
8004 * itemx:: How to put more entries in the first column.
8008 @node table, ftable vtable, Two-column Tables, Two-column Tables
8009 @subheading Using the @code{@@table} Command
8011 Use the @code{@@table} command to produce two-column tables.@refill
8014 Write the @code{@@table} command at the beginning of a line and follow
8015 it on the same line with an argument that is a Texinfo ``indicating''
8016 command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8017 @code{@@kbd} (@pxref{Indicating}). Although these commands are usually
8018 followed by arguments in braces, in this case you use the command name
8019 without an argument because @code{@@item} will supply the argument.
8020 This command will be applied to the text that goes into the first column
8021 of each item and determines how it will be highlighted. For example,
8022 @code{@@code} will cause the text in the first column to be highlighted
8023 with an @code{@@code} command. (We recommend @code{@@code} for
8024 @code{@@table}'s of command-line options.)
8027 You may also choose to use the @code{@@asis} command as an argument to
8028 @code{@@table}. @code{@@asis} is a command that does nothing; if you
8029 use this command after @code{@@table}, @TeX{} and the Info formatting
8030 commands output the first column entries without added highlighting
8033 (The @code{@@table} command may work with other commands besides those
8034 listed here. However, you can only use commands that normally take
8035 arguments in braces.)@refill
8037 Begin each table entry with an @code{@@item} command at the beginning
8038 of a line. Write the first column text on the same line as the
8039 @code{@@item} command. Write the second column text on the line
8040 following the @code{@@item} line and on subsequent lines. (You do not
8041 need to type anything for an empty second column entry.) You may
8042 write as many lines of supporting text as you wish, even several
8043 paragraphs. But only text on the same line as the @code{@@item} will
8044 be placed in the first column.@refill
8047 Normally, you should put a blank line before an @code{@@item} line.
8048 This puts a blank like in the Info file. Except when the entries are
8049 very brief, a blank line looks better.@refill
8052 The following table, for example, highlights the text in the first
8053 column with an @code{@@samp} command:@refill
8059 This is the text for
8063 Text for @@samp@{bar@}.
8073 This is the text for
8076 Text for @samp{bar}.
8079 If you want to list two or more named items with a single block of
8080 text, use the @code{@@itemx} command. (@xref{itemx, ,
8081 @code{@@itemx}}.)@refill
8083 @node ftable vtable, itemx, table, Two-column Tables
8084 @comment node-name, next, previous, up
8085 @subsection @code{@@ftable} and @code{@@vtable}
8086 @cindex Tables with indexes
8087 @cindex Indexing table entries automatically
8091 The @code{@@ftable} and @code{@@vtable} commands are the same as the
8092 @code{@@table} command except that @code{@@ftable} automatically enters
8093 each of the items in the first column of the table into the index of
8094 functions and @code{@@vtable} automatically enters each of the items in
8095 the first column of the table into the index of variables. This
8096 simplifies the task of creating indices. Only the items on the same
8097 line as the @code{@@item} commands are indexed, and they are indexed in
8098 exactly the form that they appear on that line. @xref{Indices, ,
8099 Creating Indices}, for more information about indices.@refill
8101 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8102 writing the @@-command at the beginning of a line, followed on the same
8103 line by an argument that is a Texinfo command such as @code{@@code},
8104 exactly as you would for an @code{@@table} command; and end the table
8105 with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8108 See the example for @code{@@table} in the previous section.
8110 @node itemx, , ftable vtable, Two-column Tables
8111 @comment node-name, next, previous, up
8112 @subsection @code{@@itemx}
8113 @cindex Two named items for @code{@@table}
8116 Use the @code{@@itemx} command inside a table when you have two or more
8117 first column entries for the same item, each of which should appear on a
8118 line of its own. Use @code{@@itemx} for all but the first entry;
8119 @code{@@itemx} should always follow an @code{@@item} command. The
8120 @code{@@itemx} command works exactly like @code{@@item} except that it
8121 does not generate extra vertical space above the first column text.
8131 These two functions accept a character or a string as
8132 argument, and return the corresponding upper case (lower
8133 case) character or string.
8144 These two functions accept a character or a string as
8145 argument, and return the corresponding upper case (lower
8146 case) character or string.@refill
8150 (Note also that this example illustrates multi-line supporting text in
8151 a two-column table.)@refill
8154 @node Multi-column Tables, , Two-column Tables, Lists and Tables
8155 @section Multi-column Tables
8156 @cindex Tables, making multi-column
8159 @code{@@multitable} allows you to construct tables with any number of
8160 columns, with each column having any width you like.
8162 You define the column widths on the @code{@@multitable} line itself, and
8163 write each row of the actual table following an @code{@@item} command,
8164 with columns separated by an @code{@@tab} command. Finally, @code{@@end
8165 multitable} completes the table. Details in the sections below.
8168 * Multitable Column Widths:: Defining multitable column widths.
8169 * Multitable Rows:: Defining multitable rows, with examples.
8172 @node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables
8173 @subsection Multitable Column Widths
8174 @cindex Multitable column widths
8175 @cindex Column widths, defining for multitables
8176 @cindex Widths, defining multitable column
8178 You can define the column widths for a multitable in two ways: as
8179 fractions of the line length; or with a prototype row. Mixing the two
8180 methods is not supported. In either case, the widths are defined
8181 entirely on the same line as the @code{@@multitable} command.
8185 @findex columnfractions
8186 @cindex Line length, column widths as fraction of
8187 To specify column widths as fractions of the line length, write
8188 @code{@@columnfractions} and the decimal numbers (presumably less than
8189 1) after the @code{@@multitable} command, as in:
8192 @@multitable @@columnfractions .33 .33 .33
8196 The fractions need not add up exactly to 1.0, as these do
8197 not. This allows you to produce tables that do not need the full line
8201 @cindex Prototype row, column widths defined by
8202 To specify a prototype row, write the longest entry for each column
8203 enclosed in braces after the @code{@@multitable} command. For example:
8206 @@multitable @{some text for column one@} @{for column two@}
8210 The first column will then have the width of the typeset `some text for
8211 column one', and the second column the width of `for column two'.
8213 The prototype entries need not appear in the table itself.
8215 Although we used simple text in this example, the prototype entries can
8216 contain Texinfo commands; markup commands such as @code{@@code} are
8217 particularly likely to be useful.
8222 @node Multitable Rows, , Multitable Column Widths, Multi-column Tables
8223 @subsection Multitable Rows
8224 @cindex Multitable rows
8225 @cindex Rows, of a multitable
8229 After the @code{@@multitable} command defining the column widths (see
8230 the previous section), you begin each row in the body of a multitable
8231 with @code{@@item}, and separate the column entries with @code{@@tab}.
8232 Line breaks are not special within the table body, and you may break
8233 input lines in your source file as necessary.
8235 Here is a complete example of a multi-column table (the text is from
8236 @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
8237 xemacs, XEmacs User's Manual}):
8240 @@multitable @@columnfractions .15 .45 .4
8241 @@item Key @@tab Command @@tab Description
8243 @@tab @@code@{split-window-vertically@}
8244 @@tab Split the selected window into two windows,
8245 with one above the other.
8247 @@tab @@code@{split-window-horizontally@}
8248 @@tab Split the selected window into two windows
8249 positioned side by side.
8252 @@tab In the mode line or scroll bar of a window,
8260 @multitable @columnfractions .15 .45 .4
8261 @item Key @tab Command @tab Description
8263 @tab @code{split-window-vertically}
8264 @tab Split the selected window into two windows,
8265 with one above the other.
8267 @tab @code{split-window-horizontally}
8268 @tab Split the selected window into two windows
8269 positioned side by side.
8272 @tab In the mode line or scroll bar of a window,
8277 @node Indices, Insertions, Lists and Tables, Top
8278 @comment node-name, next, previous, up
8279 @chapter Creating Indices
8281 @cindex Creating indices
8283 Using Texinfo, you can generate indices without having to sort and
8284 collate entries manually. In an index, the entries are listed in
8285 alphabetical order, together with information on how to find the
8286 discussion of each entry. In a printed manual, this information
8287 consists of page numbers. In an Info file, this information is a menu
8288 entry leading to the first node referenced.@refill
8290 Texinfo provides several predefined kinds of index: an index
8291 for functions, an index for variables, an index for concepts, and so
8292 on. You can combine indices or use them for other than their
8293 canonical purpose. If you wish, you can define your own indices.@refill
8296 * Index Entries:: Choose different words for index entries.
8297 * Predefined Indices:: Use different indices for different kinds
8299 * Indexing Commands:: How to make an index entry.
8300 * Combining Indices:: How to combine indices.
8301 * New Indices:: How to define your own indices.
8304 @node Index Entries, Predefined Indices, Indices, Indices
8305 @comment node-name, next, previous, up
8306 @section Making Index Entries
8307 @cindex Index entries, making
8308 @cindex Entries, making index
8310 When you are making index entries, it is good practice to think of the
8311 different ways people may look for something. Different people
8312 @emph{do not} think of the same words when they look something up. A
8313 helpful index will have items indexed under all the different words
8314 that people may use. For example, one reader may think it obvious that
8315 the two-letter names for indices should be listed under ``Indices,
8316 two-letter names'', since the word ``Index'' is the general concept.
8317 But another reader may remember the specific concept of two-letter
8318 names and search for the entry listed as ``Two letter names for
8319 indices''. A good index will have both entries and will help both
8322 Like typesetting, the construction of an index is a highly skilled,
8323 professional art, the subtleties of which are not appreciated until you
8324 need to do it yourself.@refill
8326 @xref{Printing Indices & Menus}, for information about printing an index
8327 at the end of a book or creating an index menu in an Info file.@refill
8329 @node Predefined Indices, Indexing Commands, Index Entries, Indices
8330 @comment node-name, next, previous, up
8331 @section Predefined Indices
8333 Texinfo provides six predefined indices:@refill
8337 A @dfn{concept index} listing concepts that are discussed.@refill
8340 A @dfn{function index} listing functions (such as entry points of
8344 A @dfn{variables index} listing variables (such as global variables
8345 of libraries).@refill
8348 A @dfn{keystroke index} listing keyboard commands.@refill
8351 A @dfn{program index} listing names of programs.@refill
8354 A @dfn{data type index} listing data types (such as structures defined in
8355 header files).@refill
8359 Not every manual needs all of these, and most manuals use two or three
8360 of them. This manual has two indices: a
8361 concept index and an @@-command index (that is actually the function
8362 index but is called a command index in the chapter heading). Two or
8363 more indices can be combined into one using the @code{@@synindex} or
8364 @code{@@syncodeindex} commands. @xref{Combining Indices}.@refill
8366 @node Indexing Commands, Combining Indices, Predefined Indices, Indices
8367 @comment node-name, next, previous, up
8368 @section Defining the Entries of an Index
8369 @cindex Defining indexing entries
8370 @cindex Index entries
8371 @cindex Entries for an index
8372 @cindex Specifying index entries
8373 @cindex Creating index entries
8375 The data to make an index come from many individual indexing commands
8376 scattered throughout the Texinfo source file. Each command says to add
8377 one entry to a particular index; after formatting, the index will give
8378 the current page number or node name as the reference.@refill
8380 An index entry consists of an indexing command at the beginning of a
8381 line followed, on the rest of the line, by the entry.@refill
8383 For example, this section begins with the following five entries for
8384 the concept index:@refill
8387 @@cindex Defining indexing entries
8388 @@cindex Index entries
8389 @@cindex Entries for an index
8390 @@cindex Specifying index entries
8391 @@cindex Creating index entries
8394 Each predefined index has its own indexing command---@code{@@cindex}
8395 for the concept index, @code{@@findex} for the function index, and so
8398 @cindex Writing index entries
8399 @cindex Index entry writing
8400 Concept index entries consist of text. The best way to write an index
8401 is to choose entries that are terse yet clear. If you can do this,
8402 the index often looks better if the entries are not capitalized, but
8403 written just as they would appear in the middle of a sentence.
8404 (Capitalize proper names and acronyms that always call for upper case
8405 letters.) This is the case convention we use in most GNU manuals'
8408 If you don't see how to make an entry terse yet clear, make it longer
8409 and clear---not terse and confusing. If many of the entries are several
8410 words long, the index may look better if you use a different convention:
8411 to capitalize the first word of each entry. But do not capitalize a
8412 case-sensitive name such as a C or Lisp function name or a shell
8413 command; that would be a spelling error.
8415 Whichever case convention you use, please use it consistently!
8418 Concept index entries consist of English text. The usual convention
8419 is to capitalize the first word of each such index entry, unless that
8420 word is the name of a function, variable, or other such entity that
8421 should not be capitalized. However, if your concept index entries are
8422 consistently short (one or two words each) it may look better for each
8423 regular entry to start with a lower case letter, aside from proper
8424 names and acronyms that always call for upper case letters. Whichever
8425 convention you adapt, please be consistent!
8428 Entries in indices other than the concept index are symbol names in
8429 programming languages, or program names; these names are usually
8430 case-sensitive, so use upper and lower case as required for them.
8432 By default, entries for a concept index are printed in a small roman
8433 font and entries for the other indices are printed in a small
8434 @code{@@code} font. You may change the way part of an entry is
8435 printed with the usual Texinfo commands, such as @code{@@file} for
8436 file names and @code{@@emph} for emphasis (@pxref{Marking
8438 @cindex Index font types
8440 @cindex Predefined indexing commands
8441 @cindex Indexing commands, predefined
8442 The six indexing commands for predefined indices are:
8445 @item @@cindex @var{concept}
8447 Make an entry in the concept index for @var{concept}.@refill
8449 @item @@findex @var{function}
8451 Make an entry in the function index for @var{function}.@refill
8453 @item @@vindex @var{variable}
8455 Make an entry in the variable index for @var{variable}.@refill
8457 @item @@kindex @var{keystroke}
8459 Make an entry in the key index for @var{keystroke}.@refill
8461 @item @@pindex @var{program}
8463 Make an entry in the program index for @var{program}.@refill
8465 @item @@tindex @var{data type}
8467 Make an entry in the data type index for @var{data type}.@refill
8471 @strong{Caution:} Do not use a colon in an index entry. In Info, a
8472 colon separates the menu entry name from the node name. An extra
8473 colon confuses Info.
8474 @xref{Menu Parts, , The Parts of a Menu},
8475 for more information about the structure of a menu entry.@refill
8478 If you write several identical index entries in different places in a
8479 Texinfo file, the index in the printed manual will list all the pages to
8480 which those entries refer. However, the index in the Info file will
8481 list @strong{only} the node that references the @strong{first} of those
8482 index entries. Therefore, it is best to write indices in which each
8483 entry refers to only one place in the Texinfo file. Fortunately, this
8484 constraint is a feature rather than a loss since it means that the index
8485 will be easy to use. Otherwise, you could create an index that lists
8486 several pages for one entry and your reader would not know to which page
8487 to turn. If you have two identical entries for one topic, change the
8488 topics slightly, or qualify them to indicate the difference.@refill
8490 You are not actually required to use the predefined indices for their
8491 canonical purposes. For example, suppose you wish to index some C
8492 preprocessor macros. You could put them in the function index along
8493 with actual functions, just by writing @code{@@findex} commands for
8494 them; then, when you print the ``Function Index'' as an unnumbered
8495 chapter, you could give it the title `Function and Macro Index' and
8496 all will be consistent for the reader. Or you could put the macros in
8497 with the data types by writing @code{@@tindex} commands for them, and
8498 give that index a suitable title so the reader will understand.
8499 (@xref{Printing Indices & Menus}.)@refill
8501 @node Combining Indices, New Indices, Indexing Commands, Indices
8502 @comment node-name, next, previous, up
8503 @section Combining Indices
8504 @cindex Combining indices
8505 @cindex Indices, combining them
8507 Sometimes you will want to combine two disparate indices such as functions
8508 and concepts, perhaps because you have few enough of one of them that
8509 a separate index for them would look silly.@refill
8511 You could put functions into the concept index by writing
8512 @code{@@cindex} commands for them instead of @code{@@findex} commands,
8513 and produce a consistent manual by printing the concept index with the
8514 title `Function and Concept Index' and not printing the `Function
8515 Index' at all; but this is not a robust procedure. It works only if
8516 your document is never included as part of another
8517 document that is designed to have a separate function index; if your
8518 document were to be included with such a document, the functions from
8519 your document and those from the other would not end up together.
8520 Also, to make your function names appear in the right font in the
8521 concept index, you would need to enclose every one of them between
8522 the braces of @code{@@code}.@refill
8525 * syncodeindex:: How to merge two indices, using @code{@@code}
8526 font for the merged-from index.
8527 * synindex:: How to merge two indices, using the
8528 default font of the merged-to index.
8531 @node syncodeindex, synindex, Combining Indices, Combining Indices
8532 @subsection @code{@@syncodeindex}
8533 @findex syncodeindex
8535 When you want to combine functions and concepts into one index, you
8536 should index the functions with @code{@@findex} and index the concepts
8537 with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8538 redirect the function index entries into the concept index.@refill
8539 @findex syncodeindex
8541 The @code{@@syncodeindex} command takes two arguments; they are the name
8542 of the index to redirect, and the name of the index to redirect it to.
8543 The template looks like this:@refill
8546 @@syncodeindex @var{from} @var{to}
8549 @cindex Predefined names for indices
8550 @cindex Two letter names for indices
8551 @cindex Indices, two letter names
8552 @cindex Names for indices
8553 For this purpose, the indices are given two-letter names:@refill
8570 Write an @code{@@syncodeindex} command before or shortly after the
8571 end-of-header line at the beginning of a Texinfo file. For example,
8572 to merge a function index with a concept index, write the
8576 @@syncodeindex fn cp
8580 This will cause all entries designated for the function index to merge
8581 in with the concept index instead.@refill
8583 To merge both a variables index and a function index into a concept
8584 index, write the following:@refill
8588 @@syncodeindex vr cp
8589 @@syncodeindex fn cp
8593 @cindex Fonts for indices
8594 The @code{@@syncodeindex} command puts all the entries from the `from'
8595 index (the redirected index) into the @code{@@code} font, overriding
8596 whatever default font is used by the index to which the entries are
8597 now directed. This way, if you direct function names from a function
8598 index into a concept index, all the function names are printed in the
8599 @code{@@code} font as you would expect.@refill
8601 @node synindex, , syncodeindex, Combining Indices
8602 @subsection @code{@@synindex}
8605 The @code{@@synindex} command is nearly the same as the
8606 @code{@@syncodeindex} command, except that it does not put the
8607 `from' index entries into the @code{@@code} font; rather it puts
8608 them in the roman font. Thus, you use @code{@@synindex} when you
8609 merge a concept index into a function index.@refill
8611 @xref{Printing Indices & Menus}, for information about printing an index
8612 at the end of a book or creating an index menu in an Info file.@refill
8614 @node New Indices, , Combining Indices, Indices
8615 @section Defining New Indices
8616 @cindex Defining new indices
8617 @cindex Indices, defining new
8618 @cindex New index defining
8620 @findex defcodeindex
8622 In addition to the predefined indices, you may use the
8623 @code{@@defindex} and @code{@@defcodeindex} commands to define new
8624 indices. These commands create new indexing @@-commands with which
8625 you mark index entries. The @code{@@defindex }command is used like
8629 @@defindex @var{name}
8632 The name of an index should be a two letter word, such as @samp{au}.
8639 This defines a new index, called the @samp{au} index. At the same
8640 time, it creates a new indexing command, @code{@@auindex}, that you
8641 can use to make index entries. Use the new indexing command just as
8642 you would use a predefined indexing command.@refill
8644 For example, here is a section heading followed by a concept index
8645 entry and two @samp{au} index entries.@refill
8648 @@section Cognitive Semantics
8649 @@cindex kinesthetic image schemas
8650 @@auindex Johnson, Mark
8651 @@auindex Lakoff, George
8655 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
8656 Texinfo constructs the new indexing command by concatenating the name
8657 of the index with @samp{index}; thus, defining an @samp{au} index
8658 leads to the automatic creation of an @code{@@auindex} command.@refill
8660 Use the @code{@@printindex} command to print the index, as you do with
8661 the predefined indices. For example:@refill
8665 @@node Author Index, Subject Index, , Top
8666 @@unnumbered Author Index
8672 The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8673 that, in the printed output, it prints entries in an @code{@@code} font
8674 instead of a roman font. Thus, it parallels the @code{@@findex} command
8675 rather than the @code{@@cindex} command.@refill
8677 You should define new indices within or right after the end-of-header
8678 line of a Texinfo file, before any @code{@@synindex} or
8679 @code{@@syncodeindex} commands (@pxref{Header}).@refill
8681 @node Insertions, Breaks, Indices, Top
8682 @comment node-name, next, previous, up
8683 @chapter Special Insertions
8684 @cindex Inserting special characters and symbols
8685 @cindex Special insertions
8687 Texinfo provides several commands for inserting characters that have
8688 special meaning in Texinfo, such as braces, and for other graphic
8689 elements that do not correspond to simple characters you can type.
8695 @item Braces, @samp{@@} and periods.
8696 @item Whitespace within and around a sentence.
8698 @item Dots and bullets.
8699 @item The @TeX{} logo and the copyright symbol.
8700 @item Mathematical expressions.
8705 * Braces Atsigns:: How to insert braces, @samp{@@}.
8706 * Inserting Space:: How to insert the right amount of space
8708 * Inserting Accents:: How to insert accents and special characters.
8709 * Dots Bullets:: How to insert dots and bullets.
8710 * TeX and copyright:: How to insert the @TeX{} logo
8711 and the copyright symbol.
8712 * pounds:: How to insert the pounds currency symbol.
8713 * minus:: How to insert a minus sign.
8714 * math:: How to format a mathematical expression.
8715 * Glyphs:: How to indicate results of evaluation,
8716 expansion of macros, errors, etc.
8717 * Images:: How to include graphics.
8721 @node Braces Atsigns, Inserting Space, Insertions, Insertions
8722 @section Inserting @@ and Braces
8723 @cindex Inserting @@, braces
8724 @cindex Braces, inserting
8725 @cindex Special characters, commands to insert
8726 @cindex Commands to insert special characters
8728 @samp{@@} and curly braces are special characters in Texinfo. To insert
8729 these characters so they appear in text, you must put an @samp{@@} in
8730 front of these characters to prevent Texinfo from misinterpreting
8733 Do not put braces after any of these commands; they are not
8737 * Inserting An Atsign:: How to insert @samp{@@}.
8738 * Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
8741 @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
8742 @subsection Inserting @samp{@@} with @@@@
8743 @findex @@ @r{(single @samp{@@})}
8745 @code{@@@@} stands for a single @samp{@@} in either printed or Info
8748 Do not put braces after an @code{@@@@} command.
8750 @node Inserting Braces, , Inserting An Atsign, Braces Atsigns
8751 @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
8752 @findex @{ @r{(single @samp{@{})}
8753 @findex @} @r{(single @samp{@}})}
8755 @code{@@@{} stands for a single @samp{@{} in either printed or Info
8758 @code{@@@}} stands for a single @samp{@}} in either printed or Info
8761 Do not put braces after either an @code{@@@{} or an @code{@@@}}
8765 @node Inserting Space, Inserting Accents, Braces Atsigns, Insertions
8766 @section Inserting Space
8768 @cindex Inserting space
8769 @cindex Spacing, inserting
8770 @cindex Whitespace, inserting
8771 The following sections describe commands that control spacing of various
8772 kinds within and after sentences.
8775 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
8776 * Ending a Sentence:: Sometimes it does.
8777 * Multiple Spaces:: Inserting multiple spaces.
8778 * dmn:: How to format a dimension.
8781 @node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space
8782 @subsection Not Ending a Sentence
8784 @cindex Not ending a sentence
8785 @cindex Sentence non-ending punctuation
8786 @cindex Periods, inserting
8787 Depending on whether a period or exclamation point or question mark is
8788 inside or at the end of a sentence, less or more space is inserted after
8789 a period in a typeset manual. Since it is not always possible for
8790 Texinfo to determine when a period ends a sentence and when it is used
8791 in an abbreviation, special commands are needed in some circumstances.
8792 (Usually, Texinfo can guess how to handle periods, so you do not need to
8793 use the special commands; you just enter a period as you would if you
8794 were using a typewriter, which means you put two spaces after the
8795 period, question mark, or exclamation mark that ends a sentence.)
8797 @findex : @r{(suppress widening)}
8798 Use the @code{@@:}@: command after a period, question mark,
8799 exclamation mark, or colon that should not be followed by extra space.
8800 For example, use @code{@@:}@: after periods that end abbreviations
8801 which are not at the ends of sentences.
8807 The s.o.p.@@: has three parts @dots{}
8808 The s.o.p. has three parts @dots{}
8816 produces the following. If you look carefully at this printed output,
8817 you will see a little more whitespace after @samp{s.o.p.} in the second
8822 The s.o.p.@: has three parts @dots{}@*
8823 The s.o.p. has three parts @dots{}
8827 (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
8830 @code{@@:} has no effect on the Info output. Do not put braces after
8834 @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
8835 @subsection Ending a Sentence
8837 @cindex Ending a Sentence
8838 @cindex Sentence ending punctuation
8840 @findex . @r{(end of sentence)}
8841 @findex ! @r{(end of sentence)}
8842 @findex ? @r{(end of sentence)}
8843 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
8844 exclamation point, and @code{@@?}@: instead of a question mark at the end
8845 of a sentence that ends with a single capital letter. Otherwise, @TeX{}
8846 will think the letter is an abbreviation and will not insert the correct
8847 end-of-sentence spacing. Here is an example:
8850 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
8851 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
8859 produces the following. If you look carefully at this printed output,
8860 you will see a little more whitespace after the @samp{W} in the first
8865 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
8866 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
8869 In the Info file output, @code{@@.}@: is equivalent to a simple
8870 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
8872 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
8873 work well with the Emacs sentence motion commands (@pxref{Sentences,,,
8874 xemacs, XEmacs User's Manual}). This made it necessary for them to be
8875 incompatible with some other formatting systems that use @@-commands.
8877 Do not put braces after any of these commands.
8880 @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
8881 @subsection Multiple Spaces
8883 @cindex Multiple spaces
8884 @cindex Whitespace, inserting
8889 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
8890 and newline) into a single space. Info output, on the other hand,
8891 preserves whitespace as you type it, except for changing a newline into
8892 a space; this is why it is important to put two spaces at the end of
8893 sentences in Texinfo documents.
8895 Occasionally, you may want to actually insert several consecutive
8896 spaces, either for purposes of example (what your program does with
8897 multiple spaces as input), or merely for purposes of appearance in
8898 headings or lists. Texinfo supports three commands:
8899 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
8900 which insert a single space into the output. (Here,
8901 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
8902 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
8903 character and end-of-line, i.e., when @samp{@@} is the last character on
8920 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
8921 @code{@@multitable} (@pxref{Multi-column Tables}).
8923 Do not follow any of these commands with braces.
8926 @node dmn, , Multiple Spaces, Inserting Space
8927 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
8928 @cindex Thin space between number, dimension
8929 @cindex Dimension formatting
8930 @cindex Format a dimension
8933 At times, you may want to write @samp{12@dmn{pt}} or
8934 @samp{8.5@dmn{in}} with little or no space between the number and the
8935 abbreviation for the dimension. You can use the @code{@@dmn} command
8936 to do this. On seeing the command, @TeX{} inserts just enough space
8937 for proper typesetting; the Info formatting commands insert no space
8938 at all, since the Info file does not require it.@refill
8940 To use the @code{@@dmn} command, write the number and then follow it
8941 immediately, with no intervening space, by @code{@@dmn}, and then by
8942 the dimension within braces. For example,
8945 A4 paper is 8.27@@dmn@{in@} wide.
8952 A4 paper is 8.27@dmn{in} wide.
8955 Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
8956 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
8957 In these cases, however, the formatters may insert a line break between
8958 the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
8959 you write a period after an abbreviation within a sentence, you should
8960 write @samp{@@:} after the period to prevent @TeX{} from inserting extra
8961 whitespace, as shown here. @xref{Inserting Space}.
8964 @node Inserting Accents, Dots Bullets, Inserting Space, Insertions
8965 @section Inserting Accents
8967 @cindex Inserting accents
8968 @cindex Accents, inserting
8969 @cindex Floating accents, inserting
8971 Here is a table with the commands Texinfo provides for inserting
8972 floating accents. The commands with non-alphabetic names do not take
8973 braces around their argument (which is taken to be the next character).
8974 (Exception: @code{@@,} @emph{does} take braces around its argument.)
8975 This is so as to make the source as convenient to type and read as
8976 possible, since accented characters are very common in some languages.
8979 @cindex Umlaut accent
8981 @cindex Acute accent
8983 @cindex Macron accent
8985 @cindex Circumflex accent
8987 @cindex Grave accent
8989 @cindex Tilde accent
8991 @cindex Cedilla accent
8995 @cindex Hungariam umlaut accent
8999 @cindex Tie-after accent
9001 @cindex Breve accent
9003 @cindex Underbar accent
9005 @cindex Underdot accent
9007 @cindex Check accent
9008 @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9009 @item Command @tab Output @tab What
9010 @item @t{@@"o} @tab @"o @tab umlaut accent
9011 @item @t{@@'o} @tab @'o @tab acute accent
9012 @item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9013 @item @t{@@=o} @tab @=o @tab macron/overbar accent
9014 @item @t{@@^o} @tab @^o @tab circumflex accent
9015 @item @t{@@`o} @tab @`o @tab grave accent
9016 @item @t{@@~o} @tab @~o @tab tilde accent
9017 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
9018 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
9019 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9020 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9021 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent
9022 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9023 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9024 @item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent
9027 This table lists the Texinfo commands for inserting other characters
9028 commonly used in languages other than English.
9030 @findex questiondown
9031 @cindex @questiondown{}
9033 @cindex @exclamdown{}
9045 @cindex Dotless i, j
9063 @multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
9064 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
9065 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9066 @item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle
9067 @item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures
9068 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
9069 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
9070 @item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l
9071 @item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash
9072 @item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures
9073 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
9077 @node Dots Bullets, TeX and copyright, Inserting Accents, Insertions
9078 @section Inserting Ellipsis, Dots, and Bullets
9079 @cindex Dots, inserting
9080 @cindex Bullets, inserting
9081 @cindex Ellipsis, inserting
9082 @cindex Inserting ellipsis
9083 @cindex Inserting dots
9084 @cindex Special typesetting commands
9085 @cindex Typesetting commands for dots, etc.
9087 An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9088 periods, so a special command is used for ellipsis in Texinfo. The
9089 @code{@@bullet} command is special, too. Each of these commands is
9090 followed by a pair of braces, @samp{@{@}}, without any whitespace
9091 between the name of the command and the braces. (You need to use braces
9092 with these commands because you can use them next to other text; without
9093 the braces, the formatters would be confused. @xref{Command Syntax, ,
9094 @@-Command Syntax}, for further information.)@refill
9097 * dots:: How to insert dots @dots{}
9098 * bullet:: How to insert a bullet.
9102 @node dots, bullet, Dots Bullets, Dots Bullets
9103 @subsection @code{@@dots}@{@} (@dots{})
9105 @cindex Inserting dots
9106 @cindex Dots, inserting
9108 Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9109 three dots in a row, appropriately spaced, like this: `@dots{}'. Do
9110 not simply write three periods in the input file; that would work for
9111 the Info file output, but would produce the wrong amount of space
9112 between the periods in the printed manual.
9114 Similarly, the @code{@@enddots@{@}} command generates an
9115 end-of-sentence ellipsis (four dots) @enddots{}
9118 Here is an ellipsis: @dots{}
9119 Here are three periods in a row: ...
9121 In printed output, the three periods in a row are closer together than
9122 the dots in the ellipsis.
9126 @node bullet, , dots, Dots Bullets
9127 @subsection @code{@@bullet}@{@} (@bullet{})
9130 Use the @code{@@bullet@{@}} command to generate a large round dot, or
9131 the closest possible thing to one. In Info, an asterisk is used.@refill
9133 Here is a bullet: @bullet{}
9135 When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9136 type the braces, because @code{@@itemize} supplies them.
9137 (@xref{itemize, , @code{@@itemize}}.)@refill
9140 @node TeX and copyright, pounds, Dots Bullets, Insertions
9141 @section Inserting @TeX{} and the Copyright Symbol
9143 The logo `@TeX{}' is typeset in a special fashion and it needs an
9144 @@-command. The copyright symbol, `@copyright{}', is also special.
9145 Each of these commands is followed by a pair of braces, @samp{@{@}},
9146 without any whitespace between the name of the command and the
9150 * tex:: How to insert the @TeX{} logo.
9151 * copyright symbol:: How to use @code{@@copyright}@{@}.
9155 @node tex, copyright symbol, TeX and copyright, TeX and copyright
9156 @subsection @code{@@TeX}@{@} (@TeX{})
9157 @findex tex (command)
9159 Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
9160 manual, this is a special logo that is different from three ordinary
9161 letters. In Info, it just looks like @samp{TeX}. The
9162 @code{@@TeX@{@}} command is unique among Texinfo commands in that the
9163 @kbd{T} and the @kbd{X} are in upper case.@refill
9166 @node copyright symbol, , tex, TeX and copyright
9167 @subsection @code{@@copyright}@{@} (@copyright{})
9170 Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
9171 a printed manual, this is a @samp{c} inside a circle, and in Info,
9172 this is @samp{(C)}.@refill
9175 @node pounds, minus, TeX and copyright, Insertions
9176 @section @code{@@pounds@{@}} (@pounds{}): Pounds Sterling
9179 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a
9180 printed manual, this is the symbol for the currency pounds sterling.
9181 In Info, it is a @samp{#}. Other currency symbols are unfortunately not
9185 @node minus, math, pounds, Insertions
9186 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9189 Use the @code{@@minus@{@}} command to generate a minus sign. In a
9190 fixed-width font, this is a single hyphen, but in a proportional font,
9191 the symbol is the customary length for a minus sign---a little longer
9192 than a hyphen, shorter than an em-dash:
9195 @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9197 `-' is a hyphen generated with the character @samp{-},
9199 `---' is an em-dash for text.
9203 In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9206 You should not use @code{@@minus@{@}} inside @code{@@code} or
9207 @code{@@example} because the width distinction is not made in the
9208 fixed-width font they use.
9210 When you use @code{@@minus} to specify the mark beginning each entry in
9211 an itemized list, you do not need to type the braces
9212 (@pxref{itemize, , @code{@@itemize}}.)
9215 @node math, Glyphs, minus, Insertions
9216 @section @code{@@math} - Inserting Mathematical Expressions
9218 @cindex Mathematical expressions
9220 You can write a short mathematical expression with the @code{@@math}
9221 command. Write the mathematical expression between braces, like this:
9224 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9230 This produces the following in @TeX{}:
9233 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
9237 and the following in Info:
9241 This produces the following in Info:
9245 (a + b)(a + b) = a^2 + 2ab + b^2
9248 Thus, the @code{@@math} command has no effect on the Info output.
9250 For complex mathematical expressions, you can also use @TeX{} directly
9251 (@pxref{Raw Formatter Commands}). When you use @TeX{} directly,
9252 remember to write the mathematical expression between one or two
9253 @samp{$} (dollar-signs) as appropriate.
9256 @node Glyphs, Images, math, Insertions
9257 @section Glyphs for Examples
9260 In Texinfo, code is often illustrated in examples that are delimited
9261 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9262 @code{@@end lisp}. In such examples, you can indicate the results of
9263 evaluation or an expansion using @samp{@result{}} or
9264 @samp{@expansion{}}. Likewise, there are commands to insert glyphs
9266 printed output, error messages, equivalence of expressions, and the
9267 location of point.@refill
9269 The glyph-insertion commands do not need to be used within an example, but
9270 most often they are. Every glyph-insertion command is followed by a pair of
9271 left- and right-hand braces.@refill
9275 * result:: How to show the result of expression.
9276 * expansion:: How to indicate an expansion.
9277 * Print Glyph:: How to indicate printed output.
9278 * Error Glyph:: How to indicate an error message.
9279 * Equivalence:: How to indicate equivalence.
9280 * Point Glyph:: How to indicate the location of point.
9283 @node Glyphs Summary, result, Glyphs, Glyphs
9285 @subheading Glyphs Summary
9287 Here are the different glyph commands:@refill
9292 @code{@@result@{@}} points to the result of an expression.@refill
9295 @code{@@expansion@{@}} shows the results of a macro expansion.@refill
9298 @code{@@print@{@}} indicates printed output.@refill
9301 @code{@@error@{@}} indicates that the following text is an error
9305 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9308 @code{@@point@{@}} shows the location of point.@refill
9321 @node result, expansion, Glyphs Summary, Glyphs
9322 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9323 @cindex Result of an expression
9324 @cindex Indicating evaluation
9325 @cindex Evaluation glyph
9326 @cindex Value of an expression, indicating
9328 Use the @code{@@result@{@}} command to indicate the result of
9329 evaluating an expression.@refill
9332 The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
9333 as @samp{@result{}} in the printed output.
9336 The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9337 and as a double stemmed arrow in the printed output.@refill
9340 Thus, the following,
9348 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9351 @node expansion, Print Glyph, result, Glyphs
9352 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9353 @cindex Expansion, indicating it
9355 When an expression is a macro call, it expands into a new expression.
9356 You can indicate the result of the expansion with the
9357 @code{@@expansion@{@}} command.@refill
9360 The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
9361 as @samp{@expansion{}} in the printed output.
9364 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9365 in Info and as a long arrow with a flat base in the printed output.@refill
9369 For example, the following
9375 @@expansion@{@} (car (cdr (cdr '(a b c))))
9387 @expansion{} (car (cdr (cdr '(a b c))))
9393 which may be read as:
9396 @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9397 the result of evaluating the expression is @code{c}.
9401 Often, as in this case, an example looks better if the
9402 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9406 @node Print Glyph, Error Glyph, expansion, Glyphs
9407 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9408 @cindex Printed output, indicating it
9410 Sometimes an expression will print output during its execution. You
9411 can indicate the printed output with the @code{@@print@{@}} command.@refill
9414 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
9415 as @samp{@print{}} in the printed output.
9418 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9419 and similarly, as a horizontal dash butting against a vertical bar, in
9420 the printed output.@refill
9423 In the following example, the printed text is indicated with
9424 @samp{@print{}}, and the value of the expression follows on the
9429 (progn (print 'foo) (print 'bar))
9437 In a Texinfo source file, this example is written as follows:
9442 (progn (print 'foo) (print 'bar))
9451 @node Error Glyph, Equivalence, Print Glyph, Glyphs
9452 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9453 @cindex Error message, indicating it
9455 A piece of code may cause an error when you evaluate it. You can
9456 designate the error message with the @code{@@error@{@}} command.@refill
9459 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
9460 and as @samp{@error{}} in the printed output.
9463 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9464 and as the word `error' in a box in the printed output.@refill
9473 @@error@{@} Wrong type argument: integer-or-marker-p, x
9482 @error{} Wrong type argument: integer-or-marker-p, x
9486 This indicates that the following error message is printed
9487 when you evaluate the expression:
9490 Wrong type argument: integer-or-marker-p, x
9493 @samp{@error{}} itself is not part of the error message.
9496 @node Equivalence, Point Glyph, Error Glyph, Glyphs
9497 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9498 @cindex Equivalence, indicating it
9500 Sometimes two expressions produce identical results. You can indicate the
9501 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9504 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
9505 as @samp{@equiv{}} in the printed output.
9508 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9509 and as a three parallel horizontal lines in the printed output.@refill
9516 (make-sparse-keymap) @@equiv@{@} (list 'keymap)
9524 (make-sparse-keymap) @equiv{} (list 'keymap)
9528 This indicates that evaluating @code{(make-sparse-keymap)} produces
9529 identical results to evaluating @code{(list 'keymap)}.
9532 @node Point Glyph, , Equivalence, Glyphs
9533 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9534 @cindex Point, indicating it in a buffer
9536 Sometimes you need to show an example of text in an Emacs buffer. In
9537 such examples, the convention is to include the entire contents of the
9538 buffer in question between two lines of dashes containing the buffer
9541 You can use the @samp{@@point@{@}} command to show the location of point
9542 in the text in the buffer. (The symbol for point, of course, is not
9543 part of the text in the buffer; it indicates the place @emph{between}
9544 two characters where point is located.)@refill
9547 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
9548 as @samp{@point{}} in the printed output.
9551 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9552 and as a small five pointed star in the printed output.@refill
9555 The following example shows the contents of buffer @file{foo} before
9556 and after evaluating a Lisp command to insert the word @code{changed}.@refill
9560 ---------- Buffer: foo ----------
9561 This is the @point{}contents of foo.
9562 ---------- Buffer: foo ----------
9571 ---------- Buffer: foo ----------
9572 This is the changed @point{}contents of foo.
9573 ---------- Buffer: foo ----------
9578 In a Texinfo source file, the example is written like this:@refill
9582 ---------- Buffer: foo ----------
9583 This is the @@point@{@}contents of foo.
9584 ---------- Buffer: foo ----------
9588 ---------- Buffer: foo ----------
9589 This is the changed @@point@{@}contents of foo.
9590 ---------- Buffer: foo ----------
9595 @c this should be described with figures when we have them
9596 @c perhaps in the quotation/example chapter.
9597 @node Images, , Glyphs, Insertions
9598 @section Inserting Images
9600 @cindex Images, inserting
9601 @cindex Pictures, inserting
9604 You can insert an image in an external file with the @code{@@image}
9608 @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@}
9611 @cindex Formats for images
9612 @cindex Image formats
9613 The @var{filename} argument is mandatory, and must not have an
9614 extension, because the different processors support different formats:
9615 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
9616 format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
9617 Info output (more or less as if it was an @code{@@example}). HTML
9618 output requires @file{@var{filename}.jpg}.
9620 @cindex Width of images
9621 @cindex Height of images
9622 @cindex Aspect ratio of images
9623 @cindex Distorting images
9624 The optional @var{width} and @var{height} arguments specify the size to
9625 scale the image to (they are ignored for Info output). If they are both
9626 specified, the image is presented in its natural size (given in the
9627 file); if only one is specified, the other is scaled proportionately;
9628 and if both are specified, both are respected, thus possibly distorting
9629 the original image by changing its aspect ratio.
9631 @cindex Dimensions and image sizes
9632 The @var{width} and @var{height} may be specified using any valid @TeX{}
9637 @cindex Points (dimension)
9638 point (72.27pt = 1in)
9644 big point (72bp = 1in)
9650 centimeter (2.54cm = 1in)
9653 millimeter (10mm = 1cm)
9655 @cindex Did@^ot points
9656 did@^ot point (1157dd = 1238pt)
9661 @cindex Scaled points
9662 scaled point (65536sp = 1pt)
9666 For example, the following will scale a file @file{ridt.eps} to one
9667 inch vertically, with the width scaled proportionately:
9670 @@image@{ridt,,1in@}
9674 For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
9675 installed somewhere that @TeX{} can find it. This file is included in
9676 the Texinfo distribution and is available from
9677 @uref{ftp://ftp.tug.org/tex/epsf.tex}.
9680 @node Breaks, Definition Commands, Insertions, Top
9681 @chapter Making and Preventing Breaks
9682 @cindex Making line and page breaks
9683 @cindex Preventing line and page breaks
9685 Usually, a Texinfo file is processed both by @TeX{} and by one of the
9686 Info formatting commands. Line, paragraph, or page breaks sometimes
9687 occur in the `wrong' place in one or other form of output. You must
9688 ensure that text looks right both in the printed manual and in the
9691 For example, in a printed manual, page breaks may occur awkwardly in
9692 the middle of an example; to prevent this, you can hold text together
9693 using a grouping command that keeps the text from being split across
9694 two pages. Conversely, you may want to force a page break where none
9695 would occur normally. Fortunately, problems like these do not often
9696 arise. When they do, use the break, break prevention, or pagination
9700 * Break Commands:: Cause and prevent splits.
9701 * Line Breaks:: How to force a single line to use two lines.
9702 * - and hyphenation:: How to tell TeX about hyphenation points.
9703 * w:: How to prevent unwanted line breaks.
9704 * sp:: How to insert blank lines.
9705 * page:: How to force the start of a new page.
9706 * group:: How to prevent unwanted page breaks.
9707 * need:: Another way to prevent unwanted page breaks.
9711 @node Break Commands, Line Breaks, Breaks, Breaks
9712 @heading The Break Commands
9718 The break commands create or allow line and paragraph breaks:@refill
9725 Skip @var{n} blank lines.@refill
9728 Insert a discretionary hyphen.
9730 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
9731 Define hyphen points in @var{hy-phen-a-ted words}.
9734 The line-break-prevention command holds text together all on one
9738 @item @@w@{@var{text}@}
9739 Prevent @var{text} from being split and hyphenated across two lines.@refill
9745 The pagination commands apply only to printed output, since Info
9746 files do not have pages.@refill
9750 Start a new page in the printed manual.@refill
9753 Hold text together that must appear on one printed page.@refill
9755 @item @@need @var{mils}
9756 Start a new printed page if not enough space on this one.@refill
9759 @node Line Breaks, - and hyphenation, Break Commands, Breaks
9760 @comment node-name, next, previous, up
9761 @section @code{@@*}: Generate Line Breaks
9762 @findex * @r{(force line break)}
9764 @cindex Breaks in a line
9766 The @code{@@*} command forces a line break in both the printed manual and
9773 This line @@* is broken @@*in two places.
9788 (Note that the space after the first @code{@@*} command is faithfully
9789 carried down to the next line.)@refill
9792 The @code{@@*} command is often used in a file's copyright page:@refill
9796 This is edition 2.0 of the Texinfo documentation,@@*
9802 In this case, the @code{@@*} command keeps @TeX{} from stretching the
9803 line across the whole page in an ugly manner.@refill
9806 @strong{Please note:} Do not write braces after an @code{@@*} command;
9807 they are not needed.@refill
9809 Do not write an @code{@@refill} command at the end of a paragraph
9810 containing an @code{@@*} command; it will cause the paragraph to be
9811 refilled after the line break occurs, negating the effect of the line
9815 @node - and hyphenation, w, Line Breaks, Breaks
9816 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
9820 @cindex Hyphenation, helping @TeX{} do
9821 @cindex Fine-tuning, and hyphenation
9823 Although @TeX{}'s hyphenation algorithm is generally pretty good, it
9824 does miss useful hyphenation points from time to time. (Or, far more
9825 rarely, insert an incorrect hyphenation.) So, for documents with an
9826 unusual vocabulary or when fine-tuning for a printed edition, you may
9827 wish to help @TeX{} out. Texinfo supports two commands for this:
9831 Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
9832 not have to) hyphenate. This is especially useful when you notice
9833 an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
9834 hboxes}). @TeX{} will not insert any hyphenation points in a word
9835 containing @code{@@-}.
9837 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
9838 Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
9839 put a @samp{-} at each hyphenation point. For example:
9841 @@hyphenation@{man-u-script man-u-scripts@}
9844 @TeX{} only uses the specified hyphenation points when the
9845 words match exactly, so give all necessary variants.
9848 Info output is not hyphenated, so these commands have no effect there.
9850 @node w, sp, - and hyphenation, Breaks
9851 @comment node-name, next, previous, up
9852 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
9853 @findex w @r{(prevent line break)}
9854 @cindex Line breaks, preventing
9855 @cindex Hyphenation, preventing
9857 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
9858 within @var{text}.@refill
9860 You can use the @code{@@w} command to prevent @TeX{} from automatically
9861 hyphenating a long name or phrase that happens to fall near the end of a
9865 You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}.
9872 You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
9876 @strong{Caution:} Do not write an @code{@@refill} command at the end
9877 of a paragraph containing an @code{@@w} command; it will cause the
9878 paragraph to be refilled and may thereby negate the effect of the
9879 @code{@@w} command.@refill
9882 @node sp, page, w, Breaks
9883 @comment node-name, next, previous, up
9884 @section @code{@@sp} @var{n}: Insert Blank Lines
9885 @findex sp @r{(line spacing)}
9886 @cindex Spaces (blank lines)
9888 @cindex Line spacing
9890 A line beginning with and containing only @code{@@sp @var{n}}
9891 generates @var{n} blank lines of space in both the printed manual and
9892 the Info file. @code{@@sp} also forces a paragraph break. For
9900 generates two blank lines.
9902 The @code{@@sp} command is most often used in the title page.@refill
9905 @c node br, page, sp, Breaks
9906 @comment node-name, next, previous, up
9907 @c section @code{@@br}: Generate Paragraph Breaks
9908 @findex br @r{(paragraph breaks)}
9909 @cindex Paragraph breaks
9910 @cindex Breaks in a paragraph
9912 The @code{@@br} command forces a paragraph break. It inserts a blank
9913 line. You can use the command within or at the end of a line. If
9914 used within a line, the @code{@@br@{@}} command must be followed by
9915 left and right braces (as shown here) to mark the end of the
9923 This line @@br@{@}contains and is ended by paragraph breaks@@br
9924 and is followed by another line.
9935 contains and is ended by paragraph breaks
9937 and is followed by another line.
9941 The @code{@@br} command is seldom used.
9944 @node page, group, sp, Breaks
9945 @comment node-name, next, previous, up
9946 @section @code{@@page}: Start a New Page
9950 A line containing only @code{@@page} starts a new page in a printed
9951 manual. The command has no effect on Info files since they are not
9952 paginated. An @code{@@page} command is often used in the @code{@@titlepage}
9953 section of a Texinfo file to start the copyright page.@refill
9955 @node group, need, page, Breaks
9956 @comment node-name, next, previous, up
9957 @section @code{@@group}: Prevent Page Breaks
9958 @cindex Group (hold text together vertically)
9959 @cindex Holding text together vertically
9960 @cindex Vertically holding text together
9963 The @code{@@group} command (on a line by itself) is used inside an
9964 @code{@@example} or similar construct to begin an unsplittable vertical
9965 group, which will appear entirely on one page in the printed output.
9966 The group is terminated by a line containing only @code{@@end group}.
9967 These two lines produce no output of their own, and in the Info file
9968 output they have no effect at all.@refill
9970 @c Once said that these environments
9971 @c turn off vertical spacing between ``paragraphs''.
9972 @c Also, quotation used to work, but doesn't in texinfo-2.72
9973 Although @code{@@group} would make sense conceptually in a wide
9974 variety of contexts, its current implementation works reliably only
9975 within @code{@@example} and variants, and within @code{@@display},
9976 @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
9977 @xref{Quotations and Examples}. (What all these commands have in
9978 common is that each line of input produces a line of output.) In
9979 other contexts, @code{@@group} can cause anomalous vertical
9983 This formatting requirement means that you should write:
9996 with the @code{@@group} and @code{@@end group} commands inside the
9997 @code{@@example} and @code{@@end example} commands.
9999 The @code{@@group} command is most often used to hold an example
10000 together on one page. In this Texinfo manual, more than 100 examples
10001 contain text that is enclosed between @code{@@group} and @code{@@end
10004 If you forget to end a group, you may get strange and unfathomable
10005 error messages when you run @TeX{}. This is because @TeX{} keeps
10006 trying to put the rest of the Texinfo file onto the one page and does
10007 not start to generate error messages until it has processed
10008 considerable text. It is a good rule of thumb to look for a missing
10009 @code{@@end group} if you get incomprehensible error messages in
10012 @node need, , group, Breaks
10013 @comment node-name, next, previous, up
10014 @section @code{@@need @var{mils}}: Prevent Page Breaks
10015 @cindex Need space at page bottom
10018 A line containing only @code{@@need @var{n}} starts
10019 a new page in a printed manual if fewer than @var{n} mils (thousandths
10020 of an inch) remain on the current page. Do not use
10021 braces around the argument @var{n}. The @code{@@need} command has no
10022 effect on Info files since they are not paginated.@refill
10025 This paragraph is preceded by an @code{@@need} command that tells
10026 @TeX{} to start a new page if fewer than 800 mils (eight-tenths
10027 inch) remain on the page. It looks like this:@refill
10032 This paragraph is preceded by @dots{}
10036 The @code{@@need} command is useful for preventing orphans (single
10037 lines at the bottoms of printed pages).@refill
10039 @node Definition Commands, Footnotes, Breaks, Top
10040 @chapter Definition Commands
10041 @cindex Definition commands
10043 The @code{@@deffn} command and the other @dfn{definition commands}
10044 enable you to describe functions, variables, macros, commands, user
10045 options, special forms and other such artifacts in a uniform
10048 In the Info file, a definition causes the entity
10049 category---`Function', `Variable', or whatever---to appear at the
10050 beginning of the first line of the definition, followed by the
10051 entity's name and arguments. In the printed manual, the command
10052 causes @TeX{} to print the entity's name and its arguments on the left
10053 margin and print the category next to the right margin. In both
10054 output formats, the body of the definition is indented. Also, the
10055 name of the entity is entered into the appropriate index:
10056 @code{@@deffn} enters the name into the index of functions,
10057 @code{@@defvr} enters it into the index of variables, and so
10060 A manual need not and should not contain more than one definition for
10061 a given name. An appendix containing a summary should use
10062 @code{@@table} rather than the definition commands.@refill
10065 * Def Cmd Template:: How to structure a description using a
10066 definition command.
10067 * Optional Arguments:: How to handle optional and repeated arguments.
10068 * deffnx:: How to group two or more `first' lines.
10069 * Def Cmds in Detail:: All the definition commands.
10070 * Def Cmd Conventions:: Conventions for writing definitions.
10071 * Sample Function Definition::
10074 @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10075 @section The Template for a Definition
10076 @cindex Definition template
10077 @cindex Template for a definition
10079 The @code{@@deffn} command is used for definitions of entities that
10080 resemble functions. To write a definition using the @code{@@deffn}
10081 command, write the @code{@@deffn} command at the beginning of a line
10082 and follow it on the same line by the category of the entity, the name
10083 of the entity itself, and its arguments (if any). Then write the body
10084 of the definition on succeeding lines. (You may embed examples in the
10085 body.) Finally, end the definition with an @code{@@end deffn} command
10086 written on a line of its own. (The other definition commands follow
10087 the same format.)@refill
10089 The template for a definition looks like this:
10093 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10094 @var{body-of-definition}
10105 @@deffn Command forward-word count
10106 This command moves point forward @@var@{count@} words
10107 (or backward if @@var@{count@} is negative). @dots{}
10116 @deffn Command forward-word count
10117 This function moves point forward @var{count} words
10118 (or backward if @var{count} is negative). @dots{}
10122 Capitalize the category name like a title. If the name of the
10123 category contains spaces, as in the phrase `Interactive Command',
10124 write braces around it. For example:@refill
10128 @@deffn @{Interactive Command@} isearch-forward
10135 Otherwise, the second word will be mistaken for the name of the
10138 Some of the definition commands are more general than others. The
10139 @code{@@deffn} command, for example, is the general definition command
10140 for functions and the like---for entities that may take arguments. When
10141 you use this command, you specify the category to which the entity
10142 belongs. The @code{@@deffn} command possesses three predefined,
10143 specialized variations, @code{@@defun}, @code{@@defmac}, and
10144 @code{@@defspec}, that specify the category for you: ``Function'',
10145 ``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
10146 is an entity much like a function.) The @code{@@defvr} command also is
10147 accompanied by several predefined, specialized variations for describing
10148 particular kinds of variables.@refill
10150 The template for a specialized definition, such as @code{@@defun}, is
10151 similar to the template for a generalized definition, except that you
10152 do not need to specify the category:@refill
10156 @@defun @var{name} @var{arguments}@dots{}
10157 @var{body-of-definition}
10167 @@defun buffer-end flag
10168 This function returns @@code@{(point-min)@} if @@var@{flag@}
10169 is less than 1, @@code@{(point-max)@} otherwise.
10179 @defun buffer-end flag
10180 This function returns @code{(point-min)} if @var{flag} is less than 1,
10181 @code{(point-max)} otherwise. @dots{}
10186 @xref{Sample Function Definition, Sample Function Definition, A Sample
10187 Function Definition}, for a more detailed example of a function
10188 definition, including the use of @code{@@example} inside the
10191 The other specialized commands work like @code{@@defun}.@refill
10193 @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10194 @section Optional and Repeated Arguments
10195 @cindex Optional and repeated arguments
10196 @cindex Repeated and optional arguments
10197 @cindex Arguments, repeated and optional
10198 @cindex Syntax, optional & repeated arguments
10199 @cindex Meta-syntactic chars for arguments
10201 Some entities take optional or repeated arguments, which may be
10202 specified by a distinctive glyph that uses square brackets and
10203 ellipses. For @w{example}, a special form often breaks its argument list
10204 into separate arguments in more complicated ways than a
10205 straightforward function.@refill
10208 An argument enclosed within square brackets is optional.
10210 @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
10211 @var{optional-arg} is optional.
10212 An argument followed by an ellipsis is optional
10213 and may be repeated more than once.
10214 @c This is consistent with Emacs Lisp Reference manual
10215 Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
10216 Parentheses are used when several arguments are grouped
10217 into additional levels of list structure in Lisp.
10219 @c The following looks better in Info (no `r', `samp' and `code'):
10221 An argument enclosed within square brackets is optional.
10222 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10223 An argument followed by an ellipsis is optional
10224 and may be repeated more than once.
10225 @c This is consistent with Emacs Lisp Reference manual
10226 Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10227 Parentheses are used when several arguments are grouped
10228 into additional levels of list structure in Lisp.
10231 Here is the @code{@@defspec} line of an example of an imaginary
10232 special form:@refill
10235 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10243 In this example, the arguments @var{from} and @var{to} are optional,
10244 but must both be present or both absent. If they are present,
10245 @var{inc} may optionally be specified as well. These arguments are
10246 grouped with the argument @var{var} into a list, to distinguish them
10247 from @var{body}, which includes all remaining elements of the
10250 In a Texinfo source file, this @code{@@defspec} line is written like
10251 this (except it would not be split over two lines, as it is in this
10256 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10257 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10262 The function is listed in the Command and Variable Index under
10263 @samp{foobar}.@refill
10265 @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10266 @section Two or More `First' Lines
10267 @cindex Two `First' Lines for @code{@@deffn}
10268 @cindex Grouping two definitions together
10269 @cindex Definitions grouped together
10272 To create two or more `first' or header lines for a definition, follow
10273 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10274 The @code{@@deffnx} command works exactly like @code{@@deffn}
10275 except that it does not generate extra vertical white space between it
10276 and the preceding line.@refill
10283 @@deffn @{Interactive Command@} isearch-forward
10284 @@deffnx @{Interactive Command@} isearch-backward
10285 These two search commands are similar except @dots{}
10293 @deffn {Interactive Command} isearch-forward
10294 @deffnx {Interactive Command} isearch-backward
10295 These two search commands are similar except @dots{}
10298 Each of the other definition commands has an `x' form: @code{@@defunx},
10299 @code{@@defvrx}, @code{@@deftypefunx}, etc.
10301 The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10303 @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10304 @section The Definition Commands
10306 Texinfo provides more than a dozen definition commands, all of which
10307 are described in this section.@refill
10309 The definition commands automatically enter the name of the entity in
10310 the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10311 and @code{@@defmac} enter function names in the index of functions;
10312 @code{@@defvr} and @code{@@defvar} enter variable names in the index
10313 of variables.@refill
10315 Although the examples that follow mostly illustrate Lisp, the commands
10316 can be used for other programming languages.@refill
10319 * Functions Commands:: Commands for functions and similar entities.
10320 * Variables Commands:: Commands for variables and similar entities.
10321 * Typed Functions:: Commands for functions in typed languages.
10322 * Typed Variables:: Commands for variables in typed languages.
10323 * Abstract Objects:: Commands for object-oriented programming.
10324 * Data Types:: The definition command for data types.
10327 @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10328 @subsection Functions and Similar Entities
10330 This section describes the commands for describing functions and similar
10335 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10336 The @code{@@deffn} command is the general definition command for
10337 functions, interactive commands, and similar entities that may take
10338 arguments. You must choose a term to describe the category of entity
10339 being defined; for example, ``Function'' could be used if the entity is
10340 a function. The @code{@@deffn} command is written at the beginning of a
10341 line and is followed on the same line by the category of entity being
10342 described, the name of this particular entity, and its arguments, if
10343 any. Terminate the definition with @code{@@end deffn} on a line of its
10347 For example, here is a definition:
10351 @@deffn Command forward-char nchars
10352 Move point forward @@var@{nchars@} characters.
10358 This shows a rather terse definition for a ``command'' named
10359 @code{forward-char} with one argument, @var{nchars}.
10361 @code{@@deffn} prints argument names such as @var{nchars} in italics or
10362 upper case, as if @code{@@var} had been used, because we think of these
10363 names as metasyntactic variables---they stand for the actual argument
10364 values. Within the text of the description, write an argument name
10365 explicitly with @code{@@var} to refer to the value of the argument. In
10366 the example above, we used @samp{@@var@{nchars@}} in this way.
10368 The template for @code{@@deffn} is:
10372 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10373 @var{body-of-definition}
10379 @item @@defun @var{name} @var{arguments}@dots{}
10380 The @code{@@defun} command is the definition command for functions.
10381 @code{@@defun} is equivalent to @samp{@@deffn Function
10390 @@defun set symbol new-value
10391 Change the value of the symbol @@var@{symbol@}
10392 to @@var@{new-value@}.
10398 shows a rather terse definition for a function @code{set} whose
10399 arguments are @var{symbol} and @var{new-value}. The argument names on
10400 the @code{@@defun} line automatically appear in italics or upper case as
10401 if they were enclosed in @code{@@var}. Terminate the definition with
10402 @code{@@end defun} on a line of its own.@refill
10408 @@defun @var{function-name} @var{arguments}@dots{}
10409 @var{body-of-definition}
10414 @code{@@defun} creates an entry in the index of functions.
10417 @item @@defmac @var{name} @var{arguments}@dots{}
10418 The @code{@@defmac} command is the definition command for macros.
10419 @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
10420 works like @code{@@defun}.@refill
10423 @item @@defspec @var{name} @var{arguments}@dots{}
10424 The @code{@@defspec} command is the definition command for special
10425 forms. (In Lisp, a special form is an entity much like a function,
10426 @pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.)
10427 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
10428 @dots{}} and works like @code{@@defun}.@refill
10431 @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
10432 @subsection Variables and Similar Entities
10434 Here are the commands for defining variables and similar
10439 @item @@defvr @var{category} @var{name}
10440 The @code{@@defvr} command is a general definition command for
10441 something like a variable---an entity that records a value. You must
10442 choose a term to describe the category of entity being defined; for
10443 example, ``Variable'' could be used if the entity is a variable.
10444 Write the @code{@@defvr} command at the beginning of a line and
10445 followed it on the same line by the category of the entity and the
10446 name of the entity.@refill
10448 Capitalize the category name like a title. If the name of the category
10449 contains spaces, as in the name ``User Option'', enclose it in braces.
10450 Otherwise, the second word will be mistaken for the name of the entity.
10455 @@defvr @{User Option@} fill-column
10456 This buffer-local variable specifies
10457 the maximum width of filled lines.
10463 Terminate the definition with @code{@@end defvr} on a line of its
10470 @@defvr @var{category} @var{name}
10471 @var{body-of-definition}
10476 @code{@@defvr} creates an entry in the index of variables for @var{name}.
10479 @item @@defvar @var{name}
10480 The @code{@@defvar} command is the definition command for variables.
10481 @code{@@defvar} is equivalent to @samp{@@defvr Variable
10499 @@defvar @var{name}
10500 @var{body-of-definition}
10505 @code{@@defvar} creates an entry in the index of variables for
10509 @item @@defopt @var{name}
10510 @cindex User options, marking
10511 The @code{@@defopt} command is the definition command for @dfn{user
10512 options}, i.e., variables intended for users to change according to
10513 taste; Emacs has many such (@pxref{Variables,,, xemacs, XEmacs User's
10514 Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
10515 Option@} @dots{}} and works like @code{@@defvar}.@refill
10519 @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
10520 @subsection Functions in Typed Languages
10522 The @code{@@deftypefn} command and its variations are for describing
10523 functions in languages in which you must declare types of variables and
10524 functions, such as C and C++.
10528 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
10529 The @code{@@deftypefn} command is the general definition command for
10530 functions and similar entities that may take arguments and that are
10531 typed. The @code{@@deftypefn} command is written at the beginning of
10532 a line and is followed on the same line by the category of entity
10533 being described, the type of the returned value, the name of this
10534 particular entity, and its arguments, if any.@refill
10542 @@deftypefn @{Library Function@} int foobar
10543 (int @@var@{foo@}, float @@var@{bar@})
10551 (where the text before the ``@dots{}'', shown above as two lines, would
10552 actually be a single line in a real Texinfo file) produces the following
10557 -- Library Function: int foobar (int FOO, float BAR)
10563 In a printed manual, it produces:
10566 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
10572 This means that @code{foobar} is a ``library function'' that returns an
10573 @code{int}, and its arguments are @var{foo} (an @code{int}) and
10574 @var{bar} (a @code{float}).@refill
10576 The argument names that you write in @code{@@deftypefn} are not subject
10577 to an implicit @code{@@var}---since the actual names of the arguments in
10578 @code{@@deftypefn} are typically scattered among data type names and
10579 keywords, Texinfo cannot find them without help. Instead, you must write
10580 @code{@@var} explicitly around the argument names. In the example
10581 above, the argument names are @samp{foo} and @samp{bar}.@refill
10583 The template for @code{@@deftypefn} is:@refill
10587 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
10588 @var{body-of-description}
10594 Note that if the @var{category} or @var{data type} is more than one
10595 word then it must be enclosed in braces to make it a single argument.@refill
10597 If you are describing a procedure in a language that has packages,
10598 such as Ada, you might consider using @code{@@deftypefn} in a manner
10599 somewhat contrary to the convention described in the preceding
10608 @@deftypefn stacks private push
10609 (@@var@{s@}:in out stack;
10610 @@var@{n@}:in integer)
10617 (The @code{@@deftypefn} arguments are shown split into three lines, but
10618 would be a single line in a real Texinfo file.)
10620 In this instance, the procedure is classified as belonging to the
10621 package @code{stacks} rather than classified as a `procedure' and its
10622 data type is described as @code{private}. (The name of the procedure
10623 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
10625 @code{@@deftypefn} creates an entry in the index of functions for
10628 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
10630 The @code{@@deftypefun} command is the specialized definition command
10631 for functions in typed languages. The command is equivalent to
10632 @samp{@@deftypefn Function @dots{}}.@refill
10640 @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
10647 produces the following in Info:
10651 -- Function: int foobar (int FOO, float BAR)
10659 and the following in a printed manual:
10662 @deftypefun int foobar (int @var{foo}, float @var{bar})
10673 @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
10674 @var{body-of-description}
10679 @code{@@deftypefun} creates an entry in the index of functions for
10685 @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
10686 @subsection Variables in Typed Languages
10688 Variables in typed languages are handled in a manner similar to
10689 functions in typed languages. @xref{Typed Functions}. The general
10690 definition command @code{@@deftypevr} corresponds to
10691 @code{@@deftypefn} and the specialized definition command
10692 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
10696 @item @@deftypevr @var{category} @var{data-type} @var{name}
10697 The @code{@@deftypevr} command is the general definition command for
10698 something like a variable in a typed language---an entity that records
10699 a value. You must choose a term to describe the category of the
10700 entity being defined; for example, ``Variable'' could be used if the
10701 entity is a variable.@refill
10703 The @code{@@deftypevr} command is written at the beginning of a line
10704 and is followed on the same line by the category of the entity
10705 being described, the data type, and the name of this particular
10714 @@deftypevr @{Global Flag@} int enable
10721 produces the following in Info:
10725 -- Global Flag: int enable
10732 and the following in a printed manual:
10735 @deftypevr {Global Flag} int enable
10745 @@deftypevr @var{category} @var{data-type} @var{name}
10746 @var{body-of-description}
10750 @code{@@deftypevr} creates an entry in the index of variables for
10754 @item @@deftypevar @var{data-type} @var{name}
10755 The @code{@@deftypevar} command is the specialized definition command
10756 for variables in typed languages. @code{@@deftypevar} is equivalent
10757 to @samp{@@deftypevr Variable @dots{}}.@refill
10765 @@deftypevar int fubar
10772 produces the following in Info:
10776 -- Variable: int fubar
10784 and the following in a printed manual:
10787 @deftypevar int fubar
10799 @@deftypevar @var{data-type} @var{name}
10800 @var{body-of-description}
10805 @code{@@deftypevar} creates an entry in the index of variables for
10809 @node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail
10810 @subsection Object-Oriented Programming
10812 Here are the commands for formatting descriptions about abstract
10813 objects, such as are used in object-oriented programming. A class is
10814 a defined type of abstract object. An instance of a class is a
10815 particular object that has the type of the class. An instance
10816 variable is a variable that belongs to the class but for which each
10817 instance has its own value.@refill
10819 In a definition, if the name of a class is truly a name defined in the
10820 programming system for a class, then you should write an @code{@@code}
10821 around it. Otherwise, it is printed in the usual text font.@refill
10825 @item @@defcv @var{category} @var{class} @var{name}
10826 The @code{@@defcv} command is the general definition command for
10827 variables associated with classes in object-oriented programming. The
10828 @code{@@defcv} command is followed by three arguments: the category of
10829 thing being defined, the class to which it belongs, and its
10834 @@defcv @{Class Option@} Window border-pattern
10841 illustrates how you would write the first line of a definition of the
10842 @code{border-pattern} class option of the class @code{Window}.@refill
10848 @@defcv @var{category} @var{class} @var{name}
10854 @code{@@defcv} creates an entry in the index of variables.
10857 @item @@defivar @var{class} @var{name}
10858 The @code{@@defivar} command is the definition command for instance
10859 variables in object-oriented programming. @code{@@defivar} is
10860 equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
10866 @@defivar @var{class} @var{instance-variable-name}
10867 @var{body-of-definition}
10872 @code{@@defivar} creates an entry in the index of variables.
10875 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
10876 The @code{@@defop} command is the general definition command for
10877 entities that may resemble methods in object-oriented programming.
10878 These entities take arguments, as functions do, but are associated
10879 with particular classes of objects.@refill
10881 For example, some systems have constructs called @dfn{wrappers} that
10882 are associated with classes as methods are, but that act more like
10883 macros than like functions. You could use @code{@@defop Wrapper} to
10884 describe one of these.@refill
10886 Sometimes it is useful to distinguish methods and @dfn{operations}.
10887 You can think of an operation as the specification for a method.
10888 Thus, a window system might specify that all window classes have a
10889 method named @code{expose}; we would say that this window system
10890 defines an @code{expose} operation on windows in general. Typically,
10891 the operation has a name and also specifies the pattern of arguments;
10892 all methods that implement the operation must accept the same
10893 arguments, since applications that use the operation do so without
10894 knowing which method will implement it.@refill
10896 Often it makes more sense to document operations than methods. For
10897 example, window application developers need to know about the
10898 @code{expose} operation, but need not be concerned with whether a
10899 given class of windows has its own method to implement this operation.
10900 To describe this operation, you would write:@refill
10903 @@defop Operation windows expose
10906 The @code{@@defop} command is written at the beginning of a line and
10907 is followed on the same line by the overall name of the category of
10908 operation, the name of the class of the operation, the name of the
10909 operation, and its arguments, if any.@refill
10917 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
10918 @var{body-of-definition}
10923 @code{@@defop} creates an entry, such as `@code{expose} on
10924 @code{windows}', in the index of functions.@refill
10926 @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
10928 The @code{@@defmethod} command is the definition command for methods
10929 in object-oriented programming. A method is a kind of function that
10930 implements an operation for a particular class of objects and its
10931 subclasses. In the Lisp Machine, methods actually were functions, but
10932 they were usually defined with @code{defmethod}.
10934 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
10935 The command is written at the beginning of a line and is followed by
10936 the name of the class of the method, the name of the method, and its
10937 arguments, if any.@refill
10945 @@defmethod @code{bar-class} bar-method argument
10952 illustrates the definition for a method called @code{bar-method} of
10953 the class @code{bar-class}. The method takes an argument.@refill
10959 @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
10960 @var{body-of-definition}
10965 @code{@@defmethod} creates an entry, such as `@code{bar-method} on
10966 @code{bar-class}', in the index of functions.@refill
10968 @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
10970 The @code{@@deftypemethod} command is the definition command for methods
10971 in object-oriented typed languages, such as C++ and Java. It is similar
10972 to the @code{@@defmethod} command with the addition of the
10973 @var{data-type} parameter to specify the return type of the method.
10978 @node Data Types, , Abstract Objects, Def Cmds in Detail
10979 @subsection Data Types
10981 Here is the command for data types:@refill
10985 @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
10986 The @code{@@deftp} command is the generic definition command for data
10987 types. The command is written at the beginning of a line and is
10988 followed on the same line by the category, by the name of the type
10989 (which is a word like @code{int} or @code{float}), and then by names of
10990 attributes of objects of that type. Thus, you could use this command
10991 for describing @code{int} or @code{float}, in which case you could use
10992 @code{data type} as the category. (A data type is a category of
10993 certain objects for purposes of deciding which operations can be
10994 performed on them.)@refill
10996 In Lisp, for example, @dfn{pair} names a particular data
10997 type, and an object of that type has two slots called the
10998 @sc{car} and the @sc{cdr}. Here is how you would write the first line
10999 of a definition of @code{pair}.@refill
11003 @@deftp @{Data type@} pair car cdr
11014 @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11015 @var{body-of-definition}
11020 @code{@@deftp} creates an entry in the index of data types.
11023 @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11024 @section Conventions for Writing Definitions
11025 @cindex Definition conventions
11026 @cindex Conventions for writing definitions
11028 When you write a definition using @code{@@deffn}, @code{@@defun}, or
11029 one of the other definition commands, please take care to use
11030 arguments that indicate the meaning, as with the @var{count} argument
11031 to the @code{forward-word} function. Also, if the name of an argument
11032 contains the name of a type, such as @var{integer}, take care that the
11033 argument actually is of that type.@refill
11035 @node Sample Function Definition, , Def Cmd Conventions, Definition Commands
11036 @section A Sample Function Definition
11037 @cindex Function definitions
11038 @cindex Command definitions
11039 @cindex Macro definitions
11040 @cindex Sample function definition
11042 A function definition uses the @code{@@defun} and @code{@@end defun}
11043 commands. The name of the function follows immediately after the
11044 @code{@@defun} command and it is followed, on the same line, by the
11045 parameter list.@refill
11047 Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp
11051 @defun apply function &rest arguments
11052 @code{apply} calls @var{function} with @var{arguments}, just
11053 like @code{funcall} but with one difference: the last of
11054 @var{arguments} is a list of arguments to give to
11055 @var{function}, rather than a single argument. We also say
11056 that this list is @dfn{appended} to the other arguments.
11058 @code{apply} returns the result of calling @var{function}.
11059 As with @code{funcall}, @var{function} must either be a Lisp
11060 function or a primitive function; special forms and macros
11061 do not make sense in @code{apply}.
11067 @error{} Wrong type argument: listp, z
11068 (apply '+ 1 2 '(3 4))
11070 (apply '+ '(1 2 3 4))
11073 (apply 'append '((a b c) nil (x y z) nil))
11074 @result{} (a b c x y z)
11077 An interesting example of using @code{apply} is found in the description
11078 of @code{mapcar}.@refill
11083 In the Texinfo source file, this example looks like this:
11087 @@defun apply function &rest arguments
11089 @@code@{apply@} calls @@var@{function@} with
11090 @@var@{arguments@}, just like @@code@{funcall@} but with one
11091 difference: the last of @@var@{arguments@} is a list of
11092 arguments to give to @@var@{function@}, rather than a single
11093 argument. We also say that this list is @@dfn@{appended@}
11094 to the other arguments.
11098 @@code@{apply@} returns the result of calling
11099 @@var@{function@}. As with @@code@{funcall@},
11100 @@var@{function@} must either be a Lisp function or a
11101 primitive function; special forms and macros do not make
11102 sense in @@code@{apply@}.
11110 @@error@{@} Wrong type argument: listp, z
11111 (apply '+ 1 2 '(3 4))
11113 (apply '+ '(1 2 3 4))
11116 (apply 'append '((a b c) nil (x y z) nil))
11117 @@result@{@} (a b c x y z)
11122 An interesting example of using @@code@{apply@} is found
11123 in the description of @@code@{mapcar@}.@@refill
11129 In this manual, this function is listed in the Command and Variable
11130 Index under @code{apply}.@refill
11132 Ordinary variables and user options are described using a format like
11133 that for functions except that variables do not take arguments.
11136 @node Footnotes, Conditionals, Definition Commands, Top
11141 A @dfn{footnote} is for a reference that documents or elucidates the
11142 primary text.@footnote{A footnote should complement or expand upon
11143 the primary text, but a reader should not need to read a footnote to
11144 understand the primary text. For a thorough discussion of footnotes,
11145 see @cite{The Chicago Manual of Style}, which is published by the
11146 University of Chicago Press.}@refill
11149 * Footnote Commands:: How to write a footnote in Texinfo.
11150 * Footnote Styles:: Controlling how footnotes appear in Info.
11153 @node Footnote Commands, Footnote Styles, Footnotes, Footnotes
11154 @section Footnote Commands
11156 In Texinfo, footnotes are created with the @code{@@footnote} command.
11157 This command is followed immediately by a left brace, then by the text
11158 of the footnote, and then by a terminating right brace. Footnotes may
11159 be of any length (they will be broken across pages if necessary), but
11160 are usually short. The template is:
11163 ordinary text@@footnote@{@var{text of footnote}@}
11166 As shown here, the @code{@@footnote} command should come right after the
11167 text being footnoted, with no intervening space; otherwise, the
11168 formatters the footnote mark might end up starting up a line.
11170 For example, this clause is followed by a sample
11171 footnote@footnote{Here is the sample footnote.}; in the Texinfo
11172 source, it looks like this:@refill
11175 @dots{}a sample footnote@@footnote@{Here is the sample
11176 footnote.@}; in the Texinfo source@dots{}
11179 @strong{Warning:} Don't use footnotes in the argument of the
11180 @code{@@item} command for a @code{@@table} table. This doesn't work, and
11181 because of limitations of @TeX{}, there is no way to fix it. You must
11182 put the footnote into the body text of the table.
11184 In a printed manual or book, the reference mark for a footnote is a
11185 small, superscripted number; the text of the footnote appears at the
11186 bottom of the page, below a horizontal line.@refill
11188 In Info, the reference mark for a footnote is a pair of parentheses
11189 with the footnote number between them, like this: @samp{(1)}.@refill
11192 @node Footnote Styles, , Footnote Commands, Footnotes
11193 @section Footnote Styles
11195 Info has two footnote styles, which determine where the text of the
11196 footnote is located:@refill
11199 @cindex @samp{@r{End}} node footnote style
11201 In the `End' node style, all the footnotes for a single node
11202 are placed at the end of that node. The footnotes are separated from
11203 the rest of the node by a line of dashes with the word
11204 @samp{Footnotes} within it. Each footnote begins with an
11205 @samp{(@var{n})} reference mark.@refill
11209 Here is an example of a single footnote in the end of node style:@refill
11213 --------- Footnotes ---------
11215 (1) Here is a sample footnote.
11219 @cindex @samp{@r{Separate}} footnote style
11221 In the `Separate' node style, all the footnotes for a single
11222 node are placed in an automatically constructed node of
11223 their own. In this style, a ``footnote reference'' follows
11224 each @samp{(@var{n})} reference mark in the body of the
11225 node. The footnote reference is actually a cross reference
11226 which you use to reach the footnote node.@refill
11228 The name of the node containing the footnotes is constructed
11229 by appending @w{@samp{-Footnotes}} to the name of the node
11230 that contains the footnotes. (Consequently, the footnotes'
11231 node for the @file{Footnotes} node is
11232 @w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
11233 `Up' node pointer that leads back to its parent node.@refill
11236 Here is how the first footnote in this manual looks after being
11237 formatted for Info in the separate node style:@refill
11241 File: texinfo.info Node: Overview-Footnotes, Up: Overview
11243 (1) Note that the first syllable of "Texinfo" is
11244 pronounced like "speck", not "hex". @dots{}
11249 A Texinfo file may be formatted into an Info file with either footnote
11252 @findex footnotestyle
11253 Use the @code{@@footnotestyle} command to specify an Info file's
11254 footnote style. Write this command at the beginning of a line followed
11255 by an argument, either @samp{end} for the end node style or
11256 @samp{separate} for the separate node style.
11262 @@footnotestyle end
11267 @@footnotestyle separate
11270 Write an @code{@@footnotestyle} command before or shortly after the
11271 end-of-header line at the beginning of a Texinfo file. (If you
11272 include the @code{@@footnotestyle} command between the start-of-header
11273 and end-of-header lines, the region formatting commands will format
11274 footnotes as specified.)@refill
11276 If you do not specify a footnote style, the formatting commands use
11277 their default style. Currently, @code{texinfo-format-buffer} and
11278 @code{texinfo-format-region} use the `separate' style and
11279 @code{makeinfo} uses the `end' style.@refill
11281 @c !!! note: makeinfo's --footnote-style option overrides footnotestyle
11283 If you use @code{makeinfo} to create the Info file, the
11284 @samp{--footnote-style} option determines which style is used,
11285 @samp{end} for the end of node style or @samp{separate} for the
11286 separate node style. Thus, to format the Texinfo manual in the
11287 separate node style, you would use the following shell command:@refill
11290 makeinfo --footnote-style=separate texinfo.texi
11294 To format the Texinfo manual in the end of node style, you would
11298 makeinfo --footnote-style=end texinfo.texi
11302 If you use @code{texinfo-format-buffer} or
11303 @code{texinfo-format-region} to create the Info file, the value of the
11304 @code{texinfo-footnote-style} variable controls the footnote style.
11305 It can be either @samp{"separate"} for the separate node style or
11306 @samp{"end"} for the end of node style. (You can change the value of
11307 this variable with the @kbd{M-x edit-options} command (@pxref{Edit
11308 Options, , Editing Variable Values, xemacs, XEmacs User's Manual}), or
11309 with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
11310 and Setting Variables, xemacs, XEmacs User's Manual}).@refill
11312 The @code{texinfo-footnote-style} variable also controls the style if
11313 you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
11314 command in Emacs.@refill
11316 This chapter contains two footnotes.@refill
11319 @node Conditionals, Macros, Footnotes, Top
11320 @comment node-name, next, previous, up
11321 @chapter Conditionally Visible Text
11322 @cindex Conditionally visible text
11323 @cindex Text, conditionally visible
11324 @cindex Visibility of conditional text
11325 @cindex If text conditionally visible
11327 Sometimes it is good to use different text for a printed manual and
11328 its corresponding Info file. In this case, you can use the
11329 @dfn{conditional commands} to specify which text is for the printed manual
11330 and which is for the Info file.@refill
11333 * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
11334 * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
11335 * Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
11336 * set clear value:: Designating which text to format (for
11337 all output formats); and how to set a
11338 flag to a string that you can insert.
11341 @node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals
11343 @heading Conditional Commands
11347 @code{@@ifinfo} begins segments of text that should be ignored
11349 typesets the printed manual. The segment of text appears only
11351 The @code{@@ifinfo} command should appear on a line by itself; end
11352 the Info-only text with a line containing @code{@@end ifinfo} by
11353 itself. At the beginning of a Texinfo file, the Info permissions are
11354 contained within a region marked by @code{@@ifinfo} and @code{@@end
11355 ifinfo}. (@xref{Info Summary and Permissions}.)@refill
11359 The @code{@@iftex} and @code{@@end iftex} commands are similar to the
11360 @code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
11361 specify text that will appear in the printed manual but not in the Info
11362 file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
11363 specify text to appear only in HTML output.@refill
11369 This text will appear only in the printed manual.
11372 However, this text will appear only in Info.
11377 The preceding example produces the following line:
11379 This text will appear only in the printed manual.
11382 However, this text will appear only in Info.
11386 Note how you only see one of the two lines, depending on whether you
11387 are reading the Info version or the printed version of this
11390 The @code{@@titlepage} command is a special variant of @code{@@iftex} that
11391 is used for making the title and copyright pages of the printed
11392 manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill
11395 @node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals
11396 @section Conditional Not Commands
11401 You can specify text to be included in any output format @emph{other}
11402 than some given one with the @code{@@ifnot@dots{}} commands:
11404 @@ifnothtml @dots{} @@end ifnothtml
11405 @@ifnotinfo @dots{} @@end ifnotinfo
11406 @@ifnottex @dots{} @@end ifnottex
11409 (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11410 actually appear on lines by themselves.)
11412 If the output file is not being made for the given format, the region is
11413 included. Otherwise, it is ignored.
11415 The regions delimited by these commands are ordinary Texinfo source as
11416 with @code{@@iftex}, not raw formatter source as with @code{@@tex}.
11419 @node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals
11420 @section Raw Formatter Commands
11421 @cindex @TeX{} commands, using ordinary
11422 @cindex HTML commands, using ordinary
11423 @cindex Raw formatter commands
11424 @cindex Ordinary @TeX{} commands, using
11425 @cindex Ordinary HTML commands, using
11426 @cindex Commands using raw @TeX{}
11427 @cindex Commands using raw HTML
11428 @cindex plain @TeX{}
11430 Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11431 can embed some raw @TeX{} commands. Info will ignore these commands
11432 since they are only in that part of the file which is seen by @TeX{}.
11433 You can write the @TeX{} commands as you would write them in a normal
11434 @TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11435 with an @samp{@@}. For example, in the @code{@@titlepage} section of a
11436 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11437 the copyright page. (The @code{@@titlepage} command causes Info to
11438 ignore the region automatically, as it does with the @code{@@iftex}
11441 However, many features of plain @TeX{} will not work, as they are
11442 overridden by Texinfo features.
11445 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11446 commands, by delineating a region with the @code{@@tex} and @code{@@end
11447 tex} commands. (The @code{@@tex} command also causes Info to ignore the
11448 region, like the @code{@@iftex} command.) The sole exception is that
11449 @code{@@} chracter still introduces a command, so that @code{@@end tex}
11450 can be recognized properly.
11452 @cindex Mathematical expressions
11453 For example, here is a mathematical expression written in
11458 $$ \chi^2 = \sum_@{i=1@}^N
11459 \left (y_i - (a + b x_i)
11460 \over \sigma_i\right)^2 $$
11465 The output of this example will appear only in a printed manual. If
11466 you are reading this in Info, you will not see the equation that appears
11467 in the printed manual.
11469 In a printed manual, the above expression looks like
11474 $$ \chi^2 = \sum_{i=1}^N
11475 \left(y_i - (a + b x_i)
11476 \over \sigma_i\right)^2 $$
11481 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11482 a region to be included in HTML output only, and @code{@@html @dots{}
11483 @@end ifhtml} for a region of raw HTML (again, except that @code{@@} is
11484 still the escape character, so the @code{@@end} command can be
11488 @node set clear value, , Raw Formatter Commands, Conditionals
11489 @comment node-name, next, previous, up
11490 @section @code{@@set}, @code{@@clear}, and @code{@@value}
11492 You can direct the Texinfo formatting commands to format or ignore parts
11493 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11494 and @code{@@ifclear} commands.@refill
11496 In addition, you can use the @code{@@set @var{flag}} command to set the
11497 value of @var{flag} to a string of characters; and use
11498 @code{@@value@{@var{flag}@}} to insert that string. You can use
11499 @code{@@set}, for example, to set a date and use @code{@@value} to
11500 insert the date in several places in the Texinfo file.@refill
11503 * ifset ifclear:: Format a region if a flag is set.
11504 * value:: Replace a flag with a string.
11505 * value Example:: An easy way to update edition information.
11509 @node ifset ifclear, value, set clear value, set clear value
11510 @subsection @code{@@ifset} and @code{@@ifclear}
11513 When a @var{flag} is set, the Texinfo formatting commands format text
11514 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
11515 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
11516 commands do @emph{not} format the text.
11518 Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a
11519 @var{flag}; a @dfn{flag} can be any single word. The format for the
11520 command looks like this:@refill
11527 Write the conditionally formatted text between @code{@@ifset @var{flag}}
11528 and @code{@@end ifset} commands, like this:@refill
11533 @var{conditional-text}
11538 For example, you can create one document that has two variants, such as
11539 a manual for a `large' and `small' model:@refill
11542 You can use this machine to dig up shrubs
11543 without hurting them.
11548 It can also dig up fully grown trees.
11551 Remember to replant promptly @dots{}
11555 In the example, the formatting commands will format the text between
11556 @code{@@ifset large} and @code{@@end ifset} because the @code{large}
11557 flag is set.@refill
11560 Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear},
11561 a flag. Clearing a flag is the opposite of setting a flag. The
11562 command looks like this:@refill
11569 Write the command on a line of its own.
11571 When @var{flag} is cleared, the Texinfo formatting commands do
11572 @emph{not} format the text between @code{@@ifset @var{flag}} and
11573 @code{@@end ifset}; that text is ignored and does not appear in either
11574 printed or Info output.@refill
11576 For example, if you clear the flag of the preceding example by writing
11577 an @code{@@clear large} command after the @code{@@set large} command
11578 (but before the conditional text), then the Texinfo formatting commands
11579 ignore the text between the @code{@@ifset large} and @code{@@end ifset}
11580 commands. In the formatted output, that text does not appear; in both
11581 printed and Info output, you see only the lines that say, ``You can use
11582 this machine to dig up shrubs without hurting them. Remember to replant
11583 promptly @dots{}''.
11586 If a flag is cleared with an @code{@@clear @var{flag}} command, then
11587 the formatting commands format text between subsequent pairs of
11588 @code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
11589 is set with @code{@@set @var{flag}}, then the formatting commands do
11590 @emph{not} format text between an @code{@@ifclear} and an @code{@@end
11591 ifclear} command; rather, they ignore that text. An @code{@@ifclear}
11592 command looks like this:@refill
11595 @@ifclear @var{flag}
11599 In brief, the commands are:@refill
11602 @item @@set @var{flag}
11603 Tell the Texinfo formatting commands that @var{flag} is set.@refill
11605 @item @@clear @var{flag}
11606 Tell the Texinfo formatting commands that @var{flag} is cleared.@refill
11608 @item @@ifset @var{flag}
11609 If @var{flag} is set, tell the Texinfo formatting commands to format
11610 the text up to the following @code{@@end ifset} command.@refill
11612 If @var{flag} is cleared, tell the Texinfo formatting commands to
11613 ignore text up to the following @code{@@end ifset} command.@refill
11615 @item @@ifclear @var{flag}
11616 If @var{flag} is set, tell the Texinfo formatting commands to ignore
11617 the text up to the following @code{@@end ifclear} command.@refill
11619 If @var{flag} is cleared, tell the Texinfo formatting commands to
11620 format the text up to the following @code{@@end ifclear}
11624 @node value, value Example, ifset ifclear, set clear value
11625 @subsection @code{@@value}
11628 You can use the @code{@@set} command to specify a value for a flag,
11629 which is expanded by the @code{@@value} command. The value is a string
11632 Write the @code{@@set} command like this:
11635 @@set foo This is a string.
11639 This sets the value of @code{foo} to ``This is a string.''
11641 The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with
11642 the string to which @var{flag} is set.@refill
11644 Thus, when @code{foo} is set as shown above, the Texinfo formatters convert
11654 You can write an @code{@@value} command within a paragraph; but you
11655 must write an @code{@@set} command on a line of its own.
11657 If you write the @code{@@set} command like this:
11664 without specifying a string, the value of @code{foo} is an empty string.
11666 If you clear a previously set flag with an @code{@@clear @var{flag}}
11667 command, a subsequent @code{@@value@{flag@}} command is invalid and the
11668 string is replaced with an error message that says @samp{@{No value for
11671 For example, if you set @code{foo} as follows:@refill
11674 @@set how-much very, very, very
11678 then the formatters transform
11682 It is a @@value@{how-much@} wet day.
11684 It is a very, very, very wet day.
11695 then the formatters transform
11699 It is a @@value@{how-much@} wet day.
11701 It is a @{No value for "how-much"@} wet day.
11705 @node value Example, , value, set clear value
11706 @subsection @code{@@value} Example
11708 You can use the @code{@@value} command to limit the number of places you
11709 need to change when you record an update to a manual.
11710 Here is how it is done in @cite{The GNU Make Manual}:
11718 @@set EDITION 0.35 Beta
11719 @@set VERSION 3.63 Beta
11720 @@set UPDATED 14 August 1992
11721 @@set UPDATE-MONTH August 1992
11727 Write text for the first @code{@@ifinfo} section, for people reading the
11732 This is Edition @@value@{EDITION@},
11733 last updated @@value@{UPDATED@},
11734 of @@cite@{The GNU Make Manual@},
11735 for @@code@{make@}, Version @@value@{VERSION@}.
11741 Write text for the title page, for people reading the printed manual:
11742 @c List only the month and the year since that looks less fussy on a
11743 @c printed cover than a date that lists the day as well.
11748 @@subtitle A Program for Directing Recompilation
11749 @@subtitle Edition @@value@{EDITION@}, @dots{}
11750 @@subtitle @@value@{UPDATE-MONTH@}
11755 (On a printed cover, a date listing the month and the year looks less
11756 fussy than a date listing the day as well as the month and year.)
11760 Write text for the Top node, for people reading the Info file:
11764 This is Edition @@value@{EDITION@}
11765 of the @@cite@{GNU Make Manual@},
11766 last updated @@value@{UPDATED@}
11767 for @@code@{make@} Version @@value@{VERSION@}.
11772 After you format the manual, the text in the first @code{@@ifinfo}
11773 section looks like this:
11777 This is Edition 0.35 Beta, last updated 14 August 1992,
11778 of `The GNU Make Manual', for `make', Version 3.63 Beta.
11782 When you update the manual, change only the values of the flags; you do
11783 not need to rewrite the three sections.
11786 @node Macros, Format/Print Hardcopy, Conditionals, Top
11787 @chapter Macros: Defining New Texinfo Commands
11789 @cindex Defining new Texinfo commands
11790 @cindex New Texinfo commands, defining
11791 @cindex Texinfo commands, defining new
11792 @cindex User-defined Texinfo commands
11794 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
11795 sequence of text and/or existing commands (including other macros). The
11796 macro can have any number of @dfn{parameters}---text you supply each
11797 time you use the macro. (This has nothing to do with the
11798 @code{@@defmac} command, which is for documenting macros in the subject
11799 of the manual; @pxref{Def Cmd Template}.)
11802 * Defining Macros:: Both defining and undefining new commands.
11803 * Invoking Macros:: Using a macro, once you've defined it.
11807 @node Defining Macros, Invoking Macros, Macros, Macros
11808 @section Defining Macros
11809 @cindex Defining macros
11810 @cindex Macro definitions
11813 You use the Texinfo @code{@@macro} command to define a macro. For example:
11816 @@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@}
11817 @var{text} @dots{} \@var{param1}\ @dots{}
11821 The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
11822 arguments supplied when the macro is subsequently used in the document
11823 (see the next section).
11825 If a macro needs no parameters, you can define it either with an empty
11826 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
11829 @cindex Body of a macro
11830 @cindex Mutually recursive macros
11831 @cindex Recursion, mutual
11832 The definition or @dfn{body} of the macro can contain any Texinfo
11833 commands, including previously-defined macros. (It is not possible to
11834 have mutually recursive Texinfo macros.) In the body, instances of a
11835 parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in
11836 the example above, are replaced by the corresponding argument from the
11840 @cindex Macros, undefining
11841 @cindex Undefining macros
11842 You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
11843 It is not an error to undefine a macro that is already undefined.
11851 @node Invoking Macros, , Defining Macros, Macros
11852 @section Invoking Macros
11853 @cindex Invoking macros
11854 @cindex Macro invocation
11856 After a macro is defined (see the previous section), you can use
11857 (@dfn{invoke}) it in your document like this:
11860 @@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@}
11864 and the result will be just as if you typed the body of
11865 @var{macro-name} at that spot. For example:
11868 @@macro foo @{p, q@}
11869 Together: \p\ & \q\.
11881 @cindex Backslash, and macros
11882 Thus, the arguments and parameters are separated by commas and delimited
11883 by braces; any whitespace after (but not before) a comma is ignored. To
11884 insert a comma, brace, or backslash in an argument, prepend a backslash,
11888 @@@var{macro-name} @{\\\@{\@}\,@}
11892 which will pass the (almost certainly error-producing) argument
11893 @samp{\@{@},} to @var{macro-name}.
11895 If the macro is defined to take a single argument, and is invoked
11896 without any braces, the entire rest of the line after the macro name is
11897 supplied as the argument. For example:
11914 @node Format/Print Hardcopy, Create an Info File, Macros, Top
11915 @comment node-name, next, previous, up
11916 @chapter Format and Print Hardcopy
11917 @cindex Format and print hardcopy
11918 @cindex Hardcopy, printing it
11919 @cindex Making a printed manual
11920 @cindex Sorting indices
11921 @cindex Indices, sorting
11922 @cindex @TeX{} index sorting
11925 There are three major shell commands for making a printed manual from a
11926 Texinfo file: one for converting the Texinfo file into a file that will be
11927 printed, a second for sorting indices, and a third for printing the
11928 formatted document. When you use the shell commands, you can either
11929 work directly in the operating system shell or work within a shell
11930 inside GNU Emacs.@refill
11932 If you are using GNU Emacs, you can use commands provided by Texinfo
11933 mode instead of shell commands. In addition to the three commands to
11934 format a file, sort the indices, and print the result, Texinfo mode
11935 offers key bindings for commands to recenter the output buffer, show the
11936 print queue, and delete a job from the print queue.@refill
11939 * Use TeX:: Use @TeX{} to format for hardcopy.
11940 * Format with tex/texindex:: How to format in a shell.
11941 * Format with texi2dvi:: A simpler way to use the shell.
11942 * Print with lpr:: How to print.
11943 * Within Emacs:: How to format and print from an Emacs shell.
11944 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
11945 * Compile-Command:: How to print using Emacs's compile command.
11946 * Requirements Summary:: @TeX{} formatting requirements summary.
11947 * Preparing for TeX:: What you need to do to use @TeX{}.
11948 * Overfull hboxes:: What are and what to do with overfull hboxes.
11949 * smallbook:: How to print small format books and manuals.
11950 * A4 Paper:: How to print on European A4 paper.
11951 * Cropmarks and Magnification:: How to print marks to indicate the size
11952 of pages and how to print scaled up output.
11955 @node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy
11957 @heading Use @TeX{}
11960 The typesetting program called @TeX{} is used for formatting a Texinfo
11961 file. @TeX{} is a very powerful typesetting program and, if used right,
11962 does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
11963 @TeX{}}, for information on how to obtain @TeX{}.)
11965 The @code{makeinfo}, @code{texinfo-format-region}, and
11966 @code{texinfo-format-buffer} commands read the very same @@-commands
11967 in the Texinfo file as does @TeX{}, but process them differently to
11968 make an Info file; see @ref{Create an Info File}.@refill
11970 @node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy
11971 @comment node-name, next, previous, up
11972 @section Format using @code{tex} and @code{texindex}
11973 @cindex Shell formatting with @code{tex} and @code{texindex}
11974 @cindex Formatting with @code{tex} and @code{texindex}
11977 Format the Texinfo file with the shell command @code{tex} followed by
11978 the name of the Texinfo file. For example:
11985 @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
11986 files containing information for indices, cross references, etc. The
11987 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
11988 any printe (see the following sections).
11991 The @code{tex} formatting command itself does not sort the indices; it
11992 writes an output file of unsorted index data. (The @code{texi2dvi}
11993 command automatically generates indices; see @ref{Format with texi2dvi,,
11994 Format using @code{texi2dvi}}.) To generate a printed index after
11995 running the @code{tex} command, you first need a sorted index to work
11996 from. The @code{texindex} command sorts indices. (The source file
11997 @file{texindex.c} comes as part of the standard Texinfo distribution,
11998 among other places.)@refill
12000 @cindex Names of index files
12001 The @code{tex} formatting command outputs unsorted index files under
12002 names that obey a standard convention: the name of your main input file
12003 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
12004 Web2c}) extension removed, followed by the two letter names of indices.
12005 For example, the raw index output files for the input file
12006 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
12007 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
12008 arguments to give to @code{texindex}.@refill
12013 Instead of specifying all the unsorted index file names explicitly, you
12014 can use @samp{??} as shell wildcards and give the command in this
12022 This command will run @code{texindex} on all the unsorted index files,
12023 including any that you have defined yourself using @code{@@defindex}
12024 or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
12025 even if there are similarly named files with two letter extensions
12026 that are not index files, such as @samp{foo.el}. The @code{texindex}
12027 command reports but otherwise ignores such files.)@refill
12029 For each file specified, @code{texindex} generates a sorted index file
12030 whose name is made by appending @samp{s} to the input file name. The
12031 @code{@@printindex} command knows to look for a file of that name
12032 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
12033 raw index output file.@refill
12035 After you have sorted the indices, you need to rerun the @code{tex}
12036 formatting command on the Texinfo file. This regenerates the DVI file,
12037 this time with up-to-date index entries.
12039 Finally, you may need to run @code{tex} one more time, to get the page
12040 numbers in the cross-references correct.
12042 To summarize, this is a four step process:
12046 Run @code{tex} on your Texinfo file. This generates a DVI file (with
12047 undefined cross-references and no indices), and the raw index files
12048 (with two letter extensions).
12051 Run @code{texindex} on the raw index files. This creates the
12052 corresponding sorted index files (with three letter extensions).
12055 Run @code{tex} again on your Texinfo file. This regenerates the DVI
12056 file, this time with indices and defined cross-references, but with page
12057 numbers for the cross-references from last time, generally incorrect.
12060 Run @code{tex} one last time. This time the correct page numbers are
12061 written for the cross-references.
12065 Alternatively, it's a one-step process: run @code{texi2dvi}.
12067 You need not run @code{texindex} each time after you run @code{tex}. If
12068 you do not, on the next run, the @code{tex} formatting command will use
12069 whatever sorted index files happen to exist from the previous use of
12070 @code{texindex}. This is usually ok while you are
12074 @node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy
12075 @comment node-name, next, previous, up
12076 @section Format using @code{texi2dvi}
12077 @pindex texi2dvi @r{(shell script)}
12079 The @code{texi2dvi} command automatically runs both @code{tex} and
12080 @code{texindex} as many times as necessary to produce a DVI file with
12081 up-to-date, sorted indices. It simplifies the
12082 @code{tex}---@code{texindex}---@code{tex} sequence described in the
12085 The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is your
12086 shell prompt):@refill
12089 prompt$ @kbd{texi2dvi @var{filename}@dots{}}
12092 For a list of options, run @samp{texi2dvi --help}.
12095 @node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy
12096 @comment node-name, next, previous, up
12097 @section Shell Print Using @code{lpr -d}
12098 @pindex lpr @r{(DVI print command)}
12100 The precise command to print a DVI file depends on your system
12101 installation, but @samp{lpr -d} is common. The command may require the
12102 DVI file name without any extension or with a @samp{.dvi}
12103 extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.)
12105 The following commands, for example, will (probably) suffice to sort the
12106 indices, format, and print the @cite{Bison Manual}:
12118 (Remember that the shell commands may be different at your site; but
12119 these are commonly used versions.)@refill
12122 Using the @code{texi2dvi} shell script, you simply need type:@refill
12126 texi2dvi bison.texinfo
12131 @node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy
12132 @comment node-name, next, previous, up
12133 @section From an Emacs Shell
12134 @cindex Print, format from Emacs shell
12135 @cindex Format, print from Emacs shell
12136 @cindex Shell, format, print from
12137 @cindex Emacs shell, format, print from
12138 @cindex GNU Emacs shell, format, print from
12140 You can give formatting and printing commands from a shell within GNU
12141 Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
12142 shell, you can format and print the document. @xref{Format/Print
12143 Hardcopy, , Format and Print Hardcopy}, for details.@refill
12145 You can switch to and from the shell buffer while @code{tex} is
12146 running and do other editing. If you are formatting a long document
12147 on a slow machine, this can be very convenient.@refill
12149 You can also use @code{texi2dvi} from an Emacs shell. For example,
12150 here is how to use @code{texi2dvi} to format and print @cite{Using and
12151 Porting GNU CC} from a shell within Emacs:
12155 texi2dvi gcc.texinfo
12161 @xref{Texinfo Mode Printing}, for more information about formatting
12162 and printing in Texinfo mode.@refill
12165 @node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy
12166 @section Formatting and Printing in Texinfo Mode
12167 @cindex Region printing in Texinfo mode
12168 @cindex Format and print in Texinfo mode
12169 @cindex Print and format in Texinfo mode
12171 Texinfo mode provides several predefined key commands for @TeX{}
12172 formatting and printing. These include commands for sorting indices,
12173 looking at the printer queue, killing the formatting job, and
12174 recentering the display of the buffer in which the operations
12179 @itemx M-x texinfo-tex-buffer
12180 Run @code{texi2dvi} on the current buffer.@refill
12183 @itemx M-x texinfo-tex-region
12184 Run @TeX{} on the current region.@refill
12187 @itemx M-x texinfo-texindex
12188 Sort the indices of a Texinfo file formatted with
12189 @code{texinfo-tex-region}.@refill
12192 @itemx M-x texinfo-tex-print
12193 Print a DVI file that was made with @code{texinfo-tex-region} or
12194 @code{texinfo-tex-buffer}.@refill
12197 @itemx M-x tex-show-print-queue
12198 Show the print queue.@refill
12201 @itemx M-x texinfo-delete-from-print-queue
12202 Delete a job from the print queue; you will be prompted for the job
12203 number shown by a preceding @kbd{C-c C-t C-q} command
12204 (@code{texinfo-show-tex-print-queue}).@refill
12207 @itemx M-x tex-kill-job
12208 Kill the currently running @TeX{} job started by
12209 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
12210 process running in the Texinfo shell buffer.@refill
12213 @itemx M-x texinfo-quit-job
12214 Quit a @TeX{} formatting job that has stopped because of an error by
12215 sending an @key{x} to it. When you do this, @TeX{} preserves a record
12216 of what it did in a @file{.log} file.@refill
12219 @itemx M-x tex-recenter-output-buffer
12220 Redisplay the shell buffer in which the @TeX{} printing and formatting
12221 commands are run to show its most recent output.@refill
12225 Thus, the usual sequence of commands for formatting a buffer is as
12226 follows (with comments to the right):@refill
12230 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
12231 C-c C-t C-p @r{Print the DVI file.}
12232 C-c C-t C-q @r{Display the printer queue.}
12236 The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
12237 called the @file{*tex-shell*}. The @code{texinfo-tex-command},
12238 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
12239 commands are all run in this shell.
12241 You can watch the commands operate in the @samp{*tex-shell*} buffer,
12242 and you can switch to and from and use the @samp{*tex-shell*} buffer
12243 as you would any other shell buffer.@refill
12246 The formatting and print commands depend on the values of several variables.
12247 The default values are:@refill
12251 @r{Variable} @r{Default value}
12253 texinfo-texi2dvi-command "texi2dvi"
12254 texinfo-tex-command "tex"
12255 texinfo-texindex-command "texindex"
12256 texinfo-delete-from-print-queue-command "lprm"
12257 texinfo-tex-trailer "@@bye"
12258 tex-start-of-header "%**start"
12259 tex-end-of-header "%**end"
12260 tex-dvi-print-command "lpr -d"
12261 tex-show-queue-command "lpq"
12265 You can change the values of these variables with the @kbd{M-x
12266 edit-options} command (@pxref{Edit Options, , Editing Variable Values,
12267 xemacs, XEmacs User's Manual}), with the @kbd{M-x set-variable} command
12268 (@pxref{Examining, , Examining and Setting Variables, xemacs, XEmacs
12269 User's Manual}), or with your @file{.emacs} initialization file
12270 (@pxref{Init File, , , xemacs, XEmacs User's Manual}).@refill
12272 @node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy
12273 @comment node-name, next, previous, up
12274 @section Using the Local Variables List
12275 @cindex Local variables
12276 @cindex Compile command for formatting
12277 @cindex Format with the compile command
12279 Yet another way to apply the @TeX{} formatting command to a Texinfo file
12280 is to put that command in a @dfn{local variables list} at the end of the
12281 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
12282 commands as a @code{compile-command} and have Emacs run it by typing
12283 @kbd{M-x compile}. This creates a special shell called the
12284 @file{*compilation*} buffer in which Emacs runs the compile command.
12285 For example, at the end of the @file{gdb.texinfo} file, after the
12286 @code{@@bye}, you could put the following:@refill
12291 compile-command: "texi2dvi gdb.texinfo"
12297 This technique is most often used by programmers who also compile programs
12298 this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill
12301 @node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy
12302 @comment node-name, next, previous, up
12303 @section @TeX{} Formatting Requirements Summary
12304 @cindex Requirements for formatting
12305 @cindex Minimal requirements for formatting
12306 @cindex Formatting requirements
12308 Every Texinfo file that is to be input to @TeX{} must begin with a
12309 @code{\input} command and must contain an @code{@@setfilename} command:
12313 @@setfilename @var{arg-not-used-by-@@TeX@{@}}
12317 The first command instructs @TeX{} to load the macros it needs to
12318 process a Texinfo file and the second command opens auxiliary files.
12320 Every Texinfo file must end with a line that terminates @TeX{}'s
12321 processing and forces out unfinished pages:
12327 Strictly speaking, these lines are all a Texinfo file needs to be
12328 processed successfully by @TeX{}.
12330 Usually, however, the beginning includes an @code{@@settitle} command to
12331 define the title of the printed manual, an @code{@@setchapternewpage}
12332 command, a title page, a copyright page, and permissions. Besides an
12333 @code{@@bye}, the end of a file usually includes indices and a table of
12334 contents. (And of course most manuals contain a body of text as well.)
12337 For more information, see
12338 @ref{settitle, , @code{@@settitle}},
12339 @ref{setchapternewpage, , @code{@@setchapternewpage}},
12340 @ref{Headings, ,Page Headings},
12341 @ref{Titlepage & Copyright Page},
12342 @ref{Printing Indices & Menus}, and
12347 For more information, see@*
12348 @ref{settitle, , @code{@@settitle}},@*
12349 @ref{setchapternewpage, , @code{@@setchapternewpage}},@*
12350 @ref{Headings, ,Page Headings},@*
12351 @ref{Titlepage & Copyright Page},@*
12352 @ref{Printing Indices & Menus}, and@*
12357 @node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy
12358 @comment node-name, next, previous, up
12359 @section Preparing to Use @TeX{}
12360 @cindex Preparing to use @TeX{}
12361 @cindex @TeX{} input initialization
12362 @cindex @code{TEXINPUTS} environment variable
12364 @cindex @b{.profile} initialization file
12365 @cindex @b{.cshrc} initialization file
12366 @cindex Initialization file for @TeX{} input
12368 @TeX{} needs to know where to find the @file{texinfo.tex} file that you
12369 have told it to input with the @samp{\input texinfo} command at the
12370 beginning of the first line. The @file{texinfo.tex} file tells @TeX{}
12371 how to handle @@-commands; it is included in all standard GNU
12374 @pindex texinfo.tex@r{, installing}
12375 Usually, the @file{texinfo.tex} file is put under the default directory
12376 that contains @TeX{} macros
12377 (@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when
12378 GNU Emacs or other GNU software is installed. In this case, @TeX{} will
12379 find the file and you do not need to do anything special.
12380 Alternatively, you can put @file{texinfo.tex} in the current directory
12381 when you run @TeX{}, and @TeX{} will find it there.
12383 @pindex epsf.tex@r{, installing}
12384 Also, you should install @file{epsf.tex} in the same place as
12385 @file{texinfo.tex}, if it is not already installed from another
12386 distribution. This file is needed to support the @code{@@image} command
12389 @pindex texinfo.cnf @r{installation}
12390 @cindex Customizing of @TeX{} for Texinfo
12391 @cindex Site-wide Texinfo configuration file
12392 Optionally, you may create an additional @file{texinfo.cnf}, and install
12393 it as well. This file is read by @TeX{} at the @code{@@setfilename}
12394 command (@pxref{setfilename,, @code{@@setfilename}}). You can put any
12395 commands you like there according to local site-wide conventions, and
12396 they will be read by @TeX{} when processing any Texinfo document. For
12397 example, if @file{texinfo.cnf} contains the a single line
12398 @samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will
12399 be processed with that page size in effect. If you have nothing to put
12400 in @file{texinfo.cnf}, you do not need to create it.
12403 If neither of the above locations for these system files suffice for
12404 you, you can specify the directories explicitly. For
12405 @file{texinfo.tex}, you can do this by writing the complete path for the
12406 file after the @code{\input} command. Another way, that works for both
12407 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
12408 might read), is to set the @code{TEXINPUTS} environment variable in your
12409 @file{.cshrc} or @file{.profile} file.
12411 Which you use of @file{.cshrc} or @file{.profile} depends on
12412 whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
12413 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
12414 command interpreter. The latter read the @file{.cshrc} file for
12415 initialization information, and the former read @file{.profile}.
12417 In a @file{.cshrc} file, you could use the following @code{csh} command
12421 setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
12425 In a @file{.profile} file, you could use the following @code{sh} command
12430 TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
12436 This would cause @TeX{} to look for @file{\input} file first in the current
12437 directory, indicated by the @samp{.}, then in a hypothetical user's
12438 @file{me/mylib} directory, and finally in a system directory.
12441 @node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy
12442 @comment node-name, next, previous, up
12443 @section Overfull ``hboxes''
12444 @cindex Overfull @samp{hboxes}
12445 @cindex @samp{hboxes}, overfull
12446 @cindex Final output
12448 @TeX{} is sometimes unable to typeset a line without extending it into
12449 the right margin. This can occur when @TeX{} comes upon what it
12450 interprets as a long word that it cannot hyphenate, such as an
12451 electronic mail network address or a very long title. When this
12452 happens, @TeX{} prints an error message like this:@refill
12455 Overfull \hbox (20.76302pt too wide)
12459 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
12460 The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill
12462 @TeX{} also provides the line number in the Texinfo source file and
12463 the text of the offending line, which is marked at all the places that
12464 @TeX{} knows how to hyphenate words.
12465 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
12466 for more information about typesetting errors.@refill
12468 If the Texinfo file has an overfull hbox, you can rewrite the sentence
12469 so the overfull hbox does not occur, or you can decide to leave it. A
12470 small excursion into the right margin often does not matter and may not
12471 even be noticeable.@refill
12473 @cindex Black rectangle in hardcopy
12474 @cindex Rectangle, ugly, black in hardcopy
12475 However, unless told otherwise, @TeX{} will print a large, ugly, black
12476 rectangle beside the line that contains the overfull hbox. This is so
12477 you will notice the location of the problem if you are correcting a
12482 To prevent such a monstrosity from marring your final printout, write
12483 the following in the beginning of the Texinfo file on a line of its own,
12484 before the @code{@@titlepage} command:@refill
12490 @node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy
12491 @comment node-name, next, previous, up
12492 @section Printing ``Small'' Books
12494 @cindex Small book size
12495 @cindex Book, printing small
12496 @cindex Page sizes for books
12497 @cindex Size of printed book
12499 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
12500 format. However, you can direct @TeX{} to typeset a document in a 7 by
12501 9.25 inch format that is suitable for bound books by inserting the
12502 following command on a line by itself at the beginning of the Texinfo
12503 file, before the title page:@refill
12510 (Since regular sized books are often about 7 by 9.25 inches, this
12511 command might better have been called the @code{@@regularbooksize}
12512 command, but it came to be called the @code{@@smallbook} command by
12513 comparison to the 8.5 by 11 inch format.)@refill
12515 If you write the @code{@@smallbook} command between the
12516 start-of-header and end-of-header lines, the Texinfo mode @TeX{}
12517 region formatting command, @code{texinfo-tex-region}, will format the
12518 region in ``small'' book size (@pxref{Start of Header}).@refill
12520 The Free Software Foundation distributes printed copies of @cite{The GNU
12521 Emacs Manual} and other manuals in the ``small'' book size.
12522 @xref{smallexample & smalllisp, , @code{@@smallexample} and
12523 @code{@@smalllisp}}, for information about commands that make it easier
12524 to produce examples for a smaller manual.@refill
12526 Alternatively, to avoid embedding this physical paper size in your
12527 document, use @code{texi2dvi} to format your document (@pxref{Format
12528 with texi2dvi}), and supply @samp{-t @@smallbook} as an argument. Then
12529 other people do not have to change the document source file to format it
12533 @node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy
12534 @comment node-name, next, previous, up
12535 @section Printing on A4 Paper
12536 @cindex A4 paper, printing on
12537 @cindex Paper size, European A4
12538 @cindex European A4 paper
12541 You can tell @TeX{} to typeset a document for printing on European size
12542 A4 paper with the @code{@@afourpaper} command. Write the command on a
12543 line by itself between @code{@@iftex} and @code{@@end iftex} lines near
12544 the beginning of the Texinfo file, before the title page:@refill
12546 For example, this is how you would write the header for this manual:@refill
12550 \input texinfo @@c -*-texinfo-*-
12551 @@c %**start of header
12552 @@setfilename texinfo
12554 @@syncodeindex vr fn
12558 @@c %**end of header
12562 Alternatively, to avoid embedding this physical paper size in your
12563 document, use @code{texi2dvi} to format your document (@pxref{Format
12564 with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument. Then
12565 other people do not have to change the document source file to format it
12568 @pindex texinfo.cnf
12569 Another alternative: put the @code{@@afourpaper} command in the file
12570 @file{texinfo.cnf} that @TeX{} will read. (No need for @code{@@iftex}
12571 there.) This will automatically typeset all the Texinfo documents at
12572 your site with that paper size in effect.
12575 @node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy
12576 @comment node-name, next, previous, up
12577 @section Cropmarks and Magnification
12580 @cindex Cropmarks for printing
12581 @cindex Printing cropmarks
12582 You can attempt to direct @TeX{} to print cropmarks at the corners of
12583 pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
12584 command on a line by itself between @code{@@iftex} and @code{@@end
12585 iftex} lines near the beginning of the Texinfo file, before the title
12586 page, like this:@refill
12596 This command is mainly for printers that typeset several pages on one
12597 sheet of film; but you can attempt to use it to mark the corners of a
12598 book set to 7 by 9.25 inches with the @code{@@smallbook} command.
12599 (Printers will not produce cropmarks for regular sized output that is
12600 printed on regular sized paper.) Since different printing machines work
12601 in different ways, you should explore the use of this command with a
12602 spirit of adventure. You may have to redefine the command in the
12603 @file{texinfo.tex} definitions file.@refill
12605 @findex mag @r{(@TeX{} command)}
12606 @cindex Magnified printing
12607 @cindex Larger or smaller pages
12608 You can attempt to direct @TeX{} to typeset pages larger or smaller than
12609 usual with the @code{\mag} @TeX{} command. Everything that is typeset
12610 is scaled proportionally larger or smaller. (@code{\mag} stands for
12611 ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
12612 plain @TeX{} command that is prefixed with a backslash. You have to
12613 write this command between @code{@@tex} and @code{@@end tex}
12614 (@pxref{Raw Formatter Commands}).
12616 Follow the @code{\mag} command with an @samp{=} and then a number that
12617 is 1000 times the magnification you desire. For example, to print pages
12618 at 1.2 normal size, write the following near the beginning of the
12619 Texinfo file, before the title page:@refill
12629 With some printing technologies, you can print normal-sized copies that
12630 look better than usual by using a larger-than-normal master.@refill
12632 Depending on your system, @code{\mag} may not work or may work only at
12633 certain magnifications. Be prepared to experiment.@refill
12635 @node Create an Info File, Install an Info File, Format/Print Hardcopy, Top
12636 @comment node-name, next, previous, up
12637 @chapter Creating an Info File
12638 @cindex Creating an Info file
12639 @cindex Info, creating an on-line file
12640 @cindex Formatting a file for Info
12642 @code{makeinfo} is a utility that converts a Texinfo file into an Info
12643 file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
12644 GNU Emacs functions that do the same.@refill
12646 A Texinfo file must contain an @code{@@setfilename} line near its
12647 beginning, otherwise the Info formatting commands will fail.
12649 For information on installing the Info file in the Info system, see
12650 @ref{Install an Info File}.@refill
12653 * makeinfo advantages:: @code{makeinfo} provides better error checking.
12654 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
12655 * makeinfo options:: Specify fill-column and other options.
12656 * Pointer Validation:: How to check that pointers point somewhere.
12657 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
12658 * texinfo-format commands:: Two Info formatting commands written
12659 in Emacs Lisp are an alternative
12660 to @code{makeinfo}.
12661 * Batch Formatting:: How to format for Info in Emacs Batch mode.
12662 * Tag and Split Files:: How tagged and split files help Info
12666 @node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File
12668 @heading @code{makeinfo} Preferred
12671 The @code{makeinfo} utility creates an Info file from a Texinfo source
12672 file more quickly than either of the Emacs formatting commands and
12673 provides better error messages. We recommend it. @code{makeinfo} is a
12674 C program that is independent of Emacs. You do not need to run Emacs to
12675 use @code{makeinfo}, which means you can use @code{makeinfo} on machines
12676 that are too small to run Emacs. You can run @code{makeinfo} in
12677 any one of three ways: from an operating system shell, from a shell
12678 inside Emacs, or by typing a key command in Texinfo mode in Emacs.
12681 The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
12682 commands are useful if you cannot run @code{makeinfo}. Also, in some
12683 circumstances, they format short regions or buffers more quickly than
12684 @code{makeinfo}.@refill
12686 @node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File
12687 @section Running @code{makeinfo} from a Shell
12689 To create an Info file from a Texinfo file, type @code{makeinfo}
12690 followed by the name of the Texinfo file. Thus, to create the Info
12691 file for Bison, type the following to the shell:
12692 is the prompt):@refill
12695 makeinfo bison.texinfo
12698 (You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
12701 Sometimes you will want to specify options. For example, if you wish
12702 to discover which version of @code{makeinfo} you are using,
12709 @xref{makeinfo options}, for more information.
12713 @node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File
12714 @comment node-name, next, previous, up
12715 @section Options for @code{makeinfo}
12716 @cindex @code{makeinfo} options
12717 @cindex Options for @code{makeinfo}
12719 The @code{makeinfo} command takes a number of options. Most often,
12720 options are used to set the value of the fill column and specify the
12721 footnote style. Each command line option is a word preceded by
12722 @samp{--} or a letter preceded by @samp{-}. You can use abbreviations
12723 for the long option names as long as they are unique.@refill
12725 For example, you could use the following shell command to create an Info
12726 file for @file{bison.texinfo} in which each line is filled to only 68
12730 makeinfo --fill-column=68 bison.texinfo
12733 You can write two or more options in sequence, like this:@refill
12736 makeinfo --no-split --fill-column=70 @dots{}
12740 This would keep the Info file together as one possibly very long
12741 file and would also set the fill column to 70.@refill
12748 @opindex -D @var{var}
12749 Cause the variable @var{var} to be defined. This is equivalent to
12750 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
12752 @item --error-limit=@var{limit}
12753 @opindex --error-limit=@var{limit}
12754 Set the maximum number of errors that @code{makeinfo} will report
12755 before exiting (on the assumption that continuing would be useless);
12759 @item --fill-column=@var{width}
12760 @opindex --fill-column=@var{width}
12761 Specify the maximum number of columns in a line; this is the right-hand
12762 edge of a line. Paragraphs that are filled will be filled to this
12763 width. (Filling is the process of breaking up and connecting lines so
12764 that lines are the same length as or shorter than the number specified
12765 as the fill column. Lines are broken between words.) The default value
12768 @item --footnote-style=@var{style}
12769 @opindex --footnote-style=@var{style}
12770 Set the footnote style to @var{style}, either @samp{end} for the end
12771 node style (the default) or @samp{separate} for the separate node style.
12772 The value set by this option overrides the value set in a Texinfo file
12773 by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
12774 footnote style is @samp{separate}, @code{makeinfo} makes a new node
12775 containing the footnotes found in the current node. When the footnote
12776 style is @samp{end}, @code{makeinfo} places the footnote references at
12777 the end of the current node.
12781 Ordinarily, if the input file has errors, the output files are not
12782 created. With this option, they are preserved.
12786 Print a usage message listing all available options, then exit successfully.
12789 @opindex -I @var{dir}
12790 Add @code{dir} to the directory search list for finding files that are
12791 included using the @code{@@include} command. By default,
12792 @code{makeinfo} searches only the current directory.
12795 @opindex --no-headers
12796 Do not include menus or node lines in the output. This results in an
12797 @sc{ascii} file that you cannot read in Info since it does not contain
12798 the requisite nodes or menus. It is primarily useful to extract certain
12799 pieces of a manual into separate files to be included in a distribution,
12800 such as @file{INSTALL} files.
12803 @opindex --no-split
12804 Suppress the splitting stage of @code{makeinfo}. By default, large
12805 output files (where the size is greater than 70k bytes) are split into
12806 smaller subfiles, each one approximately 50k bytes.
12808 @item --no-pointer-validate
12809 @itemx --no-validate
12810 @opindex --no-pointer-validate
12811 @opindex --no-validate
12812 Suppress the pointer-validation phase of @code{makeinfo}. Normally,
12813 after a Texinfo file is processed, some consistency checks are made to
12814 ensure that cross references can be resolved, etc.
12815 @xref{Pointer Validation}.@refill
12819 Suppress warning messages (but @emph{not} error messages). You might
12820 want this if the file you are creating has examples of Texinfo cross
12821 references within it, and the nodes that are referenced do not actually
12824 @item --no-number-footnotes
12825 @opindex --no-number-footnotes
12826 Suppress automatic footnote numbering. By default, @code{makeinfo}
12827 numbers each footnote sequentially in a single node, resetting the
12828 current footnote number to 1 at the start of each node.
12830 @item --output=@var{file}
12831 @itemx -o @var{file}
12832 @opindex --output=@var{file}
12833 @opindex -o @var{file}
12834 Specify that the output should be directed to @var{file} and not to the
12835 file name specified in the @code{@@setfilename} command found in the
12836 Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
12837 goes to standard output and @samp{--no-split} is implied.
12840 @opindex -P @var{dir}
12841 Prepend @code{dir} to the directory search list for @code{@@include}.
12842 See @samp{-I} for more details.
12844 @item --paragraph-indent=@var{indent}
12845 @opindex --paragraph-indent=@var{indent}
12846 Set the paragraph indentation style to @var{indent}. The value set by
12847 this option overrides the value set in a Texinfo file by an
12848 @code{@@paragraphindent} command (@pxref{paragraphindent}). The value
12849 of @var{indent} is interpreted as follows:
12853 Preserve any existing indentation at the starts of paragraphs.
12855 @item @samp{0} or @samp{none}
12856 Delete any existing indentation.
12859 Indent each paragraph by that number of spaces.
12862 @item --reference-limit=@var{limit}
12863 @opindex --reference-limit=@var{limit}
12864 Set the value of the number of references to a node that
12865 @code{makeinfo} will make without reporting a warning. If a node has more
12866 than this number of references in it, @code{makeinfo} will make the
12867 references but also report a warning. The default is 1000.
12870 Cause @var{var} to be undefined. This is equivalent to
12871 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
12875 Cause @code{makeinfo} to display messages saying what it is doing.
12876 Normally, @code{makeinfo} only outputs messages if there are errors or
12881 Print the version number, then exit successfully.
12886 @node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File
12887 @section Pointer Validation
12888 @cindex Pointer validation with @code{makeinfo}
12889 @cindex Validation of pointers
12891 If you do not suppress pointer-validation, @code{makeinfo} will check
12892 the validity of the final Info file. Mostly, this means ensuring that
12893 nodes you have referenced really exist. Here is a complete list of what
12898 If a `Next', `Previous', or `Up' node reference is a reference to a
12899 node in the current file and is not an external reference such as to
12900 @file{(dir)}, then the referenced node must exist.@refill
12903 In every node, if the `Previous' node is different from the `Up' node,
12904 then the `Previous' node must also be pointed to by a `Next' node.@refill
12907 Every node except the `Top' node must have an `Up' pointer.@refill
12910 The node referenced by an `Up' pointer must contain a reference to the
12911 current node in some manner other than through a `Next' reference.
12912 This includes menu entries and cross references.@refill
12915 If the `Next' reference of a node is not the same as the `Next' reference
12916 of the `Up' reference, then the node referenced by the `Next' pointer
12917 must have a `Previous' pointer that points back to the current node.
12918 This rule allows the last node in a section to point to the first node
12919 of the next chapter.@refill
12922 @node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File
12923 @section Running @code{makeinfo} inside Emacs
12924 @cindex Running @code{makeinfo} in Emacs
12925 @cindex @code{makeinfo} inside Emacs
12926 @cindex Shell, running @code{makeinfo} in
12928 You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
12929 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
12930 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
12931 C-m C-b} by default.@refill
12935 @itemx M-x makeinfo-region
12936 Format the current region for Info.@refill
12937 @findex makeinfo-region
12940 @itemx M-x makeinfo-buffer
12941 Format the current buffer for Info.@refill
12942 @findex makeinfo-buffer
12945 When you invoke either @code{makeinfo-region} or
12946 @code{makeinfo-buffer}, Emacs prompts for a file name, offering the
12947 name of the visited file as the default. You can edit the default
12948 file name in the minibuffer if you wish, before pressing @key{RET} to
12949 start the @code{makeinfo} process.@refill
12951 The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
12952 run the @code{makeinfo} program in a temporary shell buffer. If
12953 @code{makeinfo} finds any errors, Emacs displays the error messages in
12954 the temporary buffer.@refill
12956 @cindex Errors, parsing
12957 @cindex Parsing errors
12959 You can parse the error messages by typing @kbd{C-x `}
12960 (@code{next-error}). This causes Emacs to go to and position the
12961 cursor on the line in the Texinfo source that @code{makeinfo} thinks
12962 caused the error. @xref{Compilation, , Running @code{make} or
12963 Compilers Generally, xemacs, XEmacs User's Manual}, for more
12964 information about using the @code{next-error} command.@refill
12966 In addition, you can kill the shell in which the @code{makeinfo}
12967 command is running or make the shell buffer display its most recent
12972 @itemx M-x makeinfo-kill-job
12973 @findex makeinfo-kill-job
12974 Kill the current running @code{makeinfo} job created by
12975 @code{makeinfo-region} or @code{makeinfo-buffer}.@refill
12978 @itemx M-x makeinfo-recenter-output-buffer
12979 @findex makeinfo-recenter-output-buffer
12980 Redisplay the @code{makeinfo} shell buffer to display its most recent
12985 (Note that the parallel commands for killing and recentering a @TeX{}
12986 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
12989 You can specify options for @code{makeinfo} by setting the
12990 @code{makeinfo-options} variable with either the @kbd{M-x
12991 edit-options} or the @kbd{M-x set-variable} command, or by setting the
12992 variable in your @file{.emacs} initialization file.@refill
12994 For example, you could write the following in your @file{.emacs} file:@refill
12998 (setq makeinfo-options
12999 "--paragraph-indent=0 --no-split
13000 --fill-column=70 --verbose")
13004 @c If you write these three cross references using xref, you see
13005 @c three references to the same named manual, which looks strange.
13007 For more information, see @ref{makeinfo options, , Options for
13008 @code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and
13009 Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs
13014 For more information, see@*
13015 @ref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's Manual},@*
13016 @ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@*
13017 @ref{Init File, , , xemacs, XEmacs User's Manual}, and@*
13018 @ref{makeinfo options, , Options for @code{makeinfo}}.
13021 @node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File
13022 @comment node-name, next, previous, up
13023 @section The @code{texinfo-format@dots{}} Commands
13024 @findex texinfo-format-region
13025 @findex texinfo-format-buffer
13027 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
13028 file with the @code{texinfo-format-region} command. This formats the
13029 current region and displays the formatted text in a temporary buffer
13030 called @samp{*Info Region*}.@refill
13032 Similarly, you can format a buffer with the
13033 @code{texinfo-format-buffer} command. This command creates a new
13034 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
13035 save the Info file under the name specified by the
13036 @code{@@setfilename} line which must be near the beginning of the
13037 Texinfo file.@refill
13041 @itemx @code{texinfo-format-region}
13042 Format the current region for Info.
13043 @findex texinfo-format-region
13046 @itemx @code{texinfo-format-buffer}
13047 Format the current buffer for Info.
13048 @findex texinfo-format-buffer
13051 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
13052 commands provide you with some error checking, and other functions can
13053 provide you with further help in finding formatting errors. These
13054 procedures are described in an appendix; see @ref{Catching Mistakes}.
13055 However, the @code{makeinfo} program is often faster and
13056 provides better error checking (@pxref{makeinfo in Emacs}).@refill
13058 @node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File
13059 @comment node-name, next, previous, up
13060 @section Batch Formatting
13061 @cindex Batch formatting for Info
13062 @cindex Info batch formatting
13064 You can format Texinfo files for Info using @code{batch-texinfo-format}
13065 and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
13066 including a shell inside of Emacs. (@xref{Command Switches, , Command
13067 Line Switches and Arguments, xemacs, XEmacs User's Manual}.)@refill
13069 Here is a shell command to format all the files that end in
13070 @file{.texinfo} in the current directory:
13073 emacs -batch -funcall batch-texinfo-format *.texinfo
13077 Emacs processes all the files listed on the command line, even if an
13078 error occurs while attempting to format some of them.@refill
13080 Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
13081 it is not interactive. It kills the Batch mode Emacs on completion.@refill
13083 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
13084 and want to format several Texinfo files at once. When you use Batch
13085 mode, you create a new Emacs process. This frees your current Emacs, so
13086 you can continue working in it. (When you run
13087 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
13088 use that Emacs for anything else until the command finishes.)@refill
13090 @node Tag and Split Files, , Batch Formatting, Create an Info File
13091 @comment node-name, next, previous, up
13092 @section Tag Files and Split Files
13093 @cindex Making a tag table automatically
13094 @cindex Tag table, making automatically
13096 If a Texinfo file has more than 30,000 bytes,
13097 @code{texinfo-format-buffer} automatically creates a tag table
13098 for its Info file; @code{makeinfo} always creates a tag table. With
13099 a @dfn{tag table}, Info can jump to new nodes more quickly than it can
13102 @cindex Indirect subfiles
13103 In addition, if the Texinfo file contains more than about 70,000
13104 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
13105 large Info file into shorter @dfn{indirect} subfiles of about 50,000
13106 bytes each. Big files are split into smaller files so that Emacs does
13107 not need to make a large buffer to hold the whole of a large Info
13108 file; instead, Emacs allocates just enough memory for the small, split
13109 off file that is needed at the time. This way, Emacs avoids wasting
13110 memory when you run Info. (Before splitting was implemented, Info
13111 files were always kept short and @dfn{include files} were designed as
13112 a way to create a single, large printed manual out of the smaller Info
13113 files. @xref{Include Files}, for more information. Include files are
13114 still used for very large documents, such as @cite{The XEmacs Lisp
13115 Reference Manual}, in which each chapter is a separate file.)@refill
13117 When a file is split, Info itself makes use of a shortened version of
13118 the original file that contains just the tag table and references to
13119 the files that were split off. The split off files are called
13120 @dfn{indirect} files.@refill
13122 The split off files have names that are created by appending @w{@samp{-1}},
13123 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
13124 @code{@@setfilename} command. The shortened version of the original file
13125 continues to have the name specified by @code{@@setfilename}.@refill
13127 At one stage in writing this document, for example, the Info file was saved
13128 as @file{test-texinfo} and that file looked like this:@refill
13132 Info file: test-texinfo, -*-Text-*-
13133 produced by texinfo-format-buffer
13134 from file: new-texinfo-manual.texinfo
13138 test-texinfo-1: 102
13139 test-texinfo-2: 50422
13142 test-texinfo-3: 101300
13146 Node: overview^?104
13147 Node: info file^?1271
13150 Node: printed manual^?4853
13151 Node: conventions^?6855
13157 (But @file{test-texinfo} had far more nodes than are shown here.) Each of
13158 the split off, indirect files, @file{test-texinfo-1},
13159 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
13160 after the line that says @samp{Indirect:}. The tag table is listed after
13161 the line that says @samp{Tag table:}. @refill
13163 In the list of indirect files, the number following the file name
13164 records the cumulative number of bytes in the preceding indirect files,
13165 not counting the file list itself, the tag table, or the permissions
13166 text in each file. In the tag table, the number following the node name
13167 records the location of the beginning of the node, in bytes from the
13170 If you are using @code{texinfo-format-buffer} to create Info files,
13171 you may want to run the @code{Info-validate} command. (The
13172 @code{makeinfo} command does such a good job on its own, you do not
13173 need @code{Info-validate}.) However, you cannot run the @kbd{M-x
13174 Info-validate} node-checking command on indirect files. For
13175 information on how to prevent files from being split and how to
13176 validate the structure of the nodes, see @ref{Using
13177 Info-validate}.@refill
13180 @node Install an Info File, Command List, Create an Info File, Top
13181 @comment node-name, next, previous, up
13182 @chapter Installing an Info File
13183 @cindex Installing an Info file
13184 @cindex Info file installation
13185 @cindex @file{dir} directory for Info installation
13187 Info files are usually kept in the @file{info} directory. You can read
13188 Info files using the standalone Info program or the Info reader built
13189 into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
13192 * Directory file:: The top level menu for all Info files.
13193 * New Info File:: Listing a new info file.
13194 * Other Info Directories:: How to specify Info files that are
13195 located in other directories.
13196 * Installing Dir Entries:: How to specify what menu entry to add
13197 to the Info directory.
13198 * Invoking install-info:: @code{install-info} options.
13201 @node Directory file, New Info File, Install an Info File, Install an Info File
13203 @heading The @file{dir} File
13206 For Info to work, the @file{info} directory must contain a file that
13207 serves as a top level directory for the Info system. By convention,
13208 this file is called @file{dir}. (You can find the location of this file
13209 within Emacs by typing @kbd{C-h i} to enter Info and then typing
13210 @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
13212 The @file{dir} file is itself an Info file. It contains the top level
13213 menu for all the Info files in the system. The menu looks like
13220 * Info: (info). Documentation browsing system.
13221 * Emacs: (emacs). The extensible, self-documenting
13223 * Texinfo: (texinfo). With one source file, make
13224 either a printed manual using
13225 TeX or an Info file.
13230 Each of these menu entries points to the `Top' node of the Info file
13231 that is named in parentheses. (The menu entry does not need to
13232 specify the `Top' node, since Info goes to the `Top' node if no node
13233 name is mentioned. @xref{Other Info Files, , Nodes in Other Info
13236 Thus, the @samp{Info} entry points to the `Top' node of the
13237 @file{info} file and the @samp{Emacs} entry points to the `Top' node
13238 of the @file{emacs} file.@refill
13240 In each of the Info files, the `Up' pointer of the `Top' node refers
13241 back to the @code{dir} file. For example, the line for the `Top'
13242 node of the Emacs manual looks like this in Info:@refill
13245 File: emacs Node: Top, Up: (DIR), Next: Distrib
13249 (Note that in this case, the @file{dir} file name is written in upper
13250 case letters---it can be written in either upper or lower case. Info
13251 has a feature that it will change the case of the file name to lower
13252 case if it cannot find the name as written.)@refill
13253 @c !!! Can any file name be written in upper or lower case,
13254 @c or is dir a special case?
13255 @c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92
13258 @node New Info File, Other Info Directories, Directory file, Install an Info File
13259 @section Listing a New Info File
13260 @cindex Adding a new info file
13261 @cindex Listing a new info file
13262 @cindex New info file, listing it in @file{dir} file
13263 @cindex Info file, listing new one
13264 @cindex @file{dir} file listing
13266 To add a new Info file to your system, you must write a menu entry to
13267 add to the menu in the @file{dir} file in the @file{info} directory.
13268 For example, if you were adding documentation for GDB, you would write
13269 the following new entry:@refill
13272 * GDB: (gdb). The source-level C debugger.
13276 The first part of the menu entry is the menu entry name, followed by a
13277 colon. The second part is the name of the Info file, in parentheses,
13278 followed by a period. The third part is the description.
13280 The name of an Info file often has a @file{.info} extension. Thus, the
13281 Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
13282 The Info reader programs automatically try the file name both with and
13283 without @file{.info}; so it is better to avoid clutter and not to write
13284 @samp{.info} explicitly in the menu entry. For example, the GDB menu
13285 entry should use just @samp{gdb} for the file name, not @samp{gdb.info}.
13288 @node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File
13289 @comment node-name, next, previous, up
13290 @section Info Files in Other Directories
13291 @cindex Installing Info in another directory
13292 @cindex Info installed in another directory
13293 @cindex Another Info directory
13295 If an Info file is not in the @file{info} directory, there are three
13296 ways to specify its location:@refill
13300 Write the pathname in the @file{dir} file as the second part of the
13304 If you are using Emacs, list the name of the file in a second @file{dir}
13305 file, in its directory; and then add the name of that directory to the
13306 @code{Info-directory-list} variable in your personal or site
13307 initialization file.
13309 This tells Emacs where to look for @file{dir} files. Emacs merges the
13310 files named @file{dir} from each of the listed directories. (In Emacs
13311 version 18, you can set the @code{Info-directory} variable to the name
13312 of only one directory.)@refill
13315 Specify the Info directory name in the @code{INFOPATH} environment
13316 variable in your @file{.profile} or @file{.cshrc} initialization file.
13317 (Only you and others who set this environment variable will be able to
13318 find Info files whose location is specified this way.)@refill
13321 For example, to reach a test file in the @file{/home/bob/manuals}
13322 directory, you could add an entry like this to the menu in the
13323 @file{dir} file:@refill
13326 * Test: (/home/bob/manuals/info-test). Bob's own test file.
13330 In this case, the absolute file name of the @file{info-test} file is
13331 written as the second part of the menu entry.@refill
13333 @vindex Info-directory-list
13334 Alternatively, you could write the following in your @file{.emacs}
13339 (setq Info-directory-list
13340 '("/home/bob/manuals"
13341 "/usr/local/info"))
13345 @c reworded to avoid overfill hbox
13346 This tells Emacs to merge the @file{dir} file from the
13347 @file{/home/bob/manuals} directory with the @file{dir} file from the
13348 @file{/usr/local/info} directory. Info will list the
13349 @file{/home/bob/manuals/info-test} file as a menu entry in the
13350 @file{/home/bob/manuals/dir} file.@refill
13353 Finally, you can tell Info where to look by setting the @code{INFOPATH}
13354 environment variable in your @file{.cshrc} or @file{.profile} file. If
13355 you use a Bourne-compatible shell such as @code{sh} or @code{bash} for
13356 your shell command interpreter, you set the @code{INFOPATH} environment
13357 variable in the @file{.profile} initialization file; but if you use
13358 @code{csh} or @code{tcsh}, you must set the variable in the
13359 @file{.cshrc} initialization file. The two types of shells use
13364 In a @file{.cshrc} file, you could set the @code{INFOPATH}
13365 variable as follows:@refill
13368 setenv INFOPATH .:~/manuals:/usr/local/emacs/info
13372 In a @file{.profile} file, you would achieve the same effect by
13376 INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
13382 The @samp{.} indicates the current directory as usual. Emacs uses the
13383 @code{INFOPATH} environment variable to initialize the value of Emacs's
13384 own @code{Info-directory-list} variable.
13386 @cindex colon @r{last in @code{INFOPATH}}
13387 However you set @code{INFOPATH}, if its last character is a colon, this
13388 is replaced by the default (compiled-in) path. This gives you a way to
13389 augment the default path with new directories without having to list all
13390 the standard places. For example (using @code{sh} syntax:
13393 INFOPATH=/local/info:
13398 will search @file{/local/info} first, then the standard directories.
13399 Leading or doubled colons are not treated specially.
13402 @node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File
13403 @section Installing Info Directory Files
13405 When you install an Info file onto your system, you can use the program
13406 @code{install-info} to update the Info directory file @file{dir}.
13407 Normally the makefile for the package runs @code{install-info}, just
13408 after copying the Info file into its proper installed location.
13410 @findex dircategory
13412 In order for the Info file to work with @code{install-info}, you should
13413 use the commands @code{@@dircategory} and @code{@@direntry} in the
13414 Texinfo source file. Use @code{@@direntry} to specify the menu entry to
13415 add to the Info directory file, and use @code{@@dircategory} to specify
13416 which part of the Info directory to put it in. Here is how these
13417 commands are used in this manual:
13420 @@dircategory Texinfo documentation system
13422 * Texinfo: (texinfo). The GNU documentation format.
13423 * install-info: (texinfo)Invoking install-info. @dots{}
13428 Here's what this produces in the Info file:
13431 INFO-DIR-SECTION Texinfo documentation system
13432 START-INFO-DIR-ENTRY
13433 * Texinfo: (texinfo). The GNU documentation format.
13434 * install-info: (texinfo)Invoking install-info. @dots{}
13440 The @code{install-info} program sees these lines in the Info file, and
13441 that is how it knows what to do.
13443 Always use the @code{@@direntry} and @code{@@dircategory} commands near
13444 the beginning of the Texinfo input, before the first @code{@@node}
13445 command. If you use them later on in the input, @code{install-info}
13446 will not notice them.
13448 If you use @code{@@dircategory} more than once in the Texinfo source,
13449 each usage specifies one category; the new menu entry is added to the
13450 Info directory file in each of the categories you specify. If you use
13451 @code{@@direntry} more than once, each usage specifies one menu entry;
13452 each of these menu entries is added to the directory in each of the
13453 specified categories.
13456 @node Invoking install-info, , Installing Dir Entries, Install an Info File
13457 @section Invoking install-info
13459 @pindex install-info
13461 @code{install-info} inserts menu entries from an Info file into the
13462 top-level @file{dir} file in the Info system (see the previous sections
13463 for an explanation of how the @file{dir} file works). It's most often
13464 run as part of software installation, or when constructing a dir file
13465 for all manuals on a system. Synopsis:
13468 install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
13471 If @var{info-file} or @var{dir-file} are not specified, the various
13472 options (described below) that define them must be. There are no
13473 compile-time defaults, and standard input is never used.
13474 @code{install-info} can read only one info file and write only one dir
13475 file per invocation.
13477 @cindex @file{dir}, created by @code{install-info}
13478 If @var{dir-file} (however specified) does not exist,
13479 @code{install-info} creates it if possible (with no entries).
13486 Delete the entries in @var{info-file} from @var{dir-file}. The file
13487 name in the entry in @var{dir-file} must be @var{info-file} (except for
13488 an optional @samp{.info} in either one). Don't insert any new entries.
13490 @item --dir-file=@var{name}
13491 @opindex --dir-file=@var{name}
13492 Specify file name of the Info directory file. This is equivalent to
13493 using the @var{dir-file} argument.
13495 @item --entry=@var{text}
13496 @opindex --entry=@var{text}
13497 Insert @var{text} as an Info directory entry; @var{text} should have the
13498 form of an Info menu item line plus zero or more extra lines starting
13499 with whitespace. If you specify more than one entry, they are all
13500 added. If you don't specify any entries, they are determined from
13501 information in the Info file itself.
13505 Display a usage message listing basic usage and all available options,
13506 then exit successfully.
13508 @item --info-file=@var{file}
13509 @opindex --info-file=@var{file}
13510 Specify Info file to install in the directory.
13511 This is equivalent to using the @var{info-file} argument.
13513 @item --info-dir=@var{dir}
13514 @opindex --info-dir=@var{dir}
13515 Equivalent to @samp{--dir-file=@var{dir}/dir}.
13517 @item --item=@var{text}
13518 @opindex --item=@var{text}
13519 Same as @samp{--entry=@var{text}}. An Info directory entry is actually
13528 Same as @samp{--delete}.
13530 @item --section=@var{sec}
13531 @opindex --section=@var{sec}
13532 Put this file's entries in section @var{sec} of the directory. If you
13533 specify more than one section, all the entries are added in each of the
13534 sections. If you don't specify any sections, they are determined from
13535 information in the Info file itself.
13539 @cindex version number, finding
13540 Display version information and exit successfully.
13545 @node Command List, Tips, Install an Info File, Top
13546 @appendix @@-Command List
13547 @cindex Alphabetical @@-command list
13548 @cindex List of @@-commands
13549 @cindex @@-command list
13551 Here is an alphabetical list of the @@-commands in Texinfo. Square
13552 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
13553 @samp{@dots{}}, indicates repeated text.@refill
13557 @item @@@var{whitespace}
13558 An @code{@@} followed by a space, tab, or newline produces a normal,
13559 stretchable, interword space. @xref{Multiple Spaces}.
13562 Generate an exclamation point that really does end a sentence (usually
13563 after an end-of-sentence capital letter). @xref{Ending a Sentence}.
13567 Generate an umlaut or acute accent, respectively, over the next
13568 character, as in @"o and @'o. @xref{Inserting Accents}.
13571 Force a line break. Do not end a paragraph that uses @code{@@*} with
13572 an @code{@@refill} command. @xref{Line Breaks}.@refill
13574 @item @@,@{@var{c}@}
13575 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
13579 Insert a discretionary hyphenation point. @xref{- and hyphenation}.
13582 Produce a period that really does end a sentence (usually after an
13583 end-of-sentence capital letter). @xref{Ending a Sentence}.
13586 Indicate to @TeX{} that an immediately preceding period, question
13587 mark, exclamation mark, or colon does not end a sentence. Prevent
13588 @TeX{} from inserting extra whitespace as it does at the end of a
13589 sentence. The command has no effect on the Info file output.
13590 @xref{Not Ending a Sentence}.@refill
13593 Generate a macro (bar) accent over the next character, as in @=o.
13594 @xref{Inserting Accents}.
13597 Generate a question mark that really does end a sentence (usually after
13598 an end-of-sentence capital letter). @xref{Ending a Sentence}.
13601 Stands for an at sign, @samp{@@}.
13602 @xref{Braces Atsigns, , Inserting @@ and braces}.
13606 Generate a circumflex (hat) or grave accent, respectively, over the next
13607 character, as in @^o.
13608 @xref{Inserting Accents}.
13611 Stands for a left brace, @samp{@{}.
13612 @xref{Braces Atsigns, , Inserting @@ and braces}.
13615 Stands for a right-hand brace, @samp{@}}.@*
13616 @xref{Braces Atsigns, , Inserting @@ and braces}.
13619 Generate a tilde accent over the next character, as in @~N.
13620 @xref{Inserting Accents}.
13624 Generate the uppercase and lowercase Scandinavian A-ring letters,
13625 respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
13629 Generate the uppercase and lowercase AE ligatures, respectively:
13630 @AE{}, @ae{}. @xref{Inserting Accents}.
13633 Change page dimensions for the A4 paper size.
13634 Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}.
13637 @item @@appendix @var{title}
13638 Begin an appendix. The title appears in the table
13639 of contents of a printed manual. In Info, the title is
13640 underlined with asterisks. @xref{unnumbered & appendix, , The
13641 @code{@@unnumbered} and @code{@@appendix} Commands}.@refill
13643 @item @@appendixsec @var{title}
13644 @itemx @@appendixsection @var{title}
13645 Begin an appendix section within an appendix. The section title appears
13646 in the table of contents of a printed manual. In Info, the title is
13647 underlined with equal signs. @code{@@appendixsection} is a longer
13648 spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
13649 appendixsec heading, , Section Commands}.@refill
13651 @item @@appendixsubsec @var{title}
13652 Begin an appendix subsection within an appendix. The title appears
13653 in the table of contents of a printed manual. In Info, the title is
13654 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
13655 subheading, , Subsection Commands}.@refill
13657 @item @@appendixsubsubsec @var{title}
13658 Begin an appendix subsubsection within an appendix subsection. The
13659 title appears in the table of contents of a printed manual. In Info,
13660 the title is underlined with periods. @xref{subsubsection,, The
13661 `subsub' Commands}.@refill
13664 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
13665 print the table's first column without highlighting (``as is'').
13666 @xref{Two-column Tables, , Making a Two-column Table}.@refill
13668 @item @@author @var{author}
13669 Typeset @var{author} flushleft and underline it. @xref{title
13670 subtitle author, , The @code{@@title} and @code{@@author}
13673 @item @@b@{@var{text}@}
13674 Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill
13678 Force a paragraph break. If used within a line, follow @code{@@br}
13679 with braces. @xref{br, , @code{@@br}}.@refill
13683 Generate a large round dot, or the closest possible
13684 thing to one. @xref{bullet, , @code{@@bullet}}.@refill
13687 Stop formatting a file. The formatters do not see the contents of a
13688 file following an @code{@@bye} command. @xref{Ending a File}.@refill
13690 @item @@c @var{comment}
13691 Begin a comment in Texinfo. The rest of the line does not appear in
13692 either the Info file or the printed manual. A synonym for
13693 @code{@@comment}. @xref{Comments, , Comments}.@refill
13696 Highlight an example or quotation by drawing a box with rounded
13697 corners around it. Pair with @code{@@end cartouche}. No effect in
13698 Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
13700 @item @@center @var{line-of-text}
13701 Center the line of text following the command.
13702 @xref{titlefont center sp, , @code{@@center}}.@refill
13704 @item @@centerchap @var{line-of-text}
13705 Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
13708 @item @@chapheading @var{title}
13709 Print a chapter-like heading in the text, but not in the table of
13710 contents of a printed manual. In Info, the title is underlined with
13711 asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
13712 and @code{@@chapheading}}.@refill
13714 @item @@chapter @var{title}
13715 Begin a chapter. The chapter title appears in the table of
13716 contents of a printed manual. In Info, the title is underlined with
13717 asterisks. @xref{chapter, , @code{@@chapter}}.@refill
13719 @item @@cindex @var{entry}
13720 Add @var{entry} to the index of concepts. @xref{Index Entries, ,
13721 Defining the Entries of an Index}.@refill
13723 @item @@cite@{@var{reference}@}
13724 Highlight the name of a book or other reference that lacks a
13725 companion Info file. @xref{cite, , @code{@@cite}}.@refill
13727 @item @@clear @var{flag}
13728 Unset @var{flag}, preventing the Texinfo formatting commands from
13729 formatting text between subsequent pairs of @code{@@ifset @var{flag}}
13730 and @code{@@end ifset} commands, and preventing
13731 @code{@@value@{@var{flag}@}} from expanding to the value to which
13733 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
13735 @item @@code@{@var{sample-code}@}
13736 Highlight text that is an expression, a syntactically complete token
13737 of a program, or a program name. @xref{code, , @code{@@code}}.@refill
13739 @item @@comment @var{comment}
13740 Begin a comment in Texinfo. The rest of the line does not appear in
13741 either the Info file or the printed manual. A synonym for @code{@@c}.
13742 @xref{Comments, , Comments}.@refill
13745 Print a complete table of contents. Has no effect in Info, which uses
13746 menus instead. @xref{Contents, , Generating a Table of
13749 @item @@copyright@{@}
13750 Generate a copyright symbol. @xref{copyright symbol, ,
13751 @code{@@copyright}}.@refill
13754 @item @@ctrl@{@var{ctrl-char}@}
13755 Describe an @sc{ascii} control character. Insert actual control character
13756 into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
13759 @item @@defcodeindex @var{index-name}
13760 Define a new index and its indexing command. Print entries in an
13761 @code{@@code} font. @xref{New Indices, , Defining New
13764 @item @@defcv @var{category} @var{class} @var{name}
13765 @itemx @@defcvx @var{category} @var{class} @var{name}
13766 Format a description for a variable associated with a class in
13767 object-oriented programming. Takes three arguments: the category of
13768 thing being defined, the class to which it belongs, and its name.
13769 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13771 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
13772 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
13773 Format a description for a function, interactive command, or similar
13774 entity that may take arguments. @code{@@deffn} takes as arguments the
13775 category of entity being described, the name of this particular
13776 entity, and its arguments, if any. @xref{Definition Commands}.@refill
13778 @item @@defindex @var{index-name}
13779 Define a new index and its indexing command. Print entries in a roman
13780 font. @xref{New Indices, , Defining New Indices}.@refill
13782 @c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96.
13783 @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
13784 Create new @@-command for Info that marks text by enclosing it in
13785 strings that precede and follow the text. Write definition inside of
13786 @code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized
13787 Highlighting}.@refill
13789 @item @@defivar @var{class} @var{instance-variable-name}
13790 @itemx @@defivarx @var{class} @var{instance-variable-name}
13791 This command formats a description for an instance variable in
13792 object-oriented programming. The command is equivalent to @samp{@@defcv
13793 @{Instance Variable@} @dots{}}. @xref{Definition Commands}, and
13794 @ref{deffnx,, Def Cmds in Detail}.
13796 @item @@defmac @var{macro-name} @var{arguments}@dots{}
13797 @itemx @@defmacx @var{macro-name} @var{arguments}@dots{}
13798 Format a description for a macro. The command is equivalent to
13799 @samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and
13800 @ref{deffnx,, Def Cmds in Detail}.
13802 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
13803 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
13804 Format a description for a method in object-oriented programming. The
13805 command is equivalent to @samp{@@defop Method @dots{}}. Takes as
13806 arguments the name of the class of the method, the name of the
13807 method, and its arguments, if any. @xref{Definition Commands}, and
13808 @ref{deffnx,, Def Cmds in Detail}.
13810 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
13811 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
13812 Format a description for an operation in object-oriented programming.
13813 @code{@@defop} takes as arguments the overall name of the category of
13814 operation, the name of the class of the operation, the name of the
13815 operation, and its arguments, if any. @xref{Definition
13816 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13818 @item @@defopt @var{option-name}
13819 @itemx @@defoptx @var{option-name}
13820 Format a description for a user option. The command is equivalent to
13821 @samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and
13822 @ref{deffnx,, Def Cmds in Detail}.
13824 @item @@defspec @var{special-form-name} @var{arguments}@dots{}
13825 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
13826 Format a description for a special form. The command is equivalent to
13827 @samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands},
13828 and @ref{deffnx,, Def Cmds in Detail}.
13830 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
13831 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
13832 Format a description for a data type. @code{@@deftp} takes as arguments
13833 the category, the name of the type (which is a word like @samp{int} or
13834 @samp{float}), and then the names of attributes of objects of that type.
13835 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13837 @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
13838 @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
13839 Format a description for a function or similar entity that may take
13840 arguments and that is typed. @code{@@deftypefn} takes as arguments the
13841 classification of entity being described, the type, the name of the
13842 entity, and its arguments, if any. @xref{Definition Commands}, and
13843 @ref{deffnx,, Def Cmds in Detail}.
13845 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
13846 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
13847 Format a description for a function in a typed language.
13848 The command is equivalent to @samp{@@deftypefn Function @dots{}}.
13849 @xref{Definition Commands},
13850 and @ref{deffnx,, Def Cmds in Detail}.
13852 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
13853 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
13854 Format a description for a typed method in object-oriented programming.
13855 Takes as arguments the name of the class of the method, the return type
13856 of the method, the name of the method, and its arguments, if any.
13857 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13859 @item @@deftypevr @var{classification} @var{data-type} @var{name}
13860 @itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
13861 Format a description for something like a variable in a typed
13862 language---an entity that records a value. Takes as arguments the
13863 classification of entity being described, the type, and the name of the
13864 entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
13867 @item @@deftypevar @var{data-type} @var{variable-name}
13868 @itemx @@deftypevarx @var{data-type} @var{variable-name}
13869 Format a description for a variable in a typed language. The command is
13870 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
13871 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13873 @item @@defun @var{function-name} @var{arguments}@dots{}
13874 @itemx @@defunx @var{function-name} @var{arguments}@dots{}
13875 Format a description for functions. The command is equivalent to
13876 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
13877 @ref{deffnx,, Def Cmds in Detail}.
13879 @item @@defvar @var{variable-name}
13880 @itemx @@defvarx @var{variable-name}
13881 Format a description for variables. The command is equivalent to
13882 @samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and
13883 @ref{deffnx,, Def Cmds in Detail}.
13885 @item @@defvr @var{category} @var{name}
13886 @itemx @@defvrx @var{category} @var{name}
13887 Format a description for any kind of variable. @code{@@defvr} takes
13888 as arguments the category of the entity and the name of the entity.
13889 @xref{Definition Commands},
13890 and @ref{deffnx,, Def Cmds in Detail}.
13892 @item @@detailmenu@{@}
13893 Avoid @code{makeinfo} confusion stemming from the detailed node listing
13894 in a master menu. @xref{Master Menu Parts}.
13896 @item @@dfn@{@var{term}@}
13897 Highlight the introductory or defining use of a term.
13898 @xref{dfn, , @code{@@dfn}}.@refill
13900 @item @@dircategory @var{dirpart}
13901 Specify a part of the Info directory menu where this file's entry should
13902 go. @xref{Installing Dir Entries}.
13905 Begin the Info directory menu entry for this file.
13906 @xref{Installing Dir Entries}.
13910 Begin a kind of example. Indent text, do not fill, do not select a
13911 new font. Pair with @code{@@end display}. @xref{display, ,
13912 @code{@@display}}.@refill
13914 @item @@dmn@{@var{dimension}@}
13915 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
13916 thin space before @var{dimension}. No effect in Info.
13917 @xref{dmn, , @code{@@dmn}}.@refill
13919 @item @@dotaccent@{@var{c}@}
13920 Generate a dot accent over the character @var{c}, as in @dotaccent{oo}.
13921 @xref{Inserting Accents}.
13924 Insert an ellipsis: @samp{@dots{}}.
13925 @xref{dots, , @code{@@dots@{@}}}.@refill
13927 @item @@email@{@var{address}[, @var{displayed-text}]@}
13928 Indicate an electronic mail address.
13929 @xref{email, , @code{@@email}}.@refill
13932 @item @@emph@{@var{text}@}
13933 Highlight @var{text}; text is displayed in @emph{italics} in printed
13934 output, and surrounded by asterisks in Info. @xref{Emphasis, ,
13937 @item @@end @var{environment}
13938 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
13939 Commands,,@@-commands}.
13941 @item @@enddots@{@}
13942 Generate an end-of-sentence of ellipsis, like this @enddots{}
13943 @xref{dots,,@code{@@dots@{@}}}.
13946 @item @@enumerate [@var{number-or-letter}]
13947 Begin a numbered list, using @code{@@item} for each entry.
13948 Optionally, start list with @var{number-or-letter}. Pair with
13949 @code{@@end enumerate}. @xref{enumerate, ,
13950 @code{@@enumerate}}.@refill
13954 Indicate to the reader the exact equivalence of two forms with a
13955 glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
13958 Indicate to the reader with a glyph that the following text is
13959 an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
13961 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
13962 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
13963 Specify page footings resp.@: headings for even-numbered (left-hand)
13964 pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
13965 How to Make Your Own Headings}.@refill
13967 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
13968 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
13969 Specify page footings resp.@: headings for every page. Not relevant to
13970 Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
13973 Begin an example. Indent text, do not fill, and select fixed-width font.
13974 Pair with @code{@@end example}. @xref{example, ,
13975 @code{@@example}}.@refill
13977 @item @@exclamdown@{@}
13978 Produce an upside-down exclamation point. @xref{Inserting Accents}.
13980 @item @@exdent @var{line-of-text}
13981 Remove any indentation a line might have. @xref{exdent, ,
13982 Undoing the Indentation of a Line}.@refill
13984 @item @@expansion@{@}
13985 Indicate the result of a macro expansion to the reader with a special
13986 glyph: @samp{@expansion{}}.
13987 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
13989 @item @@file@{@var{filename}@}
13990 Highlight the name of a file, buffer, node, or directory. @xref{file, ,
13991 @code{@@file}}.@refill
13994 Prevent @TeX{} from printing large black warning rectangles beside
13995 over-wide lines. @xref{Overfull hboxes}.@refill
13998 @item @@findex @var{entry}
13999 Add @var{entry} to the index of functions. @xref{Index Entries, ,
14000 Defining the Entries of an Index}.@refill
14004 @itemx @@flushright
14005 Left justify every line but leave the right end ragged.
14006 Leave font as is. Pair with @code{@@end flushleft}.
14007 @code{@@flushright} analogous.
14008 @xref{flushleft & flushright, , @code{@@flushleft} and
14009 @code{@@flushright}}.@refill
14012 @item @@footnote@{@var{text-of-footnote}@}
14013 Enter a footnote. Footnote text is printed at the bottom of the page
14014 by @TeX{}; Info may format in either `End' node or `Separate' node style.
14015 @xref{Footnotes}.@refill
14017 @item @@footnotestyle @var{style}
14018 Specify an Info file's footnote style, either @samp{end} for the end
14019 node style or @samp{separate} for the separate node style.
14020 @xref{Footnotes}.@refill
14023 Begin a kind of example. Like @code{@@example} or @code{@@display},
14024 but do not narrow the margins and do not select the fixed-width font.
14025 Pair with @code{@@end format}. @xref{example, ,
14026 @code{@@example}}.@refill
14028 @item @@ftable @var{formatting-command}
14029 Begin a two-column table, using @code{@@item} for each entry.
14030 Automatically enter each of the items in the first column into the
14031 index of functions. Pair with @code{@@end ftable}. The same as
14032 @code{@@table}, except for indexing. @xref{ftable vtable, ,
14033 @code{@@ftable} and @code{@@vtable}}.@refill
14036 Hold text together that must appear on one printed page. Pair with
14037 @code{@@end group}. Not relevant to Info. @xref{group, ,
14038 @code{@@group}}.@refill
14040 @item @@H@{@var{c}@}
14041 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
14043 @item @@heading @var{title}
14044 Print an unnumbered section-like heading in the text, but not in the
14045 table of contents of a printed manual. In Info, the title is
14046 underlined with equal signs. @xref{unnumberedsec appendixsec heading,
14047 , Section Commands}.@refill
14049 @item @@headings @var{on-off-single-double}
14050 Turn page headings on or off, and/or specify single-sided or double-sided
14051 page headings for printing. @xref{headings on off, , The
14052 @code{@@headings} Command}.
14055 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
14056 Formatter Commands}.
14058 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
14059 Explicitly define hyphenation points. @xref{- and hyphenation,,
14060 @code{@@-} and @code{@@hyphenation}}.
14062 @item @@i@{@var{text}@}
14063 Print @var{text} in @i{italic} font. No effect in Info.
14064 @xref{Fonts}.@refill
14066 @item @@ifclear @var{flag}
14067 If @var{flag} is cleared, the Texinfo formatting commands format text
14068 between @code{@@ifclear @var{flag}} and the following @code{@@end
14070 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14074 Begin a stretch of text that will be ignored by @TeX{} when it typesets
14075 the printed manual. The text appears only in the HTML resp.@: Info
14076 file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
14077 @xref{Conditionals}.
14082 Begin a stretch of text that will be ignored in one output format but
14083 not the others. The text appears only in the format not specified.
14084 Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
14085 @code{@@end ifnotinfo}. @xref{Conditionals}.
14087 @item @@ifset @var{flag}
14088 If @var{flag} is set, the Texinfo formatting commands format text
14089 between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
14091 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14094 Begin a stretch of text that will not appear in the Info file, but
14095 will be processed only by @TeX{}. Pair with @code{@@end iftex}.
14096 @xref{Conditionals, , Conditionally Visible Text}.@refill
14099 Begin a stretch of text that will not appear in either the Info file
14100 or the printed output. Pair with @code{@@end ignore}.
14101 @xref{Comments, , Comments and Ignored Text}.@refill
14103 @item @@image@{@var{filename}, [@var{width}], [@var{height}]@}
14104 Include graphics image in external @var{filename} scaled to the given
14105 @var{width} and/or @var{height}. @xref{Images}.
14107 @item @@include @var{filename}
14108 Incorporate the contents of the file @var{filename} into the Info file
14109 or printed document. @xref{Include Files}.@refill
14111 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
14112 Make a cross reference to an Info file for which there is no printed
14113 manual. @xref{inforef, , Cross references using
14114 @code{@@inforef}}.@refill
14116 @item \input @var{macro-definitions-file}
14117 Use the specified macro definitions file. This command is used only
14118 in the first line of a Texinfo file to cause @TeX{} to make use of the
14119 @file{texinfo} macro definitions file. The backslash in @code{\input}
14120 is used instead of an @code{@@} because @TeX{} does not
14121 recognize @code{@@} until after it has read the definitions file.
14122 @xref{Header, , The Texinfo File Header}.@refill
14125 Indicate the beginning of a marked paragraph for @code{@@itemize} and
14126 @code{@@enumerate}; indicate the beginning of the text of a first column
14127 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
14128 @xref{Lists and Tables}.@refill
14130 @item @@itemize @var{mark-generating-character-or-command}
14131 Produce a sequence of indented paragraphs, with a mark inside the left
14132 margin at the beginning of each paragraph. Pair with @code{@@end
14133 itemize}. @xref{itemize, , @code{@@itemize}}.@refill
14136 Like @code{@@item} but do not generate extra vertical space above the
14137 item text. @xref{itemx, , @code{@@itemx}}.@refill
14139 @item @@kbd@{@var{keyboard-characters}@}
14140 Indicate text that is characters of input to be typed by
14141 users. @xref{kbd, , @code{@@kbd}}.@refill
14143 @item @@kbdinputstyle @var{style}
14144 Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
14145 @xref{kbd, , @code{@@kbd}}.@refill
14147 @item @@key@{@var{key-name}@}
14148 Indicate a name for a key on a keyboard.
14149 @xref{key, , @code{@@key}}.@refill
14151 @item @@kindex @var{entry}
14152 Add @var{entry} to the index of keys.
14153 @xref{Index Entries, , Defining the Entries of an Index}.@refill
14157 Generate the uppercase and lowercase Polish suppressed-L letters,
14158 respectively: @L{}, @l{}.
14160 @c Possibly this can be tossed now that we have macros. --karl, 16sep96.
14161 @c Yes, let's toss it, it's pretty weird. --karl, 15jun97.
14162 @c @item @@global@@let@var{new-command}=@var{existing-command}
14163 @c Equate a new highlighting command with an existing one. Only for
14164 @c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end
14165 @c iftex}. @xref{Customized Highlighting}.@refill
14168 Begin an example of Lisp code. Indent text, do not fill, and select
14169 fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, ,
14170 @code{@@lisp}}.@refill
14172 @item @@lowersections
14173 Change subsequent chapters to sections, sections to subsections, and so
14174 on. @xref{Raise/lower sections, , @code{@@raisesections} and
14175 @code{@@lowersections}}.@refill
14177 @item @@macro @var{macro-name} @{@var{params}@}
14178 Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}.
14179 Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
14182 @item @@majorheading @var{title}
14183 Print a chapter-like heading in the text, but not in the table of
14184 contents of a printed manual. Generate more vertical whitespace before
14185 the heading than the @code{@@chapheading} command. In Info, the chapter
14186 heading line is underlined with asterisks. @xref{majorheading &
14187 chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
14189 @item @@math@{@var{mathematical-expression}@}
14190 Format a mathematical expression.
14191 @xref{math, , @code{@@math} - Inserting Mathematical Expressions}.
14194 Mark the beginning of a menu of nodes in Info. No effect in a printed
14195 manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
14198 Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill
14200 @item @@multitable @var{column-width-spec}
14201 Begin a multi-column table. Pair with @code{@@end multitable}.
14202 @xref{Multitable Column Widths}.
14204 @item @@need @var{n}
14205 Start a new page in a printed manual if fewer than @var{n} mils
14206 (thousandths of an inch) remain on the current page. @xref{need, ,
14207 @code{@@need}}.@refill
14209 @item @@node @var{name, next, previous, up}
14210 Define the beginning of a new node in Info, and serve as a locator for
14211 references for @TeX{}. @xref{node, , @code{@@node}}.@refill
14214 Prevent text from being indented as if it were a new paragraph.
14215 @xref{noindent, , @code{@@noindent}}.@refill
14219 Generate the uppercase and lowercase O-with-slash letters, respectively:
14222 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
14223 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
14224 Specify page footings resp.@: headings for odd-numbered (right-hand)
14225 pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
14226 How to Make Your Own Headings}.@refill
14230 Generate the uppercase and lowercase OE ligatures, respectively:
14231 @OE{}, @oe{}. @xref{Inserting Accents}.
14234 Start a new page in a printed manual. No effect in Info.
14235 @xref{page, , @code{@@page}}.@refill
14237 @item @@paragraphindent @var{indent}
14238 Indent paragraphs by @var{indent} number of spaces; delete indentation
14239 if the value of @var{indent} is 0; and do not change indentation if
14240 @var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph
14243 @item @@pindex @var{entry}
14244 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
14245 the Entries of an Index}.@refill
14248 Indicate the position of point in a buffer to the reader with a
14249 glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
14250 Point in a Buffer}.@refill
14253 Generate the pounds sterling currency sign.
14254 @xref{pounds,,@code{@@pounds@{@}}}.
14257 Indicate printed output to the reader with a glyph:
14258 @samp{@print{}}. @xref{Print Glyph}.@refill
14260 @item @@printindex @var{index-name}
14261 Print an alphabetized two-column index in a printed manual or generate
14262 an alphabetized menu of index entries for Info. @xref{Printing
14263 Indices & Menus}.@refill
14265 @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14266 Make a reference that starts with a lower case `see' in a printed
14267 manual. Use within parentheses only. Do not follow command with a
14268 punctuation mark---the Info formatting commands automatically insert
14269 terminating punctuation as needed. Only the first argument is mandatory.
14270 @xref{pxref, , @code{@@pxref}}.@refill
14272 @item @@questiondown@{@}
14273 Generate an upside-down question mark. @xref{Inserting Accents}.
14276 Narrow the margins to indicate text that is quoted from another real
14277 or imaginary work. Write command on a line of its own. Pair with
14278 @code{@@end quotation}. @xref{quotation, ,
14279 @code{@@quotation}}.@refill
14282 @item @@r@{@var{text}@}
14283 Print @var{text} in @r{roman} font. No effect in Info.
14284 @xref{Fonts}.@refill
14286 @item @@raisesections
14287 Change subsequent sections to chapters, subsections to sections, and so
14288 on. @xref{Raise/lower sections, , @code{@@raisesections} and
14289 @code{@@lowersections}}.@refill
14292 @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14293 Make a reference. In a printed manual, the reference does not start
14294 with a `See'. Follow command with a punctuation mark. Only the first
14295 argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
14299 In Info, refill and indent the paragraph after all the other processing
14300 has been done. No effect on @TeX{}, which always refills. This command
14301 is no longer needed, since all formatters now automatically refill.
14302 @xref{Refilling Paragraphs}.@refill
14306 Indicate the result of an expression to the reader with a special
14307 glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
14309 @item @@ringaccent@{@var{c}@}
14310 Generate a ring accent over the next character, as in @ringaccent{o}.
14311 @xref{Inserting Accents}.
14313 @item @@samp@{@var{text}@}
14314 Highlight @var{text} that is a literal example of a sequence of
14315 characters. Used for single characters, for statements, and often for
14316 entire shell commands. @xref{samp, , @code{@@samp}}.@refill
14318 @item @@sc@{@var{text}@}
14319 Set @var{text} in a printed output in @sc{the small caps font} and
14320 set text in the Info file in uppercase letters.
14321 @xref{Smallcaps}.@refill
14323 @item @@section @var{title}
14324 Begin a section within a chapter. In a printed manual, the section
14325 title is numbered and appears in the table of contents. In Info, the
14326 title is underlined with equal signs. @xref{section, ,
14327 @code{@@section}}.@refill
14329 @item @@set @var{flag} [@var{string}]
14330 Make @var{flag} active, causing the Texinfo formatting commands to
14331 format text between subsequent pairs of @code{@@ifset @var{flag}} and
14332 @code{@@end ifset} commands. Optionally, set value of @var{flag} to
14334 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14336 @item @@setchapternewpage @var{on-off-odd}
14337 Specify whether chapters start on new pages, and if so, whether on
14338 odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
14339 @code{@@setchapternewpage}}.@refill
14341 @item @@setfilename @var{info-file-name}
14342 Provide a name to be used by the Info file. This command is essential
14343 for @TeX{} formatting as well, even though it produces no output.
14344 @xref{setfilename, , @code{@@setfilename}}.@refill
14346 @item @@settitle @var{title}
14347 Provide a title for page headers in a printed manual.
14348 @xref{settitle, , @code{@@settitle}}.@refill
14350 @item @@shortcontents
14351 Print a short table of contents. Not relevant to Info, which uses
14352 menus rather than tables of contents. A synonym for
14353 @code{@@summarycontents}. @xref{Contents, , Generating a Table of
14356 @item @@shorttitlepage@{@var{title}@}
14357 Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
14361 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
14362 rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
14363 Printing Small Books}. Also, see @ref{smallexample & smalllisp, ,
14364 @code{@@smallexample} and @code{@@smalllisp}}.@refill
14367 @item @@smallexample
14368 Indent text to indicate an example. Do not fill, select fixed-width
14369 font. In @code{@@smallbook} format, print text in a smaller font than
14370 with @code{@@example}. Pair with @code{@@end smallexample}.
14371 @xref{smallexample & smalllisp, , @code{@@smallexample} and
14372 @code{@@smalllisp}}.@refill
14376 Begin an example of Lisp code. Indent text, do not fill, select
14377 fixed-width font. In @code{@@smallbook} format, print text in a
14378 smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample &
14379 smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill
14383 Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
14386 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
14389 @item @@strong @var{text}
14390 Emphasize @var{text} by typesetting it in a @strong{bold} font for the
14391 printed manual and by surrounding it with asterisks for Info.
14392 @xref{emph & strong, , Emphasizing Text}.@refill
14394 @item @@subheading @var{title}
14395 Print an unnumbered subsection-like heading in the text, but not in
14396 the table of contents of a printed manual. In Info, the title is
14397 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
14398 subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
14399 @code{@@subheading}}.@refill
14401 @item @@subsection @var{title}
14402 Begin a subsection within a section. In a printed manual, the
14403 subsection title is numbered and appears in the table of contents. In
14404 Info, the title is underlined with hyphens. @xref{subsection, ,
14405 @code{@@subsection}}.@refill
14407 @item @@subsubheading @var{title}
14408 Print an unnumbered subsubsection-like heading in the text, but not in
14409 the table of contents of a printed manual. In Info, the title is
14410 underlined with periods. @xref{subsubsection, , The `subsub'
14413 @item @@subsubsection @var{title}
14414 Begin a subsubsection within a subsection. In a printed manual,
14415 the subsubsection title is numbered and appears in the table of
14416 contents. In Info, the title is underlined with periods.
14417 @xref{subsubsection, , The `subsub' Commands}.@refill
14419 @item @@subtitle @var{title}
14420 In a printed manual, set a subtitle in a normal sized font flush to
14421 the right-hand side of the page. Not relevant to Info, which does not
14422 have title pages. @xref{title subtitle author, , @code{@@title}
14423 @code{@@subtitle} and @code{@@author} Commands}.@refill
14425 @item @@summarycontents
14426 Print a short table of contents. Not relevant to Info, which uses
14427 menus rather than tables of contents. A synonym for
14428 @code{@@shortcontents}. @xref{Contents, , Generating a Table of
14432 @item @@syncodeindex @var{from-index} @var{into-index}
14433 Merge the index named in the first argument into the index named in
14434 the second argument, printing the entries from the first index in
14435 @code{@@code} font. @xref{Combining Indices}.@refill
14438 @item @@synindex @var{from-index} @var{into-index}
14439 Merge the index named in the first argument into the index named in
14440 the second argument. Do not change the font of @var{from-index}
14441 entries. @xref{Combining Indices}.@refill
14444 @item @@t@{@var{text}@}
14445 Print @var{text} in a @t{fixed-width}, typewriter-like font.
14446 No effect in Info. @xref{Fonts}.@refill
14449 Separate columns in a multitable. @xref{Multitable Rows}.
14452 @item @@table @var{formatting-command}
14453 Begin a two-column table, using @code{@@item} for each entry. Write
14454 each first column entry on the same line as @code{@@item}. First
14455 column entries are printed in the font resulting from
14456 @var{formatting-command}. Pair with @code{@@end table}.
14457 @xref{Two-column Tables, , Making a Two-column Table}.
14458 Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
14459 and @ref{itemx, , @code{@@itemx}}.@refill
14462 Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
14463 and @copyright{}}.@refill
14466 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
14467 Formatter Commands}.
14469 @item @@thischapter
14470 @itemx @@thischaptername
14474 Only allowed in a heading or footing. Stands for the number and name of
14475 the current chapter (in the format `Chapter 1: Title'), the chapter name
14476 only, the filename, the current page number, and the title of the
14477 document, respectively. @xref{Custom Headings, , How to Make Your Own
14480 @item @@tieaccent@{@var{cc}@}
14481 Generate a tie-after accent over the next two characters @var{cc}, as in
14482 `@tieaccent{oo}'. @xref{Inserting Accents}.
14484 @item @@tindex @var{entry}
14485 Add @var{entry} to the index of data types. @xref{Index Entries, ,
14486 Defining the Entries of an Index}.@refill
14488 @item @@title @var{title}
14489 In a printed manual, set a title flush to the left-hand side of the
14490 page in a larger than normal font and underline it with a black rule.
14491 Not relevant to Info, which does not have title pages. @xref{title
14492 subtitle author, , The @code{@@title} @code{@@subtitle} and
14493 @code{@@author} Commands}.@refill
14496 @item @@titlefont@{@var{text}@}
14497 In a printed manual, print @var{text} in a larger than normal font.
14498 Not relevant to Info, which does not have title pages.
14499 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
14500 and @code{@@sp} Commands}.@refill
14504 Indicate to Texinfo the beginning of the title page. Write command on
14505 a line of its own. Pair with @code{@@end titlepage}. Nothing between
14506 @code{@@titlepage} and @code{@@end titlepage} appears in Info.
14507 @xref{titlepage, , @code{@@titlepage}}.@refill
14511 Insert the current date, in `1 Jan 1900' style. @xref{Custom
14512 Headings, , How to Make Your Own Headings}.@refill
14514 @item @@top @var{title}
14515 In a Texinfo file to be formatted with @code{makeinfo}, identify the
14516 topmost @code{@@node} line in the file, which must be written on the line
14517 immediately preceding the @code{@@top} command. Used for
14518 @code{makeinfo}'s node pointer insertion feature. The title is
14519 underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
14520 line normally should be enclosed by @code{@@ifinfo} and @code{@@end
14521 ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
14522 command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
14523 Pointer Creation, , Creating Pointers with @code{makeinfo}}.
14525 @item @@u@{@var{c}@}
14526 @itemx @@ubaraccent@{@var{c}@}
14527 @itemx @@udotaccent@{@var{c}@}
14528 Generate a breve, underbar, or underdot accent, respectively, over or
14529 under the character @var{c}, as in @u{o}, @ubaraccent{o},
14530 @udotaccent{o}. @xref{Inserting Accents}.
14532 @item @@unnumbered @var{title}
14533 In a printed manual, begin a chapter that appears without chapter
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 asterisks.
14536 @xref{unnumbered & appendix, , @code{@@unnumbered} and
14537 @code{@@appendix}}.@refill
14539 @item @@unnumberedsec @var{title}
14540 In a printed manual, begin a section that appears without section
14541 numbers of any kind. The title appears in the table of contents of a
14542 printed manual. In Info, the title is underlined with equal signs.
14543 @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
14545 @item @@unnumberedsubsec @var{title}
14546 In a printed manual, begin an unnumbered subsection within a
14547 chapter. The title appears in the table of contents of a printed
14548 manual. In Info, the title is underlined with hyphens.
14549 @xref{unnumberedsubsec appendixsubsec subheading, ,
14550 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
14551 @code{@@subheading}}.@refill
14553 @item @@unnumberedsubsubsec @var{title}
14554 In a printed manual, begin an unnumbered subsubsection within a
14555 chapter. The title appears in the table of contents of a printed
14556 manual. In Info, the title is underlined with periods.
14557 @xref{subsubsection, , The `subsub' Commands}.@refill
14559 @item @@uref@{@var{url}[, @var{displayed-text}@}
14560 Define a cross reference to an external uniform resource locator for the
14561 World Wide Web. @xref{url, , @code{@@url}}.@refill
14563 @item @@url@{@var{url}@}
14564 Indicate text that is a uniform resource locator for the World Wide
14565 Web. @xref{url, , @code{@@url}}.@refill
14567 @item @@v@{@var{c}@}
14568 Generate check accent over the character @var{c}, as in @v{o}.
14569 @xref{Inserting Accents}.
14571 @item @@value@{@var{flag}@}
14572 Replace @var{flag} with the value to which it is set by @code{@@set
14574 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14576 @item @@var@{@var{metasyntactic-variable}@}
14577 Highlight a metasyntactic variable, which is something that stands for
14578 another piece of text. @xref{var, , Indicating Metasyntactic
14582 @item @@vindex @var{entry}
14583 Add @var{entry} to the index of variables. @xref{Index Entries, ,
14584 Defining the Entries of an Index}.@refill
14587 @item @@vskip @var{amount}
14588 In a printed manual, insert whitespace so as to push text on the
14589 remainder of the page towards the bottom of the page. Used in
14590 formatting the copyright page with the argument @samp{0pt plus
14591 1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
14592 only in contexts ignored for Info. @xref{Copyright & Permissions, ,
14593 The Copyright Page and Printed Permissions}.@refill
14596 @item @@vtable @var{formatting-command}
14597 Begin a two-column table, using @code{@@item} for each entry.
14598 Automatically enter each of the items in the first column into the
14599 index of variables. Pair with @code{@@end vtable}. The same as
14600 @code{@@table}, except for indexing. @xref{ftable vtable, ,
14601 @code{@@ftable} and @code{@@vtable}}.@refill
14604 @item @@w@{@var{text}@}
14605 Prevent @var{text} from being split across two lines. Do not end a
14606 paragraph that uses @code{@@w} with an @code{@@refill} command.
14607 @xref{w, , @code{@@w}}.@refill
14610 @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14611 Make a reference that starts with `See' in a printed manual. Follow
14612 command with a punctuation mark. Only the first argument is
14613 mandatory. @xref{xref, , @code{@@xref}}.@refill
14617 @node Tips, Sample Texinfo File, Command List, Top
14618 @appendix Tips and Hints
14620 Here are some tips for writing Texinfo documentation:@refill
14627 Write in the present tense, not in the past or the future.
14630 Write actively! For example, write ``We recommend that @dots{}'' rather
14631 than ``It is recommended that @dots{}''.
14634 Use 70 or 72 as your fill column. Longer lines are hard to read.
14637 Include a copyright notice and copying permissions.
14640 @subsubheading Index, Index, Index!
14642 Write many index entries, in different ways.
14643 Readers like indices; they are helpful and convenient.
14645 Although it is easiest to write index entries as you write the body of
14646 the text, some people prefer to write entries afterwards. In either
14647 case, write an entry before the paragraph to which it applies. This
14648 way, an index entry points to the first page of a paragraph that is
14649 split across pages.
14651 Here are more hints we have found valuable:
14655 Write each index entry differently, so each entry refers to a different
14656 place in the document.
14659 Write index entries only where a topic is discussed significantly. For
14660 example, it is not useful to index ``debugging information'' in a
14661 chapter on reporting bugs. Someone who wants to know about debugging
14662 information will certainly not find it in that chapter.
14665 Consistently capitalize the first word of every concept index entry,
14666 or else consistently use lower case. Terse entries often call for
14667 lower case; longer entries for capitalization. Whichever case
14668 convention you use, please use one or the other consistently! Mixing
14669 the two styles looks bad.
14672 Always capitalize or use upper case for those words in an index for
14673 which this is proper, such as names of countries or acronyms. Always
14674 use the appropriate case for case-sensitive names, such as those in C or
14678 Write the indexing commands that refer to a whole section immediately
14679 after the section command, and write the indexing commands that refer to
14680 the paragraph before the paragraph.
14683 In the example that follows, a blank line comes after the index
14684 entry for ``Leaping'':
14688 @@section The Dog and the Fox
14689 @@cindex Jumping, in general
14692 @@cindex Dog, lazy, jumped over
14693 @@cindex Lazy dog jumped over
14694 @@cindex Fox, jumps over dog
14695 @@cindex Quick fox jumps over dog
14696 The quick brown fox jumps over the lazy dog.
14701 (Note that the example shows entries for the same concept that are
14702 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
14703 readers can look up the concept in different ways.)
14706 @subsubheading Blank Lines
14710 Insert a blank line between a sectioning command and the first following
14711 sentence or paragraph, or between the indexing commands associated with
14712 the sectioning command and the first following sentence or paragraph, as
14713 shown in the tip on indexing. Otherwise, a formatter may fold title and
14714 paragraph together.
14717 Always insert a blank line before an @code{@@table} command and after an
14718 @code{@@end table} command; but never insert a blank line after an
14719 @code{@@table} command or before an @code{@@end table} command.
14730 Jump over lazy dogs.
14735 Also jump over lazy dogs.
14741 On the other hand, @dots{}
14745 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
14746 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
14750 @subsubheading Complete Phrases
14752 Complete phrases are easier to read than @dots{}
14756 Write entries in an itemized list as complete sentences; or at least, as
14757 complete phrases. Incomplete expressions @dots{} awkward @dots{} like
14761 Write the prefatory sentence or phrase for a multi-item list or table as
14762 a complete expression. Do not write ``You can set:''; instead, write
14763 ``You can set these variables:''. The former expression sounds cut off.
14766 @subsubheading Editions, Dates and Versions
14768 Write the edition and version numbers and date in three places in every
14773 In the first @code{@@ifinfo} section, for people reading the Texinfo file.
14776 In the @code{@@titlepage} section, for people reading the printed manual.
14779 In the `Top' node, for people reading the Info file.
14783 Also, it helps to write a note before the first @code{@@ifinfo}
14784 section to explain what you are doing.
14793 @@c Specify the edition and version numbers and date
14794 @@c in *three* places:
14795 @@c 1. First ifinfo section 2. title page 3. top node
14796 @@c To find the locations, search for !!set
14801 @@c !!set edition, date, version
14802 This is Edition 4.03, January 1992,
14803 of the @@cite@{GDB Manual@} for GDB Version 4.3.
14809 ---or use @code{@@set} and @code{@@value}
14810 (@pxref{value Example, , @code{@@value} Example}).
14812 @subsubheading Definition Commands
14814 Definition commands are @code{@@deffn}, @code{@@defun},
14815 @code{@@defmac}, and the like, and enable you to write descriptions in
14816 a uniform format.@refill
14820 Write just one definition command for each entity you define with a
14821 definition command. The automatic indexing feature creates an index
14822 entry that leads the reader to the definition.
14825 Use @code{@@table} @dots{} @code{@@end table} in an appendix that
14826 contains a summary of functions, not @code{@@deffn} or other definition
14830 @subsubheading Capitalization
14834 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
14835 @samp{i} in upper case.
14838 Capitalize ``Info''; it is a name.
14841 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
14842 @samp{T} and @samp{X}. This command causes the formatters to
14843 typeset the name according to the wishes of Donald Knuth, who wrote
14847 @subsubheading Spaces
14849 Do not use spaces to format a Texinfo file, except inside of
14850 @code{@@example} @dots{} @code{@@end example} and similar commands.
14853 For example, @TeX{} fills the following:
14858 @@kbd@{M-x vc-next-action@}
14859 Perform the next logical operation
14860 on the version-controlled file
14861 corresponding to the current buffer.
14867 so it looks like this:
14872 @kbd{M-x vc-next-action}
14873 Perform the next logical operation on the version-controlled file
14874 corresponding to the current buffer.
14879 `C-x v' `M-x vc-next-action' Perform the next logical operation on the
14880 version-controlled file corresponding to the current buffer.
14885 In this case, the text should be formatted with
14886 @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
14888 @subsubheading @@code, @@samp, @@var, and @samp{---}
14892 Use @code{@@code} around Lisp symbols, including command names.
14896 The main function is @@code@{vc-next-action@}, @dots{}
14900 Avoid putting letters such as @samp{s} immediately after an
14901 @samp{@@code}. Such letters look bad.
14904 Use @code{@@var} around meta-variables. Do not write angle brackets
14908 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
14909 typesets these as a long dash and the Info formatters reduce three
14913 @subsubheading Periods Outside of Quotes
14915 Place periods and other punctuation marks @emph{outside} of quotations,
14916 unless the punctuation is part of the quotation. This practice goes
14917 against publishing conventions in the United States, but enables the
14918 reader to distinguish between the contents of the quotation and the
14921 For example, you should write the following sentence with the period
14922 outside the end quotation marks:
14925 Evidently, @samp{au} is an abbreviation for ``author''.
14929 since @samp{au} does @emph{not} serve as an abbreviation for
14930 @samp{author.} (with a period following the word).
14932 @subsubheading Introducing New Terms
14936 Introduce new terms so that a reader who does not know them can
14937 understand them from context; or write a definition for the term.
14939 For example, in the following, the terms ``check in'', ``register'' and
14940 ``delta'' are all appearing for the first time; the example sentence should be
14941 rewritten so they are understandable.
14944 The major function assists you in checking in a file to your
14945 version control system and registering successive sets of changes to
14950 Use the @code{@@dfn} command around a word being introduced, to indicate
14951 that the reader should not expect to know the meaning already, and
14952 should expect to learn the meaning from this passage.
14955 @subsubheading @@pxref
14957 @c !!! maybe include this in the tips on pxref
14959 By the way, it is okay to use pxref with something else in front of
14960 it within the parens, as long as the pxref is followed by the close
14961 paren, and the material inside the parens is not part of a larger
14962 sentence. Also, you can use xref inside parens as part of a complete
14963 sentence so long as you terminate the cross reference with punctuation.
14965 Absolutely never use @code{@@pxref} except in the special context for
14966 which it is designed: inside parentheses, with the closing parenthesis
14967 following immediately after the closing brace. One formatter
14968 automatically inserts closing punctuation and the other does not. This
14969 means that the output looks right both in printed output and in an Info
14970 file, but only when the command is used inside parentheses.
14972 @subsubheading Invoking from a Shell
14974 You can invoke programs such as Emacs, GCC, and @code{gawk} from a
14975 shell. The documentation for each program should contain a section that
14976 describes this. Unfortunately, if the node names and titles for these
14977 sections are all different, readers find it hard to search for the
14980 Name such sections with a phrase beginning with the word
14981 @w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way
14982 users can find the section easily.
14984 @subsubheading ANSI C Syntax
14986 When you use @code{@@example} to describe a C function's calling
14987 conventions, use the ANSI C syntax, like this:@refill
14990 void dld_init (char *@@var@{path@});
14994 And in the subsequent discussion, refer to the argument values by
14995 writing the same argument names, again highlighted with
14996 @code{@@var}.@refill
14999 Avoid the obsolete style that looks like this:@refill
15008 Also, it is best to avoid writing @code{#include} above the
15009 declaration just to indicate that the function is declared in a
15010 header file. The practice may give the misimpression that the
15011 @code{#include} belongs near the declaration of the function. Either
15012 state explicitly which header file holds the declaration or, better
15013 yet, name the header file used for a group of functions at the
15014 beginning of the section that describes the functions.@refill
15016 @subsubheading Bad Examples
15018 Here are several examples of bad writing to avoid:
15020 In this example, say, `` @dots{} you must @code{@@dfn}@{check
15021 in@} the new version.'' That flows better.
15024 When you are done editing the file, you must perform a
15025 @code{@@dfn}@{check in@}.
15028 In the following example, say, ``@dots{} makes a unified interface such as VC
15032 SCCS, RCS and other version-control systems all perform similar
15033 functions in broadly similar ways (it is this resemblance which makes
15034 a unified control mode like this possible).
15037 And in this example, you should specify what `it' refers to:
15040 If you are working with other people, it assists in coordinating
15041 everyone's changes so they do not step on each other.
15044 @subsubheading And Finally @dots{}
15048 Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
15049 sound in the name `Bach'. But pronounce Texinfo as in `speck':
15053 Write notes for yourself at the very end of a Texinfo file after the
15054 @code{@@bye}. None of the formatters process text after the
15055 @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
15056 @code{@@end ignore}.
15060 @node Sample Texinfo File, Sample Permissions, Tips, Top
15061 @appendix A Sample Texinfo File
15062 @cindex Sample Texinfo file, no comments
15064 Here is a complete, short sample Texinfo file, without any commentary.
15065 You can see this file, with comments, in the first chapter.
15066 @xref{Short Sample, , A Short Sample Texinfo File}.
15070 \input texinfo @@c -*-texinfo-*-
15071 @@c %**start of header
15072 @@setfilename sample.info
15073 @@settitle Sample Document
15074 @@c %**end of header
15076 @@setchapternewpage odd
15079 This is a short example of a complete Texinfo file.
15081 Copyright 1990 Free Software Foundation, Inc.
15086 @@comment The title is printed in a large font.
15087 @@center @@titlefont@{Sample Title@}
15089 @@c The following two commands start the copyright page.
15091 @@vskip 0pt plus 1filll
15092 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
15095 @@node Top, First Chapter, , (dir)
15096 @@comment node-name, next, previous, up
15099 * First Chapter:: The first chapter is the
15100 only chapter in this sample.
15101 * Concept Index:: This index has two entries.
15104 @@node First Chapter, Concept Index, Top, Top
15105 @@comment node-name, next, previous, up
15106 @@chapter First Chapter
15107 @@cindex Sample index entry
15109 This is the contents of the first chapter.
15110 @@cindex Another sample index entry
15112 Here is a numbered list.
15116 This is the first item.
15119 This is the second item.
15122 The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
15123 commands transform a Texinfo file such as this into
15124 an Info file; and @@TeX@{@} typesets it for a printed
15127 @@node Concept Index, , First Chapter, Top
15128 @@comment node-name, next, previous, up
15129 @@unnumbered Concept Index
15138 @node Sample Permissions, Include Files, Sample Texinfo File, Top
15139 @appendix Sample Permissions
15140 @cindex Permissions
15141 @cindex Copying permissions
15143 Texinfo files should contain sections that tell the readers that they
15144 have the right to copy and distribute the Texinfo file, the Info file,
15145 and the printed manual.@refill
15147 Also, if you are writing a manual about software, you should explain
15148 that the software is free and either include the GNU General Public
15149 License (GPL) or provide a reference to it. @xref{Distrib, ,
15150 Distribution, xemacs, XEmacs User's Manual}, for an example of the text
15151 that could be used in the software ``Distribution'', ``General Public
15152 License'', and ``NO WARRANTY'' sections of a document. @xref{Copying,
15153 , Texinfo Copying Conditions}, for an example of a brief explanation
15154 of how the copying conditions provide you with rights. @refill
15157 * Inserting Permissions:: How to put permissions in your document.
15158 * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions.
15159 * Titlepage Permissions:: Sample Titlepage copying permissions.
15162 @node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions
15164 @appendixsec Inserting Permissions
15167 In a Texinfo file, the first @code{@@ifinfo} section usually begins
15168 with a line that says what the file documents. This is what a person
15169 reading the unprocessed Texinfo file or using the advanced Info
15170 command @kbd{g *} sees first. @inforef{Expert, Advanced Info
15171 commands, info}, for more information. (A reader using the regular
15172 Info commands usually starts reading at the first node and skips
15173 this first section, which is not in a node.)@refill
15175 In the @code{@@ifinfo} section, the summary sentence is followed by a
15176 copyright notice and then by the copying permission notice. One of
15177 the copying permission paragraphs is enclosed in @code{@@ignore} and
15178 @code{@@end ignore} commands. This paragraph states that the Texinfo
15179 file can be processed through @TeX{} and printed, provided the printed
15180 manual carries the proper copying permission notice. This paragraph
15181 is not made part of the Info file since it is not relevant to the Info
15182 file; but it is a mandatory part of the Texinfo file since it permits
15183 people to process the Texinfo file in @TeX{} and print the
15186 In the printed manual, the Free Software Foundation copying permission
15187 notice follows the copyright notice and publishing information and is
15188 located within the region delineated by the @code{@@titlepage} and
15189 @code{@@end titlepage} commands. The copying permission notice is exactly
15190 the same as the notice in the @code{@@ifinfo} section except that the
15191 paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
15192 not part of the notice.@refill
15194 To make it simple to insert a permission notice into each section of
15195 the Texinfo file, sample permission notices for each section are
15196 reproduced in full below.@refill
15198 Note that you may need to specify the correct name of a section
15199 mentioned in the permission notice. For example, in @cite{The GDB
15200 Manual}, the name of the section referring to the General Public
15201 License is called the ``GDB General Public License'', but in the
15202 sample shown below, that section is referred to generically as the
15203 ``GNU General Public License''. If the Texinfo file does not carry a
15204 copy of the General Public License, leave out the reference to it, but
15205 be sure to include the rest of the sentence.@refill
15207 @node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions
15208 @comment node-name, next, previous, up
15209 @appendixsec @samp{ifinfo} Copying Permissions
15210 @cindex @samp{ifinfo} permissions
15212 In the @code{@@ifinfo} section of a Texinfo file, the standard Free
15213 Software Foundation permission notice reads as follows:@refill
15216 This file documents @dots{}
15218 Copyright 1998 Free Software Foundation, Inc.
15220 Permission is granted to make and distribute verbatim
15221 copies of this manual provided the copyright notice and
15222 this permission notice are preserved on all copies.
15225 Permission is granted to process this file through TeX
15226 and print the results, provided the printed document
15227 carries a copying permission notice identical to this
15228 one except for the removal of this paragraph (this
15229 paragraph not being relevant to the printed manual).
15232 Permission is granted to copy and distribute modified
15233 versions of this manual under the conditions for
15234 verbatim copying, provided also that the sections
15235 entitled ``Copying'' and ``GNU General Public License''
15236 are included exactly as in the original, and provided
15237 that the entire resulting derived work is distributed
15238 under the terms of a permission notice identical to this
15241 Permission is granted to copy and distribute
15242 translations of this manual into another language,
15243 under the above conditions for modified versions,
15244 except that this permission notice may be stated in a
15245 translation approved by the Free Software Foundation.
15248 @node Titlepage Permissions, , ifinfo Permissions, Sample Permissions
15249 @comment node-name, next, previous, up
15250 @appendixsec Titlepage Copying Permissions
15251 @cindex Titlepage permissions
15253 In the @code{@@titlepage} section of a Texinfo file, the standard Free
15254 Software Foundation copying permission notice follows the copyright
15255 notice and publishing information. The standard phrasing is as
15259 Permission is granted to make and distribute verbatim
15260 copies of this manual provided the copyright notice and
15261 this permission notice are preserved on all copies.
15263 Permission is granted to copy and distribute modified
15264 versions of this manual under the conditions for
15265 verbatim copying, provided also that the sections
15266 entitled ``Copying'' and ``GNU General Public License''
15267 are included exactly as in the original, and provided
15268 that the entire resulting derived work is distributed
15269 under the terms of a permission notice identical to this
15272 Permission is granted to copy and distribute
15273 translations of this manual into another language,
15274 under the above conditions for modified versions,
15275 except that this permission notice may be stated in a
15276 translation approved by the Free Software Foundation.
15280 @node Include Files, Headings, Sample Permissions, Top
15281 @appendix Include Files
15282 @cindex Include files
15284 When @TeX{} or an Info formatting command sees an @code{@@include}
15285 command in a Texinfo file, it processes the contents of the file named
15286 by the command and incorporates them into the DVI or Info file being
15287 created. Index entries from the included file are incorporated into
15288 the indices of the output file.@refill
15290 Include files let you keep a single large document as a collection of
15291 conveniently small parts.@refill
15294 * Using Include Files:: How to use the @code{@@include} command.
15295 * texinfo-multiple-files-update:: How to create and update nodes and
15296 menus when using included files.
15297 * Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
15298 * Sample Include File:: A sample outer file with included files
15299 within it; and a sample included file.
15300 * Include Files Evolution:: How use of the @code{@@include} command
15301 has changed over time.
15304 @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
15305 @appendixsec How to Use Include Files
15308 To include another file within a Texinfo file, write the
15309 @code{@@include} command at the beginning of a line and follow it on
15310 the same line by the name of a file to be included. For
15314 @@include buffers.texi
15317 An included file should simply be a segment of text that you expect to
15318 be included as is into the overall or @dfn{outer} Texinfo file; it
15319 should not contain the standard beginning and end parts of a Texinfo
15320 file. In particular, you should not start an included file with a
15321 line saying @samp{\input texinfo}; if you do, that phrase is inserted
15322 into the output file as is. Likewise, you should not end an included
15323 file with an @code{@@bye} command; nothing after @code{@@bye} is
15326 In the past, you were required to write an @code{@@setfilename} line at the
15327 beginning of an included file, but no longer. Now, it does not matter
15328 whether you write such a line. If an @code{@@setfilename} line exists
15329 in an included file, it is ignored.@refill
15331 Conventionally, an included file begins with an @code{@@node} line that
15332 is followed by an @code{@@chapter} line. Each included file is one
15333 chapter. This makes it easy to use the regular node and menu creating
15334 and updating commands to create the node pointers and menus within the
15335 included file. However, the simple Emacs node and menu creating and
15336 updating commands do not work with multiple Texinfo files. Thus you
15337 cannot use these commands to fill in the `Next', `Previous', and `Up'
15338 pointers of the @code{@@node} line that begins the included file. Also,
15339 you cannot use the regular commands to create a master menu for the
15340 whole file. Either you must insert the menus and the `Next',
15341 `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
15342 Texinfo mode command, @code{texinfo-multiple-files-update}, that is
15343 designed for @code{@@include} files.@refill
15345 @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
15346 @appendixsec @code{texinfo-multiple-files-update}
15347 @findex texinfo-multiple-files-update
15349 GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
15350 command. This command creates or updates `Next', `Previous', and `Up'
15351 pointers of included files as well as those in the outer or overall
15352 Texinfo file, and it creates or updates a main menu in the outer file.
15353 Depending whether you call it with optional arguments, the command
15354 updates only the pointers in the first @code{@@node} line of the
15355 included files or all of them:@refill
15358 @item M-x texinfo-multiple-files-update
15359 Called without any arguments:@refill
15363 Create or update the `Next', `Previous', and `Up' pointers of the
15364 first @code{@@node} line in each file included in an outer or overall
15365 Texinfo file.@refill
15368 Create or update the `Top' level node pointers of the outer or
15369 overall file.@refill
15372 Create or update a main menu in the outer file.@refill
15375 @item C-u M-x texinfo-multiple-files-update
15376 Called with @kbd{C-u} as a prefix argument:
15380 Create or update pointers in the first @code{@@node} line in each
15384 Create or update the `Top' level node pointers of the outer file.
15387 Create and insert a master menu in the outer file. The master menu
15388 is made from all the menus in all the included files.@refill
15391 @item C-u 8 M-x texinfo-multiple-files-update
15392 Called with a numeric prefix argument, such as @kbd{C-u 8}:
15396 Create or update @strong{all} the `Next', `Previous', and `Up' pointers
15397 of all the included files.@refill
15400 Create or update @strong{all} the menus of all the included
15404 Create or update the `Top' level node pointers of the outer or
15405 overall file.@refill
15408 And then create a master menu in the outer file. This is similar to
15409 invoking @code{texinfo-master-menu} with an argument when you are
15410 working with just one file.@refill
15414 Note the use of the prefix argument in interactive use: with a regular
15415 prefix argument, just @w{@kbd{C-u}}, the
15416 @code{texinfo-multiple-files-update} command inserts a master menu;
15417 with a numeric prefix argument, such as @kbd{C-u 8}, the command
15418 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
15419 master menu.@refill
15421 @node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files
15422 @appendixsec Include File Requirements
15423 @cindex Include file requirements
15424 @cindex Requirements for include files
15426 If you plan to use the @code{texinfo-multiple-files-update} command,
15427 the outer Texinfo file that lists included files within it should
15428 contain nothing but the beginning and end parts of a Texinfo file, and
15429 a number of @code{@@include} commands listing the included files. It
15430 should not even include indices, which should be listed in an included
15431 file of their own.@refill
15433 Moreover, each of the included files must contain exactly one highest
15434 level node (conventionally, @code{@@chapter} or equivalent),
15435 and this node must be the first node in the included file.
15436 Furthermore, each of these highest level nodes in each included file
15437 must be at the same hierarchical level in the file structure.
15438 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
15439 @code{@@unnumbered} node. Thus, normally, each included file contains
15440 one, and only one, chapter or equivalent-level node.@refill
15442 The outer file should contain only @emph{one} node, the `Top' node. It
15443 should @emph{not} contain any nodes besides the single `Top' node. The
15444 @code{texinfo-multiple-files-update} command will not process
15447 @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
15448 @appendixsec Sample File with @code{@@include}
15449 @cindex Sample @code{@@include} file
15450 @cindex Include file sample
15451 @cindex @code{@@include} file sample
15453 Here is an example of a complete outer Texinfo file with @code{@@include} files
15454 within it before running @code{texinfo-multiple-files-update}, which
15455 would insert a main or master menu:@refill
15459 \input texinfo @@c -*-texinfo-*-
15460 @c %**start of header
15461 @@setfilename include-example.info
15462 @@settitle Include Example
15463 @c %**end of header
15467 @@setchapternewpage odd
15470 @@center @@titlefont@{Include Example@}
15472 @@center by Whom Ever
15477 @@vskip 0pt plus 1filll
15478 Copyright @@copyright@{@} 1998 Free Software Foundation, Inc.
15484 @@node Top, First, , (dir)
15490 @@include foo.texinfo
15491 @@include bar.texinfo
15492 @@include concept-index.texinfo
15503 An included file, such as @file{foo.texinfo}, might look like
15508 @@node First, Second, , Top
15509 @@chapter First Chapter
15511 Contents of first chapter @dots{}
15515 The full contents of @file{concept-index.texinfo} might be as simple as this:
15519 @@node Concept Index, , Second, Top
15520 @@unnumbered Concept Index
15526 The outer Texinfo source file for @cite{The XEmacs Lisp Reference
15527 Manual} is named @file{elisp.texi}. This outer file contains a master
15528 menu with 417 entries and a list of 41 @code{@@include}
15531 @node Include Files Evolution, , Sample Include File, Include Files
15532 @comment node-name, next, previous, up
15533 @appendixsec Evolution of Include Files
15535 When Info was first created, it was customary to create many small
15536 Info files on one subject. Each Info file was formatted from its own
15537 Texinfo source file. This custom meant that Emacs did not need to
15538 make a large buffer to hold the whole of a large Info file when
15539 someone wanted information; instead, Emacs allocated just enough
15540 memory for the small Info file that contained the particular
15541 information sought. This way, Emacs could avoid wasting memory.@refill
15543 References from one file to another were made by referring to the file
15544 name as well as the node name. (@xref{Other Info Files, , Referring to
15545 Other Info Files}. Also, see @ref{Four and Five Arguments, ,
15546 @code{@@xref} with Four and Five Arguments}.)@refill
15548 Include files were designed primarily as a way to create a single,
15549 large printed manual out of several smaller Info files. In a printed
15550 manual, all the references were within the same document, so @TeX{}
15551 could automatically determine the references' page numbers. The Info
15552 formatting commands used include files only for creating joint
15553 indices; each of the individual Texinfo files had to be formatted for
15554 Info individually. (Each, therefore, required its own
15555 @code{@@setfilename} line.)@refill
15557 However, because large Info files are now split automatically, it is
15558 no longer necessary to keep them small.@refill
15560 Nowadays, multiple Texinfo files are used mostly for large documents,
15561 such as @cite{The XEmacs Lisp Reference Manual}, and for projects
15562 in which several different people write different sections of a
15563 document simultaneously.@refill
15565 In addition, the Info formatting commands have been extended to work
15566 with the @code{@@include} command so as to create a single large Info
15567 file that is split into smaller files if necessary. This means that
15568 you can write menus and cross references without naming the different
15569 Texinfo files.@refill
15572 @node Headings, Catching Mistakes, Include Files, Top
15573 @appendix Page Headings
15576 @cindex Page numbering
15577 @cindex Page headings
15578 @cindex Formatting headings and footings
15580 Most printed manuals contain headings along the top of every page
15581 except the title and copyright pages. Some manuals also contain
15582 footings. (Headings and footings have no meaning to Info, which is
15583 not paginated.)@refill
15586 * Headings Introduced:: Conventions for using page headings.
15587 * Heading Format:: Standard page heading formats.
15588 * Heading Choice:: How to specify the type of page heading.
15589 * Custom Headings:: How to create your own headings and footings.
15592 @node Headings Introduced, Heading Format, Headings, Headings
15594 @heading Headings Introduced
15597 Texinfo provides standard page heading formats for manuals that are
15598 printed on one side of each sheet of paper and for manuals that are
15599 printed on both sides of the paper. Typically, you will use these
15600 formats, but you can specify your own format if you wish.@refill
15602 In addition, you can specify whether chapters should begin on a new
15603 page, or merely continue the same page as the previous chapter; and if
15604 chapters begin on new pages, you can specify whether they must be
15605 odd-numbered pages.@refill
15607 By convention, a book is printed on both sides of each sheet of paper.
15608 When you open a book, the right-hand page is odd-numbered, and
15609 chapters begin on right-hand pages---a preceding left-hand page is
15610 left blank if necessary. Reports, however, are often printed on just
15611 one side of paper, and chapters begin on a fresh page immediately
15612 following the end of the preceding chapter. In short or informal
15613 reports, chapters often do not begin on a new page at all, but are
15614 separated from the preceding text by a small amount of whitespace.@refill
15616 The @code{@@setchapternewpage} command controls whether chapters begin
15617 on new pages, and whether one of the standard heading formats is used.
15618 In addition, Texinfo has several heading and footing commands that you
15619 can use to generate your own heading and footing formats.@refill
15621 In Texinfo, headings and footings are single lines at the tops and
15622 bottoms of pages; you cannot create multiline headings or footings.
15623 Each header or footer line is divided into three parts: a left part, a
15624 middle part, and a right part. Any part, or a whole line, may be left
15625 blank. Text for the left part of a header or footer line is set
15626 flushleft; text for the middle part is centered; and, text for the
15627 right part is set flushright.@refill
15629 @node Heading Format, Heading Choice, Headings Introduced, Headings
15630 @comment node-name, next, previous, up
15631 @appendixsec Standard Heading Formats
15633 Texinfo provides two standard heading formats, one for manuals printed
15634 on one side of each sheet of paper, and the other for manuals printed
15635 on both sides of the paper.
15637 By default, nothing is specified for the footing of a Texinfo file,
15638 so the footing remains blank.@refill
15640 The standard format for single-sided printing consists of a header
15641 line in which the left-hand part contains the name of the chapter, the
15642 central part is blank, and the right-hand part contains the page
15646 A single-sided page looks like this:
15650 _______________________
15652 | chapter page number |
15654 | Start of text ... |
15661 The standard format for two-sided printing depends on whether the page
15662 number is even or odd. By convention, even-numbered pages are on the
15663 left- and odd-numbered pages are on the right. (@TeX{} will adjust the
15664 widths of the left- and right-hand margins. Usually, widths are
15665 correct, but during double-sided printing, it is wise to check that
15666 pages will bind properly---sometimes a printer will produce output in
15667 which the even-numbered pages have a larger right-hand margin than the
15668 odd-numbered pages.)@refill
15670 In the standard double-sided format, the left part of the left-hand
15671 (even-numbered) page contains the page number, the central part is
15672 blank, and the right part contains the title (specified by the
15673 @code{@@settitle} command). The left part of the right-hand
15674 (odd-numbered) page contains the name of the chapter, the central part
15675 is blank, and the right part contains the page number.@refill
15678 Two pages, side by side as in an open book, look like this:@refill
15682 _______________________ _______________________
15684 | page number title | | chapter page number |
15686 | Start of text ... | | More text ... |
15694 The chapter name is preceded by the word ``Chapter'', the chapter number
15695 and a colon. This makes it easier to keep track of where you are in the
15698 @node Heading Choice, Custom Headings, Heading Format, Headings
15699 @comment node-name, next, previous, up
15700 @appendixsec Specifying the Type of Heading
15702 @TeX{} does not begin to generate page headings for a standard Texinfo
15703 file until it reaches the @code{@@end titlepage} command. Thus, the
15704 title and copyright pages are not numbered. The @code{@@end
15705 titlepage} command causes @TeX{} to begin to generate page headings
15706 according to a standard format specified by the
15707 @code{@@setchapternewpage} command that precedes the
15708 @code{@@titlepage} section.@refill
15711 There are four possibilities:@refill
15714 @item No @code{@@setchapternewpage} command
15715 Cause @TeX{} to specify the single-sided heading format, with chapters
15716 on new pages. This is the same as @code{@@setchapternewpage on}.@refill
15718 @item @code{@@setchapternewpage on}
15719 Specify the single-sided heading format, with chapters on new pages.@refill
15721 @item @code{@@setchapternewpage off}
15722 Cause @TeX{} to start a new chapter on the same page as the last page of
15723 the preceding chapter, after skipping some vertical whitespace. Also
15724 cause @TeX{} to typeset for single-sided printing. (You can override
15725 the headers format with the @code{@@headings double} command; see
15726 @ref{headings on off, , The @code{@@headings} Command}.)@refill
15728 @item @code{@@setchapternewpage odd}
15729 Specify the double-sided heading format, with chapters on new pages.@refill
15733 Texinfo lacks an @code{@@setchapternewpage even} command.@refill
15735 @node Custom Headings, , Heading Choice, Headings
15736 @comment node-name, next, previous, up
15737 @appendixsec How to Make Your Own Headings
15739 You can use the standard headings provided with Texinfo or specify
15740 your own. By default, Texinfo has no footers, so if you specify them,
15741 the available page size for the main text will be slightly reduced.
15743 @c Following paragraph is verbose to prevent overfull hboxes.
15744 Texinfo provides six commands for specifying headings and
15745 footings. The @code{@@everyheading} command and
15746 @code{@@everyfooting} command generate page headers and footers
15747 that are the same for both even- and odd-numbered pages.
15748 The @code{@@evenheading} command and @code{@@evenfooting}
15749 command generate headers and footers for even-numbered
15750 (left-hand) pages; and the @code{@@oddheading} command and
15751 @code{@@oddfooting} command generate headers and footers for
15752 odd-numbered (right-hand) pages.@refill
15754 Write custom heading specifications in the Texinfo file immediately
15755 after the @code{@@end titlepage} command. Enclose your specifications
15756 between @code{@@iftex} and @code{@@end iftex} commands since the
15757 @code{texinfo-format-buffer} command may not recognize them. Also,
15758 you must cancel the predefined heading commands with the
15759 @code{@@headings off} command before defining your own
15760 specifications.@refill
15763 Here is how to tell @TeX{} to place the chapter name at the left, the
15764 page number in the center, and the date at the right of every header
15765 for both even- and odd-numbered pages:@refill
15771 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
15777 You need to divide the left part from the central part and the central
15778 part from the right part by inserting @samp{@@|} between parts.
15779 Otherwise, the specification command will not be able to tell where
15780 the text for one part ends and the next part begins.@refill
15782 Each part can contain text or @@-commands. The text
15783 is printed as if the part were within an ordinary paragraph in the
15784 body of the page. The @@-commands replace
15785 themselves with the page number, date, chapter name, or
15789 Here are the six heading and footing commands:@refill
15791 @findex everyheading
15792 @findex everyfooting
15794 @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
15795 @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
15797 The `every' commands specify the format for both even- and odd-numbered
15798 pages. These commands are for documents that are printed on one side
15799 of each sheet of paper, or for documents in which you want symmetrical
15800 headers or footers.@refill
15802 @findex evenheading
15803 @findex evenfooting
15806 @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
15807 @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
15809 @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
15810 @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
15812 The `even' and `odd' commands specify the format for even-numbered
15813 pages and odd-numbered pages. These commands are for books and
15814 manuals that are printed on both sides of each sheet of paper.
15817 Use the @samp{@@this@dots{}} series of @@-commands to
15818 provide the names of chapters
15819 and sections and the page number. You can use the
15820 @samp{@@this@dots{}} commands in the left, center, or right portions
15821 of headers and footers, or anywhere else in a Texinfo file so long as
15822 they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
15825 Here are the @samp{@@this@dots{}} commands:@refill
15830 Expands to the current page number.@refill
15831 @c !!! Karl Berry says that `thissection' can fail on page breaks.
15833 @item @@thissection
15834 Expands to the name of the current section.@refill
15837 @findex thischaptername
15838 @item @@thischaptername
15839 Expands to the name of the current chapter.@refill
15841 @findex thischapter
15842 @item @@thischapter
15843 Expands to the number and name of the current
15844 chapter, in the format `Chapter 1: Title'.@refill
15848 Expands to the name of the document, as specified by the
15849 @code{@@settitle} command.@refill
15853 For @code{@@include} files only: expands to the name of the current
15854 @code{@@include} file. If the current Texinfo source file is not an
15855 @code{@@include} file, this command has no effect. This command does
15856 @emph{not} provide the name of the current Texinfo source file unless
15857 it is an @code{@@include} file. (@xref{Include Files}, for more
15858 information about @code{@@include} files.)@refill
15862 You can also use the @code{@@today@{@}} command, which expands to the
15863 current date, in `1 Jan 1900' format.@refill
15866 Other @@-commands and text are printed in a header or footer just as
15867 if they were in the body of a page. It is useful to incorporate text,
15868 particularly when you are writing drafts:@refill
15874 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
15875 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
15880 Beware of overlong titles: they may overlap another part of the
15881 header or footer and blot it out.@refill
15884 @node Catching Mistakes, Refilling Paragraphs, Headings, Top
15885 @appendix Formatting Mistakes
15886 @cindex Structure, catching mistakes in
15887 @cindex Nodes, catching mistakes
15888 @cindex Catching mistakes
15889 @cindex Correcting mistakes
15890 @cindex Mistakes, catching
15891 @cindex Problems, catching
15892 @cindex Debugging the Texinfo structure
15894 Besides mistakes in the content of your documentation, there
15895 are two kinds of mistake you can make with Texinfo: you can make mistakes
15896 with @@-commands, and you can make mistakes with the structure of the
15897 nodes and chapters.@refill
15899 Emacs has two tools for catching the @@-command mistakes and two for
15900 catching structuring mistakes.@refill
15902 For finding problems with @@-commands, you can run @TeX{} or a region
15903 formatting command on the region that has a problem; indeed, you can
15904 run these commands on each region as you write it.@refill
15906 For finding problems with the structure of nodes and chapters, you can use
15907 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
15908 command and you can use the @kbd{M-x Info-validate} command.@refill
15911 * makeinfo Preferred:: @code{makeinfo} finds errors.
15912 * Debugging with Info:: How to catch errors with Info formatting.
15913 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
15914 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
15915 * Using occur:: How to list all lines containing a pattern.
15916 * Running Info-Validate:: How to find badly referenced nodes.
15919 @node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
15921 @heading @code{makeinfo} Find Errors
15924 The @code{makeinfo} program does an excellent job of catching errors
15925 and reporting them---far better than @code{texinfo-format-region} or
15926 @code{texinfo-format-buffer}. In addition, the various functions for
15927 automatically creating and updating node pointers and menus remove
15928 many opportunities for human error.@refill
15930 If you can, use the updating commands to create and insert pointers
15931 and menus. These prevent many errors. Then use @code{makeinfo} (or
15932 its Texinfo mode manifestations, @code{makeinfo-region} and
15933 @code{makeinfo-buffer}) to format your file and check for other
15934 errors. This is the best way to work with Texinfo. But if you
15935 cannot use @code{makeinfo}, or your problem is very puzzling, then you
15936 may want to use the tools described in this appendix.@refill
15938 @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
15939 @comment node-name, next, previous, up
15940 @appendixsec Catching Errors with Info Formatting
15941 @cindex Catching errors with Info formatting
15942 @cindex Debugging with Info formatting
15944 After you have written part of a Texinfo file, you can use the
15945 @code{texinfo-format-region} or the @code{makeinfo-region} command to
15946 see whether the region formats properly.@refill
15948 Most likely, however, you are reading this section because for some
15949 reason you cannot use the @code{makeinfo-region} command; therefore, the
15950 rest of this section presumes that you are using
15951 @code{texinfo-format-region}.@refill
15953 If you have made a mistake with an @@-command,
15954 @code{texinfo-format-region} will stop processing at or after the
15955 error and display an error message. To see where in the buffer the
15956 error occurred, switch to the @samp{*Info Region*} buffer; the cursor
15957 will be in a position that is after the location of the error. Also,
15958 the text will not be formatted after the place where the error
15959 occurred (or more precisely, where it was detected).@refill
15961 For example, if you accidentally end a menu with the command @code{@@end
15962 menus} with an `s' on the end, instead of with @code{@@end menu}, you
15963 will see an error message that says:@refill
15966 @@end menus is not handled by texinfo
15970 The cursor will stop at the point in the buffer where the error
15971 occurs, or not long after it. The buffer will look like this:@refill
15975 ---------- Buffer: *Info Region* ----------
15978 * Using texinfo-show-structure:: How to use
15979 `texinfo-show-structure'
15981 * Running Info-Validate:: How to check for
15982 unreferenced nodes.
15985 ---------- Buffer: *Info Region* ----------
15989 The @code{texinfo-format-region} command sometimes provides slightly
15990 odd error messages. For example, the following cross reference fails to format:@refill
15993 (@@xref@{Catching Mistakes, for more info.)
15997 In this case, @code{texinfo-format-region} detects the missing closing
15998 brace but displays a message that says @samp{Unbalanced parentheses}
15999 rather than @samp{Unbalanced braces}. This is because the formatting
16000 command looks for mismatches between braces as if they were
16001 parentheses.@refill
16003 Sometimes @code{texinfo-format-region} fails to detect mistakes. For
16004 example, in the following, the closing brace is swapped with the
16005 closing parenthesis:@refill
16008 (@@xref@{Catching Mistakes), for more info.@}
16012 Formatting produces:
16014 (*Note for more info.: Catching Mistakes)
16017 The only way for you to detect this error is to realize that the
16018 reference should have looked like this:@refill
16021 (*Note Catching Mistakes::, for more info.)
16024 Incidentally, if you are reading this node in Info and type @kbd{f
16025 @key{RET}} (@code{Info-follow-reference}), you will generate an error
16029 No such node: "Catching Mistakes) The only way @dots{}
16033 This is because Info perceives the example of the error as the first
16034 cross reference in this node and if you type a @key{RET} immediately
16035 after typing the Info @kbd{f} command, Info will attempt to go to the
16036 referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
16037 will complete the node name of the correctly written example and take
16038 you to the `Catching Mistakes' node. (If you try this, you can return
16039 from the `Catching Mistakes' node by typing @kbd{l}
16040 (@code{Info-last}).)
16042 @c !!! section on using Elisp debugger ignored.
16044 Sometimes @code{texinfo-format-region} will stop long after the
16045 original error; this is because it does not discover the problem until
16046 then. In this case, you will need to backtrack.@refill
16049 @c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
16052 @c node Using the Emacs Lisp Debugger
16053 @c appendixsubsec Using the Emacs Lisp Debugger
16054 @c index Using the Emacs Lisp debugger
16055 @c index Emacs Lisp debugger
16056 @c index Debugger, using the Emacs Lisp
16058 If an error is especially elusive, you can turn on the Emacs Lisp
16059 debugger and look at the backtrace; this tells you where in the
16060 @code{texinfo-format-region} function the problem occurred. You can
16061 turn on the debugger with the command:@refill
16064 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
16068 and turn it off with
16071 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
16074 Often, when you are using the debugger, it is easier to follow what is
16075 going on if you use the Emacs Lisp files that are not byte-compiled.
16076 The byte-compiled sources send octal numbers to the debugger that may
16077 look mysterious. To use the uncompiled source files, load
16078 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
16081 The debugger will not catch an error if @code{texinfo-format-region}
16082 does not detect one. In the example shown above,
16083 @code{texinfo-format-region} did not find the error when the whole
16084 list was formatted, but only when part of the list was formatted.
16085 When @code{texinfo-format-region} did not find an error, the debugger
16086 did not find one either. @refill
16088 However, when @code{texinfo-format-region} did report an error, it
16089 invoked the debugger. This is the backtrace it produced:@refill
16092 ---------- Buffer: *Backtrace* ----------
16093 Signalling: (search-failed "[@},]")
16094 re-search-forward("[@},]")
16097 texinfo-format-parse-args()
16099 texinfo-format-xref()
16100 funcall(texinfo-format-xref)
16105 texinfo-format-scan()
16106 (save-excursion ...)
16108 texinfo-format-region(103370 103631)
16109 * call-interactively(texinfo-format-region)
16110 ---------- Buffer: *Backtrace* ----------
16113 The backtrace is read from the bottom up.
16114 @code{texinfo-format-region} was called interactively; and it, in
16115 turn, called various functions, including @code{texinfo-format-scan},
16116 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
16117 Inside the function @code{texinfo-format-parse-args}, the function
16118 @code{re-search-forward} was called; it was this function that could
16119 not find the missing right-hand brace.@refill
16121 @xref{Lisp Debug, , Debugging Emacs Lisp, xemacs, XEmacs User's Manual},
16122 for more information.@refill
16125 @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
16126 @comment node-name, next, previous, up
16127 @appendixsec Catching Errors with @TeX{} Formatting
16128 @cindex Catching errors with @TeX{} formatting
16129 @cindex Debugging with @TeX{} formatting
16131 You can also catch mistakes when you format a file with @TeX{}.@refill
16133 Usually, you will want to do this after you have run
16134 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
16135 the same file, because @code{texinfo-format-buffer} sometimes displays
16136 error messages that make more sense than @TeX{}. (@xref{Debugging
16137 with Info}, for more information.)@refill
16139 For example, @TeX{} was run on a Texinfo file, part of which is shown
16143 ---------- Buffer: texinfo.texi ----------
16144 name of the Texinfo file as an extension. The
16145 @@samp@{??@} are `wildcards' that cause the shell to
16146 substitute all the raw index files. (@@xref@{sorting
16147 indices, for more information about sorting
16149 ---------- Buffer: texinfo.texi ----------
16153 (The cross reference lacks a closing brace.)
16154 @TeX{} produced the following output, after which it stopped:@refill
16157 ---------- Buffer: *tex-shell* ----------
16159 @{sorting indices, for more information about sorting
16160 indices.) @@refill @@ETC.
16161 ! Paragraph ended before @@xref was complete.
16167 ---------- Buffer: *tex-shell* ----------
16170 In this case, @TeX{} produced an accurate and
16171 understandable error message:
16174 Paragraph ended before @@xref was complete.
16178 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
16179 @samp{l.27} means that @TeX{} detected the problem on line 27 of the
16180 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
16181 circumstance.@refill
16183 Unfortunately, @TeX{} is not always so helpful, and sometimes you must
16184 truly be a Sherlock Holmes to discover what went wrong.@refill
16186 In any case, if you run into a problem like this, you can do one of three
16191 You can tell @TeX{} to continue running and ignore just this error by
16192 typing @key{RET} at the @samp{?} prompt.@refill
16195 You can tell @TeX{} to continue running and to ignore all errors as best
16196 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
16198 This is often the best thing to do. However, beware: the one error
16199 may produce a cascade of additional error messages as its consequences
16200 are felt through the rest of the file. To stop @TeX{} when it is
16201 producing such an avalanche of error messages, type @kbd{C-c} (or
16202 @kbd{C-c C-c}, if you are running a shell inside Emacs).
16205 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
16206 at the @samp{?} prompt.@refill
16209 Please note that if you are running @TeX{} inside Emacs, you need to
16210 switch to the shell buffer and line at which @TeX{} offers the @samp{?}
16213 Sometimes @TeX{} will format a file without producing error messages even
16214 though there is a problem. This usually occurs if a command is not ended
16215 but @TeX{} is able to continue processing anyhow. For example, if you fail
16216 to end an itemized list with the @code{@@end itemize} command, @TeX{} will
16217 write a DVI file that you can print out. The only error message that
16218 @TeX{} will give you is the somewhat mysterious comment that@refill
16221 (@@end occurred inside a group at level 1)
16225 However, if you print the DVI file, you will find that the text
16226 of the file that follows the itemized list is entirely indented as if
16227 it were part of the last item in the itemized list. The error message
16228 is the way @TeX{} says that it expected to find an @code{@@end}
16229 command somewhere in the file; but that it could not determine where
16230 it was needed.@refill
16232 Another source of notoriously hard-to-find errors is a missing
16233 @code{@@end group} command. If you ever are stumped by
16234 incomprehensible errors, look for a missing @code{@@end group} command
16237 If the Texinfo file lacks header lines,
16238 @TeX{} may stop in the
16239 beginning of its run and display output that looks like the following.
16240 The @samp{*} indicates that @TeX{} is waiting for input.@refill
16243 This is TeX, Version 3.14159 (Web2c 7.0)
16249 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
16250 write the header lines in the Texinfo file and run the @TeX{} command
16251 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
16252 instead of @samp{@@}; and in this circumstance, you are working
16253 directly with @TeX{}, not with Texinfo.)@refill
16255 @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
16256 @comment node-name, next, previous, up
16257 @appendixsec Using @code{texinfo-show-structure}
16258 @cindex Showing the structure of a file
16259 @findex texinfo-show-structure
16261 It is not always easy to keep track of the nodes, chapters, sections, and
16262 subsections of a Texinfo file. This is especially true if you are revising
16263 or adding to a Texinfo file that someone else has written.@refill
16265 In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
16266 command lists all the lines that begin with the @@-commands that
16267 specify the structure: @code{@@chapter}, @code{@@section},
16268 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
16269 as prefix argument, if interactive),
16270 the command also shows the @code{@@node} lines. The
16271 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
16272 Texinfo mode, by default.@refill
16274 The lines are displayed in a buffer called the @samp{*Occur*} buffer,
16275 indented by hierarchical level. For example, here is a part of what was
16276 produced by running @code{texinfo-show-structure} on this manual:@refill
16280 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
16281 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
16282 in buffer texinfo.texi.
16284 4177:@@chapter Nodes
16285 4198: @@heading Two Paths
16286 4231: @@section Node and Menu Illustration
16287 4337: @@section The @@code@{@@@@node@} Command
16288 4393: @@subheading Choosing Node and Pointer Names
16289 4417: @@subsection How to Write an @@code@{@@@@node@} Line
16290 4469: @@subsection @@code@{@@@@node@} Line Tips
16295 This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
16296 with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
16297 commands respectively. If you move your cursor into the @samp{*Occur*}
16298 window, you can position the cursor over one of the lines and use the
16299 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
16300 the corresponding spot in the Texinfo file. @xref{Other Repeating
16301 Search, , Using Occur, xemacs, XEmacs User's Manual}, for more
16302 information about @code{occur-mode-goto-occurrence}.@refill
16304 The first line in the @samp{*Occur*} window describes the @dfn{regular
16305 expression} specified by @var{texinfo-heading-pattern}. This regular
16306 expression is the pattern that @code{texinfo-show-structure} looks for.
16307 @xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual},
16308 for more information.@refill
16310 When you invoke the @code{texinfo-show-structure} command, Emacs will
16311 display the structure of the whole buffer. If you want to see the
16312 structure of just a part of the buffer, of one chapter, for example,
16313 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
16314 region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is
16315 how the example used above was generated. (To see the whole buffer
16316 again, use @kbd{C-x n w} (@code{widen}).)@refill
16318 If you call @code{texinfo-show-structure} with a prefix argument by
16319 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
16320 @code{@@node} as well as the lines beginning with the @@-sign commands
16321 for @code{@@chapter}, @code{@@section}, and the like.@refill
16323 You can remind yourself of the structure of a Texinfo file by looking at
16324 the list in the @samp{*Occur*} window; and if you have mis-named a node
16325 or left out a section, you can correct the mistake.@refill
16327 @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
16328 @comment node-name, next, previous, up
16329 @appendixsec Using @code{occur}
16330 @cindex Occurrences, listing with @code{@@occur}
16333 Sometimes the @code{texinfo-show-structure} command produces too much
16334 information. Perhaps you want to remind yourself of the overall structure
16335 of a Texinfo file, and are overwhelmed by the detailed list produced by
16336 @code{texinfo-show-structure}. In this case, you can use the @code{occur}
16337 command directly. To do this, type@refill
16344 and then, when prompted, type a @dfn{regexp}, a regular expression for
16345 the pattern you want to match. (@xref{Regexps, , Regular Expressions,
16346 xemacs, XEmacs User's Manual}.) The @code{occur} command works from the
16347 current location of the cursor in the buffer to the end of the buffer.
16348 If you want to run @code{occur} on the whole buffer, place the cursor at
16349 the beginning of the buffer.@refill
16351 For example, to see all the lines that contain the word
16352 @samp{@@chapter} in them, just type @samp{@@chapter}. This will
16353 produce a list of the chapters. It will also list all the sentences
16354 with @samp{@@chapter} in the middle of the line.@refill
16356 If you want to see only those lines that start with the word
16357 @samp{@@chapter}, type @samp{^@@chapter} when prompted by
16358 @code{occur}. If you want to see all the lines that end with a word
16359 or phrase, end the last word with a @samp{$}; for example,
16360 @samp{catching mistakes$}. This can be helpful when you want to see
16361 all the nodes that are part of the same chapter or section and
16362 therefore have the same `Up' pointer.@refill
16364 @xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual},
16365 for more information.@refill
16367 @node Running Info-Validate, , Using occur, Catching Mistakes
16368 @comment node-name, next, previous, up
16369 @appendixsec Finding Badly Referenced Nodes
16370 @findex Info-validate
16371 @cindex Nodes, checking for badly referenced
16372 @cindex Checking for badly referenced nodes
16373 @cindex Looking for badly referenced nodes
16374 @cindex Finding badly referenced nodes
16375 @cindex Badly referenced nodes
16377 You can use the @code{Info-validate} command to check whether any of
16378 the `Next', `Previous', `Up' or other node pointers fail to point to a
16379 node. This command checks that every node pointer points to an
16380 existing node. The @code{Info-validate} command works only on Info
16381 files, not on Texinfo files.@refill
16383 The @code{makeinfo} program validates pointers automatically, so you
16384 do not need to use the @code{Info-validate} command if you are using
16385 @code{makeinfo}. You only may need to use @code{Info-validate} if you
16386 are unable to run @code{makeinfo} and instead must create an Info file
16387 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
16388 if you write an Info file from scratch.@refill
16391 * Using Info-validate:: How to run @code{Info-validate}.
16392 * Unsplit:: How to create an unsplit file.
16393 * Tagifying:: How to tagify a file.
16394 * Splitting:: How to split a file manually.
16397 @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
16398 @appendixsubsec Running @code{Info-validate}
16399 @cindex Running @code{Info-validate}
16400 @cindex Info validating a large file
16401 @cindex Validating a large file
16403 To use @code{Info-validate}, visit the Info file you wish to check and
16411 (Note that the @code{Info-validate} command requires an upper case
16412 `I'. You may also need to create a tag table before running
16413 @code{Info-validate}. @xref{Tagifying}.)@refill
16415 If your file is valid, you will receive a message that says ``File appears
16416 valid''. However, if you have a pointer that does not point to a node,
16417 error messages will be displayed in a buffer called @samp{*problems in
16418 info file*}.@refill
16420 For example, @code{Info-validate} was run on a test file that contained
16421 only the first node of this manual. One of the messages said:@refill
16424 In node "Overview", invalid Next: Texinfo Mode
16428 This meant that the node called @samp{Overview} had a `Next' pointer that
16429 did not point to anything (which was true in this case, since the test file
16430 had only one node in it).@refill
16432 Now suppose we add a node named @samp{Texinfo Mode} to our test case
16433 but we do not specify a `Previous' for this node. Then we will get
16434 the following error message:@refill
16437 In node "Texinfo Mode", should have Previous: Overview
16441 This is because every `Next' pointer should be matched by a
16442 `Previous' (in the node where the `Next' points) which points back.@refill
16444 @code{Info-validate} also checks that all menu entries and cross references
16445 point to actual nodes.@refill
16447 Note that @code{Info-validate} requires a tag table and does not work
16448 with files that have been split. (The @code{texinfo-format-buffer}
16449 command automatically splits large files.) In order to use
16450 @code{Info-validate} on a large file, you must run
16451 @code{texinfo-format-buffer} with an argument so that it does not split
16452 the Info file; and you must create a tag table for the unsplit
16455 @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
16456 @comment node-name, next, previous, up
16457 @appendixsubsec Creating an Unsplit File
16458 @cindex Creating an unsplit file
16459 @cindex Unsplit file creation
16461 You can run @code{Info-validate} only on a single Info file that has a
16462 tag table. The command will not work on the indirect subfiles that
16463 are generated when a master file is split. If you have a large file
16464 (longer than 70,000 bytes or so), you need to run the
16465 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
16466 a way that it does not create indirect subfiles. You will also need
16467 to create a tag table for the Info file. After you have done this,
16468 you can run @code{Info-validate} and look for badly referenced
16471 The first step is to create an unsplit Info file. To prevent
16472 @code{texinfo-format-buffer} from splitting a Texinfo file into
16473 smaller Info files, give a prefix to the @kbd{M-x
16474 texinfo-format-buffer} command:@refill
16477 C-u M-x texinfo-format-buffer
16488 When you do this, Texinfo will not split the file and will not create
16489 a tag table for it. @refill
16490 @cindex Making a tag table manually
16491 @cindex Tag table, making manually
16493 @node Tagifying, Splitting, Unsplit, Running Info-Validate
16494 @appendixsubsec Tagifying a File
16496 After creating an unsplit Info file, you must create a tag table for
16497 it. Visit the Info file you wish to tagify and type:@refill
16504 (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
16505 Info file with a tag table that you can validate.@refill
16507 The third step is to validate the Info file:@refill
16514 (Note the upper case @samp{I} in @code{Info-validate}.)
16515 In brief, the steps are:@refill
16519 C-u M-x texinfo-format-buffer
16525 After you have validated the node structure, you can rerun
16526 @code{texinfo-format-buffer} in the normal way so it will construct a
16527 tag table and split the file automatically, or you can make the tag
16528 table and split the file manually.@refill
16530 @node Splitting, , Tagifying, Running Info-Validate
16531 @comment node-name, next, previous, up
16532 @appendixsubsec Splitting a File Manually
16533 @cindex Splitting an Info file manually
16534 @cindex Info file, splitting manually
16536 You should split a large file or else let the
16537 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
16538 for you automatically. (Generally you will let one of the formatting
16539 commands do this job for you. @xref{Create an Info File}.)@refill
16541 The split-off files are called the indirect subfiles.@refill
16543 Info files are split to save memory. With smaller files, Emacs does not
16544 have make such a large buffer to hold the information.@refill
16546 If an Info file has more than 30 nodes, you should also make a tag
16547 table for it. @xref{Using Info-validate}, for information
16548 about creating a tag table. (Again, tag tables are usually created
16549 automatically by the formatting command; you only need to create a tag
16550 table yourself if you are doing the job manually. Most likely, you
16551 will do this for a large, unsplit file on which you have run
16552 @code{Info-validate}.)@refill
16554 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
16556 Before running @code{Info-split}, you need to load the @code{info} library
16557 into Emacs by giving the command @kbd{M-x load-library @key{RET} info
16561 Visit the Info file you wish to tagify and split and type the two
16570 (Note that the @samp{I} in @samp{Info} is upper case.)@refill
16572 When you use the @code{Info-split} command, the buffer is modified into a
16573 (small) Info file which lists the indirect subfiles. This file should be
16574 saved in place of the original visited file. The indirect subfiles are
16575 written in the same directory the original file is in, with names generated
16576 by appending @samp{-} and a number to the original file name.@refill
16578 The primary file still functions as an Info file, but it contains just
16579 the tag table and a directory of subfiles.@refill
16582 @node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top
16583 @appendix Refilling Paragraphs
16584 @cindex Refilling paragraphs
16585 @cindex Filling paragraphs
16588 The @code{@@refill} command refills and, optionally, indents the first
16589 line of a paragraph.@footnote{Perhaps the command should have been
16590 called the @code{@@refillandindent} command, but @code{@@refill} is
16591 shorter and the name was chosen before indenting was possible.} The
16592 @code{@@refill} command is no longer important, but we describe it here
16593 because you once needed it. You will see it in many old Texinfo
16596 Without refilling, paragraphs containing long @@-constructs may look
16597 bad after formatting because the formatter removes @@-commands and
16598 shortens some lines more than others. In the past, neither the
16599 @code{texinfo-format-region} command nor the
16600 @code{texinfo-format-buffer} command refilled paragraphs
16601 automatically. The @code{@@refill} command had to be written at the
16602 end of every paragraph to cause these formatters to fill them. (Both
16603 @TeX{} and @code{makeinfo} have always refilled paragraphs
16604 automatically.) Now, all the Info formatters automatically fill and
16605 indent those paragraphs that need to be filled and indented.@refill
16607 The @code{@@refill} command causes @code{texinfo-format-region} and
16608 @code{texinfo-format-buffer} to refill a paragraph in the Info file
16609 @emph{after} all the other processing has been done. For this reason,
16610 you can not use @code{@@refill} with a paragraph containing either
16611 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
16612 override those two commands.@refill
16614 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
16615 commands now automatically append @code{@@refill} to the end of each
16616 paragraph that should be filled. They do not append @code{@@refill} to
16617 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
16618 and therefore do not refill or indent them.@refill
16621 @node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top
16622 @comment node-name, next, previous, up
16623 @appendix @@-Command Syntax
16624 @cindex @@-command syntax
16626 The character @samp{@@} is used to start special Texinfo commands.
16627 (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
16628 has four types of @@-command:@refill
16631 @item 1. Non-alphabetic commands.
16632 These commands consist of an @@ followed by a punctuation mark or other
16633 character that is not part of the alphabet. Non-alphabetic commands are
16634 almost always part of the text within a paragraph, and never take any
16635 argument. The two characters (@@ and the other one) are complete in
16636 themselves; none is followed by braces. The non-alphabetic commands
16637 are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
16638 @code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
16639 @code{@@@}}.@refill
16641 @item 2. Alphabetic commands that do not require arguments.
16642 These commands start with @@ followed by a word followed by left- and
16643 right-hand braces. These commands insert special symbols in the
16644 document; they do not require arguments. For example,
16645 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
16646 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
16647 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
16649 @item 3. Alphabetic commands that require arguments within braces.
16650 These commands start with @@ followed by a letter or a word, followed by an
16651 argument within braces. For example, the command @code{@@dfn} indicates
16652 the introductory or defining use of a term; it is used as follows: @samp{In
16653 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
16655 @item 4. Alphabetic commands that occupy an entire line.
16656 These commands occupy an entire line. The line starts with @@,
16657 followed by the name of the command (a word); for example, @code{@@center}
16658 or @code{@@cindex}. If no argument is needed, the word is followed by
16659 the end of the line. If there is an argument, it is separated from
16660 the command name by a space. Braces are not used.@refill
16663 @cindex Braces and argument syntax
16664 Thus, the alphabetic commands fall into classes that have
16665 different argument syntaxes. You cannot tell to which class a command
16666 belongs by the appearance of its name, but you can tell by the
16667 command's meaning: if the command stands for a glyph, it is in
16668 class 2 and does not require an argument; if it makes sense to use the
16669 command together with other text as part of a paragraph, the command
16670 is in class 3 and must be followed by an argument in braces;
16671 otherwise, it is in class 4 and uses the rest of the line as its
16674 The purpose of having a different syntax for commands of classes 3 and
16675 4 is to make Texinfo files easier to read, and also to help the GNU
16676 Emacs paragraph and filling commands work properly. There is only one
16677 exception to this rule: the command @code{@@refill}, which is always
16678 used at the end of a paragraph immediately following the final period
16679 or other punctuation character. @code{@@refill} takes no argument and
16680 does @emph{not} require braces. @code{@@refill} never confuses the
16681 Emacs paragraph commands because it cannot appear at the beginning of
16685 @node Obtaining TeX, Command and Variable Index, Command Syntax, Top
16686 @appendix How to Obtain @TeX{}
16687 @cindex Obtaining @TeX{}
16688 @cindex @TeX{}, how to obtain
16690 @c !!! Here is information about obtaining TeX. Update it whenever.
16691 @c !!! Also consider updating TeX.README on ftp.gnu.org.
16692 @c Updated by RJC on 1 March 1995, conversation with MacKay.
16693 @c Updated by kb@cs.umb.edu on 29 July 1996.
16694 @c Updated by kb@cs.umb.edu on 25 April 1997.
16695 @c Updated by kb@cs.umb.edu on 27 February 1998.
16696 @TeX{} is freely redistributable. You can obtain @TeX{} for Unix
16697 systems via anonymous ftp or on physical media. The core material
16698 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
16700 Instructions for retrieval by anonymous ftp and information on other
16701 available distributions:
16703 @uref{ftp://tug.org/tex/unixtex.ftp}
16704 @uref{http://tug.org/unixtex.ftp}
16707 The Free Software Foundation provides a core distribution on its Source
16708 Code CD-ROM suitable for printing Texinfo manuals; the University of
16709 Washington maintains and supports a tape distribution; the @TeX{} Users
16710 Group co-sponsors a complete CD-ROM @TeX{} distribution.
16715 For the FSF Source Code CD-ROM, please contact:
16720 Free Software Foundation, Inc.
16721 59 Temple Place Suite 330
16722 Boston, MA @ @ 02111-1307
16724 Telephone: @w{+1-617-542-5942}
16725 Fax: (including Japan) @w{+1-617-542-2652}
16726 Free Dial Fax (in Japan):
16727 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
16728 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
16729 Electronic mail: @code{gnu@@gnu.org}
16736 Free Software Foundation, Inc.
16737 59 Temple Place Suite 330
16738 Boston, MA @w{ } 02111-1307
16741 Telephone: @w{+1-617-542-5942}
16742 Fax: (including Japan) @w{+1-617-542-2652}
16743 Free Dial Fax (in Japan):
16744 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
16745 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
16746 Electronic mail: @code{gnu@@gnu.org}
16752 To order a complete distribution on CD-ROM, please see
16753 @uref{http://tug.org/tex-live.html}. (This distribution is also
16754 available by FTP; see the URL's above.)
16757 To order a full distribution from the University of Washington on either
16758 a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge,
16764 Denny Hall, Mail Stop DH-10
16765 University of Washington
16766 Seattle, WA @w{ } 98195
16768 Telephone: +1-206-543-2268
16769 Electronic mail: @code{mackay@@cs.washington.edu}
16774 Please make checks payable to the University of Washington.
16775 Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. Overseas
16776 sites: please add to the base cost, if desired, $20.00 for shipment via
16777 air parcel post, or $30.00 for shipment via courier.
16781 Many other @TeX{} distributions are available; see
16782 @uref{http://tug.org/}.
16785 @c These are no longer ``new'', and the explanations
16786 @c are all given elsewhere anyway, I think. --karl, 25apr97.
16787 @ignore (the entire appendix)
16788 @c node New Features, Command and Variable Index, Obtaining TeX, Top
16789 @c appendix Second Edition Features
16792 % Widen the space for the first column so three control-character
16793 % strings fit in the first column. Switched back to default .8in
16794 % value at end of chapter.
16795 \global\tableindent=1.0in
16798 The second edition of the Texinfo manual describes more than 20 new
16799 Texinfo mode commands and more than 50 previously undocumented Texinfo
16800 @@-commands. This edition is more than twice the length of the first
16803 Here is a brief description of the new commands.@refill
16806 * New Texinfo Mode Commands:: The updating commands are especially useful.
16807 * New Commands:: Many newly described @@-commands.
16810 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
16811 @c appendixsec New Texinfo Mode Commands
16813 Texinfo mode provides commands and features especially designed for
16814 working with Texinfo files. More than 20 new commands have been
16815 added, including commands for automatically creating and updating
16816 both nodes and menus. This is a tedious task when done by hand.@refill
16818 The keybindings are intended to be somewhat mnemonic.@refill
16820 @c subheading Update all nodes and menus
16822 The @code{texinfo-master-menu} command is the primary command:
16826 @itemx M-x texinfo-master-menu
16827 Create or update a master menu.
16828 With @kbd{C-u} as a prefix argument,
16829 first create or update all nodes
16833 @c subheading Update Pointers
16836 Create or update `Next', `Previous', and `Up' node pointers.@refill
16839 @xref{Updating Nodes and Menus}.
16843 @itemx M-x texinfo-update-node
16847 @itemx M-x texinfo-every-node-update
16848 Update every node in the buffer.
16851 @c subheading Update Menus
16854 Create or update menus.@refill
16857 @xref{Updating Nodes and Menus}.
16861 @itemx M-x texinfo-make-menu
16862 Make or update a menu.
16865 @itemx M-x texinfo-all-menus-update
16866 Make or update all the menus in a buffer.
16867 With @kbd{C-u} as a prefix argument,
16868 first update all the nodes.
16871 @c subheading Insert Title as Description
16874 Insert a node's chapter or section title in the space for the
16875 description in a menu entry line; position point so you can edit the
16876 insert. (This command works somewhat differently than the other
16877 insertion commands, which insert only a predefined string.)@refill
16880 @xref{Inserting, Inserting Frequently Used Commands}.
16887 @c subheading Format for Info
16890 Provide keybindings both for the Info formatting commands that are
16891 written in Emacs Lisp and for @code{makeinfo} that is written in
16895 @xref{Info Formatting}.
16898 Use the Emacs lisp @code{texinfo-format@dots{}} commands:
16909 Use @code{makeinfo}:
16919 Recenter the @code{makeinfo} output buffer.
16922 Kill the @code{makeinfo} formatting job.
16925 @c subheading Typeset and Print
16928 Typeset and print Texinfo documents from within Emacs.@refill
16936 @xref{Printing, , Formatting and Printing}.
16941 Run @code{texi2dvi} on the buffer.
16944 Run @TeX{} on the region.
16947 Run @code{texindex}.
16950 Print the DVI file.
16953 Show the print queue.
16956 Delete a job from the print queue.
16959 Kill the current @TeX{} formatting job.
16962 Quit a currently stopped @TeX{} formatting job.
16965 Recenter the output buffer.
16968 @c subheading Other Updating Commands
16971 The ``other updating commands'' do not have standard keybindings because
16972 they are used less frequently.@refill
16975 @xref{Other Updating Commands}.
16978 @item M-x texinfo-insert-node-lines
16979 Insert missing @code{@@node} lines using
16980 section titles as node names.
16982 @item M-x texinfo-multiple-files-update
16983 Update a multi-file document.
16984 With a numeric prefix, such as @kbd{C-u 8},
16985 update @strong{every} pointer and
16986 menu in @strong{all} the files and
16987 then insert a master menu.
16989 @item M-x texinfo-indent-menu-description
16990 Indent descriptions in menus.
16992 @item M-x texinfo-sequential-node-update
16993 Insert node pointers in strict sequence.
16996 @c node New Commands, , New Texinfo Mode Commands, Obtaining TeX
16997 @c appendixsec New Texinfo @@-Commands
16999 The second edition of the Texinfo manual describes more than 50
17000 commands that were not described in the first edition. A third or so
17001 of these commands existed in Texinfo but were not documented in the
17002 manual; the others are new. Here is a listing, with brief
17003 descriptions of them:@refill
17005 @c subheading Indexing
17008 Create your own index, and merge indices.@refill
17014 @item @@defindex @var{index-name}
17015 Define a new index and its indexing command.
17016 See also the @code{@@defcodeindex} command.
17018 @c written verbosely to avoid overfull hbox
17019 @item @@synindex @var{from-index} @var{into-index}
17020 Merge the @var{from-index} index into the @var{into-index} index.
17021 See also the @code{@@syncodeindex} command.
17024 @c subheading Definitions
17027 Describe functions, variables, macros,
17028 commands, user options, special forms, and other such artifacts in a
17029 uniform format.@refill
17032 @xref{Definition Commands}.
17035 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
17036 Format a description for functions, interactive
17037 commands, and similar entities.
17039 @item @@defvr, @@defop, @dots{}
17040 15 other related commands.
17043 @c subheading Glyphs
17046 Indicate the results of evaluation, expansion,
17047 printed output, an error message, equivalence of expressions, and the
17048 location of point.@refill
17062 @item @@expansion@{@}
17063 @itemx @expansion{}
17076 Result of an expression
17079 @c subheading Page Headings
17082 Customize page headings.
17088 @item @@headings @var{on-off-single-double}
17089 Headings on or off, single, or double-sided.
17091 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
17092 Footings for even-numbered (left-hand) pages.
17094 @item @@evenheading, @@everyheading, @@oddheading, @dots{}
17095 Five other related commands.
17097 @item @@thischapter
17098 Insert name of chapter and chapter number.
17100 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
17104 @c subheading Formatting
17107 Format blocks of text.
17110 @xref{Quotations and Examples}, and@*
17111 @ref{Lists and Tables, , Making Lists and Tables}.
17115 Draw rounded box surrounding text (not in Info).
17117 @item @@enumerate @var{optional-arg}
17118 Enumerate a list with letters or numbers.
17120 @item @@exdent @var{line-of-text}
17121 Remove indentation.
17130 Do not narrow nor change font.
17132 @item @@ftable @var{formatting-command}
17133 @itemx @@vtable @var{formatting-command}
17134 Two-column table with indexing.
17137 For an example of Lisp code.
17139 @item @@smallexample
17141 Like @@table and @@lisp @r{but for} @@smallbook.
17144 @c subheading Conditionals
17147 Conditionally format text.
17150 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
17153 @item @@set @var{flag} [@var{string}]
17154 Set a flag. Optionally, set value
17155 of @var{flag} to @var{string}.
17157 @item @@clear @var{flag}
17160 @item @@value@{@var{flag}@}
17161 Replace with value to which @var{flag} is set.
17163 @item @@ifset @var{flag}
17164 Format, if @var{flag} is set.
17166 @item @@ifclear @var{flag}
17167 Ignore, if @var{flag} is set.
17170 @c subheading @@heading series for Titles
17173 Produce unnumbered headings that do not appear in a table of contents.
17176 @xref{Structuring}.
17179 @item @@heading @var{title}
17180 Unnumbered section-like heading not listed
17181 in the table of contents of a printed manual.
17183 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
17188 @c subheading Font commands
17192 @xref{Smallcaps}, and @*
17196 @item @@r@{@var{text}@}
17197 Print in roman font.
17199 @item @@sc@{@var{text}@}
17200 Print in @sc{small caps} font.
17203 @c subheading Miscellaneous
17206 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
17207 see @ref{Customized Highlighting},@*
17208 see @ref{Overfull hboxes},@*
17209 see @ref{Footnotes},@*
17210 see @ref{dmn, , Format a Dimension},@*
17211 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
17212 see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@*
17213 see @ref{minus, , Inserting a Minus Sign},@*
17214 see @ref{paragraphindent, , Paragraph Indenting},@*
17215 see @ref{Cross Reference Commands},@*
17216 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
17217 see @ref{Custom Headings, , How to Make Your Own Headings}.
17220 @item @@author @var{author}
17221 Typeset author's name.
17223 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
17224 @c Define a highlighting command for Info. (Info only.)
17227 Produce cleaner printed output.
17229 @item @@footnotestyle @var{end-or-separate}
17230 Specify footnote style.
17232 @item @@dmn@{@var{dimension}@}
17233 Format a dimension.
17235 @item @@global@@let@var{new-cmd}=@var{existing-cmd}
17236 Define a highlighting command for @TeX{}. (@TeX{} only.)
17238 @item @@lowersections
17239 Reduce hierarchical level of sectioning commands.
17241 @item @@math@{@var{mathematical-expression}@}
17242 Format a mathematical expression.
17245 Generate a minus sign.
17247 @item @@paragraphindent @var{asis-or-number}
17248 Specify paragraph indentation.
17250 @item @@raisesections
17251 Raise hierarchical level of sectioning commands.
17253 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
17254 Make a reference. In the printed manual, the
17255 reference does not start with the word `see'.
17257 @item @@title @var{title}
17258 Typeset @var{title} in the alternative
17261 @item @@subtitle @var{subtitle}
17262 Typeset @var{subtitle} in the alternative
17266 Insert the current date.
17269 % Switch width of first column of tables back to default value
17270 \global\tableindent=.8in
17274 @node Command and Variable Index, Concept Index, Obtaining TeX, Top
17275 @comment node-name, next, previous, up
17276 @unnumbered Command and Variable Index
17278 This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
17279 functions, and several variables. To make the list easier to use, the
17280 commands are listed without their preceding @samp{@@}.@refill
17285 @node Concept Index, , Command and Variable Index, Top
17286 @unnumbered Concept Index