1 \input texinfo.tex @c -*-texinfo-*-
2 @c $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
3 @c Ordinarily Texinfo files have the extension .texi. But texinfo.texi
4 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
6 @c Everything between the start/end of header lines will be passed by
7 @c Emacs's {texinfo,makeinfo}-format region commands. See the `start of
8 @c header' node for more info.
11 @c makeinfo and texinfo.tex ignore all text before @setfilename.
13 @c Ordinarily the setfilename argument ends with .info. But
14 @c texinfo.info-13 is too long for 14-character filesystems.
17 @c Automake automatically updates version.texi to @set VERSION and
18 @c @set UPDATED to appropriate values.
20 @settitle GNU Texinfo @value{VERSION}
22 @c Define a new index for options.
24 @c Put everything except function (command, in this case) names in one
25 @c index (arbitrarily chosen to be the concept index).
30 @footnotestyle separate
34 @comment %**end of header
37 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
38 a documentation system that can produce both online information and a
39 printed manual from a single source.
41 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
42 Free Software Foundation, Inc.
45 Permission is granted to copy, distribute and/or modify this document
46 under the terms of the GNU Free Documentation License, Version 1.1 or
47 any later version published by the Free Software Foundation; with no
48 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
49 and with the Back-Cover Texts as in (a) below. A copy of the license is
50 included in the section entitled ``GNU Free Documentation License.''
52 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
53 this GNU Manual, like GNU software. Copies published by the Free
54 Software Foundation raise funds for GNU development.''
58 @dircategory Texinfo documentation system
60 * Texinfo: (texinfo). The GNU documentation format.
61 * install-info: (texinfo)Invoking install-info. Update info/dir entries.
62 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
63 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
64 * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
67 @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
68 @c prefix arg). This updates the node pointers, which texinfmt.el needs.
70 @c Set smallbook if printing in smallbook format so the example of the
71 @c smallbook font is actually written using smallbook; in bigbook, a kludge
72 @c is used for TeX output. Do this through the -t option to texi2dvi,
73 @c so this same source can be used for other paper sizes as well.
78 @c If you like blank pages, add through texi2dvi -t.
79 @c setchapternewpage odd
81 @c Currently undocumented command, 5 December 1993:
82 @c nwnode (Same as node, but no warnings; for `makeinfo'.)
85 @shorttitlepage Texinfo
89 @subtitle The GNU Documentation Format
90 @subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
92 @author Robert J. Chassell
93 @author Richard M. Stallman
95 @c Include the Distribution inside the titlepage so
96 @c that headings are turned off.
99 @vskip 0pt plus 1filll
102 Published by the Free Software Foundation @*
103 59 Temple Place Suite 330 @*
104 Boston, MA 02111-1307 @*
106 ISBN 1-882114-67-1 @c for version 4.0, September 1999.
107 @c ISBN 1-882114-65-5 is for version 3.12, March 1998.
108 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
109 @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
111 Cover art by Etienne Suvasa.
125 The first part of this master menu lists the major nodes in this Info
126 document, including the @@-command and concept indices. The rest of
127 the menu lists all the lower level nodes in the document.
132 * Copying Conditions:: Your rights.
133 * Overview:: Texinfo in brief.
134 * Texinfo Mode:: How to use Texinfo mode.
135 * Beginning a File:: What is at the beginning of a Texinfo file?
136 * Ending a File:: What is at the end of a Texinfo file?
137 * Structuring:: How to create chapters, sections, subsections,
138 appendices, and other parts.
139 * Nodes:: How to write nodes.
140 * Menus:: How to write menus.
141 * Cross References:: How to write cross references.
142 * Marking Text:: How to mark words and phrases as code,
143 keyboard input, meta-syntactic
144 variables, and the like.
145 * Quotations and Examples:: How to write quotations, examples, etc.
146 * Lists and Tables:: How to write lists and tables.
147 * Indices:: How to create indices.
148 * Insertions:: How to insert @@-signs, braces, etc.
149 * Breaks:: How to force and prevent line and page breaks.
150 * Definition Commands:: How to describe functions and the like
152 * Conditionals:: How to specify text for either @TeX{} or Info.
153 * Internationalization::
154 * Defining New Texinfo Commands::
155 * Hardcopy:: How to convert a Texinfo file to a file
156 for printing and how to print that file.
157 * Creating and Installing Info Files::
158 * Command List:: All the Texinfo @@-commands.
159 * Tips:: Hints on how to write a Texinfo document.
160 * Sample Texinfo Files:: Complete examples, including full texts.
161 * Include Files:: How to incorporate other Texinfo files.
162 * Headings:: How to write page headings and footings.
163 * Catching Mistakes:: How to find formatting mistakes.
164 * Refilling Paragraphs:: All about paragraph refilling.
165 * Command Syntax:: A description of @@-Command syntax.
166 * Obtaining TeX:: How to Obtain @TeX{}.
167 * Copying This Manual:: The GNU Free Documentation License.
168 * Command and Variable Index:: A menu containing commands and variables.
169 * Concept Index:: A menu covering many topics.
172 --- The Detailed Node Listing ---
176 * Reporting Bugs:: Submitting effective bug reports.
177 * Using Texinfo:: Create printed or online output.
178 * Info Files:: What is an Info file?
179 * Printed Books:: Characteristics of a printed book or manual.
180 * Formatting Commands:: @@-commands are used for formatting.
181 * Conventions:: General rules for writing a Texinfo file.
182 * Comments:: Writing comments and ignored text in general.
183 * Minimum:: What a Texinfo file must have.
184 * Six Parts:: Usually, a Texinfo file has six parts.
185 * Short Sample:: A short sample Texinfo file.
186 * History:: Acknowledgements, contributors and genesis.
190 * Texinfo Mode Overview:: How Texinfo mode can help you.
191 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
192 purpose editing features.
193 * Inserting:: How to insert frequently used @@-commands.
194 * Showing the Structure:: How to show the structure of a file.
195 * Updating Nodes and Menus:: How to update or create new nodes and menus.
196 * Info Formatting:: How to format for Info.
197 * Printing:: How to format and print part or all of a file.
198 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
200 Updating Nodes and Menus
202 * Updating Commands:: Five major updating commands.
203 * Updating Requirements:: How to structure a Texinfo file for
204 using the updating command.
205 * Other Updating Commands:: How to indent descriptions, insert
206 missing nodes lines, and update
209 Beginning a Texinfo File
211 * Sample Beginning:: A sample beginning for a Texinfo file.
212 * Texinfo File Header::
213 * Document Permissions::
214 * Titlepage & Copyright Page:: Creating the title and copyright pages.
215 * The Top Node:: Creating the `Top' node and master menu.
216 * Global Document Commands::
217 * Software Copying Permissions:: Ensure that you and others continue to
218 have the right to use and share software.
222 * First Line:: The first line of a Texinfo file.
223 * Start of Header:: Formatting a region requires this.
224 * setfilename:: Tell Info the name of the Info file.
225 * settitle:: Create a title for the printed work.
226 * End of Header:: Formatting a region requires this.
230 * copying:: Declare the document's copying permissions.
231 * insertcopying:: Where to insert the permissions.
233 Title and Copyright Pages
235 * titlepage:: Create a title for the printed document.
236 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
237 and @code{@@sp} commands.
238 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
239 and @code{@@author} commands.
240 * Copyright:: How to write the copyright notice and
241 include copying permissions.
242 * end titlepage:: Turn on page headings after the title and
244 * headings on off:: An option for turning headings on and off
245 and double or single sided printing.
247 The `Top' Node and Master Menu
250 * Master Menu Parts::
252 Global Document Commands
254 * documentdescription:: Document summary for the HTML output.
255 * setchapternewpage:: Start chapters on right-hand pages.
256 * paragraphindent:: Specify paragraph indentation.
257 * exampleindent:: Specify environment indentation.
259 Ending a Texinfo File
261 * Printing Indices & Menus:: How to print an index in hardcopy and
262 generate index menus in Info.
263 * Contents:: How to create a table of contents.
264 * File End:: How to mark the end of a file.
268 * Tree Structuring:: A manual is like an upside down tree @dots{}
269 * Structuring Command Types:: How to divide a manual into parts.
270 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
272 * unnumbered & appendix::
273 * majorheading & chapheading::
275 * unnumberedsec appendixsec heading::
277 * unnumberedsubsec appendixsubsec subheading::
278 * subsubsection:: Commands for the lowest level sections.
279 * Raise/lower sections:: How to change commands' hierarchical level.
283 * Two Paths:: Different commands to structure
284 Info output and printed output.
285 * Node Menu Illustration:: A diagram, and sample nodes and menus.
286 * node:: Creating nodes, in detail.
287 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
288 * anchor:: Defining arbitrary cross-reference targets.
290 The @code{@@node} Command
292 * Node Names:: How to choose node and pointer names.
293 * Writing a Node:: How to write an @code{@@node} line.
294 * Node Line Tips:: Keep names short.
295 * Node Line Requirements:: Keep names unique, without @@-commands.
296 * First Node:: How to write a `Top' node.
297 * makeinfo top command:: How to use the @code{@@top} command.
301 * Menu Location:: Put a menu in a short node.
302 * Writing a Menu:: What is a menu?
303 * Menu Parts:: A menu entry has three parts.
304 * Less Cluttered Menu Entry:: Two part menu entry.
305 * Menu Example:: Two and three part menu entries.
306 * Other Info Files:: How to refer to a different Info file.
310 * References:: What cross references are for.
311 * Cross Reference Commands:: A summary of the different commands.
312 * Cross Reference Parts:: A cross reference has several parts.
313 * xref:: Begin a reference with `See' @dots{}
314 * Top Node Naming:: How to refer to the beginning of another file.
315 * ref:: A reference for the last part of a sentence.
316 * pxref:: How to write a parenthetical cross reference.
317 * inforef:: How to refer to an Info-only file.
318 * uref:: How to refer to a uniform resource locator.
322 * Reference Syntax:: What a reference looks like and requires.
323 * One Argument:: @code{@@xref} with one argument.
324 * Two Arguments:: @code{@@xref} with two arguments.
325 * Three Arguments:: @code{@@xref} with three arguments.
326 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
328 Marking Words and Phrases
330 * Indicating:: How to indicate definitions, files, etc.
331 * Emphasis:: How to emphasize text.
333 Indicating Definitions, Commands, etc.
335 * Useful Highlighting:: Highlighting provides useful information.
336 * code:: Indicating program code.
337 * kbd:: Showing keyboard input.
338 * key:: Specifying keys.
339 * samp:: A literal sequence of characters.
340 * verb:: A verbatim sequence of characters.
341 * var:: Indicating metasyntactic variables.
342 * env:: Indicating environment variables.
343 * file:: Indicating file names.
344 * command:: Indicating command names.
345 * option:: Indicating option names.
346 * dfn:: Specifying definitions.
347 * cite:: Referring to books not in the Info system.
348 * acronym:: Indicating acronyms.
349 * url:: Indicating a World Wide Web reference.
350 * email:: Indicating an electronic mail address.
354 * emph & strong:: How to emphasize text in Texinfo.
355 * Smallcaps:: How to use the small caps font.
356 * Fonts:: Various font commands for printed output.
358 Quotations and Examples
360 * Block Enclosing Commands:: Different constructs for different purposes.
361 * quotation:: Writing a quotation.
362 * example:: Writing an example in a fixed-width font.
363 * verbatim:: Writing a verbatim example.
364 * verbatiminclude:: Including a file verbatim.
365 * lisp:: Illustrating Lisp code.
366 * small:: Forms for @code{@@smallbook}.
367 * display:: Writing an example in the current font.
368 * format:: Writing an example without narrowed margins.
369 * exdent:: Undo indentation on a line.
370 * flushleft & flushright:: Pushing text flush left or flush right.
371 * noindent:: Preventing paragraph indentation.
372 * cartouche:: Drawing rounded rectangles around examples.
376 * Introducing Lists:: Texinfo formats lists for you.
377 * itemize:: How to construct a simple list.
378 * enumerate:: How to construct a numbered list.
379 * Two-column Tables:: How to construct a two-column table.
380 * Multi-column Tables:: How to construct generalized tables.
382 Making a Two-column Table
384 * table:: How to construct a two-column table.
385 * ftable vtable:: Automatic indexing for two-column tables.
386 * itemx:: How to put more entries in the first column.
390 * Multitable Column Widths:: Defining multitable column widths.
391 * Multitable Rows:: Defining multitable rows, with examples.
395 * Index Entries:: Choose different words for index entries.
396 * Predefined Indices:: Use different indices for different kinds
398 * Indexing Commands:: How to make an index entry.
399 * Combining Indices:: How to combine indices.
400 * New Indices:: How to define your own indices.
404 * syncodeindex:: How to merge two indices, using @code{@@code}
405 font for the merged-from index.
406 * synindex:: How to merge two indices, using the
407 default font of the merged-to index.
411 * Braces Atsigns:: How to insert braces, @samp{@@}.
412 * Inserting Space:: How to insert the right amount of space
414 * Inserting Accents:: How to insert accents and special characters.
415 * Dots Bullets:: How to insert dots and bullets.
416 * TeX and copyright:: How to insert the @TeX{} logo
417 and the copyright symbol.
418 * pounds:: How to insert the pounds currency symbol.
419 * minus:: How to insert a minus sign.
420 * math:: How to format a mathematical expression.
421 * Glyphs:: How to indicate results of evaluation,
422 expansion of macros, errors, etc.
423 * Footnotes:: How to include footnotes.
424 * Images:: How to include graphics.
426 Inserting @@ and Braces
428 * Inserting An Atsign:: How to insert @samp{@@}.
429 * Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
433 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
434 * Ending a Sentence:: Sometimes it does.
435 * Multiple Spaces:: Inserting multiple spaces.
436 * dmn:: How to format a dimension.
438 Inserting Ellipsis and Bullets
440 * dots:: How to insert dots @dots{}
441 * bullet:: How to insert a bullet.
443 Inserting @TeX{} and the Copyright Symbol
445 * tex:: How to insert the @TeX{} logo.
446 * copyright symbol:: How to use @code{@@copyright}@{@}.
451 * result:: How to show the result of expression.
452 * expansion:: How to indicate an expansion.
453 * Print Glyph:: How to indicate printed output.
454 * Error Glyph:: How to indicate an error message.
455 * Equivalence:: How to indicate equivalence.
456 * Point Glyph:: How to indicate the location of point.
469 * Footnote Commands:: How to write a footnote in Texinfo.
470 * Footnote Styles:: Controlling how footnotes appear in Info.
472 Making and Preventing Breaks
474 * Break Commands:: Cause and prevent splits.
475 * Line Breaks:: How to force a single line to use two lines.
476 * - and hyphenation:: How to tell @TeX{} about hyphenation points.
477 * w:: How to prevent unwanted line breaks.
478 * sp:: How to insert blank lines.
479 * page:: How to force the start of a new page.
480 * group:: How to prevent unwanted page breaks.
481 * need:: Another way to prevent unwanted page breaks.
485 * Def Cmd Template:: How to structure a description using a
487 * Optional Arguments:: How to handle optional and repeated arguments.
488 * deffnx:: How to group two or more `first' lines.
489 * Def Cmds in Detail:: All the definition commands.
490 * Def Cmd Conventions:: Conventions for writing definitions.
491 * Sample Function Definition::
493 The Definition Commands
495 * Functions Commands:: Commands for functions and similar entities.
496 * Variables Commands:: Commands for variables and similar entities.
497 * Typed Functions:: Commands for functions in typed languages.
498 * Typed Variables:: Commands for variables in typed languages.
499 * Abstract Objects:: Commands for object-oriented programming.
500 * Data Types:: The definition command for data types.
502 Conditionally Visible Text
504 * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
505 * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
506 * Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
507 * set clear value:: Designating which text to format (for
508 all output formats); and how to set a
509 flag to a string that you can insert.
511 @code{@@set}, @code{@@clear}, and @code{@@value}
513 * set value:: Expand a flag variable to a string.
514 * ifset ifclear:: Format a region if a flag is set.
515 * value Example:: An easy way to update edition information.
519 * documentlanguage:: Declaring the current language.
520 * documentencoding:: Declaring the input encoding.
522 Defining New Texinfo Commands
524 * Defining Macros:: Defining and undefining new commands.
525 * Invoking Macros:: Using a macro, once you've defined it.
526 * Macro Details:: Beyond basic macro usage.
527 * alias:: Command aliases.
528 * definfoenclose:: Customized highlighting.
530 Formatting and Printing Hardcopy
532 * Use TeX:: Use @TeX{} to format for hardcopy.
533 * Format with tex/texindex:: How to format with explicit shell commands.
534 * Format with texi2dvi:: A simpler way to format.
535 * Print with lpr:: How to print.
536 * Within Emacs:: How to format and print from an Emacs shell.
537 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
538 * Compile-Command:: How to print using Emacs's compile command.
539 * Requirements Summary:: @TeX{} formatting requirements summary.
540 * Preparing for TeX:: What to do before you use @TeX{}.
541 * Overfull hboxes:: What are and what to do with overfull hboxes.
542 * smallbook:: How to print small format books and manuals.
543 * A4 Paper:: How to print on A4 or A5 paper.
544 * pagesizes:: How to print with customized page sizes.
545 * Cropmarks and Magnification:: How to print marks to indicate the size
546 of pages and how to print scaled up output.
547 * PDF Output:: Portable Document Format output.
549 Creating and Installing Info Files
551 * Creating an Info File::
552 * Installing an Info File::
554 Creating an Info File
556 * makeinfo advantages:: @code{makeinfo} provides better error checking.
557 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
558 * makeinfo options:: Specify fill-column and other options.
559 * Pointer Validation:: How to check that pointers point somewhere.
560 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
561 * texinfo-format commands:: Two Info formatting commands written
562 in Emacs Lisp are an alternative
564 * Batch Formatting:: How to format for Info in Emacs Batch mode.
565 * Tag and Split Files:: How tagged and split files help Info
567 * makeinfo html:: Generating HTML output.
569 Installing an Info File
571 * Directory File:: The top level menu for all Info files.
572 * New Info File:: Listing a new Info file.
573 * Other Info Directories:: How to specify Info files that are
574 located in other directories.
575 * Installing Dir Entries:: How to specify what menu entry to add
576 to the Info directory.
577 * Invoking install-info:: @code{install-info} options.
581 * Short Sample Texinfo File::
586 * Using Include Files:: How to use the @code{@@include} command.
587 * texinfo-multiple-files-update:: How to create and update nodes and
588 menus when using included files.
589 * Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
590 * Sample Include File:: A sample outer file with included files
591 within it; and a sample included file.
592 * Include Files Evolution:: How use of the @code{@@include} command
593 has changed over time.
597 * Headings Introduced:: Conventions for using page headings.
598 * Heading Format:: Standard page heading formats.
599 * Heading Choice:: How to specify the type of page heading.
600 * Custom Headings:: How to create your own headings and footings.
604 * makeinfo Preferred:: @code{makeinfo} finds errors.
605 * Debugging with Info:: How to catch errors with Info formatting.
606 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
607 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
608 * Using occur:: How to list all lines containing a pattern.
609 * Running Info-Validate:: How to find badly referenced nodes.
611 Finding Badly Referenced Nodes
613 * Using Info-validate:: How to run @code{Info-validate}.
614 * Unsplit:: How to create an unsplit file.
615 * Tagifying:: How to tagify a file.
616 * Splitting:: How to split a file manually.
620 * GNU Free Documentation License:: License for copying this manual.
625 @c Reward readers for getting to the end of the menu :).
626 @c Contributed by Arnold Robbins.
628 Documentation is like sex: when it is good, it is very, very good; and
629 when it is bad, it is better than nothing.
634 @node Copying Conditions
635 @unnumbered Texinfo Copying Conditions
636 @cindex Copying conditions
637 @cindex Conditions for copying Texinfo
639 The programs currently being distributed that relate to Texinfo include
640 @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
641 These programs are @dfn{free}; this means that everyone is free to use
642 them and free to redistribute them on a free basis. The Texinfo-related
643 programs are not in the public domain; they are copyrighted and there
644 are restrictions on their distribution, but these restrictions are
645 designed to permit everything that a good cooperating citizen would want
646 to do. What is not allowed is to try to prevent others from further
647 sharing any version of these programs that they might get from you.
649 Specifically, we want to make sure that you have the right to give away
650 copies of the programs that relate to Texinfo, that you receive source
651 code or else can get it if you want it, that you can change these
652 programs or use pieces of them in new free programs, and that you know
653 you can do these things.
655 To make sure that everyone has such rights, we have to forbid you to
656 deprive anyone else of these rights. For example, if you distribute
657 copies of the Texinfo related programs, you must give the recipients all
658 the rights that you have. You must make sure that they, too, receive or
659 can get the source code. And you must tell them their rights.
661 Also, for our own protection, we must make certain that everyone finds
662 out that there is no warranty for the programs that relate to Texinfo.
663 If these programs are modified by someone else and passed on, we want
664 their recipients to know that what they have is not what we distributed,
665 so that any problems introduced by others will not reflect on our
668 The precise conditions of the licenses for the programs currently being
669 distributed that relate to Texinfo are found in the General Public
670 Licenses that accompany them. This manual specifically is covered by
671 the GNU Free Documentation License (@pxref{GNU Free Documentation
676 @chapter Overview of Texinfo
677 @cindex Overview of Texinfo
678 @cindex Texinfo overview
680 @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
681 like ``speck'', not ``hex''. This odd pronunciation is derived from,
682 but is not the same as, the pronunciation of @TeX{}. In the word
683 @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
684 the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
685 last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
686 were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
687 letters in lower case.} is a documentation system that uses a single
688 source file to produce both online information and printed output. This
689 means that instead of writing two different documents, one for the
690 online information and the other for a printed work, you need write only
691 one document. Therefore, when the work is revised, you need revise only
695 * Reporting Bugs:: Submitting effective bug reports.
696 * Using Texinfo:: Create printed or online output.
697 * Info Files:: What is an Info file?
698 * Printed Books:: Characteristics of a printed book or manual.
699 * Formatting Commands:: @@-commands are used for formatting.
700 * Conventions:: General rules for writing a Texinfo file.
701 * Comments:: Writing comments and ignored text in general.
702 * Minimum:: What a Texinfo file must have.
703 * Six Parts:: Usually, a Texinfo file has six parts.
704 * Short Sample:: A short sample Texinfo file.
705 * History:: Acknowledgements, contributors and genesis.
710 @section Reporting Bugs
712 @cindex Bugs, reporting
713 @cindex Suggestions for Texinfo, making
714 @cindex Reporting bugs
715 We welcome bug reports and suggestions for any aspect of the Texinfo system,
716 programs, documentation, installation, anything. Please email them to
717 @email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo
718 from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
720 @cindex Checklist for bug reports
721 For bug reports, please include enough information for the maintainers
722 to reproduce the problem. Generally speaking, that means:
725 @item the version number of Texinfo and the program(s) or manual(s) involved.
726 @item hardware and operating system names and versions.
727 @item the contents of any input files necessary to reproduce the bug.
728 @item a description of the problem and samples of any erroneous output.
729 @item any unusual options you gave to @command{configure}.
730 @item anything else that you think would be helpful.
733 When in doubt whether something is needed or not, include it. It's
734 better to include too much than to leave out something important.
736 @cindex Patches, contributing
737 Patches are most welcome; if possible, please make them with
738 @samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
739 Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
740 Log,,, emacs, The GNU Emacs Manual}).
742 When sending patches, if possible please do not encode or split them in
743 any way; it's much easier to deal with one plain text message, however
744 large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/,
745 GNU shar} is a convenient way of packaging multiple and/or binary files
750 @section Using Texinfo
752 @cindex Using Texinfo in general
753 @cindex Texinfo, introduction to
754 @cindex Introduction to Texinfo
756 Using Texinfo, you can create a printed document with the normal
757 features of a book, including chapters, sections, cross references, and
758 indices. From the same Texinfo source file, you can create a
759 menu-driven, online Info file with nodes, menus, cross references, and
760 indices. You can also create from that same source file an HTML output
761 file suitable for use with a web browser, or an XML file. @cite{The GNU
762 Emacs Manual} is a good example of a Texinfo file, as is this manual.
764 To make a printed document, you process a Texinfo source file with the
765 @TeX{} typesetting program (but the Texinfo language is very different
766 and much stricter than @TeX{}'s usual language, plain @TeX{}). This
767 creates a DVI file that you can typeset and print as a book or report
771 To output an Info file, process your Texinfo source with the
772 @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
773 You can install the result in your Info tree (@pxref{Installing an Info
776 To output an HTML file, run @code{makeinfo --html} on your Texinfo
777 source. You can (for example) install the result on your web site.
779 @cindex Docbook, converting to Texinfo
780 @cindex Conversion, from Docbook to Texinfo
781 To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
782 To output DocBook (a particular form of XML), run @code{makeinfo
783 --docbook}. If you want to convert from Docbook @emph{to} Texinfo,
784 please see @uref{http://docbook2X.sourceforge.net/}.
786 @cindex Output formats, supporting more
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
795 Info, plain text, HTML, XML, and DocBook.
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 writing a good user tutorial 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 Man pages still have their place, and if you wish to support them, the
834 program @command{help2man} may be useful; it generates a traditional man
835 page from the @samp{--help} output of a program. In fact, this is
836 currently used to generate man pages for the Texinfo programs
837 themselves. It is GNU software written by Brendan O'Dea, available from
838 @uref{ftp://ftp.gnu.org/gnu/help2man/}.
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
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
858 @inforef{Top, info, info}, for more information about using Info.
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
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.}
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 In the United States, documents are most often printed on 8.5 inch by 11
981 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But
982 you 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 A4 or A5 size paper
984 (@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
985 Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
988 By changing the parameters in @file{texinfo.tex}, you can change the
989 size of the printed document. In addition, you can change the style in
990 which the printed document is formatted; for example, you can change the
991 sizes and fonts used, the amount of indentation for each paragraph, the
992 degree to which words are hyphenated, and the like. By changing the
993 specifications, you can make a book look dignified, old and serious, or
994 light-hearted, young and cheery.
996 @TeX{} is freely distributable. It is written in a superset of Pascal
997 called WEB and can be compiled either in Pascal or (by using a
998 conversion program that comes with the @TeX{} distribution) in C.
999 (@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
1000 about @TeX{}.)@refill
1002 @TeX{} is very powerful and has a great many features. Because a
1003 Texinfo file must be able to present information both on a
1004 character-only terminal in Info form and in a typeset book, the
1005 formatting commands that Texinfo supports are necessarily limited.
1007 To get a copy of @TeX{}, see
1008 @ref{Obtaining TeX, , How to Obtain @TeX{}}.
1011 @node Formatting Commands
1012 @section @@-commands
1014 @cindex Formatting commands
1016 In a Texinfo file, the commands that tell @TeX{} how to typeset the
1017 printed manual and tell @code{makeinfo} and
1018 @code{texinfo-format-buffer} how to create an Info file are preceded
1019 by @samp{@@}; they are called @dfn{@@-commands}. For example,
1020 @code{@@node} is the command to indicate a node and @code{@@chapter}
1021 is the command to indicate the start of a chapter.@refill
1024 @strong{Please note:} All the @@-commands, with the exception of the
1025 @code{@@TeX@{@}} command, must be written entirely in lower case.
1028 The Texinfo @@-commands are a strictly limited set of constructs. The
1029 strict limits make it possible for Texinfo files to be understood both
1030 by @TeX{} and by the code that converts them into Info files. You can
1031 display Info files on any terminal that displays alphabetic and
1032 numeric characters. Similarly, you can print the output generated by
1033 @TeX{} on a wide variety of printers.@refill
1035 Depending on what they do or what arguments@footnote{The word
1036 @dfn{argument} comes from the way it is used in mathematics and does not
1037 refer to a dispute between two people; it refers to the information
1038 presented to the command. According to the @cite{Oxford English
1039 Dictionary}, the word derives from the Latin for @dfn{to make clear,
1040 prove}; thus it came to mean `the evidence offered as proof', which is
1041 to say, `the information offered', which led to its mathematical
1042 meaning. In its other thread of derivation, the word came to mean `to
1043 assert in a manner against which others may make counter assertions',
1044 which led to the meaning of `argument' as a dispute.} they take, you
1045 need to write @@-commands on lines of their own or as part of
1050 Write a command such as @code{@@noindent} at the beginning of a line as
1051 the only text on the line. (@code{@@noindent} prevents the beginning of
1052 the next line from being indented as the beginning of a
1056 Write a command such as @code{@@chapter} at the beginning of a line
1057 followed by the command's arguments, in this case the chapter title, on
1058 the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
1061 Write a command such as @code{@@dots@{@}} wherever you wish but usually
1062 within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
1065 Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
1066 wish (but usually within a sentence) with its argument,
1067 @var{sample-code} in this example, between the braces. (@code{@@code}
1068 marks text as being code.)@refill
1071 Write a command such as @code{@@example} on a line of its own; write the
1072 body-text on following lines; and write the matching @code{@@end}
1073 command, @code{@@end example} in this case, at the on a line of its own
1074 after the body-text. (@code{@@example} @dots{} @code{@@end example}
1075 indents and typesets body-text as an example.) It's usually ok to
1076 indent environment commands like this, but in complicated and
1077 hard-to-define circumstances the extra spaces cause extra space to
1078 appear in the output, so beware.
1082 @cindex Braces, when to use
1083 As a general rule, a command requires braces if it mingles among other
1084 text; but it does not need braces if it starts a line of its own. The
1085 non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1086 they do not need braces.@refill
1088 As you gain experience with Texinfo, you will rapidly learn how to
1089 write the different commands: the different ways to write commands
1090 make it easier to write and read Texinfo files than if all commands
1091 followed exactly the same syntax. (For details about @@-command
1092 syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
1096 @section General Syntactic Conventions
1097 @cindex General syntactic conventions
1098 @cindex Syntactic conventions
1099 @cindex Conventions, syntactic
1101 This section describes the general conventions used in all Texinfo documents.
1105 All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
1106 @samp{@}} can appear in a Texinfo file and stand for themselves.
1107 @samp{@@} is the escape character which introduces commands, while
1108 @samp{@{} and @samp{@}} are used to surround arguments to certain
1109 commands. To put one of these special characters into the document, put
1110 an @samp{@@} character in front of it, like this: @samp{@@@@},
1111 @samp{@@@{}, and @samp{@@@}}.
1114 It is customary in @TeX{} to use doubled single-quote characters to
1115 begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}. This
1116 convention should be followed in Texinfo files. @TeX{} converts
1117 two single quotes to left- and right-hand doubled
1119 @c this comes out as "like this" in Info, of course, which is just confusing.
1123 and Info converts doubled single-quote characters to @sc{ascii}
1124 double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
1127 Use three hyphens in a row, @samp{---}, for a dash---like this. In
1128 @TeX{}, a single or double hyphen produces a printed dash that is
1129 shorter than the usual typeset dash. Info reduces three hyphens to two
1130 for display on the screen.
1133 To prevent a paragraph from being indented in the printed manual, put
1134 the command @code{@@noindent} on a line by itself before the
1138 If you mark off a region of the Texinfo file with the @code{@@iftex}
1139 and @w{@code{@@end iftex}} commands, that region will appear only in
1140 the printed copy; in that region, you can use certain commands
1141 borrowed from plain @TeX{} that you cannot use in Info. Conversely,
1142 text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
1143 appear in all output formats @emph{except} @TeX{}.
1145 Each of the other output formats (@code{html}, @code{info},
1146 @code{plaintext}) have an analogous pair of commands. @xref{Conditionals}.
1149 @cindex Tabs; don't use!
1151 @strong{Caution:} Do not use tab characters in a Texinfo file (except in
1152 verbatim modes)! @TeX{} uses variable-width fonts, which means that it
1153 is impractical at best to define a tab to work in all circumstances.
1154 Consequently, @TeX{} treats tabs like single spaces, and that is not
1155 what they look like. Furthermore, @code{makeinfo} does nothing special
1156 with tabs, and thus a tab character in your input file may appear
1157 differently in the output, for example, in indented text.
1160 To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
1161 spaces when you press the @key{TAB} key.
1164 Also, you can run @code{untabify} in Emacs to convert tabs in a region
1174 @findex c @r{(comment)}
1176 You can write comments in a Texinfo file that will not appear in
1177 either the Info file or the printed manual by using the
1178 @code{@@comment} command (which may be abbreviated to @code{@@c}).
1179 Such comments are for the person who revises the Texinfo file. All the
1180 text on a line that follows either @code{@@comment} or @code{@@c} is a
1181 comment; the rest of the line does not appear in either the Info file
1182 or the printed manual.
1184 Often, you can write the @code{@@comment} or @code{@@c} in the middle of
1185 a line, and only the text that follows after the @code{@@comment} or
1186 @code{@@c} command does not appear; but some commands, such as
1187 @code{@@settitle} and @code{@@setfilename}, work on a whole line. You
1188 cannot use @code{@@comment} or @code{@@c} in a line beginning with such
1191 @cindex Ignored text
1192 @cindex Unprocessed text
1194 You can write long stretches of text that will not appear in either
1195 the Info file or the printed manual by using the @code{@@ignore} and
1196 @code{@@end ignore} commands. Write each of these commands on a line
1197 of its own, starting each command at the beginning of the line. Text
1198 between these two commands does not appear in the processed output.
1199 You can use @code{@@ignore} and @code{@@end ignore} for writing
1202 Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1203 @code{@@ifclear} conditions is ignored in the sense that it will not
1204 contribute to the formatted output. However, @TeX{} and makeinfo must
1205 still parse the ignored text, in order to understand when to @emph{stop}
1206 ignoring text from the source file; that means that you may still get
1207 error messages if you have invalid Texinfo commands within ignored text.
1211 @section What a Texinfo File Must Have
1212 @cindex Minimal Texinfo file (requirements)
1213 @cindex Must have in Texinfo file
1214 @cindex Required in Texinfo file
1215 @cindex Texinfo file minimum
1217 By convention, the namea of a Texinfo file ends with (in order of
1218 preference) one of the extensions @file{.texinfo}, @file{.texi},
1219 @file{.txi}, or @file{.tex}. The longer extensions are preferred since
1220 they describe more clearly to a human reader the nature of the file.
1221 The shorter extensions are for operating systems that cannot handle long
1224 In order to be made into a printed manual and an Info file, a Texinfo
1225 file @strong{must} begin with lines like this:
1230 @@setfilename @var{info-file-name}
1231 @@settitle @var{name-of-manual}
1236 The contents of the file follow this beginning, and then you
1237 @strong{must} end a Texinfo file with a line like this:
1243 @findex \input @r{(raw @TeX{} startup)}
1245 Here's an explanation:
1249 The @samp{\input texinfo} line tells @TeX{} to use the
1250 @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1251 @@-commands into @TeX{} typesetting commands. (Note the use of the
1252 backslash, @samp{\}; this is correct for @TeX{}.)
1255 The @code{@@setfilename} line provides a name for the Info file and
1256 tells @TeX{} to open auxiliary files. @strong{All text before
1257 @code{@@setfilename} is ignored!}
1260 The @code{@@settitle} line specifies a title for the page headers (or
1261 footers) of the printed manual, and the default document description for
1262 the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
1263 is optional---if you don't mind your document being titled `Untitled'.
1266 The @code{@@bye} line at the end of the file on a line of its own tells
1267 the formatters that the file is ended and to stop formatting.
1271 Typically, you will not use quite such a spare format, but will include
1272 mode setting and start-of-header and end-of-header lines at the
1273 beginning of a Texinfo file, like this:
1277 \input texinfo @@c -*-texinfo-*-
1278 @@c %**start of header
1279 @@setfilename @var{info-file-name}
1280 @@settitle @var{name-of-manual}
1281 @@c %**end of header
1286 In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1287 Texinfo mode when you edit the file.
1289 The @code{@@c} lines which surround the @code{@@setfilename} and
1290 @code{@@settitle} lines are optional, but you need them in order to
1291 run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
1293 Furthermore, you will usually provide a Texinfo file with a title page,
1294 indices, and the like, all of which are explained in this manual. But
1295 the minimum, which can be useful for short documents, is just the three
1296 lines at the beginning and the one line at the end.
1300 @section Six Parts of a Texinfo File
1302 Generally, a Texinfo file contains more than the minimal beginning and
1303 end described in the previous section---it usually contains the six
1304 parts listed below. These are described fully in the following sections.
1308 The @dfn{Header} names the file, tells @TeX{} which definitions file to
1309 use, and other such housekeeping tasks.
1311 @item 2. Summary and Copyright
1312 The @dfn{Summary and Copyright} segment describes the document and
1313 contains the copyright notice and copying permissions. This is done
1314 with the @code{@@copying} command.
1316 @item 3. Title and Copyright
1317 The @dfn{Title and Copyright} segment contains the title and copyright
1318 pages for the printed manual. The segment must be enclosed between
1319 @code{@@titlepage} and @code{@@end titlepage} commands. The title and
1320 copyright page appear only in the printed manual.
1322 @item 4. `Top' Node and Master Menu
1323 The `Top' node starts off the online output; it does not appear in the
1324 printed manual. We recommend including the copying permissions here as
1325 well as the segments above. And it contains at least a top-level menu
1326 listing the chapters, and possibly a @dfn{Master Menu} listing all the
1327 nodes in the entire document.
1330 The @dfn{Body} of the document is typically structured like a
1331 traditional book or encyclopedia, but it may be free form.
1334 The @dfn{End} segment contains commands for printing indices and
1335 generating the table of contents, and the @code{@@bye} command on a line
1341 @section A Short Sample Texinfo File
1342 @cindex Sample Texinfo file, with comments
1344 Here is a very short but complete Texinfo file, in the six conventional
1345 parts enumerated in the previous section, so you can see how Texinfo
1346 source appears in practice. The first three parts of the file, from
1347 @samp{\input texinfo} through to @samp{@@end titlepage}, look more
1348 intimidating than they are: most of the material is standard
1349 boilerplate; when writing a manual, you simply change the names as
1352 @xref{Beginning a File}, for full documentation on the commands listed
1353 here. @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
1355 In the following, the sample text is @emph{indented}; comments on it are
1356 not. The complete file, without interspersed comments, is shown in
1357 @ref{Short Sample Texinfo File}.
1359 @subheading Part 1: Header
1362 The header does not appear in either the Info file or the
1363 printed output. It sets various parameters, including the
1364 name of the Info file and the title used in the header.
1368 \input texinfo @@c -*-texinfo-*-
1369 @@c %**start of header
1370 @@setfilename sample.info
1371 @@settitle Sample Manual 1.0
1372 @@c %**end of header
1376 @subheading Part 2: Summary Description and Copyright
1379 A real manual includes more text here, according to the license under
1380 which it is distributed. @xref{GNU Sample Texts}.
1385 This is a short example of a complete Texinfo file, version 1.0.
1387 Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
1392 @subheading Part 3: Titlepage, Contents, Copyright
1395 The titlepage segment does not appear in the online output, only in the
1396 printed manual. We use the @code{@@insertcopying} command to
1397 include the permission text from the previous section, instead of
1398 writing it out again; it is output on the back of the title page. The
1399 @code{@@contents} command generates a table of contents.
1404 @@title Sample Title
1408 @@c The following two commands start the copyright page.
1410 @@vskip 0pt plus 1filll
1415 @@c Output the table of contents at the beginning.
1419 @subheading Part 4: `Top' Node and Master Menu
1422 The `Top' node contains the master menu for the Info file. Since a
1423 printed manual uses a table of contents rather than a menu, the master
1424 menu appears only in online output. We also include the copying text
1425 again for the benefit of online readers. And since the copying text
1426 begins with a brief description of the manual, no other text is needed.
1441 * First Chapter:: The first chapter is the
1442 only chapter in this sample.
1443 * Index:: Complete index.
1449 @subheading Part 5: The Body of the Document
1452 The body segment contains all the text of the document, but not the
1453 indices or table of contents. This example illustrates a node and a
1454 chapter containing an enumerated list.
1458 @@node First Chapter
1459 @@chapter First Chapter
1461 @@cindex chapter, first
1465 This is the first chapter.
1466 @@cindex index entry, another
1470 Here is a numbered list.
1474 This is the first item.
1477 This is the second item.
1483 @subheading Part 6: The End of the Document
1486 The end segment contains commands for generating an index in a node and
1487 unnumbered chapter of its own, and the @code{@@bye} command that marks
1488 the end of the document.
1504 @subheading Some Results
1506 Here is what the contents of the first chapter of the sample look like:
1511 This is the first chapter.
1513 Here is a numbered list.
1517 This is the first item.
1520 This is the second item.
1528 @cindex Stallman, Richard M.
1529 @cindex Chassell, Robert J.
1532 Richard M.@: Stallman invented the Texinfo format, wrote the initial
1533 processors, and created Edition 1.0 of this manual. @w{Robert J.@:}
1534 Chassell greatly revised and extended the manual, starting with Edition
1535 1.1. Brian Fox was responsible for the standalone Texinfo distribution
1536 until version 3.8, and wrote the standalone @command{makeinfo} and
1537 @command{info} programs. Karl Berry has continued maintenance since
1538 Texinfo 3.8 (manual edition 2.22).
1540 @cindex Pinard, Fran@,{c}ois
1541 @cindex Zuhn, David D.
1542 @cindex Weisshaus, Melissa
1543 @cindex Zaretskii, Eli
1544 @cindex Schwab, Andreas
1545 @cindex Weinberg, Zack
1546 Our thanks go out to all who helped improve this work, particularly the
1547 indefatigable Eli Zaretskii and Andreas Schwab, who have provided
1548 patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
1549 tirelessly recorded and reported mistakes and obscurities. Zack
1550 Weinberg did the impossible by implementing the macro syntax in
1551 @file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her
1552 frequent reviews of nearly similar editions. Dozens of others have
1553 contributed patches and suggestions, they are gratefully acknowledged in
1554 the @file{ChangeLog} file. Our mistakes are our own.
1558 @cindex History of Texinfo
1559 @cindex Texinfo history
1560 A bit of history: in the 1970's at CMU, Brian Reid developed a program
1561 and format named Scribe to mark up documents for printing. It used the
1562 @code{@@} character to introduce commands, as Texinfo does. Much more
1563 consequentially, it strived to describe document contents rather than
1564 formatting, an idea wholeheartedly adopted by Texinfo.
1568 Meanwhile, people at MIT developed another, not too dissimilar format
1569 called Bolio. This then was converted to using @TeX{} as its typesetting
1570 language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been
1571 0.02 on October 31, 1984.
1573 Bo@TeX{} could only be used as a markup language for documents to be
1574 printed, not for online documents. Richard Stallman (RMS) worked on
1575 both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1576 called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
1577 mark up language for text that is intended to be read both online and
1578 as printed hard copy.
1582 @chapter Using Texinfo Mode
1583 @cindex Texinfo mode
1584 @cindex Mode, using Texinfo
1588 You may edit a Texinfo file with any text editor you choose. A Texinfo
1589 file is no different from any other @sc{ascii} file. However, GNU Emacs
1590 comes with a special mode, called Texinfo mode, that provides Emacs
1591 commands and tools to help ease your work.
1593 This chapter describes features of GNU Emacs' Texinfo mode but not any
1594 features of the Texinfo formatting language. So if you are reading this
1595 manual straight through from the beginning, you may want to skim through
1596 this chapter briefly and come back to it after reading succeeding
1597 chapters which describe the Texinfo formatting language in detail.
1600 * Texinfo Mode Overview:: How Texinfo mode can help you.
1601 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1602 purpose editing features.
1603 * Inserting:: How to insert frequently used @@-commands.
1604 * Showing the Structure:: How to show the structure of a file.
1605 * Updating Nodes and Menus:: How to update or create new nodes and menus.
1606 * Info Formatting:: How to format for Info.
1607 * Printing:: How to format and print part or all of a file.
1608 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
1611 @node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
1613 @heading Texinfo Mode Overview
1616 Texinfo mode provides special features for working with Texinfo
1622 Insert frequently used @@-commands. @refill
1625 Automatically create @code{@@node} lines.
1628 Show the structure of a Texinfo source file.@refill
1631 Automatically create or update the `Next',
1632 `Previous', and `Up' pointers of a node.
1635 Automatically create or update menus.@refill
1638 Automatically create a master menu.@refill
1641 Format a part or all of a file for Info.@refill
1644 Typeset and print part or all of a file.@refill
1647 Perhaps the two most helpful features are those for inserting frequently
1648 used @@-commands and for creating node pointers and menus.@refill
1650 @node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
1651 @section The Usual GNU Emacs Editing Commands
1653 In most cases, the usual Text mode commands work the same in Texinfo
1654 mode as they do in Text mode. Texinfo mode adds new editing commands
1655 and tools to GNU Emacs' general purpose editing features. The major
1656 difference concerns filling. In Texinfo mode, the paragraph
1657 separation variable and syntax table are redefined so that Texinfo
1658 commands that should be on lines of their own are not inadvertently
1659 included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
1660 command will refill a paragraph but not mix an indexing command on a
1661 line adjacent to it into the paragraph.@refill
1663 In addition, Texinfo mode sets the @code{page-delimiter} variable to
1664 the value of @code{texinfo-chapter-level-regexp}; by default, this is
1665 a regular expression matching the commands for chapters and their
1666 equivalents, such as appendices. With this value for the page
1667 delimiter, you can jump from chapter title to chapter title with the
1668 @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1669 (@code{backward-page}) commands and narrow to a chapter with the
1670 @kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
1671 The GNU Emacs Manual}, for details about the page commands.)@refill
1673 You may name a Texinfo file however you wish, but the convention is to
1674 end a Texinfo file name with one of the extensions
1675 @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
1676 extension is preferred, since it is explicit, but a shorter extension
1677 may be necessary for operating systems that limit the length of file
1678 names. GNU Emacs automatically enters Texinfo mode when you visit a
1679 file with a @file{.texinfo}, @file{.texi} or @file{.txi}
1680 extension. Also, Emacs switches to Texinfo mode
1682 file that has @samp{-*-texinfo-*-} in its first line. If ever you are
1683 in another mode and wish to switch to Texinfo mode, type @code{M-x
1684 texinfo-mode}.@refill
1686 Like all other Emacs features, you can customize or enhance Texinfo
1687 mode as you wish. In particular, the keybindings are very easy to
1688 change. The keybindings described here are the default or standard
1691 @node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
1692 @comment node-name, next, previous, up
1693 @section Inserting Frequently Used Commands
1694 @cindex Inserting frequently used commands
1695 @cindex Frequently used commands, inserting
1696 @cindex Commands, inserting them
1698 Texinfo mode provides commands to insert various frequently used
1699 @@-commands into the buffer. You can use these commands to save
1702 The insert commands are invoked by typing @kbd{C-c} twice and then the
1703 first letter of the @@-command:@refill
1707 @itemx M-x texinfo-insert-@@code
1708 @findex texinfo-insert-@@code
1709 Insert @code{@@code@{@}} and put the
1710 cursor between the braces.@refill
1713 @itemx M-x texinfo-insert-@@dfn
1714 @findex texinfo-insert-@@dfn
1715 Insert @code{@@dfn@{@}} and put the
1716 cursor between the braces.@refill
1719 @itemx M-x texinfo-insert-@@end
1720 @findex texinfo-insert-@@end
1721 Insert @code{@@end} and attempt to insert the correct following word,
1722 such as @samp{example} or @samp{table}. (This command does not handle
1723 nested lists correctly, but inserts the word appropriate to the
1724 immediately preceding list.)@refill
1727 @itemx M-x texinfo-insert-@@item
1728 @findex texinfo-insert-@@item
1729 Insert @code{@@item} and put the
1730 cursor at the beginning of the next line.@refill
1733 @itemx M-x texinfo-insert-@@kbd
1734 @findex texinfo-insert-@@kbd
1735 Insert @code{@@kbd@{@}} and put the
1736 cursor between the braces.@refill
1739 @itemx M-x texinfo-insert-@@node
1740 @findex texinfo-insert-@@node
1741 Insert @code{@@node} and a comment line
1742 listing the sequence for the `Next',
1743 `Previous', and `Up' nodes.
1744 Leave point after the @code{@@node}.@refill
1747 @itemx M-x texinfo-insert-@@noindent
1748 @findex texinfo-insert-@@noindent
1749 Insert @code{@@noindent} and put the
1750 cursor at the beginning of the next line.@refill
1753 @itemx M-x texinfo-insert-@@samp
1754 @findex texinfo-insert-@@samp
1755 Insert @code{@@samp@{@}} and put the
1756 cursor between the braces.@refill
1759 @itemx M-x texinfo-insert-@@table
1760 @findex texinfo-insert-@@table
1761 Insert @code{@@table} followed by a @key{SPC}
1762 and leave the cursor after the @key{SPC}.@refill
1765 @itemx M-x texinfo-insert-@@var
1766 @findex texinfo-insert-@@var
1767 Insert @code{@@var@{@}} and put the
1768 cursor between the braces.@refill
1771 @itemx M-x texinfo-insert-@@example
1772 @findex texinfo-insert-@@example
1773 Insert @code{@@example} and put the
1774 cursor at the beginning of the next line.@refill
1776 @c M-@{ was the binding for texinfo-insert-braces;
1777 @c in Emacs 19, backward-paragraph will take this binding.
1779 @itemx M-x texinfo-insert-braces
1780 @findex texinfo-insert-braces
1781 Insert @code{@{@}} and put the cursor between the braces.@refill
1787 Move from between a pair of braces forward past the closing brace.
1788 Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
1789 is, however, more mnemonic; hence the two keybindings. (Also, you can
1790 move out from between braces by typing @kbd{C-f}.)@refill
1793 To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1794 @emph{existing} word, position the cursor in front of the word and type
1795 @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
1796 The value of the prefix argument tells Emacs how many words following
1797 point to include between braces---@samp{1} for one word, @samp{2} for
1798 two words, and so on. Use a negative argument to enclose the previous
1799 word or words. If you do not specify a prefix argument, Emacs inserts
1800 the @@-command string and positions the cursor between the braces. This
1801 feature works only for those @@-commands that operate on a word or words
1802 within one line, such as @code{@@kbd} and @code{@@var}.@refill
1804 This set of insert commands was created after analyzing the frequency
1805 with which different @@-commands are used in the @cite{GNU Emacs
1806 Manual} and the @cite{GDB Manual}. If you wish to add your own insert
1807 commands, you can bind a keyboard macro to a key, use abbreviations,
1808 or extend the code in @file{texinfo.el}.@refill
1810 @findex texinfo-start-menu-description
1811 @cindex Menu description, start
1812 @cindex Description for menu, start
1813 @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1814 command that works differently from the other insert commands. It
1815 inserts a node's section or chapter title in the space for the
1816 description in a menu entry line. (A menu entry has three parts, the
1817 entry name, the node name, and the description. Only the node name is
1818 required, but a description helps explain what the node is about.
1819 @xref{Menu Parts, , The Parts of a Menu}.)@refill
1821 To use @code{texinfo-start-menu-description}, position point in a menu
1822 entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
1823 the title that goes with the node name, and inserts the title as a
1824 description; it positions point at beginning of the inserted text so you
1825 can edit it. The function does not insert the title if the menu entry
1826 line already contains a description.@refill
1828 This command is only an aid to writing descriptions; it does not do the
1829 whole job. You must edit the inserted text since a title tends to use
1830 the same words as a node name but a useful description uses different
1833 @node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
1834 @comment node-name, next, previous, up
1835 @section Showing the Section Structure of a File
1836 @cindex Showing the section structure of a file
1837 @cindex Section structure of a file, showing it
1838 @cindex Structure of a file, showing it
1839 @cindex Outline of file structure, showing it
1840 @cindex Contents-like outline of file structure
1841 @cindex File section structure, showing it
1842 @cindex Texinfo file section structure, showing it
1844 You can show the section structure of a Texinfo file by using the
1845 @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
1846 shows the section structure of a Texinfo file by listing the lines
1847 that begin with the @@-commands for @code{@@chapter},
1848 @code{@@section}, and the like. It constructs what amounts
1849 to a table of contents. These lines are displayed in another buffer
1850 called the @samp{*Occur*} buffer. In that buffer, you can position
1851 the cursor over one of the lines and use the @kbd{C-c C-c} command
1852 (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1853 in the Texinfo file.@refill
1857 @itemx M-x texinfo-show-structure
1858 @findex texinfo-show-structure
1859 Show the @code{@@chapter}, @code{@@section}, and such lines of a
1860 Texinfo file.@refill
1863 @itemx M-x occur-mode-goto-occurrence
1864 @findex occur-mode-goto-occurrence
1865 Go to the line in the Texinfo file corresponding to the line under the
1866 cursor in the @file{*Occur*} buffer.@refill
1869 If you call @code{texinfo-show-structure} with a prefix argument by
1870 typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1871 @@-commands for @code{@@chapter}, @code{@@section}, and the like, but
1872 also the @code{@@node} lines. You can use @code{texinfo-show-structure}
1873 with a prefix argument to check whether the `Next', `Previous', and `Up'
1874 pointers of an @code{@@node} line are correct.
1876 Often, when you are working on a manual, you will be interested only
1877 in the structure of the current chapter. In this case, you can mark
1878 off the region of the buffer that you are interested in by using the
1879 @kbd{C-x n n} (@code{narrow-to-region}) command and
1880 @code{texinfo-show-structure} will work on only that region. To see
1881 the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
1882 (@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
1883 information about the narrowing commands.)@refill
1885 @vindex page-delimiter
1886 @cindex Page delimiter in Texinfo mode
1887 In addition to providing the @code{texinfo-show-structure} command,
1888 Texinfo mode sets the value of the page delimiter variable to match
1889 the chapter-level @@-commands. This enables you to use the @kbd{C-x
1890 ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
1891 commands to move forward and backward by chapter, and to use the
1892 @kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
1893 @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
1894 about the page commands.@refill
1896 @node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
1897 @comment node-name, next, previous, up
1898 @section Updating Nodes and Menus
1899 @cindex Updating nodes and menus
1900 @cindex Create nodes, menus automatically
1901 @cindex Insert nodes, menus automatically
1902 @cindex Automatically insert nodes, menus
1904 Texinfo mode provides commands for automatically creating or updating
1905 menus and node pointers. The commands are called ``update'' commands
1906 because their most frequent use is for updating a Texinfo file after you
1907 have worked on it; but you can use them to insert the `Next',
1908 `Previous', and `Up' pointers into an @code{@@node} line that has none
1909 and to create menus in a file that has none.
1911 If you do not use the updating commands, you need to write menus and
1912 node pointers by hand, which is a tedious task.@refill
1915 * Updating Commands:: Five major updating commands.
1916 * Updating Requirements:: How to structure a Texinfo file for
1917 using the updating command.
1918 * Other Updating Commands:: How to indent descriptions, insert
1919 missing nodes lines, and update
1923 @node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
1925 @subheading The Updating Commands
1928 You can use the updating commands to:@refill
1932 insert or update the `Next', `Previous', and `Up' pointers of a
1936 insert or update the menu for a section, and@refill
1939 create a master menu for a Texinfo source file.@refill
1942 You can also use the commands to update all the nodes and menus in a
1943 region or in a whole Texinfo file.@refill
1945 The updating commands work only with conventional Texinfo files, which
1946 are structured hierarchically like books. In such files, a structuring
1947 command line must follow closely after each @code{@@node} line, except
1948 for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
1949 a line beginning with @code{@@chapter}, @code{@@section}, or other
1952 You can write the structuring command line on the line that follows
1953 immediately after an @code{@@node} line or else on the line that
1954 follows after a single @code{@@comment} line or a single
1955 @code{@@ifinfo} line. You cannot interpose more than one line between
1956 the @code{@@node} line and the structuring command line; and you may
1957 interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
1959 Commands which work on a whole buffer require that the `Top' node be
1960 followed by a node with an @code{@@chapter} or equivalent-level command.
1961 The menu updating commands will not create a main or master menu for a
1962 Texinfo file that has only @code{@@chapter}-level nodes! The menu
1963 updating commands only create menus @emph{within} nodes for lower level
1964 nodes. To create a menu of chapters, you must provide a `Top'
1967 The menu updating commands remove menu entries that refer to other Info
1968 files since they do not refer to nodes within the current buffer. This
1969 is a deficiency. Rather than use menu entries, you can use cross
1970 references to refer to other Info files. None of the updating commands
1971 affect cross references.@refill
1973 Texinfo mode has five updating commands that are used most often: two
1974 are for updating the node pointers or menu of a single node (or a
1975 region); two are for updating every node pointer and menu in a file;
1976 and one, the @code{texinfo-master-menu} command, is for creating a
1977 master menu for a complete file, and optionally, for updating every
1978 node and menu in the whole Texinfo file.@refill
1980 The @code{texinfo-master-menu} command is the primary command:@refill
1984 @itemx M-x texinfo-master-menu
1985 @findex texinfo-master-menu
1986 Create or update a master menu that includes all the other menus
1987 (incorporating the descriptions from pre-existing menus, if
1990 With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
1991 update all the nodes and all the regular menus in the buffer before
1992 constructing the master menu. (@xref{The Top Node, , The Top Node and
1993 Master Menu}, for more about a master menu.)@refill
1995 For @code{texinfo-master-menu} to work, the Texinfo file must have a
1996 `Top' node and at least one subsequent node.@refill
1998 After extensively editing a Texinfo file, you can type the following:
2001 C-u M-x texinfo-master-menu
2007 This updates all the nodes and menus completely and all at once.@refill
2010 The other major updating commands do smaller jobs and are designed for
2011 the person who updates nodes and menus as he or she writes a Texinfo
2015 The commands are:@refill
2019 @itemx M-x texinfo-update-node
2020 @findex texinfo-update-node
2021 Insert the `Next', `Previous', and `Up' pointers for the node that point is
2022 within (i.e., for the @code{@@node} line preceding point). If the
2023 @code{@@node} line has pre-existing `Next', `Previous', or `Up'
2024 pointers in it, the old pointers are removed and new ones inserted.
2025 With an argument (prefix argument, @kbd{C-u}, if interactive), this command
2026 updates all @code{@@node} lines in the region (which is the text
2027 between point and mark).@refill
2030 @itemx M-x texinfo-make-menu
2031 @findex texinfo-make-menu
2032 Create or update the menu in the node that point is within.
2033 With an argument (@kbd{C-u} as prefix argument, if
2034 interactive), the command makes or updates menus for the
2035 nodes which are either within or a part of the
2038 Whenever @code{texinfo-make-menu} updates an existing menu, the
2039 descriptions from that menu are incorporated into the new menu. This
2040 is done by copying descriptions from the existing menu to the entries
2041 in the new menu that have the same node names. If the node names are
2042 different, the descriptions are not copied to the new menu.@refill
2045 @itemx M-x texinfo-every-node-update
2046 @findex texinfo-every-node-update
2047 Insert or update the `Next', `Previous', and `Up' pointers for every
2048 node in the buffer.@refill
2051 @itemx M-x texinfo-all-menus-update
2052 @findex texinfo-all-menus-update
2053 Create or update all the menus in the buffer. With an argument
2054 (@kbd{C-u} as prefix argument, if interactive), first insert
2055 or update all the node
2056 pointers before working on the menus.@refill
2058 If a master menu exists, the @code{texinfo-all-menus-update} command
2059 updates it; but the command does not create a new master menu if none
2060 already exists. (Use the @code{texinfo-master-menu} command for
2063 When working on a document that does not merit a master menu, you can
2069 C-u M-x texinfo-all-menus-update
2073 This updates all the nodes and menus.@refill
2076 The @code{texinfo-column-for-description} variable specifies the
2077 column to which menu descriptions are indented. By default, the value
2078 is 32 although it is often useful to reduce it to as low as 24. You
2079 can set the variable with the @kbd{M-x edit-options} command
2080 (@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
2081 Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
2082 , Examining and Setting Variables, emacs, The GNU Emacs
2085 Also, the @code{texinfo-indent-menu-description} command may be used to
2086 indent existing menu descriptions to a specified column. Finally, if
2087 you wish, you can use the @code{texinfo-insert-node-lines} command to
2088 insert missing @code{@@node} lines into a file. (@xref{Other Updating
2089 Commands}, for more information.)@refill
2091 @node Updating Requirements
2092 @subsection Updating Requirements
2093 @cindex Updating requirements
2094 @cindex Requirements for updating commands
2096 To use the updating commands, you must organize the Texinfo file
2097 hierarchically with chapters, sections, subsections, and the like.
2098 When you construct the hierarchy of the manual, do not `jump down'
2099 more than one level at a time: you can follow the `Top' node with a
2100 chapter, but not with a section; you can follow a chapter with a
2101 section, but not with a subsection. However, you may `jump up' any
2102 number of levels at one time---for example, from a subsection to a
2105 Each @code{@@node} line, with the exception of the line for the `Top'
2106 node, must be followed by a line with a structuring command such as
2107 @code{@@chapter}, @code{@@section}, or
2108 @code{@@unnumberedsubsec}.@refill
2110 Each @code{@@node} line/structuring-command line combination
2111 must look either like this:
2115 @@node Comments, Minimum, Conventions, Overview
2116 @@comment node-name, next, previous, up
2121 or like this (without the @code{@@comment} line):
2125 @@node Comments, Minimum, Conventions, Overview
2130 or like this (without the explicit node pointers):
2140 In this example, `Comments' is the name of both the node and the
2141 section. The next node is called `Minimum' and the previous node is
2142 called `Conventions'. The `Comments' section is within the `Overview'
2143 node, which is specified by the `Up' pointer. (Instead of an
2144 @code{@@comment} line, you may also write an @code{@@ifinfo} line.)
2146 If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2147 and be the first node in the file.
2149 The menu updating commands create a menu of sections within a chapter,
2150 a menu of subsections within a section, and so on. This means that
2151 you must have a `Top' node if you want a menu of chapters.@refill
2153 Incidentally, the @code{makeinfo} command will create an Info file for a
2154 hierarchically organized Texinfo file that lacks `Next', `Previous' and
2155 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
2156 formatted with @code{makeinfo}, you have no need for the update node
2157 commands. (@xref{Creating an Info File}, for more information about
2158 @code{makeinfo}.) However, both @code{makeinfo} and the
2159 @code{texinfo-format-@dots{}} commands require that you insert menus in
2163 @node Other Updating Commands
2164 @subsection Other Updating Commands
2166 In addition to the five major updating commands, Texinfo mode
2167 possesses several less frequently used updating commands:@refill
2170 @item M-x texinfo-insert-node-lines
2171 @findex texinfo-insert-node-lines
2172 Insert @code{@@node} lines before the @code{@@chapter},
2173 @code{@@section}, and other sectioning commands wherever they are
2174 missing throughout a region in a Texinfo file.@refill
2176 With an argument (@kbd{C-u} as prefix argument, if interactive), the
2177 @code{texinfo-insert-node-lines} command not only inserts
2178 @code{@@node} lines but also inserts the chapter or section titles as
2179 the names of the corresponding nodes. In addition, it inserts the
2180 titles as node names in pre-existing @code{@@node} lines that lack
2181 names. Since node names should be more concise than section or
2182 chapter titles, you must manually edit node names so inserted.@refill
2184 For example, the following marks a whole buffer as a region and inserts
2185 @code{@@node} lines and titles throughout:@refill
2188 C-x h C-u M-x texinfo-insert-node-lines
2191 This command inserts titles as node names in @code{@@node} lines; the
2192 @code{texinfo-start-menu-description} command (@pxref{Inserting,
2193 Inserting Frequently Used Commands}) inserts titles as descriptions in
2194 menu entries, a different action. However, in both cases, you need to
2195 edit the inserted text.
2197 @item M-x texinfo-multiple-files-update
2198 @findex texinfo-multiple-files-update @r{(in brief)}
2199 Update nodes and menus in a document built from several separate files.
2200 With @kbd{C-u} as a prefix argument, create and insert a master menu in
2201 the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
2202 update all the menus and all the `Next', `Previous', and `Up' pointers
2203 of all the included files before creating and inserting a master menu in
2204 the outer file. The @code{texinfo-multiple-files-update} command is
2205 described in the appendix on @code{@@include} files.
2207 @xref{texinfo-multiple-files-update}.@refill
2210 @xref{texinfo-multiple-files-update, ,
2211 @code{texinfo-multiple-files-update}}.@refill
2214 @item M-x texinfo-indent-menu-description
2215 @findex texinfo-indent-menu-description
2216 Indent every description in the menu following point to the specified
2217 column. You can use this command to give yourself more space for
2218 descriptions. With an argument (@kbd{C-u} as prefix argument, if
2219 interactive), the @code{texinfo-indent-menu-description} command indents
2220 every description in every menu in the region. However, this command
2221 does not indent the second and subsequent lines of a multi-line
2224 @item M-x texinfo-sequential-node-update
2225 @findex texinfo-sequential-node-update
2226 Insert the names of the nodes immediately following and preceding the
2227 current node as the `Next' or `Previous' pointers regardless of those
2228 nodes' hierarchical level. This means that the `Next' node of a
2229 subsection may well be the next chapter. Sequentially ordered nodes are
2230 useful for novels and other documents that you read through
2231 sequentially. (However, in Info, the @kbd{g *} command lets
2232 you look through the file sequentially, so sequentially ordered nodes
2233 are not strictly necessary.) With an argument (prefix argument, if
2234 interactive), the @code{texinfo-sequential-node-update} command
2235 sequentially updates all the nodes in the region.@refill
2238 @node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
2239 @comment node-name, next, previous, up
2240 @section Formatting for Info
2241 @cindex Formatting for Info
2242 @cindex Running an Info formatter
2243 @cindex Info formatting
2245 Texinfo mode provides several commands for formatting part or all of a
2246 Texinfo file for Info. Often, when you are writing a document, you
2247 want to format only part of a file---that is, a region.@refill
2249 You can use either the @code{texinfo-format-region} or the
2250 @code{makeinfo-region} command to format a region:@refill
2253 @findex texinfo-format-region
2255 @itemx M-x texinfo-format-region
2257 @itemx M-x makeinfo-region
2258 Format the current region for Info.@refill
2261 You can use either the @code{texinfo-format-buffer} or the
2262 @code{makeinfo-buffer} command to format a whole buffer:@refill
2265 @findex texinfo-format-buffer
2267 @itemx M-x texinfo-format-buffer
2269 @itemx M-x makeinfo-buffer
2270 Format the current buffer for Info.@refill
2274 For example, after writing a Texinfo file, you can type the following:
2279 C-u M-x texinfo-master-menu
2283 This updates all the nodes and menus. Then type the following to create
2292 For @TeX{} or the Info formatting commands to work, the file @emph{must}
2293 include a line that has @code{@@setfilename} in its header.
2295 @xref{Creating an Info File}, for details about Info formatting.@refill
2297 @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
2298 @comment node-name, next, previous, up
2299 @section Formatting and Printing
2300 @cindex Formatting for printing
2301 @cindex Printing a region or buffer
2302 @cindex Region formatting and printing
2303 @cindex Buffer formatting and printing
2304 @cindex Part of file formatting and printing
2306 Typesetting and printing a Texinfo file is a multi-step process in which
2307 you first create a file for printing (called a DVI file), and then
2308 print the file. Optionally, you may also create indices. To do this,
2309 you must run the @code{texindex} command after first running the
2310 @code{tex} typesetting command; and then you must run the @code{tex}
2311 command again. Or else run the @code{texi2dvi} command which
2312 automatically creates indices as needed (@pxref{Format with texi2dvi}).
2314 Often, when you are writing a document, you want to typeset and print
2315 only part of a file to see what it will look like. You can use the
2316 @code{texinfo-tex-region} and related commands for this purpose. Use
2317 the @code{texinfo-tex-buffer} command to format all of a
2322 @itemx M-x texinfo-tex-buffer
2323 @findex texinfo-tex-buffer
2324 Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
2325 buffer, this command automatically creates or updates indices as
2329 @itemx M-x texinfo-tex-region
2330 @findex texinfo-tex-region
2331 Run @TeX{} on the region.@refill
2334 @itemx M-x texinfo-texindex
2335 Run @code{texindex} to sort the indices of a Texinfo file formatted with
2336 @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
2337 not run @code{texindex} automatically; it only runs the @code{tex}
2338 typesetting command. You must run the @code{texinfo-tex-region} command
2339 a second time after sorting the raw index files with the @code{texindex}
2340 command. (Usually, you do not format an index when you format a region,
2341 only when you format a buffer. Now that the @code{texi2dvi} command
2342 exists, there is little or no need for this command.)@refill
2345 @itemx M-x texinfo-tex-print
2346 @findex texinfo-tex-print
2347 Print the file (or the part of the file) previously formatted with
2348 @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2351 For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2352 file @emph{must} start with a @samp{\input texinfo} line and must
2353 include an @code{@@settitle} line. The file must end with @code{@@bye}
2354 on a line by itself. (When you use @code{texinfo-tex-region}, you must
2355 surround the @code{@@settitle} line with start-of-header and
2356 end-of-header lines.)@refill
2358 @xref{Hardcopy}, for a description of the other @TeX{} related
2359 commands, such as @code{tex-show-print-queue}.@refill
2361 @node Texinfo Mode Summary, , Printing, Texinfo Mode
2362 @comment node-name, next, previous, up
2363 @section Texinfo Mode Summary
2365 In Texinfo mode, each set of commands has default keybindings that
2366 begin with the same keys. All the commands that are custom-created
2367 for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
2370 @subheading Insert Commands
2372 The insert commands are invoked by typing @kbd{C-c} twice and then the
2373 first letter of the @@-command to be inserted. (It might make more
2374 sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2375 @kbd{C-c C-c} is quick to type.)@refill
2378 C-c C-c c @r{Insert} @samp{@@code}.
2379 C-c C-c d @r{Insert} @samp{@@dfn}.
2380 C-c C-c e @r{Insert} @samp{@@end}.
2381 C-c C-c i @r{Insert} @samp{@@item}.
2382 C-c C-c n @r{Insert} @samp{@@node}.
2383 C-c C-c s @r{Insert} @samp{@@samp}.
2384 C-c C-c v @r{Insert} @samp{@@var}.
2385 C-c C-c @{ @r{Insert braces.}
2387 C-c C-c @} @r{Move out of enclosing braces.}
2390 C-c C-c C-d @r{Insert a node's section title}
2391 @r{in the space for the description}
2392 @r{in a menu entry line.}
2396 @subheading Show Structure
2398 The @code{texinfo-show-structure} command is often used within a
2399 narrowed region.@refill
2402 C-c C-s @r{List all the headings.}
2405 @subheading The Master Update Command
2407 The @code{texinfo-master-menu} command creates a master menu; and can
2408 be used to update every node and menu in a file as well.@refill
2410 @c Probably should use @tables in this section.
2414 M-x texinfo-master-menu
2415 @r{Create or update a master menu.}
2419 C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
2420 @r{create or update all nodes and regular}
2421 @r{menus, and then create a master menu.}
2425 @subheading Update Pointers
2427 The update pointer commands are invoked by typing @kbd{C-c C-u} and
2428 then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2429 @code{texinfo-every-node-update}.@refill
2432 C-c C-u C-n @r{Update a node.}
2433 C-c C-u C-e @r{Update every node in the buffer.}
2436 @subheading Update Menus
2438 Invoke the update menu commands by typing @kbd{C-c C-u}
2439 and then either @kbd{C-m} for @code{texinfo-make-menu} or
2440 @kbd{C-a} for @code{texinfo-all-menus-update}. To update
2441 both nodes and menus at the same time, precede @kbd{C-c C-u
2442 C-a} with @kbd{C-u}.@refill
2445 C-c C-u C-m @r{Make or update a menu.}
2448 C-c C-u C-a @r{Make or update all}
2449 @r{menus in a buffer.}
2453 C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2454 @r{first create or update all nodes and}
2455 @r{then create or update all menus.}
2459 @subheading Format for Info
2461 The Info formatting commands that are written in Emacs Lisp are
2462 invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2463 or @kbd{C-b} for the whole buffer.@refill
2465 The Info formatting commands that are written in C and based on the
2466 @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2467 either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2471 Use the @code{texinfo-format@dots{}} commands:
2475 C-c C-e C-r @r{Format the region.}
2476 C-c C-e C-b @r{Format the buffer.}
2482 Use @code{makeinfo}:
2485 C-c C-m C-r @r{Format the region.}
2486 C-c C-m C-b @r{Format the buffer.}
2487 C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
2488 C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
2491 @subheading Typeset and Print
2493 The @TeX{} typesetting and printing commands are invoked by typing
2494 @kbd{C-c C-t} and then another control command: @kbd{C-r} for
2495 @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2499 C-c C-t C-r @r{Run @TeX{} on the region.}
2500 C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
2501 C-c C-t C-i @r{Run} @code{texindex}.
2502 C-c C-t C-p @r{Print the DVI file.}
2503 C-c C-t C-q @r{Show the print queue.}
2504 C-c C-t C-d @r{Delete a job from the print queue.}
2505 C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
2506 C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
2507 C-c C-t C-l @r{Recenter the output buffer.}
2510 @subheading Other Updating Commands
2512 The remaining updating commands do not have standard keybindings because
2513 they are rarely used.
2517 M-x texinfo-insert-node-lines
2518 @r{Insert missing @code{@@node} lines in region.}
2519 @r{With @kbd{C-u} as a prefix argument,}
2520 @r{use section titles as node names.}
2524 M-x texinfo-multiple-files-update
2525 @r{Update a multi-file document.}
2526 @r{With @kbd{C-u 2} as a prefix argument,}
2527 @r{create or update all nodes and menus}
2528 @r{in all included files first.}
2532 M-x texinfo-indent-menu-description
2533 @r{Indent descriptions.}
2537 M-x texinfo-sequential-node-update
2538 @r{Insert node pointers in strict sequence.}
2543 @node Beginning a File
2544 @chapter Beginning a Texinfo File
2545 @cindex Beginning a Texinfo file
2546 @cindex Texinfo file beginning
2547 @cindex File beginning
2549 Certain pieces of information must be provided at the beginning of a
2550 Texinfo file, such as the name for the output file(s), the title of the
2551 document, and the Top node.
2553 This chapter expands on the minimal complete Texinfo source file
2554 previously given (@pxref{Six Parts}).
2557 * Sample Beginning:: A sample beginning for a Texinfo file.
2558 * Texinfo File Header:: The first lines.
2559 * Document Permissions:: Ensuring your manual is free.
2560 * Titlepage & Copyright Page:: Creating the title and copyright pages.
2561 * The Top Node:: Creating the `Top' node and master menu.
2562 * Global Document Commands:: Affecting formatting throughout.
2563 * Software Copying Permissions:: Ensure that you and others continue to
2564 have the right to use and share software.
2568 @node Sample Beginning
2569 @section Sample Texinfo File Beginning
2571 @cindex Example beginning of Texinfo file
2573 The following sample shows what is needed. The elements given here are
2574 explained in more detail in the following sections. Other commands are
2575 often included at the beginning of Texinfo files, but the ones here are
2578 @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
2581 \input texinfo @@c -*-texinfo-*-
2582 @@c %**start of header
2583 @@setfilename @var{infoname}.info
2584 @@settitle @var{name-of-manual} @var{version}
2585 @@c %**end of header
2588 This manual is for @var{program}, version @var{version}.
2590 Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2594 Permission is granted to @dots{}
2601 @@title @var{name-of-manual-when-printed}
2602 @@subtitle @var{subtitle-if-any}
2603 @@subtitle @var{second-subtitle}
2604 @@author @var{author}
2608 @@c The following two commands
2609 @@c start the copyright page.
2611 @@vskip 0pt plus 1filll
2615 Published by @dots{}
2618 @@c So the toc is printed in the right place.
2630 * First Chapter:: Getting started @dots{}
2631 * Second Chapter:: @dots{}
2633 * Copying:: Your rights and freedoms.
2638 @@node First Chapter
2639 @@chapter First Chapter
2641 @@cindex first chapter
2642 @@cindex chapter, first
2648 @node Texinfo File Header
2649 @section Texinfo File Header
2650 @cindex Header for Texinfo files
2651 @cindex Texinfo file header
2653 Texinfo files start with at least three lines that provide Info and
2654 @TeX{} with necessary information. These are the @code{\input texinfo}
2655 line, the @code{@@settitle} line, and the @code{@@setfilename} line.
2657 Also, if you want to format just part of the Texinfo file, you must
2658 write the @code{@@settitle} and @code{@@setfilename} lines between
2659 start-of-header and end-of-header lines. The start- and end-of-header
2660 lines are optional, but they do no harm, so you might as well always
2663 Any command that affects document formatting as a whole makes sense to
2664 include in the header. @code{@@synindex} (@pxref{synindex}), for
2665 instance, is another command often included in the header. @xref{GNU
2666 Sample Texts}, for complete sample texts.
2668 Thus, the beginning of a Texinfo file generally looks like this:
2672 \input texinfo @@c -*-texinfo-*-
2673 @@c %**start of header
2674 @@setfilename sample.info
2675 @@settitle Sample Manual 1.0
2676 @@c %**end of header
2681 * First Line:: The first line of a Texinfo file.
2682 * Start of Header:: Formatting a region requires this.
2683 * setfilename:: Tell Info the name of the Info file.
2684 * settitle:: Create a title for the printed work.
2685 * End of Header:: Formatting a region requires this.
2690 @subsection The First Line of a Texinfo File
2691 @cindex First line of a Texinfo file
2692 @cindex Beginning line of a Texinfo file
2693 @cindex Header of a Texinfo file
2695 Every Texinfo file that is to be the top-level input to @TeX{} must begin
2696 with a line that looks like this:
2699 \input texinfo @@c -*-texinfo-*-
2703 This line serves two functions:
2707 When the file is processed by @TeX{}, the @samp{\input texinfo} command
2708 tells @TeX{} to load the macros needed for processing a Texinfo file.
2709 These are in a file called @file{texinfo.tex}, which should have been
2710 installed on your system along with either the @TeX{} or Texinfo
2711 software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
2712 a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
2713 file causes the switch from @samp{\} to @samp{@@}; before the switch
2714 occurs, @TeX{} requires @samp{\}, which is why it appears at the
2715 beginning of the file.
2718 When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2719 specification tells Emacs to use Texinfo mode.
2723 @node Start of Header
2724 @subsection Start of Header
2725 @cindex Start of header line
2727 A start-of-header line is a Texinfo comment that looks like this:
2730 @@c %**start of header
2733 Write the start-of-header line on the second line of a Texinfo file.
2734 Follow the start-of-header line with @code{@@setfilename} and
2735 @code{@@settitle} lines and, optionally, with other commands that
2736 globally affect the document formatting, such as @code{@@synindex} or
2737 @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
2740 The start- and end-of-header lines allow you to format only part of a
2741 Texinfo file for Info or printing. @xref{texinfo-format commands}.
2743 The odd string of characters, @samp{%**}, is to ensure that no other
2744 comment is accidentally taken for a start-of-header line. You can
2745 change it if you wish by setting the @code{tex-start-of-header} and/or
2746 @code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}.
2750 @subsection @code{@@setfilename}: Set the output file name
2752 @cindex Texinfo requires @code{@@setfilename}
2754 In order to serve as the primary input file for either @code{makeinfo}
2755 or @TeX{}, a Texinfo file must contain a line that looks like this:
2758 @@setfilename @var{info-file-name}
2761 Write the @code{@@setfilename} command at the beginning of a line and
2762 follow it on the same line by the Info file name. Do not write anything
2763 else on the line; anything on the line after the command is considered
2764 part of the file name, including what would otherwise be a
2767 @cindex Ignored before @code{@@setfilename}
2768 @cindex @samp{\input} source line ignored
2769 The Info formatting commands ignore everything written before the
2770 @code{@@setfilename} line, which is why the very first line of
2771 the file (the @code{\input} line) does not show up in the output.
2773 The @code{@@setfilename} line specifies the name of the output file to
2774 be generated. This name must be different from the name of the Texinfo
2775 file. There are two conventions for choosing the name: you can either
2776 remove the extension (such as @samp{.texi}) entirely from the input file
2777 name, or, preferably, replace it with the @samp{.info} extension.
2779 @cindex Length of file names
2780 @cindex File name collision
2781 @cindex Info file name, choosing
2782 Although an explicit @samp{.info} extension is preferable, some
2783 operating systems cannot handle long file names. You can run into a
2784 problem even when the file name you specify is itself short enough.
2785 This occurs because the Info formatters split a long Info file into
2786 short indirect subfiles, and name them by appending @samp{-1},
2787 @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2788 file name. (@xref{Tag and Split Files}.) The subfile name
2789 @file{texinfo.info-10}, for example, is too long for old systems with a
2790 14-character limit on filenames; so the Info file name for this document
2791 is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
2792 is running on operating systems such as MS-DOS which impose severe
2793 limits on file names, it may remove some characters from the original
2794 file name to leave enough space for the subfile suffix, thus producing
2795 files named @file{texin-10}, @file{gcc.i12}, etc.
2797 When producing HTML output, @code{makeinfo} will replace any extension
2798 with @samp{html}, or add @samp{.html} if the given name has no
2802 The @code{@@setfilename} line produces no output when you typeset a
2803 manual with @TeX{}, but it is nevertheless essential: it opens the
2804 index, cross-reference, and other auxiliary files used by Texinfo, and
2805 also reads @file{texinfo.cnf} if that file is present on your system
2806 (@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2810 @subsection @code{@@settitle}: Set the document title
2813 In order to be made into a printed manual, a Texinfo file must contain
2814 a line that looks like this:
2817 @@settitle @var{title}
2820 Write the @code{@@settitle} command at the beginning of a line and
2821 follow it on the same line by the title. This tells @TeX{} the title to
2822 use in a header or footer. Do not write anything else on the line;
2823 anything on the line after the command is considered part of the title,
2824 including what would otherwise be a comment.
2826 The @code{@@settitle} command should precede everything that generates
2827 actual output in @TeX{}.
2829 @cindex <title> HTML tag
2830 In the HTML file produced by @command{makeinfo}, @var{title} also serves
2831 as the document @samp{<title>} and the default document description in
2832 the @samp{<head>} part; see @ref{documentdescription}, for how to change
2835 The title in the @code{@@settitle} command does not affect the title as
2836 it appears on the title page. Thus, the two do not need not match
2837 exactly. A practice we recommend is to include the version or edition
2838 number of the manual in the @code{@@settitle} title; on the title page,
2839 the version number generally appears as a @code{@@subtitle} so it would
2840 be omitted from the @code{@@title}. (@xref{titlepage}.)
2842 Conventionally, when @TeX{} formats a Texinfo file for double-sided
2843 output, the title is printed in the left-hand (even-numbered) page
2844 headings and the current chapter title is printed in the right-hand
2845 (odd-numbered) page headings. (@TeX{} learns the title of each chapter
2846 from each @code{@@chapter} command.) By default, no page footer is
2849 Even if you are printing in a single-sided style, @TeX{} looks for an
2850 @code{@@settitle} command line, in case you include the manual title
2853 @TeX{} prints page headings only for that text that comes after the
2854 @code{@@end titlepage} command in the Texinfo file, or that comes
2855 after an @code{@@headings} command that turns on headings.
2856 (@xref{headings on off, , The @code{@@headings} Command}, for more
2859 You may, if you wish, create your own, customized headings and footings.
2860 @xref{Headings}, for a detailed discussion of this.
2864 @subsection End of Header
2865 @cindex End of header line
2867 Follow the header lines with an @w{end-of-header} line, which is a
2868 Texinfo comment that looks like this:
2871 @@c %**end of header
2874 @xref{Start of Header}.
2877 @node Document Permissions
2878 @section Document Permissions
2879 @cindex Document Permissions
2880 @cindex Copying Permissions
2882 The copyright notice and copying permissions for a document need to
2883 appear in several places in the various Texinfo output formats.
2884 Therefore, Texinfo provides a command (@code{@@copying}) to declare
2885 this text once, and another command (@code{@@insertcopying}) to
2886 insert the text at appropriate points.
2889 * copying:: Declare the document's copying permissions.
2890 * insertcopying:: Where to insert the permissions.
2895 @subsection @code{@@copying}: Declare copying permissions
2898 The @code{@@copying} command should be given very early in the document;
2899 right after the header material (@pxref{Texinfo File Header}) is the
2900 recommended location. It conventionally consists of a sentence or two
2901 about what the program is, the legal copyright line, and the copying
2902 permissions. Here is a skeletal example:
2906 This manual is for @var{program} (version @var{version}),
2909 Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2912 Permission is granted to @dots{}
2917 The @code{@@quotation} has no legal significance; it's there to improve
2918 readability in some contexts.
2920 @xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
2921 @xref{GNU Free Documentation License}, for the license itself under
2922 which GNU and other free manuals are distributed.
2924 The text of @code{@@copying} is output as a comment at the beginning of
2925 Info, HTML, and XML output files. It is @emph{not} output implicitly in
2926 plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
2927 emit the copying information. See the next section for details.
2930 In output formats that support it (print and HTML), the
2931 @code{@@copyright@{@}} command generates a @samp{c} inside a circle. In
2932 Info and plain text, it generates @samp{(C)}. The copyright notice
2933 itself has the following legally defined sequence:
2936 Copyright @copyright{} @var{years} @var{copyright-owner}.
2939 @cindex Copyright word, always in English
2940 The word `Copyright' must always be written in English, even if the
2941 manual is otherwise in another language. This is due to international
2944 @cindex Years, in copyright line
2945 The list of years should include all years in which a version was
2946 completed (even if it was released in a subsequent year). Ranges are
2947 not allowed, each year must be written out individually, separated by
2950 @cindex Copyright owner for FSF works
2951 The copyright owner (or owners) is whoever holds legal copyright on the
2952 work. In the case of works assigned to the FSF, the owner is `Free
2953 Software Foundation, Inc.'.
2955 @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
2956 additional information.
2960 @subsection @code{@@insertcopying}: Include permissions text
2961 @findex insertcopying
2962 @cindex Copying text, including
2963 @cindex Permissions text, including
2964 @cindex Including permissions text
2966 The @code{@@insertcopying} command is simply written on a line by
2973 It inserts the text previously defined by @code{@@copying}. Legally, it
2974 must be used on the copyright page in the printed manual
2975 (@pxref{Copyright}).
2977 Although it's not a legal requirement, we also strongly recommend using
2978 @code{@@insertcopying} in the Top node of your manual (@pxref{The Top
2981 The @code{@@copying} command itself causes the permissions text to
2982 appear in an Info file @emph{before} the first node. The text is also
2983 copied into the beginning of each split Info output file, as is legally
2984 necessary. This location implies a human reading the manual using Info
2985 does @emph{not} see this text (except when using the advanced Info
2986 command @kbd{g *}). Therefore, an explicit @code{@@insertcopying}
2987 in the Top node makes it apparent to readers that the manual is free.
2989 Similarly, the @code{@@copying} text is automatically included at the
2990 beginning of each HTML output file, as an HTML comment. Again, this
2991 text is not visible (unless the reader views the HTML source). And
2992 therefore again, the @code{@@insertcopying} in the Top node is valuable
2993 because it makes the copying permissions visible and thus promotes
2996 The permissions text defined by @code{@@copying} also appears
2997 automatically at the beginning of the XML output file.
3000 @node Titlepage & Copyright Page
3001 @section Title and Copyright Pages
3003 In hard copy output, the manual's name and author are usually printed on
3004 a title page. Copyright information is usually printed on the back of
3007 The title and copyright pages appear in the printed manual, but not in
3008 the Info file. Because of this, it is possible to use several slightly
3009 obscure @TeX{} typesetting commands that cannot be used in an Info file.
3010 In addition, this part of the beginning of a Texinfo file contains the
3011 text of the copying permissions that appears in the printed manual.
3013 @cindex Title page, for plain text
3014 @cindex Copyright page, for plain text
3015 You may wish to include titlepage-like information for plain text
3016 output. Simply place any such leading material between
3017 @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
3018 includes this when writing plain text (@samp{--no-headers}), along with
3019 an @code{@@insertcopying}.
3022 * titlepage:: Create a title for the printed document.
3023 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3024 and @code{@@sp} commands.
3025 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
3026 and @code{@@author} commands.
3027 * Copyright:: How to write the copyright notice and
3028 include copying permissions.
3029 * end titlepage:: Turn on page headings after the title and
3031 * headings on off:: An option for turning headings on and off
3032 and double or single sided printing.
3037 @subsection @code{@@titlepage}
3041 Start the material for the title page and following copyright page
3042 with @code{@@titlepage} on a line by itself and end it with
3043 @code{@@end titlepage} on a line by itself.
3045 The @code{@@end titlepage} command starts a new page and turns on page
3046 numbering. (@xref{Headings, , Page Headings}, for details about how to
3047 generate page headings.) All the material that you want to appear on
3048 unnumbered pages should be put between the @code{@@titlepage} and
3049 @code{@@end titlepage} commands. You can force the table of contents to
3050 appear there with the @code{@@setcontentsaftertitlepage} command
3053 @findex page@r{, within @code{@@titlepage}}
3054 By using the @code{@@page} command you can force a page break within the
3055 region delineated by the @code{@@titlepage} and @code{@@end titlepage}
3056 commands and thereby create more than one unnumbered page. This is how
3057 the copyright page is produced. (The @code{@@titlepage} command might
3058 perhaps have been better named the @code{@@titleandadditionalpages}
3059 command, but that would have been rather long!)
3061 When you write a manual about a computer program, you should write the
3062 version of the program to which the manual applies on the title page.
3063 If the manual changes more frequently than the program or is independent
3064 of it, you should also include an edition number@footnote{We have found
3065 that it is helpful to refer to versions of independent manuals as
3066 `editions' and versions of programs as `versions'; otherwise, we find we
3067 are liable to confuse each other in conversation by referring to both
3068 the documentation and the software with the same words.} for the manual.
3069 This helps readers keep track of which manual is for which version of
3070 the program. (The `Top' node should also contain this information; see
3071 @ref{The Top Node}.)
3073 Texinfo provides two main methods for creating a title page. One method
3074 uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3075 to generate a title page in which the words on the page are
3078 The second method uses the @code{@@title}, @code{@@subtitle}, and
3079 @code{@@author} commands to create a title page with black rules under
3080 the title and author lines and the subtitle text set flush to the
3081 right hand side of the page. With this method, you do not specify any
3082 of the actual formatting of the title page. You specify the text
3083 you want, and Texinfo does the formatting.
3085 You may use either method, or you may combine them; see the examples in
3088 @findex shorttitlepage
3089 @cindex Bastard title page
3090 @cindex Title page, bastard
3091 For extremely simple applications, and for the bastard title page in
3092 traditional book front matter, Texinfo also provides a command
3093 @code{@@shorttitlepage} which takes the rest of the line as the title.
3094 The argument is typeset on a page by itself and followed by a blank
3098 @node titlefont center sp
3099 @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3102 @findex sp @r{(titlepage line spacing)}
3104 You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3105 commands to create a title page for a printed document. (This is the
3106 first of the two methods for creating a title page in Texinfo.)
3108 Use the @code{@@titlefont} command to select a large font suitable for
3109 the title itself. You can use @code{@@titlefont} more than once if you
3110 have an especially long title.
3116 @@titlefont@{Texinfo@}
3119 Use the @code{@@center} command at the beginning of a line to center
3120 the remaining text on that line. Thus,
3123 @@center @@titlefont@{Texinfo@}
3127 centers the title, which in this example is ``Texinfo'' printed
3130 Use the @code{@@sp} command to insert vertical space. For example:
3137 This inserts two blank lines on the printed page. (@xref{sp, ,
3138 @code{@@sp}}, for more information about the @code{@@sp}
3141 A template for this method looks like this:
3147 @@center @@titlefont@{@var{name-of-manual-when-printed}@}
3149 @@center @var{subtitle-if-any}
3151 @@center @var{author}
3157 The spacing of the example fits an 8.5 by 11 inch manual.
3160 @node title subtitle author
3161 @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3166 You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3167 commands to create a title page in which the vertical and horizontal
3168 spacing is done for you automatically. This contrasts with the method
3169 described in the previous section, in which the @code{@@sp} command is
3170 needed to adjust vertical spacing.
3172 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3173 commands at the beginning of a line followed by the title, subtitle,
3176 The @code{@@title} command produces a line in which the title is set
3177 flush to the left-hand side of the page in a larger than normal font.
3178 The title is underlined with a black rule. Only a single line is
3179 allowed; the @code{@@*} command may not be used to break the title into
3180 two lines. To handle very long titles, you may find it profitable to
3181 use both @code{@@title} and @code{@@titlefont}; see the final example in
3184 The @code{@@subtitle} command sets subtitles in a normal-sized font
3185 flush to the right-hand side of the page.
3187 The @code{@@author} command sets the names of the author or authors in
3188 a middle-sized font flush to the left-hand side of the page on a line
3189 near the bottom of the title page. The names are underlined with a
3190 black rule that is thinner than the rule that underlines the title.
3191 (The black rule only occurs if the @code{@@author} command line is
3192 followed by an @code{@@page} command line.)
3194 There are two ways to use the @code{@@author} command: you can write
3195 the name or names on the remaining part of the line that starts with
3196 an @code{@@author} command:
3199 @@author by Jane Smith and John Doe
3203 or you can write the names one above each other by using two (or more)
3204 @code{@@author} commands:
3214 (Only the bottom name is underlined with a black rule.)
3217 A template for this method looks like this:
3222 @@title @var{name-of-manual-when-printed}
3223 @@subtitle @var{subtitle-if-any}
3224 @@subtitle @var{second-subtitle}
3225 @@author @var{author}
3232 You may also combine the @code{@@titlefont} method described in the
3233 previous section and @code{@@title} method described in this one. This
3234 may be useful if you have a very long title. Here is a real-life example:
3239 @@titlefont@{GNU Software@}
3241 @@title for MS-Windows and MS-DOS
3242 @@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3243 @@author by Daniel Hagerty, Melissa Weisshaus
3244 @@author and Eli Zaretskii
3249 (The use of @code{@@value} here is explained in @ref{value Example}.
3253 @subsection Copyright Page
3254 @cindex Copyright page
3255 @cindex Printed permissions
3256 @cindex Permissions, printed
3258 By international treaty, the copyright notice for a book must be either
3259 on the title page or on the back of the title page. When the copyright
3260 notice is on the back of the title page, that page is customarily not
3261 numbered. Therefore, in Texinfo, the information on the copyright page
3262 should be within @code{@@titlepage} and @code{@@end titlepage}
3265 @findex vskip @r{@TeX{} vertical skip}
3266 @findex filll @r{@TeX{} dimension}
3267 Use the @code{@@page} command to cause a page break. To push the
3268 copyright notice and the other text on the copyright page towards the
3269 bottom of the page, use the following incantantion after @code{@@page}:
3272 @@vskip 0pt plus 1filll
3276 This is a @TeX{} command that is not supported by the Info formatting
3277 commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
3278 plus 1filll} means to put in zero points of mandatory whitespace, and as
3279 much optional whitespace as needed to push the following text to the
3280 bottom of the page. Note the use of three @samp{l}s in the word
3281 @samp{filll}; this is correct.
3283 To insert the copyright text itself, write @code{@@insertcopying}
3284 next (@pxref{Document Permissions}):
3290 Follow the copying text by the publisher, ISBN numbers, cover art
3291 credits, and other such information.
3293 Here is an example putting all this together:
3299 @@vskip 0pt plus 1filll
3302 Published by @dots{}
3304 Cover art by @dots{}
3310 @subsection Heading Generation
3311 @findex end titlepage
3312 @cindex Headings, page, begin to appear
3313 @cindex Titlepage end starts headings
3314 @cindex End titlepage starts headings
3316 The @code{@@end titlepage} command must be written on a line by itself.
3317 It not only marks the end of the title and copyright pages, but also
3318 causes @TeX{} to start generating page headings and page numbers.
3320 To repeat what is said elsewhere, Texinfo has two standard page heading
3321 formats, one for documents which are printed on one side of each sheet of paper
3322 (single-sided printing), and the other for documents which are printed on both
3323 sides of each sheet (double-sided printing).
3324 You can specify these formats in different ways:
3328 The conventional way is to write an @code{@@setchapternewpage} command
3329 before the title page commands, and then have the @code{@@end
3330 titlepage} command start generating page headings in the manner desired.
3331 (@xref{setchapternewpage}.)
3334 Alternatively, you can use the @code{@@headings} command to prevent page
3335 headings from being generated or to start them for either single or
3336 double-sided printing. (Write an @code{@@headings} command immediately
3337 after the @code{@@end titlepage} command. @xref{headings on off, , The
3338 @code{@@headings} Command}, for more information.)@refill
3341 Or, you may specify your own page heading and footing format.
3342 @xref{Headings, , Page Headings}, for detailed
3343 information about page headings and footings.
3346 Most documents are formatted with the standard single-sided or
3347 double-sided format, using @code{@@setchapternewpage odd} for
3348 double-sided printing and no @code{@@setchapternewpage} command for
3349 single-sided printing.
3352 @node headings on off
3353 @subsection The @code{@@headings} Command
3356 The @code{@@headings} command is rarely used. It specifies what kind of
3357 page headings and footings to print on each page. Usually, this is
3358 controlled by the @code{@@setchapternewpage} command. You need the
3359 @code{@@headings} command only if the @code{@@setchapternewpage} command
3360 does not do what you want, or if you want to turn off pre-defined page
3361 headings prior to defining your own. Write an @code{@@headings} command
3362 immediately after the @code{@@end titlepage} command.@refill
3364 You can use @code{@@headings} as follows:@refill
3367 @item @@headings off
3368 Turn off printing of page headings.@refill
3370 @item @@headings single
3371 Turn on page headings appropriate for single-sided printing.
3374 @item @@headings double
3375 @itemx @@headings on
3376 Turn on page headings appropriate for double-sided printing. The two
3377 commands, @code{@@headings on} and @code{@@headings double}, are
3380 @item @@headings singleafter
3381 @itemx @@headings doubleafter
3382 Turn on @code{single} or @code{double} headings, respectively, after the
3383 current page is output.
3386 Turn on page headings: @code{single} if @samp{@@setchapternewpage
3387 on}, @code{double} otherwise.
3390 For example, suppose you write @code{@@setchapternewpage off} before the
3391 @code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3392 same page as the end of the last chapter. This command also causes
3393 @TeX{} to typeset page headers for single-sided printing. To cause
3394 @TeX{} to typeset for double sided printing, write @code{@@headings
3395 double} after the @code{@@end titlepage} command.
3397 You can stop @TeX{} from generating any page headings at all by
3398 writing @code{@@headings off} on a line of its own immediately after the
3399 line containing the @code{@@end titlepage} command, like this:@refill
3407 The @code{@@headings off} command overrides the @code{@@end titlepage}
3408 command, which would otherwise cause @TeX{} to print page
3411 You can also specify your own style of page heading and footing.
3412 @xref{Headings, , Page Headings}, for more information.@refill
3416 @section The `Top' Node and Master Menu
3420 The `Top' node is the node in which a reader enters an Info manual. As
3421 such, it should begin with the @code{@@insertcopying} command
3422 (@pxref{Document Permissions}) to provide a brief description of the
3423 manual (including the version number) and copying permissions, and end
3424 with a master menu for the whole manual. Of course you should include
3425 any other general information you feel a reader would find helpful.
3428 It is also conventional to write an @code{@@top} sectioning command line
3429 containing the title of the document immediately after the @code{@@node
3430 Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
3433 The contents of the `Top' node should appear only in the online output;
3434 none of it should appear in printed output, so enclose it between
3435 @code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
3436 print either an @code{@@node} line or a menu; they appear only in Info;
3437 strictly speaking, you are not required to enclose these parts between
3438 @code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
3439 so. @xref{Conditionals, , Conditionally Visible Text}.)
3442 * Top Node Example::
3443 * Master Menu Parts::
3447 @node Top Node Example
3448 @subsection Top Node Example
3450 @cindex Top node example
3452 Here is an example of a Top node.
3463 Additional general information.
3476 @node Master Menu Parts
3477 @subsection Parts of a Master Menu
3479 @cindex Menu, master
3480 @cindex Parts of a master menu
3482 A @dfn{master menu} is a detailed main menu listing all the nodes in a
3485 A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3486 commands and does not appear in the printed document.
3488 Generally, a master menu is divided into parts.
3492 The first part contains the major nodes in the Texinfo file: the nodes
3493 for the chapters, chapter-like sections, and the appendices.
3496 The second part contains nodes for the indices.
3499 The third and subsequent parts contain a listing of the other, lower
3500 level nodes, often ordered by chapter. This way, rather than go
3501 through an intermediary menu, an inquirer can go directly to a
3502 particular node when searching for specific information. These menu
3503 items are not required; add them if you think they are a
3504 convenience. If you do use them, put @code{@@detailmenu} before the
3505 first one, and @code{@@end detailmenu} after the last; otherwise,
3506 @code{makeinfo} will get confused.
3509 Each section in the menu can be introduced by a descriptive line. So
3510 long as the line does not begin with an asterisk, it will not be
3511 treated as a menu entry. (@xref{Writing a Menu}, for more
3514 For example, the master menu for this manual looks like the following
3515 (but has many more entries):
3520 * Copying Conditions:: Your rights.
3521 * Overview:: Texinfo in brief.
3525 * Command and Variable Index::
3531 --- The Detailed Node Listing ---
3535 * Reporting Bugs:: @dots{}
3540 Beginning a Texinfo File
3542 * Sample Beginning:: @dots{}
3550 @node Global Document Commands
3551 @section Global Document Commands
3552 @cindex Global Document Commands
3554 Besides the basic commands mentioned in the previous sections, here are
3555 additional commands which affect the document as a whole. They are
3556 generally all given before the Top node, if they are given at all.
3559 * documentdescription:: Document summary for the HTML output.
3560 * setchapternewpage:: Start chapters on right-hand pages.
3561 * paragraphindent:: Specify paragraph indentation.
3562 * exampleindent:: Specify environment indentation.
3566 @node documentdescription
3567 @subsection @code{@@documentdescription}: Summary text
3568 @cindex Document description
3569 @cindex Description of document
3570 @cindex Summary of document
3571 @cindex Abstract of document
3572 @cindex <meta> HTML tag, and document description
3573 @findex documentdescription
3575 When producing HTML output for a document, @command{makeinfo} writes a
3576 @samp{<meta>} element in the @samp{<head>} to give some idea of the
3577 content of the document. By default, this @dfn{description} is the title
3578 of the document, taken from the @code{@@settitle} command
3579 (@pxref{settitle}). To change this, use the @code{@@documentdescription}
3583 @@documentdescription
3585 @@end documentdescription
3589 This will produce the following output in the @samp{<head>} of the HTML:
3592 <meta name=description content="descriptive text.">
3595 @code{@@documentdescription} must be specified before the first node of
3599 @node setchapternewpage
3600 @subsection @code{@@setchapternewpage}:
3601 @cindex Starting chapters
3602 @cindex Pages, starting odd
3603 @findex setchapternewpage
3605 In an officially bound book, text is usually printed on both sides of
3606 the paper, chapters start on right-hand pages, and right-hand pages have
3607 odd numbers. But in short reports, text often is printed only on one
3608 side of the paper. Also in short reports, chapters sometimes do not
3609 start on new pages, but are printed on the same page as the end of the
3610 preceding chapter, after a small amount of vertical whitespace.
3612 You can use the @code{@@setchapternewpage} command with various
3613 arguments to specify how @TeX{} should start chapters and whether it
3614 should format headers for printing on one or both sides of the paper
3615 (single-sided or double-sided printing).
3617 Write the @code{@@setchapternewpage} command at the beginning of a
3618 line followed by its argument.
3620 For example, you would write the following to cause each chapter to
3621 start on a fresh odd-numbered page:
3624 @@setchapternewpage odd
3627 You can specify one of three alternatives with the
3628 @code{@@setchapternewpage} command:
3632 @item @code{@@setchapternewpage off}
3633 Cause @TeX{} to typeset a new chapter on the same page as the last
3634 chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
3635 format page headers for single-sided printing.
3637 @item @code{@@setchapternewpage on}
3638 Cause @TeX{} to start new chapters on new pages and to format page
3639 headers for single-sided printing. This is the form most often used for
3640 short reports or personal printing. This is the default.
3642 @item @code{@@setchapternewpage odd}
3643 Cause @TeX{} to start new chapters on new, odd-numbered pages
3644 (right-handed pages) and to typeset for double-sided printing. This is
3645 the form most often used for books and manuals.
3648 Texinfo does not have an @code{@@setchapternewpage even} command,
3649 because there is no printing tradition of starting chapters or books on
3650 an even-numbered page.
3652 If you don't like the default headers that @code{@@setchapternewpage}
3653 sets, you can explicit control them with the @code{@@headings} command.
3654 @xref{headings on off, , The @code{@@headings} Command}.
3656 At the beginning of a manual or book, pages are not numbered---for
3657 example, the title and copyright pages of a book are not numbered. By
3658 convention, table of contents and frontmatter pages are numbered with
3659 roman numerals and not in sequence with the rest of the document.
3661 Since an Info file does not have pages, the @code{@@setchapternewpage}
3662 command has no effect on it.
3664 We recommend not including any @code{@@setchapternewpage} command in
3665 your manual sources at all, since the desired output is not intrinsic to
3666 the document. For a particular hard copy run, if you don't want the
3667 default option (no blank pages, same headers on all pages) use the
3668 @option{--texinfo} option to @command{texi2dvi} to specify the output
3672 @node paragraphindent
3673 @subsection Paragraph Indenting
3674 @cindex Indenting paragraphs, control of
3675 @cindex Paragraph indentation control
3676 @findex paragraphindent
3678 The Texinfo processors may insert whitespace at the beginning of the
3679 first line of each paragraph, thereby indenting that paragraph. You can
3680 use the @code{@@paragraphindent} command to specify this indentation.
3681 Write an @code{@@paragraphindent} command at the beginning of a line
3682 followed by either @samp{asis} or a number:
3685 @@paragraphindent @var{indent}
3688 The indentation is according to the value of @var{indent}:
3692 Do not change the existing indentation (not implemented in @TeX{}).
3696 Omit all indentation.
3699 Indent by @var{n} space characters in Info output, by @var{n} ems in
3704 The default value of @var{indent} is 3. @code{@@paragraphindent} is
3705 ignored for HTML output.
3707 It is best to write the @code{@@paragraphindent} command before the
3708 end-of-header line at the beginning of a Texinfo file, so the region
3709 formatting commands indent paragraphs as specified. @xref{Start of
3712 A peculiarity of the @code{texinfo-format-buffer} and
3713 @code{texinfo-format-region} commands is that they do not indent (nor
3714 fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
3715 @xref{Refilling Paragraphs}, for further information.
3719 @subsection @code{@@exampleindent}: Environment Indenting
3720 @cindex Indenting environments
3721 @cindex Environment indentation
3722 @cindex Example indentation
3723 @findex exampleindent
3725 The Texinfo processors indent each line of @code{@@example} and similar
3726 environments. You can use the @code{@@exampleindent} command to specify
3727 this indentation. Write an @code{@@exampleindent} command at the
3728 beginning of a line followed by either @samp{asis} or a number:
3731 @@exampleindent @var{indent}
3734 The indentation is according to the value of @var{indent}:
3738 Do not change the existing indentation (not implemented in @TeX{}).
3741 Omit all indentation.
3744 Indent environments by @var{n} space characters in Info output, by
3745 @var{n} ems in @TeX{}.
3749 The default value of @var{indent} is 5. @code{@@exampleindent} is
3750 ignored for HTML output.
3752 It is best to write the @code{@@exampleindent} command before the
3753 end-of-header line at the beginning of a Texinfo file, so the region
3754 formatting commands indent paragraphs as specified. @xref{Start of
3758 @node Software Copying Permissions
3759 @section Software Copying Permissions
3760 @cindex Software copying permissions
3761 @cindex Copying software
3762 @cindex Distribution
3763 @cindex License agreement
3765 If the Texinfo file has a section containing the ``General Public
3766 License'' and the distribution information and a warranty disclaimer for
3767 the software that is documented, we recommend placing this right after
3768 the `Top' node. The General Public License is very important to Project
3769 GNU software. It ensures that you and others will continue to have a
3770 right to use and share the software.
3772 The copying and distribution information and the disclaimer are followed
3773 by an introduction or else by the first chapter of the manual.
3775 @cindex Introduction, as part of file
3776 Although an introduction is not a required part of a Texinfo file, it
3777 is very helpful. Ideally, it should state clearly and concisely what
3778 the file is about and who would be interested in reading it. In
3779 general, an introduction would follow the licensing and distribution
3780 information, although sometimes people put it earlier in the document.
3784 @chapter Ending a Texinfo File
3785 @cindex Ending a Texinfo file
3786 @cindex Texinfo file ending
3790 The end of a Texinfo file should include commands to create indices and
3791 (perhaps) to generate both the full and summary tables of contents.
3792 Finally, it must include the @code{@@bye} command that marks the last
3793 line to be processed.
3811 * Printing Indices & Menus:: How to print an index in hardcopy and
3812 generate index menus in Info.
3813 * Contents:: How to create a table of contents.
3814 * File End:: How to mark the end of a file.
3818 @node Printing Indices & Menus
3819 @section Printing Indices and Menus
3821 @cindex Printing an index
3822 @cindex Indices, printing and menus
3823 @cindex Generating menus with indices
3824 @cindex Menus generated with indices
3826 To print an index means to include it as part of a manual or Info file.
3827 This does not happen automatically just because you use @code{@@cindex}
3828 or other index-entry generating commands in the Texinfo file; those just
3829 cause the raw data for the index to be accumulated. To generate an
3830 index, you must include the @code{@@printindex} command at the place in
3831 the document where you want the index to appear. Also, as part of the
3832 process of creating a printed manual, you must run a program called
3833 @code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
3834 sorted index file. The sorted index file is what is actually used to
3837 Texinfo offers six separate types of predefined index, each with a
3838 two-letter abbreviation, as illustrated in the following table.
3839 However, you may merge indices (@pxref{Combining Indices}) or define
3840 your own indices (@pxref{New Indices}).
3842 Here are the predefined indices, their abbreviations, and the
3843 corresponding index entry commands:
3847 concept index (@code{@@cindex})
3849 function index (@code{@@findex})
3851 variable index (@code{@@index})
3853 key index (@code{@@kindex})
3855 program index (@code{@@pindex})
3857 data type index (@code{@@tindex})
3860 The @code{@@printindex} command takes a two-letter index abbreviation,
3861 reads the corresponding sorted index file and formats it appropriately
3864 The @code{@@printindex} command does not generate a chapter heading for
3865 the index. Consequently, you should precede the @code{@@printindex}
3866 command with a suitable section or chapter command (usually
3867 @code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading
3868 and put the index into the table of contents. Precede the
3869 @code{@@unnumbered} command with an @code{@@node} line.
3875 @@node Variable Index
3876 @@unnumbered Variable Index
3882 @@node Concept Index
3883 @@unnumbered Concept Index
3891 We recommend placing the concept index last, since that makes it easiest
3892 to find. We also recommend having a single index whenever possible,
3893 since then readers have only one place to look (@pxref{Combining Indices}).
3897 @section Generating a Table of Contents
3898 @cindex Table of contents
3899 @cindex Contents, Table of
3900 @cindex Short table of contents
3902 @findex summarycontents
3903 @findex shortcontents
3905 The @code{@@chapter}, @code{@@section}, and other structuring commands
3906 supply the information to make up a table of contents, but they do not
3907 cause an actual table to appear in the manual. To do this, you must use
3908 the @code{@@contents} and/or @code{@@summarycontents} command(s).
3912 Generate a table of contents in a printed manual, including all
3913 chapters, sections, subsections, etc., as well as appendices and
3914 unnumbered chapters. Headings generated by the @code{@@heading}
3915 series of commands do not appear in the table of contents.
3917 @item @@shortcontents
3918 @itemx @@summarycontents
3919 (@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
3921 Generate a short or summary table of contents that lists only the
3922 chapters, appendices, and unnumbered chapters. Sections, subsections
3923 and subsubsections are omitted. Only a long manual needs a short table
3924 of contents in addition to the full table of contents.
3928 Both contents commands should be written on a line by themselves.
3929 The contents commands automatically generate a chapter-like heading at
3930 the top of the first table of contents page, so don't include any
3931 sectioning command such as @code{@@unnumbered} before them.
3933 Since an Info file uses menus instead of tables of contents, the Info
3934 formatting commands ignore the contents commands. But the contents are
3935 included in plain text output (generated by @code{makeinfo
3936 --no-headers}), unless @code{makeinfo} is writing its output to standard
3939 When @code{makeinfo} writes a short table of contents while producing
3940 html output, the links in the short table of contents point to
3941 corresponding entries in the full table of contents rather than the text
3942 of the document. The links in the full table of contents point to the
3943 main text of the document.
3945 The contents commands can be placed either at the very end of the file,
3946 after any indices (see the previous section) and just before the
3947 @code{@@bye} (see the next section), or near the beginning of the file,
3948 after the @code{@@end titlepage} (@pxref{titlepage}). The advantage to
3949 the former is that then the contents output is always up to date,
3950 because it reflects the processing just done. The advantage to the
3951 latter is that the contents are printed in the proper place, thus you do
3952 not need to rearrange the DVI file with @command{dviselect} or shuffle
3955 @findex setcontentsaftertitlepage
3956 @findex setshortcontentsaftertitlepage
3957 @cindex Contents, after title page
3958 @cindex Table of contents, after title page
3959 As an author, you can put the contents commands wherever you prefer.
3960 But if you are a user simply printing a manual, you may wish to print
3961 the contents after the title page even if the author put the contents
3962 commands at the end of the document (as is the case in most existing
3963 Texinfo documents, at this writing). You can do this by specifying
3964 @code{@@setcontentsaftertitlepage} and/or
3965 @code{@@setshortcontentsaftertitlepage}. The first prints only the main
3966 contents after the @code{@@end titlepage}; the second prints both the
3967 short contents and the main contents. In either case, any subsequent
3968 @code{@@contents} or @code{@@shortcontents} is ignored (unless no
3969 @code{@@end titlepage} is ever encountered).
3971 You need to include the @code{@@set@dots{}contentsaftertitlepage}
3972 commands early in the document (just after @code{@@setfilename}, for
3973 example). We recommend using @command{texi2dvi} (@pxref{Format with
3974 texi2dvi}) to specify this without altering the source file at all. For
3977 texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
3982 @section @code{@@bye} File Ending
3985 An @code{@@bye} command terminates @TeX{} or Info formatting. None of
3986 the formatting commands reading anything following @code{@@bye}. The
3987 @code{@@bye} command should be on a line by itself.
3989 If you wish, you may follow the @code{@@bye} line with notes. These
3990 notes will not be formatted and will not appear in either Info or a
3991 printed manual; it is as if text after @code{@@bye} were within
3992 @code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
3993 @code{@@bye} line with a local variables list for Emacs.
3994 @xref{Compile-Command, , Using Local Variables and the Compile Command},
3995 for more information.
3999 @chapter Chapter Structuring
4000 @cindex Chapter structuring
4001 @cindex Structuring of chapters
4003 The @dfn{chapter structuring} commands divide a document into a hierarchy of
4004 chapters, sections, subsections, and subsubsections. These commands
4005 generate large headings; they also provide information for the table
4006 of contents of a printed manual (@pxref{Contents, , Generating a Table
4007 of Contents}).@refill
4009 The chapter structuring commands do not create an Info node structure,
4010 so normally you should put an @code{@@node} command immediately before
4011 each chapter structuring command (@pxref{Nodes}). The only time you
4012 are likely to use the chapter structuring commands without using the
4013 node structuring commands is if you are writing a document that
4014 contains no cross references and will never be transformed into Info
4017 It is unlikely that you will ever write a Texinfo file that is
4018 intended only as an Info file and not as a printable document. If you
4019 do, you might still use chapter structuring commands to create a
4020 heading at the top of each node---but you don't need to.@refill
4023 * Tree Structuring:: A manual is like an upside down tree @dots{}
4024 * Structuring Command Types:: How to divide a manual into parts.
4025 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
4027 * unnumbered & appendix::
4028 * majorheading & chapheading::
4030 * unnumberedsec appendixsec heading::
4032 * unnumberedsubsec appendixsubsec subheading::
4033 * subsubsection:: Commands for the lowest level sections.
4034 * Raise/lower sections:: How to change commands' hierarchical level.
4038 @node Tree Structuring
4039 @section Tree Structure of Sections
4040 @cindex Tree structuring
4042 A Texinfo file is usually structured like a book with chapters,
4043 sections, subsections, and the like. This structure can be visualized
4044 as a tree (or rather as an upside-down tree) with the root at the top
4045 and the levels corresponding to chapters, sections, subsection, and
4046 subsubsections.@refill
4048 Here is a diagram that shows a Texinfo file with three chapters,
4049 each of which has two sections.@refill
4055 -------------------------------------
4057 Chapter 1 Chapter 2 Chapter 3
4059 -------- -------- --------
4061 Section Section Section Section Section Section
4062 1.1 1.2 2.1 2.2 3.1 3.2
4067 In a Texinfo file that has this structure, the beginning of Chapter 2
4068 looks like this:@refill
4072 @@node Chapter 2, Chapter 3, Chapter 1, top
4077 The chapter structuring commands are described in the sections that
4078 follow; the @code{@@node} and @code{@@menu} commands are described in
4079 following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
4082 @node Structuring Command Types
4083 @section Structuring Command Types
4085 The chapter structuring commands fall into four groups or series, each
4086 of which contains structuring commands corresponding to the
4087 hierarchical levels of chapters, sections, subsections, and
4088 subsubsections.@refill
4090 The four groups are the @code{@@chapter} series, the
4091 @code{@@unnumbered} series, the @code{@@appendix} series, and the
4092 @code{@@heading} series.@refill
4094 Each command produces titles that have a different appearance on the
4095 printed page or Info file; only some of the commands produce
4096 titles that are listed in the table of contents of a printed book or
4101 The @code{@@chapter} and @code{@@appendix} series of commands produce
4102 numbered or lettered entries both in the body of a printed work and in
4103 its table of contents.@refill
4106 The @code{@@unnumbered} series of commands produce unnumbered entries
4107 both in the body of a printed work and in its table of contents. The
4108 @code{@@top} command, which has a special use, is a member of this
4109 series (@pxref{makeinfo top, , @code{@@top}}).@refill
4112 The @code{@@heading} series of commands produce unnumbered headings
4113 that do not appear in a table of contents. The heading commands never
4114 start a new page.@refill
4117 The @code{@@majorheading} command produces results similar to using
4118 the @code{@@chapheading} command but generates a larger vertical
4119 whitespace before the heading.@refill
4122 When an @code{@@setchapternewpage} command says to do so, the
4123 @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
4124 start new pages in the printed manual; the @code{@@heading} commands
4128 Here are the four groups of chapter structuring commands:
4131 {\globaldefs = 1 \smallfonts}
4134 @multitable @columnfractions .19 .30 .29 .22
4135 @item @tab @tab @tab No new page
4136 @item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered}
4137 @item In contents @tab In contents @tab In contents @tab Omitted from@*contents
4138 @item @tab @code{@@top} @tab @tab @code{@@majorheading}
4139 @item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading}
4140 @item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading}
4141 @item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading}
4142 @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
4145 {\globaldefs = 1 \textfonts}
4150 @section @code{@@top}
4152 The @code{@@top} command is a special sectioning command that you use
4153 only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4154 The @code{@@top} command tells the @code{makeinfo} formatter which node
4155 is the `Top' node, so it can use it as the root of the node tree if your
4156 manual uses implicit pointers. It has the same typesetting effect as
4157 @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
4158 and @code{@@appendix}}). For detailed information, see @ref{makeinfo
4159 top command, , The @code{@@top} Command}.
4161 The @code{@@top} node and its menu (if any) is conventionally wrapped in
4162 an @code{@@ifnottex} conditional so that it will appear only in Info and
4163 HTML output, not @TeX{}.
4166 @node chapter, unnumbered & appendix, makeinfo top, Structuring
4167 @comment node-name, next, previous, up
4168 @section @code{@@chapter}
4171 @code{@@chapter} identifies a chapter in the document. Write the
4172 command at the beginning of a line and follow it on the same line by
4173 the title of the chapter.@refill
4175 For example, this chapter in this manual is entitled ``Chapter
4176 Structuring''; the @code{@@chapter} line looks like this:@refill
4179 @@chapter Chapter Structuring
4182 In @TeX{}, the @code{@@chapter} command creates a chapter in the
4183 document, specifying the chapter title. The chapter is numbered
4184 automatically.@refill
4186 In Info, the @code{@@chapter} command causes the title to appear on a
4187 line by itself, with a line of asterisks inserted underneath. Thus,
4188 in Info, the above example produces the following output:@refill
4196 Texinfo also provides a command @code{@@centerchap}, which is analogous
4197 to @code{@@unnumbered}, but centers its argument in the printed output.
4198 This kind of stylistic choice is not usually offered by Texinfo.
4199 @c but the Hacker's Dictionary wanted it ...
4202 @node unnumbered & appendix
4203 @section @code{@@unnumbered} and @code{@@appendix}
4207 Use the @code{@@unnumbered} command to create a chapter that appears
4208 in a printed manual without chapter numbers of any kind. Use the
4209 @code{@@appendix} command to create an appendix in a printed manual
4210 that is labelled by letter instead of by number.@refill
4212 For Info file output, the @code{@@unnumbered} and @code{@@appendix}
4213 commands are equivalent to @code{@@chapter}: the title is printed on a
4214 line by itself with a line of asterisks underneath. (@xref{chapter, ,
4215 @code{@@chapter}}.)@refill
4217 To create an appendix or an unnumbered chapter, write an
4218 @code{@@appendix} or @code{@@unnumbered} command at the beginning of a
4219 line and follow it on the same line by the title, as you would if you
4220 were creating a chapter.@refill
4223 @node majorheading & chapheading, section, unnumbered & appendix, Structuring
4224 @section @code{@@majorheading}, @code{@@chapheading}
4225 @findex majorheading
4228 The @code{@@majorheading} and @code{@@chapheading} commands put
4229 chapter-like headings in the body of a document.@refill
4231 However, neither command causes @TeX{} to produce a numbered heading
4232 or an entry in the table of contents; and neither command causes
4233 @TeX{} to start a new page in a printed manual.@refill
4235 In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4236 whitespace before the heading than an @code{@@chapheading} command but
4237 is otherwise the same.@refill
4240 the @code{@@majorheading} and
4241 @code{@@chapheading} commands are equivalent to
4242 @code{@@chapter}: the title is printed on a line by itself with a line
4243 of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
4245 @node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
4246 @comment node-name, next, previous, up
4247 @section @code{@@section}
4250 In a printed manual, an @code{@@section} command identifies a
4251 numbered section within a chapter. The section title appears in the
4252 table of contents. In Info, an @code{@@section} command provides a
4253 title for a segment of text, underlined with @samp{=}.@refill
4255 This section is headed with an @code{@@section} command and looks like
4256 this in the Texinfo file:@refill
4259 @@section @@code@{@@@@section@}
4262 To create a section, write the @code{@@section} command at the
4263 beginning of a line and follow it on the same line by the section
4269 @@section This is a section
4285 @node unnumberedsec appendixsec heading, subsection, section, Structuring
4286 @comment node-name, next, previous, up
4287 @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
4288 @findex unnumberedsec
4292 The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4293 commands are, respectively, the unnumbered, appendix-like, and
4294 heading-like equivalents of the @code{@@section} command.
4295 (@xref{section, , @code{@@section}}.)@refill
4298 @item @@unnumberedsec
4299 The @code{@@unnumberedsec} command may be used within an
4300 unnumbered chapter or within a regular chapter or appendix to
4301 provide an unnumbered section.@refill
4304 @itemx @@appendixsection
4305 @code{@@appendixsection} is a longer spelling of the
4306 @code{@@appendixsec} command; the two are synonymous.@refill
4307 @findex appendixsection
4309 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4310 command is used only within appendices.@refill
4313 You may use the @code{@@heading} command anywhere you wish for a
4314 section-style heading that will not appear in the table of contents.@refill
4317 @node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
4318 @comment node-name, next, previous, up
4319 @section The @code{@@subsection} Command
4322 Subsections are to sections as sections are to chapters.
4323 (@xref{section, , @code{@@section}}.) In Info, subsection titles are
4324 underlined with @samp{-}. For example,@refill
4327 @@subsection This is a subsection
4335 This is a subsection
4336 --------------------
4340 In a printed manual, subsections are listed in the table of contents
4341 and are numbered three levels deep.@refill
4343 @node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
4344 @comment node-name, next, previous, up
4345 @section The @code{@@subsection}-like Commands
4346 @cindex Subsection-like commands
4347 @findex unnumberedsubsec
4348 @findex appendixsubsec
4351 The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4352 @code{@@subheading} commands are, respectively, the unnumbered,
4353 appendix-like, and heading-like equivalents of the @code{@@subsection}
4354 command. (@xref{subsection, , @code{@@subsection}}.)@refill
4356 In Info, the @code{@@subsection}-like commands generate a title
4357 underlined with hyphens. In a printed manual, an @code{@@subheading}
4358 command produces a heading like that of a subsection except that it is
4359 not numbered and does not appear in the table of contents. Similarly,
4360 an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4361 that of a subsection and an @code{@@appendixsubsec} command produces a
4362 subsection-like heading labelled with a letter and numbers; both of
4363 these commands produce headings that appear in the table of
4366 @node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
4367 @comment node-name, next, previous, up
4368 @section The `subsub' Commands
4369 @cindex Subsub commands
4370 @findex subsubsection
4371 @findex unnumberedsubsubsec
4372 @findex appendixsubsubsec
4373 @findex subsubheading
4375 The fourth and lowest level sectioning commands in Texinfo are the
4376 `subsub' commands. They are:@refill
4379 @item @@subsubsection
4380 Subsubsections are to subsections as subsections are to sections.
4381 (@xref{subsection, , @code{@@subsection}}.) In a printed manual,
4382 subsubsection titles appear in the table of contents and are numbered
4383 four levels deep.@refill
4385 @item @@unnumberedsubsubsec
4386 Unnumbered subsubsection titles appear in the table of contents of a
4387 printed manual, but lack numbers. Otherwise, unnumbered
4388 subsubsections are the same as subsubsections. In Info, unnumbered
4389 subsubsections look exactly like ordinary subsubsections.@refill
4391 @item @@appendixsubsubsec
4392 Conventionally, appendix commands are used only for appendices and are
4393 lettered and numbered appropriately in a printed manual. They also
4394 appear in the table of contents. In Info, appendix subsubsections look
4395 exactly like ordinary subsubsections.@refill
4397 @item @@subsubheading
4398 The @code{@@subsubheading} command may be used anywhere that you need
4399 a small heading that will not appear in the table of contents. In
4400 Info, subsubheadings look exactly like ordinary subsubsection
4404 In Info, `subsub' titles are underlined with periods.
4408 @@subsubsection This is a subsubsection
4416 This is a subsubsection
4417 .......................
4421 @node Raise/lower sections, , subsubsection, Structuring
4422 @comment node-name, next, previous, up
4423 @section @code{@@raisesections} and @code{@@lowersections}
4424 @findex raisesections
4425 @findex lowersections
4426 @cindex Raising and lowering sections
4427 @cindex Sections, raising and lowering
4429 The @code{@@raisesections} and @code{@@lowersections} commands raise and
4430 lower the hierarchical level of chapters, sections, subsections and the
4431 like. The @code{@@raisesections} command changes sections to chapters,
4432 subsections to sections, and so on. The @code{@@lowersections} command
4433 changes chapters to sections, sections to subsections, and so on.
4435 @cindex Include files, and section levels
4436 An @code{@@lowersections} command is useful if you wish to include text
4437 that is written as an outer or standalone Texinfo file in another
4438 Texinfo file as an inner, included file. If you write the command at
4439 the beginning of the file, all your @code{@@chapter} commands are
4440 formatted as if they were @code{@@section} commands, all your
4441 @code{@@section} command are formatted as if they were
4442 @code{@@subsection} commands, and so on.
4445 @code{@@raisesections} raises a command one level in the chapter
4446 structuring hierarchy:@refill
4452 @@subsection @@section,
4453 @@section @@chapter,
4454 @@heading @@chapheading,
4460 @code{@@lowersections} lowers a command one level in the chapter
4461 structuring hierarchy:@refill
4467 @@chapter @@section,
4468 @@subsection @@subsubsection,
4469 @@heading @@subheading,
4474 An @code{@@raisesections} or @code{@@lowersections} command changes only
4475 those structuring commands that follow the command in the Texinfo file.
4476 Write an @code{@@raisesections} or @code{@@lowersections} command on a
4479 An @code{@@lowersections} command cancels an @code{@@raisesections}
4480 command, and vice versa. Typically, the commands are used like this:
4484 @@include somefile.texi
4488 Without the @code{@@raisesections}, all the subsequent sections in your
4489 document will be lowered.
4491 Repeated use of the commands continue to raise or lower the hierarchical
4492 level a step at a time.
4494 An attempt to raise above `chapters' reproduces chapter commands; an
4495 attempt to lower below `subsubsections' reproduces subsubsection
4501 @dfn{Nodes} are the primary segments of a Texinfo file. They do not
4502 themselves impose a hierarchical or any other kind of structure on a file.
4503 Nodes contain @dfn{node pointers} that name other nodes, and can contain
4504 @dfn{menus} which are lists of nodes. In Info, the movement commands
4505 can carry you to a pointed-to node or to a node listed in a menu. Node
4506 pointers and menus provide structure for Info files just as chapters,
4507 sections, subsections, and the like, provide structure for printed
4511 * Two Paths:: Different commands to structure
4512 Info output and printed output.
4513 * Node Menu Illustration:: A diagram, and sample nodes and menus.
4514 * node:: Creating nodes, in detail.
4515 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
4516 * anchor:: Defining arbitrary cross-reference targets.
4523 The node and menu commands and the chapter structuring commands are
4524 technically independent of each other:
4528 In Info, node and menu commands provide structure. The chapter
4529 structuring commands generate headings with different kinds of
4530 underlining---asterisks for chapters, hyphens for sections, and so on;
4531 they do nothing else.@refill
4534 In @TeX{}, the chapter structuring commands generate chapter and section
4535 numbers and tables of contents. The node and menu commands provide
4536 information for cross references; they do nothing else.@refill
4539 You can use node pointers and menus to structure an Info file any way
4540 you want; and you can write a Texinfo file so that its Info output has a
4541 different structure than its printed output. However, virtually all
4542 Texinfo files are written such that the structure for the Info output
4543 corresponds to the structure for the printed output. It is neither
4544 convenient nor understandable to the reader to do otherwise.@refill
4546 Generally, printed output is structured in a tree-like hierarchy in
4547 which the chapters are the major limbs from which the sections branch
4548 out. Similarly, node pointers and menus are organized to create a
4549 matching structure in the Info output.@refill
4552 @node Node Menu Illustration
4553 @section Node and Menu Illustration
4555 Here is a copy of the diagram shown earlier that illustrates a Texinfo
4556 file with three chapters, each of which contains two sections.@refill
4558 The ``root'' is at the top of the diagram and the ``leaves'' are at the
4559 bottom. This is how such a diagram is drawn conventionally; it
4560 illustrates an upside-down tree. For this reason, the root node is
4561 called the `Top' node, and `Up' node pointers carry you closer to the
4568 -------------------------------------
4570 Chapter 1 Chapter 2 Chapter 3
4572 -------- -------- --------
4574 Section Section Section Section Section Section
4575 1.1 1.2 2.1 2.2 3.1 3.2
4579 The fully-written command to start Chapter 2 would be this:
4583 @@node Chapter 2, Chapter 3, Chapter 1, Top
4584 @@comment node-name, next, previous, up
4589 This @code{@@node} line says that the name of this node is ``Chapter
4590 2'', the name of the `Next' node is ``Chapter 3'', the name of the
4591 `Previous' node is ``Chapter 1'', and the name of the `Up' node is
4592 ``Top''. You can omit writing out these node names if your document is
4593 hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
4594 pointer relationships still obtain.
4597 @strong{Please Note:} `Next' refers to the next node at the same
4598 hierarchical level in the manual, not necessarily to the next node
4599 within the Texinfo file. In the Texinfo file, the subsequent node may
4600 be at a lower level---a section-level node most often follows a
4601 chapter-level node, for example. `Next' and `Previous' refer to nodes
4602 at the @emph{same} hierarchical level. (The `Top' node contains the
4603 exception to this rule. Since the `Top' node is the only node at that
4604 level, `Next' refers to the first following node, which is almost always
4605 a chapter or chapter-level node.)@refill
4608 To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
4609 2. (@xref{Menus}.) You would write the menu just
4610 before the beginning of Section 2.1, like this:@refill
4615 * Sect. 2.1:: Description of this section.
4621 Write the node for Sect. 2.1 like this:@refill
4625 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4626 @@comment node-name, next, previous, up
4630 In Info format, the `Next' and `Previous' pointers of a node usually
4631 lead to other nodes at the same level---from chapter to chapter or from
4632 section to section (sometimes, as shown, the `Previous' pointer points
4633 up); an `Up' pointer usually leads to a node at the level above (closer
4634 to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4635 to `leaves'). (A cross reference can point to a node at any level;
4636 see @ref{Cross References}.)@refill
4638 Usually, an @code{@@node} command and a chapter structuring command are
4639 used in sequence, along with indexing commands. (You may follow the
4640 @code{@@node} line with a comment line that reminds you which pointer is
4643 Here is the beginning of the chapter in this manual called ``Ending a
4644 Texinfo File''. This shows an @code{@@node} line followed by a comment
4645 line, an @code{@@chapter} line, and then by indexing lines.@refill
4649 @@node Ending a File, Structuring, Beginning a File, Top
4650 @@comment node-name, next, previous, up
4651 @@chapter Ending a Texinfo File
4652 @@cindex Ending a Texinfo file
4653 @@cindex Texinfo file ending
4654 @@cindex File ending
4660 @section The @code{@@node} Command
4662 @cindex Node, defined
4665 A @dfn{node} is a segment of text that begins at an @code{@@node}
4666 command and continues until the next @code{@@node} command. The
4667 definition of node is different from that for chapter or section. A
4668 chapter may contain sections and a section may contain subsections;
4669 but a node cannot contain subnodes; the text of a node continues only
4670 until the next @code{@@node} command in the file. A node usually
4671 contains only one chapter structuring command, the one that follows
4672 the @code{@@node} line. On the other hand, in printed output nodes
4673 are used only for cross references, so a chapter or section may
4674 contain any number of nodes. Indeed, a chapter usually contains
4675 several nodes, one for each section, subsection, and
4676 subsubsection.@refill
4678 To create a node, write an @code{@@node} command at the beginning of a
4679 line, and follow it with up to four arguments, separated by commas, on
4680 the rest of the same line. The first argument is required; it is the
4681 name of this node. The subsequent arguments are the names of the
4682 `Next', `Previous', and `Up' pointers, in that order, and may be omitted
4683 if your Texinfo document is hierarchically organized (@pxref{makeinfo
4686 You may insert spaces before each name if you wish; the spaces are
4687 ignored. You must write the name of the node and the names of the
4688 `Next', `Previous', and `Up' pointers all on the same line. Otherwise,
4689 the formatters fail. (@inforef{Top, info, info}, for more information
4690 about nodes in Info.)
4692 Usually, you write one of the chapter-structuring command lines
4693 immediately after an @code{@@node} line---for example, an
4694 @code{@@section} or @code{@@subsection} line. (@xref{Structuring
4698 @strong{Please note:} The GNU Emacs Texinfo mode updating commands work
4699 only with Texinfo files in which @code{@@node} lines are followed by chapter
4700 structuring lines. @xref{Updating Requirements}.@refill
4703 @TeX{} uses @code{@@node} lines to identify the names to use for cross
4704 references. For this reason, you must write @code{@@node} lines in a
4705 Texinfo file that you intend to format for printing, even if you do not
4706 intend to format it for Info. (Cross references, such as the one at the
4707 end of this sentence, are made with @code{@@xref} and related commands;
4708 see @ref{Cross References}.)@refill
4711 * Node Names:: How to choose node and pointer names.
4712 * Writing a Node:: How to write an @code{@@node} line.
4713 * Node Line Tips:: Keep names short.
4714 * Node Line Requirements:: Keep names unique, without @@-commands.
4715 * First Node:: How to write a `Top' node.
4716 * makeinfo top command:: How to use the @code{@@top} command.
4721 @subsection Choosing Node and Pointer Names
4723 @cindex Node names, choosing
4724 The name of a node identifies the node. The pointers enable
4725 you to reach other nodes and consist of the names of those nodes.@refill
4727 Normally, a node's `Up' pointer contains the name of the node whose menu
4728 mentions that node. The node's `Next' pointer contains the name of the
4729 node that follows that node in that menu and its `Previous' pointer
4730 contains the name of the node that precedes it in that menu. When a
4731 node's `Previous' node is the same as its `Up' node, both node pointers
4732 name the same node.@refill
4734 Usually, the first node of a Texinfo file is the `Top' node, and its
4735 `Up' and `Previous' pointers point to the @file{dir} file, which
4736 contains the main menu for all of Info.@refill
4738 The `Top' node itself contains the main or master menu for the manual.
4739 Also, it is helpful to include a brief description of the manual in the
4740 `Top' node. @xref{First Node}, for information on how to write the
4741 first node of a Texinfo file.@refill
4743 Even when you explicitly specify all pointers, that does not mean you
4744 can write the nodes in the Texinfo source file in an arbitrary order!
4745 Because @TeX{} processes the file sequentially, irrespective of node
4746 pointers, you must write the nodes in the order you wish them to appear
4747 in the printed output.
4750 @node Writing a Node
4751 @subsection How to Write an @code{@@node} Line
4752 @cindex Writing an @code{@@node} line
4753 @cindex @code{@@node} line writing
4754 @cindex Node line writing
4756 The easiest way to write an @code{@@node} line is to write @code{@@node}
4757 at the beginning of a line and then the name of the node, like
4761 @@node @var{node-name}
4764 If you are using GNU Emacs, you can use the update node commands
4765 provided by Texinfo mode to insert the names of the pointers; or you
4766 can leave the pointers out of the Texinfo file and let @code{makeinfo}
4767 insert node pointers into the Info file it creates. (@xref{Texinfo
4768 Mode}, and @ref{makeinfo Pointer Creation}.)@refill
4770 Alternatively, you can insert the `Next', `Previous', and `Up'
4771 pointers yourself. If you do this, you may find it helpful to use the
4772 Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
4773 @samp{@@node} and a comment line listing the names of the pointers in
4774 their proper order. The comment line helps you keep track of which
4775 arguments are for which pointers. This comment line is especially useful
4776 if you are not familiar with Texinfo.@refill
4778 The template for a fully-written-out node line with `Next', `Previous',
4779 and `Up' pointers looks like this:@refill
4782 @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4785 If you wish, you can ignore @code{@@node} lines altogether in your first
4786 draft and then use the @code{texinfo-insert-node-lines} command to
4787 create @code{@@node} lines for you. However, we do not recommend this
4788 practice. It is better to name the node itself at the same time that
4789 you write a segment so you can easily make cross references. A large
4790 number of cross references are an especially important feature of a good
4793 After you have inserted an @code{@@node} line, you should immediately
4794 write an @@-command for the chapter or section and insert its name.
4795 Next (and this is important!), put in several index entries. Usually,
4796 you will find at least two and often as many as four or five ways of
4797 referring to the node in the index. Use them all. This will make it
4798 much easier for people to find the node.
4801 @node Node Line Tips
4802 @subsection @code{@@node} Line Tips
4804 Here are three suggestions:
4808 Try to pick node names that are informative but short.@refill
4810 In the Info file, the file name, node name, and pointer names are all
4811 inserted on one line, which may run into the right edge of the window.
4812 (This does not cause a problem with Info, but is ugly.)@refill
4815 Try to pick node names that differ from each other near the beginnings
4816 of their names. This way, it is easy to use automatic name completion in
4820 By convention, node names are capitalized just as they would be for
4821 section or chapter titles---initial and significant words are
4822 capitalized; others are not.@refill
4826 @node Node Line Requirements, First Node, Node Line Tips, node
4827 @subsection @code{@@node} Line Requirements
4829 @cindex Node line requirements
4830 @cindex Restrictions on node names
4831 Here are several requirements for @code{@@node} lines:
4834 @cindex Unique nodename requirement
4835 @cindex Node name must be unique
4837 All the node names for a single Info file must be unique.@refill
4839 Duplicates confuse the Info movement commands. This means, for
4840 example, that if you end every chapter with a summary, you must name
4841 each summary node differently. You cannot just call each one
4842 ``Summary''. You may, however, duplicate the titles of chapters, sections,
4843 and the like. Thus you can end each chapter in a book with a section
4844 called ``Summary'', so long as the node names for those sections are all
4848 A pointer name must be the name of a node.@refill
4850 The node to which a pointer points may come before or after the
4851 node containing the pointer.
4853 @cindex @@-commands in nodename
4854 @cindex Node name, should not contain @@-commands
4856 @w{@@-commands} used in node names generally confuse Info, so you
4857 should avoid them. This includes punctuation characters that are
4858 escaped with a @samp{@@}, such as @code{@@} and @code{@{}. For a few
4859 rare cases when this is useful, Texinfo has limited support for using
4860 @w{@@-commands} in node names; see @ref{Pointer Validation}.
4863 Thus, the beginning of the section called @code{@@chapter} looks like
4868 @@node chapter, unnumbered & appendix, makeinfo top, Structuring
4869 @@comment node-name, next, previous, up
4870 @@section @@code@{@@@@chapter@}
4876 @cindex Parentheses in nodename
4877 You cannot use parentheses in node names, because a node name such as
4878 @samp{(foo)bar} is interpreted by the Info readers as a node
4879 @samp{bar} in an Info file @file{foo}.
4882 @cindex Apostrophe in nodename
4883 @cindex Colon in nodename
4884 @cindex Comma in nodename
4885 @cindex Period in nodename
4886 @cindex Characters, invalid in node name
4887 @cindex Invalid characters in node names
4888 Unfortunately, you cannot use periods, commas, colons or apostrophes
4889 within a node name; these confuse @TeX{} or the Info formatters.
4892 For example, the following is a section title:
4895 @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
4899 The corresponding node name is:
4902 unnumberedsec appendixsec heading
4905 @cindex Case in node name
4907 Case is significant.
4912 @subsection The First Node
4913 @cindex Top node is first
4916 The first node of a Texinfo file is the @dfn{Top} node, except in an
4917 included file (@pxref{Include Files}). The Top node should contain a
4918 short summary, copying permissions, and a master menu. @xref{The Top
4919 Node}, for more information on the Top node contents and examples.
4921 Here is a description of the node pointers to be used in the Top node:
4926 @cindex Up node of Top node
4927 @cindex (dir) as Up node of Top node
4928 The Top node (which must be named @samp{top} or @samp{Top}) should have
4929 as its `Up' node the name of a node in another file, where there is a
4930 menu that leads to this file. Specify the file name in parentheses.
4932 Usually, all Info files are installed in the same Info directory tree;
4933 in this case, use @samp{(dir)} as the parent of the Top node; this is
4934 short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
4935 file, which contains the main menu for the Info system as a whole.
4938 @cindex Previous node of Top node
4939 On the other hand, do not define the `Previous' node of the Top node to
4940 be @samp{(dir)}, as it causes confusing behavior for users: if you are
4941 in the Top node and hits @key{DEL} to go backwards, you wind up in the
4942 middle of the some other entry in the @file{dir} file, which has nothing
4943 to do with what you were reading.
4946 @cindex Next node of Top node
4947 The `Next' node of the Top node should be the first chapter in your
4952 @xref{Installing an Info File}, for more information about installing
4953 an Info file in the @file{info} directory.
4955 For concreteness, here is an example with explicit pointers (which you
4956 can maintain automatically with the texinfo mode commands):
4958 Or you can leave the pointers off entirely and let the tools implicitly
4959 define them. This is recommended. Thus:
4966 @node makeinfo top command
4967 @subsection The @code{@@top} Sectioning Command
4968 @findex top @r{(@@-command)}
4970 A special sectioning command, @code{@@top} should be used with the
4971 @code{@@node Top} line. The @code{@@top} sectioning command tells
4972 @code{makeinfo} that it marks the `Top' node in the file. It provides
4973 the information that @code{makeinfo} needs to insert node pointers
4974 automatically. Write the @code{@@top} command at the beginning of the
4975 line immediately following the @code{@@node Top} line. Write the title
4976 on the remaining part of the same line as the @code{@@top} command.
4978 In Info, the @code{@@top} sectioning command causes the title to appear
4979 on a line by itself, with a line of asterisks inserted underneath, as
4980 other sectioning commands do.
4982 In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
4983 sectioning command is merely a synonym for @code{@@unnumbered}.
4984 Neither of these formatters require an @code{@@top} command, and do
4985 nothing special with it. You can use @code{@@chapter} or
4986 @code{@@unnumbered} after the @code{@@node Top} line when you use
4987 these formatters. Also, you can use @code{@@chapter} or
4988 @code{@@unnumbered} when you use the Texinfo updating commands to
4989 create or update pointers and menus.
4991 Thus, in practice, a Top node starts like this:
4995 @@top Your Manual Title
4999 @node makeinfo Pointer Creation
5000 @section Creating Pointers with @code{makeinfo}
5001 @cindex Creating pointers with @code{makeinfo}
5002 @cindex Pointer creation with @code{makeinfo}
5003 @cindex Automatic pointer creation with @code{makeinfo}
5005 The @code{makeinfo} program has a feature for automatically defining
5006 node pointers for a hierarchically organized file.
5008 When you take advantage of this feature, you do not need to write the
5009 `Next', `Previous', and `Up' pointers after the name of a node.
5010 However, you must write a sectioning command, such as @code{@@chapter}
5011 or @code{@@section}, on the line immediately following each truncated
5012 @code{@@node} line (except that comment lines may intervene).
5014 In addition, you must follow the `Top' @code{@@node} line with a line
5015 beginning with @code{@@top} to mark the `Top' node in the
5016 file. @xref{makeinfo top, , @code{@@top}}.
5018 Finally, you must write the name of each node (except for the `Top'
5019 node) in a menu that is one or more hierarchical levels above the
5020 node's hierarchical level.
5022 This node pointer insertion feature in @code{makeinfo} relieves you from
5023 the need to update menus and pointers manually or with Texinfo mode
5024 commands. (@xref{Updating Nodes and Menus}.)
5026 In most cases, you will want to take advantage of this feature and not
5027 redundantly specify node pointers. However, Texinfo documents are not
5028 required to be organized hierarchically or in fact contain sectioning
5029 commands at all. For example, if you never intend the document to be
5030 printed. In those cases, you will need to explicitly specify the pointers.
5034 @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
5038 @cindex Cross-reference targets, arbitrary
5039 @cindex Targets for cross-references, arbitrary
5041 An @dfn{anchor} is a position in your document, labeled so that
5042 cross-references can refer to it, just as they can to nodes. You create
5043 an anchor with the @code{@@anchor} command, and give the label as a
5044 normal brace-delimited argument. For example:
5047 This marks the @@anchor@{x-spot@}spot.
5049 @@xref@{x-spot,,the spot@}.
5055 This marks the spot.
5057 See [the spot], page 1.
5060 As you can see, the @code{@@anchor} command itself produces no output.
5061 This example defines an anchor `x-spot' just before the word `spot'.
5062 You can refer to it later with an @code{@@xref} or other cross-reference
5063 command, as shown. @xref{Cross References}, for details on the
5064 cross-reference commands.
5066 It is best to put @code{@@anchor} commands just before the position you
5067 wish to refer to; that way, the reader's eye is led on to the correct
5068 text when they jump to the anchor. You can put the @code{@@anchor}
5069 command on a line by itself if that helps readability of the source.
5070 Spaces are always ignored after @code{@@anchor}.
5072 Anchor names and node names may not conflict. Anchors and nodes are
5073 given similar treatment in some ways; for example, the @code{goto-node}
5074 command in standalone Info takes either an anchor name or a node name as
5075 an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
5083 @dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can
5084 carry you to any node, regardless of the hierarchical structure; even to
5085 nodes in a different Info file. However, the GNU Emacs Texinfo mode
5086 updating commands work only to create menus of subordinate nodes.
5087 Conventionally, cross references are used to refer to other nodes.} In
5088 Info, you use menus to go to such nodes. Menus have no effect in
5089 printed manuals and do not appear in them.
5091 By convention, a menu is put at the end of a node since a reader who
5092 uses the menu may not see text that follows it. Furthermore, a node
5093 that has a menu should not contain much text. If you have a lot of text
5094 and a menu, move most of the text into a new subnode---all but a few
5095 lines. Otherwise, a reader with a terminal that displays only a few
5096 lines may miss the menu and its associated text. As a practical matter,
5097 you should locate a menu within 20 lines of the beginning of the
5101 * Menu Location:: Put a menu in a short node.
5102 * Writing a Menu:: What is a menu?
5103 * Menu Parts:: A menu entry has three parts.
5104 * Less Cluttered Menu Entry:: Two part menu entry.
5105 * Menu Example:: Two and three part menu entries.
5106 * Other Info Files:: How to refer to a different Info file.
5110 @node Menu Location, Writing a Menu, Menus, Menus
5112 @heading Menus Need Short Nodes
5114 @cindex Menu location
5115 @cindex Location of menus
5116 @cindex Nodes for menus are short
5117 @cindex Short nodes for menus
5119 The short text before a menu may look awkward in a printed manual. To
5120 avoid this, you can write a menu near the beginning of its node and
5121 follow the menu by an @code{@@node} line, and then an @code{@@heading}
5122 line located within @code{@@ifinfo} and @code{@@end ifinfo}. This way,
5123 the menu, @code{@@node} line, and title appear only in the Info file,
5124 not the printed document.
5126 For example, the preceding two paragraphs follow an Info-only menu,
5127 @code{@@node} line, and heading, and look like this:
5132 * Menu Location:: Put a menu in a short node.
5133 * Writing a Menu:: What is a menu?
5134 * Menu Parts:: A menu entry has three parts.
5135 * Less Cluttered Menu Entry:: Two part menu entry.
5136 * Menu Example:: Two and three part entries.
5137 * Other Info Files:: How to refer to a different
5141 @@node Menu Location, Writing a Menu, , Menus
5143 @@heading Menus Need Short Nodes
5148 The Texinfo file for this document contains a number of
5149 examples of this procedure; one is at the beginning of this chapter.
5152 @node Writing a Menu, Menu Parts, Menu Location, Menus
5153 @section Writing a Menu
5154 @cindex Writing a menu
5155 @cindex Menu writing
5157 A menu consists of an @code{@@menu} command on a line by
5158 itself followed by menu entry lines or menu comment lines
5159 and then by an @code{@@end menu} command on a line by
5162 A menu looks like this:@refill
5167 Larger Units of Text
5169 * Files:: All about handling files.
5170 * Multiples: Buffers. Multiple buffers; editing
5171 several files at once.
5176 In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
5177 entry}. (Note the space after the asterisk.) A line that does not
5178 start with an @w{@samp{* }} may also appear in a menu. Such a line is
5179 not a menu entry but is a menu comment line that appears in the Info
5180 file. In the example above, the line @samp{Larger Units of Text} is a
5181 menu comment line; the two lines starting with @w{@samp{* }} are menu
5182 @cindex Spaces, in menus
5183 entries. Space characters in a menu are preserved as-is; this allows
5184 you to format the menu as you wish.
5187 @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
5188 @section The Parts of a Menu
5189 @cindex Parts of a menu
5191 @cindex @code{@@menu} parts
5193 A menu entry has three parts, only the second of which is required:
5197 The menu entry name (optional).
5200 The name of the node (required).
5203 A description of the item (optional).
5206 The template for a menu entry looks like this:@refill
5209 * @var{menu-entry-name}: @var{node-name}. @var{description}
5212 Follow the menu entry name with a single colon and follow the node name
5213 with tab, comma, period, or newline.@refill
5215 In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5216 command. The menu entry name is what the user types after the @kbd{m}
5219 The third part of a menu entry is a descriptive phrase or sentence.
5220 Menu entry names and node names are often short; the description
5221 explains to the reader what the node is about. A useful description
5222 complements the node name rather than repeats it. The description,
5223 which is optional, can spread over two or more lines; if it does, some
5224 authors prefer to indent the second line while others prefer to align it
5225 with the first (and all others). It's up to you.
5228 @node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
5229 @comment node-name, next, previous, up
5230 @section Less Cluttered Menu Entry
5231 @cindex Two part menu entry
5232 @cindex Double-colon menu entries
5233 @cindex Menu entries with two colons
5234 @cindex Less cluttered menu entry
5235 @cindex Uncluttered menu entry
5237 When the menu entry name and node name are the same, you can write
5238 the name immediately after the asterisk and space at the beginning of
5239 the line and follow the name with two colons.@refill
5245 * Name:: @var{description}
5253 * Name: Name. @var{description}
5256 You should use the node name for the menu entry name whenever possible,
5257 since it reduces visual clutter in the menu.@refill
5259 @node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
5260 @comment node-name, next, previous, up
5261 @section A Menu Example
5262 @cindex Menu example
5263 @cindex Example menu
5265 A menu looks like this in Texinfo:@refill
5270 * menu entry name: Node name. A short description.
5271 * Node name:: This form is preferred.
5284 * menu entry name: Node name. A short description.
5285 * Node name:: This form is preferred.
5290 Here is an example as you might see it in a Texinfo file:@refill
5295 Larger Units of Text
5297 * Files:: All about handling files.
5298 * Multiples: Buffers. Multiple buffers; editing
5299 several files at once.
5311 Larger Units of Text
5313 * Files:: All about handling files.
5314 * Multiples: Buffers. Multiple buffers; editing
5315 several files at once.
5319 In this example, the menu has two entries. @samp{Files} is both a menu
5320 entry name and the name of the node referred to by that name.
5321 @samp{Multiples} is the menu entry name; it refers to the node named
5322 @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5323 appears in the menu, but is not an entry.@refill
5325 Since no file name is specified with either @samp{Files} or
5326 @samp{Buffers}, they must be the names of nodes in the same Info file
5327 (@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5329 @node Other Info Files, , Menu Example, Menus
5330 @comment node-name, next, previous, up
5331 @section Referring to Other Info Files
5332 @cindex Referring to other Info files
5333 @cindex Nodes in other Info files
5334 @cindex Other Info files' nodes
5335 @cindex Going to other Info files' nodes
5336 @cindex Info; other files' nodes
5338 You can create a menu entry that enables a reader in Info to go to a
5339 node in another Info file by writing the file name in parentheses just
5340 before the node name. In this case, you should use the three-part menu
5341 entry format, which saves the reader from having to type the file
5345 The format looks like this:@refill
5350 * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
5351 * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5356 For example, to refer directly to the @samp{Outlining} and
5357 @samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
5358 menu like this:@refill
5363 * Outlining: (emacs)Outline Mode. The major mode for
5365 * Rebinding: (emacs)Rebinding. How to redefine the
5371 If you do not list the node name, but only name the file, then Info
5372 presumes that you are referring to the `Top' node.@refill
5374 The @file{dir} file that contains the main menu for Info has menu
5375 entries that list only file names. These take you directly to the `Top'
5376 nodes of each Info document. (@xref{Installing an Info File}.)
5383 * Info: (info). Documentation browsing system.
5384 * Emacs: (emacs). The extensible, self-documenting
5390 (The @file{dir} top level directory for the Info system is an Info file,
5391 not a Texinfo file, but a menu entry looks the same in both types of
5394 The GNU Emacs Texinfo mode menu updating commands only work with nodes
5395 within the current buffer, so you cannot use them to create menus that
5396 refer to other files. You must write such menus by hand.
5399 @node Cross References
5400 @chapter Cross References
5401 @cindex Making cross references
5402 @cindex Cross references
5405 @dfn{Cross references} are used to refer the reader to other parts of the
5406 same or different Texinfo files. In Texinfo, nodes and anchors are the
5407 places to which cross references can refer.
5410 * References:: What cross references are for.
5411 * Cross Reference Commands:: A summary of the different commands.
5412 * Cross Reference Parts:: A cross reference has several parts.
5413 * xref:: Begin a reference with `See' @dots{}
5414 * Top Node Naming:: How to refer to the beginning of another file.
5415 * ref:: A reference for the last part of a sentence.
5416 * pxref:: How to write a parenthetical cross reference.
5417 * inforef:: How to refer to an Info-only file.
5418 * uref:: How to refer to a uniform resource locator.
5421 @node References, Cross Reference Commands, Cross References, Cross References
5423 @heading What References Are For
5426 Often, but not always, a printed document should be designed so that
5427 it can be read sequentially. People tire of flipping back and forth
5428 to find information that should be presented to them as they need
5431 However, in any document, some information will be too detailed for
5432 the current context, or incidental to it; use cross references to
5433 provide access to such information. Also, an online help system or a
5434 reference manual is not like a novel; few read such documents in
5435 sequence from beginning to end. Instead, people look up what they
5436 need. For this reason, such creations should contain many cross
5437 references to help readers find other information that they may not
5440 In a printed manual, a cross reference results in a page reference,
5441 unless it is to another manual altogether, in which case the cross
5442 reference names that manual.@refill
5444 In Info, a cross reference results in an entry that you can follow using
5445 the Info @samp{f} command. (@inforef{Help-Adv, Some advanced Info
5446 commands, info}.)@refill
5448 The various cross reference commands use nodes (or anchors,
5449 @pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
5450 This is evident in Info, in which a cross reference takes you to the
5451 specified location. @TeX{} also uses nodes to define cross reference
5452 locations, but the action is less obvious. When @TeX{} generates a DVI
5453 file, it records each node's page number and uses the page numbers in making
5454 references. Thus, if you are writing a manual that will only be
5455 printed, and will not be used online, you must nonetheless write
5456 @code{@@node} lines to name the places to which you make cross
5460 @node Cross Reference Commands, Cross Reference Parts, References, Cross References
5461 @comment node-name, next, previous, up
5462 @section Different Cross Reference Commands
5463 @cindex Different cross reference commands
5465 There are four different cross reference commands:@refill
5469 Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5470 or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5473 Used within or, more often, at the end of a sentence; same as
5474 @code{@@xref} for Info; produces just the reference in the printed
5475 manual without a preceding `See'.@refill
5478 Used within parentheses to make a reference that suits both an Info
5479 file and a printed book. Starts with a lower case `see' within the
5480 printed manual. (@samp{p} is for `parenthesis'.)@refill
5483 Used to make a reference to an Info file for which there is no printed
5488 (The @code{@@cite} command is used to make references to books and
5489 manuals for which there is no corresponding Info file and, therefore,
5490 no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
5492 @node Cross Reference Parts, xref, Cross Reference Commands, Cross References
5493 @comment node-name, next, previous, up
5494 @section Parts of a Cross Reference
5495 @cindex Cross reference parts
5496 @cindex Parts of a cross reference
5498 A cross reference command requires only one argument, which is the
5499 name of the node to which it refers. But a cross reference command
5500 may contain up to four additional arguments. By using these
5501 arguments, you can provide a cross reference name for Info, a topic
5502 description or section title for the printed output, the name of a
5503 different Info file, and the name of a different printed
5506 Here is a simple cross reference example:@refill
5509 @@xref@{Node name@}.
5523 See Section @var{nnn} [Node name], page @var{ppp}.
5527 Here is an example of a full five-part cross reference:@refill
5531 @@xref@{Node name, Cross Reference Name, Particular Topic,
5532 info-file-name, A Printed Manual@}, for details.
5540 *Note Cross Reference Name: (info-file-name)Node name,
5548 See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5554 The five possible arguments for a cross reference are:@refill
5558 The node or anchor name (required). This is the location to which the
5559 cross reference takes you. In a printed document, the location of the
5560 node provides the page reference only for references within the same
5564 The cross reference name for the Info reference, if it is to be different
5565 from the node name. If you include this argument, it becomes
5566 the first part of the cross reference. It is usually omitted.@refill
5569 A topic description or section name. Often, this is the title of the
5570 section. This is used as the name of the reference in the printed
5571 manual. If omitted, the node name is used.@refill
5574 The name of the Info file in which the reference is located, if it is
5575 different from the current file. You need not include any @samp{.info}
5576 suffix on the file name, since Info readers try appending it
5580 The name of a printed manual from a different Texinfo file.@refill
5583 The template for a full five argument cross reference looks like
5588 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5589 @var{info-file-name}, @var{printed-manual-title}@}.
5593 Cross references with one, two, three, four, and five arguments are
5594 described separately following the description of @code{@@xref}.@refill
5596 Write a node name in a cross reference in exactly the same way as in
5597 the @code{@@node} line, including the same capitalization; otherwise, the
5598 formatters may not find the reference.@refill
5600 You can write cross reference commands within a paragraph, but note
5601 how Info and @TeX{} format the output of each of the various commands:
5602 write @code{@@xref} at the beginning of a sentence; write
5603 @code{@@pxref} only within parentheses, and so on.@refill
5605 @node xref, Top Node Naming, Cross Reference Parts, Cross References
5606 @comment node-name, next, previous, up
5607 @section @code{@@xref}
5609 @cindex Cross references using @code{@@xref}
5610 @cindex References using @code{@@xref}
5612 The @code{@@xref} command generates a cross reference for the
5613 beginning of a sentence. The Info formatting commands convert it into
5614 an Info cross reference, which the Info @samp{f} command can use to
5615 bring you directly to another node. The @TeX{} typesetting commands
5616 convert it into a page reference, or a reference to another book or
5620 * Reference Syntax:: What a reference looks like and requires.
5621 * One Argument:: @code{@@xref} with one argument.
5622 * Two Arguments:: @code{@@xref} with two arguments.
5623 * Three Arguments:: @code{@@xref} with three arguments.
5624 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
5627 @node Reference Syntax, One Argument, xref, xref
5629 @subheading What a Reference Looks Like and Requires
5632 Most often, an Info cross reference looks like this:@refill
5635 *Note @var{node-name}::.
5642 *Note @var{cross-reference-name}: @var{node-name}.
5646 In @TeX{}, a cross reference looks like this:
5649 See Section @var{section-number} [@var{node-name}], page @var{page}.
5656 See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5659 The @code{@@xref} command does not generate a period or comma to end
5660 the cross reference in either the Info file or the printed output.
5661 You must write that period or comma yourself; otherwise, Info will not
5662 recognize the end of the reference. (The @code{@@pxref} command works
5663 differently. @xref{pxref, , @code{@@pxref}}.)@refill
5666 @strong{Please note:} A period or comma @strong{must} follow the closing
5667 brace of an @code{@@xref}. It is required to terminate the cross
5668 reference. This period or comma will appear in the output, both in
5669 the Info file and in the printed manual.@refill
5672 @code{@@xref} must refer to an Info node by name. Use @code{@@node}
5673 to define the node (@pxref{Writing a Node}).@refill
5675 @code{@@xref} is followed by several arguments inside braces, separated by
5676 commas. Whitespace before and after these commas is ignored.@refill
5678 A cross reference requires only the name of a node; but it may contain
5679 up to four additional arguments. Each of these variations produces a
5680 cross reference that looks somewhat different.@refill
5683 @strong{Please note:} Commas separate arguments in a cross reference;
5684 avoid including them in the title or other part lest the formatters
5685 mistake them for separators.@refill
5688 @node One Argument, Two Arguments, Reference Syntax, xref
5689 @subsection @code{@@xref} with One Argument
5691 The simplest form of @code{@@xref} takes one argument, the name of
5692 another node in the same Info file. The Info formatters produce
5693 output that the Info readers can use to jump to the reference; @TeX{}
5694 produces output that specifies the page and section number for you.@refill
5701 @@xref@{Tropical Storms@}.
5708 *Note Tropical Storms::.
5715 See Section 3.1 [Tropical Storms], page 24.
5719 (Note that in the preceding example the closing brace is followed by a
5722 You can write a clause after the cross reference, like this:@refill
5725 @@xref@{Tropical Storms@}, for more info.
5732 *Note Tropical Storms::, for more info.
5739 See Section 3.1 [Tropical Storms], page 24, for more info.
5743 (Note that in the preceding example the closing brace is followed by a
5744 comma, and then by the clause, which is followed by a period.)@refill
5746 @node Two Arguments, Three Arguments, One Argument, xref
5747 @subsection @code{@@xref} with Two Arguments
5749 With two arguments, the second is used as the name of the Info cross
5750 reference, while the first is still the name of the node to which the
5751 cross reference points.@refill
5755 The template is like this:
5758 @@xref@{@var{node-name}, @var{cross-reference-name}@}.
5766 @@xref@{Electrical Effects, Lightning@}.
5773 *Note Lightning: Electrical Effects.
5780 See Section 5.2 [Electrical Effects], page 57.
5784 (Note that in the preceding example the closing brace is followed by a
5785 period; and that the node name is printed, not the cross reference name.)
5787 You can write a clause after the cross reference, like this:@refill
5790 @@xref@{Electrical Effects, Lightning@}, for more info.
5796 *Note Lightning: Electrical Effects, for more info.
5803 See Section 5.2 [Electrical Effects], page 57, for more info.
5807 (Note that in the preceding example the closing brace is followed by a
5808 comma, and then by the clause, which is followed by a period.)@refill
5810 @node Three Arguments, Four and Five Arguments, Two Arguments, xref
5811 @subsection @code{@@xref} with Three Arguments
5813 A third argument replaces the node name in the @TeX{} output. The third
5814 argument should be the name of the section in the printed output, or
5815 else state the topic discussed by that section. Often, you will want to
5816 use initial upper case letters so it will be easier to read when the
5817 reference is printed. Use a third argument when the node name is
5818 unsuitable because of syntax or meaning.@refill
5820 Remember to avoid placing a comma within the title or topic section of
5821 a cross reference, or within any other section. The formatters divide
5822 cross references into arguments according to the commas; a comma
5823 within a title or other section will divide it into two arguments. In
5824 a reference, you need to write a title such as ``Clouds, Mist, and
5825 Fog'' without the commas.@refill
5827 Also, remember to write a comma or period after the closing brace of an
5828 @code{@@xref} to terminate the cross reference. In the following
5829 examples, a clause follows a terminating comma.@refill
5834 The template is like this:
5838 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
5848 @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
5857 *Note Lightning: Electrical Effects, for details.
5864 See Section 5.2 [Thunder and Lightning], page 57, for details.
5867 If a third argument is given and the second one is empty, then the
5868 third argument serves both. (Note how two commas, side by side, mark
5869 the empty second argument.)@refill
5873 @@xref@{Electrical Effects, , Thunder and Lightning@},
5882 *Note Thunder and Lightning: Electrical Effects, for details.
5889 See Section 5.2 [Thunder and Lightning], page 57, for details.
5892 As a practical matter, it is often best to write cross references with
5893 just the first argument if the node name and the section title are the
5894 same, and with the first and third arguments if the node name and title
5895 are different.@refill
5897 Here are several examples from @cite{The GNU Awk User's Guide}:@refill
5900 @@xref@{Sample Program@}.
5902 @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
5903 @@xref@{Close Output, , Closing Output Files and Pipes@},
5904 for more information.
5905 @@xref@{Regexp, , Regular Expressions as Patterns@}.
5908 @node Four and Five Arguments, , Three Arguments, xref
5909 @subsection @code{@@xref} with Four and Five Arguments
5911 In a cross reference, a fourth argument specifies the name of another
5912 Info file, different from the file in which the reference appears, and
5913 a fifth argument specifies its title as a printed manual.@refill
5915 Remember that a comma or period must follow the closing brace of an
5916 @code{@@xref} command to terminate the cross reference. In the
5917 following examples, a clause follows a terminating comma.@refill
5925 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5926 @var{info-file-name}, @var{printed-manual-title}@}.
5935 @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
5936 weather, An Introduction to Meteorology@}, for details.
5943 *Note Lightning: (weather)Electrical Effects, for details.
5947 The name of the Info file is enclosed in parentheses and precedes
5948 the name of the node.
5951 In a printed manual, the reference looks like this:@refill
5954 See section ``Thunder and Lightning'' in @i{An Introduction to
5955 Meteorology}, for details.
5959 The title of the printed manual is typeset in italics; and the
5960 reference lacks a page number since @TeX{} cannot know to which page a
5961 reference refers when that reference is to another manual.@refill
5963 Often, you will leave out the second argument when you use the long
5964 version of @code{@@xref}. In this case, the third argument, the topic
5965 description, will be used as the cross reference name in Info.@refill
5968 The template looks like this:
5971 @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
5972 @var{printed-manual-title}@}, for details.
5979 *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
5986 See section @var{title-or-topic} in @var{printed-manual-title}, for details.
5994 @@xref@{Electrical Effects, , Thunder and Lightning,
5995 weather, An Introduction to Meteorology@}, for details.
6003 *Note Thunder and Lightning: (weather)Electrical Effects,
6012 See section ``Thunder and Lightning'' in @i{An Introduction to
6013 Meteorology}, for details.
6016 On rare occasions, you may want to refer to another Info file that
6017 is within a single printed manual---when multiple Texinfo files are
6018 incorporated into the same @TeX{} run but make separate Info files.
6019 In this case, you need to specify only the fourth argument, and not
6022 @node Top Node Naming, ref, xref, Cross References
6023 @section Naming a `Top' Node
6024 @cindex Naming a `Top' Node in references
6025 @cindex @samp{@r{Top}} node naming for references
6027 In a cross reference, you must always name a node. This means that in
6028 order to refer to a whole manual, you must identify the `Top' node by
6029 writing it as the first argument to the @code{@@xref} command. (This
6030 is different from the way you write a menu entry; see @ref{Other Info
6031 Files, , Referring to Other Info Files}.) At the same time, to
6032 provide a meaningful section topic or title in the printed cross
6033 reference (instead of the word `Top'), you must write an appropriate
6034 entry for the third argument to the @code{@@xref} command.
6038 Thus, to make a cross reference to @cite{The GNU Make Manual},
6042 @@xref@{Top, , Overview, make, The GNU Make Manual@}.
6049 *Note Overview: (make)Top.
6056 See section ``Overview'' in @i{The GNU Make Manual}.
6060 In this example, @samp{Top} is the name of the first node, and
6061 @samp{Overview} is the name of the first section of the manual.@refill
6062 @node ref, pxref, Top Node Naming, Cross References
6063 @comment node-name, next, previous, up
6064 @section @code{@@ref}
6065 @cindex Cross references using @code{@@ref}
6066 @cindex References using @code{@@ref}
6069 @code{@@ref} is nearly the same as @code{@@xref} except that it does
6070 not generate a `See' in the printed output, just the reference itself.
6071 This makes it useful as the last part of a sentence.@refill
6079 For more information, see @@ref@{Hurricanes@}.
6086 For more information, see *Note Hurricanes::.
6093 For more information, see Section 8.2 [Hurricanes], page 123.
6096 The @code{@@ref} command sometimes leads writers to express themselves
6097 in a manner that is suitable for a printed manual but looks awkward
6098 in the Info format. Bear in mind that your audience will be using
6099 both the printed and the Info format.@refill
6108 Sea surges are described in @@ref@{Hurricanes@}.
6117 Sea surges are described in Section 6.7 [Hurricanes], page 72.
6122 in a printed document, and the following in Info:
6125 Sea surges are described in *Note Hurricanes::.
6129 @strong{Caution:} You @emph{must} write a period, comma, or right
6130 parenthesis immediately after an @code{@@ref} command with two or more
6131 arguments. Otherwise, Info will not find the end of the cross reference
6132 entry and its attempt to follow the cross reference will fail. As a
6133 general rule, you should write a period or comma after every
6134 @code{@@ref} command. This looks best in both the printed and the Info
6138 @node pxref, inforef, ref, Cross References
6139 @comment node-name, next, previous, up
6140 @section @code{@@pxref}
6141 @cindex Cross references using @code{@@pxref}
6142 @cindex References using @code{@@pxref}
6145 The parenthetical reference command, @code{@@pxref}, is nearly the
6146 same as @code{@@xref}, but you use it @emph{only} inside parentheses
6147 and you do @emph{not} type a comma or period after the command's
6148 closing brace. The command differs from @code{@@xref} in two
6153 @TeX{} typesets the reference for the printed manual with a lower case
6154 `see' rather than an upper case `See'.@refill
6157 The Info formatting commands automatically end the reference with a
6158 closing colon or period.@refill
6161 Because one type of formatting automatically inserts closing
6162 punctuation and the other does not, you should use @code{@@pxref}
6163 @emph{only} inside parentheses as part of another sentence. Also, you
6164 yourself should not insert punctuation after the reference, as you do
6165 with @code{@@xref}.@refill
6167 @code{@@pxref} is designed so that the output looks right and works
6168 right between parentheses both in printed output and in an Info file.
6169 In a printed manual, a closing comma or period should not follow a
6170 cross reference within parentheses; such punctuation is wrong. But in
6171 an Info file, suitable closing punctuation must follow the cross
6172 reference so Info can recognize its end. @code{@@pxref} spares you
6173 the need to use complicated methods to put a terminator into one form
6174 of the output and not the other.@refill
6177 With one argument, a parenthetical cross reference looks like
6182 @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
6191 @dots{} storms cause flooding (*Note Hurricanes::) @dots{}
6199 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
6202 With two arguments, a parenthetical cross reference has this
6206 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6213 @dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
6221 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6224 @code{@@pxref} can be used with up to five arguments just like
6225 @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
6228 @strong{Please note:} Use @code{@@pxref} only as a parenthetical
6229 reference. Do not try to use @code{@@pxref} as a clause in a sentence.
6230 It will look bad in either the Info file, the printed output, or
6233 Also, parenthetical cross references look best at the ends of sentences.
6234 Although you may write them in the middle of a sentence, that location
6235 breaks up the flow of text.@refill
6238 @node inforef, uref, pxref, Cross References
6239 @section @code{@@inforef}
6240 @cindex Cross references using @code{@@inforef}
6241 @cindex References using @code{@@inforef}
6244 @code{@@inforef} is used for cross references to Info files for which
6245 there are no printed manuals. Even in a printed manual,
6246 @code{@@inforef} generates a reference directing the user to look in
6247 an Info file.@refill
6249 The command takes either two or three arguments, in the following
6257 The cross reference name (optional).
6264 Separate the arguments with commas, as with @code{@@xref}. Also, you
6265 must terminate the reference with a comma or period after the
6266 @samp{@}}, as you do with @code{@@xref}.@refill
6272 @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6281 @@inforef@{Expert, Advanced Info commands, info@},
6282 for more information.
6292 *Note Advanced Info commands: (info)Expert,
6293 for more information.
6302 See Info file @file{info}, node @samp{Expert}, for more information.
6311 @@inforef@{Expert, , info@}, for more information.
6320 *Note (info)Expert::, for more information.
6328 See Info file @file{info}, node @samp{Expert}, for more information.
6331 The converse of @code{@@inforef} is @code{@@cite}, which is used to
6332 refer to printed works for which no Info form exists. @xref{cite, ,
6333 @code{@@cite}}.@refill
6337 @section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
6339 @cindex Uniform resource locator, referring to
6340 @cindex URL, referring to
6342 @cindex @code{href}, producing HTML
6343 @code{@@uref} produces a reference to a uniform resource locator (url).
6344 It takes one mandatory argument, the url, and two optional arguments
6345 which control the text that is displayed. In HTML output, @code{@@uref}
6346 produces a link you can follow.
6348 The second argument, if specified, is the text to display (the default
6349 is the url itself); in Info and DVI output, but not in HTML output, the
6352 @cindex Man page, reference to
6353 The third argument, on the other hand, if specified is also the text to
6354 display, but the url is @emph{not} output in any format. This is useful
6355 when the text is already sufficiently referential, as in a man page. If
6356 the third argument is given, the second argument is ignored.
6358 The simple one argument form, where the url is both the target and the
6362 The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
6367 The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
6371 An example of the two-argument form:
6373 The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
6374 holds programs and texts.
6379 The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
6380 holds programs and texts.
6383 @noindent that is, the Info output is this:
6385 The official GNU ftp site (ftp://ftp.gnu.org/gnu)
6386 holds programs and texts.
6389 @noindent and the HTML output is this:
6391 The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
6392 holds programs and texts.
6396 An example of the three-argument form:
6398 The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{}
6403 The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
6406 @noindent but with HTML:
6408 The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
6411 To merely indicate a url without creating a link people can follow, use
6412 @code{@@url} (@pxref{url, @code{@@url}}).
6414 Some people prefer to display url's in the unambiguous format:
6417 <URL:http://@var{host}/@var{path}>
6421 @cindex <URL convention, not used
6422 You can use this form in the input file if you wish. We feel it's not
6423 necessary to clutter up the output with the extra @samp{<URL:} and
6424 @samp{>}, since any software that tries to detect url's in text already
6425 has to detect them without the @samp{<URL:} to be useful.
6429 @chapter Marking Words and Phrases
6430 @cindex Paragraph, marking text within
6431 @cindex Marking words and phrases
6432 @cindex Words and phrases, marking them
6433 @cindex Marking text within a paragraph
6434 @cindex Text, marking up
6436 In Texinfo, you can mark words and phrases in a variety of ways.
6437 The Texinfo formatters use this information to determine how to
6439 You can specify, for example, whether a word or phrase is a
6440 defining occurrence, a metasyntactic variable, or a symbol used in a
6441 program. Also, you can emphasize text, in several different ways.
6444 * Indicating:: How to indicate definitions, files, etc.
6445 * Emphasis:: How to emphasize text.
6449 @node Indicating, Emphasis, Marking Text, Marking Text
6450 @section Indicating Definitions, Commands, etc.
6451 @cindex Highlighting text
6452 @cindex Indicating commands, definitions, etc.
6454 Texinfo has commands for indicating just what kind of object a piece of
6455 text refers to. For example, metasyntactic variables are marked by
6456 @code{@@var}, and code by @code{@@code}. Since the pieces of text are
6457 labelled by commands that tell what kind of object they are, it is easy
6458 to change the way the Texinfo formatters prepare such text. (Texinfo is
6459 an @emph{intentional} formatting language rather than a @emph{typesetting}
6460 formatting language.)@refill
6462 For example, in a printed manual,
6463 code is usually illustrated in a typewriter font;
6464 @code{@@code} tells @TeX{} to typeset this text in this font. But it
6465 would be easy to change the way @TeX{} highlights code to use another
6466 font, and this change would not affect how keystroke examples are
6467 highlighted. If straight typesetting commands were used in the body
6468 of the file and you wanted to make a change, you would need to check
6469 every single occurrence to make sure that you were changing code and
6470 not something else that should not be changed.@refill
6473 * Useful Highlighting:: Highlighting provides useful information.
6474 * code:: Indicating program code.
6475 * kbd:: Showing keyboard input.
6476 * key:: Specifying keys.
6477 * samp:: A literal sequence of characters.
6478 * verb:: A verbatim sequence of characters.
6479 * var:: Indicating metasyntactic variables.
6480 * env:: Indicating environment variables.
6481 * file:: Indicating file names.
6482 * command:: Indicating command names.
6483 * option:: Indicating option names.
6484 * dfn:: Specifying definitions.
6485 * cite:: Referring to books not in the Info system.
6486 * acronym:: Indicating acronyms.
6487 * url:: Indicating a World Wide Web reference.
6488 * email:: Indicating an electronic mail address.
6492 @node Useful Highlighting, code, Indicating, Indicating
6494 @subheading Highlighting Commands are Useful
6497 The highlighting commands can be used to extract useful information
6498 from the file, such as lists of functions or file names. It is
6499 possible, for example, to write a program in Emacs Lisp (or a keyboard
6500 macro) to insert an index entry after every paragraph that contains
6501 words or phrases marked by a specified command. You could do this to
6502 construct an index of functions if you had not already made the
6505 The commands serve a variety of purposes:@refill
6508 @item @@code@{@var{sample-code}@}
6509 Indicate text that is a literal example of a piece of a program.@refill
6511 @item @@kbd@{@var{keyboard-characters}@}
6512 Indicate keyboard input.@refill
6514 @item @@key@{@var{key-name}@}
6515 Indicate the conventional name for a key on a keyboard.@refill
6517 @item @@samp@{@var{text}@}
6518 Indicate text that is a literal example of a sequence of characters.@refill
6520 @item @@var@{@var{metasyntactic-variable}@}
6521 Indicate a metasyntactic variable.@refill
6523 @item @@env@{@var{environment-variable}@}
6524 Indicate an environment variable.@refill
6526 @item @@file@{@var{file-name}@}
6527 Indicate the name of a file.@refill
6529 @item @@command@{@var{command-name}@}
6530 Indicate the name of a command.@refill
6532 @item @@option@{@var{option}@}
6533 Indicate a command-line option.@refill
6535 @item @@dfn@{@var{term}@}
6536 Indicate the introductory or defining use of a term.@refill
6538 @item @@cite@{@var{reference}@}
6539 Indicate the name of a book.@refill
6541 @item @@acronym@{@var{acronym}@}
6542 Indicate an acronym.@refill
6544 @item @@url@{@var{uniform-resource-locator}@}
6545 Indicate a uniform resource locator for the World Wide Web.
6547 @item @@email@{@var{email-address}[, @var{displayed-text}]@}
6548 Indicate an electronic mail address.
6551 @item @@ctrl@{@var{ctrl-char}@}
6552 Use for an @sc{ascii} control character.@refill
6558 @subsection @code{@@code}@{@var{sample-code}@}
6561 @cindex Syntactic tokens, indicating
6562 Use the @code{@@code} command to indicate text that is a piece of a
6563 program and which consists of entire syntactic tokens. Enclose the
6566 @cindex Expressions in a program, indicating
6567 @cindex Keywords, indicating
6568 @cindex Reserved words, indicating
6569 Thus, you should use @code{@@code} for an expression in a program, for
6570 the name of a variable or function used in a program, or for a
6571 keyword in a programming language.
6573 Use @code{@@code} for command names in languages that resemble
6574 programming languages, such as Texinfo. For example, @code{@@code} and
6575 @code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
6576 @samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
6578 @cindex Case, not altering in @code{@@code}
6579 It is incorrect to alter the case of a word inside an @code{@@code}
6580 command when it appears at the beginning of a sentence. Most computer
6581 languages are case sensitive. In C, for example, @code{Printf} is
6582 different from the identifier @code{printf}, and most likely is a
6583 misspelling of it. Even in languages which are not case sensitive, it
6584 is confusing to a human reader to see identifiers spelled in different
6585 ways. Pick one spelling and always use that. If you do not want to
6586 start a sentence with a command name written all in lower case, you
6587 should rearrange the sentence.
6589 In the printed manual, @code{@@code} causes @TeX{} to typeset the
6590 argument in a typewriter face. In the Info file, it causes the Info
6591 formatting commands to use single quotation marks around the text.
6597 The function returns @@code@{nil@}.
6601 produces this in the printed manual:
6604 The function returns @code{nil}.
6609 and this in the Info file:
6611 The function returns `nil'.
6615 Here are some cases for which it is preferable not to use @code{@@code}:
6619 For shell command names such as @command{ls} (use @code{@@command}).
6622 For shell options such as @samp{-c} when such options stand alone (use
6626 Also, an entire shell command often looks better if written using
6627 @code{@@samp} rather than @code{@@code}. In this case, the rule is to
6628 choose the more pleasing format.
6631 For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
6634 For a string of characters shorter than a syntactic token. For example,
6635 if you are writing about @samp{goto-ch}, which is just a part of the
6636 name for the @code{goto-char} Emacs Lisp function, you should use
6640 In general, when writing about the characters used in a token; for
6641 example, do not use @code{@@code} when you are explaining what letters
6642 or printable symbols can be used in the names of functions. (Use
6643 @code{@@samp}.) Also, you should not use @code{@@code} to mark text
6644 that is considered input to programs unless the input is written in a
6645 language that is like a programming language. For example, you should
6646 not use @code{@@code} for the keystroke commands of GNU Emacs (use
6647 @code{@@kbd} instead) although you may use @code{@@code} for the names
6648 of the Emacs Lisp functions that the keystroke commands invoke.
6652 Since @code{@@command}, @code{@@option}, and @code{@@env} were
6653 introduced relatively recently, it is acceptable to use @code{@@code} or
6654 @code{@@samp} for command names, options, and environment variables.
6655 The new commands allow you to express the markup more precisely, but
6656 there is no real harm in using the older commands, and of course the
6657 long-standing manuals do so.
6661 @subsection @code{@@kbd}@{@var{keyboard-characters}@}
6663 @cindex Keyboard input
6665 Use the @code{@@kbd} command for characters of input to be typed by
6666 users. For example, to refer to the characters @kbd{M-a},
6674 and to refer to the characters @kbd{M-x shell}, write@refill
6681 @cindex slanted typewriter font, for @code{@@kbd}
6682 The @code{@@kbd} command has the same effect as @code{@@code} in Info,
6683 but by default produces a different font (slanted typewriter instead of
6684 normal typewriter) in the printed manual, so users can distinguish the
6685 characters they are supposed to type from those the computer outputs.
6687 @findex kbdinputstyle
6688 Since the usage of @code{@@kbd} varies from manual to manual, you can
6689 control the font switching with the @code{@@kbdinputstyle} command.
6690 This command has no effect on Info output. Write this command at the
6691 beginning of a line with a single word as an argument, one of the
6693 @vindex distinct@r{, arg to @@kbdinputstyle}
6694 @vindex example@r{, arg to @@kbdinputstyle}
6695 @vindex code@r{, arg to @@kbdinputstyle}
6698 Always use the same font for @code{@@kbd} as @code{@@code}.
6700 Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6701 and similar environments.
6703 (the default) Always use the distinguishing font for @code{@@kbd}.
6706 You can embed another @@-command inside the braces of an @code{@@kbd}
6707 command. Here, for example, is the way to describe a command that
6708 would be described more verbosely as ``press an @samp{r} and then
6709 press the @key{RET} key'':@refill
6712 @@kbd@{r @@key@{RET@}@}
6716 This produces: @kbd{r @key{RET}}
6718 You also use the @code{@@kbd} command if you are spelling out the letters
6719 you type; for example:@refill
6722 To give the @@code@{logout@} command,
6723 type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6730 To give the @code{logout} command,
6731 type the characters @kbd{l o g o u t @key{RET}}.
6734 (Also, this example shows that you can add spaces for clarity. If you
6735 really want to mention a space character as one of the characters of
6736 input, write @kbd{@@key@{SPC@}} for it.)@refill
6739 @node key, samp, kbd, Indicating
6740 @comment node-name, next, previous, up
6741 @subsection @code{@@key}@{@var{key-name}@}
6744 Use the @code{@@key} command for the conventional name for a key on a
6745 keyboard, as in:@refill
6751 You can use the @code{@@key} command within the argument of an
6752 @code{@@kbd} command when the sequence of characters to be typed
6753 includes one or more keys that are described by name.@refill
6756 For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
6759 @@kbd@{C-x @@key@{ESC@}@}
6762 Here is a list of the recommended names for keys:
6763 @cindex Recommended names for keys
6764 @cindex Keys, recommended names
6765 @cindex Names recommended for keys
6766 @cindex Abbreviations for keys
6775 Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
6776 it might be better to call this character @kbd{C-j}.
6795 There are subtleties to handling words like `meta' or `ctrl' that are
6796 names of modifier keys. When mentioning a character in which the
6797 modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
6798 alone; do not use the @code{@@key} command; but when you are referring
6799 to the modifier key in isolation, use the @code{@@key} command. For
6800 example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
6801 @samp{@@key@{META@}} to produce @key{META}.
6803 @c I don't think this is a good explanation.
6804 @c I think it will puzzle readers more than it clarifies matters. -- rms.
6805 @c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
6806 @c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
6807 @c the beginning of the sentence. The @code{@@key@{META@}} key is often in
6808 @c the lower left of the keyboard.''@refill
6811 @subsection @code{@@samp}@{@var{text}@}
6814 Use the @code{@@samp} command to indicate text that is a literal example
6815 or `sample' of a sequence of characters in a file, string, pattern, etc.
6816 Enclose the text in braces. The argument appears within single
6817 quotation marks in both the Info file and the printed manual; in
6818 addition, it is printed in a fixed-width font.@refill
6821 To match @@samp@{foo@} at the end of the line,
6822 use the regexp @@samp@{foo$@}.
6829 To match @samp{foo} at the end of the line, use the regexp
6833 Any time you are referring to single characters, you should use
6834 @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
6835 Also, you may use @code{@@samp} for entire statements in C and for entire
6836 shell commands---in this case, @code{@@samp} often looks better than
6837 @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
6838 not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
6840 Only include punctuation marks within braces if they are part of the
6841 string you are specifying. Write punctuation marks outside the braces
6842 if those punctuation marks are part of the English text that surrounds
6843 the string. In the following sentence, for example, the commas and
6844 period are outside of the braces:@refill
6848 In English, the vowels are @@samp@{a@}, @@samp@{e@},
6849 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
6858 In English, the vowels are @samp{a}, @samp{e},
6859 @samp{i}, @samp{o}, @samp{u}, and sometimes
6865 @subsection @code{@@verb}@{<char>@var{text}<char>@}
6867 @cindex Verbatim in-line text
6869 @cindex Delimiter character, for verbatim
6870 Use the @code{@@verb} command to print a verbatim sequence of
6873 Like La@TeX{}'s @code{\verb} command, the verbatim text can be quoted using
6874 any unique delimiter character. Enclose the verbatim text, including the
6875 delimiters, in braces. Text is printed in a fixed-width font:
6878 How many @@verb@{|@@|@}-escapes does one need to print this
6879 @@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
6886 How many @verb{|@|}-escapes does one need to print this
6887 @verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
6890 This is in contrast to @code{@@samp} (see the previous
6891 section), whose argument is normal Texinfo text, where the characters
6892 @code{@@@{@}} are special; with @code{@@verb}, nothing is special except
6893 the delimiter character you choose.
6897 @subsection @code{@@var}@{@var{metasyntactic-variable}@}
6900 Use the @code{@@var} command to indicate metasyntactic variables. A
6901 @dfn{metasyntactic variable} is something that stands for another piece of
6902 text. For example, you should use a metasyntactic variable in the
6903 documentation of a function to describe the arguments that are passed
6904 to that function.@refill
6906 Do not use @code{@@var} for the names of particular variables in
6907 programming languages. These are specific names from a program, so
6908 @code{@@code} is correct for them (@pxref{code}). For example, the
6909 Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
6910 variable; it is properly formatted using @code{@@code}.
6912 Do not use @code{@@var} for environment variables either; @code{@@env}
6913 is correct for them (see the next section).
6915 The effect of @code{@@var} in the Info file is to change the case of the
6916 argument to all upper case. In the printed manual and HTML output, the
6917 argument is printed in slanted type.
6923 To delete file @@var@{filename@},
6924 type @@samp@{rm @@var@{filename@}@}.
6931 To delete file @var{filename}, type @samp{rm @var{filename}}.
6935 (Note that @code{@@var} may appear inside @code{@@code},
6936 @code{@@samp}, @code{@@file}, etc.)@refill
6938 Write a metasyntactic variable all in lower case without spaces, and
6939 use hyphens to make it more readable. Thus, the Texinfo source for
6940 the illustration of how to begin a Texinfo manual looks like
6946 @@@@setfilename @@var@{info-file-name@}
6947 @@@@settitle @@var@{name-of-manual@}
6957 @@setfilename @var{info-file-name}
6958 @@settitle @var{name-of-manual}
6962 In some documentation styles, metasyntactic variables are shown with
6963 angle brackets, for example:@refill
6966 @dots{}, type rm <filename>
6970 However, that is not the style that Texinfo uses. (You can, of
6971 course, modify the sources to @file{texinfo.tex} and the Info formatting commands
6972 to output the @code{<@dots{}>} format if you wish.)@refill
6976 @subsection @code{@@env}@{@var{environment-variable}@}
6979 Use the @code{@@env} command to indicate environment variables, as used
6980 by many operating systems, including GNU. Do not use it for
6981 metasyntactic variables; use @code{@@var} instead (see the previous
6984 @code{@@env} is equivalent to @code{@@code} in its effects.
6988 The @@env@{PATH@} environment variable @dots{}
6992 The @env{PATH} environment variable @dots{}
6997 @subsection @code{@@file}@{@var{file-name}@}
7000 Use the @code{@@file} command to indicate text that is the name of a
7001 file, buffer, or directory, or is the name of a node in Info. You can
7002 also use the command for file name suffixes. Do not use @code{@@file}
7003 for symbols in a programming language; use @code{@@code}.
7005 Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
7009 The @@file@{.el@} files are in
7010 the @@file@{/usr/local/emacs/lisp@} directory.
7017 The @file{.el} files are in
7018 the @file{/usr/local/emacs/lisp} directory.
7023 @subsection @code{@@command}@{@var{command-name}@}
7025 @cindex Command names, indicating
7026 @cindex Program names, indicating
7028 Use the @code{@@command} command to indicate command names, such as
7029 @command{ls} or @command{cc}.
7031 @code{@@command} is equivalent to @code{@@code} in its effects.
7035 The command @@command@{ls@} lists directory contents.
7039 The command @command{ls} lists directory contents.
7042 You should write the name of a program in the ordinary text font, rather
7043 than using @code{@@command}, if you regard it as a new English word,
7044 such as `Emacs' or `Bison'.
7046 When writing an entire shell command invocation, as in @samp{ls -l},
7047 you should use either @code{@@samp} or @code{@@code} at your discretion.
7051 @subsection @code{@@option}@{@var{option-name}@}
7054 Use the @code{@@option} command to indicate a command-line option; for
7055 example, @option{-l} or @option{--version} or
7056 @option{--output=@var{filename}}.
7058 @code{@@option} is equivalent to @code{@@samp} in its effects.
7062 The option @@option@{-l@} produces a long listing.
7066 The option @option{-l} produces a long listing.
7069 In tables, putting options inside @code{@@code} produces a
7070 more pleasing effect.
7073 @comment node-name, next, previous, up
7074 @subsection @code{@@dfn}@{@var{term}@}
7077 Use the @code{@@dfn} command to identify the introductory or defining
7078 use of a technical term. Use the command only in passages whose
7079 purpose is to introduce a term which will be used again or which the
7080 reader ought to know. Mere passing mention of a term for the first
7081 time does not deserve @code{@@dfn}. The command generates italics in
7082 the printed manual, and double quotation marks in the Info file. For
7086 Getting rid of a file is called @@dfn@{deleting@} it.
7093 Getting rid of a file is called @dfn{deleting} it.
7096 As a general rule, a sentence containing the defining occurrence of a
7097 term should be a definition of the term. The sentence does not need
7098 to say explicitly that it is a definition, but it should contain the
7099 information of a definition---it should make the meaning clear.
7102 @subsection @code{@@cite}@{@var{reference}@}
7105 Use the @code{@@cite} command for the name of a book that lacks a
7106 companion Info file. The command produces italics in the printed
7107 manual, and quotation marks in the Info file.
7109 If a book is written in Texinfo, it is better to use a cross reference
7110 command since a reader can easily follow such a reference in Info.
7111 @xref{xref, , @code{@@xref}}.
7115 @c node ctrl, , cite, Indicating
7116 @comment node-name, next, previous, up
7117 @c subsection @code{@@ctrl}@{@var{ctrl-char}@}
7120 The @code{@@ctrl} command is seldom used. It describes an @sc{ascii}
7121 control character by inserting the actual character into the Info
7124 Usually, in Texinfo, you talk what you type as keyboard entry by
7125 describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
7126 @kbd{C-a}. Use @code{@@kbd} in this way when talking about a control
7127 character that is typed on the keyboard by the user. When talking
7128 about a control character appearing in a file or a string, do not use
7129 @code{@@kbd} since the control character is not typed. Also, do not
7130 use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
7131 to make it easier for a reader to understand.@refill
7133 @code{@@ctrl} is an idea from the beginnings of Texinfo which may not
7134 really fit in to the scheme of things. But there may be times when
7135 you want to use the command. The pattern is
7136 @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character
7137 whose control-equivalent is wanted. For example, to specify
7138 @samp{control-f}, you would enter@refill
7151 In the Info file, this generates the specified control character, output
7152 literally into the file. This is done so a user can copy the specified
7153 control character (along with whatever else he or she wants) into another
7154 Emacs buffer and use it. Since the `control-h',`control-i', and
7155 `control-j' characters are formatting characters, they should not be
7156 indicated with @code{@@ctrl}.@refill
7158 In a printed manual, @code{@@ctrl} generates text to describe or
7159 identify that control character: an uparrow followed by the character
7165 @subsection @code{@@acronym}@{@var{acronym}@}
7168 @cindex NASA, as acronym
7169 @cindex F.B.I., as acronym
7170 @cindex Abbreviations, tagging
7171 @cindex Acronyms, tagging
7172 Use the @code{@@acronym} command for abbreviations written in all
7173 capital letters, such as `@acronym{NASA}'. The abbreviation is given as
7174 the single argument in braces, as in @samp{@@acronym@{NASA@}}. As
7175 a matter of style, or for particular abbreviations, you may prefer to
7176 use periods, as in @samp{@@acronym@{F.B.I.@}}.
7178 In @TeX{} and HTML, the argument is printed in a slightly smaller font
7179 size. In Info or plain text output, this command changes nothing.
7183 @subsection @code{@@url}@{@var{uniform-resource-locator}@}
7185 @cindex Uniform resource locator, indicating
7186 @cindex URL, indicating
7188 Use the @code{@@url} command to indicate a uniform resource locator on
7189 the World Wide Web. This is analogous to @code{@@file}, @code{@@var},
7190 etc., and is purely for markup purposes. It does not produce a link you
7191 can follow in HTML output (use the @code{@@uref} command for that,
7192 @pxref{uref,, @code{@@uref}}). It is useful for url's which do
7193 not actually exist. For example:
7195 @c Two lines because one is too long for smallbook format.
7197 For example, the url might be @@url@{http://example.org/path@}.
7200 @noindent which produces:
7203 For example, the url might be @url{http://example.org/path}.
7208 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
7211 Use the @code{@@email} command to indicate an electronic mail address.
7212 It takes one mandatory argument, the address, and one optional argument, the
7213 text to display (the default is the address itself).
7216 In Info and @TeX{}, the address is shown in angle brackets, preceded by
7217 the text to display if any. In HTML output, @code{@@email} produces a
7218 @samp{mailto} link that usually brings up a mail composition window.
7222 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
7223 suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
7227 Send bug reports to @email{bug-texinfo@@gnu.org},
7228 suggestions to the @email{bug-texinfo@@gnu.org, same place}.
7233 @comment node-name, next, previous, up
7234 @section Emphasizing Text
7235 @cindex Emphasizing text
7237 Usually, Texinfo changes the font to mark words in the text according to
7238 what category the words belong to; an example is the @code{@@code} command.
7239 Most often, this is the best way to mark words.
7240 However, sometimes you will want to emphasize text without indicating a
7241 category. Texinfo has two commands to do this. Also, Texinfo has
7242 several commands that specify the font in which @TeX{} will typeset
7243 text. These commands have no effect on Info and only one of them,
7244 the @code{@@r} command, has any regular use.@refill
7247 * emph & strong:: How to emphasize text in Texinfo.
7248 * Smallcaps:: How to use the small caps font.
7249 * Fonts:: Various font commands for printed output.
7253 @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
7254 @cindex Emphasizing text, font for
7258 The @code{@@emph} and @code{@@strong} commands are for emphasis;
7259 @code{@@strong} is stronger. In printed output, @code{@@emph} produces
7260 @emph{italics} and @code{@@strong} produces @strong{bold}.
7268 @@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
7269 files in the directory.
7276 produces the following in printed output:
7279 @strong{Caution}: @samp{rm * .[^.]*} removes @emph{all}
7280 files in the directory.
7284 and the following in Info:
7292 *Caution*: `rm * .[^.]*' removes _all_
7293 files in the directory.
7296 The @code{@@strong} command is seldom used except to mark what is, in
7297 effect, a typographical element, such as the word `Caution' in the
7300 In the Info output, @code{@@emph} surrounds the text with underscores
7301 (@samp{_}), and @code{@@strong} puts asterisks around the text.
7304 @strong{Caution:} Do not use @code{@@strong} with the word @samp{Note};
7305 Info will mistake the combination for a cross reference. Use a phrase
7306 such as @strong{Please note} or @strong{Caution} instead.
7311 @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
7312 @cindex Small caps font
7313 @findex sc @r{(small caps font)}
7315 Use the @samp{@@sc} command to set text in the printed and the HTML
7316 output in @sc{a small caps font} and set text in the Info file in upper
7317 case letters. Write the text you want to be in small caps (where
7318 possible) between braces in lower case, like this:
7321 The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
7328 The @sc{acm} and @sc{ieee} are technical societies.
7331 @TeX{} typesets the small caps font in a manner that prevents the
7332 letters from `jumping out at you on the page'. This makes small caps
7333 text easier to read than text in all upper case---but it's usually
7334 better to use regular mixed case anyway. The Info formatting commands
7335 set all small caps text in upper case. In HTML, the text is upper-cased
7336 and a smaller font is used to render it.
7338 If the text between the braces of an @code{@@sc} command is uppercase,
7339 @TeX{} typesets in FULL-SIZE CAPITALS. Use full-size capitals
7340 sparingly, if ever, and since it's redundant to mark all-uppercase text
7341 with @code{@@sc}, @command{makeinfo} warns about such usage.
7343 You may also use the small caps font for a jargon word such as
7344 @sc{ato} (a @sc{nasa} word meaning `abort to orbit').
7346 There are subtleties to using the small caps font with a jargon word
7347 such as @sc{cdr}, a word used in Lisp programming. In this case, you
7348 should use the small caps font when the word refers to the second and
7349 subsequent elements of a list (the @sc{cdr} of the list), but you
7350 should use @samp{@@code} when the word refers to the Lisp function of
7355 @subsection Fonts for Printing, Not Info
7356 @cindex Fonts for printing, not for Info
7357 @findex i @r{(italic font)}
7358 @findex b @r{(bold font)}
7359 @findex t @r{(typewriter font)}
7360 @findex r @r{(Roman font)}
7362 Texinfo provides four font commands that specify font changes in the
7363 printed manual but have no effect in the Info file. @code{@@i}
7364 requests @i{italic} font (in some versions of @TeX{}, a slanted font
7365 is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
7366 @t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
7367 @r{roman} font, which is the usual font in which text is printed. All
7368 four commands apply to an argument that follows, surrounded by
7371 Only the @code{@@r} command has much use: in example programs, you
7372 can use the @code{@@r} command to convert code comments from the
7373 fixed-width font to a roman font. This looks better in printed
7382 (+ 2 2) ; @@r@{Add two plus two.@}
7391 (+ 2 2) ; @r{Add two plus two.}
7394 If possible, you should avoid using the other three font commands. If
7395 you need to use one, it probably indicates a gap in the Texinfo
7399 @node Quotations and Examples
7400 @chapter Quotations and Examples
7402 Quotations and examples are blocks of text consisting of one or more
7403 whole paragraphs that are set off from the bulk of the text and
7404 treated differently. They are usually indented.@refill
7406 In Texinfo, you always begin a quotation or example by writing an
7407 @@-command at the beginning of a line by itself, and end it by writing
7408 an @code{@@end} command that is also at the beginning of a line by
7409 itself. For instance, you begin an example by writing @code{@@example}
7410 by itself at the beginning of a line and end the example by writing
7411 @code{@@end example} on a line by itself, at the beginning of that
7416 * Block Enclosing Commands:: Different constructs for different purposes.
7417 * quotation:: Writing a quotation.
7418 * example:: Writing an example in a fixed-width font.
7419 * verbatim:: Writing a verbatim example.
7420 * verbatiminclude:: Including a file verbatim.
7421 * lisp:: Illustrating Lisp code.
7422 * small:: Forms for @code{@@smallbook}.
7423 * display:: Writing an example in the current font.
7424 * format:: Writing an example without narrowed margins.
7425 * exdent:: Undo indentation on a line.
7426 * flushleft & flushright:: Pushing text flush left or flush right.
7427 * noindent:: Preventing paragraph indentation.
7428 * cartouche:: Drawing rounded rectangles around examples.
7432 @node Block Enclosing Commands
7433 @section Block Enclosing Commands
7435 Here are commands for quotations and examples, explained further in the
7440 Indicate text that is quoted. The text is filled, indented, and
7441 printed in a roman font by default.
7444 Illustrate code, commands, and the like. The text is printed
7445 in a fixed-width font, and indented but not filled.
7448 Mark a piece of text that is to be printed verbatim; no character
7449 substitutions are made and all commands are ignored, until the next
7450 @code{@@end verbatim}. The text is printed in a fixed-width font,
7451 and not indented or filled. Extra spaces and blank lines are
7452 significant, and tabs are expanded.
7454 @item @@smallexample
7455 Same as @code{@@example}, except that in @TeX{} this command typesets
7456 text in a smaller font.
7459 Like @code{@@example}, but specifically for illustrating Lisp code. The
7460 text is printed in a fixed-width font, and indented but not filled.
7463 Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
7466 Display illustrative text. The text is indented but not filled, and
7467 no font is selected (so, by default, the font is roman).@refill
7469 @item @@smalldisplay
7470 Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
7473 Like @code{@@display} (the text is not filled and no font is selected),
7474 but the text is not indented.
7477 Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
7480 The @code{@@exdent} command is used within the above constructs to
7481 undo the indentation of a line.
7483 The @code{@@flushleft} and @code{@@flushright} commands are used to line
7484 up the left or right margins of unfilled text.@refill
7486 The @code{@@noindent} command may be used after one of the above
7487 constructs to prevent the following text from being indented as a new
7490 You can use the @code{@@cartouche} command within one of the above
7491 constructs to highlight the example or quotation by drawing a box with
7492 rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
7497 @section @code{@@quotation}
7501 The text of a quotation is processed normally except that:
7505 the margins are closer to the center of the page, so the whole of the
7506 quotation is indented;@refill
7509 the first lines of paragraphs are indented no more than other
7513 in the printed output, interparagraph spacing is reduced.@refill
7517 This is an example of text written between an @code{@@quotation}
7518 command and an @code{@@end quotation} command. An @code{@@quotation}
7519 command is most often used to indicate text that is excerpted from
7520 another (real or hypothetical) printed work.@refill
7523 Write an @code{@@quotation} command as text on a line by itself. This
7524 line will disappear from the output. Mark the end of the quotation
7525 with a line beginning with and containing only @code{@@end quotation}.
7526 The @code{@@end quotation} line will likewise disappear from the
7527 output. Thus, the following,@refill
7545 @section @code{@@example}: Example Text
7546 @cindex Examples, formatting them
7547 @cindex Formatting examples
7550 The @code{@@example} command is used to indicate an example that is
7551 not part of the running text, such as computer input or output.
7555 This is an example of text written between an
7556 @code{@@example} command
7557 and an @code{@@end example} command.
7558 The text is indented but not filled.
7562 In the printed manual, the text is typeset in a
7563 fixed-width font, and extra spaces and blank lines are
7564 significant. In the Info file, an analogous result is
7565 obtained by indenting each line with five spaces.
7569 Write an @code{@@example} command at the beginning of a line by itself.
7570 Mark the end of the example
7571 with an @code{@@end example} command, also written at the beginning of a
7572 line by itself.@refill
7590 The lines containing @code{@@example} and @code{@@end example}
7591 will disappear from the output.
7592 To make the output look good,
7593 you should put a blank line before the
7594 @code{@@example} and another blank line after the @code{@@end example}.
7595 Note that blank lines inside the beginning
7596 @code{@@example} and the ending @code{@@end example} will appear in
7600 @strong{Caution:} Do not use tabs in the lines of an example or anywhere
7601 else in Texinfo (except in verbatim environments)! The @TeX{}
7602 implementation of Texinfo treats tabs as single spaces, and that is not
7603 what they look like. (If necessary, in Emacs, you can use @kbd{M-x
7604 untabify} to convert tabs in a region to multiple spaces.)@refill
7607 Examples are often, logically speaking, ``in the middle'' of a
7608 paragraph, and the text that continues after an example should not be
7609 indented. The @code{@@noindent} command prevents a piece of text from
7610 being indented as if it were a new paragraph.
7615 (The @code{@@code} command is used for examples of code that are
7616 embedded within sentences, not set off from preceding and following
7617 text. @xref{code, , @code{@@code}}.)
7621 @section @code{@@verbatim}: Literal Text
7623 @cindex Verbatim environment
7625 Use the @code{@@verbatim} environment for printing of text that may
7626 contain special characters or commands that should not be interpreted,
7627 such as computer input or output (@code{@@example} interprets its text
7628 as regular Texinfo commands). This is especially useful for including
7629 automatically generated output in a Texinfo manual. Here is an example;
7630 the output you see is just the same as the input, with a line
7631 @code{@@verbatim} before and a line @code{@@end verbatim} after.
7634 This is an example of text written in a @verbatim
7635 block. No character substitutions are made. All commands
7636 are ignored, until `<at>end verbatim'.
7638 In the printed manual, the text is typeset in a
7639 fixed-width font, and not indented or filled. All
7640 spaces and blank lines are significant, including tabs.
7643 Write a @code{@@verbatim} command at the beginning of a line by itself.
7644 This line will disappear from the output. Mark the end of the verbatim
7645 block with a @code{@@end verbatim} command, also written at the
7646 beginning of a line by itself. The @code{@@end verbatim} will also
7647 disappear from the output.
7650 @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
7655 @exdent <tab>@@command with strange characters: @@'e
7656 @exdent expand<tab>me
7658 @exdent @@end verbatim
7666 @command with strange characters: @'e
7671 Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
7672 produce no output, tyically you should put a blank line before the
7673 @code{@@verbatim} and another blank line after the @code{@@end
7674 verbatim}. Blank lines between the beginning @code{@@verbatim} and the
7675 ending @code{@@end verbatim} will appear in the output.
7678 @node verbatiminclude
7679 @section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
7680 @cindex Verbatim, include file
7681 @cindex Including a file verbatim
7682 @findex verbatiminclude
7684 You can include the exact contents of a file in the document with the
7685 @code{@@verbatiminclude} command:
7688 @@verbatiminclude @var{filename}
7691 The contents of @var{filename} is printed in a verbatim environment
7692 (@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
7693 exactly as it is, with all special characters and white space retained.
7697 @section @code{@@lisp}: Marking a Lisp Example
7699 @cindex Lisp example
7701 The @code{@@lisp} command is used for Lisp code. It is synonymous
7702 with the @code{@@example} command.
7705 This is an example of text written between an
7706 @code{@@lisp} command and an @code{@@end lisp} command.
7709 Use @code{@@lisp} instead of @code{@@example} to preserve information
7710 regarding the nature of the example. This is useful, for example, if
7711 you write a function that evaluates only and all the Lisp code in a
7712 Texinfo file. Then you can use the Texinfo file as a Lisp
7713 library.@footnote{It would be straightforward to extend Texinfo to work
7714 in a similar fashion for C, Fortran, or other languages.}
7716 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
7721 @section @code{@@small@dots{}} Block Commands
7722 @cindex Small examples
7723 @cindex Examples in smaller fonts
7724 @cindex Lisp examples in smaller fonts
7725 @findex smalldisplay
7726 @findex smallexample
7730 In addition to the regular @code{@@example} and @code{@@lisp} commands,
7731 Texinfo has ``small'' example-style commands. These are
7732 @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
7735 In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
7736 font than the non-small example commands. Consequently, many examples
7737 containing long lines fit on a page without needing to be shortened.
7739 In Info, the @code{@@small@dots{}} commands are equivalent to their
7740 non-small companion commands.
7742 Mark the end of an @code{@@small@dots{}} block with a corresponding
7743 @code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
7744 @code{@@end smallexample}.
7747 Here is an example written in the small font used by the
7748 @code{@@smallexample} and @code{@@smalllisp} commands:
7753 % Remove extra vskip; this is a kludge to counter the effect of display
7754 \vskip-3\baselineskip
7756 \dots{} to make sure that you have the freedom to
7757 distribute copies of free software (and charge for
7758 this service if you wish), that you receive source
7759 code or can get it if you want it, that you can
7760 change the software or use pieces of it in new free
7761 programs; and that you know you can do these things.}
7769 This is an example of text written between @code{@@smallexample} and
7770 @code{@@end smallexample}. In Info this text appears in its normal size;
7771 but in printed manuals, this text appears in a smaller font.
7777 This is an example of text written between @code{@@smallexample} and
7778 @code{@@end smallexample}. In Info this text appears in its normal size;
7779 but in a 7 by 9.25 inch manual, this text appears in a smaller font.
7783 The @code{@@small@dots{}} commands make it easier to prepare manuals
7784 without forcing you to edit examples by hand to fit them onto narrower
7787 As a general rule, a printed document looks better if you use only one
7788 of (for example) @code{@@example} or in @code{@@smallexample}
7789 consistently within a chapter. Only occasionally should you mix the two
7792 @xref{smallbook, , Printing ``Small'' Books}, for more information
7793 about the @code{@@smallbook} command.
7797 @section @code{@@display} and @code{@@smalldisplay}
7798 @cindex Display formatting
7801 The @code{@@display} command begins a kind of example. It is like the
7802 @code{@@example} command
7804 a printed manual, @code{@@display} does not select the fixed-width
7805 font. In fact, it does not specify the font at all, so that the text
7806 appears in the same font it would have appeared in without the
7807 @code{@@display} command.@refill
7810 This is an example of text written between an @code{@@display} command
7811 and an @code{@@end display} command. The @code{@@display} command
7812 indents the text, but does not fill it.
7815 @findex smalldisplay
7816 Texinfo also provides a command @code{@@smalldisplay}, which is like
7817 @code{@@display} but uses a smaller font in @code{@@smallbook} format.
7822 @section @code{@@format} and @code{@@smallformat}
7825 The @code{@@format} command is similar to @code{@@example} except
7826 that, in the printed manual, @code{@@format} does not select the
7827 fixed-width font and does not narrow the margins.@refill
7830 This is an example of text written between an @code{@@format} command
7831 and an @code{@@end format} command. As you can see
7833 the @code{@@format} command does not fill the text.
7837 Texinfo also provides a command @code{@@smallformat}, which is like
7838 @code{@@format} but uses a smaller font in @code{@@smallbook} format.
7844 @section @code{@@exdent}: Undoing a Line's Indentation
7845 @cindex Indentation undoing
7848 The @code{@@exdent} command removes any indentation a line might have.
7849 The command is written at the beginning of a line and applies only to
7850 the text that follows the command that is on the same line. Do not use
7851 braces around the text. In a printed manual, the text on an
7852 @code{@@exdent} line is printed in the roman font.@refill
7854 @code{@@exdent} is usually used within examples. Thus,@refill
7859 This line follows an @@@@example command.
7860 @@exdent This line is exdented.
7861 This line follows the exdented line.
7862 The @@@@end example comes on the next line.
7872 This line follows an @@example command.
7873 @exdent This line is exdented.
7874 This line follows the exdented line.
7875 The @@end example comes on the next line.
7879 In practice, the @code{@@exdent} command is rarely used.
7880 Usually, you un-indent text by ending the example and
7881 returning the page to its normal width.@refill
7884 @node flushleft & flushright
7885 @section @code{@@flushleft} and @code{@@flushright}
7888 @cindex ragged right
7891 The @code{@@flushleft} and @code{@@flushright} commands line up the
7892 ends of lines on the left and right margins of a page,
7893 but do not fill the text. The commands are written on lines of their
7894 own, without braces. The @code{@@flushleft} and @code{@@flushright}
7895 commands are ended by @code{@@end flushleft} and @code{@@end
7896 flushright} commands on lines of their own.@refill
7921 @code{@@flushright} produces the type of indentation often used in the
7922 return address of letters. For example,
7927 Here is an example of text written
7928 flushright. The @@code@{@@flushright@} command
7929 right justifies every line but leaves the
7939 Here is an example of text written
7940 flushright. The @code{@@flushright} command
7941 right justifies every line but leaves the
7947 @section @code{@@noindent}: Omitting Indentation
7950 An example or other inclusion can break a paragraph into segments.
7951 Ordinarily, the formatters indent text that follows an example as a new
7952 paragraph. However, you can prevent this by writing @code{@@noindent}
7953 at the beginning of a line by itself preceding the continuation
7966 This line is not indented. As you can see, the
7967 beginning of the line is fully flush left with the line
7968 that follows after it. (This whole example is between
7969 @@code@{@@@@display@} and @@code@{@@@@end display@}.)
7981 % Remove extra vskip; this is a kludge to counter the effect of display
7982 \vskip-3.5\baselineskip
7986 This line is not indented. As you can see, the
7987 beginning of the line is fully flush left with the line
7988 that follows after it. (This whole example is between
7989 @code{@@display} and @code{@@end display}.)
7992 To adjust the number of blank lines properly in the Info file output,
7993 remember that the line containing @code{@@noindent} does not generate a
7994 blank line, and neither does the @code{@@end example} line.@refill
7996 In the Texinfo source file for this manual, each line that says
7997 `produces' is preceded by a line containing @code{@@noindent}.@refill
7999 Do not put braces after an @code{@@noindent} command; they are not
8000 necessary, since @code{@@noindent} is a command used outside of
8001 paragraphs (@pxref{Command Syntax}).@refill
8005 @section @code{@@cartouche}: Rounded Rectangles Around Examples
8007 @cindex Box with rounded corners
8008 @cindex Rounded rectangles, around examples
8010 In a printed manual, the @code{@@cartouche} command draws a box with
8011 rounded corners around its contents. You can use this command to
8012 further highlight an example or quotation. For instance, you could
8013 write a manual in which one type of example is surrounded by a cartouche
8016 @code{@@cartouche} affects only the printed manual; it has no effect in
8027 /usr/local/share/emacs
8034 surrounds the two-line example with a box with rounded corners, in the
8038 In a printed manual, the example looks like this:@refill
8044 /usr/local/lib/emacs/info
8051 @node Lists and Tables
8052 @chapter Lists and Tables
8053 @cindex Making lists and tables
8054 @cindex Lists and tables, making
8055 @cindex Tables and lists, making
8057 Texinfo has several ways of making lists and tables. Lists can be
8058 bulleted or numbered; two-column tables can highlight the items in
8059 the first column; multi-column tables are also supported.
8062 * Introducing Lists:: Texinfo formats lists for you.
8063 * itemize:: How to construct a simple list.
8064 * enumerate:: How to construct a numbered list.
8065 * Two-column Tables:: How to construct a two-column table.
8066 * Multi-column Tables:: How to construct generalized tables.
8069 @node Introducing Lists, itemize, Lists and Tables, Lists and Tables
8071 @heading Introducing Lists
8074 Texinfo automatically indents the text in lists or tables, and numbers
8075 an enumerated list. This last feature is useful if you modify the
8076 list, since you do not need to renumber it yourself.@refill
8078 Numbered lists and tables begin with the appropriate @@-command at the
8079 beginning of a line, and end with the corresponding @code{@@end}
8080 command on a line by itself. The table and itemized-list commands
8081 also require that you write formatting information on the same line as
8082 the beginning @@-command.@refill
8084 Begin an enumerated list, for example, with an @code{@@enumerate}
8085 command and end the list with an @code{@@end enumerate} command.
8086 Begin an itemized list with an @code{@@itemize} command, followed on
8087 the same line by a formatting command such as @code{@@bullet}, and end
8088 the list with an @code{@@end itemize} command.@refill
8091 Precede each element of a list with an @code{@@item} or @code{@@itemx}
8096 Here is an itemized list of the different kinds of table and lists:@refill
8100 Itemized lists with and without bullets.
8103 Enumerated lists, using numbers or letters.
8106 Two-column tables with highlighting.
8111 Here is an enumerated list with the same items:@refill
8115 Itemized lists with and without bullets.
8118 Enumerated lists, using numbers or letters.
8121 Two-column tables with highlighting.
8126 And here is a two-column table with the same items and their
8127 @w{@@-commands}:@refill
8131 Itemized lists with and without bullets.
8134 Enumerated lists, using numbers or letters.
8139 Two-column tables, optionally with indexing.
8144 @section @code{@@itemize}: Making an Itemized List
8148 The @code{@@itemize} command produces sequences of indented
8149 paragraphs, with a bullet or other mark inside the left margin
8150 at the beginning of each paragraph for which such a mark is desired.@refill
8152 @cindex @code{@@w}, for blank items
8153 Begin an itemized list by writing @code{@@itemize} at the beginning of
8154 a line. Follow the command, on the same line, with a character or a
8155 Texinfo command that generates a mark. Usually, you will write
8156 @code{@@bullet} after @code{@@itemize}, but you can use
8157 @code{@@minus}, or any command or character that results in a single
8158 character in the Info file. If you don't want any mark at all, use
8159 @code{@@w}. (When you write the mark command such as
8160 @code{@@bullet} after an @code{@@itemize} command, you may omit the
8161 @samp{@{@}}.) If you don't specify a mark command, the default is
8164 Write the text of the indented paragraphs themselves after the
8165 @code{@@itemize}, up to another line that says @code{@@end
8169 Before each paragraph for which a mark in the margin is desired, write a
8170 line that says just @code{@@item}. It is ok to have text following the
8173 Usually, you should put a blank line before an @code{@@item}. This
8174 puts a blank line in the Info file. (@TeX{} inserts the proper
8175 interline whitespace in either case.) Except when the entries are
8176 very brief, these blank lines make the list look better.@refill
8178 Here is an example of the use of @code{@@itemize}, followed by the
8179 output it produces. @code{@@bullet} produces an @samp{*} in Info and a
8180 round dot in @TeX{}.
8209 Itemized lists may be embedded within other itemized lists. Here is a
8210 list marked with dashes embedded in a list marked with bullets:@refill
8255 @section @code{@@enumerate}: Making a Numbered or Lettered List
8259 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
8260 @code{@@itemize}}), except that the labels on the items are
8261 successive integers or letters instead of bullets.
8263 Write the @code{@@enumerate} command at the beginning of a line. The
8264 command does not require an argument, but accepts either a number or a
8265 letter as an option. Without an argument, @code{@@enumerate} starts the
8266 list with the number @samp{1}. With a numeric argument, such as
8267 @samp{3}, the command starts the list with that number. With an upper
8268 or lower case letter, such as @samp{a} or @samp{A}, the command starts
8269 the list with that letter.
8271 Write the text of the enumerated list in the same way you write an
8272 itemized list: put @code{@@item} on a line of its own before the start
8273 of each paragraph that you want enumerated. Do not write any other text
8274 on the line beginning with @code{@@item}.
8276 You should put a blank line between entries in the list.
8277 This generally makes it easier to read the Info file.
8280 Here is an example of @code{@@enumerate} without an argument:
8305 Here is an example with an argument of @kbd{3}:@refill
8311 Predisposing causes.
8314 Precipitating causes.
8317 Perpetuating causes.
8327 Predisposing causes.
8330 Precipitating causes.
8333 Perpetuating causes.
8336 Here is a brief summary of the alternatives. The summary is constructed
8337 using @code{@@enumerate} with an argument of @kbd{a}.@refill
8343 Without an argument, produce a numbered list, starting with the number
8347 @code{@@enumerate @var{positive-integer}}
8349 With a (positive) numeric argument, start a numbered list with that
8350 number. You can use this to continue a list that you interrupted with
8354 @code{@@enumerate @var{upper-case-letter}}
8356 With an upper case letter as argument, start a list
8357 in which each item is marked
8358 by a letter, beginning with that upper case letter.@refill
8361 @code{@@enumerate @var{lower-case-letter}}
8363 With a lower case letter as argument, start a list
8364 in which each item is marked by
8365 a letter, beginning with that lower case letter.@refill
8368 You can also nest enumerated lists, as in an outline.@refill
8370 @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
8371 @section Making a Two-column Table
8372 @cindex Tables, making two-column
8375 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
8376 @code{@@itemize}}), but allows you to specify a name or heading line for
8377 each item. The @code{@@table} command is used to produce two-column
8378 tables, and is especially useful for glossaries, explanatory
8379 exhibits, and command-line option summaries.
8382 * table:: How to construct a two-column table.
8383 * ftable vtable:: Automatic indexing for two-column tables.
8384 * itemx:: How to put more entries in the first column.
8387 @node table, ftable vtable, Two-column Tables, Two-column Tables
8389 @subheading Using the @code{@@table} Command
8391 Use the @code{@@table} command to produce two-column tables.@refill
8394 Write the @code{@@table} command at the beginning of a line and follow
8395 it on the same line with an argument that is a Texinfo ``indicating''
8396 command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
8397 @code{@@kbd} (@pxref{Indicating}). Although these commands are usually
8398 followed by arguments in braces, in this case you use the command name
8399 without an argument because @code{@@item} will supply the argument.
8400 This command will be applied to the text that goes into the first column
8401 of each item and determines how it will be highlighted. For example,
8402 @code{@@code} will cause the text in the first column to be highlighted
8403 with an @code{@@code} command. (We recommend @code{@@code} for
8404 @code{@@table}'s of command-line options.)
8407 You may also choose to use the @code{@@asis} command as an argument to
8408 @code{@@table}. @code{@@asis} is a command that does nothing; if you
8409 use this command after @code{@@table}, @TeX{} and the Info formatting
8410 commands output the first column entries without added highlighting
8413 (The @code{@@table} command may work with other commands besides those
8414 listed here. However, you can only use commands that normally take
8415 arguments in braces.)@refill
8418 Begin each table entry with an @code{@@item} command at the beginning
8419 of a line. Write the first column text on the same line as the
8420 @code{@@item} command. Write the second column text on the line
8421 following the @code{@@item} line and on subsequent lines. (You do not
8422 need to type anything for an empty second column entry.) You may
8423 write as many lines of supporting text as you wish, even several
8424 paragraphs. But only text on the same line as the @code{@@item} will
8425 be placed in the first column, including any footnote.
8427 Normally, you should put a blank line before an @code{@@item} line.
8428 This puts a blank like in the Info file. Except when the entries are
8429 very brief, a blank line looks better.@refill
8432 The following table, for example, highlights the text in the first
8433 column with an @code{@@samp} command:@refill
8439 This is the text for
8443 Text for @@samp@{bar@}.
8453 This is the text for
8456 Text for @samp{bar}.
8459 If you want to list two or more named items with a single block of
8460 text, use the @code{@@itemx} command. (@xref{itemx, ,
8461 @code{@@itemx}}.)@refill
8465 @subsection @code{@@ftable} and @code{@@vtable}
8466 @cindex Tables with indexes
8467 @cindex Indexing table entries automatically
8471 The @code{@@ftable} and @code{@@vtable} commands are the same as the
8472 @code{@@table} command except that @code{@@ftable} automatically enters
8473 each of the items in the first column of the table into the index of
8474 functions and @code{@@vtable} automatically enters each of the items in
8475 the first column of the table into the index of variables. This
8476 simplifies the task of creating indices. Only the items on the same
8477 line as the @code{@@item} commands are indexed, and they are indexed in
8478 exactly the form that they appear on that line. @xref{Indices},
8479 for more information about indices.@refill
8481 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8482 writing the @@-command at the beginning of a line, followed on the same
8483 line by an argument that is a Texinfo command such as @code{@@code},
8484 exactly as you would for an @code{@@table} command; and end the table
8485 with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8488 See the example for @code{@@table} in the previous section.
8491 @subsection @code{@@itemx}
8492 @cindex Two named items for @code{@@table}
8495 Use the @code{@@itemx} command inside a table when you have two or more
8496 first column entries for the same item, each of which should appear on a
8497 line of its own. Use @code{@@itemx} for all but the first entry;
8498 @code{@@itemx} should always follow an @code{@@item} command. The
8499 @code{@@itemx} command works exactly like @code{@@item} except that it
8500 does not generate extra vertical space above the first column text.
8509 These two functions accept a character or a string as
8510 argument, and return the corresponding upper case (lower
8511 case) character or string.
8522 These two functions accept a character or a string as
8523 argument, and return the corresponding upper case (lower
8524 case) character or string.@refill
8528 (Note also that this example illustrates multi-line supporting text in
8529 a two-column table.)@refill
8532 @node Multi-column Tables, , Two-column Tables, Lists and Tables
8533 @section Multi-column Tables
8534 @cindex Tables, making multi-column
8537 @code{@@multitable} allows you to construct tables with any number of
8538 columns, with each column having any width you like.
8540 You define the column widths on the @code{@@multitable} line itself, and
8541 write each row of the actual table following an @code{@@item} command,
8542 with columns separated by an @code{@@tab} command. Finally, @code{@@end
8543 multitable} completes the table. Details in the sections below.
8546 * Multitable Column Widths:: Defining multitable column widths.
8547 * Multitable Rows:: Defining multitable rows, with examples.
8550 @node Multitable Column Widths
8551 @subsection Multitable Column Widths
8552 @cindex Multitable column widths
8553 @cindex Column widths, defining for multitables
8554 @cindex Widths, defining multitable column
8556 You can define the column widths for a multitable in two ways: as
8557 fractions of the line length; or with a prototype row. Mixing the two
8558 methods is not supported. In either case, the widths are defined
8559 entirely on the same line as the @code{@@multitable} command.
8563 @findex columnfractions
8564 @cindex Line length, column widths as fraction of
8565 To specify column widths as fractions of the line length, write
8566 @code{@@columnfractions} and the decimal numbers (presumably less than
8567 1) after the @code{@@multitable} command, as in:
8570 @@multitable @@columnfractions .33 .33 .33
8573 @noindent The fractions need not add up exactly to 1.0, as these do
8574 not. This allows you to produce tables that do not need the full line
8575 length. You can use a leading zero if you wish.
8578 @cindex Prototype row, column widths defined by
8579 To specify a prototype row, write the longest entry for each column
8580 enclosed in braces after the @code{@@multitable} command. For example:
8583 @@multitable @{some text for column one@} @{for column two@}
8587 The first column will then have the width of the typeset `some text for
8588 column one', and the second column the width of `for column two'.
8590 The prototype entries need not appear in the table itself.
8592 Although we used simple text in this example, the prototype entries can
8593 contain Texinfo commands; markup commands such as @code{@@code} are
8594 particularly likely to be useful.
8599 @node Multitable Rows, , Multitable Column Widths, Multi-column Tables
8600 @subsection Multitable Rows
8601 @cindex Multitable rows
8602 @cindex Rows, of a multitable
8606 After the @code{@@multitable} command defining the column widths (see
8607 the previous section), you begin each row in the body of a multitable
8608 with @code{@@item}, and separate the column entries with @code{@@tab}.
8609 Line breaks are not special within the table body, and you may break
8610 input lines in your source file as necessary.
8612 Here is a complete example of a multi-column table (the text is from
8613 @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
8614 emacs, The GNU Emacs Manual}):
8617 @@multitable @@columnfractions .15 .45 .4
8618 @@item Key @@tab Command @@tab Description
8620 @@tab @@code@{split-window-vertically@}
8621 @@tab Split the selected window into two windows,
8622 with one above the other.
8624 @@tab @@code@{split-window-horizontally@}
8625 @@tab Split the selected window into two windows
8626 positioned side by side.
8629 @@tab In the mode line or scroll bar of a window,
8636 @multitable @columnfractions .15 .45 .4
8637 @item Key @tab Command @tab Description
8639 @tab @code{split-window-vertically}
8640 @tab Split the selected window into two windows,
8641 with one above the other.
8643 @tab @code{split-window-horizontally}
8644 @tab Split the selected window into two windows
8645 positioned side by side.
8648 @tab In the mode line or scroll bar of a window,
8653 @node Indices, Insertions, Lists and Tables, Top
8654 @comment node-name, next, previous, up
8658 Using Texinfo, you can generate indices without having to sort and
8659 collate entries manually. In an index, the entries are listed in
8660 alphabetical order, together with information on how to find the
8661 discussion of each entry. In a printed manual, this information
8662 consists of page numbers. In an Info file, this information is a menu
8663 entry leading to the first node referenced.@refill
8665 Texinfo provides several predefined kinds of index: an index
8666 for functions, an index for variables, an index for concepts, and so
8667 on. You can combine indices or use them for other than their
8668 canonical purpose. If you wish, you can define your own indices.@refill
8671 * Index Entries:: Choose different words for index entries.
8672 * Predefined Indices:: Use different indices for different kinds
8674 * Indexing Commands:: How to make an index entry.
8675 * Combining Indices:: How to combine indices.
8676 * New Indices:: How to define your own indices.
8679 @node Index Entries, Predefined Indices, Indices, Indices
8680 @comment node-name, next, previous, up
8681 @section Making Index Entries
8682 @cindex Index entries, making
8683 @cindex Entries, making index
8685 When you are making index entries, it is good practice to think of the
8686 different ways people may look for something. Different people
8687 @emph{do not} think of the same words when they look something up. A
8688 helpful index will have items indexed under all the different words
8689 that people may use. For example, one reader may think it obvious that
8690 the two-letter names for indices should be listed under ``Indices,
8691 two-letter names'', since the word ``Index'' is the general concept.
8692 But another reader may remember the specific concept of two-letter
8693 names and search for the entry listed as ``Two letter names for
8694 indices''. A good index will have both entries and will help both
8697 Like typesetting, the construction of an index is a highly skilled,
8698 professional art, the subtleties of which are not appreciated until you
8699 need to do it yourself.@refill
8701 @xref{Printing Indices & Menus}, for information about printing an index
8702 at the end of a book or creating an index menu in an Info file.@refill
8704 @node Predefined Indices, Indexing Commands, Index Entries, Indices
8705 @comment node-name, next, previous, up
8706 @section Predefined Indices
8708 Texinfo provides six predefined indices:@refill
8712 A @dfn{concept index} listing concepts that are discussed.@refill
8715 A @dfn{function index} listing functions (such as entry points of
8719 A @dfn{variables index} listing variables (such as global variables
8720 of libraries).@refill
8723 A @dfn{keystroke index} listing keyboard commands.@refill
8726 A @dfn{program index} listing names of programs.@refill
8729 A @dfn{data type index} listing data types (such as structures defined in
8730 header files).@refill
8734 Not every manual needs all of these, and most manuals use two or three
8735 of them. This manual has two indices: a
8736 concept index and an @@-command index (that is actually the function
8737 index but is called a command index in the chapter heading). Two or
8738 more indices can be combined into one using the @code{@@synindex} or
8739 @code{@@syncodeindex} commands. @xref{Combining Indices}.@refill
8741 @node Indexing Commands, Combining Indices, Predefined Indices, Indices
8742 @comment node-name, next, previous, up
8743 @section Defining the Entries of an Index
8744 @cindex Defining indexing entries
8745 @cindex Index entries
8746 @cindex Entries for an index
8747 @cindex Specifying index entries
8748 @cindex Creating index entries
8750 The data to make an index come from many individual indexing commands
8751 scattered throughout the Texinfo source file. Each command says to add
8752 one entry to a particular index; after formatting, the index will give
8753 the current page number or node name as the reference.@refill
8755 An index entry consists of an indexing command at the beginning of a
8756 line followed, on the rest of the line, by the entry.@refill
8758 For example, this section begins with the following five entries for
8759 the concept index:@refill
8762 @@cindex Defining indexing entries
8763 @@cindex Index entries
8764 @@cindex Entries for an index
8765 @@cindex Specifying index entries
8766 @@cindex Creating index entries
8769 Each predefined index has its own indexing command---@code{@@cindex}
8770 for the concept index, @code{@@findex} for the function index, and so
8773 @cindex Writing index entries
8774 @cindex Index entry writing
8775 Concept index entries consist of text. The best way to write an index
8776 is to choose entries that are terse yet clear. If you can do this,
8777 the index often looks better if the entries are not capitalized, but
8778 written just as they would appear in the middle of a sentence.
8779 (Capitalize proper names and acronyms that always call for upper case
8780 letters.) This is the case convention we use in most GNU manuals'
8783 If you don't see how to make an entry terse yet clear, make it longer
8784 and clear---not terse and confusing. If many of the entries are several
8785 words long, the index may look better if you use a different convention:
8786 to capitalize the first word of each entry. But do not capitalize a
8787 case-sensitive name such as a C or Lisp function name or a shell
8788 command; that would be a spelling error.
8790 Whichever case convention you use, please use it consistently!
8792 Entries in indices other than the concept index are symbol names in
8793 programming languages, or program names; these names are usually
8794 case-sensitive, so use upper and lower case as required for them.
8796 By default, entries for a concept index are printed in a small roman
8797 font and entries for the other indices are printed in a small
8798 @code{@@code} font. You may change the way part of an entry is
8799 printed with the usual Texinfo commands, such as @code{@@file} for
8800 file names and @code{@@emph} for emphasis (@pxref{Marking
8802 @cindex Index font types
8804 @cindex Predefined indexing commands
8805 @cindex Indexing commands, predefined
8806 The six indexing commands for predefined indices are:
8809 @item @@cindex @var{concept}
8811 Make an entry in the concept index for @var{concept}.@refill
8813 @item @@findex @var{function}
8815 Make an entry in the function index for @var{function}.@refill
8817 @item @@vindex @var{variable}
8819 Make an entry in the variable index for @var{variable}.@refill
8821 @item @@kindex @var{keystroke}
8823 Make an entry in the key index for @var{keystroke}.@refill
8825 @item @@pindex @var{program}
8827 Make an entry in the program index for @var{program}.@refill
8829 @item @@tindex @var{data type}
8831 Make an entry in the data type index for @var{data type}.@refill
8835 @strong{Caution:} Do not use a colon in an index entry. In Info, a
8836 colon separates the menu entry name from the node name, so a colon in
8837 the entry itself confuses Info. @xref{Menu Parts, , The Parts of a
8838 Menu}, for more information about the structure of a menu entry.
8841 You are not actually required to use the predefined indices for their
8842 canonical purposes. For example, suppose you wish to index some C
8843 preprocessor macros. You could put them in the function index along
8844 with actual functions, just by writing @code{@@findex} commands for
8845 them; then, when you print the ``Function Index'' as an unnumbered
8846 chapter, you could give it the title `Function and Macro Index' and
8847 all will be consistent for the reader. Or you could put the macros in
8848 with the data types by writing @code{@@tindex} commands for them, and
8849 give that index a suitable title so the reader will understand.
8850 (@xref{Printing Indices & Menus}.)@refill
8852 @node Combining Indices, New Indices, Indexing Commands, Indices
8853 @comment node-name, next, previous, up
8854 @section Combining Indices
8855 @cindex Combining indices
8856 @cindex Indices, combining them
8858 Sometimes you will want to combine two disparate indices such as functions
8859 and concepts, perhaps because you have few enough of one of them that
8860 a separate index for them would look silly.@refill
8862 You could put functions into the concept index by writing
8863 @code{@@cindex} commands for them instead of @code{@@findex} commands,
8864 and produce a consistent manual by printing the concept index with the
8865 title `Function and Concept Index' and not printing the `Function
8866 Index' at all; but this is not a robust procedure. It works only if
8867 your document is never included as part of another
8868 document that is designed to have a separate function index; if your
8869 document were to be included with such a document, the functions from
8870 your document and those from the other would not end up together.
8871 Also, to make your function names appear in the right font in the
8872 concept index, you would need to enclose every one of them between
8873 the braces of @code{@@code}.@refill
8876 * syncodeindex:: How to merge two indices, using @code{@@code}
8877 font for the merged-from index.
8878 * synindex:: How to merge two indices, using the
8879 default font of the merged-to index.
8883 @subsection @code{@@syncodeindex}
8884 @findex syncodeindex
8886 When you want to combine functions and concepts into one index, you
8887 should index the functions with @code{@@findex} and index the concepts
8888 with @code{@@cindex}, and use the @code{@@syncodeindex} command to
8889 redirect the function index entries into the concept index.@refill
8890 @findex syncodeindex
8892 The @code{@@syncodeindex} command takes two arguments; they are the name
8893 of the index to redirect, and the name of the index to redirect it to.
8894 The template looks like this:@refill
8897 @@syncodeindex @var{from} @var{to}
8900 @cindex Predefined names for indices
8901 @cindex Two letter names for indices
8902 @cindex Indices, two letter names
8903 @cindex Names for indices
8904 For this purpose, the indices are given two-letter names:@refill
8921 Write an @code{@@syncodeindex} command before or shortly after the
8922 end-of-header line at the beginning of a Texinfo file. For example,
8923 to merge a function index with a concept index, write the
8927 @@syncodeindex fn cp
8931 This will cause all entries designated for the function index to merge
8932 in with the concept index instead.@refill
8934 To merge both a variables index and a function index into a concept
8935 index, write the following:@refill
8939 @@syncodeindex vr cp
8940 @@syncodeindex fn cp
8944 @cindex Fonts for indices
8945 The @code{@@syncodeindex} command puts all the entries from the `from'
8946 index (the redirected index) into the @code{@@code} font, overriding
8947 whatever default font is used by the index to which the entries are
8948 now directed. This way, if you direct function names from a function
8949 index into a concept index, all the function names are printed in the
8950 @code{@@code} font as you would expect.@refill
8952 @node synindex, , syncodeindex, Combining Indices
8953 @subsection @code{@@synindex}
8956 The @code{@@synindex} command is nearly the same as the
8957 @code{@@syncodeindex} command, except that it does not put the
8958 `from' index entries into the @code{@@code} font; rather it puts
8959 them in the roman font. Thus, you use @code{@@synindex} when you
8960 merge a concept index into a function index.@refill
8962 @xref{Printing Indices & Menus}, for information about printing an index
8963 at the end of a book or creating an index menu in an Info file.@refill
8965 @node New Indices, , Combining Indices, Indices
8966 @section Defining New Indices
8967 @cindex Defining new indices
8968 @cindex Indices, defining new
8969 @cindex New index defining
8971 @findex defcodeindex
8973 In addition to the predefined indices, you may use the
8974 @code{@@defindex} and @code{@@defcodeindex} commands to define new
8975 indices. These commands create new indexing @@-commands with which
8976 you mark index entries. The @code{@@defindex }command is used like
8980 @@defindex @var{name}
8983 The name of an index should be a two letter word, such as @samp{au}.
8990 This defines a new index, called the @samp{au} index. At the same
8991 time, it creates a new indexing command, @code{@@auindex}, that you
8992 can use to make index entries. Use the new indexing command just as
8993 you would use a predefined indexing command.@refill
8995 For example, here is a section heading followed by a concept index
8996 entry and two @samp{au} index entries.@refill
8999 @@section Cognitive Semantics
9000 @@cindex kinesthetic image schemas
9001 @@auindex Johnson, Mark
9002 @@auindex Lakoff, George
9006 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
9007 Texinfo constructs the new indexing command by concatenating the name
9008 of the index with @samp{index}; thus, defining an @samp{au} index
9009 leads to the automatic creation of an @code{@@auindex} command.@refill
9011 Use the @code{@@printindex} command to print the index, as you do with
9012 the predefined indices. For example:@refill
9016 @@node Author Index, Subject Index, , Top
9017 @@unnumbered Author Index
9023 The @code{@@defcodeindex} is like the @code{@@defindex} command, except
9024 that, in the printed output, it prints entries in an @code{@@code} font
9025 instead of a roman font. Thus, it parallels the @code{@@findex} command
9026 rather than the @code{@@cindex} command.@refill
9028 You should define new indices within or right after the end-of-header
9029 line of a Texinfo file, before any @code{@@synindex} or
9030 @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
9034 @chapter Special Insertions
9035 @cindex Inserting special characters and symbols
9036 @cindex Special insertions
9038 Texinfo provides several commands for inserting characters that have
9039 special meaning in Texinfo, such as braces, and for other graphic
9040 elements that do not correspond to simple characters you can type.
9046 @item Braces and @samp{@@}.
9047 @item Whitespace within and around a sentence.
9049 @item Dots and bullets.
9050 @item The @TeX{} logo and the copyright symbol.
9051 @item The pounds currency symbol.
9052 @item The minus sign.
9053 @item Mathematical expressions.
9054 @item Glyphs for evaluation, macros, errors, etc.
9061 * Braces Atsigns:: How to insert braces, @samp{@@}.
9062 * Inserting Space:: How to insert the right amount of space
9064 * Inserting Accents:: How to insert accents and special characters.
9065 * Dots Bullets:: How to insert dots and bullets.
9066 * TeX and copyright:: How to insert the @TeX{} logo
9067 and the copyright symbol.
9068 * pounds:: How to insert the pounds currency symbol.
9069 * minus:: How to insert a minus sign.
9070 * math:: How to format a mathematical expression.
9071 * Glyphs:: How to indicate results of evaluation,
9072 expansion of macros, errors, etc.
9073 * Footnotes:: How to include footnotes.
9074 * Images:: How to include graphics.
9078 @node Braces Atsigns, Inserting Space, Insertions, Insertions
9079 @section Inserting @@ and Braces
9080 @cindex Inserting @@, braces
9081 @cindex Braces, inserting
9082 @cindex Special characters, commands to insert
9083 @cindex Commands to insert special characters
9085 @samp{@@} and curly braces are special characters in Texinfo. To insert
9086 these characters so they appear in text, you must put an @samp{@@} in
9087 front of these characters to prevent Texinfo from misinterpreting
9090 Do not put braces after any of these commands; they are not
9094 * Inserting An Atsign:: How to insert @samp{@@}.
9095 * Inserting Braces:: How to insert @samp{@{} and @samp{@}}.
9098 @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
9099 @subsection Inserting @samp{@@} with @@@@
9100 @findex @@ @r{(literal @samp{@@})}
9102 @code{@@@@} stands for a single @samp{@@} in either printed or Info
9105 Do not put braces after an @code{@@@@} command.
9108 @node Inserting Braces
9109 @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
9110 @findex @{ @r{(literal @samp{@{})}
9111 @findex @} @r{(literal @samp{@}})}
9113 @code{@@@{} stands for a single @samp{@{} in either printed or Info
9116 @code{@@@}} stands for a single @samp{@}} in either printed or Info
9119 Do not put braces after either an @code{@@@{} or an @code{@@@}}
9123 @node Inserting Space
9124 @section Inserting Space
9126 @cindex Inserting space
9127 @cindex Spacing, inserting
9128 The following sections describe commands that control spacing of various
9129 kinds within and after sentences.
9132 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
9133 * Ending a Sentence:: Sometimes it does.
9134 * Multiple Spaces:: Inserting multiple spaces.
9135 * dmn:: How to format a dimension.
9139 @node Not Ending a Sentence
9140 @subsection Not Ending a Sentence
9142 @cindex Not ending a sentence
9143 @cindex Sentence non-ending punctuation
9144 @cindex Periods, inserting
9145 Depending on whether a period or exclamation point or question mark is
9146 inside or at the end of a sentence, less or more space is inserted after
9147 a period in a typeset manual. Since it is not always possible
9148 to determine when a period ends a sentence and when it is used
9149 in an abbreviation, special commands are needed in some circumstances.
9150 Usually, Texinfo can guess how to handle periods, so you do not need to
9151 use the special commands; you just enter a period as you would if you
9152 were using a typewriter, which means you put two spaces after the
9153 period, question mark, or exclamation mark that ends a sentence.
9155 @findex <colon> @r{(suppress widening)}
9156 Use the @code{@@:}@: command after a period, question mark,
9157 exclamation mark, or colon that should not be followed by extra space.
9158 For example, use @code{@@:}@: after periods that end abbreviations
9159 which are not at the ends of sentences.
9164 The s.o.p.@@: has three parts @dots{}
9165 The s.o.p. has three parts @dots{}
9173 produces the following. If you look carefully at this printed output,
9174 you will see a little more whitespace after @samp{s.o.p.} in the second
9179 The s.o.p.@: has three parts @dots{}@*
9180 The s.o.p. has three parts @dots{}
9184 (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
9187 @code{@@:} has no effect on the Info output. Do not put braces after
9191 @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
9192 @subsection Ending a Sentence
9194 @cindex Ending a Sentence
9195 @cindex Sentence ending punctuation
9197 @findex . @r{(end of sentence)}
9198 @findex ! @r{(end of sentence)}
9199 @findex ? @r{(end of sentence)}
9200 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
9201 exclamation point, and @code{@@?}@: instead of a question mark at the end
9202 of a sentence that ends with a single capital letter. Otherwise, @TeX{}
9203 will think the letter is an abbreviation and will not insert the correct
9204 end-of-sentence spacing. Here is an example:
9207 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
9208 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9216 produces the following. If you look carefully at this printed output,
9217 you will see a little more whitespace after the @samp{W} in the first
9222 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
9223 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
9226 In the Info file output, @code{@@.}@: is equivalent to a simple
9227 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
9229 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
9230 work well with the Emacs sentence motion commands (@pxref{Sentences,,,
9231 emacs, The GNU Emacs Manual}).
9233 Do not put braces after any of these commands.
9236 @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
9237 @subsection Multiple Spaces
9239 @cindex Multiple spaces
9240 @cindex Whitespace, inserting
9241 @cindex Space, inserting horizontal
9246 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
9247 and newline) into a single space. Info output, on the other hand,
9248 preserves whitespace as you type it, except for changing a newline into
9249 a space; this is why it is important to put two spaces at the end of
9250 sentences in Texinfo documents.
9252 Occasionally, you may want to actually insert several consecutive
9253 spaces, either for purposes of example (what your program does with
9254 multiple spaces as input), or merely for purposes of appearance in
9255 headings or lists. Texinfo supports three commands:
9256 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
9257 which insert a single space into the output. (Here,
9258 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
9259 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
9260 character and end-of-line, i.e., when @samp{@@} is the last character on
9276 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
9277 @code{@@multitable} (@pxref{Multi-column Tables}).
9279 Do not follow any of these commands with braces.
9281 To produce a non-breakable space, see @ref{w, non-breakable space}.
9285 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
9286 @cindex Thin space between number, dimension
9287 @cindex Dimension formatting
9288 @cindex Format a dimension
9291 At times, you may want to write @samp{12@dmn{pt}} or
9292 @samp{8.5@dmn{in}} with little or no space between the number and the
9293 abbreviation for the dimension. You can use the @code{@@dmn} command
9294 to do this. On seeing the command, @TeX{} inserts just enough space
9295 for proper typesetting; the Info formatting commands insert no space
9296 at all, since the Info file does not require it.
9298 To use the @code{@@dmn} command, write the number and then follow it
9299 immediately, with no intervening space, by @code{@@dmn}, and then by
9300 the dimension within braces. For example,
9303 A4 paper is 8.27@@dmn@{in@} wide.
9310 A4 paper is 8.27@dmn{in} wide.
9313 Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
9314 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
9315 In these cases, however, the formatters may insert a line break between
9316 the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
9317 you write a period after an abbreviation within a sentence, you should
9318 write @samp{@@:} after the period to prevent @TeX{} from inserting extra
9319 whitespace, as shown here. @xref{Not Ending a Sentence}.
9322 @node Inserting Accents
9323 @section Inserting Accents
9325 @cindex Inserting accents
9326 @cindex Accents, inserting
9327 @cindex Floating accents, inserting
9329 Here is a table with the commands Texinfo provides for inserting
9330 floating accents. The commands with non-alphabetic names do not take
9331 braces around their argument (which is taken to be the next character).
9332 (Exception: @code{@@,} @emph{does} take braces around its argument.)
9333 This is so as to make the source as convenient to type and read as
9334 possible, since accented characters are very common in some languages.
9336 @findex " @r{(umlaut accent)}
9337 @cindex Umlaut accent
9338 @findex ' @r{(umlaut accent)}
9339 @cindex Acute accent
9340 @findex = @r{(macron accent)}
9341 @cindex Macron accent
9342 @findex ^ @r{(circumflex accent)}
9343 @cindex Circumflex accent
9344 @findex ` @r{(grave accent)}
9345 @cindex Grave accent
9346 @findex ~ @r{(tilde accent)}
9347 @cindex Tilde accent
9348 @findex , @r{(cedilla accent)}
9349 @cindex Cedilla accent
9352 @findex H @r{(Hungarian umlaut accent)}
9353 @cindex Hungarian umlaut accent
9357 @cindex Tie-after accent
9358 @findex u @r{(breve accent)}
9359 @cindex Breve accent
9361 @cindex Underbar accent
9363 @cindex Underdot accent
9364 @findex v @r{(check accent)}
9365 @cindex Check accent
9366 @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
9367 @item Command @tab Output @tab What
9368 @item @t{@@"o} @tab @"o @tab umlaut accent
9369 @item @t{@@'o} @tab @'o @tab acute accent
9370 @item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
9371 @item @t{@@=o} @tab @=o @tab macron/overbar accent
9372 @item @t{@@^o} @tab @^o @tab circumflex accent
9373 @item @t{@@`o} @tab @`o @tab grave accent
9374 @item @t{@@~o} @tab @~o @tab tilde accent
9375 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
9376 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
9377 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
9378 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
9379 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent
9380 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
9381 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
9382 @item @t{@@v@{o@}} @tab @v{o} @tab hacek or check accent
9385 This table lists the Texinfo commands for inserting other characters
9386 commonly used in languages other than English.
9388 @findex questiondown
9389 @cindex @questiondown{}
9391 @cindex @exclamdown{}
9403 @cindex Dotless i, j
9421 @multitable {x@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
9422 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
9423 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
9424 @item @t{@@aa@{@},@@AA@{@}} @tab @aa{},@AA{} @tab a,A with circle
9425 @item @t{@@ae@{@},@@AE@{@}} @tab @ae{},@AE{} @tab ae,AE ligatures
9426 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
9427 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
9428 @item @t{@@l@{@},@@L@{@}} @tab @l{},@L{} @tab suppressed-L,l
9429 @item @t{@@o@{@},@@O@{@}} @tab @o{},@O{} @tab O,o with slash
9430 @item @t{@@oe@{@},@@OE@{@}} @tab @oe{},@OE{} @tab oe,OE ligatures
9431 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
9436 @section Inserting Ellipsis and Bullets
9437 @cindex Dots, inserting
9438 @cindex Bullets, inserting
9439 @cindex Ellipsis, inserting
9440 @cindex Inserting ellipsis
9441 @cindex Inserting dots
9442 @cindex Special typesetting commands
9443 @cindex Typesetting commands for dots, etc.
9445 An @dfn{ellipsis} (a line of dots) is not typeset as a string of
9446 periods, so a special command is used for ellipsis in Texinfo. The
9447 @code{@@bullet} command is special, too. Each of these commands is
9448 followed by a pair of braces, @samp{@{@}}, without any whitespace
9449 between the name of the command and the braces. (You need to use braces
9450 with these commands because you can use them next to other text; without
9451 the braces, the formatters would be confused. @xref{Command Syntax, ,
9452 @@-Command Syntax}, for further information.)@refill
9455 * dots:: How to insert dots @dots{}
9456 * bullet:: How to insert a bullet.
9461 @subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
9464 @cindex Inserting dots
9465 @cindex Dots, inserting
9467 Use the @code{@@dots@{@}} command to generate an ellipsis, which is
9468 three dots in a row, appropriately spaced, like this: `@dots{}'. Do
9469 not simply write three periods in the input file; that would work for
9470 the Info file output, but would produce the wrong amount of space
9471 between the periods in the printed manual.
9473 Similarly, the @code{@@enddots@{@}} command generates an
9474 end-of-sentence ellipsis (four dots) @enddots{}
9477 Here is an ellipsis: @dots{}
9478 Here are three periods in a row: ...
9480 In printed output, the three periods in a row are closer together than
9481 the dots in the ellipsis.
9486 @subsection @code{@@bullet}@{@} (@bullet{})
9489 Use the @code{@@bullet@{@}} command to generate a large round dot, or
9490 the closest possible thing to one. In Info, an asterisk is used.@refill
9492 Here is a bullet: @bullet{}
9494 When you use @code{@@bullet} in @code{@@itemize}, you do not need to
9495 type the braces, because @code{@@itemize} supplies them.
9496 (@xref{itemize, , @code{@@itemize}}.)@refill
9499 @node TeX and copyright, pounds, Dots Bullets, Insertions
9500 @section Inserting @TeX{} and the Copyright Symbol
9502 The logo `@TeX{}' is typeset in a special fashion and it needs an
9503 @@-command. The copyright symbol, `@copyright{}', is also special.
9504 Each of these commands is followed by a pair of braces, @samp{@{@}},
9505 without any whitespace between the name of the command and the
9509 * tex:: How to insert the @TeX{} logo.
9510 * copyright symbol:: How to use @code{@@copyright}@{@}.
9515 @subsection @code{@@TeX}@{@} (@TeX{})
9516 @findex tex (command)
9518 Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
9519 manual, this is a special logo that is different from three ordinary
9520 letters. In Info, it just looks like @samp{TeX}. The
9521 @code{@@TeX@{@}} command is unique among Texinfo commands in that the
9522 @samp{T} and the @samp{X} are in upper case.@refill
9525 @node copyright symbol
9526 @subsection @code{@@copyright}@{@} (@copyright{})
9529 Use the @code{@@copyright@{@}} command to generate `@copyright{}'. In
9530 a printed manual, this is a @samp{c} inside a circle, and in Info,
9531 this is @samp{(C)}.@refill
9534 @node pounds, minus, TeX and copyright, Insertions
9535 @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
9538 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. In a
9539 printed manual, this is the symbol for the currency pounds sterling.
9540 In Info, it is a @samp{#}. Other currency symbols are unfortunately not
9544 @node minus, math, pounds, Insertions
9545 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
9550 Use the @code{@@minus@{@}} command to generate a minus sign. In a
9551 fixed-width font, this is a single hyphen, but in a proportional font,
9552 the symbol is the customary length for a minus sign---a little longer
9553 than a hyphen, shorter than an em-dash:
9556 @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
9558 `-' is a hyphen generated with the character @samp{-},
9560 `---' is an em-dash for text.
9564 In the fixed-width font used by Info, @code{@@minus@{@}} is the same
9567 You should not use @code{@@minus@{@}} inside @code{@@code} or
9568 @code{@@example} because the width distinction is not made in the
9569 fixed-width font they use.
9571 When you use @code{@@minus} to specify the mark beginning each entry in
9572 an itemized list, you do not need to type the braces
9573 (@pxref{itemize, , @code{@@itemize}}.)
9577 @section @code{@@math}: Inserting Mathematical Expressions
9579 @cindex Mathematical expressions
9580 @cindex Formulas, mathematical
9582 You can write a short mathematical expression with the @code{@@math}
9583 command. Write the mathematical expression between braces, like this:
9586 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
9590 @noindent This produces the following in @TeX{}:
9593 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
9596 @noindent and the following in Info:
9599 @noindent This produces the following in Info:
9603 (a + b)(a + b) = a^2 + 2ab + b^2
9606 Thus, the @code{@@math} command has no effect on the Info output.
9608 @code{@@math} implies @code{@@tex}. This not only makes it possible to
9609 write superscripts and subscripts (as in the above example), but also
9610 allows you to use any of the plain @TeX{} math control sequences. It's
9611 conventional to use @samp{\} instead of @samp{@@} for these commands.
9614 @@math@{\sin 2\pi \equiv \cos 3\pi@}
9618 @noindent which looks like this in @TeX{}:
9620 @math{\sin 2\pi \equiv \cos 3\pi}
9625 @noindent which looks like the input in Info and HTML:
9627 \sin 2\pi \equiv \cos 3\pi
9630 @findex \ @r{(literal \ in @code{@@math})}
9631 Since @samp{\} is an escape character inside @code{@@math}, you can use
9632 @code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
9633 but you'll get the literal @samp{\\} in Info). @code{@@\} is not
9634 defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
9638 @cindex Displayed equations
9639 @cindex Equations, displayed
9640 For displayed equations, you must at present use @TeX{} directly
9641 (@pxref{Raw Formatter Commands}).
9645 @section Glyphs for Examples
9647 @cindex Examples, glyphs for
9649 In Texinfo, code is often illustrated in examples that are delimited
9650 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
9651 @code{@@end lisp}. In such examples, you can indicate the results of
9652 evaluation or an expansion using @samp{@result{}} or
9653 @samp{@expansion{}}. Likewise, there are commands to insert glyphs
9655 printed output, error messages, equivalence of expressions, and the
9656 location of point.@refill
9658 The glyph-insertion commands do not need to be used within an example, but
9659 most often they are. Every glyph-insertion command is followed by a pair of
9660 left- and right-hand braces.@refill
9664 * result:: How to show the result of expression.
9665 * expansion:: How to indicate an expansion.
9666 * Print Glyph:: How to indicate printed output.
9667 * Error Glyph:: How to indicate an error message.
9668 * Equivalence:: How to indicate equivalence.
9669 * Point Glyph:: How to indicate the location of point.
9673 @node Glyphs Summary
9674 @subsection Glyphs Summary
9676 Here are the different glyph commands:@refill
9680 @code{@@result@{@}} points to the result of an expression.@refill
9683 @code{@@expansion@{@}} shows the results of a macro expansion.@refill
9686 @code{@@print@{@}} indicates printed output.@refill
9689 @code{@@error@{@}} indicates that the following text is an error
9693 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
9696 @code{@@point@{@}} shows the location of point.@refill
9710 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
9711 @cindex Result of an expression
9712 @cindex Indicating evaluation
9713 @cindex Evaluation glyph
9714 @cindex Value of an expression, indicating
9717 Use the @code{@@result@{@}} command to indicate the result of
9718 evaluating an expression.@refill
9721 The @code{@@result@{@}} command is displayed as @samp{=>} in Info and
9722 as @samp{@result{}} in the printed output.
9725 The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
9726 and as a double stemmed arrow in the printed output.@refill
9729 Thus, the following,
9737 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
9740 @node expansion, Print Glyph, result, Glyphs
9741 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
9742 @cindex Expansion, indicating it
9745 When an expression is a macro call, it expands into a new expression.
9746 You can indicate the result of the expansion with the
9747 @code{@@expansion@{@}} command.@refill
9750 The @code{@@expansion@{@}} command is displayed as @samp{==>} in Info and
9751 as @samp{@expansion{}} in the printed output.
9754 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
9755 in Info and as a long arrow with a flat base in the printed output.@refill
9759 For example, the following
9765 @@expansion@{@} (car (cdr (cdr '(a b c))))
9777 @expansion{} (car (cdr (cdr '(a b c))))
9783 which may be read as:
9786 @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
9787 the result of evaluating the expression is @code{c}.
9791 Often, as in this case, an example looks better if the
9792 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
9796 @node Print Glyph, Error Glyph, expansion, Glyphs
9797 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
9798 @cindex Printed output, indicating it
9801 Sometimes an expression will print output during its execution. You
9802 can indicate the printed output with the @code{@@print@{@}} command.@refill
9805 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
9806 as @samp{@print{}} in the printed output.
9809 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
9810 and similarly, as a horizontal dash butting against a vertical bar, in
9811 the printed output.@refill
9814 In the following example, the printed text is indicated with
9815 @samp{@print{}}, and the value of the expression follows on the
9820 (progn (print 'foo) (print 'bar))
9828 In a Texinfo source file, this example is written as follows:
9833 (progn (print 'foo) (print 'bar))
9842 @node Error Glyph, Equivalence, Print Glyph, Glyphs
9843 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
9844 @cindex Error message, indicating it
9847 A piece of code may cause an error when you evaluate it. You can
9848 designate the error message with the @code{@@error@{@}} command.@refill
9851 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
9852 and as @samp{@error{}} in the printed output.
9855 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
9856 and as the word `error' in a box in the printed output.@refill
9865 @@error@{@} Wrong type argument: integer-or-marker-p, x
9874 @error{} Wrong type argument: integer-or-marker-p, x
9878 This indicates that the following error message is printed
9879 when you evaluate the expression:
9882 Wrong type argument: integer-or-marker-p, x
9885 @samp{@error{}} itself is not part of the error message.
9888 @node Equivalence, Point Glyph, Error Glyph, Glyphs
9889 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
9890 @cindex Equivalence, indicating it
9893 Sometimes two expressions produce identical results. You can indicate the
9894 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
9897 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
9898 as @samp{@equiv{}} in the printed output.
9901 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
9902 and as a three parallel horizontal lines in the printed output.@refill
9909 (make-sparse-keymap) @@equiv@{@} (list 'keymap)
9917 (make-sparse-keymap) @equiv{} (list 'keymap)
9921 This indicates that evaluating @code{(make-sparse-keymap)} produces
9922 identical results to evaluating @code{(list 'keymap)}.
9926 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
9927 @cindex Point, indicating in a buffer
9930 Sometimes you need to show an example of text in an Emacs buffer. In
9931 such examples, the convention is to include the entire contents of the
9932 buffer in question between two lines of dashes containing the buffer
9935 You can use the @samp{@@point@{@}} command to show the location of point
9936 in the text in the buffer. (The symbol for point, of course, is not
9937 part of the text in the buffer; it indicates the place @emph{between}
9938 two characters where point is located.)@refill
9941 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
9942 as @samp{@point{}} in the printed output.
9945 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
9946 and as a small five pointed star in the printed output.@refill
9949 The following example shows the contents of buffer @file{foo} before
9950 and after evaluating a Lisp command to insert the word @code{changed}.@refill
9954 ---------- Buffer: foo ----------
9955 This is the @point{}contents of foo.
9956 ---------- Buffer: foo ----------
9965 ---------- Buffer: foo ----------
9966 This is the changed @point{}contents of foo.
9967 ---------- Buffer: foo ----------
9972 In a Texinfo source file, the example is written like this:@refill
9976 ---------- Buffer: foo ----------
9977 This is the @@point@{@}contents of foo.
9978 ---------- Buffer: foo ----------
9982 ---------- Buffer: foo ----------
9983 This is the changed @@point@{@}contents of foo.
9984 ---------- Buffer: foo ----------
9994 A @dfn{footnote} is for a reference that documents or elucidates the
9995 primary text.@footnote{A footnote should complement or expand upon
9996 the primary text, but a reader should not need to read a footnote to
9997 understand the primary text. For a thorough discussion of footnotes,
9998 see @cite{The Chicago Manual of Style}, which is published by the
9999 University of Chicago Press.}
10002 * Footnote Commands:: How to write a footnote in Texinfo.
10003 * Footnote Styles:: Controlling how footnotes appear in Info.
10007 @node Footnote Commands
10008 @subsection Footnote Commands
10010 In Texinfo, footnotes are created with the @code{@@footnote} command.
10011 This command is followed immediately by a left brace, then by the text
10012 of the footnote, and then by a terminating right brace. Footnotes may
10013 be of any length (they will be broken across pages if necessary), but
10014 are usually short. The template is:
10017 ordinary text@@footnote@{@var{text of footnote}@}
10020 As shown here, the @code{@@footnote} command should come right after the
10021 text being footnoted, with no intervening space; otherwise, the footnote
10022 marker might end up starting a line.
10024 For example, this clause is followed by a sample footnote@footnote{Here
10025 is the sample footnote.}; in the Texinfo source, it looks like
10029 @dots{}a sample footnote@@footnote@{Here is the sample
10030 footnote.@}; in the Texinfo source@dots{}
10033 As you can see, the source includes two punctuation marks next to each
10034 other; in this case, @samp{.@};} is the sequence. This is normal (the
10035 first ends the footnote and the second belongs to the sentence being
10036 footnoted), so don't worry that it looks odd.
10038 In a printed manual or book, the reference mark for a footnote is a
10039 small, superscripted number; the text of the footnote appears at the
10040 bottom of the page, below a horizontal line.
10042 In Info, the reference mark for a footnote is a pair of parentheses
10043 with the footnote number between them, like this: @samp{(1)}. The
10044 reference mark is followed by a cross-reference link to the footnote's
10047 In the HTML output, footnote references are marked with a small,
10048 superscripted number which is rendered as a hypertext link to the
10051 By the way, footnotes in the argument of an @code{@@item} command for a
10052 @code{@@table} must be on the same line as the @code{@@item}
10053 (as usual). @xref{Two-column Tables}.
10056 @node Footnote Styles
10057 @subsection Footnote Styles
10059 Info has two footnote styles, which determine where the text of the
10060 footnote is located:@refill
10063 @cindex @samp{@r{End}} node footnote style
10065 In the `End' node style, all the footnotes for a single node
10066 are placed at the end of that node. The footnotes are separated from
10067 the rest of the node by a line of dashes with the word
10068 @samp{Footnotes} within it. Each footnote begins with an
10069 @samp{(@var{n})} reference mark.@refill
10073 Here is an example of a single footnote in the end of node style:@refill
10077 --------- Footnotes ---------
10079 (1) Here is a sample footnote.
10083 @cindex @samp{@r{Separate}} footnote style
10085 In the `Separate' node style, all the footnotes for a single
10086 node are placed in an automatically constructed node of
10087 their own. In this style, a ``footnote reference'' follows
10088 each @samp{(@var{n})} reference mark in the body of the
10089 node. The footnote reference is actually a cross reference
10090 which you use to reach the footnote node.@refill
10092 The name of the node with the footnotes is constructed
10093 by appending @w{@samp{-Footnotes}} to the name of the node
10094 that contains the footnotes. (Consequently, the footnotes'
10095 node for the @file{Footnotes} node is
10096 @w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
10097 `Up' node pointer that leads back to its parent node.@refill
10100 Here is how the first footnote in this manual looks after being
10101 formatted for Info in the separate node style:@refill
10105 File: texinfo.info Node: Overview-Footnotes, Up: Overview
10107 (1) The first syllable of "Texinfo" is pronounced like "speck", not
10113 A Texinfo file may be formatted into an Info file with either footnote
10116 @findex footnotestyle
10117 Use the @code{@@footnotestyle} command to specify an Info file's
10118 footnote style. Write this command at the beginning of a line followed
10119 by an argument, either @samp{end} for the end node style or
10120 @samp{separate} for the separate node style.
10126 @@footnotestyle end
10131 @@footnotestyle separate
10134 Write an @code{@@footnotestyle} command before or shortly after the
10135 end-of-header line at the beginning of a Texinfo file. (If you
10136 include the @code{@@footnotestyle} command between the start-of-header
10137 and end-of-header lines, the region formatting commands will format
10138 footnotes as specified.)@refill
10140 If you do not specify a footnote style, the formatting commands use
10141 their default style. Currently, @code{texinfo-format-buffer} and
10142 @code{texinfo-format-region} use the `separate' style and
10143 @code{makeinfo} uses the `end' style.@refill
10145 @c !!! note: makeinfo's --footnote-style option overrides footnotestyle
10147 If you use @code{makeinfo} to create the Info file, the
10148 @samp{--footnote-style} option determines which style is used,
10149 @samp{end} for the end of node style or @samp{separate} for the
10150 separate node style. Thus, to format the Texinfo manual in the
10151 separate node style, you would use the following shell command:@refill
10154 makeinfo --footnote-style=separate texinfo.texi
10158 To format the Texinfo manual in the end of node style, you would
10162 makeinfo --footnote-style=end texinfo.texi
10166 If you use @code{texinfo-format-buffer} or
10167 @code{texinfo-format-region} to create the Info file, the value of the
10168 @code{texinfo-footnote-style} variable controls the footnote style.
10169 It can be either @samp{"separate"} for the separate node style or
10170 @samp{"end"} for the end of node style. (You can change the value of
10171 this variable with the @kbd{M-x edit-options} command (@pxref{Edit
10172 Options, , Editing Variable Values, emacs, The GNU Emacs Manual}), or
10173 with the @kbd{M-x set-variable} command (@pxref{Examining, , Examining
10174 and Setting Variables, emacs, The GNU Emacs Manual}).@refill
10176 The @code{texinfo-footnote-style} variable also controls the style if
10177 you use the @kbd{M-x makeinfo-region} or @kbd{M-x makeinfo-buffer}
10178 command in Emacs.@refill
10181 This chapter contains two footnotes.@refill
10185 @c this should be described with figures when we have them
10186 @c perhaps in the quotation/example chapter.
10188 @section Inserting Images
10190 @cindex Images, inserting
10191 @cindex Pictures, inserting
10194 You can insert an image given in an external file with the
10195 @code{@@image} command:
10198 @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@}
10201 @cindex Formats for images
10202 @cindex Image formats
10203 The @var{filename} argument is mandatory, and must not have an
10204 extension, because the different processors support different formats:
10207 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
10210 @pindex pdftex@r{, and images}
10211 PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
10213 @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
10214 Info output (more or less as if it was an @code{@@example}).
10217 uses the optional fifth argument to @code{@@image} for the extension if
10218 you supply it. For example:
10220 @pindex XPM image format
10222 @@image@{foo,,,,xpm@}
10226 will cause @samp{makeinfo --html} to try @file{foo.xpm}.
10228 @cindex GIF, unsupported due to patents
10229 @cindex PNG image format
10230 @cindex JPG image format
10231 If you do not supply the optional fifth argument, @samp{makeinfo
10232 ---html} first tries @file{@var{filename}.png}; if that does not exist,
10233 it tries @file{@var{filename}.jpg}. If that does not exist either, it
10234 complains. (We cannot support GIF format directly due to software
10238 @cindex Width of images
10239 @cindex Height of images
10240 @cindex Aspect ratio of images
10241 @cindex Distorting images
10242 The optional @var{width} and @var{height} arguments specify the size to
10243 scale the image to (they are ignored for Info output). If neither is
10244 specified, the image is presented in its natural size (given in the
10245 file); if only one is specified, the other is scaled proportionately;
10246 and if both are specified, both are respected, thus possibly distorting
10247 the original image by changing its aspect ratio.
10249 @cindex Dimensions and image sizes
10250 The @var{width} and @var{height} may be specified using any valid @TeX{}
10255 @cindex Points (dimension)
10256 point (72.27pt = 1in)
10262 big point (72bp = 1in)
10267 @cindex Centimeters
10268 centimeter (2.54cm = 1in)
10270 @cindex Millimeters
10271 millimeter (10mm = 1cm)
10273 @cindex Did@^ot points
10274 did@^ot point (1157dd = 1238pt)
10277 cicero (1cc = 12dd)
10279 @cindex Scaled points
10280 scaled point (65536sp = 1pt)
10284 For example, the following will scale a file @file{ridt.eps} to one
10285 inch vertically, with the width scaled proportionately:
10288 @@image@{ridt,,1in@}
10292 For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
10293 installed somewhere that @TeX{} can find it. (The standard location is
10294 @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
10295 root of your @TeX{} directory tree.) This file is included in the
10296 Texinfo distribution and is also available from
10297 @uref{ftp://tug.org/tex/epsf.tex}, among other places.
10299 @code{@@image} can be used within a line as well as for displayed
10300 figures. Therefore, if you intend it to be displayed, be sure to leave
10301 a blank line before the command, or the output will run into the
10304 @cindex alt attribute for images
10305 @cindex alternate text for images
10306 When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
10307 inline images to the optional fourth argument to @code{@@image}, if
10308 supplied. If not supplied, @code{makeinfo} uses the full file name of
10309 the image being displayed.
10313 @chapter Making and Preventing Breaks
10314 @cindex Making line and page breaks
10315 @cindex Preventing line and page breaks
10317 @cindex Line breaks
10318 Usually, a Texinfo file is processed both by @TeX{} and by one of the
10319 Info formatting commands. Line, paragraph, or page breaks sometimes
10320 occur in the `wrong' place in one or other form of output. You must
10321 ensure that text looks right both in the printed manual and in the
10324 @cindex White space, excessive
10325 @cindex Page breaks
10326 For example, in a printed manual, page breaks may occur awkwardly in
10327 the middle of an example; to prevent this, you can hold text together
10328 using a grouping command that keeps the text from being split across
10329 two pages. Conversely, you may want to force a page break where none
10330 would occur normally. Fortunately, problems like these do not often
10331 arise. When they do, use the break, break prevention, or pagination
10335 * Break Commands:: Cause and prevent splits.
10336 * Line Breaks:: How to force a single line to use two lines.
10337 * - and hyphenation:: How to tell @TeX{} about hyphenation points.
10338 * w:: How to prevent unwanted line breaks.
10339 * sp:: How to insert blank lines.
10340 * page:: How to force the start of a new page.
10341 * group:: How to prevent unwanted page breaks.
10342 * need:: Another way to prevent unwanted page breaks.
10346 @node Break Commands, Line Breaks, Breaks, Breaks
10348 @heading Break Commands
10351 The break commands create or allow line and paragraph breaks:@refill
10355 Force a line break.
10358 Skip @var{n} blank lines.@refill
10361 Insert a discretionary hyphen.
10363 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
10364 Define hyphen points in @var{hy-phen-a-ted words}.
10367 The line-break-prevention command holds text together all on one
10371 @item @@w@{@var{text}@}
10372 Prevent @var{text} from being split and hyphenated across two lines.@refill
10378 The pagination commands apply only to printed output, since Info
10379 files do not have pages.@refill
10383 Start a new page in the printed manual.@refill
10386 Hold text together that must appear on one printed page.@refill
10388 @item @@need @var{mils}
10389 Start a new printed page if not enough space on this one.@refill
10393 @section @code{@@*}: Generate Line Breaks
10394 @findex * @r{(force line break)}
10395 @cindex Line breaks
10396 @cindex Breaks in a line
10398 The @code{@@*} command forces a line break in both the printed manual and
10405 This line @@* is broken @@*in two places.
10420 (Note that the space after the first @code{@@*} command is faithfully
10421 carried down to the next line.)@refill
10424 The @code{@@*} command is often used in a file's copyright page:@refill
10428 This is edition 2.0 of the Texinfo documentation,@@*
10434 In this case, the @code{@@*} command keeps @TeX{} from stretching the
10435 line across the whole page in an ugly manner.@refill
10438 @strong{Please note:} Do not write braces after an @code{@@*} command;
10439 they are not needed.@refill
10441 Do not write an @code{@@refill} command at the end of a paragraph
10442 containing an @code{@@*} command; it will cause the paragraph to be
10443 refilled after the line break occurs, negating the effect of the line
10448 @node - and hyphenation
10449 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
10451 @findex - @r{(discretionary hyphen)}
10452 @findex hyphenation
10453 @cindex Hyphenation, helping @TeX{} do
10454 @cindex Fine-tuning, and hyphenation
10456 Although @TeX{}'s hyphenation algorithm is generally pretty good, it
10457 does miss useful hyphenation points from time to time. (Or, far more
10458 rarely, insert an incorrect hyphenation.) So, for documents with an
10459 unusual vocabulary or when fine-tuning for a printed edition, you may
10460 wish to help @TeX{} out. Texinfo supports two commands for this:
10464 Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
10465 not have to) hyphenate. This is especially useful when you notice an
10466 overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
10467 hboxes}). @TeX{} will not insert any hyphenation points itself into a
10468 word containing @code{@@-}.
10470 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
10471 Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
10472 put a @samp{-} at each hyphenation point. For example:
10474 @@hyphenation@{man-u-script man-u-scripts@}
10476 @noindent @TeX{} only uses the specified hyphenation points when the
10477 words match exactly, so give all necessary variants.
10480 Info output is not hyphenated, so these commands have no effect there.
10483 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
10484 @findex w @r{(prevent line break)}
10485 @cindex Line breaks, preventing
10486 @cindex Hyphenation, preventing
10488 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
10489 within @var{text}.@refill
10491 You can use the @code{@@w} command to prevent @TeX{} from automatically
10492 hyphenating a long name or phrase that happens to fall near the end of a
10496 You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}.
10503 You can copy GNU software from @w{@samp{ftp.gnu.org}}.
10506 @cindex Non-breakable space
10507 @cindex Unbreakable space
10509 You can also use @code{@@w} to produce a non-breakable space:
10512 None of the formatters will break at this@@w@{ @}space.
10517 @section @code{@@sp} @var{n}: Insert Blank Lines
10518 @findex sp @r{(line spacing)}
10519 @cindex Space, inserting vertical
10520 @cindex Blank lines
10521 @cindex Line spacing
10523 A line beginning with and containing only @code{@@sp @var{n}}
10524 generates @var{n} blank lines of space in both the printed manual and
10525 the Info file. @code{@@sp} also forces a paragraph break. For
10533 generates two blank lines.
10535 The @code{@@sp} command is most often used in the title page.@refill
10538 @c node br, page, sp, Breaks
10539 @comment node-name, next, previous, up
10540 @c section @code{@@br}: Generate Paragraph Breaks
10541 @findex br @r{(paragraph breaks)}
10542 @cindex Paragraph breaks
10543 @cindex Breaks in a paragraph
10545 The @code{@@br} command forces a paragraph break. It inserts a blank
10546 line. You can use the command within or at the end of a line. If
10547 used within a line, the @code{@@br@{@}} command must be followed by
10548 left and right braces (as shown here) to mark the end of the
10556 This line @@br@{@}contains and is ended by paragraph breaks@@br
10557 and is followed by another line.
10568 contains and is ended by paragraph breaks
10570 and is followed by another line.
10574 The @code{@@br} command is seldom used.
10579 @section @code{@@page}: Start a New Page
10580 @cindex Page breaks
10583 A line containing only @code{@@page} starts a new page in a printed
10584 manual. The command has no effect on Info files since they are not
10585 paginated. An @code{@@page} command is often used in the @code{@@titlepage}
10586 section of a Texinfo file to start the copyright page.
10589 @node group, need, page, Breaks
10590 @comment node-name, next, previous, up
10591 @section @code{@@group}: Prevent Page Breaks
10592 @cindex Group (hold text together vertically)
10593 @cindex Holding text together vertically
10594 @cindex Vertically holding text together
10597 The @code{@@group} command (on a line by itself) is used inside an
10598 @code{@@example} or similar construct to begin an unsplittable vertical
10599 group, which will appear entirely on one page in the printed output.
10600 The group is terminated by a line containing only @code{@@end group}.
10601 These two lines produce no output of their own, and in the Info file
10602 output they have no effect at all.@refill
10604 @c Once said that these environments
10605 @c turn off vertical spacing between ``paragraphs''.
10606 @c Also, quotation used to work, but doesn't in texinfo-2.72
10607 Although @code{@@group} would make sense conceptually in a wide
10608 variety of contexts, its current implementation works reliably only
10609 within @code{@@example} and variants, and within @code{@@display},
10610 @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
10611 @xref{Quotations and Examples}. (What all these commands have in
10612 common is that each line of input produces a line of output.) In
10613 other contexts, @code{@@group} can cause anomalous vertical
10617 This formatting requirement means that you should write:
10630 with the @code{@@group} and @code{@@end group} commands inside the
10631 @code{@@example} and @code{@@end example} commands.
10633 The @code{@@group} command is most often used to hold an example
10634 together on one page. In this Texinfo manual, more than 100 examples
10635 contain text that is enclosed between @code{@@group} and @code{@@end
10638 If you forget to end a group, you may get strange and unfathomable
10639 error messages when you run @TeX{}. This is because @TeX{} keeps
10640 trying to put the rest of the Texinfo file onto the one page and does
10641 not start to generate error messages until it has processed
10642 considerable text. It is a good rule of thumb to look for a missing
10643 @code{@@end group} if you get incomprehensible error messages in
10646 @node need, , group, Breaks
10647 @comment node-name, next, previous, up
10648 @section @code{@@need @var{mils}}: Prevent Page Breaks
10649 @cindex Need space at page bottom
10652 A line containing only @code{@@need @var{n}} starts
10653 a new page in a printed manual if fewer than @var{n} mils (thousandths
10654 of an inch) remain on the current page. Do not use
10655 braces around the argument @var{n}. The @code{@@need} command has no
10656 effect on Info files since they are not paginated.@refill
10659 This paragraph is preceded by an @code{@@need} command that tells
10660 @TeX{} to start a new page if fewer than 800 mils (eight-tenths
10661 inch) remain on the page. It looks like this:@refill
10666 This paragraph is preceded by @dots{}
10670 The @code{@@need} command is useful for preventing orphans (single
10671 lines at the bottoms of printed pages).@refill
10674 @node Definition Commands
10675 @chapter Definition Commands
10676 @cindex Definition commands
10678 The @code{@@deffn} command and the other @dfn{definition commands}
10679 enable you to describe functions, variables, macros, commands, user
10680 options, special forms and other such artifacts in a uniform
10683 In the Info file, a definition causes the entity
10684 category---`Function', `Variable', or whatever---to appear at the
10685 beginning of the first line of the definition, followed by the
10686 entity's name and arguments. In the printed manual, the command
10687 causes @TeX{} to print the entity's name and its arguments on the left
10688 margin and print the category next to the right margin. In both
10689 output formats, the body of the definition is indented. Also, the
10690 name of the entity is entered into the appropriate index:
10691 @code{@@deffn} enters the name into the index of functions,
10692 @code{@@defvr} enters it into the index of variables, and so
10695 A manual need not and should not contain more than one definition for
10696 a given name. An appendix containing a summary should use
10697 @code{@@table} rather than the definition commands.@refill
10700 * Def Cmd Template:: How to structure a description using a
10701 definition command.
10702 * Optional Arguments:: How to handle optional and repeated arguments.
10703 * deffnx:: How to group two or more `first' lines.
10704 * Def Cmds in Detail:: All the definition commands.
10705 * Def Cmd Conventions:: Conventions for writing definitions.
10706 * Sample Function Definition::
10709 @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
10710 @section The Template for a Definition
10711 @cindex Definition template
10712 @cindex Template for a definition
10714 The @code{@@deffn} command is used for definitions of entities that
10715 resemble functions. To write a definition using the @code{@@deffn}
10716 command, write the @code{@@deffn} command at the beginning of a line
10717 and follow it on the same line by the category of the entity, the name
10718 of the entity itself, and its arguments (if any). Then write the body
10719 of the definition on succeeding lines. (You may embed examples in the
10720 body.) Finally, end the definition with an @code{@@end deffn} command
10721 written on a line of its own. (The other definition commands follow
10722 the same format.)@refill
10724 The template for a definition looks like this:
10728 @@deffn @var{category} @var{name} @var{arguments}@dots{}
10729 @var{body-of-definition}
10740 @@deffn Command forward-word count
10741 This command moves point forward @@var@{count@} words
10742 (or backward if @@var@{count@} is negative). @dots{}
10751 @deffn Command forward-word count
10752 This function moves point forward @var{count} words
10753 (or backward if @var{count} is negative). @dots{}
10757 Capitalize the category name like a title. If the name of the
10758 category contains spaces, as in the phrase `Interactive Command',
10759 write braces around it. For example:@refill
10763 @@deffn @{Interactive Command@} isearch-forward
10770 Otherwise, the second word will be mistaken for the name of the
10773 Some of the definition commands are more general than others. The
10774 @code{@@deffn} command, for example, is the general definition command
10775 for functions and the like---for entities that may take arguments. When
10776 you use this command, you specify the category to which the entity
10777 belongs. The @code{@@deffn} command possesses three predefined,
10778 specialized variations, @code{@@defun}, @code{@@defmac}, and
10779 @code{@@defspec}, that specify the category for you: ``Function'',
10780 ``Macro'', and ``Special Form'' respectively. (In Lisp, a special form
10781 is an entity much like a function.) The @code{@@defvr} command also is
10782 accompanied by several predefined, specialized variations for describing
10783 particular kinds of variables.@refill
10785 The template for a specialized definition, such as @code{@@defun}, is
10786 similar to the template for a generalized definition, except that you
10787 do not need to specify the category:@refill
10791 @@defun @var{name} @var{arguments}@dots{}
10792 @var{body-of-definition}
10802 @@defun buffer-end flag
10803 This function returns @@code@{(point-min)@} if @@var@{flag@}
10804 is less than 1, @@code@{(point-max)@} otherwise.
10814 @defun buffer-end flag
10815 This function returns @code{(point-min)} if @var{flag} is less than 1,
10816 @code{(point-max)} otherwise. @dots{}
10821 @xref{Sample Function Definition, Sample Function Definition, A Sample
10822 Function Definition}, for a more detailed example of a function
10823 definition, including the use of @code{@@example} inside the
10826 The other specialized commands work like @code{@@defun}.@refill
10828 @cindex Macros in definition commands
10829 Note that, due to implementation difficulties, macros are not expanded
10830 in @code{@@deffn} and all the other definition commands.
10832 @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
10833 @section Optional and Repeated Arguments
10834 @cindex Optional and repeated arguments
10835 @cindex Repeated and optional arguments
10836 @cindex Arguments, repeated and optional
10837 @cindex Syntax, optional & repeated arguments
10838 @cindex Meta-syntactic chars for arguments
10840 Some entities take optional or repeated arguments, which may be
10841 specified by a distinctive glyph that uses square brackets and
10842 ellipses. For @w{example}, a special form often breaks its argument list
10843 into separate arguments in more complicated ways than a
10844 straightforward function.@refill
10847 An argument enclosed within square brackets is optional.
10849 @samp{@code{@r{[}@var{optional-arg}@r{]}}} means that
10850 @var{optional-arg} is optional.
10851 An argument followed by an ellipsis is optional
10852 and may be repeated more than once.
10853 @c This is consistent with Emacs Lisp Reference manual
10854 Thus, @samp{@var{repeated-args}@dots{}} stands for zero or more arguments.
10855 Parentheses are used when several arguments are grouped
10856 into additional levels of list structure in Lisp.
10858 @c The following looks better in Info (no `r', `samp' and `code'):
10860 An argument enclosed within square brackets is optional.
10861 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
10862 An argument followed by an ellipsis is optional
10863 and may be repeated more than once.
10864 @c This is consistent with Emacs Lisp Reference manual
10865 Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
10866 Parentheses are used when several arguments are grouped
10867 into additional levels of list structure in Lisp.
10870 Here is the @code{@@defspec} line of an example of an imaginary
10871 special form:@refill
10874 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
10882 In this example, the arguments @var{from} and @var{to} are optional,
10883 but must both be present or both absent. If they are present,
10884 @var{inc} may optionally be specified as well. These arguments are
10885 grouped with the argument @var{var} into a list, to distinguish them
10886 from @var{body}, which includes all remaining elements of the
10889 In a Texinfo source file, this @code{@@defspec} line is written like
10890 this (except it would not be split over two lines, as it is in this
10895 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
10896 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
10901 The function is listed in the Command and Variable Index under
10902 @samp{foobar}.@refill
10904 @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
10905 @section Two or More `First' Lines
10906 @cindex Two `First' Lines for @code{@@deffn}
10907 @cindex Grouping two definitions together
10908 @cindex Definitions grouped together
10911 To create two or more `first' or header lines for a definition, follow
10912 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
10913 The @code{@@deffnx} command works exactly like @code{@@deffn}
10914 except that it does not generate extra vertical white space between it
10915 and the preceding line.@refill
10922 @@deffn @{Interactive Command@} isearch-forward
10923 @@deffnx @{Interactive Command@} isearch-backward
10924 These two search commands are similar except @dots{}
10932 @deffn {Interactive Command} isearch-forward
10933 @deffnx {Interactive Command} isearch-backward
10934 These two search commands are similar except @dots{}
10937 Each definition command has an `x' form: @code{@@defunx},
10938 @code{@@defvrx}, @code{@@deftypefunx}, etc.
10940 The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
10942 @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
10943 @section The Definition Commands
10945 Texinfo provides more than a dozen definition commands, all of which
10946 are described in this section.@refill
10948 The definition commands automatically enter the name of the entity in
10949 the appropriate index: for example, @code{@@deffn}, @code{@@defun},
10950 and @code{@@defmac} enter function names in the index of functions;
10951 @code{@@defvr} and @code{@@defvar} enter variable names in the index
10952 of variables.@refill
10954 Although the examples that follow mostly illustrate Lisp, the commands
10955 can be used for other programming languages.@refill
10958 * Functions Commands:: Commands for functions and similar entities.
10959 * Variables Commands:: Commands for variables and similar entities.
10960 * Typed Functions:: Commands for functions in typed languages.
10961 * Typed Variables:: Commands for variables in typed languages.
10962 * Abstract Objects:: Commands for object-oriented programming.
10963 * Data Types:: The definition command for data types.
10966 @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
10967 @subsection Functions and Similar Entities
10969 This section describes the commands for describing functions and similar
10974 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
10975 The @code{@@deffn} command is the general definition command for
10976 functions, interactive commands, and similar entities that may take
10977 arguments. You must choose a term to describe the category of entity
10978 being defined; for example, ``Function'' could be used if the entity is
10979 a function. The @code{@@deffn} command is written at the beginning of a
10980 line and is followed on the same line by the category of entity being
10981 described, the name of this particular entity, and its arguments, if
10982 any. Terminate the definition with @code{@@end deffn} on a line of its
10986 For example, here is a definition:
10990 @@deffn Command forward-char nchars
10991 Move point forward @@var@{nchars@} characters.
10997 This shows a rather terse definition for a ``command'' named
10998 @code{forward-char} with one argument, @var{nchars}.
11000 @code{@@deffn} prints argument names such as @var{nchars} in italics or
11001 upper case, as if @code{@@var} had been used, because we think of these
11002 names as metasyntactic variables---they stand for the actual argument
11003 values. Within the text of the description, write an argument name
11004 explicitly with @code{@@var} to refer to the value of the argument. In
11005 the example above, we used @samp{@@var@{nchars@}} in this way.
11007 The template for @code{@@deffn} is:
11011 @@deffn @var{category} @var{name} @var{arguments}@dots{}
11012 @var{body-of-definition}
11018 @item @@defun @var{name} @var{arguments}@dots{}
11019 The @code{@@defun} command is the definition command for functions.
11020 @code{@@defun} is equivalent to @samp{@@deffn Function
11029 @@defun set symbol new-value
11030 Change the value of the symbol @@var@{symbol@}
11031 to @@var@{new-value@}.
11037 shows a rather terse definition for a function @code{set} whose
11038 arguments are @var{symbol} and @var{new-value}. The argument names on
11039 the @code{@@defun} line automatically appear in italics or upper case as
11040 if they were enclosed in @code{@@var}. Terminate the definition with
11041 @code{@@end defun} on a line of its own.@refill
11047 @@defun @var{function-name} @var{arguments}@dots{}
11048 @var{body-of-definition}
11053 @code{@@defun} creates an entry in the index of functions.
11056 @item @@defmac @var{name} @var{arguments}@dots{}
11057 The @code{@@defmac} command is the definition command for macros.
11058 @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
11059 works like @code{@@defun}.@refill
11062 @item @@defspec @var{name} @var{arguments}@dots{}
11063 The @code{@@defspec} command is the definition command for special
11064 forms. (In Lisp, a special form is an entity much like a function,
11065 @pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
11066 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
11067 @dots{}} and works like @code{@@defun}.@refill
11070 @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
11071 @subsection Variables and Similar Entities
11073 Here are the commands for defining variables and similar
11078 @item @@defvr @var{category} @var{name}
11079 The @code{@@defvr} command is a general definition command for
11080 something like a variable---an entity that records a value. You must
11081 choose a term to describe the category of entity being defined; for
11082 example, ``Variable'' could be used if the entity is a variable.
11083 Write the @code{@@defvr} command at the beginning of a line and
11084 follow it on the same line by the category of the entity and the
11085 name of the entity.
11087 Capitalize the category name like a title. If the name of the category
11088 contains spaces, as in the name ``User Option'', enclose it in braces.
11089 Otherwise, the second word will be mistaken for the name of the entity.
11094 @@defvr @{User Option@} fill-column
11095 This buffer-local variable specifies
11096 the maximum width of filled lines.
11102 Terminate the definition with @code{@@end defvr} on a line of its
11109 @@defvr @var{category} @var{name}
11110 @var{body-of-definition}
11115 @code{@@defvr} creates an entry in the index of variables for @var{name}.
11118 @item @@defvar @var{name}
11119 The @code{@@defvar} command is the definition command for variables.
11120 @code{@@defvar} is equivalent to @samp{@@defvr Variable
11138 @@defvar @var{name}
11139 @var{body-of-definition}
11144 @code{@@defvar} creates an entry in the index of variables for
11148 @item @@defopt @var{name}
11149 @cindex User options, marking
11150 The @code{@@defopt} command is the definition command for @dfn{user
11151 options}, i.e., variables intended for users to change according to
11152 taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
11153 Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
11154 Option@} @dots{}} and works like @code{@@defvar}.@refill
11158 @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
11159 @subsection Functions in Typed Languages
11161 The @code{@@deftypefn} command and its variations are for describing
11162 functions in languages in which you must declare types of variables and
11163 functions, such as C and C++.
11167 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
11168 The @code{@@deftypefn} command is the general definition command for
11169 functions and similar entities that may take arguments and that are
11170 typed. The @code{@@deftypefn} command is written at the beginning of
11171 a line and is followed on the same line by the category of entity
11172 being described, the type of the returned value, the name of this
11173 particular entity, and its arguments, if any.@refill
11181 @@deftypefn @{Library Function@} int foobar
11182 (int @@var@{foo@}, float @@var@{bar@})
11190 (where the text before the ``@dots{}'', shown above as two lines, would
11191 actually be a single line in a real Texinfo file) produces the following
11196 -- Library Function: int foobar (int FOO, float BAR)
11202 In a printed manual, it produces:
11205 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
11211 This means that @code{foobar} is a ``library function'' that returns an
11212 @code{int}, and its arguments are @var{foo} (an @code{int}) and
11213 @var{bar} (a @code{float}).@refill
11215 The argument names that you write in @code{@@deftypefn} are not subject
11216 to an implicit @code{@@var}---since the actual names of the arguments in
11217 @code{@@deftypefn} are typically scattered among data type names and
11218 keywords, Texinfo cannot find them without help. Instead, you must write
11219 @code{@@var} explicitly around the argument names. In the example
11220 above, the argument names are @samp{foo} and @samp{bar}.@refill
11222 The template for @code{@@deftypefn} is:@refill
11226 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
11227 @var{body-of-description}
11233 Note that if the @var{category} or @var{data type} is more than one
11234 word then it must be enclosed in braces to make it a single argument.@refill
11236 If you are describing a procedure in a language that has packages,
11237 such as Ada, you might consider using @code{@@deftypefn} in a manner
11238 somewhat contrary to the convention described in the preceding
11247 @@deftypefn stacks private push
11248 (@@var@{s@}:in out stack;
11249 @@var@{n@}:in integer)
11256 (The @code{@@deftypefn} arguments are shown split into three lines, but
11257 would be a single line in a real Texinfo file.)
11259 In this instance, the procedure is classified as belonging to the
11260 package @code{stacks} rather than classified as a `procedure' and its
11261 data type is described as @code{private}. (The name of the procedure
11262 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
11264 @code{@@deftypefn} creates an entry in the index of functions for
11267 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
11269 The @code{@@deftypefun} command is the specialized definition command
11270 for functions in typed languages. The command is equivalent to
11271 @samp{@@deftypefn Function @dots{}}.@refill
11279 @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
11286 produces the following in Info:
11290 -- Function: int foobar (int FOO, float BAR)
11298 and the following in a printed manual:
11301 @deftypefun int foobar (int @var{foo}, float @var{bar})
11312 @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
11313 @var{body-of-description}
11318 @code{@@deftypefun} creates an entry in the index of functions for
11324 @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
11325 @subsection Variables in Typed Languages
11327 Variables in typed languages are handled in a manner similar to
11328 functions in typed languages. @xref{Typed Functions}. The general
11329 definition command @code{@@deftypevr} corresponds to
11330 @code{@@deftypefn} and the specialized definition command
11331 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
11335 @item @@deftypevr @var{category} @var{data-type} @var{name}
11336 The @code{@@deftypevr} command is the general definition command for
11337 something like a variable in a typed language---an entity that records
11338 a value. You must choose a term to describe the category of the
11339 entity being defined; for example, ``Variable'' could be used if the
11340 entity is a variable.@refill
11342 The @code{@@deftypevr} command is written at the beginning of a line
11343 and is followed on the same line by the category of the entity
11344 being described, the data type, and the name of this particular
11353 @@deftypevr @{Global Flag@} int enable
11360 produces the following in Info:
11364 -- Global Flag: int enable
11371 and the following in a printed manual:
11374 @deftypevr {Global Flag} int enable
11384 @@deftypevr @var{category} @var{data-type} @var{name}
11385 @var{body-of-description}
11389 @code{@@deftypevr} creates an entry in the index of variables for
11393 @item @@deftypevar @var{data-type} @var{name}
11394 The @code{@@deftypevar} command is the specialized definition command
11395 for variables in typed languages. @code{@@deftypevar} is equivalent
11396 to @samp{@@deftypevr Variable @dots{}}.@refill
11404 @@deftypevar int fubar
11411 produces the following in Info:
11415 -- Variable: int fubar
11423 and the following in a printed manual:
11426 @deftypevar int fubar
11438 @@deftypevar @var{data-type} @var{name}
11439 @var{body-of-description}
11444 @code{@@deftypevar} creates an entry in the index of variables for
11448 @node Abstract Objects
11449 @subsection Object-Oriented Programming
11451 Here are the commands for formatting descriptions about abstract
11452 objects, such as are used in object-oriented programming. A class is
11453 a defined type of abstract object. An instance of a class is a
11454 particular object that has the type of the class. An instance
11455 variable is a variable that belongs to the class but for which each
11456 instance has its own value.@refill
11458 In a definition, if the name of a class is truly a name defined in the
11459 programming system for a class, then you should write an @code{@@code}
11460 around it. Otherwise, it is printed in the usual text font.@refill
11464 @item @@defcv @var{category} @var{class} @var{name}
11465 The @code{@@defcv} command is the general definition command for
11466 variables associated with classes in object-oriented programming. The
11467 @code{@@defcv} command is followed by three arguments: the category of
11468 thing being defined, the class to which it belongs, and its
11473 @@defcv @{Class Option@} Window border-pattern
11480 illustrates how you would write the first line of a definition of the
11481 @code{border-pattern} class option of the class @code{Window}.@refill
11486 @@defcv @var{category} @var{class} @var{name}
11492 @code{@@defcv} creates an entry in the index of variables.
11495 @item @@defivar @var{class} @var{name}
11496 The @code{@@defivar} command is the definition command for instance
11497 variables in object-oriented programming. @code{@@defivar} is
11498 equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
11503 @@defivar @var{class} @var{instance-variable-name}
11504 @var{body-of-definition}
11509 @code{@@defivar} creates an entry in the index of variables.
11511 @findex deftypeivar
11512 @item @@deftypeivar @var{class} @var{data-type} @var{name}
11513 The @code{@@deftypeivar} command is the definition command for typed
11514 instance variables in object-oriented programming. It is similar to
11515 @code{@@defivar} with the addition of the @var{data-type} parameter to
11516 specify the type of the instance variable. @code{@@deftypeivar} creates an
11517 entry in the index of variables.
11520 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11521 The @code{@@defop} command is the general definition command for
11522 entities that may resemble methods in object-oriented programming.
11523 These entities take arguments, as functions do, but are associated with
11524 particular classes of objects.@refill
11526 For example, some systems have constructs called @dfn{wrappers} that
11527 are associated with classes as methods are, but that act more like
11528 macros than like functions. You could use @code{@@defop Wrapper} to
11529 describe one of these.@refill
11531 Sometimes it is useful to distinguish methods and @dfn{operations}.
11532 You can think of an operation as the specification for a method.
11533 Thus, a window system might specify that all window classes have a
11534 method named @code{expose}; we would say that this window system
11535 defines an @code{expose} operation on windows in general. Typically,
11536 the operation has a name and also specifies the pattern of arguments;
11537 all methods that implement the operation must accept the same
11538 arguments, since applications that use the operation do so without
11539 knowing which method will implement it.@refill
11541 Often it makes more sense to document operations than methods. For
11542 example, window application developers need to know about the
11543 @code{expose} operation, but need not be concerned with whether a
11544 given class of windows has its own method to implement this operation.
11545 To describe this operation, you would write:@refill
11548 @@defop Operation windows expose
11551 The @code{@@defop} command is written at the beginning of a line and
11552 is followed on the same line by the overall name of the category of
11553 operation, the name of the class of the operation, the name of the
11554 operation, and its arguments, if any.@refill
11559 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
11560 @var{body-of-definition}
11565 @code{@@defop} creates an entry, such as `@code{expose} on
11566 @code{windows}', in the index of functions.@refill
11569 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11570 The @code{@@deftypeop} command is the definition command for typed
11571 operations in object-oriented programming. It is similar to
11572 @code{@@defop} with the addition of the @var{data-type} parameter to
11573 specify the return type of the method. @code{@@deftypeop} creates an
11574 entry in the index of functions.
11576 @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
11578 The @code{@@defmethod} command is the definition command for methods
11579 in object-oriented programming. A method is a kind of function that
11580 implements an operation for a particular class of objects and its
11583 @c ADR: Who cares?!?
11584 @c KB: Oh, I don't know, I think this info is crucial!
11585 In the Lisp Machine, methods actually were functions, but
11586 they were usually defined with @code{defmethod}.
11589 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
11590 The command is written at the beginning of a line and is followed by
11591 the name of the class of the method, the name of the method, and its
11592 arguments, if any.@refill
11598 @@defmethod @code{bar-class} bar-method argument
11605 illustrates the definition for a method called @code{bar-method} of
11606 the class @code{bar-class}. The method takes an argument.@refill
11612 @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
11613 @var{body-of-definition}
11618 @code{@@defmethod} creates an entry, such as `@code{bar-method} on
11619 @code{bar-class}', in the index of functions.@refill
11622 @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
11624 The @code{@@deftypemethod} command is the definition command for methods
11625 in object-oriented typed languages, such as C++ and Java. It is similar
11626 to the @code{@@defmethod} command with the addition of the
11627 @var{data-type} parameter to specify the return type of the method.
11633 @subsection Data Types
11635 Here is the command for data types:@refill
11639 @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
11640 The @code{@@deftp} command is the generic definition command for data
11641 types. The command is written at the beginning of a line and is
11642 followed on the same line by the category, by the name of the type
11643 (which is a word like @code{int} or @code{float}), and then by names of
11644 attributes of objects of that type. Thus, you could use this command
11645 for describing @code{int} or @code{float}, in which case you could use
11646 @code{data type} as the category. (A data type is a category of
11647 certain objects for purposes of deciding which operations can be
11648 performed on them.)@refill
11650 In Lisp, for example, @dfn{pair} names a particular data
11651 type, and an object of that type has two slots called the
11652 @sc{car} and the @sc{cdr}. Here is how you would write the first line
11653 of a definition of @code{pair}.@refill
11657 @@deftp @{Data type@} pair car cdr
11668 @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
11669 @var{body-of-definition}
11674 @code{@@deftp} creates an entry in the index of data types.
11677 @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
11678 @section Conventions for Writing Definitions
11679 @cindex Definition conventions
11680 @cindex Conventions for writing definitions
11682 When you write a definition using @code{@@deffn}, @code{@@defun}, or
11683 one of the other definition commands, please take care to use
11684 arguments that indicate the meaning, as with the @var{count} argument
11685 to the @code{forward-word} function. Also, if the name of an argument
11686 contains the name of a type, such as @var{integer}, take care that the
11687 argument actually is of that type.@refill
11689 @node Sample Function Definition, , Def Cmd Conventions, Definition Commands
11690 @section A Sample Function Definition
11691 @cindex Function definitions
11692 @cindex Command definitions
11693 @cindex Macro definitions
11694 @cindex Sample function definition
11696 A function definition uses the @code{@@defun} and @code{@@end defun}
11697 commands. The name of the function follows immediately after the
11698 @code{@@defun} command and it is followed, on the same line, by the
11699 parameter list.@refill
11701 Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
11702 Lisp Reference Manual}.
11705 @defun apply function &rest arguments
11706 @code{apply} calls @var{function} with @var{arguments}, just
11707 like @code{funcall} but with one difference: the last of
11708 @var{arguments} is a list of arguments to give to
11709 @var{function}, rather than a single argument. We also say
11710 that this list is @dfn{appended} to the other arguments.
11712 @code{apply} returns the result of calling @var{function}.
11713 As with @code{funcall}, @var{function} must either be a Lisp
11714 function or a primitive function; special forms and macros
11715 do not make sense in @code{apply}.
11721 @error{} Wrong type argument: listp, z
11722 (apply '+ 1 2 '(3 4))
11724 (apply '+ '(1 2 3 4))
11727 (apply 'append '((a b c) nil (x y z) nil))
11728 @result{} (a b c x y z)
11731 An interesting example of using @code{apply} is found in the description
11732 of @code{mapcar}.@refill
11737 In the Texinfo source file, this example looks like this:
11741 @@defun apply function &rest arguments
11742 @@code@{apply@} calls @@var@{function@} with
11743 @@var@{arguments@}, just like @@code@{funcall@} but with one
11744 difference: the last of @@var@{arguments@} is a list of
11745 arguments to give to @@var@{function@}, rather than a single
11746 argument. We also say that this list is @@dfn@{appended@}
11747 to the other arguments.
11751 @@code@{apply@} returns the result of calling
11752 @@var@{function@}. As with @@code@{funcall@},
11753 @@var@{function@} must either be a Lisp function or a
11754 primitive function; special forms and macros do not make
11755 sense in @@code@{apply@}.
11763 @@error@{@} Wrong type argument: listp, z
11764 (apply '+ 1 2 '(3 4))
11766 (apply '+ '(1 2 3 4))
11769 (apply 'append '((a b c) nil (x y z) nil))
11770 @@result@{@} (a b c x y z)
11775 An interesting example of using @@code@{apply@} is found
11776 in the description of @@code@{mapcar@}.
11782 In this manual, this function is listed in the Command and Variable
11783 Index under @code{apply}.@refill
11785 Ordinary variables and user options are described using a format like
11786 that for functions except that variables do not take arguments.
11790 @chapter Conditionally Visible Text
11791 @cindex Conditionally visible text
11792 @cindex Text, conditionally visible
11793 @cindex Visibility of conditional text
11794 @cindex If text conditionally visible
11796 Sometimes it is good to use different text for different output formats.
11797 For example, you can use the @dfn{conditional commands} to specify
11798 different text for the printed manual and the Info output.
11800 Conditional commands may not be nested.
11802 The conditional commands comprise the following categories.
11805 @item Commands for HTML, Info, or @TeX{}.
11806 @item Commands for not HTML, Info, or @TeX{}.
11807 @item Raw @TeX{} or HTML commands.
11809 Substituting text for all formats, and testing if a flag is set or clear.
11813 * Conditional Commands:: Specifying text for HTML, Info, or @TeX{}.
11814 * Conditional Not Commands:: Specifying text for not HTML, Info, or @TeX{}.
11815 * Raw Formatter Commands:: Using raw @TeX{} or HTML commands.
11816 * set clear value:: Designating which text to format (for
11817 all output formats); and how to set a
11818 flag to a string that you can insert.
11822 @node Conditional Commands
11823 @section Conditional Commands
11825 Texinfo has a pair of commands for each output format, to allow
11826 conditional inclusion of text for a particular output format.
11829 @code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
11830 when it typesets the printed manual. The segment of text appears only
11831 in the Info file and (for historical compatibility) the plain text
11832 output. The @code{@@ifinfo} command should appear on a line by itself;
11833 end the Info-only text with a line containing @code{@@end ifinfo} by
11838 @findex ifplaintext
11839 The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
11840 @code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
11841 will appear in the printed manual but not in the Info file. Likewise
11842 for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
11843 appear only in HTML output. And for @code{@@ifplaintext} and
11844 @code{@@end ifplaintext}, which specify text to appear only in plain
11851 This text will appear only in the printed manual.
11854 However, this text will appear only in Info (or plain text).
11857 And this text will only appear in HTML.
11860 Whereas this text will only appear in plain text.
11865 The preceding example produces the following line:
11867 This text will appear only in the printed manual.
11870 However, this text will appear only in Info (or plain text).
11873 And this text will only appear in HTML.
11876 Whereas this text will only appear in plain text.
11880 Notice that you only see one of the input lines, depending on which
11881 version of the manual you are reading.
11884 @node Conditional Not Commands
11885 @section Conditional Not Commands
11888 @findex ifnotplaintext
11891 You can specify text to be included in any output format @emph{other}
11892 than some given one with the @code{@@ifnot@dots{}} commands:
11894 @@ifnothtml @dots{} @@end ifnothtml
11895 @@ifnotinfo @dots{} @@end ifnotinfo
11896 @@ifnotplaintext @dots{} @@end ifnotplaintext
11897 @@ifnottex @dots{} @@end ifnottex
11900 (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
11901 appear on lines by themselves in your actual source file.)
11903 If the output file is @emph{not} being made for the given format, the
11904 region is included. Otherwise, it is ignored.
11906 With one exception (for historical compatibility): @code{@@ifnotinfo}
11907 text is omitted for both Info and plain text output, not just Info. To
11908 specify text which appears only in Info and not in plain text, use
11909 @code{@@ifnotplaintext}, like this:
11913 This will be in Info, but not plain text.
11914 @end ifnotplaintext
11918 The regions delimited by these commands are ordinary Texinfo source as
11919 with @code{@@iftex}, not raw formatter source as with @code{@@tex}
11920 (@pxref{Raw Formatter Commands}).
11923 @node Raw Formatter Commands
11924 @section Raw Formatter Commands
11925 @cindex @TeX{} commands, using ordinary
11926 @cindex HTML commands, using ordinary
11927 @cindex Raw formatter commands
11928 @cindex Ordinary @TeX{} commands, using
11929 @cindex Ordinary HTML commands, using
11930 @cindex Commands using raw @TeX{}
11931 @cindex Commands using raw HTML
11932 @cindex plain @TeX{}
11934 Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
11935 can embed some raw @TeX{} commands. Info will ignore these commands
11936 since they are only in that part of the file which is seen by @TeX{}.
11937 You can write the @TeX{} commands as you would write them in a normal
11938 @TeX{} file, except that you must replace the @samp{\} used by @TeX{}
11939 with an @samp{@@}. For example, in the @code{@@titlepage} section of a
11940 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
11941 the copyright page. (The @code{@@titlepage} command causes Info to
11942 ignore the region automatically, as it does with the @code{@@iftex}
11945 However, many features of plain @TeX{} will not work, as they are
11946 overridden by Texinfo features.
11949 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
11950 commands, by delineating a region with the @code{@@tex} and @code{@@end
11951 tex} commands. (The @code{@@tex} command also causes Info to ignore the
11952 region, like the @code{@@iftex} command.) The sole exception is that the
11953 @code{@@} character still introduces a command, so that @code{@@end tex}
11954 can be recognized properly.
11956 @cindex Mathematical expressions
11957 For example, here is a mathematical expression written in
11962 $$ \chi^2 = \sum_@{i=1@}^N
11963 \left (y_i - (a + b x_i)
11964 \over \sigma_i\right)^2 $$
11969 The output of this example will appear only in a printed manual. If
11970 you are reading this in Info, you will not see the equation that appears
11971 in the printed manual.
11973 In a printed manual, the above expression looks like
11978 $$ \chi^2 = \sum_{i=1}^N
11979 \left(y_i - (a + b x_i)
11980 \over \sigma_i\right)^2 $$
11985 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
11986 a region to be included in HTML output only, and @code{@@html @dots{}
11987 @@end html} for a region of raw HTML (again, except that @code{@@} is
11988 still the escape character, so the @code{@@end} command can be
11992 @node set clear value
11993 @section @code{@@set}, @code{@@clear}, and @code{@@value}
11995 You can direct the Texinfo formatting commands to format or ignore parts
11996 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
11997 and @code{@@ifclear} commands.@refill
11999 Brief descriptions:
12002 @item @@set @var{flag} [@var{value}]
12003 Set the variable @var{flag}, to the optional @var{value} if specifed.
12005 @item @@clear @var{flag}
12006 Undefine the variable @var{flag}, whether or not it was previously defined.
12008 @item @@ifset @var{flag}
12009 If @var{flag} is set, text through the next @code{@@end ifset} command
12010 is formatted. If @var{flag} is clear, text through the following
12011 @code{@@end ifset} command is ignored.
12013 @item @@ifclear @var{flag}
12014 If @var{flag} is set, text through the next @code{@@end ifclear} command
12015 is ignored. If @var{flag} is clear, text through the following
12016 @code{@@end ifclear} command is formatted.
12020 * set value:: Expand a flag variable to a string.
12021 * ifset ifclear:: Format a region if a flag is set.
12022 * value Example:: An easy way to update edition information.
12027 @subsection @code{@@set} and @code{@@value}
12030 You use the @code{@@set} command to specify a value for a flag, which is
12031 later expanded by the @code{@@value} command.
12033 A @dfn{flag} is an identifier. In general, it is best to use only
12034 letters and numerals in a flag name, not @samp{-} or @samp{_}---they
12035 will work in some contexts, but not all, due to limitations in @TeX{}.
12037 The value is the remainder of the input line, and can contain anything.
12039 Write the @code{@@set} command like this:
12042 @@set foo This is a string.
12046 This sets the value of the flag @code{foo} to ``This is a string.''.
12048 The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
12049 command with the string to which @var{flag} is set. Thus, when
12050 @code{foo} is set as shown above, the Texinfo formatters convert this:
12055 @exdent @r{to this:}
12060 You can write an @code{@@value} command within a paragraph; but you
12061 must write an @code{@@set} command on a line of its own.
12063 If you write the @code{@@set} command like this:
12070 without specifying a string, the value of @code{foo} is the empty string.
12072 If you clear a previously set flag with @code{@@clear @var{flag}}, a
12073 subsequent @code{@@value@{flag@}} command will report an error.
12075 For example, if you set @code{foo} as follows:@refill
12078 @@set how-much very, very, very
12082 then the formatters transform
12086 It is a @@value@{how-much@} wet day.
12088 It is a very, very, very wet day.
12099 then the formatters transform
12103 It is a @@value@{how-much@} wet day.
12105 It is a @{No value for "how-much"@} wet day.
12110 @node ifset ifclear
12111 @subsection @code{@@ifset} and @code{@@ifclear}
12114 When a @var{flag} is set, the Texinfo formatting commands format text
12115 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
12116 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
12117 commands do @emph{not} format the text. @code{@@ifclear} operates
12120 Write the conditionally formatted text between @code{@@ifset @var{flag}}
12121 and @code{@@end ifset} commands, like this:
12126 @var{conditional-text}
12131 For example, you can create one document that has two variants, such as
12132 a manual for a `large' and `small' model:
12136 You can use this machine to dig up shrubs
12137 without hurting them.
12142 It can also dig up fully grown trees.
12145 Remember to replant promptly @dots{}
12149 In the example, the formatting commands will format the text between
12150 @code{@@ifset large} and @code{@@end ifset} because the @code{large}
12153 When @var{flag} is cleared, the Texinfo formatting commands do
12154 @emph{not} format the text between @code{@@ifset @var{flag}} and
12155 @code{@@end ifset}; that text is ignored and does not appear in either
12156 printed or Info output.
12158 For example, if you clear the flag of the preceding example by writing
12159 an @code{@@clear large} command after the @code{@@set large} command
12160 (but before the conditional text), then the Texinfo formatting commands
12161 ignore the text between the @code{@@ifset large} and @code{@@end ifset}
12162 commands. In the formatted output, that text does not appear; in both
12163 printed and Info output, you see only the lines that say, ``You can use
12164 this machine to dig up shrubs without hurting them. Remember to replant
12165 promptly @dots{}''.
12168 If a flag is cleared with an @code{@@clear @var{flag}} command, then
12169 the formatting commands format text between subsequent pairs of
12170 @code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
12171 is set with @code{@@set @var{flag}}, then the formatting commands do
12172 @emph{not} format text between an @code{@@ifclear} and an @code{@@end
12173 ifclear} command; rather, they ignore that text. An @code{@@ifclear}
12174 command looks like this:
12177 @@ifclear @var{flag}
12181 @node value Example
12182 @subsection @code{@@value} Example
12184 You can use the @code{@@value} command to minimize the number of places
12185 you need to change when you record an update to a manual. @xref{GNU
12186 Sample Texts}, for an example of this same principle can work with
12187 Automake distributions, and full texts.
12189 Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
12198 @@set EDITION 0.35 Beta
12199 @@set VERSION 3.63 Beta
12200 @@set UPDATED 14 August 1992
12201 @@set UPDATE-MONTH August 1992
12206 Write text for the @code{@@copying} section (@pxref{copying}):
12211 This is Edition @@value@{EDITION@},
12212 last updated @@value@{UPDATED@},
12213 of @@cite@{The GNU Make Manual@},
12214 for @@code@{make@}, version @@value@{VERSION@}.
12218 Permission is granted @dots{}
12224 Write text for the title page, for people reading the printed manual:
12230 @@subtitle A Program for Directing Recompilation
12231 @@subtitle Edition @@value@{EDITION@}, @dots{}
12232 @@subtitle @@value@{UPDATE-MONTH@}
12241 (On a printed cover, a date listing the month and the year looks less
12242 fussy than a date listing the day as well as the month and year.)
12245 Write text for the Top node, for people reading the Info file:
12259 After you format the manual, the @code{@@value} constructs have been
12260 expanded, so the output contains text like this:
12264 This is Edition 0.35 Beta, last updated 14 August 1992,
12265 of `The GNU Make Manual', for `make', Version 3.63 Beta.
12270 When you update the manual, you change only the values of the flags; you
12271 do not need to edit the three sections.
12274 @node Internationalization
12275 @chapter Internationalization
12277 @cindex Internationalization
12278 Texinfo has some support for writing in languages other than English,
12279 although this area still needs considerable work.
12281 For a list of the various accented and special characters Texinfo
12282 supports, see @ref{Inserting Accents}.
12285 * documentlanguage:: Declaring the current language.
12286 * documentencoding:: Declaring the input encoding.
12290 @node documentlanguage
12291 @section @code{@@documentlanguage @var{cc}}: Set the Document Language
12293 @findex documentlanguage
12294 @cindex Language, declaring
12295 @cindex Document language, declaring
12297 The @code{@@documentlanguage} command declares the current document
12298 language. Write it on a line by itself, with a two-letter ISO-639
12299 language code following (list is included below). If you have a
12300 multilingual document, the intent is to be able to use this command
12301 multiple times, to declare each language change. If the command is not
12302 used at all, the default is @code{en} for English.
12304 @cindex @file{txi-@var{cc}.tex}
12305 At present, this command is ignored in Info and HTML output. For
12306 @TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
12307 exists). Such a file appropriately redefines the various English words
12308 used in @TeX{} output, such as `Chapter', `See', and so on.
12310 @cindex Hyphenation patterns, language-dependent
12311 It would be good if this command also changed @TeX{}'s ideas of the
12312 current hyphenation patterns (via the @TeX{} primitive
12313 @code{\language}), but this is unfortunately not currently implemented.
12315 @cindex ISO 639 codes
12316 @cindex Language codes
12317 Hereare the valid language codes, from ISO-639.
12319 @multitable @columnfractions .07 .26 .07 .26 .07 .26
12321 @code{aa} @tab Afar @tab
12322 @code{ab} @tab Abkhazian @tab
12323 @code{af} @tab Afrikaans
12325 @code{am} @tab Amharic @tab
12326 @code{ar} @tab Arabic @tab
12327 @code{as} @tab Assamese
12329 @code{ay} @tab Aymara @tab
12330 @code{az} @tab Azerbaijani @tab
12331 @code{ba} @tab Bashkir
12333 @code{be} @tab Byelorussian @tab
12334 @code{bg} @tab Bulgarian @tab
12335 @code{bh} @tab Bihari
12337 @code{bi} @tab Bislama @tab
12338 @code{bn} @tab Bengali; Bangla @tab
12339 @code{bo} @tab Tibetan
12341 @code{br} @tab Breton @tab
12342 @code{ca} @tab Catalan @tab
12343 @code{co} @tab Corsican
12345 @code{cs} @tab Czech @tab
12346 @code{cy} @tab Welsh @tab
12347 @code{da} @tab Danish
12349 @code{de} @tab German @tab
12350 @code{dz} @tab Bhutani @tab
12351 @code{el} @tab Greek
12353 @code{en} @tab English @tab
12354 @code{eo} @tab Esperanto @tab
12355 @code{es} @tab Spanish
12357 @code{et} @tab Estonian @tab
12358 @code{eu} @tab Basque @tab
12359 @code{fa} @tab Persian
12361 @code{fi} @tab Finnish @tab
12362 @code{fj} @tab Fiji @tab
12363 @code{fo} @tab Faroese
12365 @code{fr} @tab French @tab
12366 @code{fy} @tab Frisian @tab
12367 @code{ga} @tab Irish
12369 @code{gd} @tab Scots Gaelic @tab
12370 @code{gl} @tab Galician @tab
12371 @code{gn} @tab Guarani
12373 @code{gu} @tab Gujarati @tab
12374 @code{ha} @tab Hausa @tab
12375 @code{he} @tab Hebrew
12377 @code{hi} @tab Hindi @tab
12378 @code{hr} @tab Croatian @tab
12379 @code{hu} @tab Hungarian
12381 @code{hy} @tab Armenian @tab
12382 @code{ia} @tab Interlingua @tab
12383 @code{id} @tab Indonesian
12385 @code{ie} @tab Interlingue @tab
12386 @code{ik} @tab Inupiak @tab
12387 @code{is} @tab Icelandic
12389 @code{it} @tab Italian @tab
12390 @code{iu} @tab Inuktitut @tab
12391 @code{ja} @tab Japanese
12393 @code{jw} @tab Javanese @tab
12394 @code{ka} @tab Georgian @tab
12395 @code{kk} @tab Kazakh
12397 @code{kl} @tab Greenlandic @tab
12398 @code{km} @tab Cambodian @tab
12399 @code{kn} @tab Kannada
12401 @code{ks} @tab Kashmiri @tab
12402 @code{ko} @tab Korean @tab
12403 @code{ku} @tab Kurdish
12405 @code{ky} @tab Kirghiz @tab
12406 @code{la} @tab Latin @tab
12407 @code{ln} @tab Lingala
12409 @code{lt} @tab Lithuanian @tab
12410 @code{lo} @tab Laothian @tab
12411 @code{lv} @tab Latvian, Lettish
12413 @code{mg} @tab Malagasy @tab
12414 @code{mi} @tab Maori @tab
12415 @code{mk} @tab Macedonian
12417 @code{ml} @tab Malayalam @tab
12418 @code{mn} @tab Mongolian @tab
12419 @code{mo} @tab Moldavian
12421 @code{mr} @tab Marathi @tab
12422 @code{ms} @tab Malay @tab
12423 @code{mt} @tab Maltese
12425 @code{my} @tab Burmese @tab
12426 @code{na} @tab Nauru @tab
12427 @code{ne} @tab Nepali
12429 @code{nl} @tab Dutch @tab
12430 @code{no} @tab Norwegian @tab
12431 @code{oc} @tab Occitan
12433 @code{om} @tab (Afan) Oromo @tab
12434 @code{or} @tab Oriya @tab
12435 @code{pa} @tab Punjabi
12437 @code{pl} @tab Polish @tab
12438 @code{ps} @tab Pashto, Pushto @tab
12439 @code{pt} @tab Portuguese
12441 @code{qu} @tab Quechua @tab
12442 @code{rm} @tab Rhaeto-Romance @tab
12443 @code{rn} @tab Kirundi
12445 @code{ro} @tab Romanian @tab
12446 @code{ru} @tab Russian @tab
12447 @code{rw} @tab Kinyarwanda
12449 @code{sa} @tab Sanskrit @tab
12450 @code{sd} @tab Sindhi @tab
12451 @code{sg} @tab Sangro
12453 @code{sh} @tab Serbo-Croatian @tab
12454 @code{si} @tab Sinhalese @tab
12455 @code{sk} @tab Slovak
12457 @code{sl} @tab Slovenian @tab
12458 @code{sm} @tab Samoan @tab
12459 @code{sn} @tab Shona
12461 @code{so} @tab Somali @tab
12462 @code{sq} @tab Albanian @tab
12463 @code{sr} @tab Serbian
12465 @code{ss} @tab Siswati @tab
12466 @code{st} @tab Sesotho @tab
12467 @code{su} @tab Sundanese
12469 @code{sv} @tab Swedish @tab
12470 @code{sw} @tab Swahili @tab
12471 @code{ta} @tab Tamil
12473 @code{te} @tab Telugu @tab
12474 @code{tg} @tab Tajik @tab
12475 @code{th} @tab Thai
12477 @code{ti} @tab Tigrinya @tab
12478 @code{tk} @tab Turkmen @tab
12479 @code{tl} @tab Tagalog
12481 @code{tn} @tab Setswana @tab
12482 @code{to} @tab Tonga @tab
12483 @code{tr} @tab Turkish
12485 @code{ts} @tab Tsonga @tab
12486 @code{tt} @tab Tatar @tab
12489 @code{ug} @tab Uighur @tab
12490 @code{uk} @tab Ukrainian @tab
12491 @code{ur} @tab Urdu
12493 @code{uz} @tab Uzbek @tab
12494 @code{vi} @tab Vietnamese @tab
12495 @code{vo} @tab Volapuk
12497 @code{wo} @tab Wolof @tab
12498 @code{xh} @tab Xhosa @tab
12499 @code{yi} @tab Yiddish
12501 @code{yo} @tab Yoruba @tab
12502 @code{za} @tab Zhuang @tab
12503 @code{zh} @tab Chinese
12505 @code{zu} @tab Zulu
12509 @node documentencoding
12510 @section @code{@@documentencoding @var{enc}}: Set Input Encoding
12512 @findex documentencoding
12513 @cindex Encoding, declaring
12514 @cindex Input encoding, declaring
12515 @cindex Document input encoding
12517 The @code{@@documentencoding} command declares the input document
12518 encoding. Write it on a line by itself, with a valid encoding
12519 specification following, such as @samp{ISO-8859-1}.
12521 @cindex http-equiv, and charset
12522 @cindex meta HTML tag, and charset
12523 At present, this is used only in HTML output from @code{makeinfo}. If a
12524 document encoding @var{enc} is specified, it is used in a
12525 @samp{<meta>} tag included in the @samp{<head>} of the output:
12528 <meta http-equiv="Content-Type" content="text/html;
12529 charset=@var{enc}">
12533 @node Defining New Texinfo Commands
12534 @chapter Defining New Texinfo Commands
12536 @cindex Defining new Texinfo commands
12537 @cindex New Texinfo commands, defining
12538 @cindex Texinfo commands, defining new
12539 @cindex User-defined Texinfo commands
12541 Texinfo provides several ways to define new commands:
12545 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
12546 sequence of text and/or existing commands (including other macros). The
12547 macro can have any number of @dfn{parameters}---text you supply each
12548 time you use the macro.
12550 Incidentally, these macros have nothing to do with the @code{@@defmac}
12551 command, which is for documenting macros in the subject of the manual
12552 (@pxref{Def Cmd Template}).
12555 @samp{@@alias} is a convenient way to define a new name for an existing
12559 @samp{@@definfoenclose} allows you to define new commands with
12560 customized output in the Info file.
12565 * Defining Macros:: Defining and undefining new commands.
12566 * Invoking Macros:: Using a macro, once you've defined it.
12567 * Macro Details:: Beyond basic macro usage.
12568 * alias:: Command aliases.
12569 * definfoenclose:: Customized highlighting.
12573 @node Defining Macros
12574 @section Defining Macros
12575 @cindex Defining macros
12576 @cindex Macro definitions
12579 You use the Texinfo @code{@@macro} command to define a macro, like this:
12582 @@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
12583 @var{text} @dots{} \@var{param1}\ @dots{}
12587 The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
12588 arguments supplied when the macro is subsequently used in the document
12589 (described in the next section).
12591 For a macro to work with @TeX{}, @var{macroname} must consist entirely
12592 of letters: no digits, hyphens, underscores, or other special characters.
12594 If a macro needs no parameters, you can define it either with an empty
12595 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
12598 @cindex Body of a macro
12599 @cindex Mutually recursive macros
12600 @cindex Recursion, mutual
12601 The definition or @dfn{body} of the macro can contain most Texinfo
12602 commands, including previously-defined macros. Not-yet-defined macro
12603 invocations are not allowed; thus, it is not possible to have mutually
12604 recursive Texinfo macros. Also, a macro definition that defines another
12605 macro does not work in @TeX{} due to limitations in the design of
12608 @cindex Parameters to macros
12609 In the macro body, instances of a parameter name surrounded by
12610 backslashes, as in @samp{\@var{param1}\} in the example above, are
12611 replaced by the corresponding argument from the macro invocation. You
12612 can use parameter names any number of times in the body, including zero.
12614 @cindex Backslash in macros
12615 To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
12616 other use of @samp{\} in the body yields a warning.
12618 @cindex Spaces in macros
12619 @cindex Whitespace in macros
12620 The newlines after the @code{@@macro} line and before the @code{@@end
12621 macro} line are ignored, that is, not included in the macro body. All
12622 other whitespace is treated according to the usual Texinfo rules.
12624 @cindex Recursive macro invocations
12626 To allow a macro to be used recursively, that is, in an argument to a
12627 call to itself, you must define it with @samp{@@rmacro}, like this:
12630 @@rmacro rmac @{arg@}
12634 @@rmac@{1@@rmac@{text@}2@}
12637 This produces the output `a1atextb2b'. With @samp{@@macro} instead of
12638 @samp{@@rmacro}, an error message is given.
12641 @cindex Macros, undefining
12642 @cindex Undefining macros
12643 You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
12644 It is not an error to undefine a macro that is already undefined.
12652 @node Invoking Macros
12653 @section Invoking Macros
12654 @cindex Invoking macros
12655 @cindex Expanding macros
12656 @cindex Running macros
12657 @cindex Macro invocation
12659 After a macro is defined (see the previous section), you can use
12660 (@dfn{invoke}) it in your document like this:
12663 @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
12666 @noindent and the result will be just as if you typed the body of
12667 @var{macroname} at that spot. For example:
12670 @@macro foo @{p, q@}
12671 Together: \p\ & \q\.
12676 @noindent produces:
12682 @cindex Backslash, and macros
12683 Thus, the arguments and parameters are separated by commas and delimited
12684 by braces; any whitespace after (but not before) a comma is ignored.
12685 The braces are required in the invocation (but not the definition), even
12686 when the macro takes no arguments, consistent with all other Texinfo
12687 commands. For example:
12690 @@macro argless @{@}
12696 @noindent produces:
12702 @cindex Comma, in macro arguments
12703 @cindex Braces, in macro arguments
12704 To insert a comma, brace, or backslash in an argument, prepend a
12708 @@@var{macname} @{\\\@{\@}\,@}
12712 which will pass the (almost certainly error-producing) argument
12713 @samp{\@{@},} to @var{macname}. However, commas in parameters, even
12714 if escaped by a backslash, might cause trouble in @TeX{}.
12716 If the macro is defined to take a single argument, and is invoked
12717 without any braces, the entire rest of the line after the macro name is
12718 supplied as the argument. For example:
12727 @noindent produces:
12729 @c Sorry for cheating, but let's not require macros to process the manual.
12734 If the macro is defined to take a single argument, and is invoked with
12735 braces, the braced text is passed as the argument, regardless of
12736 commas. For example:
12745 @noindent produces:
12752 @node Macro Details
12753 @section Macro Details
12754 @cindex Macro details
12755 @cindex Details of macro usage
12757 Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
12758 implementations, Texinfo macros have the following limitations.
12762 All macros are expanded inside at least one @TeX{} group. This means
12763 that @code{@@set} and other such commands will have no effect inside a
12767 Macros containing a command which must be on a line by itself, such as a
12768 conditional, cannot be invoked in the middle of a line.
12771 Commas in macro arguments, even if escaped by a backslash, don't
12775 The @TeX{} implementation cannot construct macros that define macros in
12776 the natural way. To do this, you must use conditionals and raw @TeX{}.
12781 @@macro ctor @{name, arg@}
12783 something involving \arg\ somehow
12788 \gdef\ctor#1@{\ctorx#1,@}
12789 \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
12794 It is best to avoid comments inside macro definitions.
12798 If some macro feature causes errors when producing the printed version
12799 of a manual, try expanding the macros with @command{makeinfo} by
12800 invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
12804 @section @samp{@@alias @var{new}=@var{existing}}
12805 @cindex Aliases, command
12806 @cindex Command aliases
12809 The @samp{@@alias} command defines a new command to be just like an
12810 existing one. This is useful for defining additional markup names, thus
12811 preserving semantic information in the input even though the output
12812 result may be the same.
12814 Write the @samp{@@alias} command on a line by itself, followed by the
12815 new command name, an equals sign, and the existing command name.
12816 Whitespace around the equals sign is ignored. Thus:
12818 @@alias @var{new} = @var{existing}
12821 For example, if your document contains citations for both books and
12822 some other media (movies, for example), you might like to define a
12823 macro @code{@@moviecite@{@}} that does the same thing as an ordinary
12824 @code{@@cite@{@}} but conveys the extra semantic information as well.
12825 You'd do this as follows:
12828 @@alias moviecite = cite
12831 Macros do not always have the same effect due to vagaries of argument
12832 parsing. Also, aliases are much simpler to define than macros. So the
12833 command is not redundant. (It was also heavily used in the Jargon File!)
12835 Aliases must not be recursive, directly or indirectly.
12837 @node definfoenclose
12838 @section @samp{definfoenclose}: Customized Highlighting
12839 @cindex Highlighting, customized
12840 @cindex Customized highlighting
12841 @findex definfoenclose
12843 A @code{@@definfoenclose} command may be used to define a highlighting
12844 command for Info, but not for @TeX{}. A command defined using
12845 @code{@@definfoenclose} marks text by enclosing it in strings that
12846 precede and follow the text. You can use this to get closer control of
12849 Presumably, if you define a command with @code{@@definfoenclose} for Info,
12850 you will create a corresponding command for @TeX{}, either in
12851 @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
12854 Write a @code{@@definfoenclose} command on a line and follow it with
12855 three arguments separated by commas. The first argument to
12856 @code{@@definfoenclose} is the @@-command name (without the @code{@@});
12857 the second argument is the Info start delimiter string; and the third
12858 argument is the Info end delimiter string. The latter two arguments
12859 enclose the highlighted text in the Info file. A delimiter string may
12860 contain spaces. Neither the start nor end delimiter is required. If
12861 you do not want a start delimiter but do want an end delimiter, you must
12862 follow the command name with two commas in a row; otherwise, the Info
12863 formatting commands will naturally misinterpret the end delimiter string
12864 you intended as the start delimiter string.
12866 If you do a @code{@@definfoenclose} on the name of a pre-defined macro
12867 (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
12868 enclosure definition will override the built-in definition.
12870 An enclosure command defined this way takes one argument in braces; this
12871 is intended for new markup commands (@pxref{Marking Text}).
12874 For example, you can write:
12877 @@definfoenclose phoo,//,\\
12881 near the beginning of a Texinfo file to define @code{@@phoo} as an Info
12882 formatting command that inserts `//' before and `\\' after the argument
12883 to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
12884 want `//bar\\' highlighted in Info.
12886 Also, for @TeX{} formatting, you could write
12890 @@global@@let@@phoo=@@i
12895 to define @code{@@phoo} as a command that causes @TeX{} to typeset the
12896 argument to @code{@@phoo} in italics.
12898 Each definition applies to its own formatter: one for @TeX{}, the other
12899 for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
12900 @code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
12901 the raw @TeX{} commands do need to be in @samp{@@iftex}.
12904 Here is another example: write
12907 @@definfoenclose headword, , :
12911 near the beginning of the file, to define @code{@@headword} as an Info
12912 formatting command that inserts nothing before and a colon after the
12913 argument to @code{@@headword}.
12915 @samp{@@definfoenclose} definitions must not be recursive, directly or
12920 @chapter Formatting and Printing Hardcopy
12921 @cindex Format and print hardcopy
12922 @cindex Printing hardcopy
12923 @cindex Hardcopy, printing it
12924 @cindex Making a printed manual
12925 @cindex Sorting indices
12926 @cindex Indices, sorting
12927 @cindex @TeX{} index sorting
12930 There are three major shell commands for making a printed manual from a
12931 Texinfo file: one for converting the Texinfo file into a file that will be
12932 printed, a second for sorting indices, and a third for printing the
12933 formatted document. When you use the shell commands, you can either
12934 work directly in the operating system shell or work within a shell
12937 If you are using GNU Emacs, you can use commands provided by Texinfo
12938 mode instead of shell commands. In addition to the three commands to
12939 format a file, sort the indices, and print the result, Texinfo mode
12940 offers key bindings for commands to recenter the output buffer, show the
12941 print queue, and delete a job from the print queue.
12944 * Use TeX:: Use @TeX{} to format for hardcopy.
12945 * Format with tex/texindex:: How to format with explicit shell commands.
12946 * Format with texi2dvi:: A simpler way to format.
12947 * Print with lpr:: How to print.
12948 * Within Emacs:: How to format and print from an Emacs shell.
12949 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
12950 * Compile-Command:: How to print using Emacs's compile command.
12951 * Requirements Summary:: @TeX{} formatting requirements summary.
12952 * Preparing for TeX:: What to do before you use @TeX{}.
12953 * Overfull hboxes:: What are and what to do with overfull hboxes.
12954 * smallbook:: How to print small format books and manuals.
12955 * A4 Paper:: How to print on A4 or A5 paper.
12956 * pagesizes:: How to print with customized page sizes.
12957 * Cropmarks and Magnification:: How to print marks to indicate the size
12958 of pages and how to print scaled up output.
12959 * PDF Output:: Portable Document Format output.
12963 @section Use @TeX{}
12965 The typesetting program called @TeX{} is used for formatting a Texinfo
12966 file. @TeX{} is a very powerful typesetting program and, if used correctly,
12967 does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
12968 @TeX{}}, for information on how to obtain @TeX{}.)
12970 The standalone @code{makeinfo} program and Emacs functions
12971 @code{texinfo-format-region} and @code{texinfo-format-buffer} commands
12972 read the very same @@-commands in the Texinfo file as does @TeX{}, but
12973 process them differently to make an Info file (@pxref{Creating an Info
12977 @node Format with tex/texindex
12978 @section Format with @code{tex} and @code{texindex}
12979 @cindex Shell formatting with @code{tex} and @code{texindex}
12980 @cindex Formatting with @code{tex} and @code{texindex}
12983 Format the Texinfo file with the shell command @code{tex} followed by
12984 the name of the Texinfo file. For example:
12990 @noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
12991 files containing information for indices, cross references, etc. The
12992 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
12993 any device (see the following sections).
12996 The @code{tex} formatting command itself does not sort the indices; it
12997 writes an output file of unsorted index data. (The @code{texi2dvi}
12998 command automatically generates indices; @pxref{Format with texi2dvi,,
12999 Format with @code{texi2dvi}}.) To generate a printed index after
13000 running the @code{tex} command, you first need a sorted index to work
13001 from. The @code{texindex} command sorts indices. (The source file
13002 @file{texindex.c} comes as part of the standard Texinfo distribution,
13003 among other places.)@refill
13005 @cindex Names of index files
13006 @cindex Index file names
13007 The @code{tex} formatting command outputs unsorted index files under
13008 names that obey a standard convention: the name of your main input file
13009 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
13010 Web2c}) extension removed, followed by the two letter names of indices.
13011 For example, the raw index output files for the input file
13012 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
13013 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
13014 arguments to give to @code{texindex}.
13019 Instead of specifying all the unsorted index file names explicitly, you
13020 can use @samp{??} as shell wildcards and give the command in this
13028 This command will run @code{texindex} on all the unsorted index files,
13029 including any that you have defined yourself using @code{@@defindex}
13030 or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
13031 even if there are similarly named files with two letter extensions
13032 that are not index files, such as @samp{foo.el}. The @code{texindex}
13033 command reports but otherwise ignores such files.)
13035 For each file specified, @code{texindex} generates a sorted index file
13036 whose name is made by appending @samp{s} to the input file name. The
13037 @code{@@printindex} command looks for a file with that name
13038 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
13039 raw index output file.
13041 After you have sorted the indices, you need to rerun the @code{tex}
13042 formatting command on the Texinfo file. This regenerates the DVI file,
13043 this time with up-to-date index entries.
13045 Finally, you may need to run @code{tex} one more time, to get the page
13046 numbers in the cross-references correct.
13048 To summarize, this is a five step process:
13052 Run @code{tex} on your Texinfo file. This generates a DVI file (with
13053 undefined cross-references and no indices), and the raw index files
13054 (with two letter extensions).
13057 Run @code{texindex} on the raw index files. This creates the
13058 corresponding sorted index files (with three letter extensions).
13061 Run @code{tex} again on your Texinfo file. This regenerates the DVI
13062 file, this time with indices and defined cross-references, but with page
13063 numbers for the cross-references from last time, generally incorrect.
13066 Sort the indices again, with @code{texindex}.
13069 Run @code{tex} one last time. This time the correct page numbers are
13070 written for the cross-references.
13074 Alternatively, it's a one-step process: run @code{texi2dvi}
13075 (@pxref{Format with texi2dvi}).
13077 You need not run @code{texindex} each time after you run @code{tex}. If
13078 you do not, on the next run, the @code{tex} formatting command will use
13079 whatever sorted index files happen to exist from the previous use of
13080 @code{texindex}. This is usually ok while you are debugging.
13082 @cindex Auxiliary files, avoiding
13084 @cindex Pointer validation, suppressing
13085 @cindex Chapters, formatting one at a time
13086 Sometimes you may wish to print a document while you know it is
13087 incomplete, or to print just one chapter of a document. In that case,
13088 the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
13089 when cross-references are not satisfied are just nuisances. You can
13090 avoid them with the @code{@@novalidate} command, which you must give
13091 @emph{before} the @code{@@setfilename} command
13092 (@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
13093 your file would look approximately like this:
13098 @@setfilename myfile.info
13102 @noindent @code{@@novalidate} also turns off validation in
13103 @code{makeinfo}, just like its @code{--no-validate} option
13104 (@pxref{Pointer Validation}).
13107 @node Format with texi2dvi
13108 @section Format with @code{texi2dvi}
13109 @pindex texi2dvi @r{(shell script)}
13111 The @code{texi2dvi} command automatically runs both @code{tex} and
13112 @code{texindex} as many times as necessary to produce a DVI file with
13113 sorted indices and all cross-references resolved. It simplifies the
13114 @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
13115 described in the previous section.
13117 To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
13118 @samp{prompt$ } is your shell prompt):
13121 prompt$ @kbd{texi2dvi foo.texi}
13124 As shown in this example, the input filenames to @code{texi2dvi} must
13125 include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
13126 MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
13127 texi2dvi foo.texi} instead of relying on the operating system to invoke
13128 the shell on the @samp{texi2dvi} script.
13130 Perhaps the most useful option to @code{texi2dvi} is
13131 @samp{--texinfo=@var{cmd}}. This inserts @var{cmd} on a line by itself
13132 after the @code{@@setfilename} in a temporary copy of the input file
13133 before running @TeX{}. With this, you can specify different printing
13134 formats, such as @code{@@smallbook} (@pxref{smallbook}),
13135 @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
13136 (@pxref{pagesizes}), without actually changing the document source.
13137 (You can also do this on a site-wide basis with @file{texinfo.cnf};
13138 @pxref{Preparing for TeX,,Preparing for @TeX{}}).
13140 For a list of other options, run @samp{texi2dvi --help}.
13143 @node Print with lpr
13144 @section Shell Print Using @code{lpr -d}
13145 @pindex lpr @r{(DVI print command)}
13147 The precise command to print a DVI file depends on your system
13148 installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
13151 For example, the following commands will (perhaps) suffice to sort the
13152 indices, format, and print the @cite{Bison Manual}:
13164 (Remember that the shell commands may be different at your site; but
13165 these are commonly used versions.)
13167 Using the @code{texi2dvi} shell script (see the previous section):
13171 texi2dvi bison.texinfo
13173 # or perhaps dvips bison.dvi -o
13177 @cindex Shell printing, on MS-DOS/MS-Windows
13178 @cindex Printing DVI files, on MS-DOS/MS-Windows
13179 @pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
13180 @code{lpr} is a standard program on Unix systems, but it is usually
13181 absent on MS-DOS/MS-Windows. Some network packages come with a
13182 program named @code{lpr}, but these are usually limited to sending files
13183 to a print server over the network, and generally don't support the
13184 @samp{-d} option. If you are unfortunate enough to work on one of these
13185 systems, you have several alternative ways of printing DVI files:
13188 @item Find and install a Unix-like @code{lpr} program, or its clone.
13189 If you can do that, you will be able to print DVI files just like
13192 @item Send the DVI files to a network printer queue for DVI files.
13193 Some network printers have special queues for printing DVI files. You
13194 should be able to set up your network software to send files to that
13195 queue. In some cases, the version of @code{lpr} which comes with your
13196 network software will have a special option to send a file to specific
13200 lpr -Qdvi -hprint.server.domain bison.dvi
13203 @item Convert the DVI file to a Postscript or PCL file and send it to your
13204 local printer. @xref{dvips invocation,,, dvips, Dvips}, and the man
13205 pages for @code{dvilj}, for detailed description of these tools. Once
13206 the DVI file is converted to the format your local printer understands
13207 directly, just send it to the appropriate port, usually @samp{PRN}.
13212 @section From an Emacs Shell
13213 @cindex Print, format from Emacs shell
13214 @cindex Format, print from Emacs shell
13215 @cindex Shell, format, print from
13216 @cindex Emacs shell, format, print from
13217 @cindex GNU Emacs shell, format, print from
13219 You can give formatting and printing commands from a shell within GNU
13220 Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
13221 shell, you can format and print the document. @xref{Hardcopy, , Format
13222 and Print Hardcopy}, for details.
13224 You can switch to and from the shell buffer while @code{tex} is
13225 running and do other editing. If you are formatting a long document
13226 on a slow machine, this can be very convenient.@refill
13228 You can also use @code{texi2dvi} from an Emacs shell. For example,
13229 here is how to use @code{texi2dvi} to format and print @cite{Using and
13230 Porting GNU CC} from a shell within Emacs:
13234 texi2dvi gcc.texinfo
13240 @xref{Texinfo Mode Printing}, for more information about formatting
13241 and printing in Texinfo mode.@refill
13245 @node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
13246 @section Formatting and Printing in Texinfo Mode
13247 @cindex Region printing in Texinfo mode
13248 @cindex Format and print in Texinfo mode
13249 @cindex Print and format in Texinfo mode
13251 Texinfo mode provides several predefined key commands for @TeX{}
13252 formatting and printing. These include commands for sorting indices,
13253 looking at the printer queue, killing the formatting job, and
13254 recentering the display of the buffer in which the operations
13259 @itemx M-x texinfo-tex-buffer
13260 Run @code{texi2dvi} on the current buffer.@refill
13263 @itemx M-x texinfo-tex-region
13264 Run @TeX{} on the current region.@refill
13267 @itemx M-x texinfo-texindex
13268 Sort the indices of a Texinfo file formatted with
13269 @code{texinfo-tex-region}.@refill
13272 @itemx M-x texinfo-tex-print
13273 Print a DVI file that was made with @code{texinfo-tex-region} or
13274 @code{texinfo-tex-buffer}.@refill
13277 @itemx M-x tex-show-print-queue
13278 Show the print queue.@refill
13281 @itemx M-x texinfo-delete-from-print-queue
13282 Delete a job from the print queue; you will be prompted for the job
13283 number shown by a preceding @kbd{C-c C-t C-q} command
13284 (@code{texinfo-show-tex-print-queue}).@refill
13287 @itemx M-x tex-kill-job
13288 Kill the currently running @TeX{} job started by either
13289 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
13290 process running in the Texinfo shell buffer.@refill
13293 @itemx M-x texinfo-quit-job
13294 Quit a @TeX{} formatting job that has stopped because of an error by
13295 sending an @key{x} to it. When you do this, @TeX{} preserves a record
13296 of what it did in a @file{.log} file.@refill
13299 @itemx M-x tex-recenter-output-buffer
13300 Redisplay the shell buffer in which the @TeX{} printing and formatting
13301 commands are run to show its most recent output.@refill
13305 Thus, the usual sequence of commands for formatting a buffer is as
13306 follows (with comments to the right):@refill
13310 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
13311 C-c C-t C-p @r{Print the DVI file.}
13312 C-c C-t C-q @r{Display the printer queue.}
13316 The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
13317 called the @file{*tex-shell*}. The @code{texinfo-tex-command},
13318 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
13319 commands are all run in this shell.
13321 You can watch the commands operate in the @samp{*tex-shell*} buffer,
13322 and you can switch to and from and use the @samp{*tex-shell*} buffer
13323 as you would any other shell buffer.@refill
13326 The formatting and print commands depend on the values of several variables.
13327 The default values are:@refill
13331 @r{Variable} @r{Default value}
13333 texinfo-texi2dvi-command "texi2dvi"
13334 texinfo-tex-command "tex"
13335 texinfo-texindex-command "texindex"
13336 texinfo-delete-from-print-queue-command "lprm"
13337 texinfo-tex-trailer "@@bye"
13338 tex-start-of-header "%**start"
13339 tex-end-of-header "%**end"
13340 tex-dvi-print-command "lpr -d"
13341 tex-show-queue-command "lpq"
13345 You can change the values of these variables with the @kbd{M-x
13346 edit-options} command (@pxref{Edit Options, , Editing Variable Values,
13347 emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
13348 (@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
13349 Emacs Manual}), or with your @file{.emacs} initialization file
13350 (@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
13352 @cindex Customize Emacs package (@t{Development/Docs/Texinfo})
13353 Beginning with version 20, GNU Emacs offers a user-friendly interface,
13354 called @dfn{Customize}, for changing values of user-definable variables.
13355 @xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
13356 Emacs Manual}, for more details about this. The Texinfo variables can
13357 be found in the @samp{Development/Docs/Texinfo} group, once you invoke
13358 the @kbd{M-x customize} command.
13361 @node Compile-Command
13362 @section Using the Local Variables List
13363 @cindex Local variables
13364 @cindex Compile command for formatting
13365 @cindex Format with the compile command
13367 Yet another way to apply the @TeX{} formatting command to a Texinfo file
13368 is to put that command in a @dfn{local variables list} at the end of the
13369 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
13370 commands as a @code{compile-command} and have Emacs run it by typing
13371 @kbd{M-x compile}. This creates a special shell called the
13372 @file{*compilation*} buffer in which Emacs runs the compile command.
13373 For example, at the end of the @file{gdb.texinfo} file, after the
13374 @code{@@bye}, you could put the following:@refill
13379 compile-command: "texi2dvi gdb.texinfo"
13385 This technique is most often used by programmers who also compile programs
13386 this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
13389 @node Requirements Summary
13390 @section @TeX{} Formatting Requirements Summary
13391 @cindex Requirements for formatting
13392 @cindex Minimal requirements for formatting
13393 @cindex Formatting requirements
13395 Every Texinfo file that is to be input to @TeX{} must begin with a
13396 @code{\input} command and must contain an @code{@@setfilename} command:
13400 @@setfilename @var{arg-not-used-by-@TeX{}}
13404 The first command instructs @TeX{} to load the macros it needs to
13405 process a Texinfo file and the second command opens auxiliary files.
13407 Every Texinfo file must end with a line that terminates @TeX{}'s
13408 processing and forces out unfinished pages:
13414 Strictly speaking, these lines are all a Texinfo file needs to be
13415 processed successfully by @TeX{}.
13417 Usually, however, the beginning includes an @code{@@settitle} command to
13418 define the title of the printed manual, an @code{@@setchapternewpage}
13419 command, a title page, a copyright page, and permissions. Besides an
13420 @code{@@bye}, the end of a file usually includes indices and a table of
13421 contents. (And of course most manuals contain a body of text as well.)
13423 For more information, see:
13425 @item @ref{settitle, , @code{@@settitle}}
13426 @item @ref{setchapternewpage, , @code{@@setchapternewpage}}
13427 @item @ref{Headings, ,Page Headings}
13428 @item @ref{Titlepage & Copyright Page}
13429 @item @ref{Printing Indices & Menus}
13430 @item @ref{Contents}
13434 @node Preparing for TeX
13435 @section Preparing for @TeX{}
13436 @cindex Preparing for @TeX{}
13437 @cindex @TeX{} input initialization
13438 @cindex @code{TEXINPUTS} environment variable
13440 @cindex @b{.profile} initialization file
13441 @cindex @b{.cshrc} initialization file
13442 @cindex Initialization file for @TeX{} input
13444 @TeX{} needs to know where to find the @file{texinfo.tex} file that the
13445 @samp{\input texinfo} command on the first line reads. The
13446 @file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
13447 included in all standard GNU distributions.
13449 @pindex texinfo.tex@r{, installing}
13451 Usually, the installer has put the @file{texinfo.tex} file in the
13452 default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
13453 other GNU software is installed. In this case, @TeX{} will find the
13454 file and you do not need to do anything special. If this has not been
13455 done, you can put @file{texinfo.tex} in the current directory when you
13456 run @TeX{}, and @TeX{} will find it there.
13458 @pindex epsf.tex@r{, installing}
13459 Also, you should install @file{epsf.tex}, if it is not already installed
13460 from another distribution. More details are at the end of the description
13461 of the @code{@@image} command (@pxref{Images}).
13463 @pindex pdfcolor.tex@r{, installing}
13464 Likewise for @file{pdfcolor.tex}, if it is not already installed and you
13467 @pindex texinfo.cnf @r{installation}
13468 @cindex Customizing of @TeX{} for Texinfo
13469 @cindex Site-wide Texinfo configuration file
13470 Optionally, you may create an additional @file{texinfo.cnf}, and install
13471 it as well. This file is read by @TeX{} when the @code{@@setfilename}
13472 command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any
13473 commands you like there, according to local site-wide conventions. They
13474 will be read by @TeX{} when processing any Texinfo document. For
13475 example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
13476 (@pxref{A4 Paper}), then all Texinfo documents will be processed with
13477 that page size in effect. If you have nothing to put in
13478 @file{texinfo.cnf}, you do not need to create it.
13481 If neither of the above locations for these system files suffice for
13482 you, you can specify the directories explicitly. For
13483 @file{texinfo.tex}, you can do this by writing the complete path for the
13484 file after the @code{\input} command. Another way, that works for both
13485 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
13486 might read), is to set the @code{TEXINPUTS} environment variable in your
13487 @file{.cshrc} or @file{.profile} file.
13489 Which you use of @file{.cshrc} or @file{.profile} depends on
13490 whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
13491 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
13492 command interpreter. The latter read the @file{.cshrc} file for
13493 initialization information, and the former read @file{.profile}.
13495 In a @file{.cshrc} file, you could use the following @code{csh} command
13499 setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
13503 In a @file{.profile} file, you could use the following @code{sh} command
13508 TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
13513 On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
13514 of the @samp{;} character, instead of @samp{:}, as directory separator
13515 on these systems.}:
13519 set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
13524 It is customary for DOS/Windows users to put such commands in the
13525 @file{autoexec.bat} file, or in the Windows Registry.@refill
13528 These settings would cause @TeX{} to look for @file{\input} file first
13529 in the current directory, indicated by the @samp{.}, then in a
13530 hypothetical user's @file{me/mylib} directory, and finally in a system
13531 directory @file{/usr/lib/tex/macros}.
13533 @cindex Dumping a .fmt file
13534 @cindex Format file, dumping
13535 Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
13536 web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
13537 disadvantage is that then updating @file{texinfo.tex} requires
13538 redumping.) You can do this by running this command, assuming
13539 @file{epsf.tex} is findable by @TeX{}:
13542 initex texinfo @@dump
13545 (@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
13546 wherever your @code{.fmt} files are found; typically, this will be in the
13547 subdirectory @file{web2c} of your @TeX{} installation.
13550 @node Overfull hboxes
13551 @section Overfull ``hboxes''
13552 @cindex Overfull @samp{hboxes}
13553 @cindex @samp{hboxes}, overfull
13554 @cindex Final output
13556 @TeX{} is sometimes unable to typeset a line without extending it into
13557 the right margin. This can occur when @TeX{} comes upon what it
13558 interprets as a long word that it cannot hyphenate, such as an
13559 electronic mail network address or a very long title. When this
13560 happens, @TeX{} prints an error message like this:
13563 Overfull @@hbox (20.76302pt too wide)
13568 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
13569 @samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
13571 @TeX{} also provides the line number in the Texinfo source file and
13572 the text of the offending line, which is marked at all the places that
13573 @TeX{} considered hyphenation.
13574 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
13575 for more information about typesetting errors.
13577 If the Texinfo file has an overfull hbox, you can rewrite the sentence
13578 so the overfull hbox does not occur, or you can decide to leave it. A
13579 small excursion into the right margin often does not matter and may not
13580 even be noticeable.
13582 If you have many overfull boxes and/or an antipathy to rewriting, you
13583 can coerce @TeX{} into greatly increasing the allowable interword
13584 spacing, thus (if you're lucky) avoiding many of the bad line breaks,
13587 @findex \emergencystretch
13590 \global\emergencystretch = .9\hsize
13595 (You should adjust the fraction as needed.) This huge value for
13596 @code{\emergencystretch} cannot be the default, since then the typeset
13597 output would generally be of noticeably lower quality; the default
13598 is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
13599 containing the current line width.
13601 @cindex Black rectangle in hardcopy
13602 @cindex Rectangle, black in hardcopy
13603 @cindex Box, ugly black in hardcopy
13604 @cindex Ugly black rectangles in hardcopy
13605 For what overfull boxes you have, however, @TeX{} will print a large,
13606 ugly, black rectangle beside the line that contains the overfull hbox
13607 unless told otherwise. This is so you will notice the location of the
13608 problem if you are correcting a draft.
13611 To prevent such a monstrosity from marring your final printout, write
13612 the following in the beginning of the Texinfo file on a line of its own,
13613 before the @code{@@titlepage} command:
13621 @section Printing ``Small'' Books
13623 @cindex Small book size
13624 @cindex Book, printing small
13625 @cindex Page sizes for books
13626 @cindex Size of printed book
13628 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
13629 format. However, you can direct @TeX{} to typeset a document in a 7 by
13630 9.25 inch format that is suitable for bound books by inserting the
13631 following command on a line by itself at the beginning of the Texinfo
13632 file, before the title page:@refill
13639 (Since many books are about 7 by 9.25 inches, this command might better
13640 have been called the @code{@@regularbooksize} command, but it came to be
13641 called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
13643 If you write the @code{@@smallbook} command between the
13644 start-of-header and end-of-header lines, the Texinfo mode @TeX{}
13645 region formatting command, @code{texinfo-tex-region}, will format the
13646 region in ``small'' book size (@pxref{Start of Header}).@refill
13648 @xref{small}, for information about
13649 commands that make it easier to produce examples for a smaller manual.
13651 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13652 @TeX{}}, for other ways to format with @code{@@smallbook} that do not
13653 require changing the source file.
13657 @section Printing on A4 Paper
13658 @cindex A4 paper, printing on
13659 @cindex A5 paper, printing on
13660 @cindex Paper size, A4
13661 @cindex European A4 paper
13664 You can tell @TeX{} to format a document for printing on European size
13665 A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
13666 command. Write the command on a line by itself near the beginning of
13667 the Texinfo file, before the title page. For example, this is how you
13668 would write the header for this manual:
13672 \input texinfo @@c -*-texinfo-*-
13673 @@c %**start of header
13674 @@setfilename texinfo
13677 @@c %**end of header
13681 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13682 @TeX{}}, for other ways to format for different paper sizes that do not
13683 require changing the source file.
13687 You may or may not prefer the formatting that results from the command
13688 @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
13692 @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
13694 @cindex Custom page sizes
13695 @cindex Page sizes, customized
13696 @cindex Text width and height
13697 @cindex Width of text area
13698 @cindex Height of text area
13699 @cindex Depth of text area
13701 You can explicitly specify the height and (optionally) width of the main
13702 text area on the page with the @code{@@pagesizes} command. Write this
13703 on a line by itself near the beginning of the Texinfo file, before the
13704 title page. The height comes first, then the width if desired,
13705 separated by a comma. Examples:
13708 @@pagesizes 200mm,150mm @c for b5 paper
13712 @@pagesizes 11.5in @c for legal paper
13715 @cindex B5 paper, printing on
13716 @cindex Legal paper, printing on
13717 This would be reasonable for printing on B5-size paper. To emphasize,
13718 this command specifies the size of the @emph{text area}, not the size of
13719 the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
13720 8.5@dmn{in} for legal).
13722 @cindex Margins on page, not controllable
13723 To make more elaborate changes, such as changing any of the page
13724 margins, you must define a new command in @file{texinfo.tex} (or
13725 @file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
13727 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
13728 @TeX{}}, for other ways to specify @code{@@pagesizes} that do not
13729 require changing the source file.
13731 @code{@@pagesizes} is ignored by @code{makeinfo}.
13734 @node Cropmarks and Magnification
13735 @section Cropmarks and Magnification
13737 @cindex Cropmarks for printing
13738 @cindex Printing cropmarks
13739 You can (attempt to) direct @TeX{} to print cropmarks at the corners of
13740 pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
13741 command on a line by itself between @code{@@iftex} and @code{@@end
13742 iftex} lines near the beginning of the Texinfo file, before the title
13743 page, like this:@refill
13753 This command is mainly for printers that typeset several pages on one
13754 sheet of film; but you can attempt to use it to mark the corners of a
13755 book set to 7 by 9.25 inches with the @code{@@smallbook} command.
13756 (Printers will not produce cropmarks for regular sized output that is
13757 printed on regular sized paper.) Since different printing machines work
13758 in different ways, you should explore the use of this command with a
13759 spirit of adventure. You may have to redefine the command in
13760 @file{texinfo.tex}.
13762 @findex \mag @r{(raw @TeX{} magnification)}
13763 @cindex Magnified printing
13764 @cindex Larger or smaller pages
13765 You can attempt to direct @TeX{} to typeset pages larger or smaller than
13766 usual with the @code{\mag} @TeX{} command. Everything that is typeset
13767 is scaled proportionally larger or smaller. (@code{\mag} stands for
13768 ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
13769 plain @TeX{} command that is prefixed with a backslash. You have to
13770 write this command between @code{@@tex} and @code{@@end tex}
13771 (@pxref{Raw Formatter Commands}).
13773 Follow the @code{\mag} command with an @samp{=} and then a number that
13774 is 1000 times the magnification you desire. For example, to print pages
13775 at 1.2 normal size, write the following near the beginning of the
13776 Texinfo file, before the title page:
13786 With some printing technologies, you can print normal-sized copies that
13787 look better than usual by giving a larger-than-normal master to your
13788 print shop. They do the reduction, thus effectively increasing the
13791 Depending on your system, DVI files prepared with a
13792 nonstandard-@code{\mag} may not print or may print only with certain
13793 magnifications. Be prepared to experiment.
13797 @section PDF Output
13801 You can generate a PDF output file from Texinfo source by using the
13802 @command{pdftex} program to process your file instead of plain
13803 @command{tex}. Just run @samp{pdftex foo.texi} instead of @samp{tex
13804 foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
13806 @dfn{PDF} stands for `Portable Document Format'. It was invented by
13807 Adobe Systems some years ago for document interchange, based on their
13808 PostScript language. A @uref{http://www.foolabs.com/xpdf/, PDF reader}
13809 for the X window system is freely available, as is the
13810 @uref{http://partners.adobe.com/asn/developer/technotes/, definition of
13811 the file format}. Since PDF is a binary format, there are no
13812 @samp{@@ifpdf} or @samp{@@pdf} commands as with the other output
13815 Despite the `portable' in the name, PDF files are nowhere near as
13816 portable in practice as the plain ASCII formats (Info, HTML) that
13817 Texinfo supports (DVI portability is arguable). They also tend to be
13818 much larger and do not support the bitmap fonts used by @TeX{} (by
13819 default) very well. Nevertheless, a PDF file does preserve an actual
13820 printed document on a screen as faithfully as possible, so it has its place.
13822 PDF support in Texinfo is fairly rudimentary.
13825 @node Creating and Installing Info Files
13826 @chapter Creating and Installing Info Files
13828 This chapter describes how to create and install Info files. @xref{Info
13829 Files}, for general information about the file format itself.
13832 * Creating an Info File::
13833 * Installing an Info File::
13837 @node Creating an Info File
13838 @section Creating an Info File
13839 @cindex Creating an Info file
13840 @cindex Info, creating an online file
13841 @cindex Formatting a file for Info
13843 @code{makeinfo} is a program that converts a Texinfo file into an Info
13844 file, HTML file, or plain text. @code{texinfo-format-region} and
13845 @code{texinfo-format-buffer} are GNU Emacs functions that convert
13848 For information on installing the Info file in the Info system,
13849 @pxref{Installing an Info File}.
13852 * makeinfo advantages:: @code{makeinfo} provides better error checking.
13853 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
13854 * makeinfo options:: Specify fill-column and other options.
13855 * Pointer Validation:: How to check that pointers point somewhere.
13856 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
13857 * texinfo-format commands:: Two Info formatting commands written
13858 in Emacs Lisp are an alternative
13859 to @code{makeinfo}.
13860 * Batch Formatting:: How to format for Info in Emacs Batch mode.
13861 * Tag and Split Files:: How tagged and split files help Info
13863 * makeinfo html:: Generating HTML output.
13867 @node makeinfo advantages
13868 @subsection @code{makeinfo} Preferred
13870 The @code{makeinfo} utility creates an Info file from a Texinfo source
13871 file more quickly than either of the Emacs formatting commands and
13872 provides better error messages. We recommend it. @code{makeinfo} is a
13873 C program that is independent of Emacs. You do not need to run Emacs to
13874 use @code{makeinfo}, which means you can use @code{makeinfo} on machines
13875 that are too small to run Emacs. You can run @code{makeinfo} in any one
13876 of three ways: from an operating system shell, from a shell inside
13877 Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
13878 command in Texinfo mode in Emacs.
13881 The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
13882 commands are useful if you cannot run @code{makeinfo}. Also, in some
13883 circumstances, they format short regions or buffers more quickly than
13884 @code{makeinfo}.@refill
13886 @node Invoking makeinfo
13887 @subsection Running @code{makeinfo} from a Shell
13889 To create an Info file from a Texinfo file, type @code{makeinfo}
13890 followed by the name of the Texinfo file. Thus, to create the Info
13891 file for Bison, type the following to the shell:
13894 makeinfo bison.texinfo
13897 (You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
13900 Sometimes you will want to specify options. For example, if you wish
13901 to discover which version of @code{makeinfo} you are using,
13908 @xref{makeinfo options}, for more information.
13912 @node makeinfo options
13913 @subsection Options for @code{makeinfo}
13914 @cindex @code{makeinfo} options
13915 @cindex Options for @code{makeinfo}
13917 The @code{makeinfo} command takes a number of options. Most often,
13918 options are used to set the value of the fill column and specify the
13919 footnote style. Each command line option is a word preceded by
13920 @samp{--} or a letter preceded by @samp{-}. You can use abbreviations
13921 for the long option names as long as they are unique.@refill
13923 For example, you could use the following shell command to create an Info
13924 file for @file{bison.texinfo} in which each line is filled to only 68
13928 makeinfo --fill-column=68 bison.texinfo
13931 You can write two or more options in sequence, like this:@refill
13934 makeinfo --no-split --fill-column=70 @dots{}
13938 This would keep the Info file together as one possibly very long
13939 file and would also set the fill column to 70.@refill
13946 @opindex -D @var{var}
13947 Cause the variable @var{var} to be defined. This is equivalent to
13948 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
13950 @item --commands-in-node-names
13951 @opindex --commands-in-node-names
13952 Allow @code{@@}-commands in node names. This is not recommended, as it
13953 can probably never be implemented in @TeX{}. It also makes
13954 @code{makeinfo} much slower. Also, this option is ignored when
13955 @samp{--no-validate} is used. @xref{Pointer Validation}, for more
13960 Generate DocBook output rather than Info.
13962 @item --error-limit=@var{limit}
13963 @itemx -e @var{limit}
13964 @opindex --error-limit=@var{limit}
13965 @opindex -e @var{limit}
13966 Set the maximum number of errors that @code{makeinfo} will report
13967 before exiting (on the assumption that continuing would be useless);
13970 @item --fill-column=@var{width}
13971 @itemx -f @var{width}
13972 @opindex --fill-column=@var{width}
13973 @opindex -f @var{width}
13974 Specify the maximum number of columns in a line; this is the right-hand
13975 edge of a line. Paragraphs that are filled will be filled to this
13976 width. (Filling is the process of breaking up and connecting lines so
13977 that lines are the same length as or shorter than the number specified
13978 as the fill column. Lines are broken between words.) The default value
13979 is 72. Ignored with @samp{--html}.
13981 @item --footnote-style=@var{style}
13982 @itemx -s @var{style}
13983 @opindex --footnote-style=@var{style}
13984 @opindex -s @var{style}
13985 Set the footnote style to @var{style}, either @samp{end} for the end
13986 node style (the default) or @samp{separate} for the separate node style.
13987 The value set by this option overrides the value set in a Texinfo file
13988 by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
13989 footnote style is @samp{separate}, @code{makeinfo} makes a new node
13990 containing the footnotes found in the current node. When the footnote
13991 style is @samp{end}, @code{makeinfo} places the footnote references at
13992 the end of the current node. Ignored with @samp{--html}.
13998 Ordinarily, if the input file has errors, the output files are not
13999 created. With this option, they are preserved.
14005 Print a usage message listing all available options, then exit successfully.
14009 Generate HTML output rather than Info. @xref{makeinfo html}. By
14010 default, the HTML output is split into one output file per source node,
14011 and the split output is written into a subdirectory with the name of the
14012 top-level info file.
14015 @opindex -I @var{dir}
14016 Append @var{dir} to the directory search list for finding files that
14017 are included using the @code{@@include} command. By default,
14018 @code{makeinfo} searches only the current directory. If @var{dir} is
14019 not given, the current directory @file{.} is appended. Note that
14020 @var{dir} can actually be a list of several directories separated by the
14021 usual path separator character (@samp{:} on Unix, @samp{;} on
14022 MS-DOS/MS-Windows).
14024 @item --macro-expand=@var{file}
14025 @itemx -E @var{file}
14026 Output the Texinfo source with all the macros expanded to the named
14027 file. Normally, the results of macro expansion are used internally by
14028 @code{makeinfo} and then discarded. This option is used by
14029 @command{texi2dvi} if you are using an old version of @file{texinfo.tex}
14030 that does not support @code{@@macro}.
14033 @opindex --no-headers
14034 @cindex Plain text output
14035 @cindex ASCII text output
14036 @cindex Generating plain text files
14037 @cindex @file{INSTALL} file, generating
14038 @cindex Node separators, omitting
14039 @cindex Menus, omitting
14040 For Info output, do not include menus or node separator lines in the
14041 output. This results in a simple plain text file that you can (for
14042 example) send in email without complications, or include in a
14043 distribution (as in an @file{INSTALL} file).
14045 @cindex Navigation links, omitting
14046 For HTML output, likewise omit menus. And if @samp{--no-split} is also
14047 specified, do not include a navigation links at the top of each node
14048 (these are never included in the default case of split output).
14049 @xref{makeinfo html}.
14051 In both cases, write to standard output by default (can still be
14052 overridden by @option{-o}).
14055 @opindex --no-split
14056 @cindex Splitting of output files
14057 @cindex Output file splitting
14058 Suppress the splitting stage of @code{makeinfo}. By default, large
14059 output files (where the size is greater than 70k bytes) are split into
14060 smaller subfiles. For Info output, each one is approximately 50k bytes.
14061 For HTML output, each file contains one node (@pxref{makeinfo html}).
14063 @item --no-pointer-validate
14064 @itemx --no-validate
14065 @opindex --no-pointer-validate
14066 @opindex --no-validate
14067 @cindex Pointer validation, suppressing
14068 Suppress the pointer-validation phase of @code{makeinfo}. This can also
14069 be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
14070 @TeX{}}). Normally, after a Texinfo file is processed, some consistency
14071 checks are made to ensure that cross references can be resolved, etc.
14072 @xref{Pointer Validation}.
14076 Suppress warning messages (but @emph{not} error messages). You might
14077 want this if the file you are creating has examples of Texinfo cross
14078 references within it, and the nodes that are referenced do not actually
14081 @item --number-sections
14082 @opindex --number-sections
14083 Output chapter, section, and appendix numbers as in printed manuals.
14085 @item --no-number-footnotes
14086 @opindex --no-number-footnotes
14087 Suppress automatic footnote numbering. By default, @code{makeinfo}
14088 numbers each footnote sequentially in a single node, resetting the
14089 current footnote number to 1 at the start of each node.
14091 @item --output=@var{file}
14092 @itemx -o @var{file}
14093 @opindex --output=@var{file}
14094 @opindex -o @var{file}
14095 Specify that the output should be directed to @var{file} and not to the
14096 file name specified in the @code{@@setfilename} command found in the
14097 Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
14098 goes to standard output and @samp{--no-split} is implied. For split
14099 HTML output, @var{file} is the name for the directory into which all
14100 HTML nodes are written (@pxref{makeinfo html}).
14103 @opindex -P @var{dir}
14104 Prepend @var{dir} to the directory search list for @code{@@include}.
14105 If @var{dir} is not given, the current directory @file{.} is prepended.
14106 See @samp{-I} for more details.
14108 @item --paragraph-indent=@var{indent}
14109 @itemx -p @var{indent}
14110 @opindex --paragraph-indent=@var{indent}
14111 @opindex -p @var{indent}
14112 Set the paragraph indentation style to @var{indent}. The value set by
14113 this option overrides the value set in a Texinfo file by an
14114 @code{@@paragraphindent} command (@pxref{paragraphindent}). The value
14115 of @var{indent} is interpreted as follows:
14119 Preserve any existing indentation at the starts of paragraphs.
14121 @item @samp{0} or @samp{none}
14122 Delete any existing indentation.
14125 Indent each paragraph by @var{num} spaces.
14128 @item --reference-limit=@var{limit}
14129 @itemx -r @var{limit}
14130 @opindex --reference-limit=@var{limit}
14131 @opindex -r @var{limit}
14132 Set the value of the number of references to a node that
14133 @code{makeinfo} will make without reporting a warning. If a node has more
14134 than this number of references in it, @code{makeinfo} will make the
14135 references but also report a warning. The default is 1000.
14138 Cause @var{var} to be undefined. This is equivalent to
14139 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
14143 Cause @code{makeinfo} to display messages saying what it is doing.
14144 Normally, @code{makeinfo} only outputs messages if there are errors or
14151 Print the version number, then exit successfully.
14155 Generate XML output rather than Info.
14160 @node Pointer Validation
14161 @subsection Pointer Validation
14162 @cindex Pointer validation with @code{makeinfo}
14163 @cindex Validation of pointers
14165 If you do not suppress pointer validation with the @samp{--no-validate}
14166 option or the @code{@@novalidate} command in the source file (@pxref{Use
14167 TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
14168 Info file. Mostly, this means ensuring that nodes you have referenced
14169 really exist. Here is a complete list of what is checked:
14173 If a `Next', `Previous', or `Up' node reference is a reference to a
14174 node in the current file and is not an external reference such as to
14175 @file{(dir)}, then the referenced node must exist.@refill
14178 In every node, if the `Previous' node is different from the `Up' node,
14179 then the node pointed to by the `Previous' field must have a `Next'
14180 field which points back to this node.@refill
14183 Every node except the `Top' node must have an `Up' pointer.@refill
14186 The node referenced by an `Up' pointer must itself reference the current
14187 node through a menu item, unless the node referenced by `Up'
14188 has the form `(@var{file})'.
14191 If the `Next' reference of a node is not the same as the `Next' reference
14192 of the `Up' reference, then the node referenced by the `Next' pointer
14193 must have a `Previous' pointer that points back to the current node.
14194 This rule allows the last node in a section to point to the first node
14195 of the next chapter.@refill
14198 Every node except `Top' should be referenced by at least one other node,
14199 either via the `Previous' or `Next' links, or via a menu or a
14200 cross-reference.@refill
14203 @cindex @@-commands in @@node, limited support
14204 Some Texinfo documents might fail during the validation phase because
14205 they use commands like @code{@@value} and @code{@@definfoenclose} in
14206 node definitions and cross-references inconsistently. Consider the
14211 @@set nodename Node 1
14213 @@node @@value@{nodename@}, Node 2, Top, Top
14217 @@node Node 2, , Node 1, Top
14224 Here, the node ``Node 1'' was referenced both verbatim and through
14227 By default, @code{makeinfo} fails such cases, because node names are not
14228 fully expanded until they are written to the output file. You should
14229 always try to reference nodes consistently; e.g., in the above example,
14230 the second @code{@@node} line should have also used @code{@@value}.
14231 However, if, for some reason, you @emph{must} reference node names
14232 inconsistently, and @code{makeinfo} fails to validate the file, you can
14233 use the @samp{--commands-in-node-names} option to force @code{makeinfo}
14234 to perform the expensive expansion of all node names it finds in the
14235 document. This might considerably slow down the program, though;
14236 twofold increase in conversion time was measured for large documents
14237 such as the Jargon file.
14239 @cindex @@value in @@node lines
14240 The support for @code{@@}-commands in @code{@@node} directives is not
14241 general enough to be freely used. For example, if the example above
14242 redefined @code{nodename} somewhere in the document, @code{makeinfo}
14243 will fail to convert it, even if invoked with the
14244 @samp{--commands-in-node-names} option.
14246 @samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
14250 @node makeinfo in Emacs
14251 @subsection Running @code{makeinfo} inside Emacs
14252 @cindex Running @code{makeinfo} in Emacs
14253 @cindex @code{makeinfo} inside Emacs
14254 @cindex Shell, running @code{makeinfo} in
14256 You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
14257 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
14258 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
14259 C-m C-b} by default.@refill
14263 @itemx M-x makeinfo-region
14264 Format the current region for Info.@refill
14265 @findex makeinfo-region
14268 @itemx M-x makeinfo-buffer
14269 Format the current buffer for Info.@refill
14270 @findex makeinfo-buffer
14273 When you invoke either @code{makeinfo-region} or
14274 @code{makeinfo-buffer}, Emacs prompts for a file name, offering the
14275 name of the visited file as the default. You can edit the default
14276 file name in the minibuffer if you wish, before pressing @key{RET} to
14277 start the @code{makeinfo} process.@refill
14279 The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
14280 run the @code{makeinfo} program in a temporary shell buffer. If
14281 @code{makeinfo} finds any errors, Emacs displays the error messages in
14282 the temporary buffer.@refill
14284 @cindex Errors, parsing
14285 @cindex Parsing errors
14287 You can parse the error messages by typing @kbd{C-x `}
14288 (@code{next-error}). This causes Emacs to go to and position the
14289 cursor on the line in the Texinfo source that @code{makeinfo} thinks
14290 caused the error. @xref{Compilation, , Running @code{make} or
14291 Compilers Generally, emacs, The GNU Emacs Manual}, for more
14292 information about using the @code{next-error} command.@refill
14294 In addition, you can kill the shell in which the @code{makeinfo}
14295 command is running or make the shell buffer display its most recent
14300 @itemx M-x makeinfo-kill-job
14301 @findex makeinfo-kill-job
14302 Kill the current running @code{makeinfo} job
14303 (from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
14306 @itemx M-x makeinfo-recenter-output-buffer
14307 @findex makeinfo-recenter-output-buffer
14308 Redisplay the @code{makeinfo} shell buffer to display its most recent
14313 (Note that the parallel commands for killing and recentering a @TeX{}
14314 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
14317 You can specify options for @code{makeinfo} by setting the
14318 @code{makeinfo-options} variable with either the @kbd{M-x
14319 edit-options} or the @kbd{M-x set-variable} command, or by setting the
14320 variable in your @file{.emacs} initialization file.@refill
14322 For example, you could write the following in your @file{.emacs} file:@refill
14326 (setq makeinfo-options
14327 "--paragraph-indent=0 --no-split
14328 --fill-column=70 --verbose")
14332 @c If you write these three cross references using xref, you see
14333 @c three references to the same named manual, which looks strange.
14335 For more information, see @ref{makeinfo options, , Options for
14336 @code{makeinfo}}, as well as ``Editing Variable Values,'' ``Examining
14337 and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs
14342 For more information, see@*
14343 @ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
14344 @ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
14345 @ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
14346 @ref{makeinfo options, , Options for @code{makeinfo}}.
14349 @node texinfo-format commands
14350 @comment node-name, next, previous, up
14351 @subsection The @code{texinfo-format@dots{}} Commands
14352 @findex texinfo-format-region
14353 @findex texinfo-format-buffer
14355 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
14356 file with the @code{texinfo-format-region} command. This formats the
14357 current region and displays the formatted text in a temporary buffer
14358 called @samp{*Info Region*}.@refill
14360 Similarly, you can format a buffer with the
14361 @code{texinfo-format-buffer} command. This command creates a new
14362 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
14363 save the Info file under the name specified by the
14364 @code{@@setfilename} line which must be near the beginning of the
14365 Texinfo file.@refill
14369 @itemx @code{texinfo-format-region}
14370 Format the current region for Info.
14371 @findex texinfo-format-region
14374 @itemx @code{texinfo-format-buffer}
14375 Format the current buffer for Info.
14376 @findex texinfo-format-buffer
14379 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
14380 commands provide you with some error checking, and other functions can
14381 provide you with further help in finding formatting errors. These
14382 procedures are described in an appendix; see @ref{Catching Mistakes}.
14383 However, the @code{makeinfo} program is often faster and
14384 provides better error checking (@pxref{makeinfo in Emacs}).@refill
14386 @node Batch Formatting
14387 @comment node-name, next, previous, up
14388 @subsection Batch Formatting
14389 @cindex Batch formatting for Info
14390 @cindex Info batch formatting
14392 You can format Texinfo files for Info using @code{batch-texinfo-format}
14393 and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
14394 including a shell inside of Emacs. (@xref{Command Switches, , Command
14395 Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
14397 Here is a shell command to format all the files that end in
14398 @file{.texinfo} in the current directory:
14401 emacs -batch -funcall batch-texinfo-format *.texinfo
14405 Emacs processes all the files listed on the command line, even if an
14406 error occurs while attempting to format some of them.@refill
14408 Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
14409 it is not interactive. It kills the Batch mode Emacs on completion.@refill
14411 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
14412 and want to format several Texinfo files at once. When you use Batch
14413 mode, you create a new Emacs process. This frees your current Emacs, so
14414 you can continue working in it. (When you run
14415 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
14416 use that Emacs for anything else until the command finishes.)@refill
14418 @node Tag and Split Files
14419 @comment node-name, next, previous, up
14420 @subsection Tag Files and Split Files
14421 @cindex Making a tag table automatically
14422 @cindex Tag table, making automatically
14424 If a Texinfo file has more than 30,000 bytes,
14425 @code{texinfo-format-buffer} automatically creates a tag table
14426 for its Info file; @code{makeinfo} always creates a tag table. With
14427 a @dfn{tag table}, Info can jump to new nodes more quickly than it can
14430 @cindex Indirect subfiles
14431 In addition, if the Texinfo file contains more than about 70,000
14432 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
14433 large Info file into shorter @dfn{indirect} subfiles of about 50,000
14434 bytes each. Big files are split into smaller files so that Emacs does
14435 not need to make a large buffer to hold the whole of a large Info
14436 file; instead, Emacs allocates just enough memory for the small, split-off
14437 file that is needed at the time. This way, Emacs avoids wasting
14438 memory when you run Info. (Before splitting was implemented, Info
14439 files were always kept short and @dfn{include files} were designed as
14440 a way to create a single, large printed manual out of the smaller Info
14441 files. @xref{Include Files}, for more information. Include files are
14442 still used for very large documents, such as @cite{The Emacs Lisp
14443 Reference Manual}, in which each chapter is a separate file.)@refill
14445 When a file is split, Info itself makes use of a shortened version of
14446 the original file that contains just the tag table and references to
14447 the files that were split off. The split-off files are called
14448 @dfn{indirect} files.@refill
14450 The split-off files have names that are created by appending @w{@samp{-1}},
14451 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
14452 @code{@@setfilename} command. The shortened version of the original file
14453 continues to have the name specified by @code{@@setfilename}.@refill
14455 At one stage in writing this document, for example, the Info file was saved
14456 as the file @file{test-texinfo} and that file looked like this:@refill
14460 Info file: test-texinfo, -*-Text-*-
14461 produced by texinfo-format-buffer
14462 from file: new-texinfo-manual.texinfo
14466 test-texinfo-1: 102
14467 test-texinfo-2: 50422
14470 test-texinfo-3: 101300
14474 Node: overview^?104
14475 Node: info file^?1271
14478 Node: printed manual^?4853
14479 Node: conventions^?6855
14485 (But @file{test-texinfo} had far more nodes than are shown here.) Each of
14486 the split-off, indirect files, @file{test-texinfo-1},
14487 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
14488 after the line that says @samp{Indirect:}. The tag table is listed after
14489 the line that says @samp{Tag table:}. @refill
14491 In the list of indirect files, the number following the file name
14492 records the cumulative number of bytes in the preceding indirect files,
14493 not counting the file list itself, the tag table, or the permissions
14494 text in each file. In the tag table, the number following the node name
14495 records the location of the beginning of the node, in bytes from the
14496 beginning of the (unsplit) output.
14498 If you are using @code{texinfo-format-buffer} to create Info files,
14499 you may want to run the @code{Info-validate} command. (The
14500 @code{makeinfo} command does such a good job on its own, you do not
14501 need @code{Info-validate}.) However, you cannot run the @kbd{M-x
14502 Info-validate} node-checking command on indirect files. For
14503 information on how to prevent files from being split and how to
14504 validate the structure of the nodes, see @ref{Using
14505 Info-validate}.@refill
14508 @node makeinfo html
14509 @subsection Generating HTML
14512 Besides generating output in the Info format, you can use the
14513 @samp{--html} option to generate output in HTML format, for installation
14514 on a web site (for example). By default, the HTML output is split at
14517 When splitting, the HTML output files are written into a subdirectory.
14518 The subdirectory is named according to the name from
14519 @code{@@setfilename} with any extension removed; for example, HTML
14520 output for @code{@@setfilename emacs.info} would be written into a
14521 subdirectory named @samp{emacs}. If that directory cannot be created
14522 for any reason, then @samp{.html} is appended to the directory name, as
14523 in @samp{emacs.html} (this is necessary because sometimes the info file
14524 is named without an extension, e.g., @samp{texinfo}). If the
14525 @samp{@var{name}.html} directory can't be created either,
14526 @code{makeinfo} gives up. In any case, the top-level output file within
14527 the directory is always named @samp{index.html}.
14529 Monolithic output (@code{--no-split}) is named according to
14530 @code{@@setfilename} or @code{--outfile}. Cross-document node
14531 references are not supported in monolithic HTML.
14533 Texinfo input marked up with the @code{@@ifhtml} command will produce
14534 output only with the @samp{--html} option supplied. Input marked up
14535 with the @code{@@html} is passed literally to the output (suppressing
14536 the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
14537 which have special significance in HTML).
14539 The @samp{--footnote-style} option is currently ignored for HTML output;
14540 footnotes are linked to the end of the output file.
14542 The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866). The
14543 exception is that HTML 3.2 tables are generated from the
14544 @code{@@multitable} command, but tagged to degrade as well as possible
14545 in browsers without table support. The HTML 4 @samp{lang} attribute on
14546 the @samp{<html>} attribute is also used. Please report output from an
14547 error-free run of @code{makeinfo} which has browser portability problems
14550 Navigation bars are inserted at the start of nodes, similarly to Info
14551 output. The @samp{--no-headers} option will suppress this if used with
14552 @samp{--no-split}. Header @code{<link>} elements in split output can
14553 support info-like navigation with browsers like Lynx and @w{Emacs W3}
14554 which implement this @w{HTML 1.0} feature. @samp{@@xref} commands to
14555 other documents are generated assuming the other document is available
14556 in split HTML form, and installed in the same HTML documentation tree,
14557 at @file{../<info-document>/}.
14560 @node Installing an Info File
14561 @section Installing an Info File
14562 @cindex Installing an Info file
14563 @cindex Info file installation
14564 @cindex @file{dir} directory for Info installation
14566 Info files are usually kept in the @file{info} directory. You can read
14567 Info files using the standalone Info program or the Info reader built
14568 into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
14571 * Directory File:: The top level menu for all Info files.
14572 * New Info File:: Listing a new Info file.
14573 * Other Info Directories:: How to specify Info files that are
14574 located in other directories.
14575 * Installing Dir Entries:: How to specify what menu entry to add
14576 to the Info directory.
14577 * Invoking install-info:: @code{install-info} options.
14581 @node Directory File
14582 @subsection The Directory File @file{dir}
14584 For Info to work, the @file{info} directory must contain a file that
14585 serves as a top level directory for the Info system. By convention,
14586 this file is called @file{dir}. (You can find the location of this file
14587 within Emacs by typing @kbd{C-h i} to enter Info and then typing
14588 @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
14590 The @file{dir} file is itself an Info file. It contains the top level
14591 menu for all the Info files in the system. The menu looks like
14597 * Info: (info). Documentation browsing system.
14598 * Emacs: (emacs). The extensible, self-documenting
14600 * Texinfo: (texinfo). With one source file, make
14601 either a printed manual using
14602 @@TeX@{@} or an Info file.
14607 Each of these menu entries points to the `Top' node of the Info file
14608 that is named in parentheses. (The menu entry does not need to
14609 specify the `Top' node, since Info goes to the `Top' node if no node
14610 name is mentioned. @xref{Other Info Files, , Nodes in Other Info
14613 Thus, the @samp{Info} entry points to the `Top' node of the
14614 @file{info} file and the @samp{Emacs} entry points to the `Top' node
14615 of the @file{emacs} file.@refill
14617 In each of the Info files, the `Up' pointer of the `Top' node refers
14618 back to the @code{dir} file. For example, the line for the `Top'
14619 node of the Emacs manual looks like this in Info:@refill
14622 File: emacs Node: Top, Up: (DIR), Next: Distrib
14626 In this case, the @file{dir} file name is written in upper case
14627 letters---it can be written in either upper or lower case. This is not
14628 true in general, it is a special case for @file{dir}.
14631 @node New Info File
14632 @subsection Listing a New Info File
14633 @cindex Adding a new Info file
14634 @cindex Listing a new Info file
14635 @cindex New Info file, listing it in @file{dir} file
14636 @cindex Info file, listing a new
14637 @cindex @file{dir} file listing
14639 To add a new Info file to your system, you must write a menu entry to
14640 add to the menu in the @file{dir} file in the @file{info} directory.
14641 For example, if you were adding documentation for GDB, you would write
14642 the following new entry:@refill
14645 * GDB: (gdb). The source-level C debugger.
14649 The first part of the menu entry is the menu entry name, followed by a
14650 colon. The second part is the name of the Info file, in parentheses,
14651 followed by a period. The third part is the description.
14653 The name of an Info file often has a @file{.info} extension. Thus, the
14654 Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
14655 The Info reader programs automatically try the file name both with and
14656 without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
14657 try the @file{.inf} extension as well.}; so it is better to avoid
14658 clutter and not to write @samp{.info} explicitly in the menu entry. For
14659 example, the GDB menu entry should use just @samp{gdb} for the file
14660 name, not @samp{gdb.info}.
14663 @node Other Info Directories
14664 @subsection Info Files in Other Directories
14665 @cindex Installing Info in another directory
14666 @cindex Info installed in another directory
14667 @cindex Another Info directory
14668 @cindex @file{dir} files and Info directories
14670 If an Info file is not in the @file{info} directory, there are three
14671 ways to specify its location:@refill
14675 Write the pathname in the @file{dir} file as the second part of the menu.
14678 If you are using Emacs, list the name of the file in a second @file{dir}
14679 file, in its directory; and then add the name of that directory to the
14680 @code{Info-directory-list} variable in your personal or site
14681 initialization file.
14683 This variable tells Emacs where to look for @file{dir} files (the files
14684 must be named @file{dir}). Emacs merges the files named @file{dir} from
14685 each of the listed directories. (In Emacs version 18, you can set the
14686 @code{Info-directory} variable to the name of only one
14690 Specify the Info directory name in the @code{INFOPATH} environment
14691 variable in your @file{.profile} or @file{.cshrc} initialization file.
14692 (Only you and others who set this environment variable will be able to
14693 find Info files whose location is specified this way.)
14696 For example, to reach a test file in the @file{/home/bob/info}
14697 directory, you could add an entry like this to the menu in the
14698 standard @file{dir} file:@refill
14701 * Test: (/home/bob/info/info-test). Bob's own test file.
14705 In this case, the absolute file name of the @file{info-test} file is
14706 written as the second part of the menu entry.@refill
14708 Alternatively, you could write the following in your @file{.emacs} file:
14710 @vindex Info-directory-list
14714 (setq Info-directory-list
14715 (cons (expand-file-name "/home/bob/info")
14716 Info-directory-list))
14720 This tells Emacs to merge the system @file{dir} file with the @file{dir}
14721 file in @file{/home/bob/info}. Thus, Info will list the
14722 @file{/home/bob/info/info-test} file as a menu entry in the
14723 @file{/home/bob/info/dir} file. Emacs does the merging only when
14724 @kbd{M-x info} is first run, so if you want to set
14725 @code{Info-directory-list} in an Emacs session where you've already run
14726 @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
14727 to recompose the @file{dir} file.
14730 Finally, you can tell Info where to look by setting the @code{INFOPATH}
14731 environment variable in your shell startup file, such as @file{.cshrc},
14732 @file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible
14733 shell such as @code{sh} or @code{bash} for your shell command
14734 interpreter, you set the @code{INFOPATH} environment variable in the
14735 @file{.profile} initialization file; but if you use @code{csh} or
14736 @code{tcsh}, you set the variable in the @file{.cshrc} initialization
14737 file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
14738 your @file{autoexec.bat} file or in the Registry. Each type of shell
14739 uses a different syntax.
14743 In a @file{.cshrc} file, you could set the @code{INFOPATH}
14744 variable as follows:@refill
14747 setenv INFOPATH .:~/info:/usr/local/emacs/info
14751 In a @file{.profile} file, you would achieve the same effect by
14755 INFOPATH=.:$HOME/info:/usr/local/emacs/info
14760 @pindex autoexec.bat
14761 In a @file{autoexec.bat} file, you write this command@footnote{Note the
14762 use of @samp{;} as the directory separator, and a different syntax for
14763 using values of other environment variables.}:
14766 set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
14771 The @samp{.} indicates the current directory as usual. Emacs uses the
14772 @code{INFOPATH} environment variable to initialize the value of Emacs's
14773 own @code{Info-directory-list} variable. The stand-alone Info reader
14774 merges any files named @file{dir} in any directory listed in the
14775 @env{INFOPATH} variable into a single menu presented to you in the node
14776 called @samp{(dir)Top}.
14778 @cindex colon, last in @env{INFOPATH}
14779 However you set @env{INFOPATH}, if its last character is a
14780 colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
14781 is replaced by the default (compiled-in) path. This gives you a way to
14782 augment the default path with new directories without having to list all
14783 the standard places. For example (using @code{sh} syntax):
14786 INFOPATH=/local/info:
14791 will search @file{/local/info} first, then the standard directories.
14792 Leading or doubled colons are not treated specially.
14794 @cindex @file{dir} file, creating your own
14795 When you create your own @file{dir} file for use with
14796 @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
14797 copying an existing @file{dir} file and replace all the text after the
14798 @samp{* Menu:} with your desired entries. That way, the punctuation and
14799 special CTRL-_ characters that Info needs will be present.
14802 @node Installing Dir Entries
14803 @subsection Installing Info Directory Files
14805 When you install an Info file onto your system, you can use the program
14806 @code{install-info} to update the Info directory file @file{dir}.
14807 Normally the makefile for the package runs @code{install-info}, just
14808 after copying the Info file into its proper installed location.
14810 @findex dircategory
14812 In order for the Info file to work with @code{install-info}, you include
14813 the commands @code{@@dircategory} and
14814 @code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
14815 file. Use @code{@@direntry} to specify the menu entries to add to the
14816 Info directory file, and use @code{@@dircategory} to specify which part
14817 of the Info directory to put it in. Here is how these commands are used
14821 @@dircategory Texinfo documentation system
14823 * Texinfo: (texinfo). The GNU documentation format.
14824 * install-info: (texinfo)Invoking install-info. @dots{}
14829 Here's what this produces in the Info file:
14832 INFO-DIR-SECTION Texinfo documentation system
14833 START-INFO-DIR-ENTRY
14834 * Texinfo: (texinfo). The GNU documentation format.
14835 * install-info: (texinfo)Invoking install-info. @dots{}
14841 The @code{install-info} program sees these lines in the Info file, and
14842 that is how it knows what to do.
14844 Always use the @code{@@direntry} and @code{@@dircategory} commands near
14845 the beginning of the Texinfo input, before the first @code{@@node}
14846 command. If you use them later on in the input, @code{install-info}
14847 will not notice them.
14849 If you use @code{@@dircategory} more than once in the Texinfo source,
14850 each usage specifies the `current' category; any subsequent
14851 @code{@@direntry} commands will add to that category.
14853 Here are some recommended @code{@@dircategory} categories:
14857 GNU programming tools
14858 GNU programming documentation
14862 Individual utilities
14865 The idea is to include the `Invoking' node for every program installed
14866 by a package under `Individual utilities', and an entry for the manual
14867 as a whole in the appropriate other category.
14870 @node Invoking install-info
14871 @subsection Invoking install-info
14873 @pindex install-info
14875 @code{install-info} inserts menu entries from an Info file into the
14876 top-level @file{dir} file in the Info system (see the previous sections
14877 for an explanation of how the @file{dir} file works). It's most often
14878 run as part of software installation, or when constructing a @file{dir} file
14879 for all manuals on a system. Synopsis:
14882 install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
14885 If @var{info-file} or @var{dir-file} are not specified, the options
14886 (described below) that define them must be. There are no compile-time
14887 defaults, and standard input is never used. @code{install-info} can
14888 read only one Info file and write only one @file{dir} file per invocation.
14890 @cindex @file{dir}, created by @code{install-info}
14891 If @var{dir-file} (however specified) does not exist,
14892 @code{install-info} creates it if possible (with no entries).
14894 @cindex Compressed files, reading
14895 @cindex Dir files, compressed
14896 If any input file is compressed with @code{gzip} (@pxref{Invoking
14897 gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
14898 for reading. And if @var{dir-file} is compressed, @code{install-info}
14899 also automatically leaves it compressed after writing any changes.
14900 If @var{dir-file} itself does not exist, @code{install-info} tries to
14901 open @file{@var{dir-file}.gz}.
14908 Delete the entries in @var{info-file} from @var{dir-file}. The file
14909 name in the entry in @var{dir-file} must be @var{info-file} (except for
14910 an optional @samp{.info} in either one). Don't insert any new entries.
14912 @item --dir-file=@var{name}
14913 @itemx -d @var{name}
14914 @opindex --dir-file=@var{name}
14915 @opindex -d @var{name}
14916 Specify file name of the Info directory file. This is equivalent to
14917 using the @var{dir-file} argument.
14919 @item --entry=@var{text}
14920 @itemx -e @var{text}
14921 @opindex --entry=@var{text}
14922 @opindex -e @var{text}
14923 Insert @var{text} as an Info directory entry; @var{text} should have the
14924 form of an Info menu item line plus zero or more extra lines starting
14925 with whitespace. If you specify more than one entry, they are all
14926 added. If you don't specify any entries, they are determined from
14927 information in the Info file itself.
14933 Display a usage message listing basic usage and all available options,
14934 then exit successfully.
14936 @item --info-file=@var{file}
14937 @itemx -i @var{file}
14938 @opindex --info-file=@var{file}
14939 @opindex -i @var{file}
14940 Specify Info file to install in the directory.
14941 Equivalent to using the @var{info-file} argument.
14943 @item --info-dir=@var{dir}
14944 @itemx -D @var{dir}
14945 @opindex --info-dir=@var{dir}
14946 @opindex -D @var{dir}
14947 Specify the directory where @file{dir} resides.
14948 Equivalent to @samp{--dir-file=@var{dir}/dir}.
14950 @item --item=@var{text}
14951 @opindex --item=@var{text}
14952 Same as @samp{--entry=@var{text}}. An Info directory entry is actually
14963 Same as @samp{--delete}.
14965 @item --section=@var{sec}
14966 @itemx -s @var{sec}
14967 @opindex --section=@var{sec}
14968 @opindex -s @var{sec}
14969 Put this file's entries in section @var{sec} of the directory. If you
14970 specify more than one section, all the entries are added in each of the
14971 sections. If you don't specify any sections, they are determined from
14972 information in the Info file itself.
14978 @cindex version number, finding
14979 Display version information and exit successfully.
14985 @appendix @@-Command List
14986 @cindex Alphabetical @@-command list
14987 @cindex List of @@-commands
14988 @cindex @@-command list
14989 @cindex Reference to @@-commands
14991 Here is an alphabetical list of the @@-commands in Texinfo. Square
14992 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
14993 @samp{@dots{}}, indicates repeated text.
14997 @item @@@var{whitespace}
14998 An @code{@@} followed by a space, tab, or newline produces a normal,
14999 stretchable, interword space. @xref{Multiple Spaces}.
15002 Generate an exclamation point that really does end a sentence (usually
15003 after an end-of-sentence capital letter). @xref{Ending a Sentence}.
15007 Generate an umlaut or acute accent, respectively, over the next
15008 character, as in @"o and @'o. @xref{Inserting Accents}.
15011 Force a line break. Do not end a paragraph that uses @code{@@*} with
15012 an @code{@@refill} command. @xref{Line Breaks}.
15014 @item @@,@{@var{c}@}
15015 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
15019 Insert a discretionary hyphenation point. @xref{- and hyphenation}.
15022 Produce a period that really does end a sentence (usually after an
15023 end-of-sentence capital letter). @xref{Ending a Sentence}.
15026 Indicate to @TeX{} that an immediately preceding period, question
15027 mark, exclamation mark, or colon does not end a sentence. Prevent
15028 @TeX{} from inserting extra whitespace as it does at the end of a
15029 sentence. The command has no effect on the Info file output.
15030 @xref{Not Ending a Sentence}.
15033 Generate a macron (bar) accent over the next character, as in @=o.
15034 @xref{Inserting Accents}.
15037 Generate a question mark that really does end a sentence (usually after
15038 an end-of-sentence capital letter). @xref{Ending a Sentence}.
15041 Stands for an at sign, @samp{@@}.
15042 @xref{Braces Atsigns, , Inserting @@ and braces}.
15045 Stands for a backslash (@samp{\}) inside @code{@@math}.
15046 @xref{math,,@code{math}}.
15050 Generate a circumflex (hat) or grave accent, respectively, over the next
15051 character, as in @^o and @`e.
15052 @xref{Inserting Accents}.
15055 Stands for a left brace, @samp{@{}.
15056 @xref{Braces Atsigns, , Inserting @@ and braces}.
15059 Stands for a right-hand brace, @samp{@}}.@*
15060 @xref{Braces Atsigns, , Inserting @@ and braces}.
15063 Generate a tilde accent over the next character, as in @~N.
15064 @xref{Inserting Accents}.
15068 Generate the uppercase and lowercase Scandinavian A-ring letters,
15069 respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
15071 @item @@acronym@{@var{abbrev}@}
15072 Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
15073 capital letters, such as `NASA'. @xref{acronym,, @code{acronym}}.
15077 Generate the uppercase and lowercase AE ligatures, respectively:
15078 @AE{}, @ae{}. @xref{Inserting Accents}.
15080 @itemx @@afivepaper
15081 Change page dimensions for the A5 paper size. @xref{A4 Paper}.
15084 @itemx @@afourpaper
15086 Change page dimensions for the A4 paper size. @xref{A4 Paper}.
15088 @item @@alias @var{new}=@var{existing}
15089 Make the command @samp{@@@var{new}} an alias for the existing command
15090 @samp{@@@var{existing}}. @xref{alias}.
15092 @item @@anchor@{@var{name}@}
15093 Define @var{name} as the current location for use as a cross-reference
15094 target. @xref{anchor,, @code{@@anchor}}.
15096 @item @@appendix @var{title}
15097 Begin an appendix. The title appears in the table
15098 of contents of a printed manual. In Info, the title is
15099 underlined with asterisks. @xref{unnumbered & appendix, , The
15100 @code{@@unnumbered} and @code{@@appendix} Commands}.@refill
15102 @item @@appendixsec @var{title}
15103 @itemx @@appendixsection @var{title}
15104 Begin an appendix section within an appendix. The section title appears
15105 in the table of contents of a printed manual. In Info, the title is
15106 underlined with equal signs. @code{@@appendixsection} is a longer
15107 spelling of the @code{@@appendixsec} command. @xref{unnumberedsec
15108 appendixsec heading, , Section Commands}.@refill
15110 @item @@appendixsubsec @var{title}
15111 Begin an appendix subsection within an appendix. The title appears
15112 in the table of contents of a printed manual. In Info, the title is
15113 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
15114 subheading, , Subsection Commands}.@refill
15116 @item @@appendixsubsubsec @var{title}
15117 Begin an appendix subsubsection within an appendix subsection. The
15118 title appears in the table of contents of a printed manual. In Info,
15119 the title is underlined with periods. @xref{subsubsection,, The
15120 `subsub' Commands}.@refill
15123 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
15124 print the table's first column without highlighting (``as is'').
15125 @xref{Two-column Tables, , Making a Two-column Table}.@refill
15127 @item @@author @var{author}
15128 Typeset @var{author} flushleft and underline it. @xref{title
15129 subtitle author, , The @code{@@title} and @code{@@author}
15132 @item @@b@{@var{text}@}
15133 Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill
15137 Force a paragraph break. If used within a line, follow @code{@@br}
15138 with braces. @xref{br, , @code{@@br}}.@refill
15142 Generate a large round dot, or the closest possible
15143 thing to one. @xref{bullet, , @code{@@bullet}}.@refill
15146 Stop formatting a file. The formatters do not see the contents of a
15147 file following an @code{@@bye} command. @xref{Ending a File}.@refill
15149 @item @@c @var{comment}
15150 Begin a comment in Texinfo. The rest of the line does not appear in
15151 either the Info file or the printed manual. A synonym for
15152 @code{@@comment}. @xref{Comments, , Comments}.@refill
15155 Highlight an example or quotation by drawing a box with rounded
15156 corners around it. Pair with @code{@@end cartouche}. No effect in
15157 Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
15159 @item @@center @var{line-of-text}
15160 Center the line of text following the command.
15161 @xref{titlefont center sp, , @code{@@center}}.@refill
15163 @item @@centerchap @var{line-of-text}
15164 Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
15167 @item @@chapheading @var{title}
15168 Print a chapter-like heading in the text, but not in the table of
15169 contents of a printed manual. In Info, the title is underlined with
15170 asterisks. @xref{majorheading & chapheading, , @code{@@majorheading}
15171 and @code{@@chapheading}}.@refill
15173 @item @@chapter @var{title}
15174 Begin a chapter. The chapter title appears in the table of
15175 contents of a printed manual. In Info, the title is underlined with
15176 asterisks. @xref{chapter, , @code{@@chapter}}.@refill
15178 @item @@cindex @var{entry}
15179 Add @var{entry} to the index of concepts. @xref{Index Entries, ,
15180 Defining the Entries of an Index}.@refill
15182 @item @@cite@{@var{reference}@}
15183 Highlight the name of a book or other reference that lacks a
15184 companion Info file. @xref{cite, , @code{@@cite}}.@refill
15186 @item @@clear @var{flag}
15187 Unset @var{flag}, preventing the Texinfo formatting commands from
15188 formatting text between subsequent pairs of @code{@@ifset @var{flag}}
15189 and @code{@@end ifset} commands, and preventing
15190 @code{@@value@{@var{flag}@}} from expanding to the value to which
15192 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15194 @item @@code@{@var{sample-code}@}
15195 Highlight text that is an expression, a syntactically complete token
15196 of a program, or a program name. @xref{code, , @code{@@code}}.@refill
15198 @item @@command@{@var{command-name}@}
15199 Indicate a command name, such as @command{ls}.
15200 @xref{command,, @code{@@command}}.
15202 @item @@comment @var{comment}
15203 Begin a comment in Texinfo. The rest of the line does not appear in
15204 either the Info file or the printed manual. A synonym for @code{@@c}.
15208 Print a complete table of contents. Has no effect in Info, which uses
15209 menus instead. @xref{Contents, , Generating a Table of
15212 @item @@copyright@{@}
15213 Generate a copyright symbol. @xref{copyright symbol, ,
15214 @code{@@copyright}}.@refill
15217 @item @@ctrl@{@var{ctrl-char}@}
15218 Describe an @sc{ascii} control character. Insert actual control character
15219 into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill
15222 @item @@defcodeindex @var{index-name}
15223 Define a new index and its indexing command. Print entries in an
15224 @code{@@code} font. @xref{New Indices, , Defining New
15227 @item @@defcv @var{category} @var{class} @var{name}
15228 @itemx @@defcvx @var{category} @var{class} @var{name}
15229 Format a description for a variable associated with a class in
15230 object-oriented programming. Takes three arguments: the category of
15231 thing being defined, the class to which it belongs, and its name.
15232 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15234 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
15235 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
15236 Format a description for a function, interactive command, or similar
15237 entity that may take arguments. @code{@@deffn} takes as arguments the
15238 category of entity being described, the name of this particular
15239 entity, and its arguments, if any. @xref{Definition Commands}.@refill
15241 @item @@defindex @var{index-name}
15242 Define a new index and its indexing command. Print entries in a roman
15243 font. @xref{New Indices, , Defining New Indices}.@refill
15245 @item @@definfoenclose @var{newcmd}, @var{before}, @var{after},
15246 Create new @@-command @var{newcmd} for Info that marks text by enclosing
15247 it in strings that precede and follow the text. @xref{definfoenclose}.
15249 @item @@defivar @var{class} @var{instance-variable-name}
15250 @itemx @@defivarx @var{class} @var{instance-variable-name}
15251 This command formats a description for an instance variable in
15252 object-oriented programming. The command is equivalent to @samp{@@defcv
15253 @{Instance Variable@} @dots{}}. @xref{Definition Commands}, and
15254 @ref{deffnx,, Def Cmds in Detail}.
15256 @item @@defmac @var{macroname} @var{arguments}@dots{}
15257 @itemx @@defmacx @var{macroname} @var{arguments}@dots{}
15258 Format a description for a macro. The command is equivalent to
15259 @samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and
15260 @ref{deffnx,, Def Cmds in Detail}.
15262 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
15263 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
15264 Format a description for a method in object-oriented programming. The
15265 command is equivalent to @samp{@@defop Method @dots{}}. Takes as
15266 arguments the name of the class of the method, the name of the
15267 method, and its arguments, if any. @xref{Definition Commands}, and
15268 @ref{deffnx,, Def Cmds in Detail}.
15270 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
15271 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
15272 Format a description for an operation in object-oriented programming.
15273 @code{@@defop} takes as arguments the overall name of the category of
15274 operation, the name of the class of the operation, the name of the
15275 operation, and its arguments, if any. @xref{Definition
15276 Commands}, and @ref{Abstract Objects}.
15278 @item @@defopt @var{option-name}
15279 @itemx @@defoptx @var{option-name}
15280 Format a description for a user option. The command is equivalent to
15281 @samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and
15282 @ref{deffnx,, Def Cmds in Detail}.
15284 @item @@defspec @var{special-form-name} @var{arguments}@dots{}
15285 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
15286 Format a description for a special form. The command is equivalent to
15287 @samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands},
15288 and @ref{deffnx,, Def Cmds in Detail}.
15290 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
15291 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
15292 Format a description for a data type. @code{@@deftp} takes as arguments
15293 the category, the name of the type (which is a word like @samp{int} or
15294 @samp{float}), and then the names of attributes of objects of that type.
15295 @xref{Definition Commands}, and @ref{Data Types}.
15297 @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
15298 @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
15299 Format a description for a function or similar entity that may take
15300 arguments and that is typed. @code{@@deftypefn} takes as arguments the
15301 classification of entity being described, the type, the name of the
15302 entity, and its arguments, if any. @xref{Definition Commands}, and
15303 @ref{deffnx,, Def Cmds in Detail}.
15305 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
15306 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
15307 Format a description for a function in a typed language.
15308 The command is equivalent to @samp{@@deftypefn Function @dots{}}.
15309 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15311 @item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
15312 @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
15313 Format a description for a typed instance variable in object-oriented
15314 programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
15316 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
15317 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
15318 Format a description for a typed method in object-oriented programming.
15319 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15321 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
15322 @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
15323 Format a description for a typed operation in object-oriented programming.
15324 @xref{Definition Commands}, and @ref{Abstract Objects}.
15326 @item @@deftypevar @var{data-type} @var{variable-name}
15327 @itemx @@deftypevarx @var{data-type} @var{variable-name}
15328 Format a description for a variable in a typed language. The command is
15329 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
15330 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
15332 @item @@deftypevr @var{classification} @var{data-type} @var{name}
15333 @itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
15334 Format a description for something like a variable in a typed
15335 language---an entity that records a value. Takes as arguments the
15336 classification of entity being described, the type, and the name of the
15337 entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
15340 @item @@defun @var{function-name} @var{arguments}@dots{}
15341 @itemx @@defunx @var{function-name} @var{arguments}@dots{}
15342 Format a description for functions. The command is equivalent to
15343 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
15344 @ref{deffnx,, Def Cmds in Detail}.
15346 @item @@defvar @var{variable-name}
15347 @itemx @@defvarx @var{variable-name}
15348 Format a description for variables. The command is equivalent to
15349 @samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and
15350 @ref{deffnx,, Def Cmds in Detail}.
15352 @item @@defvr @var{category} @var{name}
15353 @itemx @@defvrx @var{category} @var{name}
15354 Format a description for any kind of variable. @code{@@defvr} takes
15355 as arguments the category of the entity and the name of the entity.
15356 @xref{Definition Commands},
15357 and @ref{deffnx,, Def Cmds in Detail}.
15360 Avoid @code{makeinfo} confusion stemming from the detailed node listing
15361 in a master menu. @xref{Master Menu Parts}.
15363 @item @@dfn@{@var{term}@}
15364 Highlight the introductory or defining use of a term.
15365 @xref{dfn, , @code{@@dfn}}.@refill
15367 @item @@dircategory @var{dirpart}
15368 Specify a part of the Info directory menu where this file's entry should
15369 go. @xref{Installing Dir Entries}.
15372 Begin the Info directory menu entry for this file. Pair with
15373 @code{@@end direntry}. @xref{Installing Dir Entries}.
15376 Begin a kind of example. Like @code{@@example} (indent text, do not
15377 fill), but do not select a new font. Pair with @code{@@end display}.
15378 @xref{display, , @code{@@display}}.
15380 @item @@dmn@{@var{dimension}@}
15381 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
15382 thin space before @var{dimension}. No effect in Info.
15383 @xref{dmn, , @code{@@dmn}}.
15385 @item @@documentdescription
15386 Set the document description text, included in the HTML output. Pair
15387 with @code{@@end documentdescription}. @xref{documentdescription,,
15388 @code{@@documentdescription}}.
15390 @item @@documentencoding @var{enc}
15391 Declare the input encoding to be @var{enc}.
15392 @xref{documentencoding,, @code{@@documentencoding}}.
15394 @item @@documentlanguage @var{CC}
15395 Declare the document language as the two-character ISO-639 abbreviation
15396 @var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}.
15398 @item @@dotaccent@{@var{c}@}
15399 Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
15400 @xref{Inserting Accents}.
15403 Insert an ellipsis: @samp{@dots{}}.
15404 @xref{dots, , @code{@@dots}}.@refill
15406 @item @@email@{@var{address}[, @var{displayed-text}]@}
15407 Indicate an electronic mail address.
15408 @xref{email, , @code{@@email}}.
15410 @item @@emph@{@var{text}@}
15411 Highlight @var{text}; text is displayed in @emph{italics} in printed
15412 output, and surrounded by asterisks in Info. @xref{Emphasis, ,
15415 @item @@end @var{environment}
15416 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
15417 Commands,,@@-commands}.
15419 @item @@env@{@var{environment-variable}@}
15420 Indicate an environment variable name, such as @env{PATH}.
15421 @xref{env,, @code{@@env}}.
15423 @item @@enddots@{@}
15424 Generate an end-of-sentence of ellipsis, like this @enddots{}
15425 @xref{dots,,@code{@@dots@{@}}}.
15427 @item @@enumerate [@var{number-or-letter}]
15428 Begin a numbered list, using @code{@@item} for each entry.
15429 Optionally, start list with @var{number-or-letter}. Pair with
15430 @code{@@end enumerate}. @xref{enumerate, ,
15431 @code{@@enumerate}}.@refill
15434 Indicate to the reader the exact equivalence of two forms with a
15435 glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
15438 Indicate to the reader with a glyph that the following text is
15439 an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
15441 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15442 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15443 Specify page footings resp.@: headings for even-numbered (left-hand)
15444 pages. @xref{Custom Headings, ,
15445 How to Make Your Own Headings}.@refill
15447 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15448 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15449 Specify page footings resp.@: headings for every page. Not relevant to
15450 Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill
15453 Begin an example. Indent text, do not fill, and select fixed-width font.
15454 Pair with @code{@@end example}. @xref{example, ,
15455 @code{@@example}}.@refill
15457 @item @@exampleindent @var{indent}
15458 Indent example-like environments by @var{indent} number of spaces
15459 (perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
15461 @item @@exclamdown@{@}
15462 Produce an upside-down exclamation point. @xref{Inserting Accents}.
15464 @item @@exdent @var{line-of-text}
15465 Remove any indentation a line might have. @xref{exdent, ,
15466 Undoing the Indentation of a Line}.@refill
15468 @item @@expansion@{@}
15469 Indicate the result of a macro expansion to the reader with a special
15470 glyph: @samp{@expansion{}}.
15471 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
15473 @item @@file@{@var{filename}@}
15474 Highlight the name of a file, buffer, node, or directory. @xref{file, ,
15475 @code{@@file}}.@refill
15478 Prevent @TeX{} from printing large black warning rectangles beside
15479 over-wide lines. @xref{Overfull hboxes}.@refill
15481 @item @@findex @var{entry}
15482 Add @var{entry} to the index of functions. @xref{Index Entries, ,
15483 Defining the Entries of an Index}.@refill
15486 @itemx @@flushright
15487 Left justify every line but leave the right end ragged.
15488 Leave font as is. Pair with @code{@@end flushleft}.
15489 @code{@@flushright} analogous.
15490 @xref{flushleft & flushright, , @code{@@flushleft} and
15491 @code{@@flushright}}.@refill
15493 @item @@footnote@{@var{text-of-footnote}@}
15494 Enter a footnote. Footnote text is printed at the bottom of the page
15495 by @TeX{}; Info may format in either `End' node or `Separate' node style.
15496 @xref{Footnotes}.@refill
15498 @item @@footnotestyle @var{style}
15499 Specify an Info file's footnote style, either @samp{end} for the end
15500 node style or @samp{separate} for the separate node style.
15501 @xref{Footnotes}.@refill
15504 Begin a kind of example. Like @code{@@display}, but do not narrow the
15505 margins. Pair with @code{@@end format}. @xref{example,,
15508 @item @@ftable @var{formatting-command}
15509 Begin a two-column table, using @code{@@item} for each entry.
15510 Automatically enter each of the items in the first column into the
15511 index of functions. Pair with @code{@@end ftable}. The same as
15512 @code{@@table}, except for indexing. @xref{ftable vtable, ,
15513 @code{@@ftable} and @code{@@vtable}}.@refill
15516 Hold text together that must appear on one printed page. Pair with
15517 @code{@@end group}. Not relevant to Info. @xref{group, ,
15518 @code{@@group}}.@refill
15520 @item @@H@{@var{c}@}
15521 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
15523 @item @@heading @var{title}
15524 Print an unnumbered section-like heading in the text, but not in the
15525 table of contents of a printed manual. In Info, the title is
15526 underlined with equal signs. @xref{unnumberedsec appendixsec heading,
15527 , Section Commands}.@refill
15529 @item @@headings @var{on-off-single-double}
15530 Turn page headings on or off, and/or specify single-sided or double-sided
15531 page headings for printing. @xref{headings on off, , The
15532 @code{@@headings} Command}.
15535 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
15536 Formatter Commands}.
15538 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
15539 Explicitly define hyphenation points. @xref{- and hyphenation,,
15540 @code{@@-} and @code{@@hyphenation}}.
15542 @item @@i@{@var{text}@}
15543 Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}.
15545 @item @@ifclear @var{flag}
15546 If @var{flag} is cleared, the Texinfo formatting commands format text
15547 between @code{@@ifclear @var{flag}} and the following @code{@@end
15549 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15553 Begin a stretch of text that will be ignored by @TeX{} when it typesets
15554 the printed manual. @code{@@ifhtml} text appears only in the HTML
15555 output. @code{@@ifinfo} output appears in both Info and (for historical
15556 compatibility) plain text output . Pair with @code{@@end ifhtml}
15557 resp.@: @code{@@end ifinfo}. @xref{Conditionals}.
15561 @itemx @@ifnotplaintext
15563 Begin a stretch of text that will be ignored in one output format but
15564 not the others. The text appears in the formats not specified:
15565 @code{@@ifnothtml} text is omitted from html output, etc. The exception
15566 is @code{@@ifnotinfo} text, which is omitted from plain text output as
15567 well as Info output. Pair with @code{@@end ifnothtml} resp.@:
15568 @code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
15569 @code{@@end ifnottex}. @xref{Conditionals}.
15571 @item @@ifplaintext
15572 Begin a stretch of text that appears only in the plain text output.
15573 Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
15575 @item @@ifset @var{flag}
15576 If @var{flag} is set, the Texinfo formatting commands format text
15577 between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
15579 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
15582 Begin a stretch of text that will not appear in the Info file, but
15583 will be processed only by @TeX{}. Pair with @code{@@end iftex}.
15584 @xref{Conditionals, , Conditionally Visible Text}.@refill
15587 Begin a stretch of text that will not appear in either the Info file
15588 or the printed output. Pair with @code{@@end ignore}.
15589 @xref{Comments, , Comments and Ignored Text}.@refill
15591 @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
15592 Include graphics image in external @var{filename} scaled to the given
15593 @var{width} and/or @var{height}, using @var{alt} text and looking for
15594 @samp{@var{filename}.@var{ext}} in HTML. @xref{Images}.
15596 @item @@include @var{filename}
15597 Incorporate the contents of the file @var{filename} into the Info file
15598 or printed document. @xref{Include Files}.@refill
15600 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
15601 Make a cross reference to an Info file for which there is no printed
15602 manual. @xref{inforef, , Cross references using
15603 @code{@@inforef}}.@refill
15605 @item \input @var{macro-definitions-file}
15606 Use the specified macro definitions file. This command is used only
15607 in the first line of a Texinfo file to cause @TeX{} to make use of the
15608 @file{texinfo} macro definitions file. The backslash in @code{\input}
15609 is used instead of an @code{@@} because @TeX{} does not
15610 recognize @code{@@} until after it has read the definitions file.
15611 @xref{Texinfo File Header}.
15614 Indicate the beginning of a marked paragraph for @code{@@itemize} and
15615 @code{@@enumerate}; indicate the beginning of the text of a first column
15616 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
15617 @xref{Lists and Tables}.@refill
15619 @item @@itemize @var{mark-generating-character-or-command}
15620 Produce a sequence of indented paragraphs, with a mark inside the left
15621 margin at the beginning of each paragraph. Pair with @code{@@end
15622 itemize}. @xref{itemize, , @code{@@itemize}}.@refill
15625 Like @code{@@item} but do not generate extra vertical space above the
15626 item text. @xref{itemx, , @code{@@itemx}}.@refill
15628 @item @@kbd@{@var{keyboard-characters}@}
15629 Indicate text that is characters of input to be typed by
15630 users. @xref{kbd, , @code{@@kbd}}.@refill
15632 @item @@kbdinputstyle @var{style}
15633 Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
15634 @xref{kbd, , @code{@@kbd}}.@refill
15636 @item @@key@{@var{key-name}@}
15637 Indicate a name for a key on a keyboard.
15638 @xref{key, , @code{@@key}}.@refill
15640 @item @@kindex @var{entry}
15641 Add @var{entry} to the index of keys.
15642 @xref{Index Entries, , Defining the Entries of an Index}.@refill
15646 Generate the uppercase and lowercase Polish suppressed-L letters,
15647 respectively: @L{}, @l{}.
15649 @c Possibly this can be tossed now that we have macros. --karl, 16sep96.
15650 @c Yes, let's toss it, it's pretty weird. --karl, 15jun97.
15651 @c @item @@global@@let@var{new-command}=@var{existing-command}
15652 @c Equate a new highlighting command with an existing one. Only for
15653 @c @TeX{}. Write definition inside of @code{@@iftex} @dots{} @code{@@end
15654 @c iftex}. @xref{Customized Highlighting}.@refill
15657 Begin an example of Lisp code. Indent text, do not fill, and select
15658 fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
15660 @item @@lowersections
15661 Change subsequent chapters to sections, sections to subsections, and so
15662 on. @xref{Raise/lower sections, , @code{@@raisesections} and
15663 @code{@@lowersections}}.@refill
15665 @item @@macro @var{macroname} @{@var{params}@}
15666 Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
15667 Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining
15670 @item @@majorheading @var{title}
15671 Print a chapter-like heading in the text, but not in the table of
15672 contents of a printed manual. Generate more vertical whitespace before
15673 the heading than the @code{@@chapheading} command. In Info, the chapter
15674 heading line is underlined with asterisks. @xref{majorheading &
15675 chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
15677 @item @@math@{@var{mathematical-expression}@}
15678 Format a mathematical expression.
15679 @xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
15682 Mark the beginning of a menu of nodes in Info. No effect in a printed
15683 manual. Pair with @code{@@end menu}. @xref{Menus}.@refill
15686 Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill
15688 @item @@multitable @var{column-width-spec}
15689 Begin a multi-column table. Pair with @code{@@end multitable}.
15690 @xref{Multitable Column Widths}.
15692 @item @@need @var{n}
15693 Start a new page in a printed manual if fewer than @var{n} mils
15694 (thousandths of an inch) remain on the current page. @xref{need, ,
15695 @code{@@need}}.@refill
15697 @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
15698 Define the beginning of a new node in Info, and serve as a locator for
15699 references for @TeX{}. @xref{node, , @code{@@node}}.@refill
15702 Prevent text from being indented as if it were a new paragraph.
15703 @xref{noindent, , @code{@@noindent}}.@refill
15706 Suppress validation of node references, omit creation of auxiliary files
15707 with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}.
15711 Generate the uppercase and lowercase O-with-slash letters, respectively:
15714 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
15715 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
15716 Specify page footings resp.@: headings for odd-numbered (right-hand)
15717 pages. @xref{Custom Headings, ,
15718 How to Make Your Own Headings}.@refill
15722 Generate the uppercase and lowercase OE ligatures, respectively:
15723 @OE{}, @oe{}. @xref{Inserting Accents}.
15725 @item @@option@{@var{option-name}@}
15726 Indicate a command-line option, such as @option{-l} or @option{--help}.
15727 @xref{option,, @code{@@option}}.
15730 Start a new page in a printed manual. No effect in Info.
15731 @xref{page, , @code{@@page}}.@refill
15733 @item @@pagesizes [@var{width}][, @var{height}]
15734 Change page dimensions. @xref{pagesizes}.
15736 @item @@paragraphindent @var{indent}
15737 Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
15738 source file indentation if @var{indent} is @code{asis}.
15739 @xref{paragraphindent,, Paragraph Indenting}.
15741 @item @@pindex @var{entry}
15742 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
15743 the Entries of an Index}.@refill
15746 Indicate the position of point in a buffer to the reader with a
15747 glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
15748 Point in a Buffer}.@refill
15751 Generate the pounds sterling currency sign.
15752 @xref{pounds,,@code{@@pounds@{@}}}.
15755 Indicate printed output to the reader with a glyph:
15756 @samp{@print{}}. @xref{Print Glyph}.@refill
15758 @item @@printindex @var{index-name}
15759 Print an alphabetized two-column index in a printed manual or generate
15760 an alphabetized menu of index entries for Info. @xref{Printing
15761 Indices & Menus}.@refill
15763 @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15764 Make a reference that starts with a lower case `see' in a printed
15765 manual. Use within parentheses only. Do not follow command with a
15766 punctuation mark---the Info formatting commands automatically insert
15767 terminating punctuation as needed. Only the first argument is mandatory.
15768 @xref{pxref, , @code{@@pxref}}.@refill
15770 @item @@questiondown@{@}
15771 Generate an upside-down question mark. @xref{Inserting Accents}.
15774 Narrow the margins to indicate text that is quoted from another real
15775 or imaginary work. Write command on a line of its own. Pair with
15776 @code{@@end quotation}. @xref{quotation, ,
15777 @code{@@quotation}}.@refill
15779 @item @@r@{@var{text}@}
15780 Print @var{text} in @r{roman} font. No effect in Info.
15781 @xref{Fonts}.@refill
15783 @item @@raisesections
15784 Change subsequent sections to chapters, subsections to sections, and so
15785 on. @xref{Raise/lower sections, , @code{@@raisesections} and
15786 @code{@@lowersections}}.@refill
15788 @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
15789 Make a reference. In a printed manual, the reference does not start
15790 with a `See'. Follow command with a punctuation mark. Only the first
15791 argument is mandatory. @xref{ref, , @code{@@ref}}.@refill
15794 In Info, refill and indent the paragraph after all the other processing
15795 has been done. No effect on @TeX{}, which always refills. This command
15796 is no longer needed, since all formatters now automatically refill.
15797 @xref{Refilling Paragraphs}.@refill
15800 Indicate the result of an expression to the reader with a special
15801 glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
15803 @item @@ringaccent@{@var{c}@}
15804 Generate a ring accent over the next character, as in @ringaccent{o}.
15805 @xref{Inserting Accents}.
15807 @item @@samp@{@var{text}@}
15808 Highlight @var{text} that is a literal example of a sequence of
15809 characters. Used for single characters, for statements, and often for
15810 entire shell commands. @xref{samp, , @code{@@samp}}.@refill
15812 @item @@sc@{@var{text}@}
15813 Set @var{text} in a printed output in @sc{the small caps font} and
15814 set text in the Info file in uppercase letters.
15815 @xref{Smallcaps}.@refill
15817 @item @@section @var{title}
15818 Begin a section within a chapter. In a printed manual, the section
15819 title is numbered and appears in the table of contents. In Info, the
15820 title is underlined with equal signs. @xref{section, ,
15821 @code{@@section}}.@refill
15823 @item @@set @var{flag} [@var{string}]
15824 Make @var{flag} active, causing the Texinfo formatting commands to
15825 format text between subsequent pairs of @code{@@ifset @var{flag}} and
15826 @code{@@end ifset} commands. Optionally, set value of @var{flag} to
15828 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
15830 @item @@setchapternewpage @var{on-off-odd}
15831 Specify whether chapters start on new pages, and if so, whether on
15832 odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
15833 @code{@@setchapternewpage}}.
15835 @item @@setcontentsaftertitlepage
15836 Put the table of contents after the @samp{@@end titlepage} even if the
15837 @code{@@contents} command is not there. @xref{Contents}.
15839 @item @@setfilename @var{info-file-name}
15840 Provide a name to be used by the Info file. This command is essential
15841 for @TeX{} formatting as well, even though it produces no output.
15842 @xref{setfilename, , @code{@@setfilename}}.
15844 @item @@setshortcontentsaftertitlepage
15845 Place the short table of contents after the @samp{@@end titlepage}
15846 command even if the @code{@@shortcontents} command is not there.
15849 @item @@settitle @var{title}
15850 Provide a title for page headers in a printed manual, and the default
15851 document description for HTML @samp{<head>}.
15852 @xref{settitle, , @code{@@settitle}}.@refill
15854 @item @@shortcontents
15855 Print a short table of contents. Not relevant to Info, which uses
15856 menus rather than tables of contents. A synonym for
15857 @code{@@summarycontents}. @xref{Contents, , Generating a Table of
15860 @item @@shorttitlepage @var{title}
15861 Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
15864 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
15865 rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
15866 Printing Small Books}. Also, see @ref{small}.
15868 @item @@smalldisplay
15869 Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
15870 filling), but do not select the fixed-width font. Pair with @code{@@end
15871 smalldisplay}. @xref{small}.
15873 @item @@smallexample
15874 Indent text to indicate an example. Do not fill, select fixed-width
15875 font, narrow the margins. In printed manuals, print text in a smaller
15876 font than with @code{@@example}. Pair with @code{@@end smallexample}.
15879 @item @@smallformat
15880 Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
15881 the margins. Pair with @code{@@end smallformat}. @xref{small}.
15884 Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
15885 with @code{@@end smalllisp}. @xref{small}.
15888 Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
15891 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
15893 @item @@strong @{@var{text}@}
15894 Emphasize @var{text} by typesetting it in a @strong{bold} font for the
15895 printed manual and by surrounding it with asterisks for Info.
15896 @xref{emph & strong, , Emphasizing Text}.@refill
15898 @item @@subheading @var{title}
15899 Print an unnumbered subsection-like heading in the text, but not in
15900 the table of contents of a printed manual. In Info, the title is
15901 underlined with hyphens. @xref{unnumberedsubsec appendixsubsec
15902 subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
15903 @code{@@subheading}}.@refill
15905 @item @@subsection @var{title}
15906 Begin a subsection within a section. In a printed manual, the
15907 subsection title is numbered and appears in the table of contents. In
15908 Info, the title is underlined with hyphens. @xref{subsection, ,
15909 @code{@@subsection}}.@refill
15911 @item @@subsubheading @var{title}
15912 Print an unnumbered subsubsection-like heading in the text, but not in
15913 the table of contents of a printed manual. In Info, the title is
15914 underlined with periods. @xref{subsubsection, , The `subsub'
15917 @item @@subsubsection @var{title}
15918 Begin a subsubsection within a subsection. In a printed manual,
15919 the subsubsection title is numbered and appears in the table of
15920 contents. In Info, the title is underlined with periods.
15921 @xref{subsubsection, , The `subsub' Commands}.@refill
15923 @item @@subtitle @var{title}
15924 In a printed manual, set a subtitle in a normal sized font flush to
15925 the right-hand side of the page. Not relevant to Info, which does not
15926 have title pages. @xref{title subtitle author, , @code{@@title}
15927 @code{@@subtitle} and @code{@@author} Commands}.@refill
15929 @item @@summarycontents
15930 Print a short table of contents. Not relevant to Info, which uses
15931 menus rather than tables of contents. A synonym for
15932 @code{@@shortcontents}. @xref{Contents, , Generating a Table of
15935 @item @@syncodeindex @var{from-index} @var{into-index}
15936 Merge the index named in the first argument into the index named in
15937 the second argument, printing the entries from the first index in
15938 @code{@@code} font. @xref{Combining Indices}.@refill
15940 @item @@synindex @var{from-index} @var{into-index}
15941 Merge the index named in the first argument into the index named in
15942 the second argument. Do not change the font of @var{from-index}
15943 entries. @xref{Combining Indices}.@refill
15945 @item @@t@{@var{text}@}
15946 Print @var{text} in a @t{fixed-width}, typewriter-like font.
15947 No effect in Info. @xref{Fonts}.@refill
15950 Separate columns in a multitable. @xref{Multitable Rows}.
15952 @item @@table @var{formatting-command}
15953 Begin a two-column table, using @code{@@item} for each entry. Write
15954 each first column entry on the same line as @code{@@item}. First
15955 column entries are printed in the font resulting from
15956 @var{formatting-command}. Pair with @code{@@end table}.
15957 @xref{Two-column Tables, , Making a Two-column Table}.
15958 Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
15959 and @ref{itemx, , @code{@@itemx}}.@refill
15962 Insert the logo @TeX{}. @xref{TeX and copyright, , Inserting @TeX{}
15963 and @copyright{}}.@refill
15966 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
15967 Formatter Commands}.
15969 @item @@thischapter
15970 @itemx @@thischaptername
15974 Only allowed in a heading or footing. Stands for the number and name of
15975 the current chapter (in the format `Chapter 1: Title'), the chapter name
15976 only, the filename, the current page number, and the title of the
15977 document, respectively. @xref{Custom Headings, , How to Make Your Own
15980 @item @@tieaccent@{@var{cc}@}
15981 Generate a tie-after accent over the next two characters @var{cc}, as in
15982 `@tieaccent{oo}'. @xref{Inserting Accents}.
15984 @item @@tindex @var{entry}
15985 Add @var{entry} to the index of data types. @xref{Index Entries, ,
15986 Defining the Entries of an Index}.@refill
15988 @item @@title @var{title}
15989 In a printed manual, set a title flush to the left-hand side of the
15990 page in a larger than normal font and underline it with a black rule.
15991 Not relevant to Info, which does not have title pages. @xref{title
15992 subtitle author, , The @code{@@title} @code{@@subtitle} and
15993 @code{@@author} Commands}.@refill
15995 @item @@titlefont@{@var{text}@}
15996 In a printed manual, print @var{text} in a larger than normal font.
15997 Not relevant to Info, which does not have title pages.
15998 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
15999 and @code{@@sp} Commands}.@refill
16002 Indicate to Texinfo the beginning of the title page. Write command on
16003 a line of its own. Pair with @code{@@end titlepage}. Nothing between
16004 @code{@@titlepage} and @code{@@end titlepage} appears in Info.
16005 @xref{titlepage, , @code{@@titlepage}}.@refill
16008 Insert the current date, in `1 Jan 1900' style. @xref{Custom
16009 Headings, , How to Make Your Own Headings}.@refill
16011 @item @@top @var{title}
16012 In a Texinfo file to be formatted with @code{makeinfo}, identify the
16013 topmost @code{@@node} in the file, which must be written on the line
16014 immediately preceding the @code{@@top} command. Used for
16015 @code{makeinfo}'s node pointer insertion feature. The title is
16016 underlined with asterisks. Both the @code{@@node} line and the @code{@@top}
16017 line normally should be enclosed by @code{@@ifnottex} and @code{@@end
16018 ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
16019 command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo
16020 Pointer Creation, , Creating Pointers with @code{makeinfo}}.
16022 @item @@u@{@var{c}@}
16023 @itemx @@ubaraccent@{@var{c}@}
16024 @itemx @@udotaccent@{@var{c}@}
16025 Generate a breve, underbar, or underdot accent, respectively, over or
16026 under the character @var{c}, as in @u{o}, @ubaraccent{o},
16027 @udotaccent{o}. @xref{Inserting Accents}.
16029 @item @@unnumbered @var{title}
16030 In a printed manual, begin a chapter that appears without chapter
16031 numbers of any kind. The title appears in the table of contents of a
16032 printed manual. In Info, the title is underlined with asterisks.
16033 @xref{unnumbered & appendix, , @code{@@unnumbered} and
16034 @code{@@appendix}}.@refill
16036 @item @@unnumberedsec @var{title}
16037 In a printed manual, begin a section that appears without section
16038 numbers of any kind. The title appears in the table of contents of a
16039 printed manual. In Info, the title is underlined with equal signs.
16040 @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
16042 @item @@unnumberedsubsec @var{title}
16043 In a printed manual, begin an unnumbered subsection within a
16044 chapter. The title appears in the table of contents of a printed
16045 manual. In Info, the title is underlined with hyphens.
16046 @xref{unnumberedsubsec appendixsubsec subheading, ,
16047 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
16048 @code{@@subheading}}.@refill
16050 @item @@unnumberedsubsubsec @var{title}
16051 In a printed manual, begin an unnumbered subsubsection within a
16052 chapter. The title appears in the table of contents of a printed
16053 manual. In Info, the title is underlined with periods.
16054 @xref{subsubsection, , The `subsub' Commands}.@refill
16056 @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
16057 Define a cross reference to an external uniform resource locator for the
16058 World Wide Web. @xref{uref, , @code{@@uref}}.@refill
16060 @item @@url@{@var{url}@}
16061 Indicate text that is a uniform resource locator for the World Wide
16062 Web. @xref{url, , @code{@@url}}.@refill
16064 @item @@v@{@var{c}@}
16065 Generate check accent over the character @var{c}, as in @v{o}.
16066 @xref{Inserting Accents}.
16068 @item @@value@{@var{flag}@}
16069 Replace @var{flag} with the value to which it is set by @code{@@set
16071 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
16073 @item @@var@{@var{metasyntactic-variable}@}
16074 Highlight a metasyntactic variable, which is something that stands for
16075 another piece of text. @xref{var, , Indicating Metasyntactic
16078 @item @@verb@{@var{delim} @var{literal} @var{delim}@}
16079 Output @var{literal}, delimited by the single character @var{delim},
16080 exactly as is (in the fixed-width font), including any whitespace or
16081 Texinfo special characters. @xref{verb,,@code{verb}}.
16084 Output the text of the environment exactly as is (in the fixed-width
16085 font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
16087 @item @@verbatiminclude @var{filename}
16088 Output the contents of @var{filename} exactly as is (in the fixed-width font).
16089 @xref{verbatiminclude,,@code{verbatiminclude}}.
16091 @item @@vindex @var{entry}
16092 Add @var{entry} to the index of variables. @xref{Index Entries, ,
16093 Defining the Entries of an Index}.@refill
16095 @item @@vskip @var{amount}
16096 In a printed manual, insert whitespace so as to push text on the
16097 remainder of the page towards the bottom of the page. Used in
16098 formatting the copyright page with the argument @samp{0pt plus
16099 1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
16100 only in contexts ignored for Info. @xref{Copyright}.
16102 @item @@vtable @var{formatting-command}
16103 Begin a two-column table, using @code{@@item} for each entry.
16104 Automatically enter each of the items in the first column into the
16105 index of variables. Pair with @code{@@end vtable}. The same as
16106 @code{@@table}, except for indexing. @xref{ftable vtable, ,
16107 @code{@@ftable} and @code{@@vtable}}.@refill
16109 @item @@w@{@var{text}@}
16110 Prevent @var{text} from being split across two lines. Do not end a
16111 paragraph that uses @code{@@w} with an @code{@@refill} command.
16112 @xref{w, , @code{@@w}}.@refill
16114 @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
16115 Make a reference that starts with `See' in a printed manual. Follow
16116 command with a punctuation mark. Only the first argument is
16117 mandatory. @xref{xref, , @code{@@xref}}.@refill
16122 @appendix Tips and Hints
16124 Here are some tips for writing Texinfo documentation:@refill
16131 Write in the present tense, not in the past or the future.
16134 Write actively! For example, write ``We recommend that @dots{}'' rather
16135 than ``It is recommended that @dots{}''.
16138 Use 70 or 72 as your fill column. Longer lines are hard to read.
16141 Include a copyright notice and copying permissions.
16144 @subsubheading Index, Index, Index!
16146 Write many index entries, in different ways.
16147 Readers like indices; they are helpful and convenient.
16149 Although it is easiest to write index entries as you write the body of
16150 the text, some people prefer to write entries afterwards. In either
16151 case, write an entry before the paragraph to which it applies. This
16152 way, an index entry points to the first page of a paragraph that is
16153 split across pages.
16155 Here are more hints we have found valuable:
16159 Write each index entry differently, so each entry refers to a different
16160 place in the document.
16163 Write index entries only where a topic is discussed significantly. For
16164 example, it is not useful to index ``debugging information'' in a
16165 chapter on reporting bugs. Someone who wants to know about debugging
16166 information will certainly not find it in that chapter.
16169 Consistently capitalize the first word of every concept index entry,
16170 or else consistently use lower case. Terse entries often call for
16171 lower case; longer entries for capitalization. Whichever case
16172 convention you use, please use one or the other consistently! Mixing
16173 the two styles looks bad.
16176 Always capitalize or use upper case for those words in an index for
16177 which this is proper, such as names of countries or acronyms. Always
16178 use the appropriate case for case-sensitive names, such as those in C or
16182 Write the indexing commands that refer to a whole section immediately
16183 after the section command, and write the indexing commands that refer to
16184 a paragraph before that paragraph.
16186 In the example that follows, a blank line comes after the index
16187 entry for ``Leaping'':
16191 @@section The Dog and the Fox
16192 @@cindex Jumping, in general
16195 @@cindex Dog, lazy, jumped over
16196 @@cindex Lazy dog jumped over
16197 @@cindex Fox, jumps over dog
16198 @@cindex Quick fox jumps over dog
16199 The quick brown fox jumps over the lazy dog.
16204 (Note that the example shows entries for the same concept that are
16205 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
16206 readers can look up the concept in different ways.)
16209 @subsubheading Blank Lines
16213 Insert a blank line between a sectioning command and the first following
16214 sentence or paragraph, or between the indexing commands associated with
16215 the sectioning command and the first following sentence or paragraph, as
16216 shown in the tip on indexing. Otherwise, a formatter may fold title and
16217 paragraph together.
16220 Always insert a blank line before an @code{@@table} command and after an
16221 @code{@@end table} command; but never insert a blank line after an
16222 @code{@@table} command or before an @code{@@end table} command.
16233 Jump over lazy dogs.
16238 Also jump over lazy dogs.
16244 On the other hand, @dots{}
16248 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
16249 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
16253 @subsubheading Complete Phrases
16255 Complete phrases are easier to read than @dots{}
16259 Write entries in an itemized list as complete sentences; or at least, as
16260 complete phrases. Incomplete expressions @dots{} awkward @dots{} like
16264 Write the prefatory sentence or phrase for a multi-item list or table as
16265 a complete expression. Do not write ``You can set:''; instead, write
16266 ``You can set these variables:''. The former expression sounds cut off.
16269 @subsubheading Editions, Dates and Versions
16271 Include edition numbers, version numbers, and dates in the
16272 @code{@@copying} text (for people reading the Texinfo file, and for the
16273 legal copyright in the output files). Then use @code{@@insertcopying}
16274 in the @code{@@titlepage} section (for people reading the printed
16275 output) and the Top node (for people reading the online output).
16277 It is easiest to do this using @code{@@set} and @code{@@value}.
16278 @xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
16281 @subsubheading Definition Commands
16283 Definition commands are @code{@@deffn}, @code{@@defun},
16284 @code{@@defmac}, and the like, and enable you to write descriptions in
16285 a uniform format.@refill
16289 Write just one definition command for each entity you define with a
16290 definition command. The automatic indexing feature creates an index
16291 entry that leads the reader to the definition.
16294 Use @code{@@table} @dots{} @code{@@end table} in an appendix that
16295 contains a summary of functions, not @code{@@deffn} or other definition
16299 @subsubheading Capitalization
16303 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
16304 @samp{i} in upper case.
16307 Capitalize ``Info''; it is a name.
16310 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
16311 @samp{T} and @samp{X}. This command causes the formatters to
16312 typeset the name according to the wishes of Donald Knuth, who wrote
16316 @subsubheading Spaces
16318 Do not use spaces to format a Texinfo file, except inside of
16319 @code{@@example} @dots{} @code{@@end example} and similar commands.
16322 For example, @TeX{} fills the following:
16327 @@kbd@{M-x vc-next-action@}
16328 Perform the next logical operation
16329 on the version-controlled file
16330 corresponding to the current buffer.
16336 so it looks like this:
16341 @kbd{M-x vc-next-action}
16342 Perform the next logical operation on the version-controlled file
16343 corresponding to the current buffer.
16348 `C-x v' `M-x vc-next-action' Perform the next logical operation on the
16349 version-controlled file corresponding to the current buffer.
16354 In this case, the text should be formatted with
16355 @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
16357 @subsubheading @@code, @@samp, @@var, and @samp{---}
16361 Use @code{@@code} around Lisp symbols, including command names.
16365 The main function is @@code@{vc-next-action@}, @dots{}
16369 Avoid putting letters such as @samp{s} immediately after an
16370 @samp{@@code}. Such letters look bad.
16373 Use @code{@@var} around meta-variables. Do not write angle brackets
16377 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
16378 typesets these as a long dash and the Info formatters reduce three
16382 @subsubheading Periods Outside of Quotes
16384 Place periods and other punctuation marks @emph{outside} of quotations,
16385 unless the punctuation is part of the quotation. This practice goes
16386 against publishing conventions in the United States, but enables the
16387 reader to distinguish between the contents of the quotation and the
16390 For example, you should write the following sentence with the period
16391 outside the end quotation marks:
16394 Evidently, @samp{au} is an abbreviation for ``author''.
16398 since @samp{au} does @emph{not} serve as an abbreviation for
16399 @samp{author.} (with a period following the word).
16401 @subsubheading Introducing New Terms
16405 Introduce new terms so that a reader who does not know them can
16406 understand them from context; or write a definition for the term.
16408 For example, in the following, the terms ``check in'', ``register'' and
16409 ``delta'' are all appearing for the first time; the example sentence should be
16410 rewritten so they are understandable.
16413 The major function assists you in checking in a file to your
16414 version control system and registering successive sets of changes to
16419 Use the @code{@@dfn} command around a word being introduced, to indicate
16420 that the reader should not expect to know the meaning already, and
16421 should expect to learn the meaning from this passage.
16424 @subsubheading @@pxref
16426 @c !!! maybe include this in the tips on pxref
16428 By the way, it is okay to use pxref with something else in front of
16429 it within the parens, as long as the pxref is followed by the close
16430 paren, and the material inside the parens is not part of a larger
16431 sentence. Also, you can use xref inside parens as part of a complete
16432 sentence so long as you terminate the cross reference with punctuation.
16434 Absolutely never use @code{@@pxref} except in the special context for
16435 which it is designed: inside parentheses, with the closing parenthesis
16436 following immediately after the closing brace. One formatter
16437 automatically inserts closing punctuation and the other does not. This
16438 means that the output looks right both in printed output and in an Info
16439 file, but only when the command is used inside parentheses.
16441 @subsubheading Invoking from a Shell
16443 You can invoke programs such as Emacs, GCC, and @code{gawk} from a
16444 shell. The documentation for each program should contain a section that
16445 describes this. Unfortunately, if the node names and titles for these
16446 sections are all different, they are difficult for users to find.
16448 So, there is a convention to name such sections with a phrase beginning
16449 with the word `Invoking', as in `Invoking Emacs'; this way, users can
16450 find the section easily.
16453 @subsubheading ANSI C Syntax
16455 When you use @code{@@example} to describe a C function's calling
16456 conventions, use the ANSI C syntax, like this:@refill
16459 void dld_init (char *@@var@{path@});
16463 And in the subsequent discussion, refer to the argument values by
16464 writing the same argument names, again highlighted with
16465 @code{@@var}.@refill
16468 Avoid the obsolete style that looks like this:@refill
16477 Also, it is best to avoid writing @code{#include} above the
16478 declaration just to indicate that the function is declared in a
16479 header file. The practice may give the misimpression that the
16480 @code{#include} belongs near the declaration of the function. Either
16481 state explicitly which header file holds the declaration or, better
16482 yet, name the header file used for a group of functions at the
16483 beginning of the section that describes the functions.@refill
16485 @subsubheading Bad Examples
16487 Here are several examples of bad writing to avoid:
16489 In this example, say, `` @dots{} you must @code{@@dfn}@{check
16490 in@} the new version.'' That flows better.
16493 When you are done editing the file, you must perform a
16494 @code{@@dfn}@{check in@}.
16497 In the following example, say, ``@dots{} makes a unified interface such as VC
16501 SCCS, RCS and other version-control systems all perform similar
16502 functions in broadly similar ways (it is this resemblance which makes
16503 a unified control mode like this possible).
16506 And in this example, you should specify what `it' refers to:
16509 If you are working with other people, it assists in coordinating
16510 everyone's changes so they do not step on each other.
16513 @subsubheading And Finally @dots{}
16517 Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
16518 sound in the name `Bach'. But pronounce Texinfo as in `speck':
16522 Write notes for yourself at the very end of a Texinfo file after the
16523 @code{@@bye}. None of the formatters process text after the
16524 @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
16525 @code{@@end ignore}.
16529 @node Sample Texinfo Files
16530 @appendix Sample Texinfo Files
16531 @cindex Sample Texinfo files
16533 The first example is from the first chapter (@pxref{Short Sample}),
16534 given here in its entirety, without commentary. The second sample
16535 includes the full texts to be used in GNU manuals.
16538 * Short Sample Texinfo File::
16539 * GNU Sample Texts::
16543 @node Short Sample Texinfo File
16544 @section Short Sample
16545 @cindex Sample Texinfo file, no comments
16547 Here is a complete, short sample Texinfo file, without any commentary.
16548 You can see this file, with comments, in the first chapter. @xref{Short
16551 In a nutshell: The @command{makeinfo} program transforms a Texinfo
16552 source file such as this into an Info file or HTML; and @TeX{} typesets
16553 it for a printed manual.
16558 \input texinfo @@c -*-texinfo-*-
16559 @@c %**start of header
16560 @@setfilename sample.info
16561 @@settitle Sample Manual 1.0
16562 @@c %**end of header
16565 This is a short example of a complete Texinfo file.
16567 Copyright (C) 2002 Free Software Foundation, Inc.
16571 @@title Sample Title
16573 @@vskip 0pt plus 1filll
16577 @@c Output the table of the contents at the beginning.
16587 * First Chapter:: The first chapter is the
16588 only chapter in this sample.
16589 * Index:: Complete index.
16593 @@node First Chapter
16594 @@chapter First Chapter
16596 @@cindex chapter, first
16598 This is the first chapter.
16599 @@cindex index entry, another
16601 Here is a numbered list.
16605 This is the first item.
16608 This is the second item.
16621 @node GNU Sample Texts
16622 @section GNU Sample Texts
16624 @cindex GNU sample texts
16625 @cindex Sample texts, GNU
16626 @cindex Full texts, GNU
16628 Here is a sample Texinfo document with the full texts that should be
16629 used in GNU manuals.
16631 As well as the legal texts, it also serves as a practical example of how
16632 many elements in a GNU system can affect the manual. If you're not
16633 familiar with all these different elements, don't worry. They're not
16634 required and a perfectly good manual can be written without them.
16635 They're included here nonetheless because many manuals do (or could)
16638 @xref{Short Sample}, for a minimal example of a Texinfo file.
16639 @xref{Beginning a File}, for a full explanation of that minimal
16642 Here are some notes on the example:
16646 @cindex $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $ comment
16647 @cindex CVS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
16648 @cindex RCS $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $, in Texinfo
16649 The @samp{$Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $} comment is for CVS (@pxref{Top,, Overview, cvs,
16650 Concurrent Versions System}) or RCS (see rcsintro(1)) version control
16651 systems, which expand it into a string such as:
16653 $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
16655 (This is useful in all sources that use version control, not just manuals.)
16658 @pindex automake@r{, and version info}
16659 The @file{version.texi} in the @code{@@include} command is maintained
16660 automatically by Automake (@pxref{Top,, Introduction, automake, GNU
16661 Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
16662 elsewhere. If your distribution doesn't use Automake, you can mimic
16663 these or equivalent settings.
16666 The @code{@@syncodeindex} command reflects the recommendation to use only
16667 one index if at all possible, to make it easier for readers.
16670 The @code{@@dircategory} is for constructing the Info directory.
16671 @xref{Installing Dir Entries}, which includes a variety of recommended
16675 The `Invoking' node is a GNU standard to help users find the basic
16676 information about command-line usage of a given program. @xref{Manual
16677 Structure Details,,,standards, GNU Coding Standards}.
16680 It is best to include the entire GNU Free Documentation License in a GNU
16681 manual, unless the manual is only a few pages long. Of course this
16682 sample is even shorter than that, but it includes the FDL anyway in
16683 order to show one conventional way of doing so. The @file{fdl.texi}
16684 file is available on the GNU machines (and in the Texinfo and other GNU
16687 The FDL provides for omitting itself under certain conditions, but in
16688 that case the sample texts given here have to be modified. @xref{GNU
16689 Free Documentation License}.
16692 If your manual has invariant sections (again, see the license itself for
16693 details), then don't forget to include them.
16696 Here is the sample document:
16698 @c We do the first part of this with @example instead of @verbatim
16699 @c because the literal @setfilename and @include confuse Automake. Argh.
16701 \input texinfo @@c -*-texinfo-*-
16702 @@comment $Id: texinfo.txi,v 1.219 2002/03/28 16:36:00 karl Exp $
16703 @@comment %**start of header
16704 @@setfilename sample.info
16705 @@include version.texi
16706 @@settitle GNU Sample @@value@{VERSION@}
16707 @@syncodeindex pg cp
16708 @@comment %**end of header
16710 This manual is for GNU Sample
16711 (version @@value@{VERSION@}, @@value@{UPDATED@}),
16712 which is an example in the Texinfo documentation.
16714 Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16717 Permission is granted to copy, distribute and/or modify this document
16718 under the terms of the GNU Free Documentation License, Version 1.1 or
16719 any later version published by the Free Software Foundation; with no
16720 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
16721 and with the Back-Cover Texts as in (a) below. A copy of the
16722 license is included in the section entitled ``GNU Free Documentation
16725 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
16726 this GNU Manual, like GNU software. Copies published by the Free
16727 Software Foundation raise funds for GNU development.''
16731 @@dircategory Texinfo documentation system
16733 * sample: (sample)Invoking sample.
16738 @@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@}
16739 @@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@})
16741 @@vskip 0pt plus 1filll
16755 * Invoking sample::
16756 * Copying This Manual::
16761 @@node Invoking sample
16762 @@chapter Invoking sample
16765 @@cindex invoking @@command@{sample@}
16767 This is a sample manual. There is no sample program to
16768 invoke, but if there was, you could see its basic usage
16769 and command line options here.
16772 @@node Copying This Manual
16773 @@appendix Copying This Manual
16776 * GNU Free Documentation License:: License for copying this manual.
16791 @node Include Files
16792 @appendix Include Files
16793 @cindex Include files
16795 When @TeX{} or an Info formatting command sees an @code{@@include}
16796 command in a Texinfo file, it processes the contents of the file named
16797 by the command and incorporates them into the DVI or Info file being
16798 created. Index entries from the included file are incorporated into
16799 the indices of the output file.
16801 Include files let you keep a single large document as a collection of
16802 conveniently small parts.
16805 * Using Include Files:: How to use the @code{@@include} command.
16806 * texinfo-multiple-files-update:: How to create and update nodes and
16807 menus when using included files.
16808 * Include File Requirements:: What @code{texinfo-multiple-files-update} expects.
16809 * Sample Include File:: A sample outer file with included files
16810 within it; and a sample included file.
16811 * Include Files Evolution:: How use of the @code{@@include} command
16812 has changed over time.
16815 @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
16816 @section How to Use Include Files
16819 To include another file within a Texinfo file, write the
16820 @code{@@include} command at the beginning of a line and follow it on
16821 the same line by the name of a file to be included. For
16825 @@include buffers.texi
16828 An included file should simply be a segment of text that you expect to
16829 be included as is into the overall or @dfn{outer} Texinfo file; it
16830 should not contain the standard beginning and end parts of a Texinfo
16831 file. In particular, you should not start an included file with a
16832 line saying @samp{\input texinfo}; if you do, that phrase is inserted
16833 into the output file as is. Likewise, you should not end an included
16834 file with an @code{@@bye} command; nothing after @code{@@bye} is
16837 In the past, you were required to write an @code{@@setfilename} line at the
16838 beginning of an included file, but no longer. Now, it does not matter
16839 whether you write such a line. If an @code{@@setfilename} line exists
16840 in an included file, it is ignored.@refill
16842 Conventionally, an included file begins with an @code{@@node} line that
16843 is followed by an @code{@@chapter} line. Each included file is one
16844 chapter. This makes it easy to use the regular node and menu creating
16845 and updating commands to create the node pointers and menus within the
16846 included file. However, the simple Emacs node and menu creating and
16847 updating commands do not work with multiple Texinfo files. Thus you
16848 cannot use these commands to fill in the `Next', `Previous', and `Up'
16849 pointers of the @code{@@node} line that begins the included file. Also,
16850 you cannot use the regular commands to create a master menu for the
16851 whole file. Either you must insert the menus and the `Next',
16852 `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
16853 Texinfo mode command, @code{texinfo-multiple-files-update}, that is
16854 designed for @code{@@include} files.@refill
16856 @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
16857 @section @code{texinfo-multiple-files-update}
16858 @findex texinfo-multiple-files-update
16860 GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
16861 command. This command creates or updates `Next', `Previous', and `Up'
16862 pointers of included files as well as those in the outer or overall
16863 Texinfo file, and it creates or updates a main menu in the outer file.
16864 Depending whether you call it with optional arguments, the command
16865 updates only the pointers in the first @code{@@node} line of the
16866 included files or all of them:@refill
16869 @item M-x texinfo-multiple-files-update
16870 Called without any arguments:@refill
16874 Create or update the `Next', `Previous', and `Up' pointers of the
16875 first @code{@@node} line in each file included in an outer or overall
16876 Texinfo file.@refill
16879 Create or update the `Top' level node pointers of the outer or
16880 overall file.@refill
16883 Create or update a main menu in the outer file.@refill
16886 @item C-u M-x texinfo-multiple-files-update
16887 Called with @kbd{C-u} as a prefix argument:
16891 Create or update pointers in the first @code{@@node} line in each
16895 Create or update the `Top' level node pointers of the outer file.
16898 Create and insert a master menu in the outer file. The master menu
16899 is made from all the menus in all the included files.@refill
16902 @item C-u 8 M-x texinfo-multiple-files-update
16903 Called with a numeric prefix argument, such as @kbd{C-u 8}:
16907 Create or update @strong{all} the `Next', `Previous', and `Up' pointers
16908 of all the included files.@refill
16911 Create or update @strong{all} the menus of all the included
16915 Create or update the `Top' level node pointers of the outer or
16916 overall file.@refill
16919 And then create a master menu in the outer file. This is similar to
16920 invoking @code{texinfo-master-menu} with an argument when you are
16921 working with just one file.@refill
16925 Note the use of the prefix argument in interactive use: with a regular
16926 prefix argument, just @w{@kbd{C-u}}, the
16927 @code{texinfo-multiple-files-update} command inserts a master menu;
16928 with a numeric prefix argument, such as @kbd{C-u 8}, the command
16929 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
16930 master menu.@refill
16933 @node Include File Requirements
16934 @section Include File Requirements
16935 @cindex Include file requirements
16936 @cindex Requirements for include files
16938 If you plan to use the @code{texinfo-multiple-files-update} command,
16939 the outer Texinfo file that lists included files within it should
16940 contain nothing but the beginning and end parts of a Texinfo file, and
16941 a number of @code{@@include} commands listing the included files. It
16942 should not even include indices, which should be listed in an included
16943 file of their own.@refill
16945 Moreover, each of the included files must contain exactly one highest
16946 level node (conventionally, @code{@@chapter} or equivalent),
16947 and this node must be the first node in the included file.
16948 Furthermore, each of these highest level nodes in each included file
16949 must be at the same hierarchical level in the file structure.
16950 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
16951 @code{@@unnumbered} node. Thus, normally, each included file contains
16952 one, and only one, chapter or equivalent-level node.@refill
16954 The outer file should contain only @emph{one} node, the `Top' node. It
16955 should @emph{not} contain any nodes besides the single `Top' node. The
16956 @code{texinfo-multiple-files-update} command will not process
16959 @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
16960 @section Sample File with @code{@@include}
16961 @cindex Sample @code{@@include} file
16962 @cindex Include file sample
16963 @cindex @code{@@include} file sample
16965 Here is an example of a complete outer Texinfo file with @code{@@include} files
16966 within it before running @code{texinfo-multiple-files-update}, which
16967 would insert a main or master menu:@refill
16971 \input texinfo @@c -*-texinfo-*-
16972 @c %**start of header
16973 @@setfilename include-example.info
16974 @@settitle Include Example
16975 @c %**end of header
16979 @@setchapternewpage odd
16982 @@center @@titlefont@{Include Example@}
16984 @@center by Whom Ever
16989 @@vskip 0pt plus 1filll
16990 Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
16996 @@node Top, First, , (dir)
17002 @@include foo.texinfo
17003 @@include bar.texinfo
17004 @@include concept-index.texinfo
17015 An included file, such as @file{foo.texinfo}, might look like this:
17019 @@node First, Second, , Top
17020 @@chapter First Chapter
17022 Contents of first chapter @dots{}
17026 The full contents of @file{concept-index.texinfo} might be as simple as this:
17030 @@node Concept Index
17031 @@unnumbered Concept Index
17037 The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
17038 Manual} is named @file{elisp.texi}. This outer file contains a master
17039 menu with 417 entries and a list of 41 @code{@@include}
17043 @node Include Files Evolution
17044 @section Evolution of Include Files
17046 When Info was first created, it was customary to create many small
17047 Info files on one subject. Each Info file was formatted from its own
17048 Texinfo source file. This custom meant that Emacs did not need to
17049 make a large buffer to hold the whole of a large Info file when
17050 someone wanted information; instead, Emacs allocated just enough
17051 memory for the small Info file that contained the particular
17052 information sought. This way, Emacs could avoid wasting memory.@refill
17054 References from one file to another were made by referring to the file
17055 name as well as the node name. (@xref{Other Info Files, , Referring to
17056 Other Info Files}. Also, see @ref{Four and Five Arguments, ,
17057 @code{@@xref} with Four and Five Arguments}.)@refill
17059 Include files were designed primarily as a way to create a single,
17060 large printed manual out of several smaller Info files. In a printed
17061 manual, all the references were within the same document, so @TeX{}
17062 could automatically determine the references' page numbers. The Info
17063 formatting commands used include files only for creating joint
17064 indices; each of the individual Texinfo files had to be formatted for
17065 Info individually. (Each, therefore, required its own
17066 @code{@@setfilename} line.)@refill
17068 However, because large Info files are now split automatically, it is
17069 no longer necessary to keep them small.@refill
17071 Nowadays, multiple Texinfo files are used mostly for large documents,
17072 such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
17073 in which several different people write different sections of a
17074 document simultaneously.@refill
17076 In addition, the Info formatting commands have been extended to work
17077 with the @code{@@include} command so as to create a single large Info
17078 file that is split into smaller files if necessary. This means that
17079 you can write menus and cross references without naming the different
17080 Texinfo files.@refill
17084 @appendix Page Headings
17087 @cindex Page numbering
17088 @cindex Page headings
17089 @cindex Formatting headings and footings
17091 Most printed manuals contain headings along the top of every page
17092 except the title and copyright pages. Some manuals also contain
17093 footings. (Headings and footings have no meaning to Info, which is
17094 not paginated.)@refill
17097 * Headings Introduced:: Conventions for using page headings.
17098 * Heading Format:: Standard page heading formats.
17099 * Heading Choice:: How to specify the type of page heading.
17100 * Custom Headings:: How to create your own headings and footings.
17103 @node Headings Introduced, Heading Format, Headings, Headings
17105 @heading Headings Introduced
17108 Texinfo provides standard page heading formats for manuals that are
17109 printed on one side of each sheet of paper and for manuals that are
17110 printed on both sides of the paper. Typically, you will use these
17111 formats, but you can specify your own format if you wish.@refill
17113 In addition, you can specify whether chapters should begin on a new
17114 page, or merely continue the same page as the previous chapter; and if
17115 chapters begin on new pages, you can specify whether they must be
17116 odd-numbered pages.@refill
17118 By convention, a book is printed on both sides of each sheet of paper.
17119 When you open a book, the right-hand page is odd-numbered, and
17120 chapters begin on right-hand pages---a preceding left-hand page is
17121 left blank if necessary. Reports, however, are often printed on just
17122 one side of paper, and chapters begin on a fresh page immediately
17123 following the end of the preceding chapter. In short or informal
17124 reports, chapters often do not begin on a new page at all, but are
17125 separated from the preceding text by a small amount of whitespace.@refill
17127 The @code{@@setchapternewpage} command controls whether chapters begin
17128 on new pages, and whether one of the standard heading formats is used.
17129 In addition, Texinfo has several heading and footing commands that you
17130 can use to generate your own heading and footing formats.@refill
17132 In Texinfo, headings and footings are single lines at the tops and
17133 bottoms of pages; you cannot create multiline headings or footings.
17134 Each header or footer line is divided into three parts: a left part, a
17135 middle part, and a right part. Any part, or a whole line, may be left
17136 blank. Text for the left part of a header or footer line is set
17137 flushleft; text for the middle part is centered; and, text for the
17138 right part is set flushright.@refill
17140 @node Heading Format, Heading Choice, Headings Introduced, Headings
17141 @comment node-name, next, previous, up
17142 @section Standard Heading Formats
17144 Texinfo provides two standard heading formats, one for manuals printed
17145 on one side of each sheet of paper, and the other for manuals printed
17146 on both sides of the paper.
17148 By default, nothing is specified for the footing of a Texinfo file,
17149 so the footing remains blank.@refill
17151 The standard format for single-sided printing consists of a header
17152 line in which the left-hand part contains the name of the chapter, the
17153 central part is blank, and the right-hand part contains the page
17157 A single-sided page looks like this:
17161 _______________________
17163 | chapter page number |
17165 | Start of text ... |
17172 The standard format for two-sided printing depends on whether the page
17173 number is even or odd. By convention, even-numbered pages are on the
17174 left- and odd-numbered pages are on the right. (@TeX{} will adjust the
17175 widths of the left- and right-hand margins. Usually, widths are
17176 correct, but during double-sided printing, it is wise to check that
17177 pages will bind properly---sometimes a printer will produce output in
17178 which the even-numbered pages have a larger right-hand margin than the
17179 odd-numbered pages.)@refill
17181 In the standard double-sided format, the left part of the left-hand
17182 (even-numbered) page contains the page number, the central part is
17183 blank, and the right part contains the title (specified by the
17184 @code{@@settitle} command). The left part of the right-hand
17185 (odd-numbered) page contains the name of the chapter, the central part
17186 is blank, and the right part contains the page number.@refill
17189 Two pages, side by side as in an open book, look like this:@refill
17193 _______________________ _______________________
17195 | page number title | | chapter page number |
17197 | Start of text ... | | More text ... |
17205 The chapter name is preceded by the word ``Chapter'', the chapter number
17206 and a colon. This makes it easier to keep track of where you are in the
17209 @node Heading Choice, Custom Headings, Heading Format, Headings
17210 @comment node-name, next, previous, up
17211 @section Specifying the Type of Heading
17213 @TeX{} does not begin to generate page headings for a standard Texinfo
17214 file until it reaches the @code{@@end titlepage} command. Thus, the
17215 title and copyright pages are not numbered. The @code{@@end
17216 titlepage} command causes @TeX{} to begin to generate page headings
17217 according to a standard format specified by the
17218 @code{@@setchapternewpage} command that precedes the
17219 @code{@@titlepage} section.@refill
17222 There are four possibilities:@refill
17225 @item No @code{@@setchapternewpage} command
17226 Cause @TeX{} to specify the single-sided heading format, with chapters
17227 on new pages. This is the same as @code{@@setchapternewpage on}.@refill
17229 @item @code{@@setchapternewpage on}
17230 Specify the single-sided heading format, with chapters on new pages.@refill
17232 @item @code{@@setchapternewpage off}
17233 Cause @TeX{} to start a new chapter on the same page as the last page of
17234 the preceding chapter, after skipping some vertical whitespace. Also
17235 cause @TeX{} to typeset for single-sided printing. (You can override
17236 the headers format with the @code{@@headings double} command; see
17237 @ref{headings on off, , The @code{@@headings} Command}.)@refill
17239 @item @code{@@setchapternewpage odd}
17240 Specify the double-sided heading format, with chapters on new pages.@refill
17244 Texinfo lacks an @code{@@setchapternewpage even} command.@refill
17246 @node Custom Headings, , Heading Choice, Headings
17247 @comment node-name, next, previous, up
17248 @section How to Make Your Own Headings
17250 You can use the standard headings provided with Texinfo or specify
17251 your own. By default, Texinfo has no footers, so if you specify them,
17252 the available page size for the main text will be slightly reduced.
17254 Texinfo provides six commands for specifying headings and
17258 @code{@@everyheading} @code{@@everyfooting} generate page headers and
17259 footers that are the same for both even- and odd-numbered pages.
17261 @code{@@evenheading} and @code{@@evenfooting} command generate headers
17262 and footers for even-numbered (left-hand) pages.
17264 @code{@@oddheading} and @code{@@oddfooting} generate headers and footers
17265 for odd-numbered (right-hand) pages.
17268 Write custom heading specifications in the Texinfo file immediately
17269 after the @code{@@end titlepage} command.
17270 You must cancel the predefined heading commands with the
17271 @code{@@headings off} command before defining your own
17272 specifications.@refill
17275 Here is how to tell @TeX{} to place the chapter name at the left, the
17276 page number in the center, and the date at the right of every header
17277 for both even- and odd-numbered pages:@refill
17282 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
17287 You need to divide the left part from the central part and the central
17288 part from the right part by inserting @samp{@@|} between parts.
17289 Otherwise, the specification command will not be able to tell where
17290 the text for one part ends and the next part begins.@refill
17292 Each part can contain text or @@-commands. The text
17293 is printed as if the part were within an ordinary paragraph in the
17294 body of the page. The @@-commands replace
17295 themselves with the page number, date, chapter name, or
17299 Here are the six heading and footing commands:@refill
17301 @findex everyheading
17302 @findex everyfooting
17304 @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
17305 @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
17307 The `every' commands specify the format for both even- and odd-numbered
17308 pages. These commands are for documents that are printed on one side
17309 of each sheet of paper, or for documents in which you want symmetrical
17310 headers or footers.@refill
17312 @findex evenheading
17313 @findex evenfooting
17316 @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
17317 @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
17319 @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
17320 @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
17322 The `even' and `odd' commands specify the format for even-numbered
17323 pages and odd-numbered pages. These commands are for books and
17324 manuals that are printed on both sides of each sheet of paper.
17327 Use the @samp{@@this@dots{}} series of @@-commands to
17328 provide the names of chapters
17329 and sections and the page number. You can use the
17330 @samp{@@this@dots{}} commands in the left, center, or right portions
17331 of headers and footers, or anywhere else in a Texinfo file so long as
17332 they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
17335 Here are the @samp{@@this@dots{}} commands:@refill
17340 Expands to the current page number.@refill
17341 @c !!! Karl Berry says that `thissection' can fail on page breaks.
17343 @item @@thissection
17344 Expands to the name of the current section.@refill
17347 @findex thischaptername
17348 @item @@thischaptername
17349 Expands to the name of the current chapter.@refill
17351 @findex thischapter
17352 @item @@thischapter
17353 Expands to the number and name of the current
17354 chapter, in the format `Chapter 1: Title'.@refill
17358 Expands to the name of the document, as specified by the
17359 @code{@@settitle} command.@refill
17363 For @code{@@include} files only: expands to the name of the current
17364 @code{@@include} file. If the current Texinfo source file is not an
17365 @code{@@include} file, this command has no effect. This command does
17366 @emph{not} provide the name of the current Texinfo source file unless
17367 it is an @code{@@include} file. (@xref{Include Files}, for more
17368 information about @code{@@include} files.)@refill
17372 You can also use the @code{@@today@{@}} command, which expands to the
17373 current date, in `1 Jan 1900' format.@refill
17376 Other @@-commands and text are printed in a header or footer just as
17377 if they were in the body of a page. It is useful to incorporate text,
17378 particularly when you are writing drafts:@refill
17383 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
17384 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
17388 Beware of overlong titles: they may overlap another part of the
17389 header or footer and blot it out.@refill
17392 @node Catching Mistakes
17393 @appendix Formatting Mistakes
17394 @cindex Structure, catching mistakes in
17395 @cindex Nodes, catching mistakes
17396 @cindex Catching mistakes
17397 @cindex Correcting mistakes
17398 @cindex Mistakes, catching
17399 @cindex Problems, catching
17400 @cindex Debugging the Texinfo structure
17402 Besides mistakes in the content of your documentation, there are two
17403 kinds of mistake you can make with Texinfo: you can make mistakes with
17404 @@-commands, and you can make mistakes with the structure of the nodes
17407 Emacs has two tools for catching the @@-command mistakes and two for
17408 catching structuring mistakes.@refill
17410 For finding problems with @@-commands, you can run @TeX{} or a region
17411 formatting command on the region that has a problem; indeed, you can
17412 run these commands on each region as you write it.@refill
17414 For finding problems with the structure of nodes and chapters, you can use
17415 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
17416 command and you can use the @kbd{M-x Info-validate} command.@refill
17419 * makeinfo Preferred:: @code{makeinfo} finds errors.
17420 * Debugging with Info:: How to catch errors with Info formatting.
17421 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
17422 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
17423 * Using occur:: How to list all lines containing a pattern.
17424 * Running Info-Validate:: How to find badly referenced nodes.
17427 @node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
17429 @heading @code{makeinfo} Find Errors
17432 The @code{makeinfo} program does an excellent job of catching errors
17433 and reporting them---far better than @code{texinfo-format-region} or
17434 @code{texinfo-format-buffer}. In addition, the various functions for
17435 automatically creating and updating node pointers and menus remove
17436 many opportunities for human error.@refill
17438 If you can, use the updating commands to create and insert pointers
17439 and menus. These prevent many errors. Then use @code{makeinfo} (or
17440 its Texinfo mode manifestations, @code{makeinfo-region} and
17441 @code{makeinfo-buffer}) to format your file and check for other
17442 errors. This is the best way to work with Texinfo. But if you
17443 cannot use @code{makeinfo}, or your problem is very puzzling, then you
17444 may want to use the tools described in this appendix.@refill
17446 @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
17447 @comment node-name, next, previous, up
17448 @section Catching Errors with Info Formatting
17449 @cindex Catching errors with Info formatting
17450 @cindex Debugging with Info formatting
17452 After you have written part of a Texinfo file, you can use the
17453 @code{texinfo-format-region} or the @code{makeinfo-region} command to
17454 see whether the region formats properly.@refill
17456 Most likely, however, you are reading this section because for some
17457 reason you cannot use the @code{makeinfo-region} command; therefore, the
17458 rest of this section presumes that you are using
17459 @code{texinfo-format-region}.@refill
17461 If you have made a mistake with an @@-command,
17462 @code{texinfo-format-region} will stop processing at or after the
17463 error and display an error message. To see where in the buffer the
17464 error occurred, switch to the @samp{*Info Region*} buffer; the cursor
17465 will be in a position that is after the location of the error. Also,
17466 the text will not be formatted after the place where the error
17467 occurred (or more precisely, where it was detected).@refill
17469 For example, if you accidentally end a menu with the command @code{@@end
17470 menus} with an `s' on the end, instead of with @code{@@end menu}, you
17471 will see an error message that says:@refill
17474 @@end menus is not handled by texinfo
17478 The cursor will stop at the point in the buffer where the error
17479 occurs, or not long after it. The buffer will look like this:@refill
17483 ---------- Buffer: *Info Region* ----------
17486 * Using texinfo-show-structure:: How to use
17487 `texinfo-show-structure'
17489 * Running Info-Validate:: How to check for
17490 unreferenced nodes.
17493 ---------- Buffer: *Info Region* ----------
17497 The @code{texinfo-format-region} command sometimes provides slightly
17498 odd error messages. For example, the following cross reference fails to format:@refill
17501 (@@xref@{Catching Mistakes, for more info.)
17505 In this case, @code{texinfo-format-region} detects the missing closing
17506 brace but displays a message that says @samp{Unbalanced parentheses}
17507 rather than @samp{Unbalanced braces}. This is because the formatting
17508 command looks for mismatches between braces as if they were
17509 parentheses.@refill
17511 Sometimes @code{texinfo-format-region} fails to detect mistakes. For
17512 example, in the following, the closing brace is swapped with the
17513 closing parenthesis:@refill
17516 (@@xref@{Catching Mistakes), for more info.@}
17520 Formatting produces:
17522 (*Note for more info.: Catching Mistakes)
17525 The only way for you to detect this error is to realize that the
17526 reference should have looked like this:@refill
17529 (*Note Catching Mistakes::, for more info.)
17532 Incidentally, if you are reading this node in Info and type @kbd{f
17533 @key{RET}} (@code{Info-follow-reference}), you will generate an error
17537 No such node: "Catching Mistakes) The only way @dots{}
17541 This is because Info perceives the example of the error as the first
17542 cross reference in this node and if you type a @key{RET} immediately
17543 after typing the Info @kbd{f} command, Info will attempt to go to the
17544 referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
17545 will complete the node name of the correctly written example and take
17546 you to the `Catching Mistakes' node. (If you try this, you can return
17547 from the `Catching Mistakes' node by typing @kbd{l}
17548 (@code{Info-last}).)
17550 @c !!! section on using Elisp debugger ignored.
17552 Sometimes @code{texinfo-format-region} will stop long after the
17553 original error; this is because it does not discover the problem until
17554 then. In this case, you will need to backtrack.@refill
17557 @c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
17560 @c node Using the Emacs Lisp Debugger
17561 @c appendixsubsec Using the Emacs Lisp Debugger
17562 @c index Using the Emacs Lisp debugger
17563 @c index Emacs Lisp debugger
17564 @c index Debugger, using the Emacs Lisp
17566 If an error is especially elusive, you can turn on the Emacs Lisp
17567 debugger and look at the backtrace; this tells you where in the
17568 @code{texinfo-format-region} function the problem occurred. You can
17569 turn on the debugger with the command:@refill
17572 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
17576 and turn it off with
17579 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
17582 Often, when you are using the debugger, it is easier to follow what is
17583 going on if you use the Emacs Lisp files that are not byte-compiled.
17584 The byte-compiled sources send octal numbers to the debugger that may
17585 look mysterious. To use the uncompiled source files, load
17586 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
17589 The debugger will not catch an error if @code{texinfo-format-region}
17590 does not detect one. In the example shown above,
17591 @code{texinfo-format-region} did not find the error when the whole
17592 list was formatted, but only when part of the list was formatted.
17593 When @code{texinfo-format-region} did not find an error, the debugger
17594 did not find one either. @refill
17596 However, when @code{texinfo-format-region} did report an error, it
17597 invoked the debugger. This is the backtrace it produced:@refill
17600 ---------- Buffer: *Backtrace* ----------
17601 Signalling: (search-failed "[@},]")
17602 re-search-forward("[@},]")
17605 texinfo-format-parse-args()
17607 texinfo-format-xref()
17608 funcall(texinfo-format-xref)
17613 texinfo-format-scan()
17614 (save-excursion ...)
17616 texinfo-format-region(103370 103631)
17617 * call-interactively(texinfo-format-region)
17618 ---------- Buffer: *Backtrace* ----------
17621 The backtrace is read from the bottom up.
17622 @code{texinfo-format-region} was called interactively; and it, in
17623 turn, called various functions, including @code{texinfo-format-scan},
17624 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
17625 Inside the function @code{texinfo-format-parse-args}, the function
17626 @code{re-search-forward} was called; it was this function that could
17627 not find the missing right-hand brace.@refill
17629 @xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs
17630 Manual}, for more information.@refill
17633 @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
17634 @comment node-name, next, previous, up
17635 @section Catching Errors with @TeX{} Formatting
17636 @cindex Catching errors with @TeX{} formatting
17637 @cindex Debugging with @TeX{} formatting
17639 You can also catch mistakes when you format a file with @TeX{}.@refill
17641 Usually, you will want to do this after you have run
17642 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
17643 the same file, because @code{texinfo-format-buffer} sometimes displays
17644 error messages that make more sense than @TeX{}. (@xref{Debugging
17645 with Info}, for more information.)@refill
17647 For example, @TeX{} was run on a Texinfo file, part of which is shown
17651 ---------- Buffer: texinfo.texi ----------
17652 name of the Texinfo file as an extension. The
17653 @@samp@{??@} are `wildcards' that cause the shell to
17654 substitute all the raw index files. (@@xref@{sorting
17655 indices, for more information about sorting
17657 ---------- Buffer: texinfo.texi ----------
17661 (The cross reference lacks a closing brace.)
17662 @TeX{} produced the following output, after which it stopped:@refill
17665 ---------- Buffer: *tex-shell* ----------
17667 @{sorting indices, for more information about sorting
17668 indices.) @@refill @@ETC.
17669 ! Paragraph ended before @@xref was complete.
17675 ---------- Buffer: *tex-shell* ----------
17678 In this case, @TeX{} produced an accurate and
17679 understandable error message:
17682 Paragraph ended before @@xref was complete.
17686 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
17687 @samp{l.27} means that @TeX{} detected the problem on line 27 of the
17688 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
17689 circumstance.@refill
17691 Unfortunately, @TeX{} is not always so helpful, and sometimes you must
17692 truly be a Sherlock Holmes to discover what went wrong.@refill
17694 In any case, if you run into a problem like this, you can do one of three
17699 You can tell @TeX{} to continue running and ignore just this error by
17700 typing @key{RET} at the @samp{?} prompt.@refill
17703 You can tell @TeX{} to continue running and to ignore all errors as best
17704 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
17706 This is often the best thing to do. However, beware: the one error
17707 may produce a cascade of additional error messages as its consequences
17708 are felt through the rest of the file. To stop @TeX{} when it is
17709 producing such an avalanche of error messages, type @kbd{C-c} (or
17710 @kbd{C-c C-c}, if you are running a shell inside Emacs).
17713 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
17714 at the @samp{?} prompt.@refill
17717 If you are running @TeX{} inside Emacs, you need to switch to the shell
17718 buffer and line at which @TeX{} offers the @samp{?} prompt.
17720 Sometimes @TeX{} will format a file without producing error messages even
17721 though there is a problem. This usually occurs if a command is not ended
17722 but @TeX{} is able to continue processing anyhow. For example, if you fail
17723 to end an itemized list with the @code{@@end itemize} command, @TeX{} will
17724 write a DVI file that you can print out. The only error message that
17725 @TeX{} will give you is the somewhat mysterious comment that@refill
17728 (@@end occurred inside a group at level 1)
17732 However, if you print the DVI file, you will find that the text
17733 of the file that follows the itemized list is entirely indented as if
17734 it were part of the last item in the itemized list. The error message
17735 is the way @TeX{} says that it expected to find an @code{@@end}
17736 command somewhere in the file; but that it could not determine where
17737 it was needed.@refill
17739 Another source of notoriously hard-to-find errors is a missing
17740 @code{@@end group} command. If you ever are stumped by
17741 incomprehensible errors, look for a missing @code{@@end group} command
17744 If the Texinfo file lacks header lines,
17745 @TeX{} may stop in the
17746 beginning of its run and display output that looks like the following.
17747 The @samp{*} indicates that @TeX{} is waiting for input.@refill
17750 This is TeX, Version 3.14159 (Web2c 7.0)
17756 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
17757 write the header lines in the Texinfo file and run the @TeX{} command
17758 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
17759 instead of @samp{@@}; and in this circumstance, you are working
17760 directly with @TeX{}, not with Texinfo.)@refill
17762 @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
17763 @comment node-name, next, previous, up
17764 @section Using @code{texinfo-show-structure}
17765 @cindex Showing the structure of a file
17766 @findex texinfo-show-structure
17768 It is not always easy to keep track of the nodes, chapters, sections, and
17769 subsections of a Texinfo file. This is especially true if you are revising
17770 or adding to a Texinfo file that someone else has written.@refill
17772 In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
17773 command lists all the lines that begin with the @@-commands that
17774 specify the structure: @code{@@chapter}, @code{@@section},
17775 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
17776 as prefix argument, if interactive),
17777 the command also shows the @code{@@node} lines. The
17778 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
17779 Texinfo mode, by default.@refill
17781 The lines are displayed in a buffer called the @samp{*Occur*} buffer,
17782 indented by hierarchical level. For example, here is a part of what was
17783 produced by running @code{texinfo-show-structure} on this manual:@refill
17787 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
17788 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
17789 in buffer texinfo.texi.
17791 4177:@@chapter Nodes
17792 4198: @@heading Two Paths
17793 4231: @@section Node and Menu Illustration
17794 4337: @@section The @@code@{@@@@node@} Command
17795 4393: @@subheading Choosing Node and Pointer Names
17796 4417: @@subsection How to Write an @@code@{@@@@node@} Line
17797 4469: @@subsection @@code@{@@@@node@} Line Tips
17802 This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
17803 with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
17804 commands respectively. If you move your cursor into the @samp{*Occur*}
17805 window, you can position the cursor over one of the lines and use the
17806 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
17807 the corresponding spot in the Texinfo file. @xref{Other Repeating
17808 Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
17809 information about @code{occur-mode-goto-occurrence}.@refill
17811 The first line in the @samp{*Occur*} window describes the @dfn{regular
17812 expression} specified by @var{texinfo-heading-pattern}. This regular
17813 expression is the pattern that @code{texinfo-show-structure} looks for.
17814 @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
17815 for more information.@refill
17817 When you invoke the @code{texinfo-show-structure} command, Emacs will
17818 display the structure of the whole buffer. If you want to see the
17819 structure of just a part of the buffer, of one chapter, for example,
17820 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
17821 region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
17822 how the example used above was generated. (To see the whole buffer
17823 again, use @kbd{C-x n w} (@code{widen}).)@refill
17825 If you call @code{texinfo-show-structure} with a prefix argument by
17826 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
17827 @code{@@node} as well as the lines beginning with the @@-sign commands
17828 for @code{@@chapter}, @code{@@section}, and the like.@refill
17830 You can remind yourself of the structure of a Texinfo file by looking at
17831 the list in the @samp{*Occur*} window; and if you have mis-named a node
17832 or left out a section, you can correct the mistake.@refill
17834 @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
17835 @comment node-name, next, previous, up
17836 @section Using @code{occur}
17837 @cindex Occurrences, listing with @code{@@occur}
17840 Sometimes the @code{texinfo-show-structure} command produces too much
17841 information. Perhaps you want to remind yourself of the overall structure
17842 of a Texinfo file, and are overwhelmed by the detailed list produced by
17843 @code{texinfo-show-structure}. In this case, you can use the @code{occur}
17844 command directly. To do this, type@refill
17851 and then, when prompted, type a @dfn{regexp}, a regular expression for
17852 the pattern you want to match. (@xref{Regexps, , Regular Expressions,
17853 emacs, The GNU Emacs Manual}.) The @code{occur} command works from
17854 the current location of the cursor in the buffer to the end of the
17855 buffer. If you want to run @code{occur} on the whole buffer, place
17856 the cursor at the beginning of the buffer.@refill
17858 For example, to see all the lines that contain the word
17859 @samp{@@chapter} in them, just type @samp{@@chapter}. This will
17860 produce a list of the chapters. It will also list all the sentences
17861 with @samp{@@chapter} in the middle of the line.@refill
17863 If you want to see only those lines that start with the word
17864 @samp{@@chapter}, type @samp{^@@chapter} when prompted by
17865 @code{occur}. If you want to see all the lines that end with a word
17866 or phrase, end the last word with a @samp{$}; for example,
17867 @samp{catching mistakes$}. This can be helpful when you want to see
17868 all the nodes that are part of the same chapter or section and
17869 therefore have the same `Up' pointer.@refill
17871 @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
17872 for more information.@refill
17874 @node Running Info-Validate, , Using occur, Catching Mistakes
17875 @comment node-name, next, previous, up
17876 @section Finding Badly Referenced Nodes
17877 @findex Info-validate
17878 @cindex Nodes, checking for badly referenced
17879 @cindex Checking for badly referenced nodes
17880 @cindex Looking for badly referenced nodes
17881 @cindex Finding badly referenced nodes
17882 @cindex Badly referenced nodes
17884 You can use the @code{Info-validate} command to check whether any of
17885 the `Next', `Previous', `Up' or other node pointers fail to point to a
17886 node. This command checks that every node pointer points to an
17887 existing node. The @code{Info-validate} command works only on Info
17888 files, not on Texinfo files.@refill
17890 The @code{makeinfo} program validates pointers automatically, so you
17891 do not need to use the @code{Info-validate} command if you are using
17892 @code{makeinfo}. You only may need to use @code{Info-validate} if you
17893 are unable to run @code{makeinfo} and instead must create an Info file
17894 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
17895 if you write an Info file from scratch.@refill
17898 * Using Info-validate:: How to run @code{Info-validate}.
17899 * Unsplit:: How to create an unsplit file.
17900 * Tagifying:: How to tagify a file.
17901 * Splitting:: How to split a file manually.
17904 @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
17905 @subsection Running @code{Info-validate}
17906 @cindex Running @code{Info-validate}
17907 @cindex Info validating a large file
17908 @cindex Validating a large file
17910 To use @code{Info-validate}, visit the Info file you wish to check and
17918 Note that the @code{Info-validate} command requires an upper case
17919 `I'. You may also need to create a tag table before running
17920 @code{Info-validate}. @xref{Tagifying}.
17922 If your file is valid, you will receive a message that says ``File appears
17923 valid''. However, if you have a pointer that does not point to a node,
17924 error messages will be displayed in a buffer called @samp{*problems in
17925 info file*}.@refill
17927 For example, @code{Info-validate} was run on a test file that contained
17928 only the first node of this manual. One of the messages said:@refill
17931 In node "Overview", invalid Next: Texinfo Mode
17935 This meant that the node called @samp{Overview} had a `Next' pointer that
17936 did not point to anything (which was true in this case, since the test file
17937 had only one node in it).@refill
17939 Now suppose we add a node named @samp{Texinfo Mode} to our test case
17940 but we do not specify a `Previous' for this node. Then we will get
17941 the following error message:@refill
17944 In node "Texinfo Mode", should have Previous: Overview
17948 This is because every `Next' pointer should be matched by a
17949 `Previous' (in the node where the `Next' points) which points back.@refill
17951 @code{Info-validate} also checks that all menu entries and cross references
17952 point to actual nodes.@refill
17954 @code{Info-validate} requires a tag table and does not work with files
17955 that have been split. (The @code{texinfo-format-buffer} command
17956 automatically splits large files.) In order to use @code{Info-validate}
17957 on a large file, you must run @code{texinfo-format-buffer} with an
17958 argument so that it does not split the Info file; and you must create a
17959 tag table for the unsplit file.
17961 @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
17962 @comment node-name, next, previous, up
17963 @subsection Creating an Unsplit File
17964 @cindex Creating an unsplit file
17965 @cindex Unsplit file creation
17967 You can run @code{Info-validate} only on a single Info file that has a
17968 tag table. The command will not work on the indirect subfiles that
17969 are generated when a master file is split. If you have a large file
17970 (longer than 70,000 bytes or so), you need to run the
17971 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
17972 a way that it does not create indirect subfiles. You will also need
17973 to create a tag table for the Info file. After you have done this,
17974 you can run @code{Info-validate} and look for badly referenced
17977 The first step is to create an unsplit Info file. To prevent
17978 @code{texinfo-format-buffer} from splitting a Texinfo file into
17979 smaller Info files, give a prefix to the @kbd{M-x
17980 texinfo-format-buffer} command:@refill
17983 C-u M-x texinfo-format-buffer
17994 When you do this, Texinfo will not split the file and will not create
17995 a tag table for it. @refill
17996 @cindex Making a tag table manually
17997 @cindex Tag table, making manually
17999 @node Tagifying, Splitting, Unsplit, Running Info-Validate
18000 @subsection Tagifying a File
18002 After creating an unsplit Info file, you must create a tag table for
18003 it. Visit the Info file you wish to tagify and type:@refill
18010 (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
18011 Info file with a tag table that you can validate.@refill
18013 The third step is to validate the Info file:@refill
18020 (Note the upper case @samp{I} in @code{Info-validate}.)
18021 In brief, the steps are:@refill
18025 C-u M-x texinfo-format-buffer
18031 After you have validated the node structure, you can rerun
18032 @code{texinfo-format-buffer} in the normal way so it will construct a
18033 tag table and split the file automatically, or you can make the tag
18034 table and split the file manually.@refill
18036 @node Splitting, , Tagifying, Running Info-Validate
18037 @comment node-name, next, previous, up
18038 @subsection Splitting a File Manually
18039 @cindex Splitting an Info file manually
18040 @cindex Info file, splitting manually
18042 You should split a large file or else let the
18043 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
18044 for you automatically. (Generally you will let one of the formatting
18045 commands do this job for you. @xref{Creating an Info File}.)@refill
18047 The split-off files are called the indirect subfiles.@refill
18049 Info files are split to save memory. With smaller files, Emacs does not
18050 have make such a large buffer to hold the information.@refill
18052 If an Info file has more than 30 nodes, you should also make a tag
18053 table for it. @xref{Using Info-validate}, for information
18054 about creating a tag table. (Again, tag tables are usually created
18055 automatically by the formatting command; you only need to create a tag
18056 table yourself if you are doing the job manually. Most likely, you
18057 will do this for a large, unsplit file on which you have run
18058 @code{Info-validate}.)@refill
18060 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
18062 Before running @code{Info-split}, you need to load the @code{info} library
18063 into Emacs by giving the command @kbd{M-x load-library @key{RET} info
18067 Visit the Info file you wish to tagify and split and type the two
18076 (Note that the @samp{I} in @samp{Info} is upper case.)@refill
18078 When you use the @code{Info-split} command, the buffer is modified into a
18079 (small) Info file which lists the indirect subfiles. This file should be
18080 saved in place of the original visited file. The indirect subfiles are
18081 written in the same directory the original file is in, with names generated
18082 by appending @samp{-} and a number to the original file name.@refill
18084 The primary file still functions as an Info file, but it contains just
18085 the tag table and a directory of subfiles.@refill
18088 @node Refilling Paragraphs
18089 @appendix Refilling Paragraphs
18090 @cindex Refilling paragraphs
18091 @cindex Filling paragraphs
18092 @cindex Paragraphs, filling
18095 The @code{@@refill} command refills and, optionally, indents the first
18096 line of a paragraph.@footnote{Perhaps the command should have been
18097 called the @code{@@refillandindent} command, but @code{@@refill} is
18098 shorter and the name was chosen before indenting was possible.} The
18099 @code{@@refill} command is no longer important, but we describe it here
18100 because you once needed it. You will see it in many old Texinfo
18103 Without refilling, paragraphs containing long @@-constructs may look
18104 bad after formatting because the formatter removes @@-commands and
18105 shortens some lines more than others. In the past, neither the
18106 @code{texinfo-format-region} command nor the
18107 @code{texinfo-format-buffer} command refilled paragraphs
18108 automatically. The @code{@@refill} command had to be written at the
18109 end of every paragraph to cause these formatters to fill them. (Both
18110 @TeX{} and @code{makeinfo} have always refilled paragraphs
18111 automatically.) Now, all the Info formatters automatically fill and
18112 indent those paragraphs that need to be filled and indented.@refill
18114 The @code{@@refill} command causes @code{texinfo-format-region} and
18115 @code{texinfo-format-buffer} to refill a paragraph in the Info file
18116 @emph{after} all the other processing has been done. For this reason,
18117 you can not use @code{@@refill} with a paragraph containing either
18118 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
18119 override those two commands.@refill
18121 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
18122 commands now automatically append @code{@@refill} to the end of each
18123 paragraph that should be filled. They do not append @code{@@refill} to
18124 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
18125 and therefore do not refill or indent them.@refill
18128 @node Command Syntax
18129 @appendix @@-Command Syntax
18130 @cindex @@-command syntax
18131 @cindex Syntax, of @@-commands
18132 @cindex Command syntax
18134 The character @samp{@@} is used to start special Texinfo commands.
18135 (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
18136 has four types of @@-command:@refill
18139 @item 1. Non-alphabetic commands.
18140 These commands consist of an @@ followed by a punctuation mark or other
18141 character that is not part of the alphabet. Non-alphabetic commands are
18142 almost always part of the text within a paragraph, and never take any
18143 argument. The two characters (@@ and the other one) are complete in
18144 themselves; none is followed by braces. The non-alphabetic commands
18145 are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
18146 @code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
18147 @code{@@@}}.@refill
18149 @item 2. Alphabetic commands that do not require arguments.
18150 These commands start with @@ followed by a word followed by left- and
18151 right-hand braces. These commands insert special symbols in the
18152 document; they do not require arguments. For example,
18153 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
18154 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
18155 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
18157 @item 3. Alphabetic commands that require arguments within braces.
18158 These commands start with @@ followed by a letter or a word, followed by an
18159 argument within braces. For example, the command @code{@@dfn} indicates
18160 the introductory or defining use of a term; it is used as follows: @samp{In
18161 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
18163 @item 4. Alphabetic commands that occupy an entire line.
18164 These commands occupy an entire line. The line starts with @@,
18165 followed by the name of the command (a word); for example, @code{@@center}
18166 or @code{@@cindex}. If no argument is needed, the word is followed by
18167 the end of the line. If there is an argument, it is separated from
18168 the command name by a space. Braces are not used.@refill
18171 @cindex Braces and argument syntax
18172 Thus, the alphabetic commands fall into classes that have
18173 different argument syntaxes. You cannot tell to which class a command
18174 belongs by the appearance of its name, but you can tell by the
18175 command's meaning: if the command stands for a glyph, it is in
18176 class 2 and does not require an argument; if it makes sense to use the
18177 command together with other text as part of a paragraph, the command
18178 is in class 3 and must be followed by an argument in braces;
18179 otherwise, it is in class 4 and uses the rest of the line as its
18182 The purpose of having a different syntax for commands of classes 3 and
18183 4 is to make Texinfo files easier to read, and also to help the GNU
18184 Emacs paragraph and filling commands work properly. There is only one
18185 exception to this rule: the command @code{@@refill}, which is always
18186 used at the end of a paragraph immediately following the final period
18187 or other punctuation character. @code{@@refill} takes no argument and
18188 does @emph{not} require braces. @code{@@refill} never confuses the
18189 Emacs paragraph commands because it cannot appear at the beginning of
18193 @node Obtaining TeX
18194 @appendix How to Obtain @TeX{}
18195 @cindex Obtaining @TeX{}
18196 @cindex @TeX{}, how to obtain
18198 @c !!! Here is information about obtaining TeX. Update it whenever.
18199 @c !!! Also consider updating TeX.README on ftp.gnu.org.
18200 @c Updated by RJC on 1 March 1995, conversation with MacKay.
18201 @c Updated by kb@cs.umb.edu on 29 July 1996.
18202 @c Updated by kb@cs.umb.edu on 25 April 1997.
18203 @c Updated by kb@cs.umb.edu on 27 February 1998.
18204 @TeX{} is freely redistributable. You can obtain @TeX{} for Unix
18205 systems via anonymous ftp or on physical media. The core material
18206 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
18208 Instructions for retrieval by anonymous ftp and information on other
18209 available distributions:
18211 @uref{ftp://tug.org/tex/unixtex.ftp}
18212 @uref{http://tug.org/unixtex.ftp}
18215 The Free Software Foundation provides a core distribution on its Source
18216 Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
18220 Free Software Foundation, Inc.
18221 59 Temple Place Suite 330
18222 Boston, MA @ @ 02111-1307
18224 Telephone: @w{+1-617-542-5942}
18225 Fax: (including Japan) @w{+1-617-542-2652}
18226 Free Dial Fax (in Japan):
18227 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
18228 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
18229 Electronic mail: @code{gnu@@gnu.org}
18233 Many other @TeX{} distributions are available; see
18234 @uref{http://tug.org/}.
18237 @c These are no longer ``new'', and the explanations
18238 @c are all given elsewhere anyway, I think. --karl, 25apr97.
18239 @c So ignore the entire appendix.
18241 @c node New Features, Command and Variable Index, Obtaining TeX, Top
18242 @c appendix Second Edition Features
18245 % Widen the space for the first column so three control-character
18246 % strings fit in the first column. Switched back to default .8in
18247 % value at end of chapter.
18248 \global\tableindent=1.0in
18251 The second edition of the Texinfo manual describes more than 20 new
18252 Texinfo mode commands and more than 50 previously undocumented Texinfo
18253 @@-commands. This edition is more than twice the length of the first
18256 Here is a brief description of the new commands.@refill
18259 * New Texinfo Mode Commands:: The updating commands are especially useful.
18260 * New Commands:: Many newly described @@-commands.
18263 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
18264 @c appendixsec New Texinfo Mode Commands
18266 Texinfo mode provides commands and features especially designed for
18267 working with Texinfo files. More than 20 new commands have been
18268 added, including commands for automatically creating and updating
18269 both nodes and menus. This is a tedious task when done by hand.@refill
18271 The keybindings are intended to be somewhat mnemonic.@refill
18273 @c subheading Update all nodes and menus
18275 The @code{texinfo-master-menu} command is the primary command:
18279 @itemx M-x texinfo-master-menu
18280 Create or update a master menu.
18281 With @kbd{C-u} as a prefix argument,
18282 first create or update all nodes
18286 @c subheading Update Pointers
18289 Create or update `Next', `Previous', and `Up' node pointers.@refill
18292 @xref{Updating Nodes and Menus}.
18296 @itemx M-x texinfo-update-node
18300 @itemx M-x texinfo-every-node-update
18301 Update every node in the buffer.
18304 @c subheading Update Menus
18307 Create or update menus.@refill
18310 @xref{Updating Nodes and Menus}.
18314 @itemx M-x texinfo-make-menu
18315 Make or update a menu.
18318 @itemx M-x texinfo-all-menus-update
18319 Make or update all the menus in a buffer.
18320 With @kbd{C-u} as a prefix argument,
18321 first update all the nodes.
18324 @c subheading Insert Title as Description
18327 Insert a node's chapter or section title in the space for the
18328 description in a menu entry line; position point so you can edit the
18329 insert. (This command works somewhat differently than the other
18330 insertion commands, which insert only a predefined string.)@refill
18333 @xref{Inserting, Inserting Frequently Used Commands}.
18340 @c subheading Format for Info
18343 Provide keybindings both for the Info formatting commands that are
18344 written in Emacs Lisp and for @code{makeinfo} that is written in
18348 @xref{Info Formatting}.
18351 Use the Emacs lisp @code{texinfo-format@dots{}} commands:
18362 Use @code{makeinfo}:
18372 Recenter the @code{makeinfo} output buffer.
18375 Kill the @code{makeinfo} formatting job.
18378 @c subheading Typeset and Print
18381 Typeset and print Texinfo documents from within Emacs.@refill
18389 @xref{Printing, , Formatting and Printing}.
18394 Run @code{texi2dvi} on the buffer.
18397 Run @TeX{} on the region.
18400 Run @code{texindex}.
18403 Print the DVI file.
18406 Show the print queue.
18409 Delete a job from the print queue.
18412 Kill the current @TeX{} formatting job.
18415 Quit a currently stopped @TeX{} formatting job.
18418 Recenter the output buffer.
18421 @c subheading Other Updating Commands
18424 The ``other updating commands'' do not have standard keybindings because
18425 they are used less frequently.@refill
18428 @xref{Other Updating Commands}.
18431 @item M-x texinfo-insert-node-lines
18432 Insert missing @code{@@node} lines using
18433 section titles as node names.
18435 @item M-x texinfo-multiple-files-update
18436 Update a multi-file document.
18437 With a numeric prefix, such as @kbd{C-u 8},
18438 update @strong{every} pointer and
18439 menu in @strong{all} the files and
18440 then insert a master menu.
18442 @item M-x texinfo-indent-menu-description
18443 Indent descriptions in menus.
18445 @item M-x texinfo-sequential-node-update
18446 Insert node pointers in strict sequence.
18449 @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX
18450 @c appendix.sec New Texinfo @@-Commands
18452 The second edition of the Texinfo manual describes more than 50
18453 commands that were not described in the first edition. A third or so
18454 of these commands existed in Texinfo but were not documented in the
18455 manual; the others are new. Here is a listing, with brief
18456 descriptions of them:@refill
18458 @c subheading Indexing
18461 Create your own index, and merge indices.@refill
18467 @item @@defindex @var{index-name}
18468 Define a new index and its indexing command.
18469 See also the @code{@@defcodeindex} command.
18471 @c written verbosely to avoid overfull hbox
18472 @item @@synindex @var{from-index} @var{into-index}
18473 Merge the @var{from-index} index into the @var{into-index} index.
18474 See also the @code{@@syncodeindex} command.
18477 @c subheading Definitions
18480 Describe functions, variables, macros,
18481 commands, user options, special forms, and other such artifacts in a
18482 uniform format.@refill
18485 @xref{Definition Commands}.
18488 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
18489 Format a description for functions, interactive
18490 commands, and similar entities.
18492 @item @@defvr, @@defop, @dots{}
18493 15 other related commands.
18496 @c subheading Glyphs
18499 Indicate the results of evaluation, expansion,
18500 printed output, an error message, equivalence of expressions, and the
18501 location of point.@refill
18515 @item @@expansion@{@}
18516 @itemx @expansion{}
18529 Result of an expression
18532 @c subheading Page Headings
18535 Customize page headings.
18541 @item @@headings @var{on-off-single-double}
18542 Headings on or off, single, or double-sided.
18544 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
18545 Footings for even-numbered (left-hand) pages.
18547 @item @@evenheading, @@everyheading, @@oddheading, @dots{}
18548 Five other related commands.
18550 @item @@thischapter
18551 Insert name of chapter and chapter number.
18553 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
18557 @c subheading Formatting
18560 Format blocks of text.
18563 @xref{Quotations and Examples}, and@*
18564 @ref{Lists and Tables, , Making Lists and Tables}.
18568 Draw rounded box surrounding text (not in Info).
18570 @item @@enumerate @var{optional-arg}
18571 Enumerate a list with letters or numbers.
18573 @item @@exdent @var{line-of-text}
18574 Remove indentation.
18583 Do not narrow nor change font.
18585 @item @@ftable @var{formatting-command}
18586 @itemx @@vtable @var{formatting-command}
18587 Two-column table with indexing.
18590 For an example of Lisp code.
18592 @item @@smallexample
18594 Like @@table and @@lisp @r{but for} @@smallbook.
18597 @c subheading Conditionals
18600 Conditionally format text.
18603 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
18606 @item @@set @var{flag} [@var{string}]
18607 Set a flag. Optionally, set value
18608 of @var{flag} to @var{string}.
18610 @item @@clear @var{flag}
18613 @item @@value@{@var{flag}@}
18614 Replace with value to which @var{flag} is set.
18616 @item @@ifset @var{flag}
18617 Format, if @var{flag} is set.
18619 @item @@ifclear @var{flag}
18620 Ignore, if @var{flag} is set.
18623 @c subheading @@heading series for Titles
18626 Produce unnumbered headings that do not appear in a table of contents.
18629 @xref{Structuring}.
18632 @item @@heading @var{title}
18633 Unnumbered section-like heading not listed
18634 in the table of contents of a printed manual.
18636 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
18641 @c subheading Font commands
18645 @xref{Smallcaps}, and @*
18649 @item @@r@{@var{text}@}
18650 Print in roman font.
18652 @item @@sc@{@var{text}@}
18653 Print in @sc{small caps} font.
18656 @c subheading Miscellaneous
18659 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
18660 see @ref{Customized Highlighting},@*
18661 see @ref{Overfull hboxes},@*
18662 see @ref{Footnotes},@*
18663 see @ref{dmn, , Format a Dimension},@*
18664 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
18665 see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@*
18666 see @ref{minus, , Inserting a Minus Sign},@*
18667 see @ref{paragraphindent, , Paragraph Indenting},@*
18668 see @ref{Cross Reference Commands},@*
18669 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
18670 see @ref{Custom Headings, , How to Make Your Own Headings}.
18673 @item @@author @var{author}
18674 Typeset author's name.
18676 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
18677 @c Define a highlighting command for Info. (Info only.)
18680 Produce cleaner printed output.
18682 @item @@footnotestyle @var{end-or-separate}
18683 Specify footnote style.
18685 @item @@dmn@{@var{dimension}@}
18686 Format a dimension.
18688 @item @@global@@let@var{new-cmd}=@var{existing-cmd}
18689 Define a highlighting command for @TeX{}. (@TeX{} only.)
18691 @item @@lowersections
18692 Reduce hierarchical level of sectioning commands.
18694 @item @@math@{@var{mathematical-expression}@}
18695 Format a mathematical expression.
18698 Generate a minus sign.
18700 @item @@paragraphindent @var{asis-or-number}
18701 Specify paragraph indentation.
18703 @item @@raisesections
18704 Raise hierarchical level of sectioning commands.
18706 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
18707 Make a reference. In the printed manual, the
18708 reference does not start with the word `see'.
18710 @item @@title @var{title}
18711 Typeset @var{title} in the alternative
18714 @item @@subtitle @var{subtitle}
18715 Typeset @var{subtitle} in the alternative
18719 Insert the current date.
18722 % Switch width of first column of tables back to default value
18723 \global\tableindent=.8in
18728 @node Copying This Manual
18729 @appendix Copying This Manual
18732 * GNU Free Documentation License:: License for copying this manual.
18738 @node Command and Variable Index
18739 @unnumbered Command and Variable Index
18741 This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
18742 functions, and several variables. To make the list easier to use, the
18743 commands are listed without their preceding @samp{@@}.@refill
18748 @node Concept Index
18749 @unnumbered Concept Index