1 \input texinfo.tex @c -*-texinfo-*-
2 @c $Id: texinfo.texi,v 1.14.4.1 2002/07/09 08:36:53 stephent Exp $
5 @c All text is ignored before the setfilename.
6 @setfilename ../info/texinfo.info
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 XEmacs User's
747 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 hit @key{DEL} to go backwards, you wind up in the middle of some other
4772 entry in the @file{dir} file, which has nothing to do with what you were
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{XEmacs User's Manual}, you would
5162 write a menu like this:@refill
5167 * Outlining: (xemacs)Outline Mode. The major mode for
5169 * Rebinding: (xemacs)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
7458 This is an example of text written between @code{@@smallexample} and
7459 @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
7460 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7461 this text appears in a smaller font.
7467 This is an example of text written between @code{@@smallexample} and
7468 @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
7469 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7470 this text appears in a smaller font.
7474 The @code{@@smallexample} and @code{@@smalllisp} commands make it
7475 easier to prepare smaller format manuals without forcing you to edit
7476 examples by hand to fit them onto narrower pages.@refill
7478 As a general rule, a printed document looks better if you write all the
7479 examples in a chapter consistently in @code{@@example} or in
7480 @code{@@smallexample}. Only occasionally should you mix the two
7483 @xref{smallbook, , Printing ``Small'' Books}, for more information
7484 about the @code{@@smallbook} command.@refill
7486 @node display, format, smallexample & smalllisp, Quotations and Examples
7487 @comment node-name, next, previous, up
7488 @section @code{@@display}
7489 @cindex Display formatting
7492 The @code{@@display} command begins a kind of example. It is like the
7493 @code{@@example} command
7495 a printed manual, @code{@@display} does not select the fixed-width
7496 font. In fact, it does not specify the font at all, so that the text
7497 appears in the same font it would have appeared in without the
7498 @code{@@display} command.@refill
7501 This is an example of text written between an @code{@@display} command
7502 and an @code{@@end display} command. The @code{@@display} command
7503 indents the text, but does not fill it.
7506 @node format, exdent, display, Quotations and Examples
7507 @comment node-name, next, previous, up
7508 @section @code{@@format}
7511 The @code{@@format} command is similar to @code{@@example} except
7512 that, in the printed manual, @code{@@format} does not select the
7513 fixed-width font and does not narrow the margins.@refill
7516 This is an example of text written between an @code{@@format} command
7517 and an @code{@@end format} command. As you can see
7519 the @code{@@format} command does not fill the text.
7522 @node exdent, flushleft & flushright, format, Quotations and Examples
7523 @section @code{@@exdent}: Undoing a Line's Indentation
7524 @cindex Indentation undoing
7527 The @code{@@exdent} command removes any indentation a line might have.
7528 The command is written at the beginning of a line and applies only to
7529 the text that follows the command that is on the same line. Do not use
7530 braces around the text. In a printed manual, the text on an
7531 @code{@@exdent} line is printed in the roman font.@refill
7533 @code{@@exdent} is usually used within examples. Thus,@refill
7538 This line follows an @@@@example command.
7539 @@exdent This line is exdented.
7540 This line follows the exdented line.
7541 The @@@@end example comes on the next line.
7551 This line follows an @@example command.
7552 @exdent This line is exdented.
7553 This line follows the exdented line.
7554 The @@end example comes on the next line.
7558 In practice, the @code{@@exdent} command is rarely used.
7559 Usually, you un-indent text by ending the example and
7560 returning the page to its normal width.@refill
7562 @node flushleft & flushright, cartouche, exdent, Quotations and Examples
7563 @section @code{@@flushleft} and @code{@@flushright}
7567 The @code{@@flushleft} and @code{@@flushright} commands line up the
7568 ends of lines on the left and right margins of a page,
7569 but do not fill the text. The commands are written on lines of their
7570 own, without braces. The @code{@@flushleft} and @code{@@flushright}
7571 commands are ended by @code{@@end flushleft} and @code{@@end
7572 flushright} commands on lines of their own.@refill
7597 @code{@@flushright} produces the type of indentation often used in the
7598 return address of letters. For example,
7603 Here is an example of text written
7604 flushright. The @@code@{@@flushright@} command
7605 right justifies every line but leaves the
7615 Here is an example of text written
7616 flushright. The @code{@@flushright} command
7617 right justifies every line but leaves the
7621 @node cartouche, , flushleft & flushright, Quotations and Examples
7622 @section Drawing Cartouches Around Examples
7624 @cindex Box with rounded corners
7626 In a printed manual, the @code{@@cartouche} command draws a box with
7627 rounded corners around its contents. You can use this command to
7628 further highlight an example or quotation. For instance, you could
7629 write a manual in which one type of example is surrounded by a cartouche
7630 for emphasis.@refill
7632 The @code{@@cartouche} command affects only the printed manual; it has
7633 no effect in the Info file.@refill
7643 /usr/local/share/emacs
7650 surrounds the two-line example with a box with rounded corners, in the
7654 In a printed manual, the example looks like this:@refill
7660 /usr/local/lib/emacs/info
7667 @node Lists and Tables, Indices, Quotations and Examples, Top
7668 @chapter Lists and Tables
7669 @cindex Making lists and tables
7670 @cindex Lists and tables, making
7671 @cindex Tables and lists, making
7673 Texinfo has several ways of making lists and tables. Lists can be
7674 bulleted or numbered; two-column tables can highlight the items in
7675 the first column; multi-column tables are also supported.
7678 * Introducing Lists:: Texinfo formats lists for you.
7679 * itemize:: How to construct a simple list.
7680 * enumerate:: How to construct a numbered list.
7681 * Two-column Tables:: How to construct a two-column table.
7682 * Multi-column Tables:: How to construct generalized tables.
7686 @node Introducing Lists, itemize, Lists and Tables, Lists and Tables
7687 @heading Introducing Lists
7690 Texinfo automatically indents the text in lists or tables, and numbers
7691 an enumerated list. This last feature is useful if you modify the
7692 list, since you do not need to renumber it yourself.@refill
7694 Numbered lists and tables begin with the appropriate @@-command at the
7695 beginning of a line, and end with the corresponding @code{@@end}
7696 command on a line by itself. The table and itemized-list commands
7697 also require that you write formatting information on the same line as
7698 the beginning @@-command.@refill
7700 Begin an enumerated list, for example, with an @code{@@enumerate}
7701 command and end the list with an @code{@@end enumerate} command.
7702 Begin an itemized list with an @code{@@itemize} command, followed on
7703 the same line by a formatting command such as @code{@@bullet}, and end
7704 the list with an @code{@@end itemize} command.@refill
7707 Precede each element of a list with an @code{@@item} or @code{@@itemx}
7712 Here is an itemized list of the different kinds of table and lists:@refill
7716 Itemized lists with and without bullets.
7719 Enumerated lists, using numbers or letters.
7722 Two-column tables with highlighting.
7727 Here is an enumerated list with the same items:@refill
7731 Itemized lists with and without bullets.
7734 Enumerated lists, using numbers or letters.
7737 Two-column tables with highlighting.
7742 And here is a two-column table with the same items and their
7743 @w{@@-commands}:@refill
7747 Itemized lists with and without bullets.
7750 Enumerated lists, using numbers or letters.
7755 Two-column tables with indexing.
7758 @node itemize, enumerate, Introducing Lists, Lists and Tables
7759 @comment node-name, next, previous, up
7760 @section Making an Itemized List
7764 The @code{@@itemize} command produces sequences of indented
7765 paragraphs, with a bullet or other mark inside the left margin
7766 at the beginning of each paragraph for which such a mark is desired.@refill
7768 Begin an itemized list by writing @code{@@itemize} at the beginning of
7769 a line. Follow the command, on the same line, with a character or a
7770 Texinfo command that generates a mark. Usually, you will write
7771 @code{@@bullet} after @code{@@itemize}, but you can use
7772 @code{@@minus}, or any character or any special symbol that results in
7773 a single character in the Info file. (When you write @code{@@bullet}
7774 or @code{@@minus} after an @code{@@itemize} command, you may omit the
7775 @samp{@{@}}.)@refill
7777 Write the text of the indented paragraphs themselves after the
7778 @code{@@itemize}, up to another line that says @code{@@end
7781 Before each paragraph for which a mark in the margin is desired, write
7782 a line that says just @code{@@item}. Do not write any other text on this
7786 Usually, you should put a blank line before an @code{@@item}. This
7787 puts a blank line in the Info file. (@TeX{} inserts the proper
7788 interline whitespace in either case.) Except when the entries are
7789 very brief, these blank lines make the list look better.@refill
7791 Here is an example of the use of @code{@@itemize}, followed by the
7792 output it produces. Note that @code{@@bullet} produces a @samp{*} in
7793 Info and a round dot in @TeX{}.@refill
7822 Itemized lists may be embedded within other itemized lists. Here is a
7823 list marked with dashes embedded in a list marked with bullets:@refill
7866 @node enumerate, Two-column Tables, itemize, Lists and Tables
7867 @comment node-name, next, previous, up
7868 @section Making a Numbered or Lettered List
7872 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
7873 @code{@@itemize}}), except that the labels on the items are
7874 successive integers or letters instead of bullets.
7876 Write the @code{@@enumerate} command at the beginning of a line. The
7877 command does not require an argument, but accepts either a number or a
7878 letter as an option. Without an argument, @code{@@enumerate} starts the
7879 list with the number @samp{1}. With a numeric argument, such as
7880 @samp{3}, the command starts the list with that number. With an upper
7881 or lower case letter, such as @samp{a} or @samp{A}, the command starts
7882 the list with that letter.@refill
7884 Write the text of the enumerated list in the same way you write an
7885 itemized list: put @code{@@item} on a line of its own before the start
7886 of each paragraph that you want enumerated. Do not write any other text
7887 on the line beginning with @code{@@item}.@refill
7889 You should put a blank line between entries in the list.
7890 This generally makes it easier to read the Info file.@refill
7893 Here is an example of @code{@@enumerate} without an argument:@refill
7918 Here is an example with an argument of @kbd{3}:@refill
7924 Predisposing causes.
7927 Precipitating causes.
7930 Perpetuating causes.
7940 Predisposing causes.
7943 Precipitating causes.
7946 Perpetuating causes.
7949 Here is a brief summary of the alternatives. The summary is constructed
7950 using @code{@@enumerate} with an argument of @kbd{a}.@refill
7956 Without an argument, produce a numbered list, starting with the number
7960 @code{@@enumerate @var{positive-integer}}
7962 With a (positive) numeric argument, start a numbered list with that
7963 number. You can use this to continue a list that you interrupted with
7967 @code{@@enumerate @var{upper-case-letter}}
7969 With an upper case letter as argument, start a list
7970 in which each item is marked
7971 by a letter, beginning with that upper case letter.@refill
7974 @code{@@enumerate @var{lower-case-letter}}
7976 With a lower case letter as argument, start a list
7977 in which each item is marked by
7978 a letter, beginning with that lower case letter.@refill
7981 You can also nest enumerated lists, as in an outline.@refill
7983 @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
7984 @section Making a Two-column Table
7985 @cindex Tables, making two-column
7988 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
7989 @code{@@itemize}}), but allows you to specify a name or heading line for
7990 each item. The @code{@@table} command is used to produce two-column
7991 tables, and is especially useful for glossaries, explanatory
7992 exhibits, and command-line option summaries.
7995 * table:: How to construct a two-column table.
7996 * ftable vtable:: Automatic indexing for two-column tables.
7997 * itemx:: How to put more entries in the first column.
8001 @node table, ftable vtable, Two-column Tables, Two-column Tables
8002 @subheading Using the @code{@@table} Command
8004 Use the @code{@@table} command to produce two-column tables.@refill
8007 Write the @code{@@table} command at the beginning of a line and follow
8008 it on the same line with an argument that is a Texinfo ``indicating''
8009 command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8010 @code{@@kbd} (@pxref{Indicating}). Although these commands are usually
8011 followed by arguments in braces, in this case you use the command name
8012 without an argument because @code{@@item} will supply the argument.
8013 This command will be applied to the text that goes into the first column
8014 of each item and determines how it will be highlighted. For example,
8015 @code{@@code} will cause the text in the first column to be highlighted
8016 with an @code{@@code} command. (We recommend @code{@@code} for
8017 @code{@@table}'s of command-line options.)
8020 You may also choose to use the @code{@@asis} command as an argument to
8021 @code{@@table}. @code{@@asis} is a command that does nothing; if you
8022 use this command after @code{@@table}, @TeX{} and the Info formatting
8023 commands output the first column entries without added highlighting
8026 (The @code{@@table} command may work with other commands besides those
8027 listed here. However, you can only use commands that normally take
8028 arguments in braces.)@refill
8030 Begin each table entry with an @code{@@item} command at the beginning
8031 of a line. Write the first column text on the same line as the
8032 @code{@@item} command. Write the second column text on the line
8033 following the @code{@@item} line and on subsequent lines. (You do not
8034 need to type anything for an empty second column entry.) You may
8035 write as many lines of supporting text as you wish, even several
8036 paragraphs. But only text on the same line as the @code{@@item} will
8037 be placed in the first column.@refill
8040 Normally, you should put a blank line before an @code{@@item} line.
8041 This puts a blank like in the Info file. Except when the entries are
8042 very brief, a blank line looks better.@refill
8045 The following table, for example, highlights the text in the first
8046 column with an @code{@@samp} command:@refill
8052 This is the text for
8056 Text for @@samp@{bar@}.
8066 This is the text for
8069 Text for @samp{bar}.
8072 If you want to list two or more named items with a single block of
8073 text, use the @code{@@itemx} command. (@xref{itemx, ,
8074 @code{@@itemx}}.)@refill
8076 @node ftable vtable, itemx, table, Two-column Tables
8077 @comment node-name, next, previous, up
8078 @subsection @code{@@ftable} and @code{@@vtable}
8079 @cindex Tables with indexes
8080 @cindex Indexing table entries automatically
8084 The @code{@@ftable} and @code{@@vtable} commands are the same as the
8085 @code{@@table} command except that @code{@@ftable} automatically enters
8086 each of the items in the first column of the table into the index of
8087 functions and @code{@@vtable} automatically enters each of the items in
8088 the first column of the table into the index of variables. This
8089 simplifies the task of creating indices. Only the items on the same
8090 line as the @code{@@item} commands are indexed, and they are indexed in
8091 exactly the form that they appear on that line. @xref{Indices, ,
8092 Creating Indices}, for more information about indices.@refill
8094 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8095 writing the @@-command at the beginning of a line, followed on the same
8096 line by an argument that is a Texinfo command such as @code{@@code},
8097 exactly as you would for an @code{@@table} command; and end the table
8098 with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8101 See the example for @code{@@table} in the previous section.
8103 @node itemx, , ftable vtable, Two-column Tables
8104 @comment node-name, next, previous, up
8105 @subsection @code{@@itemx}
8106 @cindex Two named items for @code{@@table}
8109 Use the @code{@@itemx} command inside a table when you have two or more
8110 first column entries for the same item, each of which should appear on a
8111 line of its own. Use @code{@@itemx} for all but the first entry;
8112 @code{@@itemx} should always follow an @code{@@item} command. The
8113 @code{@@itemx} command works exactly like @code{@@item} except that it
8114 does not generate extra vertical space above the first column text.
8124 These two functions accept a character or a string as
8125 argument, and return the corresponding upper case (lower
8126 case) character or string.
8137 These two functions accept a character or a string as
8138 argument, and return the corresponding upper case (lower
8139 case) character or string.@refill
8143 (Note also that this example illustrates multi-line supporting text in
8144 a two-column table.)@refill
8147 @node Multi-column Tables, , Two-column Tables, Lists and Tables
8148 @section Multi-column Tables
8149 @cindex Tables, making multi-column
8152 @code{@@multitable} allows you to construct tables with any number of
8153 columns, with each column having any width you like.
8155 You define the column widths on the @code{@@multitable} line itself, and
8156 write each row of the actual table following an @code{@@item} command,
8157 with columns separated by an @code{@@tab} command. Finally, @code{@@end
8158 multitable} completes the table. Details in the sections below.
8161 * Multitable Column Widths:: Defining multitable column widths.
8162 * Multitable Rows:: Defining multitable rows, with examples.
8165 @node Multitable Column Widths, Multitable Rows, Multi-column Tables, Multi-column Tables
8166 @subsection Multitable Column Widths
8167 @cindex Multitable column widths
8168 @cindex Column widths, defining for multitables
8169 @cindex Widths, defining multitable column
8171 You can define the column widths for a multitable in two ways: as
8172 fractions of the line length; or with a prototype row. Mixing the two
8173 methods is not supported. In either case, the widths are defined
8174 entirely on the same line as the @code{@@multitable} command.
8178 @findex columnfractions
8179 @cindex Line length, column widths as fraction of
8180 To specify column widths as fractions of the line length, write
8181 @code{@@columnfractions} and the decimal numbers (presumably less than
8182 1) after the @code{@@multitable} command, as in:
8185 @@multitable @@columnfractions .33 .33 .33
8189 The fractions need not add up exactly to 1.0, as these do
8190 not. This allows you to produce tables that do not need the full line
8194 @cindex Prototype row, column widths defined by
8195 To specify a prototype row, write the longest entry for each column
8196 enclosed in braces after the @code{@@multitable} command. For example:
8199 @@multitable @{some text for column one@} @{for column two@}
8203 The first column will then have the width of the typeset `some text for
8204 column one', and the second column the width of `for column two'.
8206 The prototype entries need not appear in the table itself.
8208 Although we used simple text in this example, the prototype entries can
8209 contain Texinfo commands; markup commands such as @code{@@code} are
8210 particularly likely to be useful.
8215 @node Multitable Rows, , Multitable Column Widths, Multi-column Tables
8216 @subsection Multitable Rows
8217 @cindex Multitable rows
8218 @cindex Rows, of a multitable
8222 After the @code{@@multitable} command defining the column widths (see
8223 the previous section), you begin each row in the body of a multitable
8224 with @code{@@item}, and separate the column entries with @code{@@tab}.
8225 Line breaks are not special within the table body, and you may break
8226 input lines in your source file as necessary.
8228 Here is a complete example of a multi-column table (the text is from
8229 @cite{The XEmacs Users' Manual}, @pxref{Split Window,, Splitting Windows,
8230 xemacs, XEmacs User's Manual}):
8233 @@multitable @@columnfractions .15 .45 .4
8234 @@item Key @@tab Command @@tab Description
8236 @@tab @@code@{split-window-vertically@}
8237 @@tab Split the selected window into two windows,
8238 with one above the other.
8240 @@tab @@code@{split-window-horizontally@}
8241 @@tab Split the selected window into two windows
8242 positioned side by side.
8245 @@tab In the mode line or scroll bar of a window,
8253 @multitable @columnfractions .15 .45 .4
8254 @item Key @tab Command @tab Description
8256 @tab @code{split-window-vertically}
8257 @tab Split the selected window into two windows,
8258 with one above the other.
8260 @tab @code{split-window-horizontally}
8261 @tab Split the selected window into two windows
8262 positioned side by side.
8265 @tab In the mode line or scroll bar of a window,
8270 @node Indices, Insertions, Lists and Tables, Top
8271 @comment node-name, next, previous, up
8272 @chapter Creating Indices
8274 @cindex Creating indices
8276 Using Texinfo, you can generate indices without having to sort and
8277 collate entries manually. In an index, the entries are listed in
8278 alphabetical order, together with information on how to find the
8279 discussion of each entry. In a printed manual, this information
8280 consists of page numbers. In an Info file, this information is a menu
8281 entry leading to the first node referenced.@refill
8283 Texinfo provides several predefined kinds of index: an index
8284 for functions, an index for variables, an index for concepts, and so
8285 on. You can combine indices or use them for other than their
8286 canonical purpose. If you wish, you can define your own indices.@refill
8289 * Index Entries:: Choose different words for index entries.
8290 * Predefined Indices:: Use different indices for different kinds
8292 * Indexing Commands:: How to make an index entry.
8293 * Combining Indices:: How to combine indices.
8294 * New Indices:: How to define your own indices.
8297 @node Index Entries, Predefined Indices, Indices, Indices
8298 @comment node-name, next, previous, up
8299 @section Making Index Entries
8300 @cindex Index entries, making
8301 @cindex Entries, making index
8303 When you are making index entries, it is good practice to think of the
8304 different ways people may look for something. Different people
8305 @emph{do not} think of the same words when they look something up. A
8306 helpful index will have items indexed under all the different words
8307 that people may use. For example, one reader may think it obvious that
8308 the two-letter names for indices should be listed under ``Indices,
8309 two-letter names'', since the word ``Index'' is the general concept.
8310 But another reader may remember the specific concept of two-letter
8311 names and search for the entry listed as ``Two letter names for
8312 indices''. A good index will have both entries and will help both
8315 Like typesetting, the construction of an index is a highly skilled,
8316 professional art, the subtleties of which are not appreciated until you
8317 need to do it yourself.@refill
8319 @xref{Printing Indices & Menus}, for information about printing an index
8320 at the end of a book or creating an index menu in an Info file.@refill
8322 @node Predefined Indices, Indexing Commands, Index Entries, Indices
8323 @comment node-name, next, previous, up
8324 @section Predefined Indices
8326 Texinfo provides six predefined indices:@refill
8330 A @dfn{concept index} listing concepts that are discussed.@refill
8333 A @dfn{function index} listing functions (such as entry points of
8337 A @dfn{variables index} listing variables (such as global variables
8338 of libraries).@refill
8341 A @dfn{keystroke index} listing keyboard commands.@refill
8344 A @dfn{program index} listing names of programs.@refill
8347 A @dfn{data type index} listing data types (such as structures defined in
8348 header files).@refill
8352 Not every manual needs all of these, and most manuals use two or three
8353 of them. This manual has two indices: a
8354 concept index and an @@-command index (that is actually the function
8355 index but is called a command index in the chapter heading). Two or
8356 more indices can be combined into one using the @code{@@synindex} or
8357 @code{@@syncodeindex} commands. @xref{Combining Indices}.@refill
8359 @node Indexing Commands, Combining Indices, Predefined Indices, Indices
8360 @comment node-name, next, previous, up
8361 @section Defining the Entries of an Index
8362 @cindex Defining indexing entries
8363 @cindex Index entries
8364 @cindex Entries for an index
8365 @cindex Specifying index entries
8366 @cindex Creating index entries
8368 The data to make an index come from many individual indexing commands
8369 scattered throughout the Texinfo source file. Each command says to add
8370 one entry to a particular index; after formatting, the index will give
8371 the current page number or node name as the reference.@refill
8373 An index entry consists of an indexing command at the beginning of a
8374 line followed, on the rest of the line, by the entry.@refill
8376 For example, this section begins with the following five entries for
8377 the concept index:@refill
8380 @@cindex Defining indexing entries
8381 @@cindex Index entries
8382 @@cindex Entries for an index
8383 @@cindex Specifying index entries
8384 @@cindex Creating index entries
8387 Each predefined index has its own indexing command---@code{@@cindex}
8388 for the concept index, @code{@@findex} for the function index, and so
8391 @cindex Writing index entries
8392 @cindex Index entry writing
8393 Concept index entries consist of text. The best way to write an index
8394 is to choose entries that are terse yet clear. If you can do this,
8395 the index often looks better if the entries are not capitalized, but
8396 written just as they would appear in the middle of a sentence.
8397 (Capitalize proper names and acronyms that always call for upper case
8398 letters.) This is the case convention we use in most GNU manuals'
8401 If you don't see how to make an entry terse yet clear, make it longer
8402 and clear---not terse and confusing. If many of the entries are several
8403 words long, the index may look better if you use a different convention:
8404 to capitalize the first word of each entry. But do not capitalize a
8405 case-sensitive name such as a C or Lisp function name or a shell
8406 command; that would be a spelling error.
8408 Whichever case convention you use, please use it consistently!
8411 Concept index entries consist of English text. The usual convention
8412 is to capitalize the first word of each such index entry, unless that
8413 word is the name of a function, variable, or other such entity that
8414 should not be capitalized. However, if your concept index entries are
8415 consistently short (one or two words each) it may look better for each
8416 regular entry to start with a lower case letter, aside from proper
8417 names and acronyms that always call for upper case letters. Whichever
8418 convention you adapt, please be consistent!
8421 Entries in indices other than the concept index are symbol names in
8422 programming languages, or program names; these names are usually
8423 case-sensitive, so use upper and lower case as required for them.
8425 By default, entries for a concept index are printed in a small roman
8426 font and entries for the other indices are printed in a small
8427 @code{@@code} font. You may change the way part of an entry is
8428 printed with the usual Texinfo commands, such as @code{@@file} for
8429 file names and @code{@@emph} for emphasis (@pxref{Marking
8431 @cindex Index font types
8433 @cindex Predefined indexing commands
8434 @cindex Indexing commands, predefined
8435 The six indexing commands for predefined indices are:
8438 @item @@cindex @var{concept}
8440 Make an entry in the concept index for @var{concept}.@refill
8442 @item @@findex @var{function}
8444 Make an entry in the function index for @var{function}.@refill
8446 @item @@vindex @var{variable}
8448 Make an entry in the variable index for @var{variable}.@refill
8450 @item @@kindex @var{keystroke}
8452 Make an entry in the key index for @var{keystroke}.@refill
8454 @item @@pindex @var{program}
8456 Make an entry in the program index for @var{program}.@refill
8458 @item @@tindex @var{data type}
8460 Make an entry in the data type index for @var{data type}.@refill
8464 @strong{Caution:} Do not use a colon in an index entry. In Info, a
8465 colon separates the menu entry name from the node name. An extra
8466 colon confuses Info.
8467 @xref{Menu Parts, , The Parts of a Menu},
8468 for more information about the structure of a menu entry.@refill
8471 If you write several identical index entries in different places in a
8472 Texinfo file, the index in the printed manual will list all the pages to
8473 which those entries refer. However, the index in the Info file will
8474 list @strong{only} the node that references the @strong{first} of those
8475 index entries. Therefore, it is best to write indices in which each
8476 entry refers to only one place in the Texinfo file. Fortunately, this
8477 constraint is a feature rather than a loss since it means that the index
8478 will be easy to use. Otherwise, you could create an index that lists
8479 several pages for one entry and your reader would not know to which page
8480 to turn. If you have two identical entries for one topic, change the
8481 topics slightly, or qualify them to indicate the difference.@refill
8483 You are not actually required to use the predefined indices for their
8484 canonical purposes. For example, suppose you wish to index some C
8485 preprocessor macros. You could put them in the function index along
8486 with actual functions, just by writing @code{@@findex} commands for
8487 them; then, when you print the ``Function Index'' as an unnumbered
8488 chapter, you could give it the title `Function and Macro Index' and
8489 all will be consistent for the reader. Or you could put the macros in
8490 with the data types by writing @code{@@tindex} commands for them, and
8491 give that index a suitable title so the reader will understand.
8492 (@xref{Printing Indices & Menus}.)@refill
8494 @node Combining Indices, New Indices, Indexing Commands, Indices
8495 @comment node-name, next, previous, up
8496 @section Combining Indices
8497 @cindex Combining indices
8498 @cindex Indices, combining them
8500 Sometimes you will want to combine two disparate indices such as functions
8501 and concepts, perhaps because you have few enough of one of them that
8502 a separate index for them would look silly.@refill
8504 You could put functions into the concept index by writing
8505 @code{@@cindex} commands for them instead of @code{@@findex} commands,
8506 and produce a consistent manual by printing the concept index with the
8507 title `Function and Concept Index' and not printing the `Function
8508 Index' at all; but this is not a robust procedure. It works only if
8509 your document is never included as part of another
8510 document that is designed to have a separate function index; if your
8511 document were to be included with such a document, the functions from
8512 your document and those from the other would not end up together.
8513 Also, to make your function names appear in the right font in the
8514 concept index, you would need to enclose every one of them between
8515 the braces of @code{@@code}.@refill
8518 * syncodeindex:: How to merge two indices, using @code{@@code}
8519 font for the merged-from index.
8520 * synindex:: How to merge two indices, using the
8521 default font of the merged-to index.
8524 @node syncodeindex, synindex, Combining Indices, Combining Indices
8525 @subsection @code{@@syncodeindex}
8526 @findex syncodeindex
8528 When you want to combine functions and concepts into one index, you
8529 should index the functions with @code{@@findex} and index the concepts
8530 with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8531 redirect the function index entries into the concept index.@refill
8532 @findex syncodeindex
8534 The @code{@@syncodeindex} command takes two arguments; they are the name
8535 of the index to redirect, and the name of the index to redirect it to.
8536 The template looks like this:@refill
8539 @@syncodeindex @var{from} @var{to}
8542 @cindex Predefined names for indices
8543 @cindex Two letter names for indices
8544 @cindex Indices, two letter names
8545 @cindex Names for indices
8546 For this purpose, the indices are given two-letter names:@refill
8563 Write an @code{@@syncodeindex} command before or shortly after the
8564 end-of-header line at the beginning of a Texinfo file. For example,
8565 to merge a function index with a concept index, write the
8569 @@syncodeindex fn cp
8573 This will cause all entries designated for the function index to merge
8574 in with the concept index instead.@refill
8576 To merge both a variables index and a function index into a concept
8577 index, write the following:@refill
8581 @@syncodeindex vr cp
8582 @@syncodeindex fn cp
8586 @cindex Fonts for indices
8587 The @code{@@syncodeindex} command puts all the entries from the `from'
8588 index (the redirected index) into the @code{@@code} font, overriding
8589 whatever default font is used by the index to which the entries are
8590 now directed. This way, if you direct function names from a function
8591 index into a concept index, all the function names are printed in the
8592 @code{@@code} font as you would expect.@refill
8594 @node synindex, , syncodeindex, Combining Indices
8595 @subsection @code{@@synindex}
8598 The @code{@@synindex} command is nearly the same as the
8599 @code{@@syncodeindex} command, except that it does not put the
8600 `from' index entries into the @code{@@code} font; rather it puts
8601 them in the roman font. Thus, you use @code{@@synindex} when you
8602 merge a concept index into a function index.@refill
8604 @xref{Printing Indices & Menus}, for information about printing an index
8605 at the end of a book or creating an index menu in an Info file.@refill
8607 @node New Indices, , Combining Indices, Indices
8608 @section Defining New Indices
8609 @cindex Defining new indices
8610 @cindex Indices, defining new
8611 @cindex New index defining
8613 @findex defcodeindex
8615 In addition to the predefined indices, you may use the
8616 @code{@@defindex} and @code{@@defcodeindex} commands to define new
8617 indices. These commands create new indexing @@-commands with which
8618 you mark index entries. The @code{@@defindex }command is used like
8622 @@defindex @var{name}
8625 The name of an index should be a two letter word, such as @samp{au}.
8632 This defines a new index, called the @samp{au} index. At the same
8633 time, it creates a new indexing command, @code{@@auindex}, that you
8634 can use to make index entries. Use the new indexing command just as
8635 you would use a predefined indexing command.@refill
8637 For example, here is a section heading followed by a concept index
8638 entry and two @samp{au} index entries.@refill
8641 @@section Cognitive Semantics
8642 @@cindex kinesthetic image schemas
8643 @@auindex Johnson, Mark
8644 @@auindex Lakoff, George
8648 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
8649 Texinfo constructs the new indexing command by concatenating the name
8650 of the index with @samp{index}; thus, defining an @samp{au} index
8651 leads to the automatic creation of an @code{@@auindex} command.@refill
8653 Use the @code{@@printindex} command to print the index, as you do with
8654 the predefined indices. For example:@refill
8658 @@node Author Index, Subject Index, , Top
8659 @@unnumbered Author Index
8665 The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8666 that, in the printed output, it prints entries in an @code{@@code} font
8667 instead of a roman font. Thus, it parallels the @code{@@findex} command
8668 rather than the @code{@@cindex} command.@refill
8670 You should define new indices within or right after the end-of-header
8671 line of a Texinfo file, before any @code{@@synindex} or
8672 @code{@@syncodeindex} commands (@pxref{Header}).@refill
8674 @node Insertions, Breaks, Indices, Top
8675 @comment node-name, next, previous, up
8676 @chapter Special Insertions
8677 @cindex Inserting special characters and symbols
8678 @cindex Special insertions
8680 Texinfo provides several commands for inserting characters that have
8681 special meaning in Texinfo, such as braces, and for other graphic
8682 elements that do not correspond to simple characters you can type.
8688 @item Braces, @samp{@@} and periods.
8689 @item Whitespace within and around a sentence.
8691 @item Dots and bullets.
8692 @item The @TeX{} logo and the copyright symbol.
8693 @item Mathematical expressions.
8698 * Braces Atsigns:: How to insert braces, @samp{@@}.
8699 * Inserting Space:: How to insert the right amount of space
8701 * Inserting Accents:: How to insert accents and special characters.
8702 * Dots Bullets:: How to insert dots and bullets.
8703 * TeX and copyright:: How to insert the @TeX{} logo
8704 and the copyright symbol.
8705 * pounds:: How to insert the pounds currency symbol.
8706 * minus:: How to insert a minus sign.
8707 * math:: How to format a mathematical expression.
8708 * Glyphs:: How to indicate results of evaluation,
8709 expansion of macros, errors, etc.
8710 * Images:: How to include graphics.
8714 @node Braces Atsigns, Inserting Space, Insertions, Insertions
8715 @section Inserting @@ and Braces
8716 @cindex Inserting @@, braces
8717 @cindex Braces, inserting
8718 @cindex Special characters, commands to insert
8719 @cindex Commands to insert special characters
8721 @samp{@@} and curly braces are special characters in Texinfo. To insert
8722 these characters so they appear in text, you must put an @samp{@@} in
8723 front of these characters to prevent Texinfo from misinterpreting
8726 Do not put braces after any of these commands; they are not
8730 * Inserting An Atsign:: How to insert @samp{@@}.
8731 * Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
8734 @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
8735 @subsection Inserting @samp{@@} with @@@@
8736 @findex @@ @r{(single @samp{@@})}
8738 @code{@@@@} stands for a single @samp{@@} in either printed or Info
8741 Do not put braces after an @code{@@@@} command.
8743 @node Inserting Braces, , Inserting An Atsign, Braces Atsigns
8744 @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
8745 @findex @{ @r{(single @samp{@{})}
8746 @findex @} @r{(single @samp{@}})}
8748 @code{@@@{} stands for a single @samp{@{} in either printed or Info
8751 @code{@@@}} stands for a single @samp{@}} in either printed or Info
8754 Do not put braces after either an @code{@@@{} or an @code{@@@}}
8758 @node Inserting Space, Inserting Accents, Braces Atsigns, Insertions
8759 @section Inserting Space
8761 @cindex Inserting space
8762 @cindex Spacing, inserting
8763 @cindex Whitespace, inserting
8764 The following sections describe commands that control spacing of various
8765 kinds within and after sentences.
8768 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
8769 * Ending a Sentence:: Sometimes it does.
8770 * Multiple Spaces:: Inserting multiple spaces.
8771 * dmn:: How to format a dimension.
8774 @node Not Ending a Sentence, Ending a Sentence, Inserting Space, Inserting Space
8775 @subsection Not Ending a Sentence
8777 @cindex Not ending a sentence
8778 @cindex Sentence non-ending punctuation
8779 @cindex Periods, inserting
8780 Depending on whether a period or exclamation point or question mark is
8781 inside or at the end of a sentence, less or more space is inserted after
8782 a period in a typeset manual. Since it is not always possible for
8783 Texinfo to determine when a period ends a sentence and when it is used
8784 in an abbreviation, special commands are needed in some circumstances.
8785 (Usually, Texinfo can guess how to handle periods, so you do not need to
8786 use the special commands; you just enter a period as you would if you
8787 were using a typewriter, which means you put two spaces after the
8788 period, question mark, or exclamation mark that ends a sentence.)
8790 @findex : @r{(suppress widening)}
8791 Use the @code{@@:}@: command after a period, question mark,
8792 exclamation mark, or colon that should not be followed by extra space.
8793 For example, use @code{@@:}@: after periods that end abbreviations
8794 which are not at the ends of sentences.
8800 The s.o.p.@@: has three parts @dots{}
8801 The s.o.p. has three parts @dots{}
8809 produces the following. If you look carefully at this printed output,
8810 you will see a little more whitespace after @samp{s.o.p.} in the second
8815 The s.o.p.@: has three parts @dots{}@*
8816 The s.o.p. has three parts @dots{}
8820 (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
8823 @code{@@:} has no effect on the Info output. Do not put braces after
8827 @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
8828 @subsection Ending a Sentence
8830 @cindex Ending a Sentence
8831 @cindex Sentence ending punctuation
8833 @findex . @r{(end of sentence)}
8834 @findex ! @r{(end of sentence)}
8835 @findex ? @r{(end of sentence)}
8836 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
8837 exclamation point, and @code{@@?}@: instead of a question mark at the end
8838 of a sentence that ends with a single capital letter. Otherwise, @TeX{}
8839 will think the letter is an abbreviation and will not insert the correct
8840 end-of-sentence spacing. Here is an example:
8843 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
8844 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
8852 produces the following. If you look carefully at this printed output,
8853 you will see a little more whitespace after the @samp{W} in the first
8858 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
8859 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
8862 In the Info file output, @code{@@.}@: is equivalent to a simple
8863 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
8865 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
8866 work well with the Emacs sentence motion commands (@pxref{Sentences,,,
8867 xemacs, XEmacs User's Manual}). This made it necessary for them to be
8868 incompatible with some other formatting systems that use @@-commands.
8870 Do not put braces after any of these commands.
8873 @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
8874 @subsection Multiple Spaces
8876 @cindex Multiple spaces
8877 @cindex Whitespace, inserting
8882 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
8883 and newline) into a single space. Info output, on the other hand,
8884 preserves whitespace as you type it, except for changing a newline into
8885 a space; this is why it is important to put two spaces at the end of
8886 sentences in Texinfo documents.
8888 Occasionally, you may want to actually insert several consecutive
8889 spaces, either for purposes of example (what your program does with
8890 multiple spaces as input), or merely for purposes of appearance in
8891 headings or lists. Texinfo supports three commands:
8892 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
8893 which insert a single space into the output. (Here,
8894 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
8895 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
8896 character and end-of-line, i.e., when @samp{@@} is the last character on
8913 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
8914 @code{@@multitable} (@pxref{Multi-column Tables}).
8916 Do not follow any of these commands with braces.
8919 @node dmn, , Multiple Spaces, Inserting Space
8920 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
8921 @cindex Thin space between number, dimension
8922 @cindex Dimension formatting
8923 @cindex Format a dimension
8926 At times, you may want to write @samp{12@dmn{pt}} or
8927 @samp{8.5@dmn{in}} with little or no space between the number and the
8928 abbreviation for the dimension. You can use the @code{@@dmn} command
8929 to do this. On seeing the command, @TeX{} inserts just enough space
8930 for proper typesetting; the Info formatting commands insert no space
8931 at all, since the Info file does not require it.@refill
8933 To use the @code{@@dmn} command, write the number and then follow it
8934 immediately, with no intervening space, by @code{@@dmn}, and then by
8935 the dimension within braces. For example,
8938 A4 paper is 8.27@@dmn@{in@} wide.
8945 A4 paper is 8.27@dmn{in} wide.
8948 Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
8949 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
8950 In these cases, however, the formatters may insert a line break between
8951 the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
8952 you write a period after an abbreviation within a sentence, you should
8953 write @samp{@@:} after the period to prevent @TeX{} from inserting extra
8954 whitespace, as shown here. @xref{Inserting Space}.
8957 @node Inserting Accents, Dots Bullets, Inserting Space, Insertions
8958 @section Inserting Accents
8960 @cindex Inserting accents
8961 @cindex Accents, inserting
8962 @cindex Floating accents, inserting
8964 Here is a table with the commands Texinfo provides for inserting
8965 floating accents. The commands with non-alphabetic names do not take
8966 braces around their argument (which is taken to be the next character).
8967 (Exception: @code{@@,} @emph{does} take braces around its argument.)
8968 This is so as to make the source as convenient to type and read as
8969 possible, since accented characters are very common in some languages.
8972 @cindex Umlaut accent
8974 @cindex Acute accent
8976 @cindex Macron accent
8978 @cindex Circumflex accent
8980 @cindex Grave accent
8982 @cindex Tilde accent
8984 @cindex Cedilla accent
8988 @cindex Hungariam umlaut accent
8992 @cindex Tie-after accent
8994 @cindex Breve accent
8996 @cindex Underbar accent
8998 @cindex Underdot accent
9000 @cindex Check accent
9001 @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9002 @item Command @tab Output @tab What
9003 @item @t{@@"o} @tab @"o @tab umlaut accent
9004 @item @t{@@'o} @tab @'o @tab acute accent
9005 @item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9006 @item @t{@@=o} @tab @=o @tab macron/overbar accent
9007 @item @t{@@^o} @tab @^o @tab circumflex accent
9008 @item @t{@@`o} @tab @`o @tab grave accent
9009 @item @t{@@~o} @tab @~o @tab tilde accent
9010 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
9011 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
9012 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9013 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9014 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent
9015 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9016 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9017 @item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent
9020 This table lists the Texinfo commands for inserting other characters
9021 commonly used in languages other than English.
9023 @findex questiondown
9024 @cindex @questiondown{}
9026 @cindex @exclamdown{}
9038 @cindex Dotless i, j
9056 @multitable {@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
9057 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
9058 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9059 @item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab A,a with circle
9060 @item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures
9061 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
9062 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
9063 @item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l
9064 @item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash
9065 @item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab OE,oe ligatures
9066 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
9070 @node Dots Bullets, TeX and copyright, Inserting Accents, Insertions
9071 @section Inserting Ellipsis, Dots, and Bullets
9072 @cindex Dots, inserting
9073 @cindex Bullets, inserting
9074 @cindex Ellipsis, inserting
9075 @cindex Inserting ellipsis
9076 @cindex Inserting dots
9077 @cindex Special typesetting commands
9078 @cindex Typesetting commands for dots, etc.
9080 An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9081 periods, so a special command is used for ellipsis in Texinfo. The
9082 @code{@@bullet} command is special, too. Each of these commands is
9083 followed by a pair of braces, @samp{@{@}}, without any whitespace
9084 between the name of the command and the braces. (You need to use braces
9085 with these commands because you can use them next to other text; without
9086 the braces, the formatters would be confused. @xref{Command Syntax, ,
9087 @@-Command Syntax}, for further information.)@refill
9090 * dots:: How to insert dots @dots{}
9091 * bullet:: How to insert a bullet.
9095 @node dots, bullet, Dots Bullets, Dots Bullets
9096 @subsection @code{@@dots}@{@} (@dots{})
9098 @cindex Inserting dots
9099 @cindex Dots, inserting
9101 Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9102 three dots in a row, appropriately spaced, like this: `@dots{}'. Do
9103 not simply write three periods in the input file; that would work for
9104 the Info file output, but would produce the wrong amount of space
9105 between the periods in the printed manual.
9107 Similarly, the @code{@@enddots@{@}} command generates an
9108 end-of-sentence ellipsis (four dots) @enddots{}
9111 Here is an ellipsis: @dots{}
9112 Here are three periods in a row: ...
9114 In printed output, the three periods in a row are closer together than
9115 the dots in the ellipsis.
9119 @node bullet, , dots, Dots Bullets
9120 @subsection @code{@@bullet}@{@} (@bullet{})
9123 Use the @code{@@bullet@{@}} command to generate a large round dot, or
9124 the closest possible thing to one. In Info, an asterisk is used.@refill
9126 Here is a bullet: @bullet{}
9128 When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9129 type the braces, because @code{@@itemize} supplies them.
9130 (@xref{itemize, , @code{@@itemize}}.)@refill
9133 @node TeX and copyright, pounds, Dots Bullets, Insertions
9134 @section Inserting @TeX{} and the Copyright Symbol
9136 The logo `@TeX{}' is typeset in a special fashion and it needs an
9137 @@-command. The copyright symbol, `@copyright{}', is also special.
9138 Each of these commands is followed by a pair of braces, @samp{@{@}},
9139 without any whitespace between the name of the command and the
9143 * tex:: How to insert the @TeX{} logo.
9144 * copyright symbol:: How to use @code{@@copyright}@{@}.
9148 @node tex, copyright symbol, TeX and copyright, TeX and copyright
9149 @subsection @code{@@TeX}@{@} (@TeX{})
9150 @findex tex (command)
9152 Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
9153 manual, this is a special logo that is different from three ordinary
9154 letters. In Info, it just looks like @samp{TeX}. The
9155 @code{@@TeX@{@}} command is unique among Texinfo commands in that the
9156 @kbd{T} and the @kbd{X} are in upper case.@refill
9159 @node copyright symbol, , tex, TeX and copyright
9160 @subsection @code{@@copyright}@{@} (@copyright{})
9163 Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
9164 a printed manual, this is a @samp{c} inside a circle, and in Info,
9165 this is @samp{(C)}.@refill
9168 @node pounds, minus, TeX and copyright, Insertions
9169 @section @code{@@pounds@{@}} (@pounds{}): Pounds Sterling
9172 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a
9173 printed manual, this is the symbol for the currency pounds sterling.
9174 In Info, it is a @samp{#}. Other currency symbols are unfortunately not
9178 @node minus, math, pounds, Insertions
9179 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9182 Use the @code{@@minus@{@}} command to generate a minus sign. In a
9183 fixed-width font, this is a single hyphen, but in a proportional font,
9184 the symbol is the customary length for a minus sign---a little longer
9185 than a hyphen, shorter than an em-dash:
9188 @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9190 `-' is a hyphen generated with the character @samp{-},
9192 `---' is an em-dash for text.
9196 In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9199 You should not use @code{@@minus@{@}} inside @code{@@code} or
9200 @code{@@example} because the width distinction is not made in the
9201 fixed-width font they use.
9203 When you use @code{@@minus} to specify the mark beginning each entry in
9204 an itemized list, you do not need to type the braces
9205 (@pxref{itemize, , @code{@@itemize}}.)
9208 @node math, Glyphs, minus, Insertions
9209 @section @code{@@math} - Inserting Mathematical Expressions
9211 @cindex Mathematical expressions
9213 You can write a short mathematical expression with the @code{@@math}
9214 command. Write the mathematical expression between braces, like this:
9217 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9223 This produces the following in @TeX{}:
9226 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
9230 and the following in Info:
9234 This produces the following in Info:
9238 (a + b)(a + b) = a^2 + 2ab + b^2
9241 Thus, the @code{@@math} command has no effect on the Info output.
9243 For complex mathematical expressions, you can also use @TeX{} directly
9244 (@pxref{Raw Formatter Commands}). When you use @TeX{} directly,
9245 remember to write the mathematical expression between one or two
9246 @samp{$} (dollar-signs) as appropriate.
9249 @node Glyphs, Images, math, Insertions
9250 @section Glyphs for Examples
9253 In Texinfo, code is often illustrated in examples that are delimited
9254 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9255 @code{@@end lisp}. In such examples, you can indicate the results of
9256 evaluation or an expansion using @samp{@result{}} or
9257 @samp{@expansion{}}. Likewise, there are commands to insert glyphs
9259 printed output, error messages, equivalence of expressions, and the
9260 location of point.@refill
9262 The glyph-insertion commands do not need to be used within an example, but
9263 most often they are. Every glyph-insertion command is followed by a pair of
9264 left- and right-hand braces.@refill
9268 * result:: How to show the result of expression.
9269 * expansion:: How to indicate an expansion.
9270 * Print Glyph:: How to indicate printed output.
9271 * Error Glyph:: How to indicate an error message.
9272 * Equivalence:: How to indicate equivalence.
9273 * Point Glyph:: How to indicate the location of point.
9276 @node Glyphs Summary, result, Glyphs, Glyphs
9278 @subheading Glyphs Summary
9280 Here are the different glyph commands:@refill
9285 @code{@@result@{@}} points to the result of an expression.@refill
9288 @code{@@expansion@{@}} shows the results of a macro expansion.@refill
9291 @code{@@print@{@}} indicates printed output.@refill
9294 @code{@@error@{@}} indicates that the following text is an error
9298 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9301 @code{@@point@{@}} shows the location of point.@refill
9314 @node result, expansion, Glyphs Summary, Glyphs
9315 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9316 @cindex Result of an expression
9317 @cindex Indicating evaluation
9318 @cindex Evaluation glyph
9319 @cindex Value of an expression, indicating
9321 Use the @code{@@result@{@}} command to indicate the result of
9322 evaluating an expression.@refill
9325 The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
9326 as @samp{@result{}} in the printed output.
9329 The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9330 and as a double stemmed arrow in the printed output.@refill
9333 Thus, the following,
9341 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9344 @node expansion, Print Glyph, result, Glyphs
9345 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9346 @cindex Expansion, indicating it
9348 When an expression is a macro call, it expands into a new expression.
9349 You can indicate the result of the expansion with the
9350 @code{@@expansion@{@}} command.@refill
9353 The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
9354 as @samp{@expansion{}} in the printed output.
9357 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9358 in Info and as a long arrow with a flat base in the printed output.@refill
9362 For example, the following
9368 @@expansion@{@} (car (cdr (cdr '(a b c))))
9380 @expansion{} (car (cdr (cdr '(a b c))))
9386 which may be read as:
9389 @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9390 the result of evaluating the expression is @code{c}.
9394 Often, as in this case, an example looks better if the
9395 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9399 @node Print Glyph, Error Glyph, expansion, Glyphs
9400 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9401 @cindex Printed output, indicating it
9403 Sometimes an expression will print output during its execution. You
9404 can indicate the printed output with the @code{@@print@{@}} command.@refill
9407 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
9408 as @samp{@print{}} in the printed output.
9411 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9412 and similarly, as a horizontal dash butting against a vertical bar, in
9413 the printed output.@refill
9416 In the following example, the printed text is indicated with
9417 @samp{@print{}}, and the value of the expression follows on the
9422 (progn (print 'foo) (print 'bar))
9430 In a Texinfo source file, this example is written as follows:
9435 (progn (print 'foo) (print 'bar))
9444 @node Error Glyph, Equivalence, Print Glyph, Glyphs
9445 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9446 @cindex Error message, indicating it
9448 A piece of code may cause an error when you evaluate it. You can
9449 designate the error message with the @code{@@error@{@}} command.@refill
9452 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
9453 and as @samp{@error{}} in the printed output.
9456 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9457 and as the word `error' in a box in the printed output.@refill
9466 @@error@{@} Wrong type argument: integer-or-marker-p, x
9475 @error{} Wrong type argument: integer-or-marker-p, x
9479 This indicates that the following error message is printed
9480 when you evaluate the expression:
9483 Wrong type argument: integer-or-marker-p, x
9486 @samp{@error{}} itself is not part of the error message.
9489 @node Equivalence, Point Glyph, Error Glyph, Glyphs
9490 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9491 @cindex Equivalence, indicating it
9493 Sometimes two expressions produce identical results. You can indicate the
9494 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9497 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
9498 as @samp{@equiv{}} in the printed output.
9501 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9502 and as a three parallel horizontal lines in the printed output.@refill
9509 (make-sparse-keymap) @@equiv@{@} (list 'keymap)
9517 (make-sparse-keymap) @equiv{} (list 'keymap)
9521 This indicates that evaluating @code{(make-sparse-keymap)} produces
9522 identical results to evaluating @code{(list 'keymap)}.
9525 @node Point Glyph, , Equivalence, Glyphs
9526 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9527 @cindex Point, indicating it in a buffer
9529 Sometimes you need to show an example of text in an Emacs buffer. In
9530 such examples, the convention is to include the entire contents of the
9531 buffer in question between two lines of dashes containing the buffer
9534 You can use the @samp{@@point@{@}} command to show the location of point
9535 in the text in the buffer. (The symbol for point, of course, is not
9536 part of the text in the buffer; it indicates the place @emph{between}
9537 two characters where point is located.)@refill
9540 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
9541 as @samp{@point{}} in the printed output.
9544 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9545 and as a small five pointed star in the printed output.@refill
9548 The following example shows the contents of buffer @file{foo} before
9549 and after evaluating a Lisp command to insert the word @code{changed}.@refill
9553 ---------- Buffer: foo ----------
9554 This is the @point{}contents of foo.
9555 ---------- Buffer: foo ----------
9564 ---------- Buffer: foo ----------
9565 This is the changed @point{}contents of foo.
9566 ---------- Buffer: foo ----------
9571 In a Texinfo source file, the example is written like this:@refill
9575 ---------- Buffer: foo ----------
9576 This is the @@point@{@}contents of foo.
9577 ---------- Buffer: foo ----------
9581 ---------- Buffer: foo ----------
9582 This is the changed @@point@{@}contents of foo.
9583 ---------- Buffer: foo ----------
9588 @c this should be described with figures when we have them
9589 @c perhaps in the quotation/example chapter.
9590 @node Images, , Glyphs, Insertions
9591 @section Inserting Images
9593 @cindex Images, inserting
9594 @cindex Pictures, inserting
9597 You can insert an image in an external file with the @code{@@image}
9601 @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@}
9604 @cindex Formats for images
9605 @cindex Image formats
9606 The @var{filename} argument is mandatory, and must not have an
9607 extension, because the different processors support different formats:
9608 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
9609 format); @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
9610 Info output (more or less as if it was an @code{@@example}). HTML
9611 output requires @file{@var{filename}.jpg}.
9613 @cindex Width of images
9614 @cindex Height of images
9615 @cindex Aspect ratio of images
9616 @cindex Distorting images
9617 The optional @var{width} and @var{height} arguments specify the size to
9618 scale the image to (they are ignored for Info output). If they are both
9619 specified, the image is presented in its natural size (given in the
9620 file); if only one is specified, the other is scaled proportionately;
9621 and if both are specified, both are respected, thus possibly distorting
9622 the original image by changing its aspect ratio.
9624 @cindex Dimensions and image sizes
9625 The @var{width} and @var{height} may be specified using any valid @TeX{}
9630 @cindex Points (dimension)
9631 point (72.27pt = 1in)
9637 big point (72bp = 1in)
9643 centimeter (2.54cm = 1in)
9646 millimeter (10mm = 1cm)
9648 @cindex Did@^ot points
9649 did@^ot point (1157dd = 1238pt)
9654 @cindex Scaled points
9655 scaled point (65536sp = 1pt)
9659 For example, the following will scale a file @file{ridt.eps} to one
9660 inch vertically, with the width scaled proportionately:
9663 @@image@{ridt,,1in@}
9667 For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
9668 installed somewhere that @TeX{} can find it. This file is included in
9669 the Texinfo distribution and is available from
9670 @uref{ftp://ftp.tug.org/tex/epsf.tex}.
9673 @node Breaks, Definition Commands, Insertions, Top
9674 @chapter Making and Preventing Breaks
9675 @cindex Making line and page breaks
9676 @cindex Preventing line and page breaks
9678 Usually, a Texinfo file is processed both by @TeX{} and by one of the
9679 Info formatting commands. Line, paragraph, or page breaks sometimes
9680 occur in the `wrong' place in one or other form of output. You must
9681 ensure that text looks right both in the printed manual and in the
9684 For example, in a printed manual, page breaks may occur awkwardly in
9685 the middle of an example; to prevent this, you can hold text together
9686 using a grouping command that keeps the text from being split across
9687 two pages. Conversely, you may want to force a page break where none
9688 would occur normally. Fortunately, problems like these do not often
9689 arise. When they do, use the break, break prevention, or pagination
9693 * Break Commands:: Cause and prevent splits.
9694 * Line Breaks:: How to force a single line to use two lines.
9695 * - and hyphenation:: How to tell TeX about hyphenation points.
9696 * w:: How to prevent unwanted line breaks.
9697 * sp:: How to insert blank lines.
9698 * page:: How to force the start of a new page.
9699 * group:: How to prevent unwanted page breaks.
9700 * need:: Another way to prevent unwanted page breaks.
9704 @node Break Commands, Line Breaks, Breaks, Breaks
9705 @heading The Break Commands
9711 The break commands create or allow line and paragraph breaks:@refill
9718 Skip @var{n} blank lines.@refill
9721 Insert a discretionary hyphen.
9723 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
9724 Define hyphen points in @var{hy-phen-a-ted words}.
9727 The line-break-prevention command holds text together all on one
9731 @item @@w@{@var{text}@}
9732 Prevent @var{text} from being split and hyphenated across two lines.@refill
9738 The pagination commands apply only to printed output, since Info
9739 files do not have pages.@refill
9743 Start a new page in the printed manual.@refill
9746 Hold text together that must appear on one printed page.@refill
9748 @item @@need @var{mils}
9749 Start a new printed page if not enough space on this one.@refill
9752 @node Line Breaks, - and hyphenation, Break Commands, Breaks
9753 @comment node-name, next, previous, up
9754 @section @code{@@*}: Generate Line Breaks
9755 @findex * @r{(force line break)}
9757 @cindex Breaks in a line
9759 The @code{@@*} command forces a line break in both the printed manual and
9766 This line @@* is broken @@*in two places.
9781 (Note that the space after the first @code{@@*} command is faithfully
9782 carried down to the next line.)@refill
9785 The @code{@@*} command is often used in a file's copyright page:@refill
9789 This is edition 2.0 of the Texinfo documentation,@@*
9795 In this case, the @code{@@*} command keeps @TeX{} from stretching the
9796 line across the whole page in an ugly manner.@refill
9799 @strong{Please note:} Do not write braces after an @code{@@*} command;
9800 they are not needed.@refill
9802 Do not write an @code{@@refill} command at the end of a paragraph
9803 containing an @code{@@*} command; it will cause the paragraph to be
9804 refilled after the line break occurs, negating the effect of the line
9808 @node - and hyphenation, w, Line Breaks, Breaks
9809 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
9813 @cindex Hyphenation, helping @TeX{} do
9814 @cindex Fine-tuning, and hyphenation
9816 Although @TeX{}'s hyphenation algorithm is generally pretty good, it
9817 does miss useful hyphenation points from time to time. (Or, far more
9818 rarely, insert an incorrect hyphenation.) So, for documents with an
9819 unusual vocabulary or when fine-tuning for a printed edition, you may
9820 wish to help @TeX{} out. Texinfo supports two commands for this:
9824 Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
9825 not have to) hyphenate. This is especially useful when you notice
9826 an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
9827 hboxes}). @TeX{} will not insert any hyphenation points in a word
9828 containing @code{@@-}.
9830 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
9831 Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
9832 put a @samp{-} at each hyphenation point. For example:
9834 @@hyphenation@{man-u-script man-u-scripts@}
9837 @TeX{} only uses the specified hyphenation points when the
9838 words match exactly, so give all necessary variants.
9841 Info output is not hyphenated, so these commands have no effect there.
9843 @node w, sp, - and hyphenation, Breaks
9844 @comment node-name, next, previous, up
9845 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
9846 @findex w @r{(prevent line break)}
9847 @cindex Line breaks, preventing
9848 @cindex Hyphenation, preventing
9850 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
9851 within @var{text}.@refill
9853 You can use the @code{@@w} command to prevent @TeX{} from automatically
9854 hyphenating a long name or phrase that happens to fall near the end of a
9858 You can copy GNU software from @@w@{@@samp@{ftp.gnu.ai.mit.edu@}@}.
9865 You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
9869 @strong{Caution:} Do not write an @code{@@refill} command at the end
9870 of a paragraph containing an @code{@@w} command; it will cause the
9871 paragraph to be refilled and may thereby negate the effect of the
9872 @code{@@w} command.@refill
9875 @node sp, page, w, Breaks
9876 @comment node-name, next, previous, up
9877 @section @code{@@sp} @var{n}: Insert Blank Lines
9878 @findex sp @r{(line spacing)}
9879 @cindex Spaces (blank lines)
9881 @cindex Line spacing
9883 A line beginning with and containing only @code{@@sp @var{n}}
9884 generates @var{n} blank lines of space in both the printed manual and
9885 the Info file. @code{@@sp} also forces a paragraph break. For
9893 generates two blank lines.
9895 The @code{@@sp} command is most often used in the title page.@refill
9898 @c node br, page, sp, Breaks
9899 @comment node-name, next, previous, up
9900 @c section @code{@@br}: Generate Paragraph Breaks
9901 @findex br @r{(paragraph breaks)}
9902 @cindex Paragraph breaks
9903 @cindex Breaks in a paragraph
9905 The @code{@@br} command forces a paragraph break. It inserts a blank
9906 line. You can use the command within or at the end of a line. If
9907 used within a line, the @code{@@br@{@}} command must be followed by
9908 left and right braces (as shown here) to mark the end of the
9916 This line @@br@{@}contains and is ended by paragraph breaks@@br
9917 and is followed by another line.
9928 contains and is ended by paragraph breaks
9930 and is followed by another line.
9934 The @code{@@br} command is seldom used.
9937 @node page, group, sp, Breaks
9938 @comment node-name, next, previous, up
9939 @section @code{@@page}: Start a New Page
9943 A line containing only @code{@@page} starts a new page in a printed
9944 manual. The command has no effect on Info files since they are not
9945 paginated. An @code{@@page} command is often used in the @code{@@titlepage}
9946 section of a Texinfo file to start the copyright page.@refill
9948 @node group, need, page, Breaks
9949 @comment node-name, next, previous, up
9950 @section @code{@@group}: Prevent Page Breaks
9951 @cindex Group (hold text together vertically)
9952 @cindex Holding text together vertically
9953 @cindex Vertically holding text together
9956 The @code{@@group} command (on a line by itself) is used inside an
9957 @code{@@example} or similar construct to begin an unsplittable vertical
9958 group, which will appear entirely on one page in the printed output.
9959 The group is terminated by a line containing only @code{@@end group}.
9960 These two lines produce no output of their own, and in the Info file
9961 output they have no effect at all.@refill
9963 @c Once said that these environments
9964 @c turn off vertical spacing between ``paragraphs''.
9965 @c Also, quotation used to work, but doesn't in texinfo-2.72
9966 Although @code{@@group} would make sense conceptually in a wide
9967 variety of contexts, its current implementation works reliably only
9968 within @code{@@example} and variants, and within @code{@@display},
9969 @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
9970 @xref{Quotations and Examples}. (What all these commands have in
9971 common is that each line of input produces a line of output.) In
9972 other contexts, @code{@@group} can cause anomalous vertical
9976 This formatting requirement means that you should write:
9989 with the @code{@@group} and @code{@@end group} commands inside the
9990 @code{@@example} and @code{@@end example} commands.
9992 The @code{@@group} command is most often used to hold an example
9993 together on one page. In this Texinfo manual, more than 100 examples
9994 contain text that is enclosed between @code{@@group} and @code{@@end
9997 If you forget to end a group, you may get strange and unfathomable
9998 error messages when you run @TeX{}. This is because @TeX{} keeps
9999 trying to put the rest of the Texinfo file onto the one page and does
10000 not start to generate error messages until it has processed
10001 considerable text. It is a good rule of thumb to look for a missing
10002 @code{@@end group} if you get incomprehensible error messages in
10005 @node need, , group, Breaks
10006 @comment node-name, next, previous, up
10007 @section @code{@@need @var{mils}}: Prevent Page Breaks
10008 @cindex Need space at page bottom
10011 A line containing only @code{@@need @var{n}} starts
10012 a new page in a printed manual if fewer than @var{n} mils (thousandths
10013 of an inch) remain on the current page. Do not use
10014 braces around the argument @var{n}. The @code{@@need} command has no
10015 effect on Info files since they are not paginated.@refill
10018 This paragraph is preceded by an @code{@@need} command that tells
10019 @TeX{} to start a new page if fewer than 800 mils (eight-tenths
10020 inch) remain on the page. It looks like this:@refill
10025 This paragraph is preceded by @dots{}
10029 The @code{@@need} command is useful for preventing orphans (single
10030 lines at the bottoms of printed pages).@refill
10032 @node Definition Commands, Footnotes, Breaks, Top
10033 @chapter Definition Commands
10034 @cindex Definition commands
10036 The @code{@@deffn} command and the other @dfn{definition commands}
10037 enable you to describe functions, variables, macros, commands, user
10038 options, special forms and other such artifacts in a uniform
10041 In the Info file, a definition causes the entity
10042 category---`Function', `Variable', or whatever---to appear at the
10043 beginning of the first line of the definition, followed by the
10044 entity's name and arguments. In the printed manual, the command
10045 causes @TeX{} to print the entity's name and its arguments on the left
10046 margin and print the category next to the right margin. In both
10047 output formats, the body of the definition is indented. Also, the
10048 name of the entity is entered into the appropriate index:
10049 @code{@@deffn} enters the name into the index of functions,
10050 @code{@@defvr} enters it into the index of variables, and so
10053 A manual need not and should not contain more than one definition for
10054 a given name. An appendix containing a summary should use
10055 @code{@@table} rather than the definition commands.@refill
10058 * Def Cmd Template:: How to structure a description using a
10059 definition command.
10060 * Optional Arguments:: How to handle optional and repeated arguments.
10061 * deffnx:: How to group two or more `first' lines.
10062 * Def Cmds in Detail:: All the definition commands.
10063 * Def Cmd Conventions:: Conventions for writing definitions.
10064 * Sample Function Definition::
10067 @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10068 @section The Template for a Definition
10069 @cindex Definition template
10070 @cindex Template for a definition
10072 The @code{@@deffn} command is used for definitions of entities that
10073 resemble functions. To write a definition using the @code{@@deffn}
10074 command, write the @code{@@deffn} command at the beginning of a line
10075 and follow it on the same line by the category of the entity, the name
10076 of the entity itself, and its arguments (if any). Then write the body
10077 of the definition on succeeding lines. (You may embed examples in the
10078 body.) Finally, end the definition with an @code{@@end deffn} command
10079 written on a line of its own. (The other definition commands follow
10080 the same format.)@refill
10082 The template for a definition looks like this:
10086 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10087 @var{body-of-definition}
10098 @@deffn Command forward-word count
10099 This command moves point forward @@var@{count@} words
10100 (or backward if @@var@{count@} is negative). @dots{}
10109 @deffn Command forward-word count
10110 This function moves point forward @var{count} words
10111 (or backward if @var{count} is negative). @dots{}
10115 Capitalize the category name like a title. If the name of the
10116 category contains spaces, as in the phrase `Interactive Command',
10117 write braces around it. For example:@refill
10121 @@deffn @{Interactive Command@} isearch-forward
10128 Otherwise, the second word will be mistaken for the name of the
10131 Some of the definition commands are more general than others. The
10132 @code{@@deffn} command, for example, is the general definition command
10133 for functions and the like---for entities that may take arguments. When
10134 you use this command, you specify the category to which the entity
10135 belongs. The @code{@@deffn} command possesses three predefined,
10136 specialized variations, @code{@@defun}, @code{@@defmac}, and
10137 @code{@@defspec}, that specify the category for you: ``Function'',
10138 ``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
10139 is an entity much like a function.) The @code{@@defvr} command also is
10140 accompanied by several predefined, specialized variations for describing
10141 particular kinds of variables.@refill
10143 The template for a specialized definition, such as @code{@@defun}, is
10144 similar to the template for a generalized definition, except that you
10145 do not need to specify the category:@refill
10149 @@defun @var{name} @var{arguments}@dots{}
10150 @var{body-of-definition}
10160 @@defun buffer-end flag
10161 This function returns @@code@{(point-min)@} if @@var@{flag@}
10162 is less than 1, @@code@{(point-max)@} otherwise.
10172 @defun buffer-end flag
10173 This function returns @code{(point-min)} if @var{flag} is less than 1,
10174 @code{(point-max)} otherwise. @dots{}
10179 @xref{Sample Function Definition, Sample Function Definition, A Sample
10180 Function Definition}, for a more detailed example of a function
10181 definition, including the use of @code{@@example} inside the
10184 The other specialized commands work like @code{@@defun}.@refill
10186 @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10187 @section Optional and Repeated Arguments
10188 @cindex Optional and repeated arguments
10189 @cindex Repeated and optional arguments
10190 @cindex Arguments, repeated and optional
10191 @cindex Syntax, optional & repeated arguments
10192 @cindex Meta-syntactic chars for arguments
10194 Some entities take optional or repeated arguments, which may be
10195 specified by a distinctive glyph that uses square brackets and
10196 ellipses. For @w{example}, a special form often breaks its argument list
10197 into separate arguments in more complicated ways than a
10198 straightforward function.@refill
10201 An argument enclosed within square brackets is optional.
10203 @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
10204 @var{optional-arg} is optional.
10205 An argument followed by an ellipsis is optional
10206 and may be repeated more than once.
10207 @c This is consistent with Emacs Lisp Reference manual
10208 Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
10209 Parentheses are used when several arguments are grouped
10210 into additional levels of list structure in Lisp.
10212 @c The following looks better in Info (no `r', `samp' and `code'):
10214 An argument enclosed within square brackets is optional.
10215 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10216 An argument followed by an ellipsis is optional
10217 and may be repeated more than once.
10218 @c This is consistent with Emacs Lisp Reference manual
10219 Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10220 Parentheses are used when several arguments are grouped
10221 into additional levels of list structure in Lisp.
10224 Here is the @code{@@defspec} line of an example of an imaginary
10225 special form:@refill
10228 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10236 In this example, the arguments @var{from} and @var{to} are optional,
10237 but must both be present or both absent. If they are present,
10238 @var{inc} may optionally be specified as well. These arguments are
10239 grouped with the argument @var{var} into a list, to distinguish them
10240 from @var{body}, which includes all remaining elements of the
10243 In a Texinfo source file, this @code{@@defspec} line is written like
10244 this (except it would not be split over two lines, as it is in this
10249 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10250 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10255 The function is listed in the Command and Variable Index under
10256 @samp{foobar}.@refill
10258 @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10259 @section Two or More `First' Lines
10260 @cindex Two `First' Lines for @code{@@deffn}
10261 @cindex Grouping two definitions together
10262 @cindex Definitions grouped together
10265 To create two or more `first' or header lines for a definition, follow
10266 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10267 The @code{@@deffnx} command works exactly like @code{@@deffn}
10268 except that it does not generate extra vertical white space between it
10269 and the preceding line.@refill
10276 @@deffn @{Interactive Command@} isearch-forward
10277 @@deffnx @{Interactive Command@} isearch-backward
10278 These two search commands are similar except @dots{}
10286 @deffn {Interactive Command} isearch-forward
10287 @deffnx {Interactive Command} isearch-backward
10288 These two search commands are similar except @dots{}
10291 Each of the other definition commands has an `x' form: @code{@@defunx},
10292 @code{@@defvrx}, @code{@@deftypefunx}, etc.
10294 The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10296 @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10297 @section The Definition Commands
10299 Texinfo provides more than a dozen definition commands, all of which
10300 are described in this section.@refill
10302 The definition commands automatically enter the name of the entity in
10303 the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10304 and @code{@@defmac} enter function names in the index of functions;
10305 @code{@@defvr} and @code{@@defvar} enter variable names in the index
10306 of variables.@refill
10308 Although the examples that follow mostly illustrate Lisp, the commands
10309 can be used for other programming languages.@refill
10312 * Functions Commands:: Commands for functions and similar entities.
10313 * Variables Commands:: Commands for variables and similar entities.
10314 * Typed Functions:: Commands for functions in typed languages.
10315 * Typed Variables:: Commands for variables in typed languages.
10316 * Abstract Objects:: Commands for object-oriented programming.
10317 * Data Types:: The definition command for data types.
10320 @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10321 @subsection Functions and Similar Entities
10323 This section describes the commands for describing functions and similar
10328 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10329 The @code{@@deffn} command is the general definition command for
10330 functions, interactive commands, and similar entities that may take
10331 arguments. You must choose a term to describe the category of entity
10332 being defined; for example, ``Function'' could be used if the entity is
10333 a function. The @code{@@deffn} command is written at the beginning of a
10334 line and is followed on the same line by the category of entity being
10335 described, the name of this particular entity, and its arguments, if
10336 any. Terminate the definition with @code{@@end deffn} on a line of its
10340 For example, here is a definition:
10344 @@deffn Command forward-char nchars
10345 Move point forward @@var@{nchars@} characters.
10351 This shows a rather terse definition for a ``command'' named
10352 @code{forward-char} with one argument, @var{nchars}.
10354 @code{@@deffn} prints argument names such as @var{nchars} in italics or
10355 upper case, as if @code{@@var} had been used, because we think of these
10356 names as metasyntactic variables---they stand for the actual argument
10357 values. Within the text of the description, write an argument name
10358 explicitly with @code{@@var} to refer to the value of the argument. In
10359 the example above, we used @samp{@@var@{nchars@}} in this way.
10361 The template for @code{@@deffn} is:
10365 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10366 @var{body-of-definition}
10372 @item @@defun @var{name} @var{arguments}@dots{}
10373 The @code{@@defun} command is the definition command for functions.
10374 @code{@@defun} is equivalent to @samp{@@deffn Function
10383 @@defun set symbol new-value
10384 Change the value of the symbol @@var@{symbol@}
10385 to @@var@{new-value@}.
10391 shows a rather terse definition for a function @code{set} whose
10392 arguments are @var{symbol} and @var{new-value}. The argument names on
10393 the @code{@@defun} line automatically appear in italics or upper case as
10394 if they were enclosed in @code{@@var}. Terminate the definition with
10395 @code{@@end defun} on a line of its own.@refill
10401 @@defun @var{function-name} @var{arguments}@dots{}
10402 @var{body-of-definition}
10407 @code{@@defun} creates an entry in the index of functions.
10410 @item @@defmac @var{name} @var{arguments}@dots{}
10411 The @code{@@defmac} command is the definition command for macros.
10412 @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
10413 works like @code{@@defun}.@refill
10416 @item @@defspec @var{name} @var{arguments}@dots{}
10417 The @code{@@defspec} command is the definition command for special
10418 forms. (In Lisp, a special form is an entity much like a function,
10419 @pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.)
10420 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
10421 @dots{}} and works like @code{@@defun}.@refill
10424 @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
10425 @subsection Variables and Similar Entities
10427 Here are the commands for defining variables and similar
10432 @item @@defvr @var{category} @var{name}
10433 The @code{@@defvr} command is a general definition command for
10434 something like a variable---an entity that records a value. You must
10435 choose a term to describe the category of entity being defined; for
10436 example, ``Variable'' could be used if the entity is a variable.
10437 Write the @code{@@defvr} command at the beginning of a line and
10438 followed it on the same line by the category of the entity and the
10439 name of the entity.@refill
10441 Capitalize the category name like a title. If the name of the category
10442 contains spaces, as in the name ``User Option'', enclose it in braces.
10443 Otherwise, the second word will be mistaken for the name of the entity.
10448 @@defvr @{User Option@} fill-column
10449 This buffer-local variable specifies
10450 the maximum width of filled lines.
10456 Terminate the definition with @code{@@end defvr} on a line of its
10463 @@defvr @var{category} @var{name}
10464 @var{body-of-definition}
10469 @code{@@defvr} creates an entry in the index of variables for @var{name}.
10472 @item @@defvar @var{name}
10473 The @code{@@defvar} command is the definition command for variables.
10474 @code{@@defvar} is equivalent to @samp{@@defvr Variable
10492 @@defvar @var{name}
10493 @var{body-of-definition}
10498 @code{@@defvar} creates an entry in the index of variables for
10502 @item @@defopt @var{name}
10503 @cindex User options, marking
10504 The @code{@@defopt} command is the definition command for @dfn{user
10505 options}, i.e., variables intended for users to change according to
10506 taste; Emacs has many such (@pxref{Variables,,, xemacs, XEmacs User's
10507 Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
10508 Option@} @dots{}} and works like @code{@@defvar}.@refill
10512 @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
10513 @subsection Functions in Typed Languages
10515 The @code{@@deftypefn} command and its variations are for describing
10516 functions in languages in which you must declare types of variables and
10517 functions, such as C and C++.
10521 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
10522 The @code{@@deftypefn} command is the general definition command for
10523 functions and similar entities that may take arguments and that are
10524 typed. The @code{@@deftypefn} command is written at the beginning of
10525 a line and is followed on the same line by the category of entity
10526 being described, the type of the returned value, the name of this
10527 particular entity, and its arguments, if any.@refill
10535 @@deftypefn @{Library Function@} int foobar
10536 (int @@var@{foo@}, float @@var@{bar@})
10544 (where the text before the ``@dots{}'', shown above as two lines, would
10545 actually be a single line in a real Texinfo file) produces the following
10550 -- Library Function: int foobar (int FOO, float BAR)
10556 In a printed manual, it produces:
10559 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
10565 This means that @code{foobar} is a ``library function'' that returns an
10566 @code{int}, and its arguments are @var{foo} (an @code{int}) and
10567 @var{bar} (a @code{float}).@refill
10569 The argument names that you write in @code{@@deftypefn} are not subject
10570 to an implicit @code{@@var}---since the actual names of the arguments in
10571 @code{@@deftypefn} are typically scattered among data type names and
10572 keywords, Texinfo cannot find them without help. Instead, you must write
10573 @code{@@var} explicitly around the argument names. In the example
10574 above, the argument names are @samp{foo} and @samp{bar}.@refill
10576 The template for @code{@@deftypefn} is:@refill
10580 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
10581 @var{body-of-description}
10587 Note that if the @var{category} or @var{data type} is more than one
10588 word then it must be enclosed in braces to make it a single argument.@refill
10590 If you are describing a procedure in a language that has packages,
10591 such as Ada, you might consider using @code{@@deftypefn} in a manner
10592 somewhat contrary to the convention described in the preceding
10601 @@deftypefn stacks private push
10602 (@@var@{s@}:in out stack;
10603 @@var@{n@}:in integer)
10610 (The @code{@@deftypefn} arguments are shown split into three lines, but
10611 would be a single line in a real Texinfo file.)
10613 In this instance, the procedure is classified as belonging to the
10614 package @code{stacks} rather than classified as a `procedure' and its
10615 data type is described as @code{private}. (The name of the procedure
10616 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
10618 @code{@@deftypefn} creates an entry in the index of functions for
10621 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
10623 The @code{@@deftypefun} command is the specialized definition command
10624 for functions in typed languages. The command is equivalent to
10625 @samp{@@deftypefn Function @dots{}}.@refill
10633 @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
10640 produces the following in Info:
10644 -- Function: int foobar (int FOO, float BAR)
10652 and the following in a printed manual:
10655 @deftypefun int foobar (int @var{foo}, float @var{bar})
10666 @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
10667 @var{body-of-description}
10672 @code{@@deftypefun} creates an entry in the index of functions for
10678 @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
10679 @subsection Variables in Typed Languages
10681 Variables in typed languages are handled in a manner similar to
10682 functions in typed languages. @xref{Typed Functions}. The general
10683 definition command @code{@@deftypevr} corresponds to
10684 @code{@@deftypefn} and the specialized definition command
10685 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
10689 @item @@deftypevr @var{category} @var{data-type} @var{name}
10690 The @code{@@deftypevr} command is the general definition command for
10691 something like a variable in a typed language---an entity that records
10692 a value. You must choose a term to describe the category of the
10693 entity being defined; for example, ``Variable'' could be used if the
10694 entity is a variable.@refill
10696 The @code{@@deftypevr} command is written at the beginning of a line
10697 and is followed on the same line by the category of the entity
10698 being described, the data type, and the name of this particular
10707 @@deftypevr @{Global Flag@} int enable
10714 produces the following in Info:
10718 -- Global Flag: int enable
10725 and the following in a printed manual:
10728 @deftypevr {Global Flag} int enable
10738 @@deftypevr @var{category} @var{data-type} @var{name}
10739 @var{body-of-description}
10743 @code{@@deftypevr} creates an entry in the index of variables for
10747 @item @@deftypevar @var{data-type} @var{name}
10748 The @code{@@deftypevar} command is the specialized definition command
10749 for variables in typed languages. @code{@@deftypevar} is equivalent
10750 to @samp{@@deftypevr Variable @dots{}}.@refill
10758 @@deftypevar int fubar
10765 produces the following in Info:
10769 -- Variable: int fubar
10777 and the following in a printed manual:
10780 @deftypevar int fubar
10792 @@deftypevar @var{data-type} @var{name}
10793 @var{body-of-description}
10798 @code{@@deftypevar} creates an entry in the index of variables for
10802 @node Abstract Objects, Data Types, Typed Variables, Def Cmds in Detail
10803 @subsection Object-Oriented Programming
10805 Here are the commands for formatting descriptions about abstract
10806 objects, such as are used in object-oriented programming. A class is
10807 a defined type of abstract object. An instance of a class is a
10808 particular object that has the type of the class. An instance
10809 variable is a variable that belongs to the class but for which each
10810 instance has its own value.@refill
10812 In a definition, if the name of a class is truly a name defined in the
10813 programming system for a class, then you should write an @code{@@code}
10814 around it. Otherwise, it is printed in the usual text font.@refill
10818 @item @@defcv @var{category} @var{class} @var{name}
10819 The @code{@@defcv} command is the general definition command for
10820 variables associated with classes in object-oriented programming. The
10821 @code{@@defcv} command is followed by three arguments: the category of
10822 thing being defined, the class to which it belongs, and its
10827 @@defcv @{Class Option@} Window border-pattern
10834 illustrates how you would write the first line of a definition of the
10835 @code{border-pattern} class option of the class @code{Window}.@refill
10841 @@defcv @var{category} @var{class} @var{name}
10847 @code{@@defcv} creates an entry in the index of variables.
10850 @item @@defivar @var{class} @var{name}
10851 The @code{@@defivar} command is the definition command for instance
10852 variables in object-oriented programming. @code{@@defivar} is
10853 equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
10859 @@defivar @var{class} @var{instance-variable-name}
10860 @var{body-of-definition}
10865 @code{@@defivar} creates an entry in the index of variables.
10868 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
10869 The @code{@@defop} command is the general definition command for
10870 entities that may resemble methods in object-oriented programming.
10871 These entities take arguments, as functions do, but are associated
10872 with particular classes of objects.@refill
10874 For example, some systems have constructs called @dfn{wrappers} that
10875 are associated with classes as methods are, but that act more like
10876 macros than like functions. You could use @code{@@defop Wrapper} to
10877 describe one of these.@refill
10879 Sometimes it is useful to distinguish methods and @dfn{operations}.
10880 You can think of an operation as the specification for a method.
10881 Thus, a window system might specify that all window classes have a
10882 method named @code{expose}; we would say that this window system
10883 defines an @code{expose} operation on windows in general. Typically,
10884 the operation has a name and also specifies the pattern of arguments;
10885 all methods that implement the operation must accept the same
10886 arguments, since applications that use the operation do so without
10887 knowing which method will implement it.@refill
10889 Often it makes more sense to document operations than methods. For
10890 example, window application developers need to know about the
10891 @code{expose} operation, but need not be concerned with whether a
10892 given class of windows has its own method to implement this operation.
10893 To describe this operation, you would write:@refill
10896 @@defop Operation windows expose
10899 The @code{@@defop} command is written at the beginning of a line and
10900 is followed on the same line by the overall name of the category of
10901 operation, the name of the class of the operation, the name of the
10902 operation, and its arguments, if any.@refill
10910 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
10911 @var{body-of-definition}
10916 @code{@@defop} creates an entry, such as `@code{expose} on
10917 @code{windows}', in the index of functions.@refill
10919 @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
10921 The @code{@@defmethod} command is the definition command for methods
10922 in object-oriented programming. A method is a kind of function that
10923 implements an operation for a particular class of objects and its
10924 subclasses. In the Lisp Machine, methods actually were functions, but
10925 they were usually defined with @code{defmethod}.
10927 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
10928 The command is written at the beginning of a line and is followed by
10929 the name of the class of the method, the name of the method, and its
10930 arguments, if any.@refill
10938 @@defmethod @code{bar-class} bar-method argument
10945 illustrates the definition for a method called @code{bar-method} of
10946 the class @code{bar-class}. The method takes an argument.@refill
10952 @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
10953 @var{body-of-definition}
10958 @code{@@defmethod} creates an entry, such as `@code{bar-method} on
10959 @code{bar-class}', in the index of functions.@refill
10961 @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
10963 The @code{@@deftypemethod} command is the definition command for methods
10964 in object-oriented typed languages, such as C++ and Java. It is similar
10965 to the @code{@@defmethod} command with the addition of the
10966 @var{data-type} parameter to specify the return type of the method.
10971 @node Data Types, , Abstract Objects, Def Cmds in Detail
10972 @subsection Data Types
10974 Here is the command for data types:@refill
10978 @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
10979 The @code{@@deftp} command is the generic definition command for data
10980 types. The command is written at the beginning of a line and is
10981 followed on the same line by the category, by the name of the type
10982 (which is a word like @code{int} or @code{float}), and then by names of
10983 attributes of objects of that type. Thus, you could use this command
10984 for describing @code{int} or @code{float}, in which case you could use
10985 @code{data type} as the category. (A data type is a category of
10986 certain objects for purposes of deciding which operations can be
10987 performed on them.)@refill
10989 In Lisp, for example, @dfn{pair} names a particular data
10990 type, and an object of that type has two slots called the
10991 @sc{car} and the @sc{cdr}. Here is how you would write the first line
10992 of a definition of @code{pair}.@refill
10996 @@deftp @{Data type@} pair car cdr
11007 @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11008 @var{body-of-definition}
11013 @code{@@deftp} creates an entry in the index of data types.
11016 @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11017 @section Conventions for Writing Definitions
11018 @cindex Definition conventions
11019 @cindex Conventions for writing definitions
11021 When you write a definition using @code{@@deffn}, @code{@@defun}, or
11022 one of the other definition commands, please take care to use
11023 arguments that indicate the meaning, as with the @var{count} argument
11024 to the @code{forward-word} function. Also, if the name of an argument
11025 contains the name of a type, such as @var{integer}, take care that the
11026 argument actually is of that type.@refill
11028 @node Sample Function Definition, , Def Cmd Conventions, Definition Commands
11029 @section A Sample Function Definition
11030 @cindex Function definitions
11031 @cindex Command definitions
11032 @cindex Macro definitions
11033 @cindex Sample function definition
11035 A function definition uses the @code{@@defun} and @code{@@end defun}
11036 commands. The name of the function follows immediately after the
11037 @code{@@defun} command and it is followed, on the same line, by the
11038 parameter list.@refill
11040 Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp
11044 @defun apply function &rest arguments
11045 @code{apply} calls @var{function} with @var{arguments}, just
11046 like @code{funcall} but with one difference: the last of
11047 @var{arguments} is a list of arguments to give to
11048 @var{function}, rather than a single argument. We also say
11049 that this list is @dfn{appended} to the other arguments.
11051 @code{apply} returns the result of calling @var{function}.
11052 As with @code{funcall}, @var{function} must either be a Lisp
11053 function or a primitive function; special forms and macros
11054 do not make sense in @code{apply}.
11060 @error{} Wrong type argument: listp, z
11061 (apply '+ 1 2 '(3 4))
11063 (apply '+ '(1 2 3 4))
11066 (apply 'append '((a b c) nil (x y z) nil))
11067 @result{} (a b c x y z)
11070 An interesting example of using @code{apply} is found in the description
11071 of @code{mapcar}.@refill
11076 In the Texinfo source file, this example looks like this:
11080 @@defun apply function &rest arguments
11082 @@code@{apply@} calls @@var@{function@} with
11083 @@var@{arguments@}, just like @@code@{funcall@} but with one
11084 difference: the last of @@var@{arguments@} is a list of
11085 arguments to give to @@var@{function@}, rather than a single
11086 argument. We also say that this list is @@dfn@{appended@}
11087 to the other arguments.
11091 @@code@{apply@} returns the result of calling
11092 @@var@{function@}. As with @@code@{funcall@},
11093 @@var@{function@} must either be a Lisp function or a
11094 primitive function; special forms and macros do not make
11095 sense in @@code@{apply@}.
11103 @@error@{@} Wrong type argument: listp, z
11104 (apply '+ 1 2 '(3 4))
11106 (apply '+ '(1 2 3 4))
11109 (apply 'append '((a b c) nil (x y z) nil))
11110 @@result@{@} (a b c x y z)
11115 An interesting example of using @@code@{apply@} is found
11116 in the description of @@code@{mapcar@}.@@refill
11122 In this manual, this function is listed in the Command and Variable
11123 Index under @code{apply}.@refill
11125 Ordinary variables and user options are described using a format like
11126 that for functions except that variables do not take arguments.
11129 @node Footnotes, Conditionals, Definition Commands, Top
11134 A @dfn{footnote} is for a reference that documents or elucidates the
11135 primary text.@footnote{A footnote should complement or expand upon
11136 the primary text, but a reader should not need to read a footnote to
11137 understand the primary text. For a thorough discussion of footnotes,
11138 see @cite{The Chicago Manual of Style}, which is published by the
11139 University of Chicago Press.}@refill
11142 * Footnote Commands:: How to write a footnote in Texinfo.
11143 * Footnote Styles:: Controlling how footnotes appear in Info.
11146 @node Footnote Commands, Footnote Styles, Footnotes, Footnotes
11147 @section Footnote Commands
11149 In Texinfo, footnotes are created with the @code{@@footnote} command.
11150 This command is followed immediately by a left brace, then by the text
11151 of the footnote, and then by a terminating right brace. Footnotes may
11152 be of any length (they will be broken across pages if necessary), but
11153 are usually short. The template is:
11156 ordinary text@@footnote@{@var{text of footnote}@}
11159 As shown here, the @code{@@footnote} command should come right after the
11160 text being footnoted, with no intervening space; otherwise, the
11161 formatters the footnote mark might end up starting up a line.
11163 For example, this clause is followed by a sample
11164 footnote@footnote{Here is the sample footnote.}; in the Texinfo
11165 source, it looks like this:@refill
11168 @dots{}a sample footnote@@footnote@{Here is the sample
11169 footnote.@}; in the Texinfo source@dots{}
11172 @strong{Warning:} Don't use footnotes in the argument of the
11173 @code{@@item} command for a @code{@@table} table. This doesn't work, and
11174 because of limitations of @TeX{}, there is no way to fix it. You must
11175 put the footnote into the body text of the table.
11177 In a printed manual or book, the reference mark for a footnote is a
11178 small, superscripted number; the text of the footnote appears at the
11179 bottom of the page, below a horizontal line.@refill
11181 In Info, the reference mark for a footnote is a pair of parentheses
11182 with the footnote number between them, like this: @samp{(1)}.@refill
11185 @node Footnote Styles, , Footnote Commands, Footnotes
11186 @section Footnote Styles
11188 Info has two footnote styles, which determine where the text of the
11189 footnote is located:@refill
11192 @cindex @samp{@r{End}} node footnote style
11194 In the `End' node style, all the footnotes for a single node
11195 are placed at the end of that node. The footnotes are separated from
11196 the rest of the node by a line of dashes with the word
11197 @samp{Footnotes} within it. Each footnote begins with an
11198 @samp{(@var{n})} reference mark.@refill
11202 Here is an example of a single footnote in the end of node style:@refill
11206 --------- Footnotes ---------
11208 (1) Here is a sample footnote.
11212 @cindex @samp{@r{Separate}} footnote style
11214 In the `Separate' node style, all the footnotes for a single
11215 node are placed in an automatically constructed node of
11216 their own. In this style, a ``footnote reference'' follows
11217 each @samp{(@var{n})} reference mark in the body of the
11218 node. The footnote reference is actually a cross reference
11219 which you use to reach the footnote node.@refill
11221 The name of the node containing the footnotes is constructed
11222 by appending @w{@samp{-Footnotes}} to the name of the node
11223 that contains the footnotes. (Consequently, the footnotes'
11224 node for the @file{Footnotes} node is
11225 @w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
11226 `Up' node pointer that leads back to its parent node.@refill
11229 Here is how the first footnote in this manual looks after being
11230 formatted for Info in the separate node style:@refill
11234 File: texinfo.info Node: Overview-Footnotes, Up: Overview
11236 (1) Note that the first syllable of "Texinfo" is
11237 pronounced like "speck", not "hex". @dots{}
11242 A Texinfo file may be formatted into an Info file with either footnote
11245 @findex footnotestyle
11246 Use the @code{@@footnotestyle} command to specify an Info file's
11247 footnote style. Write this command at the beginning of a line followed
11248 by an argument, either @samp{end} for the end node style or
11249 @samp{separate} for the separate node style.
11255 @@footnotestyle end
11260 @@footnotestyle separate
11263 Write an @code{@@footnotestyle} command before or shortly after the
11264 end-of-header line at the beginning of a Texinfo file. (If you
11265 include the @code{@@footnotestyle} command between the start-of-header
11266 and end-of-header lines, the region formatting commands will format
11267 footnotes as specified.)@refill
11269 If you do not specify a footnote style, the formatting commands use
11270 their default style. Currently, @code{texinfo-format-buffer} and
11271 @code{texinfo-format-region} use the `separate' style and
11272 @code{makeinfo} uses the `end' style.@refill
11274 @c !!! note: makeinfo's --footnote-style option overrides footnotestyle
11276 If you use @code{makeinfo} to create the Info file, the
11277 @samp{--footnote-style} option determines which style is used,
11278 @samp{end} for the end of node style or @samp{separate} for the
11279 separate node style. Thus, to format the Texinfo manual in the
11280 separate node style, you would use the following shell command:@refill
11283 makeinfo --footnote-style=separate texinfo.texi
11287 To format the Texinfo manual in the end of node style, you would
11291 makeinfo --footnote-style=end texinfo.texi
11295 If you use @code{texinfo-format-buffer} or
11296 @code{texinfo-format-region} to create the Info file, the value of the
11297 @code{texinfo-footnote-style} variable controls the footnote style.
11298 It can be either @samp{"separate"} for the separate node style or
11299 @samp{"end"} for the end of node style. (You can change the value of
11300 this variable with the @kbd{M-x edit-options} command (@pxref{Edit
11301 Options, , Editing Variable Values, xemacs, XEmacs User's Manual}), or
11302 with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
11303 and Setting Variables, xemacs, XEmacs User's Manual}).@refill
11305 The @code{texinfo-footnote-style} variable also controls the style if
11306 you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
11307 command in Emacs.@refill
11309 This chapter contains two footnotes.@refill
11312 @node Conditionals, Macros, Footnotes, Top
11313 @comment node-name, next, previous, up
11314 @chapter Conditionally Visible Text
11315 @cindex Conditionally visible text
11316 @cindex Text, conditionally visible
11317 @cindex Visibility of conditional text
11318 @cindex If text conditionally visible
11320 Sometimes it is good to use different text for a printed manual and
11321 its corresponding Info file. In this case, you can use the
11322 @dfn{conditional commands} to specify which text is for the printed manual
11323 and which is for the Info file.@refill
11326 * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
11327 * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
11328 * Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
11329 * set clear value:: Designating which text to format (for
11330 all output formats); and how to set a
11331 flag to a string that you can insert.
11334 @node Conditional Commands, Conditional Not Commands, Conditionals, Conditionals
11336 @heading Conditional Commands
11340 @code{@@ifinfo} begins segments of text that should be ignored
11342 typesets the printed manual. The segment of text appears only
11344 The @code{@@ifinfo} command should appear on a line by itself; end
11345 the Info-only text with a line containing @code{@@end ifinfo} by
11346 itself. At the beginning of a Texinfo file, the Info permissions are
11347 contained within a region marked by @code{@@ifinfo} and @code{@@end
11348 ifinfo}. (@xref{Info Summary and Permissions}.)@refill
11352 The @code{@@iftex} and @code{@@end iftex} commands are similar to the
11353 @code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
11354 specify text that will appear in the printed manual but not in the Info
11355 file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
11356 specify text to appear only in HTML output.@refill
11362 This text will appear only in the printed manual.
11365 However, this text will appear only in Info.
11370 The preceding example produces the following line:
11372 This text will appear only in the printed manual.
11375 However, this text will appear only in Info.
11379 Note how you only see one of the two lines, depending on whether you
11380 are reading the Info version or the printed version of this
11383 The @code{@@titlepage} command is a special variant of @code{@@iftex} that
11384 is used for making the title and copyright pages of the printed
11385 manual. (@xref{titlepage, , @code{@@titlepage}}.) @refill
11388 @node Conditional Not Commands, Raw Formatter Commands, Conditional Commands, Conditionals
11389 @section Conditional Not Commands
11394 You can specify text to be included in any output format @emph{other}
11395 than some given one with the @code{@@ifnot@dots{}} commands:
11397 @@ifnothtml @dots{} @@end ifnothtml
11398 @@ifnotinfo @dots{} @@end ifnotinfo
11399 @@ifnottex @dots{} @@end ifnottex
11402 (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11403 actually appear on lines by themselves.)
11405 If the output file is not being made for the given format, the region is
11406 included. Otherwise, it is ignored.
11408 The regions delimited by these commands are ordinary Texinfo source as
11409 with @code{@@iftex}, not raw formatter source as with @code{@@tex}.
11412 @node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals
11413 @section Raw Formatter Commands
11414 @cindex @TeX{} commands, using ordinary
11415 @cindex HTML commands, using ordinary
11416 @cindex Raw formatter commands
11417 @cindex Ordinary @TeX{} commands, using
11418 @cindex Ordinary HTML commands, using
11419 @cindex Commands using raw @TeX{}
11420 @cindex Commands using raw HTML
11421 @cindex plain @TeX{}
11423 Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11424 can embed some raw @TeX{} commands. Info will ignore these commands
11425 since they are only in that part of the file which is seen by @TeX{}.
11426 You can write the @TeX{} commands as you would write them in a normal
11427 @TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11428 with an @samp{@@}. For example, in the @code{@@titlepage} section of a
11429 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11430 the copyright page. (The @code{@@titlepage} command causes Info to
11431 ignore the region automatically, as it does with the @code{@@iftex}
11434 However, many features of plain @TeX{} will not work, as they are
11435 overridden by Texinfo features.
11438 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11439 commands, by delineating a region with the @code{@@tex} and @code{@@end
11440 tex} commands. (The @code{@@tex} command also causes Info to ignore the
11441 region, like the @code{@@iftex} command.) The sole exception is that
11442 @code{@@} chracter still introduces a command, so that @code{@@end tex}
11443 can be recognized properly.
11445 @cindex Mathematical expressions
11446 For example, here is a mathematical expression written in
11451 $$ \chi^2 = \sum_@{i=1@}^N
11452 \left (y_i - (a + b x_i)
11453 \over \sigma_i\right)^2 $$
11458 The output of this example will appear only in a printed manual. If
11459 you are reading this in Info, you will not see the equation that appears
11460 in the printed manual.
11462 In a printed manual, the above expression looks like
11467 $$ \chi^2 = \sum_{i=1}^N
11468 \left(y_i - (a + b x_i)
11469 \over \sigma_i\right)^2 $$
11474 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11475 a region to be included in HTML output only, and @code{@@html @dots{}
11476 @@end ifhtml} for a region of raw HTML (again, except that @code{@@} is
11477 still the escape character, so the @code{@@end} command can be
11481 @node set clear value, , Raw Formatter Commands, Conditionals
11482 @comment node-name, next, previous, up
11483 @section @code{@@set}, @code{@@clear}, and @code{@@value}
11485 You can direct the Texinfo formatting commands to format or ignore parts
11486 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11487 and @code{@@ifclear} commands.@refill
11489 In addition, you can use the @code{@@set @var{flag}} command to set the
11490 value of @var{flag} to a string of characters; and use
11491 @code{@@value@{@var{flag}@}} to insert that string. You can use
11492 @code{@@set}, for example, to set a date and use @code{@@value} to
11493 insert the date in several places in the Texinfo file.@refill
11496 * ifset ifclear:: Format a region if a flag is set.
11497 * value:: Replace a flag with a string.
11498 * value Example:: An easy way to update edition information.
11502 @node ifset ifclear, value, set clear value, set clear value
11503 @subsection @code{@@ifset} and @code{@@ifclear}
11506 When a @var{flag} is set, the Texinfo formatting commands format text
11507 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
11508 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
11509 commands do @emph{not} format the text.
11511 Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a
11512 @var{flag}; a @dfn{flag} can be any single word. The format for the
11513 command looks like this:@refill
11520 Write the conditionally formatted text between @code{@@ifset @var{flag}}
11521 and @code{@@end ifset} commands, like this:@refill
11526 @var{conditional-text}
11531 For example, you can create one document that has two variants, such as
11532 a manual for a `large' and `small' model:@refill
11535 You can use this machine to dig up shrubs
11536 without hurting them.
11541 It can also dig up fully grown trees.
11544 Remember to replant promptly @dots{}
11548 In the example, the formatting commands will format the text between
11549 @code{@@ifset large} and @code{@@end ifset} because the @code{large}
11550 flag is set.@refill
11553 Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear},
11554 a flag. Clearing a flag is the opposite of setting a flag. The
11555 command looks like this:@refill
11562 Write the command on a line of its own.
11564 When @var{flag} is cleared, the Texinfo formatting commands do
11565 @emph{not} format the text between @code{@@ifset @var{flag}} and
11566 @code{@@end ifset}; that text is ignored and does not appear in either
11567 printed or Info output.@refill
11569 For example, if you clear the flag of the preceding example by writing
11570 an @code{@@clear large} command after the @code{@@set large} command
11571 (but before the conditional text), then the Texinfo formatting commands
11572 ignore the text between the @code{@@ifset large} and @code{@@end ifset}
11573 commands. In the formatted output, that text does not appear; in both
11574 printed and Info output, you see only the lines that say, ``You can use
11575 this machine to dig up shrubs without hurting them. Remember to replant
11576 promptly @dots{}''.
11579 If a flag is cleared with an @code{@@clear @var{flag}} command, then
11580 the formatting commands format text between subsequent pairs of
11581 @code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
11582 is set with @code{@@set @var{flag}}, then the formatting commands do
11583 @emph{not} format text between an @code{@@ifclear} and an @code{@@end
11584 ifclear} command; rather, they ignore that text. An @code{@@ifclear}
11585 command looks like this:@refill
11588 @@ifclear @var{flag}
11592 In brief, the commands are:@refill
11595 @item @@set @var{flag}
11596 Tell the Texinfo formatting commands that @var{flag} is set.@refill
11598 @item @@clear @var{flag}
11599 Tell the Texinfo formatting commands that @var{flag} is cleared.@refill
11601 @item @@ifset @var{flag}
11602 If @var{flag} is set, tell the Texinfo formatting commands to format
11603 the text up to the following @code{@@end ifset} command.@refill
11605 If @var{flag} is cleared, tell the Texinfo formatting commands to
11606 ignore text up to the following @code{@@end ifset} command.@refill
11608 @item @@ifclear @var{flag}
11609 If @var{flag} is set, tell the Texinfo formatting commands to ignore
11610 the text up to the following @code{@@end ifclear} command.@refill
11612 If @var{flag} is cleared, tell the Texinfo formatting commands to
11613 format the text up to the following @code{@@end ifclear}
11617 @node value, value Example, ifset ifclear, set clear value
11618 @subsection @code{@@value}
11621 You can use the @code{@@set} command to specify a value for a flag,
11622 which is expanded by the @code{@@value} command. The value is a string
11625 Write the @code{@@set} command like this:
11628 @@set foo This is a string.
11632 This sets the value of @code{foo} to ``This is a string.''
11634 The Texinfo formatters replace an @code{@@value@{@var{flag}@}} command with
11635 the string to which @var{flag} is set.@refill
11637 Thus, when @code{foo} is set as shown above, the Texinfo formatters convert
11647 You can write an @code{@@value} command within a paragraph; but you
11648 must write an @code{@@set} command on a line of its own.
11650 If you write the @code{@@set} command like this:
11657 without specifying a string, the value of @code{foo} is an empty string.
11659 If you clear a previously set flag with an @code{@@clear @var{flag}}
11660 command, a subsequent @code{@@value@{flag@}} command is invalid and the
11661 string is replaced with an error message that says @samp{@{No value for
11664 For example, if you set @code{foo} as follows:@refill
11667 @@set how-much very, very, very
11671 then the formatters transform
11675 It is a @@value@{how-much@} wet day.
11677 It is a very, very, very wet day.
11688 then the formatters transform
11692 It is a @@value@{how-much@} wet day.
11694 It is a @{No value for "how-much"@} wet day.
11698 @node value Example, , value, set clear value
11699 @subsection @code{@@value} Example
11701 You can use the @code{@@value} command to limit the number of places you
11702 need to change when you record an update to a manual.
11703 Here is how it is done in @cite{The GNU Make Manual}:
11711 @@set EDITION 0.35 Beta
11712 @@set VERSION 3.63 Beta
11713 @@set UPDATED 14 August 1992
11714 @@set UPDATE-MONTH August 1992
11720 Write text for the first @code{@@ifinfo} section, for people reading the
11725 This is Edition @@value@{EDITION@},
11726 last updated @@value@{UPDATED@},
11727 of @@cite@{The GNU Make Manual@},
11728 for @@code@{make@}, Version @@value@{VERSION@}.
11734 Write text for the title page, for people reading the printed manual:
11735 @c List only the month and the year since that looks less fussy on a
11736 @c printed cover than a date that lists the day as well.
11741 @@subtitle A Program for Directing Recompilation
11742 @@subtitle Edition @@value@{EDITION@}, @dots{}
11743 @@subtitle @@value@{UPDATE-MONTH@}
11748 (On a printed cover, a date listing the month and the year looks less
11749 fussy than a date listing the day as well as the month and year.)
11753 Write text for the Top node, for people reading the Info file:
11757 This is Edition @@value@{EDITION@}
11758 of the @@cite@{GNU Make Manual@},
11759 last updated @@value@{UPDATED@}
11760 for @@code@{make@} Version @@value@{VERSION@}.
11765 After you format the manual, the text in the first @code{@@ifinfo}
11766 section looks like this:
11770 This is Edition 0.35 Beta, last updated 14 August 1992,
11771 of `The GNU Make Manual', for `make', Version 3.63 Beta.
11775 When you update the manual, change only the values of the flags; you do
11776 not need to rewrite the three sections.
11779 @node Macros, Format/Print Hardcopy, Conditionals, Top
11780 @chapter Macros: Defining New Texinfo Commands
11782 @cindex Defining new Texinfo commands
11783 @cindex New Texinfo commands, defining
11784 @cindex Texinfo commands, defining new
11785 @cindex User-defined Texinfo commands
11787 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
11788 sequence of text and/or existing commands (including other macros). The
11789 macro can have any number of @dfn{parameters}---text you supply each
11790 time you use the macro. (This has nothing to do with the
11791 @code{@@defmac} command, which is for documenting macros in the subject
11792 of the manual; @pxref{Def Cmd Template}.)
11795 * Defining Macros:: Both defining and undefining new commands.
11796 * Invoking Macros:: Using a macro, once you've defined it.
11800 @node Defining Macros, Invoking Macros, Macros, Macros
11801 @section Defining Macros
11802 @cindex Defining macros
11803 @cindex Macro definitions
11806 You use the Texinfo @code{@@macro} command to define a macro. For example:
11809 @@macro @var{macro-name}@{@var{param1}, @var{param2}, @dots{}@}
11810 @var{text} @dots{} \@var{param1}\ @dots{}
11814 The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
11815 arguments supplied when the macro is subsequently used in the document
11816 (see the next section).
11818 If a macro needs no parameters, you can define it either with an empty
11819 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
11822 @cindex Body of a macro
11823 @cindex Mutually recursive macros
11824 @cindex Recursion, mutual
11825 The definition or @dfn{body} of the macro can contain any Texinfo
11826 commands, including previously-defined macros. (It is not possible to
11827 have mutually recursive Texinfo macros.) In the body, instances of a
11828 parameter name surrounded by backslashes, as in @samp{\@var{param1}\} in
11829 the example above, are replaced by the corresponding argument from the
11833 @cindex Macros, undefining
11834 @cindex Undefining macros
11835 You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
11836 It is not an error to undefine a macro that is already undefined.
11844 @node Invoking Macros, , Defining Macros, Macros
11845 @section Invoking Macros
11846 @cindex Invoking macros
11847 @cindex Macro invocation
11849 After a macro is defined (see the previous section), you can use
11850 (@dfn{invoke}) it in your document like this:
11853 @@@var{macro-name} @{@var{arg1}, @var{arg2}, @dots{}@}
11857 and the result will be just as if you typed the body of
11858 @var{macro-name} at that spot. For example:
11861 @@macro foo @{p, q@}
11862 Together: \p\ & \q\.
11874 @cindex Backslash, and macros
11875 Thus, the arguments and parameters are separated by commas and delimited
11876 by braces; any whitespace after (but not before) a comma is ignored. To
11877 insert a comma, brace, or backslash in an argument, prepend a backslash,
11881 @@@var{macro-name} @{\\\@{\@}\,@}
11885 which will pass the (almost certainly error-producing) argument
11886 @samp{\@{@},} to @var{macro-name}.
11888 If the macro is defined to take a single argument, and is invoked
11889 without any braces, the entire rest of the line after the macro name is
11890 supplied as the argument. For example:
11907 @node Format/Print Hardcopy, Create an Info File, Macros, Top
11908 @comment node-name, next, previous, up
11909 @chapter Format and Print Hardcopy
11910 @cindex Format and print hardcopy
11911 @cindex Hardcopy, printing it
11912 @cindex Making a printed manual
11913 @cindex Sorting indices
11914 @cindex Indices, sorting
11915 @cindex @TeX{} index sorting
11918 There are three major shell commands for making a printed manual from a
11919 Texinfo file: one for converting the Texinfo file into a file that will be
11920 printed, a second for sorting indices, and a third for printing the
11921 formatted document. When you use the shell commands, you can either
11922 work directly in the operating system shell or work within a shell
11923 inside GNU Emacs.@refill
11925 If you are using GNU Emacs, you can use commands provided by Texinfo
11926 mode instead of shell commands. In addition to the three commands to
11927 format a file, sort the indices, and print the result, Texinfo mode
11928 offers key bindings for commands to recenter the output buffer, show the
11929 print queue, and delete a job from the print queue.@refill
11932 * Use TeX:: Use @TeX{} to format for hardcopy.
11933 * Format with tex/texindex:: How to format in a shell.
11934 * Format with texi2dvi:: A simpler way to use the shell.
11935 * Print with lpr:: How to print.
11936 * Within Emacs:: How to format and print from an Emacs shell.
11937 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
11938 * Compile-Command:: How to print using Emacs's compile command.
11939 * Requirements Summary:: @TeX{} formatting requirements summary.
11940 * Preparing for TeX:: What you need to do to use @TeX{}.
11941 * Overfull hboxes:: What are and what to do with overfull hboxes.
11942 * smallbook:: How to print small format books and manuals.
11943 * A4 Paper:: How to print on European A4 paper.
11944 * Cropmarks and Magnification:: How to print marks to indicate the size
11945 of pages and how to print scaled up output.
11948 @node Use TeX, Format with tex/texindex, Format/Print Hardcopy, Format/Print Hardcopy
11950 @heading Use @TeX{}
11953 The typesetting program called @TeX{} is used for formatting a Texinfo
11954 file. @TeX{} is a very powerful typesetting program and, if used right,
11955 does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
11956 @TeX{}}, for information on how to obtain @TeX{}.)
11958 The @code{makeinfo}, @code{texinfo-format-region}, and
11959 @code{texinfo-format-buffer} commands read the very same @@-commands
11960 in the Texinfo file as does @TeX{}, but process them differently to
11961 make an Info file; see @ref{Create an Info File}.@refill
11963 @node Format with tex/texindex, Format with texi2dvi, Use TeX, Format/Print Hardcopy
11964 @comment node-name, next, previous, up
11965 @section Format using @code{tex} and @code{texindex}
11966 @cindex Shell formatting with @code{tex} and @code{texindex}
11967 @cindex Formatting with @code{tex} and @code{texindex}
11970 Format the Texinfo file with the shell command @code{tex} followed by
11971 the name of the Texinfo file. For example:
11978 @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
11979 files containing information for indices, cross references, etc. The
11980 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
11981 any printe (see the following sections).
11984 The @code{tex} formatting command itself does not sort the indices; it
11985 writes an output file of unsorted index data. (The @code{texi2dvi}
11986 command automatically generates indices; see @ref{Format with texi2dvi,,
11987 Format using @code{texi2dvi}}.) To generate a printed index after
11988 running the @code{tex} command, you first need a sorted index to work
11989 from. The @code{texindex} command sorts indices. (The source file
11990 @file{texindex.c} comes as part of the standard Texinfo distribution,
11991 among other places.)@refill
11993 @cindex Names of index files
11994 The @code{tex} formatting command outputs unsorted index files under
11995 names that obey a standard convention: the name of your main input file
11996 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
11997 Web2c}) extension removed, followed by the two letter names of indices.
11998 For example, the raw index output files for the input file
11999 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
12000 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
12001 arguments to give to @code{texindex}.@refill
12006 Instead of specifying all the unsorted index file names explicitly, you
12007 can use @samp{??} as shell wildcards and give the command in this
12015 This command will run @code{texindex} on all the unsorted index files,
12016 including any that you have defined yourself using @code{@@defindex}
12017 or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
12018 even if there are similarly named files with two letter extensions
12019 that are not index files, such as @samp{foo.el}. The @code{texindex}
12020 command reports but otherwise ignores such files.)@refill
12022 For each file specified, @code{texindex} generates a sorted index file
12023 whose name is made by appending @samp{s} to the input file name. The
12024 @code{@@printindex} command knows to look for a file of that name
12025 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
12026 raw index output file.@refill
12028 After you have sorted the indices, you need to rerun the @code{tex}
12029 formatting command on the Texinfo file. This regenerates the DVI file,
12030 this time with up-to-date index entries.
12032 Finally, you may need to run @code{tex} one more time, to get the page
12033 numbers in the cross-references correct.
12035 To summarize, this is a four step process:
12039 Run @code{tex} on your Texinfo file. This generates a DVI file (with
12040 undefined cross-references and no indices), and the raw index files
12041 (with two letter extensions).
12044 Run @code{texindex} on the raw index files. This creates the
12045 corresponding sorted index files (with three letter extensions).
12048 Run @code{tex} again on your Texinfo file. This regenerates the DVI
12049 file, this time with indices and defined cross-references, but with page
12050 numbers for the cross-references from last time, generally incorrect.
12053 Run @code{tex} one last time. This time the correct page numbers are
12054 written for the cross-references.
12058 Alternatively, it's a one-step process: run @code{texi2dvi}.
12060 You need not run @code{texindex} each time after you run @code{tex}. If
12061 you do not, on the next run, the @code{tex} formatting command will use
12062 whatever sorted index files happen to exist from the previous use of
12063 @code{texindex}. This is usually ok while you are
12067 @node Format with texi2dvi, Print with lpr, Format with tex/texindex, Format/Print Hardcopy
12068 @comment node-name, next, previous, up
12069 @section Format using @code{texi2dvi}
12070 @pindex texi2dvi @r{(shell script)}
12072 The @code{texi2dvi} command automatically runs both @code{tex} and
12073 @code{texindex} as many times as necessary to produce a DVI file with
12074 up-to-date, sorted indices. It simplifies the
12075 @code{tex}---@code{texindex}---@code{tex} sequence described in the
12078 The syntax for @code{texi2dvi} is like this (where @samp{prompt$} is your
12079 shell prompt):@refill
12082 prompt$ @kbd{texi2dvi @var{filename}@dots{}}
12085 For a list of options, run @samp{texi2dvi --help}.
12088 @node Print with lpr, Within Emacs, Format with texi2dvi, Format/Print Hardcopy
12089 @comment node-name, next, previous, up
12090 @section Shell Print Using @code{lpr -d}
12091 @pindex lpr @r{(DVI print command)}
12093 The precise command to print a DVI file depends on your system
12094 installation, but @samp{lpr -d} is common. The command may require the
12095 DVI file name without any extension or with a @samp{.dvi}
12096 extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.)
12098 The following commands, for example, will (probably) suffice to sort the
12099 indices, format, and print the @cite{Bison Manual}:
12111 (Remember that the shell commands may be different at your site; but
12112 these are commonly used versions.)@refill
12115 Using the @code{texi2dvi} shell script, you simply need type:@refill
12119 texi2dvi bison.texinfo
12124 @node Within Emacs, Texinfo Mode Printing, Print with lpr, Format/Print Hardcopy
12125 @comment node-name, next, previous, up
12126 @section From an Emacs Shell
12127 @cindex Print, format from Emacs shell
12128 @cindex Format, print from Emacs shell
12129 @cindex Shell, format, print from
12130 @cindex Emacs shell, format, print from
12131 @cindex GNU Emacs shell, format, print from
12133 You can give formatting and printing commands from a shell within GNU
12134 Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
12135 shell, you can format and print the document. @xref{Format/Print
12136 Hardcopy, , Format and Print Hardcopy}, for details.@refill
12138 You can switch to and from the shell buffer while @code{tex} is
12139 running and do other editing. If you are formatting a long document
12140 on a slow machine, this can be very convenient.@refill
12142 You can also use @code{texi2dvi} from an Emacs shell. For example,
12143 here is how to use @code{texi2dvi} to format and print @cite{Using and
12144 Porting GNU CC} from a shell within Emacs:
12148 texi2dvi gcc.texinfo
12154 @xref{Texinfo Mode Printing}, for more information about formatting
12155 and printing in Texinfo mode.@refill
12158 @node Texinfo Mode Printing, Compile-Command, Within Emacs, Format/Print Hardcopy
12159 @section Formatting and Printing in Texinfo Mode
12160 @cindex Region printing in Texinfo mode
12161 @cindex Format and print in Texinfo mode
12162 @cindex Print and format in Texinfo mode
12164 Texinfo mode provides several predefined key commands for @TeX{}
12165 formatting and printing. These include commands for sorting indices,
12166 looking at the printer queue, killing the formatting job, and
12167 recentering the display of the buffer in which the operations
12172 @itemx M-x texinfo-tex-buffer
12173 Run @code{texi2dvi} on the current buffer.@refill
12176 @itemx M-x texinfo-tex-region
12177 Run @TeX{} on the current region.@refill
12180 @itemx M-x texinfo-texindex
12181 Sort the indices of a Texinfo file formatted with
12182 @code{texinfo-tex-region}.@refill
12185 @itemx M-x texinfo-tex-print
12186 Print a DVI file that was made with @code{texinfo-tex-region} or
12187 @code{texinfo-tex-buffer}.@refill
12190 @itemx M-x tex-show-print-queue
12191 Show the print queue.@refill
12194 @itemx M-x texinfo-delete-from-print-queue
12195 Delete a job from the print queue; you will be prompted for the job
12196 number shown by a preceding @kbd{C-c C-t C-q} command
12197 (@code{texinfo-show-tex-print-queue}).@refill
12200 @itemx M-x tex-kill-job
12201 Kill the currently running @TeX{} job started by
12202 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
12203 process running in the Texinfo shell buffer.@refill
12206 @itemx M-x texinfo-quit-job
12207 Quit a @TeX{} formatting job that has stopped because of an error by
12208 sending an @key{x} to it. When you do this, @TeX{} preserves a record
12209 of what it did in a @file{.log} file.@refill
12212 @itemx M-x tex-recenter-output-buffer
12213 Redisplay the shell buffer in which the @TeX{} printing and formatting
12214 commands are run to show its most recent output.@refill
12218 Thus, the usual sequence of commands for formatting a buffer is as
12219 follows (with comments to the right):@refill
12223 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
12224 C-c C-t C-p @r{Print the DVI file.}
12225 C-c C-t C-q @r{Display the printer queue.}
12229 The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
12230 called the @file{*tex-shell*}. The @code{texinfo-tex-command},
12231 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
12232 commands are all run in this shell.
12234 You can watch the commands operate in the @samp{*tex-shell*} buffer,
12235 and you can switch to and from and use the @samp{*tex-shell*} buffer
12236 as you would any other shell buffer.@refill
12239 The formatting and print commands depend on the values of several variables.
12240 The default values are:@refill
12244 @r{Variable} @r{Default value}
12246 texinfo-texi2dvi-command "texi2dvi"
12247 texinfo-tex-command "tex"
12248 texinfo-texindex-command "texindex"
12249 texinfo-delete-from-print-queue-command "lprm"
12250 texinfo-tex-trailer "@@bye"
12251 tex-start-of-header "%**start"
12252 tex-end-of-header "%**end"
12253 tex-dvi-print-command "lpr -d"
12254 tex-show-queue-command "lpq"
12258 You can change the values of these variables with the @kbd{M-x
12259 edit-options} command (@pxref{Edit Options, , Editing Variable Values,
12260 xemacs, XEmacs User's Manual}), with the @kbd{M-x set-variable} command
12261 (@pxref{Examining, , Examining and Setting Variables, xemacs, XEmacs
12262 User's Manual}), or with your @file{.emacs} initialization file
12263 (@pxref{Init File, , , xemacs, XEmacs User's Manual}).@refill
12265 @node Compile-Command, Requirements Summary, Texinfo Mode Printing, Format/Print Hardcopy
12266 @comment node-name, next, previous, up
12267 @section Using the Local Variables List
12268 @cindex Local variables
12269 @cindex Compile command for formatting
12270 @cindex Format with the compile command
12272 Yet another way to apply the @TeX{} formatting command to a Texinfo file
12273 is to put that command in a @dfn{local variables list} at the end of the
12274 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
12275 commands as a @code{compile-command} and have Emacs run it by typing
12276 @kbd{M-x compile}. This creates a special shell called the
12277 @file{*compilation*} buffer in which Emacs runs the compile command.
12278 For example, at the end of the @file{gdb.texinfo} file, after the
12279 @code{@@bye}, you could put the following:@refill
12284 compile-command: "texi2dvi gdb.texinfo"
12290 This technique is most often used by programmers who also compile programs
12291 this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill
12294 @node Requirements Summary, Preparing for TeX, Compile-Command, Format/Print Hardcopy
12295 @comment node-name, next, previous, up
12296 @section @TeX{} Formatting Requirements Summary
12297 @cindex Requirements for formatting
12298 @cindex Minimal requirements for formatting
12299 @cindex Formatting requirements
12301 Every Texinfo file that is to be input to @TeX{} must begin with a
12302 @code{\input} command and must contain an @code{@@setfilename} command:
12306 @@setfilename @var{arg-not-used-by-@@TeX@{@}}
12310 The first command instructs @TeX{} to load the macros it needs to
12311 process a Texinfo file and the second command opens auxiliary files.
12313 Every Texinfo file must end with a line that terminates @TeX{}'s
12314 processing and forces out unfinished pages:
12320 Strictly speaking, these lines are all a Texinfo file needs to be
12321 processed successfully by @TeX{}.
12323 Usually, however, the beginning includes an @code{@@settitle} command to
12324 define the title of the printed manual, an @code{@@setchapternewpage}
12325 command, a title page, a copyright page, and permissions. Besides an
12326 @code{@@bye}, the end of a file usually includes indices and a table of
12327 contents. (And of course most manuals contain a body of text as well.)
12330 For more information, see
12331 @ref{settitle, , @code{@@settitle}},
12332 @ref{setchapternewpage, , @code{@@setchapternewpage}},
12333 @ref{Headings, ,Page Headings},
12334 @ref{Titlepage & Copyright Page},
12335 @ref{Printing Indices & Menus}, and
12340 For more information, see@*
12341 @ref{settitle, , @code{@@settitle}},@*
12342 @ref{setchapternewpage, , @code{@@setchapternewpage}},@*
12343 @ref{Headings, ,Page Headings},@*
12344 @ref{Titlepage & Copyright Page},@*
12345 @ref{Printing Indices & Menus}, and@*
12350 @node Preparing for TeX, Overfull hboxes, Requirements Summary, Format/Print Hardcopy
12351 @comment node-name, next, previous, up
12352 @section Preparing to Use @TeX{}
12353 @cindex Preparing to use @TeX{}
12354 @cindex @TeX{} input initialization
12355 @cindex @code{TEXINPUTS} environment variable
12357 @cindex @b{.profile} initialization file
12358 @cindex @b{.cshrc} initialization file
12359 @cindex Initialization file for @TeX{} input
12361 @TeX{} needs to know where to find the @file{texinfo.tex} file that you
12362 have told it to input with the @samp{\input texinfo} command at the
12363 beginning of the first line. The @file{texinfo.tex} file tells @TeX{}
12364 how to handle @@-commands; it is included in all standard GNU
12367 @pindex texinfo.tex@r{, installing}
12368 Usually, the @file{texinfo.tex} file is put under the default directory
12369 that contains @TeX{} macros
12370 (@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when
12371 GNU Emacs or other GNU software is installed. In this case, @TeX{} will
12372 find the file and you do not need to do anything special.
12373 Alternatively, you can put @file{texinfo.tex} in the current directory
12374 when you run @TeX{}, and @TeX{} will find it there.
12376 @pindex epsf.tex@r{, installing}
12377 Also, you should install @file{epsf.tex} in the same place as
12378 @file{texinfo.tex}, if it is not already installed from another
12379 distribution. This file is needed to support the @code{@@image} command
12382 @pindex texinfo.cnf @r{installation}
12383 @cindex Customizing of @TeX{} for Texinfo
12384 @cindex Site-wide Texinfo configuration file
12385 Optionally, you may create an additional @file{texinfo.cnf}, and install
12386 it as well. This file is read by @TeX{} at the @code{@@setfilename}
12387 command (@pxref{setfilename,, @code{@@setfilename}}). You can put any
12388 commands you like there according to local site-wide conventions, and
12389 they will be read by @TeX{} when processing any Texinfo document. For
12390 example, if @file{texinfo.cnf} contains the a single line
12391 @samp{@@afourpaper} (@pxref{A4 Paper}), then all Texinfo documents will
12392 be processed with that page size in effect. If you have nothing to put
12393 in @file{texinfo.cnf}, you do not need to create it.
12396 If neither of the above locations for these system files suffice for
12397 you, you can specify the directories explicitly. For
12398 @file{texinfo.tex}, you can do this by writing the complete path for the
12399 file after the @code{\input} command. Another way, that works for both
12400 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
12401 might read), is to set the @code{TEXINPUTS} environment variable in your
12402 @file{.cshrc} or @file{.profile} file.
12404 Which you use of @file{.cshrc} or @file{.profile} depends on
12405 whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
12406 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
12407 command interpreter. The latter read the @file{.cshrc} file for
12408 initialization information, and the former read @file{.profile}.
12410 In a @file{.cshrc} file, you could use the following @code{csh} command
12414 setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
12418 In a @file{.profile} file, you could use the following @code{sh} command
12423 TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
12429 This would cause @TeX{} to look for @file{\input} file first in the current
12430 directory, indicated by the @samp{.}, then in a hypothetical user's
12431 @file{me/mylib} directory, and finally in a system directory.
12434 @node Overfull hboxes, smallbook, Preparing for TeX, Format/Print Hardcopy
12435 @comment node-name, next, previous, up
12436 @section Overfull ``hboxes''
12437 @cindex Overfull @samp{hboxes}
12438 @cindex @samp{hboxes}, overfull
12439 @cindex Final output
12441 @TeX{} is sometimes unable to typeset a line without extending it into
12442 the right margin. This can occur when @TeX{} comes upon what it
12443 interprets as a long word that it cannot hyphenate, such as an
12444 electronic mail network address or a very long title. When this
12445 happens, @TeX{} prints an error message like this:@refill
12448 Overfull \hbox (20.76302pt too wide)
12452 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
12453 The backslash, @samp{\}, is the @TeX{} equivalent of @samp{@@}.)@refill
12455 @TeX{} also provides the line number in the Texinfo source file and
12456 the text of the offending line, which is marked at all the places that
12457 @TeX{} knows how to hyphenate words.
12458 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
12459 for more information about typesetting errors.@refill
12461 If the Texinfo file has an overfull hbox, you can rewrite the sentence
12462 so the overfull hbox does not occur, or you can decide to leave it. A
12463 small excursion into the right margin often does not matter and may not
12464 even be noticeable.@refill
12466 @cindex Black rectangle in hardcopy
12467 @cindex Rectangle, ugly, black in hardcopy
12468 However, unless told otherwise, @TeX{} will print a large, ugly, black
12469 rectangle beside the line that contains the overfull hbox. This is so
12470 you will notice the location of the problem if you are correcting a
12475 To prevent such a monstrosity from marring your final printout, write
12476 the following in the beginning of the Texinfo file on a line of its own,
12477 before the @code{@@titlepage} command:@refill
12483 @node smallbook, A4 Paper, Overfull hboxes, Format/Print Hardcopy
12484 @comment node-name, next, previous, up
12485 @section Printing ``Small'' Books
12487 @cindex Small book size
12488 @cindex Book, printing small
12489 @cindex Page sizes for books
12490 @cindex Size of printed book
12492 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
12493 format. However, you can direct @TeX{} to typeset a document in a 7 by
12494 9.25 inch format that is suitable for bound books by inserting the
12495 following command on a line by itself at the beginning of the Texinfo
12496 file, before the title page:@refill
12503 (Since regular sized books are often about 7 by 9.25 inches, this
12504 command might better have been called the @code{@@regularbooksize}
12505 command, but it came to be called the @code{@@smallbook} command by
12506 comparison to the 8.5 by 11 inch format.)@refill
12508 If you write the @code{@@smallbook} command between the
12509 start-of-header and end-of-header lines, the Texinfo mode @TeX{}
12510 region formatting command, @code{texinfo-tex-region}, will format the
12511 region in ``small'' book size (@pxref{Start of Header}).@refill
12513 The Free Software Foundation distributes printed copies of @cite{The GNU
12514 Emacs Manual} and other manuals in the ``small'' book size.
12515 @xref{smallexample & smalllisp, , @code{@@smallexample} and
12516 @code{@@smalllisp}}, for information about commands that make it easier
12517 to produce examples for a smaller manual.@refill
12519 Alternatively, to avoid embedding this physical paper size in your
12520 document, use @code{texi2dvi} to format your document (@pxref{Format
12521 with texi2dvi}), and supply @samp{-t @@smallbook} as an argument. Then
12522 other people do not have to change the document source file to format it
12526 @node A4 Paper, Cropmarks and Magnification, smallbook, Format/Print Hardcopy
12527 @comment node-name, next, previous, up
12528 @section Printing on A4 Paper
12529 @cindex A4 paper, printing on
12530 @cindex Paper size, European A4
12531 @cindex European A4 paper
12534 You can tell @TeX{} to typeset a document for printing on European size
12535 A4 paper with the @code{@@afourpaper} command. Write the command on a
12536 line by itself between @code{@@iftex} and @code{@@end iftex} lines near
12537 the beginning of the Texinfo file, before the title page:@refill
12539 For example, this is how you would write the header for this manual:@refill
12543 \input texinfo @@c -*-texinfo-*-
12544 @@c %**start of header
12545 @@setfilename texinfo
12547 @@syncodeindex vr fn
12551 @@c %**end of header
12555 Alternatively, to avoid embedding this physical paper size in your
12556 document, use @code{texi2dvi} to format your document (@pxref{Format
12557 with texi2dvi}), and supply @samp{-t @@afourpaper} as an argument. Then
12558 other people do not have to change the document source file to format it
12561 @pindex texinfo.cnf
12562 Another alternative: put the @code{@@afourpaper} command in the file
12563 @file{texinfo.cnf} that @TeX{} will read. (No need for @code{@@iftex}
12564 there.) This will automatically typeset all the Texinfo documents at
12565 your site with that paper size in effect.
12568 @node Cropmarks and Magnification, , A4 Paper, Format/Print Hardcopy
12569 @comment node-name, next, previous, up
12570 @section Cropmarks and Magnification
12573 @cindex Cropmarks for printing
12574 @cindex Printing cropmarks
12575 You can attempt to direct @TeX{} to print cropmarks at the corners of
12576 pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
12577 command on a line by itself between @code{@@iftex} and @code{@@end
12578 iftex} lines near the beginning of the Texinfo file, before the title
12579 page, like this:@refill
12589 This command is mainly for printers that typeset several pages on one
12590 sheet of film; but you can attempt to use it to mark the corners of a
12591 book set to 7 by 9.25 inches with the @code{@@smallbook} command.
12592 (Printers will not produce cropmarks for regular sized output that is
12593 printed on regular sized paper.) Since different printing machines work
12594 in different ways, you should explore the use of this command with a
12595 spirit of adventure. You may have to redefine the command in the
12596 @file{texinfo.tex} definitions file.@refill
12598 @findex mag @r{(@TeX{} command)}
12599 @cindex Magnified printing
12600 @cindex Larger or smaller pages
12601 You can attempt to direct @TeX{} to typeset pages larger or smaller than
12602 usual with the @code{\mag} @TeX{} command. Everything that is typeset
12603 is scaled proportionally larger or smaller. (@code{\mag} stands for
12604 ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
12605 plain @TeX{} command that is prefixed with a backslash. You have to
12606 write this command between @code{@@tex} and @code{@@end tex}
12607 (@pxref{Raw Formatter Commands}).
12609 Follow the @code{\mag} command with an @samp{=} and then a number that
12610 is 1000 times the magnification you desire. For example, to print pages
12611 at 1.2 normal size, write the following near the beginning of the
12612 Texinfo file, before the title page:@refill
12622 With some printing technologies, you can print normal-sized copies that
12623 look better than usual by using a larger-than-normal master.@refill
12625 Depending on your system, @code{\mag} may not work or may work only at
12626 certain magnifications. Be prepared to experiment.@refill
12628 @node Create an Info File, Install an Info File, Format/Print Hardcopy, Top
12629 @comment node-name, next, previous, up
12630 @chapter Creating an Info File
12631 @cindex Creating an Info file
12632 @cindex Info, creating an on-line file
12633 @cindex Formatting a file for Info
12635 @code{makeinfo} is a utility that converts a Texinfo file into an Info
12636 file; @code{texinfo-format-region} and @code{texinfo-format-buffer} are
12637 GNU Emacs functions that do the same.@refill
12639 A Texinfo file must contain an @code{@@setfilename} line near its
12640 beginning, otherwise the Info formatting commands will fail.
12642 For information on installing the Info file in the Info system, see
12643 @ref{Install an Info File}.@refill
12646 * makeinfo advantages:: @code{makeinfo} provides better error checking.
12647 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
12648 * makeinfo options:: Specify fill-column and other options.
12649 * Pointer Validation:: How to check that pointers point somewhere.
12650 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
12651 * texinfo-format commands:: Two Info formatting commands written
12652 in Emacs Lisp are an alternative
12653 to @code{makeinfo}.
12654 * Batch Formatting:: How to format for Info in Emacs Batch mode.
12655 * Tag and Split Files:: How tagged and split files help Info
12659 @node makeinfo advantages, Invoking makeinfo, Create an Info File, Create an Info File
12661 @heading @code{makeinfo} Preferred
12664 The @code{makeinfo} utility creates an Info file from a Texinfo source
12665 file more quickly than either of the Emacs formatting commands and
12666 provides better error messages. We recommend it. @code{makeinfo} is a
12667 C program that is independent of Emacs. You do not need to run Emacs to
12668 use @code{makeinfo}, which means you can use @code{makeinfo} on machines
12669 that are too small to run Emacs. You can run @code{makeinfo} in
12670 any one of three ways: from an operating system shell, from a shell
12671 inside Emacs, or by typing a key command in Texinfo mode in Emacs.
12674 The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
12675 commands are useful if you cannot run @code{makeinfo}. Also, in some
12676 circumstances, they format short regions or buffers more quickly than
12677 @code{makeinfo}.@refill
12679 @node Invoking makeinfo, makeinfo options, makeinfo advantages, Create an Info File
12680 @section Running @code{makeinfo} from a Shell
12682 To create an Info file from a Texinfo file, type @code{makeinfo}
12683 followed by the name of the Texinfo file. Thus, to create the Info
12684 file for Bison, type the following to the shell:
12685 is the prompt):@refill
12688 makeinfo bison.texinfo
12691 (You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
12694 Sometimes you will want to specify options. For example, if you wish
12695 to discover which version of @code{makeinfo} you are using,
12702 @xref{makeinfo options}, for more information.
12706 @node makeinfo options, Pointer Validation, Invoking makeinfo, Create an Info File
12707 @comment node-name, next, previous, up
12708 @section Options for @code{makeinfo}
12709 @cindex @code{makeinfo} options
12710 @cindex Options for @code{makeinfo}
12712 The @code{makeinfo} command takes a number of options. Most often,
12713 options are used to set the value of the fill column and specify the
12714 footnote style. Each command line option is a word preceded by
12715 @samp{--} or a letter preceded by @samp{-}. You can use abbreviations
12716 for the long option names as long as they are unique.@refill
12718 For example, you could use the following shell command to create an Info
12719 file for @file{bison.texinfo} in which each line is filled to only 68
12723 makeinfo --fill-column=68 bison.texinfo
12726 You can write two or more options in sequence, like this:@refill
12729 makeinfo --no-split --fill-column=70 @dots{}
12733 This would keep the Info file together as one possibly very long
12734 file and would also set the fill column to 70.@refill
12741 @opindex -D @var{var}
12742 Cause the variable @var{var} to be defined. This is equivalent to
12743 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
12745 @item --error-limit=@var{limit}
12746 @opindex --error-limit=@var{limit}
12747 Set the maximum number of errors that @code{makeinfo} will report
12748 before exiting (on the assumption that continuing would be useless);
12752 @item --fill-column=@var{width}
12753 @opindex --fill-column=@var{width}
12754 Specify the maximum number of columns in a line; this is the right-hand
12755 edge of a line. Paragraphs that are filled will be filled to this
12756 width. (Filling is the process of breaking up and connecting lines so
12757 that lines are the same length as or shorter than the number specified
12758 as the fill column. Lines are broken between words.) The default value
12761 @item --footnote-style=@var{style}
12762 @opindex --footnote-style=@var{style}
12763 Set the footnote style to @var{style}, either @samp{end} for the end
12764 node style (the default) or @samp{separate} for the separate node style.
12765 The value set by this option overrides the value set in a Texinfo file
12766 by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
12767 footnote style is @samp{separate}, @code{makeinfo} makes a new node
12768 containing the footnotes found in the current node. When the footnote
12769 style is @samp{end}, @code{makeinfo} places the footnote references at
12770 the end of the current node.
12774 Ordinarily, if the input file has errors, the output files are not
12775 created. With this option, they are preserved.
12779 Print a usage message listing all available options, then exit successfully.
12782 @opindex -I @var{dir}
12783 Add @code{dir} to the directory search list for finding files that are
12784 included using the @code{@@include} command. By default,
12785 @code{makeinfo} searches only the current directory.
12788 @opindex --no-headers
12789 Do not include menus or node lines in the output. This results in an
12790 @sc{ascii} file that you cannot read in Info since it does not contain
12791 the requisite nodes or menus. It is primarily useful to extract certain
12792 pieces of a manual into separate files to be included in a distribution,
12793 such as @file{INSTALL} files.
12796 @opindex --no-split
12797 Suppress the splitting stage of @code{makeinfo}. By default, large
12798 output files (where the size is greater than 70k bytes) are split into
12799 smaller subfiles, each one approximately 50k bytes.
12801 @item --no-pointer-validate
12802 @itemx --no-validate
12803 @opindex --no-pointer-validate
12804 @opindex --no-validate
12805 Suppress the pointer-validation phase of @code{makeinfo}. Normally,
12806 after a Texinfo file is processed, some consistency checks are made to
12807 ensure that cross references can be resolved, etc.
12808 @xref{Pointer Validation}.@refill
12812 Suppress warning messages (but @emph{not} error messages). You might
12813 want this if the file you are creating has examples of Texinfo cross
12814 references within it, and the nodes that are referenced do not actually
12817 @item --no-number-footnotes
12818 @opindex --no-number-footnotes
12819 Suppress automatic footnote numbering. By default, @code{makeinfo}
12820 numbers each footnote sequentially in a single node, resetting the
12821 current footnote number to 1 at the start of each node.
12823 @item --output=@var{file}
12824 @itemx -o @var{file}
12825 @opindex --output=@var{file}
12826 @opindex -o @var{file}
12827 Specify that the output should be directed to @var{file} and not to the
12828 file name specified in the @code{@@setfilename} command found in the
12829 Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
12830 goes to standard output and @samp{--no-split} is implied.
12833 @opindex -P @var{dir}
12834 Prepend @code{dir} to the directory search list for @code{@@include}.
12835 See @samp{-I} for more details.
12837 @item --paragraph-indent=@var{indent}
12838 @opindex --paragraph-indent=@var{indent}
12839 Set the paragraph indentation style to @var{indent}. The value set by
12840 this option overrides the value set in a Texinfo file by an
12841 @code{@@paragraphindent} command (@pxref{paragraphindent}). The value
12842 of @var{indent} is interpreted as follows:
12846 Preserve any existing indentation at the starts of paragraphs.
12848 @item @samp{0} or @samp{none}
12849 Delete any existing indentation.
12852 Indent each paragraph by that number of spaces.
12855 @item --reference-limit=@var{limit}
12856 @opindex --reference-limit=@var{limit}
12857 Set the value of the number of references to a node that
12858 @code{makeinfo} will make without reporting a warning. If a node has more
12859 than this number of references in it, @code{makeinfo} will make the
12860 references but also report a warning. The default is 1000.
12863 Cause @var{var} to be undefined. This is equivalent to
12864 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
12868 Cause @code{makeinfo} to display messages saying what it is doing.
12869 Normally, @code{makeinfo} only outputs messages if there are errors or
12874 Print the version number, then exit successfully.
12879 @node Pointer Validation, makeinfo in Emacs, makeinfo options, Create an Info File
12880 @section Pointer Validation
12881 @cindex Pointer validation with @code{makeinfo}
12882 @cindex Validation of pointers
12884 If you do not suppress pointer-validation, @code{makeinfo} will check
12885 the validity of the final Info file. Mostly, this means ensuring that
12886 nodes you have referenced really exist. Here is a complete list of what
12891 If a `Next', `Previous', or `Up' node reference is a reference to a
12892 node in the current file and is not an external reference such as to
12893 @file{(dir)}, then the referenced node must exist.@refill
12896 In every node, if the `Previous' node is different from the `Up' node,
12897 then the `Previous' node must also be pointed to by a `Next' node.@refill
12900 Every node except the `Top' node must have an `Up' pointer.@refill
12903 The node referenced by an `Up' pointer must contain a reference to the
12904 current node in some manner other than through a `Next' reference.
12905 This includes menu entries and cross references.@refill
12908 If the `Next' reference of a node is not the same as the `Next' reference
12909 of the `Up' reference, then the node referenced by the `Next' pointer
12910 must have a `Previous' pointer that points back to the current node.
12911 This rule allows the last node in a section to point to the first node
12912 of the next chapter.@refill
12915 @node makeinfo in Emacs, texinfo-format commands, Pointer Validation, Create an Info File
12916 @section Running @code{makeinfo} inside Emacs
12917 @cindex Running @code{makeinfo} in Emacs
12918 @cindex @code{makeinfo} inside Emacs
12919 @cindex Shell, running @code{makeinfo} in
12921 You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
12922 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
12923 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
12924 C-m C-b} by default.@refill
12928 @itemx M-x makeinfo-region
12929 Format the current region for Info.@refill
12930 @findex makeinfo-region
12933 @itemx M-x makeinfo-buffer
12934 Format the current buffer for Info.@refill
12935 @findex makeinfo-buffer
12938 When you invoke either @code{makeinfo-region} or
12939 @code{makeinfo-buffer}, Emacs prompts for a file name, offering the
12940 name of the visited file as the default. You can edit the default
12941 file name in the minibuffer if you wish, before pressing @key{RET} to
12942 start the @code{makeinfo} process.@refill
12944 The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
12945 run the @code{makeinfo} program in a temporary shell buffer. If
12946 @code{makeinfo} finds any errors, Emacs displays the error messages in
12947 the temporary buffer.@refill
12949 @cindex Errors, parsing
12950 @cindex Parsing errors
12952 You can parse the error messages by typing @kbd{C-x `}
12953 (@code{next-error}). This causes Emacs to go to and position the
12954 cursor on the line in the Texinfo source that @code{makeinfo} thinks
12955 caused the error. @xref{Compilation, , Running @code{make} or
12956 Compilers Generally, xemacs, XEmacs User's Manual}, for more
12957 information about using the @code{next-error} command.@refill
12959 In addition, you can kill the shell in which the @code{makeinfo}
12960 command is running or make the shell buffer display its most recent
12965 @itemx M-x makeinfo-kill-job
12966 @findex makeinfo-kill-job
12967 Kill the current running @code{makeinfo} job created by
12968 @code{makeinfo-region} or @code{makeinfo-buffer}.@refill
12971 @itemx M-x makeinfo-recenter-output-buffer
12972 @findex makeinfo-recenter-output-buffer
12973 Redisplay the @code{makeinfo} shell buffer to display its most recent
12978 (Note that the parallel commands for killing and recentering a @TeX{}
12979 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
12982 You can specify options for @code{makeinfo} by setting the
12983 @code{makeinfo-options} variable with either the @kbd{M-x
12984 edit-options} or the @kbd{M-x set-variable} command, or by setting the
12985 variable in your @file{.emacs} initialization file.@refill
12987 For example, you could write the following in your @file{.emacs} file:@refill
12991 (setq makeinfo-options
12992 "--paragraph-indent=0 --no-split
12993 --fill-column=70 --verbose")
12997 @c If you write these three cross references using xref, you see
12998 @c three references to the same named manual, which looks strange.
13000 For more information, see @ref{makeinfo options, , Options for
13001 @code{makeinfo}}, as well as ``Editing Variable Values,''``Examining and
13002 Setting Variables,'' and ``Init File'' in the @cite{The GNU Emacs
13007 For more information, see@*
13008 @ref{Edit Options, , Editing Variable Values, xemacs, XEmacs User's Manual},@*
13009 @ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@*
13010 @ref{Init File, , , xemacs, XEmacs User's Manual}, and@*
13011 @ref{makeinfo options, , Options for @code{makeinfo}}.
13014 @node texinfo-format commands, Batch Formatting, makeinfo in Emacs, Create an Info File
13015 @comment node-name, next, previous, up
13016 @section The @code{texinfo-format@dots{}} Commands
13017 @findex texinfo-format-region
13018 @findex texinfo-format-buffer
13020 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
13021 file with the @code{texinfo-format-region} command. This formats the
13022 current region and displays the formatted text in a temporary buffer
13023 called @samp{*Info Region*}.@refill
13025 Similarly, you can format a buffer with the
13026 @code{texinfo-format-buffer} command. This command creates a new
13027 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
13028 save the Info file under the name specified by the
13029 @code{@@setfilename} line which must be near the beginning of the
13030 Texinfo file.@refill
13034 @itemx @code{texinfo-format-region}
13035 Format the current region for Info.
13036 @findex texinfo-format-region
13039 @itemx @code{texinfo-format-buffer}
13040 Format the current buffer for Info.
13041 @findex texinfo-format-buffer
13044 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
13045 commands provide you with some error checking, and other functions can
13046 provide you with further help in finding formatting errors. These
13047 procedures are described in an appendix; see @ref{Catching Mistakes}.
13048 However, the @code{makeinfo} program is often faster and
13049 provides better error checking (@pxref{makeinfo in Emacs}).@refill
13051 @node Batch Formatting, Tag and Split Files, texinfo-format commands, Create an Info File
13052 @comment node-name, next, previous, up
13053 @section Batch Formatting
13054 @cindex Batch formatting for Info
13055 @cindex Info batch formatting
13057 You can format Texinfo files for Info using @code{batch-texinfo-format}
13058 and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
13059 including a shell inside of Emacs. (@xref{Command Switches, , Command
13060 Line Switches and Arguments, xemacs, XEmacs User's Manual}.)@refill
13062 Here is a shell command to format all the files that end in
13063 @file{.texinfo} in the current directory:
13066 emacs -batch -funcall batch-texinfo-format *.texinfo
13070 Emacs processes all the files listed on the command line, even if an
13071 error occurs while attempting to format some of them.@refill
13073 Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
13074 it is not interactive. It kills the Batch mode Emacs on completion.@refill
13076 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
13077 and want to format several Texinfo files at once. When you use Batch
13078 mode, you create a new Emacs process. This frees your current Emacs, so
13079 you can continue working in it. (When you run
13080 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
13081 use that Emacs for anything else until the command finishes.)@refill
13083 @node Tag and Split Files, , Batch Formatting, Create an Info File
13084 @comment node-name, next, previous, up
13085 @section Tag Files and Split Files
13086 @cindex Making a tag table automatically
13087 @cindex Tag table, making automatically
13089 If a Texinfo file has more than 30,000 bytes,
13090 @code{texinfo-format-buffer} automatically creates a tag table
13091 for its Info file; @code{makeinfo} always creates a tag table. With
13092 a @dfn{tag table}, Info can jump to new nodes more quickly than it can
13095 @cindex Indirect subfiles
13096 In addition, if the Texinfo file contains more than about 70,000
13097 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
13098 large Info file into shorter @dfn{indirect} subfiles of about 50,000
13099 bytes each. Big files are split into smaller files so that Emacs does
13100 not need to make a large buffer to hold the whole of a large Info
13101 file; instead, Emacs allocates just enough memory for the small, split
13102 off file that is needed at the time. This way, Emacs avoids wasting
13103 memory when you run Info. (Before splitting was implemented, Info
13104 files were always kept short and @dfn{include files} were designed as
13105 a way to create a single, large printed manual out of the smaller Info
13106 files. @xref{Include Files}, for more information. Include files are
13107 still used for very large documents, such as @cite{The XEmacs Lisp
13108 Reference Manual}, in which each chapter is a separate file.)@refill
13110 When a file is split, Info itself makes use of a shortened version of
13111 the original file that contains just the tag table and references to
13112 the files that were split off. The split off files are called
13113 @dfn{indirect} files.@refill
13115 The split off files have names that are created by appending @w{@samp{-1}},
13116 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
13117 @code{@@setfilename} command. The shortened version of the original file
13118 continues to have the name specified by @code{@@setfilename}.@refill
13120 At one stage in writing this document, for example, the Info file was saved
13121 as @file{test-texinfo} and that file looked like this:@refill
13125 Info file: test-texinfo, -*-Text-*-
13126 produced by texinfo-format-buffer
13127 from file: new-texinfo-manual.texinfo
13131 test-texinfo-1: 102
13132 test-texinfo-2: 50422
13135 test-texinfo-3: 101300
13139 Node: overview^?104
13140 Node: info file^?1271
13143 Node: printed manual^?4853
13144 Node: conventions^?6855
13150 (But @file{test-texinfo} had far more nodes than are shown here.) Each of
13151 the split off, indirect files, @file{test-texinfo-1},
13152 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
13153 after the line that says @samp{Indirect:}. The tag table is listed after
13154 the line that says @samp{Tag table:}. @refill
13156 In the list of indirect files, the number following the file name
13157 records the cumulative number of bytes in the preceding indirect files,
13158 not counting the file list itself, the tag table, or the permissions
13159 text in each file. In the tag table, the number following the node name
13160 records the location of the beginning of the node, in bytes from the
13163 If you are using @code{texinfo-format-buffer} to create Info files,
13164 you may want to run the @code{Info-validate} command. (The
13165 @code{makeinfo} command does such a good job on its own, you do not
13166 need @code{Info-validate}.) However, you cannot run the @kbd{M-x
13167 Info-validate} node-checking command on indirect files. For
13168 information on how to prevent files from being split and how to
13169 validate the structure of the nodes, see @ref{Using
13170 Info-validate}.@refill
13173 @node Install an Info File, Command List, Create an Info File, Top
13174 @comment node-name, next, previous, up
13175 @chapter Installing an Info File
13176 @cindex Installing an Info file
13177 @cindex Info file installation
13178 @cindex @file{dir} directory for Info installation
13180 Info files are usually kept in the @file{info} directory. You can read
13181 Info files using the standalone Info program or the Info reader built
13182 into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
13185 * Directory file:: The top level menu for all Info files.
13186 * New Info File:: Listing a new info file.
13187 * Other Info Directories:: How to specify Info files that are
13188 located in other directories.
13189 * Installing Dir Entries:: How to specify what menu entry to add
13190 to the Info directory.
13191 * Invoking install-info:: @code{install-info} options.
13194 @node Directory file, New Info File, Install an Info File, Install an Info File
13196 @heading The @file{dir} File
13199 For Info to work, the @file{info} directory must contain a file that
13200 serves as a top level directory for the Info system. By convention,
13201 this file is called @file{dir}. (You can find the location of this file
13202 within Emacs by typing @kbd{C-h i} to enter Info and then typing
13203 @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
13205 The @file{dir} file is itself an Info file. It contains the top level
13206 menu for all the Info files in the system. The menu looks like
13213 * Info: (info). Documentation browsing system.
13214 * Emacs: (emacs). The extensible, self-documenting
13216 * Texinfo: (texinfo). With one source file, make
13217 either a printed manual using
13218 TeX or an Info file.
13223 Each of these menu entries points to the `Top' node of the Info file
13224 that is named in parentheses. (The menu entry does not need to
13225 specify the `Top' node, since Info goes to the `Top' node if no node
13226 name is mentioned. @xref{Other Info Files, , Nodes in Other Info
13229 Thus, the @samp{Info} entry points to the `Top' node of the
13230 @file{info} file and the @samp{Emacs} entry points to the `Top' node
13231 of the @file{emacs} file.@refill
13233 In each of the Info files, the `Up' pointer of the `Top' node refers
13234 back to the @code{dir} file. For example, the line for the `Top'
13235 node of the Emacs manual looks like this in Info:@refill
13238 File: emacs Node: Top, Up: (DIR), Next: Distrib
13242 (Note that in this case, the @file{dir} file name is written in upper
13243 case letters---it can be written in either upper or lower case. Info
13244 has a feature that it will change the case of the file name to lower
13245 case if it cannot find the name as written.)@refill
13246 @c !!! Can any file name be written in upper or lower case,
13247 @c or is dir a special case?
13248 @c Yes, apparently so, at least with Gillespie's Info. --rjc 24mar92
13251 @node New Info File, Other Info Directories, Directory file, Install an Info File
13252 @section Listing a New Info File
13253 @cindex Adding a new info file
13254 @cindex Listing a new info file
13255 @cindex New info file, listing it in @file{dir} file
13256 @cindex Info file, listing new one
13257 @cindex @file{dir} file listing
13259 To add a new Info file to your system, you must write a menu entry to
13260 add to the menu in the @file{dir} file in the @file{info} directory.
13261 For example, if you were adding documentation for GDB, you would write
13262 the following new entry:@refill
13265 * GDB: (gdb). The source-level C debugger.
13269 The first part of the menu entry is the menu entry name, followed by a
13270 colon. The second part is the name of the Info file, in parentheses,
13271 followed by a period. The third part is the description.
13273 The name of an Info file often has a @file{.info} extension. Thus, the
13274 Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
13275 The Info reader programs automatically try the file name both with and
13276 without @file{.info}; so it is better to avoid clutter and not to write
13277 @samp{.info} explicitly in the menu entry. For example, the GDB menu
13278 entry should use just @samp{gdb} for the file name, not @samp{gdb.info}.
13281 @node Other Info Directories, Installing Dir Entries, New Info File, Install an Info File
13282 @comment node-name, next, previous, up
13283 @section Info Files in Other Directories
13284 @cindex Installing Info in another directory
13285 @cindex Info installed in another directory
13286 @cindex Another Info directory
13288 If an Info file is not in the @file{info} directory, there are three
13289 ways to specify its location:@refill
13293 Write the pathname in the @file{dir} file as the second part of the
13297 If you are using Emacs, list the name of the file in a second @file{dir}
13298 file, in its directory; and then add the name of that directory to the
13299 @code{Info-directory-list} variable in your personal or site
13300 initialization file.
13302 This tells Emacs where to look for @file{dir} files. Emacs merges the
13303 files named @file{dir} from each of the listed directories. (In Emacs
13304 version 18, you can set the @code{Info-directory} variable to the name
13305 of only one directory.)@refill
13308 Specify the Info directory name in the @code{INFOPATH} environment
13309 variable in your @file{.profile} or @file{.cshrc} initialization file.
13310 (Only you and others who set this environment variable will be able to
13311 find Info files whose location is specified this way.)@refill
13314 For example, to reach a test file in the @file{/home/bob/manuals}
13315 directory, you could add an entry like this to the menu in the
13316 @file{dir} file:@refill
13319 * Test: (/home/bob/manuals/info-test). Bob's own test file.
13323 In this case, the absolute file name of the @file{info-test} file is
13324 written as the second part of the menu entry.@refill
13326 @vindex Info-directory-list
13327 Alternatively, you could write the following in your @file{.emacs}
13332 (setq Info-directory-list
13333 '("/home/bob/manuals"
13334 "/usr/local/info"))
13338 @c reworded to avoid overfill hbox
13339 This tells Emacs to merge the @file{dir} file from the
13340 @file{/home/bob/manuals} directory with the @file{dir} file from the
13341 @file{/usr/local/info} directory. Info will list the
13342 @file{/home/bob/manuals/info-test} file as a menu entry in the
13343 @file{/home/bob/manuals/dir} file.@refill
13346 Finally, you can tell Info where to look by setting the @code{INFOPATH}
13347 environment variable in your @file{.cshrc} or @file{.profile} file. If
13348 you use a Bourne-compatible shell such as @code{sh} or @code{bash} for
13349 your shell command interpreter, you set the @code{INFOPATH} environment
13350 variable in the @file{.profile} initialization file; but if you use
13351 @code{csh} or @code{tcsh}, you must set the variable in the
13352 @file{.cshrc} initialization file. The two types of shells use
13357 In a @file{.cshrc} file, you could set the @code{INFOPATH}
13358 variable as follows:@refill
13361 setenv INFOPATH .:~/manuals:/usr/local/emacs/info
13365 In a @file{.profile} file, you would achieve the same effect by
13369 INFOPATH=.:$HOME/manuals:/usr/local/emacs/info
13375 The @samp{.} indicates the current directory as usual. Emacs uses the
13376 @code{INFOPATH} environment variable to initialize the value of Emacs's
13377 own @code{Info-directory-list} variable.
13379 @cindex colon @r{last in @code{INFOPATH}}
13380 However you set @code{INFOPATH}, if its last character is a colon, this
13381 is replaced by the default (compiled-in) path. This gives you a way to
13382 augment the default path with new directories without having to list all
13383 the standard places. For example (using @code{sh} syntax:
13386 INFOPATH=/local/info:
13391 will search @file{/local/info} first, then the standard directories.
13392 Leading or doubled colons are not treated specially.
13395 @node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File
13396 @section Installing Info Directory Files
13398 When you install an Info file onto your system, you can use the program
13399 @code{install-info} to update the Info directory file @file{dir}.
13400 Normally the makefile for the package runs @code{install-info}, just
13401 after copying the Info file into its proper installed location.
13403 @findex dircategory
13405 In order for the Info file to work with @code{install-info}, you should
13406 use the commands @code{@@dircategory} and @code{@@direntry} in the
13407 Texinfo source file. Use @code{@@direntry} to specify the menu entry to
13408 add to the Info directory file, and use @code{@@dircategory} to specify
13409 which part of the Info directory to put it in. Here is how these
13410 commands are used in this manual:
13413 @@dircategory Texinfo documentation system
13415 * Texinfo: (texinfo). The GNU documentation format.
13416 * install-info: (texinfo)Invoking install-info. @dots{}
13421 Here's what this produces in the Info file:
13424 INFO-DIR-SECTION Texinfo documentation system
13425 START-INFO-DIR-ENTRY
13426 * Texinfo: (texinfo). The GNU documentation format.
13427 * install-info: (texinfo)Invoking install-info. @dots{}
13433 The @code{install-info} program sees these lines in the Info file, and
13434 that is how it knows what to do.
13436 Always use the @code{@@direntry} and @code{@@dircategory} commands near
13437 the beginning of the Texinfo input, before the first @code{@@node}
13438 command. If you use them later on in the input, @code{install-info}
13439 will not notice them.
13441 If you use @code{@@dircategory} more than once in the Texinfo source,
13442 each usage specifies one category; the new menu entry is added to the
13443 Info directory file in each of the categories you specify. If you use
13444 @code{@@direntry} more than once, each usage specifies one menu entry;
13445 each of these menu entries is added to the directory in each of the
13446 specified categories.
13449 @node Invoking install-info, , Installing Dir Entries, Install an Info File
13450 @section Invoking install-info
13452 @pindex install-info
13454 @code{install-info} inserts menu entries from an Info file into the
13455 top-level @file{dir} file in the Info system (see the previous sections
13456 for an explanation of how the @file{dir} file works). It's most often
13457 run as part of software installation, or when constructing a dir file
13458 for all manuals on a system. Synopsis:
13461 install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
13464 If @var{info-file} or @var{dir-file} are not specified, the various
13465 options (described below) that define them must be. There are no
13466 compile-time defaults, and standard input is never used.
13467 @code{install-info} can read only one info file and write only one dir
13468 file per invocation.
13470 @cindex @file{dir}, created by @code{install-info}
13471 If @var{dir-file} (however specified) does not exist,
13472 @code{install-info} creates it if possible (with no entries).
13479 Delete the entries in @var{info-file} from @var{dir-file}. The file
13480 name in the entry in @var{dir-file} must be @var{info-file} (except for
13481 an optional @samp{.info} in either one). Don't insert any new entries.
13483 @item --dir-file=@var{name}
13484 @opindex --dir-file=@var{name}
13485 Specify file name of the Info directory file. This is equivalent to
13486 using the @var{dir-file} argument.
13488 @item --entry=@var{text}
13489 @opindex --entry=@var{text}
13490 Insert @var{text} as an Info directory entry; @var{text} should have the
13491 form of an Info menu item line plus zero or more extra lines starting
13492 with whitespace. If you specify more than one entry, they are all
13493 added. If you don't specify any entries, they are determined from
13494 information in the Info file itself.
13498 Display a usage message listing basic usage and all available options,
13499 then exit successfully.
13501 @item --info-file=@var{file}
13502 @opindex --info-file=@var{file}
13503 Specify Info file to install in the directory.
13504 This is equivalent to using the @var{info-file} argument.
13506 @item --info-dir=@var{dir}
13507 @opindex --info-dir=@var{dir}
13508 Equivalent to @samp{--dir-file=@var{dir}/dir}.
13510 @item --item=@var{text}
13511 @opindex --item=@var{text}
13512 Same as @samp{--entry=@var{text}}. An Info directory entry is actually
13521 Same as @samp{--delete}.
13523 @item --section=@var{sec}
13524 @opindex --section=@var{sec}
13525 Put this file's entries in section @var{sec} of the directory. If you
13526 specify more than one section, all the entries are added in each of the
13527 sections. If you don't specify any sections, they are determined from
13528 information in the Info file itself.
13532 @cindex version number, finding
13533 Display version information and exit successfully.
13538 @node Command List, Tips, Install an Info File, Top
13539 @appendix @@-Command List
13540 @cindex Alphabetical @@-command list
13541 @cindex List of @@-commands
13542 @cindex @@-command list
13544 Here is an alphabetical list of the @@-commands in Texinfo. Square
13545 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
13546 @samp{@dots{}}, indicates repeated text.@refill
13550 @item @@@var{whitespace}
13551 An @code{@@} followed by a space, tab, or newline produces a normal,
13552 stretchable, interword space. @xref{Multiple Spaces}.
13555 Generate an exclamation point that really does end a sentence (usually
13556 after an end-of-sentence capital letter). @xref{Ending a Sentence}.
13560 Generate an umlaut or acute accent, respectively, over the next
13561 character, as in @"o and @'o. @xref{Inserting Accents}.
13564 Force a line break. Do not end a paragraph that uses @code{@@*} with
13565 an @code{@@refill} command. @xref{Line Breaks}.@refill
13567 @item @@,@{@var{c}@}
13568 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
13572 Insert a discretionary hyphenation point. @xref{- and hyphenation}.
13575 Produce a period that really does end a sentence (usually after an
13576 end-of-sentence capital letter). @xref{Ending a Sentence}.
13579 Indicate to @TeX{} that an immediately preceding period, question
13580 mark, exclamation mark, or colon does not end a sentence. Prevent
13581 @TeX{} from inserting extra whitespace as it does at the end of a
13582 sentence. The command has no effect on the Info file output.
13583 @xref{Not Ending a Sentence}.@refill
13586 Generate a macro (bar) accent over the next character, as in @=o.
13587 @xref{Inserting Accents}.
13590 Generate a question mark that really does end a sentence (usually after
13591 an end-of-sentence capital letter). @xref{Ending a Sentence}.
13594 Stands for an at sign, @samp{@@}.
13595 @xref{Braces Atsigns, , Inserting @@ and braces}.
13599 Generate a circumflex (hat) or grave accent, respectively, over the next
13600 character, as in @^o.
13601 @xref{Inserting Accents}.
13604 Stands for a left brace, @samp{@{}.
13605 @xref{Braces Atsigns, , Inserting @@ and braces}.
13608 Stands for a right-hand brace, @samp{@}}.@*
13609 @xref{Braces Atsigns, , Inserting @@ and braces}.
13612 Generate a tilde accent over the next character, as in @~N.
13613 @xref{Inserting Accents}.
13617 Generate the uppercase and lowercase Scandinavian A-ring letters,
13618 respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
13622 Generate the uppercase and lowercase AE ligatures, respectively:
13623 @AE{}, @ae{}. @xref{Inserting Accents}.
13626 Change page dimensions for the A4 paper size.
13627 Only allowed inside @code{@@iftex} @dots{} @code{@@end iftex}.
13630 @item @@appendix @var{title}
13631 Begin an appendix. The title appears in the table
13632 of contents of a printed manual. In Info, the title is
13633 underlined with asterisks. @xref{unnumbered & appendix, , The
13634 @code{@@unnumbered} and @code{@@appendix} Commands}.@refill
13636 @item @@appendixsec @var{title}
13637 @itemx @@appendixsection @var{title}
13638 Begin an appendix section within an appendix. The section title appears
13639 in the table of contents of a printed manual. In Info, the title is
13640 underlined with equal signs. @code{@@appendixsection} is a longer
13641 spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
13642 appendixsec heading, , Section Commands}.@refill
13644 @item @@appendixsubsec @var{title}
13645 Begin an appendix subsection within an appendix. The title appears
13646 in the table of contents of a printed manual. In Info, the title is
13647 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
13648 subheading, , Subsection Commands}.@refill
13650 @item @@appendixsubsubsec @var{title}
13651 Begin an appendix subsubsection within an appendix subsection. The
13652 title appears in the table of contents of a printed manual. In Info,
13653 the title is underlined with periods. @xref{subsubsection,, The
13654 `subsub' Commands}.@refill
13657 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
13658 print the table's first column without highlighting (``as is'').
13659 @xref{Two-column Tables, , Making a Two-column Table}.@refill
13661 @item @@author @var{author}
13662 Typeset @var{author} flushleft and underline it. @xref{title
13663 subtitle author, , The @code{@@title} and @code{@@author}
13666 @item @@b@{@var{text}@}
13667 Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill
13671 Force a paragraph break. If used within a line, follow @code{@@br}
13672 with braces. @xref{br, , @code{@@br}}.@refill
13676 Generate a large round dot, or the closest possible
13677 thing to one. @xref{bullet, , @code{@@bullet}}.@refill
13680 Stop formatting a file. The formatters do not see the contents of a
13681 file following an @code{@@bye} command. @xref{Ending a File}.@refill
13683 @item @@c @var{comment}
13684 Begin a comment in Texinfo. The rest of the line does not appear in
13685 either the Info file or the printed manual. A synonym for
13686 @code{@@comment}. @xref{Comments, , Comments}.@refill
13689 Highlight an example or quotation by drawing a box with rounded
13690 corners around it. Pair with @code{@@end cartouche}. No effect in
13691 Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
13693 @item @@center @var{line-of-text}
13694 Center the line of text following the command.
13695 @xref{titlefont center sp, , @code{@@center}}.@refill
13697 @item @@centerchap @var{line-of-text}
13698 Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
13701 @item @@chapheading @var{title}
13702 Print a chapter-like heading in the text, but not in the table of
13703 contents of a printed manual. In Info, the title is underlined with
13704 asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
13705 and @code{@@chapheading}}.@refill
13707 @item @@chapter @var{title}
13708 Begin a chapter. The chapter title appears in the table of
13709 contents of a printed manual. In Info, the title is underlined with
13710 asterisks. @xref{chapter, , @code{@@chapter}}.@refill
13712 @item @@cindex @var{entry}
13713 Add @var{entry} to the index of concepts. @xref{Index Entries, ,
13714 Defining the Entries of an Index}.@refill
13716 @item @@cite@{@var{reference}@}
13717 Highlight the name of a book or other reference that lacks a
13718 companion Info file. @xref{cite, , @code{@@cite}}.@refill
13720 @item @@clear @var{flag}
13721 Unset @var{flag}, preventing the Texinfo formatting commands from
13722 formatting text between subsequent pairs of @code{@@ifset @var{flag}}
13723 and @code{@@end ifset} commands, and preventing
13724 @code{@@value@{@var{flag}@}} from expanding to the value to which
13726 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
13728 @item @@code@{@var{sample-code}@}
13729 Highlight text that is an expression, a syntactically complete token
13730 of a program, or a program name. @xref{code, , @code{@@code}}.@refill
13732 @item @@comment @var{comment}
13733 Begin a comment in Texinfo. The rest of the line does not appear in
13734 either the Info file or the printed manual. A synonym for @code{@@c}.
13735 @xref{Comments, , Comments}.@refill
13738 Print a complete table of contents. Has no effect in Info, which uses
13739 menus instead. @xref{Contents, , Generating a Table of
13742 @item @@copyright@{@}
13743 Generate a copyright symbol. @xref{copyright symbol, ,
13744 @code{@@copyright}}.@refill
13747 @item @@ctrl@{@var{ctrl-char}@}
13748 Describe an @sc{ascii} control character. Insert actual control character
13749 into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
13752 @item @@defcodeindex @var{index-name}
13753 Define a new index and its indexing command. Print entries in an
13754 @code{@@code} font. @xref{New Indices, , Defining New
13757 @item @@defcv @var{category} @var{class} @var{name}
13758 @itemx @@defcvx @var{category} @var{class} @var{name}
13759 Format a description for a variable associated with a class in
13760 object-oriented programming. Takes three arguments: the category of
13761 thing being defined, the class to which it belongs, and its name.
13762 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13764 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
13765 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
13766 Format a description for a function, interactive command, or similar
13767 entity that may take arguments. @code{@@deffn} takes as arguments the
13768 category of entity being described, the name of this particular
13769 entity, and its arguments, if any. @xref{Definition Commands}.@refill
13771 @item @@defindex @var{index-name}
13772 Define a new index and its indexing command. Print entries in a roman
13773 font. @xref{New Indices, , Defining New Indices}.@refill
13775 @c Unused so far as I can see and unsupported by makeinfo -- karl, 15sep96.
13776 @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
13777 Create new @@-command for Info that marks text by enclosing it in
13778 strings that precede and follow the text. Write definition inside of
13779 @code{@@ifinfo} @dots{} @code{@@end ifinfo}. @xref{Customized
13780 Highlighting}.@refill
13782 @item @@defivar @var{class} @var{instance-variable-name}
13783 @itemx @@defivarx @var{class} @var{instance-variable-name}
13784 This command formats a description for an instance variable in
13785 object-oriented programming. The command is equivalent to @samp{@@defcv
13786 @{Instance Variable@} @dots{}}. @xref{Definition Commands}, and
13787 @ref{deffnx,, Def Cmds in Detail}.
13789 @item @@defmac @var{macro-name} @var{arguments}@dots{}
13790 @itemx @@defmacx @var{macro-name} @var{arguments}@dots{}
13791 Format a description for a macro. The command is equivalent to
13792 @samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and
13793 @ref{deffnx,, Def Cmds in Detail}.
13795 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
13796 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
13797 Format a description for a method in object-oriented programming. The
13798 command is equivalent to @samp{@@defop Method @dots{}}. Takes as
13799 arguments the name of the class of the method, the name of the
13800 method, and its arguments, if any. @xref{Definition Commands}, and
13801 @ref{deffnx,, Def Cmds in Detail}.
13803 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
13804 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
13805 Format a description for an operation in object-oriented programming.
13806 @code{@@defop} takes as arguments the overall name of the category of
13807 operation, the name of the class of the operation, the name of the
13808 operation, and its arguments, if any. @xref{Definition
13809 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13811 @item @@defopt @var{option-name}
13812 @itemx @@defoptx @var{option-name}
13813 Format a description for a user option. The command is equivalent to
13814 @samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and
13815 @ref{deffnx,, Def Cmds in Detail}.
13817 @item @@defspec @var{special-form-name} @var{arguments}@dots{}
13818 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
13819 Format a description for a special form. The command is equivalent to
13820 @samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands},
13821 and @ref{deffnx,, Def Cmds in Detail}.
13823 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
13824 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
13825 Format a description for a data type. @code{@@deftp} takes as arguments
13826 the category, the name of the type (which is a word like @samp{int} or
13827 @samp{float}), and then the names of attributes of objects of that type.
13828 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13830 @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
13831 @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
13832 Format a description for a function or similar entity that may take
13833 arguments and that is typed. @code{@@deftypefn} takes as arguments the
13834 classification of entity being described, the type, the name of the
13835 entity, and its arguments, if any. @xref{Definition Commands}, and
13836 @ref{deffnx,, Def Cmds in Detail}.
13838 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
13839 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
13840 Format a description for a function in a typed language.
13841 The command is equivalent to @samp{@@deftypefn Function @dots{}}.
13842 @xref{Definition Commands},
13843 and @ref{deffnx,, Def Cmds in Detail}.
13845 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
13846 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
13847 Format a description for a typed method in object-oriented programming.
13848 Takes as arguments the name of the class of the method, the return type
13849 of the method, the name of the method, and its arguments, if any.
13850 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13852 @item @@deftypevr @var{classification} @var{data-type} @var{name}
13853 @itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
13854 Format a description for something like a variable in a typed
13855 language---an entity that records a value. Takes as arguments the
13856 classification of entity being described, the type, and the name of the
13857 entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
13860 @item @@deftypevar @var{data-type} @var{variable-name}
13861 @itemx @@deftypevarx @var{data-type} @var{variable-name}
13862 Format a description for a variable in a typed language. The command is
13863 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
13864 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
13866 @item @@defun @var{function-name} @var{arguments}@dots{}
13867 @itemx @@defunx @var{function-name} @var{arguments}@dots{}
13868 Format a description for functions. The command is equivalent to
13869 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
13870 @ref{deffnx,, Def Cmds in Detail}.
13872 @item @@defvar @var{variable-name}
13873 @itemx @@defvarx @var{variable-name}
13874 Format a description for variables. The command is equivalent to
13875 @samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and
13876 @ref{deffnx,, Def Cmds in Detail}.
13878 @item @@defvr @var{category} @var{name}
13879 @itemx @@defvrx @var{category} @var{name}
13880 Format a description for any kind of variable. @code{@@defvr} takes
13881 as arguments the category of the entity and the name of the entity.
13882 @xref{Definition Commands},
13883 and @ref{deffnx,, Def Cmds in Detail}.
13885 @item @@detailmenu@{@}
13886 Avoid @code{makeinfo} confusion stemming from the detailed node listing
13887 in a master menu. @xref{Master Menu Parts}.
13889 @item @@dfn@{@var{term}@}
13890 Highlight the introductory or defining use of a term.
13891 @xref{dfn, , @code{@@dfn}}.@refill
13893 @item @@dircategory @var{dirpart}
13894 Specify a part of the Info directory menu where this file's entry should
13895 go. @xref{Installing Dir Entries}.
13898 Begin the Info directory menu entry for this file.
13899 @xref{Installing Dir Entries}.
13903 Begin a kind of example. Indent text, do not fill, do not select a
13904 new font. Pair with @code{@@end display}. @xref{display, ,
13905 @code{@@display}}.@refill
13907 @item @@dmn@{@var{dimension}@}
13908 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
13909 thin space before @var{dimension}. No effect in Info.
13910 @xref{dmn, , @code{@@dmn}}.@refill
13912 @item @@dotaccent@{@var{c}@}
13913 Generate a dot accent over the character @var{c}, as in @dotaccent{oo}.
13914 @xref{Inserting Accents}.
13917 Insert an ellipsis: @samp{@dots{}}.
13918 @xref{dots, , @code{@@dots@{@}}}.@refill
13920 @item @@email@{@var{address}[, @var{displayed-text}]@}
13921 Indicate an electronic mail address.
13922 @xref{email, , @code{@@email}}.@refill
13925 @item @@emph@{@var{text}@}
13926 Highlight @var{text}; text is displayed in @emph{italics} in printed
13927 output, and surrounded by asterisks in Info. @xref{Emphasis, ,
13930 @item @@end @var{environment}
13931 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
13932 Commands,,@@-commands}.
13934 @item @@enddots@{@}
13935 Generate an end-of-sentence of ellipsis, like this @enddots{}
13936 @xref{dots,,@code{@@dots@{@}}}.
13939 @item @@enumerate [@var{number-or-letter}]
13940 Begin a numbered list, using @code{@@item} for each entry.
13941 Optionally, start list with @var{number-or-letter}. Pair with
13942 @code{@@end enumerate}. @xref{enumerate, ,
13943 @code{@@enumerate}}.@refill
13947 Indicate to the reader the exact equivalence of two forms with a
13948 glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
13951 Indicate to the reader with a glyph that the following text is
13952 an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
13954 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
13955 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
13956 Specify page footings resp.@: headings for even-numbered (left-hand)
13957 pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
13958 How to Make Your Own Headings}.@refill
13960 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
13961 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
13962 Specify page footings resp.@: headings for every page. Not relevant to
13963 Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
13966 Begin an example. Indent text, do not fill, and select fixed-width font.
13967 Pair with @code{@@end example}. @xref{example, ,
13968 @code{@@example}}.@refill
13970 @item @@exclamdown@{@}
13971 Produce an upside-down exclamation point. @xref{Inserting Accents}.
13973 @item @@exdent @var{line-of-text}
13974 Remove any indentation a line might have. @xref{exdent, ,
13975 Undoing the Indentation of a Line}.@refill
13977 @item @@expansion@{@}
13978 Indicate the result of a macro expansion to the reader with a special
13979 glyph: @samp{@expansion{}}.
13980 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
13982 @item @@file@{@var{filename}@}
13983 Highlight the name of a file, buffer, node, or directory. @xref{file, ,
13984 @code{@@file}}.@refill
13987 Prevent @TeX{} from printing large black warning rectangles beside
13988 over-wide lines. @xref{Overfull hboxes}.@refill
13991 @item @@findex @var{entry}
13992 Add @var{entry} to the index of functions. @xref{Index Entries, ,
13993 Defining the Entries of an Index}.@refill
13997 @itemx @@flushright
13998 Left justify every line but leave the right end ragged.
13999 Leave font as is. Pair with @code{@@end flushleft}.
14000 @code{@@flushright} analogous.
14001 @xref{flushleft & flushright, , @code{@@flushleft} and
14002 @code{@@flushright}}.@refill
14005 @item @@footnote@{@var{text-of-footnote}@}
14006 Enter a footnote. Footnote text is printed at the bottom of the page
14007 by @TeX{}; Info may format in either `End' node or `Separate' node style.
14008 @xref{Footnotes}.@refill
14010 @item @@footnotestyle @var{style}
14011 Specify an Info file's footnote style, either @samp{end} for the end
14012 node style or @samp{separate} for the separate node style.
14013 @xref{Footnotes}.@refill
14016 Begin a kind of example. Like @code{@@example} or @code{@@display},
14017 but do not narrow the margins and do not select the fixed-width font.
14018 Pair with @code{@@end format}. @xref{example, ,
14019 @code{@@example}}.@refill
14021 @item @@ftable @var{formatting-command}
14022 Begin a two-column table, using @code{@@item} for each entry.
14023 Automatically enter each of the items in the first column into the
14024 index of functions. Pair with @code{@@end ftable}. The same as
14025 @code{@@table}, except for indexing. @xref{ftable vtable, ,
14026 @code{@@ftable} and @code{@@vtable}}.@refill
14029 Hold text together that must appear on one printed page. Pair with
14030 @code{@@end group}. Not relevant to Info. @xref{group, ,
14031 @code{@@group}}.@refill
14033 @item @@H@{@var{c}@}
14034 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
14036 @item @@heading @var{title}
14037 Print an unnumbered section-like heading in the text, but not in the
14038 table of contents of a printed manual. In Info, the title is
14039 underlined with equal signs. @xref{unnumberedsec appendixsec heading,
14040 , Section Commands}.@refill
14042 @item @@headings @var{on-off-single-double}
14043 Turn page headings on or off, and/or specify single-sided or double-sided
14044 page headings for printing. @xref{headings on off, , The
14045 @code{@@headings} Command}.
14048 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
14049 Formatter Commands}.
14051 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
14052 Explicitly define hyphenation points. @xref{- and hyphenation,,
14053 @code{@@-} and @code{@@hyphenation}}.
14055 @item @@i@{@var{text}@}
14056 Print @var{text} in @i{italic} font. No effect in Info.
14057 @xref{Fonts}.@refill
14059 @item @@ifclear @var{flag}
14060 If @var{flag} is cleared, the Texinfo formatting commands format text
14061 between @code{@@ifclear @var{flag}} and the following @code{@@end
14063 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14067 Begin a stretch of text that will be ignored by @TeX{} when it typesets
14068 the printed manual. The text appears only in the HTML resp.@: Info
14069 file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
14070 @xref{Conditionals}.
14075 Begin a stretch of text that will be ignored in one output format but
14076 not the others. The text appears only in the format not specified.
14077 Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
14078 @code{@@end ifnotinfo}. @xref{Conditionals}.
14080 @item @@ifset @var{flag}
14081 If @var{flag} is set, the Texinfo formatting commands format text
14082 between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
14084 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14087 Begin a stretch of text that will not appear in the Info file, but
14088 will be processed only by @TeX{}. Pair with @code{@@end iftex}.
14089 @xref{Conditionals, , Conditionally Visible Text}.@refill
14092 Begin a stretch of text that will not appear in either the Info file
14093 or the printed output. Pair with @code{@@end ignore}.
14094 @xref{Comments, , Comments and Ignored Text}.@refill
14096 @item @@image@{@var{filename}, [@var{width}], [@var{height}]@}
14097 Include graphics image in external @var{filename} scaled to the given
14098 @var{width} and/or @var{height}. @xref{Images}.
14100 @item @@include @var{filename}
14101 Incorporate the contents of the file @var{filename} into the Info file
14102 or printed document. @xref{Include Files}.@refill
14104 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
14105 Make a cross reference to an Info file for which there is no printed
14106 manual. @xref{inforef, , Cross references using
14107 @code{@@inforef}}.@refill
14109 @item \input @var{macro-definitions-file}
14110 Use the specified macro definitions file. This command is used only
14111 in the first line of a Texinfo file to cause @TeX{} to make use of the
14112 @file{texinfo} macro definitions file. The backslash in @code{\input}
14113 is used instead of an @code{@@} because @TeX{} does not
14114 recognize @code{@@} until after it has read the definitions file.
14115 @xref{Header, , The Texinfo File Header}.@refill
14118 Indicate the beginning of a marked paragraph for @code{@@itemize} and
14119 @code{@@enumerate}; indicate the beginning of the text of a first column
14120 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
14121 @xref{Lists and Tables}.@refill
14123 @item @@itemize @var{mark-generating-character-or-command}
14124 Produce a sequence of indented paragraphs, with a mark inside the left
14125 margin at the beginning of each paragraph. Pair with @code{@@end
14126 itemize}. @xref{itemize, , @code{@@itemize}}.@refill
14129 Like @code{@@item} but do not generate extra vertical space above the
14130 item text. @xref{itemx, , @code{@@itemx}}.@refill
14132 @item @@kbd@{@var{keyboard-characters}@}
14133 Indicate text that is characters of input to be typed by
14134 users. @xref{kbd, , @code{@@kbd}}.@refill
14136 @item @@kbdinputstyle @var{style}
14137 Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
14138 @xref{kbd, , @code{@@kbd}}.@refill
14140 @item @@key@{@var{key-name}@}
14141 Indicate a name for a key on a keyboard.
14142 @xref{key, , @code{@@key}}.@refill
14144 @item @@kindex @var{entry}
14145 Add @var{entry} to the index of keys.
14146 @xref{Index Entries, , Defining the Entries of an Index}.@refill
14150 Generate the uppercase and lowercase Polish suppressed-L letters,
14151 respectively: @L{}, @l{}.
14153 @c Possibly this can be tossed now that we have macros. --karl, 16sep96.
14154 @c Yes, let's toss it, it's pretty weird. --karl, 15jun97.
14155 @c @item @@global@@let@var{new-command}=@var{existing-command}
14156 @c Equate a new highlighting command with an existing one. Only for
14157 @c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end
14158 @c iftex}. @xref{Customized Highlighting}.@refill
14161 Begin an example of Lisp code. Indent text, do not fill, and select
14162 fixed-width font. Pair with @code{@@end lisp}. @xref{Lisp Example, ,
14163 @code{@@lisp}}.@refill
14165 @item @@lowersections
14166 Change subsequent chapters to sections, sections to subsections, and so
14167 on. @xref{Raise/lower sections, , @code{@@raisesections} and
14168 @code{@@lowersections}}.@refill
14170 @item @@macro @var{macro-name} @{@var{params}@}
14171 Define a new Texinfo command @code{@@@var{macro-name}@{@var{params}@}}.
14172 Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
14175 @item @@majorheading @var{title}
14176 Print a chapter-like heading in the text, but not in the table of
14177 contents of a printed manual. Generate more vertical whitespace before
14178 the heading than the @code{@@chapheading} command. In Info, the chapter
14179 heading line is underlined with asterisks. @xref{majorheading &
14180 chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
14182 @item @@math@{@var{mathematical-expression}@}
14183 Format a mathematical expression.
14184 @xref{math, , @code{@@math} - Inserting Mathematical Expressions}.
14187 Mark the beginning of a menu of nodes in Info. No effect in a printed
14188 manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
14191 Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill
14193 @item @@multitable @var{column-width-spec}
14194 Begin a multi-column table. Pair with @code{@@end multitable}.
14195 @xref{Multitable Column Widths}.
14197 @item @@need @var{n}
14198 Start a new page in a printed manual if fewer than @var{n} mils
14199 (thousandths of an inch) remain on the current page. @xref{need, ,
14200 @code{@@need}}.@refill
14202 @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
14203 Define the beginning of a new node in Info, and serve as a locator for
14204 references for @TeX{}. @xref{node, , @code{@@node}}.@refill
14207 Prevent text from being indented as if it were a new paragraph.
14208 @xref{noindent, , @code{@@noindent}}.@refill
14212 Generate the uppercase and lowercase O-with-slash letters, respectively:
14215 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
14216 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
14217 Specify page footings resp.@: headings for odd-numbered (right-hand)
14218 pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
14219 How to Make Your Own Headings}.@refill
14223 Generate the uppercase and lowercase OE ligatures, respectively:
14224 @OE{}, @oe{}. @xref{Inserting Accents}.
14227 Start a new page in a printed manual. No effect in Info.
14228 @xref{page, , @code{@@page}}.@refill
14230 @item @@paragraphindent @var{indent}
14231 Indent paragraphs by @var{indent} number of spaces; delete indentation
14232 if the value of @var{indent} is 0; and do not change indentation if
14233 @var{indent} is @code{asis}. @xref{paragraphindent, , Paragraph
14236 @item @@pindex @var{entry}
14237 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
14238 the Entries of an Index}.@refill
14241 Indicate the position of point in a buffer to the reader with a
14242 glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
14243 Point in a Buffer}.@refill
14246 Generate the pounds sterling currency sign.
14247 @xref{pounds,,@code{@@pounds@{@}}}.
14250 Indicate printed output to the reader with a glyph:
14251 @samp{@print{}}. @xref{Print Glyph}.@refill
14253 @item @@printindex @var{index-name}
14254 Print an alphabetized two-column index in a printed manual or generate
14255 an alphabetized menu of index entries for Info. @xref{Printing
14256 Indices & Menus}.@refill
14258 @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14259 Make a reference that starts with a lower case `see' in a printed
14260 manual. Use within parentheses only. Do not follow command with a
14261 punctuation mark---the Info formatting commands automatically insert
14262 terminating punctuation as needed. Only the first argument is mandatory.
14263 @xref{pxref, , @code{@@pxref}}.@refill
14265 @item @@questiondown@{@}
14266 Generate an upside-down question mark. @xref{Inserting Accents}.
14269 Narrow the margins to indicate text that is quoted from another real
14270 or imaginary work. Write command on a line of its own. Pair with
14271 @code{@@end quotation}. @xref{quotation, ,
14272 @code{@@quotation}}.@refill
14275 @item @@r@{@var{text}@}
14276 Print @var{text} in @r{roman} font. No effect in Info.
14277 @xref{Fonts}.@refill
14279 @item @@raisesections
14280 Change subsequent sections to chapters, subsections to sections, and so
14281 on. @xref{Raise/lower sections, , @code{@@raisesections} and
14282 @code{@@lowersections}}.@refill
14285 @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14286 Make a reference. In a printed manual, the reference does not start
14287 with a `See'. Follow command with a punctuation mark. Only the first
14288 argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
14292 In Info, refill and indent the paragraph after all the other processing
14293 has been done. No effect on @TeX{}, which always refills. This command
14294 is no longer needed, since all formatters now automatically refill.
14295 @xref{Refilling Paragraphs}.@refill
14299 Indicate the result of an expression to the reader with a special
14300 glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
14302 @item @@ringaccent@{@var{c}@}
14303 Generate a ring accent over the next character, as in @ringaccent{o}.
14304 @xref{Inserting Accents}.
14306 @item @@samp@{@var{text}@}
14307 Highlight @var{text} that is a literal example of a sequence of
14308 characters. Used for single characters, for statements, and often for
14309 entire shell commands. @xref{samp, , @code{@@samp}}.@refill
14311 @item @@sc@{@var{text}@}
14312 Set @var{text} in a printed output in @sc{the small caps font} and
14313 set text in the Info file in uppercase letters.
14314 @xref{Smallcaps}.@refill
14316 @item @@section @var{title}
14317 Begin a section within a chapter. In a printed manual, the section
14318 title is numbered and appears in the table of contents. In Info, the
14319 title is underlined with equal signs. @xref{section, ,
14320 @code{@@section}}.@refill
14322 @item @@set @var{flag} [@var{string}]
14323 Make @var{flag} active, causing the Texinfo formatting commands to
14324 format text between subsequent pairs of @code{@@ifset @var{flag}} and
14325 @code{@@end ifset} commands. Optionally, set value of @var{flag} to
14327 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14329 @item @@setchapternewpage @var{on-off-odd}
14330 Specify whether chapters start on new pages, and if so, whether on
14331 odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
14332 @code{@@setchapternewpage}}.@refill
14334 @item @@setfilename @var{info-file-name}
14335 Provide a name to be used by the Info file. This command is essential
14336 for @TeX{} formatting as well, even though it produces no output.
14337 @xref{setfilename, , @code{@@setfilename}}.@refill
14339 @item @@settitle @var{title}
14340 Provide a title for page headers in a printed manual.
14341 @xref{settitle, , @code{@@settitle}}.@refill
14343 @item @@shortcontents
14344 Print a short table of contents. Not relevant to Info, which uses
14345 menus rather than tables of contents. A synonym for
14346 @code{@@summarycontents}. @xref{Contents, , Generating a Table of
14349 @item @@shorttitlepage@{@var{title}@}
14350 Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
14354 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
14355 rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
14356 Printing Small Books}. Also, see @ref{smallexample & smalllisp, ,
14357 @code{@@smallexample} and @code{@@smalllisp}}.@refill
14360 @item @@smallexample
14361 Indent text to indicate an example. Do not fill, select fixed-width
14362 font. In @code{@@smallbook} format, print text in a smaller font than
14363 with @code{@@example}. Pair with @code{@@end smallexample}.
14364 @xref{smallexample & smalllisp, , @code{@@smallexample} and
14365 @code{@@smalllisp}}.@refill
14369 Begin an example of Lisp code. Indent text, do not fill, select
14370 fixed-width font. In @code{@@smallbook} format, print text in a
14371 smaller font. Pair with @code{@@end smalllisp}. @xref{smallexample &
14372 smalllisp, , @code{@@smallexample} and @code{@@smalllisp}}.@refill
14376 Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
14379 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
14382 @item @@strong @var{text}
14383 Emphasize @var{text} by typesetting it in a @strong{bold} font for the
14384 printed manual and by surrounding it with asterisks for Info.
14385 @xref{emph & strong, , Emphasizing Text}.@refill
14387 @item @@subheading @var{title}
14388 Print an unnumbered subsection-like heading in the text, but not in
14389 the table of contents of a printed manual. In Info, the title is
14390 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
14391 subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
14392 @code{@@subheading}}.@refill
14394 @item @@subsection @var{title}
14395 Begin a subsection within a section. In a printed manual, the
14396 subsection title is numbered and appears in the table of contents. In
14397 Info, the title is underlined with hyphens. @xref{subsection, ,
14398 @code{@@subsection}}.@refill
14400 @item @@subsubheading @var{title}
14401 Print an unnumbered subsubsection-like heading in the text, but not in
14402 the table of contents of a printed manual. In Info, the title is
14403 underlined with periods. @xref{subsubsection, , The `subsub'
14406 @item @@subsubsection @var{title}
14407 Begin a subsubsection within a subsection. In a printed manual,
14408 the subsubsection title is numbered and appears in the table of
14409 contents. In Info, the title is underlined with periods.
14410 @xref{subsubsection, , The `subsub' Commands}.@refill
14412 @item @@subtitle @var{title}
14413 In a printed manual, set a subtitle in a normal sized font flush to
14414 the right-hand side of the page. Not relevant to Info, which does not
14415 have title pages. @xref{title subtitle author, , @code{@@title}
14416 @code{@@subtitle} and @code{@@author} Commands}.@refill
14418 @item @@summarycontents
14419 Print a short table of contents. Not relevant to Info, which uses
14420 menus rather than tables of contents. A synonym for
14421 @code{@@shortcontents}. @xref{Contents, , Generating a Table of
14425 @item @@syncodeindex @var{from-index} @var{into-index}
14426 Merge the index named in the first argument into the index named in
14427 the second argument, printing the entries from the first index in
14428 @code{@@code} font. @xref{Combining Indices}.@refill
14431 @item @@synindex @var{from-index} @var{into-index}
14432 Merge the index named in the first argument into the index named in
14433 the second argument. Do not change the font of @var{from-index}
14434 entries. @xref{Combining Indices}.@refill
14437 @item @@t@{@var{text}@}
14438 Print @var{text} in a @t{fixed-width}, typewriter-like font.
14439 No effect in Info. @xref{Fonts}.@refill
14442 Separate columns in a multitable. @xref{Multitable Rows}.
14445 @item @@table @var{formatting-command}
14446 Begin a two-column table, using @code{@@item} for each entry. Write
14447 each first column entry on the same line as @code{@@item}. First
14448 column entries are printed in the font resulting from
14449 @var{formatting-command}. Pair with @code{@@end table}.
14450 @xref{Two-column Tables, , Making a Two-column Table}.
14451 Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
14452 and @ref{itemx, , @code{@@itemx}}.@refill
14455 Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
14456 and @copyright{}}.@refill
14459 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
14460 Formatter Commands}.
14462 @item @@thischapter
14463 @itemx @@thischaptername
14467 Only allowed in a heading or footing. Stands for the number and name of
14468 the current chapter (in the format `Chapter 1: Title'), the chapter name
14469 only, the filename, the current page number, and the title of the
14470 document, respectively. @xref{Custom Headings, , How to Make Your Own
14473 @item @@tieaccent@{@var{cc}@}
14474 Generate a tie-after accent over the next two characters @var{cc}, as in
14475 `@tieaccent{oo}'. @xref{Inserting Accents}.
14477 @item @@tindex @var{entry}
14478 Add @var{entry} to the index of data types. @xref{Index Entries, ,
14479 Defining the Entries of an Index}.@refill
14481 @item @@title @var{title}
14482 In a printed manual, set a title flush to the left-hand side of the
14483 page in a larger than normal font and underline it with a black rule.
14484 Not relevant to Info, which does not have title pages. @xref{title
14485 subtitle author, , The @code{@@title} @code{@@subtitle} and
14486 @code{@@author} Commands}.@refill
14489 @item @@titlefont@{@var{text}@}
14490 In a printed manual, print @var{text} in a larger than normal font.
14491 Not relevant to Info, which does not have title pages.
14492 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
14493 and @code{@@sp} Commands}.@refill
14497 Indicate to Texinfo the beginning of the title page. Write command on
14498 a line of its own. Pair with @code{@@end titlepage}. Nothing between
14499 @code{@@titlepage} and @code{@@end titlepage} appears in Info.
14500 @xref{titlepage, , @code{@@titlepage}}.@refill
14504 Insert the current date, in `1 Jan 1900' style. @xref{Custom
14505 Headings, , How to Make Your Own Headings}.@refill
14507 @item @@top @var{title}
14508 In a Texinfo file to be formatted with @code{makeinfo}, identify the
14509 topmost @code{@@node} line in the file, which must be written on the line
14510 immediately preceding the @code{@@top} command. Used for
14511 @code{makeinfo}'s node pointer insertion feature. The title is
14512 underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
14513 line normally should be enclosed by @code{@@ifinfo} and @code{@@end
14514 ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
14515 command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
14516 Pointer Creation, , Creating Pointers with @code{makeinfo}}.
14518 @item @@u@{@var{c}@}
14519 @itemx @@ubaraccent@{@var{c}@}
14520 @itemx @@udotaccent@{@var{c}@}
14521 Generate a breve, underbar, or underdot accent, respectively, over or
14522 under the character @var{c}, as in @u{o}, @ubaraccent{o},
14523 @udotaccent{o}. @xref{Inserting Accents}.
14525 @item @@unnumbered @var{title}
14526 In a printed manual, begin a chapter that appears without chapter
14527 numbers of any kind. The title appears in the table of contents of a
14528 printed manual. In Info, the title is underlined with asterisks.
14529 @xref{unnumbered & appendix, , @code{@@unnumbered} and
14530 @code{@@appendix}}.@refill
14532 @item @@unnumberedsec @var{title}
14533 In a printed manual, begin a section that appears without section
14534 numbers of any kind. The title appears in the table of contents of a
14535 printed manual. In Info, the title is underlined with equal signs.
14536 @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
14538 @item @@unnumberedsubsec @var{title}
14539 In a printed manual, begin an unnumbered subsection within a
14540 chapter. The title appears in the table of contents of a printed
14541 manual. In Info, the title is underlined with hyphens.
14542 @xref{unnumberedsubsec appendixsubsec subheading, ,
14543 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
14544 @code{@@subheading}}.@refill
14546 @item @@unnumberedsubsubsec @var{title}
14547 In a printed manual, begin an unnumbered subsubsection within a
14548 chapter. The title appears in the table of contents of a printed
14549 manual. In Info, the title is underlined with periods.
14550 @xref{subsubsection, , The `subsub' Commands}.@refill
14552 @item @@uref@{@var{url}[, @var{displayed-text}@}
14553 Define a cross reference to an external uniform resource locator for the
14554 World Wide Web. @xref{url, , @code{@@url}}.@refill
14556 @item @@url@{@var{url}@}
14557 Indicate text that is a uniform resource locator for the World Wide
14558 Web. @xref{url, , @code{@@url}}.@refill
14560 @item @@v@{@var{c}@}
14561 Generate check accent over the character @var{c}, as in @v{o}.
14562 @xref{Inserting Accents}.
14564 @item @@value@{@var{flag}@}
14565 Replace @var{flag} with the value to which it is set by @code{@@set
14567 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14569 @item @@var@{@var{metasyntactic-variable}@}
14570 Highlight a metasyntactic variable, which is something that stands for
14571 another piece of text. @xref{var, , Indicating Metasyntactic
14575 @item @@vindex @var{entry}
14576 Add @var{entry} to the index of variables. @xref{Index Entries, ,
14577 Defining the Entries of an Index}.@refill
14580 @item @@vskip @var{amount}
14581 In a printed manual, insert whitespace so as to push text on the
14582 remainder of the page towards the bottom of the page. Used in
14583 formatting the copyright page with the argument @samp{0pt plus
14584 1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
14585 only in contexts ignored for Info. @xref{Copyright & Permissions, ,
14586 The Copyright Page and Printed Permissions}.@refill
14589 @item @@vtable @var{formatting-command}
14590 Begin a two-column table, using @code{@@item} for each entry.
14591 Automatically enter each of the items in the first column into the
14592 index of variables. Pair with @code{@@end vtable}. The same as
14593 @code{@@table}, except for indexing. @xref{ftable vtable, ,
14594 @code{@@ftable} and @code{@@vtable}}.@refill
14597 @item @@w@{@var{text}@}
14598 Prevent @var{text} from being split across two lines. Do not end a
14599 paragraph that uses @code{@@w} with an @code{@@refill} command.
14600 @xref{w, , @code{@@w}}.@refill
14603 @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
14604 Make a reference that starts with `See' in a printed manual. Follow
14605 command with a punctuation mark. Only the first argument is
14606 mandatory. @xref{xref, , @code{@@xref}}.@refill
14610 @node Tips, Sample Texinfo File, Command List, Top
14611 @appendix Tips and Hints
14613 Here are some tips for writing Texinfo documentation:@refill
14620 Write in the present tense, not in the past or the future.
14623 Write actively! For example, write ``We recommend that @dots{}'' rather
14624 than ``It is recommended that @dots{}''.
14627 Use 70 or 72 as your fill column. Longer lines are hard to read.
14630 Include a copyright notice and copying permissions.
14633 @subsubheading Index, Index, Index!
14635 Write many index entries, in different ways.
14636 Readers like indices; they are helpful and convenient.
14638 Although it is easiest to write index entries as you write the body of
14639 the text, some people prefer to write entries afterwards. In either
14640 case, write an entry before the paragraph to which it applies. This
14641 way, an index entry points to the first page of a paragraph that is
14642 split across pages.
14644 Here are more hints we have found valuable:
14648 Write each index entry differently, so each entry refers to a different
14649 place in the document.
14652 Write index entries only where a topic is discussed significantly. For
14653 example, it is not useful to index ``debugging information'' in a
14654 chapter on reporting bugs. Someone who wants to know about debugging
14655 information will certainly not find it in that chapter.
14658 Consistently capitalize the first word of every concept index entry,
14659 or else consistently use lower case. Terse entries often call for
14660 lower case; longer entries for capitalization. Whichever case
14661 convention you use, please use one or the other consistently! Mixing
14662 the two styles looks bad.
14665 Always capitalize or use upper case for those words in an index for
14666 which this is proper, such as names of countries or acronyms. Always
14667 use the appropriate case for case-sensitive names, such as those in C or
14671 Write the indexing commands that refer to a whole section immediately
14672 after the section command, and write the indexing commands that refer to
14673 the paragraph before the paragraph.
14676 In the example that follows, a blank line comes after the index
14677 entry for ``Leaping'':
14681 @@section The Dog and the Fox
14682 @@cindex Jumping, in general
14685 @@cindex Dog, lazy, jumped over
14686 @@cindex Lazy dog jumped over
14687 @@cindex Fox, jumps over dog
14688 @@cindex Quick fox jumps over dog
14689 The quick brown fox jumps over the lazy dog.
14694 (Note that the example shows entries for the same concept that are
14695 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
14696 readers can look up the concept in different ways.)
14699 @subsubheading Blank Lines
14703 Insert a blank line between a sectioning command and the first following
14704 sentence or paragraph, or between the indexing commands associated with
14705 the sectioning command and the first following sentence or paragraph, as
14706 shown in the tip on indexing. Otherwise, a formatter may fold title and
14707 paragraph together.
14710 Always insert a blank line before an @code{@@table} command and after an
14711 @code{@@end table} command; but never insert a blank line after an
14712 @code{@@table} command or before an @code{@@end table} command.
14723 Jump over lazy dogs.
14728 Also jump over lazy dogs.
14734 On the other hand, @dots{}
14738 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
14739 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
14743 @subsubheading Complete Phrases
14745 Complete phrases are easier to read than @dots{}
14749 Write entries in an itemized list as complete sentences; or at least, as
14750 complete phrases. Incomplete expressions @dots{} awkward @dots{} like
14754 Write the prefatory sentence or phrase for a multi-item list or table as
14755 a complete expression. Do not write ``You can set:''; instead, write
14756 ``You can set these variables:''. The former expression sounds cut off.
14759 @subsubheading Editions, Dates and Versions
14761 Write the edition and version numbers and date in three places in every
14766 In the first @code{@@ifinfo} section, for people reading the Texinfo file.
14769 In the @code{@@titlepage} section, for people reading the printed manual.
14772 In the `Top' node, for people reading the Info file.
14776 Also, it helps to write a note before the first @code{@@ifinfo}
14777 section to explain what you are doing.
14786 @@c Specify the edition and version numbers and date
14787 @@c in *three* places:
14788 @@c 1. First ifinfo section 2. title page 3. top node
14789 @@c To find the locations, search for !!set
14794 @@c !!set edition, date, version
14795 This is Edition 4.03, January 1992,
14796 of the @@cite@{GDB Manual@} for GDB Version 4.3.
14802 ---or use @code{@@set} and @code{@@value}
14803 (@pxref{value Example, , @code{@@value} Example}).
14805 @subsubheading Definition Commands
14807 Definition commands are @code{@@deffn}, @code{@@defun},
14808 @code{@@defmac}, and the like, and enable you to write descriptions in
14809 a uniform format.@refill
14813 Write just one definition command for each entity you define with a
14814 definition command. The automatic indexing feature creates an index
14815 entry that leads the reader to the definition.
14818 Use @code{@@table} @dots{} @code{@@end table} in an appendix that
14819 contains a summary of functions, not @code{@@deffn} or other definition
14823 @subsubheading Capitalization
14827 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
14828 @samp{i} in upper case.
14831 Capitalize ``Info''; it is a name.
14834 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
14835 @samp{T} and @samp{X}. This command causes the formatters to
14836 typeset the name according to the wishes of Donald Knuth, who wrote
14840 @subsubheading Spaces
14842 Do not use spaces to format a Texinfo file, except inside of
14843 @code{@@example} @dots{} @code{@@end example} and similar commands.
14846 For example, @TeX{} fills the following:
14851 @@kbd@{M-x vc-next-action@}
14852 Perform the next logical operation
14853 on the version-controlled file
14854 corresponding to the current buffer.
14860 so it looks like this:
14865 @kbd{M-x vc-next-action}
14866 Perform the next logical operation on the version-controlled file
14867 corresponding to the current buffer.
14872 `C-x v' `M-x vc-next-action' Perform the next logical operation on the
14873 version-controlled file corresponding to the current buffer.
14878 In this case, the text should be formatted with
14879 @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
14881 @subsubheading @@code, @@samp, @@var, and @samp{---}
14885 Use @code{@@code} around Lisp symbols, including command names.
14889 The main function is @@code@{vc-next-action@}, @dots{}
14893 Avoid putting letters such as @samp{s} immediately after an
14894 @samp{@@code}. Such letters look bad.
14897 Use @code{@@var} around meta-variables. Do not write angle brackets
14901 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
14902 typesets these as a long dash and the Info formatters reduce three
14906 @subsubheading Periods Outside of Quotes
14908 Place periods and other punctuation marks @emph{outside} of quotations,
14909 unless the punctuation is part of the quotation. This practice goes
14910 against publishing conventions in the United States, but enables the
14911 reader to distinguish between the contents of the quotation and the
14914 For example, you should write the following sentence with the period
14915 outside the end quotation marks:
14918 Evidently, @samp{au} is an abbreviation for ``author''.
14922 since @samp{au} does @emph{not} serve as an abbreviation for
14923 @samp{author.} (with a period following the word).
14925 @subsubheading Introducing New Terms
14929 Introduce new terms so that a reader who does not know them can
14930 understand them from context; or write a definition for the term.
14932 For example, in the following, the terms ``check in'', ``register'' and
14933 ``delta'' are all appearing for the first time; the example sentence should be
14934 rewritten so they are understandable.
14937 The major function assists you in checking in a file to your
14938 version control system and registering successive sets of changes to
14943 Use the @code{@@dfn} command around a word being introduced, to indicate
14944 that the reader should not expect to know the meaning already, and
14945 should expect to learn the meaning from this passage.
14948 @subsubheading @@pxref
14950 @c !!! maybe include this in the tips on pxref
14952 By the way, it is okay to use pxref with something else in front of
14953 it within the parens, as long as the pxref is followed by the close
14954 paren, and the material inside the parens is not part of a larger
14955 sentence. Also, you can use xref inside parens as part of a complete
14956 sentence so long as you terminate the cross reference with punctuation.
14958 Absolutely never use @code{@@pxref} except in the special context for
14959 which it is designed: inside parentheses, with the closing parenthesis
14960 following immediately after the closing brace. One formatter
14961 automatically inserts closing punctuation and the other does not. This
14962 means that the output looks right both in printed output and in an Info
14963 file, but only when the command is used inside parentheses.
14965 @subsubheading Invoking from a Shell
14967 You can invoke programs such as Emacs, GCC, and @code{gawk} from a
14968 shell. The documentation for each program should contain a section that
14969 describes this. Unfortunately, if the node names and titles for these
14970 sections are all different, readers find it hard to search for the
14973 Name such sections with a phrase beginning with the word
14974 @w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way
14975 users can find the section easily.
14977 @subsubheading ANSI C Syntax
14979 When you use @code{@@example} to describe a C function's calling
14980 conventions, use the ANSI C syntax, like this:@refill
14983 void dld_init (char *@@var@{path@});
14987 And in the subsequent discussion, refer to the argument values by
14988 writing the same argument names, again highlighted with
14989 @code{@@var}.@refill
14992 Avoid the obsolete style that looks like this:@refill
15001 Also, it is best to avoid writing @code{#include} above the
15002 declaration just to indicate that the function is declared in a
15003 header file. The practice may give the misimpression that the
15004 @code{#include} belongs near the declaration of the function. Either
15005 state explicitly which header file holds the declaration or, better
15006 yet, name the header file used for a group of functions at the
15007 beginning of the section that describes the functions.@refill
15009 @subsubheading Bad Examples
15011 Here are several examples of bad writing to avoid:
15013 In this example, say, `` @dots{} you must @code{@@dfn}@{check
15014 in@} the new version.'' That flows better.
15017 When you are done editing the file, you must perform a
15018 @code{@@dfn}@{check in@}.
15021 In the following example, say, ``@dots{} makes a unified interface such as VC
15025 SCCS, RCS and other version-control systems all perform similar
15026 functions in broadly similar ways (it is this resemblance which makes
15027 a unified control mode like this possible).
15030 And in this example, you should specify what `it' refers to:
15033 If you are working with other people, it assists in coordinating
15034 everyone's changes so they do not step on each other.
15037 @subsubheading And Finally @dots{}
15041 Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
15042 sound in the name `Bach'. But pronounce Texinfo as in `speck':
15046 Write notes for yourself at the very end of a Texinfo file after the
15047 @code{@@bye}. None of the formatters process text after the
15048 @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
15049 @code{@@end ignore}.
15053 @node Sample Texinfo File, Sample Permissions, Tips, Top
15054 @appendix A Sample Texinfo File
15055 @cindex Sample Texinfo file, no comments
15057 Here is a complete, short sample Texinfo file, without any commentary.
15058 You can see this file, with comments, in the first chapter.
15059 @xref{Short Sample, , A Short Sample Texinfo File}.
15063 \input texinfo @@c -*-texinfo-*-
15064 @@c %**start of header
15065 @@setfilename sample.info
15066 @@settitle Sample Document
15067 @@c %**end of header
15069 @@setchapternewpage odd
15072 This is a short example of a complete Texinfo file.
15074 Copyright 1990 Free Software Foundation, Inc.
15079 @@comment The title is printed in a large font.
15080 @@center @@titlefont@{Sample Title@}
15082 @@c The following two commands start the copyright page.
15084 @@vskip 0pt plus 1filll
15085 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
15088 @@node Top, First Chapter, , (dir)
15089 @@comment node-name, next, previous, up
15092 * First Chapter:: The first chapter is the
15093 only chapter in this sample.
15094 * Concept Index:: This index has two entries.
15097 @@node First Chapter, Concept Index, Top, Top
15098 @@comment node-name, next, previous, up
15099 @@chapter First Chapter
15100 @@cindex Sample index entry
15102 This is the contents of the first chapter.
15103 @@cindex Another sample index entry
15105 Here is a numbered list.
15109 This is the first item.
15112 This is the second item.
15115 The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
15116 commands transform a Texinfo file such as this into
15117 an Info file; and @@TeX@{@} typesets it for a printed
15120 @@node Concept Index, , First Chapter, Top
15121 @@comment node-name, next, previous, up
15122 @@unnumbered Concept Index
15131 @node Sample Permissions, Include Files, Sample Texinfo File, Top
15132 @appendix Sample Permissions
15133 @cindex Permissions
15134 @cindex Copying permissions
15136 Texinfo files should contain sections that tell the readers that they
15137 have the right to copy and distribute the Texinfo file, the Info file,
15138 and the printed manual.@refill
15140 Also, if you are writing a manual about software, you should explain
15141 that the software is free and either include the GNU General Public
15142 License (GPL) or provide a reference to it. @xref{Distrib, ,
15143 Distribution, xemacs, XEmacs User's Manual}, for an example of the text
15144 that could be used in the software ``Distribution'', ``General Public
15145 License'', and ``NO WARRANTY'' sections of a document. @xref{Copying,
15146 , Texinfo Copying Conditions}, for an example of a brief explanation
15147 of how the copying conditions provide you with rights. @refill
15150 * Inserting Permissions:: How to put permissions in your document.
15151 * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions.
15152 * Titlepage Permissions:: Sample Titlepage copying permissions.
15155 @node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions
15157 @appendixsec Inserting Permissions
15160 In a Texinfo file, the first @code{@@ifinfo} section usually begins
15161 with a line that says what the file documents. This is what a person
15162 reading the unprocessed Texinfo file or using the advanced Info
15163 command @kbd{g *} sees first. @inforef{Expert, Advanced Info
15164 commands, info}, for more information. (A reader using the regular
15165 Info commands usually starts reading at the first node and skips
15166 this first section, which is not in a node.)@refill
15168 In the @code{@@ifinfo} section, the summary sentence is followed by a
15169 copyright notice and then by the copying permission notice. One of
15170 the copying permission paragraphs is enclosed in @code{@@ignore} and
15171 @code{@@end ignore} commands. This paragraph states that the Texinfo
15172 file can be processed through @TeX{} and printed, provided the printed
15173 manual carries the proper copying permission notice. This paragraph
15174 is not made part of the Info file since it is not relevant to the Info
15175 file; but it is a mandatory part of the Texinfo file since it permits
15176 people to process the Texinfo file in @TeX{} and print the
15179 In the printed manual, the Free Software Foundation copying permission
15180 notice follows the copyright notice and publishing information and is
15181 located within the region delineated by the @code{@@titlepage} and
15182 @code{@@end titlepage} commands. The copying permission notice is exactly
15183 the same as the notice in the @code{@@ifinfo} section except that the
15184 paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
15185 not part of the notice.@refill
15187 To make it simple to insert a permission notice into each section of
15188 the Texinfo file, sample permission notices for each section are
15189 reproduced in full below.@refill
15191 Note that you may need to specify the correct name of a section
15192 mentioned in the permission notice. For example, in @cite{The GDB
15193 Manual}, the name of the section referring to the General Public
15194 License is called the ``GDB General Public License'', but in the
15195 sample shown below, that section is referred to generically as the
15196 ``GNU General Public License''. If the Texinfo file does not carry a
15197 copy of the General Public License, leave out the reference to it, but
15198 be sure to include the rest of the sentence.@refill
15200 @node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions
15201 @comment node-name, next, previous, up
15202 @appendixsec @samp{ifinfo} Copying Permissions
15203 @cindex @samp{ifinfo} permissions
15205 In the @code{@@ifinfo} section of a Texinfo file, the standard Free
15206 Software Foundation permission notice reads as follows:@refill
15209 This file documents @dots{}
15211 Copyright 1998 Free Software Foundation, Inc.
15213 Permission is granted to make and distribute verbatim
15214 copies of this manual provided the copyright notice and
15215 this permission notice are preserved on all copies.
15218 Permission is granted to process this file through TeX
15219 and print the results, provided the printed document
15220 carries a copying permission notice identical to this
15221 one except for the removal of this paragraph (this
15222 paragraph not being relevant to the printed manual).
15225 Permission is granted to copy and distribute modified
15226 versions of this manual under the conditions for
15227 verbatim copying, provided also that the sections
15228 entitled ``Copying'' and ``GNU General Public License''
15229 are included exactly as in the original, and provided
15230 that the entire resulting derived work is distributed
15231 under the terms of a permission notice identical to this
15234 Permission is granted to copy and distribute
15235 translations of this manual into another language,
15236 under the above conditions for modified versions,
15237 except that this permission notice may be stated in a
15238 translation approved by the Free Software Foundation.
15241 @node Titlepage Permissions, , ifinfo Permissions, Sample Permissions
15242 @comment node-name, next, previous, up
15243 @appendixsec Titlepage Copying Permissions
15244 @cindex Titlepage permissions
15246 In the @code{@@titlepage} section of a Texinfo file, the standard Free
15247 Software Foundation copying permission notice follows the copyright
15248 notice and publishing information. The standard phrasing is as
15252 Permission is granted to make and distribute verbatim
15253 copies of this manual provided the copyright notice and
15254 this permission notice are preserved on all copies.
15256 Permission is granted to copy and distribute modified
15257 versions of this manual under the conditions for
15258 verbatim copying, provided also that the sections
15259 entitled ``Copying'' and ``GNU General Public License''
15260 are included exactly as in the original, and provided
15261 that the entire resulting derived work is distributed
15262 under the terms of a permission notice identical to this
15265 Permission is granted to copy and distribute
15266 translations of this manual into another language,
15267 under the above conditions for modified versions,
15268 except that this permission notice may be stated in a
15269 translation approved by the Free Software Foundation.
15273 @node Include Files, Headings, Sample Permissions, Top
15274 @appendix Include Files
15275 @cindex Include files
15277 When @TeX{} or an Info formatting command sees an @code{@@include}
15278 command in a Texinfo file, it processes the contents of the file named
15279 by the command and incorporates them into the DVI or Info file being
15280 created. Index entries from the included file are incorporated into
15281 the indices of the output file.@refill
15283 Include files let you keep a single large document as a collection of
15284 conveniently small parts.@refill
15287 * Using Include Files:: How to use the @code{@@include} command.
15288 * texinfo-multiple-files-update:: How to create and update nodes and
15289 menus when using included files.
15290 * Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
15291 * Sample Include File:: A sample outer file with included files
15292 within it; and a sample included file.
15293 * Include Files Evolution:: How use of the @code{@@include} command
15294 has changed over time.
15297 @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
15298 @appendixsec How to Use Include Files
15301 To include another file within a Texinfo file, write the
15302 @code{@@include} command at the beginning of a line and follow it on
15303 the same line by the name of a file to be included. For
15307 @@include buffers.texi
15310 An included file should simply be a segment of text that you expect to
15311 be included as is into the overall or @dfn{outer} Texinfo file; it
15312 should not contain the standard beginning and end parts of a Texinfo
15313 file. In particular, you should not start an included file with a
15314 line saying @samp{\input texinfo}; if you do, that phrase is inserted
15315 into the output file as is. Likewise, you should not end an included
15316 file with an @code{@@bye} command; nothing after @code{@@bye} is
15319 In the past, you were required to write an @code{@@setfilename} line at the
15320 beginning of an included file, but no longer. Now, it does not matter
15321 whether you write such a line. If an @code{@@setfilename} line exists
15322 in an included file, it is ignored.@refill
15324 Conventionally, an included file begins with an @code{@@node} line that
15325 is followed by an @code{@@chapter} line. Each included file is one
15326 chapter. This makes it easy to use the regular node and menu creating
15327 and updating commands to create the node pointers and menus within the
15328 included file. However, the simple Emacs node and menu creating and
15329 updating commands do not work with multiple Texinfo files. Thus you
15330 cannot use these commands to fill in the `Next', `Previous', and `Up'
15331 pointers of the @code{@@node} line that begins the included file. Also,
15332 you cannot use the regular commands to create a master menu for the
15333 whole file. Either you must insert the menus and the `Next',
15334 `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
15335 Texinfo mode command, @code{texinfo-multiple-files-update}, that is
15336 designed for @code{@@include} files.@refill
15338 @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
15339 @appendixsec @code{texinfo-multiple-files-update}
15340 @findex texinfo-multiple-files-update
15342 GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
15343 command. This command creates or updates `Next', `Previous', and `Up'
15344 pointers of included files as well as those in the outer or overall
15345 Texinfo file, and it creates or updates a main menu in the outer file.
15346 Depending whether you call it with optional arguments, the command
15347 updates only the pointers in the first @code{@@node} line of the
15348 included files or all of them:@refill
15351 @item M-x texinfo-multiple-files-update
15352 Called without any arguments:@refill
15356 Create or update the `Next', `Previous', and `Up' pointers of the
15357 first @code{@@node} line in each file included in an outer or overall
15358 Texinfo file.@refill
15361 Create or update the `Top' level node pointers of the outer or
15362 overall file.@refill
15365 Create or update a main menu in the outer file.@refill
15368 @item C-u M-x texinfo-multiple-files-update
15369 Called with @kbd{C-u} as a prefix argument:
15373 Create or update pointers in the first @code{@@node} line in each
15377 Create or update the `Top' level node pointers of the outer file.
15380 Create and insert a master menu in the outer file. The master menu
15381 is made from all the menus in all the included files.@refill
15384 @item C-u 8 M-x texinfo-multiple-files-update
15385 Called with a numeric prefix argument, such as @kbd{C-u 8}:
15389 Create or update @strong{all} the `Next', `Previous', and `Up' pointers
15390 of all the included files.@refill
15393 Create or update @strong{all} the menus of all the included
15397 Create or update the `Top' level node pointers of the outer or
15398 overall file.@refill
15401 And then create a master menu in the outer file. This is similar to
15402 invoking @code{texinfo-master-menu} with an argument when you are
15403 working with just one file.@refill
15407 Note the use of the prefix argument in interactive use: with a regular
15408 prefix argument, just @w{@kbd{C-u}}, the
15409 @code{texinfo-multiple-files-update} command inserts a master menu;
15410 with a numeric prefix argument, such as @kbd{C-u 8}, the command
15411 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
15412 master menu.@refill
15414 @node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files
15415 @appendixsec Include File Requirements
15416 @cindex Include file requirements
15417 @cindex Requirements for include files
15419 If you plan to use the @code{texinfo-multiple-files-update} command,
15420 the outer Texinfo file that lists included files within it should
15421 contain nothing but the beginning and end parts of a Texinfo file, and
15422 a number of @code{@@include} commands listing the included files. It
15423 should not even include indices, which should be listed in an included
15424 file of their own.@refill
15426 Moreover, each of the included files must contain exactly one highest
15427 level node (conventionally, @code{@@chapter} or equivalent),
15428 and this node must be the first node in the included file.
15429 Furthermore, each of these highest level nodes in each included file
15430 must be at the same hierarchical level in the file structure.
15431 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
15432 @code{@@unnumbered} node. Thus, normally, each included file contains
15433 one, and only one, chapter or equivalent-level node.@refill
15435 The outer file should contain only @emph{one} node, the `Top' node. It
15436 should @emph{not} contain any nodes besides the single `Top' node. The
15437 @code{texinfo-multiple-files-update} command will not process
15440 @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
15441 @appendixsec Sample File with @code{@@include}
15442 @cindex Sample @code{@@include} file
15443 @cindex Include file sample
15444 @cindex @code{@@include} file sample
15446 Here is an example of a complete outer Texinfo file with @code{@@include} files
15447 within it before running @code{texinfo-multiple-files-update}, which
15448 would insert a main or master menu:@refill
15452 \input texinfo @@c -*-texinfo-*-
15453 @c %**start of header
15454 @@setfilename include-example.info
15455 @@settitle Include Example
15456 @c %**end of header
15460 @@setchapternewpage odd
15463 @@center @@titlefont@{Include Example@}
15465 @@center by Whom Ever
15470 @@vskip 0pt plus 1filll
15471 Copyright @@copyright@{@} 1998 Free Software Foundation, Inc.
15477 @@node Top, First, , (dir)
15483 @@include foo.texinfo
15484 @@include bar.texinfo
15485 @@include concept-index.texinfo
15496 An included file, such as @file{foo.texinfo}, might look like
15501 @@node First, Second, , Top
15502 @@chapter First Chapter
15504 Contents of first chapter @dots{}
15508 The full contents of @file{concept-index.texinfo} might be as simple as this:
15512 @@node Concept Index, , Second, Top
15513 @@unnumbered Concept Index
15519 The outer Texinfo source file for @cite{The XEmacs Lisp Reference
15520 Manual} is named @file{elisp.texi}. This outer file contains a master
15521 menu with 417 entries and a list of 41 @code{@@include}
15524 @node Include Files Evolution, , Sample Include File, Include Files
15525 @comment node-name, next, previous, up
15526 @appendixsec Evolution of Include Files
15528 When Info was first created, it was customary to create many small
15529 Info files on one subject. Each Info file was formatted from its own
15530 Texinfo source file. This custom meant that Emacs did not need to
15531 make a large buffer to hold the whole of a large Info file when
15532 someone wanted information; instead, Emacs allocated just enough
15533 memory for the small Info file that contained the particular
15534 information sought. This way, Emacs could avoid wasting memory.@refill
15536 References from one file to another were made by referring to the file
15537 name as well as the node name. (@xref{Other Info Files, , Referring to
15538 Other Info Files}. Also, see @ref{Four and Five Arguments, ,
15539 @code{@@xref} with Four and Five Arguments}.)@refill
15541 Include files were designed primarily as a way to create a single,
15542 large printed manual out of several smaller Info files. In a printed
15543 manual, all the references were within the same document, so @TeX{}
15544 could automatically determine the references' page numbers. The Info
15545 formatting commands used include files only for creating joint
15546 indices; each of the individual Texinfo files had to be formatted for
15547 Info individually. (Each, therefore, required its own
15548 @code{@@setfilename} line.)@refill
15550 However, because large Info files are now split automatically, it is
15551 no longer necessary to keep them small.@refill
15553 Nowadays, multiple Texinfo files are used mostly for large documents,
15554 such as @cite{The XEmacs Lisp Reference Manual}, and for projects
15555 in which several different people write different sections of a
15556 document simultaneously.@refill
15558 In addition, the Info formatting commands have been extended to work
15559 with the @code{@@include} command so as to create a single large Info
15560 file that is split into smaller files if necessary. This means that
15561 you can write menus and cross references without naming the different
15562 Texinfo files.@refill
15565 @node Headings, Catching Mistakes, Include Files, Top
15566 @appendix Page Headings
15569 @cindex Page numbering
15570 @cindex Page headings
15571 @cindex Formatting headings and footings
15573 Most printed manuals contain headings along the top of every page
15574 except the title and copyright pages. Some manuals also contain
15575 footings. (Headings and footings have no meaning to Info, which is
15576 not paginated.)@refill
15579 * Headings Introduced:: Conventions for using page headings.
15580 * Heading Format:: Standard page heading formats.
15581 * Heading Choice:: How to specify the type of page heading.
15582 * Custom Headings:: How to create your own headings and footings.
15585 @node Headings Introduced, Heading Format, Headings, Headings
15587 @heading Headings Introduced
15590 Texinfo provides standard page heading formats for manuals that are
15591 printed on one side of each sheet of paper and for manuals that are
15592 printed on both sides of the paper. Typically, you will use these
15593 formats, but you can specify your own format if you wish.@refill
15595 In addition, you can specify whether chapters should begin on a new
15596 page, or merely continue the same page as the previous chapter; and if
15597 chapters begin on new pages, you can specify whether they must be
15598 odd-numbered pages.@refill
15600 By convention, a book is printed on both sides of each sheet of paper.
15601 When you open a book, the right-hand page is odd-numbered, and
15602 chapters begin on right-hand pages---a preceding left-hand page is
15603 left blank if necessary. Reports, however, are often printed on just
15604 one side of paper, and chapters begin on a fresh page immediately
15605 following the end of the preceding chapter. In short or informal
15606 reports, chapters often do not begin on a new page at all, but are
15607 separated from the preceding text by a small amount of whitespace.@refill
15609 The @code{@@setchapternewpage} command controls whether chapters begin
15610 on new pages, and whether one of the standard heading formats is used.
15611 In addition, Texinfo has several heading and footing commands that you
15612 can use to generate your own heading and footing formats.@refill
15614 In Texinfo, headings and footings are single lines at the tops and
15615 bottoms of pages; you cannot create multiline headings or footings.
15616 Each header or footer line is divided into three parts: a left part, a
15617 middle part, and a right part. Any part, or a whole line, may be left
15618 blank. Text for the left part of a header or footer line is set
15619 flushleft; text for the middle part is centered; and, text for the
15620 right part is set flushright.@refill
15622 @node Heading Format, Heading Choice, Headings Introduced, Headings
15623 @comment node-name, next, previous, up
15624 @appendixsec Standard Heading Formats
15626 Texinfo provides two standard heading formats, one for manuals printed
15627 on one side of each sheet of paper, and the other for manuals printed
15628 on both sides of the paper.
15630 By default, nothing is specified for the footing of a Texinfo file,
15631 so the footing remains blank.@refill
15633 The standard format for single-sided printing consists of a header
15634 line in which the left-hand part contains the name of the chapter, the
15635 central part is blank, and the right-hand part contains the page
15639 A single-sided page looks like this:
15643 _______________________
15645 | chapter page number |
15647 | Start of text ... |
15654 The standard format for two-sided printing depends on whether the page
15655 number is even or odd. By convention, even-numbered pages are on the
15656 left- and odd-numbered pages are on the right. (@TeX{} will adjust the
15657 widths of the left- and right-hand margins. Usually, widths are
15658 correct, but during double-sided printing, it is wise to check that
15659 pages will bind properly---sometimes a printer will produce output in
15660 which the even-numbered pages have a larger right-hand margin than the
15661 odd-numbered pages.)@refill
15663 In the standard double-sided format, the left part of the left-hand
15664 (even-numbered) page contains the page number, the central part is
15665 blank, and the right part contains the title (specified by the
15666 @code{@@settitle} command). The left part of the right-hand
15667 (odd-numbered) page contains the name of the chapter, the central part
15668 is blank, and the right part contains the page number.@refill
15671 Two pages, side by side as in an open book, look like this:@refill
15675 _______________________ _______________________
15677 | page number title | | chapter page number |
15679 | Start of text ... | | More text ... |
15687 The chapter name is preceded by the word ``Chapter'', the chapter number
15688 and a colon. This makes it easier to keep track of where you are in the
15691 @node Heading Choice, Custom Headings, Heading Format, Headings
15692 @comment node-name, next, previous, up
15693 @appendixsec Specifying the Type of Heading
15695 @TeX{} does not begin to generate page headings for a standard Texinfo
15696 file until it reaches the @code{@@end titlepage} command. Thus, the
15697 title and copyright pages are not numbered. The @code{@@end
15698 titlepage} command causes @TeX{} to begin to generate page headings
15699 according to a standard format specified by the
15700 @code{@@setchapternewpage} command that precedes the
15701 @code{@@titlepage} section.@refill
15704 There are four possibilities:@refill
15707 @item No @code{@@setchapternewpage} command
15708 Cause @TeX{} to specify the single-sided heading format, with chapters
15709 on new pages. This is the same as @code{@@setchapternewpage on}.@refill
15711 @item @code{@@setchapternewpage on}
15712 Specify the single-sided heading format, with chapters on new pages.@refill
15714 @item @code{@@setchapternewpage off}
15715 Cause @TeX{} to start a new chapter on the same page as the last page of
15716 the preceding chapter, after skipping some vertical whitespace. Also
15717 cause @TeX{} to typeset for single-sided printing. (You can override
15718 the headers format with the @code{@@headings double} command; see
15719 @ref{headings on off, , The @code{@@headings} Command}.)@refill
15721 @item @code{@@setchapternewpage odd}
15722 Specify the double-sided heading format, with chapters on new pages.@refill
15726 Texinfo lacks an @code{@@setchapternewpage even} command.@refill
15728 @node Custom Headings, , Heading Choice, Headings
15729 @comment node-name, next, previous, up
15730 @appendixsec How to Make Your Own Headings
15732 You can use the standard headings provided with Texinfo or specify
15733 your own. By default, Texinfo has no footers, so if you specify them,
15734 the available page size for the main text will be slightly reduced.
15736 @c Following paragraph is verbose to prevent overfull hboxes.
15737 Texinfo provides six commands for specifying headings and
15738 footings. The @code{@@everyheading} command and
15739 @code{@@everyfooting} command generate page headers and footers
15740 that are the same for both even- and odd-numbered pages.
15741 The @code{@@evenheading} command and @code{@@evenfooting}
15742 command generate headers and footers for even-numbered
15743 (left-hand) pages; and the @code{@@oddheading} command and
15744 @code{@@oddfooting} command generate headers and footers for
15745 odd-numbered (right-hand) pages.@refill
15747 Write custom heading specifications in the Texinfo file immediately
15748 after the @code{@@end titlepage} command. Enclose your specifications
15749 between @code{@@iftex} and @code{@@end iftex} commands since the
15750 @code{texinfo-format-buffer} command may not recognize them. Also,
15751 you must cancel the predefined heading commands with the
15752 @code{@@headings off} command before defining your own
15753 specifications.@refill
15756 Here is how to tell @TeX{} to place the chapter name at the left, the
15757 page number in the center, and the date at the right of every header
15758 for both even- and odd-numbered pages:@refill
15764 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
15770 You need to divide the left part from the central part and the central
15771 part from the right part by inserting @samp{@@|} between parts.
15772 Otherwise, the specification command will not be able to tell where
15773 the text for one part ends and the next part begins.@refill
15775 Each part can contain text or @@-commands. The text
15776 is printed as if the part were within an ordinary paragraph in the
15777 body of the page. The @@-commands replace
15778 themselves with the page number, date, chapter name, or
15782 Here are the six heading and footing commands:@refill
15784 @findex everyheading
15785 @findex everyfooting
15787 @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
15788 @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
15790 The `every' commands specify the format for both even- and odd-numbered
15791 pages. These commands are for documents that are printed on one side
15792 of each sheet of paper, or for documents in which you want symmetrical
15793 headers or footers.@refill
15795 @findex evenheading
15796 @findex evenfooting
15799 @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
15800 @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
15802 @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
15803 @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
15805 The `even' and `odd' commands specify the format for even-numbered
15806 pages and odd-numbered pages. These commands are for books and
15807 manuals that are printed on both sides of each sheet of paper.
15810 Use the @samp{@@this@dots{}} series of @@-commands to
15811 provide the names of chapters
15812 and sections and the page number. You can use the
15813 @samp{@@this@dots{}} commands in the left, center, or right portions
15814 of headers and footers, or anywhere else in a Texinfo file so long as
15815 they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
15818 Here are the @samp{@@this@dots{}} commands:@refill
15823 Expands to the current page number.@refill
15824 @c !!! Karl Berry says that `thissection' can fail on page breaks.
15826 @item @@thissection
15827 Expands to the name of the current section.@refill
15830 @findex thischaptername
15831 @item @@thischaptername
15832 Expands to the name of the current chapter.@refill
15834 @findex thischapter
15835 @item @@thischapter
15836 Expands to the number and name of the current
15837 chapter, in the format `Chapter 1: Title'.@refill
15841 Expands to the name of the document, as specified by the
15842 @code{@@settitle} command.@refill
15846 For @code{@@include} files only: expands to the name of the current
15847 @code{@@include} file. If the current Texinfo source file is not an
15848 @code{@@include} file, this command has no effect. This command does
15849 @emph{not} provide the name of the current Texinfo source file unless
15850 it is an @code{@@include} file. (@xref{Include Files}, for more
15851 information about @code{@@include} files.)@refill
15855 You can also use the @code{@@today@{@}} command, which expands to the
15856 current date, in `1 Jan 1900' format.@refill
15859 Other @@-commands and text are printed in a header or footer just as
15860 if they were in the body of a page. It is useful to incorporate text,
15861 particularly when you are writing drafts:@refill
15867 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
15868 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
15873 Beware of overlong titles: they may overlap another part of the
15874 header or footer and blot it out.@refill
15877 @node Catching Mistakes, Refilling Paragraphs, Headings, Top
15878 @appendix Formatting Mistakes
15879 @cindex Structure, catching mistakes in
15880 @cindex Nodes, catching mistakes
15881 @cindex Catching mistakes
15882 @cindex Correcting mistakes
15883 @cindex Mistakes, catching
15884 @cindex Problems, catching
15885 @cindex Debugging the Texinfo structure
15887 Besides mistakes in the content of your documentation, there
15888 are two kinds of mistake you can make with Texinfo: you can make mistakes
15889 with @@-commands, and you can make mistakes with the structure of the
15890 nodes and chapters.@refill
15892 Emacs has two tools for catching the @@-command mistakes and two for
15893 catching structuring mistakes.@refill
15895 For finding problems with @@-commands, you can run @TeX{} or a region
15896 formatting command on the region that has a problem; indeed, you can
15897 run these commands on each region as you write it.@refill
15899 For finding problems with the structure of nodes and chapters, you can use
15900 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
15901 command and you can use the @kbd{M-x Info-validate} command.@refill
15904 * makeinfo Preferred:: @code{makeinfo} finds errors.
15905 * Debugging with Info:: How to catch errors with Info formatting.
15906 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
15907 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
15908 * Using occur:: How to list all lines containing a pattern.
15909 * Running Info-Validate:: How to find badly referenced nodes.
15912 @node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
15914 @heading @code{makeinfo} Find Errors
15917 The @code{makeinfo} program does an excellent job of catching errors
15918 and reporting them---far better than @code{texinfo-format-region} or
15919 @code{texinfo-format-buffer}. In addition, the various functions for
15920 automatically creating and updating node pointers and menus remove
15921 many opportunities for human error.@refill
15923 If you can, use the updating commands to create and insert pointers
15924 and menus. These prevent many errors. Then use @code{makeinfo} (or
15925 its Texinfo mode manifestations, @code{makeinfo-region} and
15926 @code{makeinfo-buffer}) to format your file and check for other
15927 errors. This is the best way to work with Texinfo. But if you
15928 cannot use @code{makeinfo}, or your problem is very puzzling, then you
15929 may want to use the tools described in this appendix.@refill
15931 @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
15932 @comment node-name, next, previous, up
15933 @appendixsec Catching Errors with Info Formatting
15934 @cindex Catching errors with Info formatting
15935 @cindex Debugging with Info formatting
15937 After you have written part of a Texinfo file, you can use the
15938 @code{texinfo-format-region} or the @code{makeinfo-region} command to
15939 see whether the region formats properly.@refill
15941 Most likely, however, you are reading this section because for some
15942 reason you cannot use the @code{makeinfo-region} command; therefore, the
15943 rest of this section presumes that you are using
15944 @code{texinfo-format-region}.@refill
15946 If you have made a mistake with an @@-command,
15947 @code{texinfo-format-region} will stop processing at or after the
15948 error and display an error message. To see where in the buffer the
15949 error occurred, switch to the @samp{*Info Region*} buffer; the cursor
15950 will be in a position that is after the location of the error. Also,
15951 the text will not be formatted after the place where the error
15952 occurred (or more precisely, where it was detected).@refill
15954 For example, if you accidentally end a menu with the command @code{@@end
15955 menus} with an `s' on the end, instead of with @code{@@end menu}, you
15956 will see an error message that says:@refill
15959 @@end menus is not handled by texinfo
15963 The cursor will stop at the point in the buffer where the error
15964 occurs, or not long after it. The buffer will look like this:@refill
15968 ---------- Buffer: *Info Region* ----------
15971 * Using texinfo-show-structure:: How to use
15972 `texinfo-show-structure'
15974 * Running Info-Validate:: How to check for
15975 unreferenced nodes.
15978 ---------- Buffer: *Info Region* ----------
15982 The @code{texinfo-format-region} command sometimes provides slightly
15983 odd error messages. For example, the following cross reference fails to format:@refill
15986 (@@xref@{Catching Mistakes, for more info.)
15990 In this case, @code{texinfo-format-region} detects the missing closing
15991 brace but displays a message that says @samp{Unbalanced parentheses}
15992 rather than @samp{Unbalanced braces}. This is because the formatting
15993 command looks for mismatches between braces as if they were
15994 parentheses.@refill
15996 Sometimes @code{texinfo-format-region} fails to detect mistakes. For
15997 example, in the following, the closing brace is swapped with the
15998 closing parenthesis:@refill
16001 (@@xref@{Catching Mistakes), for more info.@}
16005 Formatting produces:
16007 (*Note for more info.: Catching Mistakes)
16010 The only way for you to detect this error is to realize that the
16011 reference should have looked like this:@refill
16014 (*Note Catching Mistakes::, for more info.)
16017 Incidentally, if you are reading this node in Info and type @kbd{f
16018 @key{RET}} (@code{Info-follow-reference}), you will generate an error
16022 No such node: "Catching Mistakes) The only way @dots{}
16026 This is because Info perceives the example of the error as the first
16027 cross reference in this node and if you type a @key{RET} immediately
16028 after typing the Info @kbd{f} command, Info will attempt to go to the
16029 referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
16030 will complete the node name of the correctly written example and take
16031 you to the `Catching Mistakes' node. (If you try this, you can return
16032 from the `Catching Mistakes' node by typing @kbd{l}
16033 (@code{Info-last}).)
16035 @c !!! section on using Elisp debugger ignored.
16037 Sometimes @code{texinfo-format-region} will stop long after the
16038 original error; this is because it does not discover the problem until
16039 then. In this case, you will need to backtrack.@refill
16042 @c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
16045 @c node Using the Emacs Lisp Debugger
16046 @c appendixsubsec Using the Emacs Lisp Debugger
16047 @c index Using the Emacs Lisp debugger
16048 @c index Emacs Lisp debugger
16049 @c index Debugger, using the Emacs Lisp
16051 If an error is especially elusive, you can turn on the Emacs Lisp
16052 debugger and look at the backtrace; this tells you where in the
16053 @code{texinfo-format-region} function the problem occurred. You can
16054 turn on the debugger with the command:@refill
16057 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
16061 and turn it off with
16064 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
16067 Often, when you are using the debugger, it is easier to follow what is
16068 going on if you use the Emacs Lisp files that are not byte-compiled.
16069 The byte-compiled sources send octal numbers to the debugger that may
16070 look mysterious. To use the uncompiled source files, load
16071 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
16074 The debugger will not catch an error if @code{texinfo-format-region}
16075 does not detect one. In the example shown above,
16076 @code{texinfo-format-region} did not find the error when the whole
16077 list was formatted, but only when part of the list was formatted.
16078 When @code{texinfo-format-region} did not find an error, the debugger
16079 did not find one either. @refill
16081 However, when @code{texinfo-format-region} did report an error, it
16082 invoked the debugger. This is the backtrace it produced:@refill
16085 ---------- Buffer: *Backtrace* ----------
16086 Signalling: (search-failed "[@},]")
16087 re-search-forward("[@},]")
16090 texinfo-format-parse-args()
16092 texinfo-format-xref()
16093 funcall(texinfo-format-xref)
16098 texinfo-format-scan()
16099 (save-excursion ...)
16101 texinfo-format-region(103370 103631)
16102 * call-interactively(texinfo-format-region)
16103 ---------- Buffer: *Backtrace* ----------
16106 The backtrace is read from the bottom up.
16107 @code{texinfo-format-region} was called interactively; and it, in
16108 turn, called various functions, including @code{texinfo-format-scan},
16109 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
16110 Inside the function @code{texinfo-format-parse-args}, the function
16111 @code{re-search-forward} was called; it was this function that could
16112 not find the missing right-hand brace.@refill
16114 @xref{Lisp Debug, , Debugging Emacs Lisp, xemacs, XEmacs User's Manual},
16115 for more information.@refill
16118 @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
16119 @comment node-name, next, previous, up
16120 @appendixsec Catching Errors with @TeX{} Formatting
16121 @cindex Catching errors with @TeX{} formatting
16122 @cindex Debugging with @TeX{} formatting
16124 You can also catch mistakes when you format a file with @TeX{}.@refill
16126 Usually, you will want to do this after you have run
16127 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
16128 the same file, because @code{texinfo-format-buffer} sometimes displays
16129 error messages that make more sense than @TeX{}. (@xref{Debugging
16130 with Info}, for more information.)@refill
16132 For example, @TeX{} was run on a Texinfo file, part of which is shown
16136 ---------- Buffer: texinfo.texi ----------
16137 name of the Texinfo file as an extension. The
16138 @@samp@{??@} are `wildcards' that cause the shell to
16139 substitute all the raw index files. (@@xref@{sorting
16140 indices, for more information about sorting
16142 ---------- Buffer: texinfo.texi ----------
16146 (The cross reference lacks a closing brace.)
16147 @TeX{} produced the following output, after which it stopped:@refill
16150 ---------- Buffer: *tex-shell* ----------
16152 @{sorting indices, for more information about sorting
16153 indices.) @@refill @@ETC.
16154 ! Paragraph ended before @@xref was complete.
16160 ---------- Buffer: *tex-shell* ----------
16163 In this case, @TeX{} produced an accurate and
16164 understandable error message:
16167 Paragraph ended before @@xref was complete.
16171 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
16172 @samp{l.27} means that @TeX{} detected the problem on line 27 of the
16173 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
16174 circumstance.@refill
16176 Unfortunately, @TeX{} is not always so helpful, and sometimes you must
16177 truly be a Sherlock Holmes to discover what went wrong.@refill
16179 In any case, if you run into a problem like this, you can do one of three
16184 You can tell @TeX{} to continue running and ignore just this error by
16185 typing @key{RET} at the @samp{?} prompt.@refill
16188 You can tell @TeX{} to continue running and to ignore all errors as best
16189 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
16191 This is often the best thing to do. However, beware: the one error
16192 may produce a cascade of additional error messages as its consequences
16193 are felt through the rest of the file. To stop @TeX{} when it is
16194 producing such an avalanche of error messages, type @kbd{C-c} (or
16195 @kbd{C-c C-c}, if you are running a shell inside Emacs).
16198 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
16199 at the @samp{?} prompt.@refill
16202 Please note that if you are running @TeX{} inside Emacs, you need to
16203 switch to the shell buffer and line at which @TeX{} offers the @samp{?}
16206 Sometimes @TeX{} will format a file without producing error messages even
16207 though there is a problem. This usually occurs if a command is not ended
16208 but @TeX{} is able to continue processing anyhow. For example, if you fail
16209 to end an itemized list with the @code{@@end itemize} command, @TeX{} will
16210 write a DVI file that you can print out. The only error message that
16211 @TeX{} will give you is the somewhat mysterious comment that@refill
16214 (@@end occurred inside a group at level 1)
16218 However, if you print the DVI file, you will find that the text
16219 of the file that follows the itemized list is entirely indented as if
16220 it were part of the last item in the itemized list. The error message
16221 is the way @TeX{} says that it expected to find an @code{@@end}
16222 command somewhere in the file; but that it could not determine where
16223 it was needed.@refill
16225 Another source of notoriously hard-to-find errors is a missing
16226 @code{@@end group} command. If you ever are stumped by
16227 incomprehensible errors, look for a missing @code{@@end group} command
16230 If the Texinfo file lacks header lines,
16231 @TeX{} may stop in the
16232 beginning of its run and display output that looks like the following.
16233 The @samp{*} indicates that @TeX{} is waiting for input.@refill
16236 This is TeX, Version 3.14159 (Web2c 7.0)
16242 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
16243 write the header lines in the Texinfo file and run the @TeX{} command
16244 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
16245 instead of @samp{@@}; and in this circumstance, you are working
16246 directly with @TeX{}, not with Texinfo.)@refill
16248 @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
16249 @comment node-name, next, previous, up
16250 @appendixsec Using @code{texinfo-show-structure}
16251 @cindex Showing the structure of a file
16252 @findex texinfo-show-structure
16254 It is not always easy to keep track of the nodes, chapters, sections, and
16255 subsections of a Texinfo file. This is especially true if you are revising
16256 or adding to a Texinfo file that someone else has written.@refill
16258 In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
16259 command lists all the lines that begin with the @@-commands that
16260 specify the structure: @code{@@chapter}, @code{@@section},
16261 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
16262 as prefix argument, if interactive),
16263 the command also shows the @code{@@node} lines. The
16264 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
16265 Texinfo mode, by default.@refill
16267 The lines are displayed in a buffer called the @samp{*Occur*} buffer,
16268 indented by hierarchical level. For example, here is a part of what was
16269 produced by running @code{texinfo-show-structure} on this manual:@refill
16273 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
16274 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
16275 in buffer texinfo.texi.
16277 4177:@@chapter Nodes
16278 4198: @@heading Two Paths
16279 4231: @@section Node and Menu Illustration
16280 4337: @@section The @@code@{@@@@node@} Command
16281 4393: @@subheading Choosing Node and Pointer Names
16282 4417: @@subsection How to Write an @@code@{@@@@node@} Line
16283 4469: @@subsection @@code@{@@@@node@} Line Tips
16288 This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
16289 with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
16290 commands respectively. If you move your cursor into the @samp{*Occur*}
16291 window, you can position the cursor over one of the lines and use the
16292 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
16293 the corresponding spot in the Texinfo file. @xref{Other Repeating
16294 Search, , Using Occur, xemacs, XEmacs User's Manual}, for more
16295 information about @code{occur-mode-goto-occurrence}.@refill
16297 The first line in the @samp{*Occur*} window describes the @dfn{regular
16298 expression} specified by @var{texinfo-heading-pattern}. This regular
16299 expression is the pattern that @code{texinfo-show-structure} looks for.
16300 @xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual},
16301 for more information.@refill
16303 When you invoke the @code{texinfo-show-structure} command, Emacs will
16304 display the structure of the whole buffer. If you want to see the
16305 structure of just a part of the buffer, of one chapter, for example,
16306 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
16307 region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is
16308 how the example used above was generated. (To see the whole buffer
16309 again, use @kbd{C-x n w} (@code{widen}).)@refill
16311 If you call @code{texinfo-show-structure} with a prefix argument by
16312 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
16313 @code{@@node} as well as the lines beginning with the @@-sign commands
16314 for @code{@@chapter}, @code{@@section}, and the like.@refill
16316 You can remind yourself of the structure of a Texinfo file by looking at
16317 the list in the @samp{*Occur*} window; and if you have mis-named a node
16318 or left out a section, you can correct the mistake.@refill
16320 @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
16321 @comment node-name, next, previous, up
16322 @appendixsec Using @code{occur}
16323 @cindex Occurrences, listing with @code{@@occur}
16326 Sometimes the @code{texinfo-show-structure} command produces too much
16327 information. Perhaps you want to remind yourself of the overall structure
16328 of a Texinfo file, and are overwhelmed by the detailed list produced by
16329 @code{texinfo-show-structure}. In this case, you can use the @code{occur}
16330 command directly. To do this, type@refill
16337 and then, when prompted, type a @dfn{regexp}, a regular expression for
16338 the pattern you want to match. (@xref{Regexps, , Regular Expressions,
16339 xemacs, XEmacs User's Manual}.) The @code{occur} command works from the
16340 current location of the cursor in the buffer to the end of the buffer.
16341 If you want to run @code{occur} on the whole buffer, place the cursor at
16342 the beginning of the buffer.@refill
16344 For example, to see all the lines that contain the word
16345 @samp{@@chapter} in them, just type @samp{@@chapter}. This will
16346 produce a list of the chapters. It will also list all the sentences
16347 with @samp{@@chapter} in the middle of the line.@refill
16349 If you want to see only those lines that start with the word
16350 @samp{@@chapter}, type @samp{^@@chapter} when prompted by
16351 @code{occur}. If you want to see all the lines that end with a word
16352 or phrase, end the last word with a @samp{$}; for example,
16353 @samp{catching mistakes$}. This can be helpful when you want to see
16354 all the nodes that are part of the same chapter or section and
16355 therefore have the same `Up' pointer.@refill
16357 @xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual},
16358 for more information.@refill
16360 @node Running Info-Validate, , Using occur, Catching Mistakes
16361 @comment node-name, next, previous, up
16362 @appendixsec Finding Badly Referenced Nodes
16363 @findex Info-validate
16364 @cindex Nodes, checking for badly referenced
16365 @cindex Checking for badly referenced nodes
16366 @cindex Looking for badly referenced nodes
16367 @cindex Finding badly referenced nodes
16368 @cindex Badly referenced nodes
16370 You can use the @code{Info-validate} command to check whether any of
16371 the `Next', `Previous', `Up' or other node pointers fail to point to a
16372 node. This command checks that every node pointer points to an
16373 existing node. The @code{Info-validate} command works only on Info
16374 files, not on Texinfo files.@refill
16376 The @code{makeinfo} program validates pointers automatically, so you
16377 do not need to use the @code{Info-validate} command if you are using
16378 @code{makeinfo}. You only may need to use @code{Info-validate} if you
16379 are unable to run @code{makeinfo} and instead must create an Info file
16380 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
16381 if you write an Info file from scratch.@refill
16384 * Using Info-validate:: How to run @code{Info-validate}.
16385 * Unsplit:: How to create an unsplit file.
16386 * Tagifying:: How to tagify a file.
16387 * Splitting:: How to split a file manually.
16390 @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
16391 @appendixsubsec Running @code{Info-validate}
16392 @cindex Running @code{Info-validate}
16393 @cindex Info validating a large file
16394 @cindex Validating a large file
16396 To use @code{Info-validate}, visit the Info file you wish to check and
16404 (Note that the @code{Info-validate} command requires an upper case
16405 `I'. You may also need to create a tag table before running
16406 @code{Info-validate}. @xref{Tagifying}.)@refill
16408 If your file is valid, you will receive a message that says ``File appears
16409 valid''. However, if you have a pointer that does not point to a node,
16410 error messages will be displayed in a buffer called @samp{*problems in
16411 info file*}.@refill
16413 For example, @code{Info-validate} was run on a test file that contained
16414 only the first node of this manual. One of the messages said:@refill
16417 In node "Overview", invalid Next: Texinfo Mode
16421 This meant that the node called @samp{Overview} had a `Next' pointer that
16422 did not point to anything (which was true in this case, since the test file
16423 had only one node in it).@refill
16425 Now suppose we add a node named @samp{Texinfo Mode} to our test case
16426 but we do not specify a `Previous' for this node. Then we will get
16427 the following error message:@refill
16430 In node "Texinfo Mode", should have Previous: Overview
16434 This is because every `Next' pointer should be matched by a
16435 `Previous' (in the node where the `Next' points) which points back.@refill
16437 @code{Info-validate} also checks that all menu entries and cross references
16438 point to actual nodes.@refill
16440 Note that @code{Info-validate} requires a tag table and does not work
16441 with files that have been split. (The @code{texinfo-format-buffer}
16442 command automatically splits large files.) In order to use
16443 @code{Info-validate} on a large file, you must run
16444 @code{texinfo-format-buffer} with an argument so that it does not split
16445 the Info file; and you must create a tag table for the unsplit
16448 @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
16449 @comment node-name, next, previous, up
16450 @appendixsubsec Creating an Unsplit File
16451 @cindex Creating an unsplit file
16452 @cindex Unsplit file creation
16454 You can run @code{Info-validate} only on a single Info file that has a
16455 tag table. The command will not work on the indirect subfiles that
16456 are generated when a master file is split. If you have a large file
16457 (longer than 70,000 bytes or so), you need to run the
16458 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
16459 a way that it does not create indirect subfiles. You will also need
16460 to create a tag table for the Info file. After you have done this,
16461 you can run @code{Info-validate} and look for badly referenced
16464 The first step is to create an unsplit Info file. To prevent
16465 @code{texinfo-format-buffer} from splitting a Texinfo file into
16466 smaller Info files, give a prefix to the @kbd{M-x
16467 texinfo-format-buffer} command:@refill
16470 C-u M-x texinfo-format-buffer
16481 When you do this, Texinfo will not split the file and will not create
16482 a tag table for it. @refill
16483 @cindex Making a tag table manually
16484 @cindex Tag table, making manually
16486 @node Tagifying, Splitting, Unsplit, Running Info-Validate
16487 @appendixsubsec Tagifying a File
16489 After creating an unsplit Info file, you must create a tag table for
16490 it. Visit the Info file you wish to tagify and type:@refill
16497 (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
16498 Info file with a tag table that you can validate.@refill
16500 The third step is to validate the Info file:@refill
16507 (Note the upper case @samp{I} in @code{Info-validate}.)
16508 In brief, the steps are:@refill
16512 C-u M-x texinfo-format-buffer
16518 After you have validated the node structure, you can rerun
16519 @code{texinfo-format-buffer} in the normal way so it will construct a
16520 tag table and split the file automatically, or you can make the tag
16521 table and split the file manually.@refill
16523 @node Splitting, , Tagifying, Running Info-Validate
16524 @comment node-name, next, previous, up
16525 @appendixsubsec Splitting a File Manually
16526 @cindex Splitting an Info file manually
16527 @cindex Info file, splitting manually
16529 You should split a large file or else let the
16530 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
16531 for you automatically. (Generally you will let one of the formatting
16532 commands do this job for you. @xref{Create an Info File}.)@refill
16534 The split-off files are called the indirect subfiles.@refill
16536 Info files are split to save memory. With smaller files, Emacs does not
16537 have make such a large buffer to hold the information.@refill
16539 If an Info file has more than 30 nodes, you should also make a tag
16540 table for it. @xref{Using Info-validate}, for information
16541 about creating a tag table. (Again, tag tables are usually created
16542 automatically by the formatting command; you only need to create a tag
16543 table yourself if you are doing the job manually. Most likely, you
16544 will do this for a large, unsplit file on which you have run
16545 @code{Info-validate}.)@refill
16547 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
16549 Before running @code{Info-split}, you need to load the @code{info} library
16550 into Emacs by giving the command @kbd{M-x load-library @key{RET} info
16554 Visit the Info file you wish to tagify and split and type the two
16563 (Note that the @samp{I} in @samp{Info} is upper case.)@refill
16565 When you use the @code{Info-split} command, the buffer is modified into a
16566 (small) Info file which lists the indirect subfiles. This file should be
16567 saved in place of the original visited file. The indirect subfiles are
16568 written in the same directory the original file is in, with names generated
16569 by appending @samp{-} and a number to the original file name.@refill
16571 The primary file still functions as an Info file, but it contains just
16572 the tag table and a directory of subfiles.@refill
16575 @node Refilling Paragraphs, Command Syntax, Catching Mistakes, Top
16576 @appendix Refilling Paragraphs
16577 @cindex Refilling paragraphs
16578 @cindex Filling paragraphs
16581 The @code{@@refill} command refills and, optionally, indents the first
16582 line of a paragraph.@footnote{Perhaps the command should have been
16583 called the @code{@@refillandindent} command, but @code{@@refill} is
16584 shorter and the name was chosen before indenting was possible.} The
16585 @code{@@refill} command is no longer important, but we describe it here
16586 because you once needed it. You will see it in many old Texinfo
16589 Without refilling, paragraphs containing long @@-constructs may look
16590 bad after formatting because the formatter removes @@-commands and
16591 shortens some lines more than others. In the past, neither the
16592 @code{texinfo-format-region} command nor the
16593 @code{texinfo-format-buffer} command refilled paragraphs
16594 automatically. The @code{@@refill} command had to be written at the
16595 end of every paragraph to cause these formatters to fill them. (Both
16596 @TeX{} and @code{makeinfo} have always refilled paragraphs
16597 automatically.) Now, all the Info formatters automatically fill and
16598 indent those paragraphs that need to be filled and indented.@refill
16600 The @code{@@refill} command causes @code{texinfo-format-region} and
16601 @code{texinfo-format-buffer} to refill a paragraph in the Info file
16602 @emph{after} all the other processing has been done. For this reason,
16603 you can not use @code{@@refill} with a paragraph containing either
16604 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
16605 override those two commands.@refill
16607 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
16608 commands now automatically append @code{@@refill} to the end of each
16609 paragraph that should be filled. They do not append @code{@@refill} to
16610 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
16611 and therefore do not refill or indent them.@refill
16614 @node Command Syntax, Obtaining TeX, Refilling Paragraphs, Top
16615 @comment node-name, next, previous, up
16616 @appendix @@-Command Syntax
16617 @cindex @@-command syntax
16619 The character @samp{@@} is used to start special Texinfo commands.
16620 (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
16621 has four types of @@-command:@refill
16624 @item 1. Non-alphabetic commands.
16625 These commands consist of an @@ followed by a punctuation mark or other
16626 character that is not part of the alphabet. Non-alphabetic commands are
16627 almost always part of the text within a paragraph, and never take any
16628 argument. The two characters (@@ and the other one) are complete in
16629 themselves; none is followed by braces. The non-alphabetic commands
16630 are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
16631 @code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
16632 @code{@@@}}.@refill
16634 @item 2. Alphabetic commands that do not require arguments.
16635 These commands start with @@ followed by a word followed by left- and
16636 right-hand braces. These commands insert special symbols in the
16637 document; they do not require arguments. For example,
16638 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
16639 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
16640 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
16642 @item 3. Alphabetic commands that require arguments within braces.
16643 These commands start with @@ followed by a letter or a word, followed by an
16644 argument within braces. For example, the command @code{@@dfn} indicates
16645 the introductory or defining use of a term; it is used as follows: @samp{In
16646 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
16648 @item 4. Alphabetic commands that occupy an entire line.
16649 These commands occupy an entire line. The line starts with @@,
16650 followed by the name of the command (a word); for example, @code{@@center}
16651 or @code{@@cindex}. If no argument is needed, the word is followed by
16652 the end of the line. If there is an argument, it is separated from
16653 the command name by a space. Braces are not used.@refill
16656 @cindex Braces and argument syntax
16657 Thus, the alphabetic commands fall into classes that have
16658 different argument syntaxes. You cannot tell to which class a command
16659 belongs by the appearance of its name, but you can tell by the
16660 command's meaning: if the command stands for a glyph, it is in
16661 class 2 and does not require an argument; if it makes sense to use the
16662 command together with other text as part of a paragraph, the command
16663 is in class 3 and must be followed by an argument in braces;
16664 otherwise, it is in class 4 and uses the rest of the line as its
16667 The purpose of having a different syntax for commands of classes 3 and
16668 4 is to make Texinfo files easier to read, and also to help the GNU
16669 Emacs paragraph and filling commands work properly. There is only one
16670 exception to this rule: the command @code{@@refill}, which is always
16671 used at the end of a paragraph immediately following the final period
16672 or other punctuation character. @code{@@refill} takes no argument and
16673 does @emph{not} require braces. @code{@@refill} never confuses the
16674 Emacs paragraph commands because it cannot appear at the beginning of
16678 @node Obtaining TeX, Command and Variable Index, Command Syntax, Top
16679 @appendix How to Obtain @TeX{}
16680 @cindex Obtaining @TeX{}
16681 @cindex @TeX{}, how to obtain
16683 @c !!! Here is information about obtaining TeX. Update it whenever.
16684 @c !!! Also consider updating TeX.README on ftp.gnu.org.
16685 @c Updated by RJC on 1 March 1995, conversation with MacKay.
16686 @c Updated by kb@cs.umb.edu on 29 July 1996.
16687 @c Updated by kb@cs.umb.edu on 25 April 1997.
16688 @c Updated by kb@cs.umb.edu on 27 February 1998.
16689 @TeX{} is freely redistributable. You can obtain @TeX{} for Unix
16690 systems via anonymous ftp or on physical media. The core material
16691 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
16693 Instructions for retrieval by anonymous ftp and information on other
16694 available distributions:
16696 @uref{ftp://tug.org/tex/unixtex.ftp}
16697 @uref{http://tug.org/unixtex.ftp}
16700 The Free Software Foundation provides a core distribution on its Source
16701 Code CD-ROM suitable for printing Texinfo manuals; the University of
16702 Washington maintains and supports a tape distribution; the @TeX{} Users
16703 Group co-sponsors a complete CD-ROM @TeX{} distribution.
16708 For the FSF Source Code CD-ROM, please contact:
16713 Free Software Foundation, Inc.
16714 59 Temple Place Suite 330
16715 Boston, MA @ @ 02111-1307
16717 Telephone: @w{+1-617-542-5942}
16718 Fax: (including Japan) @w{+1-617-542-2652}
16719 Free Dial Fax (in Japan):
16720 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
16721 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
16722 Electronic mail: @code{gnu@@gnu.org}
16729 Free Software Foundation, Inc.
16730 59 Temple Place Suite 330
16731 Boston, MA @w{ } 02111-1307
16734 Telephone: @w{+1-617-542-5942}
16735 Fax: (including Japan) @w{+1-617-542-2652}
16736 Free Dial Fax (in Japan):
16737 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
16738 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
16739 Electronic mail: @code{gnu@@gnu.org}
16745 To order a complete distribution on CD-ROM, please see
16746 @uref{http://tug.org/tex-live.html}. (This distribution is also
16747 available by FTP; see the URL's above.)
16750 To order a full distribution from the University of Washington on either
16751 a 1/4@dmn{in} 4-track QIC-24 cartridge or a 4@dmn{mm} DAT cartridge,
16757 Denny Hall, Mail Stop DH-10
16758 University of Washington
16759 Seattle, WA @w{ } 98195
16761 Telephone: +1-206-543-2268
16762 Electronic mail: @code{mackay@@cs.washington.edu}
16767 Please make checks payable to the University of Washington.
16768 Checks must be in U.S.@: dollars, drawn on a U.S.@: bank. Overseas
16769 sites: please add to the base cost, if desired, $20.00 for shipment via
16770 air parcel post, or $30.00 for shipment via courier.
16774 Many other @TeX{} distributions are available; see
16775 @uref{http://tug.org/}.
16778 @c These are no longer ``new'', and the explanations
16779 @c are all given elsewhere anyway, I think. --karl, 25apr97.
16780 @ignore (the entire appendix)
16781 @c node New Features, Command and Variable Index, Obtaining TeX, Top
16782 @c appendix Second Edition Features
16785 % Widen the space for the first column so three control-character
16786 % strings fit in the first column. Switched back to default .8in
16787 % value at end of chapter.
16788 \global\tableindent=1.0in
16791 The second edition of the Texinfo manual describes more than 20 new
16792 Texinfo mode commands and more than 50 previously undocumented Texinfo
16793 @@-commands. This edition is more than twice the length of the first
16796 Here is a brief description of the new commands.@refill
16799 * New Texinfo Mode Commands:: The updating commands are especially useful.
16800 * New Commands:: Many newly described @@-commands.
16803 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
16804 @c appendixsec New Texinfo Mode Commands
16806 Texinfo mode provides commands and features especially designed for
16807 working with Texinfo files. More than 20 new commands have been
16808 added, including commands for automatically creating and updating
16809 both nodes and menus. This is a tedious task when done by hand.@refill
16811 The keybindings are intended to be somewhat mnemonic.@refill
16813 @c subheading Update all nodes and menus
16815 The @code{texinfo-master-menu} command is the primary command:
16819 @itemx M-x texinfo-master-menu
16820 Create or update a master menu.
16821 With @kbd{C-u} as a prefix argument,
16822 first create or update all nodes
16826 @c subheading Update Pointers
16829 Create or update `Next', `Previous', and `Up' node pointers.@refill
16832 @xref{Updating Nodes and Menus}.
16836 @itemx M-x texinfo-update-node
16840 @itemx M-x texinfo-every-node-update
16841 Update every node in the buffer.
16844 @c subheading Update Menus
16847 Create or update menus.@refill
16850 @xref{Updating Nodes and Menus}.
16854 @itemx M-x texinfo-make-menu
16855 Make or update a menu.
16858 @itemx M-x texinfo-all-menus-update
16859 Make or update all the menus in a buffer.
16860 With @kbd{C-u} as a prefix argument,
16861 first update all the nodes.
16864 @c subheading Insert Title as Description
16867 Insert a node's chapter or section title in the space for the
16868 description in a menu entry line; position point so you can edit the
16869 insert. (This command works somewhat differently than the other
16870 insertion commands, which insert only a predefined string.)@refill
16873 @xref{Inserting, Inserting Frequently Used Commands}.
16880 @c subheading Format for Info
16883 Provide keybindings both for the Info formatting commands that are
16884 written in Emacs Lisp and for @code{makeinfo} that is written in
16888 @xref{Info Formatting}.
16891 Use the Emacs lisp @code{texinfo-format@dots{}} commands:
16902 Use @code{makeinfo}:
16912 Recenter the @code{makeinfo} output buffer.
16915 Kill the @code{makeinfo} formatting job.
16918 @c subheading Typeset and Print
16921 Typeset and print Texinfo documents from within Emacs.@refill
16929 @xref{Printing, , Formatting and Printing}.
16934 Run @code{texi2dvi} on the buffer.
16937 Run @TeX{} on the region.
16940 Run @code{texindex}.
16943 Print the DVI file.
16946 Show the print queue.
16949 Delete a job from the print queue.
16952 Kill the current @TeX{} formatting job.
16955 Quit a currently stopped @TeX{} formatting job.
16958 Recenter the output buffer.
16961 @c subheading Other Updating Commands
16964 The ``other updating commands'' do not have standard keybindings because
16965 they are used less frequently.@refill
16968 @xref{Other Updating Commands}.
16971 @item M-x texinfo-insert-node-lines
16972 Insert missing @code{@@node} lines using
16973 section titles as node names.
16975 @item M-x texinfo-multiple-files-update
16976 Update a multi-file document.
16977 With a numeric prefix, such as @kbd{C-u 8},
16978 update @strong{every} pointer and
16979 menu in @strong{all} the files and
16980 then insert a master menu.
16982 @item M-x texinfo-indent-menu-description
16983 Indent descriptions in menus.
16985 @item M-x texinfo-sequential-node-update
16986 Insert node pointers in strict sequence.
16989 @c node New Commands, , New Texinfo Mode Commands, Obtaining TeX
16990 @c appendixsec New Texinfo @@-Commands
16992 The second edition of the Texinfo manual describes more than 50
16993 commands that were not described in the first edition. A third or so
16994 of these commands existed in Texinfo but were not documented in the
16995 manual; the others are new. Here is a listing, with brief
16996 descriptions of them:@refill
16998 @c subheading Indexing
17001 Create your own index, and merge indices.@refill
17007 @item @@defindex @var{index-name}
17008 Define a new index and its indexing command.
17009 See also the @code{@@defcodeindex} command.
17011 @c written verbosely to avoid overfull hbox
17012 @item @@synindex @var{from-index} @var{into-index}
17013 Merge the @var{from-index} index into the @var{into-index} index.
17014 See also the @code{@@syncodeindex} command.
17017 @c subheading Definitions
17020 Describe functions, variables, macros,
17021 commands, user options, special forms, and other such artifacts in a
17022 uniform format.@refill
17025 @xref{Definition Commands}.
17028 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
17029 Format a description for functions, interactive
17030 commands, and similar entities.
17032 @item @@defvr, @@defop, @dots{}
17033 15 other related commands.
17036 @c subheading Glyphs
17039 Indicate the results of evaluation, expansion,
17040 printed output, an error message, equivalence of expressions, and the
17041 location of point.@refill
17055 @item @@expansion@{@}
17056 @itemx @expansion{}
17069 Result of an expression
17072 @c subheading Page Headings
17075 Customize page headings.
17081 @item @@headings @var{on-off-single-double}
17082 Headings on or off, single, or double-sided.
17084 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
17085 Footings for even-numbered (left-hand) pages.
17087 @item @@evenheading, @@everyheading, @@oddheading, @dots{}
17088 Five other related commands.
17090 @item @@thischapter
17091 Insert name of chapter and chapter number.
17093 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
17097 @c subheading Formatting
17100 Format blocks of text.
17103 @xref{Quotations and Examples}, and@*
17104 @ref{Lists and Tables, , Making Lists and Tables}.
17108 Draw rounded box surrounding text (not in Info).
17110 @item @@enumerate @var{optional-arg}
17111 Enumerate a list with letters or numbers.
17113 @item @@exdent @var{line-of-text}
17114 Remove indentation.
17123 Do not narrow nor change font.
17125 @item @@ftable @var{formatting-command}
17126 @itemx @@vtable @var{formatting-command}
17127 Two-column table with indexing.
17130 For an example of Lisp code.
17132 @item @@smallexample
17134 Like @@table and @@lisp @r{but for} @@smallbook.
17137 @c subheading Conditionals
17140 Conditionally format text.
17143 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
17146 @item @@set @var{flag} [@var{string}]
17147 Set a flag. Optionally, set value
17148 of @var{flag} to @var{string}.
17150 @item @@clear @var{flag}
17153 @item @@value@{@var{flag}@}
17154 Replace with value to which @var{flag} is set.
17156 @item @@ifset @var{flag}
17157 Format, if @var{flag} is set.
17159 @item @@ifclear @var{flag}
17160 Ignore, if @var{flag} is set.
17163 @c subheading @@heading series for Titles
17166 Produce unnumbered headings that do not appear in a table of contents.
17169 @xref{Structuring}.
17172 @item @@heading @var{title}
17173 Unnumbered section-like heading not listed
17174 in the table of contents of a printed manual.
17176 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
17181 @c subheading Font commands
17185 @xref{Smallcaps}, and @*
17189 @item @@r@{@var{text}@}
17190 Print in roman font.
17192 @item @@sc@{@var{text}@}
17193 Print in @sc{small caps} font.
17196 @c subheading Miscellaneous
17199 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
17200 see @ref{Customized Highlighting},@*
17201 see @ref{Overfull hboxes},@*
17202 see @ref{Footnotes},@*
17203 see @ref{dmn, , Format a Dimension},@*
17204 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
17205 see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@*
17206 see @ref{minus, , Inserting a Minus Sign},@*
17207 see @ref{paragraphindent, , Paragraph Indenting},@*
17208 see @ref{Cross Reference Commands},@*
17209 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
17210 see @ref{Custom Headings, , How to Make Your Own Headings}.
17213 @item @@author @var{author}
17214 Typeset author's name.
17216 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
17217 @c Define a highlighting command for Info. (Info only.)
17220 Produce cleaner printed output.
17222 @item @@footnotestyle @var{end-or-separate}
17223 Specify footnote style.
17225 @item @@dmn@{@var{dimension}@}
17226 Format a dimension.
17228 @item @@global@@let@var{new-cmd}=@var{existing-cmd}
17229 Define a highlighting command for @TeX{}. (@TeX{} only.)
17231 @item @@lowersections
17232 Reduce hierarchical level of sectioning commands.
17234 @item @@math@{@var{mathematical-expression}@}
17235 Format a mathematical expression.
17238 Generate a minus sign.
17240 @item @@paragraphindent @var{asis-or-number}
17241 Specify paragraph indentation.
17243 @item @@raisesections
17244 Raise hierarchical level of sectioning commands.
17246 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
17247 Make a reference. In the printed manual, the
17248 reference does not start with the word `see'.
17250 @item @@title @var{title}
17251 Typeset @var{title} in the alternative
17254 @item @@subtitle @var{subtitle}
17255 Typeset @var{subtitle} in the alternative
17259 Insert the current date.
17262 % Switch width of first column of tables back to default value
17263 \global\tableindent=.8in
17267 @node Command and Variable Index, Concept Index, Obtaining TeX, Top
17268 @comment node-name, next, previous, up
17269 @unnumbered Command and Variable Index
17271 This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
17272 functions, and several variables. To make the list easier to use, the
17273 commands are listed without their preceding @samp{@@}.@refill
17278 @node Concept Index, , Command and Variable Index, Top
17279 @unnumbered Concept Index