1 \input texinfo.tex @c -*-texinfo-*-
2 @c $Id: texinfo.txi,v 1.162 1999/09/28 19:38:01 karl Exp $
5 @c All text is ignored before the setfilename.
6 @setfilename ../info/texinfo.info
8 @set UPDATED 28 September 1999
11 @settitle Texinfo @value{VERSION}
13 @c Define a new index for options.
15 @c Put everything except function (command, in this case) names in one
16 @c index (arbitrarily chosen to be the concept index).
21 @footnotestyle separate
25 @comment %**end of header
27 @dircategory Texinfo documentation system
29 * Texinfo: (texinfo). The GNU documentation format.
30 * install-info: (texinfo)Invoking install-info. Update info/dir entries.
31 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
32 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
33 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
36 @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
37 @c prefix arg). This updates the node pointers, which texinfmt.el needs.
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 If you like blank pages. Can add through texi2dvi -t.
48 @c setchapternewpage odd
50 @c Currently undocumented command, 5 December 1993:
51 @c nwnode (Same as node, but no warnings; for `makeinfo'.)
54 This file documents Texinfo, a documentation system that can produce
55 both online information and a printed manual from a single source file.
57 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99
58 Free Software Foundation, Inc.
60 This edition is for Texinfo version @value{VERSION}, @value{UPDATED}.
62 Permission is granted to make and distribute verbatim copies of
63 this manual provided the copyright notice and this permission notice
64 are preserved on all copies.
67 Permission is granted to process this file through TeX and print the
68 results, provided the printed document carries copying permission
69 notice identical to this one except for the removal of this paragraph
70 (this paragraph not being relevant to the printed manual).
73 Permission is granted to copy and distribute modified versions of this
74 manual under the conditions for verbatim copying, provided that the entire
75 resulting derived work is distributed under the terms of a permission
76 notice identical to this one.
78 Permission is granted to copy and distribute translations of this manual
79 into another language, under the above conditions for modified versions,
80 except that this permission notice may be stated in a translation approved
81 by the Free Software Foundation.
85 @shorttitlepage Texinfo
88 @c use the new format for titles
90 @subtitle The GNU Documentation Format
91 @subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
93 @author Robert J. Chassell
94 @author Richard M. Stallman
96 @c Include the Distribution inside the titlepage so
97 @c that headings are turned off.
100 @vskip 0pt plus 1filll
101 Copyright @copyright{} 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99
102 Free Software Foundation, Inc.
104 This manual is for Texinfo version @value{VERSION}, @value{UPDATED}.
106 Published by the Free Software Foundation @*
107 59 Temple Place Suite 330 @*
108 Boston, MA 02111-1307 @*
110 ISBN 1-882114-67-1 @c for version 4.0, September 1999.
111 @c ISBN 1-882114-65-5 @c for version 3.12, March 1998.
112 @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
113 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
115 Permission is granted to make and distribute verbatim copies of
116 this manual provided the copyright notice and this permission notice
117 are preserved on all copies.
119 Permission is granted to copy and distribute modified versions of this
120 manual under the conditions for verbatim copying, provided that the entire
121 resulting derived work is distributed under the terms of a permission
122 notice identical to this one.
124 Permission is granted to copy and distribute translations of this manual
125 into another language, under the above conditions for modified versions,
126 except that this permission notice may be stated in a translation approved
127 by the Free Software Foundation.
129 Cover art by Etienne Suvasa.
139 Texinfo is a documentation system that uses a single source file to
140 produce both online information and printed output.
142 The first part of this master menu lists the major nodes in this Info
143 document, including the @@-command and concept indices. The rest of
144 the menu lists all the lower level nodes in the document.
146 This is Edition @value{VERSION} of the Texinfo manual, updated @value{UPDATED}.
150 * Copying:: Your rights.
151 * Overview:: Texinfo in brief.
152 * Texinfo Mode:: How to use Texinfo mode.
153 * Beginning a File:: What is at the beginning of a Texinfo file?
154 * Ending a File:: What is at the end of a Texinfo file?
155 * Structuring:: How to create chapters, sections, subsections,
156 appendices, and other parts.
157 * Nodes:: How to write nodes.
158 * Menus:: How to write menus.
159 * Cross References:: How to write cross references.
160 * Marking Text:: How to mark words and phrases as code,
161 keyboard input, meta-syntactic
162 variables, and the like.
163 * Quotations and Examples:: How to write quotations, examples, etc.
164 * Lists and Tables:: How to write lists and tables.
165 * Indices:: How to create indices.
166 * Insertions:: How to insert @@-signs, braces, etc.
167 * Breaks:: How to force and prevent line and page breaks.
168 * Definition Commands:: How to describe functions and the like
170 * Conditionals:: How to specify text for either @TeX{} or Info.
171 * Internationalization::
172 * Defining New Texinfo Commands::
173 * Hardcopy:: How to convert a Texinfo file to a file
174 for printing and how to print that file.
175 * Creating and Installing Info Files::
176 * Command List:: All the Texinfo @@-commands.
177 * Tips:: Hints on how to write a Texinfo document.
178 * Sample Texinfo File:: A sample Texinfo file to look at.
179 * Sample Permissions:: Tell readers they have the right to copy
181 * Include Files:: How to incorporate other Texinfo files.
182 * Headings:: How to write page headings and footings.
183 * Catching Mistakes:: How to find formatting mistakes.
184 * Refilling Paragraphs:: All about paragraph refilling.
185 * Command Syntax:: A description of @@-Command syntax.
186 * Obtaining TeX:: How to Obtain @TeX{}.
187 * Command and Variable Index:: A menu containing commands and variables.
188 * Concept Index:: A menu covering many topics.
192 --- The Detailed Node Listing ---
196 * Reporting Bugs:: Submitting effective bug reports.
197 * Using Texinfo:: Create printed or online output.
198 * Info Files:: What is an Info file?
199 * Printed Books:: Characteristics of a printed book or manual.
200 * Formatting Commands:: @@-commands are used for formatting.
201 * Conventions:: General rules for writing a Texinfo file.
202 * Comments:: Writing comments and ignored text in general.
203 * Minimum:: What a Texinfo file must have.
204 * Six Parts:: Usually, a Texinfo file has six parts.
205 * Short Sample:: A short sample Texinfo file.
206 * Acknowledgements and History:: Contributors and genesis.
210 * Texinfo Mode Overview:: How Texinfo mode can help you.
211 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
212 purpose editing features.
213 * Inserting:: How to insert frequently used @@-commands.
214 * Showing the Structure:: How to show the structure of a file.
215 * Updating Nodes and Menus:: How to update or create new nodes and menus.
216 * Info Formatting:: How to format for Info.
217 * Printing:: How to format and print part or all of a file.
218 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
220 Updating Nodes and Menus
222 * Updating Commands:: Five major updating commands.
223 * Updating Requirements:: How to structure a Texinfo file for
224 using the updating command.
225 * Other Updating Commands:: How to indent descriptions, insert
226 missing nodes lines, and update
229 Beginning a Texinfo File
231 * Four Parts:: Four parts begin a Texinfo file.
232 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
233 * Header:: The very beginning of a Texinfo file.
234 * Info Summary and Permissions:: Summary and copying permissions for Info.
235 * Titlepage & Copyright Page:: Creating the title and copyright pages.
236 * The Top Node:: Creating the `Top' node and master menu.
237 * Software Copying Permissions:: Ensure that you and others continue to
238 have the right to use and share software.
240 The Texinfo File Header
242 * First Line:: The first line of a Texinfo file.
243 * Start of Header:: Formatting a region requires this.
244 * setfilename:: Tell Info the name of the Info file.
245 * settitle:: Create a title for the printed work.
246 * setchapternewpage:: Start chapters on right-hand pages.
247 * paragraphindent:: Specify paragraph indentation.
248 * exampleindent:: Specify environment indentation.
249 * End of Header:: Formatting a region requires this.
251 The Title and Copyright Pages
253 * titlepage:: Create a title for the printed document.
254 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
255 and @code{@@sp} commands.
256 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
257 and @code{@@author} commands.
258 * Copyright & Permissions:: How to write the copyright notice and
259 include copying permissions.
260 * end titlepage:: Turn on page headings after the title and
262 * headings on off:: An option for turning headings on and off
263 and double or single sided printing.
265 The `Top' Node and Master Menu
267 * Title of Top Node:: Sketch what the file is about.
268 * Master Menu Parts:: A master menu has three or more parts.
270 Ending a Texinfo File
272 * Printing Indices & Menus:: How to print an index in hardcopy and
273 generate index menus in Info.
274 * Contents:: How to create a table of contents.
275 * File End:: How to mark the end of a file.
279 * Tree Structuring:: A manual is like an upside down tree @dots{}
280 * Structuring Command Types:: How to divide a manual into parts.
281 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
283 * unnumbered & appendix::
284 * majorheading & chapheading::
286 * unnumberedsec appendixsec heading::
288 * unnumberedsubsec appendixsubsec subheading::
289 * subsubsection:: Commands for the lowest level sections.
290 * Raise/lower sections:: How to change commands' hierarchical level.
294 * Two Paths:: Different commands to structure
295 Info output and printed output.
296 * Node Menu Illustration:: A diagram, and sample nodes and menus.
297 * node:: Creating nodes, in detail.
298 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
299 * anchor:: Defining arbitrary cross-reference targets.
301 The @code{@@node} Command
303 * Node Names:: How to choose node and pointer names.
304 * Writing a Node:: How to write an @code{@@node} line.
305 * Node Line Tips:: Keep names short.
306 * Node Line Requirements:: Keep names unique, without @@-commands.
307 * First Node:: How to write a `Top' node.
308 * makeinfo top command:: How to use the @code{@@top} command.
309 * Top Node Summary:: Write a brief description for readers.
313 * Menu Location:: Put a menu in a short node.
314 * Writing a Menu:: What is a menu?
315 * Menu Parts:: A menu entry has three parts.
316 * Less Cluttered Menu Entry:: Two part menu entry.
317 * Menu Example:: Two and three part menu entries.
318 * Other Info Files:: How to refer to a different Info file.
322 * References:: What cross references are for.
323 * Cross Reference Commands:: A summary of the different commands.
324 * Cross Reference Parts:: A cross reference has several parts.
325 * xref:: Begin a reference with `See' @dots{}
326 * Top Node Naming:: How to refer to the beginning of another file.
327 * ref:: A reference for the last part of a sentence.
328 * pxref:: How to write a parenthetical cross reference.
329 * inforef:: How to refer to an Info-only file.
330 * uref:: How to refer to a uniform resource locator.
334 * Reference Syntax:: What a reference looks like and requires.
335 * One Argument:: @code{@@xref} with one argument.
336 * Two Arguments:: @code{@@xref} with two arguments.
337 * Three Arguments:: @code{@@xref} with three arguments.
338 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
340 Marking Words and Phrases
342 * Indicating:: How to indicate definitions, files, etc.
343 * Emphasis:: How to emphasize text.
345 Indicating Definitions, Commands, etc.
347 * Useful Highlighting:: Highlighting provides useful information.
348 * code:: Indicating program code.
349 * kbd:: Showing keyboard input.
350 * key:: Specifying keys.
351 * samp:: Showing a literal sequence of characters.
352 * var:: Indicating metasyntactic variables.
353 * env:: Indicating environment variables.
354 * file:: Indicating file names.
355 * command:: Indicating command names.
356 * option:: Indicating option names.
357 * dfn:: Specifying definitions.
358 * cite:: Referring to books not in the Info system.
359 * acronym:: Indicating acronyms.
360 * url:: Indicating a World Wide Web reference.
361 * email:: Indicating an electronic mail address.
365 * emph & strong:: How to emphasize text in Texinfo.
366 * Smallcaps:: How to use the small caps font.
367 * Fonts:: Various font commands for printed output.
369 Quotations and Examples
371 * Block Enclosing Commands:: Use different constructs for
373 * quotation:: How to write a quotation.
374 * example:: How to write an example in a fixed-width font.
375 * noindent:: How to prevent paragraph indentation.
376 * lisp:: How to illustrate Lisp code.
377 * small:: Forms for @code{@@smallbook}.
378 * display:: How to write an example in the current font.
379 * format:: How to write an example that does not narrow
381 * exdent:: How to undo the indentation of a line.
382 * flushleft & flushright:: How to push text flushleft or flushright.
383 * cartouche:: How to draw cartouches around examples.
387 * Introducing Lists:: Texinfo formats lists for you.
388 * itemize:: How to construct a simple list.
389 * enumerate:: How to construct a numbered list.
390 * Two-column Tables:: How to construct a two-column table.
391 * Multi-column Tables:: How to construct generalized tables.
393 Making a Two-column Table
395 * table:: How to construct a two-column table.
396 * ftable vtable:: Automatic indexing for two-column tables.
397 * itemx:: How to put more entries in the first column.
401 * Multitable Column Widths:: Defining multitable column widths.
402 * Multitable Rows:: Defining multitable rows, with examples.
406 * Index Entries:: Choose different words for index entries.
407 * Predefined Indices:: Use different indices for different kinds
409 * Indexing Commands:: How to make an index entry.
410 * Combining Indices:: How to combine indices.
411 * New Indices:: How to define your own indices.
415 * syncodeindex:: How to merge two indices, using @code{@@code}
416 font for the merged-from index.
417 * synindex:: How to merge two indices, using the
418 default font of the merged-to index.
422 * Braces Atsigns:: How to insert braces, @samp{@@}.
423 * Inserting Space:: How to insert the right amount of space
425 * Inserting Accents:: How to insert accents and special characters.
426 * Dots Bullets:: How to insert dots and bullets.
427 * TeX and copyright:: How to insert the @TeX{} logo
428 and the copyright symbol.
429 * pounds:: How to insert the pounds currency symbol.
430 * minus:: How to insert a minus sign.
431 * math:: How to format a mathematical expression.
432 * Glyphs:: How to indicate results of evaluation,
433 expansion of macros, errors, etc.
434 * Footnotes:: How to include footnotes.
435 * Images:: How to include graphics.
437 Inserting @@ and Braces
439 * Inserting An Atsign:: How to insert @samp{@@}.
440 * Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
444 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
445 * Ending a Sentence:: Sometimes it does.
446 * Multiple Spaces:: Inserting multiple spaces.
447 * dmn:: How to format a dimension.
449 Inserting Ellipsis, Dots, and Bullets
451 * dots:: How to insert dots @dots{}
452 * bullet:: How to insert a bullet.
454 Inserting @TeX{} and the Copyright Symbol
456 * tex:: How to insert the @TeX{} logo.
457 * copyright symbol:: How to use @code{@@copyright}@{@}.
462 * result:: How to show the result of expression.
463 * expansion:: How to indicate an expansion.
464 * Print Glyph:: How to indicate printed output.
465 * Error Glyph:: How to indicate an error message.
466 * Equivalence:: How to indicate equivalence.
467 * Point Glyph:: How to indicate the location of point.
480 * Footnote Commands:: How to write a footnote in Texinfo.
481 * Footnote Styles:: Controlling how footnotes appear in Info.
483 Making and Preventing Breaks
485 * Break Commands:: Cause and prevent splits.
486 * Line Breaks:: How to force a single line to use two lines.
487 * - and hyphenation:: How to tell TeX about hyphenation points.
488 * w:: How to prevent unwanted line breaks.
489 * sp:: How to insert blank lines.
490 * page:: How to force the start of a new page.
491 * group:: How to prevent unwanted page breaks.
492 * need:: Another way to prevent unwanted page breaks.
496 * Def Cmd Template:: How to structure a description using a
498 * Optional Arguments:: How to handle optional and repeated arguments.
499 * deffnx:: How to group two or more `first' lines.
500 * Def Cmds in Detail:: All the definition commands.
501 * Def Cmd Conventions:: Conventions for writing definitions.
502 * Sample Function Definition::
504 The Definition Commands
506 * Functions Commands:: Commands for functions and similar entities.
507 * Variables Commands:: Commands for variables and similar entities.
508 * Typed Functions:: Commands for functions in typed languages.
509 * Typed Variables:: Commands for variables in typed languages.
510 * Abstract Objects:: Commands for object-oriented programming.
511 * Data Types:: The definition command for data types.
513 Conditionally Visible Text
515 * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
516 * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
517 * Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
518 * set clear value:: Designating which text to format (for
519 all output formats); and how to set a
520 flag to a string that you can insert.
522 @code{@@set}, @code{@@clear}, and @code{@@value}
524 * ifset ifclear:: Format a region if a flag is set.
525 * set value:: Expand a flag variable to a string.
526 * value Example:: An easy way to update edition information.
530 * documentlanguage:: Declaring the current language.
531 * documentencoding:: Declaring the input encoding.
533 Defining New Texinfo Commands
535 * Defining Macros:: Defining and undefining new commands.
536 * Invoking Macros:: Using a macro, once you've defined it.
537 * Macro Details:: Beyond basic macro usage.
538 * alias:: Command aliases.
539 * definfoenclose:: Customized highlighting.
541 Formatting and Printing Hardcopy
543 * Use TeX:: Use @TeX{} to format for hardcopy.
544 * Format with tex/texindex:: How to format with explicit shell commands.
545 * Format with texi2dvi:: A simpler way to format.
546 * Print with lpr:: How to print.
547 * Within Emacs:: How to format and print from an Emacs shell.
548 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
549 * Compile-Command:: How to print using Emacs's compile command.
550 * Requirements Summary:: @TeX{} formatting requirements summary.
551 * Preparing for TeX:: What to do before you use @TeX{}.
552 * Overfull hboxes:: What are and what to do with overfull hboxes.
553 * smallbook:: How to print small format books and manuals.
554 * A4 Paper:: How to print on European A4 paper.
555 * pagesizes:: How to print with customized page sizes.
556 * Cropmarks and Magnification:: How to print marks to indicate the size
557 of pages and how to print scaled up output.
558 * PDF Output:: Portable Document Format output.
560 Creating and Installing Info Files
562 * Creating an Info File::
563 * Install an Info File::
565 Creating an Info File
567 * makeinfo advantages:: @code{makeinfo} provides better error checking.
568 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
569 * makeinfo options:: Specify fill-column and other options.
570 * Pointer Validation:: How to check that pointers point somewhere.
571 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
572 * texinfo-format commands:: Two Info formatting commands written
573 in Emacs Lisp are an alternative
575 * Batch Formatting:: How to format for Info in Emacs Batch mode.
576 * Tag and Split Files:: How tagged and split files help Info
578 * makeinfo html:: Generating HTML output.
580 Installing an Info File
582 * Directory File:: The top level menu for all Info files.
583 * New Info File:: Listing a new info file.
584 * Other Info Directories:: How to specify Info files that are
585 located in other directories.
586 * Installing Dir Entries:: How to specify what menu entry to add
587 to the Info directory.
588 * Invoking install-info:: @code{install-info} options.
592 * Inserting Permissions:: How to put permissions in your document.
593 * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions.
594 * Titlepage Permissions:: Sample Titlepage copying permissions.
598 * Using Include Files:: How to use the @code{@@include} command.
599 * texinfo-multiple-files-update:: How to create and update nodes and
600 menus when using included files.
601 * Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
602 * Sample Include File:: A sample outer file with included files
603 within it; and a sample included file.
604 * Include Files Evolution:: How use of the @code{@@include} command
605 has changed over time.
609 * Headings Introduced:: Conventions for using page headings.
610 * Heading Format:: Standard page heading formats.
611 * Heading Choice:: How to specify the type of page heading.
612 * Custom Headings:: How to create your own headings and footings.
616 * makeinfo Preferred:: @code{makeinfo} finds errors.
617 * Debugging with Info:: How to catch errors with Info formatting.
618 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
619 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
620 * Using occur:: How to list all lines containing a pattern.
621 * Running Info-Validate:: How to find badly referenced nodes.
623 Finding Badly Referenced Nodes
625 * Using Info-validate:: How to run @code{Info-validate}.
626 * Unsplit:: How to create an unsplit file.
627 * Tagifying:: How to tagify a file.
628 * Splitting:: How to split a file manually.
632 @c Reward readers for getting to the end of the menu :).
633 @c Contributed by Arnold Robbins.
635 Documentation is like sex: when it is good, it is very, very good; and
636 when it is bad, it is better than nothing.
642 @unnumbered Texinfo Copying Conditions
643 @cindex Copying conditions
644 @cindex Conditions for copying Texinfo
646 The programs currently being distributed that relate to Texinfo include
647 portions of GNU Emacs, plus other separate programs (including
648 @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}).
649 These programs are @dfn{free}; this means that everyone is free to use
650 them and free to redistribute them on a free basis. The Texinfo-related
651 programs are not in the public domain; they are copyrighted and there
652 are restrictions on their distribution, but these restrictions are
653 designed to permit everything that a good cooperating citizen would want
654 to do. What is not allowed is to try to prevent others from further
655 sharing any version of these programs that they might get from
658 Specifically, we want to make sure that you have the right to give
659 away copies of the programs that relate to Texinfo, that you receive
660 source code or else can get it if you want it, that you can change these
661 programs or use pieces of them in new free programs, and that you know
662 you can do these things.@refill
664 To make sure that everyone has such rights, we have to forbid you to
665 deprive anyone else of these rights. For example, if you distribute
666 copies of the Texinfo related programs, you must give the recipients all
667 the rights that you have. You must make sure that they, too, receive or
668 can get the source code. And you must tell them their rights.@refill
670 Also, for our own protection, we must make certain that everyone finds
671 out that there is no warranty for the programs that relate to Texinfo.
672 If these programs are modified by someone else and passed on, we want
673 their recipients to know that what they have is not what we distributed,
674 so that any problems introduced by others will not reflect on our
677 The precise conditions of the licenses for the programs currently
678 being distributed that relate to Texinfo are found in the General Public
679 Licenses that accompany them.
683 @chapter Overview of Texinfo
684 @cindex Overview of Texinfo
685 @cindex Texinfo overview
687 @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
688 like ``speck'', not ``hex''. This odd pronunciation is derived from,
689 but is not the same as, the pronunciation of @TeX{}. In the word
690 @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
691 the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
692 last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
693 were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
694 letters in lower case.} is a documentation system that uses a single
695 source file to produce both online information and printed output. This
696 means that instead of writing two different documents, one for the
697 online information and the other for a printed work, you need write only
698 one document. Therefore, when the work is revised, you need revise only
702 * Reporting Bugs:: Submitting effective bug reports.
703 * Using Texinfo:: Create printed or online output.
704 * Info Files:: What is an Info file?
705 * Printed Books:: Characteristics of a printed book or manual.
706 * Formatting Commands:: @@-commands are used for formatting.
707 * Conventions:: General rules for writing a Texinfo file.
708 * Comments:: Writing comments and ignored text in general.
709 * Minimum:: What a Texinfo file must have.
710 * Six Parts:: Usually, a Texinfo file has six parts.
711 * Short Sample:: A short sample Texinfo file.
712 * Acknowledgements and History:: Contributors and genesis.
717 @section Reporting Bugs
719 @cindex Bugs, reporting
720 @cindex Suggestions for Texinfo, making
721 @cindex Reporting bugs
722 We welcome bug reports or suggestions for the Texinfo system, both
723 programs and documentation. Please email them to
724 @email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo
725 from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
727 @cindex Checklist for bug reports
728 For bug reports, please include enough information for the maintainers
729 to reproduce the problem. Generally speaking, that means:
732 @item the version number of Texinfo and the program(s) or manual(s) involved.
733 @item hardware, operating system, and compiler versions.
734 @item any unusual options you gave to @command{configure}.
735 @item the contents of any input files necessary to reproduce the bug.
736 @item a description of the problem and samples of any erroneous output.
737 @item anything else that you think would be helpful.
740 When in doubt whether something is needed or not, include it. It's
741 better to include too much than to leave out something important.
743 Patches are most welcome; if possible, please make them with
744 @samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
745 Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
746 Log,,, emacs, The GNU Emacs Manual}).
748 When sending email, please do not encode or split the messages in any
749 way if possible; it's much easier to deal with one plain text message,
750 however large, than many small ones.
751 @uref{ftp://ftp.gnu.org/gnu/sharutils/, GNU shar} is a convenient way of
752 packaging multiple and/or binary files for email.
756 @section Using Texinfo
758 @cindex Using Texinfo in general
759 @cindex Texinfo, introduction to
760 @cindex Introduction to Texinfo
762 Using Texinfo, you can create a printed document with the normal
763 features of a book, including chapters, sections, cross references, and
764 indices. From the same Texinfo source file, you can create a
765 menu-driven, online Info file with nodes, menus, cross references, and
766 indices. You can also create from that same source file an HTML output
767 file suitable for use with a web browser. @cite{The GNU Emacs Manual}
768 is a good example of a Texinfo file, as is this manual.
770 To make a printed document, you process a Texinfo source file with the
771 @TeX{} typesetting program (but the Texinfo language is very different
772 from @TeX{}'s usual language, plain @TeX{}). This creates a DVI file
773 that you can typeset and print as a book or report (@pxref{Hardcopy}).
776 To output an Info file, process your Texinfo source with the
777 @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
778 You can install the result in your Info tree (@pxref{Install an Info
781 To output an HTML file, process your Texinfo source with @code{makeinfo}
782 using the @samp{--html} option. You can (for example) install the
783 result on your web site.
785 @cindex Output formats, supporting more
786 @cindex Docbook output format
787 @cindex SGML-tools output format
788 If you are a programmer and would like to contribute to the GNU project
789 by implementing additional output formats for Texinfo, that would be
790 excellent. But please do not write a separate translator texi2foo for
791 your favorite format foo! That is the hard way to do the job, and makes
792 extra work in subsequent maintenance, since the Texinfo language is
793 continually being enhanced and updated. Instead, the best approach is
794 modify @code{makeinfo} to generate the new format, as it does now for
797 @TeX{} works with virtually all printers; Info works with virtually all
798 computer terminals; the HTML output works with virtually all web
799 browsers. Thus Texinfo can be used by almost any computer user.
802 A Texinfo source file is a plain @sc{ascii} file containing text and
803 @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
804 typesetting and formatting programs what to do. You may edit a Texinfo
805 file with any text editor; but it is especially convenient to use GNU
806 Emacs since that editor has a special mode, called Texinfo mode, that
807 provides various Texinfo-related features. (@xref{Texinfo Mode}.)
809 Before writing a Texinfo source file, you should learn about nodes,
810 menus, cross references, and the rest, for example by reading this
813 You can use Texinfo to create both online help and printed manuals;
814 moreover, Texinfo is freely redistributable. For these reasons, Texinfo
815 is the official documentation format of the GNU project. More
816 information is available at the @uref{http://www.gnu.org/doc/, GNU
817 documentation web page}.
819 @cindex Man page output, not supported
820 From time to time, proposals are made to generate traditional Unix man
821 pages from Texinfo source. This is not likely to ever be supported,
822 because man pages have a very strict conventional format. Merely
823 enhancing @command{makeinfo} to output troff format would be
824 insufficient. Generating a good man page therefore requires a
825 completely different source than the typical Texinfo applications of
826 generating a good user manual or a good reference manual. This makes
827 generating man pages incompatible with the Texinfo design goal of not
828 having to document the same information in different ways for different
829 output formats. You might as well just write the man page directly.
832 @cindex O'Dea, Brendan
833 If you wish to support man pages, the program @command{help2man} may be
834 useful; it generates a traditional man page from the @samp{--help}
835 output of a program. In fact, this is currently used to generate man
836 pages for the Texinfo programs themselves. It is free software written
837 by Brendan O'Dea, available from
838 @uref{http://www.ozemail.com.au/~bod/help2man.tar.gz}.
845 An Info file is a Texinfo file formatted so that the Info documentation
846 reading program can operate on it. (@code{makeinfo}
847 and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
848 into an Info file.)@refill
850 Info files are divided into pieces called @dfn{nodes}, each of which
851 contains the discussion of one topic. Each node has a name, and
852 contains both text for the user to read and pointers to other nodes,
853 which are identified by their names. The Info program displays one node
854 at a time, and provides commands with which the user can move to other
855 related nodes.@refill
858 @inforef{Top, info, info}, for more information about using Info.@refill
861 Each node of an Info file may have any number of child nodes that
862 describe subtopics of the node's topic. The names of child
863 nodes are listed in a @dfn{menu} within the parent node; this
864 allows you to use certain Info commands to move to one of the child
865 nodes. Generally, an Info file is organized like a book. If a node
866 is at the logical level of a chapter, its child nodes are at the level
867 of sections; likewise, the child nodes of sections are at the level
868 of subsections.@refill
870 All the children of any one parent are linked together in a
871 bidirectional chain of `Next' and `Previous' pointers. The `Next'
872 pointer provides a link to the next section, and the `Previous' pointer
873 provides a link to the previous section. This means that all the nodes
874 that are at the level of sections within a chapter are linked together.
875 Normally the order in this chain is the same as the order of the
876 children in the parent's menu. Each child node records the parent node
877 name as its `Up' pointer. The last child has no `Next' pointer, and the
878 first child has the parent both as its `Previous' and as its `Up'
879 pointer.@footnote{In some documents, the first child has no `Previous'
880 pointer. Occasionally, the last child has the node name of the next
881 following higher level node as its `Next' pointer.}@refill
883 The book-like structuring of an Info file into nodes that correspond
884 to chapters, sections, and the like is a matter of convention, not a
885 requirement. The `Up', `Previous', and `Next' pointers of a node can
886 point to any other nodes, and a menu can contain any other nodes.
887 Thus, the node structure can be any directed graph. But it is usually
888 more comprehensible to follow a structure that corresponds to the
889 structure of chapters and sections in a printed book or report.@refill
891 In addition to menus and to `Next', `Previous', and `Up' pointers, Info
892 provides pointers of another kind, called references, that can be
893 sprinkled throughout the text. This is usually the best way to
894 represent links that do not fit a hierarchical structure.@refill
896 Usually, you will design a document so that its nodes match the
897 structure of chapters and sections in the printed output. But
898 occasionally there are times when this is not right for the material
899 being discussed. Therefore, Texinfo uses separate commands to specify
900 the node structure for the Info file and the section structure for the
901 printed output.@refill
903 Generally, you enter an Info file through a node that by convention is
904 named `Top'. This node normally contains just a brief summary of the
905 file's purpose, and a large menu through which the rest of the file is
906 reached. From this node, you can either traverse the file
907 systematically by going from node to node, or you can go to a specific
908 node listed in the main menu, or you can search the index menus and then
909 go directly to the node that has the information you want. Alternatively,
910 with the standalone Info program, you can specify specific menu items on
911 the command line (@pxref{Top,,, info, Info}).
913 If you want to read through an Info file in sequence, as if it were a
914 printed manual, you can hit @key{SPC} repeatedly, or you get the whole
915 file with the advanced Info command @kbd{g *}. (@inforef{Expert,
916 Advanced Info commands, info}.)@refill
918 @c !!! dir file may be located in one of many places:
919 @c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH
920 @c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH
921 @c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH
923 @c /usr/local/lib/info
924 The @file{dir} file in the @file{info} directory serves as the
925 departure point for the whole Info system. From it, you can reach the
926 `Top' nodes of each of the documents in a complete Info system.@refill
928 @cindex URI syntax for Info
929 If you wish to refer to an Info file in a URI, you can use the
930 (unofficial) syntax exemplified in the following. This works with
931 Emacs/W3, for example:
933 info:///usr/info/emacs#Dissociated%20Press
934 info:emacs#Dissociated%20Press
935 info://localhost/usr/info/emacs#Dissociated%20Press
938 The @command{info} program itself does not follow URI's of any kind.
942 @section Printed Books
943 @cindex Printed book and manual characteristics
944 @cindex Manual characteristics, printed
945 @cindex Book characteristics, printed
946 @cindex Texinfo printed book characteristics
947 @cindex Characteristics, printed books or manuals
949 @cindex Knuth, Donald
950 A Texinfo file can be formatted and typeset as a printed book or manual.
951 To do this, you need @TeX{}, a powerful, sophisticated typesetting
952 program written by Donald Knuth.@footnote{You can also use the
953 @pindex texi2roff@r{, unsupported software}
954 @uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
955 do not have @TeX{}; since Texinfo is designed for use with @TeX{},
956 @code{texi2roff} is not described here. @code{texi2roff} is not part of
957 the standard GNU distribution and is not maintained or up-to-date with
958 all the Texinfo features described in this manual.}
960 A Texinfo-based book is similar to any other typeset, printed work: it
961 can have a title page, copyright page, table of contents, and preface,
962 as well as chapters, numbered or unnumbered sections and subsections,
963 page headers, cross references, footnotes, and indices.@refill
965 You can use Texinfo to write a book without ever having the intention
966 of converting it into online information. You can use Texinfo for
967 writing a printed novel, and even to write a printed memo, although
968 this latter application is not recommended since electronic mail is so
971 @TeX{} is a general purpose typesetting program. Texinfo provides a
972 file @file{texinfo.tex} that contains information (definitions or
973 @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
974 (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
975 to @TeX{} commands, which @TeX{} can then process to create the typeset
976 document.) @file{texinfo.tex} contains the specifications for printing
977 a document. You can get the latest version of @file{texinfo.tex} from
978 @uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
980 Most often, documents are printed on 8.5 inch by 11 inch
981 pages (216@dmn{mm} by 280@dmn{mm}; this is the default size), but you
982 can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
983 235@dmn{mm}; the @code{@@smallbook} size) or on European A4 size paper
984 (@code{@@afourpaper}). (@xref{smallbook, , Printing ``Small'' Books}.
985 Also, see @ref{A4 Paper, ,Printing on A4 Paper}.)@refill
987 By changing the parameters in @file{texinfo.tex}, you can change the
988 size of the printed document. In addition, you can change the style in
989 which the printed document is formatted; for example, you can change the
990 sizes and fonts used, the amount of indentation for each paragraph, the
991 degree to which words are hyphenated, and the like. By changing the
992 specifications, you can make a book look dignified, old and serious, or
993 light-hearted, young and cheery.@refill
995 @TeX{} is freely distributable. It is written in a superset of Pascal
996 called WEB and can be compiled either in Pascal or (by using a
997 conversion program that comes with the @TeX{} distribution) in C.
998 (@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
999 about @TeX{}.)@refill
1001 @TeX{} is very powerful and has a great many features. Because a
1002 Texinfo file must be able to present information both on a
1003 character-only terminal in Info form and in a typeset book, the
1004 formatting commands that Texinfo supports are necessarily
1007 To get a copy of @TeX{}, see
1008 @ref{Obtaining TeX, , How to Obtain @TeX{}}.
1011 @node Formatting Commands, Conventions, Printed Books, Overview
1012 @comment node-name, next, previous, up
1013 @section @@-commands
1015 @cindex Formatting commands
1017 In a Texinfo file, the commands that tell @TeX{} how to typeset the
1018 printed manual and tell @code{makeinfo} and
1019 @code{texinfo-format-buffer} how to create an Info file are preceded
1020 by @samp{@@}; they are called @dfn{@@-commands}. For example,
1021 @code{@@node} is the command to indicate a node and @code{@@chapter}
1022 is the command to indicate the start of a chapter.@refill
1025 @strong{Please note:} All the @@-commands, with the exception of the
1026 @code{@@TeX@{@}} command, must be written entirely in lower
1030 The Texinfo @@-commands are a strictly limited set of constructs. The
1031 strict limits make it possible for Texinfo files to be understood both
1032 by @TeX{} and by the code that converts them into Info files. You can
1033 display Info files on any terminal that displays alphabetic and
1034 numeric characters. Similarly, you can print the output generated by
1035 @TeX{} on a wide variety of printers.@refill
1037 Depending on what they do or what arguments@footnote{The word
1038 @dfn{argument} comes from the way it is used in mathematics and does not
1039 refer to a dispute between two people; it refers to the information
1040 presented to the command. According to the @cite{Oxford English
1041 Dictionary}, the word derives from the Latin for @dfn{to make clear,
1042 prove}; thus it came to mean `the evidence offered as proof', which is
1043 to say, `the information offered', which led to its mathematical
1044 meaning. In its other thread of derivation, the word came to mean `to
1045 assert in a manner against which others may make counter assertions',
1046 which led to the meaning of `argument' as a dispute.} they take, you
1047 need to write @@-commands on lines of their own or as part of
1052 Write a command such as @code{@@noindent} at the beginning of a line as
1053 the only text on the line. (@code{@@noindent} prevents the beginning of
1054 the next line from being indented as the beginning of a
1058 Write a command such as @code{@@chapter} at the beginning of a line
1059 followed by the command's arguments, in this case the chapter title, on
1060 the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
1063 Write a command such as @code{@@dots@{@}} wherever you wish but usually
1064 within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
1067 Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
1068 wish (but usually within a sentence) with its argument,
1069 @var{sample-code} in this example, between the braces. (@code{@@code}
1070 marks text as being code.)@refill
1073 Write a command such as @code{@@example} on a line of its own; write the
1074 body-text on following lines; and write the matching @code{@@end}
1075 command, @code{@@end example} in this case, at the on a line of its own
1076 after the body-text. (@code{@@example} @dots{} @code{@@end example}
1077 indents and typesets body-text as an example.) It's usually ok to
1078 indent environment commands like this, but in complicated and
1079 hard-to-define circumstances the extra spaces cause extra space to
1080 appear in the output, so beware.
1084 @cindex Braces, when to use
1085 As a general rule, a command requires braces if it mingles among other
1086 text; but it does not need braces if it starts a line of its own. The
1087 non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1088 they do not need braces.@refill
1090 As you gain experience with Texinfo, you will rapidly learn how to
1091 write the different commands: the different ways to write commands
1092 make it easier to write and read Texinfo files than if all commands
1093 followed exactly the same syntax. (For details about @@-command
1094 syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1096 @node Conventions, Comments, Formatting Commands, Overview
1097 @comment node-name, next, previous, up
1098 @section General Syntactic Conventions
1099 @cindex General syntactic conventions
1100 @cindex Syntactic conventions
1101 @cindex Conventions, syntactic
1103 This section describes the general conventions used in all Texinfo documents.
1107 All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1108 @samp{@}} can appear in a Texinfo file and stand for themselves.
1109 @samp{@@} is the escape character which introduces commands.
1110 @samp{@{} and @samp{@}} should be used only to surround arguments to
1111 certain commands. To put one of these special characters into the
1112 document, put an @samp{@@} character in front of it, like this:
1113 @samp{@@@@}, @samp{@@@{}, and @samp{@@@}}.@refill
1117 It is customary in @TeX{} to use doubled single-quote characters to
1118 begin and end quotations: ` ` and ' ' (but without a space between the
1119 two single-quote characters). This convention should be followed in
1120 Texinfo files. @TeX{} converts doubled single-quote characters to
1121 left- and right-hand doubled quotation marks and Info converts doubled
1122 single-quote characters to @sc{ascii} double-quotes: ` ` and ' ' to " .@refill
1125 It is customary in @TeX{} to use doubled single-quote characters to
1126 begin and end quotations: @w{@t{ `` }} and @w{@t{ '' }}. This
1127 convention should be followed in Texinfo files. @TeX{} converts
1128 doubled single-quote characters to left- and right-hand doubled
1129 quotation marks, ``like this'', and Info converts doubled single-quote
1130 characters to @sc{ascii} double-quotes: @w{@t{ `` }} and
1131 @w{@t{ '' }} to @w{@t{ " }}.@refill
1135 Use three hyphens in a row, @samp{---}, for a dash---like this. In
1136 @TeX{}, a single or double hyphen produces a printed dash that is
1137 shorter than the usual typeset dash. Info reduces three hyphens to two
1138 for display on the screen.
1141 To prevent a paragraph from being indented in the printed manual, put
1142 the command @code{@@noindent} on a line by itself before the
1146 If you mark off a region of the Texinfo file with the @code{@@iftex}
1147 and @w{@code{@@end iftex}} commands, that region will appear only in
1148 the printed copy; in that region, you can use certain commands
1149 borrowed from plain @TeX{} that you cannot use in Info. Likewise, if
1150 you mark off a region with the @code{@@ifinfo} and @code{@@end ifinfo}
1151 commands, that region will appear only in the Info file; in that
1152 region, you can use Info commands that you cannot use in @TeX{}.
1153 Similarly for @code{@@ifhtml @dots{} @@end ifhtml},
1154 @code{@@ifnothtml @dots{} @@end ifnothtml},
1155 @code{@@ifnotinfo @dots{} @@end ifnotinfo},
1156 @code{@@ifnottex @dots{} @@end ifnottex}.
1157 @xref{Conditionals}.
1160 @cindex Tabs; don't use!
1162 @strong{Caution:} Do not use tabs in a Texinfo file! @TeX{} uses
1163 variable-width fonts, which means that it cannot predefine a tab to work
1164 in all circumstances. Consequently, @TeX{} treats tabs like single
1165 spaces, and that is not what they look like. Furthermore,
1166 @code{makeinfo} does nothing special with tabs, and thus a tab character
1167 in your input file may appear differently in the output.
1170 To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1171 spaces when you press the @key{TAB} key.@refill
1174 Also, you can run @code{untabify} in Emacs to convert tabs in a region
1175 to multiple spaces.@refill
1178 @node Comments, Minimum, Conventions, Overview
1179 @comment node-name, next, previous, up
1182 You can write comments in a Texinfo file that will not appear in
1183 either the Info file or the printed manual by using the
1184 @code{@@comment} command (which may be abbreviated to @code{@@c}).
1185 Such comments are for the person who revises the Texinfo file. All the
1186 text on a line that follows either @code{@@comment} or @code{@@c} is a
1187 comment; the rest of the line does not appear in either the Info file
1188 or the printed manual. (Often, you can write the @code{@@comment} or
1189 @code{@@c} in the middle of a line, and only the text that follows after
1190 the @code{@@comment} or @code{@@c} command does not appear; but some
1191 commands, such as @code{@@settitle} and @code{@@setfilename}, work on a
1192 whole line. You cannot use @code{@@comment} or @code{@@c} in a line
1193 beginning with such a command.)@refill
1196 @findex c @r{(comment)}
1198 You can write long stretches of text that will not appear in either
1199 the Info file or the printed manual by using the @code{@@ignore} and
1200 @code{@@end ignore} commands. Write each of these commands on a line
1201 of its own, starting each command at the beginning of the line. Text
1202 between these two commands does not appear in the processed output.
1203 You can use @code{@@ignore} and @code{@@end ignore} for writing
1204 comments. Often, @code{@@ignore} and @code{@@end ignore} is used
1205 to enclose a part of the copying permissions that applies to the
1206 Texinfo source file of a document, but not to the Info or printed
1207 version of the document.@refill
1208 @cindex Ignored text
1209 @cindex Unprocessed text
1211 @c !!! Perhaps include this comment about ignore and ifset:
1213 Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1214 @code{@@ifclear} conditions is ignored in the sense that it will not
1215 contribute to the formatted output. However, TeX and makeinfo must
1216 still parse the ignored text, in order to understand when to
1217 @emph{stop} ignoring text from the source file; that means that you
1218 will still get error messages if you have invalid Texinfo markup
1219 within ignored text.
1222 @node Minimum, Six Parts, Comments, Overview
1223 @comment node-name, next, previous, up
1224 @section What a Texinfo File Must Have
1225 @cindex Minimal Texinfo file (requirements)
1226 @cindex Must have in Texinfo file
1227 @cindex Required in Texinfo file
1228 @cindex Texinfo file minimum
1230 By convention, the names of Texinfo files end with one of the
1231 extensions @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.
1232 The longer extension is preferred since it describes more clearly to a
1233 human reader the nature of the file. The shorter extensions are for
1234 operating systems that cannot handle long file names.@refill
1236 In order to be made into a printed manual and an Info file, a Texinfo
1237 file @strong{must} begin with lines like this:@refill
1242 @@setfilename @var{info-file-name}
1243 @@settitle @var{name-of-manual}
1248 The contents of the file follow this beginning, and then you @strong{must} end
1249 a Texinfo file with a line like this:@refill
1255 @findex input @r{(@TeX{} command)}
1257 The @samp{\input texinfo} line tells @TeX{} to use the
1258 @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1259 @@-commands into @TeX{} typesetting commands. (Note the use of the
1260 backslash, @samp{\}; this is correct for @TeX{}.) The
1261 @samp{@@setfilename} line provides a name for the Info file and tells
1262 @TeX{} to open auxiliary files. The @samp{@@settitle} line specifies a
1263 title for the page headers (or footers) of the printed manual.@refill
1265 The @code{@@bye} line at the end of the file on a line of its own tells
1266 the formatters that the file is ended and to stop formatting.@refill
1268 Usually, you will not use quite such a spare format, but will include
1269 mode setting and start-of-header and end-of-header lines at the
1270 beginning of a Texinfo file, like this:@refill
1274 \input texinfo @@c -*-texinfo-*-
1275 @@c %**start of header
1276 @@setfilename @var{info-file-name}
1277 @@settitle @var{name-of-manual}
1278 @@c %**end of header
1283 In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1284 Texinfo mode when you edit the file.
1286 The @code{@@c} lines which surround the @samp{@@setfilename} and
1287 @samp{@@settitle} lines are optional, but you need them in order to
1288 run @TeX{} or Info on just part of the file. (@xref{Start of Header},
1289 for more information.)@refill
1291 Furthermore, you will usually provide a Texinfo file with a title
1292 page, indices, and the like. But the minimum, which can be useful
1293 for short documents, is just the three lines at the beginning and the
1294 one line at the end.@refill
1296 @node Six Parts, Short Sample, Minimum, Overview
1297 @comment node-name, next, previous, up
1298 @section Six Parts of a Texinfo File
1300 Generally, a Texinfo file contains more than the minimal
1301 beginning and end---it usually contains six parts:@refill
1305 The @dfn{Header} names the file, tells @TeX{} which definitions' file to
1306 use, and performs other ``housekeeping'' tasks.@refill
1308 @item 2. Summary Description and Copyright
1309 The @dfn{Summary Description and Copyright} segment describes the document
1310 and contains the copyright notice and copying permissions for the Info
1311 file. The segment must be enclosed between @code{@@ifinfo} and
1312 @code{@@end ifinfo} commands so that the formatters place it only in the Info
1315 @item 3. Title and Copyright
1316 The @dfn{Title and Copyright} segment contains the title and copyright pages
1317 and copying permissions for the printed manual. The segment must be
1318 enclosed between @code{@@titlepage} and @code{@@end titlepage} commands.
1319 The title and copyright page appear only in the printed @w{manual}.@refill
1321 @item 4. `Top' Node and Master Menu
1322 The @dfn{Master Menu} contains a complete menu of all the nodes in the whole
1323 Info file. It appears only in the Info file, in the `Top' node.@refill
1326 The @dfn{Body} of the document may be structured like a traditional book or
1327 encyclopedia or it may be free form.@refill
1330 The @dfn{End} contains commands for printing indices and generating
1331 the table of contents, and the @code{@@bye} command on a line of its
1336 @section A Short Sample Texinfo File
1337 @cindex Sample Texinfo file
1339 Here is a complete but very short Texinfo file, in six parts. The first
1340 three parts of the file, from @samp{\input texinfo} through to
1341 @samp{@@end titlepage}, look more intimidating than they are. Most of
1342 the material is standard boilerplate; when you write a manual, simply
1343 insert the names for your own manual in this segment. (@xref{Beginning a
1346 In the following, the sample text is @emph{indented}; comments on it are
1347 not. The complete file, without any comments, is shown in
1348 @ref{Sample Texinfo File}.
1350 @subheading Part 1: Header
1353 The header does not appear in either the Info file or the
1354 printed output. It sets various parameters, including the
1355 name of the Info file and the title used in the header.
1359 \input texinfo @@c -*-texinfo-*-
1360 @@c %**start of header
1361 @@setfilename sample.info
1362 @@settitle Sample Document
1363 @@setchapternewpage odd
1364 @@c %**end of header
1368 @subheading Part 2: Summary Description and Copyright
1371 The summary description and copyright segment does not
1372 appear in the printed document.
1377 This is a short example of a complete Texinfo file.
1379 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
1384 @subheading Part 3: Titlepage and Copyright
1387 The titlepage segment does not appear in the Info file.
1393 @@comment The title is printed in a large font.
1394 @@center @@titlefont@{Sample Title@}
1398 @@c The following two commands start the copyright page.
1400 @@vskip 0pt plus 1filll
1401 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
1406 @subheading Part 4: `Top' Node and Master Menu
1409 The `Top' node contains the master menu for the Info file.
1410 Since a printed manual uses a table of contents rather than
1411 a menu, the master menu appears only in the Info file.
1415 @@node Top, First Chapter, , (dir)
1416 @@comment node-name, next, previous, up
1423 * First Chapter:: The first chapter is the
1424 only chapter in this sample.
1425 * Concept Index:: This index has two entries.
1430 @subheading Part 5: The Body of the Document
1433 The body segment contains all the text of the document, but not the
1434 indices or table of contents. This example illustrates a node and a
1435 chapter containing an enumerated list.@refill
1439 @@node First Chapter, Concept Index, Top, Top
1440 @@comment node-name, next, previous, up
1441 @@chapter First Chapter
1442 @@cindex Sample index entry
1446 This is the contents of the first chapter.
1447 @@cindex Another sample index entry
1451 Here is a numbered list.
1455 This is the first item.
1458 This is the second item.
1463 The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
1464 commands transform a Texinfo file such as this into
1465 an Info file; and @@TeX@{@} typesets it for a printed
1470 @subheading Part 6: The End of the Document
1473 The end segment contains commands for generating an index in a node and
1474 unnumbered chapter of its own, (usually) for generating the table of
1475 contents, and the @code{@@bye} command that marks the end of the
1480 @@node Concept Index, , First Chapter, Top
1481 @@unnumbered Concept Index
1492 @subheading The Results
1494 Here is what the contents of the first chapter of the sample look like:
1499 This is the contents of the first chapter.
1501 Here is a numbered list.
1505 This is the first item.
1508 This is the second item.
1511 The @code{makeinfo} and @code{texinfo-format-buffer}
1512 commands transform a Texinfo file such as this into
1513 an Info file; and @TeX{} typesets it for a printed
1518 @node Acknowledgements and History
1519 @section Acknowledgements and History
1521 @cindex Stallman, Richard M.
1522 @cindex Chassell, Robert J.
1524 Richard M.@: Stallman invented the Texinfo format, wrote the initial
1525 processors, and created Edition 1.0 of this manual. @w{Robert J.@:
1526 Chassell} greatly revised and extended the manual, starting with Edition
1527 1.1. Brian Fox was responsible for the standalone Texinfo distribution
1528 until version 3.8, and wrote the standalone @command{makeinfo} and
1529 @command{info}. Karl Berry has made the updates since Texinfo 3.8 and
1530 subsequent releases, starting with Edition 2.22 of the manual.
1532 @cindex Pinard, Fran@,{c}ois
1533 @cindex Zuhn, David D.
1534 @cindex Weisshaus, Melissa
1535 @cindex Zaretskii, Eli
1536 @cindex Schwab, Andreas
1537 @cindex Weinberg, Zack
1538 Our thanks go out to all who helped improve this work, particularly to
1539 Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, who tirelessly recorded and
1540 reported mistakes and obscurities; our special thanks go to Melissa
1541 Weisshaus for her frequent and often tedious reviews of nearly similar
1542 editions. The indefatigable Eli Zaretskii and Andreas Schwab have
1543 provided patches beyond counting. Zack Weinberg did the impossible by
1544 implementing the macro syntax in @file{texinfo.tex}. Dozens of others
1545 have contributed patches and suggestions, they are gratefully
1546 acknowledged in the @file{ChangeLog} file. Our mistakes are our own.
1550 @cindex History of Texinfo
1551 A bit of history: in the 1970's at CMU, Brian Reid developed a program
1552 and format named Scribe to mark up documents for printing. It used the
1553 @code{@@} character to introduce commands as Texinfo does and strived to
1554 describe document contents rather than formatting.
1558 Meanwhile, people at MIT developed another, not too dissimilar format
1559 called Bolio. This then was converted to using @TeX{} as its typesetting
1562 Bo@TeX{} could only be used as a markup language for documents to be
1563 printed, not for online documents. Richard Stallman (RMS) worked on
1564 both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1565 called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
1566 mark up language for text that is intended to be read both on line and
1567 as printed hard copy.
1572 @chapter Using Texinfo Mode
1573 @cindex Texinfo mode
1574 @cindex Mode, using Texinfo
1578 You may edit a Texinfo file with any text editor you choose. A Texinfo
1579 file is no different from any other @sc{ascii} file. However, GNU Emacs
1580 comes with a special mode, called Texinfo
1581 mode, that provides Emacs commands and tools to help ease your work.@refill
1583 This chapter describes features of GNU Emacs' Texinfo mode but not any
1584 features of the Texinfo formatting language. If you are reading this
1585 manual straight through from the beginning, you may want to skim through
1586 this chapter briefly and come back to it after reading succeeding
1587 chapters which describe the Texinfo formatting language in
1591 * Texinfo Mode Overview:: How Texinfo mode can help you.
1592 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1593 purpose editing features.
1594 * Inserting:: How to insert frequently used @@-commands.
1595 * Showing the Structure:: How to show the structure of a file.
1596 * Updating Nodes and Menus:: How to update or create new nodes and menus.
1597 * Info Formatting:: How to format for Info.
1598 * Printing:: How to format and print part or all of a file.
1599 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
1602 @node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
1604 @heading Texinfo Mode Overview
1607 Texinfo mode provides special features for working with Texinfo
1613 Insert frequently used @@-commands. @refill
1616 Automatically create @code{@@node} lines.
1619 Show the structure of a Texinfo source file.@refill
1622 Automatically create or update the `Next',
1623 `Previous', and `Up' pointers of a node.
1626 Automatically create or update menus.@refill
1629 Automatically create a master menu.@refill
1632 Format a part or all of a file for Info.@refill
1635 Typeset and print part or all of a file.@refill
1638 Perhaps the two most helpful features are those for inserting frequently
1639 used @@-commands and for creating node pointers and menus.@refill
1641 @node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
1642 @section The Usual GNU Emacs Editing Commands
1644 In most cases, the usual Text mode commands work the same in Texinfo
1645 mode as they do in Text mode. Texinfo mode adds new editing commands
1646 and tools to GNU Emacs' general purpose editing features. The major
1647 difference concerns filling. In Texinfo mode, the paragraph
1648 separation variable and syntax table are redefined so that Texinfo
1649 commands that should be on lines of their own are not inadvertently
1650 included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
1651 command will refill a paragraph but not mix an indexing command on a
1652 line adjacent to it into the paragraph.@refill
1654 In addition, Texinfo mode sets the @code{page-delimiter} variable to
1655 the value of @code{texinfo-chapter-level-regexp}; by default, this is
1656 a regular expression matching the commands for chapters and their
1657 equivalents, such as appendices. With this value for the page
1658 delimiter, you can jump from chapter title to chapter title with the
1659 @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1660 (@code{backward-page}) commands and narrow to a chapter with the
1661 @kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
1662 The GNU Emacs Manual}, for details about the page commands.)@refill
1664 You may name a Texinfo file however you wish, but the convention is to
1665 end a Texinfo file name with one of the extensions
1666 @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
1667 extension is preferred, since it is explicit, but a shorter extension
1668 may be necessary for operating systems that limit the length of file
1669 names. GNU Emacs automatically enters Texinfo mode when you visit a
1670 file with a @file{.texinfo}, @file{.texi} or @file{.txi}
1671 extension. Also, Emacs switches to Texinfo mode
1673 file that has @samp{-*-texinfo-*-} in its first line. If ever you are
1674 in another mode and wish to switch to Texinfo mode, type @code{M-x
1675 texinfo-mode}.@refill
1677 Like all other Emacs features, you can customize or enhance Texinfo
1678 mode as you wish. In particular, the keybindings are very easy to
1679 change. The keybindings described here are the default or standard
1682 @node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
1683 @comment node-name, next, previous, up
1684 @section Inserting Frequently Used Commands
1685 @cindex Inserting frequently used commands
1686 @cindex Frequently used commands, inserting
1687 @cindex Commands, inserting them
1689 Texinfo mode provides commands to insert various frequently used
1690 @@-commands into the buffer. You can use these commands to save
1693 The insert commands are invoked by typing @kbd{C-c} twice and then the
1694 first letter of the @@-command:@refill
1698 @itemx M-x texinfo-insert-@@code
1699 @findex texinfo-insert-@@code
1700 Insert @code{@@code@{@}} and put the
1701 cursor between the braces.@refill
1704 @itemx M-x texinfo-insert-@@dfn
1705 @findex texinfo-insert-@@dfn
1706 Insert @code{@@dfn@{@}} and put the
1707 cursor between the braces.@refill
1710 @itemx M-x texinfo-insert-@@end
1711 @findex texinfo-insert-@@end
1712 Insert @code{@@end} and attempt to insert the correct following word,
1713 such as @samp{example} or @samp{table}. (This command does not handle
1714 nested lists correctly, but inserts the word appropriate to the
1715 immediately preceding list.)@refill
1718 @itemx M-x texinfo-insert-@@item
1719 @findex texinfo-insert-@@item
1720 Insert @code{@@item} and put the
1721 cursor at the beginning of the next line.@refill
1724 @itemx M-x texinfo-insert-@@kbd
1725 @findex texinfo-insert-@@kbd
1726 Insert @code{@@kbd@{@}} and put the
1727 cursor between the braces.@refill
1730 @itemx M-x texinfo-insert-@@node
1731 @findex texinfo-insert-@@node
1732 Insert @code{@@node} and a comment line
1733 listing the sequence for the `Next',
1734 `Previous', and `Up' nodes.
1735 Leave point after the @code{@@node}.@refill
1738 @itemx M-x texinfo-insert-@@noindent
1739 @findex texinfo-insert-@@noindent
1740 Insert @code{@@noindent} and put the
1741 cursor at the beginning of the next line.@refill
1744 @itemx M-x texinfo-insert-@@samp
1745 @findex texinfo-insert-@@samp
1746 Insert @code{@@samp@{@}} and put the
1747 cursor between the braces.@refill
1750 @itemx M-x texinfo-insert-@@table
1751 @findex texinfo-insert-@@table
1752 Insert @code{@@table} followed by a @key{SPC}
1753 and leave the cursor after the @key{SPC}.@refill
1756 @itemx M-x texinfo-insert-@@var
1757 @findex texinfo-insert-@@var
1758 Insert @code{@@var@{@}} and put the
1759 cursor between the braces.@refill
1762 @itemx M-x texinfo-insert-@@example
1763 @findex texinfo-insert-@@example
1764 Insert @code{@@example} and put the
1765 cursor at the beginning of the next line.@refill
1767 @c M-@{ was the binding for texinfo-insert-braces;
1768 @c in Emacs 19, backward-paragraph will take this binding.
1770 @itemx M-x texinfo-insert-braces
1771 @findex texinfo-insert-braces
1772 Insert @code{@{@}} and put the cursor between the braces.@refill
1778 Move from between a pair of braces forward past the closing brace.
1779 Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
1780 is, however, more mnemonic; hence the two keybindings. (Also, you can
1781 move out from between braces by typing @kbd{C-f}.)@refill
1784 To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1785 @emph{existing} word, position the cursor in front of the word and type
1786 @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
1787 The value of the prefix argument tells Emacs how many words following
1788 point to include between braces---@samp{1} for one word, @samp{2} for
1789 two words, and so on. Use a negative argument to enclose the previous
1790 word or words. If you do not specify a prefix argument, Emacs inserts
1791 the @@-command string and positions the cursor between the braces. This
1792 feature works only for those @@-commands that operate on a word or words
1793 within one line, such as @code{@@kbd} and @code{@@var}.@refill
1795 This set of insert commands was created after analyzing the frequency
1796 with which different @@-commands are used in the @cite{GNU Emacs
1797 Manual} and the @cite{GDB Manual}. If you wish to add your own insert
1798 commands, you can bind a keyboard macro to a key, use abbreviations,
1799 or extend the code in @file{texinfo.el}.@refill
1801 @findex texinfo-start-menu-description
1802 @cindex Menu description, start
1803 @cindex Description for menu, start
1804 @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1805 command that works differently from the other insert commands. It
1806 inserts a node's section or chapter title in the space for the
1807 description in a menu entry line. (A menu entry has three parts, the
1808 entry name, the node name, and the description. Only the node name is
1809 required, but a description helps explain what the node is about.
1810 @xref{Menu Parts, , The Parts of a Menu}.)@refill
1812 To use @code{texinfo-start-menu-description}, position point in a menu
1813 entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
1814 the title that goes with the node name, and inserts the title as a
1815 description; it positions point at beginning of the inserted text so you
1816 can edit it. The function does not insert the title if the menu entry
1817 line already contains a description.@refill
1819 This command is only an aid to writing descriptions; it does not do the
1820 whole job. You must edit the inserted text since a title tends to use
1821 the same words as a node name but a useful description uses different
1824 @node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
1825 @comment node-name, next, previous, up
1826 @section Showing the Section Structure of a File
1827 @cindex Showing the section structure of a file
1828 @cindex Section structure of a file, showing it
1829 @cindex Structure of a file, showing it
1830 @cindex Outline of file structure, showing it
1831 @cindex Contents-like outline of file structure
1832 @cindex File section structure, showing it
1833 @cindex Texinfo file section structure, showing it
1835 You can show the section structure of a Texinfo file by using the
1836 @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
1837 shows the section structure of a Texinfo file by listing the lines
1838 that begin with the @@-commands for @code{@@chapter},
1839 @code{@@section}, and the like. It constructs what amounts
1840 to a table of contents. These lines are displayed in another buffer
1841 called the @samp{*Occur*} buffer. In that buffer, you can position
1842 the cursor over one of the lines and use the @kbd{C-c C-c} command
1843 (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1844 in the Texinfo file.@refill
1848 @itemx M-x texinfo-show-structure
1849 @findex texinfo-show-structure
1850 Show the @code{@@chapter}, @code{@@section}, and such lines of a
1851 Texinfo file.@refill
1854 @itemx M-x occur-mode-goto-occurrence
1855 @findex occur-mode-goto-occurrence
1856 Go to the line in the Texinfo file corresponding to the line under the
1857 cursor in the @file{*Occur*} buffer.@refill
1860 If you call @code{texinfo-show-structure} with a prefix argument by
1861 typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1862 @@-commands for @code{@@chapter}, @code{@@section}, and the like, but
1863 also the @code{@@node} lines. You can use @code{texinfo-show-structure}
1864 with a prefix argument to check whether the `Next', `Previous', and `Up'
1865 pointers of an @code{@@node} line are correct.
1867 Often, when you are working on a manual, you will be interested only
1868 in the structure of the current chapter. In this case, you can mark
1869 off the region of the buffer that you are interested in by using the
1870 @kbd{C-x n n} (@code{narrow-to-region}) command and
1871 @code{texinfo-show-structure} will work on only that region. To see
1872 the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
1873 (@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
1874 information about the narrowing commands.)@refill
1876 @vindex page-delimiter
1877 @cindex Page delimiter in Texinfo mode
1878 In addition to providing the @code{texinfo-show-structure} command,
1879 Texinfo mode sets the value of the page delimiter variable to match
1880 the chapter-level @@-commands. This enables you to use the @kbd{C-x
1881 ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
1882 commands to move forward and backward by chapter, and to use the
1883 @kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
1884 @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
1885 about the page commands.@refill
1887 @node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
1888 @comment node-name, next, previous, up
1889 @section Updating Nodes and Menus
1890 @cindex Updating nodes and menus
1891 @cindex Create nodes, menus automatically
1892 @cindex Insert nodes, menus automatically
1893 @cindex Automatically insert nodes, menus
1895 Texinfo mode provides commands for automatically creating or updating
1896 menus and node pointers. The commands are called ``update'' commands
1897 because their most frequent use is for updating a Texinfo file after
1898 you have worked on it; but you can use them to insert the `Next',
1899 `Previous', and `Up' pointers into an @code{@@node} line that has none and to
1900 create menus in a file that has none.@refill
1902 If you do not use the updating commands, you need to write menus and
1903 node pointers by hand, which is a tedious task.@refill
1906 * Updating Commands:: Five major updating commands.
1907 * Updating Requirements:: How to structure a Texinfo file for
1908 using the updating command.
1909 * Other Updating Commands:: How to indent descriptions, insert
1910 missing nodes lines, and update
1914 @node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
1916 @subheading The Updating Commands
1919 You can use the updating commands to:@refill
1923 insert or update the `Next', `Previous', and `Up' pointers of a
1927 insert or update the menu for a section, and@refill
1930 create a master menu for a Texinfo source file.@refill
1933 You can also use the commands to update all the nodes and menus in a
1934 region or in a whole Texinfo file.@refill
1936 The updating commands work only with conventional Texinfo files, which
1937 are structured hierarchically like books. In such files, a structuring
1938 command line must follow closely after each @code{@@node} line, except
1939 for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
1940 a line beginning with @code{@@chapter}, @code{@@section}, or other
1943 You can write the structuring command line on the line that follows
1944 immediately after an @code{@@node} line or else on the line that
1945 follows after a single @code{@@comment} line or a single
1946 @code{@@ifinfo} line. You cannot interpose more than one line between
1947 the @code{@@node} line and the structuring command line; and you may
1948 interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
1950 Commands which work on a whole buffer require that the `Top' node be
1951 followed by a node with an @code{@@chapter} or equivalent-level command.
1952 The menu updating commands will not create a main or master menu for a
1953 Texinfo file that has only @code{@@chapter}-level nodes! The menu
1954 updating commands only create menus @emph{within} nodes for lower level
1955 nodes. To create a menu of chapters, you must provide a `Top'
1958 The menu updating commands remove menu entries that refer to other Info
1959 files since they do not refer to nodes within the current buffer. This
1960 is a deficiency. Rather than use menu entries, you can use cross
1961 references to refer to other Info files. None of the updating commands
1962 affect cross references.@refill
1964 Texinfo mode has five updating commands that are used most often: two
1965 are for updating the node pointers or menu of a single node (or a
1966 region); two are for updating every node pointer and menu in a file;
1967 and one, the @code{texinfo-master-menu} command, is for creating a
1968 master menu for a complete file, and optionally, for updating every
1969 node and menu in the whole Texinfo file.@refill
1971 The @code{texinfo-master-menu} command is the primary command:@refill
1975 @itemx M-x texinfo-master-menu
1976 @findex texinfo-master-menu
1977 Create or update a master menu that includes all the other menus
1978 (incorporating the descriptions from pre-existing menus, if
1981 With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
1982 update all the nodes and all the regular menus in the buffer before
1983 constructing the master menu. (@xref{The Top Node, , The Top Node and
1984 Master Menu}, for more about a master menu.)@refill
1986 For @code{texinfo-master-menu} to work, the Texinfo file must have a
1987 `Top' node and at least one subsequent node.@refill
1989 After extensively editing a Texinfo file, you can type the following:
1992 C-u M-x texinfo-master-menu
1998 This updates all the nodes and menus completely and all at once.@refill
2001 The other major updating commands do smaller jobs and are designed for
2002 the person who updates nodes and menus as he or she writes a Texinfo
2006 The commands are:@refill
2010 @itemx M-x texinfo-update-node
2011 @findex texinfo-update-node
2012 Insert the `Next', `Previous', and `Up' pointers for the node that point is
2013 within (i.e., for the @code{@@node} line preceding point). If the
2014 @code{@@node} line has pre-existing `Next', `Previous', or `Up'
2015 pointers in it, the old pointers are removed and new ones inserted.
2016 With an argument (prefix argument, @kbd{C-u}, if interactive), this command
2017 updates all @code{@@node} lines in the region (which is the text
2018 between point and mark).@refill
2021 @itemx M-x texinfo-make-menu
2022 @findex texinfo-make-menu
2023 Create or update the menu in the node that point is within.
2024 With an argument (@kbd{C-u} as prefix argument, if
2025 interactive), the command makes or updates menus for the
2026 nodes which are either within or a part of the
2029 Whenever @code{texinfo-make-menu} updates an existing menu, the
2030 descriptions from that menu are incorporated into the new menu. This
2031 is done by copying descriptions from the existing menu to the entries
2032 in the new menu that have the same node names. If the node names are
2033 different, the descriptions are not copied to the new menu.@refill
2036 @itemx M-x texinfo-every-node-update
2037 @findex texinfo-every-node-update
2038 Insert or update the `Next', `Previous', and `Up' pointers for every
2039 node in the buffer.@refill
2042 @itemx M-x texinfo-all-menus-update
2043 @findex texinfo-all-menus-update
2044 Create or update all the menus in the buffer. With an argument
2045 (@kbd{C-u} as prefix argument, if interactive), first insert
2046 or update all the node
2047 pointers before working on the menus.@refill
2049 If a master menu exists, the @code{texinfo-all-menus-update} command
2050 updates it; but the command does not create a new master menu if none
2051 already exists. (Use the @code{texinfo-master-menu} command for
2054 When working on a document that does not merit a master menu, you can
2060 C-u M-x texinfo-all-menus-update
2064 This updates all the nodes and menus.@refill
2067 The @code{texinfo-column-for-description} variable specifies the
2068 column to which menu descriptions are indented. By default, the value
2069 is 32 although it is often useful to reduce it to as low as 24. You
2070 can set the variable with the @kbd{M-x edit-options} command
2071 (@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
2072 Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
2073 , Examining and Setting Variables, emacs, The GNU Emacs
2076 Also, the @code{texinfo-indent-menu-description} command may be used to
2077 indent existing menu descriptions to a specified column. Finally, if
2078 you wish, you can use the @code{texinfo-insert-node-lines} command to
2079 insert missing @code{@@node} lines into a file. (@xref{Other Updating
2080 Commands}, for more information.)@refill
2082 @node Updating Requirements, Other Updating Commands, Updating Commands, Updating Nodes and Menus
2083 @comment node-name, next, previous, up
2084 @subsection Updating Requirements
2085 @cindex Updating requirements
2086 @cindex Requirements for updating commands
2088 To use the updating commands, you must organize the Texinfo file
2089 hierarchically with chapters, sections, subsections, and the like.
2090 When you construct the hierarchy of the manual, do not `jump down'
2091 more than one level at a time: you can follow the `Top' node with a
2092 chapter, but not with a section; you can follow a chapter with a
2093 section, but not with a subsection. However, you may `jump up' any
2094 number of levels at one time---for example, from a subsection to a
2097 Each @code{@@node} line, with the exception of the line for the `Top'
2098 node, must be followed by a line with a structuring command such as
2099 @code{@@chapter}, @code{@@section}, or
2100 @code{@@unnumberedsubsec}.@refill
2102 Each @code{@@node} line/structuring-command line combination
2103 must look either like this:@refill
2107 @@node Comments, Minimum, Conventions, Overview
2108 @@comment node-name, next, previous, up
2113 or like this (without the @code{@@comment} line):
2117 @@node Comments, Minimum, Conventions, Overview
2123 In this example, `Comments' is the name of both the node and the
2124 section. The next node is called `Minimum' and the previous node is
2125 called `Conventions'. The `Comments' section is within the `Overview'
2126 node, which is specified by the `Up' pointer. (Instead of an
2127 @code{@@comment} line, you may also write an @code{@@ifinfo} line.)@refill
2129 If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2130 and be the first node in the file.@refill
2132 The menu updating commands create a menu of sections within a chapter,
2133 a menu of subsections within a section, and so on. This means that
2134 you must have a `Top' node if you want a menu of chapters.@refill
2136 Incidentally, the @code{makeinfo} command will create an Info file for a
2137 hierarchically organized Texinfo file that lacks `Next', `Previous' and
2138 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
2139 formatted with @code{makeinfo}, you have no need for the update node
2140 commands. (@xref{Creating an Info File}, for more information about
2141 @code{makeinfo}.) However, both @code{makeinfo} and the
2142 @code{texinfo-format-@dots{}} commands require that you insert menus in
2145 @node Other Updating Commands, , Updating Requirements, Updating Nodes and Menus
2146 @comment node-name, next, previous, up
2147 @subsection Other Updating Commands
2149 In addition to the five major updating commands, Texinfo mode
2150 possesses several less frequently used updating commands:@refill
2153 @item M-x texinfo-insert-node-lines
2154 @findex texinfo-insert-node-lines
2155 Insert @code{@@node} lines before the @code{@@chapter},
2156 @code{@@section}, and other sectioning commands wherever they are
2157 missing throughout a region in a Texinfo file.@refill
2159 With an argument (@kbd{C-u} as prefix argument, if interactive), the
2160 @code{texinfo-insert-node-lines} command not only inserts
2161 @code{@@node} lines but also inserts the chapter or section titles as
2162 the names of the corresponding nodes. In addition, it inserts the
2163 titles as node names in pre-existing @code{@@node} lines that lack
2164 names. Since node names should be more concise than section or
2165 chapter titles, you must manually edit node names so inserted.@refill
2167 For example, the following marks a whole buffer as a region and inserts
2168 @code{@@node} lines and titles throughout:@refill
2171 C-x h C-u M-x texinfo-insert-node-lines
2174 This command inserts titles as node names in @code{@@node} lines; the
2175 @code{texinfo-start-menu-description} command (@pxref{Inserting,
2176 Inserting Frequently Used Commands}) inserts titles as descriptions in
2177 menu entries, a different action. However, in both cases, you need to
2178 edit the inserted text.
2180 @item M-x texinfo-multiple-files-update
2181 @findex texinfo-multiple-files-update @r{(in brief)}
2182 Update nodes and menus in a document built from several separate files.
2183 With @kbd{C-u} as a prefix argument, create and insert a master menu in
2184 the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
2185 update all the menus and all the `Next', `Previous', and `Up' pointers
2186 of all the included files before creating and inserting a master menu in
2187 the outer file. The @code{texinfo-multiple-files-update} command is
2188 described in the appendix on @code{@@include} files.
2190 @xref{texinfo-multiple-files-update}.@refill
2193 @xref{texinfo-multiple-files-update, ,
2194 @code{texinfo-multiple-files-update}}.@refill
2197 @item M-x texinfo-indent-menu-description
2198 @findex texinfo-indent-menu-description
2199 Indent every description in the menu following point to the specified
2200 column. You can use this command to give yourself more space for
2201 descriptions. With an argument (@kbd{C-u} as prefix argument, if
2202 interactive), the @code{texinfo-indent-menu-description} command indents
2203 every description in every menu in the region. However, this command
2204 does not indent the second and subsequent lines of a multi-line
2207 @item M-x texinfo-sequential-node-update
2208 @findex texinfo-sequential-node-update
2209 Insert the names of the nodes immediately following and preceding the
2210 current node as the `Next' or `Previous' pointers regardless of those
2211 nodes' hierarchical level. This means that the `Next' node of a
2212 subsection may well be the next chapter. Sequentially ordered nodes are
2213 useful for novels and other documents that you read through
2214 sequentially. (However, in Info, the @kbd{g *} command lets
2215 you look through the file sequentially, so sequentially ordered nodes
2216 are not strictly necessary.) With an argument (prefix argument, if
2217 interactive), the @code{texinfo-sequential-node-update} command
2218 sequentially updates all the nodes in the region.@refill
2221 @node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
2222 @comment node-name, next, previous, up
2223 @section Formatting for Info
2224 @cindex Formatting for Info
2225 @cindex Running an Info formatter
2226 @cindex Info formatting
2228 Texinfo mode provides several commands for formatting part or all of a
2229 Texinfo file for Info. Often, when you are writing a document, you
2230 want to format only part of a file---that is, a region.@refill
2232 You can use either the @code{texinfo-format-region} or the
2233 @code{makeinfo-region} command to format a region:@refill
2236 @findex texinfo-format-region
2238 @itemx M-x texinfo-format-region
2240 @itemx M-x makeinfo-region
2241 Format the current region for Info.@refill
2244 You can use either the @code{texinfo-format-buffer} or the
2245 @code{makeinfo-buffer} command to format a whole buffer:@refill
2248 @findex texinfo-format-buffer
2250 @itemx M-x texinfo-format-buffer
2252 @itemx M-x makeinfo-buffer
2253 Format the current buffer for Info.@refill
2257 For example, after writing a Texinfo file, you can type the following:
2262 C-u M-x texinfo-master-menu
2266 This updates all the nodes and menus. Then type the following to create
2275 For @TeX{} or the Info formatting commands to work, the file @emph{must}
2276 include a line that has @code{@@setfilename} in its header.@refill
2278 @xref{Creating an Info File}, for details about Info formatting.@refill
2280 @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2281 @comment node-name, next, previous, up
2282 @section Formatting and Printing
2283 @cindex Formatting for printing
2284 @cindex Printing a region or buffer
2285 @cindex Region formatting and printing
2286 @cindex Buffer formatting and printing
2287 @cindex Part of file formatting and printing
2289 Typesetting and printing a Texinfo file is a multi-step process in which
2290 you first create a file for printing (called a DVI file), and then
2291 print the file. Optionally, you may also create indices. To do this,
2292 you must run the @code{texindex} command after first running the
2293 @code{tex} typesetting command; and then you must run the @code{tex}
2294 command again. Or else run the @code{texi2dvi} command which
2295 automatically creates indices as needed (@pxref{Format with texi2dvi}).
2297 Often, when you are writing a document, you want to typeset and print
2298 only part of a file to see what it will look like. You can use the
2299 @code{texinfo-tex-region} and related commands for this purpose. Use
2300 the @code{texinfo-tex-buffer} command to format all of a
2305 @itemx M-x texinfo-tex-buffer
2306 @findex texinfo-tex-buffer
2307 Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
2308 buffer, this command automatically creates or updates indices as
2312 @itemx M-x texinfo-tex-region
2313 @findex texinfo-tex-region
2314 Run @TeX{} on the region.@refill
2317 @itemx M-x texinfo-texindex
2318 Run @code{texindex} to sort the indices of a Texinfo file formatted with
2319 @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
2320 not run @code{texindex} automatically; it only runs the @code{tex}
2321 typesetting command. You must run the @code{texinfo-tex-region} command
2322 a second time after sorting the raw index files with the @code{texindex}
2323 command. (Usually, you do not format an index when you format a region,
2324 only when you format a buffer. Now that the @code{texi2dvi} command
2325 exists, there is little or no need for this command.)@refill
2328 @itemx M-x texinfo-tex-print
2329 @findex texinfo-tex-print
2330 Print the file (or the part of the file) previously formatted with
2331 @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2334 For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2335 file @emph{must} start with a @samp{\input texinfo} line and must
2336 include an @code{@@settitle} line. The file must end with @code{@@bye}
2337 on a line by itself. (When you use @code{texinfo-tex-region}, you must
2338 surround the @code{@@settitle} line with start-of-header and
2339 end-of-header lines.)@refill
2341 @xref{Hardcopy}, for a description of the other @TeX{} related
2342 commands, such as @code{tex-show-print-queue}.@refill
2344 @node Texinfo Mode Summary, , Printing, Texinfo Mode
2345 @comment node-name, next, previous, up
2346 @section Texinfo Mode Summary
2348 In Texinfo mode, each set of commands has default keybindings that
2349 begin with the same keys. All the commands that are custom-created
2350 for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
2353 @subheading Insert Commands
2355 The insert commands are invoked by typing @kbd{C-c} twice and then the
2356 first letter of the @@-command to be inserted. (It might make more
2357 sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2358 @kbd{C-c C-c} is quick to type.)@refill
2361 C-c C-c c @r{Insert} @samp{@@code}.
2362 C-c C-c d @r{Insert} @samp{@@dfn}.
2363 C-c C-c e @r{Insert} @samp{@@end}.
2364 C-c C-c i @r{Insert} @samp{@@item}.
2365 C-c C-c n @r{Insert} @samp{@@node}.
2366 C-c C-c s @r{Insert} @samp{@@samp}.
2367 C-c C-c v @r{Insert} @samp{@@var}.
2368 C-c C-c @{ @r{Insert braces.}
2370 C-c C-c @} @r{Move out of enclosing braces.}
2373 C-c C-c C-d @r{Insert a node's section title}
2374 @r{in the space for the description}
2375 @r{in a menu entry line.}
2379 @subheading Show Structure
2381 The @code{texinfo-show-structure} command is often used within a
2382 narrowed region.@refill
2385 C-c C-s @r{List all the headings.}
2388 @subheading The Master Update Command
2390 The @code{texinfo-master-menu} command creates a master menu; and can
2391 be used to update every node and menu in a file as well.@refill
2393 @c Probably should use @tables in this section.
2397 M-x texinfo-master-menu
2398 @r{Create or update a master menu.}
2402 C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
2403 @r{create or update all nodes and regular}
2404 @r{menus, and then create a master menu.}
2408 @subheading Update Pointers
2410 The update pointer commands are invoked by typing @kbd{C-c C-u} and
2411 then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2412 @code{texinfo-every-node-update}.@refill
2415 C-c C-u C-n @r{Update a node.}
2416 C-c C-u C-e @r{Update every node in the buffer.}
2419 @subheading Update Menus
2421 Invoke the update menu commands by typing @kbd{C-c C-u}
2422 and then either @kbd{C-m} for @code{texinfo-make-menu} or
2423 @kbd{C-a} for @code{texinfo-all-menus-update}. To update
2424 both nodes and menus at the same time, precede @kbd{C-c C-u
2425 C-a} with @kbd{C-u}.@refill
2428 C-c C-u C-m @r{Make or update a menu.}
2431 C-c C-u C-a @r{Make or update all}
2432 @r{menus in a buffer.}
2436 C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2437 @r{first create or update all nodes and}
2438 @r{then create or update all menus.}
2442 @subheading Format for Info
2444 The Info formatting commands that are written in Emacs Lisp are
2445 invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2446 or @kbd{C-b} for the whole buffer.@refill
2448 The Info formatting commands that are written in C and based on the
2449 @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2450 either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2454 Use the @code{texinfo-format@dots{}} commands:
2458 C-c C-e C-r @r{Format the region.}
2459 C-c C-e C-b @r{Format the buffer.}
2465 Use @code{makeinfo}:
2468 C-c C-m C-r @r{Format the region.}
2469 C-c C-m C-b @r{Format the buffer.}
2470 C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
2471 C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
2474 @subheading Typeset and Print
2476 The @TeX{} typesetting and printing commands are invoked by typing
2477 @kbd{C-c C-t} and then another control command: @kbd{C-r} for
2478 @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2482 C-c C-t C-r @r{Run @TeX{} on the region.}
2483 C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
2484 C-c C-t C-i @r{Run} @code{texindex}.
2485 C-c C-t C-p @r{Print the DVI file.}
2486 C-c C-t C-q @r{Show the print queue.}
2487 C-c C-t C-d @r{Delete a job from the print queue.}
2488 C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
2489 C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
2490 C-c C-t C-l @r{Recenter the output buffer.}
2493 @subheading Other Updating Commands
2495 The remaining updating commands do not have standard keybindings because
2496 they are rarely used.
2500 M-x texinfo-insert-node-lines
2501 @r{Insert missing @code{@@node} lines in region.}
2502 @r{With @kbd{C-u} as a prefix argument,}
2503 @r{use section titles as node names.}
2507 M-x texinfo-multiple-files-update
2508 @r{Update a multi-file document.}
2509 @r{With @kbd{C-u 2} as a prefix argument,}
2510 @r{create or update all nodes and menus}
2511 @r{in all included files first.}
2515 M-x texinfo-indent-menu-description
2516 @r{Indent descriptions.}
2520 M-x texinfo-sequential-node-update
2521 @r{Insert node pointers in strict sequence.}
2525 @node Beginning a File, Ending a File, Texinfo Mode, Top
2526 @comment node-name, next, previous, up
2527 @chapter Beginning a Texinfo File
2528 @cindex Beginning a Texinfo file
2529 @cindex Texinfo file beginning
2530 @cindex File beginning
2532 Certain pieces of information must be provided at the beginning of a
2533 Texinfo file, such as the name of the file and the title of the
2537 * Four Parts:: Four parts begin a Texinfo file.
2538 * Sample Beginning:: Here is a sample beginning for a Texinfo file.
2539 * Header:: The very beginning of a Texinfo file.
2540 * Info Summary and Permissions:: Summary and copying permissions for Info.
2541 * Titlepage & Copyright Page:: Creating the title and copyright pages.
2542 * The Top Node:: Creating the `Top' node and master menu.
2543 * Software Copying Permissions:: Ensure that you and others continue to
2544 have the right to use and share software.
2547 @node Four Parts, Sample Beginning, Beginning a File, Beginning a File
2549 @heading Four Parts Begin a File
2552 Generally, the beginning of a Texinfo file has four parts:@refill
2556 The header, delimited by special comment lines, that includes the
2557 commands for naming the Texinfo file and telling @TeX{} what
2558 definitions file to use when processing the Texinfo file.@refill
2561 A short statement of what the file is about, with a copyright notice
2562 and copying permissions. This is enclosed in @code{@@ifinfo} and
2563 @code{@@end ifinfo} commands so that the formatters place it only
2564 in the Info file.@refill
2567 A title page and copyright page, with a copyright notice and copying
2568 permissions. This is enclosed between @code{@@titlepage} and
2569 @code{@@end titlepage} commands. The title and copyright page appear
2570 only in the printed @w{manual}.@refill
2573 The `Top' node that contains a menu for the whole Info file. The
2574 contents of this node appear only in the Info file.@refill
2577 Also, optionally, you may include the copying conditions for a program
2578 and a warranty disclaimer. The copying section will be followed by an
2579 introduction or else by the first chapter of the manual.@refill
2581 Since the copyright notice and copying permissions for the Texinfo
2582 document (in contrast to the copying permissions for a program) are in
2583 parts that appear only in the Info file or only in the printed manual,
2584 this information must be given twice.@refill
2586 @node Sample Beginning, Header, Four Parts, Beginning a File
2587 @comment node-name, next, previous, up
2588 @section Sample Texinfo File Beginning
2590 The following sample shows what is needed.@refill
2593 \input texinfo @@c -*-texinfo-*-
2594 @@c %**start of header
2595 @@setfilename @var{name-of-info-file}
2596 @@settitle @var{name-of-manual}
2597 @@setchapternewpage odd
2598 @@c %**end of header
2601 This file documents @dots{}
2603 Copyright @var{year} @var{copyright-owner}
2606 Permission is granted to @dots{}
2611 @@c This title page illustrates only one of the
2612 @@c two methods of forming a title page.
2617 @@title @var{name-of-manual-when-printed}
2618 @@subtitle @var{subtitle-if-any}
2619 @@subtitle @var{second-subtitle}
2620 @@author @var{author}
2624 @@c The following two commands
2625 @@c start the copyright page.
2627 @@vskip 0pt plus 1filll
2628 Copyright @@copyright@{@} @var{year} @var{copyright-owner}
2631 Published by @dots{}
2633 Permission is granted to @dots{}
2636 @@node Top, Overview, , (dir)
2639 This document describes @dots{}
2641 This document applies to version @dots{}
2642 of the program named @dots{}
2647 * Copying:: Your rights and freedoms.
2648 * First Chapter:: Getting started @dots{}
2649 * Second Chapter:: @dots{}
2656 @@node First Chapter, Second Chapter, top, top
2657 @@comment node-name, next, previous, up
2658 @@chapter First Chapter
2659 @@cindex Index entry for First Chapter
2663 @node Header, Info Summary and Permissions, Sample Beginning, Beginning a File
2664 @comment node-name, next, previous, up
2665 @section The Texinfo File Header
2666 @cindex Header for Texinfo files
2667 @cindex Texinfo file header
2669 Texinfo files start with at least three lines that provide Info and
2670 @TeX{} with necessary information. These are the @code{\input
2671 texinfo} line, the @code{@@settitle} line, and the
2672 @code{@@setfilename} line. If you want to run @TeX{} on just a part
2673 of the Texinfo File, you must write the @code{@@settitle}
2674 and @code{@@setfilename} lines between start-of-header and end-of-header
2677 Thus, the beginning of a Texinfo file looks like this:
2681 \input texinfo @@c -*-texinfo-*-
2682 @@setfilename sample.info
2683 @@settitle Sample Document
2692 \input texinfo @@c -*-texinfo-*-
2693 @@c %**start of header
2694 @@setfilename sample.info
2695 @@settitle Sample Document
2696 @@c %**end of header
2701 * First Line:: The first line of a Texinfo file.
2702 * Start of Header:: Formatting a region requires this.
2703 * setfilename:: Tell Info the name of the Info file.
2704 * settitle:: Create a title for the printed work.
2705 * setchapternewpage:: Start chapters on right-hand pages.
2706 * paragraphindent:: Specify paragraph indentation.
2707 * exampleindent:: Specify environment indentation.
2708 * End of Header:: Formatting a region requires this.
2713 @subsection The First Line of a Texinfo File
2714 @cindex First line of a Texinfo file
2715 @cindex Beginning line of a Texinfo file
2716 @cindex Header of a Texinfo file
2718 Every Texinfo file that is to be the top-level input to @TeX{} must begin
2719 with a line that looks like this:@refill
2722 \input texinfo @@c -*-texinfo-*-
2726 This line serves two functions:
2730 When the file is processed by @TeX{}, the @samp{\input texinfo} command
2731 tells @TeX{} to load the macros needed for processing a Texinfo file.
2732 These are in a file called @file{texinfo.tex}, which is usually located
2733 in the @file{/usr/lib/tex/macros} directory. @TeX{} uses the backslash,
2734 @samp{\}, to mark the beginning of a command, just as Texinfo uses
2735 @samp{@@}. The @file{texinfo.tex} file causes the switch from @samp{\}
2736 to @samp{@@}; before the switch occurs, @TeX{} requires @samp{\}, which
2737 is why it appears at the beginning of the file.@refill
2740 When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2741 specification tells Emacs to use Texinfo mode.@refill
2744 @node Start of Header, setfilename, First Line, Header
2745 @comment node-name, next, previous, up
2746 @subsection Start of Header
2747 @cindex Start of header line
2749 Write a start-of-header line on the second line of a Texinfo file.
2750 Follow the start-of-header line with @code{@@setfilename} and
2751 @code{@@settitle} lines and, optionally, with other command lines, such
2752 as @code{@@smallbook} or @code{@@footnotestyle}; and then by an
2753 end-of-header line (@pxref{End of Header}).@refill
2755 With these lines, you can format part of a Texinfo file for Info or
2756 typeset part for printing.@refill
2758 A start-of-header line looks like this:@refill
2761 @@c %**start of header
2764 The odd string of characters, @samp{%**}, is to ensure that no other
2765 comment is accidentally taken for a start-of-header line.@refill
2768 @subsection @code{@@setfilename}
2769 @cindex Info file requires @code{@@setfilename}
2772 In order to serve as the primary input file for either @code{makeinfo}
2773 or @TeX{}, a Texinfo file must contain a line that looks like this:
2776 @@setfilename @var{info-file-name}
2779 Write the @code{@@setfilename} command at the beginning of a line and
2780 follow it on the same line by the Info file name. Do not write anything
2781 else on the line; anything on the line after the command is considered
2782 part of the file name, including what would otherwise be a
2785 The @code{@@setfilename} line specifies the name of the output file to
2786 be generated. This name should be different from the name of the
2787 Texinfo file. There are two conventions for choosing the name: you can
2788 either remove the extension (such as @samp{.texi}) from the input file
2789 name, or replace it with the @samp{.info} extension. When producing
2790 HTML output, @code{makeinfo} will replace any extension with
2791 @samp{html}, or add @samp{.html} if the given name has no extension.
2793 Some operating systems cannot handle long file names. You can run into
2794 a problem even when the file name you specify is itself short enough.
2795 This occurs because the Info formatters split a long Info file into
2796 short indirect subfiles, and name them by appending @samp{-1},
2797 @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2798 file name. (@xref{Tag and Split Files, , Tag Files and Split Files}.)
2799 The subfile name @file{texinfo.info-10}, for example, is too long for
2800 some systems; so the Info file name for this document is @file{texinfo}
2801 rather than @file{texinfo.info}. When @code{makeinfo} is running on
2802 operating systems such as MS-DOS which impose grave limits on file
2803 names, it will sometimes remove some characters from the original file
2804 name to leave enough space for the subfile suffix, thus producing files
2805 named @file{texin-10}, @file{gcc.i12}, etc.
2807 @cindex Ignored before @code{@@setfilename}
2808 @cindex @samp{\input} source line ignored
2809 The Info formatting commands ignore everything written before the
2810 @code{@@setfilename} line, which is why the very first line of
2811 the file (the @code{\input} line) does not show up in the output.
2814 The @code{@@setfilename} line produces no output when you typeset a
2815 manual with @TeX{}, but it is nevertheless essential: it opens the
2816 index, cross-reference, and other auxiliary files used by Texinfo, and
2817 also reads @file{texinfo.cnf} if that file is present on your system
2818 (@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2821 @node settitle, setchapternewpage, setfilename, Header
2822 @comment node-name, next, previous, up
2823 @subsection @code{@@settitle}
2826 In order to be made into a printed manual, a Texinfo file must contain
2827 a line that looks like this:@refill
2830 @@settitle @var{title}
2833 Write the @code{@@settitle} command at the beginning of a line and
2834 follow it on the same line by the title. This tells @TeX{} the title
2835 to use in a header or footer. Do not write anything else on the line;
2836 anything on the line after the command is considered part of the
2837 title, including a comment.@refill
2839 Conventionally, when @TeX{} formats a Texinfo file for double-sided
2840 output, the title is printed in the left-hand (even-numbered) page
2841 headings and the current chapter title is printed in the right-hand
2842 (odd-numbered) page headings. (@TeX{} learns the title of each chapter
2843 from each @code{@@chapter} command.) Page footers are not
2846 Even if you are printing in a single-sided style, @TeX{} looks for an
2847 @code{@@settitle} command line, in case you include the manual title
2848 in the heading. @refill
2850 The @code{@@settitle} command should precede everything that generates
2851 actual output in @TeX{}.@refill
2853 Although the title in the @code{@@settitle} command is usually the
2854 same as the title on the title page, it does not affect the title as
2855 it appears on the title page. Thus, the two do not need not match
2856 exactly; and the title in the @code{@@settitle} command can be a
2857 shortened or expanded version of the title as it appears on the title
2858 page. (@xref{titlepage, , @code{@@titlepage}}.)@refill
2860 @TeX{} prints page headings only for that text that comes after the
2861 @code{@@end titlepage} command in the Texinfo file, or that comes
2862 after an @code{@@headings} command that turns on headings.
2863 (@xref{headings on off, , The @code{@@headings} Command}, for more
2864 information.)@refill
2866 You may, if you wish, create your own, customized headings and
2867 footings. @xref{Headings, , Page Headings}, for a detailed discussion
2868 of this process.@refill
2871 @node setchapternewpage
2872 @subsection @code{@@setchapternewpage}
2873 @cindex Starting chapters
2874 @cindex Pages, starting odd
2875 @findex setchapternewpage
2877 In an officially bound book, text is usually printed on both sides of
2878 the paper, chapters start on right-hand pages, and right-hand pages have
2879 odd numbers. But in short reports, text often is printed only on one
2880 side of the paper. Also in short reports, chapters sometimes do not
2881 start on new pages, but are printed on the same page as the end of the
2882 preceding chapter, after a small amount of vertical whitespace.@refill
2884 You can use the @code{@@setchapternewpage} command with various
2885 arguments to specify how @TeX{} should start chapters and whether it
2886 should format headers for printing on one or both sides of the paper
2887 (single-sided or double-sided printing).@refill
2889 Write the @code{@@setchapternewpage} command at the beginning of a
2890 line followed by its argument.@refill
2892 For example, you would write the following to cause each chapter to
2893 start on a fresh odd-numbered page:@refill
2896 @@setchapternewpage odd
2899 You can specify one of three alternatives with the
2900 @code{@@setchapternewpage} command:@refill
2904 @item @code{@@setchapternewpage off}
2905 Cause @TeX{} to typeset a new chapter on the same page as the last
2906 chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
2907 format page headers for single-sided printing. (You can override the
2908 headers format with the @code{@@headings double} command; see
2909 @ref{headings on off, , The @code{@@headings} Command}.)@refill
2911 @item @code{@@setchapternewpage on}
2912 Cause @TeX{} to start new chapters on new pages and to format page
2913 headers for single-sided printing. This is the form most often
2914 used for short reports or personal printing.
2916 This alternative is the default.@refill
2918 @item @code{@@setchapternewpage odd}
2919 Cause @TeX{} to start new chapters on new, odd-numbered pages
2920 (right-handed pages) and to typeset for double-sided printing. This is
2921 the form most often used for books and manuals.@refill
2924 Texinfo does not have an @code{@@setchapternewpage even} command.@refill
2926 You can countermand or modify the effect on headers of an
2927 @code{@@setchapternewpage} command with an @code{@@headings} command.
2928 @xref{headings on off, , The @code{@@headings} Command}.@refill
2930 At the beginning of a manual or book, pages are not numbered---for
2931 example, the title and copyright pages of a book are not numbered.
2932 By convention, table of contents pages are numbered with roman
2933 numerals and not in sequence with the rest of the document.@refill
2935 Since an Info file does not have pages, the @code{@@setchapternewpage}
2936 command has no effect on it.@refill
2938 We recommend not including any @code{@@setchapternewpage} command in
2939 your manual sources at all, since the desired output is not intrinsic to
2940 the document. Instead, if you don't want the default option (no blank
2941 pages, same headers on all pages) use the @option{--texinfo} option to
2942 @command{texi2dvi} to specify the output you want.
2946 @node paragraphindent
2947 @subsection Paragraph Indenting
2948 @cindex Indenting paragraphs
2949 @cindex Paragraph indentation
2950 @findex paragraphindent
2952 The Texinfo processors may insert whitespace at the beginning of the
2953 first line of each paragraph, thereby indenting that paragraph. You can
2954 use the @code{@@paragraphindent} command to specify this indentation.
2955 Write an @code{@@paragraphindent} command at the beginning of a line
2956 followed by either @samp{asis} or a number:
2959 @@paragraphindent @var{indent}
2962 The indentation is according to the value of @var{indent}:
2966 Do not change the existing indentation (not implemented in @TeX{}).
2969 Omit all indentation.
2972 Indent by @var{n} space characters in Info output, by @var{n} ems in
2977 The default value of @var{indent} is @samp{asis}.
2978 @code{@@paragraphindent} is ignored for HTML output.
2980 Write the @code{@@paragraphindent} command before or shortly after the
2981 end-of-header line at the beginning of a Texinfo file. (If you write
2982 the command between the start-of-header and end-of-header lines, the
2983 region formatting commands indent paragraphs as specified.)
2985 A peculiarity of the @code{texinfo-format-buffer} and
2986 @code{texinfo-format-region} commands is that they do not indent (nor
2987 fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
2988 @xref{Refilling Paragraphs}, for further information.
2992 @subsection @code{@@exampleindent}: Environment Indenting
2993 @cindex Indenting environments
2994 @cindex Environment indentation
2995 @cindex Example indentation
2996 @findex exampleindent
2998 The Texinfo processors indent each line of @code{@@example} and similar
2999 environments. You can use the @code{@@exampleindent} command to specify
3000 this indentation. Write an @code{@@exampleindent} command at the
3001 beginning of a line followed by either @samp{asis} or a number:
3004 @@exampleindent @var{indent}
3007 The indentation is according to the value of @var{indent}:
3011 Do not change the existing indentation (not implemented in @TeX{}).
3014 Omit all indentation.
3017 Indent environments by @var{n} space characters in Info output, by
3018 @var{n} ems in @TeX{}.
3022 The default value of @var{indent} is 5. @code{@@exampleindent} is
3023 ignored for HTML output.
3025 Write the @code{@@exampleindent} command before or shortly after the
3026 end-of-header line at the beginning of a Texinfo file. (If you write
3027 the command between the start-of-header and end-of-header lines, the
3028 region formatting commands indent examples as specified.)
3032 @subsection End of Header
3033 @cindex End of header line
3035 Follow the header lines with an @w{end-of-header} line.
3036 An end-of-header line looks like this:@refill
3039 @@c %**end of header
3042 If you include the @code{@@setchapternewpage} command between the
3043 start-of-header and end-of-header lines, @TeX{} will typeset a region as
3044 that command specifies. Similarly, if you include an @code{@@smallbook}
3045 command between the start-of-header and end-of-header lines, @TeX{} will
3046 typeset a region in the ``small'' book format.@refill
3049 The reason for the odd string of characters (@samp{%**}) is so that the
3050 @code{texinfo-tex-region} command does not accidentally find
3051 something that it should not when it is looking for the header.@refill
3053 The start-of-header line and the end-of-header line are Texinfo mode
3054 variables that you can change.@refill
3058 @xref{Start of Header}.
3062 @node Info Summary and Permissions
3063 @section Summary and Copying Permissions for Info
3065 The title page and the copyright page appear only in the printed copy of
3066 the manual; therefore, the same information must be inserted in a
3067 section that appears only in the Info file. This section usually
3068 contains a brief description of the contents of the Info file, a
3069 copyright notice, and copying permissions.@refill
3071 The copyright notice should read:@refill
3074 Copyright @var{year} @var{copyright-owner}
3078 and be put on a line by itself.@refill
3080 Standard text for the copyright permissions is contained in an appendix
3081 to this manual; see @ref{ifinfo Permissions, , @samp{ifinfo} Copying
3082 Permissions}, for the complete text.@refill
3084 The permissions text appears in an Info file @emph{before} the first
3085 node. This mean that a reader does @emph{not} see this text when
3086 reading the file using Info, except when using the advanced Info command
3090 @node Titlepage & Copyright Page
3091 @section The Title and Copyright Pages
3093 A manual's name and author are usually printed on a title page.
3094 Sometimes copyright information is printed on the title page as well;
3095 more often, copyright information is printed on the back of the title
3098 The title and copyright pages appear in the printed manual, but not in the
3099 Info file. Because of this, it is possible to use several slightly
3100 obscure @TeX{} typesetting commands that cannot be used in an Info file.
3101 In addition, this part of the beginning of a Texinfo file contains the text
3102 of the copying permissions that will appear in the printed manual.@refill
3104 @cindex Titlepage, for plain text
3105 You may wish to include titlepage-like information for plain text
3106 output. Simply place any such leading material between @code{@@ifinfo}
3107 and @code{@@end ifinfo}; @command{makeinfo} includes this in its plain
3108 text output. It will not show up in the Info readers.
3110 @xref{Titlepage Permissions, , Titlepage Copying Permissions}, for the
3111 standard text for the copyright permissions.@refill
3114 * titlepage:: Create a title for the printed document.
3115 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3116 and @code{@@sp} commands.
3117 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
3118 and @code{@@author} commands.
3119 * Copyright & Permissions:: How to write the copyright notice and
3120 include copying permissions.
3121 * end titlepage:: Turn on page headings after the title and
3123 * headings on off:: An option for turning headings on and off
3124 and double or single sided printing.
3128 @node titlepage, titlefont center sp, Titlepage & Copyright Page, Titlepage & Copyright Page
3129 @comment node-name, next, previous, up
3130 @subsection @code{@@titlepage}
3134 Start the material for the title page and following copyright page
3135 with @code{@@titlepage} on a line by itself and end it with
3136 @code{@@end titlepage} on a line by itself.@refill
3138 The @code{@@end titlepage} command starts a new page and turns on page
3139 numbering. (@xref{Headings, , Page Headings}, for details about how to
3140 generate page headings.) All the material that you want to appear on
3141 unnumbered pages should be put between the @code{@@titlepage} and
3142 @code{@@end titlepage} commands. You can force the table of contents to
3143 appear there with the @code{@@setcontentsaftertitlepage} command
3146 @findex page@r{, within @code{@@titlepage}}
3147 By using the @code{@@page} command you can force a page break within the
3148 region delineated by the @code{@@titlepage} and @code{@@end titlepage}
3149 commands and thereby create more than one unnumbered page. This is how
3150 the copyright page is produced. (The @code{@@titlepage} command might
3151 perhaps have been better named the @code{@@titleandadditionalpages}
3152 command, but that would have been rather long!)
3154 When you write a manual about a computer program, you should write the
3155 version of the program to which the manual applies on the title page.
3156 If the manual changes more frequently than the program or is independent
3157 of it, you should also include an edition number@footnote{We have found
3158 that it is helpful to refer to versions of manuals as `editions' and
3159 versions of programs as `versions'; otherwise, we find we are liable to
3160 confuse each other in conversation by referring to both the
3161 documentation and the software with the same words.} for the manual.
3162 This helps readers keep track of which manual is for which version of
3163 the program. (The `Top' node should also contain this information; see
3164 @ref{makeinfo top, , @code{@@top}}.)
3166 Texinfo provides two main methods for creating a title page. One method
3167 uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3168 to generate a title page in which the words on the page are
3171 The second method uses the @code{@@title}, @code{@@subtitle}, and
3172 @code{@@author} commands to create a title page with black rules under
3173 the title and author lines and the subtitle text set flush to the
3174 right hand side of the page. With this method, you do not specify any
3175 of the actual formatting of the title page. You specify the text
3176 you want, and Texinfo does the formatting.
3178 You may use either method, or you may combine them; see the examples in
3181 @findex shorttitlepage
3182 @cindex Bastard title page
3183 @cindex Title page, bastard
3184 For extremely simple applications, and for the bastard title page in
3185 traditional book front matter, Texinfo also provides a command
3186 @code{@@shorttitlepage} which takes a single argument as the title. The
3187 argument is typeset on a page by itself and followed by a blank page.
3190 @node titlefont center sp
3191 @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3194 @findex sp @r{(titlepage line spacing)}
3196 You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3197 commands to create a title page for a printed document. (This is the
3198 first of the two methods for creating a title page in Texinfo.)@refill
3200 Use the @code{@@titlefont} command to select a large font suitable for
3201 the title itself. You can use @code{@@titlefont} more than once if you
3202 have an especially long title.
3208 @@titlefont@{Texinfo@}
3211 Use the @code{@@center} command at the beginning of a line to center
3212 the remaining text on that line. Thus,@refill
3215 @@center @@titlefont@{Texinfo@}
3219 centers the title, which in this example is ``Texinfo'' printed
3220 in the title font.@refill
3222 Use the @code{@@sp} command to insert vertical space. For example:@refill
3229 This inserts two blank lines on the printed page. (@xref{sp, ,
3230 @code{@@sp}}, for more information about the @code{@@sp}
3233 A template for this method looks like this:@refill
3239 @@center @@titlefont@{@var{name-of-manual-when-printed}@}
3241 @@center @var{subtitle-if-any}
3243 @@center @var{author}
3249 The spacing of the example fits an 8.5 by 11 inch manual.@refill
3252 @node title subtitle author
3253 @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3258 You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3259 commands to create a title page in which the vertical and horizontal
3260 spacing is done for you automatically. This contrasts with the method
3261 described in the previous section, in which the @code{@@sp} command is
3262 needed to adjust vertical spacing.
3264 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3265 commands at the beginning of a line followed by the title, subtitle,
3268 The @code{@@title} command produces a line in which the title is set
3269 flush to the left-hand side of the page in a larger than normal font.
3270 The title is underlined with a black rule. Only a single line is
3271 allowed; the @code{@@*} command may not be used to break the title into
3272 two lines. To handle very long titles, you may find it profitable to
3273 use both @code{@@title} and @code{@@titlefont}; see the final example in
3276 The @code{@@subtitle} command sets subtitles in a normal-sized font
3277 flush to the right-hand side of the page.@refill
3279 The @code{@@author} command sets the names of the author or authors in
3280 a middle-sized font flush to the left-hand side of the page on a line
3281 near the bottom of the title page. The names are underlined with a
3282 black rule that is thinner than the rule that underlines the title.
3283 (The black rule only occurs if the @code{@@author} command line is
3284 followed by an @code{@@page} command line.)@refill
3286 There are two ways to use the @code{@@author} command: you can write
3287 the name or names on the remaining part of the line that starts with
3288 an @code{@@author} command:@refill
3291 @@author by Jane Smith and John Doe
3295 or you can write the names one above each other by using two (or more)
3296 @code{@@author} commands:@refill
3306 (Only the bottom name is underlined with a black rule.)@refill
3309 A template for this method looks like this:@refill
3314 @@title @var{name-of-manual-when-printed}
3315 @@subtitle @var{subtitle-if-any}
3316 @@subtitle @var{second-subtitle}
3317 @@author @var{author}
3324 You may also combine the @code{@@titlefont} method described in the
3325 previous section and @code{@@title} method described in this one. This
3326 may be useful if you have a very long title. Here is a real-life example:
3331 @@titlefont@{GNU Software@}
3333 @@title for MS-Windows and MS-DOS
3334 @@subtitle Edition @@value@{edition@} for Release @@value@{cd-edition@}
3335 @@author by Daniel Hagerty, Melissa Weisshaus
3336 @@author and Eli Zaretskii
3341 (The use of @code{@@value} here is explained in @ref{value
3342 Example,,@code{@@value} Example}.)
3345 @node Copyright & Permissions
3346 @subsection Copyright Page and Permissions
3347 @cindex Copyright page
3348 @cindex Printed permissions
3349 @cindex Permissions, printed
3351 By international treaty, the copyright notice for a book should be
3352 either on the title page or on the back of the title page. The
3353 copyright notice should include the year followed by the name of the
3354 organization or person who owns the copyright.@refill
3356 When the copyright notice is on the back of the title page, that page
3357 is customarily not numbered. Therefore, in Texinfo, the information
3358 on the copyright page should be within @code{@@titlepage} and
3359 @code{@@end titlepage} commands.@refill
3363 @cindex Vertical whitespace (@samp{vskip})
3364 Use the @code{@@page} command to cause a page break. To push the
3365 copyright notice and the other text on the copyright page towards the
3366 bottom of the page, you can write a somewhat mysterious line after the
3367 @code{@@page} command that reads like this:@refill
3370 @@vskip 0pt plus 1filll
3374 This is a @TeX{} command that is not supported by the Info formatting
3375 commands. The @code{@@vskip} command inserts whitespace. The
3376 @samp{0pt plus 1filll} means to put in zero points of mandatory whitespace,
3377 and as much optional whitespace as needed to push the
3378 following text to the bottom of the page. Note the use of three
3379 @samp{l}s in the word @samp{filll}; this is the correct usage in
3383 In a printed manual, the @code{@@copyright@{@}} command generates a
3384 @samp{c} inside a circle. (In Info, it generates @samp{(C)}.) The
3385 copyright notice itself has the following legally defined sequence:@refill
3388 Copyright @copyright{} @var{year} @var{copyright-owner}
3391 It is customary to put information on how to get a manual after the
3392 copyright notice, followed by the copying permissions for the manual.
3394 Permissions must be given here as well as in the summary segment within
3395 @code{@@ifinfo} and @code{@@end ifinfo} that immediately follows the
3396 header since this text appears only in the printed manual and the
3397 @samp{ifinfo} text appears only in the Info file.
3399 @xref{Sample Permissions}, for the standard text.@refill
3403 @subsection Heading Generation
3404 @findex end titlepage
3405 @cindex Headings, page, begin to appear
3406 @cindex Titlepage end starts headings
3407 @cindex End titlepage starts headings
3409 An @code{@@end titlepage} command on a line by itself not only marks
3410 the end of the title and copyright pages, but also causes @TeX{} to start
3411 generating page headings and page numbers.
3413 To repeat what is said elsewhere, Texinfo has two standard page heading
3414 formats, one for documents which are printed on one side of each sheet of paper
3415 (single-sided printing), and the other for documents which are printed on both
3416 sides of each sheet (double-sided printing).
3417 (@xref{setchapternewpage, ,@code{@@setchapternewpage}}.)
3418 You can specify these formats in different ways:@refill
3422 The conventional way is to write an @code{@@setchapternewpage} command
3423 before the title page commands, and then have the @code{@@end
3424 titlepage} command start generating page headings in the manner desired.
3425 (@xref{setchapternewpage, , @code{@@setchapternewpage}}.)@refill
3428 Alternatively, you can use the @code{@@headings} command to prevent page
3429 headings from being generated or to start them for either single or
3430 double-sided printing. (Write an @code{@@headings} command immediately
3431 after the @code{@@end titlepage} command. @xref{headings on off, , The
3432 @code{@@headings} Command}, for more information.)@refill
3435 Or, you may specify your own page heading and footing format.
3436 @xref{Headings, , Page Headings}, for detailed
3437 information about page headings and footings.@refill
3440 Most documents are formatted with the standard single-sided or
3441 double-sided format, using @code{@@setchapternewpage odd} for
3442 double-sided printing and no @code{@@setchapternewpage} command for
3443 single-sided printing.@refill
3445 @node headings on off, , end titlepage, Titlepage & Copyright Page
3446 @comment node-name, next, previous, up
3447 @subsection The @code{@@headings} Command
3450 The @code{@@headings} command is rarely used. It specifies what kind of
3451 page headings and footings to print on each page. Usually, this is
3452 controlled by the @code{@@setchapternewpage} command. You need the
3453 @code{@@headings} command only if the @code{@@setchapternewpage} command
3454 does not do what you want, or if you want to turn off pre-defined page
3455 headings prior to defining your own. Write an @code{@@headings} command
3456 immediately after the @code{@@end titlepage} command.@refill
3458 You can use @code{@@headings} as follows:@refill
3461 @item @@headings off
3462 Turn off printing of page headings.@refill
3464 @item @@headings single
3465 Turn on page headings appropriate for single-sided printing.
3468 @item @@headings double
3469 @itemx @@headings on
3470 Turn on page headings appropriate for double-sided printing. The two
3471 commands, @code{@@headings on} and @code{@@headings double}, are
3474 @item @@headings singleafter
3475 @itemx @@headings doubleafter
3476 Turn on @code{single} or @code{double} headings, respectively, after the
3477 current page is output.
3480 Turn on page headings: @code{single} if @samp{@@setchapternewpage
3481 on}, @code{double} otherwise.
3484 For example, suppose you write @code{@@setchapternewpage off} before the
3485 @code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3486 same page as the end of the last chapter. This command also causes
3487 @TeX{} to typeset page headers for single-sided printing. To cause
3488 @TeX{} to typeset for double sided printing, write @code{@@headings
3489 double} after the @code{@@end titlepage} command.
3491 You can stop @TeX{} from generating any page headings at all by
3492 writing @code{@@headings off} on a line of its own immediately after the
3493 line containing the @code{@@end titlepage} command, like this:@refill
3501 The @code{@@headings off} command overrides the @code{@@end titlepage}
3502 command, which would otherwise cause @TeX{} to print page
3505 You can also specify your own style of page heading and footing.
3506 @xref{Headings, , Page Headings}, for more information.@refill
3510 @section The `Top' Node and Master Menu
3511 @cindex @samp{@r{Top}} node
3515 The `Top' node is the node from which you enter an Info file.@refill
3517 A `Top' node should contain a brief description of the Info file and an
3518 extensive, master menu for the whole Info file.
3519 This helps the reader understand what the Info file is
3520 about. Also, you should write the version number of the program to
3521 which the Info file applies; or, at least, the edition number.@refill
3523 The contents of the `Top' node should appear only in the Info file; none
3524 of it should appear in printed output, so enclose it between
3525 @code{@@ifinfo} and @code{@@end ifinfo} commands. (@TeX{} does not
3526 print either an @code{@@node} line or a menu; they appear only in Info;
3527 strictly speaking, you are not required to enclose these parts between
3528 @code{@@ifinfo} and @code{@@end ifinfo}, but it is simplest to do so.
3529 @xref{Conditionals, , Conditionally Visible Text}.)@refill
3532 * Title of Top Node:: Sketch what the file is about.
3533 * Master Menu Parts:: A master menu has three or more parts.
3537 @node Title of Top Node
3538 @subsection `Top' Node Title
3540 Sometimes, you will want to place an @code{@@top} sectioning command
3541 line containing the title of the document immediately after the
3542 @code{@@node Top} line (@pxref{makeinfo top command, , The @code{@@top}
3543 Sectioning Command}, for more information).@refill
3545 For example, the beginning of the Top node of this manual contains an
3546 @code{@@top} sectioning command, a short description, and edition and
3547 version information. It looks like this:@refill
3555 @@node Top, Copying, , (dir)
3558 Texinfo is a documentation system@dots{}
3562 This is edition@dots{}
3569 * Copying:: Texinfo is freely
3571 * Overview:: What is Texinfo?
3577 In a `Top' node, the `Previous', and `Up' nodes usually refer to the top
3578 level directory of the whole Info system, which is called @samp{(dir)}.
3579 The `Next' node refers to the first node that follows the main or master
3580 menu, which is usually the copying permissions, introduction, or first
3583 @node Master Menu Parts, , Title of Top Node, The Top Node
3584 @subsection Parts of a Master Menu
3585 @cindex Master menu parts
3586 @cindex Parts of a master menu
3588 A @dfn{master menu} is a detailed main menu listing all the nodes in a
3591 A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3592 commands and does not appear in the printed document.@refill
3594 Generally, a master menu is divided into parts.@refill
3598 The first part contains the major nodes in the Texinfo file: the nodes
3599 for the chapters, chapter-like sections, and the appendices.@refill
3602 The second part contains nodes for the indices.@refill
3605 The third and subsequent parts contain a listing of the other, lower
3606 level nodes, often ordered by chapter. This way, rather than go
3607 through an intermediary menu, an inquirer can go directly to a
3608 particular node when searching for specific information. These menu
3609 items are not required; add them if you think they are a
3610 convenience. If you do use them, put @code{@@detailmenu} before the
3611 first one, and @code{@@end detailmenu} after the last; otherwise,
3612 @code{makeinfo} will get confused.
3615 Each section in the menu can be introduced by a descriptive line. So
3616 long as the line does not begin with an asterisk, it will not be
3617 treated as a menu entry. (@xref{Writing a Menu}, for more
3618 information.)@refill
3620 For example, the master menu for this manual looks like the following
3621 (but has many more entries):@refill
3626 * Copying:: Texinfo is freely
3628 * Overview:: What is Texinfo?
3629 * Texinfo Mode:: Special features in GNU Emacs.
3634 * Command and Variable Index::
3635 An entry for each @@-command.
3636 * Concept Index:: An entry for each concept.
3641 --- The Detailed Node Listing ---
3645 * Info Files:: What is an Info file?
3646 * Printed Manuals:: Characteristics of
3655 * Info on a Region:: Formatting part of a file
3664 @node Software Copying Permissions, , The Top Node, Beginning a File
3665 @comment node-name, next, previous, up
3666 @section Software Copying Permissions
3667 @cindex Software copying permissions
3668 @cindex Copying software
3669 @cindex Distribution
3670 @cindex License agreement
3672 If the Texinfo file has a section containing the ``General Public
3673 License'' and the distribution information and a warranty disclaimer
3674 for the software that is documented, this section usually follows the
3675 `Top' node. The General Public License is very important to Project
3676 GNU software. It ensures that you and others will continue to have a
3677 right to use and share the software.@refill
3679 The copying and distribution information and the disclaimer are
3680 followed by an introduction or else by the first chapter of the
3683 @cindex Introduction, as part of file
3684 Although an introduction is not a required part of a Texinfo file, it
3685 is very helpful. Ideally, it should state clearly and concisely what
3686 the file is about and who would be interested in reading it. In
3687 general, an introduction would follow the licensing and distribution
3688 information, although sometimes people put it earlier in the document.
3689 Usually, an introduction is put in an @code{@@unnumbered} section.
3690 (@xref{unnumbered & appendix, , The @code{@@unnumbered} and
3691 @code{@@appendix} Commands}.)@refill
3693 @node Ending a File, Structuring, Beginning a File, Top
3694 @comment node-name, next, previous, up
3695 @chapter Ending a Texinfo File
3696 @cindex Ending a Texinfo file
3697 @cindex Texinfo file ending
3701 The end of a Texinfo file should include commands to create indices and
3702 (usually) to generate detailed and summary tables of contents. And it
3703 must include the @code{@@bye} command that marks the last line processed
3710 @@node Concept Index, , Variables Index, Top
3711 @@c node-name, next, previous, up
3712 @@unnumbered Concept Index
3721 * Printing Indices & Menus:: How to print an index in hardcopy and
3722 generate index menus in Info.
3723 * Contents:: How to create a table of contents.
3724 * File End:: How to mark the end of a file.
3727 @node Printing Indices & Menus, Contents, Ending a File, Ending a File
3728 @comment node-name, next, previous, up
3729 @section Index Menus and Printing an Index
3731 @cindex Printing an index
3732 @cindex Indices, printing and menus
3733 @cindex Generating menus with indices
3734 @cindex Menus generated with indices
3736 To print an index means to include it as part of a manual or Info
3737 file. This does not happen automatically just because you use
3738 @code{@@cindex} or other index-entry generating commands in the
3739 Texinfo file; those just cause the raw data for the index to be
3740 accumulated. To generate an index, you must include the
3741 @code{@@printindex} command at the place in the document where you
3742 want the index to appear. Also, as part of the process of creating a
3743 printed manual, you must run a program called @code{texindex}
3744 (@pxref{Hardcopy}) to sort the raw data to produce a sorted
3745 index file. The sorted index file is what is actually used to
3746 print the index.@refill
3748 Texinfo offers six different types of predefined index: the concept
3749 index, the function index, the variables index, the keystroke index, the
3750 program index, and the data type index (@pxref{Predefined Indices}). Each
3751 index type has a two-letter name: @samp{cp}, @samp{fn}, @samp{vr},
3752 @samp{ky}, @samp{pg}, and @samp{tp}. You may merge indices, or put them
3753 into separate sections (@pxref{Combining Indices}); or you may define
3754 your own indices (@pxref{New Indices, , Defining New Indices}).@refill
3756 The @code{@@printindex} command takes a two-letter index name, reads
3757 the corresponding sorted index file and formats it appropriately into
3761 The two-letter index names are:
3778 The @code{@@printindex} command does not generate a chapter heading
3779 for the index. Consequently, you should precede the
3780 @code{@@printindex} command with a suitable section or chapter command
3781 (usually @code{@@unnumbered}) to supply the chapter heading and put
3782 the index into the table of contents. Precede the @code{@@unnumbered}
3783 command with an @code{@@node} line.@refill
3790 @@node Variable Index, Concept Index, Function Index, Top
3791 @@comment node-name, next, previous, up
3792 @@unnumbered Variable Index
3798 @@node Concept Index, , Variable Index, Top
3799 @@comment node-name, next, previous, up
3800 @@unnumbered Concept Index
3807 Readers often prefer that the concept index come last in a book,
3808 since that makes it easiest to find. Having just one index helps
3809 readers also, since then they have only one place to look
3814 @section Generating a Table of Contents
3815 @cindex Table of contents
3816 @cindex Contents, Table of
3817 @cindex Short table of contents
3819 @findex summarycontents
3820 @findex shortcontents
3822 The @code{@@chapter}, @code{@@section}, and other structuring commands
3823 supply the information to make up a table of contents, but they do not
3824 cause an actual table to appear in the manual. To do this, you must use
3825 the @code{@@contents} and/or @code{@@summarycontents} command(s).
3829 Generate a table of contents in a printed manual, including all
3830 chapters, sections, subsections, etc., as well as appendices and
3831 unnumbered chapters. (Headings generated by the @code{@@heading}
3832 series of commands do not appear in the table of contents.)
3834 @item @@shortcontents
3835 @itemx @@summarycontents
3836 (@code{@@summarycontents} is a synonym for @code{@@shortcontents}; the
3837 two commands are exactly the same.)@refill
3839 Generate a short or summary table of contents that lists only the
3840 chapters (and appendices and unnumbered chapters). Omit sections, subsections
3841 and subsubsections. Only a long manual needs a short table
3842 of contents in addition to the full table of contents.@refill
3846 Both contents commands should be written on a line by themselves.
3847 The contents commands automatically generate a chapter-like heading at
3848 the top of the first table of contents page, so don't include any
3849 sectioning command such as @code{@@unnumbered} before them.
3851 Since an Info file uses menus instead of tables of contents, the Info
3852 formatting commands ignore the contents commands. But the contents are
3853 included in plain text output (generated by @code{makeinfo --no-headers}).
3855 The contents commands can be placed either at the very end of the file,
3856 after any indices (see the previous section) and just before the
3857 @code{@@bye} (see the next section), or near the beginning of the file,
3858 after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
3859 the former is that then the contents output is always up to date,
3860 because it reflects the processing just done. The advantage to the
3861 latter is that the contents are printed in the proper place, thus you do
3862 not need to rearrange the DVI file with @command{dviselect} or shuffle
3863 paper. However, contents commands at the beginning of the document are
3864 ignored when outputting to standard output.
3866 @findex setcontentsaftertitlepage
3867 @findex setshortcontentsaftertitlepage
3868 @cindex Contents, after title page
3869 @cindex Table of contents, after title page
3870 As an author, you can put the contents commands wherever you prefer.
3871 But if you are a user simply printing a manual, you may wish to print
3872 the contents after the title page even if the author put the contents
3873 commands at the end of the document (as is the case in most existing
3874 Texinfo documents). You can do this by specifying
3875 @code{@@setcontentsaftertitlepage} and/or
3876 @code{@@setshortcontentsaftertitlepage}. The first prints only the main
3877 contents after the @code{@@end titlepage}; the second prints both the
3878 short contents and the main contents. In either case, any subsequent
3879 @code{@@contents} or @code{@@shortcontents} is ignored (unless no
3880 @code{@@end titlepage} is ever encountered).
3882 You need to include the @code{@@set@dots{}contentsaftertitlepage}
3883 commands early in the document (just after @code{@@setfilename}, for
3884 example). Or, if you're using @command{texi2dvi} (@pxref{Format with
3885 texi2dvi}), you can use its @option{--texinfo} option to specify this
3886 without altering the source file at all. For example:
3888 texi2dvi --texinfo=@@setshortcontentsaftertitlepage foo.texi
3893 @section @code{@@bye} File Ending
3896 An @code{@@bye} command terminates @TeX{} or Info formatting. None of
3897 the formatting commands see any of the file following @code{@@bye}.
3898 The @code{@@bye} command should be on a line by itself.@refill
3900 If you wish, you may follow the @code{@@bye} line with notes. These notes
3901 will not be formatted and will not appear in either Info or a printed
3902 manual; it is as if text after @code{@@bye} were within @code{@@ignore}
3903 @dots{} @code{@@end ignore}. Also, you may follow the @code{@@bye} line
3904 with a local variables list. @xref{Compile-Command, , Using Local
3905 Variables and the Compile Command}, for more information.@refill
3909 @chapter Chapter Structuring
3910 @cindex Chapter structuring
3911 @cindex Structuring of chapters
3913 The @dfn{chapter structuring} commands divide a document into a hierarchy of
3914 chapters, sections, subsections, and subsubsections. These commands
3915 generate large headings; they also provide information for the table
3916 of contents of a printed manual (@pxref{Contents, , Generating a Table
3917 of Contents}).@refill
3919 The chapter structuring commands do not create an Info node structure,
3920 so normally you should put an @code{@@node} command immediately before
3921 each chapter structuring command (@pxref{Nodes}). The only time you
3922 are likely to use the chapter structuring commands without using the
3923 node structuring commands is if you are writing a document that
3924 contains no cross references and will never be transformed into Info
3927 It is unlikely that you will ever write a Texinfo file that is
3928 intended only as an Info file and not as a printable document. If you
3929 do, you might still use chapter structuring commands to create a
3930 heading at the top of each node---but you don't need to.@refill
3933 * Tree Structuring:: A manual is like an upside down tree @dots{}
3934 * Structuring Command Types:: How to divide a manual into parts.
3935 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
3937 * unnumbered & appendix::
3938 * majorheading & chapheading::
3940 * unnumberedsec appendixsec heading::
3942 * unnumberedsubsec appendixsubsec subheading::
3943 * subsubsection:: Commands for the lowest level sections.
3944 * Raise/lower sections:: How to change commands' hierarchical level.
3948 @node Tree Structuring
3949 @section Tree Structure of Sections
3950 @cindex Tree structuring
3952 A Texinfo file is usually structured like a book with chapters,
3953 sections, subsections, and the like. This structure can be visualized
3954 as a tree (or rather as an upside-down tree) with the root at the top
3955 and the levels corresponding to chapters, sections, subsection, and
3956 subsubsections.@refill
3958 Here is a diagram that shows a Texinfo file with three chapters,
3959 each of which has two sections.@refill
3965 -------------------------------------
3967 Chapter 1 Chapter 2 Chapter 3
3969 -------- -------- --------
3971 Section Section Section Section Section Section
3972 1.1 1.2 2.1 2.2 3.1 3.2
3977 In a Texinfo file that has this structure, the beginning of Chapter 2
3978 looks like this:@refill
3982 @@node Chapter 2, Chapter 3, Chapter 1, top
3987 The chapter structuring commands are described in the sections that
3988 follow; the @code{@@node} and @code{@@menu} commands are described in
3989 following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
3992 @node Structuring Command Types
3993 @section Structuring Command Types
3995 The chapter structuring commands fall into four groups or series, each
3996 of which contains structuring commands corresponding to the
3997 hierarchical levels of chapters, sections, subsections, and
3998 subsubsections.@refill
4000 The four groups are the @code{@@chapter} series, the
4001 @code{@@unnumbered} series, the @code{@@appendix} series, and the
4002 @code{@@heading} series.@refill
4004 Each command produces titles that have a different appearance on the
4005 printed page or Info file; only some of the commands produce
4006 titles that are listed in the table of contents of a printed book or
4011 The @code{@@chapter} and @code{@@appendix} series of commands produce
4012 numbered or lettered entries both in the body of a printed work and in
4013 its table of contents.@refill
4016 The @code{@@unnumbered} series of commands produce unnumbered entries
4017 both in the body of a printed work and in its table of contents. The
4018 @code{@@top} command, which has a special use, is a member of this
4019 series (@pxref{makeinfo top, , @code{@@top}}).@refill
4022 The @code{@@heading} series of commands produce unnumbered headings
4023 that do not appear in a table of contents. The heading commands never
4024 start a new page.@refill
4027 The @code{@@majorheading} command produces results similar to using
4028 the @code{@@chapheading} command but generates a larger vertical
4029 whitespace before the heading.@refill
4032 When an @code{@@setchapternewpage} command says to do so, the
4033 @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
4034 start new pages in the printed manual; the @code{@@heading} commands
4038 Here are the four groups of chapter structuring commands:@refill
4040 @multitable @columnfractions .19 .30 .29 .22
4042 @item @tab @tab @tab No new page
4043 @item Numbered @tab Unnumbered @tab Lettered and numbered
4045 @item In contents @tab In contents @tab In contents @tab Not in contents
4046 @item @tab @code{@@top} @tab
4047 @tab @code{@@majorheading}
4048 @item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix}
4049 @tab @code{@@chapheading}
4050 @item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec}
4051 @tab @code{@@heading}
4052 @item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec}
4053 @tab @code{@@subheading}
4054 @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec}
4055 @tab @code{@@subsubheading}
4060 @section @code{@@top}
4062 The @code{@@top} command is a special sectioning command that you use
4063 only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4064 The @code{@@top} command tells the @code{makeinfo} formatter which node
4065 is the `Top' node, so it can use it as the root of the node tree if your
4066 manual uses implicit pointers. It has the same typesetting effect as
4067 @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
4068 and @code{@@appendix}}). For detailed information, see @ref{makeinfo
4069 top command, , The @code{@@top} Command}.
4071 The @code{@@top} node and its menu (if any) is conventionally wrapped in
4072 an @code{@@ifnottex} conditional so that it will appear only in Info and
4073 HTML output, not @TeX{}.
4076 @node chapter, unnumbered & appendix, makeinfo top, Structuring
4077 @comment node-name, next, previous, up
4078 @section @code{@@chapter}
4081 @code{@@chapter} identifies a chapter in the document. Write the
4082 command at the beginning of a line and follow it on the same line by
4083 the title of the chapter.@refill
4085 For example, this chapter in this manual is entitled ``Chapter
4086 Structuring''; the @code{@@chapter} line looks like this:@refill
4089 @@chapter Chapter Structuring
4092 In @TeX{}, the @code{@@chapter} command creates a chapter in the
4093 document, specifying the chapter title. The chapter is numbered
4094 automatically.@refill
4096 In Info, the @code{@@chapter} command causes the title to appear on a
4097 line by itself, with a line of asterisks inserted underneath. Thus,
4098 in Info, the above example produces the following output:@refill
4106 Texinfo also provides a command @code{@@centerchap}, which is analogous
4107 to @code{@@unnumbered}, but centers its argument in the printed output.
4108 This kind of stylistic choice is not usually offered by Texinfo.
4109 @c but the Hacker's Dictionary wanted it ...
4112 @node unnumbered & appendix
4113 @section @code{@@unnumbered} and @code{@@appendix}
4117 Use the @code{@@unnumbered} command to create a chapter that appears
4118 in a printed manual without chapter numbers of any kind. Use the
4119 @code{@@appendix} command to create an appendix in a printed manual
4120 that is labelled by letter instead of by number.@refill
4122 For Info file output, the @code{@@unnumbered} and @code{@@appendix}
4123 commands are equivalent to @code{@@chapter}: the title is printed on a
4124 line by itself with a line of asterisks underneath. (@xref{chapter, ,
4125 @code{@@chapter}}.)@refill
4127 To create an appendix or an unnumbered chapter, write an
4128 @code{@@appendix} or @code{@@unnumbered} command at the beginning of a
4129 line and follow it on the same line by the title, as you would if you
4130 were creating a chapter.@refill
4133 @node majorheading & chapheading, section, unnumbered & appendix, Structuring
4134 @section @code{@@majorheading}, @code{@@chapheading}
4135 @findex majorheading
4138 The @code{@@majorheading} and @code{@@chapheading} commands put
4139 chapter-like headings in the body of a document.@refill
4141 However, neither command causes @TeX{} to produce a numbered heading
4142 or an entry in the table of contents; and neither command causes
4143 @TeX{} to start a new page in a printed manual.@refill
4145 In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4146 whitespace before the heading than an @code{@@chapheading} command but
4147 is otherwise the same.@refill
4150 the @code{@@majorheading} and
4151 @code{@@chapheading} commands are equivalent to
4152 @code{@@chapter}: the title is printed on a line by itself with a line
4153 of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
4155 @node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
4156 @comment node-name, next, previous, up
4157 @section @code{@@section}
4160 In a printed manual, an @code{@@section} command identifies a
4161 numbered section within a chapter. The section title appears in the
4162 table of contents. In Info, an @code{@@section} command provides a
4163 title for a segment of text, underlined with @samp{=}.@refill
4165 This section is headed with an @code{@@section} command and looks like
4166 this in the Texinfo file:@refill
4169 @@section @@code@{@@@@section@}
4172 To create a section, write the @code{@@section} command at the
4173 beginning of a line and follow it on the same line by the section
4179 @@section This is a section
4195 @node unnumberedsec appendixsec heading, subsection, section, Structuring
4196 @comment node-name, next, previous, up
4197 @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
4198 @findex unnumberedsec
4202 The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4203 commands are, respectively, the unnumbered, appendix-like, and
4204 heading-like equivalents of the @code{@@section} command.
4205 (@xref{section, , @code{@@section}}.)@refill
4208 @item @@unnumberedsec
4209 The @code{@@unnumberedsec} command may be used within an
4210 unnumbered chapter or within a regular chapter or appendix to
4211 provide an unnumbered section.@refill
4214 @itemx @@appendixsection
4215 @code{@@appendixsection} is a longer spelling of the
4216 @code{@@appendixsec} command; the two are synonymous.@refill
4217 @findex appendixsection
4219 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4220 command is used only within appendices.@refill
4223 You may use the @code{@@heading} command anywhere you wish for a
4224 section-style heading that will not appear in the table of contents.@refill
4227 @node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
4228 @comment node-name, next, previous, up
4229 @section The @code{@@subsection} Command
4232 Subsections are to sections as sections are to chapters.
4233 (@xref{section, , @code{@@section}}.) In Info, subsection titles are
4234 underlined with @samp{-}. For example,@refill
4237 @@subsection This is a subsection
4245 This is a subsection
4246 --------------------
4250 In a printed manual, subsections are listed in the table of contents
4251 and are numbered three levels deep.@refill
4253 @node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
4254 @comment node-name, next, previous, up
4255 @section The @code{@@subsection}-like Commands
4256 @cindex Subsection-like commands
4257 @findex unnumberedsubsec
4258 @findex appendixsubsec
4261 The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4262 @code{@@subheading} commands are, respectively, the unnumbered,
4263 appendix-like, and heading-like equivalents of the @code{@@subsection}
4264 command. (@xref{subsection, , @code{@@subsection}}.)@refill
4266 In Info, the @code{@@subsection}-like commands generate a title
4267 underlined with hyphens. In a printed manual, an @code{@@subheading}
4268 command produces a heading like that of a subsection except that it is
4269 not numbered and does not appear in the table of contents. Similarly,
4270 an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4271 that of a subsection and an @code{@@appendixsubsec} command produces a
4272 subsection-like heading labelled with a letter and numbers; both of
4273 these commands produce headings that appear in the table of
4276 @node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
4277 @comment node-name, next, previous, up
4278 @section The `subsub' Commands
4279 @cindex Subsub commands
4280 @findex subsubsection
4281 @findex unnumberedsubsubsec
4282 @findex appendixsubsubsec
4283 @findex subsubheading
4285 The fourth and lowest level sectioning commands in Texinfo are the
4286 `subsub' commands. They are:@refill
4289 @item @@subsubsection
4290 Subsubsections are to subsections as subsections are to sections.
4291 (@xref{subsection, , @code{@@subsection}}.) In a printed manual,
4292 subsubsection titles appear in the table of contents and are numbered
4293 four levels deep.@refill
4295 @item @@unnumberedsubsubsec
4296 Unnumbered subsubsection titles appear in the table of contents of a
4297 printed manual, but lack numbers. Otherwise, unnumbered
4298 subsubsections are the same as subsubsections. In Info, unnumbered
4299 subsubsections look exactly like ordinary subsubsections.@refill
4301 @item @@appendixsubsubsec
4302 Conventionally, appendix commands are used only for appendices and are
4303 lettered and numbered appropriately in a printed manual. They also
4304 appear in the table of contents. In Info, appendix subsubsections look
4305 exactly like ordinary subsubsections.@refill
4307 @item @@subsubheading
4308 The @code{@@subsubheading} command may be used anywhere that you need
4309 a small heading that will not appear in the table of contents. In
4310 Info, subsubheadings look exactly like ordinary subsubsection
4314 In Info, `subsub' titles are underlined with periods.
4318 @@subsubsection This is a subsubsection
4326 This is a subsubsection
4327 .......................
4331 @node Raise/lower sections, , subsubsection, Structuring
4332 @comment node-name, next, previous, up
4333 @section @code{@@raisesections} and @code{@@lowersections}
4334 @findex raisesections
4335 @findex lowersections
4336 @cindex Raising and lowering sections
4337 @cindex Sections, raising and lowering
4339 The @code{@@raisesections} and @code{@@lowersections} commands raise and
4340 lower the hierarchical level of chapters, sections, subsections and the
4341 like. The @code{@@raisesections} command changes sections to chapters,
4342 subsections to sections, and so on. The @code{@@lowersections} command
4343 changes chapters to sections, sections to subsections, and so on.
4345 @cindex Include files, and section levels
4346 An @code{@@lowersections} command is useful if you wish to include text
4347 that is written as an outer or standalone Texinfo file in another
4348 Texinfo file as an inner, included file. If you write the command at
4349 the beginning of the file, all your @code{@@chapter} commands are
4350 formatted as if they were @code{@@section} commands, all your
4351 @code{@@section} command are formatted as if they were
4352 @code{@@subsection} commands, and so on.
4355 @code{@@raisesections} raises a command one level in the chapter
4356 structuring hierarchy:@refill
4362 @@subsection @@section,
4363 @@section @@chapter,
4364 @@heading @@chapheading,
4370 @code{@@lowersections} lowers a command one level in the chapter
4371 structuring hierarchy:@refill
4377 @@chapter @@section,
4378 @@subsection @@subsubsection,
4379 @@heading @@subheading,
4384 An @code{@@raisesections} or @code{@@lowersections} command changes only
4385 those structuring commands that follow the command in the Texinfo file.
4386 Write an @code{@@raisesections} or @code{@@lowersections} command on a
4389 An @code{@@lowersections} command cancels an @code{@@raisesections}
4390 command, and vice versa. Typically, the commands are used like this:
4394 @@include somefile.texi
4398 Without the @code{@@raisesections}, all the subsequent sections in your
4399 document will be lowered.
4401 Repeated use of the commands continue to raise or lower the hierarchical
4402 level a step at a time.
4404 An attempt to raise above `chapters' reproduces chapter commands; an
4405 attempt to lower below `subsubsections' reproduces subsubsection
4411 @dfn{Nodes} are the primary segments of a Texinfo file. They do not
4412 themselves impose a hierarchical or any other kind of structure on a file.
4413 Nodes contain @dfn{node pointers} that name other nodes, and can contain
4414 @dfn{menus} which are lists of nodes. In Info, the movement commands
4415 can carry you to a pointed-to node or to a node listed in a menu. Node
4416 pointers and menus provide structure for Info files just as chapters,
4417 sections, subsections, and the like, provide structure for printed
4421 * Two Paths:: Different commands to structure
4422 Info output and printed output.
4423 * Node Menu Illustration:: A diagram, and sample nodes and menus.
4424 * node:: Creating nodes, in detail.
4425 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
4426 * anchor:: Defining arbitrary cross-reference targets.
4433 The node and menu commands and the chapter structuring commands are
4434 technically independent of each other:
4438 In Info, node and menu commands provide structure. The chapter
4439 structuring commands generate headings with different kinds of
4440 underlining---asterisks for chapters, hyphens for sections, and so on;
4441 they do nothing else.@refill
4444 In @TeX{}, the chapter structuring commands generate chapter and section
4445 numbers and tables of contents. The node and menu commands provide
4446 information for cross references; they do nothing else.@refill
4449 You can use node pointers and menus to structure an Info file any way
4450 you want; and you can write a Texinfo file so that its Info output has a
4451 different structure than its printed output. However, virtually all
4452 Texinfo files are written such that the structure for the Info output
4453 corresponds to the structure for the printed output. It is neither
4454 convenient nor understandable to the reader to do otherwise.@refill
4456 Generally, printed output is structured in a tree-like hierarchy in
4457 which the chapters are the major limbs from which the sections branch
4458 out. Similarly, node pointers and menus are organized to create a
4459 matching structure in the Info output.@refill
4462 @node Node Menu Illustration
4463 @section Node and Menu Illustration
4465 Here is a copy of the diagram shown earlier that illustrates a Texinfo
4466 file with three chapters, each of which contains two sections.@refill
4468 The ``root'' is at the top of the diagram and the ``leaves'' are at the
4469 bottom. This is how such a diagram is drawn conventionally; it
4470 illustrates an upside-down tree. For this reason, the root node is
4471 called the `Top' node, and `Up' node pointers carry you closer to the
4478 -------------------------------------
4480 Chapter 1 Chapter 2 Chapter 3
4482 -------- -------- --------
4484 Section Section Section Section Section Section
4485 1.1 1.2 2.1 2.2 3.1 3.2
4489 The fully-written command to start Chapter 2 would be this:
4493 @@node Chapter 2, Chapter 3, Chapter 1, Top
4494 @@comment node-name, next, previous, up
4499 This @code{@@node} line says that the name of this node is ``Chapter
4500 2'', the name of the `Next' node is ``Chapter 3'', the name of the
4501 `Previous' node is ``Chapter 1'', and the name of the `Up' node is
4502 ``Top''. You can omit writing out these node names if your document is
4503 hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
4504 pointer relationships still obtain.
4507 @strong{Please Note:} `Next' refers to the next node at the same
4508 hierarchical level in the manual, not necessarily to the next node
4509 within the Texinfo file. In the Texinfo file, the subsequent node may
4510 be at a lower level---a section-level node most often follows a
4511 chapter-level node, for example. `Next' and `Previous' refer to nodes
4512 at the @emph{same} hierarchical level. (The `Top' node contains the
4513 exception to this rule. Since the `Top' node is the only node at that
4514 level, `Next' refers to the first following node, which is almost always
4515 a chapter or chapter-level node.)@refill
4518 To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
4519 2. (@xref{Menus}.) You would write the menu just
4520 before the beginning of Section 2.1, like this:@refill
4525 * Sect. 2.1:: Description of this section.
4531 Write the node for Sect. 2.1 like this:@refill
4535 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4536 @@comment node-name, next, previous, up
4540 In Info format, the `Next' and `Previous' pointers of a node usually
4541 lead to other nodes at the same level---from chapter to chapter or from
4542 section to section (sometimes, as shown, the `Previous' pointer points
4543 up); an `Up' pointer usually leads to a node at the level above (closer
4544 to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4545 to `leaves'). (A cross reference can point to a node at any level;
4546 see @ref{Cross References}.)@refill
4548 Usually, an @code{@@node} command and a chapter structuring command are
4549 used in sequence, along with indexing commands. (You may follow the
4550 @code{@@node} line with a comment line that reminds you which pointer is
4553 Here is the beginning of the chapter in this manual called ``Ending a
4554 Texinfo File''. This shows an @code{@@node} line followed by a comment
4555 line, an @code{@@chapter} line, and then by indexing lines.@refill
4559 @@node Ending a File, Structuring, Beginning a File, Top
4560 @@comment node-name, next, previous, up
4561 @@chapter Ending a Texinfo File
4562 @@cindex Ending a Texinfo file
4563 @@cindex Texinfo file ending
4564 @@cindex File ending
4570 @section The @code{@@node} Command
4572 @cindex Node, defined
4575 A @dfn{node} is a segment of text that begins at an @code{@@node}
4576 command and continues until the next @code{@@node} command. The
4577 definition of node is different from that for chapter or section. A
4578 chapter may contain sections and a section may contain subsections;
4579 but a node cannot contain subnodes; the text of a node continues only
4580 until the next @code{@@node} command in the file. A node usually
4581 contains only one chapter structuring command, the one that follows
4582 the @code{@@node} line. On the other hand, in printed output nodes
4583 are used only for cross references, so a chapter or section may
4584 contain any number of nodes. Indeed, a chapter usually contains
4585 several nodes, one for each section, subsection, and
4586 subsubsection.@refill
4588 To create a node, write an @code{@@node} command at the beginning of a
4589 line, and follow it with up to four arguments, separated by commas, on
4590 the rest of the same line. The first argument is required; it is the
4591 name of this node. The subsequent arguments are the names of the
4592 `Next', `Previous', and `Up' pointers, in that order, and may be omitted
4593 if your Texinfo document is hierarchically organized (@pxref{makeinfo
4596 You may insert spaces before each name if you wish; the spaces are
4597 ignored. You must write the name of the node and the names of the
4598 `Next', `Previous', and `Up' pointers all on the same line. Otherwise,
4599 the formatters fail. (@inforef{Top, info, info}, for more information
4600 about nodes in Info.)
4602 Usually, you write one of the chapter-structuring command lines
4603 immediately after an @code{@@node} line---for example, an
4604 @code{@@section} or @code{@@subsection} line. (@xref{Structuring
4608 @strong{Please note:} The GNU Emacs Texinfo mode updating commands work
4609 only with Texinfo files in which @code{@@node} lines are followed by chapter
4610 structuring lines. @xref{Updating Requirements}.@refill
4613 @TeX{} uses @code{@@node} lines to identify the names to use for cross
4614 references. For this reason, you must write @code{@@node} lines in a
4615 Texinfo file that you intend to format for printing, even if you do not
4616 intend to format it for Info. (Cross references, such as the one at the
4617 end of this sentence, are made with @code{@@xref} and related commands;
4618 see @ref{Cross References}.)@refill
4621 * Node Names:: How to choose node and pointer names.
4622 * Writing a Node:: How to write an @code{@@node} line.
4623 * Node Line Tips:: Keep names short.
4624 * Node Line Requirements:: Keep names unique, without @@-commands.
4625 * First Node:: How to write a `Top' node.
4626 * makeinfo top command:: How to use the @code{@@top} command.
4627 * Top Node Summary:: Write a brief description for readers.
4632 @subsection Choosing Node and Pointer Names
4634 @cindex Node names, choosing
4635 The name of a node identifies the node. The pointers enable
4636 you to reach other nodes and consist of the names of those nodes.@refill
4638 Normally, a node's `Up' pointer contains the name of the node whose menu
4639 mentions that node. The node's `Next' pointer contains the name of the
4640 node that follows that node in that menu and its `Previous' pointer
4641 contains the name of the node that precedes it in that menu. When a
4642 node's `Previous' node is the same as its `Up' node, both node pointers
4643 name the same node.@refill
4645 Usually, the first node of a Texinfo file is the `Top' node, and its
4646 `Up' and `Previous' pointers point to the @file{dir} file, which
4647 contains the main menu for all of Info.@refill
4649 The `Top' node itself contains the main or master menu for the manual.
4650 Also, it is helpful to include a brief description of the manual in the
4651 `Top' node. @xref{First Node}, for information on how to write the
4652 first node of a Texinfo file.@refill
4654 Even when you explicitly specify all pointers, that does not mean you
4655 can write the nodes in the Texinfo source file in an arbitrary order!
4656 Because @TeX{} processes the file sequentially, irrespective of node
4657 pointers, you must write the nodes in the order you wish them to appear
4658 in the printed output.
4661 @node Writing a Node
4662 @subsection How to Write an @code{@@node} Line
4663 @cindex Writing an @code{@@node} line
4664 @cindex @code{@@node} line writing
4665 @cindex Node line writing
4667 The easiest way to write an @code{@@node} line is to write @code{@@node}
4668 at the beginning of a line and then the name of the node, like
4672 @@node @var{node-name}
4675 If you are using GNU Emacs, you can use the update node commands
4676 provided by Texinfo mode to insert the names of the pointers; or you
4677 can leave the pointers out of the Texinfo file and let @code{makeinfo}
4678 insert node pointers into the Info file it creates. (@xref{Texinfo
4679 Mode}, and @ref{makeinfo Pointer Creation}.)@refill
4681 Alternatively, you can insert the `Next', `Previous', and `Up'
4682 pointers yourself. If you do this, you may find it helpful to use the
4683 Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
4684 @samp{@@node} and a comment line listing the names of the pointers in
4685 their proper order. The comment line helps you keep track of which
4686 arguments are for which pointers. This comment line is especially useful
4687 if you are not familiar with Texinfo.@refill
4689 The template for a fully-written-out node line with `Next', `Previous',
4690 and `Up' pointers looks like this:@refill
4693 @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4696 If you wish, you can ignore @code{@@node} lines altogether in your first
4697 draft and then use the @code{texinfo-insert-node-lines} command to
4698 create @code{@@node} lines for you. However, we do not recommend this
4699 practice. It is better to name the node itself at the same time that
4700 you write a segment so you can easily make cross references. A large
4701 number of cross references are an especially important feature of a good
4704 After you have inserted an @code{@@node} line, you should immediately
4705 write an @@-command for the chapter or section and insert its name.
4706 Next (and this is important!), put in several index entries. Usually,
4707 you will find at least two and often as many as four or five ways of
4708 referring to the node in the index. Use them all. This will make it
4709 much easier for people to find the node.
4712 @node Node Line Tips
4713 @subsection @code{@@node} Line Tips
4715 Here are three suggestions:
4719 Try to pick node names that are informative but short.@refill
4721 In the Info file, the file name, node name, and pointer names are all
4722 inserted on one line, which may run into the right edge of the window.
4723 (This does not cause a problem with Info, but is ugly.)@refill
4726 Try to pick node names that differ from each other near the beginnings
4727 of their names. This way, it is easy to use automatic name completion in
4731 By convention, node names are capitalized just as they would be for
4732 section or chapter titles---initial and significant words are
4733 capitalized; others are not.@refill
4737 @node Node Line Requirements, First Node, Node Line Tips, node
4738 @subsection @code{@@node} Line Requirements
4740 @cindex Node line requirements
4741 Here are several requirements for @code{@@node} lines:
4744 @cindex Unique nodename requirement
4745 @cindex Node name must be unique
4747 All the node names for a single Info file must be unique.@refill
4749 Duplicates confuse the Info movement commands. This means, for
4750 example, that if you end every chapter with a summary, you must name
4751 each summary node differently. You cannot just call each one
4752 ``Summary''. You may, however, duplicate the titles of chapters, sections,
4753 and the like. Thus you can end each chapter in a book with a section
4754 called ``Summary'', so long as the node names for those sections are all
4758 A pointer name must be the name of a node.@refill
4760 The node to which a pointer points may come before or after the
4761 node containing the pointer.
4763 @cindex @@-commands in nodename
4764 @cindex Node name, should not contain @@-commands
4766 @w{@@-commands} used in node names generally confuse Info, so you should
4767 avoid them. For a few rare cases when this is useful, Texinfo has
4768 limited support for using @w{@@-commands} in node names; see
4769 @ref{Pointer Validation}.
4772 Thus, the beginning of the section called @code{@@chapter} looks like
4777 @@node chapter, unnumbered & appendix, makeinfo top, Structuring
4778 @@comment node-name, next, previous, up
4779 @@section @@code@{@@@@chapter@}
4785 @cindex Apostrophe in nodename
4786 @cindex Colon in nodename
4787 @cindex Comma in nodename
4788 @cindex Period in nodename
4789 @cindex Characters, invalid in node name
4790 @cindex Invalid characters in node names
4791 Unfortunately, you cannot use periods, commas, colons or apostrophes
4792 within a node name; these confuse @TeX{} or the Info formatters.@refill
4795 For example, the following is a section title:
4798 @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
4802 The corresponding node name is:
4805 unnumberedsec appendixsec heading
4808 @cindex Case in nodename
4810 Case is significant.
4814 @node First Node, makeinfo top command, Node Line Requirements, node
4815 @comment node-name, next, previous, up
4816 @subsection The First Node
4817 @cindex Top node is first
4820 The first node of a Texinfo file is the @dfn{Top} node, except in an
4821 included file (@pxref{Include Files}). The Top node contains the main
4822 or master menu for the document, and a short summary of the document
4823 (@pxref{Top Node Summary}).
4825 @cindex Up node of Top node
4826 @cindex (dir) as Up node of Top node
4827 The Top node (which must be named @samp{top} or @samp{Top}) should have
4828 as its `Up' node the name of a node in another file, where there is a
4829 menu that leads to this file. Specify the file name in parentheses. If
4830 the file is to be installed directly in the Info directory file, use
4831 @samp{(dir)} as the parent of the Top node; this is short for
4832 @samp{(dir)top}, and specifies the Top node in the @file{dir} file,
4833 which contains the main menu for the Info system as a whole. For
4834 example, the @code{@@node Top} line of this manual looks like this:
4837 @@node Top, Copying, , (dir)
4841 (You can use the Texinfo updating commands or the @code{makeinfo}
4842 utility to insert these pointers automatically.)
4844 @cindex Previous node of Top node
4845 Do not define the `Previous' node of the Top node to be @samp{(dir)}, as
4846 it causes confusing behavior for users: if you are in the Top node and
4847 hits @key{DEL} to go backwards, you wind up in the middle of the
4848 some other entry in the @file{dir} file, which has nothing to do with
4849 what you were reading.
4851 @xref{Install an Info File}, for more information about installing
4852 an Info file in the @file{info} directory.
4855 @node makeinfo top command, Top Node Summary, First Node, node
4856 @comment node-name, next, previous, up
4857 @subsection The @code{@@top} Sectioning Command
4858 @findex top @r{(@@-command)}
4860 A special sectioning command, @code{@@top}, has been created for use
4861 with the @code{@@node Top} line. The @code{@@top} sectioning command tells
4862 @code{makeinfo} that it marks the `Top' node in the file. It provides
4863 the information that @code{makeinfo} needs to insert node
4864 pointers automatically. Write the @code{@@top} command at the
4865 beginning of the line immediately following the @code{@@node Top}
4866 line. Write the title on the remaining part of the same line as the
4867 @code{@@top} command.@refill
4869 In Info, the @code{@@top} sectioning command causes the title to appear on a
4870 line by itself, with a line of asterisks inserted underneath.@refill
4872 In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4873 sectioning command is merely a synonym for @code{@@unnumbered}.
4874 Neither of these formatters require an @code{@@top} command, and do
4875 nothing special with it. You can use @code{@@chapter} or
4876 @code{@@unnumbered} after the @code{@@node Top} line when you use
4877 these formatters. Also, you can use @code{@@chapter} or
4878 @code{@@unnumbered} when you use the Texinfo updating commands to
4879 create or update pointers and menus.@refill
4882 @node Top Node Summary, , makeinfo top command, node
4883 @subsection The `Top' Node Summary
4884 @cindex @samp{@r{Top}} node summary
4886 You can help readers by writing a summary in the `Top' node, after the
4887 @code{@@top} line, before the main or master menu. The summary should
4888 briefly describe the document. In Info, this summary will appear just
4889 before the master menu. In a printed manual, this summary will appear
4890 on a page of its own.@refill
4892 If you do not want the summary to appear on a page of its own in a
4893 printed manual, you can enclose the whole of the `Top' node, including
4894 the @code{@@node Top} line and the @code{@@top} sectioning command line
4895 or other sectioning command line between @code{@@ifinfo} and @code{@@end
4896 ifinfo}. This prevents any of the text from appearing in the printed
4897 output. (@pxref{Conditionals, , Conditionally Visible Text}). You can
4898 repeat the brief description from the `Top' node within @code{@@iftex}
4899 @dots{} @code{@@end iftex} at the beginning of the first chapter, for
4900 those who read the printed manual. This saves paper and may look
4903 You should write the version number of the program to which the manual
4904 applies in the summary. This helps the reader keep track of which
4905 manual is for which version of the program. If the manual changes more
4906 frequently than the program or is independent of it, you should also
4907 include an edition number for the manual. (The title page should also
4908 contain this information: see @ref{titlepage, ,
4909 @code{@@titlepage}}.)@refill
4911 @node makeinfo Pointer Creation
4912 @section Creating Pointers with @code{makeinfo}
4913 @cindex Creating pointers with @code{makeinfo}
4914 @cindex Pointer creation with @code{makeinfo}
4915 @cindex Automatic pointer creation with @code{makeinfo}
4917 The @code{makeinfo} program has a feature for automatically defining
4918 node pointers for a hierarchically organized file.
4920 When you take advantage of this feature, you do not need to write the
4921 `Next', `Previous', and `Up' pointers after the name of a node.
4922 However, you must write a sectioning command, such as @code{@@chapter}
4923 or @code{@@section}, on the line immediately following each truncated
4924 @code{@@node} line (except that comment lines may intervene).
4926 In addition, you must follow the `Top' @code{@@node} line with a line
4927 beginning with @code{@@top} to mark the `Top' node in the
4928 file. @xref{makeinfo top, , @code{@@top}}.
4930 Finally, you must write the name of each node (except for the `Top'
4931 node) in a menu that is one or more hierarchical levels above the
4932 node's hierarchical level.
4934 This node pointer insertion feature in @code{makeinfo} relieves you from
4935 the need to update menus and pointers manually or with Texinfo mode
4936 commands. (@xref{Updating Nodes and Menus}.)
4940 @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
4944 @cindex Cross-reference targets, arbitrary
4945 @cindex Targets for cross-references, arbitrary
4947 An @dfn{anchor} is a position in your document, labeled so that
4948 cross-references can refer to it, just as they can to nodes. You create
4949 an anchor with the @code{@@anchor} command, and give the label as a
4950 normal brace-delimited argument. For example:
4953 This marks the @@anchor@{x-spot@}spot.
4955 @@xref@{x-spot,,the spot@}.
4961 This marks the spot.
4963 See [the spot], page 1.
4966 As you can see, the @code{@@anchor} command itself produces no output.
4967 This example defines an anchor `x-spot' just before the word `spot'.
4968 You can refer to it later with an @code{@@xref} or other cross-reference
4969 command, as shown. @xref{Cross References}, for details on the
4970 cross-reference commands.
4972 It is best to put @code{@@anchor} commands just before the position you
4973 wish to refer to; that way, the reader's eye is led on to the correct
4974 text when they jump to the anchor. You can put the @code{@@anchor}
4975 command on a line by itself if that helps readability of the source.
4976 Spaces are always ignored after @code{@@anchor}.
4978 Anchor names and node names may not conflict. Anchors and nodes are
4979 given similar treatment in some ways; for example, the @code{goto-node}
4980 command in standalone Info takes either an anchor name or a node name as
4981 an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
4989 @dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can
4990 carry you to any node, regardless of the hierarchical structure; even to
4991 nodes in a different Info file. However, the GNU Emacs Texinfo mode
4992 updating commands work only to create menus of subordinate nodes.
4993 Conventionally, cross references are used to refer to other nodes.} In
4994 Info, you use menus to go to such nodes. Menus have no effect in
4995 printed manuals and do not appear in them.
4997 By convention, a menu is put at the end of a node since a reader who
4998 uses the menu may not see text that follows it. Furthermore, a node
4999 that has a menu should not contain much text. If you have a lot of text
5000 and a menu, move most of the text into a new subnode---all but a few
5001 lines. Otherwise, a reader with a terminal that displays only a few
5002 lines may miss the menu and its associated text. As a practical matter,
5003 you should locate a menu within 20 lines of the beginning of the
5007 * Menu Location:: Put a menu in a short node.
5008 * Writing a Menu:: What is a menu?
5009 * Menu Parts:: A menu entry has three parts.
5010 * Less Cluttered Menu Entry:: Two part menu entry.
5011 * Menu Example:: Two and three part menu entries.
5012 * Other Info Files:: How to refer to a different Info file.
5016 @node Menu Location, Writing a Menu, Menus, Menus
5018 @heading Menus Need Short Nodes
5020 @cindex Menu location
5021 @cindex Location of menus
5022 @cindex Nodes for menus are short
5023 @cindex Short nodes for menus
5025 The short text before a menu may look awkward in a printed manual. To
5026 avoid this, you can write a menu near the beginning of its node and
5027 follow the menu by an @code{@@node} line, and then an @code{@@heading}
5028 line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
5029 the menu, @code{@@node} line, and title appear only in the Info file,
5030 not the printed document.@refill
5032 For example, the preceding two paragraphs follow an Info-only menu,
5033 @code{@@node} line, and heading, and look like this:@refill
5038 * Menu Location:: Put a menu in a short node.
5039 * Writing a Menu:: What is a menu?
5040 * Menu Parts:: A menu entry has three parts.
5041 * Less Cluttered Menu Entry:: Two part menu entry.
5042 * Menu Example:: Two and three part entries.
5043 * Other Info Files:: How to refer to a different
5047 @@node Menu Location, Writing a Menu, , Menus
5049 @@heading Menus Need Short Nodes
5054 The Texinfo file for this document contains more than a dozen
5055 examples of this procedure. One is at the beginning of this chapter;
5056 another is at the beginning of @ref{Cross References}. @refill
5059 @node Writing a Menu, Menu Parts, Menu Location, Menus
5060 @section Writing a Menu
5061 @cindex Writing a menu
5062 @cindex Menu writing
5064 A menu consists of an @code{@@menu} command on a line by
5065 itself followed by menu entry lines or menu comment lines
5066 and then by an @code{@@end menu} command on a line by
5069 A menu looks like this:@refill
5074 Larger Units of Text
5076 * Files:: All about handling files.
5077 * Multiples: Buffers. Multiple buffers; editing
5078 several files at once.
5083 In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
5084 entry}. (Note the space after the asterisk.) A line that does not
5085 start with an @w{@samp{* }} may also appear in a menu. Such a line is
5086 not a menu entry but is a menu comment line that appears in the Info
5087 file. In the example above, the line @samp{Larger Units of Text} is a
5088 menu comment line; the two lines starting with @w{@samp{* }} are menu
5089 @cindex Spaces, in menus
5090 entries. Space characters in a menu are preserved as-is; this allows
5091 you to format the menu as you wish.
5094 @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
5095 @section The Parts of a Menu
5096 @cindex Parts of a menu
5098 @cindex @code{@@menu} parts
5100 A menu entry has three parts, only the second of which is required:
5104 The menu entry name (optional).
5107 The name of the node (required).
5110 A description of the item (optional).
5113 The template for a menu entry looks like this:@refill
5116 * @var{menu-entry-name}: @var{node-name}. @var{description}
5119 Follow the menu entry name with a single colon and follow the node name
5120 with tab, comma, period, or newline.@refill
5122 In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5123 command. The menu entry name is what the user types after the @kbd{m}
5126 The third part of a menu entry is a descriptive phrase or sentence.
5127 Menu entry names and node names are often short; the description
5128 explains to the reader what the node is about. A useful description
5129 complements the node name rather than repeats it. The description,
5130 which is optional, can spread over two or more lines; if it does, some
5131 authors prefer to indent the second line while others prefer to align it
5132 with the first (and all others). It's up to you.
5135 @node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
5136 @comment node-name, next, previous, up
5137 @section Less Cluttered Menu Entry
5138 @cindex Two part menu entry
5139 @cindex Double-colon menu entries
5140 @cindex Menu entries with two colons
5141 @cindex Less cluttered menu entry
5142 @cindex Uncluttered menu entry
5144 When the menu entry name and node name are the same, you can write
5145 the name immediately after the asterisk and space at the beginning of
5146 the line and follow the name with two colons.@refill
5152 * Name:: @var{description}
5160 * Name: Name. @var{description}
5163 You should use the node name for the menu entry name whenever possible,
5164 since it reduces visual clutter in the menu.@refill
5166 @node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
5167 @comment node-name, next, previous, up
5168 @section A Menu Example
5169 @cindex Menu example
5170 @cindex Example menu
5172 A menu looks like this in Texinfo:@refill
5177 * menu entry name: Node name. A short description.
5178 * Node name:: This form is preferred.
5191 * menu entry name: Node name. A short description.
5192 * Node name:: This form is preferred.
5197 Here is an example as you might see it in a Texinfo file:@refill
5202 Larger Units of Text
5204 * Files:: All about handling files.
5205 * Multiples: Buffers. Multiple buffers; editing
5206 several files at once.
5218 Larger Units of Text
5220 * Files:: All about handling files.
5221 * Multiples: Buffers. Multiple buffers; editing
5222 several files at once.
5226 In this example, the menu has two entries. @samp{Files} is both a menu
5227 entry name and the name of the node referred to by that name.
5228 @samp{Multiples} is the menu entry name; it refers to the node named
5229 @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5230 appears in the menu, but is not an entry.@refill
5232 Since no file name is specified with either @samp{Files} or
5233 @samp{Buffers}, they must be the names of nodes in the same Info file
5234 (@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5236 @node Other Info Files, , Menu Example, Menus
5237 @comment node-name, next, previous, up
5238 @section Referring to Other Info Files
5239 @cindex Referring to other Info files
5240 @cindex Nodes in other Info files
5241 @cindex Other Info files' nodes
5242 @cindex Going to other Info files' nodes
5243 @cindex Info; other files' nodes
5245 You can create a menu entry that enables a reader in Info to go to a
5246 node in another Info file by writing the file name in parentheses just
5247 before the node name. In this case, you should use the three-part menu
5248 entry format, which saves the reader from having to type the file
5252 The format looks like this:@refill
5257 * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
5258 * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5263 For example, to refer directly to the @samp{Outlining} and
5264 @samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
5265 menu like this:@refill
5270 * Outlining: (emacs)Outline Mode. The major mode for
5272 * Rebinding: (emacs)Rebinding. How to redefine the
5278 If you do not list the node name, but only name the file, then Info
5279 presumes that you are referring to the `Top' node.@refill
5281 The @file{dir} file that contains the main menu for Info has menu
5282 entries that list only file names. These take you directly to the `Top'
5283 nodes of each Info document. (@xref{Install an Info File}.)@refill
5290 * Info: (info). Documentation browsing system.
5291 * Emacs: (emacs). The extensible, self-documenting
5297 (The @file{dir} top level directory for the Info system is an Info file,
5298 not a Texinfo file, but a menu entry looks the same in both types of
5301 The GNU Emacs Texinfo mode menu updating commands only work with nodes
5302 within the current buffer, so you cannot use them to create menus that
5303 refer to other files. You must write such menus by hand.
5306 @node Cross References
5307 @chapter Cross References
5308 @cindex Making cross references
5309 @cindex Cross references
5312 @dfn{Cross references} are used to refer the reader to other parts of the
5313 same or different Texinfo files. In Texinfo, nodes and anchors are the
5314 places to which cross references can refer.
5317 * References:: What cross references are for.
5318 * Cross Reference Commands:: A summary of the different commands.
5319 * Cross Reference Parts:: A cross reference has several parts.
5320 * xref:: Begin a reference with `See' @dots{}
5321 * Top Node Naming:: How to refer to the beginning of another file.
5322 * ref:: A reference for the last part of a sentence.
5323 * pxref:: How to write a parenthetical cross reference.
5324 * inforef:: How to refer to an Info-only file.
5325 * uref:: How to refer to a uniform resource locator.
5328 @node References, Cross Reference Commands, Cross References, Cross References
5330 @heading What References Are For
5333 Often, but not always, a printed document should be designed so that
5334 it can be read sequentially. People tire of flipping back and forth
5335 to find information that should be presented to them as they need
5338 However, in any document, some information will be too detailed for
5339 the current context, or incidental to it; use cross references to
5340 provide access to such information. Also, an online help system or a
5341 reference manual is not like a novel; few read such documents in
5342 sequence from beginning to end. Instead, people look up what they
5343 need. For this reason, such creations should contain many cross
5344 references to help readers find other information that they may not
5347 In a printed manual, a cross reference results in a page reference,
5348 unless it is to another manual altogether, in which case the cross
5349 reference names that manual.@refill
5351 In Info, a cross reference results in an entry that you can follow using
5352 the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
5353 commands, info}.)@refill
5355 The various cross reference commands use nodes (or anchors,
5356 @pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
5357 This is evident in Info, in which a cross reference takes you to the
5358 specified location. @TeX{} also uses nodes to define cross reference
5359 locations, but the action is less obvious. When @TeX{} generates a DVI
5360 file, it records each node's page number and uses the page numbers in making
5361 references. Thus, if you are writing a manual that will only be
5362 printed, and will not be used online, you must nonetheless write
5363 @code{@@node} lines to name the places to which you make cross
5367 @node Cross Reference Commands, Cross Reference Parts, References, Cross References
5368 @comment node-name, next, previous, up
5369 @section Different Cross Reference Commands
5370 @cindex Different cross reference commands
5372 There are four different cross reference commands:@refill
5376 Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5377 or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5380 Used within or, more often, at the end of a sentence; same as
5381 @code{@@xref} for Info; produces just the reference in the printed
5382 manual without a preceding `See'.@refill
5385 Used within parentheses to make a reference that suits both an Info
5386 file and a printed book. Starts with a lower case `see' within the
5387 printed manual. (@samp{p} is for `parenthesis'.)@refill
5390 Used to make a reference to an Info file for which there is no printed
5395 (The @code{@@cite} command is used to make references to books and
5396 manuals for which there is no corresponding Info file and, therefore,
5397 no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
5399 @node Cross Reference Parts, xref, Cross Reference Commands, Cross References
5400 @comment node-name, next, previous, up
5401 @section Parts of a Cross Reference
5402 @cindex Cross reference parts
5403 @cindex Parts of a cross reference
5405 A cross reference command requires only one argument, which is the
5406 name of the node to which it refers. But a cross reference command
5407 may contain up to four additional arguments. By using these
5408 arguments, you can provide a cross reference name for Info, a topic
5409 description or section title for the printed output, the name of a
5410 different Info file, and the name of a different printed
5413 Here is a simple cross reference example:@refill
5416 @@xref@{Node name@}.
5430 See Section @var{nnn} [Node name], page @var{ppp}.
5434 Here is an example of a full five-part cross reference:@refill
5438 @@xref@{Node name, Cross Reference Name, Particular Topic,
5439 info-file-name, A Printed Manual@}, for details.
5447 *Note Cross Reference Name: (info-file-name)Node name,
5455 See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5461 The five possible arguments for a cross reference are:@refill
5465 The node or anchor name (required). This is the location to which the
5466 cross reference takes you. In a printed document, the location of the
5467 node provides the page reference only for references within the same
5471 The cross reference name for the Info reference, if it is to be different
5472 from the node name. If you include this argument, it becomes
5473 the first part of the cross reference. It is usually omitted.@refill
5476 A topic description or section name. Often, this is the title of the
5477 section. This is used as the name of the reference in the printed
5478 manual. If omitted, the node name is used.@refill
5481 The name of the Info file in which the reference is located, if it is
5482 different from the current file. You need not include any @samp{.info}
5483 suffix on the file name, since Info readers try appending it
5487 The name of a printed manual from a different Texinfo file.@refill
5490 The template for a full five argument cross reference looks like
5495 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5496 @var{info-file-name}, @var{printed-manual-title}@}.
5500 Cross references with one, two, three, four, and five arguments are
5501 described separately following the description of @code{@@xref}.@refill
5503 Write a node name in a cross reference in exactly the same way as in
5504 the @code{@@node} line, including the same capitalization; otherwise, the
5505 formatters may not find the reference.@refill
5507 You can write cross reference commands within a paragraph, but note
5508 how Info and @TeX{} format the output of each of the various commands:
5509 write @code{@@xref} at the beginning of a sentence; write
5510 @code{@@pxref} only within parentheses, and so on.@refill
5512 @node xref, Top Node Naming, Cross Reference Parts, Cross References
5513 @comment node-name, next, previous, up
5514 @section @code{@@xref}
5516 @cindex Cross references using @code{@@xref}
5517 @cindex References using @code{@@xref}
5519 The @code{@@xref} command generates a cross reference for the
5520 beginning of a sentence. The Info formatting commands convert it into
5521 an Info cross reference, which the Info @samp{f} command can use to
5522 bring you directly to another node. The @TeX{} typesetting commands
5523 convert it into a page reference, or a reference to another book or
5527 * Reference Syntax:: What a reference looks like and requires.
5528 * One Argument:: @code{@@xref} with one argument.
5529 * Two Arguments:: @code{@@xref} with two arguments.
5530 * Three Arguments:: @code{@@xref} with three arguments.
5531 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
5534 @node Reference Syntax, One Argument, xref, xref
5536 @subheading What a Reference Looks Like and Requires
5539 Most often, an Info cross reference looks like this:@refill
5542 *Note @var{node-name}::.
5549 *Note @var{cross-reference-name}: @var{node-name}.
5553 In @TeX{}, a cross reference looks like this:
5556 See Section @var{section-number} [@var{node-name}], page @var{page}.
5563 See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5566 The @code{@@xref} command does not generate a period or comma to end
5567 the cross reference in either the Info file or the printed output.
5568 You must write that period or comma yourself; otherwise, Info will not
5569 recognize the end of the reference. (The @code{@@pxref} command works
5570 differently. @xref{pxref, , @code{@@pxref}}.)@refill
5573 @strong{Please note:} A period or comma @strong{must} follow the closing
5574 brace of an @code{@@xref}. It is required to terminate the cross
5575 reference. This period or comma will appear in the output, both in
5576 the Info file and in the printed manual.@refill
5579 @code{@@xref} must refer to an Info node by name. Use @code{@@node}
5580 to define the node (@pxref{Writing a Node}).@refill
5582 @code{@@xref} is followed by several arguments inside braces, separated by
5583 commas. Whitespace before and after these commas is ignored.@refill
5585 A cross reference requires only the name of a node; but it may contain
5586 up to four additional arguments. Each of these variations produces a
5587 cross reference that looks somewhat different.@refill
5590 @strong{Please note:} Commas separate arguments in a cross reference;
5591 avoid including them in the title or other part lest the formatters
5592 mistake them for separators.@refill
5595 @node One Argument, Two Arguments, Reference Syntax, xref
5596 @subsection @code{@@xref} with One Argument
5598 The simplest form of @code{@@xref} takes one argument, the name of
5599 another node in the same Info file. The Info formatters produce
5600 output that the Info readers can use to jump to the reference; @TeX{}
5601 produces output that specifies the page and section number for you.@refill
5608 @@xref@{Tropical Storms@}.
5615 *Note Tropical Storms::.
5622 See Section 3.1 [Tropical Storms], page 24.
5626 (Note that in the preceding example the closing brace is followed by a
5629 You can write a clause after the cross reference, like this:@refill
5632 @@xref@{Tropical Storms@}, for more info.
5639 *Note Tropical Storms::, for more info.
5646 See Section 3.1 [Tropical Storms], page 24, for more info.
5650 (Note that in the preceding example the closing brace is followed by a
5651 comma, and then by the clause, which is followed by a period.)@refill
5653 @node Two Arguments, Three Arguments, One Argument, xref
5654 @subsection @code{@@xref} with Two Arguments
5656 With two arguments, the second is used as the name of the Info cross
5657 reference, while the first is still the name of the node to which the
5658 cross reference points.@refill
5662 The template is like this:
5665 @@xref@{@var{node-name}, @var{cross-reference-name}@}.
5673 @@xref@{Electrical Effects, Lightning@}.
5680 *Note Lightning: Electrical Effects.
5687 See Section 5.2 [Electrical Effects], page 57.
5691 (Note that in the preceding example the closing brace is followed by a
5692 period; and that the node name is printed, not the cross reference name.)
5694 You can write a clause after the cross reference, like this:@refill
5697 @@xref@{Electrical Effects, Lightning@}, for more info.
5703 *Note Lightning: Electrical Effects, for more info.
5710 See Section 5.2 [Electrical Effects], page 57, for more info.
5714 (Note that in the preceding example the closing brace is followed by a
5715 comma, and then by the clause, which is followed by a period.)@refill
5717 @node Three Arguments, Four and Five Arguments, Two Arguments, xref
5718 @subsection @code{@@xref} with Three Arguments
5720 A third argument replaces the node name in the @TeX{} output. The third
5721 argument should be the name of the section in the printed output, or
5722 else state the topic discussed by that section. Often, you will want to
5723 use initial upper case letters so it will be easier to read when the
5724 reference is printed. Use a third argument when the node name is
5725 unsuitable because of syntax or meaning.@refill
5727 Remember to avoid placing a comma within the title or topic section of
5728 a cross reference, or within any other section. The formatters divide
5729 cross references into arguments according to the commas; a comma
5730 within a title or other section will divide it into two arguments. In
5731 a reference, you need to write a title such as ``Clouds, Mist, and
5732 Fog'' without the commas.@refill
5734 Also, remember to write a comma or period after the closing brace of an
5735 @code{@@xref} to terminate the cross reference. In the following
5736 examples, a clause follows a terminating comma.@refill
5741 The template is like this:
5745 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
5755 @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
5764 *Note Lightning: Electrical Effects, for details.
5771 See Section 5.2 [Thunder and Lightning], page 57, for details.
5774 If a third argument is given and the second one is empty, then the
5775 third argument serves both. (Note how two commas, side by side, mark
5776 the empty second argument.)@refill
5780 @@xref@{Electrical Effects, , Thunder and Lightning@},
5789 *Note Thunder and Lightning: Electrical Effects, for details.
5796 See Section 5.2 [Thunder and Lightning], page 57, for details.
5799 As a practical matter, it is often best to write cross references with
5800 just the first argument if the node name and the section title are the
5801 same, and with the first and third arguments if the node name and title
5802 are different.@refill
5804 Here are several examples from @cite{The GNU Awk User's Guide}:@refill
5807 @@xref@{Sample Program@}.
5809 @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
5810 @@xref@{Close Output, , Closing Output Files and Pipes@},
5811 for more information.
5812 @@xref@{Regexp, , Regular Expressions as Patterns@}.
5815 @node Four and Five Arguments, , Three Arguments, xref
5816 @subsection @code{@@xref} with Four and Five Arguments
5818 In a cross reference, a fourth argument specifies the name of another
5819 Info file, different from the file in which the reference appears, and
5820 a fifth argument specifies its title as a printed manual.@refill
5822 Remember that a comma or period must follow the closing brace of an
5823 @code{@@xref} command to terminate the cross reference. In the
5824 following examples, a clause follows a terminating comma.@refill
5832 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5833 @var{info-file-name}, @var{printed-manual-title}@}.
5842 @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
5843 weather, An Introduction to Meteorology@}, for details.
5850 *Note Lightning: (weather)Electrical Effects, for details.
5854 The name of the Info file is enclosed in parentheses and precedes
5855 the name of the node.
5858 In a printed manual, the reference looks like this:@refill
5861 See section ``Thunder and Lightning'' in @i{An Introduction to
5862 Meteorology}, for details.
5866 The title of the printed manual is typeset in italics; and the
5867 reference lacks a page number since @TeX{} cannot know to which page a
5868 reference refers when that reference is to another manual.@refill
5870 Often, you will leave out the second argument when you use the long
5871 version of @code{@@xref}. In this case, the third argument, the topic
5872 description, will be used as the cross reference name in Info.@refill
5875 The template looks like this:
5878 @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
5879 @var{printed-manual-title}@}, for details.
5886 *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
5893 See section @var{title-or-topic} in @var{printed-manual-title}, for details.
5901 @@xref@{Electrical Effects, , Thunder and Lightning,
5902 weather, An Introduction to Meteorology@}, for details.
5910 *Note Thunder and Lightning: (weather)Electrical Effects,
5919 See section ``Thunder and Lightning'' in @i{An Introduction to
5920 Meteorology}, for details.
5923 On rare occasions, you may want to refer to another Info file that
5924 is within a single printed manual---when multiple Texinfo files are
5925 incorporated into the same @TeX{} run but make separate Info files.
5926 In this case, you need to specify only the fourth argument, and not
5929 @node Top Node Naming, ref, xref, Cross References
5930 @section Naming a `Top' Node
5931 @cindex Naming a `Top' Node in references
5932 @cindex @samp{@r{Top}} node naming for references
5934 In a cross reference, you must always name a node. This means that in
5935 order to refer to a whole manual, you must identify the `Top' node by
5936 writing it as the first argument to the @code{@@xref} command. (This
5937 is different from the way you write a menu entry; see @ref{Other Info
5938 Files, , Referring to Other Info Files}.) At the same time, to
5939 provide a meaningful section topic or title in the printed cross
5940 reference (instead of the word `Top'), you must write an appropriate
5941 entry for the third argument to the @code{@@xref} command.
5945 Thus, to make a cross reference to @cite{The GNU Make Manual},
5949 @@xref@{Top, , Overview, make, The GNU Make Manual@}.
5956 *Note Overview: (make)Top.
5963 See section ``Overview'' in @i{The GNU Make Manual}.
5967 In this example, @samp{Top} is the name of the first node, and
5968 @samp{Overview} is the name of the first section of the manual.@refill
5969 @node ref, pxref, Top Node Naming, Cross References
5970 @comment node-name, next, previous, up
5971 @section @code{@@ref}
5972 @cindex Cross references using @code{@@ref}
5973 @cindex References using @code{@@ref}
5976 @code{@@ref} is nearly the same as @code{@@xref} except that it does
5977 not generate a `See' in the printed output, just the reference itself.
5978 This makes it useful as the last part of a sentence.@refill
5986 For more information, see @@ref@{Hurricanes@}.
5993 For more information, see *Note Hurricanes::.
6000 For more information, see Section 8.2 [Hurricanes], page 123.
6003 The @code{@@ref} command sometimes leads writers to express themselves
6004 in a manner that is suitable for a printed manual but looks awkward
6005 in the Info format. Bear in mind that your audience will be using
6006 both the printed and the Info format.@refill
6015 Sea surges are described in @@ref@{Hurricanes@}.
6024 Sea surges are described in Section 6.7 [Hurricanes], page 72.
6029 in a printed document, and the following in Info:
6032 Sea surges are described in *Note Hurricanes::.
6036 @strong{Caution:} You @emph{must} write a period, comma, or right
6037 parenthesis immediately after an @code{@@ref} command with two or more
6038 arguments. Otherwise, Info will not find the end of the cross reference
6039 entry and its attempt to follow the cross reference will fail. As a
6040 general rule, you should write a period or comma after every
6041 @code{@@ref} command. This looks best in both the printed and the Info
6045 @node pxref, inforef, ref, Cross References
6046 @comment node-name, next, previous, up
6047 @section @code{@@pxref}
6048 @cindex Cross references using @code{@@pxref}
6049 @cindex References using @code{@@pxref}
6052 The parenthetical reference command, @code{@@pxref}, is nearly the
6053 same as @code{@@xref}, but you use it @emph{only} inside parentheses
6054 and you do @emph{not} type a comma or period after the command's
6055 closing brace. The command differs from @code{@@xref} in two
6060 @TeX{} typesets the reference for the printed manual with a lower case
6061 `see' rather than an upper case `See'.@refill
6064 The Info formatting commands automatically end the reference with a
6065 closing colon or period.@refill
6068 Because one type of formatting automatically inserts closing
6069 punctuation and the other does not, you should use @code{@@pxref}
6070 @emph{only} inside parentheses as part of another sentence. Also, you
6071 yourself should not insert punctuation after the reference, as you do
6072 with @code{@@xref}.@refill
6074 @code{@@pxref} is designed so that the output looks right and works
6075 right between parentheses both in printed output and in an Info file.
6076 In a printed manual, a closing comma or period should not follow a
6077 cross reference within parentheses; such punctuation is wrong. But in
6078 an Info file, suitable closing punctuation must follow the cross
6079 reference so Info can recognize its end. @code{@@pxref} spares you
6080 the need to use complicated methods to put a terminator into one form
6081 of the output and not the other.@refill
6084 With one argument, a parenthetical cross reference looks like
6089 @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
6098 @dots{} storms cause flooding (*Note Hurricanes::) @dots{}
6106 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
6109 With two arguments, a parenthetical cross reference has this
6113 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6120 @dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
6128 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6131 @code{@@pxref} can be used with up to five arguments just like
6132 @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
6135 @strong{Please note:} Use @code{@@pxref} only as a parenthetical
6136 reference. Do not try to use @code{@@pxref} as a clause in a sentence.
6137 It will look bad in either the Info file, the printed output, or
6140 Also, parenthetical cross references look best at the ends of sentences.
6141 Although you may write them in the middle of a sentence, that location
6142 breaks up the flow of text.@refill
6145 @node inforef, uref, pxref, Cross References
6146 @section @code{@@inforef}
6147 @cindex Cross references using @code{@@inforef}
6148 @cindex References using @code{@@inforef}
6151 @code{@@inforef} is used for cross references to Info files for which
6152 there are no printed manuals. Even in a printed manual,
6153 @code{@@inforef} generates a reference directing the user to look in
6154 an Info file.@refill
6156 The command takes either two or three arguments, in the following
6164 The cross reference name (optional).
6171 Separate the arguments with commas, as with @code{@@xref}. Also, you
6172 must terminate the reference with a comma or period after the
6173 @samp{@}}, as you do with @code{@@xref}.@refill
6179 @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6188 @@inforef@{Expert, Advanced Info commands, info@},
6189 for more information.
6199 *Note Advanced Info commands: (info)Expert,
6200 for more information.
6209 See Info file @file{info}, node @samp{Expert}, for more information.
6218 @@inforef@{Expert, , info@}, for more information.
6227 *Note (info)Expert::, for more information.
6235 See Info file @file{info}, node @samp{Expert}, for more information.
6238 The converse of @code{@@inforef} is @code{@@cite}, which is used to
6239 refer to printed works for which no Info form exists. @xref{cite, ,
6240 @code{@@cite}}.@refill
6244 @section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
6246 @cindex Uniform resource locator, referring to
6247 @cindex URL, referring to
6249 @cindex @code{href}, producing HTML
6250 @code{@@uref} produces a reference to a uniform resource locator (url).
6251 It takes one mandatory argument, the url, and two optional arguments
6252 which control the text that is displayed. In HTML output, @code{@@uref}
6253 produces a link you can follow.
6255 The second argument, if specified, is the text to display (the default
6256 is the url itself); in Info and DVI output, but not in HTML output, the
6259 @cindex Man page, reference to
6260 The third argument, on the other hand, if specified is also the text to
6261 display, but the url is @emph{not} output in any format. This is useful
6262 when the text is already sufficiently referential, as in a man page. If
6263 the third argument is given, the second argument is ignored.
6265 The simple one argument form, where the url is both the target and the
6269 The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
6274 The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
6278 An example of the two-argument form:
6280 The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} holds
6286 The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} holds
6290 @noindent that is, the Info output is this:
6292 The official GNU ftp site (ftp://ftp.gnu.org/gnu) holds
6296 @noindent and the HTML output is this:
6298 The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> holds
6303 An example of the three-argument form:
6305 The @@uref@{http://example.org/man.cgi/1/ls,,ls(1)@} program @dots{}
6310 The @uref{http://example.org/man.cgi/1/ls,,ls(1)} program @dots{}
6313 @noindent but with HTML:
6315 The <a href="http://example.org/man.cgi/1/ls">ls(1)</a> program @dots{}
6318 To merely indicate a url without creating a link people can follow, use
6319 @code{@@url} (@pxref{url, @code{@@url}}).
6322 Some people prefer to display url's in the unambiguous format:
6325 <URL:http://@var{host}/@var{path}>
6329 @cindex <URL: convention, not used
6330 You can use this form in the input file if you wish. We feel it's not
6331 necessary to clutter up the output with the extra @samp{<URL:} and
6332 @samp{>}, since any software that tries to detect url's in text already
6333 has to detect them without the @samp{<URL:} to be useful.
6337 @chapter Marking Words and Phrases
6338 @cindex Paragraph, marking text within
6339 @cindex Marking words and phrases
6340 @cindex Words and phrases, marking them
6341 @cindex Marking text within a paragraph
6342 @cindex Text, marking up
6344 In Texinfo, you can mark words and phrases in a variety of ways.
6345 The Texinfo formatters use this information to determine how to
6347 You can specify, for example, whether a word or phrase is a
6348 defining occurrence, a metasyntactic variable, or a symbol used in a
6349 program. Also, you can emphasize text, in several different ways.
6352 * Indicating:: How to indicate definitions, files, etc.
6353 * Emphasis:: How to emphasize text.
6356 @node Indicating, Emphasis, Marking Text, Marking Text
6357 @comment node-name, next, previous, up
6358 @section Indicating Definitions, Commands, etc.
6359 @cindex Highlighting text
6360 @cindex Indicating commands, definitions, etc.
6362 Texinfo has commands for indicating just what kind of object a piece of
6363 text refers to. For example, metasyntactic variables are marked by
6364 @code{@@var}, and code by @code{@@code}. Since the pieces of text are
6365 labelled by commands that tell what kind of object they are, it is easy
6366 to change the way the Texinfo formatters prepare such text. (Texinfo is
6367 an @emph{intentional} formatting language rather than a @emph{typesetting}
6368 formatting language.)@refill
6370 For example, in a printed manual,
6371 code is usually illustrated in a typewriter font;
6372 @code{@@code} tells @TeX{} to typeset this text in this font. But it
6373 would be easy to change the way @TeX{} highlights code to use another
6374 font, and this change would not affect how keystroke examples are
6375 highlighted. If straight typesetting commands were used in the body
6376 of the file and you wanted to make a change, you would need to check
6377 every single occurrence to make sure that you were changing code and
6378 not something else that should not be changed.@refill
6381 * Useful Highlighting:: Highlighting provides useful information.
6382 * code:: Indicating program code.
6383 * kbd:: Showing keyboard input.
6384 * key:: Specifying keys.
6385 * samp:: Showing a literal sequence of characters.
6386 * var:: Indicating metasyntactic variables.
6387 * env:: Indicating environment variables.
6388 * file:: Indicating file names.
6389 * command:: Indicating command names.
6390 * option:: Indicating option names.
6391 * dfn:: Specifying definitions.
6392 * cite:: Referring to books not in the Info system.
6393 * acronym:: Indicating acronyms.
6394 * url:: Indicating a World Wide Web reference.
6395 * email:: Indicating an electronic mail address.
6399 @node Useful Highlighting, code, Indicating, Indicating
6401 @subheading Highlighting Commands are Useful
6404 The highlighting commands can be used to extract useful information
6405 from the file, such as lists of functions or file names. It is
6406 possible, for example, to write a program in Emacs Lisp (or a keyboard
6407 macro) to insert an index entry after every paragraph that contains
6408 words or phrases marked by a specified command. You could do this to
6409 construct an index of functions if you had not already made the
6412 The commands serve a variety of purposes:@refill
6415 @item @@code@{@var{sample-code}@}
6416 Indicate text that is a literal example of a piece of a program.@refill
6418 @item @@kbd@{@var{keyboard-characters}@}
6419 Indicate keyboard input.@refill
6421 @item @@key@{@var{key-name}@}
6422 Indicate the conventional name for a key on a keyboard.@refill
6424 @item @@samp@{@var{text}@}
6425 Indicate text that is a literal example of a sequence of characters.@refill
6427 @item @@var@{@var{metasyntactic-variable}@}
6428 Indicate a metasyntactic variable.@refill
6430 @item @@env@{@var{environment-variable}@}
6431 Indicate an environment variable.@refill
6433 @item @@file@{@var{file-name}@}
6434 Indicate the name of a file.@refill
6436 @item @@command@{@var{command-name}@}
6437 Indicate the name of a command.@refill
6439 @item @@option@{@var{option}@}
6440 Indicate a command-line option.@refill
6442 @item @@dfn@{@var{term}@}
6443 Indicate the introductory or defining use of a term.@refill
6445 @item @@cite@{@var{reference}@}
6446 Indicate the name of a book.@refill
6448 @item @@acronym@{@var{acronym}@}
6449 Indicate an acronym.@refill
6451 @item @@url@{@var{uniform-resource-locator}@}
6452 Indicate a uniform resource locator for the World Wide Web.
6454 @item @@email@{@var{email-address}[, @var{displayed-text}]@}
6455 Indicate an electronic mail address.
6458 @item @@ctrl@{@var{ctrl-char}@}
6459 Use for an @sc{ascii} control character.@refill
6465 @subsection @code{@@code}@{@var{sample-code}@}
6468 @cindex Syntactic tokens, indicating
6469 Use the @code{@@code} command to indicate text that is a piece of a
6470 program and which consists of entire syntactic tokens. Enclose the
6473 @cindex Expressions in a program, indicating
6474 @cindex Keywords, indicating
6475 @cindex Reserved words, indicating
6476 Thus, you should use @code{@@code} for an expression in a program, for
6477 the name of a variable or function used in a program, or for a
6478 keyword in a programming language.
6480 Use @code{@@code} for command names in languages that resemble
6481 programming languages, such as Texinfo. For example, @code{@@code} and
6482 @code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
6483 @samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
6485 @cindex Case, not altering in @code{@@code}
6486 It is incorrect to alter the case of a word inside an @code{@@code}
6487 command when it appears at the beginning of a sentence. Most computer
6488 languages are case sensitive. In C, for example, @code{Printf} is
6489 different from the identifier @code{printf}, and most likely is a
6490 misspelling of it. Even in languages which are not case sensitive, it
6491 is confusing to a human reader to see identifiers spelled in different
6492 ways. Pick one spelling and always use that. If you do not want to
6493 start a sentence with a command name written all in lower case, you
6494 should rearrange the sentence.
6496 In the printed manual, @code{@@code} causes @TeX{} to typeset the
6497 argument in a typewriter face. In the Info file, it causes the Info
6498 formatting commands to use single quotation marks around the text.
6504 The function returns @@code@{nil@}.
6508 produces this in the printed manual:
6511 The function returns @code{nil}.
6516 and this in the Info file:
6518 The function returns `nil'.
6522 Here are some cases for which it is preferable not to use @code{@@code}:
6526 For shell command names such as @command{ls} (use @code{@@command}).
6529 For shell options such as @samp{-c} when such options stand alone (use
6533 Also, an entire shell command often looks better if written using
6534 @code{@@samp} rather than @code{@@code}. In this case, the rule is to
6535 choose the more pleasing format.
6538 For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
6541 For a string of characters shorter than a syntactic token. For example,
6542 if you are writing about @samp{goto-ch}, which is just a part of the
6543 name for the @code{goto-char} Emacs Lisp function, you should use
6547 In general, when writing about the characters used in a token; for
6548 example, do not use @code{@@code} when you are explaining what letters
6549 or printable symbols can be used in the names of functions. (Use
6550 @code{@@samp}.) Also, you should not use @code{@@code} to mark text
6551 that is considered input to programs unless the input is written in a
6552 language that is like a programming language. For example, you should
6553 not use @code{@@code} for the keystroke commands of GNU Emacs (use
6554 @code{@@kbd} instead) although you may use @code{@@code} for the names
6555 of the Emacs Lisp functions that the keystroke commands invoke.
6559 Since @code{@@command}, @code{@@option}, and @code{@@env} were
6560 introduced relatively recently, it is acceptable to use @code{@@code} or
6561 @code{@@samp} for command names, options, and environment variables.
6562 The new commands allow you to express the markup more precisely, but
6563 there is no real harm in using the older commands, and of course the
6564 long-standing manuals do so.
6568 @subsection @code{@@kbd}@{@var{keyboard-characters}@}
6570 @cindex Keyboard input
6572 Use the @code{@@kbd} command for characters of input to be typed by
6573 users. For example, to refer to the characters @kbd{M-a},
6581 and to refer to the characters @kbd{M-x shell}, write@refill
6588 @cindex slanted typewriter font, for @code{@@kbd}
6589 The @code{@@kbd} command has the same effect as @code{@@code} in Info,
6590 but by default produces a different font (slanted typewriter instead of
6591 normal typewriter) in the printed manual, so users can distinguish the
6592 characters they are supposed to type from those the computer outputs.
6594 @findex kbdinputstyle
6595 Since the usage of @code{@@kbd} varies from manual to manual, you can
6596 control the font switching with the @code{@@kbdinputstyle} command.
6597 This command has no effect on Info output. Write this command at the
6598 beginning of a line with a single word as an argument, one of the
6600 @vindex distinct@r{, arg to @@kbdinputstyle}
6601 @vindex example@r{, arg to @@kbdinputstyle}
6602 @vindex code@r{, arg to @@kbdinputstyle}
6605 Always use the same font for @code{@@kbd} as @code{@@code}.
6607 Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6608 and similar environments.
6610 (the default) Always use the distinguishing font for @code{@@kbd}.
6613 You can embed another @@-command inside the braces of an @code{@@kbd}
6614 command. Here, for example, is the way to describe a command that
6615 would be described more verbosely as ``press an @samp{r} and then
6616 press the @key{RET} key'':@refill
6619 @@kbd@{r @@key@{RET@}@}
6623 This produces: @kbd{r @key{RET}}
6625 You also use the @code{@@kbd} command if you are spelling out the letters
6626 you type; for example:@refill
6629 To give the @@code@{logout@} command,
6630 type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6637 To give the @code{logout} command,
6638 type the characters @kbd{l o g o u t @key{RET}}.
6641 (Also, this example shows that you can add spaces for clarity. If you
6642 really want to mention a space character as one of the characters of
6643 input, write @kbd{@@key@{SPC@}} for it.)@refill
6646 @node key, samp, kbd, Indicating
6647 @comment node-name, next, previous, up
6648 @subsection @code{@@key}@{@var{key-name}@}
6651 Use the @code{@@key} command for the conventional name for a key on a
6652 keyboard, as in:@refill
6658 You can use the @code{@@key} command within the argument of an
6659 @code{@@kbd} command when the sequence of characters to be typed
6660 includes one or more keys that are described by name.@refill
6663 For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
6666 @@kbd@{C-x @@key@{ESC@}@}
6669 Here is a list of the recommended names for keys:
6670 @cindex Recommended names for keys
6671 @cindex Keys, recommended names
6672 @cindex Names recommended for keys
6673 @cindex Abbreviations for keys
6682 Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
6683 it might be better to call this character @kbd{C-j}.
6702 There are subtleties to handling words like `meta' or `ctrl' that are
6703 names of modifier keys. When mentioning a character in which the
6704 modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
6705 alone; do not use the @code{@@key} command; but when you are referring
6706 to the modifier key in isolation, use the @code{@@key} command. For
6707 example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
6708 @samp{@@key@{META@}} to produce @key{META}.
6710 @c I don't think this is a good explanation.
6711 @c I think it will puzzle readers more than it clarifies matters. -- rms.
6712 @c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
6713 @c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
6714 @c the beginning of the sentence. The @code{@@key@{META@}} key is often in
6715 @c the lower left of the keyboard.''@refill
6717 @node samp, var, key, Indicating
6718 @comment node-name, next, previous, up
6719 @subsection @code{@@samp}@{@var{text}@}
6722 Use the @code{@@samp} command to indicate text that is a literal example
6723 or `sample' of a sequence of characters in a file, string, pattern, etc.
6724 Enclose the text in braces. The argument appears within single
6725 quotation marks in both the Info file and the printed manual; in
6726 addition, it is printed in a fixed-width font.@refill
6729 To match @@samp@{foo@} at the end of the line,
6730 use the regexp @@samp@{foo$@}.
6737 To match @samp{foo} at the end of the line, use the regexp
6741 Any time you are referring to single characters, you should use
6742 @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
6743 Also, you may use @code{@@samp} for entire statements in C and for entire
6744 shell commands---in this case, @code{@@samp} often looks better than
6745 @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
6746 not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
6748 Only include punctuation marks within braces if they are part of the
6749 string you are specifying. Write punctuation marks outside the braces
6750 if those punctuation marks are part of the English text that surrounds
6751 the string. In the following sentence, for example, the commas and
6752 period are outside of the braces:@refill
6756 In English, the vowels are @@samp@{a@}, @@samp@{e@},
6757 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
6766 In English, the vowels are @samp{a}, @samp{e},
6767 @samp{i}, @samp{o}, @samp{u}, and sometimes
6773 @subsection @code{@@var}@{@var{metasyntactic-variable}@}
6776 Use the @code{@@var} command to indicate metasyntactic variables. A
6777 @dfn{metasyntactic variable} is something that stands for another piece of
6778 text. For example, you should use a metasyntactic variable in the
6779 documentation of a function to describe the arguments that are passed
6780 to that function.@refill
6782 Do not use @code{@@var} for the names of particular variables in
6783 programming languages. These are specific names from a program, so
6784 @code{@@code} is correct for them (@pxref{code}). For example, the
6785 Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
6786 variable; it is properly formatted using @code{@@code}.
6788 Do not use @code{@@var} for environment variables either; @code{@@env}
6789 is correct for them (see the next section).
6791 The effect of @code{@@var} in the Info file is to change the case of the
6792 argument to all upper case. In the printed manual and HTML output, the
6793 argument is printed in slanted type.
6799 To delete file @@var@{filename@},
6800 type @@samp@{rm @@var@{filename@}@}.
6807 To delete file @var{filename}, type @samp{rm @var{filename}}.
6811 (Note that @code{@@var} may appear inside @code{@@code},
6812 @code{@@samp}, @code{@@file}, etc.)@refill
6814 Write a metasyntactic variable all in lower case without spaces, and
6815 use hyphens to make it more readable. Thus, the Texinfo source for
6816 the illustration of how to begin a Texinfo manual looks like
6822 @@@@setfilename @@var@{info-file-name@}
6823 @@@@settitle @@var@{name-of-manual@}
6833 @@setfilename @var{info-file-name}
6834 @@settitle @var{name-of-manual}
6838 In some documentation styles, metasyntactic variables are shown with
6839 angle brackets, for example:@refill
6842 @dots{}, type rm <filename>
6846 However, that is not the style that Texinfo uses. (You can, of
6847 course, modify the sources to @file{texinfo.tex} and the Info formatting commands
6848 to output the @code{<@dots{}>} format if you wish.)@refill
6852 @subsection @code{@@env}@{@var{environment-variable}@}
6855 Use the @code{@@env} command to indicate environment variables, as used
6856 by many operating systems, including GNU. Do not use it for
6857 metasyntactic variables; use @code{@@var} instead (see the previous
6860 @code{@@env} is equivalent to @code{@@code} in its effects.
6864 The @@env@{PATH@} environment variable sets the search path for commands.
6868 The @env{PATH} environment variable sets the search path for commands.
6873 @subsection @code{@@file}@{@var{file-name}@}
6876 Use the @code{@@file} command to indicate text that is the name of a
6877 file, buffer, or directory, or is the name of a node in Info. You can
6878 also use the command for file name suffixes. Do not use @code{@@file}
6879 for symbols in a programming language; use @code{@@code}.
6881 Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
6885 The @@file@{.el@} files are in
6886 the @@file@{/usr/local/emacs/lisp@} directory.
6893 The @file{.el} files are in
6894 the @file{/usr/local/emacs/lisp} directory.
6899 @subsection @code{@@command}@{@var{command-name}@}
6901 @cindex Command names, indicating
6902 @cindex Program names, indicating
6904 Use the @code{@@command} command to indicate command names, such as
6905 @command{ls} or @command{cc}.
6907 @code{@@command} is equivalent to @code{@@code} in its effects.
6911 The command @@command@{ls@} lists directory contents.
6915 The command @command{ls} lists directory contents.
6918 You should write the name of a program in the ordinary text font, rather
6919 than using @code{@@command}, if you regard it as a new English word,
6920 such as `Emacs' or `Bison'.
6922 When writing an entire shell command invocation, as in @samp{ls -l},
6923 you should use either @code{@@samp} or @code{@@code} at your discretion.
6927 @subsection @code{@@option}@{@var{option-name}@}
6930 Use the @code{@@option} command to indicate a command-line option; for
6931 example, @option{-l} or @option{--version} or
6932 @option{--output=@var{filename}}.
6934 @code{@@option} is equivalent to @code{@@samp} in its effects.
6938 The option @@option@{-l@} produces a long listing.
6942 The option @option{-l} produces a long listing.
6945 In tables, putting options inside @code{@@code} produces a
6946 more pleasing effect.
6949 @comment node-name, next, previous, up
6950 @subsection @code{@@dfn}@{@var{term}@}
6953 Use the @code{@@dfn} command to identify the introductory or defining
6954 use of a technical term. Use the command only in passages whose
6955 purpose is to introduce a term which will be used again or which the
6956 reader ought to know. Mere passing mention of a term for the first
6957 time does not deserve @code{@@dfn}. The command generates italics in
6958 the printed manual, and double quotation marks in the Info file. For
6962 Getting rid of a file is called @@dfn@{deleting@} it.
6969 Getting rid of a file is called @dfn{deleting} it.
6972 As a general rule, a sentence containing the defining occurrence of a
6973 term should be a definition of the term. The sentence does not need
6974 to say explicitly that it is a definition, but it should contain the
6975 information of a definition---it should make the meaning clear.
6978 @subsection @code{@@cite}@{@var{reference}@}
6981 Use the @code{@@cite} command for the name of a book that lacks a
6982 companion Info file. The command produces italics in the printed
6983 manual, and quotation marks in the Info file.
6985 If a book is written in Texinfo, it is better to use a cross reference
6986 command since a reader can easily follow such a reference in Info.
6987 @xref{xref, , @code{@@xref}}.
6991 @c node ctrl, , cite, Indicating
6992 @comment node-name, next, previous, up
6993 @c subsection @code{@@ctrl}@{@var{ctrl-char}@}
6996 The @code{@@ctrl} command is seldom used. It describes an @sc{ascii}
6997 control character by inserting the actual character into the Info
7000 Usually, in Texinfo, you talk what you type as keyboard entry by
7001 describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
7002 @kbd{C-a}. Use @code{@@kbd} in this way when talking about a control
7003 character that is typed on the keyboard by the user. When talking
7004 about a control character appearing in a file or a string, do not use
7005 @code{@@kbd} since the control character is not typed. Also, do not
7006 use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
7007 to make it easier for a reader to understand.@refill
7009 @code{@@ctrl} is an idea from the beginnings of Texinfo which may not
7010 really fit in to the scheme of things. But there may be times when
7011 you want to use the command. The pattern is
7012 @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character
7013 whose control-equivalent is wanted. For example, to specify
7014 @samp{control-f}, you would enter@refill
7027 In the Info file, this generates the specified control character, output
7028 literally into the file. This is done so a user can copy the specified
7029 control character (along with whatever else he or she wants) into another
7030 Emacs buffer and use it. Since the `control-h',`control-i', and
7031 `control-j' characters are formatting characters, they should not be
7032 indicated with @code{@@ctrl}.@refill
7034 In a printed manual, @code{@@ctrl} generates text to describe or
7035 identify that control character: an uparrow followed by the character
7041 @subsection @code{@@acronym}@{@var{acronym}@}
7044 @cindex NASA, as acronym
7045 @cindex F.B.I., as acronym
7046 @cindex Abbreviations, tagging
7047 @cindex Acronyms, tagging
7048 Use the @code{@@acronym} command for abbreviations written in all
7049 capital letters, such as `@acronym{NASA}'. The abbreviation is given as
7050 the single argument in braces, as in @samp{@@acronym@{NASA@}}. As
7051 a matter of style, or for particular abbreviations, you may prefer to
7052 use periods, as in @samp{@@acronym@{F.B.I.@}}.
7054 In @TeX{} and HTML, the argument is printed in a slightly smaller font
7055 size. In Info or plain text output, this command changes nothing.
7059 @subsection @code{@@url}@{@var{uniform-resource-locator}@}
7061 @cindex Uniform resource locator, indicating
7062 @cindex URL, indicating
7064 Use the @code{@@url} command to indicate a uniform resource locator on
7065 the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
7066 etc., and is purely for markup purposes. It does not produce a link you
7067 can follow in HTML output (use the @code{@@uref} command for that,
7068 @pxref{uref,, @code{@@uref}}). It is useful for url's which do
7069 not actually exist. For example:
7071 @c Two lines because one is too long for smallbook format.
7073 For example, the url might be @@url@{http://example.org/path@}.
7076 @noindent which produces:
7079 For example, the url might be @url{http://example.org/path}.
7084 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
7087 Use the @code{@@email} command to indicate an electronic mail address.
7088 It takes one mandatory argument, the address, and one optional argument, the
7089 text to display (the default is the address itself).
7092 In Info and @TeX{}, the address is shown in angle brackets, preceded by
7093 the text to display if any. In HTML output, @code{@@email} produces a
7094 @samp{mailto} link that usually brings up a mail composition window.
7098 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}.
7099 Send suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
7103 Send bug reports to @email{bug-texinfo@@gnu.org}.
7104 Send suggestions to the @email{bug-texinfo@@gnu.org, same place}.
7108 @node Emphasis, , Indicating, Marking Text
7109 @comment node-name, next, previous, up
7110 @section Emphasizing Text
7111 @cindex Emphasizing text
7113 Usually, Texinfo changes the font to mark words in the text according to
7114 what category the words belong to; an example is the @code{@@code} command.
7115 Most often, this is the best way to mark words.
7116 However, sometimes you will want to emphasize text without indicating a
7117 category. Texinfo has two commands to do this. Also, Texinfo has
7118 several commands that specify the font in which @TeX{} will typeset
7119 text. These commands have no effect on Info and only one of them,
7120 the @code{@@r} command, has any regular use.@refill
7123 * emph & strong:: How to emphasize text in Texinfo.
7124 * Smallcaps:: How to use the small caps font.
7125 * Fonts:: Various font commands for printed output.
7129 @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
7130 @cindex Emphasizing text, font for
7134 The @code{@@emph} and @code{@@strong} commands are for emphasis;
7135 @code{@@strong} is stronger. In printed output, @code{@@emph} produces
7136 @emph{italics} and @code{@@strong} produces @strong{bold}.
7144 @@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
7145 files in the directory.
7152 produces the following in printed output:
7155 @strong{Caution}: @samp{rm * .[^.]*} removes @emph{all}
7156 files in the directory.
7160 and the following in Info:
7168 *Caution*: `rm * .[^.]*' removes _all_
7169 files in the directory.
7172 The @code{@@strong} command is seldom used except to mark what is, in
7173 effect, a typographical element, such as the word `Caution' in the
7176 In the Info output, @code{@@emph} surrounds the text with underscores
7177 (@samp{_}), and @code{@@strong} puts asterisks around the text.
7180 @strong{Caution:} Do not use @code{@@strong} with the word @samp{Note};
7181 Info will mistake the combination for a cross reference. Use a phrase
7182 such as @strong{Please note} or @strong{Caution} instead.
7187 @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
7188 @cindex Small caps font
7189 @findex sc @r{(small caps font)}
7191 Use the @samp{@@sc} command to set text in the printed and the HTML
7192 output in @sc{a small caps font} and set text in the Info file in upper
7193 case letters. Write the text you want to be in small caps (where
7194 possible) between braces in lower case, like this:
7197 The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
7204 The @sc{acm} and @sc{ieee} are technical societies.
7207 @TeX{} typesets the small caps font in a manner that prevents the
7208 letters from `jumping out at you on the page'. This makes small caps
7209 text easier to read than text in all upper case---but it's usually
7210 better to use regular mixed case anyway. The Info formatting commands
7211 set all small caps text in upper case. In HTML, the text is upper-cased
7212 and a smaller font is used to render it.
7214 If the text between the braces of an @code{@@sc} command is uppercase,
7215 @TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals
7216 sparingly, if ever, and since it's redundant to mark all-uppercase text
7217 with @code{@@sc}, @command{makeinfo} warns about such usage.
7219 You may also use the small caps font for a jargon word such as
7220 @sc{ato} (a @sc{nasa} word meaning `abort to orbit').
7222 There are subtleties to using the small caps font with a jargon word
7223 such as @sc{cdr}, a word used in Lisp programming. In this case, you
7224 should use the small caps font when the word refers to the second and
7225 subsequent elements of a list (the @sc{cdr} of the list), but you
7226 should use @samp{@@code} when the word refers to the Lisp function of
7231 @subsection Fonts for Printing, Not Info
7232 @cindex Fonts for printing, not for Info
7233 @findex i @r{(italic font)}
7234 @findex b @r{(bold font)}
7235 @findex t @r{(typewriter font)}
7236 @findex r @r{(Roman font)}
7238 Texinfo provides four font commands that specify font changes in the
7239 printed manual but have no effect in the Info file. @code{@@i}
7240 requests @i{italic} font (in some versions of @TeX{}, a slanted font
7241 is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
7242 @t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
7243 @r{roman} font, which is the usual font in which text is printed. All
7244 four commands apply to an argument that follows, surrounded by
7247 Only the @code{@@r} command has much use: in example programs, you
7248 can use the @code{@@r} command to convert code comments from the
7249 fixed-width font to a roman font. This looks better in printed
7258 (+ 2 2) ; @@r@{Add two plus two.@}
7267 (+ 2 2) ; @r{Add two plus two.}
7270 If possible, you should avoid using the other three font commands. If
7271 you need to use one, it probably indicates a gap in the Texinfo
7274 @node Quotations and Examples
7275 @chapter Quotations and Examples
7277 Quotations and examples are blocks of text consisting of one or more
7278 whole paragraphs that are set off from the bulk of the text and
7279 treated differently. They are usually indented.@refill
7281 In Texinfo, you always begin a quotation or example by writing an
7282 @@-command at the beginning of a line by itself, and end it by writing
7283 an @code{@@end} command that is also at the beginning of a line by
7284 itself. For instance, you begin an example by writing @code{@@example}
7285 by itself at the beginning of a line and end the example by writing
7286 @code{@@end example} on a line by itself, at the beginning of that
7291 * Block Enclosing Commands:: Use different constructs for
7293 * quotation:: How to write a quotation.
7294 * example:: How to write an example in a fixed-width font.
7295 * noindent:: How to prevent paragraph indentation.
7296 * lisp:: How to illustrate Lisp code.
7297 * small:: Forms for @code{@@smallbook}.
7298 * display:: How to write an example in the current font.
7299 * format:: How to write an example that does not narrow
7301 * exdent:: How to undo the indentation of a line.
7302 * flushleft & flushright:: How to push text flushleft or flushright.
7303 * cartouche:: How to draw cartouches around examples.
7306 @node Block Enclosing Commands
7307 @section Block Enclosing Commands
7309 Here are commands for quotations and examples, explained further in the
7314 Indicate text that is quoted. The text is filled, indented, and
7315 printed in a roman font by default.@refill
7318 Illustrate code, commands, and the like. The text is printed
7319 in a fixed-width font, and indented but not filled.@refill
7321 @item @@smallexample
7322 Same as @code{@@example}, except that in @TeX{} this command typesets
7323 text in a smaller font for the @code{@@smallbook} format than for the
7324 default 8.5 by 11 inch format.
7327 Like @code{@@example}, but specifically for illustrating Lisp code. The
7328 text is printed in a fixed-width font, and indented but not filled.
7331 Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
7334 Display illustrative text. The text is indented but not filled, and
7335 no font is selected (so, by default, the font is roman).@refill
7337 @item @@smalldisplay
7338 Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
7341 Like @code{@@display} (the text is not filled and no font is selected),
7342 but the text is not indented.
7345 Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
7348 The @code{@@exdent} command is used within the above constructs to
7349 undo the indentation of a line.
7351 The @code{@@flushleft} and @code{@@flushright} commands are used to line
7352 up the left or right margins of unfilled text.@refill
7354 The @code{@@noindent} command may be used after one of the above
7355 constructs to prevent the following text from being indented as a new
7358 You can use the @code{@@cartouche} command within one of the above
7359 constructs to highlight the example or quotation by drawing a box with
7360 rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
7365 @section @code{@@quotation}
7369 The text of a quotation is processed normally except that:
7373 the margins are closer to the center of the page, so the whole of the
7374 quotation is indented;@refill
7377 the first lines of paragraphs are indented no more than other
7381 in the printed output, interparagraph spacing is reduced.@refill
7385 This is an example of text written between an @code{@@quotation}
7386 command and an @code{@@end quotation} command. An @code{@@quotation}
7387 command is most often used to indicate text that is excerpted from
7388 another (real or hypothetical) printed work.@refill
7391 Write an @code{@@quotation} command as text on a line by itself. This
7392 line will disappear from the output. Mark the end of the quotation
7393 with a line beginning with and containing only @code{@@end quotation}.
7394 The @code{@@end quotation} line will likewise disappear from the
7395 output. Thus, the following,@refill
7413 @section @code{@@example}
7414 @cindex Examples, formatting them
7415 @cindex Formatting examples
7418 The @code{@@example} command is used to indicate an example that is
7419 not part of the running text, such as computer input or output.@refill
7423 This is an example of text written between an
7424 @code{@@example} command
7425 and an @code{@@end example} command.
7426 The text is indented but not filled.
7430 In the printed manual, the text is typeset in a
7431 fixed-width font, and extra spaces and blank lines are
7432 significant. In the Info file, an analogous result is
7433 obtained by indenting each line with five spaces.
7437 Write an @code{@@example} command at the beginning of a line by itself.
7438 Mark the end of the example
7439 with an @code{@@end example} command, also written at the beginning of a
7440 line by itself.@refill
7458 The lines containing @code{@@example} and @code{@@end example}
7459 will disappear from the output.
7460 To make the output look good,
7461 you should put a blank line before the
7462 @code{@@example} and another blank line after the @code{@@end example}.
7463 Note that blank lines inside the beginning
7464 @code{@@example} and the ending @code{@@end example} will appear in
7468 @strong{Caution:} Do not use tabs in the lines of an example (or anywhere
7469 else in Texinfo, for that matter)! @TeX{} treats tabs as single
7470 spaces, and that is not what they look like. This is a problem with
7471 @TeX{}. (If necessary, in Emacs, you can use @kbd{M-x untabify} to
7472 convert tabs in a region to multiple spaces.)@refill
7475 Examples are often, logically speaking, ``in the middle'' of a
7476 paragraph, and the text that continues after an example should not be
7477 indented. The @code{@@noindent} command prevents a piece of text from
7478 being indented as if it were a new paragraph.
7483 (The @code{@@code} command is used for examples of code that are
7484 embedded within sentences, not set off from preceding and following
7485 text. @xref{code, , @code{@@code}}.)
7489 @section @code{@@noindent}
7492 An example or other inclusion can break a paragraph into segments.
7493 Ordinarily, the formatters indent text that follows an example as a new
7494 paragraph. However, you can prevent this by writing @code{@@noindent}
7495 at the beginning of a line by itself preceding the continuation
7508 This line is not indented. As you can see, the
7509 beginning of the line is fully flush left with the line
7510 that follows after it. (This whole example is between
7511 @@code@{@@@@display@} and @@code@{@@@@end display@}.)
7523 % Remove extra vskip; this is a kludge to counter the effect of display
7524 \vskip-3.5\baselineskip
7528 This line is not indented. As you can see, the
7529 beginning of the line is fully flush left with the line
7530 that follows after it. (This whole example is between
7531 @code{@@display} and @code{@@end display}.)
7534 To adjust the number of blank lines properly in the Info file output,
7535 remember that the line containing @code{@@noindent} does not generate a
7536 blank line, and neither does the @code{@@end example} line.@refill
7538 In the Texinfo source file for this manual, each line that says
7539 `produces' is preceded by a line containing @code{@@noindent}.@refill
7541 Do not put braces after an @code{@@noindent} command; they are not
7542 necessary, since @code{@@noindent} is a command used outside of
7543 paragraphs (@pxref{Command Syntax}).@refill
7547 @section @code{@@lisp}
7549 @cindex Lisp example
7551 The @code{@@lisp} command is used for Lisp code. It is synonymous
7552 with the @code{@@example} command.
7555 This is an example of text written between an
7556 @code{@@lisp} command and an @code{@@end lisp} command.
7559 Use @code{@@lisp} instead of @code{@@example} to preserve information
7560 regarding the nature of the example. This is useful, for example, if
7561 you write a function that evaluates only and all the Lisp code in a
7562 Texinfo file. Then you can use the Texinfo file as a Lisp
7563 library.@footnote{It would be straightforward to extend Texinfo to work
7564 in a similar fashion for C, Fortran, or other languages.}
7566 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
7571 @section @code{@@small@dots{}} Block Commands
7572 @cindex Small book example
7573 @cindex Example for a small book
7574 @cindex Lisp example for a small book
7575 @findex smalldisplay
7576 @findex smallexample
7580 In addition to the regular @code{@@example} and @code{@@lisp} commands,
7581 Texinfo has ``small'' example-style commands. These are
7582 @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
7583 @code{@@smalllisp}. All of these commands are designed for use with the
7584 @code{@@smallbook} command (which causes @TeX{} to format a printed book for
7585 a 7 by 9.25 inch trim size rather than the default 8.5 by 11 inch size).
7587 In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
7588 font for the smaller @code{@@smallbook} format than for the 8.5 by 11
7589 inch format. Consequently, many examples containing long lines fit in a
7590 narrower, @code{@@smallbook} page without needing to be shortened. Both
7591 commands typeset in the normal font size when you format for the 8.5 by
7592 11 inch size. Indeed, in this situation, the @code{@@small@dots{}}
7593 commands are equivalent to their non-small versions.
7595 In Info, the @code{@@small@dots{}} commands are also equivalent to their
7596 non-small companion commands.
7598 Mark the end of an @code{@@small@dots{}} block with a corresponding
7599 @code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
7600 @code{@@end smallexample}.
7603 Here is an example written in the small font used by the
7604 @code{@@smallexample} and @code{@@smalllisp} commands:
7609 % Remove extra vskip; this is a kludge to counter the effect of display
7610 \vskip-3\baselineskip
7612 \dots{} to make sure that you have the freedom to
7613 distribute copies of free software (and charge for
7614 this service if you wish), that you receive source
7615 code or can get it if you want it, that you can
7616 change the software or use pieces of it in new free
7617 programs; and that you know you can do these things.}
7625 This is an example of text written between @code{@@smallexample} and
7626 @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
7627 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7628 this text appears in a smaller font.
7634 This is an example of text written between @code{@@smallexample} and
7635 @code{@@end smallexample}. In Info and in an 8.5 by 11 inch manual,
7636 this text appears in its normal size; but in a 7 by 9.25 inch manual,
7637 this text appears in a smaller font.
7641 The @code{@@small@dots{}} commands make it easier to prepare smaller
7642 format manuals without forcing you to edit examples by hand to fit them
7643 onto narrower pages.@refill
7645 As a general rule, a printed document looks better if you use only one
7646 of (for example) @code{@@example} or in @code{@@smallexample}
7647 consistently within a chapter. Only occasionally should you mix the two
7650 @xref{smallbook, , Printing ``Small'' Books}, for more information
7651 about the @code{@@smallbook} command.@refill
7655 @section @code{@@display} and @code{@@smalldisplay}
7656 @cindex Display formatting
7659 The @code{@@display} command begins a kind of example. It is like the
7660 @code{@@example} command
7662 a printed manual, @code{@@display} does not select the fixed-width
7663 font. In fact, it does not specify the font at all, so that the text
7664 appears in the same font it would have appeared in without the
7665 @code{@@display} command.@refill
7668 This is an example of text written between an @code{@@display} command
7669 and an @code{@@end display} command. The @code{@@display} command
7670 indents the text, but does not fill it.
7673 @findex smalldisplay
7674 Texinfo also provides a command @code{@@smalldisplay}, which is like
7675 @code{@@display} but uses a smaller font in @code{@@smallbook} format.
7680 @section @code{@@format} and @code{@@smallformat}
7683 The @code{@@format} command is similar to @code{@@example} except
7684 that, in the printed manual, @code{@@format} does not select the
7685 fixed-width font and does not narrow the margins.@refill
7688 This is an example of text written between an @code{@@format} command
7689 and an @code{@@end format} command. As you can see
7691 the @code{@@format} command does not fill the text.
7695 Texinfo also provides a command @code{@@smallformat}, which is like
7696 @code{@@format} but uses a smaller font in @code{@@smallbook} format.
7702 @section @code{@@exdent}: Undoing a Line's Indentation
7703 @cindex Indentation undoing
7706 The @code{@@exdent} command removes any indentation a line might have.
7707 The command is written at the beginning of a line and applies only to
7708 the text that follows the command that is on the same line. Do not use
7709 braces around the text. In a printed manual, the text on an
7710 @code{@@exdent} line is printed in the roman font.@refill
7712 @code{@@exdent} is usually used within examples. Thus,@refill
7717 This line follows an @@@@example command.
7718 @@exdent This line is exdented.
7719 This line follows the exdented line.
7720 The @@@@end example comes on the next line.
7730 This line follows an @@example command.
7731 @exdent This line is exdented.
7732 This line follows the exdented line.
7733 The @@end example comes on the next line.
7737 In practice, the @code{@@exdent} command is rarely used.
7738 Usually, you un-indent text by ending the example and
7739 returning the page to its normal width.@refill
7741 @node flushleft & flushright, cartouche, exdent, Quotations and Examples
7742 @section @code{@@flushleft} and @code{@@flushright}
7746 The @code{@@flushleft} and @code{@@flushright} commands line up the
7747 ends of lines on the left and right margins of a page,
7748 but do not fill the text. The commands are written on lines of their
7749 own, without braces. The @code{@@flushleft} and @code{@@flushright}
7750 commands are ended by @code{@@end flushleft} and @code{@@end
7751 flushright} commands on lines of their own.@refill
7776 @code{@@flushright} produces the type of indentation often used in the
7777 return address of letters. For example,
7782 Here is an example of text written
7783 flushright. The @@code@{@@flushright@} command
7784 right justifies every line but leaves the
7794 Here is an example of text written
7795 flushright. The @code{@@flushright} command
7796 right justifies every line but leaves the
7800 @node cartouche, , flushleft & flushright, Quotations and Examples
7801 @section Drawing Cartouches Around Examples
7803 @cindex Box with rounded corners
7805 In a printed manual, the @code{@@cartouche} command draws a box with
7806 rounded corners around its contents. You can use this command to
7807 further highlight an example or quotation. For instance, you could
7808 write a manual in which one type of example is surrounded by a cartouche
7809 for emphasis.@refill
7811 @code{@@cartouche} affects only the printed manual; it has no effect in
7822 /usr/local/share/emacs
7829 surrounds the two-line example with a box with rounded corners, in the
7833 In a printed manual, the example looks like this:@refill
7839 /usr/local/lib/emacs/info
7846 @node Lists and Tables, Indices, Quotations and Examples, Top
7847 @chapter Lists and Tables
7848 @cindex Making lists and tables
7849 @cindex Lists and tables, making
7850 @cindex Tables and lists, making
7852 Texinfo has several ways of making lists and tables. Lists can be
7853 bulleted or numbered; two-column tables can highlight the items in
7854 the first column; multi-column tables are also supported.
7857 * Introducing Lists:: Texinfo formats lists for you.
7858 * itemize:: How to construct a simple list.
7859 * enumerate:: How to construct a numbered list.
7860 * Two-column Tables:: How to construct a two-column table.
7861 * Multi-column Tables:: How to construct generalized tables.
7864 @node Introducing Lists, itemize, Lists and Tables, Lists and Tables
7866 @heading Introducing Lists
7869 Texinfo automatically indents the text in lists or tables, and numbers
7870 an enumerated list. This last feature is useful if you modify the
7871 list, since you do not need to renumber it yourself.@refill
7873 Numbered lists and tables begin with the appropriate @@-command at the
7874 beginning of a line, and end with the corresponding @code{@@end}
7875 command on a line by itself. The table and itemized-list commands
7876 also require that you write formatting information on the same line as
7877 the beginning @@-command.@refill
7879 Begin an enumerated list, for example, with an @code{@@enumerate}
7880 command and end the list with an @code{@@end enumerate} command.
7881 Begin an itemized list with an @code{@@itemize} command, followed on
7882 the same line by a formatting command such as @code{@@bullet}, and end
7883 the list with an @code{@@end itemize} command.@refill
7886 Precede each element of a list with an @code{@@item} or @code{@@itemx}
7891 Here is an itemized list of the different kinds of table and lists:@refill
7895 Itemized lists with and without bullets.
7898 Enumerated lists, using numbers or letters.
7901 Two-column tables with highlighting.
7906 Here is an enumerated list with the same items:@refill
7910 Itemized lists with and without bullets.
7913 Enumerated lists, using numbers or letters.
7916 Two-column tables with highlighting.
7921 And here is a two-column table with the same items and their
7922 @w{@@-commands}:@refill
7926 Itemized lists with and without bullets.
7929 Enumerated lists, using numbers or letters.
7934 Two-column tables, optionally with indexing.
7939 @section @code{@@itemize}: Making an Itemized List
7943 The @code{@@itemize} command produces sequences of indented
7944 paragraphs, with a bullet or other mark inside the left margin
7945 at the beginning of each paragraph for which such a mark is desired.@refill
7947 @cindex @code{@@w}, for blank items
7948 Begin an itemized list by writing @code{@@itemize} at the beginning of
7949 a line. Follow the command, on the same line, with a character or a
7950 Texinfo command that generates a mark. Usually, you will write
7951 @code{@@bullet} after @code{@@itemize}, but you can use
7952 @code{@@minus}, or any command or character that results in a single
7953 character in the Info file. If you don't want any mark at all, use
7954 @code{@@w}. (When you write the mark command such as
7955 @code{@@bullet} after an @code{@@itemize} command, you may omit the
7956 @samp{@{@}}.) If you don't specify a mark command, the default is
7959 Write the text of the indented paragraphs themselves after the
7960 @code{@@itemize}, up to another line that says @code{@@end
7964 Before each paragraph for which a mark in the margin is desired, write a
7965 line that says just @code{@@item}. It is ok to have text following the
7968 Usually, you should put a blank line before an @code{@@item}. This
7969 puts a blank line in the Info file. (@TeX{} inserts the proper
7970 interline whitespace in either case.) Except when the entries are
7971 very brief, these blank lines make the list look better.@refill
7973 Here is an example of the use of @code{@@itemize}, followed by the
7974 output it produces. @code{@@bullet} produces an @samp{*} in Info and a
7975 round dot in @TeX{}.
8004 Itemized lists may be embedded within other itemized lists. Here is a
8005 list marked with dashes embedded in a list marked with bullets:@refill
8050 @section @code{@@enumerate}: Making a Numbered or Lettered List
8054 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
8055 @code{@@itemize}}), except that the labels on the items are
8056 successive integers or letters instead of bullets.
8058 Write the @code{@@enumerate} command at the beginning of a line. The
8059 command does not require an argument, but accepts either a number or a
8060 letter as an option. Without an argument, @code{@@enumerate} starts the
8061 list with the number @samp{1}. With a numeric argument, such as
8062 @samp{3}, the command starts the list with that number. With an upper
8063 or lower case letter, such as @samp{a} or @samp{A}, the command starts
8064 the list with that letter.
8066 Write the text of the enumerated list in the same way you write an
8067 itemized list: put @code{@@item} on a line of its own before the start
8068 of each paragraph that you want enumerated. Do not write any other text
8069 on the line beginning with @code{@@item}.
8071 You should put a blank line between entries in the list.
8072 This generally makes it easier to read the Info file.
8075 Here is an example of @code{@@enumerate} without an argument:
8100 Here is an example with an argument of @kbd{3}:@refill
8106 Predisposing causes.
8109 Precipitating causes.
8112 Perpetuating causes.
8122 Predisposing causes.
8125 Precipitating causes.
8128 Perpetuating causes.
8131 Here is a brief summary of the alternatives. The summary is constructed
8132 using @code{@@enumerate} with an argument of @kbd{a}.@refill
8138 Without an argument, produce a numbered list, starting with the number
8142 @code{@@enumerate @var{positive-integer}}
8144 With a (positive) numeric argument, start a numbered list with that
8145 number. You can use this to continue a list that you interrupted with
8149 @code{@@enumerate @var{upper-case-letter}}
8151 With an upper case letter as argument, start a list
8152 in which each item is marked
8153 by a letter, beginning with that upper case letter.@refill
8156 @code{@@enumerate @var{lower-case-letter}}
8158 With a lower case letter as argument, start a list
8159 in which each item is marked by
8160 a letter, beginning with that lower case letter.@refill
8163 You can also nest enumerated lists, as in an outline.@refill
8165 @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
8166 @section Making a Two-column Table
8167 @cindex Tables, making two-column
8170 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
8171 @code{@@itemize}}), but allows you to specify a name or heading line for
8172 each item. The @code{@@table} command is used to produce two-column
8173 tables, and is especially useful for glossaries, explanatory
8174 exhibits, and command-line option summaries.
8177 * table:: How to construct a two-column table.
8178 * ftable vtable:: Automatic indexing for two-column tables.
8179 * itemx:: How to put more entries in the first column.
8182 @node table, ftable vtable, Two-column Tables, Two-column Tables
8184 @subheading Using the @code{@@table} Command
8186 Use the @code{@@table} command to produce two-column tables.@refill
8189 Write the @code{@@table} command at the beginning of a line and follow
8190 it on the same line with an argument that is a Texinfo ``indicating''
8191 command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8192 @code{@@kbd} (@pxref{Indicating}). Although these commands are usually
8193 followed by arguments in braces, in this case you use the command name
8194 without an argument because @code{@@item} will supply the argument.
8195 This command will be applied to the text that goes into the first column
8196 of each item and determines how it will be highlighted. For example,
8197 @code{@@code} will cause the text in the first column to be highlighted
8198 with an @code{@@code} command. (We recommend @code{@@code} for
8199 @code{@@table}'s of command-line options.)
8202 You may also choose to use the @code{@@asis} command as an argument to
8203 @code{@@table}. @code{@@asis} is a command that does nothing; if you
8204 use this command after @code{@@table}, @TeX{} and the Info formatting
8205 commands output the first column entries without added highlighting
8208 (The @code{@@table} command may work with other commands besides those
8209 listed here. However, you can only use commands that normally take
8210 arguments in braces.)@refill
8213 Begin each table entry with an @code{@@item} command at the beginning
8214 of a line. Write the first column text on the same line as the
8215 @code{@@item} command. Write the second column text on the line
8216 following the @code{@@item} line and on subsequent lines. (You do not
8217 need to type anything for an empty second column entry.) You may
8218 write as many lines of supporting text as you wish, even several
8219 paragraphs. But only text on the same line as the @code{@@item} will
8220 be placed in the first column, including any footnote.
8222 Normally, you should put a blank line before an @code{@@item} line.
8223 This puts a blank like in the Info file. Except when the entries are
8224 very brief, a blank line looks better.@refill
8227 The following table, for example, highlights the text in the first
8228 column with an @code{@@samp} command:@refill
8234 This is the text for
8238 Text for @@samp@{bar@}.
8248 This is the text for
8251 Text for @samp{bar}.
8254 If you want to list two or more named items with a single block of
8255 text, use the @code{@@itemx} command. (@xref{itemx, ,
8256 @code{@@itemx}}.)@refill
8260 @subsection @code{@@ftable} and @code{@@vtable}
8261 @cindex Tables with indexes
8262 @cindex Indexing table entries automatically
8266 The @code{@@ftable} and @code{@@vtable} commands are the same as the
8267 @code{@@table} command except that @code{@@ftable} automatically enters
8268 each of the items in the first column of the table into the index of
8269 functions and @code{@@vtable} automatically enters each of the items in
8270 the first column of the table into the index of variables. This
8271 simplifies the task of creating indices. Only the items on the same
8272 line as the @code{@@item} commands are indexed, and they are indexed in
8273 exactly the form that they appear on that line. @xref{Indices},
8274 for more information about indices.@refill
8276 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8277 writing the @@-command at the beginning of a line, followed on the same
8278 line by an argument that is a Texinfo command such as @code{@@code},
8279 exactly as you would for an @code{@@table} command; and end the table
8280 with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8283 See the example for @code{@@table} in the previous section.
8286 @subsection @code{@@itemx}
8287 @cindex Two named items for @code{@@table}
8290 Use the @code{@@itemx} command inside a table when you have two or more
8291 first column entries for the same item, each of which should appear on a
8292 line of its own. Use @code{@@itemx} for all but the first entry;
8293 @code{@@itemx} should always follow an @code{@@item} command. The
8294 @code{@@itemx} command works exactly like @code{@@item} except that it
8295 does not generate extra vertical space above the first column text.
8304 These two functions accept a character or a string as
8305 argument, and return the corresponding upper case (lower
8306 case) character or string.
8317 These two functions accept a character or a string as
8318 argument, and return the corresponding upper case (lower
8319 case) character or string.@refill
8323 (Note also that this example illustrates multi-line supporting text in
8324 a two-column table.)@refill
8327 @node Multi-column Tables, , Two-column Tables, Lists and Tables
8328 @section Multi-column Tables
8329 @cindex Tables, making multi-column
8332 @code{@@multitable} allows you to construct tables with any number of
8333 columns, with each column having any width you like.
8335 You define the column widths on the @code{@@multitable} line itself, and
8336 write each row of the actual table following an @code{@@item} command,
8337 with columns separated by an @code{@@tab} command. Finally, @code{@@end
8338 multitable} completes the table. Details in the sections below.
8341 * Multitable Column Widths:: Defining multitable column widths.
8342 * Multitable Rows:: Defining multitable rows, with examples.
8345 @node Multitable Column Widths
8346 @subsection Multitable Column Widths
8347 @cindex Multitable column widths
8348 @cindex Column widths, defining for multitables
8349 @cindex Widths, defining multitable column
8351 You can define the column widths for a multitable in two ways: as
8352 fractions of the line length; or with a prototype row. Mixing the two
8353 methods is not supported. In either case, the widths are defined
8354 entirely on the same line as the @code{@@multitable} command.
8358 @findex columnfractions
8359 @cindex Line length, column widths as fraction of
8360 To specify column widths as fractions of the line length, write
8361 @code{@@columnfractions} and the decimal numbers (presumably less than
8362 1) after the @code{@@multitable} command, as in:
8365 @@multitable @@columnfractions .33 .33 .33
8368 @noindent The fractions need not add up exactly to 1.0, as these do
8369 not. This allows you to produce tables that do not need the full line
8370 length. You can use a leading zero if you wish.
8373 @cindex Prototype row, column widths defined by
8374 To specify a prototype row, write the longest entry for each column
8375 enclosed in braces after the @code{@@multitable} command. For example:
8378 @@multitable @{some text for column one@} @{for column two@}
8382 The first column will then have the width of the typeset `some text for
8383 column one', and the second column the width of `for column two'.
8385 The prototype entries need not appear in the table itself.
8387 Although we used simple text in this example, the prototype entries can
8388 contain Texinfo commands; markup commands such as @code{@@code} are
8389 particularly likely to be useful.
8394 @node Multitable Rows, , Multitable Column Widths, Multi-column Tables
8395 @subsection Multitable Rows
8396 @cindex Multitable rows
8397 @cindex Rows, of a multitable
8401 After the @code{@@multitable} command defining the column widths (see
8402 the previous section), you begin each row in the body of a multitable
8403 with @code{@@item}, and separate the column entries with @code{@@tab}.
8404 Line breaks are not special within the table body, and you may break
8405 input lines in your source file as necessary.
8407 Here is a complete example of a multi-column table (the text is from
8408 @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
8409 emacs, The GNU Emacs Manual}):
8412 @@multitable @@columnfractions .15 .45 .4
8413 @@item Key @@tab Command @@tab Description
8415 @@tab @@code@{split-window-vertically@}
8416 @@tab Split the selected window into two windows,
8417 with one above the other.
8419 @@tab @@code@{split-window-horizontally@}
8420 @@tab Split the selected window into two windows
8421 positioned side by side.
8424 @@tab In the mode line or scroll bar of a window,
8431 @multitable @columnfractions .15 .45 .4
8432 @item Key @tab Command @tab Description
8434 @tab @code{split-window-vertically}
8435 @tab Split the selected window into two windows,
8436 with one above the other.
8438 @tab @code{split-window-horizontally}
8439 @tab Split the selected window into two windows
8440 positioned side by side.
8443 @tab In the mode line or scroll bar of a window,
8448 @node Indices, Insertions, Lists and Tables, Top
8449 @comment node-name, next, previous, up
8453 Using Texinfo, you can generate indices without having to sort and
8454 collate entries manually. In an index, the entries are listed in
8455 alphabetical order, together with information on how to find the
8456 discussion of each entry. In a printed manual, this information
8457 consists of page numbers. In an Info file, this information is a menu
8458 entry leading to the first node referenced.@refill
8460 Texinfo provides several predefined kinds of index: an index
8461 for functions, an index for variables, an index for concepts, and so
8462 on. You can combine indices or use them for other than their
8463 canonical purpose. If you wish, you can define your own indices.@refill
8466 * Index Entries:: Choose different words for index entries.
8467 * Predefined Indices:: Use different indices for different kinds
8469 * Indexing Commands:: How to make an index entry.
8470 * Combining Indices:: How to combine indices.
8471 * New Indices:: How to define your own indices.
8474 @node Index Entries, Predefined Indices, Indices, Indices
8475 @comment node-name, next, previous, up
8476 @section Making Index Entries
8477 @cindex Index entries, making
8478 @cindex Entries, making index
8480 When you are making index entries, it is good practice to think of the
8481 different ways people may look for something. Different people
8482 @emph{do not} think of the same words when they look something up. A
8483 helpful index will have items indexed under all the different words
8484 that people may use. For example, one reader may think it obvious that
8485 the two-letter names for indices should be listed under ``Indices,
8486 two-letter names'', since the word ``Index'' is the general concept.
8487 But another reader may remember the specific concept of two-letter
8488 names and search for the entry listed as ``Two letter names for
8489 indices''. A good index will have both entries and will help both
8492 Like typesetting, the construction of an index is a highly skilled,
8493 professional art, the subtleties of which are not appreciated until you
8494 need to do it yourself.@refill
8496 @xref{Printing Indices & Menus}, for information about printing an index
8497 at the end of a book or creating an index menu in an Info file.@refill
8499 @node Predefined Indices, Indexing Commands, Index Entries, Indices
8500 @comment node-name, next, previous, up
8501 @section Predefined Indices
8503 Texinfo provides six predefined indices:@refill
8507 A @dfn{concept index} listing concepts that are discussed.@refill
8510 A @dfn{function index} listing functions (such as entry points of
8514 A @dfn{variables index} listing variables (such as global variables
8515 of libraries).@refill
8518 A @dfn{keystroke index} listing keyboard commands.@refill
8521 A @dfn{program index} listing names of programs.@refill
8524 A @dfn{data type index} listing data types (such as structures defined in
8525 header files).@refill
8529 Not every manual needs all of these, and most manuals use two or three
8530 of them. This manual has two indices: a
8531 concept index and an @@-command index (that is actually the function
8532 index but is called a command index in the chapter heading). Two or
8533 more indices can be combined into one using the @code{@@synindex} or
8534 @code{@@syncodeindex} commands. @xref{Combining Indices}.@refill
8536 @node Indexing Commands, Combining Indices, Predefined Indices, Indices
8537 @comment node-name, next, previous, up
8538 @section Defining the Entries of an Index
8539 @cindex Defining indexing entries
8540 @cindex Index entries
8541 @cindex Entries for an index
8542 @cindex Specifying index entries
8543 @cindex Creating index entries
8545 The data to make an index come from many individual indexing commands
8546 scattered throughout the Texinfo source file. Each command says to add
8547 one entry to a particular index; after formatting, the index will give
8548 the current page number or node name as the reference.@refill
8550 An index entry consists of an indexing command at the beginning of a
8551 line followed, on the rest of the line, by the entry.@refill
8553 For example, this section begins with the following five entries for
8554 the concept index:@refill
8557 @@cindex Defining indexing entries
8558 @@cindex Index entries
8559 @@cindex Entries for an index
8560 @@cindex Specifying index entries
8561 @@cindex Creating index entries
8564 Each predefined index has its own indexing command---@code{@@cindex}
8565 for the concept index, @code{@@findex} for the function index, and so
8568 @cindex Writing index entries
8569 @cindex Index entry writing
8570 Concept index entries consist of text. The best way to write an index
8571 is to choose entries that are terse yet clear. If you can do this,
8572 the index often looks better if the entries are not capitalized, but
8573 written just as they would appear in the middle of a sentence.
8574 (Capitalize proper names and acronyms that always call for upper case
8575 letters.) This is the case convention we use in most GNU manuals'
8578 If you don't see how to make an entry terse yet clear, make it longer
8579 and clear---not terse and confusing. If many of the entries are several
8580 words long, the index may look better if you use a different convention:
8581 to capitalize the first word of each entry. But do not capitalize a
8582 case-sensitive name such as a C or Lisp function name or a shell
8583 command; that would be a spelling error.
8585 Whichever case convention you use, please use it consistently!
8587 Entries in indices other than the concept index are symbol names in
8588 programming languages, or program names; these names are usually
8589 case-sensitive, so use upper and lower case as required for them.
8591 By default, entries for a concept index are printed in a small roman
8592 font and entries for the other indices are printed in a small
8593 @code{@@code} font. You may change the way part of an entry is
8594 printed with the usual Texinfo commands, such as @code{@@file} for
8595 file names and @code{@@emph} for emphasis (@pxref{Marking
8597 @cindex Index font types
8599 @cindex Predefined indexing commands
8600 @cindex Indexing commands, predefined
8601 The six indexing commands for predefined indices are:
8604 @item @@cindex @var{concept}
8606 Make an entry in the concept index for @var{concept}.@refill
8608 @item @@findex @var{function}
8610 Make an entry in the function index for @var{function}.@refill
8612 @item @@vindex @var{variable}
8614 Make an entry in the variable index for @var{variable}.@refill
8616 @item @@kindex @var{keystroke}
8618 Make an entry in the key index for @var{keystroke}.@refill
8620 @item @@pindex @var{program}
8622 Make an entry in the program index for @var{program}.@refill
8624 @item @@tindex @var{data type}
8626 Make an entry in the data type index for @var{data type}.@refill
8630 @strong{Caution:} Do not use a colon in an index entry. In Info, a
8631 colon separates the menu entry name from the node name, so a colon in
8632 the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
8633 Menu}, for more information about the structure of a menu entry.
8636 You are not actually required to use the predefined indices for their
8637 canonical purposes. For example, suppose you wish to index some C
8638 preprocessor macros. You could put them in the function index along
8639 with actual functions, just by writing @code{@@findex} commands for
8640 them; then, when you print the ``Function Index'' as an unnumbered
8641 chapter, you could give it the title `Function and Macro Index' and
8642 all will be consistent for the reader. Or you could put the macros in
8643 with the data types by writing @code{@@tindex} commands for them, and
8644 give that index a suitable title so the reader will understand.
8645 (@xref{Printing Indices & Menus}.)@refill
8647 @node Combining Indices, New Indices, Indexing Commands, Indices
8648 @comment node-name, next, previous, up
8649 @section Combining Indices
8650 @cindex Combining indices
8651 @cindex Indices, combining them
8653 Sometimes you will want to combine two disparate indices such as functions
8654 and concepts, perhaps because you have few enough of one of them that
8655 a separate index for them would look silly.@refill
8657 You could put functions into the concept index by writing
8658 @code{@@cindex} commands for them instead of @code{@@findex} commands,
8659 and produce a consistent manual by printing the concept index with the
8660 title `Function and Concept Index' and not printing the `Function
8661 Index' at all; but this is not a robust procedure. It works only if
8662 your document is never included as part of another
8663 document that is designed to have a separate function index; if your
8664 document were to be included with such a document, the functions from
8665 your document and those from the other would not end up together.
8666 Also, to make your function names appear in the right font in the
8667 concept index, you would need to enclose every one of them between
8668 the braces of @code{@@code}.@refill
8671 * syncodeindex:: How to merge two indices, using @code{@@code}
8672 font for the merged-from index.
8673 * synindex:: How to merge two indices, using the
8674 default font of the merged-to index.
8677 @node syncodeindex, synindex, Combining Indices, Combining Indices
8678 @subsection @code{@@syncodeindex}
8679 @findex syncodeindex
8681 When you want to combine functions and concepts into one index, you
8682 should index the functions with @code{@@findex} and index the concepts
8683 with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8684 redirect the function index entries into the concept index.@refill
8685 @findex syncodeindex
8687 The @code{@@syncodeindex} command takes two arguments; they are the name
8688 of the index to redirect, and the name of the index to redirect it to.
8689 The template looks like this:@refill
8692 @@syncodeindex @var{from} @var{to}
8695 @cindex Predefined names for indices
8696 @cindex Two letter names for indices
8697 @cindex Indices, two letter names
8698 @cindex Names for indices
8699 For this purpose, the indices are given two-letter names:@refill
8716 Write an @code{@@syncodeindex} command before or shortly after the
8717 end-of-header line at the beginning of a Texinfo file. For example,
8718 to merge a function index with a concept index, write the
8722 @@syncodeindex fn cp
8726 This will cause all entries designated for the function index to merge
8727 in with the concept index instead.@refill
8729 To merge both a variables index and a function index into a concept
8730 index, write the following:@refill
8734 @@syncodeindex vr cp
8735 @@syncodeindex fn cp
8739 @cindex Fonts for indices
8740 The @code{@@syncodeindex} command puts all the entries from the `from'
8741 index (the redirected index) into the @code{@@code} font, overriding
8742 whatever default font is used by the index to which the entries are
8743 now directed. This way, if you direct function names from a function
8744 index into a concept index, all the function names are printed in the
8745 @code{@@code} font as you would expect.@refill
8747 @node synindex, , syncodeindex, Combining Indices
8748 @subsection @code{@@synindex}
8751 The @code{@@synindex} command is nearly the same as the
8752 @code{@@syncodeindex} command, except that it does not put the
8753 `from' index entries into the @code{@@code} font; rather it puts
8754 them in the roman font. Thus, you use @code{@@synindex} when you
8755 merge a concept index into a function index.@refill
8757 @xref{Printing Indices & Menus}, for information about printing an index
8758 at the end of a book or creating an index menu in an Info file.@refill
8760 @node New Indices, , Combining Indices, Indices
8761 @section Defining New Indices
8762 @cindex Defining new indices
8763 @cindex Indices, defining new
8764 @cindex New index defining
8766 @findex defcodeindex
8768 In addition to the predefined indices, you may use the
8769 @code{@@defindex} and @code{@@defcodeindex} commands to define new
8770 indices. These commands create new indexing @@-commands with which
8771 you mark index entries. The @code{@@defindex }command is used like
8775 @@defindex @var{name}
8778 The name of an index should be a two letter word, such as @samp{au}.
8785 This defines a new index, called the @samp{au} index. At the same
8786 time, it creates a new indexing command, @code{@@auindex}, that you
8787 can use to make index entries. Use the new indexing command just as
8788 you would use a predefined indexing command.@refill
8790 For example, here is a section heading followed by a concept index
8791 entry and two @samp{au} index entries.@refill
8794 @@section Cognitive Semantics
8795 @@cindex kinesthetic image schemas
8796 @@auindex Johnson, Mark
8797 @@auindex Lakoff, George
8801 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
8802 Texinfo constructs the new indexing command by concatenating the name
8803 of the index with @samp{index}; thus, defining an @samp{au} index
8804 leads to the automatic creation of an @code{@@auindex} command.@refill
8806 Use the @code{@@printindex} command to print the index, as you do with
8807 the predefined indices. For example:@refill
8811 @@node Author Index, Subject Index, , Top
8812 @@unnumbered Author Index
8818 The @code{@@defcodeindex} is like the @code{@@defindex} command, except
8819 that, in the printed output, it prints entries in an @code{@@code} font
8820 instead of a roman font. Thus, it parallels the @code{@@findex} command
8821 rather than the @code{@@cindex} command.@refill
8823 You should define new indices within or right after the end-of-header
8824 line of a Texinfo file, before any @code{@@synindex} or
8825 @code{@@syncodeindex} commands (@pxref{Header}).@refill
8828 @chapter Special Insertions
8829 @cindex Inserting special characters and symbols
8830 @cindex Special insertions
8832 Texinfo provides several commands for inserting characters that have
8833 special meaning in Texinfo, such as braces, and for other graphic
8834 elements that do not correspond to simple characters you can type.
8840 @item Braces and @samp{@@}.
8841 @item Whitespace within and around a sentence.
8843 @item Dots and bullets.
8844 @item The @TeX{} logo and the copyright symbol.
8845 @item The pounds currency symbol.
8846 @item The minus sign.
8847 @item Mathematical expressions.
8848 @item Glyphs for evaluation, macros, errors, etc.
8855 * Braces Atsigns:: How to insert braces, @samp{@@}.
8856 * Inserting Space:: How to insert the right amount of space
8858 * Inserting Accents:: How to insert accents and special characters.
8859 * Dots Bullets:: How to insert dots and bullets.
8860 * TeX and copyright:: How to insert the @TeX{} logo
8861 and the copyright symbol.
8862 * pounds:: How to insert the pounds currency symbol.
8863 * minus:: How to insert a minus sign.
8864 * math:: How to format a mathematical expression.
8865 * Glyphs:: How to indicate results of evaluation,
8866 expansion of macros, errors, etc.
8867 * Footnotes:: How to include footnotes.
8868 * Images:: How to include graphics.
8872 @node Braces Atsigns, Inserting Space, Insertions, Insertions
8873 @section Inserting @@ and Braces
8874 @cindex Inserting @@, braces
8875 @cindex Braces, inserting
8876 @cindex Special characters, commands to insert
8877 @cindex Commands to insert special characters
8879 @samp{@@} and curly braces are special characters in Texinfo. To insert
8880 these characters so they appear in text, you must put an @samp{@@} in
8881 front of these characters to prevent Texinfo from misinterpreting
8884 Do not put braces after any of these commands; they are not
8888 * Inserting An Atsign:: How to insert @samp{@@}.
8889 * Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
8892 @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
8893 @subsection Inserting @samp{@@} with @@@@
8894 @findex @@ @r{(single @samp{@@})}
8896 @code{@@@@} stands for a single @samp{@@} in either printed or Info
8899 Do not put braces after an @code{@@@@} command.
8902 @node Inserting Braces
8903 @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
8904 @findex @{ @r{(single @samp{@{})}
8905 @findex @} @r{(single @samp{@}})}
8907 @code{@@@{} stands for a single @samp{@{} in either printed or Info
8910 @code{@@@}} stands for a single @samp{@}} in either printed or Info
8913 Do not put braces after either an @code{@@@{} or an @code{@@@}}
8917 @node Inserting Space
8918 @section Inserting Space
8920 @cindex Inserting space
8921 @cindex Spacing, inserting
8922 The following sections describe commands that control spacing of various
8923 kinds within and after sentences.
8926 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
8927 * Ending a Sentence:: Sometimes it does.
8928 * Multiple Spaces:: Inserting multiple spaces.
8929 * dmn:: How to format a dimension.
8933 @node Not Ending a Sentence
8934 @subsection Not Ending a Sentence
8936 @cindex Not ending a sentence
8937 @cindex Sentence non-ending punctuation
8938 @cindex Periods, inserting
8939 Depending on whether a period or exclamation point or question mark is
8940 inside or at the end of a sentence, less or more space is inserted after
8941 a period in a typeset manual. Since it is not always possible
8942 to determine when a period ends a sentence and when it is used
8943 in an abbreviation, special commands are needed in some circumstances.
8944 Usually, Texinfo can guess how to handle periods, so you do not need to
8945 use the special commands; you just enter a period as you would if you
8946 were using a typewriter, which means you put two spaces after the
8947 period, question mark, or exclamation mark that ends a sentence.
8949 @findex : @r{(suppress widening)}
8950 Use the @code{@@:}@: command after a period, question mark,
8951 exclamation mark, or colon that should not be followed by extra space.
8952 For example, use @code{@@:}@: after periods that end abbreviations
8953 which are not at the ends of sentences.
8958 The s.o.p.@@: has three parts @dots{}
8959 The s.o.p. has three parts @dots{}
8967 produces the following. If you look carefully at this printed output,
8968 you will see a little more whitespace after @samp{s.o.p.} in the second
8973 The s.o.p.@: has three parts @dots{}@*
8974 The s.o.p. has three parts @dots{}
8978 (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
8981 @code{@@:} has no effect on the Info output. Do not put braces after
8985 @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
8986 @subsection Ending a Sentence
8988 @cindex Ending a Sentence
8989 @cindex Sentence ending punctuation
8991 @findex . @r{(end of sentence)}
8992 @findex ! @r{(end of sentence)}
8993 @findex ? @r{(end of sentence)}
8994 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
8995 exclamation point, and @code{@@?}@: instead of a question mark at the end
8996 of a sentence that ends with a single capital letter. Otherwise, @TeX{}
8997 will think the letter is an abbreviation and will not insert the correct
8998 end-of-sentence spacing. Here is an example:
9001 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
9002 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9010 produces the following. If you look carefully at this printed output,
9011 you will see a little more whitespace after the @samp{W} in the first
9016 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
9017 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9020 In the Info file output, @code{@@.}@: is equivalent to a simple
9021 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
9023 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
9024 work well with the Emacs sentence motion commands (@pxref{Sentences,,,
9025 emacs, The GNU Emacs Manual}).
9027 Do not put braces after any of these commands.
9030 @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
9031 @subsection Multiple Spaces
9033 @cindex Multiple spaces
9034 @cindex Whitespace, inserting
9035 @cindex Space, inserting horizontal
9040 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
9041 and newline) into a single space. Info output, on the other hand,
9042 preserves whitespace as you type it, except for changing a newline into
9043 a space; this is why it is important to put two spaces at the end of
9044 sentences in Texinfo documents.
9046 Occasionally, you may want to actually insert several consecutive
9047 spaces, either for purposes of example (what your program does with
9048 multiple spaces as input), or merely for purposes of appearance in
9049 headings or lists. Texinfo supports three commands:
9050 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
9051 which insert a single space into the output. (Here,
9052 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
9053 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
9054 character and end-of-line, i.e., when @samp{@@} is the last character on
9070 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
9071 @code{@@multitable} (@pxref{Multi-column Tables}).
9073 Do not follow any of these commands with braces.
9077 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
9078 @cindex Thin space between number, dimension
9079 @cindex Dimension formatting
9080 @cindex Format a dimension
9083 At times, you may want to write @samp{12@dmn{pt}} or
9084 @samp{8.5@dmn{in}} with little or no space between the number and the
9085 abbreviation for the dimension. You can use the @code{@@dmn} command
9086 to do this. On seeing the command, @TeX{} inserts just enough space
9087 for proper typesetting; the Info formatting commands insert no space
9088 at all, since the Info file does not require it.
9090 To use the @code{@@dmn} command, write the number and then follow it
9091 immediately, with no intervening space, by @code{@@dmn}, and then by
9092 the dimension within braces. For example,
9095 A4 paper is 8.27@@dmn@{in@} wide.
9102 A4 paper is 8.27@dmn{in} wide.
9105 Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
9106 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
9107 In these cases, however, the formatters may insert a line break between
9108 the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
9109 you write a period after an abbreviation within a sentence, you should
9110 write @samp{@@:} after the period to prevent @TeX{} from inserting extra
9111 whitespace, as shown here. @xref{Not Ending a Sentence}.
9114 @node Inserting Accents
9115 @section Inserting Accents
9117 @cindex Inserting accents
9118 @cindex Accents, inserting
9119 @cindex Floating accents, inserting
9121 Here is a table with the commands Texinfo provides for inserting
9122 floating accents. The commands with non-alphabetic names do not take
9123 braces around their argument (which is taken to be the next character).
9124 (Exception: @code{@@,} @emph{does} take braces around its argument.)
9125 This is so as to make the source as convenient to type and read as
9126 possible, since accented characters are very common in some languages.
9129 @cindex Umlaut accent
9131 @cindex Acute accent
9133 @cindex Macron accent
9135 @cindex Circumflex accent
9137 @cindex Grave accent
9139 @cindex Tilde accent
9141 @cindex Cedilla accent
9145 @cindex Hungarian umlaut accent
9149 @cindex Tie-after accent
9151 @cindex Breve accent
9153 @cindex Underbar accent
9155 @cindex Underdot accent
9157 @cindex Check accent
9158 @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9159 @item Command @tab Output @tab What
9160 @item @t{@@"o} @tab @"o @tab umlaut accent
9161 @item @t{@@'o} @tab @'o @tab acute accent
9162 @item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9163 @item @t{@@=o} @tab @=o @tab macron/overbar accent
9164 @item @t{@@^o} @tab @^o @tab circumflex accent
9165 @item @t{@@`o} @tab @`o @tab grave accent
9166 @item @t{@@~o} @tab @~o @tab tilde accent
9167 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
9168 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
9169 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9170 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9171 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent
9172 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9173 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9174 @item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent
9177 This table lists the Texinfo commands for inserting other characters
9178 commonly used in languages other than English.
9180 @findex questiondown
9181 @cindex @questiondown{}
9183 @cindex @exclamdown{}
9195 @cindex Dotless i, j
9213 @multitable {x@@questiondown@{@} } {oe,OE} {es-zet or sharp S}
9214 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
9215 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9216 @item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle
9217 @item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures
9218 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
9219 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
9220 @item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l
9221 @item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash
9222 @item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures
9223 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
9228 @section Inserting Ellipsis and Bullets
9229 @cindex Dots, inserting
9230 @cindex Bullets, inserting
9231 @cindex Ellipsis, inserting
9232 @cindex Inserting ellipsis
9233 @cindex Inserting dots
9234 @cindex Special typesetting commands
9235 @cindex Typesetting commands for dots, etc.
9237 An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9238 periods, so a special command is used for ellipsis in Texinfo. The
9239 @code{@@bullet} command is special, too. Each of these commands is
9240 followed by a pair of braces, @samp{@{@}}, without any whitespace
9241 between the name of the command and the braces. (You need to use braces
9242 with these commands because you can use them next to other text; without
9243 the braces, the formatters would be confused. @xref{Command Syntax, ,
9244 @@-Command Syntax}, for further information.)@refill
9247 * dots:: How to insert dots @dots{}
9248 * bullet:: How to insert a bullet.
9253 @subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
9256 @cindex Inserting dots
9257 @cindex Dots, inserting
9259 Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9260 three dots in a row, appropriately spaced, like this: `@dots{}'. Do
9261 not simply write three periods in the input file; that would work for
9262 the Info file output, but would produce the wrong amount of space
9263 between the periods in the printed manual.
9265 Similarly, the @code{@@enddots@{@}} command generates an
9266 end-of-sentence ellipsis (four dots) @enddots{}
9269 Here is an ellipsis: @dots{}
9270 Here are three periods in a row: ...
9272 In printed output, the three periods in a row are closer together than
9273 the dots in the ellipsis.
9278 @subsection @code{@@bullet}@{@} (@bullet{})
9281 Use the @code{@@bullet@{@}} command to generate a large round dot, or
9282 the closest possible thing to one. In Info, an asterisk is used.@refill
9284 Here is a bullet: @bullet{}
9286 When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9287 type the braces, because @code{@@itemize} supplies them.
9288 (@xref{itemize, , @code{@@itemize}}.)@refill
9291 @node TeX and copyright, pounds, Dots Bullets, Insertions
9292 @section Inserting @TeX{} and the Copyright Symbol
9294 The logo `@TeX{}' is typeset in a special fashion and it needs an
9295 @@-command. The copyright symbol, `@copyright{}', is also special.
9296 Each of these commands is followed by a pair of braces, @samp{@{@}},
9297 without any whitespace between the name of the command and the
9301 * tex:: How to insert the @TeX{} logo.
9302 * copyright symbol:: How to use @code{@@copyright}@{@}.
9307 @subsection @code{@@TeX}@{@} (@TeX{})
9308 @findex tex (command)
9310 Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
9311 manual, this is a special logo that is different from three ordinary
9312 letters. In Info, it just looks like @samp{TeX}. The
9313 @code{@@TeX@{@}} command is unique among Texinfo commands in that the
9314 @samp{T} and the @samp{X} are in upper case.@refill
9317 @node copyright symbol
9318 @subsection @code{@@copyright}@{@} (@copyright{})
9321 Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
9322 a printed manual, this is a @samp{c} inside a circle, and in Info,
9323 this is @samp{(C)}.@refill
9326 @node pounds, minus, TeX and copyright, Insertions
9327 @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
9330 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a
9331 printed manual, this is the symbol for the currency pounds sterling.
9332 In Info, it is a @samp{#}. Other currency symbols are unfortunately not
9336 @node minus, math, pounds, Insertions
9337 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9340 Use the @code{@@minus@{@}} command to generate a minus sign. In a
9341 fixed-width font, this is a single hyphen, but in a proportional font,
9342 the symbol is the customary length for a minus sign---a little longer
9343 than a hyphen, shorter than an em-dash:
9346 @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9348 `-' is a hyphen generated with the character @samp{-},
9350 `---' is an em-dash for text.
9354 In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9357 You should not use @code{@@minus@{@}} inside @code{@@code} or
9358 @code{@@example} because the width distinction is not made in the
9359 fixed-width font they use.
9361 When you use @code{@@minus} to specify the mark beginning each entry in
9362 an itemized list, you do not need to type the braces
9363 (@pxref{itemize, , @code{@@itemize}}.)
9366 @node math, Glyphs, minus, Insertions
9367 @section @code{@@math}: Inserting Mathematical Expressions
9369 @cindex Mathematical expressions
9371 You can write a short mathematical expression with the @code{@@math}
9372 command. Write the mathematical expression between braces, like this:
9375 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9381 This produces the following in @TeX{}:
9384 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
9388 and the following in Info:
9392 This produces the following in Info:
9396 (a + b)(a + b) = a^2 + 2ab + b^2
9399 Thus, the @code{@@math} command has no effect on the Info output.
9401 For complex mathematical expressions, you can also use @TeX{} directly
9402 (@pxref{Raw Formatter Commands}). When you use @TeX{} directly,
9403 remember to write the mathematical expression between one or two
9404 @samp{$} (dollar-signs) as appropriate.
9408 @section Glyphs for Examples
9411 In Texinfo, code is often illustrated in examples that are delimited
9412 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9413 @code{@@end lisp}. In such examples, you can indicate the results of
9414 evaluation or an expansion using @samp{@result{}} or
9415 @samp{@expansion{}}. Likewise, there are commands to insert glyphs
9417 printed output, error messages, equivalence of expressions, and the
9418 location of point.@refill
9420 The glyph-insertion commands do not need to be used within an example, but
9421 most often they are. Every glyph-insertion command is followed by a pair of
9422 left- and right-hand braces.@refill
9426 * result:: How to show the result of expression.
9427 * expansion:: How to indicate an expansion.
9428 * Print Glyph:: How to indicate printed output.
9429 * Error Glyph:: How to indicate an error message.
9430 * Equivalence:: How to indicate equivalence.
9431 * Point Glyph:: How to indicate the location of point.
9434 @node Glyphs Summary, result, Glyphs, Glyphs
9436 @subheading Glyphs Summary
9438 Here are the different glyph commands:@refill
9443 @code{@@result@{@}} points to the result of an expression.@refill
9446 @code{@@expansion@{@}} shows the results of a macro expansion.@refill
9449 @code{@@print@{@}} indicates printed output.@refill
9452 @code{@@error@{@}} indicates that the following text is an error
9456 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9459 @code{@@point@{@}} shows the location of point.@refill
9472 @node result, expansion, Glyphs Summary, Glyphs
9473 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9474 @cindex Result of an expression
9475 @cindex Indicating evaluation
9476 @cindex Evaluation glyph
9477 @cindex Value of an expression, indicating
9480 Use the @code{@@result@{@}} command to indicate the result of
9481 evaluating an expression.@refill
9484 The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
9485 as @samp{@result{}} in the printed output.
9488 The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9489 and as a double stemmed arrow in the printed output.@refill
9492 Thus, the following,
9500 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9503 @node expansion, Print Glyph, result, Glyphs
9504 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9505 @cindex Expansion, indicating it
9508 When an expression is a macro call, it expands into a new expression.
9509 You can indicate the result of the expansion with the
9510 @code{@@expansion@{@}} command.@refill
9513 The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
9514 as @samp{@expansion{}} in the printed output.
9517 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9518 in Info and as a long arrow with a flat base in the printed output.@refill
9522 For example, the following
9528 @@expansion@{@} (car (cdr (cdr '(a b c))))
9540 @expansion{} (car (cdr (cdr '(a b c))))
9546 which may be read as:
9549 @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9550 the result of evaluating the expression is @code{c}.
9554 Often, as in this case, an example looks better if the
9555 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9559 @node Print Glyph, Error Glyph, expansion, Glyphs
9560 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9561 @cindex Printed output, indicating it
9564 Sometimes an expression will print output during its execution. You
9565 can indicate the printed output with the @code{@@print@{@}} command.@refill
9568 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
9569 as @samp{@print{}} in the printed output.
9572 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9573 and similarly, as a horizontal dash butting against a vertical bar, in
9574 the printed output.@refill
9577 In the following example, the printed text is indicated with
9578 @samp{@print{}}, and the value of the expression follows on the
9583 (progn (print 'foo) (print 'bar))
9591 In a Texinfo source file, this example is written as follows:
9596 (progn (print 'foo) (print 'bar))
9605 @node Error Glyph, Equivalence, Print Glyph, Glyphs
9606 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9607 @cindex Error message, indicating it
9610 A piece of code may cause an error when you evaluate it. You can
9611 designate the error message with the @code{@@error@{@}} command.@refill
9614 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
9615 and as @samp{@error{}} in the printed output.
9618 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9619 and as the word `error' in a box in the printed output.@refill
9628 @@error@{@} Wrong type argument: integer-or-marker-p, x
9637 @error{} Wrong type argument: integer-or-marker-p, x
9641 This indicates that the following error message is printed
9642 when you evaluate the expression:
9645 Wrong type argument: integer-or-marker-p, x
9648 @samp{@error{}} itself is not part of the error message.
9651 @node Equivalence, Point Glyph, Error Glyph, Glyphs
9652 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9653 @cindex Equivalence, indicating it
9656 Sometimes two expressions produce identical results. You can indicate the
9657 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9660 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
9661 as @samp{@equiv{}} in the printed output.
9664 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9665 and as a three parallel horizontal lines in the printed output.@refill
9672 (make-sparse-keymap) @@equiv@{@} (list 'keymap)
9680 (make-sparse-keymap) @equiv{} (list 'keymap)
9684 This indicates that evaluating @code{(make-sparse-keymap)} produces
9685 identical results to evaluating @code{(list 'keymap)}.
9689 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9690 @cindex Point, indicating in a buffer
9693 Sometimes you need to show an example of text in an Emacs buffer. In
9694 such examples, the convention is to include the entire contents of the
9695 buffer in question between two lines of dashes containing the buffer
9698 You can use the @samp{@@point@{@}} command to show the location of point
9699 in the text in the buffer. (The symbol for point, of course, is not
9700 part of the text in the buffer; it indicates the place @emph{between}
9701 two characters where point is located.)@refill
9704 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
9705 as @samp{@point{}} in the printed output.
9708 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9709 and as a small five pointed star in the printed output.@refill
9712 The following example shows the contents of buffer @file{foo} before
9713 and after evaluating a Lisp command to insert the word @code{changed}.@refill
9717 ---------- Buffer: foo ----------
9718 This is the @point{}contents of foo.
9719 ---------- Buffer: foo ----------
9728 ---------- Buffer: foo ----------
9729 This is the changed @point{}contents of foo.
9730 ---------- Buffer: foo ----------
9735 In a Texinfo source file, the example is written like this:@refill
9739 ---------- Buffer: foo ----------
9740 This is the @@point@{@}contents of foo.
9741 ---------- Buffer: foo ----------
9745 ---------- Buffer: foo ----------
9746 This is the changed @@point@{@}contents of foo.
9747 ---------- Buffer: foo ----------
9757 A @dfn{footnote} is for a reference that documents or elucidates the
9758 primary text.@footnote{A footnote should complement or expand upon
9759 the primary text, but a reader should not need to read a footnote to
9760 understand the primary text. For a thorough discussion of footnotes,
9761 see @cite{The Chicago Manual of Style}, which is published by the
9762 University of Chicago Press.}@refill
9765 * Footnote Commands:: How to write a footnote in Texinfo.
9766 * Footnote Styles:: Controlling how footnotes appear in Info.
9769 @node Footnote Commands
9770 @subsection Footnote Commands
9772 In Texinfo, footnotes are created with the @code{@@footnote} command.
9773 This command is followed immediately by a left brace, then by the text
9774 of the footnote, and then by a terminating right brace. Footnotes may
9775 be of any length (they will be broken across pages if necessary), but
9776 are usually short. The template is:
9779 ordinary text@@footnote@{@var{text of footnote}@}
9782 As shown here, the @code{@@footnote} command should come right after the
9783 text being footnoted, with no intervening space; otherwise, the footnote
9784 marker might end up starting a line.
9786 For example, this clause is followed by a sample footnote@footnote{Here
9787 is the sample footnote.}; in the Texinfo source, it looks like
9791 @dots{}a sample footnote@@footnote@{Here is the sample
9792 footnote.@}; in the Texinfo source@dots{}
9795 In a printed manual or book, the reference mark for a footnote is a
9796 small, superscripted number; the text of the footnote appears at the
9797 bottom of the page, below a horizontal line.@refill
9799 In Info, the reference mark for a footnote is a pair of parentheses
9800 with the footnote number between them, like this: @samp{(1)}. The
9801 reference mark is followed by a cross-reference link to the footnote's
9804 In the HTML output, footnote references are marked with a small,
9805 superscripted number which is rendered as a hypertext link to the
9808 By the way, footnotes in the argument of an @code{@@item} command for a
9809 @code{@@table} must be on the same line as the @code{@@item}
9810 (as usual). @xref{Two-column Tables}.
9813 @node Footnote Styles
9814 @subsection Footnote Styles
9816 Info has two footnote styles, which determine where the text of the
9817 footnote is located:@refill
9820 @cindex @samp{@r{End}} node footnote style
9822 In the `End' node style, all the footnotes for a single node
9823 are placed at the end of that node. The footnotes are separated from
9824 the rest of the node by a line of dashes with the word
9825 @samp{Footnotes} within it. Each footnote begins with an
9826 @samp{(@var{n})} reference mark.@refill
9830 Here is an example of a single footnote in the end of node style:@refill
9834 --------- Footnotes ---------
9836 (1) Here is a sample footnote.
9840 @cindex @samp{@r{Separate}} footnote style
9842 In the `Separate' node style, all the footnotes for a single
9843 node are placed in an automatically constructed node of
9844 their own. In this style, a ``footnote reference'' follows
9845 each @samp{(@var{n})} reference mark in the body of the
9846 node. The footnote reference is actually a cross reference
9847 which you use to reach the footnote node.@refill
9849 The name of the node with the footnotes is constructed
9850 by appending @w{@samp{-Footnotes}} to the name of the node
9851 that contains the footnotes. (Consequently, the footnotes'
9852 node for the @file{Footnotes} node is
9853 @w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
9854 `Up' node pointer that leads back to its parent node.@refill
9857 Here is how the first footnote in this manual looks after being
9858 formatted for Info in the separate node style:@refill
9862 File: texinfo.info Node: Overview-Footnotes, Up: Overview
9864 (1) The first syllable of "Texinfo" is pronounced like "speck", not
9870 A Texinfo file may be formatted into an Info file with either footnote
9873 @findex footnotestyle
9874 Use the @code{@@footnotestyle} command to specify an Info file's
9875 footnote style. Write this command at the beginning of a line followed
9876 by an argument, either @samp{end} for the end node style or
9877 @samp{separate} for the separate node style.
9888 @@footnotestyle separate
9891 Write an @code{@@footnotestyle} command before or shortly after the
9892 end-of-header line at the beginning of a Texinfo file. (If you
9893 include the @code{@@footnotestyle} command between the start-of-header
9894 and end-of-header lines, the region formatting commands will format
9895 footnotes as specified.)@refill
9897 If you do not specify a footnote style, the formatting commands use
9898 their default style. Currently, @code{texinfo-format-buffer} and
9899 @code{texinfo-format-region} use the `separate' style and
9900 @code{makeinfo} uses the `end' style.@refill
9902 @c !!! note: makeinfo's --footnote-style option overrides footnotestyle
9904 If you use @code{makeinfo} to create the Info file, the
9905 @samp{--footnote-style} option determines which style is used,
9906 @samp{end} for the end of node style or @samp{separate} for the
9907 separate node style. Thus, to format the Texinfo manual in the
9908 separate node style, you would use the following shell command:@refill
9911 makeinfo --footnote-style=separate texinfo.texi
9915 To format the Texinfo manual in the end of node style, you would
9919 makeinfo --footnote-style=end texinfo.texi
9923 If you use @code{texinfo-format-buffer} or
9924 @code{texinfo-format-region} to create the Info file, the value of the
9925 @code{texinfo-footnote-style} variable controls the footnote style.
9926 It can be either @samp{"separate"} for the separate node style or
9927 @samp{"end"} for the end of node style. (You can change the value of
9928 this variable with the @kbd{M-x edit-options} command (@pxref{Edit
9929 Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or
9930 with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
9931 and Setting Variables, emacs, The GNU Emacs Manual}).@refill
9933 The @code{texinfo-footnote-style} variable also controls the style if
9934 you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
9935 command in Emacs.@refill
9938 This chapter contains two footnotes.@refill
9942 @c this should be described with figures when we have them
9943 @c perhaps in the quotation/example chapter.
9945 @section Inserting Images
9947 @cindex Images, inserting
9948 @cindex Pictures, inserting
9951 You can insert an image given in an external file with the
9952 @code{@@image} command:
9955 @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}@}
9958 @cindex Formats for images
9959 @cindex Image formats
9960 The @var{filename} argument is mandatory, and must not have an
9961 extension, because the different processors support different formats:
9964 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
9967 @pindex pdftex@r{, and images}
9968 PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
9970 @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
9971 Info output (more or less as if it was an @code{@@example}).
9973 @cindex GIF, unsupported due to patents
9974 @cindex PNG image format
9975 @cindex JPEG image format
9976 @code{makeinfo} producing HTML output tries @file{@var{filename}.png};
9977 if that does not exist, it tries @file{@var{filename}.jpg}. If that
9978 does not exist either, it complains. (We cannot support GIF format due
9982 @cindex Width of images
9983 @cindex Height of images
9984 @cindex Aspect ratio of images
9985 @cindex Distorting images
9986 The optional @var{width} and @var{height} arguments specify the size to
9987 scale the image to (they are ignored for Info output). If neither is
9988 specified, the image is presented in its natural size (given in the
9989 file); if only one is specified, the other is scaled proportionately;
9990 and if both are specified, both are respected, thus possibly distorting
9991 the original image by changing its aspect ratio.
9993 @cindex Dimensions and image sizes
9994 The @var{width} and @var{height} may be specified using any valid @TeX{}
9999 @cindex Points (dimension)
10000 point (72.27pt = 1in)
10006 big point (72bp = 1in)
10011 @cindex Centimeters
10012 centimeter (2.54cm = 1in)
10014 @cindex Millimeters
10015 millimeter (10mm = 1cm)
10017 @cindex Did@^ot points
10018 did@^ot point (1157dd = 1238pt)
10021 cicero (1cc = 12dd)
10023 @cindex Scaled points
10024 scaled point (65536sp = 1pt)
10028 For example, the following will scale a file @file{ridt.eps} to one
10029 inch vertically, with the width scaled proportionately:
10032 @@image@{ridt,,1in@}
10036 For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
10037 installed somewhere that @TeX{} can find it. (The standard location is
10038 @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
10039 root of your @TeX{} directory tree.) This file is included in the
10040 Texinfo distribution and is available from
10041 @uref{ftp://tug.org/tex/epsf.tex}.
10043 @code{@@image} can be used within a line as well as for displayed
10044 figures. Therefore, if you intend it to be displayed, be sure to leave
10045 a blank line before the command, or the output will run into the
10050 @chapter Making and Preventing Breaks
10051 @cindex Making line and page breaks
10052 @cindex Preventing line and page breaks
10054 Usually, a Texinfo file is processed both by @TeX{} and by one of the
10055 Info formatting commands. Line, paragraph, or page breaks sometimes
10056 occur in the `wrong' place in one or other form of output. You must
10057 ensure that text looks right both in the printed manual and in the
10060 For example, in a printed manual, page breaks may occur awkwardly in
10061 the middle of an example; to prevent this, you can hold text together
10062 using a grouping command that keeps the text from being split across
10063 two pages. Conversely, you may want to force a page break where none
10064 would occur normally. Fortunately, problems like these do not often
10065 arise. When they do, use the break, break prevention, or pagination
10069 * Break Commands:: Cause and prevent splits.
10070 * Line Breaks:: How to force a single line to use two lines.
10071 * - and hyphenation:: How to tell TeX about hyphenation points.
10072 * w:: How to prevent unwanted line breaks.
10073 * sp:: How to insert blank lines.
10074 * page:: How to force the start of a new page.
10075 * group:: How to prevent unwanted page breaks.
10076 * need:: Another way to prevent unwanted page breaks.
10079 @node Break Commands, Line Breaks, Breaks, Breaks
10081 @heading Break Commands
10084 The break commands create or allow line and paragraph breaks:@refill
10088 Force a line break.
10091 Skip @var{n} blank lines.@refill
10094 Insert a discretionary hyphen.
10096 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
10097 Define hyphen points in @var{hy-phen-a-ted words}.
10100 The line-break-prevention command holds text together all on one
10104 @item @@w@{@var{text}@}
10105 Prevent @var{text} from being split and hyphenated across two lines.@refill
10111 The pagination commands apply only to printed output, since Info
10112 files do not have pages.@refill
10116 Start a new page in the printed manual.@refill
10119 Hold text together that must appear on one printed page.@refill
10121 @item @@need @var{mils}
10122 Start a new printed page if not enough space on this one.@refill
10125 @node Line Breaks, - and hyphenation, Break Commands, Breaks
10126 @comment node-name, next, previous, up
10127 @section @code{@@*}: Generate Line Breaks
10128 @findex * @r{(force line break)}
10129 @cindex Line breaks
10130 @cindex Breaks in a line
10132 The @code{@@*} command forces a line break in both the printed manual and
10139 This line @@* is broken @@*in two places.
10154 (Note that the space after the first @code{@@*} command is faithfully
10155 carried down to the next line.)@refill
10158 The @code{@@*} command is often used in a file's copyright page:@refill
10162 This is edition 2.0 of the Texinfo documentation,@@*
10168 In this case, the @code{@@*} command keeps @TeX{} from stretching the
10169 line across the whole page in an ugly manner.@refill
10172 @strong{Please note:} Do not write braces after an @code{@@*} command;
10173 they are not needed.@refill
10175 Do not write an @code{@@refill} command at the end of a paragraph
10176 containing an @code{@@*} command; it will cause the paragraph to be
10177 refilled after the line break occurs, negating the effect of the line
10181 @node - and hyphenation, w, Line Breaks, Breaks
10182 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
10185 @findex hyphenation
10186 @cindex Hyphenation, helping @TeX{} do
10187 @cindex Fine-tuning, and hyphenation
10189 Although @TeX{}'s hyphenation algorithm is generally pretty good, it
10190 does miss useful hyphenation points from time to time. (Or, far more
10191 rarely, insert an incorrect hyphenation.) So, for documents with an
10192 unusual vocabulary or when fine-tuning for a printed edition, you may
10193 wish to help @TeX{} out. Texinfo supports two commands for this:
10197 Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
10198 not have to) hyphenate. This is especially useful when you notice
10199 an overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
10200 hboxes}). @TeX{} will not insert any hyphenation points in a word
10201 containing @code{@@-}.
10203 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
10204 Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
10205 put a @samp{-} at each hyphenation point. For example:
10207 @@hyphenation@{man-u-script man-u-scripts@}
10209 @noindent @TeX{} only uses the specified hyphenation points when the
10210 words match exactly, so give all necessary variants.
10213 Info output is not hyphenated, so these commands have no effect there.
10216 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
10217 @findex w @r{(prevent line break)}
10218 @cindex Line breaks, preventing
10219 @cindex Hyphenation, preventing
10221 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
10222 within @var{text}.@refill
10224 You can use the @code{@@w} command to prevent @TeX{} from automatically
10225 hyphenating a long name or phrase that happens to fall near the end of a
10229 You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}.
10236 You can copy GNU software from @w{@samp{ftp.gnu.org}}.
10239 @cindex Non-breakable space
10240 @cindex Unbreakable space
10242 You can also use @code{@@w} to produce a non-breakable space:
10245 None of the formatters will break at this@@w@{ @}space.
10250 @section @code{@@sp} @var{n}: Insert Blank Lines
10251 @findex sp @r{(line spacing)}
10252 @cindex Space, inserting vertical
10253 @cindex Blank lines
10254 @cindex Line spacing
10256 A line beginning with and containing only @code{@@sp @var{n}}
10257 generates @var{n} blank lines of space in both the printed manual and
10258 the Info file. @code{@@sp} also forces a paragraph break. For
10266 generates two blank lines.
10268 The @code{@@sp} command is most often used in the title page.@refill
10271 @c node br, page, sp, Breaks
10272 @comment node-name, next, previous, up
10273 @c section @code{@@br}: Generate Paragraph Breaks
10274 @findex br @r{(paragraph breaks)}
10275 @cindex Paragraph breaks
10276 @cindex Breaks in a paragraph
10278 The @code{@@br} command forces a paragraph break. It inserts a blank
10279 line. You can use the command within or at the end of a line. If
10280 used within a line, the @code{@@br@{@}} command must be followed by
10281 left and right braces (as shown here) to mark the end of the
10289 This line @@br@{@}contains and is ended by paragraph breaks@@br
10290 and is followed by another line.
10301 contains and is ended by paragraph breaks
10303 and is followed by another line.
10307 The @code{@@br} command is seldom used.
10310 @node page, group, sp, Breaks
10311 @comment node-name, next, previous, up
10312 @section @code{@@page}: Start a New Page
10313 @cindex Page breaks
10316 A line containing only @code{@@page} starts a new page in a printed
10317 manual. The command has no effect on Info files since they are not
10318 paginated. An @code{@@page} command is often used in the @code{@@titlepage}
10319 section of a Texinfo file to start the copyright page.@refill
10321 @node group, need, page, Breaks
10322 @comment node-name, next, previous, up
10323 @section @code{@@group}: Prevent Page Breaks
10324 @cindex Group (hold text together vertically)
10325 @cindex Holding text together vertically
10326 @cindex Vertically holding text together
10329 The @code{@@group} command (on a line by itself) is used inside an
10330 @code{@@example} or similar construct to begin an unsplittable vertical
10331 group, which will appear entirely on one page in the printed output.
10332 The group is terminated by a line containing only @code{@@end group}.
10333 These two lines produce no output of their own, and in the Info file
10334 output they have no effect at all.@refill
10336 @c Once said that these environments
10337 @c turn off vertical spacing between ``paragraphs''.
10338 @c Also, quotation used to work, but doesn't in texinfo-2.72
10339 Although @code{@@group} would make sense conceptually in a wide
10340 variety of contexts, its current implementation works reliably only
10341 within @code{@@example} and variants, and within @code{@@display},
10342 @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
10343 @xref{Quotations and Examples}. (What all these commands have in
10344 common is that each line of input produces a line of output.) In
10345 other contexts, @code{@@group} can cause anomalous vertical
10349 This formatting requirement means that you should write:
10362 with the @code{@@group} and @code{@@end group} commands inside the
10363 @code{@@example} and @code{@@end example} commands.
10365 The @code{@@group} command is most often used to hold an example
10366 together on one page. In this Texinfo manual, more than 100 examples
10367 contain text that is enclosed between @code{@@group} and @code{@@end
10370 If you forget to end a group, you may get strange and unfathomable
10371 error messages when you run @TeX{}. This is because @TeX{} keeps
10372 trying to put the rest of the Texinfo file onto the one page and does
10373 not start to generate error messages until it has processed
10374 considerable text. It is a good rule of thumb to look for a missing
10375 @code{@@end group} if you get incomprehensible error messages in
10378 @node need, , group, Breaks
10379 @comment node-name, next, previous, up
10380 @section @code{@@need @var{mils}}: Prevent Page Breaks
10381 @cindex Need space at page bottom
10384 A line containing only @code{@@need @var{n}} starts
10385 a new page in a printed manual if fewer than @var{n} mils (thousandths
10386 of an inch) remain on the current page. Do not use
10387 braces around the argument @var{n}. The @code{@@need} command has no
10388 effect on Info files since they are not paginated.@refill
10391 This paragraph is preceded by an @code{@@need} command that tells
10392 @TeX{} to start a new page if fewer than 800 mils (eight-tenths
10393 inch) remain on the page. It looks like this:@refill
10398 This paragraph is preceded by @dots{}
10402 The @code{@@need} command is useful for preventing orphans (single
10403 lines at the bottoms of printed pages).@refill
10406 @node Definition Commands
10407 @chapter Definition Commands
10408 @cindex Definition commands
10410 The @code{@@deffn} command and the other @dfn{definition commands}
10411 enable you to describe functions, variables, macros, commands, user
10412 options, special forms and other such artifacts in a uniform
10415 In the Info file, a definition causes the entity
10416 category---`Function', `Variable', or whatever---to appear at the
10417 beginning of the first line of the definition, followed by the
10418 entity's name and arguments. In the printed manual, the command
10419 causes @TeX{} to print the entity's name and its arguments on the left
10420 margin and print the category next to the right margin. In both
10421 output formats, the body of the definition is indented. Also, the
10422 name of the entity is entered into the appropriate index:
10423 @code{@@deffn} enters the name into the index of functions,
10424 @code{@@defvr} enters it into the index of variables, and so
10427 A manual need not and should not contain more than one definition for
10428 a given name. An appendix containing a summary should use
10429 @code{@@table} rather than the definition commands.@refill
10432 * Def Cmd Template:: How to structure a description using a
10433 definition command.
10434 * Optional Arguments:: How to handle optional and repeated arguments.
10435 * deffnx:: How to group two or more `first' lines.
10436 * Def Cmds in Detail:: All the definition commands.
10437 * Def Cmd Conventions:: Conventions for writing definitions.
10438 * Sample Function Definition::
10441 @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10442 @section The Template for a Definition
10443 @cindex Definition template
10444 @cindex Template for a definition
10446 The @code{@@deffn} command is used for definitions of entities that
10447 resemble functions. To write a definition using the @code{@@deffn}
10448 command, write the @code{@@deffn} command at the beginning of a line
10449 and follow it on the same line by the category of the entity, the name
10450 of the entity itself, and its arguments (if any). Then write the body
10451 of the definition on succeeding lines. (You may embed examples in the
10452 body.) Finally, end the definition with an @code{@@end deffn} command
10453 written on a line of its own. (The other definition commands follow
10454 the same format.)@refill
10456 The template for a definition looks like this:
10460 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10461 @var{body-of-definition}
10472 @@deffn Command forward-word count
10473 This command moves point forward @@var@{count@} words
10474 (or backward if @@var@{count@} is negative). @dots{}
10483 @deffn Command forward-word count
10484 This function moves point forward @var{count} words
10485 (or backward if @var{count} is negative). @dots{}
10489 Capitalize the category name like a title. If the name of the
10490 category contains spaces, as in the phrase `Interactive Command',
10491 write braces around it. For example:@refill
10495 @@deffn @{Interactive Command@} isearch-forward
10502 Otherwise, the second word will be mistaken for the name of the
10505 Some of the definition commands are more general than others. The
10506 @code{@@deffn} command, for example, is the general definition command
10507 for functions and the like---for entities that may take arguments. When
10508 you use this command, you specify the category to which the entity
10509 belongs. The @code{@@deffn} command possesses three predefined,
10510 specialized variations, @code{@@defun}, @code{@@defmac}, and
10511 @code{@@defspec}, that specify the category for you: ``Function'',
10512 ``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
10513 is an entity much like a function.) The @code{@@defvr} command also is
10514 accompanied by several predefined, specialized variations for describing
10515 particular kinds of variables.@refill
10517 The template for a specialized definition, such as @code{@@defun}, is
10518 similar to the template for a generalized definition, except that you
10519 do not need to specify the category:@refill
10523 @@defun @var{name} @var{arguments}@dots{}
10524 @var{body-of-definition}
10534 @@defun buffer-end flag
10535 This function returns @@code@{(point-min)@} if @@var@{flag@}
10536 is less than 1, @@code@{(point-max)@} otherwise.
10546 @defun buffer-end flag
10547 This function returns @code{(point-min)} if @var{flag} is less than 1,
10548 @code{(point-max)} otherwise. @dots{}
10553 @xref{Sample Function Definition, Sample Function Definition, A Sample
10554 Function Definition}, for a more detailed example of a function
10555 definition, including the use of @code{@@example} inside the
10558 The other specialized commands work like @code{@@defun}.@refill
10560 @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10561 @section Optional and Repeated Arguments
10562 @cindex Optional and repeated arguments
10563 @cindex Repeated and optional arguments
10564 @cindex Arguments, repeated and optional
10565 @cindex Syntax, optional & repeated arguments
10566 @cindex Meta-syntactic chars for arguments
10568 Some entities take optional or repeated arguments, which may be
10569 specified by a distinctive glyph that uses square brackets and
10570 ellipses. For @w{example}, a special form often breaks its argument list
10571 into separate arguments in more complicated ways than a
10572 straightforward function.@refill
10575 An argument enclosed within square brackets is optional.
10577 @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
10578 @var{optional-arg} is optional.
10579 An argument followed by an ellipsis is optional
10580 and may be repeated more than once.
10581 @c This is consistent with Emacs Lisp Reference manual
10582 Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
10583 Parentheses are used when several arguments are grouped
10584 into additional levels of list structure in Lisp.
10586 @c The following looks better in Info (no `r', `samp' and `code'):
10588 An argument enclosed within square brackets is optional.
10589 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10590 An argument followed by an ellipsis is optional
10591 and may be repeated more than once.
10592 @c This is consistent with Emacs Lisp Reference manual
10593 Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10594 Parentheses are used when several arguments are grouped
10595 into additional levels of list structure in Lisp.
10598 Here is the @code{@@defspec} line of an example of an imaginary
10599 special form:@refill
10602 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10610 In this example, the arguments @var{from} and @var{to} are optional,
10611 but must both be present or both absent. If they are present,
10612 @var{inc} may optionally be specified as well. These arguments are
10613 grouped with the argument @var{var} into a list, to distinguish them
10614 from @var{body}, which includes all remaining elements of the
10617 In a Texinfo source file, this @code{@@defspec} line is written like
10618 this (except it would not be split over two lines, as it is in this
10623 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10624 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10629 The function is listed in the Command and Variable Index under
10630 @samp{foobar}.@refill
10632 @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10633 @section Two or More `First' Lines
10634 @cindex Two `First' Lines for @code{@@deffn}
10635 @cindex Grouping two definitions together
10636 @cindex Definitions grouped together
10639 To create two or more `first' or header lines for a definition, follow
10640 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10641 The @code{@@deffnx} command works exactly like @code{@@deffn}
10642 except that it does not generate extra vertical white space between it
10643 and the preceding line.@refill
10650 @@deffn @{Interactive Command@} isearch-forward
10651 @@deffnx @{Interactive Command@} isearch-backward
10652 These two search commands are similar except @dots{}
10660 @deffn {Interactive Command} isearch-forward
10661 @deffnx {Interactive Command} isearch-backward
10662 These two search commands are similar except @dots{}
10665 Each definition command has an `x' form: @code{@@defunx},
10666 @code{@@defvrx}, @code{@@deftypefunx}, etc.
10668 The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10670 @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10671 @section The Definition Commands
10673 Texinfo provides more than a dozen definition commands, all of which
10674 are described in this section.@refill
10676 The definition commands automatically enter the name of the entity in
10677 the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10678 and @code{@@defmac} enter function names in the index of functions;
10679 @code{@@defvr} and @code{@@defvar} enter variable names in the index
10680 of variables.@refill
10682 Although the examples that follow mostly illustrate Lisp, the commands
10683 can be used for other programming languages.@refill
10686 * Functions Commands:: Commands for functions and similar entities.
10687 * Variables Commands:: Commands for variables and similar entities.
10688 * Typed Functions:: Commands for functions in typed languages.
10689 * Typed Variables:: Commands for variables in typed languages.
10690 * Abstract Objects:: Commands for object-oriented programming.
10691 * Data Types:: The definition command for data types.
10694 @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10695 @subsection Functions and Similar Entities
10697 This section describes the commands for describing functions and similar
10702 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10703 The @code{@@deffn} command is the general definition command for
10704 functions, interactive commands, and similar entities that may take
10705 arguments. You must choose a term to describe the category of entity
10706 being defined; for example, ``Function'' could be used if the entity is
10707 a function. The @code{@@deffn} command is written at the beginning of a
10708 line and is followed on the same line by the category of entity being
10709 described, the name of this particular entity, and its arguments, if
10710 any. Terminate the definition with @code{@@end deffn} on a line of its
10714 For example, here is a definition:
10718 @@deffn Command forward-char nchars
10719 Move point forward @@var@{nchars@} characters.
10725 This shows a rather terse definition for a ``command'' named
10726 @code{forward-char} with one argument, @var{nchars}.
10728 @code{@@deffn} prints argument names such as @var{nchars} in italics or
10729 upper case, as if @code{@@var} had been used, because we think of these
10730 names as metasyntactic variables---they stand for the actual argument
10731 values. Within the text of the description, write an argument name
10732 explicitly with @code{@@var} to refer to the value of the argument. In
10733 the example above, we used @samp{@@var@{nchars@}} in this way.
10735 The template for @code{@@deffn} is:
10739 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10740 @var{body-of-definition}
10746 @item @@defun @var{name} @var{arguments}@dots{}
10747 The @code{@@defun} command is the definition command for functions.
10748 @code{@@defun} is equivalent to @samp{@@deffn Function
10757 @@defun set symbol new-value
10758 Change the value of the symbol @@var@{symbol@}
10759 to @@var@{new-value@}.
10765 shows a rather terse definition for a function @code{set} whose
10766 arguments are @var{symbol} and @var{new-value}. The argument names on
10767 the @code{@@defun} line automatically appear in italics or upper case as
10768 if they were enclosed in @code{@@var}. Terminate the definition with
10769 @code{@@end defun} on a line of its own.@refill
10775 @@defun @var{function-name} @var{arguments}@dots{}
10776 @var{body-of-definition}
10781 @code{@@defun} creates an entry in the index of functions.
10784 @item @@defmac @var{name} @var{arguments}@dots{}
10785 The @code{@@defmac} command is the definition command for macros.
10786 @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
10787 works like @code{@@defun}.@refill
10790 @item @@defspec @var{name} @var{arguments}@dots{}
10791 The @code{@@defspec} command is the definition command for special
10792 forms. (In Lisp, a special form is an entity much like a function,
10793 @pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
10794 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
10795 @dots{}} and works like @code{@@defun}.@refill
10798 @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
10799 @subsection Variables and Similar Entities
10801 Here are the commands for defining variables and similar
10806 @item @@defvr @var{category} @var{name}
10807 The @code{@@defvr} command is a general definition command for
10808 something like a variable---an entity that records a value. You must
10809 choose a term to describe the category of entity being defined; for
10810 example, ``Variable'' could be used if the entity is a variable.
10811 Write the @code{@@defvr} command at the beginning of a line and
10812 follow it on the same line by the category of the entity and the
10813 name of the entity.
10815 Capitalize the category name like a title. If the name of the category
10816 contains spaces, as in the name ``User Option'', enclose it in braces.
10817 Otherwise, the second word will be mistaken for the name of the entity.
10822 @@defvr @{User Option@} fill-column
10823 This buffer-local variable specifies
10824 the maximum width of filled lines.
10830 Terminate the definition with @code{@@end defvr} on a line of its
10837 @@defvr @var{category} @var{name}
10838 @var{body-of-definition}
10843 @code{@@defvr} creates an entry in the index of variables for @var{name}.
10846 @item @@defvar @var{name}
10847 The @code{@@defvar} command is the definition command for variables.
10848 @code{@@defvar} is equivalent to @samp{@@defvr Variable
10866 @@defvar @var{name}
10867 @var{body-of-definition}
10872 @code{@@defvar} creates an entry in the index of variables for
10876 @item @@defopt @var{name}
10877 @cindex User options, marking
10878 The @code{@@defopt} command is the definition command for @dfn{user
10879 options}, i.e., variables intended for users to change according to
10880 taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
10881 Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
10882 Option@} @dots{}} and works like @code{@@defvar}.@refill
10886 @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
10887 @subsection Functions in Typed Languages
10889 The @code{@@deftypefn} command and its variations are for describing
10890 functions in languages in which you must declare types of variables and
10891 functions, such as C and C++.
10895 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
10896 The @code{@@deftypefn} command is the general definition command for
10897 functions and similar entities that may take arguments and that are
10898 typed. The @code{@@deftypefn} command is written at the beginning of
10899 a line and is followed on the same line by the category of entity
10900 being described, the type of the returned value, the name of this
10901 particular entity, and its arguments, if any.@refill
10909 @@deftypefn @{Library Function@} int foobar
10910 (int @@var@{foo@}, float @@var@{bar@})
10918 (where the text before the ``@dots{}'', shown above as two lines, would
10919 actually be a single line in a real Texinfo file) produces the following
10924 -- Library Function: int foobar (int FOO, float BAR)
10930 In a printed manual, it produces:
10933 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
10939 This means that @code{foobar} is a ``library function'' that returns an
10940 @code{int}, and its arguments are @var{foo} (an @code{int}) and
10941 @var{bar} (a @code{float}).@refill
10943 The argument names that you write in @code{@@deftypefn} are not subject
10944 to an implicit @code{@@var}---since the actual names of the arguments in
10945 @code{@@deftypefn} are typically scattered among data type names and
10946 keywords, Texinfo cannot find them without help. Instead, you must write
10947 @code{@@var} explicitly around the argument names. In the example
10948 above, the argument names are @samp{foo} and @samp{bar}.@refill
10950 The template for @code{@@deftypefn} is:@refill
10954 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
10955 @var{body-of-description}
10961 Note that if the @var{category} or @var{data type} is more than one
10962 word then it must be enclosed in braces to make it a single argument.@refill
10964 If you are describing a procedure in a language that has packages,
10965 such as Ada, you might consider using @code{@@deftypefn} in a manner
10966 somewhat contrary to the convention described in the preceding
10975 @@deftypefn stacks private push
10976 (@@var@{s@}:in out stack;
10977 @@var@{n@}:in integer)
10984 (The @code{@@deftypefn} arguments are shown split into three lines, but
10985 would be a single line in a real Texinfo file.)
10987 In this instance, the procedure is classified as belonging to the
10988 package @code{stacks} rather than classified as a `procedure' and its
10989 data type is described as @code{private}. (The name of the procedure
10990 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
10992 @code{@@deftypefn} creates an entry in the index of functions for
10995 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
10997 The @code{@@deftypefun} command is the specialized definition command
10998 for functions in typed languages. The command is equivalent to
10999 @samp{@@deftypefn Function @dots{}}.@refill
11007 @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
11014 produces the following in Info:
11018 -- Function: int foobar (int FOO, float BAR)
11026 and the following in a printed manual:
11029 @deftypefun int foobar (int @var{foo}, float @var{bar})
11040 @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
11041 @var{body-of-description}
11046 @code{@@deftypefun} creates an entry in the index of functions for
11052 @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
11053 @subsection Variables in Typed Languages
11055 Variables in typed languages are handled in a manner similar to
11056 functions in typed languages. @xref{Typed Functions}. The general
11057 definition command @code{@@deftypevr} corresponds to
11058 @code{@@deftypefn} and the specialized definition command
11059 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
11063 @item @@deftypevr @var{category} @var{data-type} @var{name}
11064 The @code{@@deftypevr} command is the general definition command for
11065 something like a variable in a typed language---an entity that records
11066 a value. You must choose a term to describe the category of the
11067 entity being defined; for example, ``Variable'' could be used if the
11068 entity is a variable.@refill
11070 The @code{@@deftypevr} command is written at the beginning of a line
11071 and is followed on the same line by the category of the entity
11072 being described, the data type, and the name of this particular
11081 @@deftypevr @{Global Flag@} int enable
11088 produces the following in Info:
11092 -- Global Flag: int enable
11099 and the following in a printed manual:
11102 @deftypevr {Global Flag} int enable
11112 @@deftypevr @var{category} @var{data-type} @var{name}
11113 @var{body-of-description}
11117 @code{@@deftypevr} creates an entry in the index of variables for
11121 @item @@deftypevar @var{data-type} @var{name}
11122 The @code{@@deftypevar} command is the specialized definition command
11123 for variables in typed languages. @code{@@deftypevar} is equivalent
11124 to @samp{@@deftypevr Variable @dots{}}.@refill
11132 @@deftypevar int fubar
11139 produces the following in Info:
11143 -- Variable: int fubar
11151 and the following in a printed manual:
11154 @deftypevar int fubar
11166 @@deftypevar @var{data-type} @var{name}
11167 @var{body-of-description}
11172 @code{@@deftypevar} creates an entry in the index of variables for
11176 @node Abstract Objects
11177 @subsection Object-Oriented Programming
11179 Here are the commands for formatting descriptions about abstract
11180 objects, such as are used in object-oriented programming. A class is
11181 a defined type of abstract object. An instance of a class is a
11182 particular object that has the type of the class. An instance
11183 variable is a variable that belongs to the class but for which each
11184 instance has its own value.@refill
11186 In a definition, if the name of a class is truly a name defined in the
11187 programming system for a class, then you should write an @code{@@code}
11188 around it. Otherwise, it is printed in the usual text font.@refill
11192 @item @@defcv @var{category} @var{class} @var{name}
11193 The @code{@@defcv} command is the general definition command for
11194 variables associated with classes in object-oriented programming. The
11195 @code{@@defcv} command is followed by three arguments: the category of
11196 thing being defined, the class to which it belongs, and its
11201 @@defcv @{Class Option@} Window border-pattern
11208 illustrates how you would write the first line of a definition of the
11209 @code{border-pattern} class option of the class @code{Window}.@refill
11214 @@defcv @var{category} @var{class} @var{name}
11220 @code{@@defcv} creates an entry in the index of variables.
11223 @item @@defivar @var{class} @var{name}
11224 The @code{@@defivar} command is the definition command for instance
11225 variables in object-oriented programming. @code{@@defivar} is
11226 equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
11231 @@defivar @var{class} @var{instance-variable-name}
11232 @var{body-of-definition}
11237 @code{@@defivar} creates an entry in the index of variables.
11239 @findex deftypeivar
11240 @item @@deftypeivar @var{class} @var{data-type} @var{name}
11241 The @code{@@deftypeivar} command is the definition command for typed
11242 instance variables in object-oriented programming. It is similar to
11243 @code{@@defivar} with the addition of the @var{data-type} parameter to
11244 specify the type of the instance variable. @code{@@deftypeivar} creates an
11245 entry in the index of variables.
11248 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11249 The @code{@@defop} command is the general definition command for
11250 entities that may resemble methods in object-oriented programming.
11251 These entities take arguments, as functions do, but are associated with
11252 particular classes of objects.@refill
11254 For example, some systems have constructs called @dfn{wrappers} that
11255 are associated with classes as methods are, but that act more like
11256 macros than like functions. You could use @code{@@defop Wrapper} to
11257 describe one of these.@refill
11259 Sometimes it is useful to distinguish methods and @dfn{operations}.
11260 You can think of an operation as the specification for a method.
11261 Thus, a window system might specify that all window classes have a
11262 method named @code{expose}; we would say that this window system
11263 defines an @code{expose} operation on windows in general. Typically,
11264 the operation has a name and also specifies the pattern of arguments;
11265 all methods that implement the operation must accept the same
11266 arguments, since applications that use the operation do so without
11267 knowing which method will implement it.@refill
11269 Often it makes more sense to document operations than methods. For
11270 example, window application developers need to know about the
11271 @code{expose} operation, but need not be concerned with whether a
11272 given class of windows has its own method to implement this operation.
11273 To describe this operation, you would write:@refill
11276 @@defop Operation windows expose
11279 The @code{@@defop} command is written at the beginning of a line and
11280 is followed on the same line by the overall name of the category of
11281 operation, the name of the class of the operation, the name of the
11282 operation, and its arguments, if any.@refill
11287 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11288 @var{body-of-definition}
11293 @code{@@defop} creates an entry, such as `@code{expose} on
11294 @code{windows}', in the index of functions.@refill
11297 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11298 The @code{@@deftypeop} command is the definition command for typed
11299 operations in object-oriented programming. It is similar to
11300 @code{@@defop} with the addition of the @var{data-type} parameter to
11301 specify the return type of the method. @code{@@deftypeop} creates an
11302 entry in the index of functions.
11304 @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
11306 The @code{@@defmethod} command is the definition command for methods
11307 in object-oriented programming. A method is a kind of function that
11308 implements an operation for a particular class of objects and its
11311 @c ADR: Who cares?!?
11312 @c KB: Oh, I don't know, I think this info is crucial!
11313 In the Lisp Machine, methods actually were functions, but
11314 they were usually defined with @code{defmethod}.
11317 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
11318 The command is written at the beginning of a line and is followed by
11319 the name of the class of the method, the name of the method, and its
11320 arguments, if any.@refill
11326 @@defmethod @code{bar-class} bar-method argument
11333 illustrates the definition for a method called @code{bar-method} of
11334 the class @code{bar-class}. The method takes an argument.@refill
11340 @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
11341 @var{body-of-definition}
11346 @code{@@defmethod} creates an entry, such as `@code{bar-method} on
11347 @code{bar-class}', in the index of functions.@refill
11350 @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11352 The @code{@@deftypemethod} command is the definition command for methods
11353 in object-oriented typed languages, such as C++ and Java. It is similar
11354 to the @code{@@defmethod} command with the addition of the
11355 @var{data-type} parameter to specify the return type of the method.
11361 @subsection Data Types
11363 Here is the command for data types:@refill
11367 @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
11368 The @code{@@deftp} command is the generic definition command for data
11369 types. The command is written at the beginning of a line and is
11370 followed on the same line by the category, by the name of the type
11371 (which is a word like @code{int} or @code{float}), and then by names of
11372 attributes of objects of that type. Thus, you could use this command
11373 for describing @code{int} or @code{float}, in which case you could use
11374 @code{data type} as the category. (A data type is a category of
11375 certain objects for purposes of deciding which operations can be
11376 performed on them.)@refill
11378 In Lisp, for example, @dfn{pair} names a particular data
11379 type, and an object of that type has two slots called the
11380 @sc{car} and the @sc{cdr}. Here is how you would write the first line
11381 of a definition of @code{pair}.@refill
11385 @@deftp @{Data type@} pair car cdr
11396 @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11397 @var{body-of-definition}
11402 @code{@@deftp} creates an entry in the index of data types.
11405 @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11406 @section Conventions for Writing Definitions
11407 @cindex Definition conventions
11408 @cindex Conventions for writing definitions
11410 When you write a definition using @code{@@deffn}, @code{@@defun}, or
11411 one of the other definition commands, please take care to use
11412 arguments that indicate the meaning, as with the @var{count} argument
11413 to the @code{forward-word} function. Also, if the name of an argument
11414 contains the name of a type, such as @var{integer}, take care that the
11415 argument actually is of that type.@refill
11417 @node Sample Function Definition, , Def Cmd Conventions, Definition Commands
11418 @section A Sample Function Definition
11419 @cindex Function definitions
11420 @cindex Command definitions
11421 @cindex Macro definitions
11422 @cindex Sample function definition
11424 A function definition uses the @code{@@defun} and @code{@@end defun}
11425 commands. The name of the function follows immediately after the
11426 @code{@@defun} command and it is followed, on the same line, by the
11427 parameter list.@refill
11429 Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
11430 Lisp Reference Manual}.
11433 @defun apply function &rest arguments
11434 @code{apply} calls @var{function} with @var{arguments}, just
11435 like @code{funcall} but with one difference: the last of
11436 @var{arguments} is a list of arguments to give to
11437 @var{function}, rather than a single argument. We also say
11438 that this list is @dfn{appended} to the other arguments.
11440 @code{apply} returns the result of calling @var{function}.
11441 As with @code{funcall}, @var{function} must either be a Lisp
11442 function or a primitive function; special forms and macros
11443 do not make sense in @code{apply}.
11449 @error{} Wrong type argument: listp, z
11450 (apply '+ 1 2 '(3 4))
11452 (apply '+ '(1 2 3 4))
11455 (apply 'append '((a b c) nil (x y z) nil))
11456 @result{} (a b c x y z)
11459 An interesting example of using @code{apply} is found in the description
11460 of @code{mapcar}.@refill
11465 In the Texinfo source file, this example looks like this:
11469 @@defun apply function &rest arguments
11470 @@code@{apply@} calls @@var@{function@} with
11471 @@var@{arguments@}, just like @@code@{funcall@} but with one
11472 difference: the last of @@var@{arguments@} is a list of
11473 arguments to give to @@var@{function@}, rather than a single
11474 argument. We also say that this list is @@dfn@{appended@}
11475 to the other arguments.
11479 @@code@{apply@} returns the result of calling
11480 @@var@{function@}. As with @@code@{funcall@},
11481 @@var@{function@} must either be a Lisp function or a
11482 primitive function; special forms and macros do not make
11483 sense in @@code@{apply@}.
11491 @@error@{@} Wrong type argument: listp, z
11492 (apply '+ 1 2 '(3 4))
11494 (apply '+ '(1 2 3 4))
11497 (apply 'append '((a b c) nil (x y z) nil))
11498 @@result@{@} (a b c x y z)
11503 An interesting example of using @@code@{apply@} is found
11504 in the description of @@code@{mapcar@}.
11510 In this manual, this function is listed in the Command and Variable
11511 Index under @code{apply}.@refill
11513 Ordinary variables and user options are described using a format like
11514 that for functions except that variables do not take arguments.
11518 @chapter Conditionally Visible Text
11519 @cindex Conditionally visible text
11520 @cindex Text, conditionally visible
11521 @cindex Visibility of conditional text
11522 @cindex If text conditionally visible
11524 Sometimes it is good to use different text for different output formats.
11525 For example, you can use the @dfn{conditional commands} to specify
11526 different text for the printed manual and the Info output.
11528 Conditional commands may not be nested.
11530 The conditional commands comprise the following categories.
11533 @item Commands for HTML, Info, or @TeX{}.
11534 @item Commands for not HTML, Info, or @TeX{}.
11535 @item Raw @TeX{} or HTML commands.
11537 Substituting text for all formats, and testing if a flag is set or clear.
11541 * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
11542 * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
11543 * Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
11544 * set clear value:: Designating which text to format (for
11545 all output formats); and how to set a
11546 flag to a string that you can insert.
11550 @node Conditional Commands
11551 @section Conditional Commands
11554 @code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
11555 when it typesets the printed manual. The segment of text appears only
11556 in the Info file. The @code{@@ifinfo} command should appear on a line
11557 by itself; end the Info-only text with a line containing @code{@@end
11558 ifinfo} by itself. At the beginning of a Texinfo file, the Info
11559 permissions are contained within a region marked by @code{@@ifinfo} and
11560 @code{@@end ifinfo}. (@xref{Info Summary and Permissions}.)
11564 The @code{@@iftex} and @code{@@end iftex} commands are similar to the
11565 @code{@@ifinfo} and @code{@@end ifinfo} commands, except that they
11566 specify text that will appear in the printed manual but not in the Info
11567 file. Likewise for @code{@@ifhtml} and @code{@@end ifhtml}, which
11568 specify text to appear only in HTML output.@refill
11574 This text will appear only in the printed manual.
11577 However, this text will appear only in Info.
11580 And this text will only appear in HTML.
11585 The preceding example produces the following line:
11587 This text will appear only in the printed manual.
11590 However, this text will appear only in Info.
11593 And this text will only appear in HTML.
11597 Notice that you only see one of the input lines, depending on which
11598 version of the manual you are reading.
11601 @node Conditional Not Commands
11602 @section Conditional Not Commands
11607 You can specify text to be included in any output format @emph{other}
11608 than some given one with the @code{@@ifnot@dots{}} commands:
11610 @@ifnothtml @dots{} @@end ifnothtml
11611 @@ifnotinfo @dots{} @@end ifnotinfo
11612 @@ifnottex @dots{} @@end ifnottex
11615 (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11616 actually appear on lines by themselves.)
11618 If the output file is not being made for the given format, the region is
11619 included. Otherwise, it is ignored.
11621 The regions delimited by these commands are ordinary Texinfo source as
11622 with @code{@@iftex}, not raw formatter source as with @code{@@tex}
11623 (@pxref{Raw Formatter Commands}).
11626 @node Raw Formatter Commands, set clear value, Conditional Not Commands, Conditionals
11627 @section Raw Formatter Commands
11628 @cindex @TeX{} commands, using ordinary
11629 @cindex HTML commands, using ordinary
11630 @cindex Raw formatter commands
11631 @cindex Ordinary @TeX{} commands, using
11632 @cindex Ordinary HTML commands, using
11633 @cindex Commands using raw @TeX{}
11634 @cindex Commands using raw HTML
11635 @cindex plain @TeX{}
11637 Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11638 can embed some raw @TeX{} commands. Info will ignore these commands
11639 since they are only in that part of the file which is seen by @TeX{}.
11640 You can write the @TeX{} commands as you would write them in a normal
11641 @TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11642 with an @samp{@@}. For example, in the @code{@@titlepage} section of a
11643 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11644 the copyright page. (The @code{@@titlepage} command causes Info to
11645 ignore the region automatically, as it does with the @code{@@iftex}
11648 However, many features of plain @TeX{} will not work, as they are
11649 overridden by Texinfo features.
11652 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11653 commands, by delineating a region with the @code{@@tex} and @code{@@end
11654 tex} commands. (The @code{@@tex} command also causes Info to ignore the
11655 region, like the @code{@@iftex} command.) The sole exception is that the
11656 @code{@@} character still introduces a command, so that @code{@@end tex}
11657 can be recognized properly.
11659 @cindex Mathematical expressions
11660 For example, here is a mathematical expression written in
11665 $$ \chi^2 = \sum_@{i=1@}^N
11666 \left (y_i - (a + b x_i)
11667 \over \sigma_i\right)^2 $$
11672 The output of this example will appear only in a printed manual. If
11673 you are reading this in Info, you will not see the equation that appears
11674 in the printed manual.
11676 In a printed manual, the above expression looks like
11681 $$ \chi^2 = \sum_{i=1}^N
11682 \left(y_i - (a + b x_i)
11683 \over \sigma_i\right)^2 $$
11688 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11689 a region to be included in HTML output only, and @code{@@html @dots{}
11690 @@end html} for a region of raw HTML (again, except that @code{@@} is
11691 still the escape character, so the @code{@@end} command can be
11695 @node set clear value
11696 @section @code{@@set}, @code{@@clear}, and @code{@@value}
11698 You can direct the Texinfo formatting commands to format or ignore parts
11699 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11700 and @code{@@ifclear} commands.@refill
11702 In addition, you can use the @code{@@set @var{flag}} command to set the
11703 value of @var{flag} to a string of characters; and use
11704 @code{@@value@{@var{flag}@}} to insert that string. You can use
11705 @code{@@set}, for example, to set a date and use @code{@@value} to
11706 insert the date in several places in the Texinfo file.@refill
11709 * ifset ifclear:: Format a region if a flag is set.
11710 * set value:: Expand a flag variable to a string.
11711 * value Example:: An easy way to update edition information.
11715 @node ifset ifclear
11716 @subsection @code{@@ifset} and @code{@@ifclear}
11719 When a @var{flag} is set, the Texinfo formatting commands format text
11720 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
11721 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
11722 commands do @emph{not} format the text.
11724 Use the @code{@@set @var{flag}} command to turn on, or @dfn{set}, a
11725 @var{flag}; a @dfn{flag} name can be any single word, containing
11726 letters, numerals, hyphens, or underscores.
11728 The format for the command looks like this:@refill
11735 Write the conditionally formatted text between @code{@@ifset @var{flag}}
11736 and @code{@@end ifset} commands, like this:@refill
11741 @var{conditional-text}
11746 For example, you can create one document that has two variants, such as
11747 a manual for a `large' and `small' model:@refill
11750 You can use this machine to dig up shrubs
11751 without hurting them.
11756 It can also dig up fully grown trees.
11759 Remember to replant promptly @dots{}
11763 In the example, the formatting commands will format the text between
11764 @code{@@ifset large} and @code{@@end ifset} because the @code{large}
11765 flag is set.@refill
11768 Use the @code{@@clear @var{flag}} command to turn off, or @dfn{clear},
11769 a flag. Clearing a flag is the opposite of setting a flag. The
11770 command looks like this:@refill
11777 Write the command on a line of its own.
11779 When @var{flag} is cleared, the Texinfo formatting commands do
11780 @emph{not} format the text between @code{@@ifset @var{flag}} and
11781 @code{@@end ifset}; that text is ignored and does not appear in either
11782 printed or Info output.@refill
11784 For example, if you clear the flag of the preceding example by writing
11785 an @code{@@clear large} command after the @code{@@set large} command
11786 (but before the conditional text), then the Texinfo formatting commands
11787 ignore the text between the @code{@@ifset large} and @code{@@end ifset}
11788 commands. In the formatted output, that text does not appear; in both
11789 printed and Info output, you see only the lines that say, ``You can use
11790 this machine to dig up shrubs without hurting them. Remember to replant
11791 promptly @dots{}''.
11794 If a flag is cleared with an @code{@@clear @var{flag}} command, then
11795 the formatting commands format text between subsequent pairs of
11796 @code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
11797 is set with @code{@@set @var{flag}}, then the formatting commands do
11798 @emph{not} format text between an @code{@@ifclear} and an @code{@@end
11799 ifclear} command; rather, they ignore that text. An @code{@@ifclear}
11800 command looks like this:@refill
11803 @@ifclear @var{flag}
11807 In brief, the commands are:@refill
11810 @item @@set @var{flag}
11811 Tell the Texinfo formatting commands that @var{flag} is set.@refill
11813 @item @@clear @var{flag}
11814 Tell the Texinfo formatting commands that @var{flag} is cleared.@refill
11816 @item @@ifset @var{flag}
11817 If @var{flag} is set, tell the Texinfo formatting commands to format
11818 the text up to the following @code{@@end ifset} command.@refill
11820 If @var{flag} is cleared, tell the Texinfo formatting commands to
11821 ignore text up to the following @code{@@end ifset} command.@refill
11823 @item @@ifclear @var{flag}
11824 If @var{flag} is set, tell the Texinfo formatting commands to ignore
11825 the text up to the following @code{@@end ifclear} command.@refill
11827 If @var{flag} is cleared, tell the Texinfo formatting commands to
11828 format the text up to the following @code{@@end ifclear}
11834 @subsection @code{@@set} and @code{@@value}
11837 You can use the @code{@@set} command to specify a value for a flag,
11838 which is expanded by the @code{@@value} command. A flag is an
11839 identifier; for best results, use only letters and numerals in a flag
11840 name, not @samp{-} or @samp{_}---they will work in some contexts, but
11841 not all, due to limitations in @TeX{}. The value is just a string of
11842 characters, the remainder of the input line.
11844 Write the @code{@@set} command like this:
11847 @@set foo This is a string.
11851 This sets the value of the flag @code{foo} to ``This is a string.''.
11853 The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
11854 command with the string to which @var{flag} is set. Thus, when
11855 @code{foo} is set as shown above, the Texinfo formatters convert
11865 You can write an @code{@@value} command within a paragraph; but you
11866 must write an @code{@@set} command on a line of its own.
11868 If you write the @code{@@set} command like this:
11875 without specifying a string, the value of @code{foo} is an empty string.
11877 If you clear a previously set flag with @code{@@clear @var{flag}}, a
11878 subsequent @code{@@value@{flag@}} command is invalid and the string is
11879 replaced with an error message that says @samp{@{No value for
11882 For example, if you set @code{foo} as follows:@refill
11885 @@set how-much very, very, very
11889 then the formatters transform
11893 It is a @@value@{how-much@} wet day.
11895 It is a very, very, very wet day.
11906 then the formatters transform
11910 It is a @@value@{how-much@} wet day.
11912 It is a @{No value for "how-much"@} wet day.
11917 @node value Example
11918 @subsection @code{@@value} Example
11920 You can use the @code{@@value} command to limit the number of places you
11921 need to change when you record an update to a manual. Here is how it is
11922 done in @cite{The GNU Make Manual}:
11930 @@set EDITION 0.35 Beta
11931 @@set VERSION 3.63 Beta
11932 @@set UPDATED 14 August 1992
11933 @@set UPDATE-MONTH August 1992
11938 Write text for the first @code{@@ifinfo} section, for people reading the
11943 This is Edition @@value@{EDITION@},
11944 last updated @@value@{UPDATED@},
11945 of @@cite@{The GNU Make Manual@},
11946 for @@code@{make@}, version @@value@{VERSION@}.
11951 Write text for the title page, for people reading the printed manual:
11952 @c List only the month and the year since that looks less fussy on a
11953 @c printed cover than a date that lists the day as well.
11958 @@subtitle A Program for Directing Recompilation
11959 @@subtitle Edition @@value@{EDITION@}, @dots{}
11960 @@subtitle @@value@{UPDATE-MONTH@}
11965 (On a printed cover, a date listing the month and the year looks less
11966 fussy than a date listing the day as well as the month and year.)
11969 Write text for the Top node, for people reading the Info file:
11973 This is Edition @@value@{EDITION@}
11974 of the @@cite@{GNU Make Manual@},
11975 last updated @@value@{UPDATED@}
11976 for @@code@{make@} Version @@value@{VERSION@}.
11980 After you format the manual, the text in the first @code{@@ifinfo}
11981 section looks like this:
11985 This is Edition 0.35 Beta, last updated 14 August 1992,
11986 of `The GNU Make Manual', for `make', Version 3.63 Beta.
11991 When you update the manual, change only the values of the flags; you do
11992 not need to edit the three sections.
11995 @node Internationalization
11996 @chapter Internationalization
11998 @cindex Internationalization
11999 Texinfo has some support for writing in languages other than English,
12000 although this area still needs considerable work.
12002 For a list of the various accented and special characters Texinfo
12003 supports, see @ref{Inserting Accents}.
12006 * documentlanguage:: Declaring the current language.
12007 * documentencoding:: Declaring the input encoding.
12011 @node documentlanguage
12012 @section @code{@@documentlanguage @var{cc}}: Set the Document Language
12014 @findex documentlanguage
12015 @cindex Language, declaring
12016 @cindex Document language, declaring
12018 The @code{@@documentlanguage} command declares the current document
12019 language. Write it on a line by itself, with a two-letter ISO-639
12020 language code following (list is included below). If you have a
12021 multilingual document, the intent is to be able to use this command
12022 multiple times, to declare each language change. If the command is not
12023 used at all, the default is @code{en} for English.
12025 @cindex @file{txi-@var{cc}.tex}
12026 At present, this command is ignored in Info and HTML output. For
12027 @TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
12028 exists). Such a file appropriately redefines the various English words
12029 used in @TeX{} output, such as `Chapter', `See', and so on.
12031 @cindex Hyphenation patterns, language-dependent
12032 It would be good if this command also changed @TeX{}'s ideas of the
12033 current hyphenation patterns (via the @TeX{} primitive
12034 @code{\language}), but this is unfortunately not currently implemented.
12036 @cindex ISO 639 codes
12037 @cindex Language codes
12038 @cindex African languages
12039 Here is the list of valid language codes. This list comes from
12040 @uref{http://www.iro.umontreal.ca/contrib/po/iso-639, the free
12041 translation project}. In the future we may wish to allow the 3-letter
12042 POV codes described at @uref{http://www.sil.org/ethnologue/#contents}.
12043 This will be necessary to support African languages.
12045 @multitable @columnfractions .06 .27 .06 .27 .06 .27
12047 @code{aa} @tab Afar @tab
12048 @code{ab} @tab Abkhazian @tab
12049 @code{af} @tab Afrikaans
12051 @code{am} @tab Amharic @tab
12052 @code{ar} @tab Arabic @tab
12053 @code{as} @tab Assamese
12055 @code{ay} @tab Aymara @tab
12056 @code{az} @tab Azerbaijani @tab
12057 @code{ba} @tab Bashkir
12059 @code{be} @tab Byelorussian @tab
12060 @code{bg} @tab Bulgarian @tab
12061 @code{bh} @tab Bihari
12063 @code{bi} @tab Bislama @tab
12064 @code{bn} @tab Bengali; Bangla @tab
12065 @code{bo} @tab Tibetan
12067 @code{br} @tab Breton @tab
12068 @code{ca} @tab Catalan @tab
12069 @code{co} @tab Corsican
12071 @code{cs} @tab Czech @tab
12072 @code{cy} @tab Welsh @tab
12073 @code{da} @tab Danish
12075 @code{de} @tab German @tab
12076 @code{dz} @tab Bhutani @tab
12077 @code{el} @tab Greek
12079 @code{en} @tab English @tab
12080 @code{eo} @tab Esperanto @tab
12081 @code{es} @tab Spanish
12083 @code{et} @tab Estonian @tab
12084 @code{eu} @tab Basque @tab
12085 @code{fa} @tab Persian
12087 @code{fi} @tab Finnish @tab
12088 @code{fj} @tab Fiji @tab
12089 @code{fo} @tab Faroese
12091 @code{fr} @tab French @tab
12092 @code{fy} @tab Frisian @tab
12093 @code{ga} @tab Irish
12095 @code{gd} @tab Scots Gaelic @tab
12096 @code{gl} @tab Galician @tab
12097 @code{gn} @tab Guarani
12099 @code{gu} @tab Gujarati @tab
12100 @code{ha} @tab Hausa @tab
12101 @code{he} @tab Hebrew
12103 @code{hi} @tab Hindi @tab
12104 @code{hr} @tab Croatian @tab
12105 @code{hu} @tab Hungarian
12107 @code{hy} @tab Armenian @tab
12108 @code{ia} @tab Interlingua @tab
12109 @code{id} @tab Indonesian
12111 @code{ie} @tab Interlingue @tab
12112 @code{ik} @tab Inupiak @tab
12113 @code{is} @tab Icelandic
12115 @code{it} @tab Italian @tab
12116 @code{iu} @tab Inuktitut @tab
12117 @code{ja} @tab Japanese
12119 @code{jw} @tab Javanese @tab
12120 @code{ka} @tab Georgian @tab
12121 @code{kk} @tab Kazakh
12123 @code{kl} @tab Greenlandic @tab
12124 @code{km} @tab Cambodian @tab
12125 @code{kn} @tab Kannada
12127 @code{ks} @tab Kashmiri @tab
12128 @code{ko} @tab Korean @tab
12129 @code{ku} @tab Kurdish
12131 @code{ky} @tab Kirghiz @tab
12132 @code{la} @tab Latin @tab
12133 @code{ln} @tab Lingala
12135 @code{lt} @tab Lithuanian @tab
12136 @code{lo} @tab Laothian @tab
12137 @code{lv} @tab Latvian, Lettish
12139 @code{mg} @tab Malagasy @tab
12140 @code{mi} @tab Maori @tab
12141 @code{mk} @tab Macedonian
12143 @code{ml} @tab Malayalam @tab
12144 @code{mn} @tab Mongolian @tab
12145 @code{mo} @tab Moldavian
12147 @code{mr} @tab Marathi @tab
12148 @code{ms} @tab Malay @tab
12149 @code{mt} @tab Maltese
12151 @code{my} @tab Burmese @tab
12152 @code{na} @tab Nauru @tab
12153 @code{ne} @tab Nepali
12155 @code{nl} @tab Dutch @tab
12156 @code{no} @tab Norwegian @tab
12157 @code{oc} @tab Occitan
12159 @code{om} @tab (Afan) Oromo @tab
12160 @code{or} @tab Oriya @tab
12161 @code{pa} @tab Punjabi
12163 @code{pl} @tab Polish @tab
12164 @code{ps} @tab Pashto, Pushto @tab
12165 @code{pt} @tab Portuguese
12167 @code{qu} @tab Quechua @tab
12168 @code{rm} @tab Rhaeto-Romance @tab
12169 @code{rn} @tab Kirundi
12171 @code{ro} @tab Romanian @tab
12172 @code{ru} @tab Russian @tab
12173 @code{rw} @tab Kinyarwanda
12175 @code{sa} @tab Sanskrit @tab
12176 @code{sd} @tab Sindhi @tab
12177 @code{sg} @tab Sangro
12179 @code{sh} @tab Serbo-Croatian @tab
12180 @code{si} @tab Sinhalese @tab
12181 @code{sk} @tab Slovak
12183 @code{sl} @tab Slovenian @tab
12184 @code{sm} @tab Samoan @tab
12185 @code{sn} @tab Shona
12187 @code{so} @tab Somali @tab
12188 @code{sq} @tab Albanian @tab
12189 @code{sr} @tab Serbian
12191 @code{ss} @tab Siswati @tab
12192 @code{st} @tab Sesotho @tab
12193 @code{su} @tab Sundanese
12195 @code{sv} @tab Swedish @tab
12196 @code{sw} @tab Swahili @tab
12197 @code{ta} @tab Tamil
12199 @code{te} @tab Telugu @tab
12200 @code{tg} @tab Tajik @tab
12201 @code{th} @tab Thai
12203 @code{ti} @tab Tigrinya @tab
12204 @code{tk} @tab Turkmen @tab
12205 @code{tl} @tab Tagalog
12207 @code{tn} @tab Setswana @tab
12208 @code{to} @tab Tonga @tab
12209 @code{tr} @tab Turkish
12211 @code{ts} @tab Tsonga @tab
12212 @code{tt} @tab Tatar @tab
12215 @code{ug} @tab Uighur @tab
12216 @code{uk} @tab Ukrainian @tab
12217 @code{ur} @tab Urdu
12219 @code{uz} @tab Uzbek @tab
12220 @code{vi} @tab Vietnamese @tab
12221 @code{vo} @tab Volapuk
12223 @code{wo} @tab Wolof @tab
12224 @code{xh} @tab Xhosa @tab
12225 @code{yi} @tab Yiddish
12227 @code{yo} @tab Yoruba @tab
12228 @code{za} @tab Zhuang @tab
12229 @code{zh} @tab Chinese
12231 @code{zu} @tab Zulu
12235 @node documentencoding
12236 @section @code{@@documentencoding @var{enc}}: Set Input Encoding
12238 @findex documentencoding
12239 @cindex Encoding, declaring
12240 @cindex Input encoding, declaring
12241 @cindex Document input encoding
12243 The @code{@@documentencoding} command declares the input document
12244 encoding. Write it on a line by itself, with a valid encoding
12245 specification following, such as @samp{ISO-8859-1}.
12247 @cindex http-equiv, and charset
12248 @cindex meta HTML tag, and charset
12249 At present, this is used only in HTML output from @code{makeinfo}. If a
12250 document encoding @var{enc} is specified, it is used in the
12251 @samp{<meta>} tag is included in the @samp{<head>} of the output:
12254 <meta http-equiv="Content-Type" content="text/html; charset=@var{enc}">
12258 @node Defining New Texinfo Commands
12259 @chapter Defining New Texinfo Commands
12261 @cindex Defining new Texinfo commands
12262 @cindex New Texinfo commands, defining
12263 @cindex Texinfo commands, defining new
12264 @cindex User-defined Texinfo commands
12266 Texinfo provides several ways to define new commands:
12270 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
12271 sequence of text and/or existing commands (including other macros). The
12272 macro can have any number of @dfn{parameters}---text you supply each
12273 time you use the macro.
12275 Incidentally, these macros have nothing to do with the @code{@@defmac}
12276 command, which is for documenting macros in the subject of the manual
12277 (@pxref{Def Cmd Template}).
12280 @samp{@@alias} is a convenient way to define a new name for an existing
12284 @samp{@@definfoenclose} allows you to define new commands with
12285 customized output in the Info file.
12290 * Defining Macros:: Defining and undefining new commands.
12291 * Invoking Macros:: Using a macro, once you've defined it.
12292 * Macro Details:: Beyond basic macro usage.
12293 * alias:: Command aliases.
12294 * definfoenclose:: Customized highlighting.
12298 @node Defining Macros
12299 @section Defining Macros
12300 @cindex Defining macros
12301 @cindex Macro definitions
12302 @cindex Definitions, a.k.a.@: macros
12305 You use the Texinfo @code{@@macro} command to define a macro, like this:
12308 @@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
12309 @var{text} @dots{} \@var{param1}\ @dots{}
12313 The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
12314 arguments supplied when the macro is subsequently used in the document
12315 (described in the next section).
12317 For a macro to work with @TeX{}, @var{macroname} must consist entirely
12318 of letters: no digits, hyphens, underscores, or other special characters.
12320 If a macro needs no parameters, you can define it either with an empty
12321 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
12324 @cindex Body of a macro
12325 @cindex Mutually recursive macros
12326 @cindex Recursion, mutual
12327 The definition or @dfn{body} of the macro can contain most Texinfo
12328 commands, including previously-defined macros. Not-yet-defined macro
12329 invocations are not allowed; thus, it is not possible to have mutually
12330 recursive Texinfo macros. Also, a macro definition that defines another
12331 macro does not work in @TeX{} due to limitations in the design of
12334 @cindex Parameters to macros
12335 In the macro body, instances of a parameter name surrounded by
12336 backslashes, as in @samp{\@var{param1}\} in the example above, are
12337 replaced by the corresponding argument from the macro invocation. You
12338 can use parameter names any number of times in the body, including zero.
12340 @cindex Backslash in macros
12341 To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
12342 other use of @samp{\} in the body yields a warning.
12344 @cindex Spaces in macros
12345 @cindex Whitespace in macros
12346 The newlines after the @code{@@macro} line and before the @code{@@end
12347 macro} line are ignored, that is, not included in the macro body. All
12348 other whitespace is treated according to the usual Texinfo rules.
12350 @cindex Recursive macro invocations
12352 To allow a macro to be used recursively, that is, in an argument to a
12353 call to itself, you must define it with @samp{@@rmacro}, like this:
12360 @@rmac@{1@@rmac@{text@}2@}
12363 This produces the output `a1atextb2b'. With @samp{@@macro} instead of
12364 @samp{@@rmacro}, an error message is given.
12367 @cindex Macros, undefining
12368 @cindex Undefining macros
12369 You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
12370 It is not an error to undefine a macro that is already undefined.
12378 @node Invoking Macros
12379 @section Invoking Macros
12380 @cindex Invoking macros
12381 @cindex Expanding macros
12382 @cindex Running macros
12383 @cindex Macro invocation
12385 After a macro is defined (see the previous section), you can use
12386 (@dfn{invoke}) it in your document like this:
12389 @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
12392 @noindent and the result will be just as if you typed the body of
12393 @var{macroname} at that spot. For example:
12396 @@macro foo @{p, q@}
12397 Together: \p\ & \q\.
12402 @noindent produces:
12408 @cindex Backslash, and macros
12409 Thus, the arguments and parameters are separated by commas and delimited
12410 by braces; any whitespace after (but not before) a comma is ignored.
12411 The braces are required in the invocation (but not the definition), even
12412 when the macro takes no arguments, consistent with all other Texinfo
12413 commands. For example:
12416 @@macro argless @{@}
12422 @noindent produces:
12428 To insert a comma, brace, or backslash in an argument, prepend a
12432 @@@var{macname} @{\\\@{\@}\,@}
12436 which will pass the (almost certainly error-producing) argument
12437 @samp{\@{@},} to @var{macname}.
12439 If the macro is defined to take a single argument, and is invoked
12440 without any braces, the entire rest of the line after the macro name is
12441 supplied as the argument. For example:
12450 @noindent produces:
12452 @c Sorry for cheating, but let's not require macros to process the manual.
12457 If the macro is defined to take a single argument, and is invoked with
12458 braces, the braced text is passed as the argument, regardless of
12459 commas. For example:
12468 @noindent produces:
12475 @node Macro Details
12476 @section Macro Details
12477 @cindex Macro details
12478 @cindex Details of macro usage
12480 Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
12481 implementations, Texinfo macros have the following limitations.
12485 All macros are expanded inside at least one @TeX{} group. This means
12486 that @set and other such commands will have no effect inside a macro.
12489 Macros containing a command which must be on a line by itself, such as a
12490 conditional, cannot be invoked in the middle of a line.
12493 The @TeX{} implementation cannot construct macros that define macros in
12494 the natural way. To do this, you must use conditionals and raw @TeX{}.
12499 @@macro ctor @{name, arg@}
12501 something involving \arg\ somehow
12506 \gdef\ctor#1@{\ctorx#1,@}
12507 \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
12512 It is best to avoid comments inside macro definitions.
12518 @section @samp{@@alias @var{new}=@var{existing}}
12519 @cindex Aliases, command
12520 @cindex Command aliases
12523 The @samp{@@alias} command defines a new command to be just like an
12524 existing one. This is useful for defining additional markup names, thus
12525 preserving semantic information in the input even though the output
12526 result may be the same.
12528 Write the @samp{@@alias} command on a line by itself, followed by the
12529 new command name, an equals sign, and the existing command name.
12530 Whitespace around the equals sign is ignored. Thus:
12532 @@alias @var{new} = @var{existing}
12535 For example, if your document contains citations for both books and
12536 some other media (movies, for example), you might like to define a
12537 macro @code{@@moviecite@{@}} that does the same thing as an ordinary
12538 @code{@@cite@{@}} but conveys the extra semantic information as well.
12539 You'd do this as follows:
12542 @@alias moviecite = cite
12545 Macros do not always have the same effect due to vagaries of argument
12546 parsing. Also, aliases are much simpler to define than macros. So the
12547 command is not redundant. (It was also heavily used in the Jargon File!)
12549 Aliases must not be recursive, directly or indirectly.
12551 @node definfoenclose
12552 @section @samp{definfoenclose}: Customized Highlighting
12553 @cindex Highlighting, customized
12554 @cindex Customized highlighting
12555 @findex definfoenclose
12557 A @code{@@definfoenclose} command may be used to define a highlighting
12558 command for Info, but not for TeX. A command defined using
12559 @code{@@definfoenclose} marks text by enclosing it in strings that
12560 precede and follow the text. You can use this to get closer control of
12563 Presumably, if you define a command with @code{@@definfoenclose} for Info,
12564 you will create a corresponding command for @TeX{}, either in
12565 @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
12568 Write a @code{@@definfoenclose} command on a line and follow it with
12569 three arguments separated by commas. The first argument to
12570 @code{@@definfoenclose} is the @@-command name (without the @code{@@});
12571 the second argument is the Info start delimiter string; and the third
12572 argument is the Info end delimiter string. The latter two arguments
12573 enclose the highlighted text in the Info file. A delimiter string may
12574 contain spaces. Neither the start nor end delimiter is required. If
12575 you do not want a start delimiter but do want an end delimiter, you must
12576 follow the command name with two commas in a row; otherwise, the Info
12577 formatting commands will naturally misinterpret the end delimiter string
12578 you intended as the start delimiter string.
12580 If you do a @code{@@definfoenclose} on the name of a pre-defined macro
12581 (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
12582 enclosure definition will override the built-in definition.
12584 An enclosure command defined this way takes one argument in braces; this
12585 is intended for new markup commands (@pxref{Marking Text}).
12588 For example, you can write:
12591 @@definfoenclose phoo,//,\\
12595 near the beginning of a Texinfo file to define @code{@@phoo} as an Info
12596 formatting command that inserts `//' before and `\\' after the argument
12597 to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
12598 want `//bar\\' highlighted in Info.
12600 Also, for TeX formatting, you could write
12604 @@global@@let@@phoo=@@i
12609 to define @code{@@phoo} as a command that causes TeX to typeset the
12610 argument to @code{@@phoo} in italics.
12612 Note that each definition applies to its own formatter: one for TeX,
12613 the other for @code{texinfo-format-buffer} or
12614 @code{texinfo-format-region}. The @code{@@definfoenclose} command need
12615 not be within @samp{@@ifinfo}, but the raw @TeX{} commands do need to be
12619 Here is another example: write
12622 @@definfoenclose headword, , :
12626 near the beginning of the file, to define @code{@@headword} as an Info
12627 formatting command that inserts nothing before and a colon after the
12628 argument to @code{@@headword}.
12630 @samp{@@definfoenclose} definitions must not be recursive, directly or
12635 @chapter Formatting and Printing Hardcopy
12636 @cindex Format and print hardcopy
12637 @cindex Printing hardcopy
12638 @cindex Hardcopy, printing it
12639 @cindex Making a printed manual
12640 @cindex Sorting indices
12641 @cindex Indices, sorting
12642 @cindex @TeX{} index sorting
12645 There are three major shell commands for making a printed manual from a
12646 Texinfo file: one for converting the Texinfo file into a file that will be
12647 printed, a second for sorting indices, and a third for printing the
12648 formatted document. When you use the shell commands, you can either
12649 work directly in the operating system shell or work within a shell
12652 If you are using GNU Emacs, you can use commands provided by Texinfo
12653 mode instead of shell commands. In addition to the three commands to
12654 format a file, sort the indices, and print the result, Texinfo mode
12655 offers key bindings for commands to recenter the output buffer, show the
12656 print queue, and delete a job from the print queue.
12659 * Use TeX:: Use @TeX{} to format for hardcopy.
12660 * Format with tex/texindex:: How to format with explicit shell commands.
12661 * Format with texi2dvi:: A simpler way to format.
12662 * Print with lpr:: How to print.
12663 * Within Emacs:: How to format and print from an Emacs shell.
12664 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
12665 * Compile-Command:: How to print using Emacs's compile command.
12666 * Requirements Summary:: @TeX{} formatting requirements summary.
12667 * Preparing for TeX:: What to do before you use @TeX{}.
12668 * Overfull hboxes:: What are and what to do with overfull hboxes.
12669 * smallbook:: How to print small format books and manuals.
12670 * A4 Paper:: How to print on European A4 paper.
12671 * pagesizes:: How to print with customized page sizes.
12672 * Cropmarks and Magnification:: How to print marks to indicate the size
12673 of pages and how to print scaled up output.
12674 * PDF Output:: Portable Document Format output.
12678 @section Use @TeX{}
12680 The typesetting program called @TeX{} is used for formatting a Texinfo
12681 file. @TeX{} is a very powerful typesetting program and, if used correctly,
12682 does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
12683 @TeX{}}, for information on how to obtain @TeX{}.)
12685 The @code{makeinfo}, @code{texinfo-format-region}, and
12686 @code{texinfo-format-buffer} commands read the very same @@-commands
12687 in the Texinfo file as does @TeX{}, but process them differently to
12688 make an Info file (@pxref{Creating an Info File}).
12691 @node Format with tex/texindex
12692 @section Format with @code{tex} and @code{texindex}
12693 @cindex Shell formatting with @code{tex} and @code{texindex}
12694 @cindex Formatting with @code{tex} and @code{texindex}
12697 Format the Texinfo file with the shell command @code{tex} followed by
12698 the name of the Texinfo file. For example:
12704 @noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
12705 files containing information for indices, cross references, etc. The
12706 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
12707 any device (see the following sections).
12710 The @code{tex} formatting command itself does not sort the indices; it
12711 writes an output file of unsorted index data. (The @code{texi2dvi}
12712 command automatically generates indices; @pxref{Format with texi2dvi,,
12713 Format with @code{texi2dvi}}.) To generate a printed index after
12714 running the @code{tex} command, you first need a sorted index to work
12715 from. The @code{texindex} command sorts indices. (The source file
12716 @file{texindex.c} comes as part of the standard Texinfo distribution,
12717 among other places.)@refill
12719 @cindex Names of index files
12720 @cindex Index file names
12721 The @code{tex} formatting command outputs unsorted index files under
12722 names that obey a standard convention: the name of your main input file
12723 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
12724 Web2c}) extension removed, followed by the two letter names of indices.
12725 For example, the raw index output files for the input file
12726 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
12727 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
12728 arguments to give to @code{texindex}.
12733 Instead of specifying all the unsorted index file names explicitly, you
12734 can use @samp{??} as shell wildcards and give the command in this
12742 This command will run @code{texindex} on all the unsorted index files,
12743 including any that you have defined yourself using @code{@@defindex}
12744 or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
12745 even if there are similarly named files with two letter extensions
12746 that are not index files, such as @samp{foo.el}. The @code{texindex}
12747 command reports but otherwise ignores such files.)
12749 For each file specified, @code{texindex} generates a sorted index file
12750 whose name is made by appending @samp{s} to the input file name. The
12751 @code{@@printindex} command looks for a file with that name
12752 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
12753 raw index output file.
12755 After you have sorted the indices, you need to rerun the @code{tex}
12756 formatting command on the Texinfo file. This regenerates the DVI file,
12757 this time with up-to-date index entries.
12759 Finally, you may need to run @code{tex} one more time, to get the page
12760 numbers in the cross-references correct.
12762 To summarize, this is a five step process:
12766 Run @code{tex} on your Texinfo file. This generates a DVI file (with
12767 undefined cross-references and no indices), and the raw index files
12768 (with two letter extensions).
12771 Run @code{texindex} on the raw index files. This creates the
12772 corresponding sorted index files (with three letter extensions).
12775 Run @code{tex} again on your Texinfo file. This regenerates the DVI
12776 file, this time with indices and defined cross-references, but with page
12777 numbers for the cross-references from last time, generally incorrect.
12780 Sort the indices again, with @code{texindex}.
12783 Run @code{tex} one last time. This time the correct page numbers are
12784 written for the cross-references.
12788 Alternatively, it's a one-step process: run @code{texi2dvi}
12789 (@pxref{Format with texi2dvi}).
12791 You need not run @code{texindex} each time after you run @code{tex}. If
12792 you do not, on the next run, the @code{tex} formatting command will use
12793 whatever sorted index files happen to exist from the previous use of
12794 @code{texindex}. This is usually ok while you are debugging.
12796 @cindex Auxiliary files, avoiding
12798 @cindex Pointer validation, suppressing
12799 @cindex Chapters, formatting one at a time
12800 Sometimes you may wish to print a document while you know it is
12801 incomplete, or to print just one chapter of a document. In that case,
12802 the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
12803 when cross-references are not satisfied are just nuisances. You can
12804 avoid them with the @code{@@novalidate} command, which you must give
12805 @emph{before} the @code{@@setfilename} command
12806 (@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
12807 your file would look approximately like this:
12812 @@setfilename myfile.info
12816 @noindent @code{@@novalidate} also turns off validation in
12817 @code{makeinfo}, just like its @code{--no-validate} option
12818 (@pxref{Pointer Validation}).
12821 @node Format with texi2dvi
12822 @section Format with @code{texi2dvi}
12823 @pindex texi2dvi @r{(shell script)}
12825 The @code{texi2dvi} command automatically runs both @code{tex} and
12826 @code{texindex} as many times as necessary to produce a DVI file with
12827 sorted indices and all cross-references resolved. It simplifies the
12828 @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
12829 described in the previous section.
12831 To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
12832 @samp{prompt$ } is your shell prompt):
12835 prompt$ @kbd{texi2dvi foo.texi}
12838 As shown in this example, the input filenames to @code{texi2dvi} must
12839 include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
12840 MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
12841 texi2dvi foo.texi} instead of relying on the operating system to invoke
12842 the shell on the @samp{texi2dvi} script.
12844 Perhaps the most useful option to @code{texi2dvi} is
12845 @samp{--texinfo=@var{cmd}}. This inserts @var{cmd} on a line by itself
12846 after the @code{@@setfilename} in a temporary copy of the input file
12847 before running @TeX{}. With this, you can specify different printing
12848 formats, such as @code{@@smallbook} (@pxref{smallbook}),
12849 @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pageparams}
12850 (@pxref{pagesizes}), without actually changing the document source.
12851 (You can also do this on a site-wide basis with @file{texinfo.cnf};
12852 @pxref{Preparing for TeX,,Preparing for @TeX{}}).
12854 For a list of other options, run @samp{texi2dvi --help}.
12857 @node Print with lpr, Within Emacs, Format with texi2dvi, Hardcopy
12858 @section Shell Print Using @code{lpr -d}
12859 @pindex lpr @r{(DVI print command)}
12861 The precise command to print a DVI file depends on your system
12862 installation, but @samp{lpr -d} is common. The command may require the
12863 DVI file name without any extension or with a @samp{.dvi}
12864 extension. (If it is @samp{lpr}, you must include the @samp{.dvi}.)
12866 For example, the following commands, will (perhaps) suffice to sort the
12867 indices, format, and print the @cite{Bison Manual}:
12879 (Remember that the shell commands may be different at your site; but
12880 these are commonly used versions.)@refill
12883 Using the @code{texi2dvi} shell script, you simply need type:@refill
12887 texi2dvi bison.texinfo
12892 @cindex Shell printing, on MS-DOS/MS-Windows
12893 @cindex Printing DVI files, on MS-DOS/MS-Windows
12894 @pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
12895 @code{lpr} is a standard program on Unix systems, but it is usually
12896 absent on MS-DOS/MS-Windows. Some network packages come with a
12897 program named @code{lpr}, but these are usually limited to sending files
12898 to a print server over the network, and generally don't support the
12899 @samp{-d} option. If you are unfortunate enough to work on one of these
12900 systems, you have several alternative ways of printing DVI files:
12903 @item Find and install a Unix-like @code{lpr} program, or its clone.
12904 If you can do that, you will be able to print DVI files just like
12907 @item Send the DVI files to a network printer queue for DVI files.
12908 Some network printers have special queues for printing DVI files. You
12909 should be able to set up your network software to send files to that
12910 queue. In some cases, the version of @code{lpr} which comes with your
12911 network software will have a special option to send a file to specific
12915 lpr -Qdvi -hprint.server.domain bison.dvi
12918 @item Convert the DVI file to a Postscript or PCL file and send it to your
12919 local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
12920 pages for @code{dvilj}, for detailed description of these tools. Once
12921 the DVI file is converted to the format your local printer understands
12922 directly, just send it to the appropriate port, usually @samp{PRN}.
12927 @section From an Emacs Shell
12928 @cindex Print, format from Emacs shell
12929 @cindex Format, print from Emacs shell
12930 @cindex Shell, format, print from
12931 @cindex Emacs shell, format, print from
12932 @cindex GNU Emacs shell, format, print from
12934 You can give formatting and printing commands from a shell within GNU
12935 Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
12936 shell, you can format and print the document. @xref{Hardcopy, , Format
12937 and Print Hardcopy}, for details.
12939 You can switch to and from the shell buffer while @code{tex} is
12940 running and do other editing. If you are formatting a long document
12941 on a slow machine, this can be very convenient.@refill
12943 You can also use @code{texi2dvi} from an Emacs shell. For example,
12944 here is how to use @code{texi2dvi} to format and print @cite{Using and
12945 Porting GNU CC} from a shell within Emacs:
12949 texi2dvi gcc.texinfo
12955 @xref{Texinfo Mode Printing}, for more information about formatting
12956 and printing in Texinfo mode.@refill
12960 @node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
12961 @section Formatting and Printing in Texinfo Mode
12962 @cindex Region printing in Texinfo mode
12963 @cindex Format and print in Texinfo mode
12964 @cindex Print and format in Texinfo mode
12966 Texinfo mode provides several predefined key commands for @TeX{}
12967 formatting and printing. These include commands for sorting indices,
12968 looking at the printer queue, killing the formatting job, and
12969 recentering the display of the buffer in which the operations
12974 @itemx M-x texinfo-tex-buffer
12975 Run @code{texi2dvi} on the current buffer.@refill
12978 @itemx M-x texinfo-tex-region
12979 Run @TeX{} on the current region.@refill
12982 @itemx M-x texinfo-texindex
12983 Sort the indices of a Texinfo file formatted with
12984 @code{texinfo-tex-region}.@refill
12987 @itemx M-x texinfo-tex-print
12988 Print a DVI file that was made with @code{texinfo-tex-region} or
12989 @code{texinfo-tex-buffer}.@refill
12992 @itemx M-x tex-show-print-queue
12993 Show the print queue.@refill
12996 @itemx M-x texinfo-delete-from-print-queue
12997 Delete a job from the print queue; you will be prompted for the job
12998 number shown by a preceding @kbd{C-c C-t C-q} command
12999 (@code{texinfo-show-tex-print-queue}).@refill
13002 @itemx M-x tex-kill-job
13003 Kill the currently running @TeX{} job started by either
13004 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
13005 process running in the Texinfo shell buffer.@refill
13008 @itemx M-x texinfo-quit-job
13009 Quit a @TeX{} formatting job that has stopped because of an error by
13010 sending an @key{x} to it. When you do this, @TeX{} preserves a record
13011 of what it did in a @file{.log} file.@refill
13014 @itemx M-x tex-recenter-output-buffer
13015 Redisplay the shell buffer in which the @TeX{} printing and formatting
13016 commands are run to show its most recent output.@refill
13020 Thus, the usual sequence of commands for formatting a buffer is as
13021 follows (with comments to the right):@refill
13025 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
13026 C-c C-t C-p @r{Print the DVI file.}
13027 C-c C-t C-q @r{Display the printer queue.}
13031 The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
13032 called the @file{*tex-shell*}. The @code{texinfo-tex-command},
13033 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
13034 commands are all run in this shell.
13036 You can watch the commands operate in the @samp{*tex-shell*} buffer,
13037 and you can switch to and from and use the @samp{*tex-shell*} buffer
13038 as you would any other shell buffer.@refill
13041 The formatting and print commands depend on the values of several variables.
13042 The default values are:@refill
13046 @r{Variable} @r{Default value}
13048 texinfo-texi2dvi-command "texi2dvi"
13049 texinfo-tex-command "tex"
13050 texinfo-texindex-command "texindex"
13051 texinfo-delete-from-print-queue-command "lprm"
13052 texinfo-tex-trailer "@@bye"
13053 tex-start-of-header "%**start"
13054 tex-end-of-header "%**end"
13055 tex-dvi-print-command "lpr -d"
13056 tex-show-queue-command "lpq"
13060 You can change the values of these variables with the @kbd{M-x
13061 edit-options} command (@pxref{Edit Options, , Editing Variable Values,
13062 emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
13063 (@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
13064 Emacs Manual}), or with your @file{.emacs} initialization file
13065 (@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
13067 @cindex Customize Emacs package
13068 @findex Development/Docs/Texinfo Customize group
13069 Beginning with version 20, GNU Emacs offers a user-friendly interface,
13070 called @dfn{Customize}, for changing values of user-definable variables.
13071 @xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
13072 Emacs Manual}, for more details about this. The Texinfo variables can
13073 be found in the @samp{Development/Docs/Texinfo} group, once you invoke
13074 the @kbd{M-x customize} command.
13077 @node Compile-Command, Requirements Summary, Texinfo Mode Printing, Hardcopy
13078 @section Using the Local Variables List
13079 @cindex Local variables
13080 @cindex Compile command for formatting
13081 @cindex Format with the compile command
13083 Yet another way to apply the @TeX{} formatting command to a Texinfo file
13084 is to put that command in a @dfn{local variables list} at the end of the
13085 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
13086 commands as a @code{compile-command} and have Emacs run it by typing
13087 @kbd{M-x compile}. This creates a special shell called the
13088 @file{*compilation*} buffer in which Emacs runs the compile command.
13089 For example, at the end of the @file{gdb.texinfo} file, after the
13090 @code{@@bye}, you could put the following:@refill
13095 compile-command: "texi2dvi gdb.texinfo"
13101 This technique is most often used by programmers who also compile programs
13102 this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
13105 @node Requirements Summary
13106 @section @TeX{} Formatting Requirements Summary
13107 @cindex Requirements for formatting
13108 @cindex Minimal requirements for formatting
13109 @cindex Formatting requirements
13111 Every Texinfo file that is to be input to @TeX{} must begin with a
13112 @code{\input} command and must contain an @code{@@setfilename} command:
13116 @@setfilename @var{arg-not-used-by-@TeX{}}
13120 The first command instructs @TeX{} to load the macros it needs to
13121 process a Texinfo file and the second command opens auxiliary files.
13123 Every Texinfo file must end with a line that terminates @TeX{}'s
13124 processing and forces out unfinished pages:
13130 Strictly speaking, these lines are all a Texinfo file needs to be
13131 processed successfully by @TeX{}.
13133 Usually, however, the beginning includes an @code{@@settitle} command to
13134 define the title of the printed manual, an @code{@@setchapternewpage}
13135 command, a title page, a copyright page, and permissions. Besides an
13136 @code{@@bye}, the end of a file usually includes indices and a table of
13137 contents. (And of course most manuals contain a body of text as well.)
13139 For more information, see:
13141 @item @ref{settitle, , @code{@@settitle}}
13142 @item @ref{setchapternewpage, , @code{@@setchapternewpage}}
13143 @item @ref{Headings, ,Page Headings}
13144 @item @ref{Titlepage & Copyright Page}
13145 @item @ref{Printing Indices & Menus}
13146 @item @ref{Contents}
13150 @node Preparing for TeX
13151 @section Preparing for @TeX{}
13152 @cindex Preparing for @TeX{}
13153 @cindex @TeX{} input initialization
13154 @cindex @code{TEXINPUTS} environment variable
13156 @cindex @b{.profile} initialization file
13157 @cindex @b{.cshrc} initialization file
13158 @cindex Initialization file for @TeX{} input
13160 @TeX{} needs to know where to find the @file{texinfo.tex} file that you
13161 have told it to input with the @samp{\input texinfo} command at the
13162 beginning of the first line. The @file{texinfo.tex} file tells @TeX{}
13163 how to handle @@-commands; it is included in all standard GNU
13166 @pindex texinfo.tex@r{, installing}
13167 Usually, the @file{texinfo.tex} file is put under the default directory
13168 that contains @TeX{} macros
13169 (@file{/usr/local/share/texmf/tex/texinfo/texinfo.tex} by default) when
13170 GNU Emacs or other GNU software is installed. In this case, @TeX{} will
13171 find the file and you do not need to do anything special.
13172 Alternatively, you can put @file{texinfo.tex} in the current directory
13173 when you run @TeX{}, and @TeX{} will find it there.
13175 @pindex epsf.tex@r{, installing}
13176 Also, you should install @file{epsf.tex} in the same place as
13177 @file{texinfo.tex}, if it is not already installed from another
13178 distribution. This file is needed to support the @code{@@image} command
13181 @pindex texinfo.cnf @r{installation}
13182 @cindex Customizing of @TeX{} for Texinfo
13183 @cindex Site-wide Texinfo configuration file
13184 Optionally, you may create an additional @file{texinfo.cnf}, and install
13185 it as well. This file is read by @TeX{} when the @code{@@setfilename}
13186 command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any
13187 commands you like there, according to local site-wide conventions. They
13188 will be read by @TeX{} when processing any Texinfo document. For
13189 example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
13190 (@pxref{A4 Paper}), then all Texinfo documents will be processed with
13191 that page size in effect. If you have nothing to put in
13192 @file{texinfo.cnf}, you do not need to create it.
13195 If neither of the above locations for these system files suffice for
13196 you, you can specify the directories explicitly. For
13197 @file{texinfo.tex}, you can do this by writing the complete path for the
13198 file after the @code{\input} command. Another way, that works for both
13199 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
13200 might read), is to set the @code{TEXINPUTS} environment variable in your
13201 @file{.cshrc} or @file{.profile} file.
13203 Which you use of @file{.cshrc} or @file{.profile} depends on
13204 whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
13205 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
13206 command interpreter. The latter read the @file{.cshrc} file for
13207 initialization information, and the former read @file{.profile}.
13209 In a @file{.cshrc} file, you could use the following @code{csh} command
13213 setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
13217 In a @file{.profile} file, you could use the following @code{sh} command
13222 TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
13227 On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
13228 of the @samp{;} character, instead of @samp{:}, as directory separator
13229 on these systems.}:
13233 set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
13238 It is customary for DOS/Windows users to put such commands in the
13239 @file{autoexec.bat} file, or in the Windows Registry.@refill
13242 These settings would cause @TeX{} to look for @file{\input} file first
13243 in the current directory, indicated by the @samp{.}, then in a
13244 hypothetical user's @file{me/mylib} directory, and finally in a system
13245 directory @file{/usr/lib/tex/macros}.
13247 @cindex Dumping a .fmt file
13248 @cindex Format file, dumping
13249 Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
13250 web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
13251 disadvantage is that then updating @file{texinfo.tex} requires
13252 redumping.) You can do this by running this command, assuming
13253 @file{epsf.tex} is findable by @TeX{}:
13256 initex texinfo @@dump
13259 (@code{@@dump} is a @TeX{} primitive.) You'll then need to move
13260 @file{texinfo.fmt} to wherever your @code{.fmt} files are found;
13261 typically this will be in the subdirectory @file{web2c} of your @TeX{}
13262 installation, for example, @file{/usr/local/share/tex/web2c}.
13265 @node Overfull hboxes
13266 @section Overfull ``hboxes''
13267 @cindex Overfull @samp{hboxes}
13268 @cindex @samp{hboxes}, overfull
13269 @cindex Final output
13271 @TeX{} is sometimes unable to typeset a line without extending it into
13272 the right margin. This can occur when @TeX{} comes upon what it
13273 interprets as a long word that it cannot hyphenate, such as an
13274 electronic mail network address or a very long title. When this
13275 happens, @TeX{} prints an error message like this:
13278 Overfull @@hbox (20.76302pt too wide)
13283 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
13284 @samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
13286 @TeX{} also provides the line number in the Texinfo source file and
13287 the text of the offending line, which is marked at all the places that
13288 @TeX{} considered hyphenation.
13289 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
13290 for more information about typesetting errors.
13292 If the Texinfo file has an overfull hbox, you can rewrite the sentence
13293 so the overfull hbox does not occur, or you can decide to leave it. A
13294 small excursion into the right margin often does not matter and may not
13295 even be noticeable.
13297 If you have many overfull boxes and/or an antipathy to rewriting, you
13298 can coerce @TeX{} into greatly increasing the allowable interword
13299 spacing, thus (if you're lucky) avoiding many of the bad line breaks,
13302 @findex \emergencystretch
13305 \global\emergencystretch = .9\hsize
13310 (You can adjust the fraction as needed.) This huge value for
13311 @code{\emergencystretch} cannot be the default, since then the typeset
13312 output would generally be of noticeably lower quality. The default
13313 value is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
13314 containing the current line width.
13316 @cindex Black rectangle in hardcopy
13317 @cindex Rectangle, black in hardcopy
13318 @cindex Box, ugly black in hardcopy
13319 @cindex Ugly black rectangles in hardcopy
13320 For what overfull boxes you have, however, @TeX{} will print a large,
13321 ugly, black rectangle beside the line that contains the overfull hbox
13322 unless told otherwise. This is so you will notice the location of the
13323 problem if you are correcting a draft.
13326 To prevent such a monstrosity from marring your final printout, write
13327 the following in the beginning of the Texinfo file on a line of its own,
13328 before the @code{@@titlepage} command:
13336 @section Printing ``Small'' Books
13338 @cindex Small book size
13339 @cindex Book, printing small
13340 @cindex Page sizes for books
13341 @cindex Size of printed book
13343 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
13344 format. However, you can direct @TeX{} to typeset a document in a 7 by
13345 9.25 inch format that is suitable for bound books by inserting the
13346 following command on a line by itself at the beginning of the Texinfo
13347 file, before the title page:@refill
13354 (Since many books are about 7 by 9.25 inches, this command might better
13355 have been called the @code{@@regularbooksize} command, but it came to be
13356 called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
13358 If you write the @code{@@smallbook} command between the
13359 start-of-header and end-of-header lines, the Texinfo mode @TeX{}
13360 region formatting command, @code{texinfo-tex-region}, will format the
13361 region in ``small'' book size (@pxref{Start of Header}).@refill
13363 @xref{small}, for information about
13364 commands that make it easier to produce examples for a smaller manual.
13366 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13367 @TeX{}}, for other ways to format with @code{@@smallbook} that do not
13368 require changing the source file.
13372 @section Printing on A4 Paper
13373 @cindex A4 paper, printing on
13374 @cindex Paper size, European A4
13375 @cindex European A4 paper
13378 You can tell @TeX{} to format a document for printing on European size
13379 A4 paper with the @code{@@afourpaper} command. Write the command on a
13380 line by itself near the beginning of the Texinfo file, before the title
13381 page. For example, this is how you would write the header for this
13386 \input texinfo @@c -*-texinfo-*-
13387 @@c %**start of header
13388 @@setfilename texinfo
13391 @@c %**end of header
13395 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13396 @TeX{}}, for other ways to format with @code{@@afourpaper} that do not
13397 require changing the source file.
13400 You may or may not prefer the formatting that results from the command
13401 @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
13406 @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
13408 @cindex Custom page sizes
13409 @cindex Page sizes, customized
13410 @cindex Text width and height
13411 @cindex Width of text area
13412 @cindex Height of text area
13413 @cindex Depth of text area
13415 You can explicitly specify the height and (optionally) width of the main
13416 text area on the page with the @code{@@pagesizes} command. Write this
13417 on a line by itself near the beginning of the Texinfo file, before the
13418 title page. The height comes first, then the width if desired,
13419 separated by a comma. Examples:
13422 @@pagesizes 200mm,150mm @c for b5 paper
13426 @@pagesizes 11.5in @c for legal paper
13429 @cindex B5 paper, printing on
13430 @cindex Legal paper, printing on
13431 This would be reasonable for printing on B5-size paper. To emphasize,
13432 this command specifies the size of the @emph{text area}, not the size of
13433 the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
13434 8.5@dmn{in} for legal).
13436 @cindex Margins on page, not controllable
13437 To make more elaborate changes, such as changing any of the page
13438 margins, you must define a new command in @file{texinfo.tex} (or
13439 @file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
13441 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13442 @TeX{}}, for other ways to specify @code{@@pagesizes} that do not
13443 require changing the source file.
13445 @code{@@pagesizes} is ignored by @code{makeinfo}.
13448 @node Cropmarks and Magnification
13449 @section Cropmarks and Magnification
13451 @cindex Cropmarks for printing
13452 @cindex Printing cropmarks
13453 You can (attempt to) direct @TeX{} to print cropmarks at the corners of
13454 pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
13455 command on a line by itself between @code{@@iftex} and @code{@@end
13456 iftex} lines near the beginning of the Texinfo file, before the title
13457 page, like this:@refill
13467 This command is mainly for printers that typeset several pages on one
13468 sheet of film; but you can attempt to use it to mark the corners of a
13469 book set to 7 by 9.25 inches with the @code{@@smallbook} command.
13470 (Printers will not produce cropmarks for regular sized output that is
13471 printed on regular sized paper.) Since different printing machines work
13472 in different ways, you should explore the use of this command with a
13473 spirit of adventure. You may have to redefine the command in
13474 @file{texinfo.tex}.
13476 @findex mag @r{(@TeX{} command)}
13477 @cindex Magnified printing
13478 @cindex Larger or smaller pages
13479 You can attempt to direct @TeX{} to typeset pages larger or smaller than
13480 usual with the @code{\mag} @TeX{} command. Everything that is typeset
13481 is scaled proportionally larger or smaller. (@code{\mag} stands for
13482 ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
13483 plain @TeX{} command that is prefixed with a backslash. You have to
13484 write this command between @code{@@tex} and @code{@@end tex}
13485 (@pxref{Raw Formatter Commands}).
13487 Follow the @code{\mag} command with an @samp{=} and then a number that
13488 is 1000 times the magnification you desire. For example, to print pages
13489 at 1.2 normal size, write the following near the beginning of the
13490 Texinfo file, before the title page:
13500 With some printing technologies, you can print normal-sized copies that
13501 look better than usual by giving a larger-than-normal master to your
13502 print shop. They do the reduction, thus effectively increasing the
13505 Depending on your system, DVI files prepared with a
13506 nonstandard-@code{\mag} may not print or may print only with certain
13507 magnifications. Be prepared to experiment.
13511 @section PDF Output
13515 You can generate a PDF output file from Texinfo source by using the
13516 @command{pdftex} program to process your file instead of plain
13517 @command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex
13518 foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
13520 PDF stands for Portable Document Format, and was invented by Adobe
13522 @uref{http://www.adobe.com/prodindex/acrobat/adobepdf.html, file format
13523 definition} is freely available, as is a
13524 @uref{http://www.foolabs.com/xpdf/, free viewer} for the X window
13525 system. Since PDF is a binary format, there is no @samp{@@ifpdf} or
13526 @samp{@@pdf} command by analogy with the other output formats.
13528 Despite the `portable' in the name, PDF files are nowhere near as
13529 portable in practice as the plain ASCII formats (Info, HTML) Texinfo
13530 also supports (portability relative to DVI is arguable). They also tend
13531 to be much larger and do not support the bitmap fonts used by @TeX{} (by
13532 default) very well. Nevertheless, a PDF file does preserve an actual
13533 printed document on a screen as faithfully as possible, unlike HTML,
13534 say, so have their place.
13536 PDF support in Texinfo is fairly rudimentary.
13539 @node Creating and Installing Info Files
13540 @chapter Creating and Installing Info Files
13542 This chapter describes how to create and install info files. @xref{Info
13543 Files}, for general information about the file format itself.
13547 * Creating an Info File::
13548 * Install an Info File::
13551 @node Creating an Info File
13552 @section Creating an Info File
13553 @cindex Creating an Info file
13554 @cindex Info, creating an online file
13555 @cindex Formatting a file for Info
13557 @code{makeinfo} is a program that converts a Texinfo file into an Info
13558 file, HTML file, or plain text. @code{texinfo-format-region} and
13559 @code{texinfo-format-buffer} are GNU Emacs functions that convert
13562 For information on installing the Info file in the Info system,
13563 @pxref{Install an Info File}.
13566 * makeinfo advantages:: @code{makeinfo} provides better error checking.
13567 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
13568 * makeinfo options:: Specify fill-column and other options.
13569 * Pointer Validation:: How to check that pointers point somewhere.
13570 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
13571 * texinfo-format commands:: Two Info formatting commands written
13572 in Emacs Lisp are an alternative
13573 to @code{makeinfo}.
13574 * Batch Formatting:: How to format for Info in Emacs Batch mode.
13575 * Tag and Split Files:: How tagged and split files help Info
13577 * makeinfo html:: Generating HTML output.
13581 @node makeinfo advantages
13582 @subsection @code{makeinfo} Preferred
13584 The @code{makeinfo} utility creates an Info file from a Texinfo source
13585 file more quickly than either of the Emacs formatting commands and
13586 provides better error messages. We recommend it. @code{makeinfo} is a
13587 C program that is independent of Emacs. You do not need to run Emacs to
13588 use @code{makeinfo}, which means you can use @code{makeinfo} on machines
13589 that are too small to run Emacs. You can run @code{makeinfo} in any one
13590 of three ways: from an operating system shell, from a shell inside
13591 Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
13592 command in Texinfo mode in Emacs.
13595 The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
13596 commands are useful if you cannot run @code{makeinfo}. Also, in some
13597 circumstances, they format short regions or buffers more quickly than
13598 @code{makeinfo}.@refill
13600 @node Invoking makeinfo
13601 @subsection Running @code{makeinfo} from a Shell
13603 To create an Info file from a Texinfo file, type @code{makeinfo}
13604 followed by the name of the Texinfo file. Thus, to create the Info
13605 file for Bison, type the following to the shell:
13608 makeinfo bison.texinfo
13611 (You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
13614 Sometimes you will want to specify options. For example, if you wish
13615 to discover which version of @code{makeinfo} you are using,
13622 @xref{makeinfo options}, for more information.
13626 @node makeinfo options
13627 @comment node-name, next, previous, up
13628 @subsection Options for @code{makeinfo}
13629 @cindex @code{makeinfo} options
13630 @cindex Options for @code{makeinfo}
13632 The @code{makeinfo} command takes a number of options. Most often,
13633 options are used to set the value of the fill column and specify the
13634 footnote style. Each command line option is a word preceded by
13635 @samp{--} or a letter preceded by @samp{-}. You can use abbreviations
13636 for the long option names as long as they are unique.@refill
13638 For example, you could use the following shell command to create an Info
13639 file for @file{bison.texinfo} in which each line is filled to only 68
13643 makeinfo --fill-column=68 bison.texinfo
13646 You can write two or more options in sequence, like this:@refill
13649 makeinfo --no-split --fill-column=70 @dots{}
13653 This would keep the Info file together as one possibly very long
13654 file and would also set the fill column to 70.@refill
13661 @opindex -D @var{var}
13662 Cause the variable @var{var} to be defined. This is equivalent to
13663 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
13665 @item --commands-in-node-names
13666 @opindex --commands-in-node-names
13667 Allow @code{@@}-commands in node names. This is not recommended, as it
13668 can probably never be implemented in @TeX{}. It also makes
13669 @code{makeinfo} much slower. Also, this option is ignored when
13670 @samp{--no-validate} is used. @xref{Pointer Validation}, for more
13673 @item --error-limit=@var{limit}
13674 @itemx -e @var{limit}
13675 @opindex --error-limit=@var{limit}
13676 @opindex -e @var{limit}
13677 Set the maximum number of errors that @code{makeinfo} will report
13678 before exiting (on the assumption that continuing would be useless);
13681 @item --fill-column=@var{width}
13682 @itemx -f @var{width}
13683 @opindex --fill-column=@var{width}
13684 @opindex -f @var{width}
13685 Specify the maximum number of columns in a line; this is the right-hand
13686 edge of a line. Paragraphs that are filled will be filled to this
13687 width. (Filling is the process of breaking up and connecting lines so
13688 that lines are the same length as or shorter than the number specified
13689 as the fill column. Lines are broken between words.) The default value
13690 is 72. Ignored with @samp{--html}.
13692 @item --footnote-style=@var{style}
13693 @itemx -s @var{style}
13694 @opindex --footnote-style=@var{style}
13695 @opindex -s @var{style}
13696 Set the footnote style to @var{style}, either @samp{end} for the end
13697 node style (the default) or @samp{separate} for the separate node style.
13698 The value set by this option overrides the value set in a Texinfo file
13699 by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
13700 footnote style is @samp{separate}, @code{makeinfo} makes a new node
13701 containing the footnotes found in the current node. When the footnote
13702 style is @samp{end}, @code{makeinfo} places the footnote references at
13703 the end of the current node. Ignored with @samp{--html}.
13709 Ordinarily, if the input file has errors, the output files are not
13710 created. With this option, they are preserved.
13716 Print a usage message listing all available options, then exit successfully.
13719 Generate HTML output rather than Info. @xref{makeinfo html}.
13722 @opindex -I @var{dir}
13723 Append @var{dir} to the directory search list for finding files that
13724 are included using the @code{@@include} command. By default,
13725 @code{makeinfo} searches only the current directory. If @var{dir} is
13726 not given, the current directory @file{.} is appended. Note that
13727 @var{dir} can actually be a list of several directories separated by the
13728 usual path separator character (@samp{:} on Unix, @samp{;} on
13729 MS-DOS/MS-Windows).
13731 @item --macro-expand=@var{file}
13732 @itemx -E @var{file}
13733 Output the Texinfo source with all the macros expanded to the named
13734 file. Normally, the results of macro expansion are used internally by
13735 @code{makeinfo} and then discarded. This option is used by
13736 @command{texi2dvi} if you are using an old version of @file{texinfo.tex}
13737 that does not support @code{@@macro}.
13740 @opindex --no-headers
13741 @cindex Plain text output
13742 @cindex ASCII text output
13743 @cindex Generating plain text files
13744 @cindex @file{INSTALL} file, generating
13745 For Info output, do not include menus or node lines in the output and
13746 write to standard output (unless @option{--output} is specified). This
13747 results in an @sc{ascii} file that you cannot read in Info since it does
13748 not contain the requisite nodes or menus. It is primarily useful to
13749 extract certain pieces of a manual into separate files to be included in
13750 a distribution, such as @file{INSTALL} files.
13752 @cindex Navigation links, omitting
13753 For HTML output, if @samp{--no-split} is also specified, do not include a
13754 navigation links at the top of each node. @xref{makeinfo html}.
13757 @opindex --no-split
13758 @cindex Splitting of output files
13759 @cindex Output file splitting
13760 Suppress the splitting stage of @code{makeinfo}. By default, large
13761 output files (where the size is greater than 70k bytes) are split into
13762 smaller subfiles. For Info output, each one is approximately 50k bytes.
13763 For HTML output, each file contains one node (@pxref{makeinfo html}).
13765 @item --no-pointer-validate
13766 @itemx --no-validate
13767 @opindex --no-pointer-validate
13768 @opindex --no-validate
13769 @cindex Pointer validation, suppressing
13770 Suppress the pointer-validation phase of @code{makeinfo}. This can also
13771 be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
13772 @TeX{}}). Normally, after a Texinfo file is processed, some consistency
13773 checks are made to ensure that cross references can be resolved, etc.
13774 @xref{Pointer Validation}.
13778 Suppress warning messages (but @emph{not} error messages). You might
13779 want this if the file you are creating has examples of Texinfo cross
13780 references within it, and the nodes that are referenced do not actually
13783 @item --number-sections
13784 @opindex --number-sections
13785 Output chapter, section, and appendix numbers as in printed manuals.
13787 @item --no-number-footnotes
13788 @opindex --no-number-footnotes
13789 Suppress automatic footnote numbering. By default, @code{makeinfo}
13790 numbers each footnote sequentially in a single node, resetting the
13791 current footnote number to 1 at the start of each node.
13793 @item --output=@var{file}
13794 @itemx -o @var{file}
13795 @opindex --output=@var{file}
13796 @opindex -o @var{file}
13797 Specify that the output should be directed to @var{file} and not to the
13798 file name specified in the @code{@@setfilename} command found in the
13799 Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
13800 goes to standard output and @samp{--no-split} is implied. For split
13801 HTML output, @var{file} is the name of the output file for the top node
13802 (@pxref{makeinfo html}).
13805 @opindex -P @var{dir}
13806 Prepend @var{dir} to the directory search list for @code{@@include}.
13807 If @var{dir} is not given, the current directory @file{.} is prepended.
13808 See @samp{-I} for more details.
13810 @item --paragraph-indent=@var{indent}
13811 @itemx -p @var{indent}
13812 @opindex --paragraph-indent=@var{indent}
13813 @opindex -p @var{indent}
13814 Set the paragraph indentation style to @var{indent}. The value set by
13815 this option overrides the value set in a Texinfo file by an
13816 @code{@@paragraphindent} command (@pxref{paragraphindent}). The value
13817 of @var{indent} is interpreted as follows:
13821 Preserve any existing indentation at the starts of paragraphs.
13823 @item @samp{0} or @samp{none}
13824 Delete any existing indentation.
13827 Indent each paragraph by @var{num} spaces.
13830 @item --reference-limit=@var{limit}
13831 @itemx -r @var{limit}
13832 @opindex --reference-limit=@var{limit}
13833 @opindex -r @var{limit}
13834 Set the value of the number of references to a node that
13835 @code{makeinfo} will make without reporting a warning. If a node has more
13836 than this number of references in it, @code{makeinfo} will make the
13837 references but also report a warning. The default is 1000.
13840 Cause @var{var} to be undefined. This is equivalent to
13841 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
13845 Cause @code{makeinfo} to display messages saying what it is doing.
13846 Normally, @code{makeinfo} only outputs messages if there are errors or
13853 Print the version number, then exit successfully.
13858 @node Pointer Validation
13859 @subsection Pointer Validation
13860 @cindex Pointer validation with @code{makeinfo}
13861 @cindex Validation of pointers
13863 If you do not suppress pointer validation with the @samp{--no-validate}
13864 option or the @code{@@novalidate} command in the source file (@pxref{Use
13865 TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
13866 Info file. Mostly, this means ensuring that nodes you have referenced
13867 really exist. Here is a complete list of what is checked:
13871 If a `Next', `Previous', or `Up' node reference is a reference to a
13872 node in the current file and is not an external reference such as to
13873 @file{(dir)}, then the referenced node must exist.@refill
13876 In every node, if the `Previous' node is different from the `Up' node,
13877 then the node pointed to by the `Previous' field must have a `Next'
13878 field which points back to this node.@refill
13881 Every node except the `Top' node must have an `Up' pointer.@refill
13884 The node referenced by an `Up' pointer must itself reference the current
13885 node through a menu item, unless the node referenced by `Up'
13886 has the form `(@var{file})'.
13889 If the `Next' reference of a node is not the same as the `Next' reference
13890 of the `Up' reference, then the node referenced by the `Next' pointer
13891 must have a `Previous' pointer that points back to the current node.
13892 This rule allows the last node in a section to point to the first node
13893 of the next chapter.@refill
13896 Every node except `Top' should be referenced by at least one other node,
13897 either via the `Previous' or `Next' links, or via a menu or a
13898 cross-reference.@refill
13901 @cindex @@-commands in @@node, limited support
13902 Some Texinfo documents might fail during the validation phase because
13903 they use commands like @code{@@value} and @code{@@definfoenclose} in
13904 node definitions and cross-references inconsistently. Consider the
13909 @@set nodename Node 1
13911 @@node @@value@{nodename@}, Node 2, Top, Top
13915 @@node Node 2, , Node 1, Top
13922 Here, the node ``Node 1'' was referenced both verbatim and through
13925 By default, @code{makeinfo} fails such cases, because node names are not
13926 fully expanded until they are written to the output file. You should
13927 always try to reference nodes consistently; e.g., in the above example,
13928 the second @code{@@node} line should have also used @code{@@value}.
13929 However, if, for some reason, you @emph{must} reference node names
13930 inconsistently, and @code{makeinfo} fails to validate the file, you can
13931 use the @samp{--commands-in-node-names} option to force @code{makeinfo}
13932 to perform the expensive expansion of all node names it finds in the
13933 document. This might considerably slow down the program, though;
13934 twofold increase in conversion time was measured for large documents
13935 such as the Jargon file.
13937 @cindex @@value in @@node lines
13938 The support for @code{@@}-commands in @code{@@node} directives is not
13939 general enough to be freely used. For example, if the example above
13940 redefined @code{nodename} somewhere in the document, @code{makeinfo}
13941 will fail to convert it, even if invoked with the
13942 @samp{--commands-in-node-names} option.
13944 @samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
13948 @node makeinfo in Emacs
13949 @subsection Running @code{makeinfo} inside Emacs
13950 @cindex Running @code{makeinfo} in Emacs
13951 @cindex @code{makeinfo} inside Emacs
13952 @cindex Shell, running @code{makeinfo} in
13954 You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
13955 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
13956 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
13957 C-m C-b} by default.@refill
13961 @itemx M-x makeinfo-region
13962 Format the current region for Info.@refill
13963 @findex makeinfo-region
13966 @itemx M-x makeinfo-buffer
13967 Format the current buffer for Info.@refill
13968 @findex makeinfo-buffer
13971 When you invoke either @code{makeinfo-region} or
13972 @code{makeinfo-buffer}, Emacs prompts for a file name, offering the
13973 name of the visited file as the default. You can edit the default
13974 file name in the minibuffer if you wish, before pressing @key{RET} to
13975 start the @code{makeinfo} process.@refill
13977 The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
13978 run the @code{makeinfo} program in a temporary shell buffer. If
13979 @code{makeinfo} finds any errors, Emacs displays the error messages in
13980 the temporary buffer.@refill
13982 @cindex Errors, parsing
13983 @cindex Parsing errors
13985 You can parse the error messages by typing @kbd{C-x `}
13986 (@code{next-error}). This causes Emacs to go to and position the
13987 cursor on the line in the Texinfo source that @code{makeinfo} thinks
13988 caused the error. @xref{Compilation, , Running @code{make} or
13989 Compilers Generally, emacs, The GNU Emacs Manual}, for more
13990 information about using the @code{next-error} command.@refill
13992 In addition, you can kill the shell in which the @code{makeinfo}
13993 command is running or make the shell buffer display its most recent
13998 @itemx M-x makeinfo-kill-job
13999 @findex makeinfo-kill-job
14000 Kill the current running @code{makeinfo} job
14001 (from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
14004 @itemx M-x makeinfo-recenter-output-buffer
14005 @findex makeinfo-recenter-output-buffer
14006 Redisplay the @code{makeinfo} shell buffer to display its most recent
14011 (Note that the parallel commands for killing and recentering a @TeX{}
14012 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
14015 You can specify options for @code{makeinfo} by setting the
14016 @code{makeinfo-options} variable with either the @kbd{M-x
14017 edit-options} or the @kbd{M-x set-variable} command, or by setting the
14018 variable in your @file{.emacs} initialization file.@refill
14020 For example, you could write the following in your @file{.emacs} file:@refill
14024 (setq makeinfo-options
14025 "--paragraph-indent=0 --no-split
14026 --fill-column=70 --verbose")
14030 @c If you write these three cross references using xref, you see
14031 @c three references to the same named manual, which looks strange.
14033 For more information, see @ref{makeinfo options, , Options for
14034 @code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining
14035 and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs
14040 For more information, see@*
14041 @ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
14042 @ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
14043 @ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
14044 @ref{makeinfo options, , Options for @code{makeinfo}}.
14047 @node texinfo-format commands
14048 @comment node-name, next, previous, up
14049 @subsection The @code{texinfo-format@dots{}} Commands
14050 @findex texinfo-format-region
14051 @findex texinfo-format-buffer
14053 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
14054 file with the @code{texinfo-format-region} command. This formats the
14055 current region and displays the formatted text in a temporary buffer
14056 called @samp{*Info Region*}.@refill
14058 Similarly, you can format a buffer with the
14059 @code{texinfo-format-buffer} command. This command creates a new
14060 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
14061 save the Info file under the name specified by the
14062 @code{@@setfilename} line which must be near the beginning of the
14063 Texinfo file.@refill
14067 @itemx @code{texinfo-format-region}
14068 Format the current region for Info.
14069 @findex texinfo-format-region
14072 @itemx @code{texinfo-format-buffer}
14073 Format the current buffer for Info.
14074 @findex texinfo-format-buffer
14077 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
14078 commands provide you with some error checking, and other functions can
14079 provide you with further help in finding formatting errors. These
14080 procedures are described in an appendix; see @ref{Catching Mistakes}.
14081 However, the @code{makeinfo} program is often faster and
14082 provides better error checking (@pxref{makeinfo in Emacs}).@refill
14084 @node Batch Formatting
14085 @comment node-name, next, previous, up
14086 @subsection Batch Formatting
14087 @cindex Batch formatting for Info
14088 @cindex Info batch formatting
14090 You can format Texinfo files for Info using @code{batch-texinfo-format}
14091 and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
14092 including a shell inside of Emacs. (@xref{Command Switches, , Command
14093 Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
14095 Here is a shell command to format all the files that end in
14096 @file{.texinfo} in the current directory:
14099 emacs -batch -funcall batch-texinfo-format *.texinfo
14103 Emacs processes all the files listed on the command line, even if an
14104 error occurs while attempting to format some of them.@refill
14106 Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
14107 it is not interactive. It kills the Batch mode Emacs on completion.@refill
14109 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
14110 and want to format several Texinfo files at once. When you use Batch
14111 mode, you create a new Emacs process. This frees your current Emacs, so
14112 you can continue working in it. (When you run
14113 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
14114 use that Emacs for anything else until the command finishes.)@refill
14116 @node Tag and Split Files
14117 @comment node-name, next, previous, up
14118 @subsection Tag Files and Split Files
14119 @cindex Making a tag table automatically
14120 @cindex Tag table, making automatically
14122 If a Texinfo file has more than 30,000 bytes,
14123 @code{texinfo-format-buffer} automatically creates a tag table
14124 for its Info file; @code{makeinfo} always creates a tag table. With
14125 a @dfn{tag table}, Info can jump to new nodes more quickly than it can
14128 @cindex Indirect subfiles
14129 In addition, if the Texinfo file contains more than about 70,000
14130 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
14131 large Info file into shorter @dfn{indirect} subfiles of about 50,000
14132 bytes each. Big files are split into smaller files so that Emacs does
14133 not need to make a large buffer to hold the whole of a large Info
14134 file; instead, Emacs allocates just enough memory for the small, split-off
14135 file that is needed at the time. This way, Emacs avoids wasting
14136 memory when you run Info. (Before splitting was implemented, Info
14137 files were always kept short and @dfn{include files} were designed as
14138 a way to create a single, large printed manual out of the smaller Info
14139 files. @xref{Include Files}, for more information. Include files are
14140 still used for very large documents, such as @cite{The Emacs Lisp
14141 Reference Manual}, in which each chapter is a separate file.)@refill
14143 When a file is split, Info itself makes use of a shortened version of
14144 the original file that contains just the tag table and references to
14145 the files that were split off. The split-off files are called
14146 @dfn{indirect} files.@refill
14148 The split-off files have names that are created by appending @w{@samp{-1}},
14149 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
14150 @code{@@setfilename} command. The shortened version of the original file
14151 continues to have the name specified by @code{@@setfilename}.@refill
14153 At one stage in writing this document, for example, the Info file was saved
14154 as the file @file{test-texinfo} and that file looked like this:@refill
14158 Info file: test-texinfo, -*-Text-*-
14159 produced by texinfo-format-buffer
14160 from file: new-texinfo-manual.texinfo
14164 test-texinfo-1: 102
14165 test-texinfo-2: 50422
14168 test-texinfo-3: 101300
14172 Node: overview^?104
14173 Node: info file^?1271
14176 Node: printed manual^?4853
14177 Node: conventions^?6855
14183 (But @file{test-texinfo} had far more nodes than are shown here.) Each of
14184 the split-off, indirect files, @file{test-texinfo-1},
14185 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
14186 after the line that says @samp{Indirect:}. The tag table is listed after
14187 the line that says @samp{Tag table:}. @refill
14189 In the list of indirect files, the number following the file name
14190 records the cumulative number of bytes in the preceding indirect files,
14191 not counting the file list itself, the tag table, or the permissions
14192 text in each file. In the tag table, the number following the node name
14193 records the location of the beginning of the node, in bytes from the
14194 beginning of the (unsplit) output.
14196 If you are using @code{texinfo-format-buffer} to create Info files,
14197 you may want to run the @code{Info-validate} command. (The
14198 @code{makeinfo} command does such a good job on its own, you do not
14199 need @code{Info-validate}.) However, you cannot run the @kbd{M-x
14200 Info-validate} node-checking command on indirect files. For
14201 information on how to prevent files from being split and how to
14202 validate the structure of the nodes, see @ref{Using
14203 Info-validate}.@refill
14206 @node makeinfo html
14207 @subsection Generating HTML
14210 As an alternative to the normal Info format output you can use the
14211 @samp{--html} option to generate output in HTML format, for installation
14212 on a web site (for example). In this release, HTML output from
14213 @code{makeinfo} is monolithic, splitting the output by chapter or node
14214 is not supported. We hope to implement this feature soon.
14216 The HTML output file is named according to @code{@@setfilename}, but
14217 with any @samp{.info} extension replaced with @samp{.html}.
14219 Texinfo input marked up with the @code{@@ifhtml} command will produce
14220 output only with the @samp{--html} option supplied. Input marked up
14221 with the @code{@@html} is passed literally to the output (suppressing
14222 the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
14223 which have special significance in HTML).
14225 The @samp{--footnote-style} option is currently ignored for HTML output;
14226 footnotes are hyperlinked at the end of the output file.
14228 The HTML generated is mostly standard (i.e., HTML 2.0, RFC1866). The
14229 exception is that HTML 3.2 tables are generated from the
14230 @code{@@multitable} command, but tagged to degrade as well as possible
14231 in browsers without table support. Please report output from an
14232 error-free run of @code{makeinfo} which violates the HTML 3.2 DTD as a
14235 Navigation bars are inserted at the start of nodes, similarly to Info
14236 output. The @samp{--no-headers} option will suppress this if used with
14237 @samp{--no-split}. Header @code{<link>} elements in split output can
14238 support info-like navigation with browsers like Lynx and @w{Emacs W3}
14239 which implement this @w{HTML 1.0} feature. You still won't normally get
14240 the multi-file regexp and index search facilities provided by Info
14241 readers. Otherwise, hyperlinks are generated from Texinfo commands
14242 where appropriate. @samp{@@xref} commands to other documents are
14243 generated assuming the other document is available in HTML form too, and
14244 @samp{.html} is appended to the @samp{@@xref} Info file name. This
14245 presumably will often not work.
14248 @node Install an Info File
14249 @section Installing an Info File
14250 @cindex Installing an Info file
14251 @cindex Info file installation
14252 @cindex @file{dir} directory for Info installation
14254 Info files are usually kept in the @file{info} directory. You can read
14255 Info files using the standalone Info program or the Info reader built
14256 into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
14259 * Directory File:: The top level menu for all Info files.
14260 * New Info File:: Listing a new info file.
14261 * Other Info Directories:: How to specify Info files that are
14262 located in other directories.
14263 * Installing Dir Entries:: How to specify what menu entry to add
14264 to the Info directory.
14265 * Invoking install-info:: @code{install-info} options.
14269 @node Directory File
14270 @subsection The Directory File @file{dir}
14272 For Info to work, the @file{info} directory must contain a file that
14273 serves as a top level directory for the Info system. By convention,
14274 this file is called @file{dir}. (You can find the location of this file
14275 within Emacs by typing @kbd{C-h i} to enter Info and then typing
14276 @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
14278 The @file{dir} file is itself an Info file. It contains the top level
14279 menu for all the Info files in the system. The menu looks like
14285 * Info: (info). Documentation browsing system.
14286 * Emacs: (emacs). The extensible, self-documenting
14288 * Texinfo: (texinfo). With one source file, make
14289 either a printed manual using
14290 TeX or an Info file.
14295 Each of these menu entries points to the `Top' node of the Info file
14296 that is named in parentheses. (The menu entry does not need to
14297 specify the `Top' node, since Info goes to the `Top' node if no node
14298 name is mentioned. @xref{Other Info Files, , Nodes in Other Info
14301 Thus, the @samp{Info} entry points to the `Top' node of the
14302 @file{info} file and the @samp{Emacs} entry points to the `Top' node
14303 of the @file{emacs} file.@refill
14305 In each of the Info files, the `Up' pointer of the `Top' node refers
14306 back to the @code{dir} file. For example, the line for the `Top'
14307 node of the Emacs manual looks like this in Info:@refill
14310 File: emacs Node: Top, Up: (DIR), Next: Distrib
14314 In this case, the @file{dir} file name is written in upper case
14315 letters---it can be written in either upper or lower case. This is not
14316 true in general, it is a special case for @file{dir}.
14319 @node New Info File
14320 @subsection Listing a New Info File
14321 @cindex Adding a new info file
14322 @cindex Listing a new info file
14323 @cindex New info file, listing it in @file{dir} file
14324 @cindex Info file, listing a new
14325 @cindex @file{dir} file listing
14327 To add a new Info file to your system, you must write a menu entry to
14328 add to the menu in the @file{dir} file in the @file{info} directory.
14329 For example, if you were adding documentation for GDB, you would write
14330 the following new entry:@refill
14333 * GDB: (gdb). The source-level C debugger.
14337 The first part of the menu entry is the menu entry name, followed by a
14338 colon. The second part is the name of the Info file, in parentheses,
14339 followed by a period. The third part is the description.
14341 The name of an Info file often has a @file{.info} extension. Thus, the
14342 Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
14343 The Info reader programs automatically try the file name both with and
14344 without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
14345 try the @file{.inf} extension as well.}; so it is better to avoid
14346 clutter and not to write @samp{.info} explicitly in the menu entry. For
14347 example, the GDB menu entry should use just @samp{gdb} for the file
14348 name, not @samp{gdb.info}.
14351 @node Other Info Directories
14352 @subsection Info Files in Other Directories
14353 @cindex Installing Info in another directory
14354 @cindex Info installed in another directory
14355 @cindex Another Info directory
14356 @cindex @file{dir} files and Info directories
14358 If an Info file is not in the @file{info} directory, there are three
14359 ways to specify its location:@refill
14363 Write the pathname in the @file{dir} file as the second part of the menu.
14366 If you are using Emacs, list the name of the file in a second @file{dir}
14367 file, in its directory; and then add the name of that directory to the
14368 @code{Info-directory-list} variable in your personal or site
14369 initialization file.
14371 This variable tells Emacs where to look for @file{dir} files (the files
14372 must be named @file{dir}). Emacs merges the files named @file{dir} from
14373 each of the listed directories. (In Emacs version 18, you can set the
14374 @code{Info-directory} variable to the name of only one
14378 Specify the Info directory name in the @code{INFOPATH} environment
14379 variable in your @file{.profile} or @file{.cshrc} initialization file.
14380 (Only you and others who set this environment variable will be able to
14381 find Info files whose location is specified this way.)
14384 For example, to reach a test file in the @file{/home/bob/info}
14385 directory, you could add an entry like this to the menu in the
14386 standard @file{dir} file:@refill
14389 * Test: (/home/bob/info/info-test). Bob's own test file.
14393 In this case, the absolute file name of the @file{info-test} file is
14394 written as the second part of the menu entry.@refill
14396 Alternatively, you could write the following in your @file{.emacs}
14399 @vindex Info-directory-list
14403 (setq Info-directory-list
14404 (cons (expand-file-name "/home/bob/info") Info-directory-list))
14408 This tells Emacs to merge the @file{dir} file from the
14409 @file{/home/bob/info} directory with the system @file{dir} file. Info
14410 will list the @file{/home/bob/info/info-test} file as a menu entry in
14411 the @file{/home/bob/info/dir} file. Emacs does the merging only
14412 when @kbd{M-x info} is first run, so if you want to set
14413 @code{Info-directory-list} in an Emacs session where you've already run
14414 @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
14415 to recompose the @file{dir} file.
14418 Finally, you can tell Info where to look by setting the @code{INFOPATH}
14419 environment variable in your shell startup file, such as @file{.cshrc},
14420 @file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible
14421 shell such as @code{sh} or @code{bash} for your shell command
14422 interpreter, you set the @code{INFOPATH} environment variable in the
14423 @file{.profile} initialization file; but if you use @code{csh} or
14424 @code{tcsh}, you set the variable in the @file{.cshrc} initialization
14425 file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
14426 your @file{autoexec.bat} file or in the Registry. Each type of shell
14427 uses a different syntax.
14431 In a @file{.cshrc} file, you could set the @code{INFOPATH}
14432 variable as follows:@refill
14435 setenv INFOPATH .:~/info:/usr/local/emacs/info
14439 In a @file{.profile} file, you would achieve the same effect by
14443 INFOPATH=.:$HOME/info:/usr/local/emacs/info
14448 @pindex autoexec.bat
14449 In a @file{autoexec.bat} file, you write this command@footnote{Note the
14450 use of @samp{;} as the directory separator, and a different syntax for
14451 using values of other environment variables.}:
14454 set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
14459 The @samp{.} indicates the current directory as usual. Emacs uses the
14460 @code{INFOPATH} environment variable to initialize the value of Emacs's
14461 own @code{Info-directory-list} variable. The stand-alone Info reader
14462 merges any files named @file{dir} in any directory listed in the
14463 @env{INFOPATH} variable into a single menu presented to you in the node
14464 called @samp{(dir)Top}.
14466 @cindex @samp{:} @r{last in @env{INFOPATH}}
14467 However you set @env{INFOPATH}, if its last character is a
14468 colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
14469 is replaced by the default (compiled-in) path. This gives you a way to
14470 augment the default path with new directories without having to list all
14471 the standard places. For example (using @code{sh} syntax):
14474 INFOPATH=/local/info:
14479 will search @file{/local/info} first, then the standard directories.
14480 Leading or doubled colons are not treated specially.
14482 @cindex @file{dir} file, creating your own
14483 When you create your own @file{dir} file for use with
14484 @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
14485 copying an existing @file{dir} file and replace all the text after the
14486 @samp{* Menu:} with your desired entries. That way, the punctuation and
14487 special CTRL-_ characters that Info needs will be present.
14490 @node Installing Dir Entries, Invoking install-info, Other Info Directories, Install an Info File
14491 @subsection Installing Info Directory Files
14493 When you install an Info file onto your system, you can use the program
14494 @code{install-info} to update the Info directory file @file{dir}.
14495 Normally the makefile for the package runs @code{install-info}, just
14496 after copying the Info file into its proper installed location.
14498 @findex dircategory
14500 In order for the Info file to work with @code{install-info}, you should
14501 use the commands @code{@@dircategory} and
14502 @code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
14503 file. Use @code{@@direntry} to specify the menu entries to add to the
14504 Info directory file, and use @code{@@dircategory} to specify which part
14505 of the Info directory to put it in. Here is how these commands are used
14509 @@dircategory Texinfo documentation system
14511 * Texinfo: (texinfo). The GNU documentation format.
14512 * install-info: (texinfo)Invoking install-info. @dots{}
14517 Here's what this produces in the Info file:
14520 INFO-DIR-SECTION Texinfo documentation system
14521 START-INFO-DIR-ENTRY
14522 * Texinfo: (texinfo). The GNU documentation format.
14523 * install-info: (texinfo)Invoking install-info. @dots{}
14529 The @code{install-info} program sees these lines in the Info file, and
14530 that is how it knows what to do.
14532 Always use the @code{@@direntry} and @code{@@dircategory} commands near
14533 the beginning of the Texinfo input, before the first @code{@@node}
14534 command. If you use them later on in the input, @code{install-info}
14535 will not notice them.
14537 If you use @code{@@dircategory} more than once in the Texinfo source,
14538 each usage specifies the `current' category; any subsequent
14539 @code{@@direntry} commands will add to that category.
14541 Here are some recommended @code{@@dircategory} categories: `GNU
14542 packages', `GNU programming tools', `GNU programming documentation',
14543 `GNU Emacs Lisp', `GNU libraries', `Linux', `TeX', `Individual
14544 utilities'. The idea is to include the `invoking' node for every
14545 program installed by a package under `Individual utilities', and an
14546 entry for the manual as a whole in the appropriate other category.
14549 @node Invoking install-info
14550 @subsection Invoking install-info
14552 @pindex install-info
14554 @code{install-info} inserts menu entries from an Info file into the
14555 top-level @file{dir} file in the Info system (see the previous sections
14556 for an explanation of how the @file{dir} file works). It's most often
14557 run as part of software installation, or when constructing a @file{dir} file
14558 for all manuals on a system. Synopsis:
14561 install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
14564 If @var{info-file} or @var{dir-file} are not specified, the options
14565 (described below) that define them must be. There are no compile-time
14566 defaults, and standard input is never used. @code{install-info} can
14567 read only one Info file and write only one @file{dir} file per invocation.
14569 @cindex @file{dir}, created by @code{install-info}
14570 If @var{dir-file} (however specified) does not exist,
14571 @code{install-info} creates it if possible (with no entries).
14573 @cindex Compressed files, reading
14574 @cindex Dir files, compressed
14575 If any input file is compressed with @code{gzip} (@pxref{Invoking
14576 gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
14577 for reading. And if @var{dir-file} is compressed, @code{install-info}
14578 also automatically leaves it compressed after writing any changes.
14579 If @var{dir-file} itself does not exist, @code{install-info} tries to
14580 open @file{@var{dir-file}.gz}.
14587 Delete the entries in @var{info-file} from @var{dir-file}. The file
14588 name in the entry in @var{dir-file} must be @var{info-file} (except for
14589 an optional @samp{.info} in either one). Don't insert any new entries.
14591 @item --dir-file=@var{name}
14592 @itemx -d @var{name}
14593 @opindex --dir-file=@var{name}
14594 @opindex -d @var{name}
14595 Specify file name of the Info directory file. This is equivalent to
14596 using the @var{dir-file} argument.
14598 @item --entry=@var{text}
14599 @itemx -e @var{text}
14600 @opindex --entry=@var{text}
14601 @opindex -e @var{text}
14602 Insert @var{text} as an Info directory entry; @var{text} should have the
14603 form of an Info menu item line plus zero or more extra lines starting
14604 with whitespace. If you specify more than one entry, they are all
14605 added. If you don't specify any entries, they are determined from
14606 information in the Info file itself.
14612 Display a usage message listing basic usage and all available options,
14613 then exit successfully.
14615 @item --info-file=@var{file}
14616 @itemx -i @var{file}
14617 @opindex --info-file=@var{file}
14618 @opindex -i @var{file}
14619 Specify Info file to install in the directory.
14620 Equivalent to using the @var{info-file} argument.
14622 @item --info-dir=@var{dir}
14623 @itemx -D @var{dir}
14624 @opindex --info-dir=@var{dir}
14625 @opindex -D @var{dir}
14626 Specify the directory where @file{dir} resides.
14627 Equivalent to @samp{--dir-file=@var{dir}/dir}.
14629 @item --item=@var{text}
14630 @opindex --item=@var{text}
14631 Same as @samp{--entry=@var{text}}. An Info directory entry is actually
14642 Same as @samp{--delete}.
14644 @item --section=@var{sec}
14645 @itemx -s @var{sec}
14646 @opindex --section=@var{sec}
14647 @opindex -s @var{sec}
14648 Put this file's entries in section @var{sec} of the directory. If you
14649 specify more than one section, all the entries are added in each of the
14650 sections. If you don't specify any sections, they are determined from
14651 information in the Info file itself.
14657 @cindex version number, finding
14658 Display version information and exit successfully.
14664 @appendix @@-Command List
14665 @cindex Alphabetical @@-command list
14666 @cindex List of @@-commands
14667 @cindex @@-command list
14668 @cindex Reference to @@-commands
14670 Here is an alphabetical list of the @@-commands in Texinfo. Square
14671 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
14672 @samp{@dots{}}, indicates repeated text.
14676 @item @@@var{whitespace}
14677 An @code{@@} followed by a space, tab, or newline produces a normal,
14678 stretchable, interword space. @xref{Multiple Spaces}.
14681 Generate an exclamation point that really does end a sentence (usually
14682 after an end-of-sentence capital letter). @xref{Ending a Sentence}.
14686 Generate an umlaut or acute accent, respectively, over the next
14687 character, as in @"o and @'o. @xref{Inserting Accents}.
14690 Force a line break. Do not end a paragraph that uses @code{@@*} with
14691 an @code{@@refill} command. @xref{Line Breaks}.@refill
14693 @item @@,@{@var{c}@}
14694 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
14698 Insert a discretionary hyphenation point. @xref{- and hyphenation}.
14701 Produce a period that really does end a sentence (usually after an
14702 end-of-sentence capital letter). @xref{Ending a Sentence}.
14705 Indicate to @TeX{} that an immediately preceding period, question
14706 mark, exclamation mark, or colon does not end a sentence. Prevent
14707 @TeX{} from inserting extra whitespace as it does at the end of a
14708 sentence. The command has no effect on the Info file output.
14709 @xref{Not Ending a Sentence}.
14712 Generate a macron (bar) accent over the next character, as in @=o.
14713 @xref{Inserting Accents}.
14716 Generate a question mark that really does end a sentence (usually after
14717 an end-of-sentence capital letter). @xref{Ending a Sentence}.
14720 Stands for an at sign, @samp{@@}.
14721 @xref{Braces Atsigns, , Inserting @@ and braces}.
14725 Generate a circumflex (hat) or grave accent, respectively, over the next
14726 character, as in @^o.
14727 @xref{Inserting Accents}.
14730 Stands for a left brace, @samp{@{}.
14731 @xref{Braces Atsigns, , Inserting @@ and braces}.
14734 Stands for a right-hand brace, @samp{@}}.@*
14735 @xref{Braces Atsigns, , Inserting @@ and braces}.
14738 Generate a tilde accent over the next character, as in @~N.
14739 @xref{Inserting Accents}.
14743 Generate the uppercase and lowercase Scandinavian A-ring letters,
14744 respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
14746 @item @@acronym@{@var{abbrev}@}
14747 Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
14748 capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
14752 Generate the uppercase and lowercase AE ligatures, respectively:
14753 @AE{}, @ae{}. @xref{Inserting Accents}.
14756 @itemx @@afourpaper
14758 Change page dimensions for the A4 paper size. @xref{A4 Paper}.
14760 @item @@alias @var{new}=@var{existing}
14761 Make the command @samp{@@@var{new}} an alias for the existing command
14762 @samp{@@@var{existing}}. @xref{alias}.
14764 @item @@anchor@{@var{name}@}
14765 Define @var{name} as the current location for use as a cross-reference
14766 target. @xref{anchor,, @code{@@anchor}}.
14768 @item @@appendix @var{title}
14769 Begin an appendix. The title appears in the table
14770 of contents of a printed manual. In Info, the title is
14771 underlined with asterisks. @xref{unnumbered & appendix, , The
14772 @code{@@unnumbered} and @code{@@appendix} Commands}.@refill
14774 @item @@appendixsec @var{title}
14775 @itemx @@appendixsection @var{title}
14776 Begin an appendix section within an appendix. The section title appears
14777 in the table of contents of a printed manual. In Info, the title is
14778 underlined with equal signs. @code{@@appendixsection} is a longer
14779 spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
14780 appendixsec heading, , Section Commands}.@refill
14782 @item @@appendixsubsec @var{title}
14783 Begin an appendix subsection within an appendix. The title appears
14784 in the table of contents of a printed manual. In Info, the title is
14785 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
14786 subheading, , Subsection Commands}.@refill
14788 @item @@appendixsubsubsec @var{title}
14789 Begin an appendix subsubsection within an appendix subsection. The
14790 title appears in the table of contents of a printed manual. In Info,
14791 the title is underlined with periods. @xref{subsubsection,, The
14792 `subsub' Commands}.@refill
14795 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
14796 print the table's first column without highlighting (``as is'').
14797 @xref{Two-column Tables, , Making a Two-column Table}.@refill
14799 @item @@author @var{author}
14800 Typeset @var{author} flushleft and underline it. @xref{title
14801 subtitle author, , The @code{@@title} and @code{@@author}
14804 @item @@b@{@var{text}@}
14805 Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill
14809 Force a paragraph break. If used within a line, follow @code{@@br}
14810 with braces. @xref{br, , @code{@@br}}.@refill
14814 Generate a large round dot, or the closest possible
14815 thing to one. @xref{bullet, , @code{@@bullet}}.@refill
14818 Stop formatting a file. The formatters do not see the contents of a
14819 file following an @code{@@bye} command. @xref{Ending a File}.@refill
14821 @item @@c @var{comment}
14822 Begin a comment in Texinfo. The rest of the line does not appear in
14823 either the Info file or the printed manual. A synonym for
14824 @code{@@comment}. @xref{Comments, , Comments}.@refill
14827 Highlight an example or quotation by drawing a box with rounded
14828 corners around it. Pair with @code{@@end cartouche}. No effect in
14829 Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
14831 @item @@center @var{line-of-text}
14832 Center the line of text following the command.
14833 @xref{titlefont center sp, , @code{@@center}}.@refill
14835 @item @@centerchap @var{line-of-text}
14836 Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
14839 @item @@chapheading @var{title}
14840 Print a chapter-like heading in the text, but not in the table of
14841 contents of a printed manual. In Info, the title is underlined with
14842 asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
14843 and @code{@@chapheading}}.@refill
14845 @item @@chapter @var{title}
14846 Begin a chapter. The chapter title appears in the table of
14847 contents of a printed manual. In Info, the title is underlined with
14848 asterisks. @xref{chapter, , @code{@@chapter}}.@refill
14850 @item @@cindex @var{entry}
14851 Add @var{entry} to the index of concepts. @xref{Index Entries, ,
14852 Defining the Entries of an Index}.@refill
14854 @item @@cite@{@var{reference}@}
14855 Highlight the name of a book or other reference that lacks a
14856 companion Info file. @xref{cite, , @code{@@cite}}.@refill
14858 @item @@clear @var{flag}
14859 Unset @var{flag}, preventing the Texinfo formatting commands from
14860 formatting text between subsequent pairs of @code{@@ifset @var{flag}}
14861 and @code{@@end ifset} commands, and preventing
14862 @code{@@value@{@var{flag}@}} from expanding to the value to which
14864 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
14866 @item @@code@{@var{sample-code}@}
14867 Highlight text that is an expression, a syntactically complete token
14868 of a program, or a program name. @xref{code, , @code{@@code}}.@refill
14870 @item @@command@{@var{command-name}@}
14871 Indicate a command name, such as @command{ls}.
14872 @xref{command,, @code{@@command}}.
14874 @item @@comment @var{comment}
14875 Begin a comment in Texinfo. The rest of the line does not appear in
14876 either the Info file or the printed manual. A synonym for @code{@@c}.
14880 Print a complete table of contents. Has no effect in Info, which uses
14881 menus instead. @xref{Contents, , Generating a Table of
14884 @item @@copyright@{@}
14885 Generate a copyright symbol. @xref{copyright symbol, ,
14886 @code{@@copyright}}.@refill
14889 @item @@ctrl@{@var{ctrl-char}@}
14890 Describe an @sc{ascii} control character. Insert actual control character
14891 into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
14894 @item @@defcodeindex @var{index-name}
14895 Define a new index and its indexing command. Print entries in an
14896 @code{@@code} font. @xref{New Indices, , Defining New
14899 @item @@defcv @var{category} @var{class} @var{name}
14900 @itemx @@defcvx @var{category} @var{class} @var{name}
14901 Format a description for a variable associated with a class in
14902 object-oriented programming. Takes three arguments: the category of
14903 thing being defined, the class to which it belongs, and its name.
14904 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
14906 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
14907 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
14908 Format a description for a function, interactive command, or similar
14909 entity that may take arguments. @code{@@deffn} takes as arguments the
14910 category of entity being described, the name of this particular
14911 entity, and its arguments, if any. @xref{Definition Commands}.@refill
14913 @item @@defindex @var{index-name}
14914 Define a new index and its indexing command. Print entries in a roman
14915 font. @xref{New Indices, , Defining New Indices}.@refill
14917 @item @@definfoenclose @var{newcmd}, @var{before}, @var{after},
14918 Create new @@-command @var{newcmd} for Info that marks text by enclosing
14919 it in strings that precede and follow the text. @xref{definfoenclose}.
14921 @item @@defivar @var{class} @var{instance-variable-name}
14922 @itemx @@defivarx @var{class} @var{instance-variable-name}
14923 This command formats a description for an instance variable in
14924 object-oriented programming. The command is equivalent to @samp{@@defcv
14925 @{Instance Variable@} @dots{}}. @xref{Definition Commands}, and
14926 @ref{deffnx,, Def Cmds in Detail}.
14928 @item @@defmac @var{macroname} @var{arguments}@dots{}
14929 @itemx @@defmacx @var{macroname} @var{arguments}@dots{}
14930 Format a description for a macro. The command is equivalent to
14931 @samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and
14932 @ref{deffnx,, Def Cmds in Detail}.
14934 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
14935 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
14936 Format a description for a method in object-oriented programming. The
14937 command is equivalent to @samp{@@defop Method @dots{}}. Takes as
14938 arguments the name of the class of the method, the name of the
14939 method, and its arguments, if any. @xref{Definition Commands}, and
14940 @ref{deffnx,, Def Cmds in Detail}.
14942 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
14943 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
14944 Format a description for an operation in object-oriented programming.
14945 @code{@@defop} takes as arguments the overall name of the category of
14946 operation, the name of the class of the operation, the name of the
14947 operation, and its arguments, if any. @xref{Definition
14948 Commands}, and @ref{Abstract Objects}.
14950 @item @@defopt @var{option-name}
14951 @itemx @@defoptx @var{option-name}
14952 Format a description for a user option. The command is equivalent to
14953 @samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and
14954 @ref{deffnx,, Def Cmds in Detail}.
14956 @item @@defspec @var{special-form-name} @var{arguments}@dots{}
14957 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
14958 Format a description for a special form. The command is equivalent to
14959 @samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands},
14960 and @ref{deffnx,, Def Cmds in Detail}.
14962 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
14963 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
14964 Format a description for a data type. @code{@@deftp} takes as arguments
14965 the category, the name of the type (which is a word like @samp{int} or
14966 @samp{float}), and then the names of attributes of objects of that type.
14967 @xref{Definition Commands}, and @ref{Data Types}.
14969 @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
14970 @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
14971 Format a description for a function or similar entity that may take
14972 arguments and that is typed. @code{@@deftypefn} takes as arguments the
14973 classification of entity being described, the type, the name of the
14974 entity, and its arguments, if any. @xref{Definition Commands}, and
14975 @ref{deffnx,, Def Cmds in Detail}.
14977 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
14978 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
14979 Format a description for a function in a typed language.
14980 The command is equivalent to @samp{@@deftypefn Function @dots{}}.
14981 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
14983 @item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
14984 @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
14985 Format a description for a typed instance variable in object-oriented
14986 programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
14988 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
14989 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
14990 Format a description for a typed method in object-oriented programming.
14991 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
14993 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
14994 @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
14995 Format a description for a typed operation in object-oriented programming.
14996 @xref{Definition Commands}, and @ref{Abstract Objects}.
14998 @item @@deftypevar @var{data-type} @var{variable-name}
14999 @itemx @@deftypevarx @var{data-type} @var{variable-name}
15000 Format a description for a variable in a typed language. The command is
15001 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
15002 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15004 @item @@deftypevr @var{classification} @var{data-type} @var{name}
15005 @itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
15006 Format a description for something like a variable in a typed
15007 language---an entity that records a value. Takes as arguments the
15008 classification of entity being described, the type, and the name of the
15009 entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
15012 @item @@defun @var{function-name} @var{arguments}@dots{}
15013 @itemx @@defunx @var{function-name} @var{arguments}@dots{}
15014 Format a description for functions. The command is equivalent to
15015 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
15016 @ref{deffnx,, Def Cmds in Detail}.
15018 @item @@defvar @var{variable-name}
15019 @itemx @@defvarx @var{variable-name}
15020 Format a description for variables. The command is equivalent to
15021 @samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and
15022 @ref{deffnx,, Def Cmds in Detail}.
15024 @item @@defvr @var{category} @var{name}
15025 @itemx @@defvrx @var{category} @var{name}
15026 Format a description for any kind of variable. @code{@@defvr} takes
15027 as arguments the category of the entity and the name of the entity.
15028 @xref{Definition Commands},
15029 and @ref{deffnx,, Def Cmds in Detail}.
15032 Avoid @code{makeinfo} confusion stemming from the detailed node listing
15033 in a master menu. @xref{Master Menu Parts}.
15035 @item @@dfn@{@var{term}@}
15036 Highlight the introductory or defining use of a term.
15037 @xref{dfn, , @code{@@dfn}}.@refill
15039 @item @@dircategory @var{dirpart}
15040 Specify a part of the Info directory menu where this file's entry should
15041 go. @xref{Installing Dir Entries}.
15044 Begin the Info directory menu entry for this file. Pair with
15045 @code{@@end direntry}. @xref{Installing Dir Entries}.
15048 Begin a kind of example. Like @code{@@example} (indent text, do not
15049 fill), but do not select a new font. Pair with @code{@@end display}.
15050 @xref{display, , @code{@@display}}.
15052 @item @@dmn@{@var{dimension}@}
15053 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
15054 thin space before @var{dimension}. No effect in Info.
15055 @xref{dmn, , @code{@@dmn}}.
15057 @item @@documentencoding @var{enc}
15058 Declare the input encoding as @var{enc}.
15059 @xref{documentencoding,, @code{@@documentencoding}}.
15061 @item @@documentlanguage @var{CC}
15062 Declare the document language as the two-character ISO-639 abbreviation
15063 @var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}.
15065 @item @@dotaccent@{@var{c}@}
15066 Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
15067 @xref{Inserting Accents}.
15070 Insert an ellipsis: @samp{@dots{}}.
15071 @xref{dots, , @code{@@dots}}.@refill
15073 @item @@email@{@var{address}[, @var{displayed-text}]@}
15074 Indicate an electronic mail address.
15075 @xref{email, , @code{@@email}}.
15077 @item @@emph@{@var{text}@}
15078 Highlight @var{text}; text is displayed in @emph{italics} in printed
15079 output, and surrounded by asterisks in Info. @xref{Emphasis, ,
15082 @item @@end @var{environment}
15083 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
15084 Commands,,@@-commands}.
15086 @item @@env@{@var{environment-variable}@}
15087 Indicate an environment variable name, such as @env{PATH}.
15088 @xref{env,, @code{@@env}}.
15090 @item @@enddots@{@}
15091 Generate an end-of-sentence of ellipsis, like this @enddots{}
15092 @xref{dots,,@code{@@dots@{@}}}.
15094 @item @@enumerate [@var{number-or-letter}]
15095 Begin a numbered list, using @code{@@item} for each entry.
15096 Optionally, start list with @var{number-or-letter}. Pair with
15097 @code{@@end enumerate}. @xref{enumerate, ,
15098 @code{@@enumerate}}.@refill
15101 Indicate to the reader the exact equivalence of two forms with a
15102 glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
15105 Indicate to the reader with a glyph that the following text is
15106 an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
15108 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15109 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15110 Specify page footings resp.@: headings for even-numbered (left-hand)
15111 pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
15112 How to Make Your Own Headings}.@refill
15114 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15115 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15116 Specify page footings resp.@: headings for every page. Not relevant to
15117 Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
15120 Begin an example. Indent text, do not fill, and select fixed-width font.
15121 Pair with @code{@@end example}. @xref{example, ,
15122 @code{@@example}}.@refill
15124 @item @@exampleindent @var{indent}
15125 Indent example-like environments by @var{indent} number of spaces
15126 (perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
15128 @item @@exclamdown@{@}
15129 Produce an upside-down exclamation point. @xref{Inserting Accents}.
15131 @item @@exdent @var{line-of-text}
15132 Remove any indentation a line might have. @xref{exdent, ,
15133 Undoing the Indentation of a Line}.@refill
15135 @item @@expansion@{@}
15136 Indicate the result of a macro expansion to the reader with a special
15137 glyph: @samp{@expansion{}}.
15138 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
15140 @item @@file@{@var{filename}@}
15141 Highlight the name of a file, buffer, node, or directory. @xref{file, ,
15142 @code{@@file}}.@refill
15145 Prevent @TeX{} from printing large black warning rectangles beside
15146 over-wide lines. @xref{Overfull hboxes}.@refill
15148 @item @@findex @var{entry}
15149 Add @var{entry} to the index of functions. @xref{Index Entries, ,
15150 Defining the Entries of an Index}.@refill
15153 @itemx @@flushright
15154 Left justify every line but leave the right end ragged.
15155 Leave font as is. Pair with @code{@@end flushleft}.
15156 @code{@@flushright} analogous.
15157 @xref{flushleft & flushright, , @code{@@flushleft} and
15158 @code{@@flushright}}.@refill
15160 @item @@footnote@{@var{text-of-footnote}@}
15161 Enter a footnote. Footnote text is printed at the bottom of the page
15162 by @TeX{}; Info may format in either `End' node or `Separate' node style.
15163 @xref{Footnotes}.@refill
15165 @item @@footnotestyle @var{style}
15166 Specify an Info file's footnote style, either @samp{end} for the end
15167 node style or @samp{separate} for the separate node style.
15168 @xref{Footnotes}.@refill
15171 Begin a kind of example. Like @code{@@display}, but do not narrow the
15172 margins. Pair with @code{@@end format}. @xref{example,,
15175 @item @@ftable @var{formatting-command}
15176 Begin a two-column table, using @code{@@item} for each entry.
15177 Automatically enter each of the items in the first column into the
15178 index of functions. Pair with @code{@@end ftable}. The same as
15179 @code{@@table}, except for indexing. @xref{ftable vtable, ,
15180 @code{@@ftable} and @code{@@vtable}}.@refill
15183 Hold text together that must appear on one printed page. Pair with
15184 @code{@@end group}. Not relevant to Info. @xref{group, ,
15185 @code{@@group}}.@refill
15187 @item @@H@{@var{c}@}
15188 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
15190 @item @@heading @var{title}
15191 Print an unnumbered section-like heading in the text, but not in the
15192 table of contents of a printed manual. In Info, the title is
15193 underlined with equal signs. @xref{unnumberedsec appendixsec heading,
15194 , Section Commands}.@refill
15196 @item @@headings @var{on-off-single-double}
15197 Turn page headings on or off, and/or specify single-sided or double-sided
15198 page headings for printing. @xref{headings on off, , The
15199 @code{@@headings} Command}.
15202 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
15203 Formatter Commands}.
15205 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
15206 Explicitly define hyphenation points. @xref{- and hyphenation,,
15207 @code{@@-} and @code{@@hyphenation}}.
15209 @item @@i@{@var{text}@}
15210 Print @var{text} in @i{italic} font. No effect in Info.
15211 @xref{Fonts}.@refill
15213 @item @@ifclear @var{flag}
15214 If @var{flag} is cleared, the Texinfo formatting commands format text
15215 between @code{@@ifclear @var{flag}} and the following @code{@@end
15217 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15221 Begin a stretch of text that will be ignored by @TeX{} when it typesets
15222 the printed manual. The text appears only in the HTML resp.@: Info
15223 file. Pair with @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
15224 @xref{Conditionals}.
15229 Begin a stretch of text that will be ignored in one output format but
15230 not the others. The text appears only in the format not specified.
15231 Pair with @code{@@end ifnothtml} resp.@: @code{@@end ifnotinfo} resp.@:
15232 @code{@@end ifnotinfo}. @xref{Conditionals}.
15234 @item @@ifset @var{flag}
15235 If @var{flag} is set, the Texinfo formatting commands format text
15236 between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
15238 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15241 Begin a stretch of text that will not appear in the Info file, but
15242 will be processed only by @TeX{}. Pair with @code{@@end iftex}.
15243 @xref{Conditionals, , Conditionally Visible Text}.@refill
15246 Begin a stretch of text that will not appear in either the Info file
15247 or the printed output. Pair with @code{@@end ignore}.
15248 @xref{Comments, , Comments and Ignored Text}.@refill
15250 @item @@image@{@var{filename}, [@var{width}], [@var{height}]@}
15251 Include graphics image in external @var{filename} scaled to the given
15252 @var{width} and/or @var{height}. @xref{Images}.
15254 @item @@include @var{filename}
15255 Incorporate the contents of the file @var{filename} into the Info file
15256 or printed document. @xref{Include Files}.@refill
15258 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
15259 Make a cross reference to an Info file for which there is no printed
15260 manual. @xref{inforef, , Cross references using
15261 @code{@@inforef}}.@refill
15263 @item \input @var{macro-definitions-file}
15264 Use the specified macro definitions file. This command is used only
15265 in the first line of a Texinfo file to cause @TeX{} to make use of the
15266 @file{texinfo} macro definitions file. The backslash in @code{\input}
15267 is used instead of an @code{@@} because @TeX{} does not
15268 recognize @code{@@} until after it has read the definitions file.
15269 @xref{Header, , The Texinfo File Header}.@refill
15272 Indicate the beginning of a marked paragraph for @code{@@itemize} and
15273 @code{@@enumerate}; indicate the beginning of the text of a first column
15274 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
15275 @xref{Lists and Tables}.@refill
15277 @item @@itemize @var{mark-generating-character-or-command}
15278 Produce a sequence of indented paragraphs, with a mark inside the left
15279 margin at the beginning of each paragraph. Pair with @code{@@end
15280 itemize}. @xref{itemize, , @code{@@itemize}}.@refill
15283 Like @code{@@item} but do not generate extra vertical space above the
15284 item text. @xref{itemx, , @code{@@itemx}}.@refill
15286 @item @@kbd@{@var{keyboard-characters}@}
15287 Indicate text that is characters of input to be typed by
15288 users. @xref{kbd, , @code{@@kbd}}.@refill
15290 @item @@kbdinputstyle @var{style}
15291 Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
15292 @xref{kbd, , @code{@@kbd}}.@refill
15294 @item @@key@{@var{key-name}@}
15295 Indicate a name for a key on a keyboard.
15296 @xref{key, , @code{@@key}}.@refill
15298 @item @@kindex @var{entry}
15299 Add @var{entry} to the index of keys.
15300 @xref{Index Entries, , Defining the Entries of an Index}.@refill
15304 Generate the uppercase and lowercase Polish suppressed-L letters,
15305 respectively: @L{}, @l{}.
15307 @c Possibly this can be tossed now that we have macros. --karl, 16sep96.
15308 @c Yes, let's toss it, it's pretty weird. --karl, 15jun97.
15309 @c @item @@global@@let@var{new-command}=@var{existing-command}
15310 @c Equate a new highlighting command with an existing one. Only for
15311 @c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end
15312 @c iftex}. @xref{Customized Highlighting}.@refill
15315 Begin an example of Lisp code. Indent text, do not fill, and select
15316 fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
15318 @item @@lowersections
15319 Change subsequent chapters to sections, sections to subsections, and so
15320 on. @xref{Raise/lower sections, , @code{@@raisesections} and
15321 @code{@@lowersections}}.@refill
15323 @item @@macro @var{macroname} @{@var{params}@}
15324 Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
15325 Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
15328 @item @@majorheading @var{title}
15329 Print a chapter-like heading in the text, but not in the table of
15330 contents of a printed manual. Generate more vertical whitespace before
15331 the heading than the @code{@@chapheading} command. In Info, the chapter
15332 heading line is underlined with asterisks. @xref{majorheading &
15333 chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
15335 @item @@math@{@var{mathematical-expression}@}
15336 Format a mathematical expression.
15337 @xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
15340 Mark the beginning of a menu of nodes in Info. No effect in a printed
15341 manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
15344 Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill
15346 @item @@multitable @var{column-width-spec}
15347 Begin a multi-column table. Pair with @code{@@end multitable}.
15348 @xref{Multitable Column Widths}.
15350 @item @@need @var{n}
15351 Start a new page in a printed manual if fewer than @var{n} mils
15352 (thousandths of an inch) remain on the current page. @xref{need, ,
15353 @code{@@need}}.@refill
15355 @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
15356 Define the beginning of a new node in Info, and serve as a locator for
15357 references for @TeX{}. @xref{node, , @code{@@node}}.@refill
15360 Prevent text from being indented as if it were a new paragraph.
15361 @xref{noindent, , @code{@@noindent}}.@refill
15364 Suppress validation of node references, omit creation of auxiliary files
15365 with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
15369 Generate the uppercase and lowercase O-with-slash letters, respectively:
15372 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15373 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15374 Specify page footings resp.@: headings for odd-numbered (right-hand)
15375 pages. Only allowed inside @code{@@iftex}. @xref{Custom Headings, ,
15376 How to Make Your Own Headings}.@refill
15380 Generate the uppercase and lowercase OE ligatures, respectively:
15381 @OE{}, @oe{}. @xref{Inserting Accents}.
15383 @item @@option@{@var{option-name}@}
15384 Indicate a command-line option, such as @option{-l} or @option{--help}.
15385 @xref{option,, @code{@@option}}.
15388 Start a new page in a printed manual. No effect in Info.
15389 @xref{page, , @code{@@page}}.@refill
15391 @item @@pagesizes [@var{width}][, @var{height}]
15392 Change page dimensions. @xref{pagesizes}.
15394 @item @@paragraphindent @var{indent}
15395 Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
15396 source file indentation if @var{indent} is @code{asis}.
15397 @xref{paragraphindent,, Paragraph Indenting}.
15399 @item @@pindex @var{entry}
15400 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
15401 the Entries of an Index}.@refill
15404 Indicate the position of point in a buffer to the reader with a
15405 glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
15406 Point in a Buffer}.@refill
15409 Generate the pounds sterling currency sign.
15410 @xref{pounds,,@code{@@pounds@{@}}}.
15413 Indicate printed output to the reader with a glyph:
15414 @samp{@print{}}. @xref{Print Glyph}.@refill
15416 @item @@printindex @var{index-name}
15417 Print an alphabetized two-column index in a printed manual or generate
15418 an alphabetized menu of index entries for Info. @xref{Printing
15419 Indices & Menus}.@refill
15421 @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15422 Make a reference that starts with a lower case `see' in a printed
15423 manual. Use within parentheses only. Do not follow command with a
15424 punctuation mark---the Info formatting commands automatically insert
15425 terminating punctuation as needed. Only the first argument is mandatory.
15426 @xref{pxref, , @code{@@pxref}}.@refill
15428 @item @@questiondown@{@}
15429 Generate an upside-down question mark. @xref{Inserting Accents}.
15432 Narrow the margins to indicate text that is quoted from another real
15433 or imaginary work. Write command on a line of its own. Pair with
15434 @code{@@end quotation}. @xref{quotation, ,
15435 @code{@@quotation}}.@refill
15437 @item @@r@{@var{text}@}
15438 Print @var{text} in @r{roman} font. No effect in Info.
15439 @xref{Fonts}.@refill
15441 @item @@raisesections
15442 Change subsequent sections to chapters, subsections to sections, and so
15443 on. @xref{Raise/lower sections, , @code{@@raisesections} and
15444 @code{@@lowersections}}.@refill
15446 @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15447 Make a reference. In a printed manual, the reference does not start
15448 with a `See'. Follow command with a punctuation mark. Only the first
15449 argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
15452 In Info, refill and indent the paragraph after all the other processing
15453 has been done. No effect on @TeX{}, which always refills. This command
15454 is no longer needed, since all formatters now automatically refill.
15455 @xref{Refilling Paragraphs}.@refill
15458 Indicate the result of an expression to the reader with a special
15459 glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
15461 @item @@ringaccent@{@var{c}@}
15462 Generate a ring accent over the next character, as in @ringaccent{o}.
15463 @xref{Inserting Accents}.
15465 @item @@samp@{@var{text}@}
15466 Highlight @var{text} that is a literal example of a sequence of
15467 characters. Used for single characters, for statements, and often for
15468 entire shell commands. @xref{samp, , @code{@@samp}}.@refill
15470 @item @@sc@{@var{text}@}
15471 Set @var{text} in a printed output in @sc{the small caps font} and
15472 set text in the Info file in uppercase letters.
15473 @xref{Smallcaps}.@refill
15475 @item @@section @var{title}
15476 Begin a section within a chapter. In a printed manual, the section
15477 title is numbered and appears in the table of contents. In Info, the
15478 title is underlined with equal signs. @xref{section, ,
15479 @code{@@section}}.@refill
15481 @item @@set @var{flag} [@var{string}]
15482 Make @var{flag} active, causing the Texinfo formatting commands to
15483 format text between subsequent pairs of @code{@@ifset @var{flag}} and
15484 @code{@@end ifset} commands. Optionally, set value of @var{flag} to
15486 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
15488 @item @@setchapternewpage @var{on-off-odd}
15489 Specify whether chapters start on new pages, and if so, whether on
15490 odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
15491 @code{@@setchapternewpage}}.
15493 @item @@setcontentsaftertitlepage
15494 Put the table of contents after the @samp{@@end titlepage} even if the
15495 @code{@@contents} command is not there. @xref{Contents}.
15497 @item @@setfilename @var{info-file-name}
15498 Provide a name to be used by the Info file. This command is essential
15499 for @TeX{} formatting as well, even though it produces no output.
15500 @xref{setfilename, , @code{@@setfilename}}.
15502 @item @@setshortcontentsaftertitlepage
15503 Place the short table of contents after the @samp{@@end titlepage}
15504 command even if the @code{@@shortcontents} command is not there.
15507 @item @@settitle @var{title}
15508 Provide a title for page headers in a printed manual.
15509 @xref{settitle, , @code{@@settitle}}.@refill
15511 @item @@shortcontents
15512 Print a short table of contents. Not relevant to Info, which uses
15513 menus rather than tables of contents. A synonym for
15514 @code{@@summarycontents}. @xref{Contents, , Generating a Table of
15517 @item @@shorttitlepage @var{title}
15518 Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
15521 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
15522 rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
15523 Printing Small Books}. Also, see @ref{small}.
15525 @item @@smalldisplay
15526 Begin a kind of example. Like @code{@@smallexample} (indent text, no
15527 filling), but do not select the fixed-width font. In @code{@@smallbook}
15528 format, print text in a smaller font than with @code{@@display}. Pair
15529 with @code{@@end smalldisplay}. @xref{small}.
15531 @item @@smallexample
15532 Indent text to indicate an example. Do not fill, select fixed-width
15533 font. In @code{@@smallbook} format, print text in a smaller font than
15534 with @code{@@example}. Pair with @code{@@end smallexample}.
15537 @item @@smallformat
15538 Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
15539 the margins and do not select the fixed-width font.
15540 In @code{@@smallbook} format, print text in a smaller font than
15541 with @code{@@format}. Pair with @code{@@end smallformat}.
15545 Begin an example of Lisp code. Indent text, do not fill, select
15546 fixed-width font. In @code{@@smallbook} format, print text in a
15547 smaller font. Pair with @code{@@end smalllisp}. @xref{small}.
15550 Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
15553 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
15555 @item @@strong @{@var{text}@}
15556 Emphasize @var{text} by typesetting it in a @strong{bold} font for the
15557 printed manual and by surrounding it with asterisks for Info.
15558 @xref{emph & strong, , Emphasizing Text}.@refill
15560 @item @@subheading @var{title}
15561 Print an unnumbered subsection-like heading in the text, but not in
15562 the table of contents of a printed manual. In Info, the title is
15563 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
15564 subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
15565 @code{@@subheading}}.@refill
15567 @item @@subsection @var{title}
15568 Begin a subsection within a section. In a printed manual, the
15569 subsection title is numbered and appears in the table of contents. In
15570 Info, the title is underlined with hyphens. @xref{subsection, ,
15571 @code{@@subsection}}.@refill
15573 @item @@subsubheading @var{title}
15574 Print an unnumbered subsubsection-like heading in the text, but not in
15575 the table of contents of a printed manual. In Info, the title is
15576 underlined with periods. @xref{subsubsection, , The `subsub'
15579 @item @@subsubsection @var{title}
15580 Begin a subsubsection within a subsection. In a printed manual,
15581 the subsubsection title is numbered and appears in the table of
15582 contents. In Info, the title is underlined with periods.
15583 @xref{subsubsection, , The `subsub' Commands}.@refill
15585 @item @@subtitle @var{title}
15586 In a printed manual, set a subtitle in a normal sized font flush to
15587 the right-hand side of the page. Not relevant to Info, which does not
15588 have title pages. @xref{title subtitle author, , @code{@@title}
15589 @code{@@subtitle} and @code{@@author} Commands}.@refill
15591 @item @@summarycontents
15592 Print a short table of contents. Not relevant to Info, which uses
15593 menus rather than tables of contents. A synonym for
15594 @code{@@shortcontents}. @xref{Contents, , Generating a Table of
15597 @item @@syncodeindex @var{from-index} @var{into-index}
15598 Merge the index named in the first argument into the index named in
15599 the second argument, printing the entries from the first index in
15600 @code{@@code} font. @xref{Combining Indices}.@refill
15602 @item @@synindex @var{from-index} @var{into-index}
15603 Merge the index named in the first argument into the index named in
15604 the second argument. Do not change the font of @var{from-index}
15605 entries. @xref{Combining Indices}.@refill
15607 @item @@t@{@var{text}@}
15608 Print @var{text} in a @t{fixed-width}, typewriter-like font.
15609 No effect in Info. @xref{Fonts}.@refill
15612 Separate columns in a multitable. @xref{Multitable Rows}.
15614 @item @@table @var{formatting-command}
15615 Begin a two-column table, using @code{@@item} for each entry. Write
15616 each first column entry on the same line as @code{@@item}. First
15617 column entries are printed in the font resulting from
15618 @var{formatting-command}. Pair with @code{@@end table}.
15619 @xref{Two-column Tables, , Making a Two-column Table}.
15620 Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
15621 and @ref{itemx, , @code{@@itemx}}.@refill
15624 Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
15625 and @copyright{}}.@refill
15628 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
15629 Formatter Commands}.
15631 @item @@thischapter
15632 @itemx @@thischaptername
15636 Only allowed in a heading or footing. Stands for the number and name of
15637 the current chapter (in the format `Chapter 1: Title'), the chapter name
15638 only, the filename, the current page number, and the title of the
15639 document, respectively. @xref{Custom Headings, , How to Make Your Own
15642 @item @@tieaccent@{@var{cc}@}
15643 Generate a tie-after accent over the next two characters @var{cc}, as in
15644 `@tieaccent{oo}'. @xref{Inserting Accents}.
15646 @item @@tindex @var{entry}
15647 Add @var{entry} to the index of data types. @xref{Index Entries, ,
15648 Defining the Entries of an Index}.@refill
15650 @item @@title @var{title}
15651 In a printed manual, set a title flush to the left-hand side of the
15652 page in a larger than normal font and underline it with a black rule.
15653 Not relevant to Info, which does not have title pages. @xref{title
15654 subtitle author, , The @code{@@title} @code{@@subtitle} and
15655 @code{@@author} Commands}.@refill
15657 @item @@titlefont@{@var{text}@}
15658 In a printed manual, print @var{text} in a larger than normal font.
15659 Not relevant to Info, which does not have title pages.
15660 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
15661 and @code{@@sp} Commands}.@refill
15664 Indicate to Texinfo the beginning of the title page. Write command on
15665 a line of its own. Pair with @code{@@end titlepage}. Nothing between
15666 @code{@@titlepage} and @code{@@end titlepage} appears in Info.
15667 @xref{titlepage, , @code{@@titlepage}}.@refill
15670 Insert the current date, in `1 Jan 1900' style. @xref{Custom
15671 Headings, , How to Make Your Own Headings}.@refill
15673 @item @@top @var{title}
15674 In a Texinfo file to be formatted with @code{makeinfo}, identify the
15675 topmost @code{@@node} line in the file, which must be written on the line
15676 immediately preceding the @code{@@top} command. Used for
15677 @code{makeinfo}'s node pointer insertion feature. The title is
15678 underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
15679 line normally should be enclosed by @code{@@ifinfo} and @code{@@end
15680 ifinfo}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
15681 command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
15682 Pointer Creation, , Creating Pointers with @code{makeinfo}}.
15684 @item @@u@{@var{c}@}
15685 @itemx @@ubaraccent@{@var{c}@}
15686 @itemx @@udotaccent@{@var{c}@}
15687 Generate a breve, underbar, or underdot accent, respectively, over or
15688 under the character @var{c}, as in @u{o}, @ubaraccent{o},
15689 @udotaccent{o}. @xref{Inserting Accents}.
15691 @item @@unnumbered @var{title}
15692 In a printed manual, begin a chapter that appears without chapter
15693 numbers of any kind. The title appears in the table of contents of a
15694 printed manual. In Info, the title is underlined with asterisks.
15695 @xref{unnumbered & appendix, , @code{@@unnumbered} and
15696 @code{@@appendix}}.@refill
15698 @item @@unnumberedsec @var{title}
15699 In a printed manual, begin a section that appears without section
15700 numbers of any kind. The title appears in the table of contents of a
15701 printed manual. In Info, the title is underlined with equal signs.
15702 @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
15704 @item @@unnumberedsubsec @var{title}
15705 In a printed manual, begin an unnumbered subsection within a
15706 chapter. The title appears in the table of contents of a printed
15707 manual. In Info, the title is underlined with hyphens.
15708 @xref{unnumberedsubsec appendixsubsec subheading, ,
15709 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
15710 @code{@@subheading}}.@refill
15712 @item @@unnumberedsubsubsec @var{title}
15713 In a printed manual, begin an unnumbered subsubsection within a
15714 chapter. The title appears in the table of contents of a printed
15715 manual. In Info, the title is underlined with periods.
15716 @xref{subsubsection, , The `subsub' Commands}.@refill
15718 @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
15719 Define a cross reference to an external uniform resource locator for the
15720 World Wide Web. @xref{uref, , @code{@@uref}}.@refill
15722 @item @@url@{@var{url}@}
15723 Indicate text that is a uniform resource locator for the World Wide
15724 Web. @xref{url, , @code{@@url}}.@refill
15726 @item @@v@{@var{c}@}
15727 Generate check accent over the character @var{c}, as in @v{o}.
15728 @xref{Inserting Accents}.
15730 @item @@value@{@var{flag}@}
15731 Replace @var{flag} with the value to which it is set by @code{@@set
15733 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15735 @item @@var@{@var{metasyntactic-variable}@}
15736 Highlight a metasyntactic variable, which is something that stands for
15737 another piece of text. @xref{var, , Indicating Metasyntactic
15740 @item @@vindex @var{entry}
15741 Add @var{entry} to the index of variables. @xref{Index Entries, ,
15742 Defining the Entries of an Index}.@refill
15744 @item @@vskip @var{amount}
15745 In a printed manual, insert whitespace so as to push text on the
15746 remainder of the page towards the bottom of the page. Used in
15747 formatting the copyright page with the argument @samp{0pt plus
15748 1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
15749 only in contexts ignored for Info. @xref{Copyright & Permissions, ,
15750 The Copyright Page and Printed Permissions}.@refill
15752 @item @@vtable @var{formatting-command}
15753 Begin a two-column table, using @code{@@item} for each entry.
15754 Automatically enter each of the items in the first column into the
15755 index of variables. Pair with @code{@@end vtable}. The same as
15756 @code{@@table}, except for indexing. @xref{ftable vtable, ,
15757 @code{@@ftable} and @code{@@vtable}}.@refill
15759 @item @@w@{@var{text}@}
15760 Prevent @var{text} from being split across two lines. Do not end a
15761 paragraph that uses @code{@@w} with an @code{@@refill} command.
15762 @xref{w, , @code{@@w}}.@refill
15764 @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15765 Make a reference that starts with `See' in a printed manual. Follow
15766 command with a punctuation mark. Only the first argument is
15767 mandatory. @xref{xref, , @code{@@xref}}.@refill
15772 @appendix Tips and Hints
15774 Here are some tips for writing Texinfo documentation:@refill
15781 Write in the present tense, not in the past or the future.
15784 Write actively! For example, write ``We recommend that @dots{}'' rather
15785 than ``It is recommended that @dots{}''.
15788 Use 70 or 72 as your fill column. Longer lines are hard to read.
15791 Include a copyright notice and copying permissions.
15794 @subsubheading Index, Index, Index!
15796 Write many index entries, in different ways.
15797 Readers like indices; they are helpful and convenient.
15799 Although it is easiest to write index entries as you write the body of
15800 the text, some people prefer to write entries afterwards. In either
15801 case, write an entry before the paragraph to which it applies. This
15802 way, an index entry points to the first page of a paragraph that is
15803 split across pages.
15805 Here are more hints we have found valuable:
15809 Write each index entry differently, so each entry refers to a different
15810 place in the document.
15813 Write index entries only where a topic is discussed significantly. For
15814 example, it is not useful to index ``debugging information'' in a
15815 chapter on reporting bugs. Someone who wants to know about debugging
15816 information will certainly not find it in that chapter.
15819 Consistently capitalize the first word of every concept index entry,
15820 or else consistently use lower case. Terse entries often call for
15821 lower case; longer entries for capitalization. Whichever case
15822 convention you use, please use one or the other consistently! Mixing
15823 the two styles looks bad.
15826 Always capitalize or use upper case for those words in an index for
15827 which this is proper, such as names of countries or acronyms. Always
15828 use the appropriate case for case-sensitive names, such as those in C or
15832 Write the indexing commands that refer to a whole section immediately
15833 after the section command, and write the indexing commands that refer to
15834 a paragraph before that paragraph.
15836 In the example that follows, a blank line comes after the index
15837 entry for ``Leaping'':
15841 @@section The Dog and the Fox
15842 @@cindex Jumping, in general
15845 @@cindex Dog, lazy, jumped over
15846 @@cindex Lazy dog jumped over
15847 @@cindex Fox, jumps over dog
15848 @@cindex Quick fox jumps over dog
15849 The quick brown fox jumps over the lazy dog.
15854 (Note that the example shows entries for the same concept that are
15855 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
15856 readers can look up the concept in different ways.)
15859 @subsubheading Blank Lines
15863 Insert a blank line between a sectioning command and the first following
15864 sentence or paragraph, or between the indexing commands associated with
15865 the sectioning command and the first following sentence or paragraph, as
15866 shown in the tip on indexing. Otherwise, a formatter may fold title and
15867 paragraph together.
15870 Always insert a blank line before an @code{@@table} command and after an
15871 @code{@@end table} command; but never insert a blank line after an
15872 @code{@@table} command or before an @code{@@end table} command.
15883 Jump over lazy dogs.
15888 Also jump over lazy dogs.
15894 On the other hand, @dots{}
15898 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
15899 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
15903 @subsubheading Complete Phrases
15905 Complete phrases are easier to read than @dots{}
15909 Write entries in an itemized list as complete sentences; or at least, as
15910 complete phrases. Incomplete expressions @dots{} awkward @dots{} like
15914 Write the prefatory sentence or phrase for a multi-item list or table as
15915 a complete expression. Do not write ``You can set:''; instead, write
15916 ``You can set these variables:''. The former expression sounds cut off.
15919 @subsubheading Editions, Dates and Versions
15921 Write the edition and version numbers and date in three places in every
15926 In the first @code{@@ifinfo} section, for people reading the Texinfo file.
15929 In the @code{@@titlepage} section, for people reading the printed manual.
15932 In the `Top' node, for people reading the Info file.
15936 Also, it helps to write a note before the first @code{@@ifinfo}
15937 section to explain what you are doing.
15946 @@c Specify the edition and version numbers and date
15947 @@c in *three* places:
15948 @@c 1. First ifinfo section 2. title page 3. top node
15949 @@c To find the locations, search for !!set
15954 @@c !!set edition, date, version
15955 This is Edition 4.03, January 1992,
15956 of the @@cite@{GDB Manual@} for GDB Version 4.3.
15962 ---or use @code{@@set} and @code{@@value}
15963 (@pxref{value Example, , @code{@@value} Example}).
15965 @subsubheading Definition Commands
15967 Definition commands are @code{@@deffn}, @code{@@defun},
15968 @code{@@defmac}, and the like, and enable you to write descriptions in
15969 a uniform format.@refill
15973 Write just one definition command for each entity you define with a
15974 definition command. The automatic indexing feature creates an index
15975 entry that leads the reader to the definition.
15978 Use @code{@@table} @dots{} @code{@@end table} in an appendix that
15979 contains a summary of functions, not @code{@@deffn} or other definition
15983 @subsubheading Capitalization
15987 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
15988 @samp{i} in upper case.
15991 Capitalize ``Info''; it is a name.
15994 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
15995 @samp{T} and @samp{X}. This command causes the formatters to
15996 typeset the name according to the wishes of Donald Knuth, who wrote
16000 @subsubheading Spaces
16002 Do not use spaces to format a Texinfo file, except inside of
16003 @code{@@example} @dots{} @code{@@end example} and similar commands.
16006 For example, @TeX{} fills the following:
16011 @@kbd@{M-x vc-next-action@}
16012 Perform the next logical operation
16013 on the version-controlled file
16014 corresponding to the current buffer.
16020 so it looks like this:
16025 @kbd{M-x vc-next-action}
16026 Perform the next logical operation on the version-controlled file
16027 corresponding to the current buffer.
16032 `C-x v' `M-x vc-next-action' Perform the next logical operation on the
16033 version-controlled file corresponding to the current buffer.
16038 In this case, the text should be formatted with
16039 @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
16041 @subsubheading @@code, @@samp, @@var, and @samp{---}
16045 Use @code{@@code} around Lisp symbols, including command names.
16049 The main function is @@code@{vc-next-action@}, @dots{}
16053 Avoid putting letters such as @samp{s} immediately after an
16054 @samp{@@code}. Such letters look bad.
16057 Use @code{@@var} around meta-variables. Do not write angle brackets
16061 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
16062 typesets these as a long dash and the Info formatters reduce three
16066 @subsubheading Periods Outside of Quotes
16068 Place periods and other punctuation marks @emph{outside} of quotations,
16069 unless the punctuation is part of the quotation. This practice goes
16070 against publishing conventions in the United States, but enables the
16071 reader to distinguish between the contents of the quotation and the
16074 For example, you should write the following sentence with the period
16075 outside the end quotation marks:
16078 Evidently, @samp{au} is an abbreviation for ``author''.
16082 since @samp{au} does @emph{not} serve as an abbreviation for
16083 @samp{author.} (with a period following the word).
16085 @subsubheading Introducing New Terms
16089 Introduce new terms so that a reader who does not know them can
16090 understand them from context; or write a definition for the term.
16092 For example, in the following, the terms ``check in'', ``register'' and
16093 ``delta'' are all appearing for the first time; the example sentence should be
16094 rewritten so they are understandable.
16097 The major function assists you in checking in a file to your
16098 version control system and registering successive sets of changes to
16103 Use the @code{@@dfn} command around a word being introduced, to indicate
16104 that the reader should not expect to know the meaning already, and
16105 should expect to learn the meaning from this passage.
16108 @subsubheading @@pxref
16110 @c !!! maybe include this in the tips on pxref
16112 By the way, it is okay to use pxref with something else in front of
16113 it within the parens, as long as the pxref is followed by the close
16114 paren, and the material inside the parens is not part of a larger
16115 sentence. Also, you can use xref inside parens as part of a complete
16116 sentence so long as you terminate the cross reference with punctuation.
16118 Absolutely never use @code{@@pxref} except in the special context for
16119 which it is designed: inside parentheses, with the closing parenthesis
16120 following immediately after the closing brace. One formatter
16121 automatically inserts closing punctuation and the other does not. This
16122 means that the output looks right both in printed output and in an Info
16123 file, but only when the command is used inside parentheses.
16125 @subsubheading Invoking from a Shell
16127 You can invoke programs such as Emacs, GCC, and @code{gawk} from a
16128 shell. The documentation for each program should contain a section that
16129 describes this. Unfortunately, if the node names and titles for these
16130 sections are all different, readers find it hard to search for the
16133 Name such sections with a phrase beginning with the word
16134 @w{`Invoking @dots{}'}, as in `Invoking Emacs'; this way
16135 users can find the section easily.
16137 @subsubheading ANSI C Syntax
16139 When you use @code{@@example} to describe a C function's calling
16140 conventions, use the ANSI C syntax, like this:@refill
16143 void dld_init (char *@@var@{path@});
16147 And in the subsequent discussion, refer to the argument values by
16148 writing the same argument names, again highlighted with
16149 @code{@@var}.@refill
16152 Avoid the obsolete style that looks like this:@refill
16161 Also, it is best to avoid writing @code{#include} above the
16162 declaration just to indicate that the function is declared in a
16163 header file. The practice may give the misimpression that the
16164 @code{#include} belongs near the declaration of the function. Either
16165 state explicitly which header file holds the declaration or, better
16166 yet, name the header file used for a group of functions at the
16167 beginning of the section that describes the functions.@refill
16169 @subsubheading Bad Examples
16171 Here are several examples of bad writing to avoid:
16173 In this example, say, `` @dots{} you must @code{@@dfn}@{check
16174 in@} the new version.'' That flows better.
16177 When you are done editing the file, you must perform a
16178 @code{@@dfn}@{check in@}.
16181 In the following example, say, ``@dots{} makes a unified interface such as VC
16185 SCCS, RCS and other version-control systems all perform similar
16186 functions in broadly similar ways (it is this resemblance which makes
16187 a unified control mode like this possible).
16190 And in this example, you should specify what `it' refers to:
16193 If you are working with other people, it assists in coordinating
16194 everyone's changes so they do not step on each other.
16197 @subsubheading And Finally @dots{}
16201 Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
16202 sound in the name `Bach'. But pronounce Texinfo as in `speck':
16206 Write notes for yourself at the very end of a Texinfo file after the
16207 @code{@@bye}. None of the formatters process text after the
16208 @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
16209 @code{@@end ignore}.
16213 @node Sample Texinfo File
16214 @appendix A Sample Texinfo File
16215 @cindex Sample Texinfo file, no comments
16217 Here is a complete, short sample Texinfo file, without any commentary.
16218 You can see this file, with comments, in the first chapter.
16219 @xref{Short Sample, , A Short Sample Texinfo File}.
16223 \input texinfo @@c -*-texinfo-*-
16224 @@c %**start of header
16225 @@setfilename sample.info
16226 @@settitle Sample Document
16227 @@c %**end of header
16229 @@setchapternewpage odd
16232 This is a short example of a complete Texinfo file.
16234 Copyright 1990 Free Software Foundation, Inc.
16239 @@comment The title is printed in a large font.
16240 @@center @@titlefont@{Sample Title@}
16242 @@c The following two commands start the copyright page.
16244 @@vskip 0pt plus 1filll
16245 Copyright @@copyright@{@} 1990 Free Software Foundation, Inc.
16248 @@node Top, First Chapter, , (dir)
16249 @@comment node-name, next, previous, up
16252 * First Chapter:: The first chapter is the
16253 only chapter in this sample.
16254 * Concept Index:: This index has two entries.
16257 @@node First Chapter, Concept Index, Top, Top
16258 @@comment node-name, next, previous, up
16259 @@chapter First Chapter
16260 @@cindex Sample index entry
16262 This is the contents of the first chapter.
16263 @@cindex Another sample index entry
16265 Here is a numbered list.
16269 This is the first item.
16272 This is the second item.
16275 The @@code@{makeinfo@} and @@code@{texinfo-format-buffer@}
16276 commands transform a Texinfo file such as this into
16277 an Info file; and @@TeX@{@} typesets it for a printed
16280 @@node Concept Index, , First Chapter, Top
16281 @@comment node-name, next, previous, up
16282 @@unnumbered Concept Index
16291 @node Sample Permissions
16292 @appendix Sample Permissions
16293 @cindex Permissions
16294 @cindex Sample permissions
16295 @cindex Copying permissions
16297 Texinfo files should contain sections that tell the readers that they
16298 have the right to copy and distribute the Texinfo file, the Info file,
16299 and the printed manual.@refill
16301 Also, if you are writing a manual about software, you should explain
16302 that the software is free and either include the GNU General Public
16303 License (GPL) or provide a reference to it. @xref{Distrib, ,
16304 Distribution, emacs, The GNU Emacs Manual}, for an example of the text
16305 that could be used in the software ``Distribution'', ``General Public
16306 License'', and ``NO WARRANTY'' sections of a document. @xref{Copying,
16307 , Texinfo Copying Conditions}, for an example of a brief explanation
16308 of how the copying conditions provide you with rights. @refill
16311 * Inserting Permissions:: How to put permissions in your document.
16312 * ifinfo Permissions:: Sample @samp{ifinfo} copying permissions.
16313 * Titlepage Permissions:: Sample Titlepage copying permissions.
16316 @node Inserting Permissions, ifinfo Permissions, Sample Permissions, Sample Permissions
16318 @section Inserting Permissions
16321 In a Texinfo file, the first @code{@@ifinfo} section usually begins
16322 with a line that says what the file documents. This is what a person
16323 reading the unprocessed Texinfo file or using the advanced Info
16324 command @kbd{g *} sees first. @inforef{Expert, Advanced Info
16325 commands, info}, for more information. (A reader using the regular
16326 Info commands usually starts reading at the first node and skips
16327 this first section, which is not in a node.)@refill
16329 In the @code{@@ifinfo} section, the summary sentence is followed by a
16330 copyright notice and then by the copying permission notice. One of
16331 the copying permission paragraphs is enclosed in @code{@@ignore} and
16332 @code{@@end ignore} commands. This paragraph states that the Texinfo
16333 file can be processed through @TeX{} and printed, provided the printed
16334 manual carries the proper copying permission notice. This paragraph
16335 is not made part of the Info file since it is not relevant to the Info
16336 file; but it is a mandatory part of the Texinfo file since it permits
16337 people to process the Texinfo file in @TeX{} and print the
16340 In the printed manual, the Free Software Foundation copying permission
16341 notice follows the copyright notice and publishing information and is
16342 located within the region delineated by the @code{@@titlepage} and
16343 @code{@@end titlepage} commands. The copying permission notice is exactly
16344 the same as the notice in the @code{@@ifinfo} section except that the
16345 paragraph enclosed in @code{@@ignore} and @code{@@end ignore} commands is
16346 not part of the notice.@refill
16348 To make it simple to insert a permission notice into each section of
16349 the Texinfo file, sample permission notices for each section are
16350 reproduced in full below.@refill
16352 You may need to specify the correct name of a section mentioned in the
16353 permission notice. For example, in @cite{The GDB Manual}, the name of
16354 the section referring to the General Public License is called the ``GDB
16355 General Public License'', but in the sample shown below, that section is
16356 referred to generically as the ``GNU General Public License''. If the
16357 Texinfo file does not carry a copy of the General Public License, leave
16358 out the reference to it, but be sure to include the rest of the
16361 @node ifinfo Permissions, Titlepage Permissions, Inserting Permissions, Sample Permissions
16362 @comment node-name, next, previous, up
16363 @section @samp{ifinfo} Copying Permissions
16364 @cindex @samp{ifinfo} permissions
16366 In the @code{@@ifinfo} section of a Texinfo file, the standard Free
16367 Software Foundation permission notice reads as follows:@refill
16370 This file documents @dots{}
16372 Copyright 1999 Free Software Foundation, Inc.
16374 Permission is granted to make and distribute verbatim
16375 copies of this manual provided the copyright notice and
16376 this permission notice are preserved on all copies.
16379 Permission is granted to process this file through TeX
16380 and print the results, provided the printed document
16381 carries a copying permission notice identical to this
16382 one except for the removal of this paragraph (this
16383 paragraph not being relevant to the printed manual).
16386 Permission is granted to copy and distribute modified
16387 versions of this manual under the conditions for
16388 verbatim copying, provided also that the sections
16389 entitled ``Copying'' and ``GNU General Public License''
16390 are included exactly as in the original, and provided
16391 that the entire resulting derived work is distributed
16392 under the terms of a permission notice identical to this
16395 Permission is granted to copy and distribute
16396 translations of this manual into another language,
16397 under the above conditions for modified versions,
16398 except that this permission notice may be stated in a
16399 translation approved by the Free Software Foundation.
16402 @node Titlepage Permissions, , ifinfo Permissions, Sample Permissions
16403 @comment node-name, next, previous, up
16404 @section Titlepage Copying Permissions
16405 @cindex Titlepage permissions
16407 In the @code{@@titlepage} section of a Texinfo file, the standard Free
16408 Software Foundation copying permission notice follows the copyright
16409 notice and publishing information. The standard phrasing is as
16413 Permission is granted to make and distribute verbatim
16414 copies of this manual provided the copyright notice and
16415 this permission notice are preserved on all copies.
16417 Permission is granted to copy and distribute modified
16418 versions of this manual under the conditions for
16419 verbatim copying, provided also that the sections
16420 entitled ``Copying'' and ``GNU General Public License''
16421 are included exactly as in the original, and provided
16422 that the entire resulting derived work is distributed
16423 under the terms of a permission notice identical to this
16426 Permission is granted to copy and distribute
16427 translations of this manual into another language,
16428 under the above conditions for modified versions,
16429 except that this permission notice may be stated in a
16430 translation approved by the Free Software Foundation.
16434 @node Include Files
16435 @appendix Include Files
16436 @cindex Include files
16438 When @TeX{} or an Info formatting command sees an @code{@@include}
16439 command in a Texinfo file, it processes the contents of the file named
16440 by the command and incorporates them into the DVI or Info file being
16441 created. Index entries from the included file are incorporated into
16442 the indices of the output file.@refill
16444 Include files let you keep a single large document as a collection of
16445 conveniently small parts.@refill
16448 * Using Include Files:: How to use the @code{@@include} command.
16449 * texinfo-multiple-files-update:: How to create and update nodes and
16450 menus when using included files.
16451 * Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
16452 * Sample Include File:: A sample outer file with included files
16453 within it; and a sample included file.
16454 * Include Files Evolution:: How use of the @code{@@include} command
16455 has changed over time.
16458 @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
16459 @section How to Use Include Files
16462 To include another file within a Texinfo file, write the
16463 @code{@@include} command at the beginning of a line and follow it on
16464 the same line by the name of a file to be included. For
16468 @@include buffers.texi
16471 An included file should simply be a segment of text that you expect to
16472 be included as is into the overall or @dfn{outer} Texinfo file; it
16473 should not contain the standard beginning and end parts of a Texinfo
16474 file. In particular, you should not start an included file with a
16475 line saying @samp{\input texinfo}; if you do, that phrase is inserted
16476 into the output file as is. Likewise, you should not end an included
16477 file with an @code{@@bye} command; nothing after @code{@@bye} is
16480 In the past, you were required to write an @code{@@setfilename} line at the
16481 beginning of an included file, but no longer. Now, it does not matter
16482 whether you write such a line. If an @code{@@setfilename} line exists
16483 in an included file, it is ignored.@refill
16485 Conventionally, an included file begins with an @code{@@node} line that
16486 is followed by an @code{@@chapter} line. Each included file is one
16487 chapter. This makes it easy to use the regular node and menu creating
16488 and updating commands to create the node pointers and menus within the
16489 included file. However, the simple Emacs node and menu creating and
16490 updating commands do not work with multiple Texinfo files. Thus you
16491 cannot use these commands to fill in the `Next', `Previous', and `Up'
16492 pointers of the @code{@@node} line that begins the included file. Also,
16493 you cannot use the regular commands to create a master menu for the
16494 whole file. Either you must insert the menus and the `Next',
16495 `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
16496 Texinfo mode command, @code{texinfo-multiple-files-update}, that is
16497 designed for @code{@@include} files.@refill
16499 @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
16500 @section @code{texinfo-multiple-files-update}
16501 @findex texinfo-multiple-files-update
16503 GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
16504 command. This command creates or updates `Next', `Previous', and `Up'
16505 pointers of included files as well as those in the outer or overall
16506 Texinfo file, and it creates or updates a main menu in the outer file.
16507 Depending whether you call it with optional arguments, the command
16508 updates only the pointers in the first @code{@@node} line of the
16509 included files or all of them:@refill
16512 @item M-x texinfo-multiple-files-update
16513 Called without any arguments:@refill
16517 Create or update the `Next', `Previous', and `Up' pointers of the
16518 first @code{@@node} line in each file included in an outer or overall
16519 Texinfo file.@refill
16522 Create or update the `Top' level node pointers of the outer or
16523 overall file.@refill
16526 Create or update a main menu in the outer file.@refill
16529 @item C-u M-x texinfo-multiple-files-update
16530 Called with @kbd{C-u} as a prefix argument:
16534 Create or update pointers in the first @code{@@node} line in each
16538 Create or update the `Top' level node pointers of the outer file.
16541 Create and insert a master menu in the outer file. The master menu
16542 is made from all the menus in all the included files.@refill
16545 @item C-u 8 M-x texinfo-multiple-files-update
16546 Called with a numeric prefix argument, such as @kbd{C-u 8}:
16550 Create or update @strong{all} the `Next', `Previous', and `Up' pointers
16551 of all the included files.@refill
16554 Create or update @strong{all} the menus of all the included
16558 Create or update the `Top' level node pointers of the outer or
16559 overall file.@refill
16562 And then create a master menu in the outer file. This is similar to
16563 invoking @code{texinfo-master-menu} with an argument when you are
16564 working with just one file.@refill
16568 Note the use of the prefix argument in interactive use: with a regular
16569 prefix argument, just @w{@kbd{C-u}}, the
16570 @code{texinfo-multiple-files-update} command inserts a master menu;
16571 with a numeric prefix argument, such as @kbd{C-u 8}, the command
16572 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
16573 master menu.@refill
16575 @node Include File Requirements, Sample Include File, texinfo-multiple-files-update, Include Files
16576 @section Include File Requirements
16577 @cindex Include file requirements
16578 @cindex Requirements for include files
16580 If you plan to use the @code{texinfo-multiple-files-update} command,
16581 the outer Texinfo file that lists included files within it should
16582 contain nothing but the beginning and end parts of a Texinfo file, and
16583 a number of @code{@@include} commands listing the included files. It
16584 should not even include indices, which should be listed in an included
16585 file of their own.@refill
16587 Moreover, each of the included files must contain exactly one highest
16588 level node (conventionally, @code{@@chapter} or equivalent),
16589 and this node must be the first node in the included file.
16590 Furthermore, each of these highest level nodes in each included file
16591 must be at the same hierarchical level in the file structure.
16592 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
16593 @code{@@unnumbered} node. Thus, normally, each included file contains
16594 one, and only one, chapter or equivalent-level node.@refill
16596 The outer file should contain only @emph{one} node, the `Top' node. It
16597 should @emph{not} contain any nodes besides the single `Top' node. The
16598 @code{texinfo-multiple-files-update} command will not process
16601 @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
16602 @section Sample File with @code{@@include}
16603 @cindex Sample @code{@@include} file
16604 @cindex Include file sample
16605 @cindex @code{@@include} file sample
16607 Here is an example of a complete outer Texinfo file with @code{@@include} files
16608 within it before running @code{texinfo-multiple-files-update}, which
16609 would insert a main or master menu:@refill
16613 \input texinfo @@c -*-texinfo-*-
16614 @c %**start of header
16615 @@setfilename include-example.info
16616 @@settitle Include Example
16617 @c %**end of header
16621 @@setchapternewpage odd
16624 @@center @@titlefont@{Include Example@}
16626 @@center by Whom Ever
16631 @@vskip 0pt plus 1filll
16632 Copyright @@copyright@{@} 1999 Free Software Foundation, Inc.
16638 @@node Top, First, , (dir)
16644 @@include foo.texinfo
16645 @@include bar.texinfo
16646 @@include concept-index.texinfo
16657 An included file, such as @file{foo.texinfo}, might look like
16662 @@node First, Second, , Top
16663 @@chapter First Chapter
16665 Contents of first chapter @dots{}
16669 The full contents of @file{concept-index.texinfo} might be as simple as this:
16673 @@node Concept Index
16674 @@unnumbered Concept Index
16680 The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
16681 Manual} is named @file{elisp.texi}. This outer file contains a master
16682 menu with 417 entries and a list of 41 @code{@@include}
16685 @node Include Files Evolution, , Sample Include File, Include Files
16686 @comment node-name, next, previous, up
16687 @section Evolution of Include Files
16689 When Info was first created, it was customary to create many small
16690 Info files on one subject. Each Info file was formatted from its own
16691 Texinfo source file. This custom meant that Emacs did not need to
16692 make a large buffer to hold the whole of a large Info file when
16693 someone wanted information; instead, Emacs allocated just enough
16694 memory for the small Info file that contained the particular
16695 information sought. This way, Emacs could avoid wasting memory.@refill
16697 References from one file to another were made by referring to the file
16698 name as well as the node name. (@xref{Other Info Files, , Referring to
16699 Other Info Files}. Also, see @ref{Four and Five Arguments, ,
16700 @code{@@xref} with Four and Five Arguments}.)@refill
16702 Include files were designed primarily as a way to create a single,
16703 large printed manual out of several smaller Info files. In a printed
16704 manual, all the references were within the same document, so @TeX{}
16705 could automatically determine the references' page numbers. The Info
16706 formatting commands used include files only for creating joint
16707 indices; each of the individual Texinfo files had to be formatted for
16708 Info individually. (Each, therefore, required its own
16709 @code{@@setfilename} line.)@refill
16711 However, because large Info files are now split automatically, it is
16712 no longer necessary to keep them small.@refill
16714 Nowadays, multiple Texinfo files are used mostly for large documents,
16715 such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
16716 in which several different people write different sections of a
16717 document simultaneously.@refill
16719 In addition, the Info formatting commands have been extended to work
16720 with the @code{@@include} command so as to create a single large Info
16721 file that is split into smaller files if necessary. This means that
16722 you can write menus and cross references without naming the different
16723 Texinfo files.@refill
16727 @appendix Page Headings
16730 @cindex Page numbering
16731 @cindex Page headings
16732 @cindex Formatting headings and footings
16734 Most printed manuals contain headings along the top of every page
16735 except the title and copyright pages. Some manuals also contain
16736 footings. (Headings and footings have no meaning to Info, which is
16737 not paginated.)@refill
16740 * Headings Introduced:: Conventions for using page headings.
16741 * Heading Format:: Standard page heading formats.
16742 * Heading Choice:: How to specify the type of page heading.
16743 * Custom Headings:: How to create your own headings and footings.
16746 @node Headings Introduced, Heading Format, Headings, Headings
16748 @heading Headings Introduced
16751 Texinfo provides standard page heading formats for manuals that are
16752 printed on one side of each sheet of paper and for manuals that are
16753 printed on both sides of the paper. Typically, you will use these
16754 formats, but you can specify your own format if you wish.@refill
16756 In addition, you can specify whether chapters should begin on a new
16757 page, or merely continue the same page as the previous chapter; and if
16758 chapters begin on new pages, you can specify whether they must be
16759 odd-numbered pages.@refill
16761 By convention, a book is printed on both sides of each sheet of paper.
16762 When you open a book, the right-hand page is odd-numbered, and
16763 chapters begin on right-hand pages---a preceding left-hand page is
16764 left blank if necessary. Reports, however, are often printed on just
16765 one side of paper, and chapters begin on a fresh page immediately
16766 following the end of the preceding chapter. In short or informal
16767 reports, chapters often do not begin on a new page at all, but are
16768 separated from the preceding text by a small amount of whitespace.@refill
16770 The @code{@@setchapternewpage} command controls whether chapters begin
16771 on new pages, and whether one of the standard heading formats is used.
16772 In addition, Texinfo has several heading and footing commands that you
16773 can use to generate your own heading and footing formats.@refill
16775 In Texinfo, headings and footings are single lines at the tops and
16776 bottoms of pages; you cannot create multiline headings or footings.
16777 Each header or footer line is divided into three parts: a left part, a
16778 middle part, and a right part. Any part, or a whole line, may be left
16779 blank. Text for the left part of a header or footer line is set
16780 flushleft; text for the middle part is centered; and, text for the
16781 right part is set flushright.@refill
16783 @node Heading Format, Heading Choice, Headings Introduced, Headings
16784 @comment node-name, next, previous, up
16785 @section Standard Heading Formats
16787 Texinfo provides two standard heading formats, one for manuals printed
16788 on one side of each sheet of paper, and the other for manuals printed
16789 on both sides of the paper.
16791 By default, nothing is specified for the footing of a Texinfo file,
16792 so the footing remains blank.@refill
16794 The standard format for single-sided printing consists of a header
16795 line in which the left-hand part contains the name of the chapter, the
16796 central part is blank, and the right-hand part contains the page
16800 A single-sided page looks like this:
16804 _______________________
16806 | chapter page number |
16808 | Start of text ... |
16815 The standard format for two-sided printing depends on whether the page
16816 number is even or odd. By convention, even-numbered pages are on the
16817 left- and odd-numbered pages are on the right. (@TeX{} will adjust the
16818 widths of the left- and right-hand margins. Usually, widths are
16819 correct, but during double-sided printing, it is wise to check that
16820 pages will bind properly---sometimes a printer will produce output in
16821 which the even-numbered pages have a larger right-hand margin than the
16822 odd-numbered pages.)@refill
16824 In the standard double-sided format, the left part of the left-hand
16825 (even-numbered) page contains the page number, the central part is
16826 blank, and the right part contains the title (specified by the
16827 @code{@@settitle} command). The left part of the right-hand
16828 (odd-numbered) page contains the name of the chapter, the central part
16829 is blank, and the right part contains the page number.@refill
16832 Two pages, side by side as in an open book, look like this:@refill
16836 _______________________ _______________________
16838 | page number title | | chapter page number |
16840 | Start of text ... | | More text ... |
16848 The chapter name is preceded by the word ``Chapter'', the chapter number
16849 and a colon. This makes it easier to keep track of where you are in the
16852 @node Heading Choice, Custom Headings, Heading Format, Headings
16853 @comment node-name, next, previous, up
16854 @section Specifying the Type of Heading
16856 @TeX{} does not begin to generate page headings for a standard Texinfo
16857 file until it reaches the @code{@@end titlepage} command. Thus, the
16858 title and copyright pages are not numbered. The @code{@@end
16859 titlepage} command causes @TeX{} to begin to generate page headings
16860 according to a standard format specified by the
16861 @code{@@setchapternewpage} command that precedes the
16862 @code{@@titlepage} section.@refill
16865 There are four possibilities:@refill
16868 @item No @code{@@setchapternewpage} command
16869 Cause @TeX{} to specify the single-sided heading format, with chapters
16870 on new pages. This is the same as @code{@@setchapternewpage on}.@refill
16872 @item @code{@@setchapternewpage on}
16873 Specify the single-sided heading format, with chapters on new pages.@refill
16875 @item @code{@@setchapternewpage off}
16876 Cause @TeX{} to start a new chapter on the same page as the last page of
16877 the preceding chapter, after skipping some vertical whitespace. Also
16878 cause @TeX{} to typeset for single-sided printing. (You can override
16879 the headers format with the @code{@@headings double} command; see
16880 @ref{headings on off, , The @code{@@headings} Command}.)@refill
16882 @item @code{@@setchapternewpage odd}
16883 Specify the double-sided heading format, with chapters on new pages.@refill
16887 Texinfo lacks an @code{@@setchapternewpage even} command.@refill
16889 @node Custom Headings, , Heading Choice, Headings
16890 @comment node-name, next, previous, up
16891 @section How to Make Your Own Headings
16893 You can use the standard headings provided with Texinfo or specify
16894 your own. By default, Texinfo has no footers, so if you specify them,
16895 the available page size for the main text will be slightly reduced.
16897 Texinfo provides six commands for specifying headings and
16901 @code{@@everyheading} @code{@@everyfooting} generate page headers and
16902 footers that are the same for both even- and odd-numbered pages.
16904 @code{@@evenheading} and @code{@@evenfooting} command generate headers
16905 and footers for even-numbered (left-hand) pages.
16907 @code{@@oddheading} and @code{@@oddfooting} generate headers and footers
16908 for odd-numbered (right-hand) pages.
16911 Write custom heading specifications in the Texinfo file immediately
16912 after the @code{@@end titlepage} command. Enclose your specifications
16913 between @code{@@iftex} and @code{@@end iftex} commands since the
16914 @code{texinfo-format-buffer} command may not recognize them. Also,
16915 you must cancel the predefined heading commands with the
16916 @code{@@headings off} command before defining your own
16917 specifications.@refill
16920 Here is how to tell @TeX{} to place the chapter name at the left, the
16921 page number in the center, and the date at the right of every header
16922 for both even- and odd-numbered pages:@refill
16928 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
16934 You need to divide the left part from the central part and the central
16935 part from the right part by inserting @samp{@@|} between parts.
16936 Otherwise, the specification command will not be able to tell where
16937 the text for one part ends and the next part begins.@refill
16939 Each part can contain text or @@-commands. The text
16940 is printed as if the part were within an ordinary paragraph in the
16941 body of the page. The @@-commands replace
16942 themselves with the page number, date, chapter name, or
16946 Here are the six heading and footing commands:@refill
16948 @findex everyheading
16949 @findex everyfooting
16951 @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
16952 @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
16954 The `every' commands specify the format for both even- and odd-numbered
16955 pages. These commands are for documents that are printed on one side
16956 of each sheet of paper, or for documents in which you want symmetrical
16957 headers or footers.@refill
16959 @findex evenheading
16960 @findex evenfooting
16963 @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
16964 @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
16966 @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
16967 @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
16969 The `even' and `odd' commands specify the format for even-numbered
16970 pages and odd-numbered pages. These commands are for books and
16971 manuals that are printed on both sides of each sheet of paper.
16974 Use the @samp{@@this@dots{}} series of @@-commands to
16975 provide the names of chapters
16976 and sections and the page number. You can use the
16977 @samp{@@this@dots{}} commands in the left, center, or right portions
16978 of headers and footers, or anywhere else in a Texinfo file so long as
16979 they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
16982 Here are the @samp{@@this@dots{}} commands:@refill
16987 Expands to the current page number.@refill
16988 @c !!! Karl Berry says that `thissection' can fail on page breaks.
16990 @item @@thissection
16991 Expands to the name of the current section.@refill
16994 @findex thischaptername
16995 @item @@thischaptername
16996 Expands to the name of the current chapter.@refill
16998 @findex thischapter
16999 @item @@thischapter
17000 Expands to the number and name of the current
17001 chapter, in the format `Chapter 1: Title'.@refill
17005 Expands to the name of the document, as specified by the
17006 @code{@@settitle} command.@refill
17010 For @code{@@include} files only: expands to the name of the current
17011 @code{@@include} file. If the current Texinfo source file is not an
17012 @code{@@include} file, this command has no effect. This command does
17013 @emph{not} provide the name of the current Texinfo source file unless
17014 it is an @code{@@include} file. (@xref{Include Files}, for more
17015 information about @code{@@include} files.)@refill
17019 You can also use the @code{@@today@{@}} command, which expands to the
17020 current date, in `1 Jan 1900' format.@refill
17023 Other @@-commands and text are printed in a header or footer just as
17024 if they were in the body of a page. It is useful to incorporate text,
17025 particularly when you are writing drafts:@refill
17031 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
17032 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
17037 Beware of overlong titles: they may overlap another part of the
17038 header or footer and blot it out.@refill
17041 @node Catching Mistakes
17042 @appendix Formatting Mistakes
17043 @cindex Structure, catching mistakes in
17044 @cindex Nodes, catching mistakes
17045 @cindex Catching mistakes
17046 @cindex Correcting mistakes
17047 @cindex Mistakes, catching
17048 @cindex Problems, catching
17049 @cindex Debugging the Texinfo structure
17051 Besides mistakes in the content of your documentation, there
17052 are two kinds of mistake you can make with Texinfo: you can make mistakes
17053 with @@-commands, and you can make mistakes with the structure of the
17054 nodes and chapters.@refill
17056 Emacs has two tools for catching the @@-command mistakes and two for
17057 catching structuring mistakes.@refill
17059 For finding problems with @@-commands, you can run @TeX{} or a region
17060 formatting command on the region that has a problem; indeed, you can
17061 run these commands on each region as you write it.@refill
17063 For finding problems with the structure of nodes and chapters, you can use
17064 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
17065 command and you can use the @kbd{M-x Info-validate} command.@refill
17068 * makeinfo Preferred:: @code{makeinfo} finds errors.
17069 * Debugging with Info:: How to catch errors with Info formatting.
17070 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
17071 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
17072 * Using occur:: How to list all lines containing a pattern.
17073 * Running Info-Validate:: How to find badly referenced nodes.
17076 @node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
17078 @heading @code{makeinfo} Find Errors
17081 The @code{makeinfo} program does an excellent job of catching errors
17082 and reporting them---far better than @code{texinfo-format-region} or
17083 @code{texinfo-format-buffer}. In addition, the various functions for
17084 automatically creating and updating node pointers and menus remove
17085 many opportunities for human error.@refill
17087 If you can, use the updating commands to create and insert pointers
17088 and menus. These prevent many errors. Then use @code{makeinfo} (or
17089 its Texinfo mode manifestations, @code{makeinfo-region} and
17090 @code{makeinfo-buffer}) to format your file and check for other
17091 errors. This is the best way to work with Texinfo. But if you
17092 cannot use @code{makeinfo}, or your problem is very puzzling, then you
17093 may want to use the tools described in this appendix.@refill
17095 @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
17096 @comment node-name, next, previous, up
17097 @section Catching Errors with Info Formatting
17098 @cindex Catching errors with Info formatting
17099 @cindex Debugging with Info formatting
17101 After you have written part of a Texinfo file, you can use the
17102 @code{texinfo-format-region} or the @code{makeinfo-region} command to
17103 see whether the region formats properly.@refill
17105 Most likely, however, you are reading this section because for some
17106 reason you cannot use the @code{makeinfo-region} command; therefore, the
17107 rest of this section presumes that you are using
17108 @code{texinfo-format-region}.@refill
17110 If you have made a mistake with an @@-command,
17111 @code{texinfo-format-region} will stop processing at or after the
17112 error and display an error message. To see where in the buffer the
17113 error occurred, switch to the @samp{*Info Region*} buffer; the cursor
17114 will be in a position that is after the location of the error. Also,
17115 the text will not be formatted after the place where the error
17116 occurred (or more precisely, where it was detected).@refill
17118 For example, if you accidentally end a menu with the command @code{@@end
17119 menus} with an `s' on the end, instead of with @code{@@end menu}, you
17120 will see an error message that says:@refill
17123 @@end menus is not handled by texinfo
17127 The cursor will stop at the point in the buffer where the error
17128 occurs, or not long after it. The buffer will look like this:@refill
17132 ---------- Buffer: *Info Region* ----------
17135 * Using texinfo-show-structure:: How to use
17136 `texinfo-show-structure'
17138 * Running Info-Validate:: How to check for
17139 unreferenced nodes.
17142 ---------- Buffer: *Info Region* ----------
17146 The @code{texinfo-format-region} command sometimes provides slightly
17147 odd error messages. For example, the following cross reference fails to format:@refill
17150 (@@xref@{Catching Mistakes, for more info.)
17154 In this case, @code{texinfo-format-region} detects the missing closing
17155 brace but displays a message that says @samp{Unbalanced parentheses}
17156 rather than @samp{Unbalanced braces}. This is because the formatting
17157 command looks for mismatches between braces as if they were
17158 parentheses.@refill
17160 Sometimes @code{texinfo-format-region} fails to detect mistakes. For
17161 example, in the following, the closing brace is swapped with the
17162 closing parenthesis:@refill
17165 (@@xref@{Catching Mistakes), for more info.@}
17169 Formatting produces:
17171 (*Note for more info.: Catching Mistakes)
17174 The only way for you to detect this error is to realize that the
17175 reference should have looked like this:@refill
17178 (*Note Catching Mistakes::, for more info.)
17181 Incidentally, if you are reading this node in Info and type @kbd{f
17182 @key{RET}} (@code{Info-follow-reference}), you will generate an error
17186 No such node: "Catching Mistakes) The only way @dots{}
17190 This is because Info perceives the example of the error as the first
17191 cross reference in this node and if you type a @key{RET} immediately
17192 after typing the Info @kbd{f} command, Info will attempt to go to the
17193 referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
17194 will complete the node name of the correctly written example and take
17195 you to the `Catching Mistakes' node. (If you try this, you can return
17196 from the `Catching Mistakes' node by typing @kbd{l}
17197 (@code{Info-last}).)
17199 @c !!! section on using Elisp debugger ignored.
17201 Sometimes @code{texinfo-format-region} will stop long after the
17202 original error; this is because it does not discover the problem until
17203 then. In this case, you will need to backtrack.@refill
17206 @c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
17209 @c node Using the Emacs Lisp Debugger
17210 @c appendixsubsec Using the Emacs Lisp Debugger
17211 @c index Using the Emacs Lisp debugger
17212 @c index Emacs Lisp debugger
17213 @c index Debugger, using the Emacs Lisp
17215 If an error is especially elusive, you can turn on the Emacs Lisp
17216 debugger and look at the backtrace; this tells you where in the
17217 @code{texinfo-format-region} function the problem occurred. You can
17218 turn on the debugger with the command:@refill
17221 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
17225 and turn it off with
17228 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
17231 Often, when you are using the debugger, it is easier to follow what is
17232 going on if you use the Emacs Lisp files that are not byte-compiled.
17233 The byte-compiled sources send octal numbers to the debugger that may
17234 look mysterious. To use the uncompiled source files, load
17235 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
17238 The debugger will not catch an error if @code{texinfo-format-region}
17239 does not detect one. In the example shown above,
17240 @code{texinfo-format-region} did not find the error when the whole
17241 list was formatted, but only when part of the list was formatted.
17242 When @code{texinfo-format-region} did not find an error, the debugger
17243 did not find one either. @refill
17245 However, when @code{texinfo-format-region} did report an error, it
17246 invoked the debugger. This is the backtrace it produced:@refill
17249 ---------- Buffer: *Backtrace* ----------
17250 Signalling: (search-failed "[@},]")
17251 re-search-forward("[@},]")
17254 texinfo-format-parse-args()
17256 texinfo-format-xref()
17257 funcall(texinfo-format-xref)
17262 texinfo-format-scan()
17263 (save-excursion ...)
17265 texinfo-format-region(103370 103631)
17266 * call-interactively(texinfo-format-region)
17267 ---------- Buffer: *Backtrace* ----------
17270 The backtrace is read from the bottom up.
17271 @code{texinfo-format-region} was called interactively; and it, in
17272 turn, called various functions, including @code{texinfo-format-scan},
17273 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
17274 Inside the function @code{texinfo-format-parse-args}, the function
17275 @code{re-search-forward} was called; it was this function that could
17276 not find the missing right-hand brace.@refill
17278 @xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs
17279 Manual}, for more information.@refill
17282 @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
17283 @comment node-name, next, previous, up
17284 @section Catching Errors with @TeX{} Formatting
17285 @cindex Catching errors with @TeX{} formatting
17286 @cindex Debugging with @TeX{} formatting
17288 You can also catch mistakes when you format a file with @TeX{}.@refill
17290 Usually, you will want to do this after you have run
17291 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
17292 the same file, because @code{texinfo-format-buffer} sometimes displays
17293 error messages that make more sense than @TeX{}. (@xref{Debugging
17294 with Info}, for more information.)@refill
17296 For example, @TeX{} was run on a Texinfo file, part of which is shown
17300 ---------- Buffer: texinfo.texi ----------
17301 name of the Texinfo file as an extension. The
17302 @@samp@{??@} are `wildcards' that cause the shell to
17303 substitute all the raw index files. (@@xref@{sorting
17304 indices, for more information about sorting
17306 ---------- Buffer: texinfo.texi ----------
17310 (The cross reference lacks a closing brace.)
17311 @TeX{} produced the following output, after which it stopped:@refill
17314 ---------- Buffer: *tex-shell* ----------
17316 @{sorting indices, for more information about sorting
17317 indices.) @@refill @@ETC.
17318 ! Paragraph ended before @@xref was complete.
17324 ---------- Buffer: *tex-shell* ----------
17327 In this case, @TeX{} produced an accurate and
17328 understandable error message:
17331 Paragraph ended before @@xref was complete.
17335 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
17336 @samp{l.27} means that @TeX{} detected the problem on line 27 of the
17337 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
17338 circumstance.@refill
17340 Unfortunately, @TeX{} is not always so helpful, and sometimes you must
17341 truly be a Sherlock Holmes to discover what went wrong.@refill
17343 In any case, if you run into a problem like this, you can do one of three
17348 You can tell @TeX{} to continue running and ignore just this error by
17349 typing @key{RET} at the @samp{?} prompt.@refill
17352 You can tell @TeX{} to continue running and to ignore all errors as best
17353 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
17355 This is often the best thing to do. However, beware: the one error
17356 may produce a cascade of additional error messages as its consequences
17357 are felt through the rest of the file. To stop @TeX{} when it is
17358 producing such an avalanche of error messages, type @kbd{C-c} (or
17359 @kbd{C-c C-c}, if you are running a shell inside Emacs).
17362 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
17363 at the @samp{?} prompt.@refill
17366 If you are running @TeX{} inside Emacs, you need to switch to the shell
17367 buffer and line at which @TeX{} offers the @samp{?} prompt.
17369 Sometimes @TeX{} will format a file without producing error messages even
17370 though there is a problem. This usually occurs if a command is not ended
17371 but @TeX{} is able to continue processing anyhow. For example, if you fail
17372 to end an itemized list with the @code{@@end itemize} command, @TeX{} will
17373 write a DVI file that you can print out. The only error message that
17374 @TeX{} will give you is the somewhat mysterious comment that@refill
17377 (@@end occurred inside a group at level 1)
17381 However, if you print the DVI file, you will find that the text
17382 of the file that follows the itemized list is entirely indented as if
17383 it were part of the last item in the itemized list. The error message
17384 is the way @TeX{} says that it expected to find an @code{@@end}
17385 command somewhere in the file; but that it could not determine where
17386 it was needed.@refill
17388 Another source of notoriously hard-to-find errors is a missing
17389 @code{@@end group} command. If you ever are stumped by
17390 incomprehensible errors, look for a missing @code{@@end group} command
17393 If the Texinfo file lacks header lines,
17394 @TeX{} may stop in the
17395 beginning of its run and display output that looks like the following.
17396 The @samp{*} indicates that @TeX{} is waiting for input.@refill
17399 This is TeX, Version 3.14159 (Web2c 7.0)
17405 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
17406 write the header lines in the Texinfo file and run the @TeX{} command
17407 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
17408 instead of @samp{@@}; and in this circumstance, you are working
17409 directly with @TeX{}, not with Texinfo.)@refill
17411 @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
17412 @comment node-name, next, previous, up
17413 @section Using @code{texinfo-show-structure}
17414 @cindex Showing the structure of a file
17415 @findex texinfo-show-structure
17417 It is not always easy to keep track of the nodes, chapters, sections, and
17418 subsections of a Texinfo file. This is especially true if you are revising
17419 or adding to a Texinfo file that someone else has written.@refill
17421 In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
17422 command lists all the lines that begin with the @@-commands that
17423 specify the structure: @code{@@chapter}, @code{@@section},
17424 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
17425 as prefix argument, if interactive),
17426 the command also shows the @code{@@node} lines. The
17427 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
17428 Texinfo mode, by default.@refill
17430 The lines are displayed in a buffer called the @samp{*Occur*} buffer,
17431 indented by hierarchical level. For example, here is a part of what was
17432 produced by running @code{texinfo-show-structure} on this manual:@refill
17436 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
17437 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
17438 in buffer texinfo.texi.
17440 4177:@@chapter Nodes
17441 4198: @@heading Two Paths
17442 4231: @@section Node and Menu Illustration
17443 4337: @@section The @@code@{@@@@node@} Command
17444 4393: @@subheading Choosing Node and Pointer Names
17445 4417: @@subsection How to Write an @@code@{@@@@node@} Line
17446 4469: @@subsection @@code@{@@@@node@} Line Tips
17451 This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
17452 with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
17453 commands respectively. If you move your cursor into the @samp{*Occur*}
17454 window, you can position the cursor over one of the lines and use the
17455 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
17456 the corresponding spot in the Texinfo file. @xref{Other Repeating
17457 Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
17458 information about @code{occur-mode-goto-occurrence}.@refill
17460 The first line in the @samp{*Occur*} window describes the @dfn{regular
17461 expression} specified by @var{texinfo-heading-pattern}. This regular
17462 expression is the pattern that @code{texinfo-show-structure} looks for.
17463 @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
17464 for more information.@refill
17466 When you invoke the @code{texinfo-show-structure} command, Emacs will
17467 display the structure of the whole buffer. If you want to see the
17468 structure of just a part of the buffer, of one chapter, for example,
17469 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
17470 region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
17471 how the example used above was generated. (To see the whole buffer
17472 again, use @kbd{C-x n w} (@code{widen}).)@refill
17474 If you call @code{texinfo-show-structure} with a prefix argument by
17475 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
17476 @code{@@node} as well as the lines beginning with the @@-sign commands
17477 for @code{@@chapter}, @code{@@section}, and the like.@refill
17479 You can remind yourself of the structure of a Texinfo file by looking at
17480 the list in the @samp{*Occur*} window; and if you have mis-named a node
17481 or left out a section, you can correct the mistake.@refill
17483 @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
17484 @comment node-name, next, previous, up
17485 @section Using @code{occur}
17486 @cindex Occurrences, listing with @code{@@occur}
17489 Sometimes the @code{texinfo-show-structure} command produces too much
17490 information. Perhaps you want to remind yourself of the overall structure
17491 of a Texinfo file, and are overwhelmed by the detailed list produced by
17492 @code{texinfo-show-structure}. In this case, you can use the @code{occur}
17493 command directly. To do this, type@refill
17500 and then, when prompted, type a @dfn{regexp}, a regular expression for
17501 the pattern you want to match. (@xref{Regexps, , Regular Expressions,
17502 emacs, The GNU Emacs Manual}.) The @code{occur} command works from
17503 the current location of the cursor in the buffer to the end of the
17504 buffer. If you want to run @code{occur} on the whole buffer, place
17505 the cursor at the beginning of the buffer.@refill
17507 For example, to see all the lines that contain the word
17508 @samp{@@chapter} in them, just type @samp{@@chapter}. This will
17509 produce a list of the chapters. It will also list all the sentences
17510 with @samp{@@chapter} in the middle of the line.@refill
17512 If you want to see only those lines that start with the word
17513 @samp{@@chapter}, type @samp{^@@chapter} when prompted by
17514 @code{occur}. If you want to see all the lines that end with a word
17515 or phrase, end the last word with a @samp{$}; for example,
17516 @samp{catching mistakes$}. This can be helpful when you want to see
17517 all the nodes that are part of the same chapter or section and
17518 therefore have the same `Up' pointer.@refill
17520 @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
17521 for more information.@refill
17523 @node Running Info-Validate, , Using occur, Catching Mistakes
17524 @comment node-name, next, previous, up
17525 @section Finding Badly Referenced Nodes
17526 @findex Info-validate
17527 @cindex Nodes, checking for badly referenced
17528 @cindex Checking for badly referenced nodes
17529 @cindex Looking for badly referenced nodes
17530 @cindex Finding badly referenced nodes
17531 @cindex Badly referenced nodes
17533 You can use the @code{Info-validate} command to check whether any of
17534 the `Next', `Previous', `Up' or other node pointers fail to point to a
17535 node. This command checks that every node pointer points to an
17536 existing node. The @code{Info-validate} command works only on Info
17537 files, not on Texinfo files.@refill
17539 The @code{makeinfo} program validates pointers automatically, so you
17540 do not need to use the @code{Info-validate} command if you are using
17541 @code{makeinfo}. You only may need to use @code{Info-validate} if you
17542 are unable to run @code{makeinfo} and instead must create an Info file
17543 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
17544 if you write an Info file from scratch.@refill
17547 * Using Info-validate:: How to run @code{Info-validate}.
17548 * Unsplit:: How to create an unsplit file.
17549 * Tagifying:: How to tagify a file.
17550 * Splitting:: How to split a file manually.
17553 @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
17554 @subsection Running @code{Info-validate}
17555 @cindex Running @code{Info-validate}
17556 @cindex Info validating a large file
17557 @cindex Validating a large file
17559 To use @code{Info-validate}, visit the Info file you wish to check and
17567 Note that the @code{Info-validate} command requires an upper case
17568 `I'. You may also need to create a tag table before running
17569 @code{Info-validate}. @xref{Tagifying}.
17571 If your file is valid, you will receive a message that says ``File appears
17572 valid''. However, if you have a pointer that does not point to a node,
17573 error messages will be displayed in a buffer called @samp{*problems in
17574 info file*}.@refill
17576 For example, @code{Info-validate} was run on a test file that contained
17577 only the first node of this manual. One of the messages said:@refill
17580 In node "Overview", invalid Next: Texinfo Mode
17584 This meant that the node called @samp{Overview} had a `Next' pointer that
17585 did not point to anything (which was true in this case, since the test file
17586 had only one node in it).@refill
17588 Now suppose we add a node named @samp{Texinfo Mode} to our test case
17589 but we do not specify a `Previous' for this node. Then we will get
17590 the following error message:@refill
17593 In node "Texinfo Mode", should have Previous: Overview
17597 This is because every `Next' pointer should be matched by a
17598 `Previous' (in the node where the `Next' points) which points back.@refill
17600 @code{Info-validate} also checks that all menu entries and cross references
17601 point to actual nodes.@refill
17603 @code{Info-validate} requires a tag table and does not work with files
17604 that have been split. (The @code{texinfo-format-buffer} command
17605 automatically splits large files.) In order to use @code{Info-validate}
17606 on a large file, you must run @code{texinfo-format-buffer} with an
17607 argument so that it does not split the Info file; and you must create a
17608 tag table for the unsplit file.
17610 @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
17611 @comment node-name, next, previous, up
17612 @subsection Creating an Unsplit File
17613 @cindex Creating an unsplit file
17614 @cindex Unsplit file creation
17616 You can run @code{Info-validate} only on a single Info file that has a
17617 tag table. The command will not work on the indirect subfiles that
17618 are generated when a master file is split. If you have a large file
17619 (longer than 70,000 bytes or so), you need to run the
17620 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
17621 a way that it does not create indirect subfiles. You will also need
17622 to create a tag table for the Info file. After you have done this,
17623 you can run @code{Info-validate} and look for badly referenced
17626 The first step is to create an unsplit Info file. To prevent
17627 @code{texinfo-format-buffer} from splitting a Texinfo file into
17628 smaller Info files, give a prefix to the @kbd{M-x
17629 texinfo-format-buffer} command:@refill
17632 C-u M-x texinfo-format-buffer
17643 When you do this, Texinfo will not split the file and will not create
17644 a tag table for it. @refill
17645 @cindex Making a tag table manually
17646 @cindex Tag table, making manually
17648 @node Tagifying, Splitting, Unsplit, Running Info-Validate
17649 @subsection Tagifying a File
17651 After creating an unsplit Info file, you must create a tag table for
17652 it. Visit the Info file you wish to tagify and type:@refill
17659 (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
17660 Info file with a tag table that you can validate.@refill
17662 The third step is to validate the Info file:@refill
17669 (Note the upper case @samp{I} in @code{Info-validate}.)
17670 In brief, the steps are:@refill
17674 C-u M-x texinfo-format-buffer
17680 After you have validated the node structure, you can rerun
17681 @code{texinfo-format-buffer} in the normal way so it will construct a
17682 tag table and split the file automatically, or you can make the tag
17683 table and split the file manually.@refill
17685 @node Splitting, , Tagifying, Running Info-Validate
17686 @comment node-name, next, previous, up
17687 @subsection Splitting a File Manually
17688 @cindex Splitting an Info file manually
17689 @cindex Info file, splitting manually
17691 You should split a large file or else let the
17692 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
17693 for you automatically. (Generally you will let one of the formatting
17694 commands do this job for you. @xref{Creating an Info File}.)@refill
17696 The split-off files are called the indirect subfiles.@refill
17698 Info files are split to save memory. With smaller files, Emacs does not
17699 have make such a large buffer to hold the information.@refill
17701 If an Info file has more than 30 nodes, you should also make a tag
17702 table for it. @xref{Using Info-validate}, for information
17703 about creating a tag table. (Again, tag tables are usually created
17704 automatically by the formatting command; you only need to create a tag
17705 table yourself if you are doing the job manually. Most likely, you
17706 will do this for a large, unsplit file on which you have run
17707 @code{Info-validate}.)@refill
17709 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
17711 Before running @code{Info-split}, you need to load the @code{info} library
17712 into Emacs by giving the command @kbd{M-x load-library @key{RET} info
17716 Visit the Info file you wish to tagify and split and type the two
17725 (Note that the @samp{I} in @samp{Info} is upper case.)@refill
17727 When you use the @code{Info-split} command, the buffer is modified into a
17728 (small) Info file which lists the indirect subfiles. This file should be
17729 saved in place of the original visited file. The indirect subfiles are
17730 written in the same directory the original file is in, with names generated
17731 by appending @samp{-} and a number to the original file name.@refill
17733 The primary file still functions as an Info file, but it contains just
17734 the tag table and a directory of subfiles.@refill
17737 @node Refilling Paragraphs
17738 @appendix Refilling Paragraphs
17739 @cindex Refilling paragraphs
17740 @cindex Filling paragraphs
17741 @cindex Paragraphs, filling
17744 The @code{@@refill} command refills and, optionally, indents the first
17745 line of a paragraph.@footnote{Perhaps the command should have been
17746 called the @code{@@refillandindent} command, but @code{@@refill} is
17747 shorter and the name was chosen before indenting was possible.} The
17748 @code{@@refill} command is no longer important, but we describe it here
17749 because you once needed it. You will see it in many old Texinfo
17752 Without refilling, paragraphs containing long @@-constructs may look
17753 bad after formatting because the formatter removes @@-commands and
17754 shortens some lines more than others. In the past, neither the
17755 @code{texinfo-format-region} command nor the
17756 @code{texinfo-format-buffer} command refilled paragraphs
17757 automatically. The @code{@@refill} command had to be written at the
17758 end of every paragraph to cause these formatters to fill them. (Both
17759 @TeX{} and @code{makeinfo} have always refilled paragraphs
17760 automatically.) Now, all the Info formatters automatically fill and
17761 indent those paragraphs that need to be filled and indented.@refill
17763 The @code{@@refill} command causes @code{texinfo-format-region} and
17764 @code{texinfo-format-buffer} to refill a paragraph in the Info file
17765 @emph{after} all the other processing has been done. For this reason,
17766 you can not use @code{@@refill} with a paragraph containing either
17767 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
17768 override those two commands.@refill
17770 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
17771 commands now automatically append @code{@@refill} to the end of each
17772 paragraph that should be filled. They do not append @code{@@refill} to
17773 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
17774 and therefore do not refill or indent them.@refill
17777 @node Command Syntax
17778 @appendix @@-Command Syntax
17779 @cindex @@-command syntax
17780 @cindex Syntax, of @@-commands
17781 @cindex Command syntax
17783 The character @samp{@@} is used to start special Texinfo commands.
17784 (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
17785 has four types of @@-command:@refill
17788 @item 1. Non-alphabetic commands.
17789 These commands consist of an @@ followed by a punctuation mark or other
17790 character that is not part of the alphabet. Non-alphabetic commands are
17791 almost always part of the text within a paragraph, and never take any
17792 argument. The two characters (@@ and the other one) are complete in
17793 themselves; none is followed by braces. The non-alphabetic commands
17794 are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
17795 @code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
17796 @code{@@@}}.@refill
17798 @item 2. Alphabetic commands that do not require arguments.
17799 These commands start with @@ followed by a word followed by left- and
17800 right-hand braces. These commands insert special symbols in the
17801 document; they do not require arguments. For example,
17802 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
17803 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
17804 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
17806 @item 3. Alphabetic commands that require arguments within braces.
17807 These commands start with @@ followed by a letter or a word, followed by an
17808 argument within braces. For example, the command @code{@@dfn} indicates
17809 the introductory or defining use of a term; it is used as follows: @samp{In
17810 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
17812 @item 4. Alphabetic commands that occupy an entire line.
17813 These commands occupy an entire line. The line starts with @@,
17814 followed by the name of the command (a word); for example, @code{@@center}
17815 or @code{@@cindex}. If no argument is needed, the word is followed by
17816 the end of the line. If there is an argument, it is separated from
17817 the command name by a space. Braces are not used.@refill
17820 @cindex Braces and argument syntax
17821 Thus, the alphabetic commands fall into classes that have
17822 different argument syntaxes. You cannot tell to which class a command
17823 belongs by the appearance of its name, but you can tell by the
17824 command's meaning: if the command stands for a glyph, it is in
17825 class 2 and does not require an argument; if it makes sense to use the
17826 command together with other text as part of a paragraph, the command
17827 is in class 3 and must be followed by an argument in braces;
17828 otherwise, it is in class 4 and uses the rest of the line as its
17831 The purpose of having a different syntax for commands of classes 3 and
17832 4 is to make Texinfo files easier to read, and also to help the GNU
17833 Emacs paragraph and filling commands work properly. There is only one
17834 exception to this rule: the command @code{@@refill}, which is always
17835 used at the end of a paragraph immediately following the final period
17836 or other punctuation character. @code{@@refill} takes no argument and
17837 does @emph{not} require braces. @code{@@refill} never confuses the
17838 Emacs paragraph commands because it cannot appear at the beginning of
17842 @node Obtaining TeX
17843 @appendix How to Obtain @TeX{}
17844 @cindex Obtaining @TeX{}
17845 @cindex @TeX{}, how to obtain
17847 @c !!! Here is information about obtaining TeX. Update it whenever.
17848 @c !!! Also consider updating TeX.README on ftp.gnu.org.
17849 @c Updated by RJC on 1 March 1995, conversation with MacKay.
17850 @c Updated by kb@cs.umb.edu on 29 July 1996.
17851 @c Updated by kb@cs.umb.edu on 25 April 1997.
17852 @c Updated by kb@cs.umb.edu on 27 February 1998.
17853 @TeX{} is freely redistributable. You can obtain @TeX{} for Unix
17854 systems via anonymous ftp or on physical media. The core material
17855 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
17857 Instructions for retrieval by anonymous ftp and information on other
17858 available distributions:
17860 @uref{ftp://tug.org/tex/unixtex.ftp}
17861 @uref{http://tug.org/unixtex.ftp}
17864 The Free Software Foundation provides a core distribution on its Source
17865 Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
17869 Free Software Foundation, Inc.
17870 59 Temple Place Suite 330
17871 Boston, MA @ @ 02111-1307
17873 Telephone: @w{+1-617-542-5942}
17874 Fax: (including Japan) @w{+1-617-542-2652}
17875 Free Dial Fax (in Japan):
17876 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
17877 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
17878 Electronic mail: @code{gnu@@gnu.org}
17882 Many other @TeX{} distributions are available; see
17883 @uref{http://tug.org/}.
17886 @c These are no longer ``new'', and the explanations
17887 @c are all given elsewhere anyway, I think. --karl, 25apr97.
17888 @c So ignore the entire appendix.
17890 @c node New Features, Command and Variable Index, Obtaining TeX, Top
17891 @c appendix Second Edition Features
17894 % Widen the space for the first column so three control-character
17895 % strings fit in the first column. Switched back to default .8in
17896 % value at end of chapter.
17897 \global\tableindent=1.0in
17900 The second edition of the Texinfo manual describes more than 20 new
17901 Texinfo mode commands and more than 50 previously undocumented Texinfo
17902 @@-commands. This edition is more than twice the length of the first
17905 Here is a brief description of the new commands.@refill
17908 * New Texinfo Mode Commands:: The updating commands are especially useful.
17909 * New Commands:: Many newly described @@-commands.
17912 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
17913 @c appendixsec New Texinfo Mode Commands
17915 Texinfo mode provides commands and features especially designed for
17916 working with Texinfo files. More than 20 new commands have been
17917 added, including commands for automatically creating and updating
17918 both nodes and menus. This is a tedious task when done by hand.@refill
17920 The keybindings are intended to be somewhat mnemonic.@refill
17922 @c subheading Update all nodes and menus
17924 The @code{texinfo-master-menu} command is the primary command:
17928 @itemx M-x texinfo-master-menu
17929 Create or update a master menu.
17930 With @kbd{C-u} as a prefix argument,
17931 first create or update all nodes
17935 @c subheading Update Pointers
17938 Create or update `Next', `Previous', and `Up' node pointers.@refill
17941 @xref{Updating Nodes and Menus}.
17945 @itemx M-x texinfo-update-node
17949 @itemx M-x texinfo-every-node-update
17950 Update every node in the buffer.
17953 @c subheading Update Menus
17956 Create or update menus.@refill
17959 @xref{Updating Nodes and Menus}.
17963 @itemx M-x texinfo-make-menu
17964 Make or update a menu.
17967 @itemx M-x texinfo-all-menus-update
17968 Make or update all the menus in a buffer.
17969 With @kbd{C-u} as a prefix argument,
17970 first update all the nodes.
17973 @c subheading Insert Title as Description
17976 Insert a node's chapter or section title in the space for the
17977 description in a menu entry line; position point so you can edit the
17978 insert. (This command works somewhat differently than the other
17979 insertion commands, which insert only a predefined string.)@refill
17982 @xref{Inserting, Inserting Frequently Used Commands}.
17989 @c subheading Format for Info
17992 Provide keybindings both for the Info formatting commands that are
17993 written in Emacs Lisp and for @code{makeinfo} that is written in
17997 @xref{Info Formatting}.
18000 Use the Emacs lisp @code{texinfo-format@dots{}} commands:
18011 Use @code{makeinfo}:
18021 Recenter the @code{makeinfo} output buffer.
18024 Kill the @code{makeinfo} formatting job.
18027 @c subheading Typeset and Print
18030 Typeset and print Texinfo documents from within Emacs.@refill
18038 @xref{Printing, , Formatting and Printing}.
18043 Run @code{texi2dvi} on the buffer.
18046 Run @TeX{} on the region.
18049 Run @code{texindex}.
18052 Print the DVI file.
18055 Show the print queue.
18058 Delete a job from the print queue.
18061 Kill the current @TeX{} formatting job.
18064 Quit a currently stopped @TeX{} formatting job.
18067 Recenter the output buffer.
18070 @c subheading Other Updating Commands
18073 The ``other updating commands'' do not have standard keybindings because
18074 they are used less frequently.@refill
18077 @xref{Other Updating Commands}.
18080 @item M-x texinfo-insert-node-lines
18081 Insert missing @code{@@node} lines using
18082 section titles as node names.
18084 @item M-x texinfo-multiple-files-update
18085 Update a multi-file document.
18086 With a numeric prefix, such as @kbd{C-u 8},
18087 update @strong{every} pointer and
18088 menu in @strong{all} the files and
18089 then insert a master menu.
18091 @item M-x texinfo-indent-menu-description
18092 Indent descriptions in menus.
18094 @item M-x texinfo-sequential-node-update
18095 Insert node pointers in strict sequence.
18098 @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX
18099 @c appendix.sec New Texinfo @@-Commands
18101 The second edition of the Texinfo manual describes more than 50
18102 commands that were not described in the first edition. A third or so
18103 of these commands existed in Texinfo but were not documented in the
18104 manual; the others are new. Here is a listing, with brief
18105 descriptions of them:@refill
18107 @c subheading Indexing
18110 Create your own index, and merge indices.@refill
18116 @item @@defindex @var{index-name}
18117 Define a new index and its indexing command.
18118 See also the @code{@@defcodeindex} command.
18120 @c written verbosely to avoid overfull hbox
18121 @item @@synindex @var{from-index} @var{into-index}
18122 Merge the @var{from-index} index into the @var{into-index} index.
18123 See also the @code{@@syncodeindex} command.
18126 @c subheading Definitions
18129 Describe functions, variables, macros,
18130 commands, user options, special forms, and other such artifacts in a
18131 uniform format.@refill
18134 @xref{Definition Commands}.
18137 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
18138 Format a description for functions, interactive
18139 commands, and similar entities.
18141 @item @@defvr, @@defop, @dots{}
18142 15 other related commands.
18145 @c subheading Glyphs
18148 Indicate the results of evaluation, expansion,
18149 printed output, an error message, equivalence of expressions, and the
18150 location of point.@refill
18164 @item @@expansion@{@}
18165 @itemx @expansion{}
18178 Result of an expression
18181 @c subheading Page Headings
18184 Customize page headings.
18190 @item @@headings @var{on-off-single-double}
18191 Headings on or off, single, or double-sided.
18193 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
18194 Footings for even-numbered (left-hand) pages.
18196 @item @@evenheading, @@everyheading, @@oddheading, @dots{}
18197 Five other related commands.
18199 @item @@thischapter
18200 Insert name of chapter and chapter number.
18202 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
18206 @c subheading Formatting
18209 Format blocks of text.
18212 @xref{Quotations and Examples}, and@*
18213 @ref{Lists and Tables, , Making Lists and Tables}.
18217 Draw rounded box surrounding text (not in Info).
18219 @item @@enumerate @var{optional-arg}
18220 Enumerate a list with letters or numbers.
18222 @item @@exdent @var{line-of-text}
18223 Remove indentation.
18232 Do not narrow nor change font.
18234 @item @@ftable @var{formatting-command}
18235 @itemx @@vtable @var{formatting-command}
18236 Two-column table with indexing.
18239 For an example of Lisp code.
18241 @item @@smallexample
18243 Like @@table and @@lisp @r{but for} @@smallbook.
18246 @c subheading Conditionals
18249 Conditionally format text.
18252 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
18255 @item @@set @var{flag} [@var{string}]
18256 Set a flag. Optionally, set value
18257 of @var{flag} to @var{string}.
18259 @item @@clear @var{flag}
18262 @item @@value@{@var{flag}@}
18263 Replace with value to which @var{flag} is set.
18265 @item @@ifset @var{flag}
18266 Format, if @var{flag} is set.
18268 @item @@ifclear @var{flag}
18269 Ignore, if @var{flag} is set.
18272 @c subheading @@heading series for Titles
18275 Produce unnumbered headings that do not appear in a table of contents.
18278 @xref{Structuring}.
18281 @item @@heading @var{title}
18282 Unnumbered section-like heading not listed
18283 in the table of contents of a printed manual.
18285 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
18290 @c subheading Font commands
18294 @xref{Smallcaps}, and @*
18298 @item @@r@{@var{text}@}
18299 Print in roman font.
18301 @item @@sc@{@var{text}@}
18302 Print in @sc{small caps} font.
18305 @c subheading Miscellaneous
18308 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
18309 see @ref{Customized Highlighting},@*
18310 see @ref{Overfull hboxes},@*
18311 see @ref{Footnotes},@*
18312 see @ref{dmn, , Format a Dimension},@*
18313 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
18314 see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@*
18315 see @ref{minus, , Inserting a Minus Sign},@*
18316 see @ref{paragraphindent, , Paragraph Indenting},@*
18317 see @ref{Cross Reference Commands},@*
18318 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
18319 see @ref{Custom Headings, , How to Make Your Own Headings}.
18322 @item @@author @var{author}
18323 Typeset author's name.
18325 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
18326 @c Define a highlighting command for Info. (Info only.)
18329 Produce cleaner printed output.
18331 @item @@footnotestyle @var{end-or-separate}
18332 Specify footnote style.
18334 @item @@dmn@{@var{dimension}@}
18335 Format a dimension.
18337 @item @@global@@let@var{new-cmd}=@var{existing-cmd}
18338 Define a highlighting command for @TeX{}. (@TeX{} only.)
18340 @item @@lowersections
18341 Reduce hierarchical level of sectioning commands.
18343 @item @@math@{@var{mathematical-expression}@}
18344 Format a mathematical expression.
18347 Generate a minus sign.
18349 @item @@paragraphindent @var{asis-or-number}
18350 Specify paragraph indentation.
18352 @item @@raisesections
18353 Raise hierarchical level of sectioning commands.
18355 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
18356 Make a reference. In the printed manual, the
18357 reference does not start with the word `see'.
18359 @item @@title @var{title}
18360 Typeset @var{title} in the alternative
18363 @item @@subtitle @var{subtitle}
18364 Typeset @var{subtitle} in the alternative
18368 Insert the current date.
18371 % Switch width of first column of tables back to default value
18372 \global\tableindent=.8in
18377 @node Command and Variable Index
18378 @unnumbered Command and Variable Index
18380 This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
18381 functions, and several variables. To make the list easier to use, the
18382 commands are listed without their preceding @samp{@@}.@refill
18387 @node Concept Index
18388 @unnumbered Concept Index