1 \input texinfo.tex @c -*-texinfo-*-
2 @c $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 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).
33 @comment %**end of header
36 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
37 a documentation system that can produce both online information and a
38 printed manual from a single source.
40 Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
41 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
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.2 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
50 is included in the section entitled ``GNU Free Documentation
53 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
54 this GNU Manual. Buying copies from GNU Press supports the FSF in
55 developing GNU and promoting software freedom.''
59 @dircategory Texinfo documentation system
61 * Texinfo: (texinfo). The GNU documentation format.
62 * install-info: (texinfo)Invoking install-info. Update info/dir entries.
63 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
64 * texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
65 * pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
66 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
67 * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
70 @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
71 @c prefix arg). This updates the node pointers, which texinfmt.el needs.
73 @c Set smallbook if printing in smallbook format so the example of the
74 @c smallbook font is actually written using smallbook; in bigbook, a kludge
75 @c is used for TeX output. Do this through the -t option to texi2dvi,
76 @c so this same source can be used for other paper sizes as well.
81 @c If you like blank pages, add through texi2dvi -t.
82 @c setchapternewpage odd
84 @c Currently undocumented command, 5 December 1993:
85 @c nwnode (Same as node, but no warnings; for `makeinfo'.)
88 @shorttitlepage GNU Texinfo
92 @subtitle The GNU Documentation Format
93 @subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
95 @author Robert J. Chassell
96 @author Richard M. Stallman
98 @c Include the Distribution inside the titlepage so
99 @c that headings are turned off.
102 @vskip 0pt plus 1filll
106 Published by the Free Software Foundation @*
107 51 Franklin St, Fifth Floor @*
108 Boston, MA 02110-1301 @*
110 ISBN 1-882114-67-1 @c for version 4.0, September 1999.
111 @c ISBN 1-882114-65-5 is for version 3.12, March 1998.
112 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
113 @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
116 Cover art by Etienne Suvasa.
128 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
129 a documentation system that can produce both online information and a
130 printed manual from a single source.
132 The first part of this master menu lists the major nodes in this Info
133 document, including the @@-command and concept indices. The rest of
134 the menu lists all the lower level nodes in the document.
139 * Copying Conditions:: Your rights.
140 * Overview:: Texinfo in brief.
141 * Texinfo Mode:: Using the GNU Emacs Texinfo mode.
142 * Beginning a File:: What is at the beginning of a Texinfo file?
143 * Ending a File:: What is at the end of a Texinfo file?
144 * Structuring:: Creating chapters, sections, appendices, etc.
145 * Nodes:: Writing nodes, the basic unit of Texinfo.
146 * Menus:: Writing menus.
147 * Cross References:: Writing cross references.
148 * Marking Text:: Marking words and phrases as code,
149 keyboard input, meta-syntactic
150 variables, and the like.
151 * Quotations and Examples:: Block quotations, examples, etc.
152 * Lists and Tables:: Itemized or numbered lists, and tables.
153 * Special Displays:: Floating figures and footnotes.
154 * Indices:: Creating indices.
155 * Insertions:: Inserting @@-signs, braces, etc.
156 * Breaks:: Forcing or preventing line and page breaks.
157 * Definition Commands:: Describing functions and the like uniformly.
158 * Conditionals:: Specifying text for only some output cases.
159 * Internationalization:: Supporting languages other than English.
160 * Defining New Texinfo Commands:: User-defined macros and aliases.
161 * Hardcopy:: Output for paper, with @TeX{}.
162 * Creating and Installing Info Files:: Details on Info output.
163 * Generating HTML:: Details on HTML output.
165 * Command List:: All the Texinfo @@-commands.
166 * Tips:: Hints on how to write a Texinfo document.
167 * Sample Texinfo Files:: Complete examples, including full texts.
168 * Include Files:: How to incorporate other Texinfo files.
169 * Headings:: How to write page headings and footings.
170 * Catching Mistakes:: How to find formatting mistakes.
171 * GNU Free Documentation License::Copying this manual.
172 * Command and Variable Index:: A menu containing commands and variables.
173 * General Index:: A menu covering many topics.
176 --- The Detailed Node Listing ---
180 * Reporting Bugs:: Submitting effective bug reports.
181 * Using Texinfo:: Create printed or online output.
182 * Output Formats:: Overview of the supported output formats.
183 * Info Files:: What is an Info file?
184 * Printed Books:: Characteristics of a printed book or manual.
185 * Formatting Commands:: @@-commands are used for formatting.
186 * Conventions:: General rules for writing a Texinfo file.
187 * Comments:: Writing comments and ignored text in general.
188 * Minimum:: What a Texinfo file must have.
189 * Six Parts:: Usually, a Texinfo file has six parts.
190 * Short Sample:: A short sample Texinfo file.
191 * History:: Acknowledgements, contributors and genesis.
195 * Texinfo Mode Overview:: How Texinfo mode can help you.
196 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
197 purpose editing features.
198 * Inserting:: How to insert frequently used @@-commands.
199 * Showing the Structure:: How to show the structure of a file.
200 * Updating Nodes and Menus:: How to update or create new nodes and menus.
201 * Info Formatting:: How to format for Info.
202 * Printing:: How to format and print part or all of a file.
203 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
205 Updating Nodes and Menus
207 * Updating Commands:: Five major updating commands.
208 * Updating Requirements:: How to structure a Texinfo file for
209 using the updating command.
210 * Other Updating Commands:: How to indent descriptions, insert
211 missing nodes lines, and update
214 Beginning a Texinfo File
216 * Sample Beginning:: A sample beginning for a Texinfo file.
217 * Texinfo File Header:: The first lines.
218 * Document Permissions:: Ensuring your manual is free.
219 * Titlepage & Copyright Page:: Creating the title and copyright pages.
220 * Contents:: How to create a table of contents.
221 * The Top Node:: Creating the `Top' node and master menu.
222 * Global Document Commands:: Affecting formatting throughout.
223 * Software Copying Permissions:: Ensure that you and others continue to
224 have the right to use and share software.
228 * First Line:: The first line of a Texinfo file.
229 * Start of Header:: Formatting a region requires this.
230 * setfilename:: Tell Info the name of the Info file.
231 * settitle:: Create a title for the printed work.
232 * End of Header:: Formatting a region requires this.
236 * copying:: Declare the document's copying permissions.
237 * insertcopying:: Where to insert the permissions.
239 Title and Copyright Pages
241 * titlepage:: Create a title for the printed document.
242 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
243 and @code{@@sp} commands.
244 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
245 and @code{@@author} commands.
246 * Copyright:: How to write the copyright notice and
247 include copying permissions.
248 * end titlepage:: Turn on page headings after the title and
250 * headings on off:: An option for turning headings on and off
251 and double or single sided printing.
253 The `Top' Node and Master Menu
256 * Master Menu Parts::
258 Global Document Commands
260 * documentdescription:: Document summary for the HTML output.
261 * setchapternewpage:: Start chapters on right-hand pages.
262 * paragraphindent:: Specify paragraph indentation.
263 * firstparagraphindent:: Suppress indentation of the first paragraph.
264 * exampleindent:: Specify environment indentation.
266 Ending a Texinfo File
268 * Printing Indices & Menus:: How to print an index in hardcopy and
269 generate index menus in Info.
270 * File End:: How to mark the end of a file.
274 * Tree Structuring:: A manual is like an upside down tree @dots{}
275 * Structuring Command Types:: How to divide a manual into parts.
276 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
278 * unnumbered & appendix::
279 * majorheading & chapheading::
281 * unnumberedsec appendixsec heading::
283 * unnumberedsubsec appendixsubsec subheading::
284 * subsubsection:: Commands for the lowest level sections.
285 * Raise/lower sections:: How to change commands' hierarchical level.
289 * Two Paths:: Different commands to structure
290 Info output and printed output.
291 * Node Menu Illustration:: A diagram, and sample nodes and menus.
292 * node:: Creating nodes, in detail.
293 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
294 * anchor:: Defining arbitrary cross-reference targets.
296 The @code{@@node} Command
298 * Node Names:: How to choose node and pointer names.
299 * Writing a Node:: How to write an @code{@@node} line.
300 * Node Line Tips:: Keep names short.
301 * Node Line Requirements:: Keep names unique, without @@-commands.
302 * First Node:: How to write a `Top' node.
303 * makeinfo top command:: How to use the @code{@@top} command.
307 * Menu Location:: Menus go at the ends of short nodes.
308 * Writing a Menu:: What is a menu?
309 * Menu Parts:: A menu entry has three parts.
310 * Less Cluttered Menu Entry:: Two part menu entry.
311 * Menu Example:: Two and three part menu entries.
312 * Other Info Files:: How to refer to a different Info file.
316 * References:: What cross references are for.
317 * Cross Reference Commands:: A summary of the different commands.
318 * Cross Reference Parts:: A cross reference has several parts.
319 * xref:: Begin a reference with `See' @dots{}
320 * Top Node Naming:: How to refer to the beginning of another file.
321 * ref:: A reference for the last part of a sentence.
322 * pxref:: How to write a parenthetical cross reference.
323 * inforef:: How to refer to an Info-only file.
324 * uref:: How to refer to a uniform resource locator.
325 * cite:: How to refer to books not in the Info system.
329 * Reference Syntax:: What a reference looks like and requires.
330 * One Argument:: @code{@@xref} with one argument.
331 * Two Arguments:: @code{@@xref} with two arguments.
332 * Three Arguments:: @code{@@xref} with three arguments.
333 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
335 Marking Words and Phrases
337 * Indicating:: How to indicate definitions, files, etc.
338 * Emphasis:: How to emphasize text.
340 Indicating Definitions, Commands, etc.
342 * Useful Highlighting:: Highlighting provides useful information.
343 * code:: Indicating program code.
344 * kbd:: Showing keyboard input.
345 * key:: Specifying keys.
346 * samp:: A literal sequence of characters.
347 * verb:: A verbatim sequence of characters.
348 * var:: Indicating metasyntactic variables.
349 * env:: Indicating environment variables.
350 * file:: Indicating file names.
351 * command:: Indicating command names.
352 * option:: Indicating option names.
353 * dfn:: Specifying definitions.
354 * abbr:: Indicating abbreviations.
355 * acronym:: Indicating acronyms.
356 * indicateurl:: Indicating a World Wide Web reference.
357 * email:: Indicating an electronic mail address.
361 * emph & strong:: How to emphasize text in Texinfo.
362 * Smallcaps:: How to use the small caps font.
363 * Fonts:: Various font commands for printed output.
365 Quotations and Examples
367 * Block Enclosing Commands:: Different constructs for different purposes.
368 * quotation:: Writing a quotation.
369 * example:: Writing an example in a fixed-width font.
370 * verbatim:: Writing a verbatim example.
371 * verbatiminclude:: Including a file verbatim.
372 * lisp:: Illustrating Lisp code.
373 * small:: Examples in a smaller font.
374 * display:: Writing an example in the current font.
375 * format:: Writing an example without narrowed margins.
376 * exdent:: Undo indentation on a line.
377 * flushleft & flushright:: Pushing text flush left or flush right.
378 * noindent:: Preventing paragraph indentation.
379 * indent:: Forcing paragraph indentation.
380 * cartouche:: Drawing rounded rectangles around examples.
384 * Introducing Lists:: Texinfo formats lists for you.
385 * itemize:: How to construct a simple list.
386 * enumerate:: How to construct a numbered list.
387 * Two-column Tables:: How to construct a two-column table.
388 * Multi-column Tables:: How to construct generalized tables.
390 Making a Two-column Table
392 * table:: How to construct a two-column table.
393 * ftable vtable:: Automatic indexing for two-column tables.
394 * itemx:: How to put more entries in the first column.
396 @code{@@multitable}: Multi-column Tables
398 * Multitable Column Widths:: Defining multitable column widths.
399 * Multitable Rows:: Defining multitable rows, with examples.
403 * Floats:: Figures, tables, and the like.
404 * Images:: Including graphics and images.
405 * Footnotes:: Writing footnotes.
409 * float:: Producing floating material.
410 * caption shortcaption:: Specifying descriptions for floats.
411 * listoffloats:: A table of contents for floats.
420 * Footnote Commands:: How to write a footnote in Texinfo.
421 * Footnote Styles:: Controlling how footnotes appear in Info.
425 * Index Entries:: Choose different words for index entries.
426 * Predefined Indices:: Use different indices for different kinds
428 * Indexing Commands:: How to make an index entry.
429 * Combining Indices:: How to combine indices.
430 * New Indices:: How to define your own indices.
434 * syncodeindex:: How to merge two indices, using @code{@@code}
435 font for the merged-from index.
436 * synindex:: How to merge two indices, using the
437 default font of the merged-to index.
441 * Atsign Braces Comma:: Inserting @@ and @{@} and ,.
442 * Inserting Quote Characters:: Inserting left and right quotes, in code.
443 * Inserting Space:: How to insert the right amount of space
445 * Inserting Accents:: How to insert accents and special characters.
446 * Inserting Quotation Marks:: How to insert quotation marks.
447 * Dots Bullets:: How to insert dots and bullets.
448 * TeX and copyright:: How to insert the @TeX{} logo
449 and the copyright symbol.
450 * euro:: How to insert the Euro currency symbol.
451 * pounds:: How to insert the pounds currency symbol.
452 * textdegree:: How to insert the degrees symbol.
453 * minus:: How to insert a minus sign.
454 * geq leq:: How to insert greater/less-than-or-equal signs.
455 * math:: How to format a mathematical expression.
456 * Click Sequences:: Inserting GUI usage sequences.
457 * Glyphs:: How to indicate results of evaluation,
458 expansion of macros, errors, etc.
460 Inserting @@ and @{@} and @comma{}
462 * Inserting an Atsign::
464 * Inserting a Comma::
468 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
469 * Ending a Sentence:: Sometimes it does.
470 * Multiple Spaces:: Inserting multiple spaces.
471 * frenchspacing:: Specifying end-of-sentence spacing.
472 * dmn:: How to format a dimension.
474 Inserting Ellipsis and Bullets
476 * dots:: How to insert dots @dots{}
477 * bullet:: How to insert a bullet.
479 Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{}
481 * tex:: The @TeX{} logos.
482 * copyright symbol:: The copyright symbol (c in a circle).
483 * registered symbol:: The registered symbol (R in a circle).
488 * result:: How to show the result of expression.
489 * expansion:: How to indicate an expansion.
490 * Print Glyph:: How to indicate printed output.
491 * Error Glyph:: How to indicate an error message.
492 * Equivalence:: How to indicate equivalence.
493 * Point Glyph:: How to indicate the location of point.
504 Forcing and Preventing Breaks
506 * Break Commands:: Summary of break-related commands.
507 * Line Breaks:: Forcing line breaks.
508 * - and hyphenation:: Helping @TeX{} with hyphenation points.
509 * allowcodebreaks:: Controlling line breaks within @@code text.
510 * w:: Preventing unwanted line breaks in text.
511 * tie:: Inserting an unbreakable but varying space.
512 * sp:: Inserting blank lines.
513 * page:: Forcing the start of a new page.
514 * group:: Preventing unwanted page breaks.
515 * need:: Another way to prevent unwanted page breaks.
519 * Def Cmd Template:: Writing descriptions using definition commands.
520 * Def Cmd Continuation Lines:: Continuing the heading over source lines.
521 * Optional Arguments:: Handling optional and repeated arguments.
522 * deffnx:: Group two or more `first' lines.
523 * Def Cmds in Detail:: Reference for all the definition commands.
524 * Def Cmd Conventions:: Conventions for writing definitions.
525 * Sample Function Definition:: An example.
527 The Definition Commands
529 * Functions Commands:: Commands for functions and similar entities.
530 * Variables Commands:: Commands for variables and similar entities.
531 * Typed Functions:: Commands for functions in typed languages.
532 * Typed Variables:: Commands for variables in typed languages.
533 * Data Types:: The definition command for data types.
534 * Abstract Objects:: Commands for object-oriented programming.
536 Object-Oriented Programming
538 * Variables: Object-Oriented Variables.
539 * Methods: Object-Oriented Methods.
541 Conditionally Visible Text
543 * Conditional Commands:: Text for a given format.
544 * Conditional Not Commands:: Text for any format other than a given one.
545 * Raw Formatter Commands:: Using raw formatter commands.
546 * set clear value:: Variable tests and substitutions.
547 * Conditional Nesting:: Using conditionals inside conditionals.
549 @code{@@set}, @code{@@clear}, and @code{@@value}
551 * set value:: Expand a flag variable to a string.
552 * ifset ifclear:: Format a region if a flag is set.
553 * value Example:: An easy way to update edition information.
557 * documentlanguage:: Declaring the current language.
558 * documentencoding:: Declaring the input encoding.
560 Defining New Texinfo Commands
562 * Defining Macros:: Defining and undefining new commands.
563 * Invoking Macros:: Using a macro, once you've defined it.
564 * Macro Details:: Limitations of Texinfo macros.
565 * alias:: Command aliases.
566 * definfoenclose:: Customized highlighting.
568 Formatting and Printing Hardcopy
570 * Use TeX:: Use @TeX{} to format for hardcopy.
571 * Format with tex/texindex:: How to format with explicit shell commands.
572 * Format with texi2dvi:: A simpler way to format.
573 * Print with lpr:: How to print.
574 * Within Emacs:: How to format and print from an Emacs shell.
575 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
576 * Compile-Command:: How to print using Emacs's compile command.
577 * Requirements Summary:: @TeX{} formatting requirements summary.
578 * Preparing for TeX:: What to do before you use @TeX{}.
579 * Overfull hboxes:: What are and what to do with overfull hboxes.
580 * smallbook:: How to print small format books and manuals.
581 * A4 Paper:: How to print on A4 or A5 paper.
582 * pagesizes:: How to print with customized page sizes.
583 * Cropmarks and Magnification:: How to print marks to indicate the size
584 of pages and how to print scaled up output.
585 * PDF Output:: Portable Document Format output.
586 * Obtaining TeX:: How to Obtain @TeX{}.
588 Creating and Installing Info Files
590 * Creating an Info File::
591 * Installing an Info File::
593 Creating an Info File
595 * makeinfo advantages:: @code{makeinfo} provides better error checking.
596 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
597 * makeinfo options:: Specify fill-column and other options.
598 * Pointer Validation:: How to check that pointers point somewhere.
599 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
600 * texinfo-format commands:: Two Info formatting commands written
601 in Emacs Lisp are an alternative
603 * Batch Formatting:: How to format for Info in Emacs Batch mode.
604 * Tag and Split Files:: How tagged and split files help Info
607 Installing an Info File
609 * Directory File:: The top level menu for all Info files.
610 * New Info File:: Listing a new Info file.
611 * Other Info Directories:: How to specify Info files that are
612 located in other directories.
613 * Installing Dir Entries:: How to specify what menu entry to add
614 to the Info directory.
615 * Invoking install-info:: @code{install-info} options.
619 * HTML Translation:: Details of the HTML output.
620 * HTML Splitting:: How HTML output is split.
621 * HTML CSS:: Influencing HTML output with Cascading Style Sheets.
622 * HTML Xref:: Cross-references in HTML output.
624 HTML Cross-references
626 * Link Basics: HTML Xref Link Basics.
627 * Node Expansion: HTML Xref Node Name Expansion.
628 * Command Expansion: HTML Xref Command Expansion.
629 * 8-bit Expansion: HTML Xref 8-bit Character Expansion.
630 * Mismatch: HTML Xref Mismatch.
634 * Command Syntax:: General syntax for varieties of @@-commands.
638 * Short Sample Texinfo File::
640 * Verbatim Copying License::
641 * All-permissive Copying License::
643 GNU Free Documentation License
647 * Using Include Files:: How to use the @code{@@include} command.
648 * texinfo-multiple-files-update:: How to create and update nodes and
649 menus when using included files.
650 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
651 * Sample Include File:: A sample outer file with included files
652 within it; and a sample included file.
653 * Include Files Evolution:: How use of the @code{@@include} command
654 has changed over time.
658 * Headings Introduced:: Conventions for using page headings.
659 * Heading Format:: Standard page heading formats.
660 * Heading Choice:: How to specify the type of page heading.
661 * Custom Headings:: How to create your own headings and footings.
665 * makeinfo Preferred:: @code{makeinfo} finds errors.
666 * Debugging with Info:: How to catch errors with Info formatting.
667 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
668 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
669 * Using occur:: How to list all lines containing a pattern.
670 * Running Info-Validate:: How to find badly referenced nodes.
672 Finding Badly Referenced Nodes
674 * Using Info-validate:: How to run @code{Info-validate}.
675 * Unsplit:: How to create an unsplit file.
676 * Tagifying:: How to tagify a file.
677 * Splitting:: How to split a file manually.
682 @c Reward readers for getting to the end of the menu :).
683 @c Contributed by Arnold Robbins.
685 Documentation is like sex: when it is good, it is very, very good; and
686 when it is bad, it is better than nothing.
691 @node Copying Conditions
692 @unnumbered Texinfo Copying Conditions
693 @cindex Copying conditions
694 @cindex Conditions for copying Texinfo
696 The programs currently being distributed that relate to Texinfo include
697 @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
698 These programs are @dfn{free}; this means that everyone is free to use
699 them and free to redistribute them on a free basis. The Texinfo-related
700 programs are not in the public domain; they are copyrighted and there
701 are restrictions on their distribution, but these restrictions are
702 designed to permit everything that a good cooperating citizen would want
703 to do. What is not allowed is to try to prevent others from further
704 sharing any version of these programs that they might get from you.
706 Specifically, we want to make sure that you have the right to give away
707 copies of the programs that relate to Texinfo, that you receive source
708 code or else can get it if you want it, that you can change these
709 programs or use pieces of them in new free programs, and that you know
710 you can do these things.
712 To make sure that everyone has such rights, we have to forbid you to
713 deprive anyone else of these rights. For example, if you distribute
714 copies of the Texinfo related programs, you must give the recipients all
715 the rights that you have. You must make sure that they, too, receive or
716 can get the source code. And you must tell them their rights.
718 Also, for our own protection, we must make certain that everyone finds
719 out that there is no warranty for the programs that relate to Texinfo.
720 If these programs are modified by someone else and passed on, we want
721 their recipients to know that what they have is not what we distributed,
722 so that any problems introduced by others will not reflect on our
725 The precise conditions of the licenses for the programs currently being
726 distributed that relate to Texinfo are found in the General Public
727 Licenses that accompany them. This manual specifically is covered by
728 the GNU Free Documentation License (@pxref{GNU Free Documentation
733 @chapter Overview of Texinfo
734 @cindex Overview of Texinfo
735 @cindex Texinfo overview
737 @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
738 like ``speck'', not ``hex''. This odd pronunciation is derived from,
739 but is not the same as, the pronunciation of @TeX{}. In the word
740 @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
741 the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
742 last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
743 were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
744 letters in lower case.} is a documentation system that uses a single
745 source file to produce both online information and printed output. This
746 means that instead of writing two different documents, one for the
747 online information and the other for a printed work, you need write only
748 one document. Therefore, when the work is revised, you need revise only
751 Manuals for most GNU packages are written in Texinfo, and available
752 online at @url{http://www.gnu.org/doc}.
755 * Reporting Bugs:: Submitting effective bug reports.
756 * Using Texinfo:: Create printed or online output.
757 * Output Formats:: Overview of the supported output formats.
758 * Info Files:: What is an Info file?
759 * Printed Books:: Characteristics of a printed book or manual.
760 * Formatting Commands:: @@-commands are used for formatting.
761 * Conventions:: General rules for writing a Texinfo file.
762 * Comments:: Writing comments and ignored text in general.
763 * Minimum:: What a Texinfo file must have.
764 * Six Parts:: Usually, a Texinfo file has six parts.
765 * Short Sample:: A short sample Texinfo file.
766 * History:: Acknowledgements, contributors and genesis.
771 @section Reporting Bugs
773 @cindex Bugs, reporting
774 @cindex Suggestions for Texinfo, making
775 @cindex Reporting bugs
776 We welcome bug reports and suggestions for any aspect of the Texinfo system,
777 programs, documentation, installation, anything. Please email them to
778 @email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo
779 from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
781 @cindex Checklist for bug reports
782 For bug reports, please include enough information for the maintainers
783 to reproduce the problem. Generally speaking, that means:
786 @item the version number of Texinfo and the program(s) or manual(s) involved.
787 @item hardware and operating system names and versions.
788 @item the contents of any input files necessary to reproduce the bug.
789 @item a description of the problem and samples of any erroneous output.
790 @item any unusual options you gave to @command{configure}.
791 @item anything else that you think would be helpful.
794 When in doubt whether something is needed or not, include it. It's
795 better to include too much than to leave out something important.
797 @cindex Patches, contributing
798 Patches are most welcome; if possible, please make them with
799 @samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging
800 Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,,
801 emacs, The GNU Emacs Manual}), and follow the existing coding style.
805 @section Using Texinfo
807 @cindex Using Texinfo in general
808 @cindex Texinfo, introduction to
809 @cindex Introduction to Texinfo
811 Using Texinfo, you can create a printed document (via the @TeX{}
812 typesetting system) the normal features of a book, including chapters,
813 sections, cross references, and indices. From the same Texinfo source
814 file, you can create an Info file with special features to make
815 documentation browsing easy. You can also create from that same
816 source file an HTML output file suitable for use with a web browser,
817 or an XML file. See the next section (@pxref{Output Formats}) for
818 details and the exact commands to generate output from the source.
820 @TeX{} works with virtually all printers; Info works with virtually all
821 computer terminals; the HTML output works with virtually all web
822 browsers. Thus Texinfo can be used by almost any computer user.
824 @cindex Source file format
825 A Texinfo source file is a plain ASCII file containing text
826 interspersed with @dfn{@@-commands} (words preceded by an @samp{@@})
827 that tell the typesetting and formatting programs what to do. You can
828 edit a Texinfo file with any text editor, but it is especially
829 convenient to use GNU Emacs since that editor has a special mode,
830 called Texinfo mode, that provides various Texinfo-related features.
831 (@xref{Texinfo Mode}.)
833 You can use Texinfo to create both online help and printed manuals;
834 moreover, Texinfo is freely redistributable. For these reasons, Texinfo
835 is the official documentation format of the GNU project. More
836 information is available at the @uref{http://www.gnu.org/doc/, GNU
837 documentation web page}.
841 @section Output Formats
842 @cindex Output formats
843 @cindex Back-end output formats
845 Here is a brief overview of the output formats currently supported by
851 (Generated via @command{makeinfo}.) This format is essentially a
852 plain text transliteration of the Texinfo source. It adds a few
853 control characters to separate nodes and provide navigational
854 information for menus, cross-references, indices, and so on. See the
855 next section (@pxref{Info Files}) for more details on this format.
856 The Emacs Info subsystem (@pxref{Top,,Getting Started,info, Info}),
857 and the standalone @command{info} program (@pxref{Top
858 ,, Info Standalone, info-stnd, GNU Info}), among others, can read these
859 files. @xref{Creating and Installing Info Files}.
862 @cindex Plain text output
863 (Generated via @command{makeinfo --no-headers}.) This is almost the
864 same as Info output, except the navigational control characters are
865 omitted. Also, standard output is used by default.
869 @cindex W3 consortium
873 (Generated via @command{makeinfo --html}.) This is the Hyper Text
874 Markup Language that has become the most commonly used language for
875 writing documents on the World Wide Web. Web browsers, such as
876 Mozilla, Lynx, and Emacs-W3, can render this language online. There
877 are many versions of HTML; @command{makeinfo} tries to use a subset
878 of the language that can be interpreted by any common browser. For
879 details of the HTML language and much related information, see
880 @uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}.
886 (Generated via @command{texi2dvi}.) This DeVice Independent binary
887 format is output by the @TeX{} typesetting program
888 (@uref{http://tug.org}). This is then read by a DVI `driver', which
889 writes the actual device-specific commands that can be viewed or
890 printed, notably Dvips for translation to PostScript (@pxref{Invoking
891 Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display
892 (@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}.
894 Be aware that the Texinfo language is very different from and much
895 stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}.
896 For more information on @TeX{} in general, please see the book
897 @cite{@TeX{} for the Impatient}, available from
898 @uref{http://savannah.gnu.org/projects/teximpatient}.
902 @cindex Beebe, Nelson
904 (Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This
905 format was developed by Adobe Systems for portable document
906 interchange, based on their previous PostScript language. It can
907 represent the exact appearance of a document, including fonts and
908 graphics, and supporting arbitrary scaling. It is intended to be
909 platform-independent and easily viewable, among other design goals;
910 @uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has
911 some background. Texinfo uses the @command{pdftex} program, a variant
912 of @TeX{}, to output PDF; see
913 @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
917 @cindex DTD, for Texinfo XML
919 (Generated via @command{makeinfo --xml}.) XML is a generic syntax
920 specification usable for any sort of content (see, for example,
921 @uref{http://www.w3.org/XML/}). The @command{makeinfo} XML output,
922 unlike all the formats above, interprets very little of the Texinfo
923 source. Rather, it merely translates the Texinfo markup commands into
924 XML syntax, for processing by further XML tools. The particular
925 syntax output is defined in the file @file{texinfo.dtd} included in
926 the Texinfo source distribution.
929 @cindex Docbook output
930 (Generated via @command{makeinfo --docbook}.) This is an XML-based
931 format developed some years ago, primarily for technical
932 documentation. It therefore bears some resemblance, in broad
933 outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want
934 to convert from Docbook @emph{to} Texinfo, please see
935 @uref{http://docbook2X.sourceforge.net}.
939 @cindex Man page output, not supported
940 From time to time, proposals are made to generate traditional Unix man
941 pages from Texinfo source. However, because man pages have a very
942 strict conventional format, generating a good man page requires a
943 completely different source than the typical Texinfo applications of
944 writing a good user tutorial and/or a good reference manual. This
945 makes generating man pages incompatible with the Texinfo design goal
946 of not having to document the same information in different ways for
947 different output formats. You might as well just write the man page
951 @cindex O'Dea, Brendan
952 Man pages still have their place, and if you wish to support them, you
953 may find the program @command{help2man} to be useful; it generates a
954 traditional man page from the @samp{--help} output of a program. In
955 fact, this is currently used to generate man pages for the programs in
956 the Texinfo distribution. It is GNU software written by Brendan
957 O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}.
959 @cindex Output formats, supporting more
960 @cindex SGML-tools output format
961 If you are a programmer and would like to contribute to the GNU project
962 by implementing additional output formats for Texinfo, that would be
963 excellent. But please do not write a separate translator texi2foo for
964 your favorite format foo! That is the hard way to do the job, and makes
965 extra work in subsequent maintenance, since the Texinfo language is
966 continually being enhanced and updated. Instead, the best approach is
967 modify @code{makeinfo} to generate the new format.
974 An Info file is a Texinfo file formatted so that the Info documentation
975 reading program can operate on it. (@code{makeinfo}
976 and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
979 Info files are divided into pieces called @dfn{nodes}, each of which
980 contains the discussion of one topic. Each node has a name, and
981 contains both text for the user to read and pointers to other nodes,
982 which are identified by their names. The Info program displays one node
983 at a time, and provides commands with which the user can move to other
986 @xref{Top,,, info, GNU Info}, for more information about using Info.
988 Each node of an Info file may have any number of child nodes that
989 describe subtopics of the node's topic. The names of child
990 nodes are listed in a @dfn{menu} within the parent node; this
991 allows you to use certain Info commands to move to one of the child
992 nodes. Generally, an Info file is organized like a book. If a node
993 is at the logical level of a chapter, its child nodes are at the level
994 of sections; likewise, the child nodes of sections are at the level
997 All the children of any one parent are linked together in a
998 bidirectional chain of `Next' and `Previous' pointers. The `Next'
999 pointer provides a link to the next section, and the `Previous' pointer
1000 provides a link to the previous section. This means that all the nodes
1001 that are at the level of sections within a chapter are linked together.
1002 Normally the order in this chain is the same as the order of the
1003 children in the parent's menu. Each child node records the parent node
1004 name as its `Up' pointer. The last child has no `Next' pointer, and the
1005 first child has the parent both as its `Previous' and as its `Up'
1006 pointer.@footnote{In some documents, the first child has no `Previous'
1007 pointer. Occasionally, the last child has the node name of the next
1008 following higher level node as its `Next' pointer.}
1010 The book-like structuring of an Info file into nodes that correspond
1011 to chapters, sections, and the like is a matter of convention, not a
1012 requirement. The `Up', `Previous', and `Next' pointers of a node can
1013 point to any other nodes, and a menu can contain any other nodes.
1014 Thus, the node structure can be any directed graph. But it is usually
1015 more comprehensible to follow a structure that corresponds to the
1016 structure of chapters and sections in a printed book or report.@refill
1018 In addition to menus and to `Next', `Previous', and `Up' pointers, Info
1019 provides pointers of another kind, called references, that can be
1020 sprinkled throughout the text. This is usually the best way to
1021 represent links that do not fit a hierarchical structure.@refill
1023 Usually, you will design a document so that its nodes match the
1024 structure of chapters and sections in the printed output. But
1025 occasionally there are times when this is not right for the material
1026 being discussed. Therefore, Texinfo uses separate commands to specify
1027 the node structure for the Info file and the section structure for the
1028 printed output.@refill
1030 Generally, you enter an Info file through a node that by convention is
1031 named `Top'. This node normally contains just a brief summary of the
1032 file's purpose, and a large menu through which the rest of the file is
1033 reached. From this node, you can either traverse the file
1034 systematically by going from node to node, or you can go to a specific
1035 node listed in the main menu, or you can search the index menus and then
1036 go directly to the node that has the information you want. Alternatively,
1037 with the standalone Info program, you can specify specific menu items on
1038 the command line (@pxref{Top,,, info, Info}).
1040 If you want to read through an Info file in sequence, as if it were a
1041 printed manual, you can hit @key{SPC} repeatedly, or you get the whole
1042 file with the advanced Info command @kbd{g *}. (@inforef{Advanced,
1043 Advanced Info commands, info}.)@refill
1045 @c !!! dir file may be located in one of many places:
1046 @c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH
1047 @c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH
1048 @c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH
1050 @c /usr/local/lib/info
1051 The @file{dir} file in the @file{info} directory serves as the
1052 departure point for the whole Info system. From it, you can reach the
1053 `Top' nodes of each of the documents in a complete Info system.@refill
1055 @cindex URI syntax for Info
1056 If you wish to refer to an Info file in a URI, you can use the
1057 (unofficial) syntax exemplified in the following. This works with
1058 Emacs/W3, for example:
1060 info:///usr/info/emacs#Dissociated%20Press
1061 info:emacs#Dissociated%20Press
1062 info://localhost/usr/info/emacs#Dissociated%20Press
1065 The @command{info} program itself does not follow URIs of any kind.
1069 @section Printed Books
1070 @cindex Printed book and manual characteristics
1071 @cindex Manual characteristics, printed
1072 @cindex Book characteristics, printed
1073 @cindex Texinfo printed book characteristics
1074 @cindex Characteristics, printed books or manuals
1076 @cindex Knuth, Donald
1077 A Texinfo file can be formatted and typeset as a printed book or manual.
1078 To do this, you need @TeX{}, a powerful, sophisticated typesetting
1079 program written by Donald Knuth.@footnote{You can also use the
1080 @pindex texi2roff@r{, unsupported software}
1081 @uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
1082 do not have @TeX{}; since Texinfo is designed for use with @TeX{},
1083 @code{texi2roff} is not described here. @code{texi2roff} is not part of
1084 the standard GNU distribution and is not maintained or up-to-date with
1085 all the Texinfo features described in this manual.}
1087 A Texinfo-based book is similar to any other typeset, printed work: it
1088 can have a title page, copyright page, table of contents, and preface,
1089 as well as chapters, numbered or unnumbered sections and subsections,
1090 page headers, cross references, footnotes, and indices.@refill
1092 You can use Texinfo to write a book without ever having the intention
1093 of converting it into online information. You can use Texinfo for
1094 writing a printed novel, and even to write a printed memo, although
1095 this latter application is not recommended since electronic mail is so
1098 @TeX{} is a general purpose typesetting program. Texinfo provides a
1099 file @file{texinfo.tex} that contains information (definitions or
1100 @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
1101 (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
1102 to @TeX{} commands, which @TeX{} can then process to create the typeset
1103 document.) @file{texinfo.tex} contains the specifications for printing
1104 a document. You can get the latest version of @file{texinfo.tex} from
1105 the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
1107 In the United States, documents are most often printed on 8.5 inch by 11
1108 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But
1109 you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
1110 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
1111 (@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
1112 Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
1115 By changing the parameters in @file{texinfo.tex}, you can change the
1116 size of the printed document. In addition, you can change the style in
1117 which the printed document is formatted; for example, you can change the
1118 sizes and fonts used, the amount of indentation for each paragraph, the
1119 degree to which words are hyphenated, and the like. By changing the
1120 specifications, you can make a book look dignified, old and serious, or
1121 light-hearted, young and cheery.
1123 @TeX{} is freely distributable. It is written in a superset of Pascal
1124 called WEB and can be compiled either in Pascal or (by using a
1125 conversion program that comes with the @TeX{} distribution) in C.
1126 (@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
1127 about @TeX{}.)@refill
1129 @TeX{} is very powerful and has a great many features. Because a
1130 Texinfo file must be able to present information both on a
1131 character-only terminal in Info form and in a typeset book, the
1132 formatting commands that Texinfo supports are necessarily limited.
1134 To get a copy of @TeX{}, see
1135 @ref{Obtaining TeX, , How to Obtain @TeX{}}.
1138 @node Formatting Commands
1139 @section @@-commands
1141 @cindex Formatting commands
1143 In a Texinfo file, the commands that tell @TeX{} how to typeset the
1144 printed manual and tell @code{makeinfo} and
1145 @code{texinfo-format-buffer} how to create an Info file are preceded
1146 by @samp{@@}; they are called @dfn{@@-commands}. For example,
1147 @code{@@node} is the command to indicate a node and @code{@@chapter}
1148 is the command to indicate the start of a chapter.@refill
1151 Almost all @@ command names are entirely lower case.
1154 The Texinfo @@-commands are a strictly limited set of constructs. The
1155 strict limits make it possible for Texinfo files to be understood both
1156 by @TeX{} and by the code that converts them into Info files. You can
1157 display Info files on any terminal that displays alphabetic and
1158 numeric characters. Similarly, you can print the output generated by
1159 @TeX{} on a wide variety of printers.@refill
1161 Depending on what they do or what arguments@footnote{The word
1162 @dfn{argument} comes from the way it is used in mathematics and does not
1163 refer to a dispute between two people; it refers to the information
1164 presented to the command. According to the @cite{Oxford English
1165 Dictionary}, the word derives from the Latin for @dfn{to make clear,
1166 prove}; thus it came to mean `the evidence offered as proof', which is
1167 to say, `the information offered', which led to its mathematical
1168 meaning. In its other thread of derivation, the word came to mean `to
1169 assert in a manner against which others may make counter assertions',
1170 which led to the meaning of `argument' as a dispute.} they take, you
1171 need to write @@-commands on lines of their own or as part of
1176 Write a command such as @code{@@quotation} at the beginning of a line as
1177 the only text on the line. (@code{@@quotation} begins an indented
1181 Write a command such as @code{@@chapter} at the beginning of a line
1182 followed by the command's arguments, in this case the chapter title, on
1183 the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
1186 Write a command such as @code{@@dots@{@}} wherever you wish but usually
1187 within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill
1190 Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
1191 wish (but usually within a sentence) with its argument,
1192 @var{sample-code} in this example, between the braces. (@code{@@code}
1193 marks text as being code.)@refill
1196 Write a command such as @code{@@example} on a line of its own; write the
1197 body-text on following lines; and write the matching @code{@@end}
1198 command, @code{@@end example} in this case, on a line of its own
1199 after the body-text. (@code{@@example} @dots{} @code{@@end example}
1200 indents and typesets body-text as an example.) It's usually ok to
1201 indent environment commands like this, but in complicated and
1202 hard-to-define circumstances the extra spaces cause extra space to
1203 appear in the output, so beware.
1207 @cindex Braces, when to use
1208 As a general rule, a command requires braces if it mingles among other
1209 text; but it does not need braces if it starts a line of its own. The
1210 non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1211 they do not need braces.@refill
1213 As you gain experience with Texinfo, you will rapidly learn how to
1214 write the different commands: the different ways to write commands
1215 actually make it easier to write and read Texinfo files than if all
1216 commands followed exactly the same syntax. @xref{Command Syntax, ,
1217 @@-Command Syntax}, for all the details.
1221 @section General Syntactic Conventions
1222 @cindex General syntactic conventions
1223 @cindex Syntactic conventions
1224 @cindex Conventions, syntactic
1225 @cindex Characters, basic input
1227 This section describes the general conventions used in all Texinfo documents.
1231 @cindex Source files, characters used
1232 All printable ASCII characters except @samp{@@}, @samp{@{} and
1233 @samp{@}} can appear in a Texinfo file and stand for themselves.
1234 @samp{@@} is the escape character which introduces commands, while
1235 @samp{@{} and @samp{@}} are used to surround arguments to certain
1236 commands. To put one of these special characters into the document, put
1237 an @samp{@@} character in front of it, like this: @samp{@@@@},
1238 @samp{@@@{}, and @samp{@@@}}.
1241 @cindex Paragraph separator
1242 @cindex Blank lines, as paragraph separator
1243 @cindex Newlines, as blank lines
1244 Separate paragraphs with one or more blank lines. Currently Texinfo
1245 only recognizes newline characters as end of line, not the CRLF
1246 sequence used on some systems; so a @dfn{blank line} means exactly two
1247 consecutive newlines. Sometimes blank lines are useful or convenient
1248 in other cases as well; you can use the @code{@@noindent} to inhibit
1249 paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}).
1252 Texinfo supports the usual quotation marks used in English, and
1253 quotation marks used in other languages, please see @ref{Inserting
1257 @cindex Multiple dashes in source
1258 @cindex Dashes in source
1259 @cindex Hyphens in source, two or three in a row
1260 @cindex Em dash, producing
1261 @cindex En dash, producing
1262 Use three hyphens in a row, @samp{---}, to produce a long dash---like
1263 this (called an @dfn{em dash}), used for punctuation in sentences.
1264 Use two hyphens, @samp{--}, to produce a medium dash (called an
1265 @dfn{en dash}), used primarily for numeric ranges, as in ``June
1266 25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen
1267 used in compound words. For display on the screen, Info reduces three
1268 hyphens to two and two hyphens to one (not transitively!). Of course,
1269 any number of hyphens in the source remain as they are in literal
1270 contexts, such as @code{@@code} and @code{@@example}.
1273 @cindex Tabs; don't use!
1274 @strong{Caution:} Last, do not use tab characters in a Texinfo file
1275 (except in verbatim modes)! @TeX{} uses variable-width fonts, which
1276 means that it is impractical at best to define a tab to work in all
1277 circumstances. Consequently, @TeX{} treats tabs like single spaces,
1278 and that is not what they look like in the source. Furthermore,
1279 @code{makeinfo} does nothing special with tabs, and thus a tab
1280 character in your input file will usually appear differently in the
1284 To avoid this problem, Texinfo mode in GNU Emacs inserts
1285 multiple spaces when you press the @key{TAB} key. Also, you can run
1286 @code{untabify} in Emacs to convert tabs in a region to multiple
1287 spaces, or use the @code{unexpand} command from the shell.
1297 @findex c @r{(comment)}
1299 You can write comments in a Texinfo file that will not appear in
1300 either the Info file or the printed manual by using the
1301 @code{@@comment} command (which may be abbreviated to @code{@@c}).
1302 Such comments are for the person who revises the Texinfo file. All the
1303 text on a line that follows either @code{@@comment} or @code{@@c} is a
1304 comment; the rest of the line does not appear in either the Info file
1305 or the printed manual.
1307 Often, you can write the @code{@@comment} or @code{@@c} in the middle of
1308 a line, and only the text that follows after the @code{@@comment} or
1309 @code{@@c} command does not appear; but some commands, such as
1310 @code{@@settitle} and @code{@@setfilename}, work on a whole line. You
1311 cannot use @code{@@comment} or @code{@@c} in a line beginning with such
1314 @cindex Ignored text
1315 @cindex Unprocessed text
1317 You can write long stretches of text that will not appear in either
1318 the Info file or the printed manual by using the @code{@@ignore} and
1319 @code{@@end ignore} commands. Write each of these commands on a line
1320 of its own, starting each command at the beginning of the line. Text
1321 between these two commands does not appear in the processed output.
1322 You can use @code{@@ignore} and @code{@@end ignore} for writing
1325 Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1326 @code{@@ifclear} conditions is ignored in the sense that it will not
1327 contribute to the formatted output. However, @TeX{} and makeinfo must
1328 still parse the ignored text, in order to understand when to @emph{stop}
1329 ignoring text from the source file; that means that you may still get
1330 error messages if you have invalid Texinfo commands within ignored text.
1334 @section What a Texinfo File Must Have
1335 @cindex Minimal Texinfo file (requirements)
1336 @cindex Must have in Texinfo file
1337 @cindex Required in Texinfo file
1338 @cindex Texinfo file minimum
1340 By convention, the name of a Texinfo file ends with (in order of
1341 preference) one of the extensions @file{.texinfo}, @file{.texi},
1342 @file{.txi}, or @file{.tex}. The longer extensions are preferred since
1343 they describe more clearly to a human reader the nature of the file.
1344 The shorter extensions are for operating systems that cannot handle long
1347 In order to be made into a printed manual and an Info file, a Texinfo
1348 file @strong{must} begin with lines like this:
1353 @@setfilename @var{info-file-name}
1354 @@settitle @var{name-of-manual}
1359 The contents of the file follow this beginning, and then you
1360 @strong{must} end a Texinfo file with a line like this:
1366 @findex \input @r{(raw @TeX{} startup)}
1368 Here's an explanation:
1372 The @samp{\input texinfo} line tells @TeX{} to use the
1373 @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1374 @@-commands into @TeX{} typesetting commands. (Note the use of the
1375 backslash, @samp{\}; this is correct for @TeX{}.)
1378 The @code{@@setfilename} line provides a name for the Info file and
1379 tells @TeX{} to open auxiliary files. @strong{All text before
1380 @code{@@setfilename} is ignored!}
1383 The @code{@@settitle} line specifies a title for the page headers (or
1384 footers) of the printed manual, and the default document description for
1385 the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
1386 is optional---if you don't mind your document being titled `Untitled'.
1389 The @code{@@bye} line at the end of the file on a line of its own tells
1390 the formatters that the file is ended and to stop formatting.
1394 Typically, you will not use quite such a spare format, but will include
1395 mode setting and start-of-header and end-of-header lines at the
1396 beginning of a Texinfo file, like this:
1400 \input texinfo @@c -*-texinfo-*-
1401 @@c %**start of header
1402 @@setfilename @var{info-file-name}
1403 @@settitle @var{name-of-manual}
1404 @@c %**end of header
1409 In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
1410 Texinfo mode when you edit the file.
1412 The @code{@@c} lines which surround the @code{@@setfilename} and
1413 @code{@@settitle} lines are optional, but you need them in order to
1414 run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
1416 Furthermore, you will usually provide a Texinfo file with a title page,
1417 indices, and the like, all of which are explained in this manual. But
1418 the minimum, which can be useful for short documents, is just the three
1419 lines at the beginning and the one line at the end.
1423 @section Six Parts of a Texinfo File
1425 Generally, a Texinfo file contains more than the minimal beginning and
1426 end described in the previous section---it usually contains the six
1427 parts listed below. These are described fully in the following sections.
1431 The @dfn{Header} names the file, tells @TeX{} which definitions file to
1432 use, and other such housekeeping tasks.
1434 @item 2. Summary and Copyright
1435 The @dfn{Summary and Copyright} segment describes the document and
1436 contains the copyright notice and copying permissions. This is done
1437 with the @code{@@copying} command.
1439 @item 3. Title and Copyright
1440 The @dfn{Title and Copyright} segment contains the title and copyright
1441 pages for the printed manual. The segment must be enclosed between
1442 @code{@@titlepage} and @code{@@end titlepage} commands. The title and
1443 copyright page appear only in the printed manual.
1445 @item 4. `Top' Node and Master Menu
1446 The `Top' node starts off the online output; it does not appear in the
1447 printed manual. We recommend including the copying permissions here as
1448 well as the segments above. And it contains at least a top-level menu
1449 listing the chapters, and possibly a @dfn{Master Menu} listing all the
1450 nodes in the entire document.
1453 The @dfn{Body} of the document is typically structured like a
1454 traditional book or encyclopedia, but it may be free form.
1457 The @dfn{End} segment may contain commands for printing indices, and
1458 closes with the @code{@@bye} command on a line of its own.
1463 @section A Short Sample Texinfo File
1464 @cindex Sample Texinfo file, with comments
1466 Here is a very short but complete Texinfo file, in the six conventional
1467 parts enumerated in the previous section, so you can see how Texinfo
1468 source appears in practice. The first three parts of the file, from
1469 @samp{\input texinfo} through to @samp{@@end titlepage}, look more
1470 intimidating than they are: most of the material is standard
1471 boilerplate; when writing a manual, you simply change the names as
1474 @xref{Beginning a File}, for full documentation on the commands listed
1475 here. @xref{GNU Sample Texts}, for the full texts to be used in GNU
1478 In the following, the sample text is @emph{indented}; comments on it are
1479 not. The complete file, without interspersed comments, is shown in
1480 @ref{Short Sample Texinfo File}.
1482 @subheading Part 1: Header
1485 The header does not appear in either the Info file or the
1486 printed output. It sets various parameters, including the
1487 name of the Info file and the title used in the header.
1491 \input texinfo @@c -*-texinfo-*-
1492 @@c %**start of header
1493 @@setfilename sample.info
1494 @@settitle Sample Manual 1.0
1495 @@c %**end of header
1499 @subheading Part 2: Summary Description and Copyright
1502 A real manual includes more text here, according to the license under
1503 which it is distributed. @xref{GNU Sample Texts}.
1508 This is a short example of a complete Texinfo file, version 1.0.
1510 Copyright @@copyright@{@} 2005 Free Software Foundation, Inc.
1515 @subheading Part 3: Titlepage, Contents, Copyright
1518 The titlepage segment does not appear in the online output, only in the
1519 printed manual. We use the @code{@@insertcopying} command to
1520 include the permission text from the previous section, instead of
1521 writing it out again; it is output on the back of the title page. The
1522 @code{@@contents} command generates a table of contents.
1527 @@title Sample Title
1531 @@c The following two commands start the copyright page.
1533 @@vskip 0pt plus 1filll
1538 @@c Output the table of contents at the beginning.
1542 @subheading Part 4: `Top' Node and Master Menu
1545 The `Top' node contains the master menu for the Info file. Since the
1546 printed manual uses a table of contents rather than a menu, it
1547 excludes the `Top' node. We repeat the short description from the
1548 beginning of the @samp{@@copying} text, but there's no need to repeat
1549 the copyright information, so we don't use @samp{@@insertcopying} here.
1550 The @samp{@@top} command itself helps @command{makeinfo} determine the
1551 relationships between nodes.
1558 This is a short sample Texinfo file.
1563 * First Chapter:: The first chapter is the
1564 only chapter in this sample.
1565 * Index:: Complete index.
1571 @subheading Part 5: The Body of the Document
1574 The body segment contains all the text of the document, but not the
1575 indices or table of contents. This example illustrates a node and a
1576 chapter containing an enumerated list.
1580 @@node First Chapter
1581 @@chapter First Chapter
1583 @@cindex chapter, first
1587 This is the first chapter.
1588 @@cindex index entry, another
1592 Here is a numbered list.
1596 This is the first item.
1599 This is the second item.
1605 @subheading Part 6: The End of the Document
1608 The end segment contains commands for generating an index in a node and
1609 unnumbered chapter of its own, and the @code{@@bye} command that marks
1610 the end of the document.
1626 @subheading Some Results
1628 Here is what the contents of the first chapter of the sample look like:
1633 This is the first chapter.
1635 Here is a numbered list.
1639 This is the first item.
1642 This is the second item.
1650 @cindex Stallman, Richard M.
1651 @cindex Chassell, Robert J.
1654 Richard M. Stallman invented the Texinfo format, wrote the initial
1655 processors, and created Edition 1.0 of this manual. Robert@tie{}J.
1656 Chassell greatly revised and extended the manual, starting with
1657 Edition 1.1. Brian Fox was responsible for the standalone Texinfo
1658 distribution until version 3.8, and wrote the standalone
1659 @command{makeinfo} and @command{info} programs. Karl Berry has
1660 continued maintenance since Texinfo 3.8 (manual edition 2.22).
1662 @cindex Pinard, Fran@,{c}ois
1663 @cindex Zuhn, David D.
1664 @cindex Weisshaus, Melissa
1665 @cindex Zaretskii, Eli
1666 @cindex Schwab, Andreas
1667 @cindex Weinberg, Zack
1668 Our thanks go out to all who helped improve this work, particularly the
1669 indefatigable Eli Zaretskii and Andreas Schwab, who have provided
1670 patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn,
1671 tirelessly recorded and reported mistakes and obscurities. Zack
1672 Weinberg did the impossible by implementing the macro syntax in
1673 @file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her
1674 frequent reviews of nearly similar editions. Dozens of others have
1675 contributed patches and suggestions, they are gratefully acknowledged in
1676 the @file{ChangeLog} file. Our mistakes are our own.
1680 @cindex History of Texinfo
1681 @cindex Texinfo history
1682 A bit of history: in the 1970's at CMU, Brian Reid developed a program
1683 and format named Scribe to mark up documents for printing. It used the
1684 @code{@@} character to introduce commands, as Texinfo does. Much more
1685 consequentially, it strove to describe document contents rather than
1686 formatting, an idea wholeheartedly adopted by Texinfo.
1690 Meanwhile, people at MIT developed another, not too dissimilar format
1691 called Bolio. This then was converted to using @TeX{} as its typesetting
1692 language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been
1693 0.02 on October 31, 1984.
1695 Bo@TeX{} could only be used as a markup language for documents to be
1696 printed, not for online documents. Richard Stallman (RMS) worked on
1697 both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1698 called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
1699 mark up language for text that is intended to be read both online and
1700 as printed hard copy.
1704 @chapter Using Texinfo Mode
1705 @cindex Texinfo mode
1706 @cindex Mode, using Texinfo
1710 You may edit a Texinfo file with any text editor you choose. A Texinfo
1711 file is no different from any other ASCII file. However, GNU Emacs
1712 comes with a special mode, called Texinfo mode, that provides Emacs
1713 commands and tools to help ease your work.
1715 This chapter describes features of GNU Emacs' Texinfo mode but not any
1716 features of the Texinfo formatting language. So if you are reading this
1717 manual straight through from the beginning, you may want to skim through
1718 this chapter briefly and come back to it after reading succeeding
1719 chapters which describe the Texinfo formatting language in detail.
1722 * Texinfo Mode Overview:: How Texinfo mode can help you.
1723 * Emacs Editing:: Texinfo mode adds to GNU Emacs' general
1724 purpose editing features.
1725 * Inserting:: How to insert frequently used @@-commands.
1726 * Showing the Structure:: How to show the structure of a file.
1727 * Updating Nodes and Menus:: How to update or create new nodes and menus.
1728 * Info Formatting:: How to format for Info.
1729 * Printing:: How to format and print part or all of a file.
1730 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
1733 @node Texinfo Mode Overview
1734 @section Texinfo Mode Overview
1736 Texinfo mode provides special features for working with Texinfo files.
1741 Insert frequently used @@-commands. @refill
1744 Automatically create @code{@@node} lines.
1747 Show the structure of a Texinfo source file.@refill
1750 Automatically create or update the `Next',
1751 `Previous', and `Up' pointers of a node.
1754 Automatically create or update menus.@refill
1757 Automatically create a master menu.@refill
1760 Format a part or all of a file for Info.@refill
1763 Typeset and print part or all of a file.@refill
1766 Perhaps the two most helpful features are those for inserting frequently
1767 used @@-commands and for creating node pointers and menus.@refill
1770 @section The Usual GNU Emacs Editing Commands
1772 In most cases, the usual Text mode commands work the same in Texinfo
1773 mode as they do in Text mode. Texinfo mode adds new editing commands
1774 and tools to GNU Emacs' general purpose editing features. The major
1775 difference concerns filling. In Texinfo mode, the paragraph
1776 separation variable and syntax table are redefined so that Texinfo
1777 commands that should be on lines of their own are not inadvertently
1778 included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
1779 command will refill a paragraph but not mix an indexing command on a
1780 line adjacent to it into the paragraph.@refill
1782 In addition, Texinfo mode sets the @code{page-delimiter} variable to
1783 the value of @code{texinfo-chapter-level-regexp}; by default, this is
1784 a regular expression matching the commands for chapters and their
1785 equivalents, such as appendices. With this value for the page
1786 delimiter, you can jump from chapter title to chapter title with the
1787 @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1788 (@code{backward-page}) commands and narrow to a chapter with the
1789 @kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs,
1790 The GNU Emacs Manual}, for details about the page commands.)@refill
1792 You may name a Texinfo file however you wish, but the convention is to
1793 end a Texinfo file name with one of the extensions
1794 @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
1795 extension is preferred, since it is explicit, but a shorter extension
1796 may be necessary for operating systems that limit the length of file
1797 names. GNU Emacs automatically enters Texinfo mode when you visit a
1798 file with a @file{.texinfo}, @file{.texi} or @file{.txi}
1799 extension. Also, Emacs switches to Texinfo mode
1801 file that has @samp{-*-texinfo-*-} in its first line. If ever you are
1802 in another mode and wish to switch to Texinfo mode, type @code{M-x
1803 texinfo-mode}.@refill
1805 Like all other Emacs features, you can customize or enhance Texinfo
1806 mode as you wish. In particular, the keybindings are very easy to
1807 change. The keybindings described here are the default or standard
1811 @comment node-name, next, previous, up
1812 @section Inserting Frequently Used Commands
1813 @cindex Inserting frequently used commands
1814 @cindex Frequently used commands, inserting
1815 @cindex Commands, inserting them
1817 Texinfo mode provides commands to insert various frequently used
1818 @@-commands into the buffer. You can use these commands to save
1821 The insert commands are invoked by typing @kbd{C-c} twice and then the
1822 first letter of the @@-command:@refill
1826 @itemx M-x texinfo-insert-@@code
1827 @findex texinfo-insert-@@code
1828 Insert @code{@@code@{@}} and put the
1829 cursor between the braces.@refill
1832 @itemx M-x texinfo-insert-@@dfn
1833 @findex texinfo-insert-@@dfn
1834 Insert @code{@@dfn@{@}} and put the
1835 cursor between the braces.@refill
1838 @itemx M-x texinfo-insert-@@end
1839 @findex texinfo-insert-@@end
1840 Insert @code{@@end} and attempt to insert the correct following word,
1841 such as @samp{example} or @samp{table}. (This command does not handle
1842 nested lists correctly, but inserts the word appropriate to the
1843 immediately preceding list.)@refill
1846 @itemx M-x texinfo-insert-@@item
1847 @findex texinfo-insert-@@item
1848 Insert @code{@@item} and put the
1849 cursor at the beginning of the next line.@refill
1852 @itemx M-x texinfo-insert-@@kbd
1853 @findex texinfo-insert-@@kbd
1854 Insert @code{@@kbd@{@}} and put the
1855 cursor between the braces.@refill
1858 @itemx M-x texinfo-insert-@@node
1859 @findex texinfo-insert-@@node
1860 Insert @code{@@node} and a comment line
1861 listing the sequence for the `Next',
1862 `Previous', and `Up' nodes.
1863 Leave point after the @code{@@node}.@refill
1866 @itemx M-x texinfo-insert-@@noindent
1867 @findex texinfo-insert-@@noindent
1868 Insert @code{@@noindent} and put the
1869 cursor at the beginning of the next line.@refill
1872 @itemx M-x texinfo-insert-@@samp
1873 @findex texinfo-insert-@@samp
1874 Insert @code{@@samp@{@}} and put the
1875 cursor between the braces.@refill
1878 @itemx M-x texinfo-insert-@@table
1879 @findex texinfo-insert-@@table
1880 Insert @code{@@table} followed by a @key{SPC}
1881 and leave the cursor after the @key{SPC}.@refill
1884 @itemx M-x texinfo-insert-@@var
1885 @findex texinfo-insert-@@var
1886 Insert @code{@@var@{@}} and put the
1887 cursor between the braces.@refill
1890 @itemx M-x texinfo-insert-@@example
1891 @findex texinfo-insert-@@example
1892 Insert @code{@@example} and put the
1893 cursor at the beginning of the next line.@refill
1895 @c M-@{ was the binding for texinfo-insert-braces;
1896 @c in Emacs 19, backward-paragraph will take this binding.
1898 @itemx M-x texinfo-insert-braces
1899 @findex texinfo-insert-braces
1900 Insert @code{@{@}} and put the cursor between the braces.@refill
1906 Move from between a pair of braces forward past the closing brace.
1907 Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which
1908 is, however, more mnemonic; hence the two keybindings. (Also, you can
1909 move out from between braces by typing @kbd{C-f}.)@refill
1912 To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1913 @emph{existing} word, position the cursor in front of the word and type
1914 @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
1915 The value of the prefix argument tells Emacs how many words following
1916 point to include between braces---@samp{1} for one word, @samp{2} for
1917 two words, and so on. Use a negative argument to enclose the previous
1918 word or words. If you do not specify a prefix argument, Emacs inserts
1919 the @@-command string and positions the cursor between the braces. This
1920 feature works only for those @@-commands that operate on a word or words
1921 within one line, such as @code{@@kbd} and @code{@@var}.@refill
1923 This set of insert commands was created after analyzing the frequency
1924 with which different @@-commands are used in the @cite{GNU Emacs
1925 Manual} and the @cite{GDB Manual}. If you wish to add your own insert
1926 commands, you can bind a keyboard macro to a key, use abbreviations,
1927 or extend the code in @file{texinfo.el}.@refill
1929 @findex texinfo-start-menu-description
1930 @cindex Menu description, start
1931 @cindex Description for menu, start
1932 @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1933 command that works differently from the other insert commands. It
1934 inserts a node's section or chapter title in the space for the
1935 description in a menu entry line. (A menu entry has three parts, the
1936 entry name, the node name, and the description. Only the node name is
1937 required, but a description helps explain what the node is about.
1938 @xref{Menu Parts, , The Parts of a Menu}.)@refill
1940 To use @code{texinfo-start-menu-description}, position point in a menu
1941 entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
1942 the title that goes with the node name, and inserts the title as a
1943 description; it positions point at beginning of the inserted text so you
1944 can edit it. The function does not insert the title if the menu entry
1945 line already contains a description.@refill
1947 This command is only an aid to writing descriptions; it does not do the
1948 whole job. You must edit the inserted text since a title tends to use
1949 the same words as a node name but a useful description uses different
1952 @node Showing the Structure
1953 @comment node-name, next, previous, up
1954 @section Showing the Section Structure of a File
1955 @cindex Showing the section structure of a file
1956 @cindex Section structure of a file, showing it
1957 @cindex Structure of a file, showing it
1958 @cindex Outline of file structure, showing it
1959 @cindex Contents-like outline of file structure
1960 @cindex File section structure, showing it
1961 @cindex Texinfo file section structure, showing it
1963 You can show the section structure of a Texinfo file by using the
1964 @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
1965 shows the section structure of a Texinfo file by listing the lines
1966 that begin with the @@-commands for @code{@@chapter},
1967 @code{@@section}, and the like. It constructs what amounts
1968 to a table of contents. These lines are displayed in another buffer
1969 called the @samp{*Occur*} buffer. In that buffer, you can position
1970 the cursor over one of the lines and use the @kbd{C-c C-c} command
1971 (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1972 in the Texinfo file.@refill
1976 @itemx M-x texinfo-show-structure
1977 @findex texinfo-show-structure
1978 Show the @code{@@chapter}, @code{@@section}, and such lines of a
1979 Texinfo file.@refill
1982 @itemx M-x occur-mode-goto-occurrence
1983 @findex occur-mode-goto-occurrence
1984 Go to the line in the Texinfo file corresponding to the line under the
1985 cursor in the @file{*Occur*} buffer.@refill
1988 If you call @code{texinfo-show-structure} with a prefix argument by
1989 typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1990 @@-commands for @code{@@chapter}, @code{@@section}, and the like, but
1991 also the @code{@@node} lines. You can use @code{texinfo-show-structure}
1992 with a prefix argument to check whether the `Next', `Previous', and `Up'
1993 pointers of an @code{@@node} line are correct.
1995 Often, when you are working on a manual, you will be interested only
1996 in the structure of the current chapter. In this case, you can mark
1997 off the region of the buffer that you are interested in by using the
1998 @kbd{C-x n n} (@code{narrow-to-region}) command and
1999 @code{texinfo-show-structure} will work on only that region. To see
2000 the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
2001 (@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
2002 information about the narrowing commands.)@refill
2004 @vindex page-delimiter
2005 @cindex Page delimiter in Texinfo mode
2006 In addition to providing the @code{texinfo-show-structure} command,
2007 Texinfo mode sets the value of the page delimiter variable to match
2008 the chapter-level @@-commands. This enables you to use the @kbd{C-x
2009 ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
2010 commands to move forward and backward by chapter, and to use the
2011 @kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter.
2012 @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
2013 about the page commands.@refill
2015 @node Updating Nodes and Menus
2016 @comment node-name, next, previous, up
2017 @section Updating Nodes and Menus
2018 @cindex Updating nodes and menus
2019 @cindex Create nodes, menus automatically
2020 @cindex Insert nodes, menus automatically
2021 @cindex Automatically insert nodes, menus
2023 Texinfo mode provides commands for automatically creating or updating
2024 menus and node pointers. The commands are called ``update'' commands
2025 because their most frequent use is for updating a Texinfo file after you
2026 have worked on it; but you can use them to insert the `Next',
2027 `Previous', and `Up' pointers into an @code{@@node} line that has none
2028 and to create menus in a file that has none.
2030 If you do not use the updating commands, you need to write menus and
2031 node pointers by hand, which is a tedious task.@refill
2034 * Updating Commands:: Five major updating commands.
2035 * Updating Requirements:: How to structure a Texinfo file for
2036 using the updating command.
2037 * Other Updating Commands:: How to indent descriptions, insert
2038 missing nodes lines, and update
2042 @node Updating Commands
2043 @subsection The Updating Commands
2045 You can use the updating commands to:@refill
2049 insert or update the `Next', `Previous', and `Up' pointers of a
2053 insert or update the menu for a section, and@refill
2056 create a master menu for a Texinfo source file.@refill
2059 You can also use the commands to update all the nodes and menus in a
2060 region or in a whole Texinfo file.@refill
2062 The updating commands work only with conventional Texinfo files, which
2063 are structured hierarchically like books. In such files, a structuring
2064 command line must follow closely after each @code{@@node} line, except
2065 for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
2066 a line beginning with @code{@@chapter}, @code{@@section}, or other
2069 You can write the structuring command line on the line that follows
2070 immediately after an @code{@@node} line or else on the line that
2071 follows after a single @code{@@comment} line or a single
2072 @code{@@ifinfo} line. You cannot interpose more than one line between
2073 the @code{@@node} line and the structuring command line; and you may
2074 interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
2076 Commands which work on a whole buffer require that the `Top' node be
2077 followed by a node with an @code{@@chapter} or equivalent-level command.
2078 The menu updating commands will not create a main or master menu for a
2079 Texinfo file that has only @code{@@chapter}-level nodes! The menu
2080 updating commands only create menus @emph{within} nodes for lower level
2081 nodes. To create a menu of chapters, you must provide a `Top'
2084 The menu updating commands remove menu entries that refer to other Info
2085 files since they do not refer to nodes within the current buffer. This
2086 is a deficiency. Rather than use menu entries, you can use cross
2087 references to refer to other Info files. None of the updating commands
2088 affect cross references.@refill
2090 Texinfo mode has five updating commands that are used most often: two
2091 are for updating the node pointers or menu of a single node (or a
2092 region); two are for updating every node pointer and menu in a file;
2093 and one, the @code{texinfo-master-menu} command, is for creating a
2094 master menu for a complete file, and optionally, for updating every
2095 node and menu in the whole Texinfo file.@refill
2097 The @code{texinfo-master-menu} command is the primary command:@refill
2101 @itemx M-x texinfo-master-menu
2102 @findex texinfo-master-menu
2103 Create or update a master menu that includes all the other menus
2104 (incorporating the descriptions from pre-existing menus, if
2107 With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
2108 update all the nodes and all the regular menus in the buffer before
2109 constructing the master menu. (@xref{The Top Node, , The Top Node and
2110 Master Menu}, for more about a master menu.)@refill
2112 For @code{texinfo-master-menu} to work, the Texinfo file must have a
2113 `Top' node and at least one subsequent node.@refill
2115 After extensively editing a Texinfo file, you can type the following:
2118 C-u M-x texinfo-master-menu
2124 This updates all the nodes and menus completely and all at once.@refill
2127 The other major updating commands do smaller jobs and are designed for
2128 the person who updates nodes and menus as he or she writes a Texinfo
2132 The commands are:@refill
2136 @itemx M-x texinfo-update-node
2137 @findex texinfo-update-node
2138 Insert the `Next', `Previous', and `Up' pointers for the node that point is
2139 within (i.e., for the @code{@@node} line preceding point). If the
2140 @code{@@node} line has pre-existing `Next', `Previous', or `Up'
2141 pointers in it, the old pointers are removed and new ones inserted.
2142 With an argument (prefix argument, @kbd{C-u}, if interactive), this command
2143 updates all @code{@@node} lines in the region (which is the text
2144 between point and mark).@refill
2147 @itemx M-x texinfo-make-menu
2148 @findex texinfo-make-menu
2149 Create or update the menu in the node that point is within.
2150 With an argument (@kbd{C-u} as prefix argument, if
2151 interactive), the command makes or updates menus for the
2152 nodes which are either within or a part of the
2155 Whenever @code{texinfo-make-menu} updates an existing menu, the
2156 descriptions from that menu are incorporated into the new menu. This
2157 is done by copying descriptions from the existing menu to the entries
2158 in the new menu that have the same node names. If the node names are
2159 different, the descriptions are not copied to the new menu.@refill
2162 @itemx M-x texinfo-every-node-update
2163 @findex texinfo-every-node-update
2164 Insert or update the `Next', `Previous', and `Up' pointers for every
2165 node in the buffer.@refill
2168 @itemx M-x texinfo-all-menus-update
2169 @findex texinfo-all-menus-update
2170 Create or update all the menus in the buffer. With an argument
2171 (@kbd{C-u} as prefix argument, if interactive), first insert
2172 or update all the node
2173 pointers before working on the menus.@refill
2175 If a master menu exists, the @code{texinfo-all-menus-update} command
2176 updates it; but the command does not create a new master menu if none
2177 already exists. (Use the @code{texinfo-master-menu} command for
2180 When working on a document that does not merit a master menu, you can
2186 C-u M-x texinfo-all-menus-update
2190 This updates all the nodes and menus.@refill
2193 The @code{texinfo-column-for-description} variable specifies the
2194 column to which menu descriptions are indented. By default, the value
2195 is 32 although it can be useful to reduce it to as low as 24. You
2196 can set the variable via customization (@pxref{Changing an Option,,,
2197 emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable}
2198 command (@pxref{Examining, , Examining and Setting Variables, emacs,
2199 The GNU Emacs Manual}).
2201 Also, the @code{texinfo-indent-menu-description} command may be used to
2202 indent existing menu descriptions to a specified column. Finally, if
2203 you wish, you can use the @code{texinfo-insert-node-lines} command to
2204 insert missing @code{@@node} lines into a file. (@xref{Other Updating
2205 Commands}, for more information.)@refill
2207 @node Updating Requirements
2208 @subsection Updating Requirements
2209 @cindex Updating requirements
2210 @cindex Requirements for updating commands
2212 To use the updating commands, you must organize the Texinfo file
2213 hierarchically with chapters, sections, subsections, and the like.
2214 When you construct the hierarchy of the manual, do not `jump down'
2215 more than one level at a time: you can follow the `Top' node with a
2216 chapter, but not with a section; you can follow a chapter with a
2217 section, but not with a subsection. However, you may `jump up' any
2218 number of levels at one time---for example, from a subsection to a
2221 Each @code{@@node} line, with the exception of the line for the `Top'
2222 node, must be followed by a line with a structuring command such as
2223 @code{@@chapter}, @code{@@section}, or
2224 @code{@@unnumberedsubsec}.@refill
2226 Each @code{@@node} line/structuring-command line combination
2227 must look either like this:
2231 @@node Comments, Minimum, Conventions, Overview
2232 @@comment node-name, next, previous, up
2237 or like this (without the @code{@@comment} line):
2241 @@node Comments, Minimum, Conventions, Overview
2246 or like this (without the explicit node pointers):
2256 In this example, `Comments' is the name of both the node and the
2257 section. The next node is called `Minimum' and the previous node is
2258 called `Conventions'. The `Comments' section is within the `Overview'
2259 node, which is specified by the `Up' pointer. (Instead of an
2260 @code{@@comment} line, you may also write an @code{@@ifinfo} line.)
2262 If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2263 and be the first node in the file.
2265 The menu updating commands create a menu of sections within a chapter,
2266 a menu of subsections within a section, and so on. This means that
2267 you must have a `Top' node if you want a menu of chapters.@refill
2269 Incidentally, the @code{makeinfo} command will create an Info file for a
2270 hierarchically organized Texinfo file that lacks `Next', `Previous' and
2271 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
2272 formatted with @code{makeinfo}, you have no need for the update node
2273 commands. (@xref{Creating an Info File}, for more information about
2274 @code{makeinfo}.) However, both @code{makeinfo} and the
2275 @code{texinfo-format-@dots{}} commands require that you insert menus in
2279 @node Other Updating Commands
2280 @subsection Other Updating Commands
2282 In addition to the five major updating commands, Texinfo mode
2283 possesses several less frequently used updating commands:@refill
2286 @item M-x texinfo-insert-node-lines
2287 @findex texinfo-insert-node-lines
2288 Insert @code{@@node} lines before the @code{@@chapter},
2289 @code{@@section}, and other sectioning commands wherever they are
2290 missing throughout a region in a Texinfo file.@refill
2292 With an argument (@kbd{C-u} as prefix argument, if interactive), the
2293 @code{texinfo-insert-node-lines} command not only inserts
2294 @code{@@node} lines but also inserts the chapter or section titles as
2295 the names of the corresponding nodes. In addition, it inserts the
2296 titles as node names in pre-existing @code{@@node} lines that lack
2297 names. Since node names should be more concise than section or
2298 chapter titles, you must manually edit node names so inserted.@refill
2300 For example, the following marks a whole buffer as a region and inserts
2301 @code{@@node} lines and titles throughout:@refill
2304 C-x h C-u M-x texinfo-insert-node-lines
2307 This command inserts titles as node names in @code{@@node} lines; the
2308 @code{texinfo-start-menu-description} command (@pxref{Inserting,
2309 Inserting Frequently Used Commands}) inserts titles as descriptions in
2310 menu entries, a different action. However, in both cases, you need to
2311 edit the inserted text.
2313 @item M-x texinfo-multiple-files-update
2314 @findex texinfo-multiple-files-update @r{(in brief)}
2315 Update nodes and menus in a document built from several separate files.
2316 With @kbd{C-u} as a prefix argument, create and insert a master menu in
2317 the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
2318 update all the menus and all the `Next', `Previous', and `Up' pointers
2319 of all the included files before creating and inserting a master menu in
2320 the outer file. The @code{texinfo-multiple-files-update} command is
2321 described in the appendix on @code{@@include} files.
2322 @xref{texinfo-multiple-files-update}.
2324 @item M-x texinfo-indent-menu-description
2325 @findex texinfo-indent-menu-description
2326 Indent every description in the menu following point to the specified
2327 column. You can use this command to give yourself more space for
2328 descriptions. With an argument (@kbd{C-u} as prefix argument, if
2329 interactive), the @code{texinfo-indent-menu-description} command indents
2330 every description in every menu in the region. However, this command
2331 does not indent the second and subsequent lines of a multi-line
2334 @item M-x texinfo-sequential-node-update
2335 @findex texinfo-sequential-node-update
2336 Insert the names of the nodes immediately following and preceding the
2337 current node as the `Next' or `Previous' pointers regardless of those
2338 nodes' hierarchical level. This means that the `Next' node of a
2339 subsection may well be the next chapter. Sequentially ordered nodes are
2340 useful for novels and other documents that you read through
2341 sequentially. (However, in Info, the @kbd{g *} command lets
2342 you look through the file sequentially, so sequentially ordered nodes
2343 are not strictly necessary.) With an argument (prefix argument, if
2344 interactive), the @code{texinfo-sequential-node-update} command
2345 sequentially updates all the nodes in the region.@refill
2348 @node Info Formatting
2349 @comment node-name, next, previous, up
2350 @section Formatting for Info
2351 @cindex Formatting for Info
2352 @cindex Running an Info formatter
2353 @cindex Info formatting
2355 Texinfo mode provides several commands for formatting part or all of a
2356 Texinfo file for Info. Often, when you are writing a document, you
2357 want to format only part of a file---that is, a region.@refill
2359 You can use either the @code{texinfo-format-region} or the
2360 @code{makeinfo-region} command to format a region:@refill
2363 @findex texinfo-format-region
2365 @itemx M-x texinfo-format-region
2367 @itemx M-x makeinfo-region
2368 Format the current region for Info.@refill
2371 You can use either the @code{texinfo-format-buffer} or the
2372 @code{makeinfo-buffer} command to format a whole buffer:@refill
2375 @findex texinfo-format-buffer
2377 @itemx M-x texinfo-format-buffer
2379 @itemx M-x makeinfo-buffer
2380 Format the current buffer for Info.@refill
2384 For example, after writing a Texinfo file, you can type the following:
2389 C-u M-x texinfo-master-menu
2393 This updates all the nodes and menus. Then type the following to create
2402 For @TeX{} or the Info formatting commands to work, the file @emph{must}
2403 include a line that has @code{@@setfilename} in its header.
2405 @xref{Creating an Info File}, for details about Info formatting.@refill
2408 @comment node-name, next, previous, up
2410 @cindex Formatting for printing
2411 @cindex Printing a region or buffer
2412 @cindex Region formatting and printing
2413 @cindex Buffer formatting and printing
2414 @cindex Part of file formatting and printing
2416 Typesetting and printing a Texinfo file is a multi-step process in which
2417 you first create a file for printing (called a DVI file), and then
2418 print the file. Optionally, you may also create indices. To do this,
2419 you must run the @code{texindex} command after first running the
2420 @code{tex} typesetting command; and then you must run the @code{tex}
2421 command again. Or else run the @code{texi2dvi} command which
2422 automatically creates indices as needed (@pxref{Format with texi2dvi}).
2424 Often, when you are writing a document, you want to typeset and print
2425 only part of a file to see what it will look like. You can use the
2426 @code{texinfo-tex-region} and related commands for this purpose. Use
2427 the @code{texinfo-tex-buffer} command to format all of a
2432 @itemx M-x texinfo-tex-buffer
2433 @findex texinfo-tex-buffer
2434 Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
2435 buffer, this command automatically creates or updates indices as
2439 @itemx M-x texinfo-tex-region
2440 @findex texinfo-tex-region
2441 Run @TeX{} on the region.@refill
2444 @itemx M-x texinfo-texindex
2445 Run @code{texindex} to sort the indices of a Texinfo file formatted with
2446 @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
2447 not run @code{texindex} automatically; it only runs the @code{tex}
2448 typesetting command. You must run the @code{texinfo-tex-region} command
2449 a second time after sorting the raw index files with the @code{texindex}
2450 command. (Usually, you do not format an index when you format a region,
2451 only when you format a buffer. Now that the @code{texi2dvi} command
2452 exists, there is little or no need for this command.)@refill
2455 @itemx M-x texinfo-tex-print
2456 @findex texinfo-tex-print
2457 Print the file (or the part of the file) previously formatted with
2458 @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2461 For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2462 file @emph{must} start with a @samp{\input texinfo} line and must
2463 include an @code{@@settitle} line. The file must end with @code{@@bye}
2464 on a line by itself. (When you use @code{texinfo-tex-region}, you must
2465 surround the @code{@@settitle} line with start-of-header and
2466 end-of-header lines.)@refill
2468 @xref{Hardcopy}, for a description of the other @TeX{} related
2469 commands, such as @code{tex-show-print-queue}.@refill
2471 @node Texinfo Mode Summary
2472 @comment node-name, next, previous, up
2473 @section Texinfo Mode Summary
2475 In Texinfo mode, each set of commands has default keybindings that
2476 begin with the same keys. All the commands that are custom-created
2477 for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
2480 @subheading Insert Commands
2482 The insert commands are invoked by typing @kbd{C-c} twice and then the
2483 first letter of the @@-command to be inserted. (It might make more
2484 sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2485 @kbd{C-c C-c} is quick to type.)@refill
2488 C-c C-c c @r{Insert} @samp{@@code}.
2489 C-c C-c d @r{Insert} @samp{@@dfn}.
2490 C-c C-c e @r{Insert} @samp{@@end}.
2491 C-c C-c i @r{Insert} @samp{@@item}.
2492 C-c C-c n @r{Insert} @samp{@@node}.
2493 C-c C-c s @r{Insert} @samp{@@samp}.
2494 C-c C-c v @r{Insert} @samp{@@var}.
2495 C-c @{ @r{Insert braces.}
2497 C-c @} @r{Move out of enclosing braces.}
2500 C-c C-c C-d @r{Insert a node's section title}
2501 @r{in the space for the description}
2502 @r{in a menu entry line.}
2506 @subheading Show Structure
2508 The @code{texinfo-show-structure} command is often used within a
2509 narrowed region.@refill
2512 C-c C-s @r{List all the headings.}
2515 @subheading The Master Update Command
2517 The @code{texinfo-master-menu} command creates a master menu; and can
2518 be used to update every node and menu in a file as well.@refill
2520 @c Probably should use @tables in this section.
2524 M-x texinfo-master-menu
2525 @r{Create or update a master menu.}
2529 C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
2530 @r{create or update all nodes and regular}
2531 @r{menus, and then create a master menu.}
2535 @subheading Update Pointers
2537 The update pointer commands are invoked by typing @kbd{C-c C-u} and
2538 then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2539 @code{texinfo-every-node-update}.@refill
2542 C-c C-u C-n @r{Update a node.}
2543 C-c C-u C-e @r{Update every node in the buffer.}
2546 @subheading Update Menus
2548 Invoke the update menu commands by typing @kbd{C-c C-u}
2549 and then either @kbd{C-m} for @code{texinfo-make-menu} or
2550 @kbd{C-a} for @code{texinfo-all-menus-update}. To update
2551 both nodes and menus at the same time, precede @kbd{C-c C-u
2552 C-a} with @kbd{C-u}.@refill
2555 C-c C-u C-m @r{Make or update a menu.}
2558 C-c C-u C-a @r{Make or update all}
2559 @r{menus in a buffer.}
2563 C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2564 @r{first create or update all nodes and}
2565 @r{then create or update all menus.}
2569 @subheading Format for Info
2571 The Info formatting commands that are written in Emacs Lisp are
2572 invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2573 or @kbd{C-b} for the whole buffer.@refill
2575 The Info formatting commands that are written in C and based on the
2576 @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2577 either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2581 Use the @code{texinfo-format@dots{}} commands:
2585 C-c C-e C-r @r{Format the region.}
2586 C-c C-e C-b @r{Format the buffer.}
2592 Use @code{makeinfo}:
2595 C-c C-m C-r @r{Format the region.}
2596 C-c C-m C-b @r{Format the buffer.}
2597 C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
2598 C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
2601 @subheading Typeset and Print
2603 The @TeX{} typesetting and printing commands are invoked by typing
2604 @kbd{C-c C-t} and then another control command: @kbd{C-r} for
2605 @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2609 C-c C-t C-r @r{Run @TeX{} on the region.}
2610 C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
2611 C-c C-t C-i @r{Run} @code{texindex}.
2612 C-c C-t C-p @r{Print the DVI file.}
2613 C-c C-t C-q @r{Show the print queue.}
2614 C-c C-t C-d @r{Delete a job from the print queue.}
2615 C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
2616 C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
2617 C-c C-t C-l @r{Recenter the output buffer.}
2620 @subheading Other Updating Commands
2622 The remaining updating commands do not have standard keybindings because
2623 they are rarely used.
2627 M-x texinfo-insert-node-lines
2628 @r{Insert missing @code{@@node} lines in region.}
2629 @r{With @kbd{C-u} as a prefix argument,}
2630 @r{use section titles as node names.}
2634 M-x texinfo-multiple-files-update
2635 @r{Update a multi-file document.}
2636 @r{With @kbd{C-u 2} as a prefix argument,}
2637 @r{create or update all nodes and menus}
2638 @r{in all included files first.}
2642 M-x texinfo-indent-menu-description
2643 @r{Indent descriptions.}
2647 M-x texinfo-sequential-node-update
2648 @r{Insert node pointers in strict sequence.}
2653 @node Beginning a File
2654 @chapter Beginning a Texinfo File
2655 @cindex Beginning a Texinfo file
2656 @cindex Texinfo file beginning
2657 @cindex File beginning
2659 Certain pieces of information must be provided at the beginning of a
2660 Texinfo file, such as the name for the output file(s), the title of the
2661 document, and the Top node. A table of contents is also generally
2664 This chapter expands on the minimal complete Texinfo source file
2665 previously given (@pxref{Six Parts}). It describes the numerous
2666 commands for handling the traditional frontmatter items in Texinfo.
2668 @cindex Frontmatter, text in
2669 Straight text outside of any command before the Top node should be
2670 avoided. Such text is treated differently in the different output
2671 formats: visible in @TeX{} and HTML, by default not shown in Info
2675 * Sample Beginning:: A sample beginning for a Texinfo file.
2676 * Texinfo File Header:: The first lines.
2677 * Document Permissions:: Ensuring your manual is free.
2678 * Titlepage & Copyright Page:: Creating the title and copyright pages.
2679 * Contents:: How to create a table of contents.
2680 * The Top Node:: Creating the `Top' node and master menu.
2681 * Global Document Commands:: Affecting formatting throughout.
2682 * Software Copying Permissions:: Ensure that you and others continue to
2683 have the right to use and share software.
2687 @node Sample Beginning
2688 @section Sample Texinfo File Beginning
2690 @cindex Example beginning of Texinfo file
2692 The following sample shows what is needed. The elements given here are
2693 explained in more detail in the following sections. Other commands are
2694 often included at the beginning of Texinfo files, but the ones here are
2697 @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
2700 \input texinfo @@c -*-texinfo-*-
2701 @@c %**start of header
2702 @@setfilename @var{infoname}.info
2703 @@settitle @var{name-of-manual} @var{version}
2704 @@c %**end of header
2707 This manual is for @var{program}, version @var{version}.
2709 Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2713 Permission is granted to @dots{}
2720 @@title @var{name-of-manual-when-printed}
2721 @@subtitle @var{subtitle-if-any}
2722 @@subtitle @var{second-subtitle}
2723 @@author @var{author}
2727 @@c The following two commands
2728 @@c start the copyright page.
2730 @@vskip 0pt plus 1filll
2734 Published by @dots{}
2737 @@c So the toc is printed at the start.
2744 This manual is for @var{program}, version @var{version}.
2749 * First Chapter:: Getting started @dots{}
2750 * Second Chapter:: @dots{}
2752 * Copying:: Your rights and freedoms.
2757 @@node First Chapter
2758 @@chapter First Chapter
2760 @@cindex first chapter
2761 @@cindex chapter, first
2767 @node Texinfo File Header
2768 @section Texinfo File Header
2769 @cindex Header for Texinfo files
2770 @cindex Texinfo file header
2772 Texinfo files start with at least three lines that provide Info and
2773 @TeX{} with necessary information. These are the @code{\input texinfo}
2774 line, the @code{@@settitle} line, and the @code{@@setfilename} line.
2776 Also, if you want to format just part of the Texinfo file, you must
2777 write the @code{@@settitle} and @code{@@setfilename} lines between
2778 start-of-header and end-of-header lines. The start- and end-of-header
2779 lines are optional, but they do no harm, so you might as well always
2782 Any command that affects document formatting as a whole makes sense to
2783 include in the header. @code{@@synindex} (@pxref{synindex}), for
2784 instance, is another command often included in the header. @xref{GNU
2785 Sample Texts}, for complete sample texts.
2787 Thus, the beginning of a Texinfo file generally looks like this:
2791 \input texinfo @@c -*-texinfo-*-
2792 @@c %**start of header
2793 @@setfilename sample.info
2794 @@settitle Sample Manual 1.0
2795 @@c %**end of header
2800 * First Line:: The first line of a Texinfo file.
2801 * Start of Header:: Formatting a region requires this.
2802 * setfilename:: Tell Info the name of the Info file.
2803 * settitle:: Create a title for the printed work.
2804 * End of Header:: Formatting a region requires this.
2809 @subsection The First Line of a Texinfo File
2810 @cindex First line of a Texinfo file
2811 @cindex Beginning line of a Texinfo file
2812 @cindex Header of a Texinfo file
2814 Every Texinfo file that is to be the top-level input to @TeX{} must begin
2815 with a line that looks like this:
2818 \input texinfo @@c -*-texinfo-*-
2822 This line serves two functions:
2826 When the file is processed by @TeX{}, the @samp{\input texinfo} command
2827 tells @TeX{} to load the macros needed for processing a Texinfo file.
2828 These are in a file called @file{texinfo.tex}, which should have been
2829 installed on your system along with either the @TeX{} or Texinfo
2830 software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
2831 a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
2832 file causes the switch from @samp{\} to @samp{@@}; before the switch
2833 occurs, @TeX{} requires @samp{\}, which is why it appears at the
2834 beginning of the file.
2837 When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
2838 specification tells Emacs to use Texinfo mode.
2842 @node Start of Header
2843 @subsection Start of Header
2844 @cindex Start of header line
2846 A start-of-header line is a Texinfo comment that looks like this:
2849 @@c %**start of header
2852 Write the start-of-header line on the second line of a Texinfo file.
2853 Follow the start-of-header line with @code{@@setfilename} and
2854 @code{@@settitle} lines and, optionally, with other commands that
2855 globally affect the document formatting, such as @code{@@synindex} or
2856 @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
2859 The start- and end-of-header lines allow you to format only part of a
2860 Texinfo file for Info or printing. @xref{texinfo-format commands}.
2862 The odd string of characters, @samp{%**}, is to ensure that no other
2863 comment is accidentally taken for a start-of-header line. You can
2864 change it if you wish by setting the @code{tex-start-of-header} and/or
2865 @code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}.
2869 @subsection @code{@@setfilename}: Set the output file name
2871 @cindex Texinfo requires @code{@@setfilename}
2873 In order to serve as the primary input file for either @code{makeinfo}
2874 or @TeX{}, a Texinfo file must contain a line that looks like this:
2877 @@setfilename @var{info-file-name}
2880 Write the @code{@@setfilename} command at the beginning of a line and
2881 follow it on the same line by the Info file name. Do not write anything
2882 else on the line; anything on the line after the command is considered
2883 part of the file name, including what would otherwise be a
2886 @cindex Ignored before @code{@@setfilename}
2887 @cindex @samp{\input} source line ignored
2888 The Info formatting commands ignore everything written before the
2889 @code{@@setfilename} line, which is why the very first line of
2890 the file (the @code{\input} line) does not show up in the output.
2892 The @code{@@setfilename} line specifies the name of the output file to
2893 be generated. This name must be different from the name of the Texinfo
2894 file. There are two conventions for choosing the name: you can either
2895 remove the extension (such as @samp{.texi}) entirely from the input file
2896 name, or, preferably, replace it with the @samp{.info} extension.
2898 @cindex Length of file names
2899 @cindex File name collision
2900 @cindex Info file name, choosing
2901 Although an explicit @samp{.info} extension is preferable, some
2902 operating systems cannot handle long file names. You can run into a
2903 problem even when the file name you specify is itself short enough.
2904 This occurs because the Info formatters split a long Info file into
2905 short indirect subfiles, and name them by appending @samp{-1},
2906 @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2907 file name. (@xref{Tag and Split Files}.) The subfile name
2908 @file{texinfo.info-10}, for example, is too long for old systems with a
2909 14-character limit on filenames; so the Info file name for this document
2910 is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
2911 is running on operating systems such as MS-DOS which impose severe
2912 limits on file names, it may remove some characters from the original
2913 file name to leave enough space for the subfile suffix, thus producing
2914 files named @file{texin-10}, @file{gcc.i12}, etc.
2916 When producing HTML output, @code{makeinfo} will replace any extension
2917 with @samp{html}, or add @samp{.html} if the given name has no
2921 The @code{@@setfilename} line produces no output when you typeset a
2922 manual with @TeX{}, but it is nevertheless essential: it opens the
2923 index, cross-reference, and other auxiliary files used by Texinfo, and
2924 also reads @file{texinfo.cnf} if that file is present on your system
2925 (@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2929 @subsection @code{@@settitle}: Set the document title
2932 In order to be made into a printed manual, a Texinfo file must contain
2933 a line that looks like this:
2936 @@settitle @var{title}
2939 Write the @code{@@settitle} command at the beginning of a line and
2940 follow it on the same line by the title. This tells @TeX{} the title to
2941 use in a header or footer. Do not write anything else on the line;
2942 anything on the line after the command is considered part of the title,
2943 including what would otherwise be a comment.
2945 The @code{@@settitle} command should precede everything that generates
2946 actual output. The best place for it is right after the
2947 @code{@@setfilename} command (see the previous section).
2949 @cindex <title> HTML tag
2950 In the HTML file produced by @command{makeinfo}, @var{title} serves as
2951 the document @samp{<title>}. It also becomes the default document
2952 description in the @samp{<head>} part (@pxref{documentdescription}).
2954 The title in the @code{@@settitle} command does not affect the title as
2955 it appears on the title page. Thus, the two do not need not match
2956 exactly. A practice we recommend is to include the version or edition
2957 number of the manual in the @code{@@settitle} title; on the title page,
2958 the version number generally appears as a @code{@@subtitle} so it would
2959 be omitted from the @code{@@title}. @xref{titlepage}.
2961 Conventionally, when @TeX{} formats a Texinfo file for double-sided
2962 output, the title is printed in the left-hand (even-numbered) page
2963 headings and the current chapter title is printed in the right-hand
2964 (odd-numbered) page headings. (@TeX{} learns the title of each chapter
2965 from each @code{@@chapter} command.) By default, no page footer is
2968 Even if you are printing in a single-sided style, @TeX{} looks for an
2969 @code{@@settitle} command line, in case you include the manual title
2972 @TeX{} prints page headings only for that text that comes after the
2973 @code{@@end titlepage} command in the Texinfo file, or that comes
2974 after an @code{@@headings} command that turns on headings.
2975 (@xref{headings on off, , The @code{@@headings} Command}, for more
2978 You may, if you wish, create your own, customized headings and footings.
2979 @xref{Headings}, for a detailed discussion of this.
2983 @subsection End of Header
2984 @cindex End of header line
2986 Follow the header lines with an @w{end-of-header} line, which is a
2987 Texinfo comment that looks like this:
2990 @@c %**end of header
2993 @xref{Start of Header}.
2996 @node Document Permissions
2997 @section Document Permissions
2998 @cindex Document Permissions
2999 @cindex Copying Permissions
3001 The copyright notice and copying permissions for a document need to
3002 appear in several places in the various Texinfo output formats.
3003 Therefore, Texinfo provides a command (@code{@@copying}) to declare
3004 this text once, and another command (@code{@@insertcopying}) to
3005 insert the text at appropriate points.
3008 * copying:: Declare the document's copying permissions.
3009 * insertcopying:: Where to insert the permissions.
3014 @subsection @code{@@copying}: Declare Copying Permissions
3017 The @code{@@copying} command should be given very early in the document;
3018 the recommended location is right after the header material
3019 (@pxref{Texinfo File Header}). It conventionally consists of a sentence
3020 or two about what the program is, identification of the documentation
3021 itself, the legal copyright line, and the copying permissions. Here is
3026 This manual is for @var{program} (version @var{version}, updated
3027 @var{date}), which @dots{}
3029 Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
3032 Permission is granted to @dots{}
3037 The @code{@@quotation} has no legal significance; it's there to improve
3038 readability in some contexts.
3040 @xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
3041 @xref{GNU Free Documentation License}, for the license itself under
3042 which GNU and other free manuals are distributed. You need to include
3043 the license as an appendix to your document.
3045 The text of @code{@@copying} is output as a comment at the beginning of
3046 Info, HTML, and XML output files. It is @emph{not} output implicitly in
3047 plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
3048 emit the copying information. See the next section for details.
3051 The @code{@@copyright@{@}} command generates a @samp{c} inside a circle
3052 in output formats that support this (print and HTML). In the other
3053 formats (Info and plain text), it generates @samp{(C)}. The copyright
3054 notice itself has the following legally defined sequence:
3057 Copyright @copyright{} @var{years} @var{copyright-owner}.
3060 @cindex Copyright word, always in English
3061 The word `Copyright' must always be written in English, even if the
3062 document is otherwise written in another language. This is due to
3065 @cindex Years, in copyright line
3066 The list of years should include all years in which a version was
3067 completed (even if it was released in a subsequent year). Ranges are
3068 not allowed; each year must be written out individually and in full,
3069 separated by commas.
3071 @cindex Copyright holder for FSF works
3072 @cindex Holder of copyright for FSF works
3073 @cindex Owner of copyright for FSF works
3074 The copyright owner (or owners) is whoever holds legal copyright on the
3075 work. In the case of works assigned to the FSF, the owner is `Free
3076 Software Foundation, Inc.'.
3078 The copyright `line' may actually be split across multiple lines, both
3079 in the source document and in the output. This often happens for
3080 documents with a long history, having many different years of
3081 publication. If you do use several lines, do not indent any of them
3082 (or anything else in the @code{@@copying} block) in the source file.
3084 @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
3085 additional information.
3089 @subsection @code{@@insertcopying}: Include Permissions Text
3090 @findex insertcopying
3091 @cindex Copying text, including
3092 @cindex Permissions text, including
3093 @cindex Including permissions text
3095 The @code{@@insertcopying} command is simply written on a line by
3102 This inserts the text previously defined by @code{@@copying}. To meet
3103 legal requirements, it must be used on the copyright page in the printed
3104 manual (@pxref{Copyright}).
3106 The @code{@@copying} command itself causes the permissions text to
3107 appear in an Info file @emph{before} the first node. The text is also
3108 copied into the beginning of each split Info output file, as is legally
3109 necessary. This location implies a human reading the manual using Info
3110 does @emph{not} see this text (except when using the advanced Info
3111 command @kbd{g *}), but this does not matter for legal purposes,
3112 because the text is present.
3114 Similarly, the @code{@@copying} text is automatically included at the
3115 beginning of each HTML output file, as an HTML comment. Again, this
3116 text is not visible (unless the reader views the HTML source).
3118 The permissions text defined by @code{@@copying} also appears
3119 automatically at the beginning of the XML output file.
3122 @node Titlepage & Copyright Page
3123 @section Title and Copyright Pages
3125 In hard copy output, the manual's name and author are usually printed on
3126 a title page. Copyright information is usually printed on the back of
3129 The title and copyright pages appear in the printed manual, but not in
3130 the Info file. Because of this, it is possible to use several slightly
3131 obscure @TeX{} typesetting commands that cannot be used in an Info file.
3132 In addition, this part of the beginning of a Texinfo file contains the
3133 text of the copying permissions that appears in the printed manual.
3135 @cindex Title page, for plain text
3136 @cindex Copyright page, for plain text
3137 You may wish to include titlepage-like information for plain text
3138 output. Simply place any such leading material between
3139 @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
3140 includes this when writing plain text (@samp{--no-headers}), along with
3141 an @code{@@insertcopying}.
3144 * titlepage:: Create a title for the printed document.
3145 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3146 and @code{@@sp} commands.
3147 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
3148 and @code{@@author} commands.
3149 * Copyright:: How to write the copyright notice and
3150 include copying permissions.
3151 * end titlepage:: Turn on page headings after the title and
3153 * headings on off:: An option for turning headings on and off
3154 and double or single sided printing.
3159 @subsection @code{@@titlepage}
3163 Start the material for the title page and following copyright page
3164 with @code{@@titlepage} on a line by itself and end it with
3165 @code{@@end titlepage} on a line by itself.
3167 The @code{@@end titlepage} command starts a new page and turns on page
3168 numbering. (@xref{Headings, , Page Headings}, for details about how to
3169 generate page headings.) All the material that you want to appear on
3170 unnumbered pages should be put between the @code{@@titlepage} and
3171 @code{@@end titlepage} commands. You can force the table of contents to
3172 appear there with the @code{@@setcontentsaftertitlepage} command
3175 @findex page@r{, within @code{@@titlepage}}
3176 By using the @code{@@page} command you can force a page break within the
3177 region delineated by the @code{@@titlepage} and @code{@@end titlepage}
3178 commands and thereby create more than one unnumbered page. This is how
3179 the copyright page is produced. (The @code{@@titlepage} command might
3180 perhaps have been better named the @code{@@titleandadditionalpages}
3181 command, but that would have been rather long!)
3183 When you write a manual about a computer program, you should write the
3184 version of the program to which the manual applies on the title page.
3185 If the manual changes more frequently than the program or is independent
3186 of it, you should also include an edition number@footnote{We have found
3187 that it is helpful to refer to versions of independent manuals as
3188 `editions' and versions of programs as `versions'; otherwise, we find we
3189 are liable to confuse each other in conversation by referring to both
3190 the documentation and the software with the same words.} for the manual.
3191 This helps readers keep track of which manual is for which version of
3192 the program. (The `Top' node should also contain this information; see
3193 @ref{The Top Node}.)
3195 Texinfo provides two main methods for creating a title page. One method
3196 uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3197 to generate a title page in which the words on the page are
3200 The second method uses the @code{@@title}, @code{@@subtitle}, and
3201 @code{@@author} commands to create a title page with black rules under
3202 the title and author lines and the subtitle text set flush to the
3203 right hand side of the page. With this method, you do not specify any
3204 of the actual formatting of the title page. You specify the text
3205 you want, and Texinfo does the formatting.
3207 You may use either method, or you may combine them; see the examples in
3210 @findex shorttitlepage
3211 @cindex Bastard title page
3212 @cindex Title page, bastard
3213 For extremely simple documents, and for the bastard title page in
3214 traditional book frontmatter, Texinfo also provides a command
3215 @code{@@shorttitlepage} which takes the rest of the line as the title.
3216 The argument is typeset on a page by itself and followed by a blank
3220 @node titlefont center sp
3221 @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3224 @findex sp @r{(titlepage line spacing)}
3226 You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3227 commands to create a title page for a printed document. (This is the
3228 first of the two methods for creating a title page in Texinfo.)
3230 Use the @code{@@titlefont} command to select a large font suitable for
3231 the title itself. You can use @code{@@titlefont} more than once if you
3232 have an especially long title.
3234 For HTML output, each @code{@@titlefont} command produces an
3235 @code{<h1>} heading, but the HTML document @code{<title>} is not
3236 affected. For that, you must put an @code{@@settitle} command before
3237 the @code{@@titlefont} command (@pxref{settitle}).
3243 @@titlefont@{Texinfo@}
3246 Use the @code{@@center} command at the beginning of a line to center
3247 the remaining text on that line. Thus,
3250 @@center @@titlefont@{Texinfo@}
3254 centers the title, which in this example is ``Texinfo'' printed
3257 Use the @code{@@sp} command to insert vertical space. For example:
3264 This inserts two blank lines on the printed page. (@xref{sp, ,
3265 @code{@@sp}}, for more information about the @code{@@sp}
3268 A template for this method looks like this:
3274 @@center @@titlefont@{@var{name-of-manual-when-printed}@}
3276 @@center @var{subtitle-if-any}
3278 @@center @var{author}
3284 The spacing of the example fits an 8.5 by 11 inch manual.
3286 You can in fact use these commands anywhere, not just on a title page,
3287 but since they are not logical markup commands, we don't recommend
3290 @node title subtitle author
3291 @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3296 You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3297 commands to create a title page in which the vertical and horizontal
3298 spacing is done for you automatically. This contrasts with the method
3299 described in the previous section, in which the @code{@@sp} command is
3300 needed to adjust vertical spacing.
3302 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3303 commands at the beginning of a line followed by the title, subtitle,
3304 or author. These commands are only effective in @TeX{} output; it's
3305 an error to use them anywhere except within @code{@@titlepage}.
3307 The @code{@@title} command produces a line in which the title is set
3308 flush to the left-hand side of the page in a larger than normal font.
3309 The title is underlined with a black rule. Only a single line is
3310 allowed; the @code{@@*} command may not be used to break the title into
3311 two lines. To handle very long titles, you may find it profitable to
3312 use both @code{@@title} and @code{@@titlefont}; see the final example in
3315 The @code{@@subtitle} command sets subtitles in a normal-sized font
3316 flush to the right-hand side of the page.
3318 The @code{@@author} command sets the names of the author or authors in
3319 a middle-sized font flush to the left-hand side of the page on a line
3320 near the bottom of the title page. The names are underlined with a
3321 black rule that is thinner than the rule that underlines the title.
3322 (The black rule only occurs if the @code{@@author} command line is
3323 followed by an @code{@@page} command line.)
3325 There are two ways to use the @code{@@author} command: you can write
3326 the name or names on the remaining part of the line that starts with
3327 an @code{@@author} command:
3330 @@author by Jane Smith and John Doe
3334 or you can write the names one above each other by using two (or more)
3335 @code{@@author} commands:
3345 (Only the bottom name is underlined with a black rule.)
3348 A template for this method looks like this:
3353 @@title @var{name-of-manual-when-printed}
3354 @@subtitle @var{subtitle-if-any}
3355 @@subtitle @var{second-subtitle}
3356 @@author @var{author}
3363 You may also combine the @code{@@titlefont} method described in the
3364 previous section and @code{@@title} method described in this one. This
3365 may be useful if you have a very long title. Here is a real-life example:
3370 @@titlefont@{GNU Software@}
3372 @@title for MS-Windows and MS-DOS
3373 @@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3374 @@author by Daniel Hagerty, Melissa Weisshaus
3375 @@author and Eli Zaretskii
3380 (The use of @code{@@value} here is explained in @ref{value Example}.
3384 @subsection Copyright Page
3385 @cindex Copyright page
3386 @cindex Printed permissions
3387 @cindex Permissions, printed
3389 By international treaty, the copyright notice for a book must be either
3390 on the title page or on the back of the title page. When the copyright
3391 notice is on the back of the title page, that page is customarily not
3392 numbered. Therefore, in Texinfo, the information on the copyright page
3393 should be within @code{@@titlepage} and @code{@@end titlepage}
3396 @findex vskip @r{@TeX{} vertical skip}
3397 @findex filll @r{@TeX{} dimension}
3398 Use the @code{@@page} command to cause a page break. To push the
3399 copyright notice and the other text on the copyright page towards the
3400 bottom of the page, use the following incantation after @code{@@page}:
3403 @@vskip 0pt plus 1filll
3407 This is a @TeX{} command that is not supported by the Info formatting
3408 commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
3409 plus 1filll} means to put in zero points of mandatory whitespace, and as
3410 much optional whitespace as needed to push the following text to the
3411 bottom of the page. Note the use of three @samp{l}s in the word
3412 @samp{filll}; this is correct.
3414 To insert the copyright text itself, write @code{@@insertcopying}
3415 next (@pxref{Document Permissions}):
3421 Follow the copying text by the publisher, ISBN numbers, cover art
3422 credits, and other such information.
3424 Here is an example putting all this together:
3430 @@vskip 0pt plus 1filll
3433 Published by @dots{}
3435 Cover art by @dots{}
3441 @subsection Heading Generation
3442 @findex end titlepage
3443 @cindex Headings, page, begin to appear
3444 @cindex Titlepage end starts headings
3445 @cindex End titlepage starts headings
3447 Like all @code{@@end} commands (@pxref{Quotations and Examples}), the @code{@@end titlepage} command
3448 must be written at the beginning of a line by itself, with only one
3449 space between the @code{@@end} and the @code{titlepage}. It not only
3450 marks the end of the title and copyright pages, but also causes @TeX{}
3451 to start generating page headings and page numbers.
3453 To repeat what is said elsewhere, Texinfo has two standard page heading
3454 formats, one for documents which are printed on one side of each sheet of paper
3455 (single-sided printing), and the other for documents which are printed on both
3456 sides of each sheet (double-sided printing).
3457 You can specify these formats in different ways:
3461 The conventional way is to write an @code{@@setchapternewpage} command
3462 before the title page commands, and then have the @code{@@end
3463 titlepage} command start generating page headings in the manner desired.
3464 (@xref{setchapternewpage}.)
3467 Alternatively, you can use the @code{@@headings} command to prevent page
3468 headings from being generated or to start them for either single or
3469 double-sided printing. (Write an @code{@@headings} command immediately
3470 after the @code{@@end titlepage} command. @xref{headings on off, , The
3471 @code{@@headings} Command}, for more information.)@refill
3474 Or, you may specify your own page heading and footing format.
3475 @xref{Headings, , Page Headings}, for detailed
3476 information about page headings and footings.
3479 Most documents are formatted with the standard single-sided or
3480 double-sided format, using @code{@@setchapternewpage odd} for
3481 double-sided printing and no @code{@@setchapternewpage} command for
3482 single-sided printing.
3485 @node headings on off
3486 @subsection The @code{@@headings} Command
3489 The @code{@@headings} command is rarely used. It specifies what kind of
3490 page headings and footings to print on each page. Usually, this is
3491 controlled by the @code{@@setchapternewpage} command. You need the
3492 @code{@@headings} command only if the @code{@@setchapternewpage} command
3493 does not do what you want, or if you want to turn off predefined page
3494 headings prior to defining your own. Write an @code{@@headings} command
3495 immediately after the @code{@@end titlepage} command.
3497 You can use @code{@@headings} as follows:
3500 @item @@headings off
3501 Turn off printing of page headings.
3503 @item @@headings single
3504 Turn on page headings appropriate for single-sided printing.
3506 @item @@headings double
3507 Turn on page headings appropriate for double-sided printing.
3509 @item @@headings singleafter
3510 @itemx @@headings doubleafter
3511 Turn on @code{single} or @code{double} headings, respectively, after the
3512 current page is output.
3515 Turn on page headings: @code{single} if @samp{@@setchapternewpage
3516 on}, @code{double} otherwise.
3519 For example, suppose you write @code{@@setchapternewpage off} before the
3520 @code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3521 same page as the end of the last chapter. This command also causes
3522 @TeX{} to typeset page headers for single-sided printing. To cause
3523 @TeX{} to typeset for double sided printing, write @code{@@headings
3524 double} after the @code{@@end titlepage} command.
3526 You can stop @TeX{} from generating any page headings at all by
3527 writing @code{@@headings off} on a line of its own immediately after the
3528 line containing the @code{@@end titlepage} command, like this:
3536 The @code{@@headings off} command overrides the @code{@@end titlepage}
3537 command, which would otherwise cause @TeX{} to print page headings.
3539 You can also specify your own style of page heading and footing.
3540 @xref{Headings, , Page Headings}, for more information.
3544 @section Generating a Table of Contents
3545 @cindex Table of contents
3546 @cindex Contents, Table of
3547 @cindex Short table of contents
3549 @findex summarycontents
3550 @findex shortcontents
3552 The @code{@@chapter}, @code{@@section}, and other structuring commands
3553 (@pxref{Structuring}) supply the information to make up a
3554 table of contents, but they do not cause an actual table to appear in
3555 the manual. To do this, you must use the @code{@@contents} and/or
3556 @code{@@summarycontents} command(s).
3560 Generates a table of contents in a printed manual, including all
3561 chapters, sections, subsections, etc., as well as appendices and
3562 unnumbered chapters. Headings generated by @code{@@majorheading},
3563 @code{@@chapheading}, and the other @code{@@@dots{}heading} commands
3564 do not appear in the table of contents (@pxref{Structuring Command
3567 @item @@shortcontents
3568 @itemx @@summarycontents
3569 (@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
3571 Generates a short or summary table of contents that lists only the
3572 chapters, appendices, and unnumbered chapters. Sections, subsections
3573 and subsubsections are omitted. Only a long manual needs a short
3574 table of contents in addition to the full table of contents.
3578 Both contents commands should be written on a line by themselves, and
3579 are best placed near the beginning of the file, after the @code{@@end
3580 titlepage} (@pxref{titlepage}). The contents commands automatically
3581 generate a chapter-like heading at the top of the first table of
3582 contents page, so don't include any sectioning command such as
3583 @code{@@unnumbered} before them.
3585 Since an Info file uses menus instead of tables of contents, the Info
3586 formatting commands ignore the contents commands. But the contents are
3587 included in plain text output (generated by @code{makeinfo
3588 --no-headers}), unless @code{makeinfo} is writing its output to standard
3591 When @code{makeinfo} writes a short table of contents while producing
3592 HTML output, the links in the short table of contents point to
3593 corresponding entries in the full table of contents rather than the text
3594 of the document. The links in the full table of contents point to the
3595 main text of the document.
3597 In the past, the contents commands were sometimes placed at the end of
3598 the file, after any indices and just before the @code{@@bye}, but we
3599 no longer recommend this.
3601 @findex setcontentsaftertitlepage
3602 @findex setshortcontentsaftertitlepage
3603 @cindex Contents, after title page
3604 @cindex Table of contents, after title page
3605 However, since many existing Texinfo documents still do have the
3606 @code{@@contents} at the end of the manual, if you are a user printing
3607 a manual, you may wish to force the contents to be printed after the
3608 title page. You can do this by specifying
3609 @code{@@setcontentsaftertitlepage} and/or
3610 @code{@@setshortcontentsaftertitlepage}. The first prints only the
3611 main contents after the @code{@@end titlepage}; the second prints both
3612 the short contents and the main contents. In either case, any
3613 subsequent @code{@@contents} or @code{@@shortcontents} is ignored
3614 (unless, erroneously, no @code{@@end titlepage} is ever encountered).
3616 You need to include the @code{@@set@dots{}contentsaftertitlepage}
3617 commands early in the document (just after @code{@@setfilename}, for
3618 example). We recommend using @command{texi2dvi} (@pxref{Format with
3619 texi2dvi}) to specify this without altering the source file at all. For
3622 texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
3627 @section The `Top' Node and Master Menu
3631 The `Top' node is the node in which a reader enters an Info manual.
3632 As such, it should begin with a brief description of the manual
3633 (including the version number), and end with a master menu for the
3634 whole manual. Of course you should include any other general
3635 information you feel a reader would find helpful.
3638 It is conventional and desirable to write an @code{@@top} sectioning
3639 command line containing the title of the document immediately after
3640 the @code{@@node Top} line (@pxref{makeinfo top command, , The
3641 @code{@@top} Sectioning Command}).
3643 The contents of the `Top' node should appear only in the online output;
3644 none of it should appear in printed output, so enclose it between
3645 @code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
3646 print either an @code{@@node} line or a menu; they appear only in Info;
3647 strictly speaking, you are not required to enclose these parts between
3648 @code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
3649 so. @xref{Conditionals, , Conditionally Visible Text}.)
3652 * Top Node Example::
3653 * Master Menu Parts::
3657 @node Top Node Example
3658 @subsection Top Node Example
3660 @cindex Top node example
3662 Here is an example of a Top node.
3674 Additional general information.
3687 @node Master Menu Parts
3688 @subsection Parts of a Master Menu
3690 @cindex Menu, master
3691 @cindex Parts of a master menu
3693 A @dfn{master menu} is a detailed main menu listing all the nodes in a
3696 A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3697 commands and does not appear in the printed document.
3699 Generally, a master menu is divided into parts.
3703 The first part contains the major nodes in the Texinfo file: the nodes
3704 for the chapters, chapter-like sections, and the appendices.
3707 The second part contains nodes for the indices.
3711 @cindex Detailed menu
3712 The third and subsequent parts contain a listing of the other, lower
3713 level nodes, often ordered by chapter. This way, rather than go
3714 through an intermediary menu, an inquirer can go directly to a
3715 particular node when searching for specific information. These menu
3716 items are not required; add them if you think they are a
3717 convenience. If you do use them, put @code{@@detailmenu} before the
3718 first one, and @code{@@end detailmenu} after the last; otherwise,
3719 @code{makeinfo} will get confused.
3722 Each section in the menu can be introduced by a descriptive line. So
3723 long as the line does not begin with an asterisk, it will not be
3724 treated as a menu entry. (@xref{Writing a Menu}, for more
3727 For example, the master menu for this manual looks like the following
3728 (but has many more entries):
3733 * Copying Conditions:: Your rights.
3734 * Overview:: Texinfo in brief.
3738 * Command and Variable Index::
3744 --- The Detailed Node Listing ---
3748 * Reporting Bugs:: @dots{}
3753 Beginning a Texinfo File
3755 * Sample Beginning:: @dots{}
3763 @node Global Document Commands
3764 @section Global Document Commands
3765 @cindex Global Document Commands
3767 Besides the basic commands mentioned in the previous sections, here are
3768 additional commands which affect the document as a whole. They are
3769 generally all given before the Top node, if they are given at all.
3772 * documentdescription:: Document summary for the HTML output.
3773 * setchapternewpage:: Start chapters on right-hand pages.
3774 * paragraphindent:: Specify paragraph indentation.
3775 * firstparagraphindent:: Suppress indentation of the first paragraph.
3776 * exampleindent:: Specify environment indentation.
3780 @node documentdescription
3781 @subsection @code{@@documentdescription}: Summary Text
3782 @cindex Document description
3783 @cindex Description of document
3784 @cindex Summary of document
3785 @cindex Abstract of document
3786 @cindex <meta> HTML tag, and document description
3787 @findex documentdescription
3789 When producing HTML output for a document, @command{makeinfo} writes a
3790 @samp{<meta>} element in the @samp{<head>} to give some idea of the
3791 content of the document. By default, this @dfn{description} is the title
3792 of the document, taken from the @code{@@settitle} command
3793 (@pxref{settitle}). To change this, use the @code{@@documentdescription}
3797 @@documentdescription
3799 @@end documentdescription
3803 This will produce the following output in the @samp{<head>} of the HTML:
3806 <meta name=description content="descriptive text.">
3809 @code{@@documentdescription} must be specified before the first node of
3813 @node setchapternewpage
3814 @subsection @code{@@setchapternewpage}:
3815 @cindex Starting chapters
3816 @cindex Pages, starting odd
3817 @findex setchapternewpage
3819 In an officially bound book, text is usually printed on both sides of
3820 the paper, chapters start on right-hand pages, and right-hand pages have
3821 odd numbers. But in short reports, text often is printed only on one
3822 side of the paper. Also in short reports, chapters sometimes do not
3823 start on new pages, but are printed on the same page as the end of the
3824 preceding chapter, after a small amount of vertical whitespace.
3826 You can use the @code{@@setchapternewpage} command with various
3827 arguments to specify how @TeX{} should start chapters and whether it
3828 should format headers for printing on one or both sides of the paper
3829 (single-sided or double-sided printing).
3831 Write the @code{@@setchapternewpage} command at the beginning of a
3832 line followed by its argument.
3834 For example, you would write the following to cause each chapter to
3835 start on a fresh odd-numbered page:
3838 @@setchapternewpage odd
3841 You can specify one of three alternatives with the
3842 @code{@@setchapternewpage} command:
3846 @item @code{@@setchapternewpage off}
3847 Cause @TeX{} to typeset a new chapter on the same page as the last
3848 chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
3849 format page headers for single-sided printing.
3851 @item @code{@@setchapternewpage on}
3852 Cause @TeX{} to start new chapters on new pages and to format page
3853 headers for single-sided printing. This is the form most often used for
3854 short reports or personal printing. This is the default.
3856 @item @code{@@setchapternewpage odd}
3857 Cause @TeX{} to start new chapters on new, odd-numbered pages
3858 (right-handed pages) and to typeset for double-sided printing. This is
3859 the form most often used for books and manuals.
3862 Texinfo does not have an @code{@@setchapternewpage even} command,
3863 because there is no printing tradition of starting chapters or books on
3864 an even-numbered page.
3866 If you don't like the default headers that @code{@@setchapternewpage}
3867 sets, you can explicit control them with the @code{@@headings} command.
3868 @xref{headings on off, , The @code{@@headings} Command}.
3870 At the beginning of a manual or book, pages are not numbered---for
3871 example, the title and copyright pages of a book are not numbered. By
3872 convention, table of contents and frontmatter pages are numbered with
3873 roman numerals and not in sequence with the rest of the document.
3875 Since an Info file does not have pages, the @code{@@setchapternewpage}
3876 command has no effect on it.
3878 We recommend not including any @code{@@setchapternewpage} command in
3879 your manual sources at all, since the desired output is not intrinsic to
3880 the document. For a particular hard copy run, if you don't want the
3881 default option (no blank pages, same headers on all pages) use the
3882 @option{--texinfo} option to @command{texi2dvi} to specify the output
3886 @node paragraphindent
3887 @subsection @code{@@paragraphindent}: Paragraph Indenting
3888 @cindex Indenting paragraphs, control of
3889 @cindex Paragraph indentation control
3890 @findex paragraphindent
3892 The Texinfo processors may insert whitespace at the beginning of the
3893 first line of each paragraph, thereby indenting that paragraph. You can
3894 use the @code{@@paragraphindent} command to specify this indentation.
3895 Write an @code{@@paragraphindent} command at the beginning of a line
3896 followed by either @samp{asis} or a number:
3899 @@paragraphindent @var{indent}
3902 The indentation is according to the value of @var{indent}:
3906 Do not change the existing indentation (not implemented in @TeX{}).
3910 Omit all indentation.
3913 Indent by @var{n} space characters in Info output, by @var{n} ems in
3918 The default value of @var{indent} is 3. @code{@@paragraphindent} is
3919 ignored for HTML output.
3921 It is best to write the @code{@@paragraphindent} command before the
3922 end-of-header line at the beginning of a Texinfo file, so the region
3923 formatting commands indent paragraphs as specified. @xref{Start of
3926 A peculiarity of the @code{texinfo-format-buffer} and
3927 @code{texinfo-format-region} commands is that they do not indent (nor
3928 fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
3931 @node firstparagraphindent
3932 @subsection @code{@@firstparagraphindent}: Indenting After Headings
3933 @cindex First paragraph, suppressing indentation of
3934 @cindex Suppressing first paragraph indentation
3935 @cindex Preventing first paragraph indentation
3936 @cindex Indenting, suppressing of first paragraph
3937 @cindex Headings, indentation after
3938 @findex firstparagraphindent
3940 As you can see in the present manual, the first paragraph in any
3941 section is not indented by default. Typographically, indentation is a
3942 paragraph separator, which means that it is unnecessary when a new
3943 section begins. This indentation is controlled with the
3944 @code{@@firstparagraphindent} command:
3947 @@firstparagraphindent @var{word}
3950 The first paragraph after a heading is indented according to the value
3955 Prevents the first paragraph from being indented (default).
3956 This option is ignored by @command{makeinfo} if
3957 @code{@@paragraphindent asis} is in effect.
3960 Include normal paragraph indentation. This respects the paragraph
3961 indentation set by a @code{@@paragraphindent} command
3962 (@pxref{paragraphindent}).
3965 For HTML and XML output, the @code{@@firstparagraphindent} setting is
3968 It is best to write the @code{@@paragraphindent} command before the
3969 end-of-header line at the beginning of a Texinfo file, so the region
3970 formatting commands indent paragraphs as specified. @xref{Start of
3975 @subsection @code{@@exampleindent}: Environment Indenting
3976 @cindex Indenting environments
3977 @cindex Environment indentation
3978 @cindex Example indentation
3979 @findex exampleindent
3981 The Texinfo processors indent each line of @code{@@example} and similar
3982 environments. You can use the @code{@@exampleindent} command to specify
3983 this indentation. Write an @code{@@exampleindent} command at the
3984 beginning of a line followed by either @samp{asis} or a number:
3987 @@exampleindent @var{indent}
3990 @code{@@exampleindent} is ignored for HTML output. Otherwise, the
3991 indentation is according to the value of @var{indent}:
3995 Do not change the existing indentation (not implemented in @TeX{}).
3998 Omit all indentation.
4001 Indent environments by @var{n} space characters in Info output, by
4002 @var{n} ems in @TeX{}.
4006 The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in}
4007 in @TeX{}, which is somewhat less. (The reduction is to help @TeX{}
4008 fit more characters onto physical lines.)
4010 It is best to write the @code{@@exampleindent} command before the
4011 end-of-header line at the beginning of a Texinfo file, so the region
4012 formatting commands indent paragraphs as specified. @xref{Start of
4016 @node Software Copying Permissions
4017 @section Software Copying Permissions
4018 @cindex Software copying permissions
4019 @cindex Copying software
4020 @cindex Distribution
4021 @cindex License agreement
4023 If the Texinfo file has a section containing the ``General Public
4024 License'' and the distribution information and a warranty disclaimer for
4025 the software that is documented, we recommend placing this right after
4026 the `Top' node. The General Public License is very important to Project
4027 GNU software. It ensures that you and others will continue to have a
4028 right to use and share the software.
4030 The copying and distribution information and the disclaimer are followed
4031 by an introduction or else by the first chapter of the manual.
4033 @cindex Introduction, as part of file
4034 Although an introduction is not a required part of a Texinfo file, it
4035 is very helpful. Ideally, it should state clearly and concisely what
4036 the file is about and who would be interested in reading it. In
4037 general, an introduction would follow the licensing and distribution
4038 information, although sometimes people put it earlier in the document.
4042 @chapter Ending a Texinfo File
4043 @cindex Ending a Texinfo file
4044 @cindex Texinfo file ending
4048 The end of a Texinfo file should include commands to create indices,
4049 and the @code{@@bye} command to mark the last line to be processed.
4063 * Printing Indices & Menus:: How to print an index in hardcopy and
4064 generate index menus in Info.
4065 * File End:: How to mark the end of a file.
4069 @node Printing Indices & Menus
4070 @section Printing Indices and Menus
4071 @cindex Printing an index
4072 @cindex Indices, printing and menus
4073 @cindex Generating menus with indices
4074 @cindex Menus generated with indices
4076 To print an index means to include it as part of a manual or Info file.
4077 This does not happen automatically just because you use @code{@@cindex}
4078 or other index-entry generating commands in the Texinfo file; those just
4079 cause the raw data for the index to be accumulated. To generate an
4080 index, you must include the @code{@@printindex} command at the place in
4081 the document where you want the index to appear. Also, as part of the
4082 process of creating a printed manual, you must run a program called
4083 @code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
4084 sorted index file. The sorted index file is what is actually used to
4087 Texinfo offers six separate types of predefined index, which suffice
4088 in most cases. @xref{Indices}, for information on this, as well
4089 defining your own new indices, combining indices, and, most
4090 importantly advice on writing the actual index entries. This section
4091 focuses on printing indices, which is done with the
4092 @code{@@printindex} command.
4095 @code{@@printindex} takes one argument, a two-letter index
4096 abbreviation. It reads the corresponding sorted index file (for
4097 printed output), and formats it appropriately into an index.
4099 The @code{@@printindex} command does not generate a chapter heading
4100 for the index, since different manuals have different needs.
4101 Consequently, you should precede the @code{@@printindex} command with
4102 a suitable section or chapter command (usually @code{@@appendix} or
4103 @code{@@unnumbered}) to supply the chapter heading and put the index
4104 into the table of contents. Precede the chapter heading with an
4105 @code{@@node} line as usual.
4111 @@node Variable Index
4112 @@unnumbered Variable Index
4118 @@node Concept Index
4119 @@unnumbered Concept Index
4125 If you have more than one index, we recommend placing the concept index last.
4129 In printed output, @code{@@printindex} produces a traditional
4130 two-column index, with dot leaders between the index terms and page
4134 In Info output, @code{@@printindex} produces a special menu containing
4135 the line number of the entry, relative to the start of the node. Info
4136 readers can use this to go to the exact line of an entry, not just the
4137 containing node. (Older Info readers will just go to the node.)
4141 * First index entry: Top. (line 7)
4144 @noindent The actual number of spaces is variable, to right-justify
4145 the line number; it's been reduced here to make the line fit in the
4149 In plain text output, @code{@@printindex} produces the same menu, but
4150 the line numbers are relative to the start of the file, since that's
4151 more convenient for that format.
4154 In HTML and Docbook output, @code{@@printindex} produces links
4155 to the index entries.
4158 In XML output, it simply records the index to be printed.
4161 It's not possible to generate an index when writing to standard
4162 output; @command{makeinfo} generates a warning in this case.
4166 @section @code{@@bye} File Ending
4169 An @code{@@bye} command terminates Texinfo processing. None of the
4170 formatters read anything following @code{@@bye}. The @code{@@bye}
4171 command should be on a line by itself.
4173 If you wish, you may follow the @code{@@bye} line with notes. These
4174 notes will not be formatted and will not appear in either Info or a
4175 printed manual; it is as if text after @code{@@bye} were within
4176 @code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
4177 @code{@@bye} line with a local variables list for Emacs.
4178 @xref{Compile-Command, , Using Local Variables and the Compile Command},
4179 for more information.
4183 @chapter Chapter Structuring
4184 @cindex Chapter structuring
4185 @cindex Structuring of chapters
4187 The @dfn{chapter structuring} commands divide a document into a hierarchy of
4188 chapters, sections, subsections, and subsubsections. These commands
4189 generate large headings; they also provide information for the table
4190 of contents of a printed manual (@pxref{Contents, , Generating a Table
4191 of Contents}).@refill
4193 The chapter structuring commands do not create an Info node structure,
4194 so normally you should put an @code{@@node} command immediately before
4195 each chapter structuring command (@pxref{Nodes}). The only time you
4196 are likely to use the chapter structuring commands without using the
4197 node structuring commands is if you are writing a document that
4198 contains no cross references and will never be transformed into Info
4201 It is unlikely that you will ever write a Texinfo file that is
4202 intended only as an Info file and not as a printable document. If you
4203 do, you might still use chapter structuring commands to create a
4204 heading at the top of each node---but you don't need to.@refill
4207 * Tree Structuring:: A manual is like an upside down tree @dots{}
4208 * Structuring Command Types:: How to divide a manual into parts.
4209 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
4211 * unnumbered & appendix::
4212 * majorheading & chapheading::
4214 * unnumberedsec appendixsec heading::
4216 * unnumberedsubsec appendixsubsec subheading::
4217 * subsubsection:: Commands for the lowest level sections.
4218 * Raise/lower sections:: How to change commands' hierarchical level.
4222 @node Tree Structuring
4223 @section Tree Structure of Sections
4224 @cindex Tree structuring
4226 A Texinfo file is usually structured like a book with chapters,
4227 sections, subsections, and the like. This structure can be visualized
4228 as a tree (or rather as an upside-down tree) with the root at the top
4229 and the levels corresponding to chapters, sections, subsection, and
4230 subsubsections.@refill
4232 Here is a diagram that shows a Texinfo file with three chapters,
4233 each of which has two sections.@refill
4239 -------------------------------------
4241 Chapter 1 Chapter 2 Chapter 3
4243 -------- -------- --------
4245 Section Section Section Section Section Section
4246 1.1 1.2 2.1 2.2 3.1 3.2
4251 In a Texinfo file that has this structure, the beginning of Chapter 2
4252 looks like this:@refill
4256 @@node Chapter 2, Chapter 3, Chapter 1, top
4261 The chapter structuring commands are described in the sections that
4262 follow; the @code{@@node} and @code{@@menu} commands are described in
4263 following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
4266 @node Structuring Command Types
4267 @section Structuring Command Types
4269 The chapter structuring commands fall into four groups or series, each
4270 of which contains structuring commands corresponding to the
4271 hierarchical levels of chapters, sections, subsections, and
4272 subsubsections.@refill
4274 The four groups are the @code{@@chapter} series, the
4275 @code{@@unnumbered} series, the @code{@@appendix} series, and the
4276 @code{@@heading} series.@refill
4278 Each command produces titles that have a different appearance on the
4279 printed page or Info file; only some of the commands produce
4280 titles that are listed in the table of contents of a printed book or
4285 The @code{@@chapter} and @code{@@appendix} series of commands produce
4286 numbered or lettered entries both in the body of a printed work and in
4287 its table of contents.@refill
4290 The @code{@@unnumbered} series of commands produce unnumbered entries
4291 both in the body of a printed work and in its table of contents. The
4292 @code{@@top} command, which has a special use, is a member of this
4293 series (@pxref{makeinfo top, , @code{@@top}}). An @code{@@unnumbered}
4294 section should be associated with a node and be a normal part of the
4298 The @code{@@heading} series of commands produce simple unnumbered
4299 headings that do not appear in a table of contents, are not associated
4300 with nodes, and cannot be cross-referenced. The heading commands
4301 never start a new page.
4304 The @code{@@majorheading} command is similar to @code{@@chapheading},
4305 except that it generates a larger vertical whitespace before the
4309 When an @code{@@setchapternewpage} command says to do so, the
4310 @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
4311 start new pages in the printed manual; the @code{@@heading} commands
4315 Here are the four groups of chapter structuring commands:
4318 {\globaldefs = 1 \smallfonts}
4321 @multitable @columnfractions .19 .30 .29 .22
4322 @item @tab @tab @tab No new page
4323 @item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered}
4324 @item In contents @tab In contents @tab In contents @tab Not in contents
4325 @item @tab @code{@@top} @tab @tab @code{@@majorheading}
4326 @item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading}
4327 @item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading}
4328 @item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading}
4329 @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
4332 {\globaldefs = 1 \textfonts}
4337 @section @code{@@top}
4339 The @code{@@top} command is a special sectioning command that you use
4340 only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4341 The @code{@@top} command tells the @code{makeinfo} formatter which node
4342 is the `Top' node, so it can use it as the root of the node tree if your
4343 manual uses implicit node pointers. It has the same typesetting effect as
4344 @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
4345 and @code{@@appendix}}). For detailed information, see @ref{makeinfo
4346 top command, , The @code{@@top} Command}.
4348 The @code{@@top} node and its menu (if any) is conventionally wrapped in
4349 an @code{@@ifnottex} conditional so that it will appear only in Info and
4350 HTML output, not @TeX{}.
4354 @comment node-name, next, previous, up
4355 @section @code{@@chapter}
4358 @code{@@chapter} identifies a chapter in the document. Write the
4359 command at the beginning of a line and follow it on the same line by
4360 the title of the chapter.@refill
4362 For example, this chapter in this manual is entitled ``Chapter
4363 Structuring''; the @code{@@chapter} line looks like this:@refill
4366 @@chapter Chapter Structuring
4369 In @TeX{}, the @code{@@chapter} command creates a chapter in the
4370 document, specifying the chapter title. The chapter is numbered
4371 automatically.@refill
4373 In Info, the @code{@@chapter} command causes the title to appear on a
4374 line by itself, with a line of asterisks inserted underneath. Thus,
4375 in Info, the above example produces the following output:@refill
4383 Texinfo also provides a command @code{@@centerchap}, which is analogous
4384 to @code{@@unnumbered}, but centers its argument in the printed output.
4385 This kind of stylistic choice is not usually offered by Texinfo.
4386 @c but the Hacker's Dictionary wanted it ...
4389 @node unnumbered & appendix
4390 @section @code{@@unnumbered} and @code{@@appendix}
4394 Use the @code{@@unnumbered} command to create a chapter that appears
4395 in a printed manual without chapter numbers of any kind. Use the
4396 @code{@@appendix} command to create an appendix in a printed manual
4397 that is labelled by letter (`A', `B', @dots{}) instead of by number.
4399 Write an @code{@@appendix} or @code{@@unnumbered} command at the
4400 beginning of a line and follow it on the same line by the title, as
4401 you would if you were creating a chapter.
4404 @node majorheading & chapheading
4405 @section @code{@@majorheading}, @code{@@chapheading}
4406 @findex majorheading
4409 The @code{@@majorheading} and @code{@@chapheading} commands put
4410 chapter-like headings in the body of a document.@refill
4412 However, neither command causes @TeX{} to produce a numbered heading
4413 or an entry in the table of contents; and neither command causes
4414 @TeX{} to start a new page in a printed manual.@refill
4416 In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4417 whitespace before the heading than an @code{@@chapheading} command but
4418 is otherwise the same.
4421 the @code{@@majorheading} and
4422 @code{@@chapheading} commands are equivalent to
4423 @code{@@chapter}: the title is printed on a line by itself with a line
4424 of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
4428 @section @code{@@section}
4431 A @code{@@section} command identifies a section within a chapter unit,
4432 whether created with @code{@@chapter}, @code{@@unnumbered}, or
4433 @code{@@appendix}, following the numbering scheme of the chapter-level
4434 command. Thus, within a @code{@@chapter} chapter numbered `1', the
4435 section is numbered like `1.2'; within an @code{@@appendix}
4436 ``chapter'' labeled `A', the section is numbered like `A.2'; within an
4437 @code{@@unnumbered} chapter, the section gets no number.
4439 For example, this section is headed with an @code{@@section} command
4440 and looks like this in the Texinfo file:
4443 @@section @@code@{@@@@section@}
4446 To create a section, write the @code{@@section} command at the
4447 beginning of a line and follow it on the same line by the section
4448 title. The output is underlined with @samp{=} in Info.
4453 @@section This is a section
4457 might produce the following in Info:
4461 5.7 This is a section
4462 =====================
4467 @node unnumberedsec appendixsec heading
4468 @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
4469 @findex unnumberedsec
4473 The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4474 commands are, respectively, the unnumbered, appendix-like, and
4475 heading-like equivalents of the @code{@@section} command, as described
4476 in the previous section.
4479 @item @@unnumberedsec
4480 The @code{@@unnumberedsec} command may be used within an
4481 unnumbered chapter or within a regular chapter or appendix to
4482 provide an unnumbered section.@refill
4485 @itemx @@appendixsection
4486 @code{@@appendixsection} is a longer spelling of the
4487 @code{@@appendixsec} command; the two are synonymous.@refill
4488 @findex appendixsection
4490 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4491 command is used only within appendices.@refill
4494 You may use the @code{@@heading} command anywhere you wish for a
4495 section-style heading that will not appear in the table of contents.@refill
4498 @code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used
4499 in ordinary circumstances, because @code{@@section} may also be used
4500 within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
4501 the previous section.
4505 @section The @code{@@subsection} Command
4508 Subsections are to sections as sections are to chapters.
4509 (@xref{section, , @code{@@section}}.) In Info, subsection titles are
4510 underlined with @samp{-}. For example,
4513 @@subsection This is a subsection
4521 1.2.3 This is a subsection
4522 --------------------------
4526 In a printed manual, subsections are listed in the table of contents
4527 and are numbered three levels deep.@refill
4530 @node unnumberedsubsec appendixsubsec subheading
4531 @section The @code{@@subsection}-like Commands
4532 @cindex Subsection-like commands
4533 @findex unnumberedsubsec
4534 @findex appendixsubsec
4537 The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4538 @code{@@subheading} commands are, respectively, the unnumbered,
4539 appendix-like, and heading-like equivalents of the @code{@@subsection}
4540 command. (@xref{subsection, , @code{@@subsection}}.)
4542 In Info, the @code{@@subsection}-like commands generate a title
4543 underlined with hyphens. In a printed manual, an @code{@@subheading}
4544 command produces a heading like that of a subsection except that it is
4545 not numbered and does not appear in the table of contents. Similarly,
4546 an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4547 that of a subsection and an @code{@@appendixsubsec} command produces a
4548 subsection-like heading labelled with a letter and numbers; both of
4549 these commands produce headings that appear in the table of
4552 @code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
4553 be used in ordinary circumstances, because @code{@@subsection} may
4554 also be used within sections of @code{@@unnumbered} and
4555 @code{@@appendix} chapters (@pxref{section,,@code{section}}).
4559 @section The `subsub' Commands
4560 @cindex Subsub commands
4561 @findex subsubsection
4562 @findex unnumberedsubsubsec
4563 @findex appendixsubsubsec
4564 @findex subsubheading
4566 The fourth and lowest level sectioning commands in Texinfo are the
4567 `subsub' commands. They are:@refill
4570 @item @@subsubsection
4571 Subsubsections are to subsections as subsections are to sections.
4572 (@xref{subsection, , @code{@@subsection}}.) In a printed manual,
4573 subsubsection titles appear in the table of contents and are numbered
4574 four levels deep.@refill
4576 @item @@unnumberedsubsubsec
4577 Unnumbered subsubsection titles appear in the table of contents of a
4578 printed manual, but lack numbers. Otherwise, unnumbered
4579 subsubsections are the same as subsubsections. In Info, unnumbered
4580 subsubsections look exactly like ordinary subsubsections.@refill
4582 @item @@appendixsubsubsec
4583 Conventionally, appendix commands are used only for appendices and are
4584 lettered and numbered appropriately in a printed manual. They also
4585 appear in the table of contents. In Info, appendix subsubsections look
4586 exactly like ordinary subsubsections.@refill
4588 @item @@subsubheading
4589 The @code{@@subsubheading} command may be used anywhere that you need
4590 a small heading that will not appear in the table of contents. In
4591 Info, subsubheadings look exactly like ordinary subsubsection
4595 @code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec} do not
4596 need to be used in ordinary circumstances, because
4597 @code{@@subsubsection} may also be used within subsections of
4598 @code{@@unnumbered} and @code{@@appendix} chapters
4599 (@pxref{section,,@code{section}}).
4602 In Info, `subsub' titles are underlined with periods.
4606 @@subsubsection This is a subsubsection
4614 1.2.3.4 This is a subsubsection
4615 ...............................
4620 @node Raise/lower sections
4621 @section @code{@@raisesections} and @code{@@lowersections}
4622 @findex raisesections
4623 @findex lowersections
4624 @cindex Raising and lowering sections
4625 @cindex Lowering and raising sections
4626 @cindex Sections, raising and lowering
4628 The @code{@@raisesections} and @code{@@lowersections} commands
4629 implicitly raise and lower the hierarchical level of following
4630 chapters, sections and the other sectioning commands.
4632 That is, the @code{@@raisesections} command changes sections to
4633 chapters, subsections to sections, and so on. Conversely, the
4634 @code{@@lowersections} command changes chapters to sections, sections
4635 to subsections, and so on. Thus, an @code{@@lowersections} command
4636 cancels an @code{@@raisesections} command, and vice versa.
4638 @cindex Include files, and section levels
4639 You can use @code{@@lowersections} to include text written as an outer
4640 or standalone Texinfo file in another Texinfo file as an inner,
4641 included file. Typical usage looks like this:
4645 @@include somefile.texi
4649 @noindent (Without the @code{@@raisesections}, all the subsequent
4650 sections in the document would be lowered.)
4652 If the included file being lowered has a @code{@@top} node, you'll
4653 need to conditionalize its inclusion with a flag (@pxref{set value}).
4655 Another difficulty can arise with documents that use the (recommended)
4656 feature of @command{makeinfo} for implicitly determining node
4657 pointers. Since @command{makeinfo} must assume a hierarchically
4658 organized document to determine the pointers, you cannot just
4659 arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections}
4660 commands in the document. The final result has to have menus that
4661 take the raising and lowering into account. Therefore, as a practical
4662 matter, you generally only want to raise or lower large chunks,
4663 usually in external files as shown above.
4665 Repeated use of the commands continue to raise or lower the
4666 hierarchical level a step at a time. An attempt to raise above
4667 `chapter' reproduces chapter commands; an attempt to lower below
4668 `subsubsection' reproduces subsubsection commands. Also, lowered
4669 subsubsections and raised chapters will not work with
4670 @command{makeinfo}'s feature of implicitly determining node pointers,
4671 since the menu structure won't be correct.
4673 Write each @code{@@raisesections} and @code{@@lowersections} command
4674 on a line of its own.
4680 @dfn{Nodes} are the primary segments of a Texinfo file. They do not
4681 in and of themselves impose a hierarchical or any other kind of
4682 structure on a file. Nodes contain @dfn{node pointers} that name
4683 other nodes, and can contain @dfn{menus} which are lists of nodes. In
4684 Info, the movement commands can carry you to a pointed-to node or to a
4685 node listed in a menu.
4687 Node pointers and menus provide structure for Info files just as
4688 chapters, sections, subsections, and the like, provide structure for
4691 Because node names are used in cross-references, it is not desirable
4692 to casually change them. Such name changes invalidate references from
4693 other manuals, from mail archives, and so on.
4696 * Two Paths:: Different commands to structure
4697 Info output and printed output.
4698 * Node Menu Illustration:: A diagram, and sample nodes and menus.
4699 * node:: Creating nodes, in detail.
4700 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
4701 * anchor:: Defining arbitrary cross-reference targets.
4708 The node and menu commands and the chapter structuring commands are
4709 technically independent of each other:
4713 In Info, node and menu commands provide structure. The chapter
4714 structuring commands generate headings with different kinds of
4715 underlining---asterisks for chapters, hyphens for sections, and so on;
4716 they do nothing else.@refill
4719 In @TeX{}, the chapter structuring commands generate chapter and section
4720 numbers and tables of contents. The node and menu commands provide
4721 information for cross references; they do nothing else.@refill
4724 You can use node pointers and menus to structure an Info file any way
4725 you want; and you can write a Texinfo file so that its Info output has a
4726 different structure than its printed output. However, virtually all
4727 Texinfo files are written such that the structure for the Info output
4728 corresponds to the structure for the printed output. It is neither
4729 convenient nor understandable to the reader to do otherwise.@refill
4731 Generally, printed output is structured in a tree-like hierarchy in
4732 which the chapters are the major limbs from which the sections branch
4733 out. Similarly, node pointers and menus are organized to create a
4734 matching structure in the Info output.@refill
4737 @node Node Menu Illustration
4738 @section Node and Menu Illustration
4740 Here is a copy of the diagram shown earlier that illustrates a Texinfo
4741 file with three chapters, each of which contains two sections.@refill
4743 The ``root'' is at the top of the diagram and the ``leaves'' are at the
4744 bottom. This is how such a diagram is drawn conventionally; it
4745 illustrates an upside-down tree. For this reason, the root node is
4746 called the `Top' node, and `Up' node pointers carry you closer to the
4753 -------------------------------------
4755 Chapter 1 Chapter 2 Chapter 3
4757 -------- -------- --------
4759 Section Section Section Section Section Section
4760 1.1 1.2 2.1 2.2 3.1 3.2
4764 The fully-written command to start Chapter 2 would be this:
4768 @@node Chapter 2, Chapter 3, Chapter 1, Top
4769 @@comment node-name, next, previous, up
4774 This @code{@@node} line says that the name of this node is ``Chapter
4775 2'', the name of the `Next' node is ``Chapter 3'', the name of the
4776 `Previous' node is ``Chapter 1'', and the name of the `Up' node is
4777 ``Top''. You can omit writing out these node names if your document is
4778 hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
4779 pointer relationships still obtain.
4782 @strong{Please Note:} `Next' refers to the next node at the same
4783 hierarchical level in the manual, not necessarily to the next node
4784 within the Texinfo file. In the Texinfo file, the subsequent node may
4785 be at a lower level---a section-level node most often follows a
4786 chapter-level node, for example. `Next' and `Previous' refer to nodes
4787 at the @emph{same} hierarchical level. (The `Top' node contains the
4788 exception to this rule. Since the `Top' node is the only node at that
4789 level, `Next' refers to the first following node, which is almost always
4790 a chapter or chapter-level node.)@refill
4793 To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
4794 2. (@xref{Menus}.) You would write the menu just
4795 before the beginning of Section 2.1, like this:@refill
4800 * Sect. 2.1:: Description of this section.
4806 Write the node for Sect. 2.1 like this:@refill
4810 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4811 @@comment node-name, next, previous, up
4815 In Info format, the `Next' and `Previous' pointers of a node usually
4816 lead to other nodes at the same level---from chapter to chapter or from
4817 section to section (sometimes, as shown, the `Previous' pointer points
4818 up); an `Up' pointer usually leads to a node at the level above (closer
4819 to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4820 to `leaves'). (A cross reference can point to a node at any level;
4821 see @ref{Cross References}.)@refill
4823 Usually, an @code{@@node} command and a chapter structuring command are
4824 used in sequence, along with indexing commands. (You may follow the
4825 @code{@@node} line with a comment line that reminds you which pointer is
4828 Here is the beginning of the chapter in this manual called ``Ending a
4829 Texinfo File''. This shows an @code{@@node} line followed by a comment
4830 line, an @code{@@chapter} line, and then by indexing lines.@refill
4834 @@node Ending a File, Structuring, Beginning a File, Top
4835 @@comment node-name, next, previous, up
4836 @@chapter Ending a Texinfo File
4837 @@cindex Ending a Texinfo file
4838 @@cindex Texinfo file ending
4839 @@cindex File ending
4845 @section The @code{@@node} Command
4847 @cindex Node, defined
4850 A @dfn{node} is a segment of text that begins at an @code{@@node}
4851 command and continues until the next @code{@@node} command. The
4852 definition of node is different from that for chapter or section. A
4853 chapter may contain sections and a section may contain subsections;
4854 but a node cannot contain subnodes; the text of a node continues only
4855 until the next @code{@@node} command in the file. A node usually
4856 contains only one chapter structuring command, the one that follows
4857 the @code{@@node} line. On the other hand, in printed output nodes
4858 are used only for cross references, so a chapter or section may
4859 contain any number of nodes. Indeed, a chapter usually contains
4860 several nodes, one for each section, subsection, and
4863 To specify a node, write an @code{@@node} command at the beginning of
4864 a line, and follow it with up to four arguments, separated by commas,
4865 on the rest of the same line. The first argument is required; it is
4866 the name of this node (for details of node names, @pxref{Node Line
4867 Requirements}). The subsequent arguments are the names of the `Next',
4868 `Previous', and `Up' pointers, in that order, and may be omitted if
4869 your Texinfo document is hierarchically organized (@pxref{makeinfo
4872 @opindex accesskey@r{, in HTML output}
4873 Whether the node pointers are specified implicitly or explicitly, the
4874 HTML output from @command{makeinfo} for each node includes links to
4875 the `Next', `Previous', and `Up' nodes. The HTML also uses the
4876 @code{accesskey} attribute with the values @samp{n}, @samp{p}, and
4877 @samp{u} respectively. This allows people using web browsers to
4878 follow the nagivation using (typically) @kbd{M-@var{letter}}, e.g.,
4879 @kbd{M-n} for the `Next' node, from anywhere within the node.
4881 You may insert spaces before each name on the @code{@@node} line if
4882 you wish; the spaces are ignored. You must write the name of the node
4883 and (if present) the names of the `Next', `Previous', and `Up'
4884 pointers all on the same line. Otherwise, the formatters fail.
4885 (@inforef{Top, info, info}, for more information about nodes in Info.)
4887 Usually, you write one of the chapter-structuring command lines
4888 immediately after an @code{@@node} line---for example, an
4889 @code{@@section} or @code{@@subsection} line. (@xref{Structuring
4892 @TeX{} uses @code{@@node} lines to identify the names to use for cross
4893 references. For this reason, you must write @code{@@node} lines in a
4894 Texinfo file that you intend to format for printing, even if you do not
4895 intend to format it for Info. (Cross references, such as the one at the
4896 end of this sentence, are made with @code{@@xref} and related commands;
4897 see @ref{Cross References}.)
4900 * Node Names:: How to choose node and pointer names.
4901 * Writing a Node:: How to write an @code{@@node} line.
4902 * Node Line Tips:: Keep names short.
4903 * Node Line Requirements:: Keep names unique, without @@-commands.
4904 * First Node:: How to write a `Top' node.
4905 * makeinfo top command:: How to use the @code{@@top} command.
4910 @subsection Choosing Node and Pointer Names
4912 @cindex Node names, choosing
4913 The name of a node identifies the node (for details of node names,
4914 @pxref{Node Line Requirements}). The pointers enable you to reach
4915 other nodes and consist simply of the names of those nodes.
4917 Normally, a node's `Up' pointer contains the name of the node whose
4918 menu mentions that node. The node's `Next' pointer contains the name
4919 of the node that follows the present node in that menu and its
4920 `Previous' pointer contains the name of the node that precedes it in
4921 that menu. When a node's `Previous' node is the same as its `Up'
4922 node, both node pointers name the same node.
4924 Usually, the first node of a Texinfo file is the `Top' node, and its
4925 `Up' and `Previous' pointers point to the @file{dir} file, which
4926 contains the main menu for all of Info.
4928 The `Top' node itself contains the main or master menu for the manual.
4929 Also, it is helpful to include a brief description of the manual in the
4930 `Top' node. @xref{First Node}, for information on how to write the
4931 first node of a Texinfo file.
4933 Even when you explicitly specify all pointers, that does not mean you
4934 can write the nodes in the Texinfo source file in an arbitrary order!
4935 Because @TeX{} processes the file sequentially, irrespective of node
4936 pointers, you must write the nodes in the order you wish them to appear
4940 @node Writing a Node
4941 @subsection How to Write an @code{@@node} Line
4942 @cindex Writing an @code{@@node} line
4943 @cindex @code{@@node} line writing
4944 @cindex Node line writing
4946 The easiest way to write an @code{@@node} line is to write @code{@@node}
4947 at the beginning of a line and then the name of the node, like
4951 @@node @var{node-name}
4954 If you are using GNU Emacs, you can use the update node commands
4955 provided by Texinfo mode to insert the names of the pointers; or you
4956 can leave the pointers out of the Texinfo file and let @code{makeinfo}
4957 insert node pointers into the Info file it creates. (@xref{Texinfo
4958 Mode}, and @ref{makeinfo Pointer Creation}.)
4960 Alternatively, you can insert the `Next', `Previous', and `Up'
4961 pointers yourself. If you do this, you may find it helpful to use the
4962 Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
4963 @samp{@@node} and a comment line listing the names of the pointers in
4964 their proper order. The comment line helps you keep track of which
4965 arguments are for which pointers. This comment line is especially useful
4966 if you are not familiar with Texinfo.
4968 The template for a fully-written-out node line with `Next', `Previous',
4969 and `Up' pointers looks like this:
4972 @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4975 The @var{node-name} argument must be present, but the others are
4976 optional. If you wish to specify some but not others, just insert
4977 commas as needed, as in: @samp{@@node mynode,,,uppernode}. However,
4978 we recommend leaving off all the pointers and letting @code{makeinfo}
4979 determine them, as described above.
4981 If you wish, you can ignore @code{@@node} lines altogether in your first
4982 draft and then use the @code{texinfo-insert-node-lines} command to
4983 create @code{@@node} lines for you. However, we do not recommend this
4984 practice. It is better to name the node itself at the same time that
4985 you write a segment so you can easily make cross references. A large
4986 number of cross references are an especially important feature of a good
4989 After you have inserted an @code{@@node} line, you should immediately
4990 write an @@-command for the chapter or section and insert its name.
4991 Next (and this is important!), put in several index entries. Usually,
4992 you will find at least two and often as many as four or five ways of
4993 referring to the node in the index. Use them all. This will make it
4994 much easier for people to find the node.
4997 @node Node Line Tips
4998 @subsection @code{@@node} Line Tips
5000 Here are three suggestions:
5004 Try to pick node names that are informative but short.@refill
5006 In the Info file, the file name, node name, and pointer names are all
5007 inserted on one line, which may run into the right edge of the window.
5008 (This does not cause a problem with Info, but is ugly.)@refill
5011 Try to pick node names that differ from each other near the beginnings
5012 of their names. This way, it is easy to use automatic name completion in
5016 By convention, node names are capitalized just as they would be for
5017 section or chapter titles---initial and significant words are
5018 capitalized; others are not.@refill
5022 @node Node Line Requirements
5023 @subsection @code{@@node} Line Requirements
5025 @cindex Node line requirements
5026 @cindex Restrictions on node names
5027 Here are several requirements for @code{@@node} lines:
5030 @cindex Unique nodename requirement
5031 @cindex Node name must be unique
5033 All the node names for a single Info file must be unique.
5035 Duplicates confuse the Info movement commands. This means, for
5036 example, that if you end every chapter with a summary, you must name
5037 each summary node differently. You cannot just call each one
5038 ``Summary''. You may, however, duplicate the titles of chapters, sections,
5039 and the like. Thus you can end each chapter in a book with a section
5040 called ``Summary'', so long as the node names for those sections are all
5044 A pointer name must be the name of a node.
5046 The node to which a pointer points may come before or after the
5047 node containing the pointer.
5049 @cindex @@-commands in nodename
5050 @cindex Node name, should not contain @@-commands
5052 @@-commands in node names are not allowed. This includes punctuation
5053 characters that are escaped with a @samp{@@}, such as @code{@@} and
5054 @code{@{}, and accent commands such as @samp{@@'}. (For a few cases
5055 when this is useful, Texinfo has limited support for using
5056 @w{@@-commands} in node names; see @ref{Pointer Validation}.) Perhaps
5057 this limitation will be removed some day.
5060 @cindex Colon in nodename
5061 @cindex Comma in nodename
5062 @cindex Parentheses in nodename
5063 @cindex Period in nodename
5064 @cindex Characters, invalid in node name
5065 @cindex Invalid characters in node names
5066 @cindex Node names, invalid characters in
5067 Unfortunately, you cannot use periods, commas, colons or parentheses
5068 within a node name; these confuse the Texinfo processors. Perhaps
5069 this limitation will be removed some day, too.
5072 For example, the following is a section title in this manual:
5075 @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
5079 But the corresponding node name lacks the commas and the @@'s:
5082 unnumberedsec appendixsec heading
5085 @cindex Case in node name
5087 Case is significant in node names.
5089 @cindex White space in node name
5090 @cindex Spaces in node name
5091 Spaces before and after names on the @samp{@@node} line are ignored,
5092 but spaces ``inside'' a name are significant. For example:
5100 @noindent all define the same node, @samp{foo bar}. References to the
5101 node should all use that name, without the leading or trailing spaces,
5102 but with the internal spaces.
5107 @subsection The First Node
5108 @cindex Top node is first
5111 The first node of a Texinfo file is the @dfn{Top} node, except in an
5112 included file (@pxref{Include Files}). The Top node should contain a
5113 short summary, copying permissions, and a master menu. @xref{The Top
5114 Node}, for more information on the Top node contents and examples.
5116 Here is a description of the node pointers to be used in the Top node:
5121 @cindex Up node of Top node
5122 @cindex (dir) as Up node of Top node
5123 The Top node (which must be named @samp{top} or @samp{Top}) should have
5124 as its `Up' node the name of a node in another file, where there is a
5125 menu that leads to this file. Specify the file name in parentheses.
5127 Usually, all Info files are installed in the same Info directory tree;
5128 in this case, use @samp{(dir)} as the parent of the Top node; this is
5129 short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
5130 file, which contains the main menu for the Info system as a whole.
5133 @cindex Prev node of Top node
5134 The `Prev' node of the Top node should also be your @samp{(dir)} file.
5137 @cindex Next node of Top node
5138 The `Next' node of the Top node should be the first chapter in your
5143 @xref{Installing an Info File}, for more information about installing
5144 an Info file in the @file{info} directory.
5146 It is usually best to leave the pointers off entirely and let the
5147 tools implicitly define them, with this simple result:
5154 @node makeinfo top command
5155 @subsection The @code{@@top} Sectioning Command
5156 @findex top @r{(@@-command)}
5158 A special sectioning command, @code{@@top} should be used with the
5159 @code{@@node Top} line. The @code{@@top} sectioning command tells
5160 @code{makeinfo} that it marks the `Top' node in the file. It provides
5161 the information that @code{makeinfo} needs to insert node pointers
5162 automatically. Write the @code{@@top} command at the beginning of the
5163 line immediately following the @code{@@node Top} line. Write the title
5164 on the remaining part of the same line as the @code{@@top} command.
5166 In Info, the @code{@@top} sectioning command causes the title to appear
5167 on a line by itself, with a line of asterisks inserted underneath, as
5168 other sectioning commands do.
5170 In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
5171 sectioning command is merely a synonym for @code{@@unnumbered}.
5172 Neither of these formatters require an @code{@@top} command, and do
5173 nothing special with it. You can use @code{@@chapter} or
5174 @code{@@unnumbered} after the @code{@@node Top} line when you use
5175 these formatters. Also, you can use @code{@@chapter} or
5176 @code{@@unnumbered} when you use the Texinfo updating commands to
5177 create or update pointers and menus.
5179 Thus, in practice, a Top node starts like this:
5183 @@top Your Manual Title
5187 @node makeinfo Pointer Creation
5188 @section Creating Pointers with @code{makeinfo}
5189 @cindex Creating pointers with @code{makeinfo}
5190 @cindex Pointer creation with @code{makeinfo}
5191 @cindex Automatic pointer creation with @code{makeinfo}
5193 The @code{makeinfo} program has a feature for automatically
5194 determining node pointers for a hierarchically organized document. We
5195 highly recommend using it.
5197 When you take advantage of this feature, you do not need to write the
5198 `Next', `Previous', and `Up' pointers after the name of a node.
5199 However, you must write a sectioning command, such as @code{@@chapter}
5200 or @code{@@section}, on the line immediately following each truncated
5201 @code{@@node} line (except that comment lines may intervene).
5203 In addition, you must follow the `Top' @code{@@node} line with a line
5204 beginning with @code{@@top} to mark the `Top' node in the
5205 file. @xref{makeinfo top, , @code{@@top}}.
5207 Finally, you must write the name of each node (except for the `Top'
5208 node) in a menu that is one or more hierarchical levels above the
5209 node's hierarchical level.
5213 If you use a detailed menu in your master menu (@pxref{Master Menu
5214 Parts}), mark it with the @code{@@detailmenu @@dots@{@} @@end
5215 detailmenu} environment, or @command{makeinfo} will get confused,
5216 typically about the last and/or first node in the document.
5218 This implicit node pointer creation feature in @code{makeinfo}
5219 relieves you from the need to update menus and pointers manually or
5220 with Texinfo mode commands. (@xref{Updating Nodes and Menus}.)
5222 In most cases, you will want to take advantage of this feature and not
5223 redundantly specify node pointers. However, Texinfo documents are not
5224 required to be organized hierarchically or in fact to contain
5225 sectioning commands at all (for example, if you never intend the
5226 document to be printed). The special procedure for handling the short
5227 text before a menu (@pxref{Menus}) also disables this
5228 feature, for that group of nodes. In those cases, you will need to
5229 explicitly specify all pointers.
5232 @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
5236 @cindex Cross-reference targets, arbitrary
5237 @cindex Targets for cross-references, arbitrary
5239 An @dfn{anchor} is a position in your document, labeled so that
5240 cross-references can refer to it, just as they can to nodes. You create
5241 an anchor with the @code{@@anchor} command, and give the label as a
5242 normal brace-delimited argument. For example:
5245 This marks the @@anchor@{x-spot@}spot.
5247 @@xref@{x-spot,,the spot@}.
5253 This marks the spot.
5255 See [the spot], page 1.
5258 As you can see, the @code{@@anchor} command itself produces no output.
5259 This example defines an anchor `x-spot' just before the word `spot'.
5260 You can refer to it later with an @code{@@xref} or other cross-reference
5261 command, as shown. @xref{Cross References}, for details on the
5262 cross-reference commands.
5264 It is best to put @code{@@anchor} commands just before the position you
5265 wish to refer to; that way, the reader's eye is led on to the correct
5266 text when they jump to the anchor. You can put the @code{@@anchor}
5267 command on a line by itself if that helps readability of the source.
5268 Whitespace (including newlines) is ignored after @code{@@anchor}.
5270 Anchor names and node names may not conflict. Anchors and nodes are
5271 given similar treatment in some ways; for example, the @code{goto-node}
5272 command in standalone Info takes either an anchor name or a node name as
5273 an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
5275 Also like node names, anchor names cannot include some characters
5276 (@pxref{Node Line Requirements}).
5284 @dfn{Menus} contain pointers to subordinate nodes. In online output,
5285 you use menus to go to such nodes. Menus have no effect in printed
5286 manuals and do not appear in them.
5288 A node with a menu should not contain much text. If you find yourself
5289 writing a lot of text before a menu, we generally recommend moving
5290 most of the text into a new subnode---all but a paragraph or two.
5291 Otherwise, a reader with a terminal that displays only a few lines may
5292 miss the menu and its associated text. As a practical matter, it is
5293 best to locate a menu within 20 or so lines of the beginning of the
5297 * Menu Location:: Menus go at the ends of short nodes.
5298 * Writing a Menu:: What is a menu?
5299 * Menu Parts:: A menu entry has three parts.
5300 * Less Cluttered Menu Entry:: Two part menu entry.
5301 * Menu Example:: Two and three part menu entries.
5302 * Other Info Files:: How to refer to a different Info file.
5307 @section Menu Location
5308 @cindex Menu location
5309 @cindex Location of menus
5311 A menu must be located at the end of a node, without any regular text
5312 or additional commands between the @code{@@end menu} and the beginning
5313 of the next node. (As a consequence, there may be at most one menu in
5316 @cindex Info format, and menus
5317 This is actually a useful restriction, since a reader who uses the
5318 menu could easily miss any such text. Technically, it is necessary
5319 because in Info format, there is no marker for the end of a menu, so
5320 Info-reading programs would have no way to know when the menu ends and
5321 normal text resumes.
5323 @cindex Hierarchical documents, and menus
5324 Technically, menus can carry you to any node, regardless of the
5325 structure of the document; even to nodes in a different Info file.
5326 However, we do not recommend ever making use of this, because the
5327 @command{makeinfo} implicit pointer creation feature (@pxref{makeinfo
5328 Pointer Creation}) and GNU Emacs Texinfo mode updating commands work
5329 only to create menus of subordinate nodes in a hierarchically
5330 structured document. Instead, use cross references to refer to
5333 In the past, we recommended using a @samp{@@heading} command within an
5334 @code{@@ifinfo} conditional instead of the normal sectioning commands
5335 after a very short node with a menu. This had the advantage of making
5336 the printed output look better, because there was no very short text
5337 between two headings on the page. But this also does not work with
5338 @command{makeinfo}'s implicit pointer creation, and it also makes the
5339 XML output incorrect, since it does not reflect the true document
5340 structure. So, regrettably, we can no longer recommend this.
5343 @node Writing a Menu
5344 @section Writing a Menu
5345 @cindex Writing a menu
5346 @cindex Menu writing
5348 A menu consists of an @code{@@menu} command on a line by itself
5349 followed by menu entry lines or menu comment lines and then by an
5350 @code{@@end menu} command on a line by itself.
5352 A menu looks like this:
5357 Larger Units of Text
5359 * Files:: All about handling files.
5360 * Multiples: Buffers. Multiple buffers; editing
5361 several files at once.
5366 In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
5367 entry}. (Note the space after the asterisk.) A line that does not
5368 start with an @w{@samp{* }} may also appear in a menu. Such a line is
5369 not a menu entry but is a menu comment line that appears in the Info
5370 file. In the example above, the line @samp{Larger Units of Text} is a
5371 menu comment line; the two lines starting with @w{@samp{* }} are menu
5372 @cindex Spaces, in menus
5373 entries. Space characters in a menu are preserved as-is; this allows
5374 you to format the menu as you wish.
5376 @opindex accesskey@r{, in HTML output}
5377 In the HTML output from @command{makeinfo}, the @code{accesskey}
5378 attribute is used with the values @samp{1}@dots{}@samp{9} for the
5379 first nine entries. This allows people using web browsers to follow
5380 the first menu entries using (typically) @kbd{M-@var{digit}}, e.g.,
5381 @kbd{M-1} for the first entry.
5385 @section The Parts of a Menu
5386 @cindex Parts of a menu
5388 @cindex @code{@@menu} parts
5390 A menu entry has three parts, only the second of which is required:
5394 The menu entry name (optional).
5397 The name of the node (required).
5400 A description of the item (optional).
5403 The template for a generic menu entry looks like this (but see the
5404 next section for one more possibility):
5407 * @var{menu-entry-name}: @var{node-name}. @var{description}
5410 Follow the menu entry name with a single colon and follow the node name
5411 with tab, comma, newline, or the two characters period and space
5414 In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5415 command. The menu entry name is what the user types after the @kbd{m}
5418 The third part of a menu entry is a descriptive phrase or sentence.
5419 Menu entry names and node names are often short; the description
5420 explains to the reader what the node is about. A useful description
5421 complements the node name rather than repeats it. The description,
5422 which is optional, can spread over two or more lines; if it does, some
5423 authors prefer to indent the second line while others prefer to align it
5424 with the first (and all others). It's up to you.
5427 @node Less Cluttered Menu Entry
5428 @section Less Cluttered Menu Entry
5429 @cindex Two part menu entry
5430 @cindex Double-colon menu entries
5431 @cindex Menu entries with two colons
5432 @cindex Less cluttered menu entry
5433 @cindex Uncluttered menu entry
5435 When the menu entry name and node name are the same, you can write
5436 the name immediately after the asterisk and space at the beginning of
5437 the line and follow the name with two colons.
5443 * Name:: @var{description}
5451 * Name: Name. @var{description}
5454 You should indeed use the node name for the menu entry name whenever
5455 possible, since it reduces visual clutter in the menu.
5459 @section A Menu Example
5460 @cindex Menu example
5461 @cindex Example menu
5463 A menu looks like this in Texinfo:@refill
5468 * menu entry name: Node name. A short description.
5469 * Node name:: This form is preferred.
5482 * menu entry name: Node name. A short description.
5483 * Node name:: This form is preferred.
5488 Here is an example as you might see it in a Texinfo file:@refill
5493 Larger Units of Text
5495 * Files:: All about handling files.
5496 * Multiples: Buffers. Multiple buffers; editing
5497 several files at once.
5509 Larger Units of Text
5511 * Files:: All about handling files.
5512 * Multiples: Buffers. Multiple buffers; editing
5513 several files at once.
5517 In this example, the menu has two entries. @samp{Files} is both a menu
5518 entry name and the name of the node referred to by that name.
5519 @samp{Multiples} is the menu entry name; it refers to the node named
5520 @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5521 appears in the menu, but is not an entry.@refill
5523 Since no file name is specified with either @samp{Files} or
5524 @samp{Buffers}, they must be the names of nodes in the same Info file
5525 (@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5527 @node Other Info Files
5528 @comment node-name, next, previous, up
5529 @section Referring to Other Info Files
5530 @cindex Referring to other Info files
5531 @cindex Nodes in other Info files
5532 @cindex Other Info files' nodes
5533 @cindex Going to other Info files' nodes
5534 @cindex Info; other files' nodes
5536 You can create a menu entry that enables a reader in Info to go to a
5537 node in another Info file by writing the file name in parentheses just
5538 before the node name. In this case, you should use the three-part menu
5539 entry format, which saves the reader from having to type the file
5543 The format looks like this:@refill
5548 * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
5549 * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5554 For example, to refer directly to the @samp{Outlining} and
5555 @samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
5556 menu like this:@refill
5561 * Outlining: (emacs)Outline Mode. The major mode for
5563 * Rebinding: (emacs)Rebinding. How to redefine the
5569 If you do not list the node name, but only name the file, then Info
5570 presumes that you are referring to the `Top' node.@refill
5572 The @file{dir} file that contains the main menu for Info has menu
5573 entries that list only file names. These take you directly to the `Top'
5574 nodes of each Info document. (@xref{Installing an Info File}.)
5581 * Info: (info). Documentation browsing system.
5582 * Emacs: (emacs). The extensible, self-documenting
5588 (The @file{dir} top level directory for the Info system is an Info file,
5589 not a Texinfo file, but a menu entry looks the same in both types of
5592 The GNU Emacs Texinfo mode menu updating commands only work with nodes
5593 within the current buffer, so you cannot use them to create menus that
5594 refer to other files. You must write such menus by hand.
5597 @node Cross References
5598 @chapter Cross References
5599 @cindex Making cross references
5600 @cindex Cross references
5603 @dfn{Cross references} are used to refer the reader to other parts of the
5604 same or different Texinfo files. In Texinfo, nodes and anchors are the
5605 places to which cross references can refer.
5608 * References:: What cross references are for.
5609 * Cross Reference Commands:: A summary of the different commands.
5610 * Cross Reference Parts:: A cross reference has several parts.
5611 * xref:: Begin a reference with `See' @dots{}
5612 * Top Node Naming:: How to refer to the beginning of another file.
5613 * ref:: A reference for the last part of a sentence.
5614 * pxref:: How to write a parenthetical cross reference.
5615 * inforef:: How to refer to an Info-only file.
5616 * uref:: How to refer to a uniform resource locator.
5617 * cite:: How to refer to books not in the Info system.
5621 @section What References Are For
5623 Often, but not always, a printed document should be designed so that
5624 it can be read sequentially. People tire of flipping back and forth
5625 to find information that should be presented to them as they need
5628 However, in any document, some information will be too detailed for
5629 the current context, or incidental to it; use cross references to
5630 provide access to such information. Also, an online help system or a
5631 reference manual is not like a novel; few read such documents in
5632 sequence from beginning to end. Instead, people look up what they
5633 need. For this reason, such creations should contain many cross
5634 references to help readers find other information that they may not
5637 In a printed manual, a cross reference results in a page reference,
5638 unless it is to another manual altogether, in which case the cross
5639 reference names that manual.@refill
5641 In Info, a cross reference results in an entry that you can follow
5642 using the Info @samp{f} command. (@inforef{Help-Xref, Following
5643 cross-references, info}.)
5645 The various cross reference commands use nodes (or anchors,
5646 @pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
5647 This is evident in Info, in which a cross reference takes you to the
5648 specified location. @TeX{} also uses nodes to define cross reference
5649 locations, but the action is less obvious. When @TeX{} generates a DVI
5650 file, it records each node's page number and uses the page numbers in making
5651 references. Thus, if you are writing a manual that will only be
5652 printed, and will not be used online, you must nonetheless write
5653 @code{@@node} lines to name the places to which you make cross
5657 @node Cross Reference Commands
5658 @comment node-name, next, previous, up
5659 @section Different Cross Reference Commands
5660 @cindex Different cross reference commands
5662 There are four different cross reference commands:@refill
5666 Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5667 or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5670 Used within or, more often, at the end of a sentence; same as
5671 @code{@@xref} for Info; produces just the reference in the printed
5672 manual without a preceding `See'.@refill
5675 Used within parentheses to make a reference that suits both an Info
5676 file and a printed book. Starts with a lower case `see' within the
5677 printed manual. (@samp{p} is for `parenthesis'.)@refill
5680 Used to make a reference to an Info file for which there is no printed
5685 (The @code{@@cite} command is used to make references to books and
5686 manuals for which there is no corresponding Info file and, therefore,
5687 no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
5689 @node Cross Reference Parts
5690 @comment node-name, next, previous, up
5691 @section Parts of a Cross Reference
5692 @cindex Cross reference parts
5693 @cindex Parts of a cross reference
5695 A cross reference command requires only one argument, which is the
5696 name of the node to which it refers. But a cross reference command
5697 may contain up to four additional arguments. By using these
5698 arguments, you can provide a cross reference name for Info, a topic
5699 description or section title for the printed output, the name of a
5700 different Info file, and the name of a different printed
5703 Here is a simple cross reference example:@refill
5706 @@xref@{Node name@}.
5720 See Section @var{nnn} [Node name], page @var{ppp}.
5724 Here is an example of a full five-part cross reference:@refill
5728 @@xref@{Node name, Cross Reference Name, Particular Topic,
5729 info-file-name, A Printed Manual@}, for details.
5737 *Note Cross Reference Name: (info-file-name)Node name,
5745 See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5751 The five possible arguments for a cross reference are:@refill
5755 The node or anchor name (required). This is the location to which the
5756 cross reference takes you. In a printed document, the location of the
5757 node provides the page reference only for references within the same
5761 The cross reference name for the Info reference, if it is to be
5762 different from the node name or the topic description. If you
5763 include this argument, it becomes the first part of the cross reference.
5764 It is usually omitted; then the topic description (third argument) is
5765 used if it was specified; if that was omitted as well, the node name
5769 A topic description or section name. Often, this is the title of the
5770 section. This is used as the name of the reference in the printed
5771 manual. If omitted, the node name is used.@refill
5774 The name of the Info file in which the reference is located, if it is
5775 different from the current file. You need not include any @samp{.info}
5776 suffix on the file name, since Info readers try appending it
5780 The name of a printed manual from a different Texinfo file.@refill
5783 The template for a full five argument cross reference looks like
5788 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5789 @var{info-file-name}, @var{printed-manual-title}@}.
5793 Cross references with one, two, three, four, and five arguments are
5794 described separately following the description of @code{@@xref}.@refill
5796 Write a node name in a cross reference in exactly the same way as in
5797 the @code{@@node} line, including the same capitalization; otherwise, the
5798 formatters may not find the reference.@refill
5800 You can write cross reference commands within a paragraph, but note
5801 how Info and @TeX{} format the output of each of the various commands:
5802 write @code{@@xref} at the beginning of a sentence; write
5803 @code{@@pxref} only within parentheses, and so on.@refill
5806 @comment node-name, next, previous, up
5807 @section @code{@@xref}
5809 @cindex Cross references using @code{@@xref}
5810 @cindex References using @code{@@xref}
5812 The @code{@@xref} command generates a cross reference for the
5813 beginning of a sentence. The Info formatting commands convert it into
5814 an Info cross reference, which the Info @samp{f} command can use to
5815 bring you directly to another node. The @TeX{} typesetting commands
5816 convert it into a page reference, or a reference to another book or
5820 * Reference Syntax:: What a reference looks like and requires.
5821 * One Argument:: @code{@@xref} with one argument.
5822 * Two Arguments:: @code{@@xref} with two arguments.
5823 * Three Arguments:: @code{@@xref} with three arguments.
5824 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
5827 @node Reference Syntax
5828 @subsection What a Reference Looks Like and Requires
5830 Most often, an Info cross reference looks like this:@refill
5833 *Note @var{node-name}::.
5840 *Note @var{cross-reference-name}: @var{node-name}.
5844 In @TeX{}, a cross reference looks like this:
5847 See Section @var{section-number} [@var{node-name}], page @var{page}.
5854 See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5857 The @code{@@xref} command does not generate a period or comma to end
5858 the cross reference in either the Info file or the printed output.
5859 You must write that period or comma yourself; otherwise, Info will not
5860 recognize the end of the reference. (The @code{@@pxref} command works
5861 differently. @xref{pxref, , @code{@@pxref}}.)@refill
5864 A period or comma @strong{must} follow the closing
5865 brace of an @code{@@xref}. It is required to terminate the cross
5866 reference. This period or comma will appear in the output, both in
5867 the Info file and in the printed manual.@refill
5870 @code{@@xref} must refer to an Info node by name. Use @code{@@node}
5871 to define the node (@pxref{Writing a Node}).@refill
5873 @code{@@xref} is followed by several arguments inside braces, separated by
5874 commas. Whitespace before and after these commas is ignored.@refill
5876 A cross reference requires only the name of a node; but it may contain
5877 up to four additional arguments. Each of these variations produces a
5878 cross reference that looks somewhat different.@refill
5881 Commas separate arguments in a cross reference;
5882 avoid including them in the title or other part lest the formatters
5883 mistake them for separators.@refill
5887 @subsection @code{@@xref} with One Argument
5889 The simplest form of @code{@@xref} takes one argument, the name of
5890 another node in the same Info file. The Info formatters produce
5891 output that the Info readers can use to jump to the reference; @TeX{}
5892 produces output that specifies the page and section number for you.@refill
5899 @@xref@{Tropical Storms@}.
5906 *Note Tropical Storms::.
5913 See Section 3.1 [Tropical Storms], page 24.
5917 (Note that in the preceding example the closing brace is followed by a
5920 You can write a clause after the cross reference, like this:@refill
5923 @@xref@{Tropical Storms@}, for more info.
5930 *Note Tropical Storms::, for more info.
5937 See Section 3.1 [Tropical Storms], page 24, for more info.
5941 (Note that in the preceding example the closing brace is followed by a
5942 comma, and then by the clause, which is followed by a period.)@refill
5945 @subsection @code{@@xref} with Two Arguments
5947 With two arguments, the second is used as the name of the Info cross
5948 reference, while the first is still the name of the node to which the
5949 cross reference points.@refill
5953 The template is like this:
5956 @@xref@{@var{node-name}, @var{cross-reference-name}@}.
5964 @@xref@{Electrical Effects, Lightning@}.
5971 *Note Lightning: Electrical Effects.
5978 See Section 5.2 [Electrical Effects], page 57.
5982 (Note that in the preceding example the closing brace is followed by a
5983 period; and that the node name is printed, not the cross reference name.)
5985 You can write a clause after the cross reference, like this:@refill
5988 @@xref@{Electrical Effects, Lightning@}, for more info.
5994 *Note Lightning: Electrical Effects, for more info.
6001 See Section 5.2 [Electrical Effects], page 57, for more info.
6005 (Note that in the preceding example the closing brace is followed by a
6006 comma, and then by the clause, which is followed by a period.)@refill
6008 @node Three Arguments
6009 @subsection @code{@@xref} with Three Arguments
6011 A third argument replaces the node name in the @TeX{} output. The third
6012 argument should be the name of the section in the printed output, or
6013 else state the topic discussed by that section. Often, you will want to
6014 use initial upper case letters so it will be easier to read when the
6015 reference is printed. Use a third argument when the node name is
6016 unsuitable because of syntax or meaning.@refill
6018 Remember to avoid placing a comma within the title or topic section of
6019 a cross reference, or within any other section. The formatters divide
6020 cross references into arguments according to the commas; a comma
6021 within a title or other section will divide it into two arguments. In
6022 a reference, you need to write a title such as ``Clouds, Mist, and
6023 Fog'' without the commas.@refill
6025 Also, remember to write a comma or period after the closing brace of an
6026 @code{@@xref} to terminate the cross reference. In the following
6027 examples, a clause follows a terminating comma.@refill
6032 The template is like this:
6036 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
6046 @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
6055 *Note Lightning: Electrical Effects, for details.
6062 See Section 5.2 [Thunder and Lightning], page 57, for details.
6065 If a third argument is given and the second one is empty, then the
6066 third argument serves both. (Note how two commas, side by side, mark
6067 the empty second argument.)@refill
6071 @@xref@{Electrical Effects, , Thunder and Lightning@},
6080 *Note Thunder and Lightning: Electrical Effects, for details.
6087 See Section 5.2 [Thunder and Lightning], page 57, for details.
6090 As a practical matter, it is often best to write cross references with
6091 just the first argument if the node name and the section title are the
6092 same, and with the first and third arguments if the node name and title
6093 are different.@refill
6095 Here are several examples from @cite{The GNU Awk User's Guide}:@refill
6098 @@xref@{Sample Program@}.
6100 @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
6101 @@xref@{Close Output, , Closing Output Files and Pipes@},
6102 for more information.
6103 @@xref@{Regexp, , Regular Expressions as Patterns@}.
6106 @node Four and Five Arguments
6107 @subsection @code{@@xref} with Four and Five Arguments
6109 In a cross reference, a fourth argument specifies the name of another
6110 Info file, different from the file in which the reference appears, and
6111 a fifth argument specifies its title as a printed manual.@refill
6113 Remember that a comma or period must follow the closing brace of an
6114 @code{@@xref} command to terminate the cross reference. In the
6115 following examples, a clause follows a terminating comma.@refill
6123 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
6124 @var{info-file-name}, @var{printed-manual-title}@}.
6133 @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
6134 weather, An Introduction to Meteorology@}, for details.
6141 *Note Lightning: (weather)Electrical Effects, for details.
6145 The name of the Info file is enclosed in parentheses and precedes
6146 the name of the node.
6149 In a printed manual, the reference looks like this:@refill
6152 See section ``Thunder and Lightning'' in @i{An Introduction to
6153 Meteorology}, for details.
6157 The title of the printed manual is typeset in italics; and the
6158 reference lacks a page number since @TeX{} cannot know to which page a
6159 reference refers when that reference is to another manual.@refill
6161 Often, you will leave out the second argument when you use the long
6162 version of @code{@@xref}. In this case, the third argument, the topic
6163 description, will be used as the cross reference name in Info.@refill
6166 The template looks like this:
6169 @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
6170 @var{printed-manual-title}@}, for details.
6177 *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
6184 See section @var{title-or-topic} in @var{printed-manual-title}, for details.
6192 @@xref@{Electrical Effects, , Thunder and Lightning,
6193 weather, An Introduction to Meteorology@}, for details.
6201 *Note Thunder and Lightning: (weather)Electrical Effects,
6210 See section ``Thunder and Lightning'' in @i{An Introduction to
6211 Meteorology}, for details.
6214 On rare occasions, you may want to refer to another Info file that
6215 is within a single printed manual---when multiple Texinfo files are
6216 incorporated into the same @TeX{} run but make separate Info files.
6217 In this case, you need to specify only the fourth argument, and not
6220 @node Top Node Naming
6221 @section Naming a `Top' Node
6222 @cindex Naming a `Top' Node in references
6223 @cindex @samp{@r{Top}} node naming for references
6225 In a cross reference, you must always name a node. This means that in
6226 order to refer to a whole manual, you must identify the `Top' node by
6227 writing it as the first argument to the @code{@@xref} command. (This
6228 is different from the way you write a menu entry; see @ref{Other Info
6229 Files, , Referring to Other Info Files}.) At the same time, to
6230 provide a meaningful section topic or title in the printed cross
6231 reference (instead of the word `Top'), you must write an appropriate
6232 entry for the third argument to the @code{@@xref} command.
6236 Thus, to make a cross reference to @cite{The GNU Make Manual},
6240 @@xref@{Top, , Overview, make, The GNU Make Manual@}.
6247 *Note Overview: (make)Top.
6254 See section ``Overview'' in @i{The GNU Make Manual}.
6258 In this example, @samp{Top} is the name of the first node, and
6259 @samp{Overview} is the name of the first section of the manual.
6263 @section @code{@@ref}
6264 @cindex Cross references using @code{@@ref}
6265 @cindex References using @code{@@ref}
6268 @code{@@ref} is nearly the same as @code{@@xref} except that it does
6269 not generate a `See' in the printed output, just the reference itself.
6270 This makes it useful as the last part of a sentence.
6272 @noindent For example,
6276 For more information, @@pxref@{This@}, and @@ref@{That@}.
6279 @noindent produces in Info:
6282 For more information, *note This::, and *note That::.
6285 @noindent and in printed output:
6288 For more information, see Section 1.1 [This], page 1,
6289 and Section 1.2 [That], page 2.
6292 The @code{@@ref} command sometimes tempts writers to express
6293 themselves in a manner that is suitable for a printed manual but looks
6294 awkward in the Info format. Bear in mind that your audience will be
6295 using both the printed and the Info format. For example:
6299 Sea surges are described in @@ref@{Hurricanes@}.
6302 @noindent looks ok in the printed output:
6305 Sea surges are described in Section 6.7 [Hurricanes], page 72.
6308 @noindent but is awkward to read in Info, ``note'' being a verb:
6311 Sea surges are described in *note Hurricanes::.
6314 You should write a period or comma immediately after an @code{@@ref}
6315 command with two or more arguments. If there is no such following
6316 punctuation, @command{makeinfo} will generate a (grammatically
6317 incorrect) period in the Info output; otherwise, the cross-reference
6318 would fail completely, due to the current syntax of Info format.
6320 In general, it is best to use @code{@@ref} only when you need some
6321 word other than ``see'' to precede the reference. When ``see'' (or
6322 ``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.
6326 @section @code{@@pxref}
6327 @cindex Cross references using @code{@@pxref}
6328 @cindex References using @code{@@pxref}
6331 The parenthetical reference command, @code{@@pxref}, is nearly the
6332 same as @code{@@xref}, but it is best used at the end of a sentence or
6333 before a closing parenthesis. The command differs from @code{@@xref}
6338 @TeX{} typesets the reference for the printed manual with a lower case
6339 `see' rather than an upper case `See'.
6342 The Info formatting commands automatically end the reference with a
6343 closing colon or period, if necessary.
6346 @code{@@pxref} is designed so that the output looks right and works
6347 right at the end of a sentence or parenthetical phrase, both in
6348 printed output and in an Info file. In a printed manual, a closing
6349 comma or period should not follow a cross reference within
6350 parentheses; such punctuation is wrong. But in an Info file, suitable
6351 closing punctuation must follow the cross reference so Info can
6352 recognize its end. @code{@@pxref} spares you the need to use
6353 complicated methods to put a terminator into one form of the output
6357 With one argument, a parenthetical cross reference looks like this:
6361 @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
6370 @dots{} storms cause flooding (*note Hurricanes::) @dots{}
6378 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
6381 With two arguments, a parenthetical cross reference has this template:
6384 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6391 @dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{}
6398 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6401 @code{@@pxref} can be used with up to five arguments, just like
6402 @code{@@xref} (@pxref{xref, , @code{@@xref}}).
6404 In past versions of Texinfo, it was not allowed to write punctuation
6405 after a @code{@@pxref}, so it could be used @emph{only} before a right
6406 parenthesis. This is no longer the case, so now it can be used (for
6407 example) at the end of a sentence, where a lowercase ``see'' works
6411 @dots{} For more information, @@pxref@{More@}.
6415 which outputs (in Info):
6418 @dots{} For more information, *note More::.
6422 This works fine. @code{@@pxref} should only be followed by a comma,
6423 period, or right parenthesis; in other cases, @command{makeinfo} has
6424 to insert a period to make the cross-reference work correctly in Info,
6425 and that period looks wrong.
6427 As a matter of general style, @code{@@pxref} is best used at the ends
6428 of sentences. Although it technically works in the middle of a
6429 sentence, that location breaks up the flow of reading.
6433 @section @code{@@inforef}
6434 @cindex Cross references using @code{@@inforef}
6435 @cindex References using @code{@@inforef}
6438 @code{@@inforef} is used for making cross references to Info
6439 documents---even from a printed manual. This might be because you
6440 want to refer to conditional @code{@@ifinfo} text
6441 (@pxref{Conditionals}), or because printed output is not available
6442 (perhaps because there is no Texinfo source), among other
6445 The command takes either two or three arguments, in the following
6453 The cross reference name (optional).
6460 Separate the arguments with commas, as with @code{@@xref}. Also, you
6461 must terminate the reference with a comma or period after the
6462 @samp{@}}, as you do with @code{@@xref}.@refill
6468 @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6477 @@inforef@{Advanced, Advanced Info commands, info@},
6478 for more information.
6488 *Note Advanced Info commands: (info)Advanced,
6489 for more information.
6495 and (in the printed output):
6498 See Info file @file{info}, node @samp{Advanced}, for more information.
6501 (This particular example is not realistic, since the Info manual is
6502 written in Texinfo, so all formats are available.)
6504 The converse of @code{@@inforef} is @code{@@cite}, which is used to
6505 refer to printed works for which no Info form exists. @xref{cite, ,
6510 @section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
6512 @cindex Uniform resource locator, referring to
6513 @cindex URL, referring to
6515 @cindex @code{href}, producing HTML
6516 @code{@@uref} produces a reference to a uniform resource locator (url).
6517 It takes one mandatory argument, the url, and two optional arguments
6518 which control the text that is displayed. In HTML output, @code{@@uref}
6519 produces a link you can follow.
6521 @code{@@url} is a synonym for @code{@@uref}. Originally, @code{@@url}
6522 had the meaning of @code{@@indicateurl}
6523 (@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it
6524 was misused the vast majority of the time. So we've changed the
6527 The second argument, if specified, is the text to display (the default
6528 is the url itself); in Info and DVI output, but not in HTML output, the
6531 @cindex Man page, reference to
6532 The third argument, if specified, is the text to display, but in this
6533 case the url is @emph{not} output in any format. This is useful when
6534 the text is already sufficiently referential, as in a man page. If
6535 the third argument is given, the second argument is ignored.
6537 If the url is long enough to cause problems with line breaking, you
6538 may find it useful to insert @code{@@/} at places where a line break
6539 would be acceptable (after @samp{/} characters, for instance). This
6540 tells @TeX{} to allow (but not force) a line break at those places.
6543 Here is an example of the simple one argument form, where the url is
6544 both the target and the text of the link:
6547 The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
6552 The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
6556 An example of the two-argument form:
6558 The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
6559 holds programs and texts.
6564 The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
6565 holds programs and texts.
6568 @noindent that is, the Info output is this:
6570 The official GNU ftp site (ftp://ftp.gnu.org/gnu)
6571 holds programs and texts.
6574 @noindent and the HTML output is this:
6576 The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
6577 holds programs and texts.
6581 An example of the three-argument form:
6583 The @@uref@{/man.cgi/1/ls,,ls@} program @dots{}
6588 The @uref{/man.cgi/1/ls,,ls} program @dots{}
6591 @noindent but with HTML:
6593 The <a href="/man.cgi/1/ls">ls</a> program @dots{}
6596 To merely indicate a url without creating a link people can follow, use
6597 @code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}).
6599 Some people prefer to display url's in the unambiguous format:
6602 <URL:http://@var{host}/@var{path}>
6606 @cindex <URL: convention, not used
6607 You can use this form in the input file if you wish. We feel it's not
6608 necessary to include the @samp{<URL:} and @samp{>} in the output,
6609 since any software that tries to detect url's in text already has to
6610 detect them without the @samp{<URL:} to be useful.
6614 @section @code{@@cite}@{@var{reference}@}
6617 Use the @code{@@cite} command for the name of a book that lacks a
6618 companion Info file. The command produces italics in the printed
6619 manual, and quotation marks in the Info file.
6621 If a book is written in Texinfo, it is better to use a cross reference
6622 command since a reader can easily follow such a reference in Info.
6623 @xref{xref, , @code{@@xref}}.
6627 @chapter Marking Words and Phrases
6628 @cindex Paragraph, marking text within
6629 @cindex Marking words and phrases
6630 @cindex Words and phrases, marking them
6631 @cindex Marking text within a paragraph
6632 @cindex Text, marking up
6634 In Texinfo, you can mark words and phrases in a variety of ways.
6635 The Texinfo formatters use this information to determine how to
6637 You can specify, for example, whether a word or phrase is a
6638 defining occurrence, a metasyntactic variable, or a symbol used in a
6639 program. Also, you can emphasize text, in several different ways.
6642 * Indicating:: How to indicate definitions, files, etc.
6643 * Emphasis:: How to emphasize text.
6648 @section Indicating Definitions, Commands, etc.
6649 @cindex Highlighting text
6650 @cindex Indicating commands, definitions, etc.
6652 Texinfo has commands for indicating just what kind of object a piece of
6653 text refers to. For example, metasyntactic variables are marked by
6654 @code{@@var}, and code by @code{@@code}. Since the pieces of text are
6655 labelled by commands that tell what kind of object they are, it is easy
6656 to change the way the Texinfo formatters prepare such text. (Texinfo is
6657 an @emph{intentional} formatting language rather than a @emph{typesetting}
6658 formatting language.)@refill
6660 For example, in a printed manual,
6661 code is usually illustrated in a typewriter font;
6662 @code{@@code} tells @TeX{} to typeset this text in this font. But it
6663 would be easy to change the way @TeX{} highlights code to use another
6664 font, and this change would not affect how keystroke examples are
6665 highlighted. If straight typesetting commands were used in the body
6666 of the file and you wanted to make a change, you would need to check
6667 every single occurrence to make sure that you were changing code and
6668 not something else that should not be changed.@refill
6671 * Useful Highlighting:: Highlighting provides useful information.
6672 * code:: Indicating program code.
6673 * kbd:: Showing keyboard input.
6674 * key:: Specifying keys.
6675 * samp:: Indicating a literal sequence of characters.
6676 * verb:: Indicating a verbatim sequence of characters.
6677 * var:: Indicating metasyntactic variables.
6678 * env:: Indicating environment variables.
6679 * file:: Indicating file names.
6680 * command:: Indicating command names.
6681 * option:: Indicating option names.
6682 * dfn:: Specifying definitions.
6683 * abbr:: Indicating abbreviations.
6684 * acronym:: Indicating acronyms.
6685 * indicateurl:: Indicating an example URL.
6686 * email:: Indicating an electronic mail address.
6690 @node Useful Highlighting
6691 @subsection Highlighting Commands are Useful
6693 The highlighting commands can be used to extract useful information
6694 from the file, such as lists of functions or file names. It is
6695 possible, for example, to write a program in Emacs Lisp (or a keyboard
6696 macro) to insert an index entry after every paragraph that contains
6697 words or phrases marked by a specified command. You could do this to
6698 construct an index of functions if you had not already made the
6701 The commands serve a variety of purposes:@refill
6704 @item @@code@{@var{sample-code}@}
6705 Indicate text that is a literal example of a piece of a program.
6706 @xref{code,,@code{@@code}}.
6708 @item @@kbd@{@var{keyboard-characters}@}
6709 Indicate keyboard input.
6710 @xref{kbd,,@code{@@kbd}}.
6712 @item @@key@{@var{key-name}@}
6713 Indicate the conventional name for a key on a keyboard.
6714 @xref{key,,@code{@@key}}.
6716 @item @@samp@{@var{text}@}
6717 Indicate text that is a literal example of a sequence of characters.
6718 @xref{samp,,@code{@@samp}}.
6720 @item @@verb@{@var{text}@}
6721 Write a verbatim sequence of characters.
6722 @xref{verb,,@code{@@verb}}.
6724 @item @@var@{@var{metasyntactic-variable}@}
6725 Indicate a metasyntactic variable.
6726 @xref{var,,@code{@@var}}.
6728 @item @@env@{@var{environment-variable}@}
6729 Indicate an environment variable.
6730 @xref{env,,@code{@@env}}.
6732 @item @@file@{@var{file-name}@}
6733 Indicate the name of a file.
6734 @xref{file,,@code{@@file}}.
6736 @item @@command@{@var{command-name}@}
6737 Indicate the name of a command.
6738 @xref{command,,@code{@@command}}.
6740 @item @@option@{@var{option}@}
6741 Indicate a command-line option.
6742 @xref{option,,@code{@@option}}.
6744 @item @@dfn@{@var{term}@}
6745 Indicate the introductory or defining use of a term.
6746 @xref{dfn,,@code{@@dfn}}.
6748 @item @@cite@{@var{reference}@}
6749 Indicate the name of a book.
6750 @xref{cite,,@code{@@cite}}.
6752 @item @@abbr@{@var{abbreviation}@}
6753 Indicate an abbreviation, such as `Comput.'.
6755 @item @@acronym@{@var{acronym}@}
6756 Indicate an acronym.
6757 @xref{acronym,,@code{@@acronym}}.
6759 @item @@indicateurl@{@var{uniform-resource-locator}@}
6760 Indicate an example (that is, nonfunctional) uniform resource locator.
6761 @xref{indicateurl,,@code{@@indicateurl}}. (Use @code{@@url}
6762 (@pxref{uref,,@code{@@url}}) for live url's.)
6764 @item @@email@{@var{email-address}[, @var{displayed-text}]@}
6765 Indicate an electronic mail address.
6766 @xref{email,,@code{@@email}}.
6769 @item @@ctrl@{@var{ctrl-char}@}
6770 Use for an ASCII control character.
6776 @subsection @code{@@code}@{@var{sample-code}@}
6779 @cindex Syntactic tokens, indicating
6780 Use the @code{@@code} command to indicate text that is a piece of a
6781 program and which consists of entire syntactic tokens. Enclose the
6784 @cindex Expressions in a program, indicating
6785 @cindex Keywords, indicating
6786 @cindex Reserved words, indicating
6787 Thus, you should use @code{@@code} for an expression in a program, for
6788 the name of a variable or function used in a program, or for a
6789 keyword in a programming language.
6791 Use @code{@@code} for command names in languages that resemble
6792 programming languages, such as Texinfo. For example, @code{@@code} and
6793 @code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
6794 @samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
6796 @cindex Case, not altering in @code{@@code}
6797 It is incorrect to alter the case of a word inside an @code{@@code}
6798 command when it appears at the beginning of a sentence. Most computer
6799 languages are case sensitive. In C, for example, @code{Printf} is
6800 different from the identifier @code{printf}, and most likely is a
6801 misspelling of it. Even in languages which are not case sensitive, it
6802 is confusing to a human reader to see identifiers spelled in different
6803 ways. Pick one spelling and always use that. If you do not want to
6804 start a sentence with a command name written all in lower case, you
6805 should rearrange the sentence.
6807 In the printed manual, @code{@@code} causes @TeX{} to typeset the
6808 argument in a typewriter face. In the Info file, it causes the Info
6809 formatting commands to use single quotation marks around the text.
6813 The function returns @@code@{nil@}.
6820 The function returns @code{nil}.
6825 and this in the Info file:
6827 The function returns `nil'.
6831 Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
6835 For shell command names such as @command{ls} (use @code{@@command}).
6838 For shell options such as @samp{-c} when such options stand alone (use
6842 Also, an entire shell command often looks better if written using
6843 @code{@@samp} rather than @code{@@code}. In this case, the rule is to
6844 choose the more pleasing format.
6847 For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
6850 For a string of characters shorter than a syntactic token. For example,
6851 if you are writing about @samp{goto-ch}, which is just a part of the
6852 name for the @code{goto-char} Emacs Lisp function, you should use
6856 In general, when writing about the characters used in a token; for
6857 example, do not use @code{@@code} when you are explaining what letters
6858 or printable symbols can be used in the names of functions. (Use
6859 @code{@@samp}.) Also, you should not use @code{@@code} to mark text
6860 that is considered input to programs unless the input is written in a
6861 language that is like a programming language. For example, you should
6862 not use @code{@@code} for the keystroke commands of GNU Emacs (use
6863 @code{@@kbd} instead) although you may use @code{@@code} for the names
6864 of the Emacs Lisp functions that the keystroke commands invoke.
6868 Since @code{@@command}, @code{@@option}, and @code{@@env} were
6869 introduced relatively recently, it is acceptable to use @code{@@code} or
6870 @code{@@samp} for command names, options, and environment variables.
6871 The new commands allow you to express the markup more precisely, but
6872 there is no real harm in using the older commands, and of course the
6873 long-standing manuals do so.
6875 Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
6876 @samp{_} characters within @code{@@code} and related commands. This
6877 can be controlled with @code{@@allowcodebreaks}
6878 (@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}).
6882 @subsection @code{@@kbd}@{@var{keyboard-characters}@}
6884 @cindex Keyboard input
6886 Use the @code{@@kbd} command for characters of input to be typed by
6887 users. For example, to refer to the characters @kbd{M-a}, write:
6894 and to refer to the characters @kbd{M-x shell}, write:
6901 @cindex Slanted typewriter font, for @code{@@kbd}
6902 By default, the @code{@@kbd} command produces a different font
6903 (slanted typewriter instead of normal typewriter) in the printed
6904 manual, so users can distinguish the characters that they are supposed
6905 to type from those that the computer outputs.
6907 In Info output, @code{@@kbd} is usually the same as @code{@@code},
6908 producing `quotes' around its argument. However, in typewriter-like
6909 contexts such as the @code{@@example} environment (@pxref{example})
6910 and @code{@@code} command itself, the quotes are omitted, since Info
6911 format cannot use distinguishing fonts.
6913 @findex kbdinputstyle
6914 Since the usage of @code{@@kbd} varies from manual to manual, you can
6915 control the font switching with the @code{@@kbdinputstyle} command.
6916 This command has no effect on Info output. Write this command at the
6917 beginning of a line with a single word as an argument, one of the
6920 @vindex distinct@r{, value for @code{@@kbdinputstyle}}
6921 @vindex example@r{, value for @code{@@kbdinputstyle}}
6922 @vindex code@r{, value for @code{@@kbdinputstyle}}
6925 Always use the same font for @code{@@kbd} as @code{@@code}.
6927 Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6928 and similar environments.
6930 (the default) Always use the distinguishing font for @code{@@kbd}.
6933 You can embed another @@-command inside the braces of an @code{@@kbd}
6934 command. Here, for example, is the way to describe a command that
6935 would be described more verbosely as ``press the @samp{r} key and then
6936 press the @key{RETURN} key'':
6939 @@kbd@{r @@key@{RET@}@}
6943 This produces: @kbd{r @key{RET}}. (The present manual uses the
6944 default for @code{@@kbdinputstyle}.)
6946 You also use the @code{@@kbd} command if you are spelling out the letters
6947 you type; for example:
6950 To give the @@code@{logout@} command,
6951 type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6958 To give the @code{logout} command,
6959 type the characters @kbd{l o g o u t @key{RET}}.
6962 (Also, this example shows that you can add spaces for clarity. If you
6963 explicitly want to mention a space character as one of the characters of
6964 input, write @kbd{@@key@{SPC@}} for it.)@refill
6968 @subsection @code{@@key}@{@var{key-name}@}
6971 Use the @code{@@key} command for the conventional name for a key on a
6972 keyboard, as in:@refill
6978 You can use the @code{@@key} command within the argument of an
6979 @code{@@kbd} command when the sequence of characters to be typed
6980 includes one or more keys that are described by name.@refill
6982 For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you
6986 @@kbd@{C-x @@key@{ESC@}@}
6987 @@kbd@{M-@@key@{TAB@}@}
6990 Here is a list of the recommended names for keys:
6991 @cindex Recommended names for keys
6992 @cindex Keys, recommended names
6993 @cindex Names recommended for keys
6994 @cindex Abbreviations for keys
7003 Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
7004 it might be better to call this character @kbd{C-j})
7023 There are subtleties to handling words like `meta' or `ctrl' that are
7024 names of modifier keys. When mentioning a character in which the
7025 modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
7026 alone; do not use the @code{@@key} command; but when you are referring
7027 to the modifier key in isolation, use the @code{@@key} command. For
7028 example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
7029 @samp{@@key@{META@}} to produce @key{META}.
7031 As a convention in GNU manuals, @code{@@key} should not be used in
7036 @subsection @code{@@samp}@{@var{text}@}
7039 Use the @code{@@samp} command to indicate text that is a literal example
7040 or `sample' of a sequence of characters in a file, string, pattern, etc.
7041 Enclose the text in braces. The argument appears within single
7042 quotation marks in both the Info file and the printed manual; in
7043 addition, it is printed in a fixed-width font.@refill
7046 To match @@samp@{foo@} at the end of the line,
7047 use the regexp @@samp@{foo$@}.
7054 To match @samp{foo} at the end of the line, use the regexp
7058 Any time you are referring to single characters, you should use
7059 @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
7060 Also, you may use @code{@@samp} for entire statements in C and for entire
7061 shell commands---in this case, @code{@@samp} often looks better than
7062 @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
7063 not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
7065 Only include punctuation marks within braces if they are part of the
7066 string you are specifying. Write punctuation marks outside the braces
7067 if those punctuation marks are part of the English text that surrounds
7068 the string. In the following sentence, for example, the commas and
7069 period are outside of the braces:@refill
7073 In English, the vowels are @@samp@{a@}, @@samp@{e@},
7074 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
7083 In English, the vowels are @samp{a}, @samp{e},
7084 @samp{i}, @samp{o}, @samp{u}, and sometimes
7090 @subsection @code{@@verb}@{<char>@var{text}<char>@}
7092 @cindex Verbatim in-line text
7094 @cindex Delimiter character, for verbatim
7095 Use the @code{@@verb} command to print a verbatim sequence of
7098 Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using
7099 any unique delimiter character. Enclose the verbatim text, including the
7100 delimiters, in braces. Text is printed in a fixed-width font:
7103 How many @@verb@{|@@|@}-escapes does one need to print this
7104 @@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
7111 How many @verb{|@|}-escapes does one need to print this
7112 @verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
7115 This is in contrast to @code{@@samp} (see the previous section),
7116 @code{@@code}, and similar commands; in those cases, the argument is
7117 normal Texinfo text, where the three characters @code{@@@{@}} are
7118 special. With @code{@@verb}, nothing is special except the delimiter
7119 character you choose.
7121 It is not reliable to use @code{@@verb} inside other Texinfo
7122 constructs. In particular, it does not work to use @code{@@verb} in
7123 anything related to cross-referencing, such as section titles or
7128 @subsection @code{@@var}@{@var{metasyntactic-variable}@}
7131 Use the @code{@@var} command to indicate metasyntactic variables. A
7132 @dfn{metasyntactic variable} is something that stands for another piece of
7133 text. For example, you should use a metasyntactic variable in the
7134 documentation of a function to describe the arguments that are passed
7135 to that function.@refill
7137 Do not use @code{@@var} for the names of particular variables in
7138 programming languages. These are specific names from a program, so
7139 @code{@@code} is correct for them (@pxref{code}). For example, the
7140 Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
7141 variable; it is properly formatted using @code{@@code}.
7143 Do not use @code{@@var} for environment variables either; @code{@@env}
7144 is correct for them (see the next section).
7146 The effect of @code{@@var} in the Info file is to change the case of the
7147 argument to all upper case. In the printed manual and HTML output, the
7148 argument is printed in slanted type.
7154 To delete file @@var@{filename@},
7155 type @@samp@{rm @@var@{filename@}@}.
7162 To delete file @var{filename}, type @samp{rm @var{filename}}.
7166 (Note that @code{@@var} may appear inside @code{@@code},
7167 @code{@@samp}, @code{@@file}, etc.)@refill
7169 Write a metasyntactic variable all in lower case without spaces, and
7170 use hyphens to make it more readable. Thus, the Texinfo source for
7171 the illustration of how to begin a Texinfo manual looks like
7177 @@@@setfilename @@var@{info-file-name@}
7178 @@@@settitle @@var@{name-of-manual@}
7188 @@setfilename @var{info-file-name}
7189 @@settitle @var{name-of-manual}
7193 In some documentation styles, metasyntactic variables are shown with
7194 angle brackets, for example:@refill
7197 @dots{}, type rm <filename>
7201 However, that is not the style that Texinfo uses. (You can, of
7202 course, modify the sources to @file{texinfo.tex} and the Info formatting commands
7203 to output the @code{<@dots{}>} format if you wish.)@refill
7207 @subsection @code{@@env}@{@var{environment-variable}@}
7210 Use the @code{@@env} command to indicate environment variables, as used
7211 by many operating systems, including GNU. Do not use it for
7212 metasyntactic variables; use @code{@@var} instead (see the previous
7215 @code{@@env} is equivalent to @code{@@code} in its effects.
7219 The @@env@{PATH@} environment variable @dots{}
7223 The @env{PATH} environment variable @dots{}
7228 @subsection @code{@@file}@{@var{file-name}@}
7231 Use the @code{@@file} command to indicate text that is the name of a
7232 file, buffer, or directory, or is the name of a node in Info. You can
7233 also use the command for file name suffixes. Do not use @code{@@file}
7234 for symbols in a programming language; use @code{@@code}.
7236 Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
7240 The @@file@{.el@} files are in
7241 the @@file@{/usr/local/emacs/lisp@} directory.
7248 The @file{.el} files are in
7249 the @file{/usr/local/emacs/lisp} directory.
7254 @subsection @code{@@command}@{@var{command-name}@}
7256 @cindex Command names, indicating
7257 @cindex Program names, indicating
7259 Use the @code{@@commannd} command to indicate command names, such as
7260 @command{ls} or @command{cc}.
7262 @code{@@command} is equivalent to @code{@@code} in its effects.
7266 The command @@command@{ls@} lists directory contents.
7270 The command @command{ls} lists directory contents.
7273 You should write the name of a program in the ordinary text font, rather
7274 than using @code{@@command}, if you regard it as a new English word,
7275 such as `Emacs' or `Bison'.
7277 When writing an entire shell command invocation, as in @samp{ls -l},
7278 you should use either @code{@@samp} or @code{@@code} at your discretion.
7282 @subsection @code{@@option}@{@var{option-name}@}
7285 Use the @code{@@option} command to indicate a command-line option; for
7286 example, @option{-l} or @option{--version} or
7287 @option{--output=@var{filename}}.
7289 @code{@@option} is equivalent to @code{@@samp} in its effects.
7293 The option @@option@{-l@} produces a long listing.
7297 The option @option{-l} produces a long listing.
7300 In tables, putting options inside @code{@@code} produces a
7301 more pleasing effect.
7304 @comment node-name, next, previous, up
7305 @subsection @code{@@dfn}@{@var{term}@}
7308 Use the @code{@@dfn} command to identify the introductory or defining
7309 use of a technical term. Use the command only in passages whose
7310 purpose is to introduce a term which will be used again or which the
7311 reader ought to know. Mere passing mention of a term for the first
7312 time does not deserve @code{@@dfn}. The command generates italics in
7313 the printed manual, and double quotation marks in the Info file. For
7317 Getting rid of a file is called @@dfn@{deleting@} it.
7324 Getting rid of a file is called @dfn{deleting} it.
7327 As a general rule, a sentence containing the defining occurrence of a
7328 term should be a definition of the term. The sentence does not need
7329 to say explicitly that it is a definition, but it should contain the
7330 information of a definition---it should make the meaning clear.
7333 @c node ctrl, , cite, Indicating
7334 @comment node-name, next, previous, up
7335 @c subsection @code{@@ctrl}@{@var{ctrl-char}@}
7338 The @code{@@ctrl} command is seldom used. It describes an ASCII
7339 control character by inserting the actual character into the Info
7342 Usually, in Texinfo, you talk what you type as keyboard entry by
7343 describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
7344 @kbd{C-a}. Use @code{@@kbd} in this way when talking about a control
7345 character that is typed on the keyboard by the user. When talking
7346 about a control character appearing in a file or a string, do not use
7347 @code{@@kbd} since the control character is not typed. Also, do not
7348 use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
7349 to make it easier for a reader to understand.@refill
7351 @code{@@ctrl} is an idea from the beginnings of Texinfo which may not
7352 really fit in to the scheme of things. But there may be times when
7353 you want to use the command. The pattern is
7354 @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character
7355 whose control-equivalent is wanted. For example, to specify
7356 @samp{control-f}, you would enter@refill
7369 In the Info file, this generates the specified control character, output
7370 literally into the file. This is done so a user can copy the specified
7371 control character (along with whatever else he or she wants) into another
7372 Emacs buffer and use it. Since the `control-h',`control-i', and
7373 `control-j' characters are formatting characters, they should not be
7374 indicated with @code{@@ctrl}.@refill
7376 In a printed manual, @code{@@ctrl} generates text to describe or
7377 identify that control character: an uparrow followed by the character
7383 @subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@}
7386 @cindex Abbreviations, tagging
7387 You can use the @code{@@abbr} command for general abbreviations. The
7388 abbreviation is given as the single argument in braces, as in
7389 @samp{@@abbr@{Comput.@}}. As a matter of style, or for particular
7390 abbreviations, you may prefer to omit periods, as in
7391 @samp{@@abbr@{Mr@} Stallman}.
7393 @code{@@abbr} accepts an optional second argument, intended to be used
7394 for the meaning of the abbreviation.
7396 If the abbreviation ends with a lowercase letter and a period, and is
7397 not at the end of a sentence, and has no second argument, remember to
7398 use the @code{@@.} command (@pxref{Not Ending a
7399 Sentence}) to get the correct spacing. However, you do not have to
7400 use @code{@@.} within the abbreviation itself; Texinfo automatically
7401 assumes periods within the abbreviation do not end a sentence.
7403 @cindex <abbr> and <abbrev> tags
7404 In @TeX{} and in the Info output, the first argument is printed as-is;
7405 if the second argument is present, it is printed in parentheses after
7406 the abbreviation. In HTML and XML, the @code{<abbr>} tag is
7407 used; in Docbook, the @code{<abbrev>} tag is used. For instance:
7410 @@abbr@{Comput. J., Computer Journal@}
7416 @abbr{Comput. J., Computer Journal}
7419 For abbreviations consisting of all capital letters, you may prefer to
7420 use the @code{@@acronym} command instead. See the next section for
7421 more on the usage of these two commands.
7425 @subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@}
7428 @cindex NASA, as acronym
7429 @cindex Acronyms, tagging
7430 Use the @code{@@acronym} command for abbreviations written in all
7431 capital letters, such as `@acronym{NASA}'. The abbreviation is given as
7432 the single argument in braces, as in @samp{@@acronym@{NASA@}}. As
7433 a matter of style, or for particular acronyms, you may prefer to
7434 use periods, as in @samp{@@acronym@{N.A.S.A.@}}.
7436 @code{@@acronym} accepts an optional second argument, intended to be
7437 used for the meaning of the acronym.
7439 If the acronym is at the end of a sentence, and if there is no second
7440 argument, remember to use the @code{@@.} or similar command
7441 (@pxref{Ending a Sentence}) to get the correct spacing.
7443 @cindex <acronym> tag
7444 In @TeX{}, the acronym is printed in slightly smaller font. In the
7445 Info output, the argument is printed as-is. In either format, if the
7446 second argument is present, it is printed in parentheses after the
7447 acronym. In HTML, Docbook, and XML, the @code{<acronym>} tag is
7450 For instance (since GNU is a recursive acronym, we use
7451 @code{@@acronym} recursively):
7454 @@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@}
7460 @acronym{GNU, @acronym{GNU}'s Not Unix}
7463 @cindex Family names, in all capitals
7464 In some circumstances, it is conventional to print family names in all
7465 capitals. Don't use @code{@@acronym} for this, since a name is not an
7466 acronym. Use @code{@@sc} instead (@pxref{Smallcaps}).
7468 @code{@@abbr} and @code{@@acronym} are closely related commands: they
7469 both signal to the reader that a shortened form is being used, and
7470 possibly give a meaning. When choosing whether to use these two
7471 commands, please bear the following in mind.
7475 In standard English usage, acronyms are a subset of abbreviations:
7476 they include pronounceable words like `@acronym{NATO}', `radar', and
7477 `snafu', and some sources also include syllable acronyms like
7478 `Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable
7479 initialisms like `@acronym{FBI}'.
7482 In Texinfo, an acronym (but not an abbreviation) should consist only
7483 of capital letters and periods, no lowercase.
7486 In @TeX{}, an acronym (but not an abbreviation) is printed in a
7487 slightly smaller font.
7490 Some browsers place a dotted bottom border under abbreviations but not
7494 It's not essential to use either of these commands for all
7495 abbreviations; use your judgment. Text is perfectly readable without
7502 @subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@}
7504 @cindex Uniform resource locator, indicating
7505 @cindex URL, indicating
7507 Use the @code{@@indicateurl} command to indicate a uniform resource
7508 locator on the World Wide Web. This is analogous to @code{@@file},
7509 @code{@@var}, etc., and is purely for markup purposes. It does not
7510 produce a link you can follow in HTML output (use the @code{@@uref}
7511 command for that, @pxref{uref,, @code{@@uref}}). It is useful for
7512 url's which do not actually exist. For example:
7515 For example, the url might be @@indicateurl@{http://example.org/path@}.
7518 @noindent which produces:
7521 For example, the url might be @indicateurl{http://example.org/path}.
7526 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
7529 Use the @code{@@email} command to indicate an electronic mail address.
7530 It takes one mandatory argument, the address, and one optional argument, the
7531 text to display (the default is the address itself).
7534 In Info, the address is shown in angle brackets, preceded by the text
7535 to display if any. In @TeX{}, the angle brackets are omitted. In
7536 HTML output, @code{@@email} produces a @samp{mailto} link that usually
7537 brings up a mail composition window. For example:
7540 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
7541 suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
7545 Send bug reports to @email{bug-texinfo@@gnu.org},
7546 suggestions to the @email{bug-texinfo@@gnu.org, same place}.
7551 @section Emphasizing Text
7552 @cindex Emphasizing text
7554 Usually, Texinfo changes the font to mark words in the text according to
7555 what category the words belong to; an example is the @code{@@code} command.
7556 Most often, this is the best way to mark words.
7557 However, sometimes you will want to emphasize text without indicating a
7558 category. Texinfo has two commands to do this. Also, Texinfo has
7559 several commands that specify the font in which @TeX{} will typeset
7560 text. These commands have no effect on Info and only one of them,
7561 the @code{@@r} command, has any regular use.@refill
7564 * emph & strong:: How to emphasize text in Texinfo.
7565 * Smallcaps:: How to use the small caps font.
7566 * Fonts:: Various font commands for printed output.
7570 @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
7571 @cindex Emphasizing text, font for
7575 The @code{@@emph} and @code{@@strong} commands are for emphasis;
7576 @code{@@strong} is stronger. In printed output, @code{@@emph} produces
7577 @emph{italics} and @code{@@strong} produces @strong{bold}.
7583 @@strong@{Caution:@} @@samp@{rm * .[^.]*@}
7584 removes @@emph@{all@} files in the directory.
7589 produces the following in printed output and HTML:
7592 @strong{Caution}: @samp{rm * .[^.]*}
7593 removes @emph{all} files in the directory.
7597 and the following in Info:
7600 *Caution:* `rm * .[^.]*' removes _all_
7601 files in the directory.
7604 The @code{@@strong} command is seldom used except to mark what is, in
7605 effect, a typographical element, such as the word `Caution' in the
7608 In the Info output, @code{@@emph} surrounds the text with underscores
7609 (@samp{_}), and @code{@@strong} puts asterisks around the text.
7612 Do not use @code{@@strong} with the word @samp{Note}; Info will
7613 mistake the combination for a cross reference. (It's usually
7614 redundant, anyway.) Use a phrase such as @strong{Please notice} or
7615 @strong{Caution} instead, or the optional argument to
7616 @code{@@quotation}---@samp{Note} is allowable there.
7621 @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
7622 @cindex Small caps font
7623 @findex sc @r{(small caps font)}
7625 Use the @samp{@@sc} command to set text in @sc{a small caps font}
7626 (where possible). Write the text you want to be in small caps between
7627 braces in lower case, like this:
7630 Richard @@sc@{Stallman@} founded @@acronym@{GNU@}.
7637 Richard @sc{Stallman} founded @acronym{GNU}.
7640 As shown here, we recommend using @code{@@acronym} for actual
7641 acronyms (@pxref{acronym}), and reserving @code{@@sc} for special
7642 cases where you want small caps. The output is not the same
7643 (@code{@@acronym} prints in a smaller text font, not the small caps
7644 font), but more importantly it describes the actual text more
7647 Family names are one case where small capitals are sometimes desirable,
7651 @TeX{} typesets any uppercase letters between the braces of an
7652 @code{@@sc} command in full-size capitals; only lowercase letters are
7653 printed in the small caps font. In the Info output, the argument to
7654 @code{@@sc} is printed in all upper case. In HTML, the argument is
7655 uppercased and the output marked with the @code{<small>} tag to reduce
7658 Since it's redundant to mark all-uppercase text with @code{@@sc},
7659 @command{makeinfo} warns about such usage.
7661 We recommend using regular mixed case wherever possible.
7665 @subsection Fonts for Printing, Not Info
7666 @cindex Fonts for printing, not Info
7668 @findex fonttextsize
7669 @cindex Font size, reducing
7670 @cindex Reducing font size
7671 @cindex Smaller fonts
7672 Texinfo provides one command to change the size of the main body font
7673 in the @TeX{} output for a document: @code{@@fonttextsize}. It has no
7674 effect at all in other output. It takes a single argument on the
7675 remainder of the line, which must be either @samp{10} or @samp{11}.
7682 @cindex Printing cost, reducing
7683 The effect is to reduce the body font to a 10@dmn{pt} size (the
7684 default is 11@dmn{pt}). Fonts for other elements, such as sections
7685 and chapters, are reduced accordingly. This should only be used in
7686 conjunction with @code{@@smallbook} (@pxref{smallbook,,Printing
7687 ``Small'' Books}) or similar, since 10@dmn{pt} fonts on standard paper
7688 (8.5x11 or A4) are too small. One reason to use this command is to
7689 save pages, and hence printing cost, for physical books.
7691 Texinfo does not at present have commands to switch the font family
7692 to use, or more general size-changing commands.
7694 @cindex Styles, font
7695 Texinfo also provides a number of font commands that specify font changes
7696 in the printed manual and (where possible) in the HTML output, but
7697 have no effect in the Info file. All the commands apply to an
7698 argument that follows, surrounded by braces.
7702 @findex b @r{(bold font)}
7704 selects @b{bold} face;
7707 @findex i @r{(italic font)}
7709 selects an @i{italic} font;
7712 @findex r @r{(roman font)}
7714 @cindex Default font
7715 selects a @r{roman} font, which is the usual font in which text is
7716 printed. It may or may not be seriffed.
7719 @findex sansserif @r{(sans serif font)}
7720 @cindex Sans serif font
7721 selects a @sansserif{sans serif} font;
7724 @findex slanted @r{(slanted font)}
7725 @cindex Slanted font
7726 @cindex Oblique font
7727 selects a @slanted{slanted} font;
7730 @findex t @r{(typewriter font)}
7731 @cindex Monospace font
7732 @cindex Fixed-width font
7733 @cindex Typewriter font
7734 selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
7738 (The commands with longer names were invented much later than the
7739 others, at which time it did not seem desirable to use very short
7740 names for such an infrequently needed feature.)
7742 @cindex <lineannotation> Docbook tag
7743 Only the @code{@@r} command has much use: in example-like
7744 environments, you can use the @code{@@r} command to write comments in
7745 the standard roman font instead of the fixed-width font. This looks
7746 better in printed output, and produces a @code{<lineannotation>} tag
7754 (+ 2 2) ; @@r@{Add two plus two.@}
7763 (+ 2 2) ; @r{Add two plus two.}
7766 In general, you should avoid using the other font commands. Some of
7767 them are only useful when documenting functionality of specific font
7768 effects, such as in @TeX{} and related packages.
7771 @node Quotations and Examples
7772 @chapter Quotations and Examples
7774 Quotations and examples are blocks of text consisting of one or more
7775 whole paragraphs that are set off from the bulk of the text and
7776 treated differently. They are usually indented in the output.
7779 In Texinfo, you always begin a quotation or example by writing an
7780 @@-command at the beginning of a line by itself, and end it by writing
7781 an @code{@@end} command that is also at the beginning of a line by
7782 itself. For instance, you begin an example by writing @code{@@example}
7783 by itself at the beginning of a line and end the example by writing
7784 @code{@@end example} on a line by itself, at the beginning of that
7785 line, and with only one space between the @code{@@end} and the
7789 * Block Enclosing Commands:: Different constructs for different purposes.
7790 * quotation:: Writing a quotation.
7791 * example:: Writing an example in a fixed-width font.
7792 * verbatim:: Writing a verbatim example.
7793 * verbatiminclude:: Including a file verbatim.
7794 * lisp:: Illustrating Lisp code.
7795 * small:: Examples in a smaller font.
7796 * display:: Writing an example in the current font.
7797 * format:: Writing an example without narrowed margins.
7798 * exdent:: Undo indentation on a line.
7799 * flushleft & flushright:: Pushing text flush left or flush right.
7800 * noindent:: Preventing paragraph indentation.
7801 * indent:: Forcing paragraph indentation.
7802 * cartouche:: Drawing rounded rectangles around examples.
7806 @node Block Enclosing Commands
7807 @section Block Enclosing Commands
7809 Here are commands for quotations and examples, explained further in the
7814 Indicate text that is quoted. The text is filled, indented (from both
7815 margins), and printed in a roman font by default.
7818 Illustrate code, commands, and the like. The text is printed
7819 in a fixed-width font, and indented but not filled.
7822 Mark a piece of text that is to be printed verbatim; no character
7823 substitutions are made and all commands are ignored, until the next
7824 @code{@@end verbatim}. The text is printed in a fixed-width font,
7825 and not indented or filled. Extra spaces and blank lines are
7826 significant, and tabs are expanded.
7828 @item @@smallexample
7829 Same as @code{@@example}, except that in @TeX{} this command typesets
7830 text in a smaller font.
7833 Like @code{@@example}, but specifically for illustrating Lisp code. The
7834 text is printed in a fixed-width font, and indented but not filled.
7837 Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
7840 Display illustrative text. The text is indented but not filled, and
7841 no font is selected (so, by default, the font is roman).@refill
7843 @item @@smalldisplay
7844 Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
7847 Like @code{@@display} (the text is not filled and no font is selected),
7848 but the text is not indented.
7851 Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
7854 The @code{@@exdent} command is used within the above constructs to
7855 undo the indentation of a line.
7857 The @code{@@flushleft} and @code{@@flushright} commands are used to line
7858 up the left or right margins of unfilled text.@refill
7860 The @code{@@noindent} command may be used after one of the above
7861 constructs to prevent the following text from being indented as a new
7864 You can use the @code{@@cartouche} environment around one of the above
7865 constructs to highlight the example or quotation by drawing a box with
7866 rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
7871 @section @code{@@quotation}: Block quotations
7875 The text of a quotation is processed normally (regular font, text is
7876 filled) except that:
7880 the margins are closer to the center of the page, so the whole of the
7881 quotation is indented;
7884 and the first lines of paragraphs are indented no more than other lines.
7889 This is an example of text written between an @code{@@quotation}
7890 command and an @code{@@end quotation} command. An @code{@@quotation}
7891 command is most often used to indicate text that is excerpted from
7892 another (real or hypothetical) printed work.
7895 Write an @code{@@quotation} command as text on a line by itself. This
7896 line will disappear from the output. Mark the end of the quotation
7897 with a line beginning with and containing only @code{@@end quotation}.
7898 The @code{@@end quotation} line will likewise disappear from the
7901 @code{@@quotation} takes one optional argument, given on the remainder
7902 of the line. This text, if present, is included at the beginning of
7903 the quotation in bold or otherwise emphasized, and followed with a
7904 @samp{:}. For example:
7921 If the @code{@@quotation} argument is exactly one of these words:
7924 Caution Important Note Tip Warning
7927 @cindex <note> Docbook tag
7928 @cindex <blockquote> HTML tag
7929 @noindent then the Docbook output uses corresponding special tags
7930 (@code{<note>}, etc.) instead of the default @code{<blockquote>}.
7931 HTML output always uses @code{<blockquote>}.
7935 @section @code{@@example}: Example Text
7936 @cindex Examples, formatting them
7937 @cindex Formatting examples
7940 The @code{@@example} environment is used to indicate an example that
7941 is not part of the running text, such as computer input or output.
7942 Write an @code{@@example} command at the beginning of a line by
7943 itself. Mark the end of the example with an @code{@@end example}
7944 command, also written at the beginning of a line by itself.
7946 An @code{@@example} environment has the following characteristics:
7949 @item Each line in the input file is a line in the output; that is,
7950 the source text is not filled as it normally is.
7951 @item Extra spaces and blank lines are significant.
7952 @item The output is indented.
7953 @item The output uses a fixed-width font.
7954 @item Texinfo commands @emph{are} expanded; if you want the output to
7955 be the input verbatim, use the @code{@@verbatim} environment instead
7956 (@pxref{verbatim,,@code{@@verbatim}}).
7963 cp foo @@var@{dest1@}; \
7964 cp foo @@var@{dest2@}
7972 cp foo @var{dest1}; \
7976 The lines containing @code{@@example} and @code{@@end example} will
7977 disappear from the output. To make the output look good, you should
7978 put a blank line before the @code{@@example} and another blank line
7979 after the @code{@@end example}. Blank lines inside the beginning
7980 @code{@@example} and the ending @code{@@end example}, on the other
7981 hand, do appear in the output.
7984 Do not use tabs in the lines of an example! (Or anywhere else in
7985 Texinfo, except in verbatim environments.) @TeX{} treats tabs as
7986 single spaces, and that is not what they look like. In Emacs, you can
7987 use @kbd{M-x untabify} to convert tabs in a region to multiple spaces.
7990 Examples are often, logically speaking, ``in the middle'' of a
7991 paragraph, and the text that continues afterwards should not be
7992 indented, as in the example above. The @code{@@noindent} command
7993 prevents a piece of text from being indented as if it were a new
7994 paragraph (@pxref{noindent,,@code{@@noindent}}.
7996 If you want to embed code fragments within sentences, instead of
7997 displaying them, use the @code{@@code} command or its relatives
7998 (@pxref{code,,@code{@@code}}).
8000 If you wish to write a ``comment'' on a line of an example in the
8001 normal roman font, you can use the @code{@@r} command (@pxref{Fonts}).
8005 @section @code{@@verbatim}: Literal Text
8007 @cindex Verbatim environment
8009 Use the @code{@@verbatim} environment for printing of text that may
8010 contain special characters or commands that should not be interpreted,
8011 such as computer input or output (@code{@@example} interprets its text
8012 as regular Texinfo commands). This is especially useful for including automatically
8013 generated files in a Texinfo manual.
8015 In general, the output will be just the same as the input. No
8016 character substitutions are made, e.g., all spaces and blank lines are
8017 significant, including tabs. In the printed manual, the text is
8018 typeset in a fixed-width font, and not indented or filled.
8020 Write a @code{@@verbatim} command at the beginning of a line by itself.
8021 This line will disappear from the output. Mark the end of the verbatim
8022 block with a @code{@@end verbatim} command, also written at the
8023 beginning of a line by itself. The @code{@@end verbatim} will also
8024 disappear from the output.
8027 @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
8030 @exdent @t{@@verbatim}
8032 @exdent @key{TAB}@t{@@command with strange characters: @@'e}
8033 @exdent @t{expand@key{TAB}me}
8035 @exdent @t{@@end verbatim}
8043 @command with strange characters: @'e
8048 Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
8049 produce no output, typically you should put a blank line before the
8050 @code{@@verbatim} and another blank line after the @code{@@end
8051 verbatim}. Blank lines between the beginning @code{@@verbatim} and
8052 the ending @code{@@end verbatim} will appear in the output.
8054 @cindex Verbatim, small
8055 @cindex Small verbatim
8056 You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in
8057 an @code{@@smallformat} environment, as shown here:
8059 @c more cheating ...
8061 @exdent @t{@@smallformat}
8062 @exdent @t{@@verbatim}
8063 @exdent @t{... still verbatim, but in a smaller font ...}
8064 @exdent @t{@@end verbatim}
8065 @exdent @t{@@end smallformat}
8068 Finally, a word of warning: it is not reliable to use
8069 @code{@@verbatim} inside other Texinfo constructs.
8072 @node verbatiminclude
8073 @section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
8074 @cindex Verbatim, include file
8075 @cindex Including a file verbatim
8076 @findex verbatiminclude
8078 You can include the exact contents of a file in the document with the
8079 @code{@@verbatiminclude} command:
8082 @@verbatiminclude @var{filename}
8085 The contents of @var{filename} is printed in a verbatim environment
8086 (@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
8087 exactly as it is, with all special characters and white space
8088 retained. No indentation is added; if you want indentation, enclose
8089 the @code{@@verbatiminclude} within @code{@@example}
8090 (@pxref{example,,@code{@@example}}).
8092 The name of the file is taken literally, with a single exception:
8093 @code{@@value@{@var{var}@}} references are expanded. This makes it
8094 possible to include files in other directories within a distribution,
8098 @@verbatiminclude @@value@{top_srcdir@}/NEWS
8101 @noindent (You still have to get @code{top_srcdir} defined in the
8104 For a method on printing the file contents in a smaller font size, see
8105 the end of the previous section on @code{@@verbatim}.
8109 @section @code{@@lisp}: Marking a Lisp Example
8111 @cindex Lisp example
8113 The @code{@@lisp} command is used for Lisp code. It is synonymous
8114 with the @code{@@example} command.
8117 This is an example of text written between an
8118 @code{@@lisp} command and an @code{@@end lisp} command.
8121 Use @code{@@lisp} instead of @code{@@example} to preserve information
8122 regarding the nature of the example. This is useful, for example, if
8123 you write a function that evaluates only and all the Lisp code in a
8124 Texinfo file. Then you can use the Texinfo file as a Lisp
8125 library.@footnote{It would be straightforward to extend Texinfo to work
8126 in a similar fashion for C, Fortran, or other languages.}
8128 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
8133 @section @code{@@small@dots{}} Block Commands
8134 @cindex Small examples
8135 @cindex Examples in smaller fonts
8136 @cindex Lisp examples in smaller fonts
8137 @findex smalldisplay
8138 @findex smallexample
8142 In addition to the regular @code{@@example} and @code{@@lisp} commands,
8143 Texinfo has ``small'' example-style commands. These are
8144 @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
8147 In Info, the @code{@@small@dots{}} commands are equivalent to their
8148 non-small companion commands.
8150 In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in
8151 a smaller font than the non-small example commands. Consequently,
8152 many examples containing long lines fit on a page without needing to
8155 Mark the end of an @code{@@small@dots{}} block with a corresponding
8156 @code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
8157 @code{@@end smallexample}.
8159 Here is an example of the font used by the @code{@@small@dots{}}
8160 commands (in Info, the output will be the same as usual):
8163 @dots{} to make sure that you have the freedom to
8164 distribute copies of free software (and charge for
8165 this service if you wish), that you receive source
8166 code or can get it if you want it, that you can
8167 change the software or use pieces of it in new free
8168 programs; and that you know you can do these things.
8171 The @code{@@small@dots{}} commands make it easier to prepare manuals
8172 without forcing you to edit examples by hand to fit them onto narrower
8175 As a general rule, a printed document looks much better if you use
8176 only one of (for instance) @code{@@example} or @code{@@smallexample}
8177 consistently within a chapter.
8181 @section @code{@@display} and @code{@@smalldisplay}
8182 @cindex Display formatting
8185 The @code{@@display} command begins a kind of example, where each line
8186 of input produces a line of output, and the output is indented. It is
8187 thus like the @code{@@example} command except that, in a printed
8188 manual, @code{@@display} does not select the fixed-width font. In
8189 fact, it does not specify the font at all, so that the text appears in
8190 the same font it would have appeared in without the @code{@@display}
8194 This is an example of text written between an @code{@@display} command
8195 and an @code{@@end display} command. The @code{@@display} command
8196 indents the text, but does not fill it.
8199 @findex smalldisplay
8200 Texinfo also provides a command @code{@@smalldisplay}, which is like
8201 @code{@@display} but uses a smaller font in @code{@@smallbook} format.
8204 The @code{@@table} command (@pxref{table}) does not work inside
8205 @code{@@display}. Since @code{@@display} is line-oriented, it doesn't
8206 make sense to use them together. If you want to indent a table, try
8207 @code{@@quotation} (@pxref{quotation}).
8211 @section @code{@@format} and @code{@@smallformat}
8214 The @code{@@format} command is similar to @code{@@example} except
8215 that, in the printed manual, @code{@@format} does not select the
8216 fixed-width font and does not narrow the margins.
8219 This is an example of text written between an @code{@@format} command
8220 and an @code{@@end format} command. As you can see
8222 the @code{@@format} command does not fill the text.
8226 Texinfo also provides a command @code{@@smallformat}, which is like
8227 @code{@@format} but uses a smaller font in @code{@@smallbook} format.
8233 @section @code{@@exdent}: Undoing a Line's Indentation
8234 @cindex Indentation undoing
8237 The @code{@@exdent} command removes any indentation a line might have.
8238 The command is written at the beginning of a line and applies only to
8239 the text that follows the command that is on the same line. Do not use
8240 braces around the text. In a printed manual, the text on an
8241 @code{@@exdent} line is printed in the roman font.@refill
8243 @code{@@exdent} is usually used within examples. Thus,@refill
8248 This line follows an @@@@example command.
8249 @@exdent This line is exdented.
8250 This line follows the exdented line.
8251 The @@@@end example comes on the next line.
8261 This line follows an @@example command.
8262 @exdent This line is exdented.
8263 This line follows the exdented line.
8264 The @@end example comes on the next line.
8268 In practice, the @code{@@exdent} command is rarely used.
8269 Usually, you un-indent text by ending the example and
8270 returning the page to its normal width.@refill
8273 @node flushleft & flushright
8274 @section @code{@@flushleft} and @code{@@flushright}
8277 @cindex Ragged right
8280 The @code{@@flushleft} and @code{@@flushright} commands line up the
8281 ends of lines on the left and right margins of a page,
8282 but do not fill the text. The commands are written on lines of their
8283 own, without braces. The @code{@@flushleft} and @code{@@flushright}
8284 commands are ended by @code{@@end flushleft} and @code{@@end
8285 flushright} commands on lines of their own.@refill
8310 @code{@@flushright} produces the type of indentation often used in the
8311 return address of letters. For example,
8316 Here is an example of text written
8317 flushright. The @@code@{@@flushright@} command
8318 right justifies every line but leaves the
8328 Here is an example of text written
8329 flushright. The @code{@@flushright} command
8330 right justifies every line but leaves the
8336 @section @code{@@noindent}: Omitting Indentation
8337 @cindex Omitting indentation
8338 @cindex Suppressing indentation
8339 @cindex Indentation, omitting
8342 An example or other inclusion can break a paragraph into segments.
8343 Ordinarily, the formatters indent text that follows an example as a new
8344 paragraph. You can prevent this on a case-by-case basis by writing
8345 @code{@@noindent} at the beginning of a line, preceding the continuation
8346 text. You can also disable indentation for all paragraphs globally with
8347 @code{@@paragraphindent} (@pxref{paragraphindent, Paragraph Indenting}).
8349 It is best to write @code{@@noindent} on a line by itself, since in most
8350 environments, spaces following the command will not be ignored. It's ok
8351 to use it at the beginning of a line, with text following, outside of
8364 This line is not indented. As you can see, the
8365 beginning of the line is fully flush left with the line
8366 that follows after it. (This whole example is between
8367 @@code@{@@@@display@} and @@code@{@@@@end display@}.)
8380 This line is not indented. As you can see, the
8381 beginning of the line is fully flush left with the line
8382 that follows after it. (This whole example is between
8383 @code{@@display} and @code{@@end display}.)
8387 To adjust the number of blank lines properly in the Info file output,
8388 remember that the line containing @code{@@noindent} does not generate a
8389 blank line, and neither does the @code{@@end example} line.
8391 In the Texinfo source file for this manual, each line that says
8392 `produces' is preceded by @code{@@noindent}.
8394 Do not put braces after an @code{@@noindent} command; they are not
8395 necessary, since @code{@@noindent} is a command used outside of
8396 paragraphs (@pxref{Command Syntax}).
8400 @section @code{@@indent}: Forcing Indentation
8401 @cindex Forcing indentation
8402 @cindex Inserting indentation
8403 @cindex Indentation, forcing
8407 To complement the @code{@@noindent} command (see the previous
8408 section), Texinfo provides the @code{@@indent} command that forces a
8409 paragraph to be indented. This paragraph, for instance, is indented
8410 using an @code{@@indent} command. The first paragraph of a section is
8411 the most likely place to use @code{@@indent}, to override the normal
8412 behavior of no indentation there (@pxref{paragraphindent}).
8414 It is best to write @code{@@indent} on a line by itself, since in most
8415 environments, spaces following the command will not be ignored. The
8416 @code{@@indent} line will not generate a blank line in the Info output
8417 within an environment.
8419 However, it is ok to use it at the beginning of a line, with text
8420 following, outside of any environment.
8422 Do not put braces after an @code{@@indent} command; they are not
8423 necessary, since @code{@@indent} is a command used outside of
8424 paragraphs (@pxref{Command Syntax}).
8428 @section @code{@@cartouche}: Rounded Rectangles Around Examples
8430 @cindex Box with rounded corners
8431 @cindex Rounded rectangles, around examples
8433 In a printed manual, the @code{@@cartouche} command draws a box with
8434 rounded corners around its contents. In HTML, a normal rectangle is
8435 drawn (that's the best HTML can do). @code{@@cartouche} has no effect
8438 You can use this command to further highlight an example or quotation.
8439 For instance, you could write a manual in which one type of example is
8440 surrounded by a cartouche for emphasis.
8448 /usr/local/share/emacs
8454 surrounds the two-line example with a box with rounded corners, in the
8457 The output from the example looks like this (if you're reading this in
8458 Info, you'll see the @code{@@cartouche} had no effect):
8467 For proper output in HTML, it's necessary to put the
8468 @code{@@cartouche} around the @code{@@example}, and not the other way
8469 around. This limitation of @command{makeinfo} may be removed one day.
8471 @code{@@cartouche} also implies @code{@@group} (@pxref{group}).
8473 @node Lists and Tables
8474 @chapter Lists and Tables
8475 @cindex Making lists and tables
8476 @cindex Lists and tables, making
8477 @cindex Tables and lists, making
8479 Texinfo has several ways of making lists and tables. Lists can be
8480 bulleted or numbered; two-column tables can highlight the items in
8481 the first column; multi-column tables are also supported.
8484 * Introducing Lists:: Texinfo formats lists for you.
8485 * itemize:: How to construct a simple list.
8486 * enumerate:: How to construct a numbered list.
8487 * Two-column Tables:: How to construct a two-column table.
8488 * Multi-column Tables:: How to construct generalized tables.
8491 @node Introducing Lists
8492 @section Introducing Lists
8494 Texinfo automatically indents the text in lists or tables, and numbers
8495 an enumerated list. This last feature is useful if you modify the
8496 list, since you do not need to renumber it yourself.@refill
8498 Numbered lists and tables begin with the appropriate @@-command at the
8499 beginning of a line, and end with the corresponding @code{@@end}
8500 command on a line by itself. The table and itemized-list commands
8501 also require that you write formatting information on the same line as
8502 the beginning @@-command.@refill
8504 Begin an enumerated list, for example, with an @code{@@enumerate}
8505 command and end the list with an @code{@@end enumerate} command.
8506 Begin an itemized list with an @code{@@itemize} command, followed on
8507 the same line by a formatting command such as @code{@@bullet}, and end
8508 the list with an @code{@@end itemize} command.@refill
8511 Precede each element of a list with an @code{@@item} or @code{@@itemx}
8516 Here is an itemized list of the different kinds of table and lists:@refill
8520 Itemized lists with and without bullets.
8523 Enumerated lists, using numbers or letters.
8526 Two-column tables with highlighting.
8531 Here is an enumerated list with the same items:@refill
8535 Itemized lists with and without bullets.
8538 Enumerated lists, using numbers or letters.
8541 Two-column tables with highlighting.
8546 And here is a two-column table with the same items and their
8547 @w{@@-commands}:@refill
8551 Itemized lists with and without bullets.
8554 Enumerated lists, using numbers or letters.
8559 Two-column tables, optionally with indexing.
8564 @section @code{@@itemize}: Making an Itemized List
8568 The @code{@@itemize} command produces sequences of indented
8569 paragraphs, with a bullet or other mark inside the left margin
8570 at the beginning of each paragraph for which such a mark is desired.@refill
8572 @cindex @code{@@w}, for blank items
8573 Begin an itemized list by writing @code{@@itemize} at the beginning of
8574 a line. Follow the command, on the same line, with a character or a
8575 Texinfo command that generates a mark. Usually, you will write
8576 @code{@@bullet} after @code{@@itemize}, but you can use
8577 @code{@@minus}, or any command or character that results in a single
8578 character in the Info file. If you don't want any mark at all, use
8579 @code{@@w}. (When you write the mark command such as
8580 @code{@@bullet} after an @code{@@itemize} command, you may omit the
8581 @samp{@{@}}.) If you don't specify a mark command, the default is
8584 Write the text of the indented paragraphs themselves after the
8585 @code{@@itemize}, up to another line that says @code{@@end
8589 At the beginning of each paragraph for which a mark in the margin is
8590 desired, write a line that starts with @code{@@item}. It is ok to
8591 have text following the @code{@@item}.
8593 Usually, you should put a blank line before an @code{@@item}. This
8594 puts a blank line in the Info file. (@TeX{} inserts the proper
8595 interline whitespace in either case.) Except when the entries are
8596 very brief, these blank lines make the list look better.@refill
8598 Here is an example of the use of @code{@@itemize}, followed by the
8599 output it produces. @code{@@bullet} produces an @samp{*} in Info and a
8600 round dot in @TeX{}.
8629 Itemized lists may be embedded within other itemized lists. Here is a
8630 list marked with dashes embedded in a list marked with bullets:@refill
8675 @section @code{@@enumerate}: Making a Numbered or Lettered List
8679 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
8680 @code{@@itemize}}), except that the labels on the items are
8681 successive integers or letters instead of bullets.
8683 Write the @code{@@enumerate} command at the beginning of a line. The
8684 command does not require an argument, but accepts either a number or a
8685 letter as an option. Without an argument, @code{@@enumerate} starts the
8686 list with the number @samp{1}. With a numeric argument, such as
8687 @samp{3}, the command starts the list with that number. With an upper
8688 or lower case letter, such as @samp{a} or @samp{A}, the command starts
8689 the list with that letter.
8691 Write the text of the enumerated list in the same way as an itemized
8692 list: write a line starting with @code{@@item} at the beginning of
8693 each paragraph that you want enumerated. It is ok to have text
8694 following the @code{@@item}.
8696 You should put a blank line between entries in the list.
8697 This generally makes it easier to read the Info file.
8700 Here is an example of @code{@@enumerate} without an argument:
8725 Here is an example with an argument of @kbd{3}:@refill
8731 Predisposing causes.
8734 Precipitating causes.
8737 Perpetuating causes.
8747 Predisposing causes.
8750 Precipitating causes.
8753 Perpetuating causes.
8756 Here is a brief summary of the alternatives. The summary is constructed
8757 using @code{@@enumerate} with an argument of @kbd{a}.@refill
8763 Without an argument, produce a numbered list, starting with the number
8767 @code{@@enumerate @var{positive-integer}}
8769 With a (positive) numeric argument, start a numbered list with that
8770 number. You can use this to continue a list that you interrupted with
8774 @code{@@enumerate @var{upper-case-letter}}
8776 With an upper case letter as argument, start a list
8777 in which each item is marked
8778 by a letter, beginning with that upper case letter.@refill
8781 @code{@@enumerate @var{lower-case-letter}}
8783 With a lower case letter as argument, start a list
8784 in which each item is marked by
8785 a letter, beginning with that lower case letter.@refill
8788 You can also nest enumerated lists, as in an outline.@refill
8790 @node Two-column Tables
8791 @section Making a Two-column Table
8792 @cindex Tables, making two-column
8795 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
8796 @code{@@itemize}}), but allows you to specify a name or heading line for
8797 each item. The @code{@@table} command is used to produce two-column
8798 tables, and is especially useful for glossaries, explanatory
8799 exhibits, and command-line option summaries.
8802 * table:: How to construct a two-column table.
8803 * ftable vtable:: Automatic indexing for two-column tables.
8804 * itemx:: How to put more entries in the first column.
8808 @subsection Using the @code{@@table} Command
8810 @cindex Definition lists, typesetting
8811 Use the @code{@@table} command to produce two-column tables. It is
8812 usually listed for ``definition lists'' of various sorts, where you
8813 have a list of terms and a brief text with each one.
8815 Write the @code{@@table} command at the beginning of a line, after a
8816 blank line, and follow it on the same line with an argument that is a
8817 Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp},
8818 @code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}).
8820 This command will be applied to the text that goes into the first
8821 column of each item and thus determines how it will be highlighted.
8822 For example, @code{@@table @@code} will cause the text in the first
8823 column to be output as if it @code{@@code} command.
8826 You may also use the @code{@@asis} command as an argument to
8827 @code{@@table}. @code{@@asis} is a command that does nothing; if you
8828 use this command after @code{@@table}, the first column entries are
8829 output without added highlighting (``as is'').
8831 The @code{@@table} command works with other commands besides those
8832 explicitly mentioned here. However, you can only use commands that
8833 normally take arguments in braces. (In this case, however, you use
8834 the command name without an argument, because the subsequent
8835 @code{@@item}'s will supply the argument.)
8838 Begin each table entry with an @code{@@item} command at the beginning
8839 of a line. Write the first column text on the same line as the
8840 @code{@@item} command. Write the second column text on the line
8841 following the @code{@@item} line and on subsequent lines. (You do not
8842 need to type anything for an empty second column entry.) You may
8843 write as many lines of supporting text as you wish, even several
8844 paragraphs. But only the text on the same line as the @code{@@item}
8845 will be placed in the first column (including any footnotes).
8847 Normally, you should put a blank line before an @code{@@item} line.
8848 This puts a blank line in the Info file. Except when the entries are
8849 very brief, a blank line looks better.
8851 End the table with a line consisting of @code{@@end table}, followed
8852 by a blank line. @TeX{} will always start a new paragraph after the
8853 table, so the blank line is needed for the Info output to be analogous.
8856 The following table, for example, highlights the text in the first
8857 column with an @code{@@samp} command:
8863 This is the text for
8867 Text for @@samp@{bar@}.
8877 This is the text for
8880 Text for @samp{bar}.
8883 If you want to list two or more named items with a single block of
8884 text, use the @code{@@itemx} command. (@xref{itemx,,@code{@@itemx}}.)
8888 @subsection @code{@@ftable} and @code{@@vtable}
8889 @cindex Tables with indexes
8890 @cindex Indexing table entries automatically
8894 The @code{@@ftable} and @code{@@vtable} commands are the same as the
8895 @code{@@table} command except that @code{@@ftable} automatically enters
8896 each of the items in the first column of the table into the index of
8897 functions and @code{@@vtable} automatically enters each of the items in
8898 the first column of the table into the index of variables. This
8899 simplifies the task of creating indices. Only the items on the same
8900 line as the @code{@@item} commands are indexed, and they are indexed in
8901 exactly the form that they appear on that line. @xref{Indices},
8902 for more information about indices.@refill
8904 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8905 writing the @@-command at the beginning of a line, followed on the same
8906 line by an argument that is a Texinfo command such as @code{@@code},
8907 exactly as you would for an @code{@@table} command; and end the table
8908 with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8911 See the example for @code{@@table} in the previous section.
8914 @subsection @code{@@itemx}
8915 @cindex Two named items for @code{@@table}
8918 Use the @code{@@itemx} command inside a table when you have two or more
8919 first column entries for the same item, each of which should appear on a
8922 Use @code{@@item} for the first entry, and @code{@@itemx} for all
8923 subsequent entries; @code{@@itemx} must always follow an @code{@@item}
8924 command, with no blank line intervening.
8926 The @code{@@itemx} command works exactly like @code{@@item} except
8927 that it does not generate extra vertical space above the first column
8928 text. If you have multiple consecutive @code{@@itemx} commands, do
8929 not insert any blank lines between them.
8938 These two functions accept a character or a string as
8939 argument, and return the corresponding upper case (lower
8940 case) character or string.
8951 These two functions accept a character or a string as
8952 argument, and return the corresponding upper case (lower
8953 case) character or string.@refill
8957 (Note also that this example illustrates multi-line supporting text in
8958 a two-column table.)@refill
8961 @node Multi-column Tables
8962 @section @code{@@multitable}: Multi-column Tables
8963 @cindex Tables, making multi-column
8966 @code{@@multitable} allows you to construct tables with any number of
8967 columns, with each column having any width you like.
8969 You define the column widths on the @code{@@multitable} line itself, and
8970 write each row of the actual table following an @code{@@item} command,
8971 with columns separated by an @code{@@tab} command. Finally, @code{@@end
8972 multitable} completes the table. Details in the sections below.
8975 * Multitable Column Widths:: Defining multitable column widths.
8976 * Multitable Rows:: Defining multitable rows, with examples.
8979 @node Multitable Column Widths
8980 @subsection Multitable Column Widths
8981 @cindex Multitable column widths
8982 @cindex Column widths, defining for multitables
8983 @cindex Widths, defining multitable column
8985 You can define the column widths for a multitable in two ways: as
8986 fractions of the line length; or with a prototype row. Mixing the two
8987 methods is not supported. In either case, the widths are defined
8988 entirely on the same line as the @code{@@multitable} command.
8992 @findex columnfractions
8993 @cindex Line length, column widths as fraction of
8994 To specify column widths as fractions of the line length, write
8995 @code{@@columnfractions} and the decimal numbers (presumably less than
8996 1; a leading zero is allowed and ignored) after the
8997 @code{@@multitable} command, as in:
9000 @@multitable @@columnfractions .33 .33 .33
9003 The fractions need not add up exactly to 1.0, as these do not. This
9004 allows you to produce tables that do not need the full line length.
9007 @cindex Prototype row, column widths defined by
9008 To specify a prototype row, write the longest entry for each column
9009 enclosed in braces after the @code{@@multitable} command. For example:
9012 @@multitable @{some text for column one@} @{for column two@}
9016 The first column will then have the width of the typeset `some text for
9017 column one', and the second column the width of `for column two'.
9019 The prototype entries need not appear in the table itself.
9021 Although we used simple text in this example, the prototype entries can
9022 contain Texinfo commands; markup commands such as @code{@@code} are
9023 particularly likely to be useful.
9028 @node Multitable Rows
9029 @subsection Multitable Rows
9030 @cindex Multitable rows
9031 @cindex Rows, of a multitable
9035 After the @code{@@multitable} command defining the column widths (see
9036 the previous section), you begin each row in the body of a multitable
9037 with @code{@@item}, and separate the column entries with @code{@@tab}.
9038 Line breaks are not special within the table body, and you may break
9039 input lines in your source file as necessary.
9042 @cindex Heading row, in table
9043 @cindex <thead> HTML tag
9044 You can also use @code{@@headitem} instead of @code{@@item} to produce
9045 a @dfn{heading row}. The @TeX{} output for such a row is in bold, and
9046 the HTML, XML, and Docbook output uses the @code{<thead>} tag. In
9047 Info, the heading row is followed by a separator line made of dashes
9048 (@samp{-} characters).
9050 Here is a complete example of a multi-column table (the text is from
9051 @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
9052 emacs, The GNU Emacs Manual}):
9055 @@multitable @@columnfractions .15 .45 .4
9056 @@headitem Key @@tab Command @@tab Description
9058 @@tab @@code@{split-window-vertically@}
9059 @@tab Split the selected window into two windows,
9060 with one above the other.
9062 @@tab @@code@{split-window-horizontally@}
9063 @@tab Split the selected window into two windows
9064 positioned side by side.
9067 @@tab In the mode line or scroll bar of a window,
9074 @multitable @columnfractions .15 .45 .4
9075 @headitem Key @tab Command @tab Description
9077 @tab @code{split-window-vertically}
9078 @tab Split the selected window into two windows,
9079 with one above the other.
9081 @tab @code{split-window-horizontally}
9082 @tab Split the selected window into two windows
9083 positioned side by side.
9086 @tab In the mode line or scroll bar of a window,
9091 @node Special Displays
9092 @chapter Special Displays
9093 @cindex Special displays
9095 The commands in this chapter allow you to write text that is specially
9096 displayed (output format permitting), outside of the normal document
9099 One set of such commands is for creating ``floats'', that is, figures,
9100 tables, and the like, set off from the main text, possibly numbered,
9101 captioned, and/or referred to from elsewhere in the document. Images
9102 are often included in these displays.
9104 Another group of commands is for creating footnotes in Texinfo.
9107 * Floats:: Figures, tables, and the like.
9108 * Images:: Including graphics and images.
9109 * Footnotes:: Writing footnotes.
9115 @cindex Floats, in general
9117 A @dfn{float} is a display which is set off from the main text. It is
9118 typically labelled as being a ``Figure'', ``Table'', ``Example'', or
9121 @cindex Floating, not yet implemented
9122 A float is so-named because, in principle, it can be moved to the
9123 bottom or top of the current page, or to a following page, in the
9124 printed output. (Floating does not make sense in other output
9125 formats.) In the present version of Texinfo, however, this floating
9126 is unfortunately not yet implemented. Instead, the floating material
9127 is simply output at the current location, more or less as if it were
9128 an @code{@@group} (@pxref{group,,@code{@@group}}).
9131 * float:: Producing floating material.
9132 * caption shortcaption:: Specifying descriptions for floats.
9133 * listoffloats:: A table of contents for floats.
9138 @subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material
9140 @cindex Float environment
9142 To produce floating material, enclose the material you want to be
9143 displayed separate between @code{@@float} and @code{@@end float}
9144 commands, on lines by themselves.
9146 Floating material uses @code{@@image} to display an already-existing
9147 graphic (@pxref{Images}), or @code{@@multitable} to display a table
9148 (@pxref{Multi-column Tables}). However, the contents of the float can
9149 be anything. Here's an example with simple text:
9152 @@float Figure,fig:ex1
9153 This is an example float.
9157 @noindent And the output:
9159 @float Figure,fig:ex1
9160 This is an example float.
9163 As shown in the example, @code{@@float} takes two arguments (separated
9164 by a comma), @var{type} and @var{label}. Both are optional.
9168 Specifies the sort of float this is; typically a word such as
9169 ``Figure'', ``Table'', etc. If not given, and @var{label} is, any
9170 cross-referencing will simply use a bare number.
9173 Specifies a cross-reference label for this float. If given, this
9174 float is automatically given a number, and will appear in any
9175 @code{@@listoffloats} output (@pxref{listoffloats}). Cross-references
9176 to @var{label} are allowed.
9178 @cindex Floats, making unnumbered
9179 @cindex Unnumbered float, creating
9180 On the other hand, if @var{label} is not given, then the float will
9181 not be numbered and consequently will not appear in the
9182 @code{@@listoffloats} output or be cross-referenceable.
9185 @noindent Normally, you specify both @var{type} and @var{label}, to get a
9186 labeled and numbered float.
9188 @cindex Floats, numbering of
9189 @cindex Numbering of floats
9190 In Texinfo, all floats are numbered the same way: with the chapter
9191 number (or appendix letter), a period, and the float number, which
9192 simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each
9193 float type is counted independently.
9195 Floats within an @code{@@unnumbered} are numbered, or outside of any
9196 chapter, are simply numbered consecutively from 1.
9198 These numbering conventions are not, at present, changeable.
9201 @node caption shortcaption
9202 @subsection @code{@@caption} & @code{@@shortcaption}
9204 @findex shortcaption
9205 @cindex Captions, for floats
9206 @cindex Short captions, for lists of floats
9208 You may write an @code{@@caption} anywhere within a @code{@@float}
9209 environment, to define a caption for the float. It is not allowed in
9210 any other context. @code{@@caption} takes a single argument, enclosed
9211 in braces. Here's an example:
9215 An example float, with caption.
9216 @@caption@{Caption for example float.@}
9220 @noindent The output is:
9223 An example float, with caption.
9224 @caption{Caption for example float.}
9227 @code{@@caption} can appear anywhere within the float; it is not
9228 processed until the @code{@@end float}. The caption text is usually a
9229 sentence or two, but may consist of several paragraphs if necessary.
9231 In the output, the caption always appears below the float; this is not
9232 currently changeable. It is preceded by the float type and/or number,
9233 as specified to the @code{@@float} command (see the previous section).
9235 The @code{@@shortcaption} command likewise may be used only within
9236 @code{@@float}, and takes a single argument in braces. The short
9237 caption text is used instead of the caption text in a list of floats
9238 (see the next section). Thus, you can write a long caption for the
9239 main document, and a short title to appear in the list of floats. For
9245 @@shortcaption@{Text for list of floats.@}
9249 The text for @code{@@caption} and @code{@@shortcaption} may not
9250 contain comments (@code{@@c}), verbatim text (@code{@@verb}),
9251 environments such as @code{@@example}, or other complex constructs.
9255 @subsection @code{@@listoffloats}: Tables of Contents for Floats
9256 @findex listoffloats
9257 @cindex List of floats
9258 @cindex Floats, list of
9259 @cindex Table of contents, for floats
9261 You can write a @code{@@listoffloats} command to generate a list of
9262 floats for a given float type (@pxref{float}), analogous to the
9263 document's overall table of contents. Typically, it is written in its
9264 own @code{@@unnumbered} node to provide a heading and structure,
9265 rather like @code{@@printindex} (@pxref{Printing Indices & Menus}).
9267 @code{@@listoffloats} takes one optional argument, the float type.
9271 @@node List of Figures
9272 @@unnumbered List of Figures
9273 @@listoffloats Figure
9276 @noindent And the output from @code{@@listoffloats}:
9279 @listoffloats Figure
9282 Without any argument, @code{@@listoffloats} generates a list of
9283 floats for which no float type was specified, i.e., no first argument
9284 to the @code{@@float} command (@pxref{float}).
9286 Each line in the list of floats contains the float type (if any),
9287 the float number, and the caption, if any---the @code{@@shortcaption}
9288 argument, if it was specified, else the @code{@@caption} argument.
9289 In Info, the result is a menu where each float can be selected. In
9290 HTML, each line is a link to the float. In printed output, the page
9293 Unnumbered floats (those without cross-reference labels) are omitted
9294 from the list of floats.
9298 @section Inserting Images
9300 @cindex Images, inserting
9301 @cindex Pictures, inserting
9304 You can insert an image given in an external file with the
9305 @code{@@image} command. Although images can be used anywhere,
9306 including the middle of a paragraph, we describe them in this chapter
9307 since they are most often part of a displayed figure or example.
9316 @subsection Image Syntax
9318 Here is the synopsis of the @code{@@image} command:
9321 @@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@}
9324 @cindex Formats for images
9325 @cindex Image formats
9326 The @var{filename} argument is mandatory, and must not have an
9327 extension, because the different processors support different formats:
9331 @pindex eps image format
9332 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
9335 @pindex pdftex@r{, and images}
9336 @pindex png image format
9337 @pindex jpeg image format
9338 @pindex pdf image inclusions
9339 pdf@TeX{} reads @file{@var{filename}.png}, @file{@var{filename}.jpg},
9340 @file{@var{filename}.jpeg}, or @file{@var{filename}.pdf} (in that
9341 order). It also tries uppercase versions of the extensions. The PDF
9342 format cannot support EPS images, so they must be converted first.
9344 @code{makeinfo} includes @file{@var{filename}.txt} verbatim for
9345 Info output (more or less as if it was an @code{@@example}).
9347 @code{makeinfo} uses the optional fifth argument @var{extension} to
9348 @code{@@image} for the filename extension, if it is specified. For example:
9350 @pindex XPM image format
9352 @@image@{foo,,,,.xpm@}
9356 will cause @code{makeinfo} to look for @file{foo.xpm} before any others.
9360 The @var{width} and @var{height} arguments are described in the next
9363 For @TeX{} output, if an image is the only thing in a paragraph it
9364 will ordinarily be displayed on a line by itself, respecting the
9365 current environment indentation, but without the normal paragraph
9366 indentation. If you want it centered, use @code{@@center}
9367 (@pxref{titlefont center sp,,@code{@@titlefont @@center @@sp}}).
9369 @cindex Alt attribute for images
9370 @cindex Images, alternate text for
9371 @findex - (in image alt string)
9372 For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for
9373 inline images to the optional @var{alttext} (fourth) argument to
9374 @code{@@image}, if supplied. If not supplied, @code{makeinfo} uses
9375 the full file name of the image being displayed. The @var{alttext} is
9376 taken as Texinfo text, so special characters such as @samp{"} and
9377 @samp{<} and @samp{&} are escaped in the HTML and XML output; also,
9378 you can get an empty @code{alt} string with @code{@@-} (a command
9379 that produces no output; @pxref{- and hyphenation}).
9381 For Info output, the @code{alt} string is also processed as Texinfo
9382 text and output. In this case, @samp{\} is escaped as @samp{\\} and
9383 @samp{"} as @samp{\"}; no other escapes are done.
9385 @cindex PNG image format
9386 @cindex JPEG image format
9387 If you do not supply the optional @var{extension} (fifth) argument,
9388 @code{makeinfo} first tries @file{@var{filename}.png}; if that does
9389 not exist, it tries @file{@var{filename}.jpg}. If that does not exist
9390 either, it complains.
9392 In Info output, @code{makeinfo} writes a reference to the binary image
9393 file (trying @var{filename} suffixed with @file{@var{extension}},
9394 @file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order)
9395 if one exists. It also literally includes the @file{.txt} file if one
9396 exists. This way, Info readers which can display images (such as the
9397 Emacs Info browser, running under X) can do so, whereas Info readers
9398 which can only use text (such as the standalone Info reader) can
9399 display the textual version.
9401 @cindex @samp{^@@^H} for images in Info
9402 The implementation of this is to put the following construct into the
9406 ^@@^H[image src="@var{binaryfile}" text="@var{txtfile}"
9407 alt="@var{alttext} ... ^@@^H]
9410 @noindent where @samp{^@@} and @samp{^H} stand for the actual null and
9411 backspace control characters. If one of the files is not present, the
9412 corresponding argument is omitted.
9414 The reason for mentioning this here is that older Info browsers (this
9415 feature was introduced in Texinfo version 4.6) will display the above
9416 literally, which, although not pretty, should not be harmful.
9420 @subsection Image Scaling
9422 @cindex Images, scaling
9423 @cindex Scaling images
9424 @cindex Width of images
9425 @cindex Height of images
9426 @cindex Aspect ratio of images
9427 @cindex Distorting images
9428 The optional @var{width} and @var{height} arguments to the
9429 @code{@@image} command (see the previous section) specify the size to
9430 scale the image to. They are ignored for Info output. If neither is
9431 specified, the image is presented in its natural size (given in the
9432 file); if only one is specified, the other is scaled proportionately;
9433 and if both are specified, both are respected, thus possibly distorting
9434 the original image by changing its aspect ratio.
9436 @cindex Dimensions and image sizes
9437 The @var{width} and @var{height} may be specified using any valid @TeX{}
9442 @cindex Points (dimension)
9443 point (72.27pt = 1in)
9449 big point (72bp = 1in)
9455 centimeter (2.54cm = 1in)
9458 millimeter (10mm = 1cm)
9460 @cindex Did@^ot points
9461 did@^ot point (1157dd = 1238pt)
9466 @cindex Scaled points
9467 scaled point (65536sp = 1pt)
9471 For example, the following will scale a file @file{ridt.eps} to one
9472 inch vertically, with the width scaled proportionately:
9475 @@image@{ridt,,1in@}
9479 For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
9480 installed somewhere that @TeX{} can find it. (The standard location is
9481 @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
9482 root of your @TeX{} directory tree.) This file is included in the
9483 Texinfo distribution and is also available from
9484 @uref{ftp://tug.org/tex/epsf.tex}, among other places.
9486 @code{@@image} can be used within a line as well as for displayed
9487 figures. Therefore, if you intend it to be displayed, be sure to leave
9488 a blank line before the command, or the output will run into the
9491 Image scaling is presently implemented only in @TeX{}, not in HTML or
9492 any other sort of output.
9500 A @dfn{footnote} is for a reference that documents or elucidates the
9501 primary text.@footnote{A footnote should complement or expand upon
9502 the primary text, but a reader should not need to read a footnote to
9503 understand the primary text. For a thorough discussion of footnotes,
9504 see @cite{The Chicago Manual of Style}, which is published by the
9505 University of Chicago Press.} Footnotes are distracting; use them
9506 sparingly, if at all. Standard bibliographical references are better
9507 placed in a bibliography at the end of a document than in footnotes
9511 * Footnote Commands:: How to write a footnote in Texinfo.
9512 * Footnote Styles:: Controlling how footnotes appear in Info.
9516 @node Footnote Commands
9517 @subsection Footnote Commands
9519 In Texinfo, footnotes are created with the @code{@@footnote} command.
9520 This command is followed immediately by a left brace, then by the text
9521 of the footnote, and then by a terminating right brace. Footnotes may
9522 be of any length (they will be broken across pages if necessary), but
9523 are usually short. The template is:
9526 ordinary text@@footnote@{@var{text of footnote}@}
9529 As shown here, the @code{@@footnote} command should come right after the
9530 text being footnoted, with no intervening space; otherwise, the footnote
9531 marker might end up starting a line.
9533 For example, this clause is followed by a sample footnote@footnote{Here
9534 is the sample footnote.}; in the Texinfo source, it looks like
9538 @dots{}a sample footnote@@footnote@{Here is the sample
9539 footnote.@}; in the Texinfo source@dots{}
9542 As you can see, the source includes two punctuation marks next to each
9543 other; in this case, @samp{.@};} is the sequence. This is normal (the
9544 first ends the footnote and the second belongs to the sentence being
9545 footnoted), so don't worry that it looks odd.
9547 In a printed manual or book, the reference mark for a footnote is a
9548 small, superscripted number; the text of the footnote appears at the
9549 bottom of the page, below a horizontal line.
9551 In Info, the reference mark for a footnote is a pair of parentheses
9552 with the footnote number between them, like this: @samp{(1)}. The
9553 reference mark is followed by a cross-reference link to the footnote's
9556 In the HTML output, footnote references are marked with a small,
9557 superscripted number which is rendered as a hypertext link to the
9560 By the way, footnotes in the argument of an @code{@@item} command for a
9561 @code{@@table} must be on the same line as the @code{@@item}
9562 (as usual). @xref{Two-column Tables}.
9565 @node Footnote Styles
9566 @subsection Footnote Styles
9568 Info has two footnote styles, which determine where the text of the
9569 footnote is located:
9572 @cindex @samp{@r{End}} node footnote style
9574 In the `End' node style, all the footnotes for a single node
9575 are placed at the end of that node. The footnotes are separated from
9576 the rest of the node by a line of dashes with the word
9577 @samp{Footnotes} within it. Each footnote begins with an
9578 @samp{(@var{n})} reference mark.
9582 Here is an example of a single footnote in the end of node style:@refill
9586 --------- Footnotes ---------
9588 (1) Here is a sample footnote.
9592 @cindex @samp{@r{Separate}} footnote style
9594 In the `Separate' node style, all the footnotes for a single
9595 node are placed in an automatically constructed node of
9596 their own. In this style, a ``footnote reference'' follows
9597 each @samp{(@var{n})} reference mark in the body of the
9598 node. The footnote reference is actually a cross reference
9599 which you use to reach the footnote node.
9601 The name of the node with the footnotes is constructed
9602 by appending @w{@samp{-Footnotes}} to the name of the node
9603 that contains the footnotes. (Consequently, the footnotes'
9604 node for the @file{Footnotes} node is
9605 @w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
9606 `Up' node pointer that leads back to its parent node.
9609 Here is how the first footnote in this manual looks after being
9610 formatted for Info in the separate node style:
9614 File: texinfo.info Node: Overview-Footnotes, Up: Overview
9616 (1) The first syllable of "Texinfo" is pronounced like "speck", not
9622 Unless your document has long and important footnotes (as in, say,
9623 Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end}
9624 style, as it is simpler for readers to follow.
9626 @findex footnotestyle
9627 Use the @code{@@footnotestyle} command to specify an Info file's
9628 footnote style. Write this command at the beginning of a line followed
9629 by an argument, either @samp{end} for the end node style or
9630 @samp{separate} for the separate node style.
9641 @@footnotestyle separate
9644 Write an @code{@@footnotestyle} command before or shortly after the
9645 end-of-header line at the beginning of a Texinfo file. (If you
9646 include the @code{@@footnotestyle} command between the start-of-header
9647 and end-of-header lines, the region formatting commands will format
9648 footnotes as specified.)@refill
9650 If you do not specify a footnote style, the formatting commands use
9651 their default style. Currently, @code{texinfo-format-buffer} and
9652 @code{texinfo-format-region} use the `separate' style and
9653 @code{makeinfo} uses the `end' style.
9660 Using Texinfo, you can generate indices without having to sort and
9661 collate entries manually. In an index, the entries are listed in
9662 alphabetical order, together with information on how to find the
9663 discussion of each entry. In a printed manual, this information
9664 consists of page numbers. In an Info file, this information is a menu
9665 entry leading to the first node referenced.
9667 Texinfo provides several predefined kinds of index: an index
9668 for functions, an index for variables, an index for concepts, and so
9669 on. You can combine indices or use them for other than their
9670 canonical purpose. Lastly, you can define your own new indices.
9672 @xref{Printing Indices & Menus}, for information on how to print
9676 * Index Entries:: Choose different words for index entries.
9677 * Predefined Indices:: Use different indices for different kinds
9679 * Indexing Commands:: How to make an index entry.
9680 * Combining Indices:: How to combine indices.
9681 * New Indices:: How to define your own indices.
9686 @section Making Index Entries
9687 @cindex Index entries, making
9688 @cindex Entries, making index
9690 When you are making index entries, it is good practice to think of the
9691 different ways people may look for something. Different people
9692 @emph{do not} think of the same words when they look something up. A
9693 helpful index will have items indexed under all the different words
9694 that people may use. For example, one reader may think it obvious that
9695 the two-letter names for indices should be listed under ``Indices,
9696 two-letter names'', since the word ``Index'' is the general concept.
9697 But another reader may remember the specific concept of two-letter
9698 names and search for the entry listed as ``Two letter names for
9699 indices''. A good index will have both entries and will help both
9702 Like typesetting, the construction of an index is a highly skilled,
9703 professional art, the subtleties of which are not appreciated until you
9704 need to do it yourself.@refill
9706 @xref{Printing Indices & Menus}, for information about printing an index
9707 at the end of a book or creating an index menu in an Info file.@refill
9710 @node Predefined Indices
9711 @section Predefined Indices
9713 Texinfo provides six predefined indices. Here are their nominal
9714 meanings, abbreviations, and the corresponding index entry commands:
9718 @cindex @code{cp} (concept) index
9719 (@code{@@cindex}) concept index, for general concepts.
9721 @cindex @code{fn} (function) index
9722 (@code{@@findex}) function index, for function and function-like
9723 names (such as entry points of libraries).
9725 @cindex @code{ky} (keystroke) index
9726 (@code{@@kindex}) keystroke index, for keyboard commands.
9728 @cindex @code{pg} (program) index
9729 (@code{@@pindex}) program index, for names of programs.
9731 @cindex @code{tp} (data type) index
9732 (@code{@@tindex}) data type index, for type names (such as structures
9733 defined in header files).
9735 @cindex @code{vr} (variable) index
9736 (@code{@@vindex}) variable index, for variable names (such as global
9737 variables of libraries).
9741 Not every manual needs all of these, and most manuals use only two or
9742 three at most. The present manual, for example, has two indices: a
9743 concept index and an @@-command index (that is actually the function
9744 index but is called a command index in the chapter heading).
9746 You are not required to use the predefined indices strictly for their
9747 canonical purposes. For example, suppose you wish to index some C
9748 preprocessor macros. You could put them in the function index along
9749 with actual functions, just by writing @code{@@findex} commands for
9750 them; then, when you print the ``Function Index'' as an unnumbered
9751 chapter, you could give it the title `Function and Macro Index' and
9752 all will be consistent for the reader.
9754 On the other hand, it is best not to stray too far from the meaning of
9755 the predefined indices. Otherwise, in the event that your text is
9756 combined with other text from other manuals, the index entries will
9757 not match up. Instead, define your own new index (@pxref{New
9760 We recommend having a single index in the final document whenever
9761 possible, however many source indices you use, since then readers have
9762 only one place to look. Two or more source indices can be combined
9763 into one output index using the @code{@@synindex} or
9764 @code{@@syncodeindex} commands (@pxref{Combining Indices}).
9767 @node Indexing Commands
9768 @section Defining the Entries of an Index
9769 @cindex Defining indexing entries
9770 @cindex Index entries
9771 @cindex Entries for an index
9772 @cindex Specifying index entries
9773 @cindex Creating index entries
9775 The data to make an index come from many individual indexing commands
9776 scattered throughout the Texinfo source file. Each command says to add
9777 one entry to a particular index; after formatting, the index will give
9778 the current page number or node name as the reference.@refill
9780 An index entry consists of an indexing command at the beginning of a
9781 line followed, on the rest of the line, by the entry.@refill
9783 For example, this section begins with the following five entries for
9784 the concept index:@refill
9787 @@cindex Defining indexing entries
9788 @@cindex Index entries, defining
9789 @@cindex Entries for an index
9790 @@cindex Specifying index entries
9791 @@cindex Creating index entries
9794 Each predefined index has its own indexing command---@code{@@cindex}
9795 for the concept index, @code{@@findex} for the function index, and so
9796 on, as listed in the previous section.
9798 @cindex Writing index entries
9799 @cindex Index entry writing
9800 Concept index entries consist of text. The best way to write an index
9801 is to choose entries that are terse yet clear. If you can do this,
9802 the index often looks better if the entries are not capitalized, but
9803 written just as they would appear in the middle of a sentence.
9804 (Capitalize proper names and acronyms that always call for upper case
9805 letters.) This is the case convention we use in most GNU manuals'
9808 If you don't see how to make an entry terse yet clear, make it longer
9809 and clear---not terse and confusing. If many of the entries are several
9810 words long, the index may look better if you use a different convention:
9811 to capitalize the first word of each entry. But do not capitalize a
9812 case-sensitive name such as a C or Lisp function name or a shell
9813 command; that would be a spelling error.
9815 Whichever case convention you use, please use it consistently!
9817 Entries in indices other than the concept index are symbol names in
9818 programming languages, or program names; these names are usually
9819 case-sensitive, so use upper and lower case as required for them.
9821 @cindex Index font types
9822 By default, entries for a concept index are printed in a small roman
9823 font and entries for the other indices are printed in a small
9824 @code{@@code} font. You may change the way part of an entry is
9825 printed with the usual Texinfo commands, such as @code{@@file} for
9826 file names (@pxref{Marking Text}), and @code{@@r} for the normal roman
9827 font (@pxref{Fonts}).
9830 Do not use a colon in an index entry. In Info, a colon separates the
9831 menu entry name from the node name, so a colon in the entry itself
9832 confuses Info. @xref{Menu Parts}, for more information about the
9833 structure of a menu entry.
9837 @node Combining Indices
9838 @section Combining Indices
9839 @cindex Combining indices
9840 @cindex Indices, combining them
9842 Sometimes you will want to combine two disparate indices such as
9843 functions and concepts, perhaps because you have few enough entries
9844 that a separate index would look silly.
9846 You could put functions into the concept index by writing
9847 @code{@@cindex} commands for them instead of @code{@@findex} commands,
9848 and produce a consistent manual by printing the concept index with the
9849 title `Function and Concept Index' and not printing the `Function
9850 Index' at all; but this is not a robust procedure. It works only if
9851 your document is never included as part of another document that is
9852 designed to have a separate function index; if your document were to
9853 be included with such a document, the functions from your document and
9854 those from the other would not end up together. Also, to make your
9855 function names appear in the right font in the concept index, you
9856 would need to enclose every one of them between the braces of
9860 * syncodeindex:: How to merge two indices, using @code{@@code}
9861 font for the merged-from index.
9862 * synindex:: How to merge two indices, using the
9863 default font of the merged-to index.
9867 @subsection @code{@@syncodeindex}
9868 @findex syncodeindex
9870 When you want to combine functions and concepts into one index, you
9871 should index the functions with @code{@@findex} and index the concepts
9872 with @code{@@cindex}, and use the @code{@@syncodeindex} command to
9873 redirect the function index entries into the concept index.@refill
9875 The @code{@@syncodeindex} command takes two arguments; they are the name
9876 of the index to redirect, and the name of the index to redirect it to.
9877 The template looks like this:@refill
9880 @@syncodeindex @var{from} @var{to}
9883 @cindex Predefined names for indices
9884 @cindex Two letter names for indices
9885 @cindex Indices, two letter names
9886 @cindex Names for indices
9887 For this purpose, the indices are given two-letter names:@refill
9904 Write an @code{@@syncodeindex} command before or shortly after the
9905 end-of-header line at the beginning of a Texinfo file. For example,
9906 to merge a function index with a concept index, write the
9910 @@syncodeindex fn cp
9914 This will cause all entries designated for the function index to merge
9915 in with the concept index instead.@refill
9917 To merge both a variables index and a function index into a concept
9918 index, write the following:@refill
9922 @@syncodeindex vr cp
9923 @@syncodeindex fn cp
9927 @cindex Fonts for indices
9928 The @code{@@syncodeindex} command puts all the entries from the `from'
9929 index (the redirected index) into the @code{@@code} font, overriding
9930 whatever default font is used by the index to which the entries are
9931 now directed. This way, if you direct function names from a function
9932 index into a concept index, all the function names are printed in the
9933 @code{@@code} font as you would expect.@refill
9936 @subsection @code{@@synindex}
9939 The @code{@@synindex} command is nearly the same as the
9940 @code{@@syncodeindex} command, except that it does not put the
9941 `from' index entries into the @code{@@code} font; rather it puts
9942 them in the roman font. Thus, you use @code{@@synindex} when you
9943 merge a concept index into a function index.@refill
9945 @xref{Printing Indices & Menus}, for information about printing an index
9946 at the end of a book or creating an index menu in an Info file.@refill
9950 @section Defining New Indices
9951 @cindex Defining new indices
9952 @cindex Indices, defining new
9953 @cindex New index defining
9955 @findex defcodeindex
9957 In addition to the predefined indices, you may use the
9958 @code{@@defindex} and @code{@@defcodeindex} commands to define new
9959 indices. These commands create new indexing @@-commands with which
9960 you mark index entries. The @code{@@defindex} command is used like
9964 @@defindex @var{name}
9967 The name of an index should be a two letter word, such as @samp{au}.
9974 This defines a new index, called the @samp{au} index. At the same
9975 time, it creates a new indexing command, @code{@@auindex}, that you
9976 can use to make index entries. Use this new indexing command just as
9977 you would use a predefined indexing command.
9979 For example, here is a section heading followed by a concept index
9980 entry and two @samp{au} index entries.
9983 @@section Cognitive Semantics
9984 @@cindex kinesthetic image schemas
9985 @@auindex Johnson, Mark
9986 @@auindex Lakoff, George
9990 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
9992 In general, Texinfo constructs the new indexing command by
9993 concatenating the name of the index with @samp{index}; thus, defining
9994 an @samp{xy} index leads to the automatic creation of an
9995 @code{@@xyindex} command.
9997 Use the @code{@@printindex} command to print the index, as you do with
9998 the predefined indices. For example:
10002 @@node Author Index
10003 @@unnumbered Author Index
10009 The @code{@@defcodeindex} is like the @code{@@defindex} command,
10010 except that, in the printed output, it prints entries in an
10011 @code{@@code} font by default instead of a roman font.
10013 You should define new indices before the end-of-header line of a
10014 Texinfo file, and (of course) before any @code{@@synindex} or
10015 @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
10019 @chapter Special Insertions
10020 @cindex Inserting special characters and symbols
10021 @cindex Special insertions
10023 Texinfo provides several commands for inserting characters that have
10024 special meaning in Texinfo, such as braces, and for other graphic
10025 elements that do not correspond to simple characters you can type.
10031 @item @samp{@@} and braces and commas.
10032 @item Whitespace within and around a sentence.
10034 @item Dots and bullets.
10035 @item The @TeX{} logo and the copyright symbol.
10036 @item The euro and pounds currency symbols.
10037 @item The degrees symbol.
10038 @item The minus sign.
10039 @item Mathematical expressions.
10040 @item Glyphs for evaluation, macros, errors, etc.
10047 * Atsign Braces Comma:: Inserting @@ and @{@} and ,.
10048 * Inserting Quote Characters:: Inserting left and right quotes, in code.
10049 * Inserting Space:: How to insert the right amount of space
10051 * Inserting Accents:: How to insert accents and special characters.
10052 * Inserting Quotation Marks:: How to insert quotation marks.
10053 * Dots Bullets:: How to insert dots and bullets.
10054 * TeX and copyright:: How to insert the @TeX{} logo
10055 and the copyright symbol.
10056 * euro:: How to insert the Euro currency symbol.
10057 * pounds:: How to insert the pounds currency symbol.
10058 * textdegree:: How to insert the degrees symbol.
10059 * minus:: How to insert a minus sign.
10060 * geq leq:: How to insert greater/less-than-or-equal signs.
10061 * math:: How to format a mathematical expression.
10062 * Click Sequences:: Inserting GUI usage sequences.
10063 * Glyphs:: How to indicate results of evaluation,
10064 expansion of macros, errors, etc.
10068 @node Atsign Braces Comma
10069 @section Inserting @@ and @{@} and @comma{}
10070 @cindex Special characters, inserting
10071 @cindex Commands to insert special characters
10073 @samp{@@} and curly braces are special characters in Texinfo. To insert
10074 these characters so they appear in text, you must put an @samp{@@} in
10075 front of these characters to prevent Texinfo from misinterpreting
10078 The comma `,' is a special character only in one uncommon context:
10079 it separates arguments to commands that take multiple arguments.
10082 * Inserting an Atsign::
10083 * Inserting Braces::
10084 * Inserting a Comma::
10088 @node Inserting an Atsign
10089 @subsection Inserting `@@' with @code{@@@@}
10090 @findex @@ @r{(literal @samp{@@})}
10091 @cindex Inserting @@ @r{(literal @samp{@@})}
10093 @code{@@@@} stands for a single @samp{@@} in either printed or Info
10096 Do not put braces after an @code{@@@@} command.
10099 @node Inserting Braces
10100 @subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}}
10101 @cindex Braces, inserting
10102 @findex @{ @r{(literal @samp{@{})}
10103 @findex @} @r{(literal @samp{@}})}
10105 @code{@@@{} stands for a single @samp{@{} in either printed or Info
10108 @code{@@@}} stands for a single @samp{@}} in either printed or Info
10111 Do not put braces after either an @code{@@@{} or an @code{@@@}}
10115 @node Inserting a Comma
10116 @subsection Inserting `,' with @code{@@comma@{@}}
10117 @cindex Commas, inserting
10120 Ordinarily, a comma `,' is a normal character that can be simply typed
10121 in your input where you need it.
10123 However, Texinfo uses the comma as a special character in one uncommon
10124 context: some commands, such as @code{@@acronym} (@pxref{acronym}) and
10125 @code{@@xref} (@pxref{Cross References}), as well as user-defined
10126 macros (@pxref{Defining Macros}), can take more than one argument. In
10127 these cases, the comma character is used to separate arguments.
10129 Since a comma character would confuse Texinfo's parsing for these
10130 commands, you must use the command @samp{@@comma@{@}} instead if you want
10131 to pass an actual comma. Here are some examples:
10134 @@acronym@{ABC, A Bizarre @@comma@{@}@}
10135 @@xref@{Comma,, The @@comma@{@} symbol@}
10136 @@mymac@{One argument@@comma@{@} containing a comma@}
10139 Although @comma{} can be used nearly anywhere, there is no need for it
10140 anywhere except in this unusual case.
10143 @node Inserting Quote Characters
10144 @section Inserting Quote Characters
10146 @cindex Inserting quote characters
10147 @cindex Quote characters, inserting
10149 As explained in the early section on general Texinfo input conventions
10150 (@pxref{Conventions}), Texinfo source files use the ASCII character
10151 @code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'}
10152 (39 decimal) to produce a right quote ('). Doubling these input
10153 characters (@code{``} and @code{''}) produces double quotes (`` and
10154 ''). These are the conventions used by @TeX{}.
10156 This works all right for text. However, in examples of computer code,
10157 readers are especially likely to cut and paste the text
10158 verbatim---and, unfortunately, some document viewers will mangle these
10159 characters. (The free PDF reader @command{xpdf} works fine, but other
10160 PDF readers, both free and nonfree, have problems.)
10162 If this is a concern for your document, Texinfo provides two special
10163 settings via @code{@@set}:
10166 @item @@set txicodequoteundirected
10167 causes the output for the @code{'} character to be the undirected
10168 single quote, like this:
10169 @set txicodequoteundirected
10171 @clear txicodequoteundirected
10173 @item @@set txicodequotebacktick
10174 Cause the output for the @code{`} character to be the standalone grave
10176 @set txicodequotebacktick
10178 @clear txicodequotebacktick
10184 If you want these settings for only part of the document,
10185 @code{@@clear} will restore the normal behavior, as in
10186 @code{@@clear@tie{}txicodequoteundirected}.
10188 These settings affect @code{@@code}, @code{@@example}, and
10189 @code{@@verbatim}; they do not affect @code{@@samp}. (@xref{Useful
10193 @node Inserting Space
10194 @section Inserting Space
10196 @cindex Inserting space
10197 @cindex Spacing, inserting
10198 The following sections describe commands that control spacing of various
10199 kinds within and after sentences.
10202 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
10203 * Ending a Sentence:: Sometimes it does.
10204 * Multiple Spaces:: Inserting multiple spaces.
10205 * frenchspacing:: Specifying end-of-sentence spacing.
10206 * dmn:: How to format a dimension.
10210 @node Not Ending a Sentence
10211 @subsection Not Ending a Sentence
10213 @cindex Not ending a sentence
10214 @cindex Sentence non-ending punctuation
10215 @cindex Periods, inserting
10216 Depending on whether a period or exclamation point or question mark is
10217 inside or at the end of a sentence, less or more space is inserted after
10218 a period in a typeset manual. Since it is not always possible
10219 to determine when a period ends a sentence and when it is used
10220 in an abbreviation, special commands are needed in some circumstances.
10221 Usually, Texinfo can guess how to handle periods, so you do not need to
10222 use the special commands; you just enter a period as you would if you
10223 were using a typewriter, which means you put two spaces after the
10224 period, question mark, or exclamation mark that ends a sentence.
10226 @findex <colon> @r{(suppress end-of-sentence space)}
10227 Use the @code{@@:}@: command after a period, question mark,
10228 exclamation mark, or colon that should not be followed by extra space.
10229 For example, use @code{@@:}@: after periods that end abbreviations
10230 which are not at the ends of sentences.
10244 produces the following. If you look carefully at this printed output,
10245 you will see a little extraneous space after @samp{vs.}@: in the second
10255 @code{@@:} has no effect on the Info and HTML output. In Docbook and
10256 XML, the previous punctuation character (.?!:) is output as an entity
10257 instead of as the normal character: @samp{. ? !
10258 :}. This gives further processors a chance to notice and not
10259 add the usual extra space.
10261 Do not put braces after @code{@@:} (or any non-alphabetic command).
10264 @node Ending a Sentence
10265 @subsection Ending a Sentence
10267 @cindex Ending a Sentence
10268 @cindex Sentence ending punctuation
10270 @findex . @r{(end of sentence)}
10271 @findex ! @r{(end of sentence)}
10272 @findex ? @r{(end of sentence)}
10273 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
10274 exclamation point, and @code{@@?}@: instead of a question mark at the end
10275 of a sentence that ends with a capital letter. Otherwise, @TeX{}
10276 will think the letter is an abbreviation and will not insert the correct
10277 end-of-sentence spacing. Here is an example:
10280 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
10281 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
10289 produces the following. If you look carefully at this printed output,
10290 you will see a little more whitespace after the @samp{W} in the first
10295 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
10296 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
10299 In the Info file output, @code{@@.}@: is equivalent to a simple
10300 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
10302 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
10303 work well with the Emacs sentence motion commands (@pxref{Sentences,,,
10304 emacs, The GNU Emacs Manual}).
10306 Do not put braces after any of these commands.
10309 @node Multiple Spaces
10310 @subsection Multiple Spaces
10312 @cindex Multiple spaces
10313 @cindex Whitespace, inserting
10314 @cindex Space, inserting horizontal
10319 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
10320 and newline) into a single space. Info output, on the other hand,
10321 preserves whitespace as you type it, except for changing a newline into
10322 a space; this is why it is important to put two spaces at the end of
10323 sentences in Texinfo documents.
10325 Occasionally, you may want to actually insert several consecutive
10326 spaces, either for purposes of example (what your program does with
10327 multiple spaces as input), or merely for purposes of appearance in
10328 headings or lists. Texinfo supports three commands:
10329 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
10330 which insert a single space into the output. (Here,
10331 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
10332 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
10333 character and end-of-line, i.e., when @samp{@@} is the last character on
10349 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
10350 @code{@@multitable} (@pxref{Multi-column Tables}).
10352 Do not follow any of these commands with braces.
10354 To produce a non-breakable space, see @ref{tie, @code{@@tie}}.
10357 @node frenchspacing
10358 @subsection @code{@@frenchspacing} @var{val}: Control sentence spacing
10359 @findex frenchspacing
10360 @cindex French spacing
10361 @cindex Sentences, spacing after
10362 @cindex Space, after sentences
10364 In American typography, it is traditional and correct to put extra
10365 space at the end of a sentence, after a semi-colon, and so on. This
10366 is the default in Texinfo. In French typography (and many others),
10367 this extra space is wrong; all spaces are uniform.
10369 Therefore Texinfo provides the @code{@@frenchspacing} command to
10370 control the spacing after punctuation. It reads the rest of the line
10371 as its argument, which must be the single word @samp{on} or @samp{off}
10372 (always these words, regardless of the language) of the document.
10373 Here is an example:
10377 This is text. Two sentences. Three sentences. French spacing.
10379 @@frenchspacing off
10380 This is text. Two sentences. Three sentences. Non-French spacing.
10383 @noindent produces (there will be no difference in Info):
10386 This is text. Two sentences. Three sentences. French spacing.
10389 This is text. Two sentences. Three sentences. Non-French spacing.
10391 @code{@@frenchspacing} mainly affects the printed output, including
10392 the output after @code{@@.}, @code{@@!}, and @code{@@?} (@pxref{Ending
10395 In Info, usually space characters in the input are written unaltered
10396 to the output, and @code{@@frenchspacing} does not change this. It
10397 does change the one case where @command{makeinfo} outputs a space on
10398 its own: when a sentence ends at a newline in the source. Here's an
10406 @noindent produces in Info output, with @code{@@frenchspacing off}
10407 (the default), two spaces between the sentences:
10410 Some sentence. Next sentence.
10413 @noindent With @code{@@frenchspacing on}, @command{makeinfo} outputs
10414 only a single space:
10417 Some sentence. Next sentence.
10420 @code{@@frenchspacing} has no effect on the HTML or Docbook output;
10421 for XML, it outputs a transliteration of itself (@pxref{Output
10426 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
10427 @cindex Thin space between number, dimension
10428 @cindex Dimension formatting
10429 @cindex Format a dimension
10432 At times, you may want to write @samp{12@dmn{pt}} or
10433 @samp{8.5@dmn{in}} with little or no space between the number and the
10434 abbreviation for the dimension. You can use the @code{@@dmn} command
10435 to do this. On seeing the command, @TeX{} inserts just enough space
10436 for proper typesetting; the Info formatting commands insert no space
10437 at all, since the Info file does not require it.
10439 To use the @code{@@dmn} command, write the number and then follow it
10440 immediately, with no intervening space, by @code{@@dmn}, and then by
10441 the dimension within braces. For example,
10444 A4 paper is 8.27@@dmn@{in@} wide.
10451 A4 paper is 8.27@dmn{in} wide.
10454 Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
10455 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
10456 In these cases, however, the formatters may insert a line break between
10457 the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
10458 you write a period after an abbreviation within a sentence, you should
10459 write @samp{@@:} after the period to prevent @TeX{} from inserting extra
10460 whitespace, as shown here. @xref{Not Ending a Sentence}.
10463 @node Inserting Accents
10464 @section Inserting Accents
10466 @cindex Inserting accents
10467 @cindex Accents, inserting
10468 @cindex Floating accents, inserting
10470 Here is a table with the commands Texinfo provides for inserting
10471 floating accents. They all need an argument, the character to accent,
10472 which can either be given in braces as usual (@code{@@'@{e@}}), or, as
10473 a special case, the braces can be omitted, in which case the argument
10474 is the next character (@code{@@'e}). This is to make the source as
10475 convenient as possible to type and read, since accented characters are
10476 very common in some languages.
10478 If the command is alphabetic, such as @code{@@dotaccent}, then there
10479 must be a space between the command name and argument if braces are
10480 not used. If the command is non-alphabetic, such as @code{@@'}, then
10481 there must @emph{not} be a space; the argument is the very next
10484 Exception: the argument to @code{@@tieaccent} must be enclosed in
10485 braces (since it is two characters instead of one).
10487 @findex documentencoding
10488 To get the true accented characters output in Info, not just the ASCII
10489 transliterations, it is necessary to specify @code{@@documentencoding}
10490 with an encoding which supports the required characters
10491 (@pxref{documentencoding,,@code{@@documentencoding}}). In this case,
10492 you can also use non-ASCII (e.g., pre-accented) characters in the
10495 @findex " @r{(umlaut accent)}
10496 @cindex Umlaut accent
10497 @findex ' @r{(umlaut accent)}
10498 @cindex Acute accent
10499 @findex = @r{(macron accent)}
10500 @cindex Macron accent
10501 @findex ^ @r{(circumflex accent)}
10502 @cindex Circumflex accent
10503 @findex ` @r{(grave accent)}
10504 @cindex Grave accent
10505 @findex ~ @r{(tilde accent)}
10506 @cindex Tilde accent
10507 @findex , @r{(cedilla accent)}
10508 @cindex Cedilla accent
10511 @findex H @r{(Hungarian umlaut accent)}
10512 @cindex Hungarian umlaut accent
10514 @cindex Ring accent
10516 @cindex Tie-after accent
10517 @findex u @r{(breve accent)}
10518 @cindex Breve accent
10520 @cindex Underbar accent
10522 @cindex Underdot accent
10523 @findex v @r{(check accent)}
10524 @cindex Hacek accent
10525 @cindex Check accent
10526 @cindex Caron accent
10527 @multitable {@t{@@questiondown@{@}}} {Output} {hacek/check/caron accent}
10528 @headitem Command @tab Output @tab What
10529 @item @t{@@"o} @tab @"o @tab umlaut accent
10530 @item @t{@@'o} @tab @'o @tab acute accent
10531 @item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
10532 @item @t{@@=o} @tab @=o @tab macron/overbar accent
10533 @item @t{@@^o} @tab @^o @tab circumflex accent
10534 @item @t{@@`o} @tab @`o @tab grave accent
10535 @item @t{@@~o} @tab @~o @tab tilde accent
10536 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
10537 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
10538 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
10539 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
10540 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent
10541 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
10542 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
10543 @item @t{@@v@{o@}} @tab @v{o} @tab hacek/check/caron accent
10546 This table lists the Texinfo commands for inserting other characters
10547 commonly used in languages other than English.
10549 @findex questiondown
10550 @cindex @questiondown{}
10552 @cindex @exclamdown{}
10562 @cindex @dotless{i} (dotless i)
10563 @cindex @dotless{j} (dotless j)
10564 @cindex Dotless i, j
10577 @cindex Romance ordinals
10578 @cindex Ordinals, Romance
10579 @cindex Feminine ordinal
10582 @cindex Masculine ordinal
10590 @multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S}
10591 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
10592 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
10593 @item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle
10594 @item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures
10595 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
10596 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
10597 @item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l
10598 @item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash
10599 @item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures
10600 @item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals
10601 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
10605 @node Inserting Quotation Marks
10606 @section Inserting Quotation Marks
10607 @cindex Inserting quotation marks
10608 @cindex Quotation marks, inserting
10610 @cindex Quotation characters (`'), in source
10611 Use doubled single-quote characters to begin and end quotations:
10612 @w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to
10613 left- and right-hand doubled quotation marks,
10614 @c this comes out as "like this" in Info, which is just confusing.
10618 and Info converts doubled single-quote characters to ASCII
10619 double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
10621 You may occasionally need to produce two consecutive single quotes;
10622 for example, in documenting a computer language such as Maxima where
10623 @t{'@w{}'} is a valid command. You can do this with the input
10624 @t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into
10625 the double-quote characters.
10627 @cindex Unicode quotation characters
10628 @cindex Grave accent, vs. left quote
10629 The left quote character (@t{`}, ASCII code 96) used in Texinfo is a
10630 grave accent in ANSI and ISO character set standards. We use it as a
10631 quote character because that is how @TeX{} is set up, by default.
10633 Texinfo supports several other quotation marks used in languages other
10634 than English. Below is a table with the commands Texinfo provides for
10635 inserting quotation marks.
10637 @findex documentencoding
10639 @cindex ISO 8859-15
10643 In order to get the symbols for the quotation marks in encoded Info
10644 output, it is necessary to specify @code{@@documentencoding UTF-8}.
10645 (@xref{documentencoding,,@code{@@documentencoding}}.) Double
10646 guillemets are also present in ISO 8859-1 (aka Latin@tie{}1) and ISO
10647 8859-15 (aka Latin@tie{}9).
10649 @cindex European Computer Modern fonts
10651 The standard @TeX{} fonts support the usual quotation marks used in
10652 English (the ones produced with single and doubled ASCII
10653 single-quotes). For the other quotation marks, @TeX{} uses European
10654 Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
10655 These fonts are freely available, of course; you can download them
10656 from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other
10659 @cindex CM-Super fonts
10660 The free EC fonts are bitmap fonts created with Metafont. Especially
10661 for on-line viewing, Type@tie{}1 (vector) versions of the fonts are
10662 preferable; these are available in the CM-Super font package
10663 (@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}).
10665 Both distributions include installation instructions.
10667 @cindex Single quotation marks
10668 @cindex Double quotation marks
10669 @cindex Left quotation marks
10670 @cindex Right quotation marks
10671 @findex quotedblleft
10675 @findex quotedblright
10679 @cindex Double low-9 quotation mark
10680 @cindex Single low-9 quotation mark
10681 @findex quotedblbase
10682 @cindex @quotedblbase{} (double low-9 quotation mark)
10683 @findex quotesinglbase
10684 @cindex @quotesinglbase{} (single low-9 quotation mark)
10685 @cindex Angle quotation marks
10688 @cindex French quotation marks
10689 @cindex Quotation marks, French
10690 @cindex German quotation marks
10691 @cindex Quotation marks, German
10692 @cindex Double guillemets
10693 @cindex Single guillemets
10694 @cindex Double angle quotation marks
10695 @cindex Single angle quotation marks
10696 @cindex Left-pointing angle quotation marks
10697 @cindex Right-pointing angle quotation marks
10698 @cindex Double left-pointing angle quotation mark
10699 @cindex Double right-pointing angle quotation mark
10700 @cindex Single left-pointing angle quotation mark
10701 @cindex Single right-pointing angle quotation mark
10702 @findex guillemetleft
10703 @findex guillemotleft
10704 @cindex @guillemetleft{}
10705 @findex guillemetright
10706 @findex guillemotright
10707 @cindex @guillemetright{}
10708 @findex guilsinglleft
10709 @cindex @guilsinglleft{}
10710 @findex guilsinglright
10711 @cindex @guilsinglright{}
10712 @multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation mark (U+00BB)}
10713 @headitem Command @tab Glyph @tab Unicode name (point)
10714 @item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C)
10715 @item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D)
10716 @item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018)
10717 @item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019)
10718 @item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E)
10719 @item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A)
10720 @item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB)
10721 @item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB)
10722 @item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039)
10723 @item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A)
10726 For the double angle quotation marks, Adobe and @LaTeX{} glyph names
10727 are also supported: @code{@@guillemotleft} and
10728 @code{@@guillemotright}. These names are actually incorrect; a
10729 ``guillemot'' is a bird species (a type of auk).
10731 Traditions for quotation mark usage vary to a great extent between
10732 languages (@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}).
10733 Texinfo does not provide commands for typesetting quotation marks
10734 according to the numerous traditions. Therefore, you have to choose
10735 the commands appropriate for the language of your manual. Sometimes
10736 aliases (@pxref{alias,,@code{@@alias}}) can simplify the usage and
10737 make the source code more readable. For example, in German,
10738 @code{@@quotedblbase} is used for the left double quote, and the right
10739 double quote is actually @code{@@quotedblleft}, which is
10740 counter-intuitive. Thus, in this case the following aliases would be
10744 @@alias lgqq = quotedblbase
10745 @@alias rgqq = quotedblleft
10750 @section Inserting Ellipsis and Bullets
10751 @cindex Dots, inserting
10752 @cindex Bullets, inserting
10753 @cindex Ellipsis, inserting
10754 @cindex Inserting ellipsis
10755 @cindex Inserting dots
10756 @cindex Special typesetting commands
10757 @cindex Typesetting commands for dots, etc.
10759 An @dfn{ellipsis} (a line of dots) is not typeset as a string of
10760 periods, so a special command is used for ellipsis in Texinfo. The
10761 @code{@@bullet} command is special, too. Each of these commands is
10762 followed by a pair of braces, @samp{@{@}}, without any whitespace
10763 between the name of the command and the braces. (You need to use braces
10764 with these commands because you can use them next to other text; without
10765 the braces, the formatters would be confused. @xref{Command Syntax, ,
10766 @@-Command Syntax}, for further information.)@refill
10769 * dots:: How to insert dots @dots{}
10770 * bullet:: How to insert a bullet.
10775 @subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
10778 @cindex Inserting dots
10779 @cindex Dots, inserting
10781 Use the @code{@@dots@{@}} command to generate an ellipsis, which is
10782 three dots in a row, appropriately spaced @dots{} like so. Do
10783 not simply write three periods in the input file; that would work for
10784 the Info file output, but would produce the wrong amount of space
10785 between the periods in the printed manual.
10787 Similarly, the @code{@@enddots@{@}} command generates an
10788 end-of-sentence ellipsis, which has different spacing afterwards,
10789 @enddots{} Look closely to see the difference.
10792 Here is an ellipsis: @dots{}
10793 Here are three periods in a row: ...
10795 In printed output, the three periods in a row are much closer together than
10796 the dots in the ellipsis.
10801 @subsection @code{@@bullet}@{@} (@bullet{})
10804 Use the @code{@@bullet@{@}} command to generate a large round dot, or
10805 the closest possible thing to one. In Info, an asterisk is used.@refill
10807 Here is a bullet: @bullet{}
10809 When you use @code{@@bullet} in @code{@@itemize}, you do not need to
10810 type the braces, because @code{@@itemize} supplies them.
10811 (@xref{itemize, , @code{@@itemize}}.)@refill
10814 @node TeX and copyright
10815 @section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{}
10817 The logo `@TeX{}' is typeset in a special fashion and it needs an
10818 @@-command. The copyright and registered symbols, `@copyright{}' and
10819 `@registeredsymbol{}', is also special. Each of these commands is
10820 followed by a pair of braces, @samp{@{@}}, without any whitespace
10821 between the name of the command and the braces.
10824 * tex:: The @TeX{} logos.
10825 * copyright symbol:: The copyright symbol (c in a circle).
10826 * registered symbol:: The registered symbol (R in a circle).
10831 @subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{})
10834 @cindex Logos, @TeX{}
10835 @cindex @TeX{} logo
10836 @cindex @LaTeX{} logo
10838 Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
10839 manual, this is a special logo that is different from three ordinary
10840 letters. In Info, it just looks like @samp{TeX}.
10842 Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}',
10843 which is even more special in printed manuals (and different from the
10844 incorrect @code{La@@TeX@{@}}. In Info, the result is just
10845 @samp{LaTeX}. (@LaTeX{} is another macro package built on top of
10846 @TeX{}, very loosely analogous to Texinfo in that it emphasizes
10847 logical structure, but much (much) larger.)
10849 The spelling of these commands are unusual among Texinfo commands in
10850 that they use both uppercase and lowercase letters.
10853 @node copyright symbol
10854 @subsection @code{@@copyright@{@}} (@copyright{})
10856 @cindex Copyright symbol
10858 Use the @code{@@copyright@{@}} command to generate the copyright
10859 symbol, `@copyright{}'. Where possible, this is a @samp{c}
10860 inside a circle; in Info, this is @samp{(C)}.
10863 @node registered symbol
10864 @subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{})
10865 @findex registeredsymbol
10866 @cindex Registered symbol
10868 Use the @code{@@registeredsymbol@{@}} command to generate the
10869 registered symbol, `@registeredsymbol{}'. Where possible, this is an
10870 @samp{R} inside a circle; in Info, this is @samp{(R)}.
10874 @section @code{@@euro}@{@} (@euro{}): Euro Currency Symbol
10876 @cindex Euro symbol
10878 Use the @code{@@euro@{@}} command to generate `@euro{}'. Where
10879 possible, this is the symbol for the Euro currency, invented as part
10880 of the European economic unification. In plain Info, it is the word
10881 @samp{Euro }. A trailing space is included in the text
10882 transliteration since typically no space is desired after the symbol,
10883 so it would be inappropriate to have a space in the source document.
10885 Texinfo cannot magically synthesize support for the Euro symbol where
10886 the underlying system (fonts, software, whatever) does not support
10887 it. Therefore, in many cases it is preferable to use the word
10888 ``Euro''. (In banking circles, the abbreviation for the Euro is EUR.)
10890 @cindex ISO 8859-15
10892 In order to get the Euro symbol in encoded Info output, for example,
10893 it is necessary to specify @code{@@documentencoding ISO-8859-15}.
10894 (@xref{documentencoding,,@code{@@documentencoding}}.) The Euro symbol
10895 is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more
10896 widely-used and supported ISO 8859-1 (Latin@tie{}1).
10900 The Euro symbol does not exist in the standard @TeX{} fonts (which
10901 were designed before the Euro was legislated into existence).
10902 Therefore, @TeX{} uses an additional font, named @code{feymr10} (along
10903 with other variables). It is freely available, of course; you can
10904 download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym},
10905 among other places. The distribution includes installation
10910 @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
10912 @cindex Pounds symbol
10914 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where
10915 possible, this is the symbol for the currency pounds sterling. In
10916 Info, it is a @samp{#}.
10920 @section @code{@@textdegree}@{@} (@textdegree{}): Degrees Symbol
10922 @cindex Degree symbol
10924 Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'.
10925 Where possible, this is the normal symbol for degrees. In plain text
10926 and Info output, it is an @samp{o}.
10930 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
10934 @cindex Em dash, compared to minus sign
10935 @cindex Hyphen, compared to minus
10936 Use the @code{@@minus@{@}} command to generate a minus sign. In a
10937 fixed-width font, this is a single hyphen, but in a proportional font,
10938 the symbol is the customary length for a minus sign---a little longer
10939 than a hyphen, shorter than an em-dash:
10942 @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
10944 `-' is a hyphen generated with the character @samp{-},
10946 `---' is an em-dash for text.
10950 In the fixed-width font used by Info, @code{@@minus@{@}} is the same
10953 You should not use @code{@@minus@{@}} inside @code{@@code} or
10954 @code{@@example} because the width distinction is not made in the
10955 fixed-width font they use.
10957 When you use @code{@@minus} to specify the mark beginning each entry in
10958 an itemized list, you do not need to type the braces
10959 (@pxref{itemize, , @code{@@itemize}}).
10963 @section @code{@@geq@{@}} (@geq{}) and @code{@@leq@{@}} (@leq{}): Inserting relations
10967 Use the @code{@@geq@{@}} and @code{@@geq@{@}} commands to generate
10968 greater-than-or-equal and less-than-equal-signs, `@geq{}' and
10969 `@leq{}'. In plain text and Info output, these are the ASCII
10970 sequences @samp{>=} and @samp{<=}. The
10974 @section @code{@@math}: Inserting Mathematical Expressions
10976 @cindex Mathematical expressions
10977 @cindex Formulas, mathematical
10979 You can write a short mathematical expression with the @code{@@math}
10980 command. Write the mathematical expression between braces, like this:
10983 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
10987 @noindent This produces the following in @TeX{}:
10990 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
10993 @noindent and the following in other formats:
10996 @noindent This produces the following in Info and HTML:
11000 (a + b)(a + b) = a^2 + 2ab + b^2
11003 The @code{@@math} command has no special effect on the Info and HTML
11004 output. @command{makeinfo} expands any @code{@@}-commands as usual,
11005 but it does not try to produce good mathematical formatting in any
11008 However, as far as the @TeX{} output is concerned, plain @TeX{}
11009 mathematical commands are allowed in @code{@@math}, starting with
11010 @samp{\}, and the plain @TeX{} math characters like @samp{^} and
11011 @samp{_} are also recognized. In essence, @code{@@math} drops you
11012 into plain @TeX{} math mode.
11014 This allows you to conveniently write superscripts and subscripts (as
11015 in the above example), and also to use all the plain @TeX{} math
11016 control sequences for symbols, functions, and so on, and thus get
11017 proper formatting in the @TeX{} output, at least.
11019 It's best to use @samp{\} instead of @samp{@@} for any such
11020 mathematical commands; otherwise, @command{makeinfo} will complain.
11021 On the other hand, input with matching (but unescaped) braces, such as
11022 @samp{k_@{75@}}, is allowed inside @code{@@math}, although
11023 @command{makeinfo} would complain about the bare braces in regular
11029 @@math@{\sin 2\pi \equiv \cos 3\pi@}
11033 @noindent which looks like this in @TeX{}:
11035 @math{\sin 2\pi \equiv \cos 3\pi}
11040 @noindent which looks like the input in Info and HTML:
11042 \sin 2\pi \equiv \cos 3\pi
11045 @findex \ @r{(literal \ in @code{@@math})}
11046 Since @samp{\} is an escape character inside @code{@@math}, you can use
11047 @code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
11048 but you'd get the literal @samp{\\} in Info). @code{@@\} is not
11049 defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
11052 @cindex Displayed equations
11053 @cindex Equations, displayed
11054 For displayed equations, you must at present use @TeX{} directly
11055 (@pxref{Raw Formatter Commands}).
11058 @node Click Sequences
11059 @section Click Sequences
11060 @cindex Click sequences
11061 @cindex Sequence of clicks
11062 @cindex GUI click sequence
11064 @findex clicksequence
11065 When documenting graphical interfaces, it is necessary to describe
11066 sequences such as `Click on @samp{File}, then choose @samp{Open}, then
11067 @dots{}'. Texinfo offers commands @code{@@clicksequence} and
11068 @code{click} to represent this, typically used like this:
11071 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
11078 @dots{} @clicksequence{File @click{} Open} @dots{}
11083 The @code{@@click} command produces a simple right arrow (@samp{->} in
11084 Info) by default; this glyph is also available independently via the
11085 command @code{@@arrow@{@}}.
11088 You can change the glyph produced by @code{@@click} with the command
11089 @code{@@clickstyle}, which takes a command name as its single argument
11090 on the rest of the line, much like @code{@@itemize} and friends
11091 (@pxref{itemize,,@code{@@itemize}}). The command should produce a
11092 glyph, and the usual empty braces @samp{@{@}} are omitted. Here's an
11096 @@clickstyle @@result
11097 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
11104 @clickstyle @result
11105 @dots{} @clicksequence{File @click{} Open} @dots{}
11110 @section Glyphs for Examples
11112 @cindex Examples, glyphs for
11114 In Texinfo, code is often illustrated in examples that are delimited
11115 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
11116 @code{@@end lisp}. In such examples, you can indicate the results of
11117 evaluation or an expansion using @samp{@result{}} or
11118 @samp{@expansion{}}. Likewise, there are commands to insert glyphs
11120 printed output, error messages, equivalence of expressions, and the
11123 The glyph-insertion commands do not need to be used within an example, but
11124 most often they are. Every glyph-insertion command is followed by a pair of
11125 left- and right-hand braces.@refill
11129 * result:: How to show the result of expression.
11130 * expansion:: How to indicate an expansion.
11131 * Print Glyph:: How to indicate printed output.
11132 * Error Glyph:: How to indicate an error message.
11133 * Equivalence:: How to indicate equivalence.
11134 * Point Glyph:: How to indicate the location of point.
11138 @node Glyphs Summary
11139 @subsection Glyphs Summary
11141 Here are the different glyph commands:@refill
11145 @code{@@result@{@}} points to the result of an expression.@refill
11148 @code{@@expansion@{@}} shows the results of a macro expansion.@refill
11151 @code{@@print@{@}} indicates printed output.@refill
11154 @code{@@error@{@}} indicates that the following text is an error
11158 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
11161 @code{@@point@{@}} shows the location of point.@refill
11175 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
11176 @cindex Result of an expression
11177 @cindex Indicating evaluation
11178 @cindex Evaluation glyph
11179 @cindex Value of an expression, indicating
11182 Use the @code{@@result@{@}} command to indicate the result of
11183 evaluating an expression.@refill
11186 The @code{@@result@{@}} command is displayed as @samp{@result{}} in
11187 the printed output and as @samp{=>} in other formats.
11190 The @code{@@result@{@}} command is displayed as @samp{@result{}} in
11191 Info and HTML and as a true double stemmed arrow in the printed output.
11194 Thus, the following,
11202 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
11206 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
11207 @cindex Expansion, indicating
11208 @cindex Macro expansion, indicating
11211 When an expression is a macro call, it expands into a new expression.
11212 You can indicate the result of the expansion with the
11213 @code{@@expansion@{@}} command.@refill
11216 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
11217 in the printed output and as @samp{==>} in other formats.
11220 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
11221 in Info and HTML, and as a long arrow with a flat base in the printed
11226 For example, the following
11232 @@expansion@{@} (car (cdr (cdr '(a b c))))
11244 @expansion{} (car (cdr (cdr '(a b c))))
11250 which may be read as:
11253 @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
11254 the result of evaluating the expression is @code{c}.
11258 Often, as in this case, an example looks better if the
11259 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented.
11263 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
11264 @cindex Printed output, indicating
11267 Sometimes an expression will print output during its execution. You
11268 can indicate the printed output with the @code{@@print@{@}} command.@refill
11271 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
11272 HTML and as @samp{@print{}} in the printed output.
11275 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
11276 and HTML and (similarly) as a horizontal dash butting against a
11277 vertical bar in the printed output.
11280 In the following example, the printed text is indicated with
11281 @samp{@print{}}, and the value of the expression follows on the
11286 (progn (print 'foo) (print 'bar))
11294 In a Texinfo source file, this example is written as follows:
11299 (progn (print 'foo) (print 'bar))
11309 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
11310 @cindex Error message, indicating
11313 A piece of code may cause an error when you evaluate it. You can
11314 designate the error message with the @code{@@error@{@}} command.@refill
11317 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
11318 and HTML and as @samp{@error{}} in the printed output.
11321 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
11322 and HTML and as the word `error' in a box in the printed output.
11331 @@error@{@} Wrong type argument: integer-or-marker-p, x
11340 @error{} Wrong type argument: integer-or-marker-p, x
11344 This indicates that the following error message is printed
11345 when you evaluate the expression:
11348 Wrong type argument: integer-or-marker-p, x
11351 @samp{@error{}} itself is not part of the error message.
11355 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
11356 @cindex Equivalence, indicating
11359 Sometimes two expressions produce identical results. You can indicate the
11360 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
11363 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
11364 HTML and as @samp{@equiv{}} in the printed output.
11367 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
11368 and HTML and as a standard mathematical equivalence sign (three
11369 parallel horizontal lines) in the printed output.
11376 (make-sparse-keymap) @@equiv@{@} (list 'keymap)
11384 (make-sparse-keymap) @equiv{} (list 'keymap)
11388 This indicates that evaluating @code{(make-sparse-keymap)} produces
11389 identical results to evaluating @code{(list 'keymap)}.
11393 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
11394 @cindex Point, indicating in a buffer
11397 Sometimes you need to show an example of text in an Emacs buffer. In
11398 such examples, the convention is to include the entire contents of the
11399 buffer in question between two lines of dashes containing the buffer
11402 You can use the @samp{@@point@{@}} command to show the location of point
11403 in the text in the buffer. (The symbol for point, of course, is not
11404 part of the text in the buffer; it indicates the place @emph{between}
11405 two characters where point is located.)@refill
11408 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
11409 HTML and as @samp{@point{}} in the printed output.
11412 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
11413 and HTML and as a small five pointed star in the printed
11417 The following example shows the contents of buffer @file{foo} before
11418 and after evaluating a Lisp command to insert the word @code{changed}.@refill
11422 ---------- Buffer: foo ----------
11423 This is the @point{}contents of foo.
11424 ---------- Buffer: foo ----------
11431 (insert "changed ")
11433 ---------- Buffer: foo ----------
11434 This is the changed @point{}contents of foo.
11435 ---------- Buffer: foo ----------
11440 In a Texinfo source file, the example is written like this:@refill
11444 ---------- Buffer: foo ----------
11445 This is the @@point@{@}contents of foo.
11446 ---------- Buffer: foo ----------
11448 (insert "changed ")
11450 ---------- Buffer: foo ----------
11451 This is the changed @@point@{@}contents of foo.
11452 ---------- Buffer: foo ----------
11458 @chapter Forcing and Preventing Breaks
11459 @cindex Forcing line and page breaks
11460 @cindex Making line and page breaks
11461 @cindex Preventing line and page breaks
11463 @cindex Line breaks
11464 Usually, a Texinfo file is processed both by @TeX{} and by one of the
11465 Info formatting commands. Line, paragraph, or page breaks sometimes
11466 occur in the `wrong' place in one or other form of output. You must
11467 ensure that text looks right both in the printed manual and in the
11470 @cindex White space, excessive
11471 @cindex Page breaks
11472 For example, in a printed manual, page breaks may occur awkwardly in
11473 the middle of an example; to prevent this, you can hold text together
11474 using a grouping command that keeps the text from being split across
11475 two pages. Conversely, you may want to force a page break where none
11476 would occur normally. Fortunately, problems like these do not often
11477 arise. When they do, use the break, break prevention, or pagination
11481 * Break Commands:: Summary of break-related commands.
11482 * Line Breaks:: Forcing line breaks.
11483 * - and hyphenation:: Helping @TeX{} with hyphenation points.
11484 * allowcodebreaks:: Controlling line breaks within @@code text.
11485 * w:: Preventing unwanted line breaks in text.
11486 * tie:: Inserting an unbreakable but varying space.
11487 * sp:: Inserting blank lines.
11488 * page:: Forcing the start of a new page.
11489 * group:: Preventing unwanted page breaks.
11490 * need:: Another way to prevent unwanted page breaks.
11494 @node Break Commands
11495 @section Break Commands
11497 The break commands create or allow line and paragraph breaks:
11501 Force a line break.
11504 Skip @var{n} blank lines.
11507 Insert a discretionary hyphen.
11509 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
11510 Define hyphen points in @var{hy-phen-a-ted words}.
11513 These commands hold text together on a single line:
11516 @item @@w@{@var{text}@}
11517 Prevent @var{text} from being split and hyphenated across two lines.
11519 Insert a normal interword space at which a line break may not occur.
11525 The pagination commands apply only to printed output, since Info
11526 files do not have pages.
11530 Start a new page in the printed manual.
11533 Hold text together that must appear on one printed page.
11535 @item @@need @var{mils}
11536 Start a new printed page if not enough space on this one.
11541 @section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks
11542 @findex * @r{(force line break)}
11543 @findex / @r{(allow line break)}
11544 @cindex Line breaks
11545 @cindex Breaks in a line
11546 @cindex Force line break
11547 @cindex Allow line break
11549 The @code{@@*} command forces a line break in both the printed manual and
11550 in Info. The @code{@@/} command allows a line break (printed manual only).
11552 Here is an example with @code{@@*}:
11555 This line @@* is broken @@*in two places.
11568 The @code{@@/} command can be useful within a url
11569 (@pxref{uref,,@code{@@uref}}), which tend to be long and are otherwise
11570 unbreakable. For example:
11573 The official Texinfo home page is on the GNU web site:
11574 @@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}.
11580 The official Texinfo home page is on the GNU web site:
11581 @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}.
11584 @noindent Without the @code{@@/} commands, @TeX{} would have nowhere to
11585 break the line. @code{@@/} has no effect in the online output.
11588 @node - and hyphenation
11589 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate
11591 @findex - @r{(discretionary hyphen)}
11592 @findex hyphenation
11593 @cindex Hyphenation, helping @TeX{} do
11594 @cindex Fine-tuning, and hyphenation
11596 Although @TeX{}'s hyphenation algorithm is generally pretty good, it
11597 does miss useful hyphenation points from time to time. (Or, far more
11598 rarely, insert an incorrect hyphenation.) So, for documents with an
11599 unusual vocabulary or when fine-tuning for a printed edition, you may
11600 wish to help @TeX{} out. Texinfo supports two commands for this:
11604 Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
11605 not have to) hyphenate. This is especially useful when you notice an
11606 overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
11607 hboxes}). @TeX{} will not insert any hyphenation points itself into a
11608 word containing @code{@@-}.
11610 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
11611 Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
11612 put a @samp{-} at each hyphenation point. For example:
11614 @@hyphenation@{man-u-script man-u-scripts@}
11616 @noindent @TeX{} only uses the specified hyphenation points when the
11617 words match exactly, so give all necessary variants, such as plurals.
11620 Info, HTML, and other non-@TeX{} output is not hyphenated, so none of
11621 these commands have any effect there.
11624 @node allowcodebreaks
11625 @section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code}
11627 @findex allowcodebreaks
11628 @cindex Breaks, within @code{@@code}
11629 @cindex -, breakpoint within @code{@@code}
11630 @cindex Hyphen, breakpoint within @code{@@code}
11631 @cindex Dash, breakpoint within @code{@@code}
11632 @cindex _, breakpoint within @code{@@code}
11633 @cindex Underscore, breakpoint within @code{@@code}
11635 Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
11636 @samp{_} characters within @code{@@code} and related commands
11637 (@pxref{code,,@code{@@code}}), more or less as if they were ``empty''
11638 hyphenation points.
11640 This is necessary as many manuals, especially for Lisp-family
11641 languages, must document very long identifiers. On the other hand,
11642 other manuals don't have this problems, and you may not wish to allow
11643 a line break at the underscore in, for example, @code{SIZE_MAX}, or
11644 even worse, after any of the four underscores in @code{__typeof__}.
11646 So Texinfo provides this command:
11649 @@allowcodebreaks false
11652 @noindent to prevent @TeX{} from breaking at @samp{-} or @samp{_} within
11653 @code{@@code}. You can go back to allowing such breaks with
11654 @code{@@allowcodebreaks true}. Write these commands on lines by
11657 These commands can be given anywhere in the document. For example,
11658 you may have just one problematic paragraph where you need to turn off
11659 the breaks, but want them in general, or vice versa.
11661 This command has no effect in Info, HTML, and other non-@TeX{} output.
11665 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
11666 @findex w @r{(prevent line break)}
11667 @cindex Line breaks, preventing
11669 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
11670 within @var{text}, for both @TeX{} and @command{makeinfo}.
11672 @cindex Non-breakable space, fixed
11673 @cindex Unbreakable space, fixed
11674 Thus, you can use @code{@@w} to produce a non-breakable space, fixed at
11675 the width of a normal interword space:
11678 @@w@{ @} @@w@{ @} @@w@{ @} indentation.
11681 @noindent produces:
11684 @w{ } @w{ } @w{ } indentation.
11687 The space from @code{@@w@{@w{ }@}}, as well as being non-breakable,
11688 also will not stretch or shrink. Sometimes that is what you want, for
11689 instance if you're doing manual indenting. However, usually you want
11690 a normal interword space that does stretch and shrink (in the printed
11691 output); see the @code{@@tie} command in the next section.
11693 @cindex Hyphenation, preventing
11694 You can also use the @code{@@w} command to prevent @TeX{} from
11695 automatically hyphenating a long name or phrase that happens to fall
11696 near the end of a line. @command{makeinfo} does not ever hyphenate
11699 @cindex Keyword expansion, preventing
11700 @cindex Version control keywords, preventing expansion of
11701 @cindex $Id expansion, preventing
11702 You can also use @code{@@w} to avoid unwanted keyword expansion in
11703 source control systems. For example, to literally write @t{@w{$}Id$}
11704 in your document, use @code{@@w@{$@}Id$}.
11708 @section @code{@@tie@{@}}: Inserting an Unbreakable Space
11709 @findex tie @r{(unbreakable interword space)}
11711 @cindex Non-breakable space, variable
11712 @cindex Unbreakable space, variable
11714 The @code{@@tie@{@}} command produces a normal interword space at which
11715 a line break may not occur. Always write it with following (empty)
11716 braces, as usual for commands used within a paragraph. Here's an
11720 @@TeX@{@} was written by Donald E.@@tie@{@}Knuth.
11723 @noindent produces:
11726 @TeX{} was written by Donald E.@tie{}Knuth.
11729 There are two important differences between @code{@@tie@{@}} and
11730 @code{@@w@{@w{ }@}}:
11734 The space produced by @code{@@tie@{@}} will stretch and shrink slightly
11735 along with the normal interword spaces in the paragraph; the space
11736 produced by @code{@@w@{@w{ }@}} will not vary.
11739 @code{@@tie@{@}} allows hyphenation of the surrounding words, while
11740 @code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical
11741 reasons, namely that it produces an @samp{\hbox}).
11747 @section @code{@@sp} @var{n}: Insert Blank Lines
11748 @findex sp @r{(line spacing)}
11749 @cindex Space, inserting vertical
11750 @cindex Blank lines
11751 @cindex Line spacing
11753 A line beginning with and containing only @code{@@sp @var{n}}
11754 generates @var{n} blank lines of space in both the printed manual and
11755 the Info file. @code{@@sp} also forces a paragraph break. For
11763 generates two blank lines.
11765 The @code{@@sp} command is most often used in the title page.@refill
11768 @c node br, page, sp, Breaks
11769 @comment node-name, next, previous, up
11770 @c section @code{@@br}: Generate Paragraph Breaks
11771 @findex br @r{(paragraph breaks)}
11772 @cindex Paragraph breaks
11773 @cindex Breaks in a paragraph
11775 The @code{@@br} command forces a paragraph break. It inserts a blank
11776 line. You can use the command within or at the end of a line. If
11777 used within a line, the @code{@@br@{@}} command must be followed by
11778 left and right braces (as shown here) to mark the end of the
11786 This line @@br@{@}contains and is ended by paragraph breaks@@br
11787 and is followed by another line.
11798 contains and is ended by paragraph breaks
11800 and is followed by another line.
11804 The @code{@@br} command is seldom used.
11809 @section @code{@@page}: Start a New Page
11810 @cindex Page breaks
11813 A line containing only @code{@@page} starts a new page in a printed
11814 manual. The command has no effect on Info files since they are not
11815 paginated. An @code{@@page} command is often used in the @code{@@titlepage}
11816 section of a Texinfo file to start the copyright page.
11820 @comment node-name, next, previous, up
11821 @section @code{@@group}: Prevent Page Breaks
11822 @cindex Group (hold text together vertically)
11823 @cindex Holding text together vertically
11824 @cindex Vertically holding text together
11827 The @code{@@group} command (on a line by itself) is used inside an
11828 @code{@@example} or similar construct to begin an unsplittable vertical
11829 group, which will appear entirely on one page in the printed output.
11830 The group is terminated by a line containing only @code{@@end group}.
11831 These two lines produce no output of their own, and in the Info file
11832 output they have no effect at all.@refill
11834 @c Once said that these environments
11835 @c turn off vertical spacing between ``paragraphs''.
11836 @c Also, quotation used to work, but doesn't in texinfo-2.72
11837 Although @code{@@group} would make sense conceptually in a wide
11838 variety of contexts, its current implementation works reliably only
11839 within @code{@@example} and variants, and within @code{@@display},
11840 @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
11841 @xref{Quotations and Examples}. (What all these commands have in
11842 common is that each line of input produces a line of output.) In
11843 other contexts, @code{@@group} can cause anomalous vertical
11847 This formatting requirement means that you should write:
11860 with the @code{@@group} and @code{@@end group} commands inside the
11861 @code{@@example} and @code{@@end example} commands.
11863 The @code{@@group} command is most often used to hold an example
11864 together on one page. In this Texinfo manual, more than 100 examples
11865 contain text that is enclosed between @code{@@group} and @code{@@end
11868 If you forget to end a group, you may get strange and unfathomable
11869 error messages when you run @TeX{}. This is because @TeX{} keeps
11870 trying to put the rest of the Texinfo file onto the one page and does
11871 not start to generate error messages until it has processed
11872 considerable text. It is a good rule of thumb to look for a missing
11873 @code{@@end group} if you get incomprehensible error messages in
11877 @comment node-name, next, previous, up
11878 @section @code{@@need @var{mils}}: Prevent Page Breaks
11879 @cindex Need space at page bottom
11882 A line containing only @code{@@need @var{n}} starts
11883 a new page in a printed manual if fewer than @var{n} mils (thousandths
11884 of an inch) remain on the current page. Do not use
11885 braces around the argument @var{n}. The @code{@@need} command has no
11886 effect on Info files since they are not paginated.@refill
11889 This paragraph is preceded by an @code{@@need} command that tells
11890 @TeX{} to start a new page if fewer than 800 mils (eight-tenths
11891 inch) remain on the page. It looks like this:@refill
11896 This paragraph is preceded by @dots{}
11900 The @code{@@need} command is useful for preventing orphans (single
11901 lines at the bottoms of printed pages).@refill
11904 @node Definition Commands
11905 @chapter Definition Commands
11906 @cindex Definition commands
11908 The @code{@@deffn} command and the other @dfn{definition commands}
11909 enable you to describe functions, variables, macros, commands, user
11910 options, special forms and other such artifacts in a uniform
11913 In the Info file, a definition causes the entity
11914 category---`Function', `Variable', or whatever---to appear at the
11915 beginning of the first line of the definition, followed by the
11916 entity's name and arguments. In the printed manual, the command
11917 causes @TeX{} to print the entity's name and its arguments on the left
11918 margin and print the category next to the right margin. In both
11919 output formats, the body of the definition is indented. Also, the
11920 name of the entity is entered into the appropriate index:
11921 @code{@@deffn} enters the name into the index of functions,
11922 @code{@@defvr} enters it into the index of variables, and so
11923 on (@pxref{Predefined Indices}).
11925 A manual need not and should not contain more than one definition for
11926 a given name. An appendix containing a summary should use
11927 @code{@@table} rather than the definition commands.@refill
11930 * Def Cmd Template:: Writing descriptions using definition commands.
11931 * Def Cmd Continuation Lines:: Continuing the heading over source lines.
11932 * Optional Arguments:: Handling optional and repeated arguments.
11933 * deffnx:: Group two or more `first' lines.
11934 * Def Cmds in Detail:: Reference for all the definition commands.
11935 * Def Cmd Conventions:: Conventions for writing definitions.
11936 * Sample Function Definition:: An example.
11940 @node Def Cmd Template
11941 @section The Template for a Definition
11942 @cindex Definition template
11943 @cindex Template for a definition
11945 The @code{@@deffn} command is used for definitions of entities that
11946 resemble functions. To write a definition using the @code{@@deffn}
11947 command, write the @code{@@deffn} command at the beginning of a line
11948 and follow it on the same line by the category of the entity, the name
11949 of the entity itself, and its arguments (if any). Then write the body
11950 of the definition on succeeding lines. (You may embed examples in the
11951 body.) Finally, end the definition with an @code{@@end deffn} command
11952 written on a line of its own.
11954 The other definition commands follow the same format: a line with the
11955 @code{@@def@dots{}} command and whatever arguments are appropriate for
11956 that command; the body of the definition; and a corresponding
11959 The template for a definition looks like this:
11963 @@deffn @var{category} @var{name} @var{arguments}@dots{}
11964 @var{body-of-definition}
11975 @@deffn Command forward-word count
11976 This command moves point forward @@var@{count@} words
11977 (or backward if @@var@{count@} is negative). @dots{}
11986 @deffn Command forward-word count
11987 This command moves point forward @var{count} words
11988 (or backward if @var{count} is negative). @dots{}
11992 Capitalize the category name like a title. If the name of the
11993 category contains spaces, as in the phrase `Interactive Command',
11994 enclose it in braces. For example:
11998 @@deffn @{Interactive Command@} isearch-forward
12005 Otherwise, the second word will be mistaken for the name of the
12006 entity. As a general rule, when any of the arguments in the heading
12007 line @emph{except} the last one are more than one word, you need to
12008 enclose them in braces. This may also be necessary if the text
12009 contains commands, for example, @samp{@{declaraci@@'on@}} if you are
12010 writing in Spanish.
12012 Some of the definition commands are more general than others. The
12013 @code{@@deffn} command, for example, is the general definition command
12014 for functions and the like---for entities that may take arguments.
12015 When you use this command, you specify the category to which the
12016 entity belongs. Three predefined, specialized variations
12017 (@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the
12018 category for you: ``Function'', ``Macro'', and ``Special Form''
12019 respectively. (In Lisp, a special form is an entity much like a
12020 function.) Similarly, the general @code{@@defvr} command is
12021 accompanied by several specialized variations for describing
12022 particular kinds of variables.
12024 @xref{Sample Function Definition}, for a detailed example of a
12025 function definition, including the use of @code{@@example} inside the
12028 @cindex Macros in definition commands
12029 Unfortunately, due to implementation difficulties, macros are not expanded
12030 in @code{@@deffn} and all the other definition commands.
12033 @node Def Cmd Continuation Lines
12034 @section Definition Command Continuation Lines
12035 @cindex Continuation lines in definition commands
12036 @cindex Definition command headings, continuing
12037 @cindex @samp{@@} as continuation in definition commands
12039 The heading line of a definition command can get very long.
12040 Therefore, Texinfo has a special syntax allowing them to be continued
12041 over multiple lines of the source file: a lone @samp{@@} at the end of
12042 each line to be continued. Here's an example:
12047 This is the basic continued defun.
12051 @noindent produces:
12055 This is the basic continued defun.
12059 As you can see, the continued lines are combined, as if they had been
12060 typed on one source line.
12062 Although this example only shows a one-line continuation,
12063 continuations may extend over any number of lines; simply put an
12064 @code{@@} at the end of each line to be continued.
12066 The @code{@@} character does not have to be the last character on the
12067 physical line: whitespace is allowed (and ignored) afterwards.
12069 @cindex Whitespace, collapsed around continuations
12070 @cindex Collapsing whitespace around continuations
12071 In general, any number of spaces or tabs around the @code{@@}
12072 continuation character, both on the line with the @code{@@} and on the
12073 continued line, are collapsed into a single space. There is one
12074 exception: the Texinfo processors will not fully collapse whitespace
12075 around a continuation inside braces. For example:
12078 @@deffn @{Category @@
12082 @noindent The output (not shown) has excess space between `Category'
12083 and `Name'. In this case, simply elide any unwanted whitespace in
12084 your input, or put the continuation @code{@@} outside braces.
12086 @code{@@} does not (currently) function as a continuation character in
12087 @emph{any} other context. Ordinarily, @samp{@@} followed by a
12088 whitespace character (space, tab, newline) produces a normal interword
12089 space (@pxref{Multiple Spaces}).
12092 @node Optional Arguments
12093 @section Optional and Repeated Arguments
12094 @cindex Optional and repeated arguments
12095 @cindex Repeated and optional arguments
12096 @cindex Arguments, repeated and optional
12097 @cindex Syntax, optional & repeated arguments
12098 @cindex Meta-syntactic chars for arguments
12100 Some entities take optional or repeated arguments, which may be
12101 specified by a distinctive glyph that uses square brackets and
12102 ellipses. For @w{example}, a special form often breaks its argument list
12103 into separate arguments in more complicated ways than a
12104 straightforward function.
12106 @c This is consistent with Emacs Lisp Reference manual
12107 An argument enclosed within square brackets is optional.
12108 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
12109 An argument followed by an ellipsis is optional
12110 and may be repeated more than once.
12111 @c This is consistent with Emacs Lisp Reference manual
12112 Thus, @var{repeated-args}@samp{@dots{}} stands for zero or more
12113 arguments. Parentheses are used when several arguments are grouped
12114 into additional levels of list structure in Lisp.
12116 Here is the @code{@@defspec} line of an example of an imaginary
12120 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
12128 In this example, the arguments @var{from} and @var{to} are optional,
12129 but must both be present or both absent. If they are present,
12130 @var{inc} may optionally be specified as well. These arguments are
12131 grouped with the argument @var{var} into a list, to distinguish them
12132 from @var{body}, which includes all remaining elements of the
12135 In a Texinfo source file, this @code{@@defspec} line is written like
12136 this (except it would not be split over two lines, as it is in this
12141 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
12142 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
12147 The function is listed in the Command and Variable Index under
12148 @samp{foobar}.@refill
12152 @section Two or More `First' Lines
12153 @cindex Two `First' Lines for @code{@@deffn}
12154 @cindex Grouping two definitions together
12155 @cindex Definitions grouped together
12158 To create two or more `first' or header lines for a definition, follow
12159 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
12160 The @code{@@deffnx} command works exactly like @code{@@deffn}
12161 except that it does not generate extra vertical white space between it
12162 and the preceding line.@refill
12169 @@deffn @{Interactive Command@} isearch-forward
12170 @@deffnx @{Interactive Command@} isearch-backward
12171 These two search commands are similar except @dots{}
12179 @deffn {Interactive Command} isearch-forward
12180 @deffnx {Interactive Command} isearch-backward
12181 These two search commands are similar except @dots{}
12184 Each definition command has an `x' form: @code{@@defunx},
12185 @code{@@defvrx}, @code{@@deftypefunx}, etc.
12187 The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}).
12190 @node Def Cmds in Detail
12191 @section The Definition Commands
12193 Texinfo provides more than a dozen definition commands, all of which
12194 are described in this section.@refill
12196 The definition commands automatically enter the name of the entity in
12197 the appropriate index: for example, @code{@@deffn}, @code{@@defun},
12198 and @code{@@defmac} enter function names in the index of functions;
12199 @code{@@defvr} and @code{@@defvar} enter variable names in the index
12200 of variables.@refill
12202 Although the examples that follow mostly illustrate Lisp, the commands
12203 can be used for other programming languages.@refill
12206 * Functions Commands:: Commands for functions and similar entities.
12207 * Variables Commands:: Commands for variables and similar entities.
12208 * Typed Functions:: Commands for functions in typed languages.
12209 * Typed Variables:: Commands for variables in typed languages.
12210 * Data Types:: The definition command for data types.
12211 * Abstract Objects:: Commands for object-oriented programming.
12214 @node Functions Commands
12215 @subsection Functions and Similar Entities
12217 This section describes the commands for describing functions and similar
12222 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
12223 The @code{@@deffn} command is the general definition command for
12224 functions, interactive commands, and similar entities that may take
12225 arguments. You must choose a term to describe the category of entity
12226 being defined; for example, ``Function'' could be used if the entity is
12227 a function. The @code{@@deffn} command is written at the beginning of a
12228 line and is followed on the same line by the category of entity being
12229 described, the name of this particular entity, and its arguments, if
12230 any. Terminate the definition with @code{@@end deffn} on a line of its
12234 For example, here is a definition:
12238 @@deffn Command forward-char nchars
12239 Move point forward @@var@{nchars@} characters.
12245 This shows a rather terse definition for a ``command'' named
12246 @code{forward-char} with one argument, @var{nchars}.
12248 @code{@@deffn} and prints argument names such as @var{nchars} in slanted
12249 type in the printed output, because we think of these names as
12250 metasyntactic variables---they stand for the actual argument values.
12251 Within the text of the description, however, write an argument name
12252 explicitly with @code{@@var} to refer to the value of the argument.
12253 In the example above, we used @samp{@@var@{nchars@}} in this way.
12255 In the unusual case when an argument name contains @samp{--}, or
12256 another character sequence which is treated specially
12257 (@pxref{Conventions}), use @code{@@var} around the argument. This
12258 causes the name to be printed in slanted typewriter, instead of the
12259 regular slanted font, exactly as input.
12260 @c except for ?` and !`, but we won't explain that.
12262 The template for @code{@@deffn} is:
12266 @@deffn @var{category} @var{name} @var{arguments}@dots{}
12267 @var{body-of-definition}
12273 @item @@defun @var{name} @var{arguments}@dots{}
12274 The @code{@@defun} command is the definition command for functions.
12275 @code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}.
12276 Terminate the definition with @code{@@end defun} on a line of its own.
12277 Thus, the template is:
12281 @@defun @var{function-name} @var{arguments}@dots{}
12282 @var{body-of-definition}
12288 @item @@defmac @var{name} @var{arguments}@dots{}
12289 The @code{@@defmac} command is the definition command for macros.
12290 @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
12291 works like @code{@@defun}.
12294 @item @@defspec @var{name} @var{arguments}@dots{}
12295 The @code{@@defspec} command is the definition command for special
12296 forms. (In Lisp, a special form is an entity much like a function,
12297 @pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
12298 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
12299 @dots{}} and works like @code{@@defun}.
12302 All these commands create entries in the index of functions.
12305 @node Variables Commands
12306 @subsection Variables and Similar Entities
12308 Here are the commands for defining variables and similar
12313 @item @@defvr @var{category} @var{name}
12314 The @code{@@defvr} command is a general definition command for
12315 something like a variable---an entity that records a value. You must
12316 choose a term to describe the category of entity being defined; for
12317 example, ``Variable'' could be used if the entity is a variable.
12318 Write the @code{@@defvr} command at the beginning of a line and
12319 follow it on the same line by the category of the entity and the
12320 name of the entity.
12322 Capitalize the category name like a title. If the name of the category
12323 contains spaces, as in the name ``User Option'', enclose it in braces.
12324 Otherwise, the second word will be mistaken for the name of the entity.
12329 @@defvr @{User Option@} fill-column
12330 This buffer-local variable specifies
12331 the maximum width of filled lines.
12337 Terminate the definition with @code{@@end defvr} on a line of its
12344 @@defvr @var{category} @var{name}
12345 @var{body-of-definition}
12350 @code{@@defvr} creates an entry in the index of variables for @var{name}.
12353 @item @@defvar @var{name}
12354 The @code{@@defvar} command is the definition command for variables.
12355 @code{@@defvar} is equivalent to @samp{@@defvr Variable
12373 @@defvar @var{name}
12374 @var{body-of-definition}
12379 @code{@@defvar} creates an entry in the index of variables for
12383 @item @@defopt @var{name}
12384 @cindex User options, marking
12385 The @code{@@defopt} command is the definition command for @dfn{user
12386 options}, i.e., variables intended for users to change according to
12387 taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
12388 Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
12389 Option@} @dots{}} and works like @code{@@defvar}. It creates an entry
12390 in the index of variables.
12394 @node Typed Functions
12395 @subsection Functions in Typed Languages
12397 The @code{@@deftypefn} command and its variations are for describing
12398 functions in languages in which you must declare types of variables and
12399 functions, such as C and C++.
12403 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
12404 The @code{@@deftypefn} command is the general definition command for
12405 functions and similar entities that may take arguments and that are
12406 typed. The @code{@@deftypefn} command is written at the beginning of
12407 a line and is followed on the same line by the category of entity
12408 being described, the type of the returned value, the name of this
12409 particular entity, and its arguments, if any.@refill
12417 @@deftypefn @{Library Function@} int foobar
12418 (int @@var@{foo@}, float @@var@{bar@})
12426 (where the text before the ``@dots{}'', shown above as two lines, would
12427 actually be a single line in a real Texinfo file) produces the following
12432 -- Library Function: int foobar (int FOO, float BAR)
12438 In a printed manual, it produces:
12441 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
12447 This means that @code{foobar} is a ``library function'' that returns an
12448 @code{int}, and its arguments are @var{foo} (an @code{int}) and
12449 @var{bar} (a @code{float}).@refill
12451 Since in typed languages, the actual names of the arguments are
12452 typically scattered among data type names and keywords, Texinfo cannot
12453 find them without help. You can either (a)@tie{}write everything
12454 as straight text, and it will be printed in slanted type; (b)@tie{}use
12455 @code{@@var} for the variable names, which will uppercase the
12456 variable names in Info and use the slanted typewriter font in printed
12457 output; (c)@tie{}use @code{@@var} for the variable names and
12458 @code{@@code} for the type names and keywords, which will be dutifully
12461 The template for @code{@@deftypefn} is:@refill
12465 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
12466 @var{body-of-description}
12472 Note that if the @var{category} or @var{data type} is more than one
12473 word then it must be enclosed in braces to make it a single argument.@refill
12475 If you are describing a procedure in a language that has packages,
12476 such as Ada, you might consider using @code{@@deftypefn} in a manner
12477 somewhat contrary to the convention described in the preceding
12478 paragraphs. For example:
12482 @@deftypefn stacks private push @@
12483 (@@var@{s@}:in out stack; @@
12484 @@var@{n@}:in integer)
12491 (The @code{@@deftypefn} arguments are shown using continuations
12492 (@pxref{Def Cmd Continuation Lines}), but could be on a single line in
12493 a real Texinfo file.)
12495 In this instance, the procedure is classified as belonging to the
12496 package @code{stacks} rather than classified as a `procedure' and its
12497 data type is described as @code{private}. (The name of the procedure
12498 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
12500 @code{@@deftypefn} creates an entry in the index of functions for
12503 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
12505 The @code{@@deftypefun} command is the specialized definition command
12506 for functions in typed languages. The command is equivalent to
12507 @samp{@@deftypefn Function @dots{}}. The template is:
12511 @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
12512 @var{body-of-description}
12517 @code{@@deftypefun} creates an entry in the index of functions for
12523 @node Typed Variables
12524 @subsection Variables in Typed Languages
12526 Variables in typed languages are handled in a manner similar to
12527 functions in typed languages. @xref{Typed Functions}. The general
12528 definition command @code{@@deftypevr} corresponds to
12529 @code{@@deftypefn} and the specialized definition command
12530 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
12534 @item @@deftypevr @var{category} @var{data-type} @var{name}
12535 The @code{@@deftypevr} command is the general definition command for
12536 something like a variable in a typed language---an entity that records
12537 a value. You must choose a term to describe the category of the
12538 entity being defined; for example, ``Variable'' could be used if the
12539 entity is a variable.@refill
12541 The @code{@@deftypevr} command is written at the beginning of a line
12542 and is followed on the same line by the category of the entity
12543 being described, the data type, and the name of this particular
12552 @@deftypevr @{Global Flag@} int enable
12559 produces the following in Info:
12563 -- Global Flag: int enable
12570 and the following in a printed manual:
12573 @deftypevr {Global Flag} int enable
12583 @@deftypevr @var{category} @var{data-type} @var{name}
12584 @var{body-of-description}
12589 @item @@deftypevar @var{data-type} @var{name}
12590 The @code{@@deftypevar} command is the specialized definition command
12591 for variables in typed languages. @code{@@deftypevar} is equivalent
12592 to @samp{@@deftypevr Variable @dots{}}. The template is:
12596 @@deftypevar @var{data-type} @var{name}
12597 @var{body-of-description}
12603 These commands create entries in the index of variables.
12606 @subsection Data Types
12608 Here is the command for data types:@refill
12612 @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
12613 The @code{@@deftp} command is the generic definition command for data
12614 types. The command is written at the beginning of a line and is
12615 followed on the same line by the category, by the name of the type
12616 (which is a word like @code{int} or @code{float}), and then by names of
12617 attributes of objects of that type. Thus, you could use this command
12618 for describing @code{int} or @code{float}, in which case you could use
12619 @code{data type} as the category. (A data type is a category of
12620 certain objects for purposes of deciding which operations can be
12621 performed on them.)@refill
12623 In Lisp, for example, @dfn{pair} names a particular data
12624 type, and an object of that type has two slots called the
12625 @sc{car} and the @sc{cdr}. Here is how you would write the first line
12626 of a definition of @code{pair}.@refill
12630 @@deftp @{Data type@} pair car cdr
12641 @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
12642 @var{body-of-definition}
12647 @code{@@deftp} creates an entry in the index of data types.
12651 @node Abstract Objects
12652 @subsection Object-Oriented Programming
12654 @cindex Object-oriented programming
12656 Here are the commands for formatting descriptions about abstract
12657 objects, such as are used in object-oriented programming. A class is
12658 a defined type of abstract object. An instance of a class is a
12659 particular object that has the type of the class. An instance
12660 variable is a variable that belongs to the class but for which each
12661 instance has its own value.
12664 * Variables: Object-Oriented Variables.
12665 * Methods: Object-Oriented Methods.
12669 @node Object-Oriented Variables
12670 @subsubsection Object-Oriented Variables
12672 @cindex Variables, object-oriented
12674 These commands allow you to define different sorts of variables in
12675 object-oriented programming languages.
12678 @item @@defcv @var{category} @var{class} @var{name}
12680 The @code{@@defcv} command is the general definition command for
12681 variables associated with classes in object-oriented programming. The
12682 @code{@@defcv} command is followed by three arguments: the category of
12683 thing being defined, the class to which it belongs, and its
12684 name. For instance:
12688 @@defcv @{Class Option@} Window border-pattern
12694 @noindent produces:
12695 @defcv {Class Option} Window border-pattern
12699 @code{@@defcv} creates an entry in the index of variables.
12701 @item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
12703 The @code{@@deftypecv} command is the definition command for typed
12704 class variables in object-oriented programming. It is analogous to
12705 @code{@@defcv} with the addition of the @var{data-type} parameter to
12706 specify the type of the instance variable. Ordinarily, the data type
12707 is a programming language construct that should be marked with
12708 @code{@@code}. For instance:
12712 @@deftypecv @{Class Option@} Window @@code@{int@} border-pattern
12718 @noindent produces:
12720 @deftypecv {Class Option} Window @code{int} border-pattern
12724 @code{@@deftypecv} creates an entry in the index of variables.
12726 @item @@defivar @var{class} @var{name}
12728 The @code{@@defivar} command is the definition command for instance
12729 variables in object-oriented programming. @code{@@defivar} is
12730 equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For
12735 @@defivar Window border-pattern
12741 @noindent produces:
12743 @defivar Window border-pattern
12747 @code{@@defivar} creates an entry in the index of variables.
12749 @item @@deftypeivar @var{class} @var{data-type} @var{name}
12750 @findex deftypeivar
12751 The @code{@@deftypeivar} command is the definition command for typed
12752 instance variables in object-oriented programming. It is analogous to
12753 @code{@@defivar} with the addition of the @var{data-type} parameter to
12754 specify the type of the instance variable. Ordinarily, the data type
12755 is a programming language construct that should be marked with
12756 @code{@@code}. For instance:
12760 @@deftypeivar Window @@code@{int@} border-pattern
12766 @noindent produces:
12768 @deftypeivar Window @code{int} border-pattern
12772 @code{@@deftypeivar} creates an entry in the index of variables.
12776 @node Object-Oriented Methods
12777 @subsubsection Object-Oriented Methods
12779 @cindex Methods, object-oriented
12781 These commands allow you to define different sorts of function-like
12782 entities resembling methods in object-oriented programming languages.
12783 These entities take arguments, as functions do, but are associated with
12784 particular classes of objects.
12789 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
12790 The @code{@@defop} command is the general definition command for these
12791 method-like entities.
12793 For example, some systems have constructs called @dfn{wrappers} that
12794 are associated with classes as methods are, but that act more like
12795 macros than like functions. You could use @code{@@defop Wrapper} to
12796 describe one of these.@refill
12798 Sometimes it is useful to distinguish methods and @dfn{operations}.
12799 You can think of an operation as the specification for a method.
12800 Thus, a window system might specify that all window classes have a
12801 method named @code{expose}; we would say that this window system
12802 defines an @code{expose} operation on windows in general. Typically,
12803 the operation has a name and also specifies the pattern of arguments;
12804 all methods that implement the operation must accept the same
12805 arguments, since applications that use the operation do so without
12806 knowing which method will implement it.@refill
12808 Often it makes more sense to document operations than methods. For
12809 example, window application developers need to know about the
12810 @code{expose} operation, but need not be concerned with whether a
12811 given class of windows has its own method to implement this operation.
12812 To describe this operation, you would write:@refill
12815 @@defop Operation windows expose
12818 The @code{@@defop} command is written at the beginning of a line and
12819 is followed on the same line by the overall name of the category of
12820 operation, the name of the class of the operation, the name of the
12821 operation, and its arguments, if any.@refill
12826 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
12827 @var{body-of-definition}
12832 @code{@@defop} creates an entry, such as `@code{expose} on
12833 @code{windows}', in the index of functions.@refill
12836 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
12837 The @code{@@deftypeop} command is the definition command for typed
12838 operations in object-oriented programming. It is similar to
12839 @code{@@defop} with the addition of the @var{data-type} parameter to
12840 specify the return type of the method. @code{@@deftypeop} creates an
12841 entry in the index of functions.
12843 @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
12845 The @code{@@defmethod} command is the definition command for methods
12846 in object-oriented programming. A method is a kind of function that
12847 implements an operation for a particular class of objects and its
12850 @c ADR: Who cares?!?
12851 @c KB: Oh, I don't know, I think this info is crucial!
12852 In the Lisp Machine, methods actually were functions, but
12853 they were usually defined with @code{defmethod}.
12856 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
12857 The command is written at the beginning of a line and is followed by
12858 the name of the class of the method, the name of the method, and its
12859 arguments, if any.@refill
12865 @@defmethod @code{bar-class} bar-method argument
12872 illustrates the definition for a method called @code{bar-method} of
12873 the class @code{bar-class}. The method takes an argument.
12875 @code{@@defmethod} creates an entry in the index of functions.
12877 @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
12879 The @code{@@deftypemethod} command is the definition command for methods
12880 in object-oriented typed languages, such as C++ and Java. It is similar
12881 to the @code{@@defmethod} command with the addition of the
12882 @var{data-type} parameter to specify the return type of the method.
12883 @code{@@deftypemethod} creates an entry in the index of functions.
12888 @node Def Cmd Conventions
12889 @section Conventions for Writing Definitions
12890 @cindex Definition conventions
12891 @cindex Conventions for writing definitions
12893 When you write a definition using @code{@@deffn}, @code{@@defun}, or
12894 one of the other definition commands, please take care to use
12895 arguments that indicate the meaning, as with the @var{count} argument
12896 to the @code{forward-word} function. Also, if the name of an argument
12897 contains the name of a type, such as @var{integer}, take care that the
12898 argument actually is of that type.@refill
12901 @node Sample Function Definition
12902 @section A Sample Function Definition
12903 @cindex Function definitions
12904 @cindex Command definitions
12905 @cindex Macro definitions
12906 @cindex Sample function definition
12908 A function definition uses the @code{@@defun} and @code{@@end defun}
12909 commands. The name of the function follows immediately after the
12910 @code{@@defun} command and it is followed, on the same line, by the
12911 parameter list.@refill
12913 Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
12914 Lisp Reference Manual}.
12917 @defun apply function &rest arguments
12918 @code{apply} calls @var{function} with @var{arguments}, just
12919 like @code{funcall} but with one difference: the last of
12920 @var{arguments} is a list of arguments to give to
12921 @var{function}, rather than a single argument. We also say
12922 that this list is @dfn{appended} to the other arguments.
12924 @code{apply} returns the result of calling @var{function}.
12925 As with @code{funcall}, @var{function} must either be a Lisp
12926 function or a primitive function; special forms and macros
12927 do not make sense in @code{apply}.
12933 @error{} Wrong type argument: listp, z
12934 (apply '+ 1 2 '(3 4))
12936 (apply '+ '(1 2 3 4))
12939 (apply 'append '((a b c) nil (x y z) nil))
12940 @result{} (a b c x y z)
12943 An interesting example of using @code{apply} is found in the description
12944 of @code{mapcar}.@refill
12949 In the Texinfo source file, this example looks like this:
12953 @@defun apply function &rest arguments
12954 @@code@{apply@} calls @@var@{function@} with
12955 @@var@{arguments@}, just like @@code@{funcall@} but with one
12956 difference: the last of @@var@{arguments@} is a list of
12957 arguments to give to @@var@{function@}, rather than a single
12958 argument. We also say that this list is @@dfn@{appended@}
12959 to the other arguments.
12963 @@code@{apply@} returns the result of calling
12964 @@var@{function@}. As with @@code@{funcall@},
12965 @@var@{function@} must either be a Lisp function or a
12966 primitive function; special forms and macros do not make
12967 sense in @@code@{apply@}.
12975 @@error@{@} Wrong type argument: listp, z
12976 (apply '+ 1 2 '(3 4))
12978 (apply '+ '(1 2 3 4))
12981 (apply 'append '((a b c) nil (x y z) nil))
12982 @@result@{@} (a b c x y z)
12987 An interesting example of using @@code@{apply@} is found
12988 in the description of @@code@{mapcar@}.
12994 In this manual, this function is listed in the Command and Variable
12995 Index under @code{apply}.@refill
12997 Ordinary variables and user options are described using a format like
12998 that for functions except that variables do not take arguments.
13002 @chapter Conditionally Visible Text
13003 @cindex Conditionally visible text
13004 @cindex Text, conditionally visible
13005 @cindex Visibility of conditional text
13006 @cindex If text conditionally visible
13008 The @dfn{conditional commands} allow you to use different text for
13009 different output formats, or for general conditions that you define.
13010 For example, you can use them to specify different text for the
13011 printed manual and the Info output.
13013 The conditional commands comprise the following categories.
13017 Commands specific to an output format (Info, @TeX{}, HTML, @dots{}).
13020 Commands specific to any output format @emph{other} than a given
13021 one (not Info, not @TeX{}, @dots{}).
13024 `Raw' formatter text for any output format, passed straight
13025 through with no interpretation of @@-commands.
13028 Format-independent variable substitutions, and testing if a variable
13034 * Conditional Commands:: Text for a given format.
13035 * Conditional Not Commands:: Text for any format other than a given one.
13036 * Raw Formatter Commands:: Using raw formatter commands.
13037 * set clear value:: Variable tests and substitutions.
13038 * Conditional Nesting:: Using conditionals inside conditionals.
13042 @node Conditional Commands
13043 @section Conditional Commands
13045 Texinfo has an @code{@@if@var{format}} environment for each output
13046 format, to allow conditional inclusion of text for a particular output
13050 @code{@@ifinfo} begins segments of text that should be ignored by
13051 @TeX{} when it typesets the printed manual, and by @command{makeinfo}
13052 when not producing Info output. The segment of text appears only in
13053 the Info file and, for historical compatibility, the plain text
13058 @findex ifplaintext
13061 The environments for the other formats are analogous:
13064 @item @@ifdocbook @dots{} @@end ifdocbook
13065 Text to appear only in the Docbook output.
13067 @item @@ifhtml @dots{} @@end ifhtml
13068 Text to appear only in the HTML output.
13070 @item @@ifplaintext @dots{} @@end ifplaintext
13071 Text to appear only in the plain text output.
13073 @item @@iftex @dots{} @@end iftex
13074 Text to appear only in the printed manual.
13076 @item @@ifxml @dots{} @@end ifxml
13077 Text to appear only in the XML output.
13080 The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear
13081 on lines by themselves in your source file.
13083 Here is an example showing all these conditionals:
13087 This text will appear only in the printed manual.
13090 However, this text will appear only in Info and plain text.
13093 And this text will only appear in HTML.
13096 Whereas this text will only appear in plain text.
13099 Notwithstanding that this will only appear in XML.
13102 Nevertheless, this will only appear in Docbook.
13107 The preceding example produces the following line:
13110 This text will appear only in the printed manual.
13113 However, this text will appear only in Info and plain text.
13116 And this text will only appear in HTML.
13119 Whereas this text will only appear in plain text.
13122 Notwithstanding that this will only appear in XML.
13125 Nevertheless, this will only appear in Docbook.
13129 Notice that you only see one of the input lines, depending on which
13130 version of the manual you are reading.
13133 @node Conditional Not Commands
13134 @section Conditional Not Commands
13135 @findex ifnotdocbook
13138 @findex ifnotplaintext
13142 You can specify text to be included in any output format @emph{other}
13143 than a given one with the @code{@@ifnot@dots{}} environments:
13146 @@ifnotdocbook @dots{} @@end ifnotdocbook
13147 @@ifnothtml @dots{} @@end ifnothtml
13148 @@ifnotinfo @dots{} @@end ifnotinfo
13149 @@ifnotplaintext @dots{} @@end ifnotplaintext
13150 @@ifnottex @dots{} @@end ifnottex
13151 @@ifnotxml @dots{} @@end ifnotxml
13155 The @code{@@ifnot@dots{}} command and the @code{@@end} command must
13156 appear on lines by themselves in your actual source file.
13158 If the output file is being made in the given format, the
13159 region is @emph{ignored}. Otherwise, it is included.
13161 There is one exception (for historical compatibility):
13162 @code{@@ifnotinfo} text is omitted for both Info and plain text
13163 output, not just Info. To specify text which appears only in Info and
13164 not in plain text, use @code{@@ifnotplaintext}, like this:
13169 This will be in Info, but not plain text.
13170 @@end ifnotplaintext
13174 The regions delimited by these commands are ordinary Texinfo source as
13175 with @code{@@iftex}, not raw formatter source as with @code{@@tex}
13176 (@pxref{Raw Formatter Commands}).
13179 @node Raw Formatter Commands
13180 @section Raw Formatter Commands
13181 @cindex Raw formatter commands
13182 @cindex @TeX{} commands, using ordinary
13183 @cindex Ordinary @TeX{} commands, using
13184 @cindex Commands using raw @TeX{}
13185 @cindex Docbook, including raw
13186 @cindex HTML, including raw
13187 @cindex XML, including raw
13188 @cindex Plain @TeX{}
13190 Inside a region delineated by @code{@@iftex} and @code{@@end iftex},
13191 you can embed some raw @TeX{} commands. The Texinfo processors will
13192 ignore such a region unless @TeX{} output is being produced. You can
13193 write the @TeX{} commands as you would write them in a normal @TeX{}
13194 file, except that you must replace the @samp{\} used by @TeX{} with an
13195 @samp{@@}. For example, in the @code{@@titlepage} section of a
13196 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
13197 the copyright page. (The @code{@@titlepage} command causes Info to
13198 ignore the region automatically, as it does with the @code{@@iftex}
13201 However, most features of plain @TeX{} will not work within
13202 @code{@@iftex}, as they are overridden by Texinfo features. The
13203 purpose of @code{@@iftex} is to provide conditional processing for the
13204 Texinfo source, not provide access to underlying formatting features.
13207 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
13208 commands, by delineating a region with the @code{@@tex} and @code{@@end
13209 tex} commands. All plain @TeX{} commands and category codes are
13210 restored within an @code{@@tex} region. The sole exception is that the
13211 @code{@@} character still introduces a command, so that @code{@@end tex}
13212 can be recognized properly. As with @code{@@iftex}, Texinfo
13213 processors will ignore such a region unless @TeX{} output is being produced.
13215 @findex \gdef @r{within @code{@@tex}}
13216 In complex cases, you may wish to define new @TeX{} macros within
13217 @code{@@tex}. You must use @code{\gdef} to do this, not @code{\def},
13218 because @code{@@tex} regions are processed in a @TeX{} group.
13220 @cindex Mathematical expressions
13221 As an example, here is a mathematical expression written in plain @TeX{}:
13225 $$ \chi^2 = \sum_@{i=1@}^N
13226 \left (y_i - (a + b x_i)
13227 \over \sigma_i\right)^2 $$
13232 The output of this example will appear only in a printed manual. If
13233 you are reading this in Info, you will not see the equation that appears
13234 in the printed manual.
13236 In a printed manual, the above expression looks like
13241 $$ \chi^2 = \sum_{i=1}^N
13242 \left(y_i - (a + b x_i)
13243 \over \sigma_i\right)^2 $$
13248 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
13249 a region to be included in HTML output only, and @code{@@html @dots{}
13250 @@end html} for a region of raw HTML.
13254 Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit
13255 a region to be included in XML output only, and @code{@@xml @dots{}
13256 @@end xml} for a region of raw XML.
13260 Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook}
13261 to delimit a region to be included in Docbook output only, and
13262 @code{@@docbook @dots{} @@end docbook} for a region of raw Docbook.
13264 In all cases, the exception to the raw processing is that @code{@@} is
13265 still an escape character, so the @code{@@end} command can be
13269 @node set clear value
13270 @section @code{@@set}, @code{@@clear}, and @code{@@value}
13272 You can direct the Texinfo formatting commands to format or ignore parts
13273 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
13274 and @code{@@ifclear} commands.
13276 Here are brief descriptions of these commands, see the following
13277 sections for more details:
13280 @item @@set @var{flag} [@var{value}]
13281 Set the variable @var{flag}, to the optional @var{value} if specified.
13283 @item @@clear @var{flag}
13284 Undefine the variable @var{flag}, whether or not it was previously defined.
13286 @item @@ifset @var{flag}
13287 If @var{flag} is set, text through the next @code{@@end ifset} command
13288 is formatted. If @var{flag} is clear, text through the following
13289 @code{@@end ifset} command is ignored.
13291 @item @@ifclear @var{flag}
13292 If @var{flag} is set, text through the next @code{@@end ifclear} command
13293 is ignored. If @var{flag} is clear, text through the following
13294 @code{@@end ifclear} command is formatted.
13298 * set value:: Expand a flag variable to a string.
13299 * ifset ifclear:: Format a region if a flag is set.
13300 * value Example:: An easy way to update edition information.
13305 @subsection @code{@@set} and @code{@@value}
13310 You use the @code{@@set} command to specify a value for a flag, which
13311 is later expanded by the @code{@@value} command.
13313 A @dfn{flag} (aka @dfn{variable}) is an identifier. It is best to use
13314 only letters and numerals in a flag name, not @samp{-} or
13315 @samp{_}---they will work in some contexts, but not all, due to
13316 limitations in @TeX{}.
13318 The value is the remainder of the input line, and can contain anything.
13320 Write the @code{@@set} command like this:
13323 @@set foo This is a string.
13327 This sets the value of the flag @code{foo} to ``This is a string.''.
13329 The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
13330 command with the string to which @var{flag} is set. Thus, when
13331 @code{foo} is set as shown above, the Texinfo formatters convert this:
13336 @exdent @r{to this:}
13341 You can write an @code{@@value} command within a paragraph; but you
13342 must write an @code{@@set} command on a line of its own.
13344 If you write the @code{@@set} command like this:
13351 without specifying a string, the value of @code{foo} is the empty string.
13353 If you clear a previously set flag with @code{@@clear @var{flag}}, a
13354 subsequent @code{@@value@{flag@}} command will report an error.
13356 For example, if you set @code{foo} as follows:
13359 @@set howmuch very, very, very
13363 then the formatters transform
13367 It is a @@value@{howmuch@} wet day.
13369 It is a very, very, very wet day.
13380 then the formatters transform
13384 It is a @@value@{howmuch@} wet day.
13386 It is a @{No value for "howmuch"@} wet day.
13391 @node ifset ifclear
13392 @subsection @code{@@ifset} and @code{@@ifclear}
13395 When a @var{flag} is set, the Texinfo formatting commands format text
13396 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
13397 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
13398 commands do @emph{not} format the text. @code{@@ifclear} operates
13401 Write the conditionally formatted text between @code{@@ifset @var{flag}}
13402 and @code{@@end ifset} commands, like this:
13407 @var{conditional-text}
13412 For example, you can create one document that has two variants, such as
13413 a manual for a `large' and `small' model:
13417 You can use this machine to dig up shrubs
13418 without hurting them.
13423 It can also dig up fully grown trees.
13426 Remember to replant promptly @dots{}
13430 In the example, the formatting commands will format the text between
13431 @code{@@ifset large} and @code{@@end ifset} because the @code{large}
13434 When @var{flag} is cleared, the Texinfo formatting commands do
13435 @emph{not} format the text between @code{@@ifset @var{flag}} and
13436 @code{@@end ifset}; that text is ignored and does not appear in either
13437 printed or Info output.
13439 For example, if you clear the flag of the preceding example by writing
13440 an @code{@@clear large} command after the @code{@@set large} command
13441 (but before the conditional text), then the Texinfo formatting commands
13442 ignore the text between the @code{@@ifset large} and @code{@@end ifset}
13443 commands. In the formatted output, that text does not appear; in both
13444 printed and Info output, you see only the lines that say, ``You can use
13445 this machine to dig up shrubs without hurting them. Remember to replant
13446 promptly @dots{}''.
13449 If a flag is cleared with an @code{@@clear @var{flag}} command, then
13450 the formatting commands format text between subsequent pairs of
13451 @code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
13452 is set with @code{@@set @var{flag}}, then the formatting commands do
13453 @emph{not} format text between an @code{@@ifclear} and an @code{@@end
13454 ifclear} command; rather, they ignore that text. An @code{@@ifclear}
13455 command looks like this:
13458 @@ifclear @var{flag}
13462 @node value Example
13463 @subsection @code{@@value} Example
13465 You can use the @code{@@value} command to minimize the number of
13466 places you need to change when you record an update to a manual.
13467 @xref{GNU Sample Texts}, for the full text of an example of using this
13468 to work with Automake distributions.
13470 This example is adapted from @ref{Top,, Overview, make, The GNU Make
13479 @@set EDITION 0.35 Beta
13480 @@set VERSION 3.63 Beta
13481 @@set UPDATED 14 August 1992
13482 @@set UPDATE-MONTH August 1992
13487 Write text for the @code{@@copying} section (@pxref{copying}):
13492 This is Edition @@value@{EDITION@},
13493 last updated @@value@{UPDATED@},
13494 of @@cite@{The GNU Make Manual@},
13495 for @@code@{make@}, version @@value@{VERSION@}.
13499 Permission is granted @dots{}
13505 Write text for the title page, for people reading the printed manual:
13511 @@subtitle A Program for Directing Recompilation
13512 @@subtitle Edition @@value@{EDITION@}, @dots{}
13513 @@subtitle @@value@{UPDATE-MONTH@}
13522 (On a printed cover, a date listing the month and the year looks less
13523 fussy than a date listing the day as well as the month and year.)
13526 Write text for the Top node, for people reading the Info file:
13540 After you format the manual, the @code{@@value} constructs have been
13541 expanded, so the output contains text like this:
13545 This is Edition 0.35 Beta, last updated 14 August 1992,
13546 of `The GNU Make Manual', for `make', Version 3.63 Beta.
13551 When you update the manual, you change only the values of the flags; you
13552 do not need to edit the three sections.
13555 @node Conditional Nesting
13556 @section Conditional Nesting
13557 @cindex Conditionals, nested
13558 @cindex Nesting conditionals
13560 Conditionals can be nested; however, the details are a little tricky.
13561 The difficulty comes with failing conditionals, such as
13562 @code{@@ifhtml} when HTML is not being produced, where the included
13563 text is to be ignored. However, it is not to be @emph{completely}
13564 ignored, since it is useful to have one @code{@@ifset} inside another,
13565 for example---that is a way to include text only if two conditions are
13566 met. Here's an example:
13571 Both somevar and anothervar are set.
13573 @@ifclear anothervar
13574 Somevar is set, anothervar is not.
13579 Technically, Texinfo requires that for a failing conditional, the
13580 ignored text must be properly nested with respect to that failing
13581 conditional. Unfortunately, it's not always feasible to check that
13582 @emph{all} conditionals are properly nested, because then the
13583 processors could have to fully interpret the ignored text, which
13584 defeats the purpose of the command. Here's an example illustrating
13590 @@ifclear ok - ok, ignored
13591 @@end junky - ok, ignored
13593 @@c WRONG - missing @@end ifset.
13596 Finally, as mentioned above, all conditional commands must be on lines
13597 by themselves, with no text (even spaces) before or after. Otherwise,
13598 the processors cannot reliably determine which commands to consider
13599 for nesting purposes.
13602 @node Internationalization
13603 @chapter Internationalization
13605 @cindex Internationalization
13606 Texinfo has some support for writing in languages other than English,
13607 although this area still needs considerable work.
13609 For a list of the various accented and special characters Texinfo
13610 supports, see @ref{Inserting Accents}.
13613 * documentlanguage:: Declaring the current language.
13614 * documentencoding:: Declaring the input encoding.
13618 @node documentlanguage
13619 @section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language
13621 @findex documentlanguage
13622 @cindex Language, declaring
13623 @cindex Locale, declaring
13624 @cindex Document language, declaring
13626 The @code{@@documentlanguage} command declares the current document
13627 locale. Write it on a line by itself, near the beginning of the
13628 file, but after @code{@@setfilename}
13629 (@pxref{setfilename,,@code{@@setfilename}}):
13632 @@documentlanguage @var{ll}[_@var{cc}]
13635 Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following
13636 the command name, optionally followed by an underscore and two-letter
13637 ISO@tie{}3166 two-letter country code (@var{cc}). If you have a
13638 multilingual document, the intent is to be able to use this command
13639 multiple times, to declare each language change. If the command is
13640 not used at all, the default is @code{en_US} for US English.
13642 As with GNU Gettext (@pxref{Top,,,gettext, Gettext}), if the country
13643 code is omitted, the main dialect is assumed where possible. For
13644 example, @code{de} is equivalent to @code{de_DE} (German as spoken in
13647 @cindex Document strings, translation of
13648 For Info and other online output, this command changes the translation
13649 of various @dfn{document strings} such as ``see'' in cross-references
13650 (@pxref{Cross References}), ``Function' in defuns (@pxref{Definition
13651 Commands}), and so on. Some strings, such as ``Node:'', ``Next:'',
13652 ``Menu:'', etc., are keywords in Info output, so are not translated
13653 there; they are translated in other output formats.
13655 @cindex @file{txi-@var{cc}.tex}
13656 For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to
13657 be read (if it exists). If @code{@@setdocumentlanguage} argument
13658 contains the optional @samp{_@var{cc}} suffix, this is tried first.
13659 For example, with @code{@@setdocumentlanguage de_DE}, @TeX{} first
13660 looks for @file{txi-de_DE.tex}, then @file{txi-de.tex}.
13662 Such a @file{txi-*} file is intended to redefine the various English
13663 words used in @TeX{} output, such as `Chapter', `See', and so on. We
13664 are aware that individual words like these cannot always be translated
13665 in isolation, and that a very different strategy would be required for
13666 ideographic (among other) scripts. Help in improving Texinfo's
13667 language support is welcome.
13669 @cindex Hyphenation patterns, language-dependent
13670 It would also be desirable for this command to also change @TeX{}'s
13671 ideas of the current hyphenation patterns (via the @TeX{} primitive
13672 @code{\language}), but this is unfortunately not currently
13675 In September 2006, the W3C Internationalization Activity released a
13676 new recommendation for specifying languages:
13677 @url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext
13678 supports this new scheme, Texinfo will too.
13680 @cindex ISO 639-2 language codes
13681 @cindex ISO 3166 country codes
13682 @cindex Language codes
13683 @cindex Country codes
13684 Since the lists of language codes and country codes are updated
13685 relatively frequently, we don't attempt to list them here. The valid
13686 language codes are on the official home page for ISO@tie{}639,
13687 @url{http://www.loc.gov/standards/iso639-2/}. The country codes and
13688 the official web site for ISO@tie{}3166 can be found via
13689 @url{http://en.wikipedia.org/wiki/ISO_3166}.
13692 @node documentencoding
13693 @section @code{@@documentencoding @var{enc}}: Set Input Encoding
13695 @findex documentencoding
13696 @cindex Encoding, declaring
13697 @cindex Input encoding, declaring
13698 @cindex Character set, declaring
13699 @cindex Document input encoding
13701 The @code{@@documentencoding} command declares the input document
13702 encoding. Write it on a line by itself, with a valid encoding
13703 specification following, near the beginning of the file but after
13704 @code{@@setfilename} (@pxref{setfilename,,@code{@@setfilename}}):
13707 @@documentencoding @var{enc}
13710 At present, Texinfo supports only these encodings:
13714 This has no particular effect, but it's included for completeness.
13717 The vast global character encoding, expressed in 8-bit bytes.
13718 The Texinfo processors have no deep knowledge of Unicode; for the most
13719 part, they just pass along the input they are given to the output.
13724 These specify the standard encodings for Western European (the first
13725 two) and Eastern European languages (the third), respectively. ISO
13726 8859-15 replaces some little-used characters from 8859-1 (e.g.,
13727 precomposed fractions) with more commonly needed ones, such as the
13728 Euro symbol (@euro{}).
13730 A full description of the encodings is beyond our scope here;
13731 one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
13734 This is the commonly used encoding for the Russian language.
13737 This is the commonly used encoding for the Ukrainian language.
13741 Specifying an encoding @var{enc} has the following effects:
13743 @opindex --enable-encoding
13744 @cindex Local Variables: section, for encoding
13745 @cindex Info output, and encoding
13746 In Info output, unless the option @option{--disable-encoding} is given
13747 to @command{makeinfo}, a so-called `Local Variables' section
13748 (@pxref{File Variables,,,emacs,The GNU Emacs Manual}) is output
13749 including @var{enc}. This allows Info readers to set the encoding
13758 Also, in Info and plain text output (barring
13759 @option{--disable-encoding}), accent constructs and special
13760 characters, such as @code{@@'e}, are output as the actual 8-bit
13761 character in the given encoding.
13763 @cindex HTML output, and encodings
13764 @cindex @code{http-equiv}, and charset specification
13765 @cindex @code{<meta>} HTML tag, and charset specification
13766 In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>}
13767 section of the HTML, that specifies @var{enc}. Web servers and
13768 browsers cooperate to use this information so the correct encoding is
13769 used to display the page, if supported by the system.
13772 <meta http-equiv="Content-Type" content="text/html;
13773 charset=@var{enc}">
13776 In split HTML output, if @option{--transliterate-file-names} is
13777 given (@pxref{HTML Xref 8-bit Character Expansion}), the names of HTML
13778 files are formed by transliteration of the corresponding node names,
13779 using the specified encoding.
13781 In XML and Docbook output, the given document encoding is written in
13782 the output file as usual with those formats.
13784 In @TeX{} output, the characters which are supported in the standard
13785 Computer Modern fonts are output accordingly. (For example, this
13786 means using constructed accents rather than precomposed glyphs.)
13787 Using a missing character generates a warning message, as does
13788 specifying an unimplemented encoding.
13791 @node Defining New Texinfo Commands
13792 @chapter Defining New Texinfo Commands
13794 @cindex Defining new Texinfo commands
13795 @cindex New Texinfo commands, defining
13796 @cindex Texinfo commands, defining new
13797 @cindex User-defined Texinfo commands
13799 Texinfo provides several ways to define new commands:
13803 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
13804 sequence of text and/or existing commands (including other macros). The
13805 macro can have any number of @dfn{parameters}---text you supply each
13806 time you use the macro.
13808 Incidentally, these macros have nothing to do with the @code{@@defmac}
13809 command, which is for documenting macros in the subject of the manual
13810 (@pxref{Def Cmd Template}).
13813 @samp{@@alias} is a convenient way to define a new name for an existing
13817 @samp{@@definfoenclose} allows you to define new commands with
13818 customized output in the Info file.
13823 * Defining Macros:: Defining and undefining new commands.
13824 * Invoking Macros:: Using a macro, once you've defined it.
13825 * Macro Details:: Limitations of Texinfo macros.
13826 * alias:: Command aliases.
13827 * definfoenclose:: Customized highlighting.
13831 @node Defining Macros
13832 @section Defining Macros
13833 @cindex Defining macros
13834 @cindex Macro definitions
13837 You use the Texinfo @code{@@macro} command to define a macro, like this:
13840 @@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
13841 @var{text} @dots{} \@var{param1}\ @dots{}
13845 The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
13846 arguments supplied when the macro is subsequently used in the document
13847 (described in the next section).
13849 @cindex Macro names, valid characters in
13850 @cindex Names of macros, valid characters of
13851 For a macro to work consistently with @TeX{}, @var{macroname} must
13852 consist entirely of letters: no digits, hyphens, underscores, or other
13853 special characters. So, we recommend using only letters. However,
13854 @command{makeinfo} will accept anything except @samp{@{@}_^=};
13855 @samp{_} and @samp{^} are excluded so that macros can be called in
13856 @code{@@math} mode without a following space
13857 (@pxref{math,,@code{@@math}}).
13859 If a macro needs no parameters, you can define it either with an empty
13860 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
13863 @cindex Body of a macro
13864 @cindex Mutually recursive macros
13865 @cindex Recursion, mutual
13866 The definition or @dfn{body} of the macro can contain most Texinfo
13867 commands, including previously-defined macros. Not-yet-defined macro
13868 invocations are not allowed; thus, it is not possible to have mutually
13869 recursive Texinfo macros. Also, a macro definition that defines another
13870 macro does not work in @TeX{} due to limitations in the design of
13873 @cindex Parameters to macros
13874 In the macro body, instances of a parameter name surrounded by
13875 backslashes, as in @samp{\@var{param1}\} in the example above, are
13876 replaced by the corresponding argument from the macro invocation. You
13877 can use parameter names any number of times in the body, including zero.
13879 @cindex Backslash in macros
13880 To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
13881 other use of @samp{\} in the body yields a warning.
13883 @cindex Spaces in macros
13884 @cindex Whitespace in macros
13885 The newlines after the @code{@@macro} line and before the @code{@@end
13886 macro} line are ignored, that is, not included in the macro body. All
13887 other whitespace is treated according to the usual Texinfo rules.
13889 @cindex Recursive macro invocations
13891 To allow a macro to be used recursively, that is, in an argument to a
13892 call to itself, you must define it with @samp{@@rmacro}, like this:
13895 @@rmacro rmac @{arg@}
13899 @@rmac@{1@@rmac@{text@}2@}
13902 This produces the output `a1atextb2b'. With @samp{@@macro} instead of
13903 @samp{@@rmacro}, an error message is given.
13906 @cindex Macros, undefining
13907 @cindex Undefining macros
13908 You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
13909 It is not an error to undefine a macro that is already undefined.
13917 @node Invoking Macros
13918 @section Invoking Macros
13919 @cindex Invoking macros
13920 @cindex Expanding macros
13921 @cindex Running macros
13922 @cindex Macro invocation
13924 After a macro is defined (see the previous section), you can use
13925 (@dfn{invoke}) it in your document like this:
13928 @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
13931 @noindent and the result will be just as if you typed the body of
13932 @var{macroname} at that spot. For example:
13935 @@macro foo @{p, q@}
13936 Together: \p\ & \q\.
13941 @noindent produces:
13947 @cindex Backslash, and macros
13948 Thus, the arguments and parameters are separated by commas and delimited
13949 by braces; any whitespace after (but not before) a comma is ignored.
13950 The braces are required in the invocation (but not the definition), even
13951 when the macro takes no arguments, consistent with all other Texinfo
13952 commands. For example:
13955 @@macro argless @{@}
13961 @noindent produces:
13967 @cindex Comma, in macro arguments
13968 Passing strings containing commas as macro arguments requires special
13969 care, since they should be properly @dfn{quoted} to prevent
13970 @command{makeinfo} from confusing them with argument separators. To
13971 manually quote a comma, prepend it with a backslash character, like
13972 this: @code{\,}. Alternatively, use the @code{@@comma} command
13973 (@pxref{Inserting a Comma}). However, to facilitate use of macros,
13974 @command{makeinfo} implements a set of rules called @dfn{automatic
13978 @item If a macro takes only one argument, all commas in its invocation
13979 are quoted by default. For example:
13983 @@macro FIXME@{text@}
13984 @@strong@{FIXME: \text\@}
13987 @@FIXME@{A nice feature, though it can be dangerous.@}
13992 will produce the following output
13995 @strong{FIXME: A nice feature, though it can be dangerous.}
13998 And indeed, it can. Namely, @command{makeinfo}
13999 does not control number of arguments passed to one-argument
14000 macros, so be careful when you invoke them.
14002 @item If a macro invocation includes another command (including a
14003 recursive invocation of itself), any commas in the nested command
14004 invocation(s) are quoted by default. For example, in
14007 @@say@{@@strong@{Yes, I do@}, person one@}
14010 the comma after @samp{Yes} is implicitly quoted. Here's another
14011 example, with a recursive macro:
14015 @@rmacro cat@{a,b@}
14019 @@cat@{@@cat@{foo, bar@}, baz@}
14024 will produce the string @samp{foobarbaz}.
14026 @item Otherwise, a comma should be explicitly quoted, as above, to be
14027 treated as a part of an argument.
14030 @cindex Braces, in macro arguments
14031 Other characters that need to be quoted in macro arguments are
14032 curly braces and backslash. For example
14035 @@@var{macname} @{\\\@{\@}\,@}
14039 will pass the (almost certainly error-producing) argument
14040 @samp{\@{@},} to @var{macname}. However, commas in parameters, even
14041 if escaped by a backslash, might cause trouble in @TeX{}.
14043 If the macro is defined to take a single argument, and is invoked
14044 without any braces, the entire rest of the line after the macro name is
14045 supplied as the argument. For example:
14054 @noindent produces:
14056 @c Sorry for cheating, but let's not require macros to process the manual.
14061 If the macro is defined to take a single argument, and is invoked with
14062 braces, the braced text is passed as the argument, regardless of
14063 commas. For example:
14072 @noindent produces:
14079 @node Macro Details
14080 @section Macro Details and Caveats
14081 @cindex Macro details
14082 @cindex Details of macro usage
14083 @cindex Caveats for macro usage
14085 Due to unavoidable limitations, certain macro-related constructs cause
14086 problems with @TeX{}. If you get macro-related errors when producing
14087 the printed version of a manual, try expanding the macros with
14088 @command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E}
14089 option (@pxref{Format with texi2dvi}).
14093 As mentioned earlier, macro names must consist entirely of letters.
14096 It is not advisable to redefine any @TeX{} primitive, plain, or
14097 Texinfo command name as a macro. Unfortunately this is a very large
14098 set of names, and the possible resulting errors are unpredictable.
14101 All macros are expanded inside at least one @TeX{} group. This means
14102 that @code{@@set} and other such commands have no effect inside a
14106 Commas in macro arguments, even if escaped by a backslash, don't
14110 Macro arguments cannot cross lines.
14113 It is (usually) best to avoid comments inside macro definitions, but
14117 Macros containing a command which must be on a line by itself, such as
14118 a conditional, cannot be invoked in the middle of a line. In general,
14119 the interaction of newlines in the macro definitions and invocations
14120 depends on the precise commands and context. You may be able to work
14121 around some problems with judicious use of @code{@@c}. Suppose you
14122 define a macro that is always intended to be used on a line by itself:
14135 Without the @code{@@c}, there will be an unwanted blank line between
14136 the @samp{@@cindex whatever} and the @samp{bar} (one newline comes
14137 from the macro definition, one from after the invocation), causing a
14140 On the other hand, you wouldn't want the @code{@@c} if the macro was
14141 sometimes invoked in the middle of a line (the text after the
14142 invocation would be treated as a comment).
14145 In general, you can't arbitrarily substitute a macro call for Texinfo
14146 command arguments, even when the text is the same. It might work with
14147 some commands, it fails with others. Best not to do it at all. For
14148 instance, this fails:
14154 @@headings @@offmacro
14158 You would expect this to be equivalent to @code{@@headings off}, but
14159 for @TeX{}nical reasons, it fails with a mysterious error message
14160 (@code{Paragraph ended before @@headings was complete}).
14163 Macros cannot define macros in the natural way. To do this, you must
14164 use conditionals and raw @TeX{}. For example:
14168 @@macro ctor @{name, arg@}
14170 something involving \arg\ somehow
14175 \gdef\ctor#1@{\ctorx#1,@}
14176 \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
14182 The @command{makeinfo} implementation also has limitations:
14186 @code{@@verbatim} and macros do not mix; for instance, you can't start
14187 a verbatim block inside a macro and end it outside.
14188 (@xref{verbatim}.) Starting any environment inside a macro and ending
14189 it outside may or may not work, for that matter.
14192 Macros that completely define macros are ok, but it's not possible to
14193 have incorrectly nested macro definitions. That is, @code{@@macro}
14194 and @code{@@end macro} (likewise for @code{@@rmacro}) must be
14195 correctly paired. For example, you cannot start a macro definition
14196 within a macro, and then end the nested definition outside the macro.
14199 @code{@@rmacro} is a kludge.
14203 One more limitation is common to both implementations: white space is
14204 ignored at the beginnings of lines.
14206 Future major revisions of Texinfo may ease some of these limitations
14207 (by introducing a new macro syntax).
14211 @section @samp{@@alias @var{new}=@var{existing}}
14212 @cindex Aliases, command
14213 @cindex Command aliases
14216 The @samp{@@alias} command defines a new command to be just like an
14217 existing one. This is useful for defining additional markup names, thus
14218 preserving semantic information in the input even though the output
14219 result may be the same.
14221 Write the @samp{@@alias} command on a line by itself, followed by the
14222 new command name, an equals sign, and the existing command name.
14223 Whitespace around the equals sign is ignored. Thus:
14225 @@alias @var{new} = @var{existing}
14228 For example, if your document contains citations for both books and
14229 some other media (movies, for example), you might like to define a
14230 macro @code{@@moviecite@{@}} that does the same thing as an ordinary
14231 @code{@@cite@{@}} but conveys the extra semantic information as well.
14232 You'd do this as follows:
14235 @@alias moviecite = cite
14238 Macros do not always have the same effect as aliases, due to vagaries
14239 of argument parsing. Also, aliases are much simpler to define than
14240 macros. So the command is not redundant. (It was also heavily used
14241 in the Jargon File!)
14243 Aliases must not be recursive, directly or indirectly.
14245 It is not advisable to redefine any @TeX{} primitive, plain, or
14246 Texinfo command name as an alias. Unfortunately this is a very large
14247 set of names, and the possible resulting errors are completely random.
14250 @node definfoenclose
14251 @section @samp{definfoenclose}: Customized Highlighting
14252 @cindex Highlighting, customized
14253 @cindex Customized highlighting
14254 @findex definfoenclose
14256 A @code{@@definfoenclose} command may be used to define a highlighting
14257 command for Info, but not for @TeX{}. A command defined using
14258 @code{@@definfoenclose} marks text by enclosing it in strings that
14259 precede and follow the text. You can use this to get closer control of
14262 Presumably, if you define a command with @code{@@definfoenclose} for Info,
14263 you will create a corresponding command for @TeX{}, either in
14264 @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
14267 Write a @code{@@definfoenclose} command on a line and follow it with
14268 three arguments separated by commas. The first argument to
14269 @code{@@definfoenclose} is the @@-command name (without the @code{@@});
14270 the second argument is the Info start delimiter string; and the third
14271 argument is the Info end delimiter string. The latter two arguments
14272 enclose the highlighted text in the Info file. A delimiter string may
14273 contain spaces. Neither the start nor end delimiter is required. If
14274 you do not want a start delimiter but do want an end delimiter, you must
14275 follow the command name with two commas in a row; otherwise, the Info
14276 formatting commands will naturally misinterpret the end delimiter string
14277 you intended as the start delimiter string.
14279 If you do a @code{@@definfoenclose} on the name of a predefined macro
14280 (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
14281 enclosure definition will override the built-in definition.
14283 An enclosure command defined this way takes one argument in braces; this
14284 is intended for new markup commands (@pxref{Marking Text}).
14287 For example, you can write:
14290 @@definfoenclose phoo,//,\\
14294 near the beginning of a Texinfo file to define @code{@@phoo} as an Info
14295 formatting command that inserts `//' before and `\\' after the argument
14296 to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
14297 want `//bar\\' highlighted in Info.
14299 Also, for @TeX{} formatting, you could write
14303 @@global@@let@@phoo=@@i
14308 to define @code{@@phoo} as a command that causes @TeX{} to typeset the
14309 argument to @code{@@phoo} in italics.
14311 Each definition applies to its own formatter: one for @TeX{}, the other
14312 for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
14313 @code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
14314 the raw @TeX{} commands do need to be in @samp{@@iftex}.
14317 Here is another example: write
14320 @@definfoenclose headword, , :
14324 near the beginning of the file, to define @code{@@headword} as an Info
14325 formatting command that inserts nothing before and a colon after the
14326 argument to @code{@@headword}.
14328 @samp{@@definfoenclose} definitions must not be recursive, directly or
14333 @chapter Formatting and Printing Hardcopy
14334 @cindex Format and print hardcopy
14335 @cindex Printing hardcopy
14336 @cindex Hardcopy, printing it
14337 @cindex Making a printed manual
14338 @cindex Sorting indices
14339 @cindex Indices, sorting
14340 @cindex @TeX{} index sorting
14343 There are three major shell commands for making a printed manual from a
14344 Texinfo file: one for converting the Texinfo file into a file that will be
14345 printed, a second for sorting indices, and a third for printing the
14346 formatted document. When you use the shell commands, you can either
14347 work directly in the operating system shell or work within a shell
14350 If you are using GNU Emacs, you can use commands provided by Texinfo
14351 mode instead of shell commands. In addition to the three commands to
14352 format a file, sort the indices, and print the result, Texinfo mode
14353 offers key bindings for commands to recenter the output buffer, show the
14354 print queue, and delete a job from the print queue.
14357 * Use TeX:: Use @TeX{} to format for hardcopy.
14358 * Format with tex/texindex:: How to format with explicit shell commands.
14359 * Format with texi2dvi:: A simpler way to format.
14360 * Print with lpr:: How to print.
14361 * Within Emacs:: How to format and print from an Emacs shell.
14362 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
14363 * Compile-Command:: How to print using Emacs's compile command.
14364 * Requirements Summary:: @TeX{} formatting requirements summary.
14365 * Preparing for TeX:: What to do before you use @TeX{}.
14366 * Overfull hboxes:: What are and what to do with overfull hboxes.
14367 * smallbook:: How to print small format books and manuals.
14368 * A4 Paper:: How to print on A4 or A5 paper.
14369 * pagesizes:: How to print with customized page sizes.
14370 * Cropmarks and Magnification:: How to print marks to indicate the size
14371 of pages and how to print scaled up output.
14372 * PDF Output:: Portable Document Format output.
14373 * Obtaining TeX:: How to Obtain @TeX{}.
14377 @section Use @TeX{}
14379 The typesetting program called @TeX{} is used for formatting a Texinfo
14380 file. @TeX{} is a very powerful typesetting program and, if used correctly,
14381 does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
14382 @TeX{}}, for information on how to obtain @TeX{}.)
14384 The standalone @code{makeinfo} program and Emacs functions
14385 @code{texinfo-format-region} and @code{texinfo-format-buffer} commands
14386 read the very same @@-commands in the Texinfo file as does @TeX{}, but
14387 process them differently to make an Info file (@pxref{Creating an Info
14391 @node Format with tex/texindex
14392 @section Format with @code{tex} and @code{texindex}
14393 @cindex Shell formatting with @code{tex} and @code{texindex}
14394 @cindex Formatting with @code{tex} and @code{texindex}
14397 You can format the Texinfo file with the shell command @code{tex}
14398 followed by the name of the Texinfo file. For example:
14404 @noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
14405 files containing information for indices, cross references, etc. The
14406 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
14407 any device (see the following sections).
14410 The @code{tex} formatting command itself does not sort the indices; it
14411 writes an output file of unsorted index data. To generate a printed
14412 index after running the @command{tex} command, you first need a sorted
14413 index to work from. The @command{texindex} command sorts indices.
14414 (The source file @file{texindex.c} comes as part of the standard
14415 Texinfo distribution, among other places.) (@command{texi2dvi} runs
14416 @command{tex} and @command{texindex} as necessary.)
14418 @cindex Names of index files
14419 @cindex Index file names
14420 The @code{tex} formatting command outputs unsorted index files under
14421 names that obey a standard convention: the name of your main input file
14422 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
14423 Web2c}) extension removed, followed by the two letter names of indices.
14424 For example, the raw index output files for the input file
14425 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
14426 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
14427 arguments to give to @code{texindex}.
14432 Instead of specifying all the unsorted index file names explicitly, you
14433 can use @samp{??} as shell wildcards and give the command in this
14441 This command will run @code{texindex} on all the unsorted index files,
14442 including any that you have defined yourself using @code{@@defindex}
14443 or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
14444 even if there are similarly named files with two letter extensions
14445 that are not index files, such as @samp{foo.el}. The @code{texindex}
14446 command reports but otherwise ignores such files.)
14448 For each file specified, @code{texindex} generates a sorted index file
14449 whose name is made by appending @samp{s} to the input file name. The
14450 @code{@@printindex} command looks for a file with that name
14451 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
14452 raw index output file.
14454 After you have sorted the indices, you need to rerun @code{tex} on the
14455 Texinfo file. This regenerates the DVI file, this time with
14456 up-to-date index entries.
14458 Finally, you may need to run @code{tex} one more time, to get the page
14459 numbers in the cross-references correct.
14461 To summarize, this is a five step process:
14465 Run @code{tex} on your Texinfo file. This generates a DVI file (with
14466 undefined cross-references and no indices), and the raw index files
14467 (with two letter extensions).
14470 Run @code{texindex} on the raw index files. This creates the
14471 corresponding sorted index files (with three letter extensions).
14474 Run @code{tex} again on your Texinfo file. This regenerates the DVI
14475 file, this time with indices and defined cross-references, but with page
14476 numbers for the cross-references from last time, generally incorrect.
14479 Sort the indices again, with @code{texindex}.
14482 Run @code{tex} one last time. This time the correct page numbers are
14483 written for the cross-references.
14487 Alternatively, it's a one-step process: run @code{texi2dvi}
14488 (@pxref{Format with texi2dvi}).
14490 You need not run @code{texindex} each time after you run @code{tex}. If
14491 you do not, on the next run, the @code{tex} formatting command will use
14492 whatever sorted index files happen to exist from the previous use of
14493 @code{texindex}. This is usually ok while you are debugging.
14495 @cindex Auxiliary files, avoiding
14497 @cindex Pointer validation, suppressing
14498 @cindex Chapters, formatting one at a time
14499 Sometimes you may wish to print a document while you know it is
14500 incomplete, or to print just one chapter of a document. In that case,
14501 the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
14502 when cross-references are not satisfied are just nuisances. You can
14503 avoid them with the @code{@@novalidate} command, which you must give
14504 @emph{before} the @code{@@setfilename} command
14505 (@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
14506 your file would look approximately like this:
14511 @@setfilename myfile.info
14515 @noindent @code{@@novalidate} also turns off validation in
14516 @code{makeinfo}, just like its @code{--no-validate} option
14517 (@pxref{Pointer Validation}).
14520 @node Format with texi2dvi
14521 @section Format with @code{texi2dvi}
14522 @pindex texi2dvi @r{(shell script)}
14524 The @code{texi2dvi} command automatically runs both @TeX{} and
14525 @command{texindex} as many times as necessary to produce a DVI file
14526 with sorted indices and all cross-references resolved. It is
14527 therefore simpler than manually executing the
14528 @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
14529 described in the previous section.
14531 To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
14532 @samp{prompt$ } is your shell prompt):
14535 prompt$ @kbd{texi2dvi foo.texi}
14538 As shown in this example, the input filenames to @code{texi2dvi} must
14539 include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
14540 MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
14541 texi2dvi foo.texi} instead of relying on the operating system to invoke
14542 the shell on the @samp{texi2dvi} script.
14544 @opindex --command @r{(@command{texi2dvi})}
14545 One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}.
14546 This inserts @var{cmd} on a line by itself after the
14547 @code{@@setfilename} in a temporary copy of the input file before
14548 running @TeX{}. With this, you can specify different printing
14549 formats, such as @code{@@smallbook} (@pxref{smallbook}),
14550 @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
14551 (@pxref{pagesizes}), without actually changing the document source.
14552 (You can also do this on a site-wide basis with @file{texinfo.cnf};
14553 @pxref{Preparing for TeX,,Preparing for @TeX{}}).
14555 @opindex --pdf @r{(@command{texi2dvi})}
14556 With the @option{--pdf} option, @command{texi2dvi} produces PDF output
14557 instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
14558 instead of @command{tex}. Alternatively, the command
14559 @command{texi2pdf} is an abbreviation for running @samp{texi2dvi
14560 --pdf}. The command @command{pdftexi2dvi} is also supported as a
14561 convenience to AUC-@TeX{} users, since the latter merely prepends
14562 @samp{pdf} to DVI producing tools to have PDF producing tools.
14564 @cindex @LaTeX{}, processing with @command{texi2dvi}
14565 @command{texi2dvi} can also be used to process @LaTeX{} files; simply
14566 run @samp{texi2dvi filename.ext}.
14568 @opindex --language @r{(@command{texi2dvi})}
14569 Normally @command{texi2dvi} is able to guess the input file language
14570 by its contents and file name suffix. If, however, it fails to do so
14571 you can specify the input language using
14572 @option{--language=@var{lang}} command line option, where @var{lang}
14573 is either @samp{latex} or @samp{texinfo}.
14575 @command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if
14576 they are available; these extended versions of @TeX{} are not
14577 required, and the DVI (or PDF) output is identical, but they simplify
14578 the @TeX{} programming in some cases, and provide additional tracing
14579 information when debugging @file{texinfo.tex}.
14581 @opindex --translate-file @r{(@command{texi2dvi})}
14582 Several options are provided for handling documents, written in
14583 character sets other than ASCII. The
14584 @option{--translate-file=@var{file}} option instructs
14585 @command{texi2dvi} to translate input into internal @TeX{} character
14586 set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX
14587 files, TCX files: Character translations, web2c, Web2c: A @TeX{}
14590 @opindex --recode @r{(@command{texi2dvi})}
14591 The options @option{--recode} and @option{--recode-from=@var{enc}}
14592 allow conversion of an input document before running @TeX{}. The
14593 @option{--recode} option recodes the document from encoding specified
14594 by @samp{@@documentencoding} command
14595 (@pxref{documentencoding,,@code{documentencoding}}) to plain 7-bit
14596 @samp{texinfo} encoding.
14598 @opindex --recode-from @r{(@command{texi2dvi})}
14599 The option @option{--recode-from=@var{enc}} recodes the document from
14600 @var{enc} encoding to the encoding specified by
14601 @samp{@@documentencoding}. This is useful, for example, if the
14602 document is written in @samp{UTF-8} encoding and an equivalent 8-bit
14603 encoding is supported by @command{makeinfo}.
14605 Both @option{--recode} and @option{--recode-from=@var{enc}} use
14606 @command{recode} utility to perform the conversion. If
14607 @command{recode} fails to process the file, @command{texi2dvi} prints
14608 a warning and continues using unmodified input file.
14610 For a list of other options, run @samp{texi2dvi --help}.
14613 @node Print with lpr
14614 @section Shell Print Using @code{lpr -d}
14615 @pindex lpr @r{(DVI print command)}
14617 The precise command to print a DVI file depends on your system
14618 installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
14621 For example, the following commands will (perhaps) suffice to sort the
14622 indices, format, and print the @cite{Bison Manual}:
14634 (Remember that the shell commands may be different at your site; but
14635 these are commonly used versions.)
14637 Using the @code{texi2dvi} shell script (see the previous section):
14641 texi2dvi bison.texinfo
14643 # or perhaps dvips bison.dvi -o
14647 @cindex Shell printing, on MS-DOS/MS-Windows
14648 @cindex Printing DVI files, on MS-DOS/MS-Windows
14649 @pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
14650 @code{lpr} is a standard program on Unix systems, but it is usually
14651 absent on MS-DOS/MS-Windows. Some network packages come with a
14652 program named @code{lpr}, but these are usually limited to sending files
14653 to a print server over the network, and generally don't support the
14654 @samp{-d} option. If you are unfortunate enough to work on one of these
14655 systems, you have several alternative ways of printing DVI files:
14658 @item Find and install a Unix-like @code{lpr} program, or its clone.
14659 If you can do that, you will be able to print DVI files just like
14662 @item Send the DVI files to a network printer queue for DVI files.
14663 Some network printers have special queues for printing DVI files. You
14664 should be able to set up your network software to send files to that
14665 queue. In some cases, the version of @code{lpr} which comes with your
14666 network software will have a special option to send a file to specific
14670 lpr -Qdvi -hprint.server.domain bison.dvi
14673 @item Convert the DVI file to a Postscript or PCL file and send it to your
14674 local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man
14675 pages for @code{dvilj}, for detailed description of these tools. Once
14676 the DVI file is converted to the format your local printer understands
14677 directly, just send it to the appropriate port, usually @samp{PRN}.
14682 @section From an Emacs Shell
14683 @cindex Print, format from Emacs shell
14684 @cindex Format, print from Emacs shell
14685 @cindex Shell, format, print from
14686 @cindex Emacs shell, format, print from
14687 @cindex GNU Emacs shell, format, print from
14689 You can give formatting and printing commands from a shell within GNU
14690 Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this
14691 shell, you can format and print the document. @xref{Hardcopy, , Format
14692 and Print Hardcopy}, for details.
14694 You can switch to and from the shell buffer while @code{tex} is
14695 running and do other editing. If you are formatting a long document
14696 on a slow machine, this can be very convenient.@refill
14698 You can also use @code{texi2dvi} from an Emacs shell. For example,
14699 here is how to use @code{texi2dvi} to format and print @cite{Using and
14700 Porting GNU CC} from a shell within Emacs:
14704 texi2dvi gcc.texinfo
14709 See the next section for more information about formatting
14710 and printing in Texinfo mode.
14713 @node Texinfo Mode Printing
14714 @section Formatting and Printing in Texinfo Mode
14715 @cindex Region printing in Texinfo mode
14716 @cindex Format and print in Texinfo mode
14717 @cindex Print and format in Texinfo mode
14719 Texinfo mode provides several predefined key commands for @TeX{}
14720 formatting and printing. These include commands for sorting indices,
14721 looking at the printer queue, killing the formatting job, and
14722 recentering the display of the buffer in which the operations
14727 @itemx M-x texinfo-tex-buffer
14728 Run @code{texi2dvi} on the current buffer.@refill
14731 @itemx M-x texinfo-tex-region
14732 Run @TeX{} on the current region.@refill
14735 @itemx M-x texinfo-texindex
14736 Sort the indices of a Texinfo file formatted with
14737 @code{texinfo-tex-region}.@refill
14740 @itemx M-x texinfo-tex-print
14741 Print a DVI file that was made with @code{texinfo-tex-region} or
14742 @code{texinfo-tex-buffer}.@refill
14745 @itemx M-x tex-show-print-queue
14746 Show the print queue.@refill
14749 @itemx M-x texinfo-delete-from-print-queue
14750 Delete a job from the print queue; you will be prompted for the job
14751 number shown by a preceding @kbd{C-c C-t C-q} command
14752 (@code{texinfo-show-tex-print-queue}).@refill
14755 @itemx M-x tex-kill-job
14756 Kill the currently running @TeX{} job started by either
14757 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
14758 process running in the Texinfo shell buffer.@refill
14761 @itemx M-x texinfo-quit-job
14762 Quit a @TeX{} formatting job that has stopped because of an error by
14763 sending an @key{x} to it. When you do this, @TeX{} preserves a record
14764 of what it did in a @file{.log} file.@refill
14767 @itemx M-x tex-recenter-output-buffer
14768 Redisplay the shell buffer in which the @TeX{} printing and formatting
14769 commands are run to show its most recent output.@refill
14773 Thus, the usual sequence of commands for formatting a buffer is as
14774 follows (with comments to the right):@refill
14778 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
14779 C-c C-t C-p @r{Print the DVI file.}
14780 C-c C-t C-q @r{Display the printer queue.}
14784 The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
14785 called the @file{*tex-shell*}. The @code{texinfo-tex-command},
14786 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
14787 commands are all run in this shell.
14789 You can watch the commands operate in the @samp{*tex-shell*} buffer,
14790 and you can switch to and from and use the @samp{*tex-shell*} buffer
14791 as you would any other shell buffer.@refill
14794 The formatting and print commands depend on the values of several variables.
14795 The default values are:@refill
14799 @r{Variable} @r{Default value}
14801 texinfo-texi2dvi-command "texi2dvi"
14802 texinfo-tex-command "tex"
14803 texinfo-texindex-command "texindex"
14804 texinfo-delete-from-print-queue-command "lprm"
14805 texinfo-tex-trailer "@@bye"
14806 tex-start-of-header "%**start"
14807 tex-end-of-header "%**end"
14808 tex-dvi-print-command "lpr -d"
14809 tex-show-queue-command "lpq"
14813 You can change the values of these variables with the @kbd{M-x
14814 set-variable} command (@pxref{Examining, , Examining and Setting
14815 Variables, emacs, The GNU Emacs Manual}), or with your @file{.emacs}
14816 initialization file (@pxref{Init File, , , emacs, The GNU Emacs
14819 @cindex Customize Emacs package (@t{Development/Docs/Texinfo})
14820 Beginning with version 20, GNU Emacs offers a user-friendly interface,
14821 called @dfn{Customize}, for changing values of user-definable variables.
14822 @xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
14823 Emacs Manual}, for more details about this. The Texinfo variables can
14824 be found in the @samp{Development/Docs/Texinfo} group, once you invoke
14825 the @kbd{M-x customize} command.
14828 @node Compile-Command
14829 @section Using the Local Variables List
14830 @cindex Local variables
14831 @cindex Compile command for formatting
14832 @cindex Format with the compile command
14834 Yet another way to apply the @TeX{} formatting command to a Texinfo file
14835 is to put that command in a @dfn{local variables list} at the end of the
14836 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
14837 commands as a @code{compile-command} and have Emacs run it by typing
14838 @kbd{M-x compile}. This creates a special shell called the
14839 @file{*compilation*} buffer in which Emacs runs the compile command.
14840 For example, at the end of the @file{gdb.texinfo} file, after the
14841 @code{@@bye}, you could put the following:@refill
14846 compile-command: "texi2dvi gdb.texinfo"
14852 This technique is most often used by programmers who also compile programs
14853 this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
14856 @node Requirements Summary
14857 @section @TeX{} Formatting Requirements Summary
14858 @cindex Requirements for formatting
14859 @cindex Minimal requirements for formatting
14860 @cindex Formatting requirements
14862 Every Texinfo file that is to be input to @TeX{} must begin with a
14863 @code{\input} command and must contain an @code{@@setfilename} command:
14867 @@setfilename @var{arg-not-used-by-@TeX{}}
14871 The first command instructs @TeX{} to load the macros it needs to
14872 process a Texinfo file and the second command opens auxiliary files.
14874 Every Texinfo file must end with a line that terminates @TeX{}'s
14875 processing and forces out unfinished pages:
14881 Strictly speaking, these lines are all a Texinfo file needs to be
14882 processed successfully by @TeX{}.
14884 Usually, however, the beginning includes an @code{@@settitle} command to
14885 define the title of the printed manual, an @code{@@setchapternewpage}
14886 command, a title page, a copyright page, and permissions. Besides an
14887 @code{@@bye}, the end of a file usually includes indices and a table of
14888 contents. (And of course most manuals contain a body of text as well.)
14890 For more information, see:
14893 @item @ref{settitle, , @code{@@settitle}}.
14894 @item @ref{setchapternewpage, , @code{@@setchapternewpage}}.
14895 @item @ref{Headings, ,Page Headings}.
14896 @item @ref{Titlepage & Copyright Page}.
14897 @item @ref{Printing Indices & Menus}.
14898 @item @ref{Contents}.
14902 @node Preparing for TeX
14903 @section Preparing for @TeX{}
14904 @cindex Preparing for @TeX{}
14905 @cindex @TeX{} input initialization
14906 @cindex @b{.profile} initialization file
14907 @cindex @b{.cshrc} initialization file
14908 @cindex Initialization file for @TeX{} input
14910 @TeX{} needs to know where to find the @file{texinfo.tex} file that the
14911 @samp{\input texinfo} command on the first line reads. The
14912 @file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
14913 included in all standard GNU distributions. The latest version is
14914 always available from the Texinfo source repository:
14916 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD}
14919 @pindex texinfo.tex@r{, installing}
14921 Usually, the installer has put the @file{texinfo.tex} file in the
14922 default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
14923 other GNU software is installed. In this case, @TeX{} will find the
14924 file and you do not need to do anything special. If this has not been
14925 done, you can put @file{texinfo.tex} in the current directory when you
14926 run @TeX{}, and @TeX{} will find it there.
14928 @pindex epsf.tex@r{, installing}
14929 Also, you should install @file{epsf.tex}, if it is not already installed
14930 from another distribution. More details are at the end of the description
14931 of the @code{@@image} command (@pxref{Images}).
14933 @cindex European Computer Modern fonts, installing
14934 @cindex EC fonts, installing
14935 @cindex CM-Super fonts, installing
14936 To be able to use quotation marks other than those used in English
14937 you'll need to install European Computer Modern fonts and optionally
14938 CM-Super fonts, unless they are already installed (@pxref{Inserting
14941 @pindex feymr10@r{, installing}
14942 @cindex Euro font, installing
14943 If you intend to use the @code{@@euro} command, you should install the
14944 Euro font, if it is not already installed. @xref{euro}.
14946 @pindex texinfo.cnf @r{installation}
14947 @cindex Customizing of @TeX{} for Texinfo
14948 @cindex Site-wide Texinfo configuration file
14949 Optionally, you may create an additional @file{texinfo.cnf}, and install
14950 it as well. This file is read by @TeX{} when the @code{@@setfilename}
14951 command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any
14952 commands you like there, according to local site-wide conventions. They
14953 will be read by @TeX{} when processing any Texinfo document. For
14954 example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
14955 (@pxref{A4 Paper}), then all Texinfo documents will be processed with
14956 that page size in effect. If you have nothing to put in
14957 @file{texinfo.cnf}, you do not need to create it.
14959 @cindex Environment variable @code{TEXINPUTS}
14961 If neither of the above locations for these system files suffice for
14962 you, you can specify the directories explicitly. For
14963 @file{texinfo.tex}, you can do this by writing the complete path for the
14964 file after the @code{\input} command. Another way, that works for both
14965 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
14966 might read), is to set the @code{TEXINPUTS} environment variable in your
14967 @file{.cshrc} or @file{.profile} file.
14969 Which you use of @file{.cshrc} or @file{.profile} depends on
14970 whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
14971 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
14972 command interpreter. The latter read the @file{.cshrc} file for
14973 initialization information, and the former read @file{.profile}.
14975 In a @file{.cshrc} file, you could use the following @code{csh} command
14979 setenv TEXINPUTS .:/home/me/mylib:
14983 In a @file{.profile} file, you could use the following @code{sh} command
14988 TEXINPUTS=.:/home/me/mylib:
14993 On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
14994 of the @samp{;} character, instead of @samp{:}, as directory separator
14995 on these systems.}:
14999 set TEXINPUTS=.;d:/home/me/mylib;c:
15004 It is customary for DOS/Windows users to put such commands in the
15005 @file{autoexec.bat} file, or in the Windows Registry.
15008 These settings would cause @TeX{} to look for @file{\input} file first
15009 in the current directory, indicated by the @samp{.}, then in a
15010 hypothetical user @samp{me}'s @file{mylib} directory, and finally in
15011 the system directories. (A leading, trailing, or doubled @samp{:}
15012 indicates searching the system directories at that point.)
15014 @cindex Dumping a .fmt file
15015 @cindex Format file, dumping
15016 Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
15017 web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
15018 disadvantage is that then updating @file{texinfo.tex} requires
15019 redumping.) You can do this by running this command, assuming
15020 @file{epsf.tex} is findable by @TeX{}:
15023 initex texinfo @@dump
15027 (@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
15028 wherever your @code{.fmt} files are found; typically, this will be in the
15029 subdirectory @file{web2c} of your @TeX{} installation.
15032 @node Overfull hboxes
15033 @section Overfull ``hboxes''
15034 @cindex Overfull @samp{hboxes}
15035 @cindex @samp{hboxes}, overfull
15036 @cindex Final output
15038 @TeX{} is sometimes unable to typeset a line without extending it into
15039 the right margin. This can occur when @TeX{} comes upon what it
15040 interprets as a long word that it cannot hyphenate, such as an
15041 electronic mail network address or a very long title. When this
15042 happens, @TeX{} prints an error message like this:
15045 Overfull @@hbox (20.76302pt too wide)
15050 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
15051 @samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
15053 @TeX{} also provides the line number in the Texinfo source file and
15054 the text of the offending line, which is marked at all the places that
15055 @TeX{} considered hyphenation.
15056 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
15057 for more information about typesetting errors.
15059 If the Texinfo file has an overfull hbox, you can rewrite the sentence
15060 so the overfull hbox does not occur, or you can decide to leave it. A
15061 small excursion into the right margin often does not matter and may not
15062 even be noticeable.
15064 If you have many overfull boxes and/or an antipathy to rewriting, you
15065 can coerce @TeX{} into greatly increasing the allowable interword
15066 spacing, thus (if you're lucky) avoiding many of the bad line breaks,
15069 @findex \emergencystretch
15072 \global\emergencystretch = .9\hsize
15077 (You should adjust the fraction as needed.) This huge value for
15078 @code{\emergencystretch} cannot be the default, since then the typeset
15079 output would generally be of noticeably lower quality; the default
15080 is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
15081 containing the current line width.
15083 @cindex Black rectangle in hardcopy
15084 @cindex Rectangle, black in hardcopy
15085 @cindex Box, ugly black in hardcopy
15086 @cindex Ugly black rectangles in hardcopy
15087 For what overfull boxes you have, however, @TeX{} will print a large,
15088 ugly, black rectangle beside the line that contains the overfull hbox
15089 unless told otherwise. This is so you will notice the location of the
15090 problem if you are correcting a draft.
15093 To prevent such a monstrosity from marring your final printout, write
15094 the following in the beginning of the Texinfo file on a line of its own,
15095 before the @code{@@titlepage} command:
15103 @section Printing ``Small'' Books
15105 @cindex Small book size
15106 @cindex Book, printing small
15107 @cindex Page sizes for books
15108 @cindex Size of printed book
15110 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
15111 format. However, you can direct @TeX{} to typeset a document in a 7 by
15112 9.25 inch format that is suitable for bound books by inserting the
15113 following command on a line by itself at the beginning of the Texinfo
15114 file, before the title page:@refill
15121 (Since many books are about 7 by 9.25 inches, this command might better
15122 have been called the @code{@@regularbooksize} command, but it came to be
15123 called the @code{@@smallbook} command by comparison to the 8.5 by 11
15126 If you write the @code{@@smallbook} command between the
15127 start-of-header and end-of-header lines, the Texinfo mode @TeX{}
15128 region formatting command, @code{texinfo-tex-region}, will format the
15129 region in ``small'' book size (@pxref{Start of Header}).@refill
15131 @xref{small}, for information about
15132 commands that make it easier to produce examples for a smaller manual.
15134 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
15135 @TeX{}}, for other ways to format with @code{@@smallbook} that do not
15136 require changing the source file.
15140 @section Printing on A4 Paper
15141 @cindex A4 paper, printing on
15142 @cindex A5 paper, printing on
15143 @cindex Paper size, A4
15144 @cindex European A4 paper
15147 You can tell @TeX{} to format a document for printing on European size
15148 A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
15149 command. Write the command on a line by itself near the beginning of
15150 the Texinfo file, before the title page. For example, this is how you
15151 would write the header for this manual:
15155 \input texinfo @@c -*-texinfo-*-
15156 @@c %**start of header
15157 @@setfilename texinfo
15160 @@c %**end of header
15164 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
15165 @TeX{}}, for other ways to format for different paper sizes that do not
15166 require changing the source file.
15170 You may or may not prefer the formatting that results from the command
15171 @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
15175 @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes
15177 @cindex Custom page sizes
15178 @cindex Page sizes, customized
15179 @cindex Text width and height
15180 @cindex Width of text area
15181 @cindex Height of text area
15182 @cindex Depth of text area
15184 You can explicitly specify the height and (optionally) width of the main
15185 text area on the page with the @code{@@pagesizes} command. Write this
15186 on a line by itself near the beginning of the Texinfo file, before the
15187 title page. The height comes first, then the width if desired,
15188 separated by a comma. Examples:
15191 @@pagesizes 200mm,150mm @c for b5 paper
15195 @@pagesizes 11.5in @c for legal paper
15198 @cindex B5 paper, printing on
15199 @cindex Legal paper, printing on
15200 This would be reasonable for printing on B5-size paper. To emphasize,
15201 this command specifies the size of the @emph{text area}, not the size of
15202 the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
15203 8.5@dmn{in} for legal).
15205 @cindex Margins on page, not controllable
15206 To make more elaborate changes, such as changing any of the page
15207 margins, you must define a new command in @file{texinfo.tex} (or
15208 @file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
15210 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
15211 @TeX{}}, for other ways to specify @code{@@pagesizes} that do not
15212 require changing the source file.
15214 @code{@@pagesizes} is ignored by @code{makeinfo}.
15217 @node Cropmarks and Magnification
15218 @section Cropmarks and Magnification
15220 @cindex Cropmarks for printing
15221 @cindex Printing cropmarks
15222 You can (attempt to) direct @TeX{} to print cropmarks at the corners of
15223 pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
15224 command on a line by itself between @code{@@iftex} and @code{@@end
15225 iftex} lines near the beginning of the Texinfo file, before the title
15226 page, like this:@refill
15236 This command is mainly for printers that typeset several pages on one
15237 sheet of film; but you can attempt to use it to mark the corners of a
15238 book set to 7 by 9.25 inches with the @code{@@smallbook} command.
15239 (Printers will not produce cropmarks for regular sized output that is
15240 printed on regular sized paper.) Since different printing machines work
15241 in different ways, you should explore the use of this command with a
15242 spirit of adventure. You may have to redefine the command in
15243 @file{texinfo.tex}.
15245 @findex \mag @r{(raw @TeX{} magnification)}
15246 @cindex Magnified printing
15247 @cindex Larger or smaller pages
15248 You can attempt to direct @TeX{} to typeset pages larger or smaller than
15249 usual with the @code{\mag} @TeX{} command. Everything that is typeset
15250 is scaled proportionally larger or smaller. (@code{\mag} stands for
15251 ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
15252 plain @TeX{} command that is prefixed with a backslash. You have to
15253 write this command between @code{@@tex} and @code{@@end tex}
15254 (@pxref{Raw Formatter Commands}).
15256 Follow the @code{\mag} command with an @samp{=} and then a number that
15257 is 1000 times the magnification you desire. For example, to print pages
15258 at 1.2 normal size, write the following near the beginning of the
15259 Texinfo file, before the title page:
15269 With some printing technologies, you can print normal-sized copies that
15270 look better than usual by giving a larger-than-normal master to your
15271 print shop. They do the reduction, thus effectively increasing the
15274 Depending on your system, DVI files prepared with a
15275 nonstandard-@code{\mag} may not print or may print only with certain
15276 magnifications. Be prepared to experiment.
15280 @section PDF Output
15284 The simplest way to generate PDF output from Texinfo source is to run
15285 the convenience script @command{texi2pdf} (or @command{pdftexi2dvi});
15286 this simply executes the @command{texi2dvi} script with the
15287 @option{--pdf} option (@pxref{Format with texi2dvi}). If for some
15288 reason you want to process the document by hand, simply run the
15289 @command{pdftex} program instead of plain @command{tex}. That is, run
15290 @samp{pdftex foo.texi} instead of @samp{tex foo.texi}.
15292 @dfn{PDF} stands for `Portable Document Format'. It was invented by
15293 Adobe Systems some years ago for document interchange, based on their
15294 PostScript language. Related links:
15298 GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF
15299 reader}. (It can also preview PostScript documents.)
15302 A freely available standalone @uref{http://www.foolabs.com/xpdf/,
15303 PDF reader} for the X window system.
15306 @uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}.
15310 At present, Texinfo does not provide
15311 @samp{@@ifpdf} or @samp{@@pdf} commands as for the other output
15312 formats, since PDF documents contain many internal links that would be
15313 hard or impossible to get right at the Texinfo source level.
15315 PDF files require special software to be displayed, unlike the plain
15316 ASCII formats (Info, HTML) that Texinfo supports. They also tend to
15317 be much larger than the DVI files output by @TeX{} by default.
15318 Nevertheless, a PDF file does define an actual typeset document in a
15319 self-contained file, so it has its place.
15322 @node Obtaining TeX
15323 @section How to Obtain @TeX{}
15324 @cindex Obtaining @TeX{}
15325 @cindex @TeX{}, how to obtain
15327 @c !!! Here is information about obtaining TeX. Update it whenever.
15328 @c !!! Also consider updating TeX.README on ftp.gnu.org.
15329 @c Updated by RJC on 1 March 1995, conversation with MacKay.
15330 @c Updated by kb@cs.umb.edu on 29 July 1996.
15331 @c Updated by kb@cs.umb.edu on 25 April 1997.
15332 @c Updated by kb@cs.umb.edu on 27 February 1998.
15333 @TeX{} is freely redistributable. You can obtain @TeX{} for Unix
15334 systems via anonymous ftp or on physical media. The core material
15335 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
15337 Instructions for retrieval by anonymous ftp and information on other
15338 available distributions:
15339 @uref{http://tug.org/unixtex.ftp}.
15341 The Free Software Foundation provides a core distribution on its Source
15342 Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
15346 Free Software Foundation, Inc.
15347 51 Franklin St, Fifth Floor
15348 Boston, MA @ @ 02110-1301
15350 Telephone: @w{+1-617-542-5942}
15351 Fax: (including Japan) @w{+1-617-542-2652}
15352 Free Dial Fax (in Japan):
15353 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
15354 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
15355 Electronic mail: @code{gnu@@gnu.org}
15359 Many other @TeX{} distributions are available; see
15360 @uref{http://tug.org/}.
15363 @node Creating and Installing Info Files
15364 @chapter Creating and Installing Info Files
15366 This chapter describes how to create and install Info files. @xref{Info
15367 Files}, for general information about the file format itself.
15370 * Creating an Info File::
15371 * Installing an Info File::
15375 @node Creating an Info File
15376 @section Creating an Info File
15377 @cindex Creating an Info file
15378 @cindex Info, creating an online file
15379 @cindex Formatting a file for Info
15381 @code{makeinfo} is a program that converts a Texinfo file into an Info
15382 file, HTML file, or plain text. @code{texinfo-format-region} and
15383 @code{texinfo-format-buffer} are GNU Emacs functions that convert
15386 For information on installing the Info file in the Info system,
15387 @pxref{Installing an Info File}.
15390 * makeinfo advantages:: @code{makeinfo} provides better error checking.
15391 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
15392 * makeinfo options:: Specify fill-column and other options.
15393 * Pointer Validation:: How to check that pointers point somewhere.
15394 * makeinfo in Emacs:: How to run @code{makeinfo} from Emacs.
15395 * texinfo-format commands:: Two Info formatting commands written
15396 in Emacs Lisp are an alternative
15397 to @code{makeinfo}.
15398 * Batch Formatting:: How to format for Info in Emacs Batch mode.
15399 * Tag and Split Files:: How tagged and split files help Info
15404 @node makeinfo advantages
15405 @subsection @code{makeinfo} Preferred
15407 The @code{makeinfo} utility creates an Info file from a Texinfo source
15408 file more quickly than either of the Emacs formatting commands and
15409 provides better error messages. We recommend it. @code{makeinfo} is a
15410 C program that is independent of Emacs. You do not need to run Emacs to
15411 use @code{makeinfo}, which means you can use @code{makeinfo} on machines
15412 that are too small to run Emacs. You can run @code{makeinfo} in any one
15413 of three ways: from an operating system shell, from a shell inside
15414 Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
15415 command in Texinfo mode in Emacs.
15417 The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
15418 commands are useful if you cannot run @code{makeinfo}. Also, in some
15419 circumstances, they format short regions or buffers more quickly than
15423 @node Invoking makeinfo
15424 @subsection Running @code{makeinfo} from a Shell
15427 To create an Info file from a Texinfo file, invoke @command{makeinfo}
15428 followed by the name of the Texinfo file. Thus, to create the Info
15429 file for Bison, type the following to the shell:
15432 makeinfo bison.texinfo
15435 (You can run a shell inside Emacs by typing @kbd{M-x shell}.)
15437 @command{makeinfo} has many options to control its actions and output;
15438 see the next section.
15440 You can give @command{makeinfo} more than one input file name; each is
15441 processed in turn. If an input file name is @samp{-}, or no input
15442 file names are given at all, standard input is read.
15445 @node makeinfo options
15446 @subsection Options for @code{makeinfo}
15447 @cindex @code{makeinfo} options
15448 @cindex Options for @code{makeinfo}
15450 The @command{makeinfo} program accepts many options. Perhaps the most
15451 commonly needed are those that change the output format. By default,
15452 @command{makeinfo} outputs Info files.
15454 Each command line option is a word preceded by @samp{--} or a letter
15455 preceded by @samp{-}. You can use abbreviations for the long option
15456 names as long as they are unique.
15458 For example, you could use the following shell command to create an Info
15459 file for @file{bison.texinfo} in which each line is filled to only 68
15463 makeinfo --fill-column=68 bison.texinfo
15466 You can write two or more options in sequence, like this:@refill
15469 makeinfo --no-split --fill-column=70 @dots{}
15473 This would keep the Info file together as one possibly very long
15474 file and would also set the fill column to 70.
15481 @opindex -D @var{var}
15482 Cause the variable @var{var} to be defined. This is equivalent to
15483 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
15485 @item --commands-in-node-names
15486 @opindex --commands-in-node-names
15487 Allow @code{@@}-commands in node names. This is not recommended, as it
15488 can probably never be implemented in @TeX{}. It also makes
15489 @code{makeinfo} much slower. Also, this option is ignored when
15490 @samp{--no-validate} is used. @xref{Pointer Validation}, for more
15493 @item --css-include=@var{file}
15494 @opindex --css-include
15495 Include the contents of @var{file}, which should contain cascading
15496 style sheets specifications, in the @samp{<style>} block of the HTML
15497 output. @xref{HTML CSS}. If @var{file} is @samp{-}, read standard
15500 @item --css-ref=@var{url}
15502 In HTML mode, add a @samp{<link>} tag to the HTML output which
15503 references a cascading style sheet at @var{url}. This allows using
15504 standalone style sheets.
15506 @item --disable-encoding
15507 @itemx --enable-encoding
15508 @opindex --disable-encoding
15509 @opindex --enable-encoding
15510 By default, or with @option{--enable-encoding}, output accented and
15511 special characters in Info or plain text output based on
15512 @samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit
15513 ASCII transliterations are output.
15514 @xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting
15519 Generate Docbook output rather than Info.
15521 @item --document-language=@var{lang}
15522 @opindex --document-language
15524 Use @var{lang} to translate Texinfo keywords which end up in the
15525 output document. The default is the locale specified by the
15526 @code{@@documentlanguage} command if there is one
15527 (@pxref{documentlanguage}).
15529 @item --error-limit=@var{limit}
15530 @itemx -e @var{limit}
15531 @opindex --error-limit=@var{limit}
15532 @opindex -e @var{limit}
15533 Set the maximum number of errors that @code{makeinfo} will report
15534 before exiting (on the assumption that continuing would be useless);
15537 @item --fill-column=@var{width}
15538 @itemx -f @var{width}
15539 @opindex --fill-column=@var{width}
15540 @opindex -f @var{width}
15541 Specify the maximum number of columns in a line; this is the right-hand
15542 edge of a line. Paragraphs that are filled will be filled to this
15543 width. (Filling is the process of breaking up and connecting lines so
15544 that lines are the same length as or shorter than the number specified
15545 as the fill column. Lines are broken between words.) The default value
15546 is 72. Ignored with @samp{--html}.
15548 @item --footnote-style=@var{style}
15549 @itemx -s @var{style}
15550 @opindex --footnote-style=@var{style}
15551 @opindex -s @var{style}
15552 Set the footnote style to @var{style}, either @samp{end} for the end
15553 node style (the default) or @samp{separate} for the separate node style.
15554 The value set by this option overrides the value set in a Texinfo file
15555 by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
15556 footnote style is @samp{separate}, @code{makeinfo} makes a new node
15557 containing the footnotes found in the current node. When the footnote
15558 style is @samp{end}, @code{makeinfo} places the footnote references at
15559 the end of the current node. Ignored with @samp{--html}.
15565 Ordinarily, if the input file has errors, the output files are not
15566 created. With this option, they are preserved.
15572 Print a usage message listing all available options, then exit successfully.
15576 Generate HTML output rather than Info. @xref{Generating HTML}. By
15577 default, the HTML output is split into one output file per Texinfo
15578 source node, and the split output is written into a subdirectory with
15579 the name of the top-level info file.
15582 @opindex -I @var{dir}
15583 Append @var{dir} to the directory search list for finding files that
15584 are included using the @code{@@include} command. By default,
15585 @code{makeinfo} searches only the current directory. If @var{dir} is
15586 not given, the current directory @file{.} is appended. Note that
15587 @var{dir} can actually be a list of several directories separated by the
15588 usual path separator character (@samp{:} on Unix, @samp{;} on
15589 MS-DOS/MS-Windows).
15592 @opindex --ifdocbook
15597 @itemx --ifplaintext
15598 @opindex --ifplaintext
15603 For the specified format, process @samp{@@if@var{format}} and
15604 @samp{@@@var{format}} commands even if not generating the given output
15605 format. For instance, if @option{--iftex} is specified, then
15606 @samp{@@iftex} and @samp{@@tex} blocks will be read.
15608 @item --internal-links=@var{file}
15609 @opindex --internal-links=@var{file}
15610 In HTML mode, output a tab separated file containing three columns:
15611 the internal link to an indexed item or item in the table of contents,
15612 the name of the index (or "toc") in which it occurs, and the term
15613 which was indexed or entered.
15615 @item --macro-expand=@var{file}
15616 @itemx -E @var{file}
15617 @opindex --macro-expand=@var{file}
15618 @opindex -E @var{file}
15619 Output the Texinfo source with all the macros expanded to the named
15620 file. Normally, the results of macro expansion are used internally by
15621 @code{makeinfo} and then discarded. This option is used by
15622 @command{texi2dvi}.
15626 @opindex --no-headers
15627 @opindex --plaintext
15628 @cindex Plain text output
15629 @cindex ASCII text output
15630 @cindex Generating plain text files
15631 @cindex @file{INSTALL} file, generating
15632 @cindex Node separators, omitting
15633 @cindex Menus, omitting
15634 Do not include menus or node separator lines in the output, and
15635 implicitly @option{--enable-encoding} (see above). This results in a
15636 simple plain text file that you can (for example) send in email
15637 without complications, or include in a distribution (as in an
15638 @file{INSTALL} file).
15640 @cindex Navigation links, omitting
15641 For HTML output, likewise omit menus. And if @samp{--no-split} is also
15642 specified, do not include a navigation links at the top of each node
15643 (these are never included in the default case of split output).
15644 @xref{Generating HTML}.
15646 In both cases, ignore @code{@@setfilename} and write to standard
15647 output by default---can be overridden with @option{-o}.
15649 @item --no-ifdocbook
15650 @opindex --no-ifdocbook
15652 @opindex --no-ifhtml
15654 @opindex --no-ifinfo
15655 @itemx --no-ifplaintext
15656 @opindex --no-ifplaintext
15658 @opindex --no-iftex
15660 @opindex --no-ifxml
15661 Do not process @samp{@@if@var{format}} and @samp{@@@var{format}}
15662 commands, and do process @samp{@@ifnot@var{format}}, even if
15663 generating the given format. For instance, if @option{--no-ifhtml} is
15664 specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be
15665 read, and @samp{@@ifnothtml} blocks will be.
15667 @item --no-number-footnotes
15668 @opindex --no-number-footnotes
15669 Suppress automatic footnote numbering. By default, @code{makeinfo}
15670 numbers each footnote sequentially in a single node, resetting the
15671 current footnote number to 1 at the start of each node.
15673 @item --no-number-sections
15674 @opindex --no-number-sections
15675 Do not output chapter, section, and appendix numbers.
15676 You need to specify this if your manual is not hierarchically-structured.
15679 @opindex --no-split
15680 @cindex Splitting of output files
15681 @cindex Output file splitting
15682 Suppress the splitting stage of @code{makeinfo}. By default, large
15683 output files (where the size is greater than 70k bytes) are split into
15684 smaller subfiles. For Info output, each one is approximately 50k bytes.
15685 For HTML output, each file contains one node (@pxref{Generating HTML}).
15687 @item --no-pointer-validate
15688 @itemx --no-validate
15689 @opindex --no-pointer-validate
15690 @opindex --no-validate
15691 @cindex Pointer validation, suppressing
15692 Suppress the pointer-validation phase of @code{makeinfo}---a dangerous
15693 thing to do. This can also be done with the @code{@@novalidate}
15694 command (@pxref{Use TeX,,Use @TeX{}}). Normally, after a Texinfo file
15695 is processed, some consistency checks are made to ensure that cross
15696 references can be resolved, etc. @xref{Pointer Validation}.
15700 Suppress warning messages (but @emph{not} error messages).
15702 @item --number-sections
15703 @opindex --number-sections
15704 Output chapter, section, and appendix numbers as in printed manuals.
15705 This is the default. It works only with hierarchically-structured
15708 @item --output=@var{file}
15709 @itemx -o @var{file}
15710 @opindex --output=@var{file}
15711 @opindex -o @var{file}
15712 Specify that the output should be directed to @var{file} and not to the
15713 file name specified in the @code{@@setfilename} command found in the
15714 Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
15715 goes to standard output and @samp{--no-split} is implied. For split
15716 HTML output, @var{file} is the name for the directory into which all
15717 HTML nodes are written (@pxref{Generating HTML}).
15720 @opindex -P @var{dir}
15721 Prepend @var{dir} to the directory search list for @code{@@include}.
15722 If @var{dir} is not given, the current directory @file{.} is prepended.
15723 See @samp{-I} for more details.
15725 @item --paragraph-indent=@var{indent}
15726 @itemx -p @var{indent}
15727 @opindex --paragraph-indent=@var{indent}
15728 @opindex -p @var{indent}
15729 Set the paragraph indentation style to @var{indent}. The value set by
15730 this option overrides the value set in a Texinfo file by an
15731 @code{@@paragraphindent} command (@pxref{paragraphindent}). The value
15732 of @var{indent} is interpreted as follows:
15736 Preserve any existing indentation at the starts of paragraphs.
15738 @item @samp{0} or @samp{none}
15739 Delete any existing indentation.
15742 Indent each paragraph by @var{num} spaces.
15745 @item --split-size=@var{num}
15746 @opindex --split-size=@var{num}
15747 Keep Info files to at most @var{num} characters; default is 300,000.
15749 @item --transliterate-file-names
15750 @opindex --transliterate-file-names
15751 Enable transliteration of 8-bit characters in node names for the
15752 purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}.
15755 Cause @var{var} to be undefined. This is equivalent to
15756 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
15760 Cause @code{makeinfo} to display messages saying what it is doing.
15761 Normally, @code{makeinfo} only outputs messages if there are errors or
15768 Print the version number, then exit successfully.
15772 Generate XML output rather than Info.
15776 @vindex TEXINFO_OUTPUT_FORMAT
15777 @cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT}
15778 @command{makeinfo} also reads the environment variable
15779 @env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not
15780 overridden by a command line option. The possible values are:
15783 docbook html info plaintext xml
15786 If not set, Info output is the default.
15789 @node Pointer Validation
15790 @subsection Pointer Validation
15791 @cindex Pointer validation with @code{makeinfo}
15792 @cindex Validation of pointers
15794 If you do not suppress pointer validation with the @samp{--no-validate}
15795 option or the @code{@@novalidate} command in the source file (@pxref{Use
15796 TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
15797 Info file. Mostly, this means ensuring that nodes you have referenced
15798 really exist. Here is a complete list of what is checked:
15802 If a `Next', `Previous', or `Up' node reference is a reference to a
15803 node in the current file and is not an external reference such as to
15804 @file{(dir)}, then the referenced node must exist.@refill
15807 In every node, if the `Previous' node is different from the `Up' node,
15808 then the node pointed to by the `Previous' field must have a `Next'
15809 field which points back to this node.@refill
15812 Every node except the `Top' node must have an `Up' pointer.@refill
15815 The node referenced by an `Up' pointer must itself reference the current
15816 node through a menu item, unless the node referenced by `Up'
15817 has the form `(@var{file})'.
15820 If the `Next' reference of a node is not the same as the `Next' reference
15821 of the `Up' reference, then the node referenced by the `Next' pointer
15822 must have a `Previous' pointer that points back to the current node.
15823 This rule allows the last node in a section to point to the first node
15824 of the next chapter.@refill
15827 Every node except `Top' should be referenced by at least one other node,
15828 either via the `Previous' or `Next' links, or via a menu or a
15829 cross-reference.@refill
15832 @cindex @@-commands in @@node, limited support
15833 Some Texinfo documents might fail during the validation phase because
15834 they use commands like @code{@@value} and @code{@@definfoenclose} in
15835 node definitions and cross-references inconsistently. (Your best bet
15836 is to avoid using @@-commands in node names.) Consider the
15841 @@set nodename Node 1
15843 @@node @@value@{nodename@}, Node 2, Top, Top
15847 @@node Node 2, , Node 1, Top
15854 Here, the node ``Node 1'' was referenced both verbatim and through
15857 By default, @code{makeinfo} fails such cases, because node names are not
15858 fully expanded until they are written to the output file. You should
15859 always try to reference nodes consistently; e.g., in the above example,
15860 the second @code{@@node} line should have also used @code{@@value}.
15861 However, if, for some reason, you @emph{must} reference node names
15862 inconsistently, and @code{makeinfo} fails to validate the file, you can
15863 use the @samp{--commands-in-node-names} option to force @code{makeinfo}
15864 to perform the expensive expansion of all node names it finds in the
15865 document. This might considerably slow down the program, though;
15866 twofold increase in conversion time was measured for large documents
15867 such as the Jargon file.
15869 @cindex @@value in @@node lines
15870 The support for @code{@@}-commands in @code{@@node} directives is not
15871 general enough to be freely used. For example, if the example above
15872 redefined @code{nodename} somewhere in the document, @code{makeinfo}
15873 will fail to convert it, even if invoked with the
15874 @samp{--commands-in-node-names} option.
15876 @samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
15880 @node makeinfo in Emacs
15881 @subsection Running @code{makeinfo} Within Emacs
15882 @cindex Running @code{makeinfo} in Emacs
15883 @cindex @code{makeinfo} inside Emacs
15884 @cindex Shell, running @code{makeinfo} in
15886 You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
15887 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
15888 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
15889 C-m C-b} by default.@refill
15893 @itemx M-x makeinfo-region
15894 Format the current region for Info.@refill
15895 @findex makeinfo-region
15898 @itemx M-x makeinfo-buffer
15899 Format the current buffer for Info.@refill
15900 @findex makeinfo-buffer
15903 When you invoke @code{makeinfo-region} the output goes to a temporary
15904 buffer. When you invoke @code{makeinfo-buffer} output goes to the
15905 file set with @code{@@setfilename} (@pxref{setfilename}).
15907 The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
15908 run the @code{makeinfo} program in a temporary shell buffer. If
15909 @code{makeinfo} finds any errors, Emacs displays the error messages in
15910 the temporary buffer.@refill
15912 @cindex Errors, parsing
15913 @cindex Parsing errors
15915 You can parse the error messages by typing @kbd{C-x `}
15916 (@code{next-error}). This causes Emacs to go to and position the
15917 cursor on the line in the Texinfo source that @code{makeinfo} thinks
15918 caused the error. @xref{Compilation, , Running @code{make} or
15919 Compilers Generally, emacs, The GNU Emacs Manual}, for more
15920 information about using the @code{next-error} command.@refill
15922 In addition, you can kill the shell in which the @code{makeinfo}
15923 command is running or make the shell buffer display its most recent
15928 @itemx M-x makeinfo-kill-job
15929 @findex makeinfo-kill-job
15930 Kill the current running @code{makeinfo} job
15931 (from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
15934 @itemx M-x makeinfo-recenter-output-buffer
15935 @findex makeinfo-recenter-output-buffer
15936 Redisplay the @code{makeinfo} shell buffer to display its most recent
15941 (Note that the parallel commands for killing and recentering a @TeX{}
15942 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
15945 You can specify options for @code{makeinfo} by setting the
15946 @code{makeinfo-options} variable with either the @kbd{M-x
15947 customize} or the @kbd{M-x set-variable} command, or by setting the
15948 variable in your @file{.emacs} initialization file.
15950 For example, you could write the following in your @file{.emacs} file:@refill
15954 (setq makeinfo-options
15955 "--paragraph-indent=0 --no-split
15956 --fill-column=70 --verbose")
15961 @c If you write these three cross references using xref, you see
15962 @c three references to the same named manual, which looks strange.
15964 For more information, see @ref{makeinfo options, , Options for
15965 @code{makeinfo}}, as well as ``Easy Customization Interface,'' ``Examining
15966 and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs
15970 For more information, see@*
15971 @ref{Easy Customization, , Easy Customization Interface, emacs, The GNU Emacs Manual},@*
15972 @ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
15973 @ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
15974 @ref{makeinfo options, , Options for @code{makeinfo}}.
15977 @node texinfo-format commands
15978 @subsection The @code{texinfo-format@dots{}} Commands
15980 In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
15981 file with the @code{texinfo-format-region} command. This formats the
15982 current region and displays the formatted text in a temporary buffer
15983 called @samp{*Info Region*}.@refill
15985 Similarly, you can format a buffer with the
15986 @code{texinfo-format-buffer} command. This command creates a new
15987 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
15988 save the Info file under the name specified by the
15989 @code{@@setfilename} line which must be near the beginning of the
15990 Texinfo file.@refill
15994 @itemx @code{texinfo-format-region}
15995 @findex texinfo-format-region
15996 Format the current region for Info.
15999 @itemx @code{texinfo-format-buffer}
16000 @findex texinfo-format-buffer
16001 Format the current buffer for Info.
16004 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
16005 commands provide you with some error checking, and other functions can
16006 provide you with further help in finding formatting errors. These
16007 procedures are described in an appendix; see @ref{Catching Mistakes}.
16008 However, the @code{makeinfo} program is often faster and
16009 provides better error checking (@pxref{makeinfo in Emacs}).@refill
16011 @node Batch Formatting
16012 @comment node-name, next, previous, up
16013 @subsection Batch Formatting
16014 @cindex Batch formatting for Info
16015 @cindex Info batch formatting
16017 You can format Texinfo files for Info using @code{batch-texinfo-format}
16018 and Emacs Batch mode. You can run Emacs in Batch mode from any shell,
16019 including a shell inside of Emacs. (@xref{Command Arguments,,,
16020 emacs, The GNU Emacs Manual}.)
16022 Here is a shell command to format all the files that end in
16023 @file{.texinfo} in the current directory:
16026 emacs -batch -funcall batch-texinfo-format *.texinfo
16030 Emacs processes all the files listed on the command line, even if an
16031 error occurs while attempting to format some of them.@refill
16033 Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
16034 it is not interactive. It kills the Batch mode Emacs on completion.@refill
16036 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
16037 and want to format several Texinfo files at once. When you use Batch
16038 mode, you create a new Emacs process. This frees your current Emacs, so
16039 you can continue working in it. (When you run
16040 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
16041 use that Emacs for anything else until the command finishes.)@refill
16043 @node Tag and Split Files
16044 @comment node-name, next, previous, up
16045 @subsection Tag Files and Split Files
16046 @cindex Making a tag table automatically
16047 @cindex Tag table, making automatically
16049 If a Texinfo file has more than 30,000 bytes,
16050 @code{texinfo-format-buffer} automatically creates a tag table
16051 for its Info file; @code{makeinfo} always creates a tag table. With
16052 a @dfn{tag table}, Info can jump to new nodes more quickly than it can
16055 @cindex Indirect subfiles
16056 In addition, if the Texinfo file contains more than about 300,000
16057 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
16058 large Info file into shorter @dfn{indirect} subfiles of about 300,000
16059 bytes each. Big files are split into smaller files so that Emacs does
16060 not need to make a large buffer to hold the whole of a large Info
16061 file; instead, Emacs allocates just enough memory for the small, split-off
16062 file that is needed at the time. This way, Emacs avoids wasting
16063 memory when you run Info. (Before splitting was implemented, Info
16064 files were always kept short and @dfn{include files} were designed as
16065 a way to create a single, large printed manual out of the smaller Info
16066 files. @xref{Include Files}, for more information. Include files are
16067 still used for very large documents, such as @cite{The Emacs Lisp
16068 Reference Manual}, in which each chapter is a separate file.)@refill
16070 When a file is split, Info itself makes use of a shortened version of
16071 the original file that contains just the tag table and references to
16072 the files that were split off. The split-off files are called
16073 @dfn{indirect} files.@refill
16075 The split-off files have names that are created by appending @w{@samp{-1}},
16076 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
16077 @code{@@setfilename} command. The shortened version of the original file
16078 continues to have the name specified by @code{@@setfilename}.@refill
16080 At one stage in writing this document, for example, the Info file was saved
16081 as the file @file{test-texinfo} and that file looked like this:@refill
16085 Info file: test-texinfo, -*-Text-*-
16086 produced by texinfo-format-buffer
16087 from file: new-texinfo-manual.texinfo
16091 test-texinfo-1: 102
16092 test-texinfo-2: 50422
16095 test-texinfo-3: 101300
16099 Node: overview^?104
16100 Node: info file^?1271
16103 Node: printed manual^?4853
16104 Node: conventions^?6855
16110 (But @file{test-texinfo} had far more nodes than are shown here.) Each of
16111 the split-off, indirect files, @file{test-texinfo-1},
16112 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
16113 after the line that says @samp{Indirect:}. The tag table is listed after
16114 the line that says @samp{Tag table:}. @refill
16116 In the list of indirect files, the number following the file name
16117 records the cumulative number of bytes in the preceding indirect files,
16118 not counting the file list itself, the tag table, or the permissions
16119 text in each file. In the tag table, the number following the node name
16120 records the location of the beginning of the node, in bytes from the
16121 beginning of the (unsplit) output.
16123 If you are using @code{texinfo-format-buffer} to create Info files,
16124 you may want to run the @code{Info-validate} command. (The
16125 @code{makeinfo} command does such a good job on its own, you do not
16126 need @code{Info-validate}.) However, you cannot run the @kbd{M-x
16127 Info-validate} node-checking command on indirect files. For
16128 information on how to prevent files from being split and how to
16129 validate the structure of the nodes, see @ref{Using Info-validate}.
16132 @node Installing an Info File
16133 @section Installing an Info File
16134 @cindex Installing an Info file
16135 @cindex Info file installation
16136 @cindex @file{dir} directory for Info installation
16138 Info files are usually kept in the @file{info} directory. You can read
16139 Info files using the standalone Info program or the Info reader built
16140 into Emacs. (@inforef{Top, info, info}, for an introduction to Info.)
16143 * Directory File:: The top level menu for all Info files.
16144 * New Info File:: Listing a new Info file.
16145 * Other Info Directories:: How to specify Info files that are
16146 located in other directories.
16147 * Installing Dir Entries:: How to specify what menu entry to add
16148 to the Info directory.
16149 * Invoking install-info:: @code{install-info} options.
16153 @node Directory File
16154 @subsection The Directory File @file{dir}
16156 For Info to work, the @file{info} directory must contain a file that
16157 serves as a top level directory for the Info system. By convention,
16158 this file is called @file{dir}. (You can find the location of this file
16159 within Emacs by typing @kbd{C-h i} to enter Info and then typing
16160 @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
16162 The @file{dir} file is itself an Info file. It contains the top level
16163 menu for all the Info files in the system. The menu looks like
16169 * Info: (info). Documentation browsing system.
16170 * Emacs: (emacs). The extensible, self-documenting
16172 * Texinfo: (texinfo). With one source file, make
16173 either a printed manual using
16174 @@TeX@{@} or an Info file.
16179 Each of these menu entries points to the `Top' node of the Info file
16180 that is named in parentheses. (The menu entry does not need to
16181 specify the `Top' node, since Info goes to the `Top' node if no node
16182 name is mentioned. @xref{Other Info Files, , Nodes in Other Info
16185 Thus, the @samp{Info} entry points to the `Top' node of the
16186 @file{info} file and the @samp{Emacs} entry points to the `Top' node
16187 of the @file{emacs} file.@refill
16189 In each of the Info files, the `Up' pointer of the `Top' node refers
16190 back to the @code{dir} file. For example, the line for the `Top'
16191 node of the Emacs manual looks like this in Info:@refill
16194 File: emacs Node: Top, Up: (DIR), Next: Distrib
16198 In this case, the @file{dir} file name is written in upper case
16199 letters---it can be written in either upper or lower case. This is not
16200 true in general, it is a special case for @file{dir}.
16203 @node New Info File
16204 @subsection Listing a New Info File
16205 @cindex Adding a new Info file
16206 @cindex Listing a new Info file
16207 @cindex New Info file, listing it in @file{dir} file
16208 @cindex Info file, listing a new
16209 @cindex @file{dir} file listing
16211 To add a new Info file to your system, you must write a menu entry to
16212 add to the menu in the @file{dir} file in the @file{info} directory.
16213 For example, if you were adding documentation for GDB, you would write
16214 the following new entry:@refill
16217 * GDB: (gdb). The source-level C debugger.
16221 The first part of the menu entry is the menu entry name, followed by a
16222 colon. The second part is the name of the Info file, in parentheses,
16223 followed by a period. The third part is the description.
16225 The name of an Info file often has a @file{.info} extension. Thus, the
16226 Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
16227 The Info reader programs automatically try the file name both with and
16228 without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
16229 try the @file{.inf} extension as well.}; so it is better to avoid
16230 clutter and not to write @samp{.info} explicitly in the menu entry. For
16231 example, the GDB menu entry should use just @samp{gdb} for the file
16232 name, not @samp{gdb.info}.
16235 @node Other Info Directories
16236 @subsection Info Files in Other Directories
16237 @cindex Installing Info in another directory
16238 @cindex Info installed in another directory
16239 @cindex Another Info directory
16240 @cindex @file{dir} files and Info directories
16242 If an Info file is not in the @file{info} directory, there are three
16243 ways to specify its location:@refill
16247 Write the pathname in the @file{dir} file as the second part of the menu.
16250 If you are using Emacs, list the name of the file in a second @file{dir}
16251 file, in its directory; and then add the name of that directory to the
16252 @code{Info-directory-list} variable in your personal or site
16253 initialization file.
16255 This variable tells Emacs where to look for @file{dir} files (the files
16256 must be named @file{dir}). Emacs merges the files named @file{dir} from
16257 each of the listed directories. (In Emacs version 18, you can set the
16258 @code{Info-directory} variable to the name of only one
16262 Specify the Info directory name in the @code{INFOPATH} environment
16263 variable in your @file{.profile} or @file{.cshrc} initialization file.
16264 (Only you and others who set this environment variable will be able to
16265 find Info files whose location is specified this way.)
16268 For example, to reach a test file in the @file{/home/bob/info}
16269 directory, you could add an entry like this to the menu in the
16270 standard @file{dir} file:@refill
16273 * Test: (/home/bob/info/info-test). Bob's own test file.
16277 In this case, the absolute file name of the @file{info-test} file is
16278 written as the second part of the menu entry.@refill
16280 Alternatively, you could write the following in your @file{.emacs} file:
16282 @vindex Info-directory-list
16286 (setq Info-directory-list
16287 (cons (expand-file-name "/home/bob/info")
16288 Info-directory-list))
16292 This tells Emacs to merge the system @file{dir} file with the @file{dir}
16293 file in @file{/home/bob/info}. Thus, Info will list the
16294 @file{/home/bob/info/info-test} file as a menu entry in the
16295 @file{/home/bob/info/dir} file. Emacs does the merging only when
16296 @kbd{M-x info} is first run, so if you want to set
16297 @code{Info-directory-list} in an Emacs session where you've already run
16298 @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
16299 to recompose the @file{dir} file.
16302 @cindex Environment variable @code{INFOPATH}
16303 Finally, you can tell Info where to look by setting the @code{INFOPATH}
16304 environment variable in your shell startup file, such as @file{.cshrc},
16305 @file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible
16306 shell such as @code{sh} or @code{bash} for your shell command
16307 interpreter, you set the @code{INFOPATH} environment variable in the
16308 @file{.profile} initialization file; but if you use @code{csh} or
16309 @code{tcsh}, you set the variable in the @file{.cshrc} initialization
16310 file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
16311 your @file{autoexec.bat} file or in the Registry. Each type of shell
16312 uses a different syntax.
16316 In a @file{.cshrc} file, you could set the @code{INFOPATH}
16317 variable as follows:@refill
16320 setenv INFOPATH .:~/info:/usr/local/emacs/info
16324 In a @file{.profile} file, you would achieve the same effect by
16328 INFOPATH=.:$HOME/info:/usr/local/emacs/info
16333 @pindex autoexec.bat
16334 In a @file{autoexec.bat} file, you write this command@footnote{Note the
16335 use of @samp{;} as the directory separator, and a different syntax for
16336 using values of other environment variables.}:
16339 set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
16344 The @samp{.} indicates the current directory as usual. Emacs uses the
16345 @code{INFOPATH} environment variable to initialize the value of Emacs's
16346 own @code{Info-directory-list} variable. The stand-alone Info reader
16347 merges any files named @file{dir} in any directory listed in the
16348 @env{INFOPATH} variable into a single menu presented to you in the node
16349 called @samp{(dir)Top}.
16351 @cindex Colon, last in @env{INFOPATH}
16352 However you set @env{INFOPATH}, if its last character is a
16353 colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
16354 is replaced by the default (compiled-in) path. This gives you a way to
16355 augment the default path with new directories without having to list all
16356 the standard places. For example (using @code{sh} syntax):
16359 INFOPATH=/local/info:
16364 will search @file{/local/info} first, then the standard directories.
16365 Leading or doubled colons are not treated specially.
16367 @cindex @file{dir} file, creating your own
16368 When you create your own @file{dir} file for use with
16369 @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
16370 copying an existing @file{dir} file and replace all the text after the
16371 @samp{* Menu:} with your desired entries. That way, the punctuation and
16372 special CTRL-_ characters that Info needs will be present.
16375 @node Installing Dir Entries
16376 @subsection Installing Info Directory Files
16378 When you install an Info file onto your system, you can use the program
16379 @code{install-info} to update the Info directory file @file{dir}.
16380 Normally the makefile for the package runs @code{install-info}, just
16381 after copying the Info file into its proper installed location.
16383 @findex dircategory
16385 In order for the Info file to work with @code{install-info}, you include
16386 the commands @code{@@dircategory} and
16387 @code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
16388 file. Use @code{@@direntry} to specify the menu entries to add to the
16389 Info directory file, and use @code{@@dircategory} to specify which part
16390 of the Info directory to put it in. Here is how these commands are used
16394 @@dircategory Texinfo documentation system
16396 * Texinfo: (texinfo). The GNU documentation format.
16397 * install-info: (texinfo)Invoking install-info. @dots{}
16402 Here's what this produces in the Info file:
16405 INFO-DIR-SECTION Texinfo documentation system
16406 START-INFO-DIR-ENTRY
16407 * Texinfo: (texinfo). The GNU documentation format.
16408 * install-info: (texinfo)Invoking install-info. @dots{}
16414 The @code{install-info} program sees these lines in the Info file, and
16415 that is how it knows what to do.
16417 Always use the @code{@@direntry} and @code{@@dircategory} commands near
16418 the beginning of the Texinfo input, before the first @code{@@node}
16419 command. If you use them later on in the input, @code{install-info}
16420 will not notice them.
16422 @code{install-info} will automatically reformat the description of the
16423 menu entries it is adding. As a matter of convention, the description
16424 of the main entry (above, @samp{The GNU documentation format}) should
16425 start at column 32, starting at zero (as in
16426 @code{what-cursor-position} in Emacs). This will make it align with
16427 most others. Description for individual utilities best start in
16428 column 48, where possible. For more information about formatting see
16429 the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
16430 @ref{Invoking install-info}.
16432 If you use @code{@@dircategory} more than once in the Texinfo source,
16433 each usage specifies the `current' category; any subsequent
16434 @code{@@direntry} commands will add to that category.
16436 @cindex Free Software Directory
16437 @cindex Dir categories, choosing
16438 @cindex Categories, choosing
16439 When choosing a category name for the @code{@@dircategory} command, we
16440 recommend consulting the @uref{http://www.gnu.org/directory,
16441 Free Software Directory}. If your program is not listed there,
16442 or listed incorrectly or incompletely, please report the situation to
16443 the directory maintainers (@email{bug-directory@@gnu.org}) so that the
16444 category names can be kept in sync.
16446 Here are a few examples (see the @file{util/dir-example} file in the
16447 Texinfo distribution for large sample @code{dir} file):
16453 Software development
16455 Text creation and manipulation
16458 @cindex Invoking nodes, including in dir file
16459 Each `Invoking' node for every program installed should have a
16460 corresponding @code{@@direntry}. This lets users easily find the
16461 documentation for the different programs they can run, as with the
16462 traditional @command{man} system.
16465 @node Invoking install-info
16466 @subsection Invoking @command{install-info}
16467 @pindex install-info
16469 @code{install-info} inserts menu entries from an Info file into the
16470 top-level @file{dir} file in the Info system (see the previous sections
16471 for an explanation of how the @file{dir} file works). @code{install-info}
16472 also removes menu entries from the @file{dir} file. It's most often
16473 run as part of software installation, or when constructing a @file{dir} file
16474 for all manuals on a system. Synopsis:
16477 install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
16480 If @var{info-file} or @var{dir-file} are not specified, the options
16481 (described below) that define them must be. There are no compile-time
16482 defaults, and standard input is never used. @code{install-info} can
16483 read only one Info file and write only one @file{dir} file per invocation.
16485 @cindex @file{dir}, created by @code{install-info}
16486 If @var{dir-file} (however specified) does not exist,
16487 @code{install-info} creates it if possible (with no entries).
16489 @cindex Compressed dir files, reading
16490 @cindex Bzipped dir files, reading
16491 @cindex LZMA-compressed dir files, reading
16492 @cindex Dir files, compressed
16493 If any input file is compressed with @code{gzip} (@pxref{Top,,,gzip,
16494 Gzip}), @code{install-info} automatically uncompresses it
16495 for reading. And if @var{dir-file} is compressed, @code{install-info}
16496 also automatically leaves it compressed after writing any changes.
16497 If @var{dir-file} itself does not exist, @code{install-info} tries to
16498 open @file{@var{dir-file}.gz}, @file{@var{dir-file}.bz2}, and
16499 @file{@var{dir-file}.lzma}, in that order.
16505 Specifies that the entry or entries will only be put into a single section.
16507 @item --align=@var{column}
16508 @opindex --align=@var{column}
16509 Specifies the column that the second and subsequent lines of menu entry's
16510 description will be formatted to begin at. The default for this option is
16511 @samp{35}. It is used in conjunction with the @samp{--max-width} option.
16512 @var{column} starts counting at 1.
16514 @item --append-new-sections
16515 Instead of alphabetizing new sections, place them at the end of the DIR file.
16517 @item --calign=@var{column}
16518 @opindex --calign=@var{column}
16519 Specifies the column that the first line of menu entry's description will
16520 be formatted to begin at. The default for this option is @samp{33}. It is
16521 used in conjunction with the @samp{--max-width} option.
16522 When the name of the menu entry exceeds this column, entry's description
16523 will start on the following line.
16524 @var{column} starts counting at 1.
16528 Report what is being done.
16532 Delete the entries in @var{info-file} from @var{dir-file}. The file
16533 name in the entry in @var{dir-file} must be @var{info-file} (except for
16534 an optional @samp{.info} in either one). Don't insert any new entries.
16535 Any empty sections that result from the removal are also removed.
16537 @item --description=@var{text}
16538 @opindex --description=@var{text}
16539 Specify the explanatory portion of the menu entry. If you don't specify
16540 a description (either via @samp{--entry}, @samp{--item} or this option),
16541 the description is taken from the Info file itself.
16543 @item --dir-file=@var{name}
16544 @opindex --dir-file=@var{name}
16545 Specify file name of the Info directory file. This is equivalent to
16546 using the @var{dir-file} argument.
16550 Same as @samp{--test}.
16552 @item --entry=@var{text}
16553 @opindex --entry=@var{text}
16554 Insert @var{text} as an Info directory entry; @var{text} should have the
16555 form of an Info menu item line plus zero or more extra lines starting
16556 with whitespace. If you specify more than one entry, they are all
16557 added. If you don't specify any entries, they are determined from
16558 information in the Info file itself.
16562 Display a usage message with basic usage and all available options,
16563 then exit successfully.
16565 @item --info-file=@var{file}
16566 @opindex --info-file=@var{file}
16567 Specify Info file to install in the directory. This is
16568 equivalent to using the @var{info-file} argument.
16570 @item --info-dir=@var{dir}
16571 @opindex --info-dir=@var{dir}
16572 Specify the directory where the directory file @file{dir} resides.
16573 Equivalent to @samp{--dir-file=@var{dir}/dir}.
16575 @item --infodir=@var{dir}
16576 @opindex --infodir=@var{dir}
16577 Same as @samp{--info-dir}.
16579 @item --item=@var{text}
16580 @opindex --item=@var{text}
16581 Same as @samp{--entry=@var{text}}. An Info directory entry is actually
16585 @opindex --keep-old
16586 Do not replace pre-existing menu entries. When @samp{--remove} is specified,
16587 this option means that empty sections are not removed.
16589 @item --max-width=@var{column}
16590 @opindex --max-width=@var{column}
16591 Specifies the column that the menu entry's description will be word-wrapped
16592 at. @var{column} starts counting at 1.
16594 @item --maxwidth=@var{column}
16595 @opindex --maxwidth=@var{column}
16596 Same as @samp{--max-width}.
16598 @item --menuentry=@var{text}
16599 @opindex --menuentry=@var{text}
16600 Same as @samp{--name}.
16602 @item --name=@var{text}
16603 @opindex --name=@var{text}
16604 Specify the name portion of the menu entry. If the @var{text} does
16605 not start with an asterisk @samp{*}, it is presumed to be the text
16606 after the @samp{*} and before the parentheses that specify the Info
16607 file. Otherwise @var{text} is taken verbatim, and is taken as
16608 defining the text up to and including the first period (a space is
16609 appended if necessary). If you don't specify the name (either via
16610 @samp{--entry}, @samp{--item} or this option), it is taken from the
16611 Info file itself. If the Info does not contain the name, the basename
16612 of the Info file is used.
16615 @opindex --no-indent
16616 Suppress formatting of new entries into the @file{dir} file.
16622 Suppress warnings, etc., for silent operation.
16626 Same as @samp{--delete}.
16628 @item --remove-exactly
16629 @opindex --remove-exactly
16630 Also like @samp{--delete}, but only entries if the Info file name
16631 matches exactly; @code{.info} and/or @code{.gz} suffixes are
16632 @emph{not} ignored.
16634 @item --section=@var{sec}
16635 @opindex --section=@var{sec}
16636 Put this file's entries in section @var{sec} of the directory. If you
16637 specify more than one section, all the entries are added in each of the
16638 sections. If you don't specify any sections, they are determined from
16639 information in the Info file itself. If the Info file doesn't specify
16640 a section, the menu entries are put into the Miscellaneous section.
16642 @item --section @var{regex} @var{sec}
16643 @opindex --section @var{regex} @var{sec}
16644 Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
16646 @code{install-info} tries to detect when this alternate syntax is used,
16647 but does not always guess correctly. Here is the heuristic that
16648 @code{install-info} uses:
16651 If the second argument to @code{--section} starts with a hyphen, the
16652 original syntax is presumed.
16654 If the second argument to @code{--section} is a file that can be
16655 opened, the original syntax is presumed.
16657 Otherwise the alternate syntax is used.
16660 When heuristic fails because your section title starts with a hyphen, or it
16661 happens to be a filename that can be opened, the syntax should be changed
16662 to @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
16665 @item --regex=@var{regex}
16666 @opindex --regex=@var{regex}
16667 Put this file's entries into any section that matches @var{regex}. If
16668 more than one section matches, all of the entries are added in each of the
16669 sections. Specify @var{regex} using basic regular expression syntax, more
16670 or less as used with @command{grep}, for example.
16674 Suppress updating of the directory file.
16678 @cindex Version number, for install-info
16679 Display version information and exit successfully.
16684 @node Generating HTML
16685 @chapter Generating HTML
16686 @cindex HTML output
16688 @command{makeinfo} generates Info output by default, but given the
16689 @option{--html} option, it will generate HTML, for web browsers and
16690 other programs. This chapter gives some details on such HTML output.
16693 @command{makeinfo} can also write in XML and Docbook format, but we do
16694 not as yet describe these further. @xref{Output Formats}, for a brief
16695 overview of all the output formats.
16698 * HTML Translation:: Details of the HTML output.
16699 * HTML Splitting:: How HTML output is split.
16700 * HTML CSS:: Influencing HTML output with Cascading Style Sheets.
16701 * HTML Xref:: Cross-references in HTML output.
16705 @node HTML Translation
16706 @section HTML Translation
16708 @command{makeinfo} will include segments of Texinfo source between
16709 @code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not
16710 any of the other conditionals, by default). Source between
16711 @code{@@html} and @code{@@end html} is passed without change to the
16712 output (i.e., suppressing the normal escaping of input @samp{<},
16713 @samp{>} and @samp{&} characters which have special significance in
16714 HTML). @xref{Conditional Commands}.
16716 @opindex --footnote-style@r{, ignored in HTML output}
16717 The @option{--footnote-style} option is currently ignored for HTML output;
16718 footnotes are always linked to the end of the output file.
16720 @cindex Navigation bar, in HTML output
16721 By default, a navigation bar is inserted at the start of each node,
16722 analogous to Info output. The @samp{--no-headers} option suppresses
16723 this if used with @samp{--no-split}. Header @code{<link>} elements in
16724 split output can support info-like navigation with browsers like Lynx
16725 and @w{Emacs W3} which implement this HTML@tie{}1.0 feature.
16727 @cindex HTML output, browser compatibility of
16728 The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866).
16729 One exception is that HTML@tie{}3.2 tables are generated from the
16730 @code{@@multitable} command, but tagged to degrade as well as possible
16731 in browsers without table support. The HTML@tie{}4 @samp{lang}
16732 attribute on the @samp{<html>} attribute is also used. (Please report
16733 output from an error-free run of @code{makeinfo} which has browser
16734 portability problems as a bug.)
16737 @node HTML Splitting
16738 @section HTML Splitting
16739 @cindex Split HTML output
16740 @cindex HTML output, split
16742 When splitting output (which is the default), @command{makeinfo}
16743 writes HTML output into (generally) one output file per Texinfo source
16746 The output file name is the node name with special characters replaced
16747 by @samp{-}'s, so it can work as a filename. In the unusual case of
16748 two different nodes having the same name after this treatment, they
16749 are written consecutively to the same file, with HTML anchors so each
16750 can be referred to separately. If @command{makeinfo} is run on a
16751 system which does not distinguish case in filenames, nodes which are
16752 the same except for case will also be folded into the same output
16755 When splitting, the HTML output files are written into a subdirectory,
16756 with the name chosen as follows:
16759 @command{makeinfo} first tries the subdirectory with the base name
16760 from @code{@@setfilename} (that is, any extension is removed). For
16761 example, HTML output for @code{@@setfilename gcc.info} would be
16762 written into a subdirectory named @samp{gcc}.
16765 If that directory cannot be created for any reason, then
16766 @command{makeinfo} tries appending @samp{.html} to the directory name.
16767 For example, output for @code{@@setfilename texinfo} would be written
16768 to @samp{texinfo.html}.
16771 If the @samp{@var{name}.html} directory can't be
16772 created either, @code{makeinfo} gives up.
16776 @noindent In any case, the top-level output file within the directory
16777 is always named @samp{index.html}.
16779 Monolithic output (@code{--no-split}) is named according to
16780 @code{@@setfilename} (with any @samp{.info} extension is replaced with
16781 @samp{.html}) or @code{--output} (the argument is used literally).
16786 @cindex HTML, and CSS
16787 @cindex CSS, and HTML output
16788 @cindex Cascading Style Sheets, and HTML output
16790 Cascading Style Sheets (CSS for short) is an Internet standard for
16791 influencing the display of HTML documents: see
16792 @uref{http://www.w3.org/Style/CSS/}.
16794 By default, @command{makeinfo} includes a few simple CSS commands to
16795 better implement the appearance of some of the environments. Here
16796 are two of them, as an example:
16799 pre.display @{ font-family:inherit @}
16800 pre.smalldisplay @{ font-family:inherit; font-size:smaller @}
16803 A full explanation of CSS is (far) beyond this manual; please see the
16804 reference above. In brief, however, this specification tells the web
16805 browser to use a `smaller' font size for @code{@@smalldisplay} text,
16806 and to use the `inherited' font (generally a regular roman typeface)
16807 for both @code{@@smalldisplay} and @code{@@display}. By default, the
16808 HTML @samp{<pre>} command uses a monospaced font.
16810 You can influence the CSS in the HTML output with two
16811 @command{makeinfo} options: @option{--css-include=@var{file}} and
16812 @option{--css-ref=@var{url}}.
16814 The option @option{--css-ref=@var{url}} adds to each output HTML file
16815 a @samp{<link>} tag referencing a CSS at the given @var{url}. This
16816 allows using external style sheets.
16818 The option @option{--css-include=@var{file}} includes the contents
16819 @var{file} in the HTML output, as you might expect. However, the
16820 details are somewhat tricky, as described in the following, to provide
16821 maximum flexibility.
16823 @cindex @@import specifications, in CSS files
16824 The CSS file may begin with so-called @samp{@@import} directives,
16825 which link to external CSS specifications for browsers to use when
16826 interpreting the document. Again, a full description is beyond our
16827 scope here, but we'll describe how they work syntactically, so we can
16828 explain how @command{makeinfo} handles them.
16830 @cindex Comments, in CSS files
16831 There can be more than one @samp{@@import}, but they have to come
16832 first in the file, with only whitespace and comments interspersed, no
16833 normal definitions. (Technical exception: an @samp{@@charset}
16834 directive may precede the @samp{@@import}'s. This does not alter
16835 @command{makeinfo}'s behavior, it just copies the @samp{@@charset} if
16836 present.) Comments in CSS files are delimited by @samp{/* ... */}, as
16837 in C. An @samp{@@import} directive must be in one of these two forms:
16840 @@import url(http://example.org/foo.css);
16841 @@import "http://example.net/bar.css";
16844 As far as @command{makeinfo} is concerned, the crucial characters are
16845 the @samp{@@} at the beginning and the semicolon terminating the
16846 directive. When reading the CSS file, it simply copies any such
16847 @samp{@@}-directive into the output, as follows:
16850 @item If @var{file} contains only normal CSS declarations, it is
16851 included after @command{makeinfo}'s default CSS, thus overriding it.
16853 @item If @var{file} begins with @samp{@@import} specifications (see
16854 below), then the @samp{import}'s are included first (they have to come
16855 first, according to the standard), and then @command{makeinfo}'s
16856 default CSS is included. If you need to override @command{makeinfo}'s
16857 defaults from an @samp{@@import}, you can do so with the @samp{!@:
16858 important} CSS construct, as in:
16860 pre.smallexample @{ font-size: inherit ! important @}
16863 @item If @var{file} contains both @samp{@@import} and inline CSS
16864 specifications, the @samp{@@import}'s are included first, then
16865 @command{makeinfo}'s defaults, and lastly the inline CSS from
16868 @item Any @@-directive other than @samp{@@import} and @samp{@@charset}
16869 is treated as a CSS declaration, meaning @command{makeinfo} includes
16870 its default CSS and then the rest of the file.
16874 If the CSS file is malformed or erroneous, @command{makeinfo}'s output
16875 is unspecified. @command{makeinfo} does not try to interpret the
16876 meaning of the CSS file in any way; it just looks for the special
16877 @samp{@@} and @samp{;} characters and blindly copies the text into the
16878 output. Comments in the CSS file may or may not be included in the
16883 @section HTML Cross-references
16884 @cindex HTML cross-references
16885 @cindex Cross-references, in HTML output
16887 Cross-references between Texinfo manuals in HTML format amount, in the
16888 end, to a standard HTML @code{<a>} link, but the details are
16889 unfortunately complex. This section describes the algorithm used in
16890 detail, so that Texinfo can cooperate with other programs, such as
16891 @command{texi2html}, by writing mutually compatible HTML files.
16893 This algorithm may or may not be used for links @emph{within} HTML
16894 output for a Texinfo file. Since no issues of compatibility arise in
16895 such cases, we do not need to specify this.
16897 We try to support references to such ``external'' manuals in both
16898 monolithic and split forms. A @dfn{monolithic} (mono) manual is
16899 entirely contained in one file, and a @dfn{split} manual has a file
16900 for each node. (@xref{HTML Splitting}.)
16902 @cindex Dumas, Patrice
16903 Acknowledgement: this algorithm was primarily devised by Patrice Dumas
16907 * Link Basics: HTML Xref Link Basics.
16908 * Node Expansion: HTML Xref Node Name Expansion.
16909 * Command Expansion: HTML Xref Command Expansion.
16910 * 8-bit Expansion: HTML Xref 8-bit Character Expansion.
16911 * Mismatch: HTML Xref Mismatch.
16915 @node HTML Xref Link Basics
16916 @subsection HTML Cross-reference Link Basics
16917 @cindex HTML cross-reference link basics
16919 For our purposes, an HTML link consists of four components: a host
16920 name, a directory part, a file part, and a target part. We
16921 always assume the @code{http} protocol. For example:
16924 http://@var{host}/@var{dir}/@var{file}.html#@var{target}
16927 The information to construct a link comes from the node name and
16928 manual name in the cross-reference command in the Texinfo source
16929 (@pxref{Cross References}), and from @dfn{external information}, which
16930 is currently simply hardwired. In the future, it may come from an
16931 external data file.
16933 We now consider each part in turn.
16935 The @var{host} is hardwired to be the local host. This could either
16936 be the literal string @samp{localhost}, or, according to the rules for
16937 HTML links, the @samp{http://localhost/} could be omitted entirely.
16939 The @var{dir} and @var{file} parts are more complicated, and depend on
16940 the relative split/mono nature of both the manual being processed and
16941 the manual that the cross-reference refers to. The underlying idea is
16942 that there is one directory for Texinfo manuals in HTML, and a given
16943 @var{manual} is either available as a monolithic file
16944 @file{@var{manual}.html}, or a split subdirectory
16945 @file{@var{manual}/*.html}. Here are the cases:
16949 If the present manual is split, and the referent manual is also split,
16950 the directory is @samp{../@var{referent/}} and the file is the
16951 expanded node name (described later).
16954 If the present manual is split, and the referent manual is mono, the
16955 directory is @samp{../} and the file is @file{@var{referent}.html}.
16958 If the present manual is mono, and the referent manual is split, the
16959 directory is @file{@var{referent}/} and the file is the expanded node
16963 If the present manual is mono, and the referent manual is also mono,
16964 the directory is @file{./} (or just the empty string), and the file is
16965 @file{@var{referent}.html}.
16969 One exception: the algorithm for node name expansion prefixes the
16970 string @samp{g_t} when the node name begins with a non-letter. This
16971 kludge (due to XHTML rules) is not necessary for filenames, and is
16974 Any directory part in the filename argument of the source
16975 cross-reference command is ignored. Thus, @code{@@xref@{,,,../foo@}}
16976 and @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name.
16977 This is because any such attempted hardwiring of the directory is very
16978 unlikely to be useful for both Info and HTML output.
16980 Finally, the @var{target} part is always the expanded node name.
16982 Whether the present manual is split or mono is determined by user
16983 option; @command{makeinfo} defaults to split, with the
16984 @option{--no-split} option overriding this.
16986 Whether the referent manual is split or mono is another bit of the
16987 external information. For now, @command{makeinfo} simply assumes the
16988 referent manual is the same as the present manual.
16990 There can be a mismatch between the format of the referent manual that
16991 the generating software assumes, and the format it's actually present
16992 in. @xref{HTML Xref Mismatch}.
16995 @node HTML Xref Node Name Expansion
16996 @subsection HTML Cross-reference Node Name Expansion
16997 @cindex HTML cross-reference node name expansion
16998 @cindex node name expansion, in HTML cross-references
16999 @cindex expansion, of node names in HTML cross-references
17001 As mentioned in the previous section, the key part of the HTML
17002 cross-reference algorithm is the conversion of node names in the
17003 Texinfo source into strings suitable for XHTML identifiers and
17004 filenames. The restrictions are similar for each: plain ASCII
17005 letters, numbers, and the @samp{-} and @samp{_} characters are all
17006 that can be used. (Although HTML anchors can contain most characters,
17007 XHTML is more restrictive.)
17009 Cross-references in Texinfo can actually refer either to nodes or
17010 anchors (@pxref{anchor}), but anchors are treated identically to nodes
17011 in this context, so we'll continue to say ``node'' names for
17014 (@@-commands and 8-bit characters are not presently handled by
17015 @command{makeinfo} for HTML cross-references. See the next section.)
17017 A special exception: the Top node (@pxref{The Top Node}) is always
17018 mapped to the file @file{index.html}, to match web server software.
17019 However, the HTML @emph{target} is @samp{Top}. Thus (in the split case):
17022 @@xref@{Top, Introduction,, emacs, The GNU Emacs Manual@}.
17023 @result{} <a href="emacs/index.html#Top">
17028 The standard ASCII letters (a-z and A-Z) are not modified. All other
17029 characters are changed as specified below.
17032 The standard ASCII numbers (0-9) are not modified except when a number
17033 is the first character of the node name. In that case, see below.
17036 Multiple consecutive space, tab and newline characters are transformed
17037 into just one space. (It's not possible to have newlines in node
17038 names with the current implementation, but we specify it anyway, just
17042 Leading and trailing spaces are removed.
17045 After the above has been applied, each remaining space character is
17046 converted into a @samp{-} character.
17049 Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}},
17050 where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
17051 This includes @samp{_}, which is mapped to @samp{_005f}.
17054 If the node name does not begin with a letter, the literal string
17055 @samp{g_t} is prefixed to the result. (Due to the rules above, that
17056 string can never occur otherwise; it is an arbitrary choice, standing
17057 for ``GNU Texinfo''.) This is necessary because XHTML requires that
17058 identifiers begin with a letter.
17065 @@node A node --- with _'%
17066 @result{} A-node-_002d_002d_002d-with-_005f_0027_0025
17069 Notice in particular:
17072 @item @samp{_} @result{} @samp{_005f}
17073 @item @samp{-} @result{} @samp{_002d}
17074 @item @samp{A node} @result{} @samp{A-node}
17077 On case-folding computer systems, nodes differing only by case will be
17078 mapped to the same file.
17080 In particular, as mentioned above, Top always maps to the file
17081 @file{index.html}. Thus, on a case-folding system, Top and a node
17082 named `Index' will both be written to @file{index.html}.
17084 Fortunately, the targets serve to distinguish these cases, since HTML
17085 target names are always case-sensitive, independent of operating
17089 @node HTML Xref Command Expansion
17090 @subsection HTML Cross-reference Command Expansion
17091 @cindex HTML cross-reference command expansion
17093 In standard Texinfo, node names may not contain @@-commands.
17094 @command{makeinfo} has an option @option{--commands-in-node-names}
17095 which partially supports it (@pxref{Invoking makeinfo}), but it is not
17096 robust and not recommended.
17098 Thus, @command{makeinfo} does not fully implement this part of the
17099 HTML cross-reference algorithm, but it is documented here for the sake
17102 First, comments are removed.
17104 Next, any @code{@@value} commands (@pxref{set value}) and macro invocations
17105 (@pxref{Invoking Macros}) are fully expanded.
17107 Then, for the following commands, the command name and braces are removed,
17108 the text of the argument is recursively transformed:
17110 @@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
17111 @@emph @@env @@file @@indicateurl @@kbd @@key
17112 @@samp @@sc @@slanted @@strong @@t @@var @@w
17115 @noindent For @code{@@sc}, any letters are capitalized.
17117 The following commands are replaced by constant text, as shown. If
17118 any of these commands have non-empty arguments, as in
17119 @code{@@TeX@{bad@}}, it is an error, and the result is unspecified.
17120 `(space)' means a space character, `(nothing)' means the empty string,
17121 etc. The notation `U+@var{xxxx}' means Unicode code point @var{xxxx}
17122 (in hex, as usual). There are further transformations of many of
17123 these expansions for the final file or target name, such as space
17124 characters to @samp{-}, etc., according to the other rules.
17126 @multitable @columnfractions .3 .5
17127 @item @code{@@(newline)} @tab (space)
17128 @item @code{@@(space)} @tab (space)
17129 @item @code{@@(tab)} @tab (space)
17130 @item @code{@@!} @tab @samp{!}
17131 @item @code{@@*} @tab (space)
17132 @item @code{@@-} @tab (nothing)
17133 @item @code{@@.} @tab @samp{.}
17134 @item @code{@@:} @tab (nothing)
17135 @item @code{@@?} @tab @samp{?}
17136 @item @code{@@@@} @tab @samp{@@}
17137 @item @code{@@@{} @tab @samp{@{}
17138 @item @code{@@@}} @tab @samp{@}}
17139 @item @code{@@LaTeX} @tab @samp{LaTeX}
17140 @item @code{@@TeX} @tab @samp{TeX}
17141 @item @code{@@arrow} @tab U+2192
17142 @item @code{@@bullet} @tab U+2022
17143 @item @code{@@comma} @tab @samp{,}
17144 @item @code{@@copyright} @tab U+00A9
17145 @item @code{@@dots} @tab U+2026
17146 @item @code{@@enddots} @tab @samp{...}
17147 @item @code{@@equiv} @tab U+2261
17148 @item @code{@@error} @tab @samp{error-->}
17149 @item @code{@@euro} @tab U+20AC
17150 @item @code{@@exclamdown} @tab U+00A1
17151 @item @code{@@expansion} @tab U+2192
17152 @item @code{@@geq} @tab U+2265
17153 @item @code{@@leq} @tab U+2264
17154 @item @code{@@minus} @tab U+2212
17155 @item @code{@@ordf} @tab U+00AA
17156 @item @code{@@ordm} @tab U+00BA
17157 @item @code{@@point} @tab U+2605
17158 @item @code{@@pounds} @tab U+00A3
17159 @item @code{@@print} @tab U+22A3
17160 @item @code{@@questiondown} @tab U+00BF
17161 @item @code{@@registeredsymbol} @tab U+00AE
17162 @item @code{@@result} @tab U+21D2
17163 @item @code{@@textdegree} @tab U+00B0
17164 @item @code{@@tie} @tab (space)
17167 Quotation mark commands are likewise replaced by their Unicode values
17168 (@pxref{Inserting Quotation Marks}).
17170 An @code{@@acronym} or @code{@@abbr} command is replaced by the first
17171 argument, followed by the second argument in parentheses, if present.
17174 An @code{@@email} command is replaced by the @var{text} argument if
17175 present, else the address. @xref{email}.
17177 An @code{@@image} command is replaced by the filename (first)
17178 argument. @xref{Images}.
17180 A @code{@@verb} command is replaced by its transformed argument.
17183 Any other command is an error, and the result is unspecified.
17186 @node HTML Xref 8-bit Character Expansion
17187 @subsection HTML Cross-reference 8-bit Character Expansion
17188 @cindex HTML cross-reference 8-bit character expansion
17189 @cindex 8-bit characters, in HTML cross-references
17190 @cindex Expansion of 8-bit characters in HTML cross-references
17191 @cindex Transliteration of 8-bit characters in HTML cross-references
17193 Usually, characters other than plain 7-bit ASCII are transformed into
17194 the corresponding Unicode code point(s) in Normalization Form C, which
17195 uses precomposed characters where available. (This is the
17196 normalization form recommended by the W3C and other bodies.) This
17197 holds when that code point is 0xffff or less, as it almost always is.
17199 These will then be further transformed by the rules above into the
17200 string @samp{_@var{xxxx}}, where @var{xxxx} is the code point in hex.
17202 For example, combining this rule and the previous section:
17205 @@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@}
17206 @result{} A-TeX-B_0306-_2605_002e_002e_002e
17209 Notice: 1)@tie{}@code{@@enddots} expands to three periods which in
17210 turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B'
17211 with a breve accent, which does not exist as a pre-accented Unicode
17212 character, therefore expands to @samp{B_0306} (B with combining
17215 When the Unicode code point is above 0xffff, the transformation is
17216 @samp{__@var{xxxxxx}}, that is, two leading underscores followed by
17217 six hex digits. Since Unicode has declared that their highest code
17218 point is 0x10ffff, this is sufficient. (We felt it was better to
17219 define this extra escape than to always use six hex digits, since the
17220 first two would nearly always be zeros.)
17222 This method works fine if the node name consists mostly of ASCII
17223 characters and contains only few 8-bit ones. If the document is
17224 written in a language whose script is not based on the Latin alphabet
17225 (such as, e.g. Ukrainian), it will create file names consisting
17226 entirely of @samp{_@var{xxxx}} notations, which is inconvenient.
17228 To handle such cases, @command{makeinfo} offers
17229 @option{--transliterate-file-names} command line option. This option
17230 enables @dfn{transliteration} of node names into ASCII characters for
17231 the purposes of file name creation and referencing. The
17232 transliteration is based on phonetic principle, which makes the
17233 produced file names easily readable.
17235 For the definition of Unicode Normalization Form C, see Unicode report
17236 UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many related
17237 documents and implementations are available elsewhere on the web.
17240 @node HTML Xref Mismatch
17241 @subsection HTML Cross-reference Mismatch
17242 @cindex HTML cross-reference mismatch
17243 @cindex Mismatched HTML cross-reference source and target
17245 As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
17246 software has to guess whether a given manual being cross-referenced is
17247 available in split or monolithic form---and, inevitably, it might
17248 guess wrong. However, it is possible when the referent manual itself
17249 is generated, it is possible to handle at least some mismatches.
17251 In the case where we assume the referent is split, but it is actually
17252 available in mono, the only recourse would be to generate a
17253 @file{manual/} subdirectory full of HTML files which redirect back to
17254 the monolithic @file{manual.html}. Since this is essentially the same
17255 as a split manual in the first place, it's not very appealing.
17257 On the other hand, in the case where we assume the referent is mono,
17258 but it is actually available in split, it is possible to use
17259 JavaScript to redirect from the putatively monolithic
17260 @file{manual.html} to the different @file{manual/node.html} files.
17264 function redirect() @{
17265 switch (location.hash) @{
17267 location.replace("manual/Node1.html#Node1"); break;
17269 location.replace("manual/Node2.html#Node2"); break;
17276 Then, in the @code{<body>} tag of @file{manual.html}:
17279 <body onLoad="redirect();">
17282 Once again, this is something the software which generated the
17283 @emph{referent} manual has to do in advance, it's not something the
17284 software generating the actual cross-reference in the present manual
17287 Ultimately, we hope to allow for an external configuration file to
17288 control which manuals are available from where, and how.
17294 external information
17295 --------------------
17297 The information for the reference is searched in the file
17298 `htmlxref.cnf' present in the following directories:
17299 <srcdir>/.texinfo/, ~/.texinfo/, SYSCONFDIR/texinfo/,
17301 The first match should be used.
17303 The file is line-oriented, with the following format:
17304 <manualname> <whitespace> <keyword> <whitespace> <urlprefix>
17305 with <keyword> being "mono" or "split". Thus
17306 texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/
17307 texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
17309 If the keyword is 'split', that is the target is split, the urlprefix gives
17310 the directory and host name.
17311 If the keyword is 'mono', that is the target is mono, the urlprefix gives
17312 directory, host and file name.
17314 '#' followed by a space begins comments. '#' followed by another character
17315 cannot begin comments as there are # in urls.
17321 @appendix @@-Command List
17322 @cindex Alphabetical @@-command list
17323 @cindex List of @@-commands
17324 @cindex @@-command list
17325 @cindex Reference to @@-commands
17327 Here is an alphabetical list of the @@-commands in Texinfo. Square
17328 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
17329 @samp{@dots{}}, indicates repeated text.
17331 More specifics on the general syntax of different @@-commands are
17332 given in the section below.
17335 * Command Syntax:: General syntax for varieties of @@-commands.
17340 @item @@@var{whitespace}
17341 An @code{@@} followed by a space, tab, or newline produces a normal,
17342 stretchable, interword space. @xref{Multiple Spaces}.
17345 Produce an exclamation point that ends a sentence (usually after an
17346 end-of-sentence capital letter). @xref{Ending a Sentence}.
17350 Generate an umlaut or acute accent, respectively, over the next
17351 character, as in @"o and @'o. @xref{Inserting Accents}.
17354 Force a line break. @xref{Line Breaks}.
17356 @item @@,@{@var{c}@}
17357 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
17361 Insert a discretionary hyphenation point. @xref{- and hyphenation}.
17364 Produce a period that ends a sentence (usually after an
17365 end-of-sentence capital letter). @xref{Ending a Sentence}.
17368 Produces no output, but allows a line break. @xref{Line Breaks}.
17371 Tell @TeX{} to refrain from inserting extra whitespace after an
17372 immediately preceding period, question mark, exclamation mark, or
17373 colon, as @TeX{} normally would. @xref{Not Ending a Sentence}.
17376 Generate a macron (bar) accent over the next character, as in @=o.
17377 @xref{Inserting Accents}.
17380 Produce a question mark that ends a sentence (usually after an
17381 end-of-sentence capital letter). @xref{Ending a Sentence}.
17384 Stands for an at sign, @samp{@@}.
17385 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
17388 Stands for a backslash (@samp{\}) inside @code{@@math}.
17389 @xref{math,,@code{math}}.
17393 Generate a circumflex (hat) or grave accent, respectively, over the next
17394 character, as in @^o and @`e.
17395 @xref{Inserting Accents}.
17398 Stands for a left brace, @samp{@{}.
17399 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
17402 Stands for a right-hand brace, @samp{@}}.@*
17403 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
17406 Generate a tilde accent over the next character, as in @~N.
17407 @xref{Inserting Accents}.
17411 Generate the uppercase and lowercase Scandinavian A-ring letters,
17412 respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
17414 @item @@abbr@{@var{abbreviation}@}
17415 Indicate a general abbreviation, such as `Comput.'. @xref{abbr,,
17418 @item @@acronym@{@var{acronym}@}
17419 Indicate an acronym in all capital letters, such as `NASA'.
17420 @xref{acronym,, @code{acronym}}.
17424 Generate the uppercase and lowercase AE ligatures, respectively:
17425 @AE{}, @ae{}. @xref{Inserting Accents}.
17427 @itemx @@afivepaper
17428 Change page dimensions for the A5 paper size. @xref{A4 Paper}.
17431 @itemx @@afourpaper
17433 Change page dimensions for the A4 paper size. @xref{A4 Paper}.
17435 @item @@alias @var{new}=@var{existing}
17436 Make the command @samp{@@@var{new}} a synonym for the existing command
17437 @samp{@@@var{existing}}. @xref{alias}.
17439 @item @@anchor@{@var{name}@}
17440 Define @var{name} as the current location for use as a cross-reference
17441 target. @xref{anchor,, @code{@@anchor}}.
17443 @item @@appendix @var{title}
17444 Begin an appendix. The title appears in the table of contents. In
17445 Info, the title is underlined with asterisks. @xref{unnumbered &
17446 appendix, , The @code{@@unnumbered} and @code{@@appendix} Commands}.
17448 @item @@appendixsec @var{title}
17449 @itemx @@appendixsection @var{title}
17450 Begin an appendix section within an appendix. The section title
17451 appears in the table of contents. In Info, the title is underlined
17452 with equal signs. @code{@@appendixsection} is a longer spelling of
17453 the @code{@@appendixsec} command. @xref{unnumberedsec appendixsec
17454 heading, , Section Commands}.
17456 @item @@appendixsubsec @var{title}
17457 Begin an appendix subsection. The title appears in the table of
17458 contents. In Info, the title is underlined with hyphens.
17459 @xref{unnumberedsubsec appendixsubsec subheading, , Subsection
17462 @item @@appendixsubsubsec @var{title}
17463 Begin an appendix subsubsection. The title appears in the table of
17464 contents. In Info, the title is underlined with periods.
17465 @xref{subsubsection,, The `subsub' Commands}.
17468 Generate a right arrow glyph: @samp{@arrow{}}. Used by default
17469 for @code{@@click}. @xref{Click Sequences}.
17472 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
17473 print the table's first column without highlighting (``as is'').
17474 @xref{Two-column Tables}.
17476 @item @@author @var{author}
17477 Typeset @var{author} flushleft and underline it. @xref{title
17478 subtitle author, , The @code{@@title} and @code{@@author}
17481 @item @@b@{@var{text}@}
17482 Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}.
17486 Force a paragraph break. If used within a line, follow @code{@@br}
17487 with braces. @xref{br, , @code{@@br}}.@refill
17491 Generate a large round dot, @bullet{} (@samp{*} in Info). Often used
17492 with @code{@@table}. @xref{bullet, , @code{@@bullet}}.
17495 Stop formatting a file. The formatters do not see anything in the
17496 input file following @code{@@bye}. @xref{Ending a File}.
17498 @item @@c @var{comment}
17499 Begin a comment in Texinfo. The rest of the line does not appear in
17500 any output. A synonym for
17501 @code{@@comment}. @xref{Comments}.
17504 Define the full caption for a @code{@@float}. @xref{caption shortcaption}.
17507 Highlight an example or quotation by drawing a box with rounded
17508 corners around it. Pair with @code{@@end cartouche}. No effect in
17509 Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
17511 @item @@center @var{line-of-text}
17512 Center the line of text following the command.
17513 @xref{titlefont center sp, , @code{@@center}}.@refill
17515 @item @@centerchap @var{line-of-text}
17516 Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
17519 @item @@chapheading @var{title}
17520 Print an unnumbered chapter-like heading, but omit from the table of
17521 contents. In Info, the title is underlined with asterisks.
17522 @xref{majorheading & chapheading, , @code{@@majorheading} and
17523 @code{@@chapheading}}.
17525 @item @@chapter @var{title}
17526 Begin a numbered chapter. The chapter title appears in the table of
17527 contents. In Info, the title is underlined with asterisks.
17528 @xref{chapter, , @code{@@chapter}}.
17530 @item @@cindex @var{entry}
17531 Add @var{entry} to the index of concepts. @xref{Index Entries, ,
17532 Defining the Entries of an Index}.@refill
17534 @item @@cite@{@var{reference}@}
17535 Highlight the name of a book or other reference that has no companion
17536 Info file. @xref{cite, , @code{@@cite}}.
17539 Represent a single ``click'' in a GUI. Used within
17540 @code{@@clicksequence}. @xref{Click Sequences}.
17542 @item @@clicksequence@{@var{action} @@click@{@} @var{action}@}
17543 Represent a sequence of clicks in a GUI. @xref{Click Sequences}.
17545 @item @@clickstyle @@@var{cmd}
17546 Execute @@@var{cmd} for each @code{@@click}; the default is
17547 @code{@@arrow}. The usual following empty braces on @@@var{cmd} are
17548 omitted. @xref{Click Sequences}.
17550 @item @@clear @var{flag}
17551 Unset @var{flag}, preventing the Texinfo formatting commands from
17552 formatting text between subsequent pairs of @code{@@ifset @var{flag}}
17553 and @code{@@end ifset} commands, and preventing
17554 @code{@@value@{@var{flag}@}} from expanding to the value to which
17556 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
17558 @item @@code@{@var{sample-code}@}
17559 Indicate an expression, a syntactically complete token of a program,
17560 or a program name. Unquoted in Info output. @xref{code, ,
17564 Insert a comma `,' character; only needed when a literal comma would
17565 be taken as an argument separator. @xref{Inserting a Comma}.
17567 @item @@command@{@var{command-name}@}
17568 Indicate a command name, such as @command{ls}.
17569 @xref{command,, @code{@@command}}.
17571 @item @@comment @var{comment}
17572 Begin a comment in Texinfo. The rest of the line does not appear in
17573 any output. A synonym for @code{@@c}.
17577 Print a complete table of contents. Has no effect in Info, which uses
17578 menus instead. @xref{Contents, , Generating a Table of
17581 @item @@copyright@{@}
17582 Generate the copyright symbol @copyright{}. @xref{copyright symbol,,
17583 @code{@@copyright@{@}}}.
17586 @item @@ctrl@{@var{ctrl-char}@}
17587 Describe an ASCII control character. Insert actual control character
17588 into Info file. @xref{ctrl, , @code{@@ctrl}}.
17591 @item @@defcodeindex @var{index-name}
17592 Define a new index and its indexing command. Print entries in an
17593 @code{@@code} font. @xref{New Indices, , Defining New Indices}.
17595 @item @@defcv @var{category} @var{class} @var{name}
17596 @itemx @@defcvx @var{category} @var{class} @var{name}
17597 Format a description for a variable associated with a class in
17598 object-oriented programming. Takes three arguments: the category of
17599 thing being defined, the class to which it belongs, and its name.
17600 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17602 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
17603 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
17604 Format a description for a function, interactive command, or similar
17605 entity that may take arguments. @code{@@deffn} takes as arguments the
17606 category of entity being described, the name of this particular
17607 entity, and its arguments, if any. @xref{Definition Commands}.@refill
17609 @item @@defindex @var{index-name}
17610 Define a new index and its indexing command. Print entries in a roman
17611 font. @xref{New Indices, , Defining New Indices}.@refill
17613 @item @@definfoenclose @var{newcmd}, @var{before}, @var{after}
17614 Must be used within @code{@@ifinfo}; create a new command
17615 @code{@@@var{newcmd}} for Info that marks text by enclosing it in
17616 strings that precede and follow the text. @xref{definfoenclose}.
17618 @item @@defivar @var{class} @var{instance-variable-name}
17619 @itemx @@defivarx @var{class} @var{instance-variable-name}
17620 Format a description for an instance variable in object-oriented
17621 programming. The command is equivalent to @samp{@@defcv @{Instance
17622 Variable@} @dots{}}. @xref{Definition Commands}, and @ref{deffnx,,
17623 Def Cmds in Detail}.
17625 @item @@defmac @var{macroname} @var{arguments}@dots{}
17626 @itemx @@defmacx @var{macroname} @var{arguments}@dots{}
17627 Format a description for a macro; equivalent to @samp{@@deffn Macro
17628 @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
17631 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
17632 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
17633 Format a description for a method in object-oriented programming;
17634 equivalent to @samp{@@defop Method @dots{}}. @xref{Definition
17635 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17637 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
17638 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
17639 Format a description for an operation in object-oriented programming.
17640 @code{@@defop} takes as arguments the name of the category of
17641 operation, the name of the operation's class, the name of the
17642 operation, and its arguments, if any. @xref{Definition Commands}, and
17643 @ref{Abstract Objects}.
17645 @item @@defopt @var{option-name}
17646 @itemx @@defoptx @var{option-name}
17647 Format a description for a user option; equivalent to @samp{@@defvr
17648 @{User Option@} @dots{}}. @xref{Definition Commands}, and
17649 @ref{deffnx,, Def Cmds in Detail}.
17651 @item @@defspec @var{special-form-name} @var{arguments}@dots{}
17652 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
17653 Format a description for a special form; equivalent to @samp{@@deffn
17654 @{Special Form@} @dots{}}. @xref{Definition Commands}, and
17655 @ref{deffnx,, Def Cmds in Detail}.
17657 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
17658 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
17659 Format a description for a data type; its arguments are the category,
17660 the name of the type (e.g., @samp{int}) , and then the names of
17661 attributes of objects of that type. @xref{Definition Commands}, and
17664 @item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
17665 @itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name}
17666 Format a description for a typed class variable in object-oriented programming.
17667 @xref{Definition Commands}, and @ref{Abstract Objects}.
17669 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
17670 @itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
17671 Format a description for a function or similar entity that may take
17672 arguments and that is typed. @code{@@deftypefn} takes as arguments the
17673 category of entity being described, the type, the name of the
17674 entity, and its arguments, if any. @xref{Definition Commands}, and
17675 @ref{deffnx,, Def Cmds in Detail}.
17677 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
17678 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
17679 Format a description for a function in a typed language.
17680 The command is equivalent to @samp{@@deftypefn Function @dots{}}.
17681 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17683 @item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
17684 @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
17685 Format a description for a typed instance variable in object-oriented
17686 programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
17688 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
17689 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
17690 Format a description for a typed method in object-oriented programming.
17691 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17693 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
17694 @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
17695 Format a description for a typed operation in object-oriented programming.
17696 @xref{Definition Commands}, and @ref{Abstract Objects}.
17698 @item @@deftypevar @var{data-type} @var{variable-name}
17699 @itemx @@deftypevarx @var{data-type} @var{variable-name}
17700 Format a description for a variable in a typed language. The command is
17701 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
17702 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17704 @item @@deftypevr @var{category} @var{data-type} @var{name}
17705 @itemx @@deftypevrx @var{category} @var{data-type} @var{name}
17706 Format a description for something like a variable in a typed
17707 language---an entity that records a value. Takes as arguments the
17708 category of entity being described, the type, and the name of the
17709 entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
17712 @item @@defun @var{function-name} @var{arguments}@dots{}
17713 @itemx @@defunx @var{function-name} @var{arguments}@dots{}
17714 Format a description for a function; equivalent to
17715 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
17716 @ref{deffnx,, Def Cmds in Detail}.
17718 @item @@defvar @var{variable-name}
17719 @itemx @@defvarx @var{variable-name}
17720 Format a description for a variable; equivalent to @samp{@@defvr
17721 Variable @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def
17724 @item @@defvr @var{category} @var{name}
17725 @itemx @@defvrx @var{category} @var{name}
17726 Format a description for any kind of variable. @code{@@defvr} takes
17727 as arguments the category of the entity and the name of the entity.
17728 @xref{Definition Commands},
17729 and @ref{deffnx,, Def Cmds in Detail}.
17732 Mark the (optional) detailed node listing in a master menu.
17733 @xref{Master Menu Parts}.
17735 @item @@dfn@{@var{term}@}
17736 Indicate the introductory or defining use of a term. @xref{dfn, ,
17739 @item @@dircategory @var{dirpart}
17740 Specify a part of the Info directory menu where this file's entry should
17741 go. @xref{Installing Dir Entries}.
17744 Begin the Info directory menu entry for this file. Pair with
17745 @code{@@end direntry}. @xref{Installing Dir Entries}.
17748 Begin a kind of example. Like @code{@@example} (indent text, do not
17749 fill), but do not select a new font. Pair with @code{@@end display}.
17750 @xref{display, , @code{@@display}}.
17752 @item @@dmn@{@var{dimension}@}
17753 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
17754 thin space before @var{dimension}. No effect in Info.
17755 @xref{dmn, , @code{@@dmn}}.
17758 Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw
17759 Formatter Commands}.
17761 @item @@documentdescription
17762 Set the document description text, included in the HTML output. Pair
17763 with @code{@@end documentdescription}. @xref{documentdescription,,
17764 @code{@@documentdescription}}.
17766 @item @@documentencoding @var{enc}
17767 Declare the input encoding to be @var{enc}.
17768 @xref{documentencoding,, @code{@@documentencoding}}.
17770 @item @@documentlanguage @var{CC}
17771 Declare the document language as the two-character ISO-639 abbreviation
17772 @var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}.
17774 @item @@dotaccent@{@var{c}@}
17775 Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
17776 @xref{Inserting Accents}.
17779 Generate an ellipsis, @samp{@dots{}}.
17780 @xref{dots, , @code{@@dots}}.@refill
17782 @item @@email@{@var{address}[, @var{displayed-text}]@}
17783 Indicate an electronic mail address.
17784 @xref{email, , @code{@@email}}.
17786 @item @@emph@{@var{text}@}
17787 Emphasize @var{text}, by using @emph{italics} where possible, and
17788 enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}.
17790 @item @@end @var{environment}
17791 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
17792 Commands,,@@-commands}.
17794 @item @@env@{@var{environment-variable}@}
17795 Indicate an environment variable name, such as @env{PATH}.
17796 @xref{env,, @code{@@env}}.
17798 @item @@enddots@{@}
17799 Generate an end-of-sentence ellipsis, like this: @enddots{}
17800 @xref{dots,,@code{@@dots@{@}}}.
17802 @item @@enumerate [@var{number-or-letter}]
17803 Begin a numbered list, using @code{@@item} for each entry.
17804 Optionally, start list with @var{number-or-letter}. Pair with
17805 @code{@@end enumerate}. @xref{enumerate, ,
17806 @code{@@enumerate}}.@refill
17809 Indicate to the reader the exact equivalence of two forms with a
17810 glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
17813 Generate the Euro currency sign.
17814 @xref{euro,,@code{@@euro@{@}}}.
17817 Indicate to the reader with a glyph that the following text is
17818 an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
17820 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
17821 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
17822 Specify page footings resp.@: headings for even-numbered (left-hand)
17823 pages. @xref{Custom Headings, ,
17824 How to Make Your Own Headings}.@refill
17826 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
17827 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
17828 Specify page footings resp.@: headings for every page. Not relevant to
17829 Info. @xref{Custom Headings, , How to Make Your Own Headings}.
17832 Begin an example. Indent text, do not fill, and select fixed-width
17833 font. Pair with @code{@@end example}. @xref{example,, @code{@@example}}.
17835 @item @@exampleindent @var{indent}
17836 Indent example-like environments by @var{indent} number of spaces
17837 (perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
17839 @item @@exclamdown@{@}
17840 Generate an upside-down exclamation point. @xref{Inserting Accents}.
17842 @item @@exdent @var{line-of-text}
17843 Remove any indentation a line might have. @xref{exdent, ,
17844 Undoing the Indentation of a Line}.@refill
17846 @item @@expansion@{@}
17847 Indicate the result of a macro expansion to the reader with a special
17848 glyph: @samp{@expansion{}}.
17849 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
17851 @item @@file@{@var{filename}@}
17852 Highlight the name of a file, buffer, node, directory, etc. @xref{file, ,
17856 Prevent @TeX{} from printing large black warning rectangles beside
17857 over-wide lines. @xref{Overfull hboxes}.@refill
17859 @item @@findex @var{entry}
17860 Add @var{entry} to the index of functions. @xref{Index Entries, ,
17861 Defining the Entries of an Index}.@refill
17864 Environment to define floating material. Pair with @code{@@end float}.
17868 @itemx @@flushright
17869 Do not fill text; left (right) justify every line while leaving the
17870 right (left) end ragged. Leave font as is. Pair with @code{@@end
17871 flushleft} (@code{@@end flushright}). @code{@@flushright} analogous.
17872 @xref{flushleft & flushright, , @code{@@flushleft} and
17873 @code{@@flushright}}.
17875 @item @@footnote@{@var{text-of-footnote}@}
17876 Enter a footnote. Footnote text is printed at the bottom of the page
17877 by @TeX{}; Info may format in either `End' node or `Separate' node style.
17880 @item @@footnotestyle @var{style}
17881 Specify an Info file's footnote style, either @samp{end} for the end
17882 node style or @samp{separate} for the separate node style.
17886 Begin a kind of example. Like @code{@@display}, but do not indent.
17887 Pair with @code{@@end format}. @xref{example,, @code{@@example}}.
17889 @item @@ftable @var{formatting-command}
17890 Begin a two-column table, using @code{@@item} for each entry.
17891 Automatically enter each of the items in the first column into the
17892 index of functions. Pair with @code{@@end ftable}. The same as
17893 @code{@@table}, except for indexing. @xref{ftable vtable, ,
17894 @code{@@ftable} and @code{@@vtable}}.@refill
17897 Generate a greater-than-or-equal sign, `@geq{}'. @xref{geq leq}.
17900 Disallow page breaks within following text. Pair with @code{@@end
17901 group}. Ignored in Info. @xref{group, , @code{@@group}}.
17903 @item @@H@{@var{c}@}
17904 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
17906 @item @@heading @var{title}
17907 Print an unnumbered section-like heading, but omit from the table of
17908 contents. In Info, the title is underlined with equal signs.
17909 @xref{unnumberedsec appendixsec heading, , Section Commands}.
17911 @item @@headings @var{on-off-single-double}
17912 Turn page headings on or off, and/or specify single-sided or double-sided
17913 page headings for printing. @xref{headings on off, , The
17914 @code{@@headings} Command}.
17917 Begin a heading row in a multitable. @xref{Multitable Rows}.
17920 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
17921 Formatter Commands}.
17923 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
17924 Explicitly define hyphenation points. @xref{- and hyphenation,,
17925 @code{@@-} and @code{@@hyphenation}}.
17927 @item @@i@{@var{text}@}
17928 Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}.
17930 @item @@ifclear @var{txivar}
17931 If the Texinfo variable @var{txivar} is not set, format the following
17932 text. Pair with @code{@@end ifclear}. @xref{set clear value, ,
17933 @code{@@set} @code{@@clear} @code{@@value}}.
17938 Begin text that will appear only in the given output format.
17939 @code{@@ifinfo} output appears in both Info and (for historical
17940 compatibility) plain text output. Pair with @code{@@end ifdocbook}
17941 resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
17942 @xref{Conditionals}.
17944 @item @@ifnotdocbook
17946 @itemx @@ifnotplaintext
17949 Begin text to be ignored in one output format but not the others.
17950 @code{@@ifnothtml} text is omitted from HTML output, etc. Pair with
17951 the corresponding @code{@@end ifnot@var{format}}.
17952 @xref{Conditionals}.
17955 Begin text to appear in output other than Info and (for historical
17956 compatibility) plain text. Pair with @code{@@end ifnotinfo}.
17957 @xref{Conditionals}.
17959 @item @@ifplaintext
17960 Begin text that will appear only in the plain text output.
17961 Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
17963 @item @@ifset @var{txivar}
17964 If the Texinfo variable @var{txivar} is set, format the following
17965 text. Pair with @code{@@end ifset}. @xref{set clear value, ,
17966 @code{@@set} @code{@@clear} @code{@@value}}.
17969 Begin text to appear only in the @TeX{} output. Pair with @code{@@end
17970 iftex}. @xref{Conditionals, , Conditionally Visible Text}.@refill
17973 Begin text that will appear only in the XML output. Pair with
17974 @code{@@end ifxml}. @xref{Conditionals}.
17977 Begin text that will not appear in any output. Pair with @code{@@end
17978 ignore}. @xref{Comments, , Comments and Ignored Text}.
17980 @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
17981 Include graphics image in external @var{filename} scaled to the given
17982 @var{width} and/or @var{height}, using @var{alt} text and looking for
17983 @samp{@var{filename}.@var{ext}} in HTML. @xref{Images}.
17985 @item @@include @var{filename}
17986 Read the contents of Texinfo source file @var{filename}. @xref{Include Files}.
17988 @item @@indicateurl@{@var{indicateurl}@}
17989 Indicate text that is a uniform resource locator for the World Wide
17990 Web. @xref{indicateurl, , @code{@@indicateurl}}.
17992 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
17993 Make a cross reference to an Info file for which there is no printed
17994 manual. @xref{inforef, , Cross references using
17995 @code{@@inforef}}.@refill
17997 @item \input @var{macro-definitions-file}
17998 Use the specified macro definitions file. This command is used only
17999 in the first line of a Texinfo file to cause @TeX{} to make use of the
18000 @file{texinfo} macro definitions file. The backslash in @code{\input}
18001 is used instead of an @code{@@} because @TeX{} does not
18002 recognize @code{@@} until after it has read the definitions file.
18003 @xref{Texinfo File Header}.
18006 Indicate the beginning of a marked paragraph for @code{@@itemize} and
18007 @code{@@enumerate}; indicate the beginning of the text of a first column
18008 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
18009 @xref{Lists and Tables}.
18011 @item @@itemize @var{mark-generating-character-or-command}
18012 Begin an unordered list: indented paragraphs with a mark, such as
18013 @code{@@bullet}, inside the left margin at the beginning of each
18014 item. Pair with @code{@@end itemize}. @xref{itemize, ,
18018 Like @code{@@item} but do not generate extra vertical space above the
18019 item text. Thus, when several items have the same description, use
18020 @code{@@item} for the first and @code{@@itemx} for the others.
18021 @xref{itemx, , @code{@@itemx}}.
18023 @item @@kbd@{@var{keyboard-characters}@}
18024 Indicate characters of input to be typed by users. @xref{kbd, ,
18027 @item @@kbdinputstyle @var{style}
18028 Specify when @code{@@kbd} should use a font distinct from
18029 @code{@@code}. @xref{kbd, , @code{@@kbd}}.
18031 @item @@key@{@var{key-name}@}
18032 Indicate the name of a key on a keyboard. @xref{key, , @code{@@key}}.
18034 @item @@kindex @var{entry}
18035 Add @var{entry} to the index of keys.
18036 @xref{Index Entries, , Defining the Entries of an Index}.@refill
18040 Generate the uppercase and lowercase Polish suppressed-L letters,
18041 respectively: @L{}, @l{}.
18044 Generate the @LaTeX{} logo. @xref{tex, , @TeX{} and @LaTeX{}}.
18047 Generate a less-than-or-equal sign, `@leq{}'. @xref{geq leq}.
18050 Begin an example of Lisp code. Indent text, do not fill, and select
18051 fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
18053 @item @@listoffloats
18054 Produce a table-of-contents-like listing of @code{@@float}s.
18055 @xref{listoffloats}.
18057 @item @@lowersections
18058 Change subsequent chapters to sections, sections to subsections, and so
18059 on. @xref{Raise/lower sections, , @code{@@raisesections} and
18060 @code{@@lowersections}}.@refill
18062 @item @@macro @var{macroname} @{@var{params}@}
18063 Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
18064 Pair with @code{@@end macro}. @xref{Defining Macros}.
18066 @item @@majorheading @var{title}
18067 Print an unnumbered chapter-like heading, but omit from
18068 the table of contents. This generates more vertical whitespace before
18069 the heading than the @code{@@chapheading} command. @xref{majorheading
18070 & chapheading, , @code{@@majorheading} and @code{@@chapheading}}.
18072 @item @@math@{@var{mathematical-expression}@}
18073 Format a mathematical expression.
18074 @xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
18077 Mark the beginning of a menu of nodes. No effect in a printed manual.
18078 Pair with @code{@@end menu}. @xref{Menus}.
18081 Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.
18083 @item @@multitable @var{column-width-spec}
18084 Begin a multi-column table. Begin each row with @code{@@item} or
18085 @code{@@headitem}, and separate columns with @code{@@tab}. Pair with
18086 @code{@@end multitable}. @xref{Multitable Column Widths}.
18088 @item @@need @var{n}
18089 Start a new page in a printed manual if fewer than @var{n} mils
18090 (thousandths of an inch) remain on the current page. @xref{need, ,
18093 @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
18094 Begin a new node. @xref{node, , @code{@@node}}.
18097 Prevent text from being indented as if it were a new paragraph.
18098 @xref{noindent, , @code{@@noindent}}.
18101 Suppress validation of node references and omit creation of auxiliary
18102 files with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer
18107 Generate the uppercase and lowercase O-with-slash letters, respectively:
18110 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
18111 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
18112 Specify page footings resp.@: headings for odd-numbered (right-hand)
18113 pages. @xref{Custom Headings, ,
18114 How to Make Your Own Headings}.@refill
18118 Generate the uppercase and lowercase OE ligatures, respectively:
18119 @OE{}, @oe{}. @xref{Inserting Accents}.
18121 @item @@option@{@var{option-name}@}
18122 Indicate a command-line option, such as @option{-l} or @option{--help}.
18123 @xref{option,, @code{@@option}}.
18126 Start a new page in a printed manual. No effect in Info.
18127 @xref{page, , @code{@@page}}.@refill
18129 @item @@pagesizes [@var{width}][, @var{height}]
18130 Change page dimensions. @xref{pagesizes}.
18132 @item @@paragraphindent @var{indent}
18133 Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
18134 source file indentation if @var{indent} is @code{asis}.
18135 @xref{paragraphindent,, Paragraph Indenting}.
18137 @item @@pindex @var{entry}
18138 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
18139 the Entries of an Index}.@refill
18142 Indicate the position of point in a buffer to the reader with a
18143 glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
18144 Point in a Buffer}.@refill
18147 Generate the pounds sterling currency sign.
18148 @xref{pounds,,@code{@@pounds@{@}}}.
18151 Indicate printed output to the reader with a glyph:
18152 @samp{@print{}}. @xref{Print Glyph}.@refill
18154 @item @@printindex @var{index-name}
18155 Generate the alphabetized index for @var{index-name} (using two columns in a printed
18156 manual). @xref{Printing Indices & Menus}.
18158 @item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
18159 Make a reference that starts with a lower case `see' in a printed
18160 manual. Use within parentheses only. Only the first argument is
18161 mandatory. @xref{pxref, , @code{@@pxref}}.
18163 @item @@questiondown@{@}
18164 Generate an upside-down question mark. @xref{Inserting Accents}.
18167 Narrow the margins to indicate text that is quoted from another work.
18168 Takes optional argument of prefix text. Pair with @code{@@end
18169 quotation}. @xref{quotation, , @code{@@quotation}}.
18171 @item @@r@{@var{text}@}
18172 Set @var{text} in the regular @r{roman} font. No effect in Info.
18175 @item @@raisesections
18176 Change subsequent sections to chapters, subsections to sections, and so
18177 on. @xref{Raise/lower sections, , @code{@@raisesections} and
18178 @code{@@lowersections}}.@refill
18180 @item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
18181 Make a plain reference that does not start with any special text.
18182 Follow command with a punctuation mark. Only the first argument is
18183 mandatory. @xref{ref, , @code{@@ref}}.
18186 This command used to refill and indent the paragraph after all the
18187 other processing has been done. It is no longer needed, since all
18188 formatters now automatically refill as needed, but you may still see
18189 it in the source to some manuals, as it does no harm.
18191 @item @@registeredsymbol@{@}
18192 Generate the legal symbol @registeredsymbol{}. @xref{registered
18193 symbol,, @code{@@registeredsymbol@{@}}}.
18196 Indicate the result of an expression to the reader with a special
18197 glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
18199 @item @@ringaccent@{@var{c}@}
18200 Generate a ring accent over the next character, as in @ringaccent{o}.
18201 @xref{Inserting Accents}.
18203 @item @@samp@{@var{text}@}
18204 Indicate a literal example of a sequence of characters, in general.
18205 Quoted in Info output. @xref{samp, , @code{@@samp}}.
18207 @item @@sansserif@{@var{text}@}
18208 Set @var{text} in a @sansserif{sans serif} font if possible. No
18209 effect in Info. @xref{Fonts}.
18211 @item @@sc@{@var{text}@}
18212 Set @var{text} in a small caps font in printed output, and uppercase
18213 in Info. @xref{Smallcaps}.
18215 @item @@section @var{title}
18216 Begin a section within a chapter. The section title appears in the
18217 table of contents. In Info, the title is underlined with equal signs.
18218 Within @code{@@chapter} and @code{@@appendix}, the section title is
18219 numbered; within @code{@@unnumbered}, the section is unnumbered.
18220 @xref{section, , @code{@@section}}.
18222 @item @@set @var{txivar} [@var{string}]
18223 Define the Texinfo variable @var{txivar}, optionally to the value
18224 @var{string}. @xref{set clear value, , @code{@@set} @code{@@clear}
18227 @item @@setchapternewpage @var{on-off-odd}
18228 Specify whether chapters start on new pages, and if so, whether on
18229 odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
18230 @code{@@setchapternewpage}}.
18232 @item @@setcontentsaftertitlepage
18233 Put the table of contents after the @samp{@@end titlepage} even if the
18234 @code{@@contents} command is at the end. @xref{Contents}.
18236 @item @@setfilename @var{info-file-name}
18237 Provide a name to be used for the output files. This command is essential
18238 for @TeX{} formatting as well, even though it produces no output of
18239 its own. @xref{setfilename, , @code{@@setfilename}}.
18241 @item @@setshortcontentsaftertitlepage
18242 Place the short table of contents after the @samp{@@end titlepage}
18243 command even if the @code{@@shortcontents} command is at the end.
18246 @item @@settitle @var{title}
18247 Specify the title for page headers in a printed manual, and the
18248 default document description for HTML @samp{<head>}. @xref{settitle,,
18249 @code{@@settitle}}.
18251 @item @@shortcaption
18252 Define the short caption for a @code{@@float}. @xref{caption shortcaption}.
18254 @item @@shortcontents
18255 Print a short table of contents, with chapter-level entries only. Not
18256 relevant to Info, which uses menus rather than tables of contents.
18257 @xref{Contents, , Generating a Table of Contents}.
18259 @item @@shorttitlepage @var{title}
18260 Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
18262 @item @@slanted@{@var{text}@}
18263 Set @var{text} in a @slanted{slanted} font if possible. No effect
18264 in Info. @xref{Fonts}.
18267 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
18268 rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
18269 Printing Small Books}. Also, see @ref{small}.
18271 @item @@smalldisplay
18272 Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
18273 filling), but do not select the fixed-width font. Pair with @code{@@end
18274 smalldisplay}. @xref{small}.
18276 @item @@smallexample
18277 Begin an example. Do not fill, select fixed-width font, narrow the
18278 margins. Where possible, print text in a smaller font than with
18279 @code{@@example}. Pair with @code{@@end smallexample}. @xref{small}.
18281 @item @@smallformat
18282 Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
18283 the margins. Pair with @code{@@end smallformat}. @xref{small}.
18286 Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
18287 with @code{@@end smalllisp}. @xref{small}.
18290 Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
18293 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
18295 @item @@strong @{@var{text}@}
18296 Emphasize @var{text} more strongly than @code{@@emph}, by using
18297 @strong{boldface} where possible; enclosed in asterisks in Info.
18298 @xref{emph & strong, , Emphasizing Text}.
18300 @item @@subheading @var{title}
18301 Print an unnumbered subsection-like heading, but omit from the table
18302 of contents of a printed manual. In Info, the title is underlined
18303 with hyphens. @xref{unnumberedsubsec appendixsubsec subheading, ,
18304 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
18305 @code{@@subheading}}.
18307 @item @@subsection @var{title}
18308 Begin a subsection within a section. The subsection title appears in
18309 the table of contents. In Info, the title is underlined with hyphens.
18310 Same context-dependent numbering as @code{@@section}. @xref{subsection, ,
18311 @code{@@subsection}}.
18313 @item @@subsubheading @var{title}
18314 Print an unnumbered subsubsection-like heading, but omit from the
18315 table of contents of a printed manual. In Info, the title is
18316 underlined with periods. @xref{subsubsection, , The `subsub'
18319 @item @@subsubsection @var{title}
18320 Begin a subsubsection within a subsection. The subsubsection title
18321 appears in the table of contents. In Info, the title is underlined
18322 with periods. Same context-dependent numbering as @code{@@section}.
18323 @xref{subsubsection, , The `subsub' Commands}.
18325 @item @@subtitle @var{title}
18326 In a printed manual, set a subtitle in a normal sized font flush to
18327 the right-hand side of the page. Not relevant to Info, which does not
18328 have title pages. @xref{title subtitle author, , @code{@@title}
18329 @code{@@subtitle} and @code{@@author} Commands}.
18331 @item @@summarycontents
18332 Print a short table of contents. Synonym for @code{@@shortcontents}.
18333 @xref{Contents, , Generating a Table of Contents}.
18335 @item @@syncodeindex @var{from-index} @var{to-index}
18336 Merge the index named in the first argument into the index named in
18337 the second argument, formatting the entries from the first index with
18338 @code{@@code} . @xref{Combining Indices}.@refill
18340 @item @@synindex @var{from-index} @var{to-index}
18341 Merge the index named in the first argument into the index named in
18342 the second argument. Do not change the font of @var{from-index}
18343 entries. @xref{Combining Indices}.
18345 @item @@t@{@var{text}@}
18346 Set @var{text} in a @t{fixed-width}, typewriter-like font. No effect
18347 in Info. @xref{Fonts}.
18350 Separate columns in a row of a multitable. @xref{Multitable Rows}.
18352 @item @@table @var{formatting-command}
18353 Begin a two-column table (description list), using @code{@@item} for
18354 each entry. Write each first column entry on the same line as
18355 @code{@@item}. First column entries are printed in the font resulting
18356 from @var{formatting-command}. Pair with @code{@@end table}.
18357 @xref{Two-column Tables, , Making a Two-column Table}. Also see
18358 @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, and
18359 @ref{itemx, , @code{@@itemx}}.
18362 Generate the @TeX{} logo. @xref{tex, , @TeX{} and @LaTeX{}}.
18365 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
18366 Formatter Commands}.
18368 @item @@thischapter
18369 @itemx @@thischaptername
18370 @itemx @@thischapternum
18374 Only allowed in a heading or footing. Stands for, respectively, the
18375 number and name of the current chapter (in the format `Chapter 1:
18376 Title'), the current chapter name only, the current chapter number
18377 only, the filename, the current page number, and the title of the
18378 document, respectively. @xref{Custom Headings, , How to Make Your Own
18382 Generate a normal interword space at which a line break is not allowed.
18383 @xref{tie,, @code{@@tie@{@}}}.
18385 @item @@tieaccent@{@var{cc}@}
18386 Generate a tie-after accent over the next two characters @var{cc}, as in
18387 `@tieaccent{oo}'. @xref{Inserting Accents}.
18389 @item @@tindex @var{entry}
18390 Add @var{entry} to the index of data types. @xref{Index Entries, ,
18391 Defining the Entries of an Index}.@refill
18393 @item @@title @var{title}
18394 In a printed manual, set a title flush to the left-hand side of the
18395 page in a larger than normal font and underline it with a black rule.
18396 Not relevant to Info, which does not have title pages. @xref{title
18397 subtitle author, , The @code{@@title} @code{@@subtitle} and
18398 @code{@@author} Commands}.@refill
18400 @item @@titlefont@{@var{text}@}
18401 In a printed manual, print @var{text} in a larger than normal font.
18402 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
18403 and @code{@@sp} Commands}.
18406 Begin the title page. Write the command on a line of its own, paired
18407 with @code{@@end titlepage}. Nothing between @code{@@titlepage} and
18408 @code{@@end titlepage} appears in Info. @xref{titlepage, ,
18409 @code{@@titlepage}}.@refill
18412 Insert the current date, in `1 Jan 1900' style. @xref{Custom
18413 Headings, , How to Make Your Own Headings}.@refill
18415 @item @@top @var{title}
18416 Mark the topmost @code{@@node} in the file, which must be defined on
18417 the line immediately preceding the @code{@@top} command. The title is
18418 formatted as a chapter-level heading. The entire top node, including
18419 the @code{@@node} and @code{@@top} lines, are normally enclosed with
18420 @code{@@ifnottex ... @@end ifnottex}. In @TeX{} and
18421 @code{texinfo-format-buffer}, the @code{@@top} command is merely a
18422 synonym for @code{@@unnumbered}. @xref{makeinfo Pointer Creation, ,
18423 Creating Pointers with @code{makeinfo}}.
18425 @item @@u@{@var{c}@}
18426 @itemx @@ubaraccent@{@var{c}@}
18427 @itemx @@udotaccent@{@var{c}@}
18428 Generate a breve, underbar, or underdot accent, respectively, over or
18429 under the character @var{c}, as in @u{o}, @ubaraccent{o},
18430 @udotaccent{o}. @xref{Inserting Accents}.
18432 @item @@unnumbered @var{title}
18433 Begin a chapter that appears without chapter numbers of any kind. The
18434 title appears in the table of contents. In Info, the title is
18435 underlined with asterisks. @xref{unnumbered & appendix, ,
18436 @code{@@unnumbered} and @code{@@appendix}}.
18438 @item @@unnumberedsec @var{title}
18439 Begin a section that appears without section numbers of any kind. The
18440 title appears in the table of contents of a printed manual. In Info,
18441 the title is underlined with equal signs. @xref{unnumberedsec
18442 appendixsec heading, , Section Commands}.
18444 @item @@unnumberedsubsec @var{title}
18445 Begin an unnumbered subsection. The title appears in the table of
18446 contents. In Info, the title is underlined with hyphens.
18447 @xref{unnumberedsubsec appendixsubsec subheading, ,
18448 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
18449 @code{@@subheading}}.
18451 @item @@unnumberedsubsubsec @var{title}
18452 Begin an unnumbered subsubsection. The title appears in the table of
18453 contents. In Info, the title is underlined with periods.
18454 @xref{subsubsection, , The `subsub' Commands}.
18456 @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
18457 @itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
18458 Define a cross reference to an external uniform resource locator,
18459 e.g., for the World Wide Web. @xref{uref, , @code{@@uref}}.
18461 @item @@v@{@var{c}@}
18462 Generate check accent over the character @var{c}, as in @v{o}.
18463 @xref{Inserting Accents}.
18465 @item @@value@{@var{txivar}@}
18466 Insert the value, if any, of the Texinfo variable @var{txivar},
18467 previously defined by @code{@@set}. @xref{set clear value, ,
18468 @code{@@set} @code{@@clear} @code{@@value}}.
18470 @item @@var@{@var{metasyntactic-variable}@}
18471 Highlight a metasyntactic variable, which is something that stands for
18472 another piece of text. @xref{var, , Indicating Metasyntactic
18475 @item @@verb@{@var{delim} @var{literal} @var{delim}@}
18476 Output @var{literal}, delimited by the single character @var{delim},
18477 exactly as is (in the fixed-width font), including any whitespace or
18478 Texinfo special characters. @xref{verb,,@code{verb}}.
18481 Output the text of the environment exactly as is (in the fixed-width
18482 font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
18484 @item @@verbatiminclude @var{filename}
18485 Output the contents of @var{filename} exactly as is (in the fixed-width font).
18486 @xref{verbatiminclude,,@code{verbatiminclude}}.
18488 @item @@vindex @var{entry}
18489 Add @var{entry} to the index of variables. @xref{Index Entries, ,
18490 Defining the Entries of an Index}.@refill
18492 @item @@vskip @var{amount}
18493 In a printed manual, insert whitespace so as to push text on the
18494 remainder of the page towards the bottom of the page. Used in
18495 formatting the copyright page with the argument @samp{0pt plus
18496 1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
18497 only in contexts ignored for Info. @xref{Copyright}.
18499 @item @@vtable @var{formatting-command}
18500 Begin a two-column table, using @code{@@item} for each entry.
18501 Automatically enter each of the items in the first column into the
18502 index of variables. Pair with @code{@@end vtable}. The same as
18503 @code{@@table}, except for indexing. @xref{ftable vtable, ,
18504 @code{@@ftable} and @code{@@vtable}}.@refill
18506 @item @@w@{@var{text}@}
18507 Disallow line breaks within @var{text}. @xref{w, , @code{@@w}}.
18510 Enter XML completely. Pair with @code{@@end xml}. @xref{Raw
18511 Formatter Commands}.
18513 @item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
18514 Make a reference that starts with `See' in a printed manual. Follow
18515 command with a punctuation mark. Only the first argument is
18516 mandatory. @xref{xref, , @code{@@xref}}.
18521 @node Command Syntax
18522 @section @@-Command Syntax
18523 @cindex @@-command syntax
18524 @cindex Syntax, of @@-commands
18525 @cindex Command syntax
18527 The character @samp{@@} is used to start special Texinfo commands.
18528 (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
18529 has four types of @@-command:@refill
18532 @item 1. Non-alphabetic commands.
18533 These commands consist of an @@ followed by a punctuation mark or
18534 other character that is not part of the alphabet. Non-alphabetic
18535 commands are almost always part of the text within a paragraph. The
18536 non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}},
18537 @code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and
18540 @item 2. Alphabetic commands that do not require arguments.
18541 These commands start with @@ followed by a word followed by left- and
18542 right-hand braces. These commands insert special symbols in the
18543 document; they do not require arguments. For example,
18544 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
18545 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
18546 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
18548 @item 3. Alphabetic commands that require arguments within braces.
18549 These commands start with @@ followed by a letter or a word, followed by an
18550 argument within braces. For example, the command @code{@@dfn} indicates
18551 the introductory or defining use of a term; it is used as follows: @samp{In
18552 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
18554 @item 4. Alphabetic commands that occupy an entire line.
18555 These commands occupy an entire line. The line starts with @@,
18556 followed by the name of the command (a word); for example, @code{@@center}
18557 or @code{@@cindex}. If no argument is needed, the word is followed by
18558 the end of the line. If there is an argument, it is separated from
18559 the command name by a space. Braces are not used.@refill
18562 @cindex Braces and argument syntax
18563 Thus, the alphabetic commands fall into classes that have
18564 different argument syntaxes. You cannot tell to which class a command
18565 belongs by the appearance of its name, but you can tell by the
18566 command's meaning: if the command stands for a glyph, it is in
18567 class 2 and does not require an argument; if it makes sense to use the
18568 command together with other text as part of a paragraph, the command
18569 is in class 3 and must be followed by an argument in braces;
18570 otherwise, it is in class 4 and uses the rest of the line as its
18573 The purpose of having a different syntax for commands of classes 3 and
18574 4 is to make Texinfo files easier to read, and also to help the GNU
18575 Emacs paragraph and filling commands work properly. There is only one
18576 exception to this rule: the command @code{@@refill}, which is always
18577 used at the end of a paragraph immediately following the final period
18578 or other punctuation character. @code{@@refill} takes no argument and
18579 does @emph{not} require braces. @code{@@refill} never confuses the
18580 Emacs paragraph commands because it cannot appear at the beginning of
18581 a line. It is also no longer needed, since all formatters now refill
18582 paragraphs automatically.
18586 @appendix Tips and Hints
18588 Here are some tips for writing Texinfo documentation:@refill
18595 Write in the present tense, not in the past or the future.
18598 Write actively! For example, write ``We recommend that @dots{}'' rather
18599 than ``It is recommended that @dots{}''.
18602 Use 70 or 72 as your fill column. Longer lines are hard to read.
18605 Include a copyright notice and copying permissions.
18608 @subsubheading Index, Index, Index!
18610 Write many index entries, in different ways.
18611 Readers like indices; they are helpful and convenient.
18613 Although it is easiest to write index entries as you write the body of
18614 the text, some people prefer to write entries afterwards. In either
18615 case, write an entry before the paragraph to which it applies. This
18616 way, an index entry points to the first page of a paragraph that is
18617 split across pages.
18619 Here are more hints we have found valuable:
18623 Write each index entry differently, so each entry refers to a different
18624 place in the document.
18627 Write index entries only where a topic is discussed significantly. For
18628 example, it is not useful to index ``debugging information'' in a
18629 chapter on reporting bugs. Someone who wants to know about debugging
18630 information will certainly not find it in that chapter.
18633 Consistently capitalize the first word of every concept index entry,
18634 or else consistently use lower case. Terse entries often call for
18635 lower case; longer entries for capitalization. Whichever case
18636 convention you use, please use one or the other consistently! Mixing
18637 the two styles looks bad.
18640 Always capitalize or use upper case for those words in an index for
18641 which this is proper, such as names of countries or acronyms. Always
18642 use the appropriate case for case-sensitive names, such as those in C or
18646 Write the indexing commands that refer to a whole section immediately
18647 after the section command, and write the indexing commands that refer to
18648 a paragraph before that paragraph.
18650 In the example that follows, a blank line comes after the index
18651 entry for ``Leaping'':
18655 @@section The Dog and the Fox
18656 @@cindex Jumping, in general
18659 @@cindex Dog, lazy, jumped over
18660 @@cindex Lazy dog jumped over
18661 @@cindex Fox, jumps over dog
18662 @@cindex Quick fox jumps over dog
18663 The quick brown fox jumps over the lazy dog.
18668 (Note that the example shows entries for the same concept that are
18669 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
18670 readers can look up the concept in different ways.)
18673 @subsubheading Blank Lines
18677 Insert a blank line between a sectioning command and the first following
18678 sentence or paragraph, or between the indexing commands associated with
18679 the sectioning command and the first following sentence or paragraph, as
18680 shown in the tip on indexing. Otherwise, a formatter may fold title and
18681 paragraph together.
18684 Always insert a blank line before an @code{@@table} command and after an
18685 @code{@@end table} command; but never insert a blank line after an
18686 @code{@@table} command or before an @code{@@end table} command.
18697 Jump over lazy dogs.
18702 Also jump over lazy dogs.
18708 On the other hand, @dots{}
18712 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
18713 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
18717 @subsubheading Complete Phrases
18719 Complete phrases are easier to read than @dots{}
18723 Write entries in an itemized list as complete sentences; or at least, as
18724 complete phrases. Incomplete expressions @dots{} awkward @dots{} like
18728 Write the prefatory sentence or phrase for a multi-item list or table as
18729 a complete expression. Do not write ``You can set:''; instead, write
18730 ``You can set these variables:''. The former expression sounds cut off.
18733 @subsubheading Editions, Dates and Versions
18735 Include edition numbers, version numbers, and dates in the
18736 @code{@@copying} text (for people reading the Texinfo file, and for the
18737 legal copyright in the output files). Then use @code{@@insertcopying}
18738 in the @code{@@titlepage} section (for people reading the printed
18739 output) and the Top node (for people reading the online output).
18741 It is easiest to do this using @code{@@set} and @code{@@value}.
18742 @xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
18745 @subsubheading Definition Commands
18747 Definition commands are @code{@@deffn}, @code{@@defun},
18748 @code{@@defmac}, and the like, and enable you to write descriptions in
18749 a uniform format.@refill
18753 Write just one definition command for each entity you define with a
18754 definition command. The automatic indexing feature creates an index
18755 entry that leads the reader to the definition.
18758 Use @code{@@table} @dots{} @code{@@end table} in an appendix that
18759 contains a summary of functions, not @code{@@deffn} or other definition
18763 @subsubheading Capitalization
18767 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
18768 @samp{i} in upper case.
18771 Capitalize ``Info''; it is a name.
18774 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
18775 @samp{T} and @samp{X}. This command causes the formatters to
18776 typeset the name according to the wishes of Donald Knuth, who wrote
18780 @subsubheading Spaces
18782 Do not use spaces to format a Texinfo file, except inside of
18783 @code{@@example} @dots{} @code{@@end example} and other literal
18784 environments and commands.
18787 For example, @TeX{} fills the following:
18792 @@kbd@{M-x vc-next-action@}
18793 Perform the next logical operation
18794 on the version-controlled file
18795 corresponding to the current buffer.
18801 so it looks like this:
18806 @kbd{M-x vc-next-action}
18807 Perform the next logical operation on the version-controlled file
18808 corresponding to the current buffer.
18813 `C-x v' `M-x vc-next-action' Perform the next logical operation on the
18814 version-controlled file corresponding to the current buffer.
18819 In this case, the text should be formatted with
18820 @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
18823 @subsubheading @@code, @@samp, @@var, and @samp{---}
18827 Use @code{@@code} around Lisp symbols, including command names.
18831 The main function is @@code@{vc-next-action@}, @dots{}
18835 Avoid putting letters such as @samp{s} immediately after an
18836 @samp{@@code}. Such letters look bad.
18839 Use @code{@@var} around meta-variables. Do not write angle brackets
18843 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
18844 typesets these as a long dash and the Info formatters reduce three
18848 @subsubheading Periods Outside of Quotes
18850 Place periods and other punctuation marks @emph{outside} of quotations,
18851 unless the punctuation is part of the quotation. This practice goes
18852 against publishing conventions in the United States, but enables the
18853 reader to distinguish between the contents of the quotation and the
18856 For example, you should write the following sentence with the period
18857 outside the end quotation marks:
18860 Evidently, @samp{au} is an abbreviation for ``author''.
18864 since @samp{au} does @emph{not} serve as an abbreviation for
18865 @samp{author.} (with a period following the word).
18867 @subsubheading Introducing New Terms
18871 Introduce new terms so that a reader who does not know them can
18872 understand them from context; or write a definition for the term.
18874 For example, in the following, the terms ``check in'', ``register'' and
18875 ``delta'' are all appearing for the first time; the example sentence should be
18876 rewritten so they are understandable.
18879 The major function assists you in checking in a file to your
18880 version control system and registering successive sets of changes to
18885 Use the @code{@@dfn} command around a word being introduced, to indicate
18886 that the reader should not expect to know the meaning already, and
18887 should expect to learn the meaning from this passage.
18890 @subsubheading @@pxref
18892 @c !!! maybe include this in the tips on pxref
18894 By the way, it is okay to use pxref with something else in front of
18895 it within the parens, as long as the pxref is followed by the close
18896 paren, and the material inside the parens is not part of a larger
18897 sentence. Also, you can use xref inside parens as part of a complete
18898 sentence so long as you terminate the cross reference with punctuation.
18900 Absolutely never use @code{@@pxref} except in the special context for
18901 which it is designed: inside parentheses, with the closing parenthesis
18902 following immediately after the closing brace. One formatter
18903 automatically inserts closing punctuation and the other does not. This
18904 means that the output looks right both in printed output and in an Info
18905 file, but only when the command is used inside parentheses.
18907 @subsubheading Invoking from a Shell
18909 You can invoke programs such as Emacs, GCC, and @code{gawk} from a
18910 shell. The documentation for each program should contain a section that
18911 describes this. Unfortunately, if the node names and titles for these
18912 sections are all different, they are difficult for users to find.
18914 So, there is a convention to name such sections with a phrase beginning
18915 with the word `Invoking', as in `Invoking Emacs'; this way, users can
18916 find the section easily.
18919 @subsubheading ANSI C Syntax
18921 When you use @code{@@example} to describe a C function's calling
18922 conventions, use the ANSI C syntax, like this:@refill
18925 void dld_init (char *@@var@{path@});
18929 And in the subsequent discussion, refer to the argument values by
18930 writing the same argument names, again highlighted with
18931 @code{@@var}.@refill
18934 Avoid the obsolete style that looks like this:@refill
18943 Also, it is best to avoid writing @code{#include} above the
18944 declaration just to indicate that the function is declared in a
18945 header file. The practice may give the misimpression that the
18946 @code{#include} belongs near the declaration of the function. Either
18947 state explicitly which header file holds the declaration or, better
18948 yet, name the header file used for a group of functions at the
18949 beginning of the section that describes the functions.@refill
18951 @subsubheading Bad Examples
18953 Here are several examples of bad writing to avoid:
18955 In this example, say, `` @dots{} you must @code{@@dfn}@{check
18956 in@} the new version.'' That flows better.
18959 When you are done editing the file, you must perform a
18960 @code{@@dfn}@{check in@}.
18963 In the following example, say, ``@dots{} makes a unified interface such as VC
18967 SCCS, RCS and other version-control systems all perform similar
18968 functions in broadly similar ways (it is this resemblance which makes
18969 a unified control mode like this possible).
18972 And in this example, you should specify what `it' refers to:
18975 If you are working with other people, it assists in coordinating
18976 everyone's changes so they do not step on each other.
18979 @subsubheading And Finally @dots{}
18983 Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
18984 sound in the name `Bach'. But pronounce Texinfo as in `speck':
18988 Write notes for yourself at the very end of a Texinfo file after the
18989 @code{@@bye}. None of the formatters process text after the
18990 @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
18991 @code{@@end ignore}.
18995 @node Sample Texinfo Files
18996 @appendix Sample Texinfo Files
18997 @cindex Sample Texinfo files
18999 The first example is from the first chapter (@pxref{Short Sample}),
19000 given here in its entirety, without commentary. The second
19001 includes the full texts to be used in GNU manuals.
19004 * Short Sample Texinfo File::
19005 * GNU Sample Texts::
19006 * Verbatim Copying License::
19007 * All-permissive Copying License::
19011 @node Short Sample Texinfo File
19012 @section Short Sample
19013 @cindex Sample Texinfo file, no comments
19015 Here is a complete, short sample Texinfo file, without any commentary.
19016 You can see this file, with comments, in the first chapter. @xref{Short
19019 In a nutshell: The @command{makeinfo} program transforms a Texinfo
19020 source file such as this into an Info file or HTML; and @TeX{} typesets
19021 it for a printed manual.
19026 \input texinfo @@c -*-texinfo-*-
19027 @@c %**start of header
19028 @@setfilename sample.info
19029 @@settitle Sample Manual 1.0
19030 @@c %**end of header
19033 This is a short example of a complete Texinfo file.
19035 Copyright @copyright{} 2005 Free Software Foundation, Inc.
19039 @@title Sample Title
19041 @@vskip 0pt plus 1filll
19045 @@c Output the table of the contents at the beginning.
19056 * First Chapter:: The first chapter is the
19057 only chapter in this sample.
19058 * Index:: Complete index.
19062 @@node First Chapter
19063 @@chapter First Chapter
19065 @@cindex chapter, first
19067 This is the first chapter.
19068 @@cindex index entry, another
19070 Here is a numbered list.
19074 This is the first item.
19077 This is the second item.
19090 @node GNU Sample Texts
19091 @section GNU Sample Texts
19093 @cindex GNU sample texts
19094 @cindex Sample texts, GNU
19095 @cindex Full texts, GNU
19097 Following is a sample Texinfo document with the full texts that should
19098 be used in GNU manuals.
19100 As well as the legal texts, it also serves as a practical example of how
19101 many elements in a GNU system can affect the manual. If you're not
19102 familiar with all these different elements, don't worry. They're not
19103 required and a perfectly good manual can be written without them.
19104 They're included here nonetheless because many manuals do (or could)
19107 @xref{Short Sample}, for a minimal example of a Texinfo file.
19108 @xref{Beginning a File}, for a full explanation of that minimal
19111 Here are some notes on the example:
19118 @cindex Documentation identification
19119 @cindex Identification of documentation
19120 The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs,
19121 Concurrent Versions System}) or RCS
19122 (@url{http://www.gnu.org/software/rcs}) version control systems, which
19123 expand it into a string such as:
19125 $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
19127 (This is useful in all sources that use version control, not just manuals.)
19128 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
19129 text, if you want a completely unambiguous reference to the
19130 documentation version.
19132 If you want to literally write @t{@w{$}Id$}, use @code{@@w}:
19133 @code{@@w@{$@}Id$}. Unfortunately, this technique does not currently
19134 work in plain text output, since it's not clear what should be done.
19135 We hope to find a solution in a future release.
19138 @pindex automake@r{, and version info}
19139 @vindex UPDATED @r{Automake variable}
19140 @vindex VERSION @r{Automake variable}
19141 @pindex time-stamp.el
19142 The @file{version.texi} in the @code{@@include} command is maintained
19143 automatically by Automake (@pxref{Top,, Introduction, automake, GNU
19144 Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
19145 elsewhere. If your distribution doesn't use Automake, but you do use
19146 Emacs, you may find the time-stamp.el package helpful (@pxref{Time
19147 Stamps,,,emacs,The GNU Emacs Manual}).
19150 The @code{@@syncodeindex} command reflects the recommendation to use
19151 only one index where possible, to make it easier for readers to look up
19155 The @code{@@dircategory} is for constructing the Info directory.
19156 @xref{Installing Dir Entries}, which includes a variety of recommended
19160 The `Invoking' node is a GNU standard to help users find the basic
19161 information about command-line usage of a given program. @xref{Manual
19162 Structure Details,,,standards, GNU Coding Standards}.
19165 @cindex GNU Free Documentation License, including entire
19166 @cindex Free Documentation License, including entire
19167 It is best to include the entire GNU Free Documentation License in a GNU
19168 manual, unless the manual is only a few pages long. Of course this
19169 sample is even shorter than that, but it includes the FDL anyway in
19170 order to show one conventional way to do so. The @file{fdl.texi} file
19171 is available on the GNU machines and in the Texinfo and other GNU
19172 source distributions.
19174 The FDL provides for omitting itself under certain conditions, but in
19175 that case the sample texts given here have to be modified. @xref{GNU
19176 Free Documentation License}.
19179 If the FSF is not the copyright holder, then use the appropriate name.
19182 If your manual is not published on paper by the FSF, then omit the
19183 last sentence in the Back-Cover Text that talks about copies from GNU
19187 If your manual has Invariant Sections (again, see the license itself
19188 for details), then change the text here accordingly.
19191 For documents that express your personal views, feelings or experiences,
19192 it is more appropriate to use a license permitting only verbatim
19193 copying, rather than the FDL. @xref{Verbatim Copying License}.
19197 Here is the sample document:
19200 \input texinfo @c -*-texinfo-*-
19201 @comment $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
19202 @comment %**start of header
19203 @setfilename sample.info
19204 @include version.texi
19205 @settitle GNU Sample @value{VERSION}
19206 @syncodeindex pg cp
19207 @comment %**end of header
19209 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
19210 which is an example in the Texinfo documentation.
19212 Copyright @copyright{} 2007 Free Software Foundation, Inc.
19215 Permission is granted to copy, distribute and/or modify this document
19216 under the terms of the GNU Free Documentation License, Version 1.2 or
19217 any later version published by the Free Software Foundation; with no
19218 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
19219 and with the Back-Cover Texts as in (a) below. A copy of the
19220 license is included in the section entitled ``GNU Free Documentation
19223 (a) The FSF's Back-Cover Text is: ``You have the freedom to
19224 copy and modify this GNU manual. Buying copies from the FSF
19225 supports it in developing GNU and promoting software freedom.''
19229 @dircategory Texinfo documentation system
19231 * sample: (sample)Invoking sample.
19236 @subtitle for version @value{VERSION}, @value{UPDATED}
19237 @author A.U. Thor (@email{bug-texinfo@@gnu.org})
19239 @vskip 0pt plus 1filll
19249 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
19253 * Invoking sample::
19254 * Copying This Manual::
19259 @node Invoking sample
19260 @chapter Invoking sample
19263 @cindex invoking @command{sample}
19265 This is a sample manual. There is no sample program to
19266 invoke, but if there was, you could see its basic usage
19267 and command line options here.
19270 @node GNU Free Documentation License
19271 @appendix GNU Free Documentation License
19285 @node Verbatim Copying License
19286 @section Verbatim Copying License
19288 @cindex Verbatim copying license
19289 @cindex License for verbatim copying
19291 For software manuals and other documentation, it is important to use a
19292 license permitting free redistribution and updating, so that when a free
19293 program is changed, the documentation can be updated as well.
19295 On the other hand, for documents that express your personal views,
19296 feelings or experiences, it is more appropriate to use a license
19297 permitting only verbatim copying.
19299 Here is sample text for such a license permitting verbatim copying only.
19300 This is just the license text itself. For a complete sample document,
19301 see the previous sections.
19305 This document is a sample for allowing verbatim copying only.
19307 Copyright @copyright{} 2005 Free Software Foundation, Inc.
19310 Permission is granted to make and distribute verbatim copies
19311 of this entire document without royalty provided the
19312 copyright notice and this permission notice are preserved.
19318 @node All-permissive Copying License
19319 @section All-permissive Copying License
19321 @cindex All-permissive copying license
19322 @cindex License for all-permissive copying
19324 For software manuals and other documentation, it is important to use a
19325 license permitting free redistribution and updating, so that when a free
19326 program is changed, the documentation can be updated as well.
19328 On the other hand, for small supporting files, short manuals (under 300
19329 lines long) and rough documentation (README files, INSTALL files, etc.),
19330 the full FDL would be overkill. They can use a simple all-permissive
19333 Here is sample text for such an all-permissive license. This is just
19334 the license text itself. For a complete sample document, see the
19338 Copyright @copyright{} 2005 Free Software Foundation, Inc.
19340 Copying and distribution of this file, with or without modification,
19341 are permitted in any medium without royalty provided the copyright
19342 notice and this notice are preserved.
19346 @node Include Files
19347 @appendix Include Files
19348 @cindex Include files
19350 When @TeX{} or an Info formatting command sees an @code{@@include}
19351 command in a Texinfo file, it processes the contents of the file named
19352 by the command and incorporates them into the DVI or Info file being
19353 created. Index entries from the included file are incorporated into
19354 the indices of the output file.
19356 Include files let you keep a single large document as a collection of
19357 conveniently small parts.
19360 * Using Include Files:: How to use the @code{@@include} command.
19361 * texinfo-multiple-files-update:: How to create and update nodes and
19362 menus when using included files.
19363 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
19364 * Sample Include File:: A sample outer file with included files
19365 within it; and a sample included file.
19366 * Include Files Evolution:: How use of the @code{@@include} command
19367 has changed over time.
19370 @node Using Include Files
19371 @section How to Use Include Files
19374 To include another file within a Texinfo file, write the
19375 @code{@@include} command at the beginning of a line and follow it on
19376 the same line by the name of a file to be included. For example:
19379 @@include buffers.texi
19382 The name of the file is taken literally, with a single exception:
19383 @code{@@value@{@var{var}@}} references are expanded. This makes it
19384 possible to reliably include files in other directories in a
19385 distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for
19388 An included file should simply be a segment of text that you expect to
19389 be included as is into the overall or @dfn{outer} Texinfo file; it
19390 should not contain the standard beginning and end parts of a Texinfo
19391 file. In particular, you should not start an included file with a
19392 line saying @samp{\input texinfo}; if you do, that phrase is inserted
19393 into the output file as is. Likewise, you should not end an included
19394 file with an @code{@@bye} command; nothing after @code{@@bye} is
19397 In the past, you were required to write an @code{@@setfilename} line at the
19398 beginning of an included file, but no longer. Now, it does not matter
19399 whether you write such a line. If an @code{@@setfilename} line exists
19400 in an included file, it is ignored.@refill
19402 Conventionally, an included file begins with an @code{@@node} line that
19403 is followed by an @code{@@chapter} line. Each included file is one
19404 chapter. This makes it easy to use the regular node and menu creating
19405 and updating commands to create the node pointers and menus within the
19406 included file. However, the simple Emacs node and menu creating and
19407 updating commands do not work with multiple Texinfo files. Thus you
19408 cannot use these commands to fill in the `Next', `Previous', and `Up'
19409 pointers of the @code{@@node} line that begins the included file. Also,
19410 you cannot use the regular commands to create a master menu for the
19411 whole file. Either you must insert the menus and the `Next',
19412 `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
19413 Texinfo mode command, @code{texinfo-multiple-files-update}, that is
19414 designed for @code{@@include} files.@refill
19416 When an included file does not have any node lines in it, the
19417 multiple files update command does not try to create a menu entry
19418 for it. Consequently, you can include any file, such as a
19419 version or an update file without node lines, not just files that
19420 are chapters. Small includable files like this are created by
19421 Automake (@pxref{GNU Sample Texts}).
19424 @node texinfo-multiple-files-update
19425 @section @code{texinfo-multiple-files-update}
19426 @findex texinfo-multiple-files-update
19428 GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
19429 command. This command creates or updates `Next', `Previous', and `Up'
19430 pointers of included files as well as those in the outer or overall
19431 Texinfo file, and it creates or updates a main menu in the outer file.
19432 Depending whether you call it with optional arguments, the command
19433 updates only the pointers in the first @code{@@node} line of the
19434 included files or all of them:@refill
19437 @item M-x texinfo-multiple-files-update
19438 Called without any arguments:@refill
19442 Create or update the `Next', `Previous', and `Up' pointers of the
19443 first @code{@@node} line in each file included in an outer or overall
19444 Texinfo file.@refill
19447 Create or update the `Top' level node pointers of the outer or
19448 overall file.@refill
19451 Create or update a main menu in the outer file.@refill
19454 @item C-u M-x texinfo-multiple-files-update
19455 Called with @kbd{C-u} as a prefix argument:
19459 Create or update pointers in the first @code{@@node} line in each
19463 Create or update the `Top' level node pointers of the outer file.
19466 Create and insert a master menu in the outer file. The master menu
19467 is made from all the menus in all the included files.@refill
19470 @item C-u 8 M-x texinfo-multiple-files-update
19471 Called with a numeric prefix argument, such as @kbd{C-u 8}:
19475 Create or update @strong{all} the `Next', `Previous', and `Up' pointers
19476 of all the included files.@refill
19479 Create or update @strong{all} the menus of all the included
19483 Create or update the `Top' level node pointers of the outer or
19484 overall file.@refill
19487 And then create a master menu in the outer file. This is similar to
19488 invoking @code{texinfo-master-menu} with an argument when you are
19489 working with just one file.@refill
19493 Note the use of the prefix argument in interactive use: with a regular
19494 prefix argument, just @w{@kbd{C-u}}, the
19495 @code{texinfo-multiple-files-update} command inserts a master menu;
19496 with a numeric prefix argument, such as @kbd{C-u 8}, the command
19497 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
19498 master menu.@refill
19501 @node Include Files Requirements
19502 @section Include Files Requirements
19503 @cindex Include files requirements
19504 @cindex Requirements for include files
19506 If you plan to use the @code{texinfo-multiple-files-update} command,
19507 the outer Texinfo file that lists included files within it should
19508 contain nothing but the beginning and end parts of a Texinfo file, and
19509 a number of @code{@@include} commands listing the included files. It
19510 should not even include indices, which should be listed in an included
19511 file of their own.@refill
19513 Moreover, each of the included files must contain exactly one highest
19514 level node (conventionally, @code{@@chapter} or equivalent),
19515 and this node must be the first node in the included file.
19516 Furthermore, each of these highest level nodes in each included file
19517 must be at the same hierarchical level in the file structure.
19518 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
19519 @code{@@unnumbered} node. Thus, normally, each included file contains
19520 one, and only one, chapter or equivalent-level node.@refill
19522 The outer file should contain only @emph{one} node, the `Top' node. It
19523 should @emph{not} contain any nodes besides the single `Top' node. The
19524 @code{texinfo-multiple-files-update} command will not process
19528 @node Sample Include File
19529 @section Sample File with @code{@@include}
19530 @cindex Sample @code{@@include} file
19531 @cindex Include file sample
19532 @cindex @code{@@include} file sample
19534 Here is an example of an outer Texinfo file with @code{@@include} files
19535 within it before running @code{texinfo-multiple-files-update}, which
19536 would insert a main or master menu:
19540 \input texinfo @@c -*-texinfo-*-
19541 @c %**start of header
19542 @@setfilename include-example.info
19543 @@settitle Include Example
19544 @c %**end of header
19547 ... @xref{Sample Texinfo Files}, for
19548 examples of the rest of the frontmatter ...
19553 @@top Include Example
19558 @@include foo.texinfo
19559 @@include bar.texinfo
19560 @@include concept-index.texinfo
19565 An included file, such as @file{foo.texinfo}, might look like this:
19570 @@chapter First Chapter
19572 Contents of first chapter @dots{}
19576 The full contents of @file{concept-index.texinfo} might be as simple as this:
19580 @@node Concept Index
19581 @@unnumbered Concept Index
19587 The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
19588 Manual} is named @file{elisp.texi}. This outer file contains a master
19589 menu with 417 entries and a list of 41 @code{@@include}
19593 @node Include Files Evolution
19594 @section Evolution of Include Files
19596 When Info was first created, it was customary to create many small
19597 Info files on one subject. Each Info file was formatted from its own
19598 Texinfo source file. This custom meant that Emacs did not need to
19599 make a large buffer to hold the whole of a large Info file when
19600 someone wanted information; instead, Emacs allocated just enough
19601 memory for the small Info file that contained the particular
19602 information sought. This way, Emacs could avoid wasting memory.@refill
19604 References from one file to another were made by referring to the file
19605 name as well as the node name. (@xref{Other Info Files, , Referring to
19606 Other Info Files}. Also, see @ref{Four and Five Arguments, ,
19607 @code{@@xref} with Four and Five Arguments}.)@refill
19609 Include files were designed primarily as a way to create a single,
19610 large printed manual out of several smaller Info files. In a printed
19611 manual, all the references were within the same document, so @TeX{}
19612 could automatically determine the references' page numbers. The Info
19613 formatting commands used include files only for creating joint
19614 indices; each of the individual Texinfo files had to be formatted for
19615 Info individually. (Each, therefore, required its own
19616 @code{@@setfilename} line.)@refill
19618 However, because large Info files are now split automatically, it is
19619 no longer necessary to keep them small.@refill
19621 Nowadays, multiple Texinfo files are used mostly for large documents,
19622 such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
19623 in which several different people write different sections of a
19624 document simultaneously.@refill
19626 In addition, the Info formatting commands have been extended to work
19627 with the @code{@@include} command so as to create a single large Info
19628 file that is split into smaller files if necessary. This means that
19629 you can write menus and cross references without naming the different
19630 Texinfo files.@refill
19634 @appendix Page Headings
19637 @cindex Page numbering
19638 @cindex Page headings
19639 @cindex Formatting headings and footings
19641 Most printed manuals contain headings along the top of every page
19642 except the title and copyright pages. Some manuals also contain
19643 footings. (Headings and footings have no meaning to Info, which is
19644 not paginated.)@refill
19647 * Headings Introduced:: Conventions for using page headings.
19648 * Heading Format:: Standard page heading formats.
19649 * Heading Choice:: How to specify the type of page heading.
19650 * Custom Headings:: How to create your own headings and footings.
19653 @node Headings Introduced
19654 @section Headings Introduced
19656 Texinfo provides standard page heading formats for manuals that are
19657 printed on one side of each sheet of paper and for manuals that are
19658 printed on both sides of the paper. Typically, you will use these
19659 formats, but you can specify your own format if you wish.@refill
19661 In addition, you can specify whether chapters should begin on a new
19662 page, or merely continue the same page as the previous chapter; and if
19663 chapters begin on new pages, you can specify whether they must be
19664 odd-numbered pages.@refill
19666 By convention, a book is printed on both sides of each sheet of paper.
19667 When you open a book, the right-hand page is odd-numbered, and
19668 chapters begin on right-hand pages---a preceding left-hand page is
19669 left blank if necessary. Reports, however, are often printed on just
19670 one side of paper, and chapters begin on a fresh page immediately
19671 following the end of the preceding chapter. In short or informal
19672 reports, chapters often do not begin on a new page at all, but are
19673 separated from the preceding text by a small amount of whitespace.@refill
19675 The @code{@@setchapternewpage} command controls whether chapters begin
19676 on new pages, and whether one of the standard heading formats is used.
19677 In addition, Texinfo has several heading and footing commands that you
19678 can use to generate your own heading and footing formats.@refill
19680 In Texinfo, headings and footings are single lines at the tops and
19681 bottoms of pages; you cannot create multiline headings or footings.
19682 Each header or footer line is divided into three parts: a left part, a
19683 middle part, and a right part. Any part, or a whole line, may be left
19684 blank. Text for the left part of a header or footer line is set
19685 flushleft; text for the middle part is centered; and, text for the
19686 right part is set flushright.@refill
19688 @node Heading Format
19689 @comment node-name, next, previous, up
19690 @section Standard Heading Formats
19692 Texinfo provides two standard heading formats, one for manuals printed
19693 on one side of each sheet of paper, and the other for manuals printed
19694 on both sides of the paper.
19696 By default, nothing is specified for the footing of a Texinfo file,
19697 so the footing remains blank.@refill
19699 The standard format for single-sided printing consists of a header
19700 line in which the left-hand part contains the name of the chapter, the
19701 central part is blank, and the right-hand part contains the page
19705 A single-sided page looks like this:
19709 _______________________
19711 | chapter page number |
19713 | Start of text ... |
19719 The standard format for two-sided printing depends on whether the page
19720 number is even or odd. By convention, even-numbered pages are on the
19721 left- and odd-numbered pages are on the right. (@TeX{} will adjust the
19722 widths of the left- and right-hand margins. Usually, widths are
19723 correct, but during double-sided printing, it is wise to check that
19724 pages will bind properly---sometimes a printer will produce output in
19725 which the even-numbered pages have a larger right-hand margin than the
19726 odd-numbered pages.)@refill
19728 In the standard double-sided format, the left part of the left-hand
19729 (even-numbered) page contains the page number, the central part is
19730 blank, and the right part contains the title (specified by the
19731 @code{@@settitle} command). The left part of the right-hand
19732 (odd-numbered) page contains the name of the chapter, the central part
19733 is blank, and the right part contains the page number.@refill
19736 Two pages, side by side as in an open book, look like this:@refill
19740 _______________________ _______________________
19742 | page number title | | chapter page number |
19744 | Start of text ... | | More text ... |
19751 The chapter name is preceded by the word ``Chapter'', the chapter number
19752 and a colon. This makes it easier to keep track of where you are in the
19755 @node Heading Choice
19756 @comment node-name, next, previous, up
19757 @section Specifying the Type of Heading
19759 @TeX{} does not begin to generate page headings for a standard Texinfo
19760 file until it reaches the @code{@@end titlepage} command. Thus, the
19761 title and copyright pages are not numbered. The @code{@@end
19762 titlepage} command causes @TeX{} to begin to generate page headings
19763 according to a standard format specified by the
19764 @code{@@setchapternewpage} command that precedes the
19765 @code{@@titlepage} section.@refill
19768 There are four possibilities:@refill
19771 @item No @code{@@setchapternewpage} command
19772 Cause @TeX{} to specify the single-sided heading format, with chapters
19773 on new pages. This is the same as @code{@@setchapternewpage on}.@refill
19775 @item @code{@@setchapternewpage on}
19776 Specify the single-sided heading format, with chapters on new pages.@refill
19778 @item @code{@@setchapternewpage off}
19779 Cause @TeX{} to start a new chapter on the same page as the last page of
19780 the preceding chapter, after skipping some vertical whitespace. Also
19781 cause @TeX{} to typeset for single-sided printing. (You can override
19782 the headers format with the @code{@@headings double} command; see
19783 @ref{headings on off, , The @code{@@headings} Command}.)@refill
19785 @item @code{@@setchapternewpage odd}
19786 Specify the double-sided heading format, with chapters on new pages.@refill
19790 Texinfo lacks an @code{@@setchapternewpage even} command.@refill
19792 @node Custom Headings
19793 @comment node-name, next, previous, up
19794 @section How to Make Your Own Headings
19796 You can use the standard headings provided with Texinfo or specify
19797 your own. By default, Texinfo has no footers, so if you specify them,
19798 the available page size for the main text will be slightly reduced.
19800 Texinfo provides six commands for specifying headings and
19804 @code{@@everyheading} @code{@@everyfooting} generate page headers and
19805 footers that are the same for both even- and odd-numbered pages.
19807 @code{@@evenheading} and @code{@@evenfooting} command generate headers
19808 and footers for even-numbered (left-hand) pages.
19810 @code{@@oddheading} and @code{@@oddfooting} generate headers and footers
19811 for odd-numbered (right-hand) pages.
19814 Write custom heading specifications in the Texinfo file immediately
19815 after the @code{@@end titlepage} command.
19816 You must cancel the predefined heading commands with the
19817 @code{@@headings off} command before defining your own
19821 Here is how to tell @TeX{} to place the chapter name at the left, the
19822 page number in the center, and the date at the right of every header
19823 for both even- and odd-numbered pages:
19828 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
19833 You need to divide the left part from the central part and the central
19834 part from the right part by inserting @samp{@@|} between parts.
19835 Otherwise, the specification command will not be able to tell where
19836 the text for one part ends and the next part begins.
19838 Each part can contain text or @@-commands. The text
19839 is printed as if the part were within an ordinary paragraph in the
19840 body of the page. The @@-commands replace
19841 themselves with the page number, date, chapter name, or
19845 Here are the six heading and footing commands:
19848 @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
19849 @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
19850 @findex everyheading
19851 @findex everyfooting
19852 The `every' commands specify the format for both even- and odd-numbered
19853 pages. These commands are for documents that are printed on one side
19854 of each sheet of paper, or for documents in which you want symmetrical
19855 headers or footers.
19857 @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
19858 @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
19859 @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
19860 @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
19861 @findex evenheading
19862 @findex evenfooting
19865 The `even' and `odd' commands specify the format for even-numbered
19866 pages and odd-numbered pages. These commands are for books and
19867 manuals that are printed on both sides of each sheet of paper.
19870 Use the @samp{@@this@dots{}} series of @@-commands to
19871 provide the names of chapters
19872 and sections and the page number. You can use the
19873 @samp{@@this@dots{}} commands in the left, center, or right portions
19874 of headers and footers, or anywhere else in a Texinfo file so long as
19875 they are between @code{@@iftex} and @code{@@end iftex} commands.
19878 Here are the @samp{@@this@dots{}} commands:
19883 Expands to the current page number.
19885 @item @@thissectionname
19886 @findex thissectionname
19887 Expands to the name of the current section.
19889 @item @@thissectionnum
19890 @findex thissectionnum
19891 Expands to the number of the current section.
19893 @item @@thissection
19894 @findex thissection
19895 Expands to the number and name of the current section, in the format
19896 `Section 1: Title'.
19898 @item @@thischaptername
19899 @findex thischaptername
19900 Expands to the name of the current chapter.
19902 @item @@thischapternum
19903 @findex thischapternum
19904 Expands to the number of the current chapter, or letter of the current
19907 @item @@thischapter
19908 @findex thischapter
19909 Expands to the number and name of the current
19910 chapter, in the format `Chapter 1: Title'.
19914 Expands to the name of the document, as specified by the
19915 @code{@@settitle} command.
19919 For @code{@@include} files only: expands to the name of the current
19920 @code{@@include} file. If the current Texinfo source file is not an
19921 @code{@@include} file, this command has no effect. This command does
19922 @emph{not} provide the name of the current Texinfo source file unless
19923 it is an @code{@@include} file. (@xref{Include Files}, for more
19924 information about @code{@@include} files.)
19928 You can also use the @code{@@today@{@}} command, which expands to the
19929 current date, in `1 Jan 1900' format.
19932 Other @@-commands and text are printed in a header or footer just as
19933 if they were in the body of a page. It is useful to incorporate text,
19934 particularly when you are writing drafts:
19939 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
19940 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
19944 Beware of overlong titles: they may overlap another part of the
19945 header or footer and blot it out.
19947 If you have very short chapters and/or sections, several of them can
19948 appear on a single page. You can specify which chapters and sections
19949 you want @code{@@thischapter}, @code{@@thissection} and other such
19950 macros to refer to on such pages as follows:
19953 @item @@everyheadingmarks @var{ref}
19954 @itemx @@everyfootingmarks @var{ref}
19955 @findex everyheadingmarks
19956 @findex everyfootingmarks
19957 The @var{ref} argument can be either @code{top} (the @code{@@this...}
19958 commands will refer to the chapter/section at the top of a page) or
19959 @code{bottom} (the commands will reflect the situation at the bottom
19960 of a page). These @samp{@@every...} commands specify what to do on
19961 both even- and odd-numbered pages.
19963 @item @@evenheadingmarks @var{ref}
19964 @itemx @@oddheadingmarks @var{ref}
19965 @itemx @@evenfootingmarks @var{ref}
19966 @itemx @@oddfootingmarks @var{ref}
19967 @findex evenheadingmarks
19968 @findex oddheadingmarks
19969 @findex evenfootingmarks
19970 @findex oddfootingmarks
19971 These @samp{@@even...} and @samp{@@odd...} commands specify what to do
19972 on only even- or odd-numbered pages, respectively. The @var{ref}
19973 argument is the same as with the @samp{@@every...} commands.
19976 Write these commands immediately after the @code{@@...contents}
19977 commands, or after the @code{@@end titlepage} command if you don't
19978 have a table of contents or if it is printed at the end of your
19981 By default the @code{@@this...} commands reflect the situation at the
19982 bottom of a page both in headings and in footings.
19985 @node Catching Mistakes
19986 @appendix Formatting Mistakes
19987 @cindex Structure, catching mistakes in
19988 @cindex Nodes, catching mistakes
19989 @cindex Catching mistakes
19990 @cindex Correcting mistakes
19991 @cindex Mistakes, catching
19992 @cindex Problems, catching
19993 @cindex Debugging the Texinfo structure
19995 Besides mistakes in the content of your documentation, there are two
19996 kinds of mistake you can make with Texinfo: you can make mistakes with
19997 @@-commands, and you can make mistakes with the structure of the nodes
20000 Emacs has two tools for catching the @@-command mistakes and two for
20001 catching structuring mistakes.@refill
20003 For finding problems with @@-commands, you can run @TeX{} or a region
20004 formatting command on the region that has a problem; indeed, you can
20005 run these commands on each region as you write it.@refill
20007 For finding problems with the structure of nodes and chapters, you can use
20008 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
20009 command and you can use the @kbd{M-x Info-validate} command.@refill
20012 * makeinfo Preferred:: @code{makeinfo} finds errors.
20013 * Debugging with Info:: How to catch errors with Info formatting.
20014 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
20015 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
20016 * Using occur:: How to list all lines containing a pattern.
20017 * Running Info-Validate:: How to find badly referenced nodes.
20021 @node makeinfo Preferred
20022 @section @code{makeinfo} Find Errors
20024 The @code{makeinfo} program does an excellent job of catching errors
20025 and reporting them---far better than @code{texinfo-format-region} or
20026 @code{texinfo-format-buffer}. In addition, the various functions for
20027 automatically creating and updating node pointers and menus remove
20028 many opportunities for human error.@refill
20030 If you can, use the updating commands to create and insert pointers
20031 and menus. These prevent many errors. Then use @code{makeinfo} (or
20032 its Texinfo mode manifestations, @code{makeinfo-region} and
20033 @code{makeinfo-buffer}) to format your file and check for other
20034 errors. This is the best way to work with Texinfo. But if you
20035 cannot use @code{makeinfo}, or your problem is very puzzling, then you
20036 may want to use the tools described in this appendix.@refill
20038 @node Debugging with Info
20039 @comment node-name, next, previous, up
20040 @section Catching Errors with Info Formatting
20041 @cindex Catching errors with Info formatting
20042 @cindex Debugging with Info formatting
20044 After you have written part of a Texinfo file, you can use the
20045 @code{texinfo-format-region} or the @code{makeinfo-region} command to
20046 see whether the region formats properly.@refill
20048 Most likely, however, you are reading this section because for some
20049 reason you cannot use the @code{makeinfo-region} command; therefore, the
20050 rest of this section presumes that you are using
20051 @code{texinfo-format-region}.@refill
20053 If you have made a mistake with an @@-command,
20054 @code{texinfo-format-region} will stop processing at or after the
20055 error and display an error message. To see where in the buffer the
20056 error occurred, switch to the @samp{*Info Region*} buffer; the cursor
20057 will be in a position that is after the location of the error. Also,
20058 the text will not be formatted after the place where the error
20059 occurred (or more precisely, where it was detected).@refill
20061 For example, if you accidentally end a menu with the command @code{@@end
20062 menus} with an `s' on the end, instead of with @code{@@end menu}, you
20063 will see an error message that says:@refill
20066 @@end menus is not handled by texinfo
20070 The cursor will stop at the point in the buffer where the error
20071 occurs, or not long after it. The buffer will look like this:@refill
20075 ---------- Buffer: *Info Region* ----------
20078 * Using texinfo-show-structure:: How to use
20079 `texinfo-show-structure'
20081 * Running Info-Validate:: How to check for
20082 unreferenced nodes.
20085 ---------- Buffer: *Info Region* ----------
20089 The @code{texinfo-format-region} command sometimes provides slightly
20090 odd error messages. For example, the following cross reference fails to format:@refill
20093 (@@xref@{Catching Mistakes, for more info.)
20097 In this case, @code{texinfo-format-region} detects the missing closing
20098 brace but displays a message that says @samp{Unbalanced parentheses}
20099 rather than @samp{Unbalanced braces}. This is because the formatting
20100 command looks for mismatches between braces as if they were
20101 parentheses.@refill
20103 Sometimes @code{texinfo-format-region} fails to detect mistakes. For
20104 example, in the following, the closing brace is swapped with the
20105 closing parenthesis:@refill
20108 (@@xref@{Catching Mistakes), for more info.@}
20112 Formatting produces:
20114 (*Note for more info.: Catching Mistakes)
20117 The only way for you to detect this error is to realize that the
20118 reference should have looked like this:@refill
20121 (*Note Catching Mistakes::, for more info.)
20124 Incidentally, if you are reading this node in Info and type @kbd{f
20125 @key{RET}} (@code{Info-follow-reference}), you will generate an error
20129 No such node: "Catching Mistakes) The only way @dots{}
20133 This is because Info perceives the example of the error as the first
20134 cross reference in this node and if you type a @key{RET} immediately
20135 after typing the Info @kbd{f} command, Info will attempt to go to the
20136 referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
20137 will complete the node name of the correctly written example and take
20138 you to the `Catching Mistakes' node. (If you try this, you can return
20139 from the `Catching Mistakes' node by typing @kbd{l}
20140 (@code{Info-last}).)
20142 @c !!! section on using Elisp debugger ignored.
20144 Sometimes @code{texinfo-format-region} will stop long after the
20145 original error; this is because it does not discover the problem until
20146 then. In this case, you will need to backtrack.@refill
20149 @c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger.
20152 @c node Using the Emacs Lisp Debugger
20153 @c appendixsubsec Using the Emacs Lisp Debugger
20154 @c index Using the Emacs Lisp debugger
20155 @c index Emacs Lisp debugger
20156 @c index Debugger, using the Emacs Lisp
20158 If an error is especially elusive, you can turn on the Emacs Lisp
20159 debugger and look at the backtrace; this tells you where in the
20160 @code{texinfo-format-region} function the problem occurred. You can
20161 turn on the debugger with the command:@refill
20164 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
20168 and turn it off with
20171 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
20174 Often, when you are using the debugger, it is easier to follow what is
20175 going on if you use the Emacs Lisp files that are not byte-compiled.
20176 The byte-compiled sources send octal numbers to the debugger that may
20177 look mysterious. To use the uncompiled source files, load
20178 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
20181 The debugger will not catch an error if @code{texinfo-format-region}
20182 does not detect one. In the example shown above,
20183 @code{texinfo-format-region} did not find the error when the whole
20184 list was formatted, but only when part of the list was formatted.
20185 When @code{texinfo-format-region} did not find an error, the debugger
20186 did not find one either. @refill
20188 However, when @code{texinfo-format-region} did report an error, it
20189 invoked the debugger. This is the backtrace it produced:@refill
20192 ---------- Buffer: *Backtrace* ----------
20193 Signalling: (search-failed "[@},]")
20194 re-search-forward("[@},]")
20197 texinfo-format-parse-args()
20199 texinfo-format-xref()
20200 funcall(texinfo-format-xref)
20205 texinfo-format-scan()
20206 (save-excursion ...)
20208 texinfo-format-region(103370 103631)
20209 * call-interactively(texinfo-format-region)
20210 ---------- Buffer: *Backtrace* ----------
20213 The backtrace is read from the bottom up.
20214 @code{texinfo-format-region} was called interactively; and it, in
20215 turn, called various functions, including @code{texinfo-format-scan},
20216 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
20217 Inside the function @code{texinfo-format-parse-args}, the function
20218 @code{re-search-forward} was called; it was this function that could
20219 not find the missing right-hand brace.@refill
20221 @xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs
20222 Manual}, for more information.@refill
20225 @node Debugging with TeX
20226 @comment node-name, next, previous, up
20227 @section Catching Errors with @TeX{} Formatting
20228 @cindex Catching errors with @TeX{} formatting
20229 @cindex Debugging with @TeX{} formatting
20231 You can also catch mistakes when you format a file with @TeX{}.@refill
20233 Usually, you will want to do this after you have run
20234 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
20235 the same file, because @code{texinfo-format-buffer} sometimes displays
20236 error messages that make more sense than @TeX{}. (@xref{Debugging
20237 with Info}, for more information.)@refill
20239 For example, @TeX{} was run on a Texinfo file, part of which is shown
20243 ---------- Buffer: texinfo.texi ----------
20244 name of the Texinfo file as an extension. The
20245 @@samp@{??@} are `wildcards' that cause the shell to
20246 substitute all the raw index files. (@@xref@{sorting
20247 indices, for more information about sorting
20249 ---------- Buffer: texinfo.texi ----------
20253 (The cross reference lacks a closing brace.)
20254 @TeX{} produced the following output, after which it stopped:@refill
20257 ---------- Buffer: *tex-shell* ----------
20259 @{sorting indices, for more information about sorting
20260 indices.) @@refill @@ETC.
20261 ! Paragraph ended before @@xref was complete.
20267 ---------- Buffer: *tex-shell* ----------
20270 In this case, @TeX{} produced an accurate and
20271 understandable error message:
20274 Paragraph ended before @@xref was complete.
20278 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
20279 @samp{l.27} means that @TeX{} detected the problem on line 27 of the
20280 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
20281 circumstance.@refill
20283 Unfortunately, @TeX{} is not always so helpful, and sometimes you must
20284 truly be a Sherlock Holmes to discover what went wrong.@refill
20286 In any case, if you run into a problem like this, you can do one of three
20291 You can tell @TeX{} to continue running and ignore just this error by
20292 typing @key{RET} at the @samp{?} prompt.@refill
20295 You can tell @TeX{} to continue running and to ignore all errors as best
20296 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
20298 This is often the best thing to do. However, beware: the one error
20299 may produce a cascade of additional error messages as its consequences
20300 are felt through the rest of the file. To stop @TeX{} when it is
20301 producing such an avalanche of error messages, type @kbd{C-c} (or
20302 @kbd{C-c C-c}, if you are running a shell inside Emacs).
20305 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
20306 at the @samp{?} prompt.@refill
20309 If you are running @TeX{} inside Emacs, you need to switch to the shell
20310 buffer and line at which @TeX{} offers the @samp{?} prompt.
20312 Sometimes @TeX{} will format a file without producing error messages even
20313 though there is a problem. This usually occurs if a command is not ended
20314 but @TeX{} is able to continue processing anyhow. For example, if you fail
20315 to end an itemized list with the @code{@@end itemize} command, @TeX{} will
20316 write a DVI file that you can print out. The only error message that
20317 @TeX{} will give you is the somewhat mysterious comment that@refill
20320 (@@end occurred inside a group at level 1)
20324 However, if you print the DVI file, you will find that the text
20325 of the file that follows the itemized list is entirely indented as if
20326 it were part of the last item in the itemized list. The error message
20327 is the way @TeX{} says that it expected to find an @code{@@end}
20328 command somewhere in the file; but that it could not determine where
20329 it was needed.@refill
20331 Another source of notoriously hard-to-find errors is a missing
20332 @code{@@end group} command. If you ever are stumped by
20333 incomprehensible errors, look for a missing @code{@@end group} command
20336 If the Texinfo file lacks header lines,
20337 @TeX{} may stop in the
20338 beginning of its run and display output that looks like the following.
20339 The @samp{*} indicates that @TeX{} is waiting for input.@refill
20342 This is TeX, Version 3.14159 (Web2c 7.0)
20348 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
20349 write the header lines in the Texinfo file and run the @TeX{} command
20350 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
20351 instead of @samp{@@}; and in this circumstance, you are working
20352 directly with @TeX{}, not with Texinfo.)@refill
20354 @node Using texinfo-show-structure
20355 @comment node-name, next, previous, up
20356 @section Using @code{texinfo-show-structure}
20357 @cindex Showing the structure of a file
20358 @findex texinfo-show-structure
20360 It is not always easy to keep track of the nodes, chapters, sections, and
20361 subsections of a Texinfo file. This is especially true if you are revising
20362 or adding to a Texinfo file that someone else has written.@refill
20364 In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
20365 command lists all the lines that begin with the @@-commands that
20366 specify the structure: @code{@@chapter}, @code{@@section},
20367 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
20368 as prefix argument, if interactive),
20369 the command also shows the @code{@@node} lines. The
20370 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
20371 Texinfo mode, by default.@refill
20373 The lines are displayed in a buffer called the @samp{*Occur*} buffer,
20374 indented by hierarchical level. For example, here is a part of what was
20375 produced by running @code{texinfo-show-structure} on this manual:@refill
20379 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
20380 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
20381 in buffer texinfo.texi.
20383 4177:@@chapter Nodes
20384 4198: @@heading Two Paths
20385 4231: @@section Node and Menu Illustration
20386 4337: @@section The @@code@{@@@@node@} Command
20387 4393: @@subheading Choosing Node and Pointer Names
20388 4417: @@subsection How to Write an @@code@{@@@@node@} Line
20389 4469: @@subsection @@code@{@@@@node@} Line Tips
20394 This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
20395 with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
20396 commands respectively. If you move your cursor into the @samp{*Occur*}
20397 window, you can position the cursor over one of the lines and use the
20398 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
20399 the corresponding spot in the Texinfo file. @xref{Other Repeating
20400 Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
20401 information about @code{occur-mode-goto-occurrence}.@refill
20403 The first line in the @samp{*Occur*} window describes the @dfn{regular
20404 expression} specified by @var{texinfo-heading-pattern}. This regular
20405 expression is the pattern that @code{texinfo-show-structure} looks for.
20406 @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
20407 for more information.@refill
20409 When you invoke the @code{texinfo-show-structure} command, Emacs will
20410 display the structure of the whole buffer. If you want to see the
20411 structure of just a part of the buffer, of one chapter, for example,
20412 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
20413 region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is
20414 how the example used above was generated. (To see the whole buffer
20415 again, use @kbd{C-x n w} (@code{widen}).)@refill
20417 If you call @code{texinfo-show-structure} with a prefix argument by
20418 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
20419 @code{@@node} as well as the lines beginning with the @@-sign commands
20420 for @code{@@chapter}, @code{@@section}, and the like.@refill
20422 You can remind yourself of the structure of a Texinfo file by looking at
20423 the list in the @samp{*Occur*} window; and if you have mis-named a node
20424 or left out a section, you can correct the mistake.@refill
20427 @comment node-name, next, previous, up
20428 @section Using @code{occur}
20429 @cindex Occurrences, listing with @code{@@occur}
20432 Sometimes the @code{texinfo-show-structure} command produces too much
20433 information. Perhaps you want to remind yourself of the overall structure
20434 of a Texinfo file, and are overwhelmed by the detailed list produced by
20435 @code{texinfo-show-structure}. In this case, you can use the @code{occur}
20436 command directly. To do this, type@refill
20443 and then, when prompted, type a @dfn{regexp}, a regular expression for
20444 the pattern you want to match. (@xref{Regexps, , Regular Expressions,
20445 emacs, The GNU Emacs Manual}.) The @code{occur} command works from
20446 the current location of the cursor in the buffer to the end of the
20447 buffer. If you want to run @code{occur} on the whole buffer, place
20448 the cursor at the beginning of the buffer.@refill
20450 For example, to see all the lines that contain the word
20451 @samp{@@chapter} in them, just type @samp{@@chapter}. This will
20452 produce a list of the chapters. It will also list all the sentences
20453 with @samp{@@chapter} in the middle of the line.@refill
20455 If you want to see only those lines that start with the word
20456 @samp{@@chapter}, type @samp{^@@chapter} when prompted by
20457 @code{occur}. If you want to see all the lines that end with a word
20458 or phrase, end the last word with a @samp{$}; for example,
20459 @samp{catching mistakes$}. This can be helpful when you want to see
20460 all the nodes that are part of the same chapter or section and
20461 therefore have the same `Up' pointer.@refill
20463 @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
20464 for more information.@refill
20466 @node Running Info-Validate
20467 @comment node-name, next, previous, up
20468 @section Finding Badly Referenced Nodes
20469 @findex Info-validate
20470 @cindex Nodes, checking for badly referenced
20471 @cindex Checking for badly referenced nodes
20472 @cindex Looking for badly referenced nodes
20473 @cindex Finding badly referenced nodes
20474 @cindex Badly referenced nodes
20476 You can use the @code{Info-validate} command to check whether any of
20477 the `Next', `Previous', `Up' or other node pointers fail to point to a
20478 node. This command checks that every node pointer points to an
20479 existing node. The @code{Info-validate} command works only on Info
20480 files, not on Texinfo files.@refill
20482 The @code{makeinfo} program validates pointers automatically, so you
20483 do not need to use the @code{Info-validate} command if you are using
20484 @code{makeinfo}. You only may need to use @code{Info-validate} if you
20485 are unable to run @code{makeinfo} and instead must create an Info file
20486 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
20487 if you write an Info file from scratch.@refill
20490 * Using Info-validate:: How to run @code{Info-validate}.
20491 * Unsplit:: How to create an unsplit file.
20492 * Tagifying:: How to tagify a file.
20493 * Splitting:: How to split a file manually.
20496 @node Using Info-validate
20497 @subsection Running @code{Info-validate}
20498 @cindex Running @code{Info-validate}
20499 @cindex Info validating a large file
20500 @cindex Validating a large file
20502 To use @code{Info-validate}, visit the Info file you wish to check and
20510 Note that the @code{Info-validate} command requires an upper case
20511 `I'. You may also need to create a tag table before running
20512 @code{Info-validate}. @xref{Tagifying}.
20514 If your file is valid, you will receive a message that says ``File appears
20515 valid''. However, if you have a pointer that does not point to a node,
20516 error messages will be displayed in a buffer called @samp{*problems in
20517 info file*}.@refill
20519 For example, @code{Info-validate} was run on a test file that contained
20520 only the first node of this manual. One of the messages said:@refill
20523 In node "Overview", invalid Next: Texinfo Mode
20527 This meant that the node called @samp{Overview} had a `Next' pointer that
20528 did not point to anything (which was true in this case, since the test file
20529 had only one node in it).@refill
20531 Now suppose we add a node named @samp{Texinfo Mode} to our test case
20532 but we do not specify a `Previous' for this node. Then we will get
20533 the following error message:@refill
20536 In node "Texinfo Mode", should have Previous: Overview
20540 This is because every `Next' pointer should be matched by a
20541 `Previous' (in the node where the `Next' points) which points back.@refill
20543 @code{Info-validate} also checks that all menu entries and cross references
20544 point to actual nodes.@refill
20546 @code{Info-validate} requires a tag table and does not work with files
20547 that have been split. (The @code{texinfo-format-buffer} command
20548 automatically splits large files.) In order to use @code{Info-validate}
20549 on a large file, you must run @code{texinfo-format-buffer} with an
20550 argument so that it does not split the Info file; and you must create a
20551 tag table for the unsplit file.
20554 @comment node-name, next, previous, up
20555 @subsection Creating an Unsplit File
20556 @cindex Creating an unsplit file
20557 @cindex Unsplit file creation
20559 You can run @code{Info-validate} only on a single Info file that has a
20560 tag table. The command will not work on the indirect subfiles that
20561 are generated when a master file is split. If you have a large file
20562 (longer than 300,000 bytes or so), you need to run the
20563 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
20564 a way that it does not create indirect subfiles. You will also need
20565 to create a tag table for the Info file. After you have done this,
20566 you can run @code{Info-validate} and look for badly referenced
20569 The first step is to create an unsplit Info file. To prevent
20570 @code{texinfo-format-buffer} from splitting a Texinfo file into
20571 smaller Info files, give a prefix to the @kbd{M-x
20572 texinfo-format-buffer} command:@refill
20575 C-u M-x texinfo-format-buffer
20586 When you do this, Texinfo will not split the file and will not create
20587 a tag table for it. @refill
20588 @cindex Making a tag table manually
20589 @cindex Tag table, making manually
20592 @subsection Tagifying a File
20594 After creating an unsplit Info file, you must create a tag table for
20595 it. Visit the Info file you wish to tagify and type:@refill
20602 (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
20603 Info file with a tag table that you can validate.@refill
20605 The third step is to validate the Info file:@refill
20612 (Note the upper case @samp{I} in @code{Info-validate}.)
20613 In brief, the steps are:@refill
20617 C-u M-x texinfo-format-buffer
20623 After you have validated the node structure, you can rerun
20624 @code{texinfo-format-buffer} in the normal way so it will construct a
20625 tag table and split the file automatically, or you can make the tag
20626 table and split the file manually.@refill
20629 @comment node-name, next, previous, up
20630 @subsection Splitting a File Manually
20631 @cindex Splitting an Info file manually
20632 @cindex Info file, splitting manually
20634 You should split a large file or else let the
20635 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
20636 for you automatically. (Generally you will let one of the formatting
20637 commands do this job for you. @xref{Creating an Info File}.)@refill
20639 The split-off files are called the indirect subfiles.@refill
20641 Info files are split to save memory. With smaller files, Emacs does not
20642 have make such a large buffer to hold the information.@refill
20644 If an Info file has more than 30 nodes, you should also make a tag
20645 table for it. @xref{Using Info-validate}, for information
20646 about creating a tag table. (Again, tag tables are usually created
20647 automatically by the formatting command; you only need to create a tag
20648 table yourself if you are doing the job manually. Most likely, you
20649 will do this for a large, unsplit file on which you have run
20650 @code{Info-validate}.)@refill
20652 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
20654 Before running @code{Info-split}, you need to load the @code{info} library
20655 into Emacs by giving the command @kbd{M-x load-library @key{RET} info
20659 Visit the Info file you wish to tagify and split and type the two
20668 (Note that the @samp{I} in @samp{Info} is upper case.)@refill
20670 When you use the @code{Info-split} command, the buffer is modified into a
20671 (small) Info file which lists the indirect subfiles. This file should be
20672 saved in place of the original visited file. The indirect subfiles are
20673 written in the same directory the original file is in, with names generated
20674 by appending @samp{-} and a number to the original file name.@refill
20676 The primary file still functions as an Info file, but it contains just
20677 the tag table and a directory of subfiles.@refill
20681 The simple description in the command summary seems sufficient to me
20682 these days, so ignore this appendix. --karl, 13mar04.
20684 @node Refilling Paragraphs
20685 @appendix Refilling Paragraphs
20686 @cindex Refilling paragraphs
20687 @cindex Filling paragraphs
20688 @cindex Paragraphs, filling
20691 The @code{@@refill} command refills and, optionally, indents the first
20692 line of a paragraph.@footnote{Perhaps the command should have been
20693 called the @code{@@refillandindent} command, but @code{@@refill} is
20694 shorter and the name was chosen before indenting was possible.} The
20695 @code{@@refill} command is no longer important, but we describe it here
20696 because you once needed it. You will see it in many old Texinfo
20699 Without refilling, paragraphs containing long @@-constructs may look
20700 bad after formatting because the formatter removes @@-commands and
20701 shortens some lines more than others. In the past, neither the
20702 @code{texinfo-format-region} command nor the
20703 @code{texinfo-format-buffer} command refilled paragraphs
20704 automatically. The @code{@@refill} command had to be written at the
20705 end of every paragraph to cause these formatters to fill them. (Both
20706 @TeX{} and @code{makeinfo} have always refilled paragraphs
20707 automatically.) Now, all the Info formatters automatically fill and
20708 indent those paragraphs that need to be filled and indented.@refill
20710 The @code{@@refill} command causes @code{texinfo-format-region} and
20711 @code{texinfo-format-buffer} to refill a paragraph in the Info file
20712 @emph{after} all the other processing has been done. For this reason,
20713 you can not use @code{@@refill} with a paragraph containing either
20714 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
20715 override those two commands.@refill
20717 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
20718 commands now automatically append @code{@@refill} to the end of each
20719 paragraph that should be filled. They do not append @code{@@refill} to
20720 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
20721 and therefore do not refill or indent them.@refill
20726 @c These are no longer ``new'', and the explanations
20727 @c are all given elsewhere anyway, I think. --karl, 25apr97.
20728 @c So ignore the entire appendix.
20730 @c node New Features, Command and Variable Index, Obtaining TeX, Top
20731 @c appendix Second Edition Features
20734 % Widen the space for the first column so three control-character
20735 % strings fit in the first column. Switched back to default .8in
20736 % value at end of chapter.
20737 \global\tableindent=1.0in
20740 The second edition of the Texinfo manual describes more than 20 new
20741 Texinfo mode commands and more than 50 previously undocumented Texinfo
20742 @@-commands. This edition is more than twice the length of the first
20745 Here is a brief description of the new commands.@refill
20748 * New Texinfo Mode Commands:: The updating commands are especially useful.
20749 * New Commands:: Many newly described @@-commands.
20752 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
20753 @c appendixsec New Texinfo Mode Commands
20755 Texinfo mode provides commands and features especially designed for
20756 working with Texinfo files. More than 20 new commands have been
20757 added, including commands for automatically creating and updating
20758 both nodes and menus. This is a tedious task when done by hand.@refill
20760 The keybindings are intended to be somewhat mnemonic.@refill
20762 @c subheading Update all nodes and menus
20764 The @code{texinfo-master-menu} command is the primary command:
20768 @itemx M-x texinfo-master-menu
20769 Create or update a master menu.
20770 With @kbd{C-u} as a prefix argument,
20771 first create or update all nodes
20775 @c subheading Update Pointers
20778 Create or update `Next', `Previous', and `Up' node pointers.@refill
20781 @xref{Updating Nodes and Menus}.
20785 @itemx M-x texinfo-update-node
20789 @itemx M-x texinfo-every-node-update
20790 Update every node in the buffer.
20793 @c subheading Update Menus
20796 Create or update menus.@refill
20799 @xref{Updating Nodes and Menus}.
20803 @itemx M-x texinfo-make-menu
20804 Make or update a menu.
20807 @itemx M-x texinfo-all-menus-update
20808 Make or update all the menus in a buffer.
20809 With @kbd{C-u} as a prefix argument,
20810 first update all the nodes.
20813 @c subheading Insert Title as Description
20816 Insert a node's chapter or section title in the space for the
20817 description in a menu entry line; position point so you can edit the
20818 insert. (This command works somewhat differently than the other
20819 insertion commands, which insert only a predefined string.)@refill
20822 @xref{Inserting, Inserting Frequently Used Commands}.
20829 @c subheading Format for Info
20832 Provide keybindings both for the Info formatting commands that are
20833 written in Emacs Lisp and for @code{makeinfo} that is written in
20837 @xref{Info Formatting}.
20840 Use the Emacs lisp @code{texinfo-format@dots{}} commands:
20851 Use @code{makeinfo}:
20861 Recenter the @code{makeinfo} output buffer.
20864 Kill the @code{makeinfo} formatting job.
20867 @c subheading Typeset and Print
20870 Typeset and print Texinfo documents from within Emacs.
20877 Run @code{texi2dvi} on the buffer.
20880 Run @TeX{} on the region.
20883 Run @code{texindex}.
20886 Print the DVI file.
20889 Show the print queue.
20892 Delete a job from the print queue.
20895 Kill the current @TeX{} formatting job.
20898 Quit a currently stopped @TeX{} formatting job.
20901 Recenter the output buffer.
20904 @c subheading Other Updating Commands
20907 The ``other updating commands'' do not have standard keybindings because
20908 they are used less frequently.@refill
20911 @xref{Other Updating Commands}.
20914 @item M-x texinfo-insert-node-lines
20915 Insert missing @code{@@node} lines using
20916 section titles as node names.
20918 @item M-x texinfo-multiple-files-update
20919 Update a multi-file document.
20920 With a numeric prefix, such as @kbd{C-u 8},
20921 update @strong{every} pointer and
20922 menu in @strong{all} the files and
20923 then insert a master menu.
20925 @item M-x texinfo-indent-menu-description
20926 Indent descriptions in menus.
20928 @item M-x texinfo-sequential-node-update
20929 Insert node pointers in strict sequence.
20932 @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX
20933 @c appendix.sec New Texinfo @@-Commands
20935 The second edition of the Texinfo manual describes more than 50
20936 commands that were not described in the first edition. A third or so
20937 of these commands existed in Texinfo but were not documented in the
20938 manual; the others are new. Here is a listing, with brief
20939 descriptions of them:@refill
20941 @c subheading Indexing
20944 Create your own index, and merge indices.@refill
20950 @item @@defindex @var{index-name}
20951 Define a new index and its indexing command.
20952 See also the @code{@@defcodeindex} command.
20954 @c written verbosely to avoid overfull hbox
20955 @item @@synindex @var{from-index} @var{into-index}
20956 Merge the @var{from-index} index into the @var{into-index} index.
20957 See also the @code{@@syncodeindex} command.
20960 @c subheading Definitions
20963 Describe functions, variables, macros,
20964 commands, user options, special forms, and other such artifacts in a
20965 uniform format.@refill
20968 @xref{Definition Commands}.
20971 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
20972 Format a description for functions, interactive
20973 commands, and similar entities.
20975 @item @@defvr, @@defop, @dots{}
20976 15 other related commands.
20979 @c subheading Glyphs
20982 Indicate the results of evaluation, expansion,
20983 printed output, an error message, equivalence of expressions, and the
20984 location of point.@refill
20998 @item @@expansion@{@}
20999 @itemx @expansion{}
21012 Result of an expression
21015 @c subheading Page Headings
21018 Customize page headings.
21024 @item @@headings @var{on-off-single-double}
21025 Headings on or off, single, or double-sided.
21027 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
21028 Footings for even-numbered (left-hand) pages.
21030 @item @@evenheading, @@everyheading, @@oddheading, @dots{}
21031 Five other related commands.
21033 @item @@thischapter
21034 Insert name of chapter and chapter number.
21036 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
21040 @c subheading Formatting
21043 Format blocks of text.
21046 @xref{Quotations and Examples}, and@*
21047 @ref{Lists and Tables, , Making Lists and Tables}.
21051 Draw rounded box surrounding text (no effect in Info).
21053 @item @@enumerate @var{optional-arg}
21054 Enumerate a list with letters or numbers.
21056 @item @@exdent @var{line-of-text}
21057 Remove indentation.
21066 Do not narrow nor change font.
21068 @item @@ftable @var{formatting-command}
21069 @itemx @@vtable @var{formatting-command}
21070 Two-column table with indexing.
21073 For an example of Lisp code.
21075 @item @@smallexample
21077 Like @@table and @@lisp, but for (originally) @@smallbook.
21080 @c subheading Conditionals
21083 Conditionally format text.
21086 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
21089 @item @@set @var{flag} [@var{string}]
21090 Set a flag. Optionally, set value
21091 of @var{flag} to @var{string}.
21093 @item @@clear @var{flag}
21096 @item @@value@{@var{flag}@}
21097 Replace with value to which @var{flag} is set.
21099 @item @@ifset @var{flag}
21100 Format, if @var{flag} is set.
21102 @item @@ifclear @var{flag}
21103 Ignore, if @var{flag} is set.
21106 @c subheading @@heading series for Titles
21109 Produce unnumbered headings that do not appear in a table of contents.
21112 @xref{Structuring}.
21115 @item @@heading @var{title}
21116 Unnumbered section-like heading not listed
21117 in the table of contents of a printed manual.
21119 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
21124 @c subheading Font commands
21128 @xref{Smallcaps}, and @*
21132 @item @@r@{@var{text}@}
21133 Print in roman font.
21135 @item @@sc@{@var{text}@}
21136 Print in @sc{small caps} font.
21139 @c subheading Miscellaneous
21142 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
21143 see @ref{Customized Highlighting},@*
21144 see @ref{Overfull hboxes},@*
21145 see @ref{Footnotes},@*
21146 see @ref{dmn, , Format a Dimension},@*
21147 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
21148 see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@*
21149 see @ref{minus, , Inserting a Minus Sign},@*
21150 see @ref{paragraphindent, , Paragraph Indenting},@*
21151 see @ref{Cross Reference Commands},@*
21152 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
21153 see @ref{Custom Headings, , How to Make Your Own Headings}.
21156 @item @@author @var{author}
21157 Typeset author's name.
21159 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
21160 @c Define a highlighting command for Info. (Info only.)
21163 Produce cleaner printed output.
21165 @item @@footnotestyle @var{end-or-separate}
21166 Specify footnote style, either @samp{end} or @samp{separate}.
21167 @xref{Footnote Styles}.
21169 @item @@dmn@{@var{dimension}@}
21170 Format a dimension.
21172 @item @@global@@let@var{new-cmd}=@var{existing-cmd}
21173 Define a highlighting command for @TeX{}. (@TeX{} only.)
21175 @item @@lowersections
21176 Reduce hierarchical level of sectioning commands.
21178 @item @@math@{@var{mathematical-expression}@}
21179 Format a mathematical expression.
21182 Generate a minus sign.
21184 @item @@paragraphindent @var{asis-or-number}
21185 Specify paragraph indentation.
21187 @item @@raisesections
21188 Raise hierarchical level of sectioning commands.
21190 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
21191 Make a reference. In the printed manual, the
21192 reference does not start with the word `see'.
21194 @item @@title @var{title}
21195 Typeset @var{title} in the alternative
21198 @item @@subtitle @var{subtitle}
21199 Typeset @var{subtitle} in the alternative
21203 Insert the current date.
21206 % Switch width of first column of tables back to default value
21207 \global\tableindent=.8in
21212 @node GNU Free Documentation License
21213 @appendix GNU Free Documentation License
21218 @node Command and Variable Index
21219 @unnumbered Command and Variable Index
21221 This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
21222 functions, and several variables. To make the list easier to use, the
21223 commands are listed without their preceding @samp{@@}.@refill
21228 @node General Index
21229 @unnumbered General Index