1\input texinfo.tex @c -*-texinfo-*- 2@c $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 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. 5 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. 9@c %**start of header 10 11@c makeinfo and texinfo.tex ignore all text before @setfilename. 12@c 13@c Ordinarily, the setfilename argument ends with .info. But 14@c texinfo.info-13 is too long for 14-character filesystems. 15@setfilename texinfo 16 17@c Automake automatically updates version.texi to @set VERSION and 18@c @set UPDATED to appropriate values. 19@include version.texi 20@settitle GNU Texinfo @value{VERSION} 21 22@c Define a new index for options. 23@defcodeindex op 24@c Put everything except function (command, in this case) names in one 25@c index (arbitrarily chosen to be the concept index). 26@syncodeindex op cp 27@syncodeindex vr cp 28@syncodeindex pg cp 29 30@paragraphindent 2 31@c finalout 32 33@comment %**end of header 34 35@copying 36This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}), 37a documentation system that can produce both online information and a 38printed manual from a single source. 39 40Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, 411999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. 42 43@quotation 44Permission is granted to copy, distribute and/or modify this document 45under the terms of the GNU Free Documentation License, Version 1.1 or 46any later version published by the Free Software Foundation; with no 47Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' 48and with the Back-Cover Texts as in (a) below. A copy of the license is 49included in the section entitled ``GNU Free Documentation License.'' 50 51(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 52this GNU Manual, like GNU software. Copies published by the Free 53Software Foundation raise funds for GNU development.'' 54@end quotation 55@end copying 56 57@dircategory Texinfo documentation system 58@direntry 59* Texinfo: (texinfo). The GNU documentation format. 60* install-info: (texinfo)Invoking install-info. Update info/dir entries. 61* texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. 62* texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. 63* texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. 64* makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. 65@end direntry 66 67@c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a 68@c prefix arg). This updates the node pointers, which texinfmt.el needs. 69 70@c Set smallbook if printing in smallbook format so the example of the 71@c smallbook font is actually written using smallbook; in bigbook, a kludge 72@c is used for TeX output. Do this through the -t option to texi2dvi, 73@c so this same source can be used for other paper sizes as well. 74@c smallbook 75@c set smallbook 76@c @@clear smallbook 77 78@c If you like blank pages, add through texi2dvi -t. 79@c setchapternewpage odd 80 81@c Currently undocumented command, 5 December 1993: 82@c nwnode (Same as node, but no warnings; for `makeinfo'.) 83 84 85@shorttitlepage GNU Texinfo 86 87@titlepage 88@title Texinfo 89@subtitle The GNU Documentation Format 90@subtitle for Texinfo version @value{VERSION}, @value{UPDATED} 91 92@author Robert J. Chassell 93@author Richard M. Stallman 94 95@c Include the Distribution inside the titlepage so 96@c that headings are turned off. 97 98@page 99@vskip 0pt plus 1filll 100@insertcopying 101 102@sp 1 103Published by the Free Software Foundation @* 10459 Temple Place Suite 330 @* 105Boston, MA 02111-1307 @* 106USA @* 107ISBN 1-882114-67-1 @c for version 4.0, September 1999. 108@c ISBN 1-882114-65-5 is for version 3.12, March 1998. 109@c ISBN 1-882114-64-7 is for edition 2.24 of November 1996. 110@c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995. 111 112@sp 1 113Cover art by Etienne Suvasa. 114@end titlepage 115 116 117@summarycontents 118@contents 119 120 121@ifnottex 122@node Top 123@top Texinfo 124 125@insertcopying 126 127The first part of this master menu lists the major nodes in this Info 128document, including the @@-command and concept indices. The rest of 129the menu lists all the lower level nodes in the document. 130 131@end ifnottex 132 133@menu 134* Copying Conditions:: Your rights. 135* Overview:: Texinfo in brief. 136* Texinfo Mode:: Using the GNU Emacs Texinfo mode. 137* Beginning a File:: What is at the beginning of a Texinfo file? 138* Ending a File:: What is at the end of a Texinfo file? 139* Structuring:: Creating chapters, sections, appendices, etc. 140* Nodes:: Writing nodes, the basic unit of Texinfo. 141* Menus:: Writing menus. 142* Cross References:: Writing cross references. 143* Marking Text:: Marking words and phrases as code, 144 keyboard input, meta-syntactic 145 variables, and the like. 146* Quotations and Examples:: Block quotations, examples, etc. 147* Lists and Tables:: Itemized or numbered lists, and tables. 148* Special Displays:: Floating figures and footnotes. 149* Indices:: Creating indices. 150* Insertions:: Inserting @@-signs, braces, etc. 151* Breaks:: Forcing or preventing line and page breaks. 152* Definition Commands:: Describing functions and the like uniformly. 153* Conditionals:: Specifying text for only some output cases. 154* Internationalization:: Supporting languages other than English. 155* Defining New Texinfo Commands:: User-defined macros and aliases. 156* Hardcopy:: Output for paper, with @TeX{}. 157* Creating and Installing Info Files:: Details on Info output. 158* Generating HTML:: Details on HTML output. 159 160* Command List:: All the Texinfo @@-commands. 161* Tips:: Hints on how to write a Texinfo document. 162* Sample Texinfo Files:: Complete examples, including full texts. 163* Include Files:: How to incorporate other Texinfo files. 164* Headings:: How to write page headings and footings. 165* Catching Mistakes:: How to find formatting mistakes. 166* Copying This Manual:: The GNU Free Documentation License. 167* Command and Variable Index:: A menu containing commands and variables. 168* Concept Index:: A menu covering many topics. 169 170@detailmenu 171 --- The Detailed Node Listing --- 172 173Overview of Texinfo 174 175* Reporting Bugs:: Submitting effective bug reports. 176* Using Texinfo:: Create printed or online output. 177* Output Formats:: Overview of the supported output formats. 178* Info Files:: What is an Info file? 179* Printed Books:: Characteristics of a printed book or manual. 180* Formatting Commands:: @@-commands are used for formatting. 181* Conventions:: General rules for writing a Texinfo file. 182* Comments:: Writing comments and ignored text in general. 183* Minimum:: What a Texinfo file must have. 184* Six Parts:: Usually, a Texinfo file has six parts. 185* Short Sample:: A short sample Texinfo file. 186* History:: Acknowledgements, contributors and genesis. 187 188Using Texinfo Mode 189 190* Texinfo Mode Overview:: How Texinfo mode can help you. 191* Emacs Editing:: Texinfo mode adds to GNU Emacs' general 192 purpose editing features. 193* Inserting:: How to insert frequently used @@-commands. 194* Showing the Structure:: How to show the structure of a file. 195* Updating Nodes and Menus:: How to update or create new nodes and menus. 196* Info Formatting:: How to format for Info. 197* Printing:: How to format and print part or all of a file. 198* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. 199 200Updating Nodes and Menus 201 202* Updating Commands:: Five major updating commands. 203* Updating Requirements:: How to structure a Texinfo file for 204 using the updating command. 205* Other Updating Commands:: How to indent descriptions, insert 206 missing nodes lines, and update 207 nodes in sequence. 208 209Beginning a Texinfo File 210 211* Sample Beginning:: A sample beginning for a Texinfo file. 212* Texinfo File Header:: The first lines. 213* Document Permissions:: Ensuring your manual is free. 214* Titlepage & Copyright Page:: Creating the title and copyright pages. 215* Contents:: How to create a table of contents. 216* The Top Node:: Creating the `Top' node and master menu. 217* Global Document Commands:: Affecting formatting throughout. 218* Software Copying Permissions:: Ensure that you and others continue to 219 have the right to use and share software. 220 221Texinfo File Header 222 223* First Line:: The first line of a Texinfo file. 224* Start of Header:: Formatting a region requires this. 225* setfilename:: Tell Info the name of the Info file. 226* settitle:: Create a title for the printed work. 227* End of Header:: Formatting a region requires this. 228 229Document Permissions 230 231* copying:: Declare the document's copying permissions. 232* insertcopying:: Where to insert the permissions. 233 234Title and Copyright Pages 235 236* titlepage:: Create a title for the printed document. 237* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, 238 and @code{@@sp} commands. 239* title subtitle author:: The @code{@@title}, @code{@@subtitle}, 240 and @code{@@author} commands. 241* Copyright:: How to write the copyright notice and 242 include copying permissions. 243* end titlepage:: Turn on page headings after the title and 244 copyright pages. 245* headings on off:: An option for turning headings on and off 246 and double or single sided printing. 247 248The `Top' Node and Master Menu 249 250* Top Node Example:: 251* Master Menu Parts:: 252 253Global Document Commands 254 255* documentdescription:: Document summary for the HTML output. 256* setchapternewpage:: Start chapters on right-hand pages. 257* paragraphindent:: Specify paragraph indentation. 258* firstparagraphindent:: Suppress indentation of the first paragraph. 259* exampleindent:: Specify environment indentation. 260 261Ending a Texinfo File 262 263* Printing Indices & Menus:: How to print an index in hardcopy and 264 generate index menus in Info. 265* File End:: How to mark the end of a file. 266 267Chapter Structuring 268 269* Tree Structuring:: A manual is like an upside down tree @dots{} 270* Structuring Command Types:: How to divide a manual into parts. 271* makeinfo top:: The @code{@@top} command, part of the `Top' node. 272* chapter:: 273* unnumbered & appendix:: 274* majorheading & chapheading:: 275* section:: 276* unnumberedsec appendixsec heading:: 277* subsection:: 278* unnumberedsubsec appendixsubsec subheading:: 279* subsubsection:: Commands for the lowest level sections. 280* Raise/lower sections:: How to change commands' hierarchical level. 281 282Nodes 283 284* Two Paths:: Different commands to structure 285 Info output and printed output. 286* Node Menu Illustration:: A diagram, and sample nodes and menus. 287* node:: Creating nodes, in detail. 288* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. 289* anchor:: Defining arbitrary cross-reference targets. 290 291The @code{@@node} Command 292 293* Node Names:: How to choose node and pointer names. 294* Writing a Node:: How to write an @code{@@node} line. 295* Node Line Tips:: Keep names short. 296* Node Line Requirements:: Keep names unique, without @@-commands. 297* First Node:: How to write a `Top' node. 298* makeinfo top command:: How to use the @code{@@top} command. 299 300Menus 301 302* Menu Location:: Menus go at the ends of short nodes. 303* Writing a Menu:: What is a menu? 304* Menu Parts:: A menu entry has three parts. 305* Less Cluttered Menu Entry:: Two part menu entry. 306* Menu Example:: Two and three part menu entries. 307* Other Info Files:: How to refer to a different Info file. 308 309Cross References 310 311* References:: What cross references are for. 312* Cross Reference Commands:: A summary of the different commands. 313* Cross Reference Parts:: A cross reference has several parts. 314* xref:: Begin a reference with `See' @dots{} 315* Top Node Naming:: How to refer to the beginning of another file. 316* ref:: A reference for the last part of a sentence. 317* pxref:: How to write a parenthetical cross reference. 318* inforef:: How to refer to an Info-only file. 319* uref:: How to refer to a uniform resource locator. 320 321@code{@@xref} 322 323* Reference Syntax:: What a reference looks like and requires. 324* One Argument:: @code{@@xref} with one argument. 325* Two Arguments:: @code{@@xref} with two arguments. 326* Three Arguments:: @code{@@xref} with three arguments. 327* Four and Five Arguments:: @code{@@xref} with four and five arguments. 328 329Marking Words and Phrases 330 331* Indicating:: How to indicate definitions, files, etc. 332* Emphasis:: How to emphasize text. 333 334Indicating Definitions, Commands, etc. 335 336* Useful Highlighting:: Highlighting provides useful information. 337* code:: Indicating program code. 338* kbd:: Showing keyboard input. 339* key:: Specifying keys. 340* samp:: A literal sequence of characters. 341* verb:: A verbatim sequence of characters. 342* var:: Indicating metasyntactic variables. 343* env:: Indicating environment variables. 344* file:: Indicating file names. 345* command:: Indicating command names. 346* option:: Indicating option names. 347* dfn:: Specifying definitions. 348* cite:: Referring to books not in the Info system. 349* abbr:: Indicating abbreviations. 350* acronym:: Indicating acronyms. 351* indicateurl:: Indicating a World Wide Web reference. 352* email:: Indicating an electronic mail address. 353 354Emphasizing Text 355 356* emph & strong:: How to emphasize text in Texinfo. 357* Smallcaps:: How to use the small caps font. 358* Fonts:: Various font commands for printed output. 359 360Quotations and Examples 361 362* Block Enclosing Commands:: Different constructs for different purposes. 363* quotation:: Writing a quotation. 364* example:: Writing an example in a fixed-width font. 365* verbatim:: Writing a verbatim example. 366* verbatiminclude:: Including a file verbatim. 367* lisp:: Illustrating Lisp code. 368* small:: Examples in a smaller font. 369* display:: Writing an example in the current font. 370* format:: Writing an example without narrowed margins. 371* exdent:: Undo indentation on a line. 372* flushleft & flushright:: Pushing text flush left or flush right. 373* noindent:: Preventing paragraph indentation. 374* indent:: Forcing paragraph indentation. 375* cartouche:: Drawing rounded rectangles around examples. 376 377Lists and Tables 378 379* Introducing Lists:: Texinfo formats lists for you. 380* itemize:: How to construct a simple list. 381* enumerate:: How to construct a numbered list. 382* Two-column Tables:: How to construct a two-column table. 383* Multi-column Tables:: How to construct generalized tables. 384 385Making a Two-column Table 386 387* table:: How to construct a two-column table. 388* ftable vtable:: Automatic indexing for two-column tables. 389* itemx:: How to put more entries in the first column. 390 391@code{@@multitable}: Multi-column Tables 392 393* Multitable Column Widths:: Defining multitable column widths. 394* Multitable Rows:: Defining multitable rows, with examples. 395 396Special Displays 397 398* Floats:: Figures, tables, and the like. 399* Images:: Including graphics and images. 400* Footnotes:: Writing footnotes. 401 402Floats 403 404* float:: Producing floating material. 405* caption shortcaption:: Specifying descriptions for floats. 406* listoffloats:: A table of contents for floats. 407 408Inserting Images 409 410* Image Syntax:: 411* Image Scaling:: 412 413Footnotes 414 415* Footnote Commands:: How to write a footnote in Texinfo. 416* Footnote Styles:: Controlling how footnotes appear in Info. 417 418Indices 419 420* Index Entries:: Choose different words for index entries. 421* Predefined Indices:: Use different indices for different kinds 422 of entries. 423* Indexing Commands:: How to make an index entry. 424* Combining Indices:: How to combine indices. 425* New Indices:: How to define your own indices. 426 427Combining Indices 428 429* syncodeindex:: How to merge two indices, using @code{@@code} 430 font for the merged-from index. 431* synindex:: How to merge two indices, using the 432 default font of the merged-to index. 433 434Special Insertions 435 436* Atsign Braces Comma:: Inserting @@ and @{@} and ,. 437* Inserting Space:: How to insert the right amount of space 438 within a sentence. 439* Inserting Accents:: How to insert accents and special characters. 440* Dots Bullets:: How to insert dots and bullets. 441* TeX and copyright:: How to insert the @TeX{} logo 442 and the copyright symbol. 443* euro:: How to insert the Euro currency symbol. 444* pounds:: How to insert the pounds currency symbol. 445* minus:: How to insert a minus sign. 446* math:: How to format a mathematical expression. 447* Glyphs:: How to indicate results of evaluation, 448 expansion of macros, errors, etc. 449 450Inserting @@ and @{@} and @comma{} 451 452* Inserting an Atsign:: 453* Inserting Braces:: 454* Inserting a Comma:: 455 456Inserting Space 457 458* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. 459* Ending a Sentence:: Sometimes it does. 460* Multiple Spaces:: Inserting multiple spaces. 461* dmn:: How to format a dimension. 462 463Inserting Ellipsis and Bullets 464 465* dots:: How to insert dots @dots{} 466* bullet:: How to insert a bullet. 467 468Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} 469 470* tex:: The @TeX{} logos. 471* copyright symbol:: The copyright symbol (c in a circle). 472* registered symbol:: The registered symbol (R in a circle). 473 474Glyphs for Examples 475 476* Glyphs Summary:: 477* result:: How to show the result of expression. 478* expansion:: How to indicate an expansion. 479* Print Glyph:: How to indicate printed output. 480* Error Glyph:: How to indicate an error message. 481* Equivalence:: How to indicate equivalence. 482* Point Glyph:: How to indicate the location of point. 483 484Glyphs Summary 485 486* result:: 487* expansion:: 488* Print Glyph:: 489* Error Glyph:: 490* Equivalence:: 491* Point Glyph:: 492 493Forcing and Preventing Breaks 494 495* Break Commands:: Summary of break-related commands. 496* Line Breaks:: Forcing line breaks. 497* - and hyphenation:: Helping @TeX{} with hyphenation points. 498* w:: Preventing unwanted line breaks in text. 499* tie:: Inserting an unbreakable but varying space. 500* sp:: Inserting blank lines. 501* page:: Forcing the start of a new page. 502* group:: Preventing unwanted page breaks. 503* need:: Another way to prevent unwanted page breaks. 504 505Definition Commands 506 507* Def Cmd Template:: Writing descriptions using definition commands. 508* Def Cmd Continuation Lines:: Continuing the heading over source lines. 509* Optional Arguments:: Handling optional and repeated arguments. 510* deffnx:: Group two or more `first' lines. 511* Def Cmds in Detail:: Reference for all the definition commands. 512* Def Cmd Conventions:: Conventions for writing definitions. 513* Sample Function Definition:: An example. 514 515The Definition Commands 516 517* Functions Commands:: Commands for functions and similar entities. 518* Variables Commands:: Commands for variables and similar entities. 519* Typed Functions:: Commands for functions in typed languages. 520* Typed Variables:: Commands for variables in typed languages. 521* Data Types:: The definition command for data types. 522* Abstract Objects:: Commands for object-oriented programming. 523 524Object-Oriented Programming 525 526* Variables: Object-Oriented Variables. 527* Methods: Object-Oriented Methods. 528 529Conditionally Visible Text 530 531* Conditional Commands:: Text for a given format. 532* Conditional Not Commands:: Text for any format other than a given one. 533* Raw Formatter Commands:: Using raw formatter commands. 534* set clear value:: Variable tests and substitutions. 535* Conditional Nesting:: Using conditionals inside conditionals. 536 537@code{@@set}, @code{@@clear}, and @code{@@value} 538 539* set value:: Expand a flag variable to a string. 540* ifset ifclear:: Format a region if a flag is set. 541* value Example:: An easy way to update edition information. 542 543Internationalization 544 545* documentlanguage:: Declaring the current language. 546* documentencoding:: Declaring the input encoding. 547 548Defining New Texinfo Commands 549 550* Defining Macros:: Defining and undefining new commands. 551* Invoking Macros:: Using a macro, once you've defined it. 552* Macro Details:: Limitations of Texinfo macros. 553* alias:: Command aliases. 554* definfoenclose:: Customized highlighting. 555 556Formatting and Printing Hardcopy 557 558* Use TeX:: Use @TeX{} to format for hardcopy. 559* Format with tex/texindex:: How to format with explicit shell commands. 560* Format with texi2dvi:: A simpler way to format. 561* Print with lpr:: How to print. 562* Within Emacs:: How to format and print from an Emacs shell. 563* Texinfo Mode Printing:: How to format and print in Texinfo mode. 564* Compile-Command:: How to print using Emacs's compile command. 565* Requirements Summary:: @TeX{} formatting requirements summary. 566* Preparing for TeX:: What to do before you use @TeX{}. 567* Overfull hboxes:: What are and what to do with overfull hboxes. 568* smallbook:: How to print small format books and manuals. 569* A4 Paper:: How to print on A4 or A5 paper. 570* pagesizes:: How to print with customized page sizes. 571* Cropmarks and Magnification:: How to print marks to indicate the size 572 of pages and how to print scaled up output. 573* PDF Output:: Portable Document Format output. 574* Obtaining TeX:: How to Obtain @TeX{}. 575 576Creating and Installing Info Files 577 578* Creating an Info File:: 579* Installing an Info File:: 580 581Creating an Info File 582 583* makeinfo advantages:: @code{makeinfo} provides better error checking. 584* Invoking makeinfo:: How to run @code{makeinfo} from a shell. 585* makeinfo options:: Specify fill-column and other options. 586* Pointer Validation:: How to check that pointers point somewhere. 587* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. 588* texinfo-format commands:: Two Info formatting commands written 589 in Emacs Lisp are an alternative 590 to @code{makeinfo}. 591* Batch Formatting:: How to format for Info in Emacs Batch mode. 592* Tag and Split Files:: How tagged and split files help Info 593 to run better. 594 595Installing an Info File 596 597* Directory File:: The top level menu for all Info files. 598* New Info File:: Listing a new Info file. 599* Other Info Directories:: How to specify Info files that are 600 located in other directories. 601* Installing Dir Entries:: How to specify what menu entry to add 602 to the Info directory. 603* Invoking install-info:: @code{install-info} options. 604 605Generating HTML 606 607* HTML Translation:: Details of the HTML output. 608* HTML Splitting:: How HTML output is split. 609* HTML CSS:: Influencing HTML output with Cascading Style Sheets. 610* HTML Xref:: Cross-references in HTML output. 611 612HTML Cross-references 613 614* Link Basics: HTML Xref Link Basics. 615* Node Expansion: HTML Xref Node Name Expansion. 616* Command Expansion: HTML Xref Command Expansion. 617* 8-bit Expansion: HTML Xref 8-bit Character Expansion. 618* Mismatch: HTML Xref Mismatch. 619 620@@-Command List 621 622* Command Syntax:: General syntax for varieties of @@-commands. 623 624Sample Texinfo Files 625 626* Short Sample Texinfo File:: 627* GNU Sample Texts:: 628* Verbatim Copying License:: 629* All-permissive Copying License:: 630 631Copying This Manual 632 633* GNU Free Documentation License:: License for copying this manual. 634 635Include Files 636 637* Using Include Files:: How to use the @code{@@include} command. 638* texinfo-multiple-files-update:: How to create and update nodes and 639 menus when using included files. 640* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. 641* Sample Include File:: A sample outer file with included files 642 within it; and a sample included file. 643* Include Files Evolution:: How use of the @code{@@include} command 644 has changed over time. 645 646Page Headings 647 648* Headings Introduced:: Conventions for using page headings. 649* Heading Format:: Standard page heading formats. 650* Heading Choice:: How to specify the type of page heading. 651* Custom Headings:: How to create your own headings and footings. 652 653Formatting Mistakes 654 655* makeinfo Preferred:: @code{makeinfo} finds errors. 656* Debugging with Info:: How to catch errors with Info formatting. 657* Debugging with TeX:: How to catch errors with @TeX{} formatting. 658* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. 659* Using occur:: How to list all lines containing a pattern. 660* Running Info-Validate:: How to find badly referenced nodes. 661 662Finding Badly Referenced Nodes 663 664* Using Info-validate:: How to run @code{Info-validate}. 665* Unsplit:: How to create an unsplit file. 666* Tagifying:: How to tagify a file. 667* Splitting:: How to split a file manually. 668 669Copying This Manual 670 671* GNU Free Documentation License:: License for copying this manual. 672 673@end detailmenu 674@end menu 675 676@c Reward readers for getting to the end of the menu :). 677@c Contributed by Arnold Robbins. 678@quotation 679Documentation is like sex: when it is good, it is very, very good; and 680when it is bad, it is better than nothing. 681---Dick Brandon 682@end quotation 683 684 685@node Copying Conditions 686@unnumbered Texinfo Copying Conditions 687@cindex Copying conditions 688@cindex Conditions for copying Texinfo 689 690The programs currently being distributed that relate to Texinfo include 691@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}. 692These programs are @dfn{free}; this means that everyone is free to use 693them and free to redistribute them on a free basis. The Texinfo-related 694programs are not in the public domain; they are copyrighted and there 695are restrictions on their distribution, but these restrictions are 696designed to permit everything that a good cooperating citizen would want 697to do. What is not allowed is to try to prevent others from further 698sharing any version of these programs that they might get from you. 699 700Specifically, we want to make sure that you have the right to give away 701copies of the programs that relate to Texinfo, that you receive source 702code or else can get it if you want it, that you can change these 703programs or use pieces of them in new free programs, and that you know 704you can do these things. 705 706To make sure that everyone has such rights, we have to forbid you to 707deprive anyone else of these rights. For example, if you distribute 708copies of the Texinfo related programs, you must give the recipients all 709the rights that you have. You must make sure that they, too, receive or 710can get the source code. And you must tell them their rights. 711 712Also, for our own protection, we must make certain that everyone finds 713out that there is no warranty for the programs that relate to Texinfo. 714If these programs are modified by someone else and passed on, we want 715their recipients to know that what they have is not what we distributed, 716so that any problems introduced by others will not reflect on our 717reputation. 718 719The precise conditions of the licenses for the programs currently being 720distributed that relate to Texinfo are found in the General Public 721Licenses that accompany them. This manual specifically is covered by 722the GNU Free Documentation License (@pxref{GNU Free Documentation 723License}). 724 725 726@node Overview 727@chapter Overview of Texinfo 728@cindex Overview of Texinfo 729@cindex Texinfo overview 730 731@dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced 732like ``speck'', not ``hex''. This odd pronunciation is derived from, 733but is not the same as, the pronunciation of @TeX{}. In the word 734@TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than 735the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the 736last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x} 737were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other 738letters in lower case.} is a documentation system that uses a single 739source file to produce both online information and printed output. This 740means that instead of writing two different documents, one for the 741online information and the other for a printed work, you need write only 742one document. Therefore, when the work is revised, you need revise only 743that one document. 744 745@menu 746* Reporting Bugs:: Submitting effective bug reports. 747* Using Texinfo:: Create printed or online output. 748* Output Formats:: Overview of the supported output formats. 749* Info Files:: What is an Info file? 750* Printed Books:: Characteristics of a printed book or manual. 751* Formatting Commands:: @@-commands are used for formatting. 752* Conventions:: General rules for writing a Texinfo file. 753* Comments:: Writing comments and ignored text in general. 754* Minimum:: What a Texinfo file must have. 755* Six Parts:: Usually, a Texinfo file has six parts. 756* Short Sample:: A short sample Texinfo file. 757* History:: Acknowledgements, contributors and genesis. 758@end menu 759 760 761@node Reporting Bugs 762@section Reporting Bugs 763 764@cindex Bugs, reporting 765@cindex Suggestions for Texinfo, making 766@cindex Reporting bugs 767We welcome bug reports and suggestions for any aspect of the Texinfo system, 768programs, documentation, installation, anything. Please email them to 769@email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo 770from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide. 771 772@cindex Checklist for bug reports 773For bug reports, please include enough information for the maintainers 774to reproduce the problem. Generally speaking, that means: 775 776@itemize @bullet 777@item the version number of Texinfo and the program(s) or manual(s) involved. 778@item hardware and operating system names and versions. 779@item the contents of any input files necessary to reproduce the bug. 780@item a description of the problem and samples of any erroneous output. 781@item any unusual options you gave to @command{configure}. 782@item anything else that you think would be helpful. 783@end itemize 784 785When in doubt whether something is needed or not, include it. It's 786better to include too much than to leave out something important. 787 788@cindex Patches, contributing 789Patches are most welcome; if possible, please make them with 790@samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging 791Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,, 792emacs, The GNU Emacs Manual}). 793 794When sending patches, if possible please do not encode or split them in 795any way; it's much easier to deal with one plain text message, however 796large, than many small ones. @uref{ftp://ftp.gnu.org/gnu/sharutils/, 797GNU shar} is a convenient way of packaging multiple and/or binary files 798for email. 799 800 801@node Using Texinfo 802@section Using Texinfo 803 804@cindex Using Texinfo in general 805@cindex Texinfo, introduction to 806@cindex Introduction to Texinfo 807 808Using Texinfo, you can create a printed document (via the @TeX{} 809typesetting system) the normal features of a book, including chapters, 810sections, cross references, and indices. From the same Texinfo source 811file, you can create an Info file with special features to make 812documentation browsing easy. You can also create from that same 813source file an HTML output file suitable for use with a web browser, 814or an XML file. See the next section (@pxref{Output Formats}) for 815details and the exact commands to generate output from the source. 816 817@TeX{} works with virtually all printers; Info works with virtually all 818computer terminals; the HTML output works with virtually all web 819browsers. Thus Texinfo can be used by almost any computer user. 820 821@cindex Source file format 822A Texinfo source file is a plain @sc{ascii} file containing text 823interspersed with @dfn{@@-commands} (words preceded by an @samp{@@}) 824that tell the typesetting and formatting programs what to do. You can 825edit a Texinfo file with any text editor, but it is especially 826convenient to use GNU Emacs since that editor has a special mode, 827called Texinfo mode, that provides various Texinfo-related features. 828(@xref{Texinfo Mode}.) 829 830You can use Texinfo to create both online help and printed manuals; 831moreover, Texinfo is freely redistributable. For these reasons, Texinfo 832is the official documentation format of the GNU project. More 833information is available at the @uref{http://www.gnu.org/doc/, GNU 834documentation web page}. 835 836 837@node Output Formats 838@section Output Formats 839@cindex Output formats 840@cindex Back-end output formats 841 842Here is a brief overview of the output formats currently supported by 843Texinfo. 844 845@table @asis 846@item Info 847@cindex Info output 848(Generated via @command{makeinfo}.) This format is essentially a 849plain text transliteration of the Texinfo source. It adds a few 850control characters to separate nodes and provide navigational 851information for menus, cross-references, indices, and so on. See the 852next section (@pxref{Info Files}) for more details on this format. 853The Emacs Info subsystem (@pxref{Top,,Getting Started,info, Info}), 854and the standalone @command{info} program (@pxref{Top 855,, Info Standalone, info-stnd, GNU Info}), among others, can read these 856files. @xref{Creating and Installing Info Files}. 857 858@item Plain text 859@cindex Plain text output 860(Generated via @command{makeinfo --no-headers}.) This is almost the 861same as Info output, except the navigational control characters are 862omitted. Also, standard output is used by default. 863 864@item HTML 865@cindex HTML output 866@cindex W3 consortium 867@cindex Mozilla 868@cindex Lynx 869@cindex Emacs-W3 870(Generated via @command{makeinfo --html}.) This is the Hyper Text 871Markup Language that has become the most commonly used language for 872writing documents on the World Wide Web. Web browsers, such as 873Mozilla, Lynx, and Emacs-W3, can render this language online. There 874are many versions of HTML; @command{makeinfo} tries to use a subset 875of the language that can be interpreted by any common browser. For 876details of the HTML language and much related information, see 877@uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}. 878 879@item DVI 880@cindex DVI output 881@pindex dvips 882@pindex xdvi 883(Generated via @command{texi2dvi}.) This DeVice Independent binary 884format is output by the @TeX{} typesetting program 885(@uref{http://tug.org}). This is then read by a DVI `driver', which 886writes the actual device-specific commands that can be viewed or 887printed, notably Dvips for translation to PostScript (@pxref{Invoking 888Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display 889(@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}. 890 891Be aware that the Texinfo language is very different from and much 892stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}. 893For more information on @TeX{} in general, please see the book 894@cite{@TeX{} for the Impatient}, available from 895@uref{http://savannah.gnu.org/projects/teximpatient}. 896 897@item PDF 898@cindex PDF output 899@cindex Beebe, Nelson 900@pindex pdftex 901(Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This 902was developed by Adobe Systems for portable document interchange, 903based on their previous PostScript language. It can represent the exact 904appearance of a document, including fonts, and supporting arbitrary 905scaling. It is intended to be platform-independent and easily 906viewable, among other design goals; for a discussion, see 907@uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebeI.pdf}. Texinfo 908uses the @command{pdftex} program, a variant of @TeX{}, to output PDF; 909see @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}. 910 911@item XML 912@cindex XML output 913@cindex DTD, for Texinfo XML 914@pindex texinfo.dtd 915(Generated via @command{makeinfo --xml}.) XML is a generic syntax 916specification usable for any sort of content (see, for example, 917@uref{http://www.w3.org/XML/}). The @command{makeinfo} xml output, 918unlike all the formats above, interprets very little of the Texinfo 919source. Rather, it merely translates the Texinfo markup commands into 920XML syntax, for processing by further XML tools. The particular 921syntax output is defined in the file @file{texinfo.dtd} included in 922the Texinfo source distribution. 923 924@item Docbook 925@cindex Docbook output 926(Generated via @command{makeinfo --docbook}.) This is an XML-based 927format developed some years ago, primarily for technical 928documentation. It therefore bears some resemblance, in broad 929outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want 930to convert from Docbook @emph{to} Texinfo, please see 931@uref{http://docbook2X.sourceforge.net}. 932 933@end table 934 935@cindex Man page output, not supported 936From time to time, proposals are made to generate traditional Unix man 937pages from Texinfo source. However, because man pages have a very 938strict conventional format, generating a good man page requires a 939completely different source than the typical Texinfo applications of 940writing a good user tutorial and/or a good reference manual. This 941makes generating man pages incompatible with the Texinfo design goal 942of not having to document the same information in different ways for 943different output formats. You might as well just write the man page 944directly. 945 946@pindex help2man 947@cindex O'Dea, Brendan 948Man pages still have their place, and if you wish to support them, you 949may find the program @command{help2man} to be useful; it generates a 950traditional man page from the @samp{--help} output of a program. In 951fact, this is currently used to generate man pages for the programs in 952the Texinfo distribution. It is GNU software written by Brendan 953O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}. 954 955@cindex Output formats, supporting more 956@cindex SGML-tools output format 957If you are a programmer and would like to contribute to the GNU project 958by implementing additional output formats for Texinfo, that would be 959excellent. But please do not write a separate translator texi2foo for 960your favorite format foo! That is the hard way to do the job, and makes 961extra work in subsequent maintenance, since the Texinfo language is 962continually being enhanced and updated. Instead, the best approach is 963modify @code{makeinfo} to generate the new format. 964 965 966@node Info Files 967@section Info Files 968@cindex Info files 969 970An Info file is a Texinfo file formatted so that the Info documentation 971reading program can operate on it. (@code{makeinfo} 972and @code{texinfo-format-buffer} are two commands that convert a Texinfo file 973into an Info file.) 974 975Info files are divided into pieces called @dfn{nodes}, each of which 976contains the discussion of one topic. Each node has a name, and 977contains both text for the user to read and pointers to other nodes, 978which are identified by their names. The Info program displays one node 979at a time, and provides commands with which the user can move to other 980related nodes. 981 982@xref{Top,,, info, GNU Info}, for more information about using Info. 983 984Each node of an Info file may have any number of child nodes that 985describe subtopics of the node's topic. The names of child 986nodes are listed in a @dfn{menu} within the parent node; this 987allows you to use certain Info commands to move to one of the child 988nodes. Generally, an Info file is organized like a book. If a node 989is at the logical level of a chapter, its child nodes are at the level 990of sections; likewise, the child nodes of sections are at the level 991of subsections. 992 993All the children of any one parent are linked together in a 994bidirectional chain of `Next' and `Previous' pointers. The `Next' 995pointer provides a link to the next section, and the `Previous' pointer 996provides a link to the previous section. This means that all the nodes 997that are at the level of sections within a chapter are linked together. 998Normally the order in this chain is the same as the order of the 999children in the parent's menu. Each child node records the parent node 1000name as its `Up' pointer. The last child has no `Next' pointer, and the 1001first child has the parent both as its `Previous' and as its `Up' 1002pointer.@footnote{In some documents, the first child has no `Previous' 1003pointer. Occasionally, the last child has the node name of the next 1004following higher level node as its `Next' pointer.} 1005 1006The book-like structuring of an Info file into nodes that correspond 1007to chapters, sections, and the like is a matter of convention, not a 1008requirement. The `Up', `Previous', and `Next' pointers of a node can 1009point to any other nodes, and a menu can contain any other nodes. 1010Thus, the node structure can be any directed graph. But it is usually 1011more comprehensible to follow a structure that corresponds to the 1012structure of chapters and sections in a printed book or report.@refill 1013 1014In addition to menus and to `Next', `Previous', and `Up' pointers, Info 1015provides pointers of another kind, called references, that can be 1016sprinkled throughout the text. This is usually the best way to 1017represent links that do not fit a hierarchical structure.@refill 1018 1019Usually, you will design a document so that its nodes match the 1020structure of chapters and sections in the printed output. But 1021occasionally there are times when this is not right for the material 1022being discussed. Therefore, Texinfo uses separate commands to specify 1023the node structure for the Info file and the section structure for the 1024printed output.@refill 1025 1026Generally, you enter an Info file through a node that by convention is 1027named `Top'. This node normally contains just a brief summary of the 1028file's purpose, and a large menu through which the rest of the file is 1029reached. From this node, you can either traverse the file 1030systematically by going from node to node, or you can go to a specific 1031node listed in the main menu, or you can search the index menus and then 1032go directly to the node that has the information you want. Alternatively, 1033with the standalone Info program, you can specify specific menu items on 1034the command line (@pxref{Top,,, info, Info}). 1035 1036If you want to read through an Info file in sequence, as if it were a 1037printed manual, you can hit @key{SPC} repeatedly, or you get the whole 1038file with the advanced Info command @kbd{g *}. (@inforef{Advanced, 1039Advanced Info commands, info}.)@refill 1040 1041@c !!! dir file may be located in one of many places: 1042@c /usr/local/emacs/info mentioned in info.c DEFAULT_INFOPATH 1043@c /usr/local/lib/emacs/info mentioned in info.c DEFAULT_INFOPATH 1044@c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH 1045@c /usr/local/info 1046@c /usr/local/lib/info 1047The @file{dir} file in the @file{info} directory serves as the 1048departure point for the whole Info system. From it, you can reach the 1049`Top' nodes of each of the documents in a complete Info system.@refill 1050 1051@cindex URI syntax for Info 1052If you wish to refer to an Info file in a URI, you can use the 1053(unofficial) syntax exemplified in the following. This works with 1054Emacs/W3, for example: 1055@example 1056info:///usr/info/emacs#Dissociated%20Press 1057info:emacs#Dissociated%20Press 1058info://localhost/usr/info/emacs#Dissociated%20Press 1059@end example 1060 1061The @command{info} program itself does not follow URI's of any kind. 1062 1063 1064@node Printed Books 1065@section Printed Books 1066@cindex Printed book and manual characteristics 1067@cindex Manual characteristics, printed 1068@cindex Book characteristics, printed 1069@cindex Texinfo printed book characteristics 1070@cindex Characteristics, printed books or manuals 1071 1072@cindex Knuth, Donald 1073A Texinfo file can be formatted and typeset as a printed book or manual. 1074To do this, you need @TeX{}, a powerful, sophisticated typesetting 1075program written by Donald Knuth.@footnote{You can also use the 1076@pindex texi2roff@r{, unsupported software} 1077@uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you 1078do not have @TeX{}; since Texinfo is designed for use with @TeX{}, 1079@code{texi2roff} is not described here. @code{texi2roff} is not part of 1080the standard GNU distribution and is not maintained or up-to-date with 1081all the Texinfo features described in this manual.} 1082 1083A Texinfo-based book is similar to any other typeset, printed work: it 1084can have a title page, copyright page, table of contents, and preface, 1085as well as chapters, numbered or unnumbered sections and subsections, 1086page headers, cross references, footnotes, and indices.@refill 1087 1088You can use Texinfo to write a book without ever having the intention 1089of converting it into online information. You can use Texinfo for 1090writing a printed novel, and even to write a printed memo, although 1091this latter application is not recommended since electronic mail is so 1092much easier.@refill 1093 1094@TeX{} is a general purpose typesetting program. Texinfo provides a 1095file @file{texinfo.tex} that contains information (definitions or 1096@dfn{macros}) that @TeX{} uses when it typesets a Texinfo file. 1097(@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands 1098to @TeX{} commands, which @TeX{} can then process to create the typeset 1099document.) @file{texinfo.tex} contains the specifications for printing 1100a document. You can get the latest version of @file{texinfo.tex} from 1101@uref{ftp://ftp.gnu.org/gnu/texinfo/texinfo.tex}. 1102 1103In the United States, documents are most often printed on 8.5 inch by 11 1104inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But 1105you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by 1106235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper 1107(@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, , 1108Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4 1109Paper}.) 1110 1111By changing the parameters in @file{texinfo.tex}, you can change the 1112size of the printed document. In addition, you can change the style in 1113which the printed document is formatted; for example, you can change the 1114sizes and fonts used, the amount of indentation for each paragraph, the 1115degree to which words are hyphenated, and the like. By changing the 1116specifications, you can make a book look dignified, old and serious, or 1117light-hearted, young and cheery. 1118 1119@TeX{} is freely distributable. It is written in a superset of Pascal 1120called WEB and can be compiled either in Pascal or (by using a 1121conversion program that comes with the @TeX{} distribution) in C. 1122(@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information 1123about @TeX{}.)@refill 1124 1125@TeX{} is very powerful and has a great many features. Because a 1126Texinfo file must be able to present information both on a 1127character-only terminal in Info form and in a typeset book, the 1128formatting commands that Texinfo supports are necessarily limited. 1129 1130To get a copy of @TeX{}, see 1131@ref{Obtaining TeX, , How to Obtain @TeX{}}. 1132 1133 1134@node Formatting Commands 1135@section @@-commands 1136@cindex @@-commands 1137@cindex Formatting commands 1138 1139In a Texinfo file, the commands that tell @TeX{} how to typeset the 1140printed manual and tell @code{makeinfo} and 1141@code{texinfo-format-buffer} how to create an Info file are preceded 1142by @samp{@@}; they are called @dfn{@@-commands}. For example, 1143@code{@@node} is the command to indicate a node and @code{@@chapter} 1144is the command to indicate the start of a chapter.@refill 1145 1146@quotation Note 1147Almost all @@ command names are entirely lower case. 1148@end quotation 1149 1150The Texinfo @@-commands are a strictly limited set of constructs. The 1151strict limits make it possible for Texinfo files to be understood both 1152by @TeX{} and by the code that converts them into Info files. You can 1153display Info files on any terminal that displays alphabetic and 1154numeric characters. Similarly, you can print the output generated by 1155@TeX{} on a wide variety of printers.@refill 1156 1157Depending on what they do or what arguments@footnote{The word 1158@dfn{argument} comes from the way it is used in mathematics and does not 1159refer to a dispute between two people; it refers to the information 1160presented to the command. According to the @cite{Oxford English 1161Dictionary}, the word derives from the Latin for @dfn{to make clear, 1162prove}; thus it came to mean `the evidence offered as proof', which is 1163to say, `the information offered', which led to its mathematical 1164meaning. In its other thread of derivation, the word came to mean `to 1165assert in a manner against which others may make counter assertions', 1166which led to the meaning of `argument' as a dispute.} they take, you 1167need to write @@-commands on lines of their own or as part of 1168sentences: 1169 1170@itemize @bullet 1171@item 1172Write a command such as @code{@@quotation} at the beginning of a line as 1173the only text on the line. (@code{@@quotation} begins an indented 1174environment.) 1175 1176@item 1177Write a command such as @code{@@chapter} at the beginning of a line 1178followed by the command's arguments, in this case the chapter title, on 1179the rest of the line. (@code{@@chapter} creates chapter titles.)@refill 1180 1181@item 1182Write a command such as @code{@@dots@{@}} wherever you wish but usually 1183within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill 1184 1185@item 1186Write a command such as @code{@@code@{@var{sample-code}@}} wherever you 1187wish (but usually within a sentence) with its argument, 1188@var{sample-code} in this example, between the braces. (@code{@@code} 1189marks text as being code.)@refill 1190 1191@item 1192Write a command such as @code{@@example} on a line of its own; write the 1193body-text on following lines; and write the matching @code{@@end} 1194command, @code{@@end example} in this case, on a line of its own 1195after the body-text. (@code{@@example} @dots{} @code{@@end example} 1196indents and typesets body-text as an example.) It's usually ok to 1197indent environment commands like this, but in complicated and 1198hard-to-define circumstances the extra spaces cause extra space to 1199appear in the output, so beware. 1200@end itemize 1201 1202@noindent 1203@cindex Braces, when to use 1204As a general rule, a command requires braces if it mingles among other 1205text; but it does not need braces if it starts a line of its own. The 1206non-alphabetic commands, such as @code{@@:}, are exceptions to the rule; 1207they do not need braces.@refill 1208 1209As you gain experience with Texinfo, you will rapidly learn how to 1210write the different commands: the different ways to write commands 1211actually make it easier to write and read Texinfo files than if all 1212commands followed exactly the same syntax. @xref{Command Syntax, , 1213@@-Command Syntax}, for all the details. 1214 1215 1216@node Conventions 1217@section General Syntactic Conventions 1218@cindex General syntactic conventions 1219@cindex Syntactic conventions 1220@cindex Conventions, syntactic 1221@cindex Characters, basic input 1222 1223This section describes the general conventions used in all Texinfo documents. 1224 1225@itemize @bullet 1226@item 1227@cindex Source files, characters used 1228All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and 1229@samp{@}} can appear in a Texinfo file and stand for themselves. 1230@samp{@@} is the escape character which introduces commands, while 1231@samp{@{} and @samp{@}} are used to surround arguments to certain 1232commands. To put one of these special characters into the document, put 1233an @samp{@@} character in front of it, like this: @samp{@@@@}, 1234@samp{@@@{}, and @samp{@@@}}. 1235 1236@item 1237@cindex Paragraph separator 1238@cindex Blank lines, as paragraph separator 1239@cindex Newlines, as blank lines 1240Separate paragraphs with one or more blank lines. Currently Texinfo 1241only recognizes newline characters as end of line, not the CRLF 1242sequence used on some systems; so a @dfn{blank line} means exactly two 1243consecutive newlines. Sometimes blank lines are useful or convenient 1244in other cases as well; you can use the @code{@@noindent} to inhibit 1245paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}). 1246 1247@item 1248@cindex Quotation characters (`'), in source 1249Use doubled single-quote characters to begin and end quotations: 1250@w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to 1251left- and right-hand doubled quotation marks, 1252@c this comes out as "like this" in Info, which is just confusing. 1253@iftex 1254``like this'', 1255@end iftex 1256and Info converts doubled single-quote characters to @sc{ascii} 1257double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}. 1258 1259You may occasionally need to produce two consecutive single quotes; 1260for example, in documenting a computer language such as Maxima where 1261@t{'@w{}'} is a valid command. You can do this with the input 1262@t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into 1263the double-quote characters. 1264 1265@cindex Unicode quotation characters 1266@cindex Grave accent, vs.@: left quote 1267The left quote character (@t{`}, ASCII code 96) used in Texinfo is a 1268grave accent in ANSI and ISO character set standards. We use it as a 1269quote character because that is how @TeX{} is set up, by default. We 1270hope to eventually support the various quotation characters in 1271Unicode. 1272 1273@item 1274@cindex Multiple dashes in source 1275@cindex Dashes in source 1276@cindex Hyphens in source, two or three in a row 1277@cindex Em dash, producing 1278@cindex En dash, producing 1279Use three hyphens in a row, @samp{---}, to produce a long dash---like 1280this (called an @dfn{em dash}), used for punctuation in sentences. 1281Use two hyphens, @samp{--}, to produce a medium dash (called an 1282@dfn{en dash}), used primarily for numeric ranges, as in ``June 128325--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen 1284used in compound words. For display on the screen, Info reduces three 1285hyphens to two and two hyphens to one (not transitively!). Of course, 1286any number of hyphens in the source remain as they are in literal 1287contexts, such as @code{@@code} and @code{@@example}. 1288 1289@item 1290@cindex Tabs; don't use! 1291@strong{Caution:} Last and most important, do not use tab characters 1292in a Texinfo file (except in verbatim modes)! @TeX{} uses 1293variable-width fonts, which means that it is impractical at best to 1294define a tab to work in all circumstances. Consequently, @TeX{} 1295treats tabs like single spaces, and that is not what they look like in 1296the source. Furthermore, @code{makeinfo} does nothing special with 1297tabs, and thus a tab character in your input file will usually appear 1298differently in the output. 1299 1300@noindent 1301To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple 1302spaces when you press the @key{TAB} key. 1303 1304@noindent 1305Also, you can run @code{untabify} in Emacs to convert tabs in a region 1306to multiple spaces, or use the @code{unexpand} command from the shell. 1307 1308@end itemize 1309 1310@node Comments 1311@section Comments 1312 1313@cindex Comments 1314@findex comment 1315@findex c @r{(comment)} 1316 1317You can write comments in a Texinfo file that will not appear in 1318either the Info file or the printed manual by using the 1319@code{@@comment} command (which may be abbreviated to @code{@@c}). 1320Such comments are for the person who revises the Texinfo file. All the 1321text on a line that follows either @code{@@comment} or @code{@@c} is a 1322comment; the rest of the line does not appear in either the Info file 1323or the printed manual. 1324 1325Often, you can write the @code{@@comment} or @code{@@c} in the middle of 1326a line, and only the text that follows after the @code{@@comment} or 1327@code{@@c} command does not appear; but some commands, such as 1328@code{@@settitle} and @code{@@setfilename}, work on a whole line. You 1329cannot use @code{@@comment} or @code{@@c} in a line beginning with such 1330a command. 1331 1332@cindex Ignored text 1333@cindex Unprocessed text 1334@findex ignore 1335You can write long stretches of text that will not appear in either 1336the Info file or the printed manual by using the @code{@@ignore} and 1337@code{@@end ignore} commands. Write each of these commands on a line 1338of its own, starting each command at the beginning of the line. Text 1339between these two commands does not appear in the processed output. 1340You can use @code{@@ignore} and @code{@@end ignore} for writing 1341comments. 1342 1343Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or 1344@code{@@ifclear} conditions is ignored in the sense that it will not 1345contribute to the formatted output. However, @TeX{} and makeinfo must 1346still parse the ignored text, in order to understand when to @emph{stop} 1347ignoring text from the source file; that means that you may still get 1348error messages if you have invalid Texinfo commands within ignored text. 1349 1350 1351@node Minimum 1352@section What a Texinfo File Must Have 1353@cindex Minimal Texinfo file (requirements) 1354@cindex Must have in Texinfo file 1355@cindex Required in Texinfo file 1356@cindex Texinfo file minimum 1357 1358By convention, the namea of a Texinfo file ends with (in order of 1359preference) one of the extensions @file{.texinfo}, @file{.texi}, 1360@file{.txi}, or @file{.tex}. The longer extensions are preferred since 1361they describe more clearly to a human reader the nature of the file. 1362The shorter extensions are for operating systems that cannot handle long 1363file names. 1364 1365In order to be made into a printed manual and an Info file, a Texinfo 1366file @strong{must} begin with lines like this: 1367 1368@example 1369@group 1370\input texinfo 1371@@setfilename @var{info-file-name} 1372@@settitle @var{name-of-manual} 1373@end group 1374@end example 1375 1376@noindent 1377The contents of the file follow this beginning, and then you 1378@strong{must} end a Texinfo file with a line like this: 1379 1380@example 1381@@bye 1382@end example 1383 1384@findex \input @r{(raw @TeX{} startup)} 1385@noindent 1386Here's an explanation: 1387 1388@itemize @bullet 1389@item 1390The @samp{\input texinfo} line tells @TeX{} to use the 1391@file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo 1392@@-commands into @TeX{} typesetting commands. (Note the use of the 1393backslash, @samp{\}; this is correct for @TeX{}.) 1394 1395@item 1396The @code{@@setfilename} line provides a name for the Info file and 1397tells @TeX{} to open auxiliary files. @strong{All text before 1398@code{@@setfilename} is ignored!} 1399 1400@item 1401The @code{@@settitle} line specifies a title for the page headers (or 1402footers) of the printed manual, and the default document description for 1403the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle} 1404is optional---if you don't mind your document being titled `Untitled'. 1405 1406@item 1407The @code{@@bye} line at the end of the file on a line of its own tells 1408the formatters that the file is ended and to stop formatting. 1409 1410@end itemize 1411 1412Typically, you will not use quite such a spare format, but will include 1413mode setting and start-of-header and end-of-header lines at the 1414beginning of a Texinfo file, like this: 1415 1416@example 1417@group 1418\input texinfo @@c -*-texinfo-*- 1419@@c %**start of header 1420@@setfilename @var{info-file-name} 1421@@settitle @var{name-of-manual} 1422@@c %**end of header 1423@end group 1424@end example 1425 1426@noindent 1427In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into 1428Texinfo mode when you edit the file. 1429 1430The @code{@@c} lines which surround the @code{@@setfilename} and 1431@code{@@settitle} lines are optional, but you need them in order to 1432run @TeX{} or Info on just part of the file. (@xref{Start of Header}.) 1433 1434Furthermore, you will usually provide a Texinfo file with a title page, 1435indices, and the like, all of which are explained in this manual. But 1436the minimum, which can be useful for short documents, is just the three 1437lines at the beginning and the one line at the end. 1438 1439 1440@node Six Parts 1441@section Six Parts of a Texinfo File 1442 1443Generally, a Texinfo file contains more than the minimal beginning and 1444end described in the previous section---it usually contains the six 1445parts listed below. These are described fully in the following sections. 1446 1447@table @r 1448@item 1. Header 1449The @dfn{Header} names the file, tells @TeX{} which definitions file to 1450use, and other such housekeeping tasks. 1451 1452@item 2. Summary and Copyright 1453The @dfn{Summary and Copyright} segment describes the document and 1454contains the copyright notice and copying permissions. This is done 1455with the @code{@@copying} command. 1456 1457@item 3. Title and Copyright 1458The @dfn{Title and Copyright} segment contains the title and copyright 1459pages for the printed manual. The segment must be enclosed between 1460@code{@@titlepage} and @code{@@end titlepage} commands. The title and 1461copyright page appear only in the printed manual. 1462 1463@item 4. `Top' Node and Master Menu 1464The `Top' node starts off the online output; it does not appear in the 1465printed manual. We recommend including the copying permissions here as 1466well as the segments above. And it contains at least a top-level menu 1467listing the chapters, and possibly a @dfn{Master Menu} listing all the 1468nodes in the entire document. 1469 1470@item 5. Body 1471The @dfn{Body} of the document is typically structured like a 1472traditional book or encyclopedia, but it may be free form. 1473 1474@item 6. End 1475The @dfn{End} segment contains commands for printing indices and 1476generating the table of contents, and the @code{@@bye} command on a line 1477of its own. 1478@end table 1479 1480 1481@node Short Sample 1482@section A Short Sample Texinfo File 1483@cindex Sample Texinfo file, with comments 1484 1485Here is a very short but complete Texinfo file, in the six conventional 1486parts enumerated in the previous section, so you can see how Texinfo 1487source appears in practice. The first three parts of the file, from 1488@samp{\input texinfo} through to @samp{@@end titlepage}, look more 1489intimidating than they are: most of the material is standard 1490boilerplate; when writing a manual, you simply change the names as 1491appropriate. 1492 1493@xref{Beginning a File}, for full documentation on the commands listed 1494here. @xref{GNU Sample Texts}, for the full texts to be used in GNU 1495manuals. 1496 1497In the following, the sample text is @emph{indented}; comments on it are 1498not. The complete file, without interspersed comments, is shown in 1499@ref{Short Sample Texinfo File}. 1500 1501@subheading Part 1: Header 1502 1503@noindent 1504The header does not appear in either the Info file or the 1505printed output. It sets various parameters, including the 1506name of the Info file and the title used in the header. 1507 1508@example 1509@group 1510\input texinfo @@c -*-texinfo-*- 1511@@c %**start of header 1512@@setfilename sample.info 1513@@settitle Sample Manual 1.0 1514@@c %**end of header 1515@end group 1516@end example 1517 1518@subheading Part 2: Summary Description and Copyright 1519 1520@noindent 1521A real manual includes more text here, according to the license under 1522which it is distributed. @xref{GNU Sample Texts}. 1523 1524@example 1525@group 1526@@copying 1527This is a short example of a complete Texinfo file, version 1.0. 1528 1529Copyright @@copyright@{@} 2004 Free Software Foundation, Inc. 1530@@end copying 1531@end group 1532@end example 1533 1534@subheading Part 3: Titlepage, Contents, Copyright 1535 1536@noindent 1537The titlepage segment does not appear in the online output, only in the 1538printed manual. We use the @code{@@insertcopying} command to 1539include the permission text from the previous section, instead of 1540writing it out again; it is output on the back of the title page. The 1541@code{@@contents} command generates a table of contents. 1542 1543@example 1544@group 1545@@titlepage 1546@@title Sample Title 1547@end group 1548 1549@group 1550@@c The following two commands start the copyright page. 1551@@page 1552@@vskip 0pt plus 1filll 1553@@insertcopying 1554@@end titlepage 1555@end group 1556 1557@@c Output the table of contents at the beginning. 1558@@contents 1559@end example 1560 1561@subheading Part 4: `Top' Node and Master Menu 1562 1563@noindent 1564The `Top' node contains the master menu for the Info file. Since the 1565printed manual uses a table of contents rather than a menu, it 1566excludes the `Top' node. We also include the copying text again for 1567the benefit of online readers. Since the copying text begins with 1568a brief description of the manual, no other text is needed in this 1569case. The @samp{@@top} command itself helps @command{makeinfo} 1570determine the relationships between nodes. 1571 1572@example 1573@@ifnottex 1574@@node Top 1575@@top Short Sample 1576 1577@@insertcopying 1578@@end ifnottex 1579 1580@group 1581@@menu 1582* First Chapter:: The first chapter is the 1583 only chapter in this sample. 1584* Index:: Complete index. 1585@@end menu 1586@end group 1587@end example 1588 1589 1590@subheading Part 5: The Body of the Document 1591 1592@noindent 1593The body segment contains all the text of the document, but not the 1594indices or table of contents. This example illustrates a node and a 1595chapter containing an enumerated list. 1596 1597@example 1598@group 1599@@node First Chapter 1600@@chapter First Chapter 1601 1602@@cindex chapter, first 1603@end group 1604 1605@group 1606This is the first chapter. 1607@@cindex index entry, another 1608@end group 1609 1610@group 1611Here is a numbered list. 1612 1613@@enumerate 1614@@item 1615This is the first item. 1616 1617@@item 1618This is the second item. 1619@@end enumerate 1620@end group 1621@end example 1622 1623 1624@subheading Part 6: The End of the Document 1625 1626@noindent 1627The end segment contains commands for generating an index in a node and 1628unnumbered chapter of its own, and the @code{@@bye} command that marks 1629the end of the document. 1630 1631@example 1632@group 1633@@node Index 1634@@unnumbered Index 1635@end group 1636 1637@group 1638@@printindex cp 1639 1640@@bye 1641@end group 1642@end example 1643 1644 1645@subheading Some Results 1646 1647Here is what the contents of the first chapter of the sample look like: 1648 1649@sp 1 1650@need 700 1651@quotation 1652This is the first chapter. 1653 1654Here is a numbered list. 1655 1656@enumerate 1657@item 1658This is the first item. 1659 1660@item 1661This is the second item. 1662@end enumerate 1663@end quotation 1664 1665 1666@node History 1667@section History 1668 1669@cindex Stallman, Richard M. 1670@cindex Chassell, Robert J. 1671@cindex Fox, Brian 1672@cindex Berry, Karl 1673Richard M.@: Stallman invented the Texinfo format, wrote the initial 1674processors, and created Edition 1.0 of this manual. @w{Robert J.@:} 1675Chassell greatly revised and extended the manual, starting with Edition 16761.1. Brian Fox was responsible for the standalone Texinfo distribution 1677until version 3.8, and wrote the standalone @command{makeinfo} and 1678@command{info} programs. Karl Berry has continued maintenance since 1679Texinfo 3.8 (manual edition 2.22). 1680 1681@cindex Pinard, Fran@,{c}ois 1682@cindex Zuhn, David D. 1683@cindex Weisshaus, Melissa 1684@cindex Zaretskii, Eli 1685@cindex Schwab, Andreas 1686@cindex Weinberg, Zack 1687Our thanks go out to all who helped improve this work, particularly the 1688indefatigable Eli Zaretskii and Andreas Schwab, who have provided 1689patches beyond counting. Fran@,{c}ois Pinard and @w{David D.@: Zuhn}, 1690tirelessly recorded and reported mistakes and obscurities. Zack 1691Weinberg did the impossible by implementing the macro syntax in 1692@file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her 1693frequent reviews of nearly similar editions. Dozens of others have 1694contributed patches and suggestions, they are gratefully acknowledged in 1695the @file{ChangeLog} file. Our mistakes are our own. 1696 1697@cindex Scribe 1698@cindex Reid, Brian 1699@cindex History of Texinfo 1700@cindex Texinfo history 1701A bit of history: in the 1970's at CMU, Brian Reid developed a program 1702and format named Scribe to mark up documents for printing. It used the 1703@code{@@} character to introduce commands, as Texinfo does. Much more 1704consequentially, it strived to describe document contents rather than 1705formatting, an idea wholeheartedly adopted by Texinfo. 1706 1707@cindex Bolio 1708@cindex Bo@TeX{} 1709Meanwhile, people at MIT developed another, not too dissimilar format 1710called Bolio. This then was converted to using @TeX{} as its typesetting 1711language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been 17120.02 on October 31, 1984. 1713 1714Bo@TeX{} could only be used as a markup language for documents to be 1715printed, not for online documents. Richard Stallman (RMS) worked on 1716both Bolio and Bo@TeX{}. He also developed a nifty on-line help format 1717called Info, and then combined Bo@TeX{} and Info to create Texinfo, a 1718mark up language for text that is intended to be read both online and 1719as printed hard copy. 1720 1721 1722@node Texinfo Mode 1723@chapter Using Texinfo Mode 1724@cindex Texinfo mode 1725@cindex Mode, using Texinfo 1726@cindex GNU Emacs 1727@cindex Emacs 1728 1729You may edit a Texinfo file with any text editor you choose. A Texinfo 1730file is no different from any other @sc{ascii} file. However, GNU Emacs 1731comes with a special mode, called Texinfo mode, that provides Emacs 1732commands and tools to help ease your work. 1733 1734This chapter describes features of GNU Emacs' Texinfo mode but not any 1735features of the Texinfo formatting language. So if you are reading this 1736manual straight through from the beginning, you may want to skim through 1737this chapter briefly and come back to it after reading succeeding 1738chapters which describe the Texinfo formatting language in detail. 1739 1740@menu 1741* Texinfo Mode Overview:: How Texinfo mode can help you. 1742* Emacs Editing:: Texinfo mode adds to GNU Emacs' general 1743 purpose editing features. 1744* Inserting:: How to insert frequently used @@-commands. 1745* Showing the Structure:: How to show the structure of a file. 1746* Updating Nodes and Menus:: How to update or create new nodes and menus. 1747* Info Formatting:: How to format for Info. 1748* Printing:: How to format and print part or all of a file. 1749* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. 1750@end menu 1751 1752@node Texinfo Mode Overview 1753@section Texinfo Mode Overview 1754 1755Texinfo mode provides special features for working with Texinfo files. 1756You can: 1757 1758@itemize @bullet 1759@item 1760Insert frequently used @@-commands. @refill 1761 1762@item 1763Automatically create @code{@@node} lines. 1764 1765@item 1766Show the structure of a Texinfo source file.@refill 1767 1768@item 1769Automatically create or update the `Next', 1770`Previous', and `Up' pointers of a node. 1771 1772@item 1773Automatically create or update menus.@refill 1774 1775@item 1776Automatically create a master menu.@refill 1777 1778@item 1779Format a part or all of a file for Info.@refill 1780 1781@item 1782Typeset and print part or all of a file.@refill 1783@end itemize 1784 1785Perhaps the two most helpful features are those for inserting frequently 1786used @@-commands and for creating node pointers and menus.@refill 1787 1788@node Emacs Editing 1789@section The Usual GNU Emacs Editing Commands 1790 1791In most cases, the usual Text mode commands work the same in Texinfo 1792mode as they do in Text mode. Texinfo mode adds new editing commands 1793and tools to GNU Emacs' general purpose editing features. The major 1794difference concerns filling. In Texinfo mode, the paragraph 1795separation variable and syntax table are redefined so that Texinfo 1796commands that should be on lines of their own are not inadvertently 1797included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph}) 1798command will refill a paragraph but not mix an indexing command on a 1799line adjacent to it into the paragraph.@refill 1800 1801In addition, Texinfo mode sets the @code{page-delimiter} variable to 1802the value of @code{texinfo-chapter-level-regexp}; by default, this is 1803a regular expression matching the commands for chapters and their 1804equivalents, such as appendices. With this value for the page 1805delimiter, you can jump from chapter title to chapter title with the 1806@kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [} 1807(@code{backward-page}) commands and narrow to a chapter with the 1808@kbd{C-x p} (@code{narrow-to-page}) command. (@xref{Pages, , ,emacs, 1809The GNU Emacs Manual}, for details about the page commands.)@refill 1810 1811You may name a Texinfo file however you wish, but the convention is to 1812end a Texinfo file name with one of the extensions 1813@file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer 1814extension is preferred, since it is explicit, but a shorter extension 1815may be necessary for operating systems that limit the length of file 1816names. GNU Emacs automatically enters Texinfo mode when you visit a 1817file with a @file{.texinfo}, @file{.texi} or @file{.txi} 1818extension. Also, Emacs switches to Texinfo mode 1819when you visit a 1820file that has @samp{-*-texinfo-*-} in its first line. If ever you are 1821in another mode and wish to switch to Texinfo mode, type @code{M-x 1822texinfo-mode}.@refill 1823 1824Like all other Emacs features, you can customize or enhance Texinfo 1825mode as you wish. In particular, the keybindings are very easy to 1826change. The keybindings described here are the default or standard 1827ones.@refill 1828 1829@node Inserting 1830@comment node-name, next, previous, up 1831@section Inserting Frequently Used Commands 1832@cindex Inserting frequently used commands 1833@cindex Frequently used commands, inserting 1834@cindex Commands, inserting them 1835 1836Texinfo mode provides commands to insert various frequently used 1837@@-commands into the buffer. You can use these commands to save 1838keystrokes.@refill 1839 1840The insert commands are invoked by typing @kbd{C-c} twice and then the 1841first letter of the @@-command:@refill 1842 1843@table @kbd 1844@item C-c C-c c 1845@itemx M-x texinfo-insert-@@code 1846@findex texinfo-insert-@@code 1847Insert @code{@@code@{@}} and put the 1848cursor between the braces.@refill 1849 1850@item C-c C-c d 1851@itemx M-x texinfo-insert-@@dfn 1852@findex texinfo-insert-@@dfn 1853Insert @code{@@dfn@{@}} and put the 1854cursor between the braces.@refill 1855 1856@item C-c C-c e 1857@itemx M-x texinfo-insert-@@end 1858@findex texinfo-insert-@@end 1859Insert @code{@@end} and attempt to insert the correct following word, 1860such as @samp{example} or @samp{table}. (This command does not handle 1861nested lists correctly, but inserts the word appropriate to the 1862immediately preceding list.)@refill 1863 1864@item C-c C-c i 1865@itemx M-x texinfo-insert-@@item 1866@findex texinfo-insert-@@item 1867Insert @code{@@item} and put the 1868cursor at the beginning of the next line.@refill 1869 1870@item C-c C-c k 1871@itemx M-x texinfo-insert-@@kbd 1872@findex texinfo-insert-@@kbd 1873Insert @code{@@kbd@{@}} and put the 1874cursor between the braces.@refill 1875 1876@item C-c C-c n 1877@itemx M-x texinfo-insert-@@node 1878@findex texinfo-insert-@@node 1879Insert @code{@@node} and a comment line 1880listing the sequence for the `Next', 1881`Previous', and `Up' nodes. 1882Leave point after the @code{@@node}.@refill 1883 1884@item C-c C-c o 1885@itemx M-x texinfo-insert-@@noindent 1886@findex texinfo-insert-@@noindent 1887Insert @code{@@noindent} and put the 1888cursor at the beginning of the next line.@refill 1889 1890@item C-c C-c s 1891@itemx M-x texinfo-insert-@@samp 1892@findex texinfo-insert-@@samp 1893Insert @code{@@samp@{@}} and put the 1894cursor between the braces.@refill 1895 1896@item C-c C-c t 1897@itemx M-x texinfo-insert-@@table 1898@findex texinfo-insert-@@table 1899Insert @code{@@table} followed by a @key{SPC} 1900and leave the cursor after the @key{SPC}.@refill 1901 1902@item C-c C-c v 1903@itemx M-x texinfo-insert-@@var 1904@findex texinfo-insert-@@var 1905Insert @code{@@var@{@}} and put the 1906cursor between the braces.@refill 1907 1908@item C-c C-c x 1909@itemx M-x texinfo-insert-@@example 1910@findex texinfo-insert-@@example 1911Insert @code{@@example} and put the 1912cursor at the beginning of the next line.@refill 1913 1914@c M-@{ was the binding for texinfo-insert-braces; 1915@c in Emacs 19, backward-paragraph will take this binding. 1916@item C-c C-c @{ 1917@itemx M-x texinfo-insert-braces 1918@findex texinfo-insert-braces 1919Insert @code{@{@}} and put the cursor between the braces.@refill 1920 1921@item C-c C-c @} 1922@itemx C-c C-c ] 1923@itemx M-x up-list 1924@findex up-list 1925Move from between a pair of braces forward past the closing brace. 1926Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which 1927is, however, more mnemonic; hence the two keybindings. (Also, you can 1928move out from between braces by typing @kbd{C-f}.)@refill 1929@end table 1930 1931To put a command such as @w{@code{@@code@{@dots{}@}}} around an 1932@emph{existing} word, position the cursor in front of the word and type 1933@kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text. 1934The value of the prefix argument tells Emacs how many words following 1935point to include between braces---@samp{1} for one word, @samp{2} for 1936two words, and so on. Use a negative argument to enclose the previous 1937word or words. If you do not specify a prefix argument, Emacs inserts 1938the @@-command string and positions the cursor between the braces. This 1939feature works only for those @@-commands that operate on a word or words 1940within one line, such as @code{@@kbd} and @code{@@var}.@refill 1941 1942This set of insert commands was created after analyzing the frequency 1943with which different @@-commands are used in the @cite{GNU Emacs 1944Manual} and the @cite{GDB Manual}. If you wish to add your own insert 1945commands, you can bind a keyboard macro to a key, use abbreviations, 1946or extend the code in @file{texinfo.el}.@refill 1947 1948@findex texinfo-start-menu-description 1949@cindex Menu description, start 1950@cindex Description for menu, start 1951@kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert 1952command that works differently from the other insert commands. It 1953inserts a node's section or chapter title in the space for the 1954description in a menu entry line. (A menu entry has three parts, the 1955entry name, the node name, and the description. Only the node name is 1956required, but a description helps explain what the node is about. 1957@xref{Menu Parts, , The Parts of a Menu}.)@refill 1958 1959To use @code{texinfo-start-menu-description}, position point in a menu 1960entry line and type @kbd{C-c C-c C-d}. The command looks for and copies 1961the title that goes with the node name, and inserts the title as a 1962description; it positions point at beginning of the inserted text so you 1963can edit it. The function does not insert the title if the menu entry 1964line already contains a description.@refill 1965 1966This command is only an aid to writing descriptions; it does not do the 1967whole job. You must edit the inserted text since a title tends to use 1968the same words as a node name but a useful description uses different 1969words.@refill 1970 1971@node Showing the Structure 1972@comment node-name, next, previous, up 1973@section Showing the Section Structure of a File 1974@cindex Showing the section structure of a file 1975@cindex Section structure of a file, showing it 1976@cindex Structure of a file, showing it 1977@cindex Outline of file structure, showing it 1978@cindex Contents-like outline of file structure 1979@cindex File section structure, showing it 1980@cindex Texinfo file section structure, showing it 1981 1982You can show the section structure of a Texinfo file by using the 1983@kbd{C-c C-s} command (@code{texinfo-show-structure}). This command 1984shows the section structure of a Texinfo file by listing the lines 1985that begin with the @@-commands for @code{@@chapter}, 1986@code{@@section}, and the like. It constructs what amounts 1987to a table of contents. These lines are displayed in another buffer 1988called the @samp{*Occur*} buffer. In that buffer, you can position 1989the cursor over one of the lines and use the @kbd{C-c C-c} command 1990(@code{occur-mode-goto-occurrence}), to jump to the corresponding spot 1991in the Texinfo file.@refill 1992 1993@table @kbd 1994@item C-c C-s 1995@itemx M-x texinfo-show-structure 1996@findex texinfo-show-structure 1997Show the @code{@@chapter}, @code{@@section}, and such lines of a 1998Texinfo file.@refill 1999 2000@item C-c C-c 2001@itemx M-x occur-mode-goto-occurrence 2002@findex occur-mode-goto-occurrence 2003Go to the line in the Texinfo file corresponding to the line under the 2004cursor in the @file{*Occur*} buffer.@refill 2005@end table 2006 2007If you call @code{texinfo-show-structure} with a prefix argument by 2008typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the 2009@@-commands for @code{@@chapter}, @code{@@section}, and the like, but 2010also the @code{@@node} lines. You can use @code{texinfo-show-structure} 2011with a prefix argument to check whether the `Next', `Previous', and `Up' 2012pointers of an @code{@@node} line are correct. 2013 2014Often, when you are working on a manual, you will be interested only 2015in the structure of the current chapter. In this case, you can mark 2016off the region of the buffer that you are interested in by using the 2017@kbd{C-x n n} (@code{narrow-to-region}) command and 2018@code{texinfo-show-structure} will work on only that region. To see 2019the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}). 2020(@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more 2021information about the narrowing commands.)@refill 2022 2023@vindex page-delimiter 2024@cindex Page delimiter in Texinfo mode 2025In addition to providing the @code{texinfo-show-structure} command, 2026Texinfo mode sets the value of the page delimiter variable to match 2027the chapter-level @@-commands. This enables you to use the @kbd{C-x 2028]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page}) 2029commands to move forward and backward by chapter, and to use the 2030@kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter. 2031@xref{Pages, , , emacs, The GNU Emacs Manual}, for more information 2032about the page commands.@refill 2033 2034@node Updating Nodes and Menus 2035@comment node-name, next, previous, up 2036@section Updating Nodes and Menus 2037@cindex Updating nodes and menus 2038@cindex Create nodes, menus automatically 2039@cindex Insert nodes, menus automatically 2040@cindex Automatically insert nodes, menus 2041 2042Texinfo mode provides commands for automatically creating or updating 2043menus and node pointers. The commands are called ``update'' commands 2044because their most frequent use is for updating a Texinfo file after you 2045have worked on it; but you can use them to insert the `Next', 2046`Previous', and `Up' pointers into an @code{@@node} line that has none 2047and to create menus in a file that has none. 2048 2049If you do not use the updating commands, you need to write menus and 2050node pointers by hand, which is a tedious task.@refill 2051 2052@menu 2053* Updating Commands:: Five major updating commands. 2054* Updating Requirements:: How to structure a Texinfo file for 2055 using the updating command. 2056* Other Updating Commands:: How to indent descriptions, insert 2057 missing nodes lines, and update 2058 nodes in sequence. 2059@end menu 2060 2061@node Updating Commands 2062@subsection The Updating Commands 2063 2064You can use the updating commands to:@refill 2065 2066@itemize @bullet 2067@item 2068insert or update the `Next', `Previous', and `Up' pointers of a 2069node,@refill 2070 2071@item 2072insert or update the menu for a section, and@refill 2073 2074@item 2075create a master menu for a Texinfo source file.@refill 2076@end itemize 2077 2078You can also use the commands to update all the nodes and menus in a 2079region or in a whole Texinfo file.@refill 2080 2081The updating commands work only with conventional Texinfo files, which 2082are structured hierarchically like books. In such files, a structuring 2083command line must follow closely after each @code{@@node} line, except 2084for the `Top' @code{@@node} line. (A @dfn{structuring command line} is 2085a line beginning with @code{@@chapter}, @code{@@section}, or other 2086similar command.) 2087 2088You can write the structuring command line on the line that follows 2089immediately after an @code{@@node} line or else on the line that 2090follows after a single @code{@@comment} line or a single 2091@code{@@ifinfo} line. You cannot interpose more than one line between 2092the @code{@@node} line and the structuring command line; and you may 2093interpose only an @code{@@comment} line or an @code{@@ifinfo} line. 2094 2095Commands which work on a whole buffer require that the `Top' node be 2096followed by a node with an @code{@@chapter} or equivalent-level command. 2097The menu updating commands will not create a main or master menu for a 2098Texinfo file that has only @code{@@chapter}-level nodes! The menu 2099updating commands only create menus @emph{within} nodes for lower level 2100nodes. To create a menu of chapters, you must provide a `Top' 2101node. 2102 2103The menu updating commands remove menu entries that refer to other Info 2104files since they do not refer to nodes within the current buffer. This 2105is a deficiency. Rather than use menu entries, you can use cross 2106references to refer to other Info files. None of the updating commands 2107affect cross references.@refill 2108 2109Texinfo mode has five updating commands that are used most often: two 2110are for updating the node pointers or menu of a single node (or a 2111region); two are for updating every node pointer and menu in a file; 2112and one, the @code{texinfo-master-menu} command, is for creating a 2113master menu for a complete file, and optionally, for updating every 2114node and menu in the whole Texinfo file.@refill 2115 2116The @code{texinfo-master-menu} command is the primary command:@refill 2117 2118@table @kbd 2119@item C-c C-u m 2120@itemx M-x texinfo-master-menu 2121@findex texinfo-master-menu 2122Create or update a master menu that includes all the other menus 2123(incorporating the descriptions from pre-existing menus, if 2124any).@refill 2125 2126With an argument (prefix argument, @kbd{C-u,} if interactive), first create or 2127update all the nodes and all the regular menus in the buffer before 2128constructing the master menu. (@xref{The Top Node, , The Top Node and 2129Master Menu}, for more about a master menu.)@refill 2130 2131For @code{texinfo-master-menu} to work, the Texinfo file must have a 2132`Top' node and at least one subsequent node.@refill 2133 2134After extensively editing a Texinfo file, you can type the following: 2135 2136@example 2137C-u M-x texinfo-master-menu 2138@exdent or 2139C-u C-c C-u m 2140@end example 2141 2142@noindent 2143This updates all the nodes and menus completely and all at once.@refill 2144@end table 2145 2146The other major updating commands do smaller jobs and are designed for 2147the person who updates nodes and menus as he or she writes a Texinfo 2148file.@refill 2149 2150@need 1000 2151The commands are:@refill 2152 2153@table @kbd 2154@item C-c C-u C-n 2155@itemx M-x texinfo-update-node 2156@findex texinfo-update-node 2157Insert the `Next', `Previous', and `Up' pointers for the node that point is 2158within (i.e., for the @code{@@node} line preceding point). If the 2159@code{@@node} line has pre-existing `Next', `Previous', or `Up' 2160pointers in it, the old pointers are removed and new ones inserted. 2161With an argument (prefix argument, @kbd{C-u}, if interactive), this command 2162updates all @code{@@node} lines in the region (which is the text 2163between point and mark).@refill 2164 2165@item C-c C-u C-m 2166@itemx M-x texinfo-make-menu 2167@findex texinfo-make-menu 2168Create or update the menu in the node that point is within. 2169With an argument (@kbd{C-u} as prefix argument, if 2170interactive), the command makes or updates menus for the 2171nodes which are either within or a part of the 2172region.@refill 2173 2174Whenever @code{texinfo-make-menu} updates an existing menu, the 2175descriptions from that menu are incorporated into the new menu. This 2176is done by copying descriptions from the existing menu to the entries 2177in the new menu that have the same node names. If the node names are 2178different, the descriptions are not copied to the new menu.@refill 2179 2180@item C-c C-u C-e 2181@itemx M-x texinfo-every-node-update 2182@findex texinfo-every-node-update 2183Insert or update the `Next', `Previous', and `Up' pointers for every 2184node in the buffer.@refill 2185 2186@item C-c C-u C-a 2187@itemx M-x texinfo-all-menus-update 2188@findex texinfo-all-menus-update 2189Create or update all the menus in the buffer. With an argument 2190(@kbd{C-u} as prefix argument, if interactive), first insert 2191or update all the node 2192pointers before working on the menus.@refill 2193 2194If a master menu exists, the @code{texinfo-all-menus-update} command 2195updates it; but the command does not create a new master menu if none 2196already exists. (Use the @code{texinfo-master-menu} command for 2197that.)@refill 2198 2199When working on a document that does not merit a master menu, you can 2200type the following: 2201 2202@example 2203C-u C-c C-u C-a 2204@exdent or 2205C-u M-x texinfo-all-menus-update 2206@end example 2207 2208@noindent 2209This updates all the nodes and menus.@refill 2210@end table 2211 2212The @code{texinfo-column-for-description} variable specifies the 2213column to which menu descriptions are indented. By default, the value 2214is 32 although it is often useful to reduce it to as low as 24. You 2215can set the variable via customization (@pxref{Changing an Option,,, 2216emacs, The GNU Emacs Manual}) or with the @kbd{M-x set-variable} 2217command (@pxref{Examining, , Examining and Setting Variables, emacs, 2218The GNU Emacs Manual}). 2219 2220Also, the @code{texinfo-indent-menu-description} command may be used to 2221indent existing menu descriptions to a specified column. Finally, if 2222you wish, you can use the @code{texinfo-insert-node-lines} command to 2223insert missing @code{@@node} lines into a file. (@xref{Other Updating 2224Commands}, for more information.)@refill 2225 2226@node Updating Requirements 2227@subsection Updating Requirements 2228@cindex Updating requirements 2229@cindex Requirements for updating commands 2230 2231To use the updating commands, you must organize the Texinfo file 2232hierarchically with chapters, sections, subsections, and the like. 2233When you construct the hierarchy of the manual, do not `jump down' 2234more than one level at a time: you can follow the `Top' node with a 2235chapter, but not with a section; you can follow a chapter with a 2236section, but not with a subsection. However, you may `jump up' any 2237number of levels at one time---for example, from a subsection to a 2238chapter.@refill 2239 2240Each @code{@@node} line, with the exception of the line for the `Top' 2241node, must be followed by a line with a structuring command such as 2242@code{@@chapter}, @code{@@section}, or 2243@code{@@unnumberedsubsec}.@refill 2244 2245Each @code{@@node} line/structuring-command line combination 2246must look either like this: 2247 2248@example 2249@group 2250@@node Comments, Minimum, Conventions, Overview 2251@@comment node-name, next, previous, up 2252@@section Comments 2253@end group 2254@end example 2255 2256or like this (without the @code{@@comment} line): 2257 2258@example 2259@group 2260@@node Comments, Minimum, Conventions, Overview 2261@@section Comments 2262@end group 2263@end example 2264 2265or like this (without the explicit node pointers): 2266 2267@example 2268@group 2269@@node Comments 2270@@section Comments 2271@end group 2272@end example 2273 2274@noindent 2275In this example, `Comments' is the name of both the node and the 2276section. The next node is called `Minimum' and the previous node is 2277called `Conventions'. The `Comments' section is within the `Overview' 2278node, which is specified by the `Up' pointer. (Instead of an 2279@code{@@comment} line, you may also write an @code{@@ifinfo} line.) 2280 2281If a file has a `Top' node, it must be called @samp{top} or @samp{Top} 2282and be the first node in the file. 2283 2284The menu updating commands create a menu of sections within a chapter, 2285a menu of subsections within a section, and so on. This means that 2286you must have a `Top' node if you want a menu of chapters.@refill 2287 2288Incidentally, the @code{makeinfo} command will create an Info file for a 2289hierarchically organized Texinfo file that lacks `Next', `Previous' and 2290`Up' pointers. Thus, if you can be sure that your Texinfo file will be 2291formatted with @code{makeinfo}, you have no need for the update node 2292commands. (@xref{Creating an Info File}, for more information about 2293@code{makeinfo}.) However, both @code{makeinfo} and the 2294@code{texinfo-format-@dots{}} commands require that you insert menus in 2295the file. 2296 2297 2298@node Other Updating Commands 2299@subsection Other Updating Commands 2300 2301In addition to the five major updating commands, Texinfo mode 2302possesses several less frequently used updating commands:@refill 2303 2304@table @kbd 2305@item M-x texinfo-insert-node-lines 2306@findex texinfo-insert-node-lines 2307Insert @code{@@node} lines before the @code{@@chapter}, 2308@code{@@section}, and other sectioning commands wherever they are 2309missing throughout a region in a Texinfo file.@refill 2310 2311With an argument (@kbd{C-u} as prefix argument, if interactive), the 2312@code{texinfo-insert-node-lines} command not only inserts 2313@code{@@node} lines but also inserts the chapter or section titles as 2314the names of the corresponding nodes. In addition, it inserts the 2315titles as node names in pre-existing @code{@@node} lines that lack 2316names. Since node names should be more concise than section or 2317chapter titles, you must manually edit node names so inserted.@refill 2318 2319For example, the following marks a whole buffer as a region and inserts 2320@code{@@node} lines and titles throughout:@refill 2321 2322@example 2323C-x h C-u M-x texinfo-insert-node-lines 2324@end example 2325 2326This command inserts titles as node names in @code{@@node} lines; the 2327@code{texinfo-start-menu-description} command (@pxref{Inserting, 2328Inserting Frequently Used Commands}) inserts titles as descriptions in 2329menu entries, a different action. However, in both cases, you need to 2330edit the inserted text. 2331 2332@item M-x texinfo-multiple-files-update 2333@findex texinfo-multiple-files-update @r{(in brief)} 2334Update nodes and menus in a document built from several separate files. 2335With @kbd{C-u} as a prefix argument, create and insert a master menu in 2336the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first 2337update all the menus and all the `Next', `Previous', and `Up' pointers 2338of all the included files before creating and inserting a master menu in 2339the outer file. The @code{texinfo-multiple-files-update} command is 2340described in the appendix on @code{@@include} files. 2341@xref{texinfo-multiple-files-update}. 2342 2343@item M-x texinfo-indent-menu-description 2344@findex texinfo-indent-menu-description 2345Indent every description in the menu following point to the specified 2346column. You can use this command to give yourself more space for 2347descriptions. With an argument (@kbd{C-u} as prefix argument, if 2348interactive), the @code{texinfo-indent-menu-description} command indents 2349every description in every menu in the region. However, this command 2350does not indent the second and subsequent lines of a multi-line 2351description.@refill 2352 2353@item M-x texinfo-sequential-node-update 2354@findex texinfo-sequential-node-update 2355Insert the names of the nodes immediately following and preceding the 2356current node as the `Next' or `Previous' pointers regardless of those 2357nodes' hierarchical level. This means that the `Next' node of a 2358subsection may well be the next chapter. Sequentially ordered nodes are 2359useful for novels and other documents that you read through 2360sequentially. (However, in Info, the @kbd{g *} command lets 2361you look through the file sequentially, so sequentially ordered nodes 2362are not strictly necessary.) With an argument (prefix argument, if 2363interactive), the @code{texinfo-sequential-node-update} command 2364sequentially updates all the nodes in the region.@refill 2365@end table 2366 2367@node Info Formatting 2368@comment node-name, next, previous, up 2369@section Formatting for Info 2370@cindex Formatting for Info 2371@cindex Running an Info formatter 2372@cindex Info formatting 2373 2374Texinfo mode provides several commands for formatting part or all of a 2375Texinfo file for Info. Often, when you are writing a document, you 2376want to format only part of a file---that is, a region.@refill 2377 2378You can use either the @code{texinfo-format-region} or the 2379@code{makeinfo-region} command to format a region:@refill 2380 2381@table @kbd 2382@findex texinfo-format-region 2383@item C-c C-e C-r 2384@itemx M-x texinfo-format-region 2385@itemx C-c C-m C-r 2386@itemx M-x makeinfo-region 2387Format the current region for Info.@refill 2388@end table 2389 2390You can use either the @code{texinfo-format-buffer} or the 2391@code{makeinfo-buffer} command to format a whole buffer:@refill 2392 2393@table @kbd 2394@findex texinfo-format-buffer 2395@item C-c C-e C-b 2396@itemx M-x texinfo-format-buffer 2397@itemx C-c C-m C-b 2398@itemx M-x makeinfo-buffer 2399Format the current buffer for Info.@refill 2400@end table 2401 2402@need 1000 2403For example, after writing a Texinfo file, you can type the following: 2404 2405@example 2406C-u C-c C-u m 2407@exdent or 2408C-u M-x texinfo-master-menu 2409@end example 2410 2411@noindent 2412This updates all the nodes and menus. Then type the following to create 2413an Info file: 2414 2415@example 2416C-c C-m C-b 2417@exdent or 2418M-x makeinfo-buffer 2419@end example 2420 2421For @TeX{} or the Info formatting commands to work, the file @emph{must} 2422include a line that has @code{@@setfilename} in its header. 2423 2424@xref{Creating an Info File}, for details about Info formatting.@refill 2425 2426@node Printing 2427@comment node-name, next, previous, up 2428@section Printing 2429@cindex Formatting for printing 2430@cindex Printing a region or buffer 2431@cindex Region formatting and printing 2432@cindex Buffer formatting and printing 2433@cindex Part of file formatting and printing 2434 2435Typesetting and printing a Texinfo file is a multi-step process in which 2436you first create a file for printing (called a DVI file), and then 2437print the file. Optionally, you may also create indices. To do this, 2438you must run the @code{texindex} command after first running the 2439@code{tex} typesetting command; and then you must run the @code{tex} 2440command again. Or else run the @code{texi2dvi} command which 2441automatically creates indices as needed (@pxref{Format with texi2dvi}). 2442 2443Often, when you are writing a document, you want to typeset and print 2444only part of a file to see what it will look like. You can use the 2445@code{texinfo-tex-region} and related commands for this purpose. Use 2446the @code{texinfo-tex-buffer} command to format all of a 2447buffer.@refill 2448 2449@table @kbd 2450@item C-c C-t C-b 2451@itemx M-x texinfo-tex-buffer 2452@findex texinfo-tex-buffer 2453Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the 2454buffer, this command automatically creates or updates indices as 2455needed.@refill 2456 2457@item C-c C-t C-r 2458@itemx M-x texinfo-tex-region 2459@findex texinfo-tex-region 2460Run @TeX{} on the region.@refill 2461 2462@item C-c C-t C-i 2463@itemx M-x texinfo-texindex 2464Run @code{texindex} to sort the indices of a Texinfo file formatted with 2465@code{texinfo-tex-region}. The @code{texinfo-tex-region} command does 2466not run @code{texindex} automatically; it only runs the @code{tex} 2467typesetting command. You must run the @code{texinfo-tex-region} command 2468a second time after sorting the raw index files with the @code{texindex} 2469command. (Usually, you do not format an index when you format a region, 2470only when you format a buffer. Now that the @code{texi2dvi} command 2471exists, there is little or no need for this command.)@refill 2472 2473@item C-c C-t C-p 2474@itemx M-x texinfo-tex-print 2475@findex texinfo-tex-print 2476Print the file (or the part of the file) previously formatted with 2477@code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill 2478@end table 2479 2480For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the 2481file @emph{must} start with a @samp{\input texinfo} line and must 2482include an @code{@@settitle} line. The file must end with @code{@@bye} 2483on a line by itself. (When you use @code{texinfo-tex-region}, you must 2484surround the @code{@@settitle} line with start-of-header and 2485end-of-header lines.)@refill 2486 2487@xref{Hardcopy}, for a description of the other @TeX{} related 2488commands, such as @code{tex-show-print-queue}.@refill 2489 2490@node Texinfo Mode Summary 2491@comment node-name, next, previous, up 2492@section Texinfo Mode Summary 2493 2494In Texinfo mode, each set of commands has default keybindings that 2495begin with the same keys. All the commands that are custom-created 2496for Texinfo mode begin with @kbd{C-c}. The keys are somewhat 2497mnemonic.@refill 2498 2499@subheading Insert Commands 2500 2501The insert commands are invoked by typing @kbd{C-c} twice and then the 2502first letter of the @@-command to be inserted. (It might make more 2503sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but 2504@kbd{C-c C-c} is quick to type.)@refill 2505 2506@example 2507C-c C-c c @r{Insert} @samp{@@code}. 2508C-c C-c d @r{Insert} @samp{@@dfn}. 2509C-c C-c e @r{Insert} @samp{@@end}. 2510C-c C-c i @r{Insert} @samp{@@item}. 2511C-c C-c n @r{Insert} @samp{@@node}. 2512C-c C-c s @r{Insert} @samp{@@samp}. 2513C-c C-c v @r{Insert} @samp{@@var}. 2514C-c C-c @{ @r{Insert braces.} 2515C-c C-c ] 2516C-c C-c @} @r{Move out of enclosing braces.} 2517 2518@group 2519C-c C-c C-d @r{Insert a node's section title} 2520 @r{in the space for the description} 2521 @r{in a menu entry line.} 2522@end group 2523@end example 2524 2525@subheading Show Structure 2526 2527The @code{texinfo-show-structure} command is often used within a 2528narrowed region.@refill 2529 2530@example 2531C-c C-s @r{List all the headings.} 2532@end example 2533 2534@subheading The Master Update Command 2535 2536The @code{texinfo-master-menu} command creates a master menu; and can 2537be used to update every node and menu in a file as well.@refill 2538 2539@c Probably should use @tables in this section. 2540@example 2541@group 2542C-c C-u m 2543M-x texinfo-master-menu 2544 @r{Create or update a master menu.} 2545@end group 2546 2547@group 2548C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first} 2549 @r{create or update all nodes and regular} 2550 @r{menus, and then create a master menu.} 2551@end group 2552@end example 2553 2554@subheading Update Pointers 2555 2556The update pointer commands are invoked by typing @kbd{C-c C-u} and 2557then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for 2558@code{texinfo-every-node-update}.@refill 2559 2560@example 2561C-c C-u C-n @r{Update a node.} 2562C-c C-u C-e @r{Update every node in the buffer.} 2563@end example 2564 2565@subheading Update Menus 2566 2567Invoke the update menu commands by typing @kbd{C-c C-u} 2568and then either @kbd{C-m} for @code{texinfo-make-menu} or 2569@kbd{C-a} for @code{texinfo-all-menus-update}. To update 2570both nodes and menus at the same time, precede @kbd{C-c C-u 2571C-a} with @kbd{C-u}.@refill 2572 2573@example 2574C-c C-u C-m @r{Make or update a menu.} 2575 2576@group 2577C-c C-u C-a @r{Make or update all} 2578 @r{menus in a buffer.} 2579@end group 2580 2581@group 2582C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,} 2583 @r{first create or update all nodes and} 2584 @r{then create or update all menus.} 2585@end group 2586@end example 2587 2588@subheading Format for Info 2589 2590The Info formatting commands that are written in Emacs Lisp are 2591invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region 2592or @kbd{C-b} for the whole buffer.@refill 2593 2594The Info formatting commands that are written in C and based on the 2595@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then 2596either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill 2597 2598@need 800 2599@noindent 2600Use the @code{texinfo-format@dots{}} commands: 2601 2602@example 2603@group 2604C-c C-e C-r @r{Format the region.} 2605C-c C-e C-b @r{Format the buffer.} 2606@end group 2607@end example 2608 2609@need 750 2610@noindent 2611Use @code{makeinfo}: 2612 2613@example 2614C-c C-m C-r @r{Format the region.} 2615C-c C-m C-b @r{Format the buffer.} 2616C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.} 2617C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.} 2618@end example 2619 2620@subheading Typeset and Print 2621 2622The @TeX{} typesetting and printing commands are invoked by typing 2623@kbd{C-c C-t} and then another control command: @kbd{C-r} for 2624@code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer}, 2625and so on.@refill 2626 2627@example 2628C-c C-t C-r @r{Run @TeX{} on the region.} 2629C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.} 2630C-c C-t C-i @r{Run} @code{texindex}. 2631C-c C-t C-p @r{Print the DVI file.} 2632C-c C-t C-q @r{Show the print queue.} 2633C-c C-t C-d @r{Delete a job from the print queue.} 2634C-c C-t C-k @r{Kill the current @TeX{} formatting job.} 2635C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.} 2636C-c C-t C-l @r{Recenter the output buffer.} 2637@end example 2638 2639@subheading Other Updating Commands 2640 2641The remaining updating commands do not have standard keybindings because 2642they are rarely used. 2643 2644@example 2645@group 2646M-x texinfo-insert-node-lines 2647 @r{Insert missing @code{@@node} lines in region.} 2648 @r{With @kbd{C-u} as a prefix argument,} 2649 @r{use section titles as node names.} 2650@end group 2651 2652@group 2653M-x texinfo-multiple-files-update 2654 @r{Update a multi-file document.} 2655 @r{With @kbd{C-u 2} as a prefix argument,} 2656 @r{create or update all nodes and menus} 2657 @r{in all included files first.} 2658@end group 2659 2660@group 2661M-x texinfo-indent-menu-description 2662 @r{Indent descriptions.} 2663@end group 2664 2665@group 2666M-x texinfo-sequential-node-update 2667 @r{Insert node pointers in strict sequence.} 2668@end group 2669@end example 2670 2671 2672@node Beginning a File 2673@chapter Beginning a Texinfo File 2674@cindex Beginning a Texinfo file 2675@cindex Texinfo file beginning 2676@cindex File beginning 2677 2678Certain pieces of information must be provided at the beginning of a 2679Texinfo file, such as the name for the output file(s), the title of the 2680document, and the Top node. A table of contents is also generally 2681produced here. 2682 2683This chapter expands on the minimal complete Texinfo source file 2684previously given (@pxref{Six Parts}). It describes the numerous 2685commands for handling the traditional frontmatter items in Texinfo. 2686 2687@cindex Frontmatter, text in 2688Straight text outside of any command before the Top node should be 2689avoided. Such text is treated differently in the different output 2690formats: visible in @TeX{} and HTML, by default not shown in Info 2691readers, and so on. 2692 2693@menu 2694* Sample Beginning:: A sample beginning for a Texinfo file. 2695* Texinfo File Header:: The first lines. 2696* Document Permissions:: Ensuring your manual is free. 2697* Titlepage & Copyright Page:: Creating the title and copyright pages. 2698* Contents:: How to create a table of contents. 2699* The Top Node:: Creating the `Top' node and master menu. 2700* Global Document Commands:: Affecting formatting throughout. 2701* Software Copying Permissions:: Ensure that you and others continue to 2702 have the right to use and share software. 2703@end menu 2704 2705 2706@node Sample Beginning 2707@section Sample Texinfo File Beginning 2708 2709@cindex Example beginning of Texinfo file 2710 2711The following sample shows what is needed. The elements given here are 2712explained in more detail in the following sections. Other commands are 2713often included at the beginning of Texinfo files, but the ones here are 2714the most critical. 2715 2716@xref{GNU Sample Texts}, for the full texts to be used in GNU manuals. 2717 2718@example 2719\input texinfo @@c -*-texinfo-*- 2720@@c %**start of header 2721@@setfilename @var{infoname}.info 2722@@settitle @var{name-of-manual} @var{version} 2723@@c %**end of header 2724 2725@@copying 2726This manual is for @var{program}, version @var{version}. 2727 2728Copyright @@copyright@{@} @var{years} @var{copyright-owner}. 2729 2730@group 2731@@quotation 2732Permission is granted to @dots{} 2733@@end quotation 2734@@end copying 2735@end group 2736 2737@group 2738@@titlepage 2739@@title @var{name-of-manual-when-printed} 2740@@subtitle @var{subtitle-if-any} 2741@@subtitle @var{second-subtitle} 2742@@author @var{author} 2743@end group 2744 2745@group 2746@@c The following two commands 2747@@c start the copyright page. 2748@@page 2749@@vskip 0pt plus 1filll 2750@@insertcopying 2751@end group 2752 2753Published by @dots{} 2754@@end titlepage 2755 2756@@c So the toc is printed at the start. 2757@@contents 2758 2759@@ifnottex 2760@@node Top 2761@@top @var{title} 2762 2763@@insertcopying 2764@@end ifnottex 2765 2766@group 2767@@menu 2768* First Chapter:: Getting started @dots{} 2769* Second Chapter:: @dots{} 2770 @dots{} 2771* Copying:: Your rights and freedoms. 2772@@end menu 2773@end group 2774 2775@group 2776@@node First Chapter 2777@@chapter First Chapter 2778 2779@@cindex first chapter 2780@@cindex chapter, first 2781@dots{} 2782@end group 2783@end example 2784 2785 2786@node Texinfo File Header 2787@section Texinfo File Header 2788@cindex Header for Texinfo files 2789@cindex Texinfo file header 2790 2791Texinfo files start with at least three lines that provide Info and 2792@TeX{} with necessary information. These are the @code{\input texinfo} 2793line, the @code{@@settitle} line, and the @code{@@setfilename} line. 2794 2795Also, if you want to format just part of the Texinfo file, you must 2796write the @code{@@settitle} and @code{@@setfilename} lines between 2797start-of-header and end-of-header lines. The start- and end-of-header 2798lines are optional, but they do no harm, so you might as well always 2799include them. 2800 2801Any command that affects document formatting as a whole makes sense to 2802include in the header. @code{@@synindex} (@pxref{synindex}), for 2803instance, is another command often included in the header. @xref{GNU 2804Sample Texts}, for complete sample texts. 2805 2806Thus, the beginning of a Texinfo file generally looks like this: 2807 2808@example 2809@group 2810\input texinfo @@c -*-texinfo-*- 2811@@c %**start of header 2812@@setfilename sample.info 2813@@settitle Sample Manual 1.0 2814@@c %**end of header 2815@end group 2816@end example 2817 2818@menu 2819* First Line:: The first line of a Texinfo file. 2820* Start of Header:: Formatting a region requires this. 2821* setfilename:: Tell Info the name of the Info file. 2822* settitle:: Create a title for the printed work. 2823* End of Header:: Formatting a region requires this. 2824@end menu 2825 2826 2827@node First Line 2828@subsection The First Line of a Texinfo File 2829@cindex First line of a Texinfo file 2830@cindex Beginning line of a Texinfo file 2831@cindex Header of a Texinfo file 2832 2833Every Texinfo file that is to be the top-level input to @TeX{} must begin 2834with a line that looks like this: 2835 2836@example 2837\input texinfo @@c -*-texinfo-*- 2838@end example 2839 2840@noindent 2841This line serves two functions: 2842 2843@enumerate 2844@item 2845When the file is processed by @TeX{}, the @samp{\input texinfo} command 2846tells @TeX{} to load the macros needed for processing a Texinfo file. 2847These are in a file called @file{texinfo.tex}, which should have been 2848installed on your system along with either the @TeX{} or Texinfo 2849software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of 2850a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex} 2851file causes the switch from @samp{\} to @samp{@@}; before the switch 2852occurs, @TeX{} requires @samp{\}, which is why it appears at the 2853beginning of the file. 2854 2855@item 2856When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode 2857specification tells Emacs to use Texinfo mode. 2858@end enumerate 2859 2860 2861@node Start of Header 2862@subsection Start of Header 2863@cindex Start of header line 2864 2865A start-of-header line is a Texinfo comment that looks like this: 2866 2867@example 2868@@c %**start of header 2869@end example 2870 2871Write the start-of-header line on the second line of a Texinfo file. 2872Follow the start-of-header line with @code{@@setfilename} and 2873@code{@@settitle} lines and, optionally, with other commands that 2874globally affect the document formatting, such as @code{@@synindex} or 2875@code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of 2876Header}). 2877 2878The start- and end-of-header lines allow you to format only part of a 2879Texinfo file for Info or printing. @xref{texinfo-format commands}. 2880 2881The odd string of characters, @samp{%**}, is to ensure that no other 2882comment is accidentally taken for a start-of-header line. You can 2883change it if you wish by setting the @code{tex-start-of-header} and/or 2884@code{tex-end-of-header} Emacs variables. @xref{Texinfo Mode Printing}. 2885 2886 2887@node setfilename 2888@subsection @code{@@setfilename}: Set the output file name 2889@findex setfilename 2890@cindex Texinfo requires @code{@@setfilename} 2891 2892In order to serve as the primary input file for either @code{makeinfo} 2893or @TeX{}, a Texinfo file must contain a line that looks like this: 2894 2895@example 2896@@setfilename @var{info-file-name} 2897@end example 2898 2899Write the @code{@@setfilename} command at the beginning of a line and 2900follow it on the same line by the Info file name. Do not write anything 2901else on the line; anything on the line after the command is considered 2902part of the file name, including what would otherwise be a 2903comment. 2904 2905@cindex Ignored before @code{@@setfilename} 2906@cindex @samp{\input} source line ignored 2907The Info formatting commands ignore everything written before the 2908@code{@@setfilename} line, which is why the very first line of 2909the file (the @code{\input} line) does not show up in the output. 2910 2911The @code{@@setfilename} line specifies the name of the output file to 2912be generated. This name must be different from the name of the Texinfo 2913file. There are two conventions for choosing the name: you can either 2914remove the extension (such as @samp{.texi}) entirely from the input file 2915name, or, preferably, replace it with the @samp{.info} extension. 2916 2917@cindex Length of file names 2918@cindex File name collision 2919@cindex Info file name, choosing 2920Although an explicit @samp{.info} extension is preferable, some 2921operating systems cannot handle long file names. You can run into a 2922problem even when the file name you specify is itself short enough. 2923This occurs because the Info formatters split a long Info file into 2924short indirect subfiles, and name them by appending @samp{-1}, 2925@samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original 2926file name. (@xref{Tag and Split Files}.) The subfile name 2927@file{texinfo.info-10}, for example, is too long for old systems with a 292814-character limit on filenames; so the Info file name for this document 2929is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo} 2930is running on operating systems such as MS-DOS which impose severe 2931limits on file names, it may remove some characters from the original 2932file name to leave enough space for the subfile suffix, thus producing 2933files named @file{texin-10}, @file{gcc.i12}, etc. 2934 2935When producing HTML output, @code{makeinfo} will replace any extension 2936with @samp{html}, or add @samp{.html} if the given name has no 2937extension. 2938 2939@pindex texinfo.cnf 2940The @code{@@setfilename} line produces no output when you typeset a 2941manual with @TeX{}, but it is nevertheless essential: it opens the 2942index, cross-reference, and other auxiliary files used by Texinfo, and 2943also reads @file{texinfo.cnf} if that file is present on your system 2944(@pxref{Preparing for TeX,, Preparing for @TeX{}}). 2945 2946 2947@node settitle 2948@subsection @code{@@settitle}: Set the document title 2949@findex settitle 2950 2951In order to be made into a printed manual, a Texinfo file must contain 2952a line that looks like this: 2953 2954@example 2955@@settitle @var{title} 2956@end example 2957 2958Write the @code{@@settitle} command at the beginning of a line and 2959follow it on the same line by the title. This tells @TeX{} the title to 2960use in a header or footer. Do not write anything else on the line; 2961anything on the line after the command is considered part of the title, 2962including what would otherwise be a comment. 2963 2964The @code{@@settitle} command should precede everything that generates 2965actual output. The best place for it is right after the 2966@code{@@setfilename} command (see the previous section). 2967 2968@cindex <title> HTML tag 2969In the HTML file produced by @command{makeinfo}, @var{title} serves as 2970the document @samp{<title>}. It also becomes the default document 2971description in the @samp{<head>} part (@pxref{documentdescription}). 2972 2973The title in the @code{@@settitle} command does not affect the title as 2974it appears on the title page. Thus, the two do not need not match 2975exactly. A practice we recommend is to include the version or edition 2976number of the manual in the @code{@@settitle} title; on the title page, 2977the version number generally appears as a @code{@@subtitle} so it would 2978be omitted from the @code{@@title}. @xref{titlepage}. 2979 2980Conventionally, when @TeX{} formats a Texinfo file for double-sided 2981output, the title is printed in the left-hand (even-numbered) page 2982headings and the current chapter title is printed in the right-hand 2983(odd-numbered) page headings. (@TeX{} learns the title of each chapter 2984from each @code{@@chapter} command.) By default, no page footer is 2985printed. 2986 2987Even if you are printing in a single-sided style, @TeX{} looks for an 2988@code{@@settitle} command line, in case you include the manual title 2989in the heading. 2990 2991@TeX{} prints page headings only for that text that comes after the 2992@code{@@end titlepage} command in the Texinfo file, or that comes 2993after an @code{@@headings} command that turns on headings. 2994(@xref{headings on off, , The @code{@@headings} Command}, for more 2995information.) 2996 2997You may, if you wish, create your own, customized headings and footings. 2998@xref{Headings}, for a detailed discussion of this. 2999 3000 3001@node End of Header 3002@subsection End of Header 3003@cindex End of header line 3004 3005Follow the header lines with an @w{end-of-header} line, which is a 3006Texinfo comment that looks like this: 3007 3008@example 3009@@c %**end of header 3010@end example 3011 3012@xref{Start of Header}. 3013 3014 3015@node Document Permissions 3016@section Document Permissions 3017@cindex Document Permissions 3018@cindex Copying Permissions 3019 3020The copyright notice and copying permissions for a document need to 3021appear in several places in the various Texinfo output formats. 3022Therefore, Texinfo provides a command (@code{@@copying}) to declare 3023this text once, and another command (@code{@@insertcopying}) to 3024insert the text at appropriate points. 3025 3026@menu 3027* copying:: Declare the document's copying permissions. 3028* insertcopying:: Where to insert the permissions. 3029@end menu 3030 3031 3032@node copying 3033@subsection @code{@@copying}: Declare Copying Permissions 3034@findex copying 3035 3036The @code{@@copying} command should be given very early in the document; 3037the recommended location is right after the header material 3038(@pxref{Texinfo File Header}). It conventionally consists of a sentence 3039or two about what the program is, identification of the documentation 3040itself, the legal copyright line, and the copying permissions. Here is 3041a skeletal example: 3042 3043@example 3044@@copying 3045This manual is for @var{program} (version @var{version}, updated 3046@var{date}), which @dots{} 3047 3048Copyright @@copyright@{@} @var{years} @var{copyright-owner}. 3049 3050@@quotation 3051Permission is granted to @dots{} 3052@@end quotation 3053@@end copying 3054@end example 3055 3056The @code{@@quotation} has no legal significance; it's there to improve 3057readability in some contexts. 3058 3059@xref{GNU Sample Texts}, for the full text to be used in GNU manuals. 3060@xref{GNU Free Documentation License}, for the license itself under 3061which GNU and other free manuals are distributed. You need to include 3062the license as an appendix to your document. 3063 3064The text of @code{@@copying} is output as a comment at the beginning of 3065Info, HTML, and XML output files. It is @emph{not} output implicitly in 3066plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to 3067emit the copying information. See the next section for details. 3068 3069@findex copyright 3070The @code{@@copyright@{@}} command generates a @samp{c} inside a circle 3071in output formats that support this (print and HTML). In the other 3072formats (Info and plain text), it generates @samp{(C)}. The copyright 3073notice itself has the following legally defined sequence: 3074 3075@example 3076Copyright @copyright{} @var{years} @var{copyright-owner}. 3077@end example 3078 3079@cindex Copyright word, always in English 3080The word `Copyright' must always be written in English, even if the 3081document is otherwise written in another language. This is due to 3082international law. 3083 3084@cindex Years, in copyright line 3085The list of years should include all years in which a version was 3086completed (even if it was released in a subsequent year). Ranges are 3087not allowed; each year must be written out individually and in full, 3088separated by commas. 3089 3090@cindex Copyright holder for FSF works 3091@cindex Holder of copyright for FSF works 3092@cindex Owner of copyright for FSF works 3093The copyright owner (or owners) is whoever holds legal copyright on the 3094work. In the case of works assigned to the FSF, the owner is `Free 3095Software Foundation, Inc.'. 3096 3097The copyright `line' may actually be split across multiple 3098lines, both in the source document and in the output. This often 3099happens for documents with a long history, having many different years 3100of publication. 3101 3102@xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for 3103additional information. 3104 3105 3106@node insertcopying 3107@subsection @code{@@insertcopying}: Include Permissions Text 3108@findex insertcopying 3109@cindex Copying text, including 3110@cindex Permissions text, including 3111@cindex Including permissions text 3112 3113The @code{@@insertcopying} command is simply written on a line by 3114itself, like this: 3115 3116@example 3117@@insertcopying 3118@end example 3119 3120This inserts the text previously defined by @code{@@copying}. To meet 3121legal requirements, it must be used on the copyright page in the printed 3122manual (@pxref{Copyright}). 3123 3124We also strongly recommend using @code{@@insertcopying} in the Top node 3125of your manual (@pxref{The Top Node}), although it is not required 3126legally. Here's why: 3127 3128The @code{@@copying} command itself causes the permissions text to 3129appear in an Info file @emph{before} the first node. The text is also 3130copied into the beginning of each split Info output file, as is legally 3131necessary. This location implies a human reading the manual using Info 3132does @emph{not} see this text (except when using the advanced Info 3133command @kbd{g *}). Therefore, an explicit @code{@@insertcopying} 3134in the Top node makes it apparent to readers that the manual is free. 3135 3136Similarly, the @code{@@copying} text is automatically included at the 3137beginning of each HTML output file, as an HTML comment. Again, this 3138text is not visible (unless the reader views the HTML source). And 3139therefore again, the @code{@@insertcopying} in the Top node is valuable 3140because it makes the copying permissions visible and thus promotes 3141freedom. 3142 3143The permissions text defined by @code{@@copying} also appears 3144automatically at the beginning of the XML output file. 3145 3146 3147@node Titlepage & Copyright Page 3148@section Title and Copyright Pages 3149 3150In hard copy output, the manual's name and author are usually printed on 3151a title page. Copyright information is usually printed on the back of 3152the title page. 3153 3154The title and copyright pages appear in the printed manual, but not in 3155the Info file. Because of this, it is possible to use several slightly 3156obscure @TeX{} typesetting commands that cannot be used in an Info file. 3157In addition, this part of the beginning of a Texinfo file contains the 3158text of the copying permissions that appears in the printed manual. 3159 3160@cindex Title page, for plain text 3161@cindex Copyright page, for plain text 3162You may wish to include titlepage-like information for plain text 3163output. Simply place any such leading material between 3164@code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo} 3165includes this when writing plain text (@samp{--no-headers}), along with 3166an @code{@@insertcopying}. 3167 3168@menu 3169* titlepage:: Create a title for the printed document. 3170* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, 3171 and @code{@@sp} commands. 3172* title subtitle author:: The @code{@@title}, @code{@@subtitle}, 3173 and @code{@@author} commands. 3174* Copyright:: How to write the copyright notice and 3175 include copying permissions. 3176* end titlepage:: Turn on page headings after the title and 3177 copyright pages. 3178* headings on off:: An option for turning headings on and off 3179 and double or single sided printing. 3180@end menu 3181 3182 3183@node titlepage 3184@subsection @code{@@titlepage} 3185@cindex Title page 3186@findex titlepage 3187 3188Start the material for the title page and following copyright page 3189with @code{@@titlepage} on a line by itself and end it with 3190@code{@@end titlepage} on a line by itself. 3191 3192The @code{@@end titlepage} command starts a new page and turns on page 3193numbering. (@xref{Headings, , Page Headings}, for details about how to 3194generate page headings.) All the material that you want to appear on 3195unnumbered pages should be put between the @code{@@titlepage} and 3196@code{@@end titlepage} commands. You can force the table of contents to 3197appear there with the @code{@@setcontentsaftertitlepage} command 3198(@pxref{Contents}). 3199 3200@findex page@r{, within @code{@@titlepage}} 3201By using the @code{@@page} command you can force a page break within the 3202region delineated by the @code{@@titlepage} and @code{@@end titlepage} 3203commands and thereby create more than one unnumbered page. This is how 3204the copyright page is produced. (The @code{@@titlepage} command might 3205perhaps have been better named the @code{@@titleandadditionalpages} 3206command, but that would have been rather long!) 3207 3208When you write a manual about a computer program, you should write the 3209version of the program to which the manual applies on the title page. 3210If the manual changes more frequently than the program or is independent 3211of it, you should also include an edition number@footnote{We have found 3212that it is helpful to refer to versions of independent manuals as 3213`editions' and versions of programs as `versions'; otherwise, we find we 3214are liable to confuse each other in conversation by referring to both 3215the documentation and the software with the same words.} for the manual. 3216This helps readers keep track of which manual is for which version of 3217the program. (The `Top' node should also contain this information; see 3218@ref{The Top Node}.) 3219 3220Texinfo provides two main methods for creating a title page. One method 3221uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands 3222to generate a title page in which the words on the page are 3223centered. 3224 3225The second method uses the @code{@@title}, @code{@@subtitle}, and 3226@code{@@author} commands to create a title page with black rules under 3227the title and author lines and the subtitle text set flush to the 3228right hand side of the page. With this method, you do not specify any 3229of the actual formatting of the title page. You specify the text 3230you want, and Texinfo does the formatting. 3231 3232You may use either method, or you may combine them; see the examples in 3233the sections below. 3234 3235@findex shorttitlepage 3236@cindex Bastard title page 3237@cindex Title page, bastard 3238For extremely simple documents, and for the bastard title page in 3239traditional book frontmatter, Texinfo also provides a command 3240@code{@@shorttitlepage} which takes the rest of the line as the title. 3241The argument is typeset on a page by itself and followed by a blank 3242page. 3243 3244 3245@node titlefont center sp 3246@subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp} 3247@findex titlefont 3248@findex center 3249@findex sp @r{(titlepage line spacing)} 3250 3251You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center} 3252commands to create a title page for a printed document. (This is the 3253first of the two methods for creating a title page in Texinfo.) 3254 3255Use the @code{@@titlefont} command to select a large font suitable for 3256the title itself. You can use @code{@@titlefont} more than once if you 3257have an especially long title. 3258 3259For HTML output, each @code{@@titlefont} command produces an 3260@code{<h1>} heading, but the HTML document @code{<title>} is not 3261affected. For that, you must put an @code{@@settitle} command before 3262the @code{@@titlefont} command (@pxref{settitle}). 3263 3264@need 700 3265For example: 3266 3267@example 3268@@titlefont@{Texinfo@} 3269@end example 3270 3271Use the @code{@@center} command at the beginning of a line to center 3272the remaining text on that line. Thus, 3273 3274@example 3275@@center @@titlefont@{Texinfo@} 3276@end example 3277 3278@noindent 3279centers the title, which in this example is ``Texinfo'' printed 3280in the title font. 3281 3282Use the @code{@@sp} command to insert vertical space. For example: 3283 3284@example 3285@@sp 2 3286@end example 3287 3288@noindent 3289This inserts two blank lines on the printed page. (@xref{sp, , 3290@code{@@sp}}, for more information about the @code{@@sp} 3291command.) 3292 3293A template for this method looks like this: 3294 3295@example 3296@group 3297@@titlepage 3298@@sp 10 3299@@center @@titlefont@{@var{name-of-manual-when-printed}@} 3300@@sp 2 3301@@center @var{subtitle-if-any} 3302@@sp 2 3303@@center @var{author} 3304@dots{} 3305@@end titlepage 3306@end group 3307@end example 3308 3309The spacing of the example fits an 8.5 by 11 inch manual. 3310 3311You can in fact use these commands anywhere, not just on a title page, 3312but since they are not logical markup commands, we don't recommend 3313them. 3314 3315@node title subtitle author 3316@subsection @code{@@title}, @code{@@subtitle}, and @code{@@author} 3317@findex title 3318@findex subtitle 3319@findex author 3320 3321You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author} 3322commands to create a title page in which the vertical and horizontal 3323spacing is done for you automatically. This contrasts with the method 3324described in the previous section, in which the @code{@@sp} command is 3325needed to adjust vertical spacing. 3326 3327Write the @code{@@title}, @code{@@subtitle}, or @code{@@author} 3328commands at the beginning of a line followed by the title, subtitle, 3329or author. These commands are only effective in @TeX{} output; it's 3330an error to use them anywhere except within @code{@@titlepage}. 3331 3332The @code{@@title} command produces a line in which the title is set 3333flush to the left-hand side of the page in a larger than normal font. 3334The title is underlined with a black rule. Only a single line is 3335allowed; the @code{@@*} command may not be used to break the title into 3336two lines. To handle very long titles, you may find it profitable to 3337use both @code{@@title} and @code{@@titlefont}; see the final example in 3338this section. 3339 3340The @code{@@subtitle} command sets subtitles in a normal-sized font 3341flush to the right-hand side of the page. 3342 3343The @code{@@author} command sets the names of the author or authors in 3344a middle-sized font flush to the left-hand side of the page on a line 3345near the bottom of the title page. The names are underlined with a 3346black rule that is thinner than the rule that underlines the title. 3347(The black rule only occurs if the @code{@@author} command line is 3348followed by an @code{@@page} command line.) 3349 3350There are two ways to use the @code{@@author} command: you can write 3351the name or names on the remaining part of the line that starts with 3352an @code{@@author} command: 3353 3354@example 3355@@author by Jane Smith and John Doe 3356@end example 3357 3358@noindent 3359or you can write the names one above each other by using two (or more) 3360@code{@@author} commands: 3361 3362@example 3363@group 3364@@author Jane Smith 3365@@author John Doe 3366@end group 3367@end example 3368 3369@noindent 3370(Only the bottom name is underlined with a black rule.) 3371 3372@need 950 3373A template for this method looks like this: 3374 3375@example 3376@group 3377@@titlepage 3378@@title @var{name-of-manual-when-printed} 3379@@subtitle @var{subtitle-if-any} 3380@@subtitle @var{second-subtitle} 3381@@author @var{author} 3382@@page 3383@dots{} 3384@@end titlepage 3385@end group 3386@end example 3387 3388You may also combine the @code{@@titlefont} method described in the 3389previous section and @code{@@title} method described in this one. This 3390may be useful if you have a very long title. Here is a real-life example: 3391 3392@example 3393@group 3394@@titlepage 3395@@titlefont@{GNU Software@} 3396@@sp 1 3397@@title for MS-Windows and MS-DOS 3398@@subtitle Edition @@value@{e@} for Release @@value@{cde@} 3399@@author by Daniel Hagerty, Melissa Weisshaus 3400@@author and Eli Zaretskii 3401@end group 3402@end example 3403 3404@noindent 3405(The use of @code{@@value} here is explained in @ref{value Example}. 3406 3407 3408@node Copyright 3409@subsection Copyright Page 3410@cindex Copyright page 3411@cindex Printed permissions 3412@cindex Permissions, printed 3413 3414By international treaty, the copyright notice for a book must be either 3415on the title page or on the back of the title page. When the copyright 3416notice is on the back of the title page, that page is customarily not 3417numbered. Therefore, in Texinfo, the information on the copyright page 3418should be within @code{@@titlepage} and @code{@@end titlepage} 3419commands. 3420 3421@findex vskip @r{@TeX{} vertical skip} 3422@findex filll @r{@TeX{} dimension} 3423Use the @code{@@page} command to cause a page break. To push the 3424copyright notice and the other text on the copyright page towards the 3425bottom of the page, use the following incantantion after @code{@@page}: 3426 3427@example 3428@@vskip 0pt plus 1filll 3429@end example 3430 3431@noindent 3432This is a @TeX{} command that is not supported by the Info formatting 3433commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt 3434plus 1filll} means to put in zero points of mandatory whitespace, and as 3435much optional whitespace as needed to push the following text to the 3436bottom of the page. Note the use of three @samp{l}s in the word 3437@samp{filll}; this is correct. 3438 3439To insert the copyright text itself, write @code{@@insertcopying} 3440next (@pxref{Document Permissions}): 3441 3442@example 3443@@insertcopying 3444@end example 3445 3446Follow the copying text by the publisher, ISBN numbers, cover art 3447credits, and other such information. 3448 3449Here is an example putting all this together: 3450 3451@example 3452@@titlepage 3453@dots{} 3454@@page 3455@@vskip 0pt plus 1filll 3456@@insertcopying 3457 3458Published by @dots{} 3459 3460Cover art by @dots{} 3461@@end titlepage 3462@end example 3463 3464 3465@node end titlepage 3466@subsection Heading Generation 3467@findex end titlepage 3468@cindex Headings, page, begin to appear 3469@cindex Titlepage end starts headings 3470@cindex End titlepage starts headings 3471 3472Like all @code{@@end} commands (@pxref{Quotations and Examples}), the @code{@@end titlepage} command 3473must be written at the beginning of a line by itself, with only one 3474space between the @code{@@end} and the @code{titlepage}. It not only 3475marks the end of the title and copyright pages, but also causes @TeX{} 3476to start generating page headings and page numbers. 3477 3478To repeat what is said elsewhere, Texinfo has two standard page heading 3479formats, one for documents which are printed on one side of each sheet of paper 3480(single-sided printing), and the other for documents which are printed on both 3481sides of each sheet (double-sided printing). 3482You can specify these formats in different ways: 3483 3484@itemize @bullet 3485@item 3486The conventional way is to write an @code{@@setchapternewpage} command 3487before the title page commands, and then have the @code{@@end 3488titlepage} command start generating page headings in the manner desired. 3489(@xref{setchapternewpage}.) 3490 3491@item 3492Alternatively, you can use the @code{@@headings} command to prevent page 3493headings from being generated or to start them for either single or 3494double-sided printing. (Write an @code{@@headings} command immediately 3495after the @code{@@end titlepage} command. @xref{headings on off, , The 3496@code{@@headings} Command}, for more information.)@refill 3497 3498@item 3499Or, you may specify your own page heading and footing format. 3500@xref{Headings, , Page Headings}, for detailed 3501information about page headings and footings. 3502@end itemize 3503 3504Most documents are formatted with the standard single-sided or 3505double-sided format, using @code{@@setchapternewpage odd} for 3506double-sided printing and no @code{@@setchapternewpage} command for 3507single-sided printing. 3508 3509 3510@node headings on off 3511@subsection The @code{@@headings} Command 3512@findex headings 3513 3514The @code{@@headings} command is rarely used. It specifies what kind of 3515page headings and footings to print on each page. Usually, this is 3516controlled by the @code{@@setchapternewpage} command. You need the 3517@code{@@headings} command only if the @code{@@setchapternewpage} command 3518does not do what you want, or if you want to turn off pre-defined page 3519headings prior to defining your own. Write an @code{@@headings} command 3520immediately after the @code{@@end titlepage} command.@refill 3521 3522You can use @code{@@headings} as follows:@refill 3523 3524@table @code 3525@item @@headings off 3526Turn off printing of page headings.@refill 3527 3528@item @@headings single 3529Turn on page headings appropriate for single-sided printing. 3530@refill 3531 3532@item @@headings double 3533@itemx @@headings on 3534Turn on page headings appropriate for double-sided printing. The two 3535commands, @code{@@headings on} and @code{@@headings double}, are 3536synonymous.@refill 3537 3538@item @@headings singleafter 3539@itemx @@headings doubleafter 3540Turn on @code{single} or @code{double} headings, respectively, after the 3541current page is output. 3542 3543@item @@headings on 3544Turn on page headings: @code{single} if @samp{@@setchapternewpage 3545on}, @code{double} otherwise. 3546@end table 3547 3548For example, suppose you write @code{@@setchapternewpage off} before the 3549@code{@@titlepage} command to tell @TeX{} to start a new chapter on the 3550same page as the end of the last chapter. This command also causes 3551@TeX{} to typeset page headers for single-sided printing. To cause 3552@TeX{} to typeset for double sided printing, write @code{@@headings 3553double} after the @code{@@end titlepage} command. 3554 3555You can stop @TeX{} from generating any page headings at all by 3556writing @code{@@headings off} on a line of its own immediately after the 3557line containing the @code{@@end titlepage} command, like this:@refill 3558 3559@example 3560@@end titlepage 3561@@headings off 3562@end example 3563 3564@noindent 3565The @code{@@headings off} command overrides the @code{@@end titlepage} 3566command, which would otherwise cause @TeX{} to print page 3567headings.@refill 3568 3569You can also specify your own style of page heading and footing. 3570@xref{Headings, , Page Headings}, for more information.@refill 3571 3572 3573@node Contents 3574@section Generating a Table of Contents 3575@cindex Table of contents 3576@cindex Contents, Table of 3577@cindex Short table of contents 3578@findex contents 3579@findex summarycontents 3580@findex shortcontents 3581 3582The @code{@@chapter}, @code{@@section}, and other structuring commands 3583(@pxref{Structuring}) supply the information to make up a 3584table of contents, but they do not cause an actual table to appear in 3585the manual. To do this, you must use the @code{@@contents} and/or 3586@code{@@summarycontents} command(s). 3587 3588@table @code 3589@item @@contents 3590Generates a table of contents in a printed manual, including all 3591chapters, sections, subsections, etc., as well as appendices and 3592unnumbered chapters. Headings generated by @code{@@majorheading}, 3593@code{@@chapheading}, and the other @code{@@@dots{}heading} commands 3594do not appear in the table of contents (@pxref{Structuring Command 3595Types}). 3596 3597@item @@shortcontents 3598@itemx @@summarycontents 3599(@code{@@summarycontents} is a synonym for @code{@@shortcontents}.) 3600 3601Generates a short or summary table of contents that lists only the 3602chapters, appendices, and unnumbered chapters. Sections, subsections 3603and subsubsections are omitted. Only a long manual needs a short 3604table of contents in addition to the full table of contents. 3605 3606@end table 3607 3608Both contents commands should be written on a line by themselves, and 3609are best placed near the beginning of the file, after the @code{@@end 3610titlepage} (@pxref{titlepage}). The contents commands automatically 3611generate a chapter-like heading at the top of the first table of 3612contents page, so don't include any sectioning command such as 3613@code{@@unnumbered} before them. 3614 3615Since an Info file uses menus instead of tables of contents, the Info 3616formatting commands ignore the contents commands. But the contents are 3617included in plain text output (generated by @code{makeinfo 3618--no-headers}), unless @code{makeinfo} is writing its output to standard 3619output. 3620 3621When @code{makeinfo} writes a short table of contents while producing 3622html output, the links in the short table of contents point to 3623corresponding entries in the full table of contents rather than the text 3624of the document. The links in the full table of contents point to the 3625main text of the document. 3626 3627In the past, the contents commands were sometimes placed at the end of 3628the file, after any indices and just before the @code{@@bye}, but we 3629no longer recommend this. 3630 3631@findex setcontentsaftertitlepage 3632@findex setshortcontentsaftertitlepage 3633@cindex Contents, after title page 3634@cindex Table of contents, after title page 3635However, since many existing Texinfo documents still do have the 3636@code{@@contents} at the end of the manual, if you are a user printing 3637a manual, you may wish to force the contents to be printed after the 3638title page. You can do this by specifying 3639@code{@@setcontentsaftertitlepage} and/or 3640@code{@@setshortcontentsaftertitlepage}. The first prints only the 3641main contents after the @code{@@end titlepage}; the second prints both 3642the short contents and the main contents. In either case, any 3643subsequent @code{@@contents} or @code{@@shortcontents} is ignored 3644(unless, erroneously, no @code{@@end titlepage} is ever encountered). 3645 3646You need to include the @code{@@set@dots{}contentsaftertitlepage} 3647commands early in the document (just after @code{@@setfilename}, for 3648example). We recommend using @command{texi2dvi} (@pxref{Format with 3649texi2dvi}) to specify this without altering the source file at all. For 3650example: 3651@example 3652texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi 3653@end example 3654 3655 3656@node The Top Node 3657@section The `Top' Node and Master Menu 3658@cindex Top node 3659@cindex Node, `Top' 3660 3661The `Top' node is the node in which a reader enters an Info manual. As 3662such, it should begin with the @code{@@insertcopying} command 3663(@pxref{Document Permissions}) to provide a brief description of the 3664manual (including the version number) and copying permissions, and end 3665with a master menu for the whole manual. Of course you should include 3666any other general information you feel a reader would find helpful. 3667 3668@findex top 3669It is also conventional to write an @code{@@top} sectioning command line 3670containing the title of the document immediately after the @code{@@node 3671Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning 3672Command}). 3673 3674The contents of the `Top' node should appear only in the online output; 3675none of it should appear in printed output, so enclose it between 3676@code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not 3677print either an @code{@@node} line or a menu; they appear only in Info; 3678strictly speaking, you are not required to enclose these parts between 3679@code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do 3680so. @xref{Conditionals, , Conditionally Visible Text}.) 3681 3682@menu 3683* Top Node Example:: 3684* Master Menu Parts:: 3685@end menu 3686 3687 3688@node Top Node Example 3689@subsection Top Node Example 3690 3691@cindex Top node example 3692 3693Here is an example of a Top node. 3694 3695@example 3696@group 3697@@ifnottex 3698@@node Top 3699@@top Sample Title 3700 3701@@insertcopying 3702@end group 3703 3704Additional general information. 3705 3706@group 3707@@menu 3708* First Chapter:: 3709* Second Chapter:: 3710@dots{} 3711* Index:: 3712@end group 3713@@end menu 3714@end example 3715 3716 3717@node Master Menu Parts 3718@subsection Parts of a Master Menu 3719@cindex Master menu 3720@cindex Menu, master 3721@cindex Parts of a master menu 3722 3723A @dfn{master menu} is a detailed main menu listing all the nodes in a 3724file. 3725 3726A master menu is enclosed in @code{@@menu} and @code{@@end menu} 3727commands and does not appear in the printed document. 3728 3729Generally, a master menu is divided into parts. 3730 3731@itemize @bullet 3732@item 3733The first part contains the major nodes in the Texinfo file: the nodes 3734for the chapters, chapter-like sections, and the appendices. 3735 3736@item 3737The second part contains nodes for the indices. 3738 3739@item 3740The third and subsequent parts contain a listing of the other, lower 3741level nodes, often ordered by chapter. This way, rather than go 3742through an intermediary menu, an inquirer can go directly to a 3743particular node when searching for specific information. These menu 3744items are not required; add them if you think they are a 3745convenience. If you do use them, put @code{@@detailmenu} before the 3746first one, and @code{@@end detailmenu} after the last; otherwise, 3747@code{makeinfo} will get confused. 3748@end itemize 3749 3750Each section in the menu can be introduced by a descriptive line. So 3751long as the line does not begin with an asterisk, it will not be 3752treated as a menu entry. (@xref{Writing a Menu}, for more 3753information.) 3754 3755For example, the master menu for this manual looks like the following 3756(but has many more entries): 3757 3758@example 3759@group 3760@@menu 3761* Copying Conditions:: Your rights. 3762* Overview:: Texinfo in brief. 3763@dots{} 3764@end group 3765@group 3766* Command and Variable Index:: 3767* Concept Index:: 3768@end group 3769 3770@group 3771@@detailmenu 3772--- The Detailed Node Listing --- 3773 3774Overview of Texinfo 3775 3776* Reporting Bugs:: @dots{} 3777@dots{} 3778@end group 3779 3780@group 3781Beginning a Texinfo File 3782 3783* Sample Beginning:: @dots{} 3784@dots{} 3785@@end detailmenu 3786@@end menu 3787@end group 3788@end example 3789 3790 3791@node Global Document Commands 3792@section Global Document Commands 3793@cindex Global Document Commands 3794 3795Besides the basic commands mentioned in the previous sections, here are 3796additional commands which affect the document as a whole. They are 3797generally all given before the Top node, if they are given at all. 3798 3799@menu 3800* documentdescription:: Document summary for the HTML output. 3801* setchapternewpage:: Start chapters on right-hand pages. 3802* paragraphindent:: Specify paragraph indentation. 3803* firstparagraphindent:: Suppress indentation of the first paragraph. 3804* exampleindent:: Specify environment indentation. 3805@end menu 3806 3807 3808@node documentdescription 3809@subsection @code{@@documentdescription}: Summary Text 3810@cindex Document description 3811@cindex Description of document 3812@cindex Summary of document 3813@cindex Abstract of document 3814@cindex <meta> HTML tag, and document description 3815@findex documentdescription 3816 3817When producing HTML output for a document, @command{makeinfo} writes a 3818@samp{<meta>} element in the @samp{<head>} to give some idea of the 3819content of the document. By default, this @dfn{description} is the title 3820of the document, taken from the @code{@@settitle} command 3821(@pxref{settitle}). To change this, use the @code{@@documentdescription} 3822environment, as in: 3823 3824@example 3825@@documentdescription 3826descriptive text. 3827@@end documentdescription 3828@end example 3829 3830@noindent 3831This will produce the following output in the @samp{<head>} of the HTML: 3832 3833@example 3834<meta name=description content="descriptive text."> 3835@end example 3836 3837@code{@@documentdescription} must be specified before the first node of 3838the document. 3839 3840 3841@node setchapternewpage 3842@subsection @code{@@setchapternewpage}: 3843@cindex Starting chapters 3844@cindex Pages, starting odd 3845@findex setchapternewpage 3846 3847In an officially bound book, text is usually printed on both sides of 3848the paper, chapters start on right-hand pages, and right-hand pages have 3849odd numbers. But in short reports, text often is printed only on one 3850side of the paper. Also in short reports, chapters sometimes do not 3851start on new pages, but are printed on the same page as the end of the 3852preceding chapter, after a small amount of vertical whitespace. 3853 3854You can use the @code{@@setchapternewpage} command with various 3855arguments to specify how @TeX{} should start chapters and whether it 3856should format headers for printing on one or both sides of the paper 3857(single-sided or double-sided printing). 3858 3859Write the @code{@@setchapternewpage} command at the beginning of a 3860line followed by its argument. 3861 3862For example, you would write the following to cause each chapter to 3863start on a fresh odd-numbered page: 3864 3865@example 3866@@setchapternewpage odd 3867@end example 3868 3869You can specify one of three alternatives with the 3870@code{@@setchapternewpage} command: 3871 3872@table @asis 3873 3874@item @code{@@setchapternewpage off} 3875Cause @TeX{} to typeset a new chapter on the same page as the last 3876chapter, after skipping some vertical whitespace. Also, cause @TeX{} to 3877format page headers for single-sided printing. 3878 3879@item @code{@@setchapternewpage on} 3880Cause @TeX{} to start new chapters on new pages and to format page 3881headers for single-sided printing. This is the form most often used for 3882short reports or personal printing. This is the default. 3883 3884@item @code{@@setchapternewpage odd} 3885Cause @TeX{} to start new chapters on new, odd-numbered pages 3886(right-handed pages) and to typeset for double-sided printing. This is 3887the form most often used for books and manuals. 3888@end table 3889 3890Texinfo does not have an @code{@@setchapternewpage even} command, 3891because there is no printing tradition of starting chapters or books on 3892an even-numbered page. 3893 3894If you don't like the default headers that @code{@@setchapternewpage} 3895sets, you can explicit control them with the @code{@@headings} command. 3896@xref{headings on off, , The @code{@@headings} Command}. 3897 3898At the beginning of a manual or book, pages are not numbered---for 3899example, the title and copyright pages of a book are not numbered. By 3900convention, table of contents and frontmatter pages are numbered with 3901roman numerals and not in sequence with the rest of the document. 3902 3903Since an Info file does not have pages, the @code{@@setchapternewpage} 3904command has no effect on it. 3905 3906We recommend not including any @code{@@setchapternewpage} command in 3907your manual sources at all, since the desired output is not intrinsic to 3908the document. For a particular hard copy run, if you don't want the 3909default option (no blank pages, same headers on all pages) use the 3910@option{--texinfo} option to @command{texi2dvi} to specify the output 3911you want. 3912 3913 3914@node paragraphindent 3915@subsection @code{@@paragraphindent}: Paragraph Indenting 3916@cindex Indenting paragraphs, control of 3917@cindex Paragraph indentation control 3918@findex paragraphindent 3919 3920The Texinfo processors may insert whitespace at the beginning of the 3921first line of each paragraph, thereby indenting that paragraph. You can 3922use the @code{@@paragraphindent} command to specify this indentation. 3923Write an @code{@@paragraphindent} command at the beginning of a line 3924followed by either @samp{asis} or a number: 3925 3926@example 3927@@paragraphindent @var{indent} 3928@end example 3929 3930The indentation is according to the value of @var{indent}: 3931 3932@table @asis 3933@item @code{asis} 3934Do not change the existing indentation (not implemented in @TeX{}). 3935 3936@item @code{none} 3937@itemx 0 3938Omit all indentation. 3939 3940@item @var{n} 3941Indent by @var{n} space characters in Info output, by @var{n} ems in 3942@TeX{}. 3943 3944@end table 3945 3946The default value of @var{indent} is 3. @code{@@paragraphindent} is 3947ignored for HTML output. 3948 3949It is best to write the @code{@@paragraphindent} command before the 3950end-of-header line at the beginning of a Texinfo file, so the region 3951formatting commands indent paragraphs as specified. @xref{Start of 3952Header}. 3953 3954A peculiarity of the @code{texinfo-format-buffer} and 3955@code{texinfo-format-region} commands is that they do not indent (nor 3956fill) paragraphs that contain @code{@@w} or @code{@@*} commands. 3957 3958 3959@node firstparagraphindent 3960@subsection @code{@@firstparagraphindent}: Indenting After Headings 3961@cindex First paragraph, suppressing indentation of 3962@cindex Suppressing first paragraph indentation 3963@cindex Preventing first paragraph indentation 3964@cindex Indenting, suppressing of first paragraph 3965@cindex Headings, indentation after 3966@findex firstparagraphindent 3967 3968As you can see in the present manual, the first paragraph in any 3969section is not indented by default. Typographically, indentation is a 3970paragraph separator, which means that it is unnecessary when a new 3971section begins. This indentation is controlled with the 3972@code{@@firstparagraphindent} command: 3973 3974@example 3975@@firstparagraphindent @var{word} 3976@end example 3977 3978The first paragraph after a heading is indented according to the value 3979of @var{word}: 3980 3981@table @asis 3982@item @code{none} 3983Prevents the first paragraph from being indented (default). 3984This option is ignored by @command{makeinfo} if 3985@code{@@paragraphindent asis} is in effect. 3986 3987@item @code{insert} 3988Include normal paragraph indentation. This respects the paragraph 3989indentation set by a @code{@@paragraphindent} command 3990(@pxref{paragraphindent}). 3991@end table 3992 3993For HTML and XML output, the @code{@@firstparagraphindent} setting is 3994ignored. 3995 3996It is best to write the @code{@@paragraphindent} command before the 3997end-of-header line at the beginning of a Texinfo file, so the region 3998formatting commands indent paragraphs as specified. @xref{Start of 3999Header}. 4000 4001 4002@node exampleindent 4003@subsection @code{@@exampleindent}: Environment Indenting 4004@cindex Indenting environments 4005@cindex Environment indentation 4006@cindex Example indentation 4007@findex exampleindent 4008 4009The Texinfo processors indent each line of @code{@@example} and similar 4010environments. You can use the @code{@@exampleindent} command to specify 4011this indentation. Write an @code{@@exampleindent} command at the 4012beginning of a line followed by either @samp{asis} or a number: 4013 4014@example 4015@@exampleindent @var{indent} 4016@end example 4017 4018@code{@@exampleindent} is ignored for HTML output. Otherwise, the 4019indentation is according to the value of @var{indent}: 4020 4021@table @asis 4022@item @code{asis} 4023Do not change the existing indentation (not implemented in @TeX{}). 4024 4025@item 0 4026Omit all indentation. 4027 4028@item @var{n} 4029Indent environments by @var{n} space characters in Info output, by 4030@var{n} ems in @TeX{}. 4031 4032@end table 4033 4034The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in} 4035in @TeX{}, which is somewhat less. (The reduction is to help @TeX{} 4036fit more characters onto physical lines.) 4037 4038It is best to write the @code{@@exampleindent} command before the 4039end-of-header line at the beginning of a Texinfo file, so the region 4040formatting commands indent paragraphs as specified. @xref{Start of 4041Header}. 4042 4043 4044@node Software Copying Permissions 4045@section Software Copying Permissions 4046@cindex Software copying permissions 4047@cindex Copying software 4048@cindex Distribution 4049@cindex License agreement 4050 4051If the Texinfo file has a section containing the ``General Public 4052License'' and the distribution information and a warranty disclaimer for 4053the software that is documented, we recommend placing this right after 4054the `Top' node. The General Public License is very important to Project 4055GNU software. It ensures that you and others will continue to have a 4056right to use and share the software. 4057 4058The copying and distribution information and the disclaimer are followed 4059by an introduction or else by the first chapter of the manual. 4060 4061@cindex Introduction, as part of file 4062Although an introduction is not a required part of a Texinfo file, it 4063is very helpful. Ideally, it should state clearly and concisely what 4064the file is about and who would be interested in reading it. In 4065general, an introduction would follow the licensing and distribution 4066information, although sometimes people put it earlier in the document. 4067 4068 4069@node Ending a File 4070@chapter Ending a Texinfo File 4071@cindex Ending a Texinfo file 4072@cindex Texinfo file ending 4073@cindex File ending 4074@findex bye 4075 4076The end of a Texinfo file should include commands to create indices, 4077and the @code{@@bye} command to mark the last line to be processed. 4078 4079For example: 4080 4081@example 4082@@node Index 4083@@unnumbered Index 4084 4085@@printindex cp 4086 4087@@bye 4088@end example 4089 4090@menu 4091* Printing Indices & Menus:: How to print an index in hardcopy and 4092 generate index menus in Info. 4093* File End:: How to mark the end of a file. 4094@end menu 4095 4096 4097@node Printing Indices & Menus 4098@section Printing Indices and Menus 4099@cindex Printing an index 4100@cindex Indices, printing and menus 4101@cindex Generating menus with indices 4102@cindex Menus generated with indices 4103 4104To print an index means to include it as part of a manual or Info file. 4105This does not happen automatically just because you use @code{@@cindex} 4106or other index-entry generating commands in the Texinfo file; those just 4107cause the raw data for the index to be accumulated. To generate an 4108index, you must include the @code{@@printindex} command at the place in 4109the document where you want the index to appear. Also, as part of the 4110process of creating a printed manual, you must run a program called 4111@code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a 4112sorted index file. The sorted index file is what is actually used to 4113print the index. 4114 4115Texinfo offers six separate types of predefined index, which suffice 4116in most cases. @xref{Indices}, for information on this, as well 4117defining your own new indices, combining indices, and, most 4118importantly advice on writing the actual index entries. This section 4119focuses on printing indices, which is done with the 4120@code{@@printindex} command. 4121 4122@findex printindex 4123@code{@@printindex} takes one argument, a two-letter index 4124abbreviation. It reads the corresponding sorted index file (for 4125printed output), and formats it appropriately into an index. 4126 4127The @code{@@printindex} command does not generate a chapter heading 4128for the index, since different manuals have different needs. 4129Consequently, you should precede the @code{@@printindex} command with 4130a suitable section or chapter command (usually @code{@@appendix} or 4131@code{@@unnumbered}) to supply the chapter heading and put the index 4132into the table of contents. Precede the chapter heading with an 4133@code{@@node} line as usual. 4134 4135For example: 4136 4137@smallexample 4138@group 4139@@node Variable Index 4140@@unnumbered Variable Index 4141 4142@@printindex vr 4143@end group 4144 4145@group 4146@@node Concept Index 4147@@unnumbered Concept Index 4148 4149@@printindex cp 4150@end group 4151@end smallexample 4152 4153If you have more than one index, we recommend placing the concept index last. 4154 4155@itemize 4156@item 4157In printed output, @code{@@printindex} produces a traditional 4158two-column index, with dot leaders between the index terms and page 4159numbers. 4160 4161@item 4162In Info output, @code{@@printindex} produces a special menu containing 4163the line number of the entry, relative to the start of the node. Info 4164readers can use this to go to the exact line of an entry, not just the 4165containing node. (Older Info readers will just go to the node.) 4166Here's an example: 4167 4168@smallexample 4169* First index entry: Top. (line 7) 4170@end smallexample 4171 4172@noindent The actual number of spaces is variable, to right-justify 4173the line number; it's been reduced here to make the line fit in the 4174printed manual. 4175 4176@item 4177In plain text output, @code{@@printindex} produces the same menu, but 4178the line numbers are relative to the start of the file, since that's 4179more convenient for that format. 4180 4181@item 4182In HTML and Docbook output, @code{@@printindex} produces links 4183to the index entries. 4184 4185@item 4186In XML output, it simply records the index to be printed. 4187@end itemize 4188 4189It's not possible to generate an index when writing to standard 4190output; @command{makeinfo} generates a warning in this case. 4191 4192 4193@node File End 4194@section @code{@@bye} File Ending 4195@findex bye 4196 4197An @code{@@bye} command terminates Texinfo processing. None of the 4198formatters read anything following @code{@@bye}. The @code{@@bye} 4199command should be on a line by itself. 4200 4201If you wish, you may follow the @code{@@bye} line with notes. These 4202notes will not be formatted and will not appear in either Info or a 4203printed manual; it is as if text after @code{@@bye} were within 4204@code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the 4205@code{@@bye} line with a local variables list for Emacs. 4206@xref{Compile-Command, , Using Local Variables and the Compile Command}, 4207for more information. 4208 4209 4210@node Structuring 4211@chapter Chapter Structuring 4212@cindex Chapter structuring 4213@cindex Structuring of chapters 4214 4215The @dfn{chapter structuring} commands divide a document into a hierarchy of 4216chapters, sections, subsections, and subsubsections. These commands 4217generate large headings; they also provide information for the table 4218of contents of a printed manual (@pxref{Contents, , Generating a Table 4219of Contents}).@refill 4220 4221The chapter structuring commands do not create an Info node structure, 4222so normally you should put an @code{@@node} command immediately before 4223each chapter structuring command (@pxref{Nodes}). The only time you 4224are likely to use the chapter structuring commands without using the 4225node structuring commands is if you are writing a document that 4226contains no cross references and will never be transformed into Info 4227format.@refill 4228 4229It is unlikely that you will ever write a Texinfo file that is 4230intended only as an Info file and not as a printable document. If you 4231do, you might still use chapter structuring commands to create a 4232heading at the top of each node---but you don't need to.@refill 4233 4234@menu 4235* Tree Structuring:: A manual is like an upside down tree @dots{} 4236* Structuring Command Types:: How to divide a manual into parts. 4237* makeinfo top:: The @code{@@top} command, part of the `Top' node. 4238* chapter:: 4239* unnumbered & appendix:: 4240* majorheading & chapheading:: 4241* section:: 4242* unnumberedsec appendixsec heading:: 4243* subsection:: 4244* unnumberedsubsec appendixsubsec subheading:: 4245* subsubsection:: Commands for the lowest level sections. 4246* Raise/lower sections:: How to change commands' hierarchical level. 4247@end menu 4248 4249 4250@node Tree Structuring 4251@section Tree Structure of Sections 4252@cindex Tree structuring 4253 4254A Texinfo file is usually structured like a book with chapters, 4255sections, subsections, and the like. This structure can be visualized 4256as a tree (or rather as an upside-down tree) with the root at the top 4257and the levels corresponding to chapters, sections, subsection, and 4258subsubsections.@refill 4259 4260Here is a diagram that shows a Texinfo file with three chapters, 4261each of which has two sections.@refill 4262 4263@example 4264@group 4265 Top 4266 | 4267 ------------------------------------- 4268 | | | 4269 Chapter 1 Chapter 2 Chapter 3 4270 | | | 4271 -------- -------- -------- 4272 | | | | | | 4273Section Section Section Section Section Section 4274 1.1 1.2 2.1 2.2 3.1 3.2 4275 4276@end group 4277@end example 4278 4279In a Texinfo file that has this structure, the beginning of Chapter 2 4280looks like this:@refill 4281 4282@example 4283@group 4284@@node Chapter 2, Chapter 3, Chapter 1, top 4285@@chapter Chapter 2 4286@end group 4287@end example 4288 4289The chapter structuring commands are described in the sections that 4290follow; the @code{@@node} and @code{@@menu} commands are described in 4291following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill 4292 4293 4294@node Structuring Command Types 4295@section Structuring Command Types 4296 4297The chapter structuring commands fall into four groups or series, each 4298of which contains structuring commands corresponding to the 4299hierarchical levels of chapters, sections, subsections, and 4300subsubsections.@refill 4301 4302The four groups are the @code{@@chapter} series, the 4303@code{@@unnumbered} series, the @code{@@appendix} series, and the 4304@code{@@heading} series.@refill 4305 4306Each command produces titles that have a different appearance on the 4307printed page or Info file; only some of the commands produce 4308titles that are listed in the table of contents of a printed book or 4309manual.@refill 4310 4311@itemize @bullet 4312@item 4313The @code{@@chapter} and @code{@@appendix} series of commands produce 4314numbered or lettered entries both in the body of a printed work and in 4315its table of contents.@refill 4316 4317@item 4318The @code{@@unnumbered} series of commands produce unnumbered entries 4319both in the body of a printed work and in its table of contents. The 4320@code{@@top} command, which has a special use, is a member of this 4321series (@pxref{makeinfo top, , @code{@@top}}). An @code{@@unnumbered} 4322section should be associated with a node and be a normal part of the 4323document structure. 4324 4325@item 4326The @code{@@heading} series of commands produce simple unnumbered 4327headings that do not appear in a table of contents, are not associated 4328with nodes, and cannot be cross-referenced. The heading commands 4329never start a new page. 4330 4331@item 4332The @code{@@majorheading} command is similar to @code{@@chapheading}, 4333except that it generates a larger vertical whitespace before the 4334heading. 4335 4336@item 4337When an @code{@@setchapternewpage} command says to do so, the 4338@code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands 4339start new pages in the printed manual; the @code{@@heading} commands 4340do not.@refill 4341@end itemize 4342 4343Here are the four groups of chapter structuring commands: 4344 4345@tex 4346{\globaldefs = 1 \smallfonts} 4347@end tex 4348 4349@multitable @columnfractions .19 .30 .29 .22 4350@item @tab @tab @tab No new page 4351@item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered} 4352@item In contents @tab In contents @tab In contents @tab Not in contents 4353@item @tab @code{@@top} @tab @tab @code{@@majorheading} 4354@item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading} 4355@item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading} 4356@item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading} 4357@item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading} 4358@end multitable 4359@tex 4360{\globaldefs = 1 \textfonts} 4361@end tex 4362 4363 4364@node makeinfo top 4365@section @code{@@top} 4366 4367The @code{@@top} command is a special sectioning command that you use 4368only after an @samp{@@node Top} line at the beginning of a Texinfo file. 4369The @code{@@top} command tells the @code{makeinfo} formatter which node 4370is the `Top' node, so it can use it as the root of the node tree if your 4371manual uses implicit node pointers. It has the same typesetting effect as 4372@code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered} 4373and @code{@@appendix}}). For detailed information, see @ref{makeinfo 4374top command, , The @code{@@top} Command}. 4375 4376The @code{@@top} node and its menu (if any) is conventionally wrapped in 4377an @code{@@ifnottex} conditional so that it will appear only in Info and 4378HTML output, not @TeX{}. 4379 4380 4381@node chapter 4382@comment node-name, next, previous, up 4383@section @code{@@chapter} 4384@findex chapter 4385 4386@code{@@chapter} identifies a chapter in the document. Write the 4387command at the beginning of a line and follow it on the same line by 4388the title of the chapter.@refill 4389 4390For example, this chapter in this manual is entitled ``Chapter 4391Structuring''; the @code{@@chapter} line looks like this:@refill 4392 4393@example 4394@@chapter Chapter Structuring 4395@end example 4396 4397In @TeX{}, the @code{@@chapter} command creates a chapter in the 4398document, specifying the chapter title. The chapter is numbered 4399automatically.@refill 4400 4401In Info, the @code{@@chapter} command causes the title to appear on a 4402line by itself, with a line of asterisks inserted underneath. Thus, 4403in Info, the above example produces the following output:@refill 4404 4405@example 4406Chapter Structuring 4407******************* 4408@end example 4409 4410@findex centerchap 4411Texinfo also provides a command @code{@@centerchap}, which is analogous 4412to @code{@@unnumbered}, but centers its argument in the printed output. 4413This kind of stylistic choice is not usually offered by Texinfo. 4414@c but the Hacker's Dictionary wanted it ... 4415 4416 4417@node unnumbered & appendix 4418@section @code{@@unnumbered} and @code{@@appendix} 4419@findex unnumbered 4420@findex appendix 4421 4422Use the @code{@@unnumbered} command to create a chapter that appears 4423in a printed manual without chapter numbers of any kind. Use the 4424@code{@@appendix} command to create an appendix in a printed manual 4425that is labelled by letter instead of by number.@refill 4426 4427For Info file output, the @code{@@unnumbered} and @code{@@appendix} 4428commands are equivalent to @code{@@chapter}: the title is printed on a 4429line by itself with a line of asterisks underneath. (@xref{chapter, , 4430@code{@@chapter}}.)@refill 4431 4432To create an appendix or an unnumbered chapter, write an 4433@code{@@appendix} or @code{@@unnumbered} command at the beginning of a 4434line and follow it on the same line by the title, as you would if you 4435were creating a chapter.@refill 4436 4437 4438@node majorheading & chapheading 4439@section @code{@@majorheading}, @code{@@chapheading} 4440@findex majorheading 4441@findex chapheading 4442 4443The @code{@@majorheading} and @code{@@chapheading} commands put 4444chapter-like headings in the body of a document.@refill 4445 4446However, neither command causes @TeX{} to produce a numbered heading 4447or an entry in the table of contents; and neither command causes 4448@TeX{} to start a new page in a printed manual.@refill 4449 4450In @TeX{}, an @code{@@majorheading} command generates a larger vertical 4451whitespace before the heading than an @code{@@chapheading} command but 4452is otherwise the same. 4453 4454In Info, 4455the @code{@@majorheading} and 4456@code{@@chapheading} commands are equivalent to 4457@code{@@chapter}: the title is printed on a line by itself with a line 4458of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill 4459 4460 4461@node section 4462@comment node-name, next, previous, up 4463@section @code{@@section} 4464@findex section 4465 4466In a printed manual, an @code{@@section} command identifies a 4467numbered section within a chapter. The section title appears in the 4468table of contents. In Info, an @code{@@section} command provides a 4469title for a segment of text, underlined with @samp{=}.@refill 4470 4471This section is headed with an @code{@@section} command and looks like 4472this in the Texinfo file:@refill 4473 4474@example 4475@@section @@code@{@@@@section@} 4476@end example 4477 4478To create a section, write the @code{@@section} command at the 4479beginning of a line and follow it on the same line by the section 4480title.@refill 4481 4482Thus, 4483 4484@example 4485@@section This is a section 4486@end example 4487 4488@noindent 4489produces 4490 4491@example 4492@group 4493This is a section 4494================= 4495@end group 4496@end example 4497 4498@noindent 4499in Info. 4500 4501 4502@node unnumberedsec appendixsec heading 4503@comment node-name, next, previous, up 4504@section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading} 4505@findex unnumberedsec 4506@findex appendixsec 4507@findex heading 4508 4509The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading} 4510commands are, respectively, the unnumbered, appendix-like, and 4511heading-like equivalents of the @code{@@section} command. 4512(@xref{section, , @code{@@section}}.)@refill 4513 4514@table @code 4515@item @@unnumberedsec 4516The @code{@@unnumberedsec} command may be used within an 4517unnumbered chapter or within a regular chapter or appendix to 4518provide an unnumbered section.@refill 4519 4520@item @@appendixsec 4521@itemx @@appendixsection 4522@code{@@appendixsection} is a longer spelling of the 4523@code{@@appendixsec} command; the two are synonymous.@refill 4524@findex appendixsection 4525 4526Conventionally, the @code{@@appendixsec} or @code{@@appendixsection} 4527command is used only within appendices.@refill 4528 4529@item @@heading 4530You may use the @code{@@heading} command anywhere you wish for a 4531section-style heading that will not appear in the table of contents.@refill 4532@end table 4533 4534 4535@node subsection 4536@comment node-name, next, previous, up 4537@section The @code{@@subsection} Command 4538@findex subsection 4539 4540Subsections are to sections as sections are to chapters. 4541(@xref{section, , @code{@@section}}.) In Info, subsection titles are 4542underlined with @samp{-}. For example,@refill 4543 4544@example 4545@@subsection This is a subsection 4546@end example 4547 4548@noindent 4549produces 4550 4551@example 4552@group 4553This is a subsection 4554-------------------- 4555@end group 4556@end example 4557 4558In a printed manual, subsections are listed in the table of contents 4559and are numbered three levels deep.@refill 4560 4561@node unnumberedsubsec appendixsubsec subheading 4562@comment node-name, next, previous, up 4563@section The @code{@@subsection}-like Commands 4564@cindex Subsection-like commands 4565@findex unnumberedsubsec 4566@findex appendixsubsec 4567@findex subheading 4568 4569The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and 4570@code{@@subheading} commands are, respectively, the unnumbered, 4571appendix-like, and heading-like equivalents of the @code{@@subsection} 4572command. (@xref{subsection, , @code{@@subsection}}.)@refill 4573 4574In Info, the @code{@@subsection}-like commands generate a title 4575underlined with hyphens. In a printed manual, an @code{@@subheading} 4576command produces a heading like that of a subsection except that it is 4577not numbered and does not appear in the table of contents. Similarly, 4578an @code{@@unnumberedsubsec} command produces an unnumbered heading like 4579that of a subsection and an @code{@@appendixsubsec} command produces a 4580subsection-like heading labelled with a letter and numbers; both of 4581these commands produce headings that appear in the table of 4582contents.@refill 4583 4584@node subsubsection 4585@section The `subsub' Commands 4586@cindex Subsub commands 4587@findex subsubsection 4588@findex unnumberedsubsubsec 4589@findex appendixsubsubsec 4590@findex subsubheading 4591 4592The fourth and lowest level sectioning commands in Texinfo are the 4593`subsub' commands. They are:@refill 4594 4595@table @code 4596@item @@subsubsection 4597Subsubsections are to subsections as subsections are to sections. 4598(@xref{subsection, , @code{@@subsection}}.) In a printed manual, 4599subsubsection titles appear in the table of contents and are numbered 4600four levels deep.@refill 4601 4602@item @@unnumberedsubsubsec 4603Unnumbered subsubsection titles appear in the table of contents of a 4604printed manual, but lack numbers. Otherwise, unnumbered 4605subsubsections are the same as subsubsections. In Info, unnumbered 4606subsubsections look exactly like ordinary subsubsections.@refill 4607 4608@item @@appendixsubsubsec 4609Conventionally, appendix commands are used only for appendices and are 4610lettered and numbered appropriately in a printed manual. They also 4611appear in the table of contents. In Info, appendix subsubsections look 4612exactly like ordinary subsubsections.@refill 4613 4614@item @@subsubheading 4615The @code{@@subsubheading} command may be used anywhere that you need 4616a small heading that will not appear in the table of contents. In 4617Info, subsubheadings look exactly like ordinary subsubsection 4618headings.@refill 4619@end table 4620 4621In Info, `subsub' titles are underlined with periods. 4622For example,@refill 4623 4624@example 4625@@subsubsection This is a subsubsection 4626@end example 4627 4628@noindent 4629produces 4630 4631@example 4632@group 4633This is a subsubsection 4634....................... 4635@end group 4636@end example 4637 4638 4639@node Raise/lower sections 4640@section @code{@@raisesections} and @code{@@lowersections} 4641@findex raisesections 4642@findex lowersections 4643@cindex Raising and lowering sections 4644@cindex Lowering and raising sections 4645@cindex Sections, raising and lowering 4646 4647The @code{@@raisesections} and @code{@@lowersections} commands 4648implicitly raise and lower the hierarchical level of following 4649chapters, sections and the other sectioning commands. 4650 4651That is, the @code{@@raisesections} command changes sections to 4652chapters, subsections to sections, and so on. Conversely, the 4653@code{@@lowersections} command changes chapters to sections, sections 4654to subsections, and so on. Thus, an @code{@@lowersections} command 4655cancels an @code{@@raisesections} command, and vice versa. 4656 4657@cindex Include files, and section levels 4658You can use @code{@@lowersections} to include text written as an outer 4659or standalone Texinfo file in another Texinfo file as an inner, 4660included file. Typical usage looks like this: 4661 4662@example 4663@@lowersections 4664@@include somefile.texi 4665@@raisesections 4666@end example 4667 4668@noindent (Without the @code{@@raisesections}, all the subsequent 4669sections in the document would be lowered.) 4670 4671If the included file being lowered has a @code{@@top} node, you'll 4672need to conditionalize its inclusion with a flag (@pxref{set value}). 4673 4674Another difficulty can arise with documents that use the (recommended) 4675feature of @command{makeinfo} for implicitly determining node 4676pointers. Since @command{makeinfo} must assume a hierarchically 4677organized document to determine the pointers, you cannot just 4678arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections} 4679commands in the document. The final result has to have menus that 4680take the raising and lowering into account. Therefore, as a practical 4681matter, you generally only want to raise or lower large chunks, 4682usually in external files as shown above. 4683 4684Repeated use of the commands continue to raise or lower the 4685hierarchical level a step at a time. An attempt to raise above 4686`chapter' reproduces chapter commands; an attempt to lower below 4687`subsubsection' reproduces subsubsection commands. Also, lowered 4688subsubsections and raised chapters will not work with 4689@command{makeinfo}'s feature of implicitly determining node pointers, 4690since the menu structure won't be correct. 4691 4692Write each @code{@@raisesections} and @code{@@lowersections} command 4693on a line of its own. 4694 4695 4696@node Nodes 4697@chapter Nodes 4698 4699@dfn{Nodes} are the primary segments of a Texinfo file. They do not 4700in and of themselves impose a hierarchical or any other kind of 4701structure on a file. Nodes contain @dfn{node pointers} that name 4702other nodes, and can contain @dfn{menus} which are lists of nodes. In 4703Info, the movement commands can carry you to a pointed-to node or to a 4704node listed in a menu. 4705 4706Node pointers and menus provide structure for Info files just as 4707chapters, sections, subsections, and the like, provide structure for 4708printed books. 4709 4710Because node names are used in cross-references, it is not desirable 4711to casually change them. Such name changes invalidate references from 4712other manuals, from mail archives, and so on. 4713 4714@menu 4715* Two Paths:: Different commands to structure 4716 Info output and printed output. 4717* Node Menu Illustration:: A diagram, and sample nodes and menus. 4718* node:: Creating nodes, in detail. 4719* makeinfo Pointer Creation:: Letting makeinfo determine node pointers. 4720* anchor:: Defining arbitrary cross-reference targets. 4721@end menu 4722 4723 4724@node Two Paths 4725@section Two Paths 4726 4727The node and menu commands and the chapter structuring commands are 4728technically independent of each other: 4729 4730@itemize @bullet 4731@item 4732In Info, node and menu commands provide structure. The chapter 4733structuring commands generate headings with different kinds of 4734underlining---asterisks for chapters, hyphens for sections, and so on; 4735they do nothing else.@refill 4736 4737@item 4738In @TeX{}, the chapter structuring commands generate chapter and section 4739numbers and tables of contents. The node and menu commands provide 4740information for cross references; they do nothing else.@refill 4741@end itemize 4742 4743You can use node pointers and menus to structure an Info file any way 4744you want; and you can write a Texinfo file so that its Info output has a 4745different structure than its printed output. However, virtually all 4746Texinfo files are written such that the structure for the Info output 4747corresponds to the structure for the printed output. It is neither 4748convenient nor understandable to the reader to do otherwise.@refill 4749 4750Generally, printed output is structured in a tree-like hierarchy in 4751which the chapters are the major limbs from which the sections branch 4752out. Similarly, node pointers and menus are organized to create a 4753matching structure in the Info output.@refill 4754 4755 4756@node Node Menu Illustration 4757@section Node and Menu Illustration 4758 4759Here is a copy of the diagram shown earlier that illustrates a Texinfo 4760file with three chapters, each of which contains two sections.@refill 4761 4762The ``root'' is at the top of the diagram and the ``leaves'' are at the 4763bottom. This is how such a diagram is drawn conventionally; it 4764illustrates an upside-down tree. For this reason, the root node is 4765called the `Top' node, and `Up' node pointers carry you closer to the 4766root.@refill 4767 4768@example 4769@group 4770 Top 4771 | 4772 ------------------------------------- 4773 | | | 4774 Chapter 1 Chapter 2 Chapter 3 4775 | | | 4776 -------- -------- -------- 4777 | | | | | | 4778Section Section Section Section Section Section 4779 1.1 1.2 2.1 2.2 3.1 3.2 4780@end group 4781@end example 4782 4783The fully-written command to start Chapter 2 would be this: 4784 4785@example 4786@group 4787@@node Chapter 2, Chapter 3, Chapter 1, Top 4788@@comment node-name, next, previous, up 4789@end group 4790@end example 4791 4792@noindent 4793This @code{@@node} line says that the name of this node is ``Chapter 47942'', the name of the `Next' node is ``Chapter 3'', the name of the 4795`Previous' node is ``Chapter 1'', and the name of the `Up' node is 4796``Top''. You can omit writing out these node names if your document is 4797hierarchically organized (@pxref{makeinfo Pointer Creation}), but the 4798pointer relationships still obtain. 4799 4800@quotation Note 4801@strong{Please Note:} `Next' refers to the next node at the same 4802hierarchical level in the manual, not necessarily to the next node 4803within the Texinfo file. In the Texinfo file, the subsequent node may 4804be at a lower level---a section-level node most often follows a 4805chapter-level node, for example. `Next' and `Previous' refer to nodes 4806at the @emph{same} hierarchical level. (The `Top' node contains the 4807exception to this rule. Since the `Top' node is the only node at that 4808level, `Next' refers to the first following node, which is almost always 4809a chapter or chapter-level node.)@refill 4810@end quotation 4811 4812To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter 48132. (@xref{Menus}.) You would write the menu just 4814before the beginning of Section 2.1, like this:@refill 4815 4816@example 4817@group 4818 @@menu 4819 * Sect. 2.1:: Description of this section. 4820 * Sect. 2.2:: 4821 @@end menu 4822@end group 4823@end example 4824 4825Write the node for Sect. 2.1 like this:@refill 4826 4827@example 4828@group 4829 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2 4830 @@comment node-name, next, previous, up 4831@end group 4832@end example 4833 4834In Info format, the `Next' and `Previous' pointers of a node usually 4835lead to other nodes at the same level---from chapter to chapter or from 4836section to section (sometimes, as shown, the `Previous' pointer points 4837up); an `Up' pointer usually leads to a node at the level above (closer 4838to the `Top' node); and a `Menu' leads to nodes at a level below (closer 4839to `leaves'). (A cross reference can point to a node at any level; 4840see @ref{Cross References}.)@refill 4841 4842Usually, an @code{@@node} command and a chapter structuring command are 4843used in sequence, along with indexing commands. (You may follow the 4844@code{@@node} line with a comment line that reminds you which pointer is 4845which.)@refill 4846 4847Here is the beginning of the chapter in this manual called ``Ending a 4848Texinfo File''. This shows an @code{@@node} line followed by a comment 4849line, an @code{@@chapter} line, and then by indexing lines.@refill 4850 4851@example 4852@group 4853@@node Ending a File, Structuring, Beginning a File, Top 4854@@comment node-name, next, previous, up 4855@@chapter Ending a Texinfo File 4856@@cindex Ending a Texinfo file 4857@@cindex Texinfo file ending 4858@@cindex File ending 4859@end group 4860@end example 4861 4862 4863@node node 4864@section The @code{@@node} Command 4865 4866@cindex Node, defined 4867@findex node 4868 4869A @dfn{node} is a segment of text that begins at an @code{@@node} 4870command and continues until the next @code{@@node} command. The 4871definition of node is different from that for chapter or section. A 4872chapter may contain sections and a section may contain subsections; 4873but a node cannot contain subnodes; the text of a node continues only 4874until the next @code{@@node} command in the file. A node usually 4875contains only one chapter structuring command, the one that follows 4876the @code{@@node} line. On the other hand, in printed output nodes 4877are used only for cross references, so a chapter or section may 4878contain any number of nodes. Indeed, a chapter usually contains 4879several nodes, one for each section, subsection, and 4880subsubsection. 4881 4882To create a node, write an @code{@@node} command at the beginning of a 4883line, and follow it with up to four arguments, separated by commas, on 4884the rest of the same line. The first argument is required; it is the 4885name of this node. The subsequent arguments are the names of the 4886`Next', `Previous', and `Up' pointers, in that order, and may be omitted 4887if your Texinfo document is hierarchically organized (@pxref{makeinfo 4888Pointer Creation}). 4889 4890You may insert spaces before each name if you wish; the spaces are 4891ignored. You must write the name of the node and (if present) the names 4892of the `Next', `Previous', and `Up' pointers all on the same line. 4893Otherwise, the formatters fail. (@inforef{Top, info, info}, for more 4894information about nodes in Info.) 4895 4896Usually, you write one of the chapter-structuring command lines 4897immediately after an @code{@@node} line---for example, an 4898@code{@@section} or @code{@@subsection} line. (@xref{Structuring 4899Command Types}.) 4900 4901@quotation Note 4902The GNU Emacs Texinfo mode updating commands work 4903only with Texinfo files in which @code{@@node} lines are followed by chapter 4904structuring lines. @xref{Updating Requirements}. 4905@end quotation 4906 4907@TeX{} uses @code{@@node} lines to identify the names to use for cross 4908references. For this reason, you must write @code{@@node} lines in a 4909Texinfo file that you intend to format for printing, even if you do not 4910intend to format it for Info. (Cross references, such as the one at the 4911end of this sentence, are made with @code{@@xref} and related commands; 4912see @ref{Cross References}.) 4913 4914@menu 4915* Node Names:: How to choose node and pointer names. 4916* Writing a Node:: How to write an @code{@@node} line. 4917* Node Line Tips:: Keep names short. 4918* Node Line Requirements:: Keep names unique, without @@-commands. 4919* First Node:: How to write a `Top' node. 4920* makeinfo top command:: How to use the @code{@@top} command. 4921@end menu 4922 4923 4924@node Node Names 4925@subsection Choosing Node and Pointer Names 4926 4927@cindex Node names, choosing 4928The name of a node identifies the node. The pointers enable 4929you to reach other nodes and consist simply of the names of those nodes. 4930 4931Normally, a node's `Up' pointer contains the name of the node whose menu 4932mentions that node. The node's `Next' pointer contains the name of the 4933node that follows that node in that menu and its `Previous' pointer 4934contains the name of the node that precedes it in that menu. When a 4935node's `Previous' node is the same as its `Up' node, both node pointers 4936name the same node. 4937 4938Usually, the first node of a Texinfo file is the `Top' node, and its 4939`Up' and `Previous' pointers point to the @file{dir} file, which 4940contains the main menu for all of Info. 4941 4942The `Top' node itself contains the main or master menu for the manual. 4943Also, it is helpful to include a brief description of the manual in the 4944`Top' node. @xref{First Node}, for information on how to write the 4945first node of a Texinfo file. 4946 4947Even when you explicitly specify all pointers, that does not mean you 4948can write the nodes in the Texinfo source file in an arbitrary order! 4949Because @TeX{} processes the file sequentially, irrespective of node 4950pointers, you must write the nodes in the order you wish them to appear 4951in the printed output. 4952 4953 4954@node Writing a Node 4955@subsection How to Write an @code{@@node} Line 4956@cindex Writing an @code{@@node} line 4957@cindex @code{@@node} line writing 4958@cindex Node line writing 4959 4960The easiest way to write an @code{@@node} line is to write @code{@@node} 4961at the beginning of a line and then the name of the node, like 4962this:@refill 4963 4964@example 4965@@node @var{node-name} 4966@end example 4967 4968If you are using GNU Emacs, you can use the update node commands 4969provided by Texinfo mode to insert the names of the pointers; or you 4970can leave the pointers out of the Texinfo file and let @code{makeinfo} 4971insert node pointers into the Info file it creates. (@xref{Texinfo 4972Mode}, and @ref{makeinfo Pointer Creation}.)@refill 4973 4974Alternatively, you can insert the `Next', `Previous', and `Up' 4975pointers yourself. If you do this, you may find it helpful to use the 4976Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts 4977@samp{@@node} and a comment line listing the names of the pointers in 4978their proper order. The comment line helps you keep track of which 4979arguments are for which pointers. This comment line is especially useful 4980if you are not familiar with Texinfo.@refill 4981 4982The template for a fully-written-out node line with `Next', `Previous', 4983and `Up' pointers looks like this:@refill 4984 4985@example 4986@@node @var{node-name}, @var{next}, @var{previous}, @var{up} 4987@end example 4988 4989If you wish, you can ignore @code{@@node} lines altogether in your first 4990draft and then use the @code{texinfo-insert-node-lines} command to 4991create @code{@@node} lines for you. However, we do not recommend this 4992practice. It is better to name the node itself at the same time that 4993you write a segment so you can easily make cross references. A large 4994number of cross references are an especially important feature of a good 4995Info file. 4996 4997After you have inserted an @code{@@node} line, you should immediately 4998write an @@-command for the chapter or section and insert its name. 4999Next (and this is important!), put in several index entries. Usually, 5000you will find at least two and often as many as four or five ways of 5001referring to the node in the index. Use them all. This will make it 5002much easier for people to find the node. 5003 5004 5005@node Node Line Tips 5006@subsection @code{@@node} Line Tips 5007 5008Here are three suggestions: 5009 5010@itemize @bullet 5011@item 5012Try to pick node names that are informative but short.@refill 5013 5014In the Info file, the file name, node name, and pointer names are all 5015inserted on one line, which may run into the right edge of the window. 5016(This does not cause a problem with Info, but is ugly.)@refill 5017 5018@item 5019Try to pick node names that differ from each other near the beginnings 5020of their names. This way, it is easy to use automatic name completion in 5021Info.@refill 5022 5023@item 5024By convention, node names are capitalized just as they would be for 5025section or chapter titles---initial and significant words are 5026capitalized; others are not.@refill 5027@end itemize 5028 5029 5030@node Node Line Requirements 5031@subsection @code{@@node} Line Requirements 5032 5033@cindex Node line requirements 5034@cindex Restrictions on node names 5035Here are several requirements for @code{@@node} lines: 5036 5037@itemize @bullet 5038@cindex Unique nodename requirement 5039@cindex Node name must be unique 5040@item 5041All the node names for a single Info file must be unique. 5042 5043Duplicates confuse the Info movement commands. This means, for 5044example, that if you end every chapter with a summary, you must name 5045each summary node differently. You cannot just call each one 5046``Summary''. You may, however, duplicate the titles of chapters, sections, 5047and the like. Thus you can end each chapter in a book with a section 5048called ``Summary'', so long as the node names for those sections are all 5049different. 5050 5051@item 5052A pointer name must be the name of a node. 5053 5054The node to which a pointer points may come before or after the 5055node containing the pointer. 5056 5057@cindex @@-commands in nodename 5058@cindex Node name, should not contain @@-commands 5059@item 5060@@-commands in node names are not allowed. This includes punctuation 5061characters that are escaped with a @samp{@@}, such as @code{@@} and 5062@code{@{}, and accent commands such as @samp{@@'}. (For a few cases 5063when this is useful, Texinfo has limited support for using 5064@w{@@-commands} in node names; see @ref{Pointer Validation}.) Perhaps 5065this limitation will be removed some day. 5066 5067@item 5068@cindex Colon in nodename 5069@cindex Comma in nodename 5070@cindex Parentheses in nodename 5071@cindex Period in nodename 5072@cindex Characters, invalid in node name 5073@cindex Invalid characters in node names 5074@cindex Node names, invalid characters in 5075Unfortunately, you cannot use periods, commas, colons or parentheses 5076within a node name; these confuse the Texinfo processors. Perhaps 5077this limitation will be removed some day, too. 5078 5079@need 700 5080For example, the following is a section title in this manual: 5081 5082@smallexample 5083@@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@} 5084@end smallexample 5085 5086@noindent 5087But the corresponding node name lacks the commas and the @@'s: 5088 5089@smallexample 5090unnumberedsec appendixsec heading 5091@end smallexample 5092 5093@cindex Case in node name 5094@item 5095Case is significant in node names. 5096 5097@cindex White space in node name 5098@cindex Spaces in node name 5099Spaces before and after names on the @samp{@@node} line are ignored, 5100but spaces ``inside'' a name are significant. For example: 5101 5102@example 5103@@node foo bar, 5104@@node foo bar , 5105@@node foo bar , 5106@end example 5107 5108@noindent all define the same node, @samp{foo bar}. References to the 5109node should all use that name, without the leading or trailing spaces, 5110but with the internal spaces. 5111@end itemize 5112 5113 5114@node First Node 5115@subsection The First Node 5116@cindex Top node is first 5117@cindex First node 5118 5119The first node of a Texinfo file is the @dfn{Top} node, except in an 5120included file (@pxref{Include Files}). The Top node should contain a 5121short summary, copying permissions, and a master menu. @xref{The Top 5122Node}, for more information on the Top node contents and examples. 5123 5124Here is a description of the node pointers to be used in the Top node: 5125 5126@itemize @bullet 5127 5128@item 5129@cindex Up node of Top node 5130@cindex (dir) as Up node of Top node 5131The Top node (which must be named @samp{top} or @samp{Top}) should have 5132as its `Up' node the name of a node in another file, where there is a 5133menu that leads to this file. Specify the file name in parentheses. 5134 5135Usually, all Info files are installed in the same Info directory tree; 5136in this case, use @samp{(dir)} as the parent of the Top node; this is 5137short for @samp{(dir)top}, and specifies the Top node in the @file{dir} 5138file, which contains the main menu for the Info system as a whole. 5139 5140@item 5141@cindex Previous node of Top node 5142On the other hand, do not define the `Previous' node of the Top node to 5143be @samp{(dir)}, as it causes confusing behavior for users: if you are 5144in the Top node and hits @key{DEL} to go backwards, you wind up in the 5145middle of the some other entry in the @file{dir} file, which has nothing 5146to do with what you were reading. 5147 5148@item 5149@cindex Next node of Top node 5150The `Next' node of the Top node should be the first chapter in your 5151document. 5152 5153@end itemize 5154 5155@xref{Installing an Info File}, for more information about installing 5156an Info file in the @file{info} directory. 5157 5158For concreteness, here is an example with explicit pointers (which you 5159can maintain automatically with the texinfo mode commands): 5160 5161Or you can leave the pointers off entirely and let the tools implicitly 5162define them. This is recommended. Thus: 5163 5164@example 5165@@node Top 5166@end example 5167 5168 5169@node makeinfo top command 5170@subsection The @code{@@top} Sectioning Command 5171@findex top @r{(@@-command)} 5172 5173A special sectioning command, @code{@@top} should be used with the 5174@code{@@node Top} line. The @code{@@top} sectioning command tells 5175@code{makeinfo} that it marks the `Top' node in the file. It provides 5176the information that @code{makeinfo} needs to insert node pointers 5177automatically. Write the @code{@@top} command at the beginning of the 5178line immediately following the @code{@@node Top} line. Write the title 5179on the remaining part of the same line as the @code{@@top} command. 5180 5181In Info, the @code{@@top} sectioning command causes the title to appear 5182on a line by itself, with a line of asterisks inserted underneath, as 5183other sectioning commands do. 5184 5185In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} 5186sectioning command is merely a synonym for @code{@@unnumbered}. 5187Neither of these formatters require an @code{@@top} command, and do 5188nothing special with it. You can use @code{@@chapter} or 5189@code{@@unnumbered} after the @code{@@node Top} line when you use 5190these formatters. Also, you can use @code{@@chapter} or 5191@code{@@unnumbered} when you use the Texinfo updating commands to 5192create or update pointers and menus. 5193 5194Thus, in practice, a Top node starts like this: 5195 5196@example 5197@@node Top 5198@@top Your Manual Title 5199@end example 5200 5201 5202@node makeinfo Pointer Creation 5203@section Creating Pointers with @code{makeinfo} 5204@cindex Creating pointers with @code{makeinfo} 5205@cindex Pointer creation with @code{makeinfo} 5206@cindex Automatic pointer creation with @code{makeinfo} 5207 5208The @code{makeinfo} program has a feature for automatically determining 5209node pointers for a hierarchically organized document. 5210 5211When you take advantage of this feature, you do not need to write the 5212`Next', `Previous', and `Up' pointers after the name of a node. 5213However, you must write a sectioning command, such as @code{@@chapter} 5214or @code{@@section}, on the line immediately following each truncated 5215@code{@@node} line (except that comment lines may intervene). 5216 5217In addition, you must follow the `Top' @code{@@node} line with a line 5218beginning with @code{@@top} to mark the `Top' node in the 5219file. @xref{makeinfo top, , @code{@@top}}. 5220 5221Finally, you must write the name of each node (except for the `Top' 5222node) in a menu that is one or more hierarchical levels above the 5223node's hierarchical level. 5224 5225This implicit node pointer insertion feature in @code{makeinfo} 5226relieves you from the need to update menus and pointers manually or 5227with Texinfo mode commands. (@xref{Updating Nodes and Menus}.) 5228 5229In most cases, you will want to take advantage of this feature and not 5230redundantly specify node pointers. However, Texinfo documents are not 5231required to be organized hierarchically or in fact to contain 5232sectioning commands at all (for example, if you never intend the 5233document to be printed). The special procedure for handling the short 5234text before a menu (@pxref{Menus}) also disables this 5235feature, for that group of nodes. In those cases, you will need to 5236explicitly specify the pointers. 5237 5238 5239@node anchor 5240@section @code{@@anchor}: Defining Arbitrary Cross-reference Targets 5241 5242@findex anchor 5243@cindex Anchors 5244@cindex Cross-reference targets, arbitrary 5245@cindex Targets for cross-references, arbitrary 5246 5247An @dfn{anchor} is a position in your document, labeled so that 5248cross-references can refer to it, just as they can to nodes. You create 5249an anchor with the @code{@@anchor} command, and give the label as a 5250normal brace-delimited argument. For example: 5251 5252@example 5253This marks the @@anchor@{x-spot@}spot. 5254@dots{} 5255@@xref@{x-spot,,the spot@}. 5256@end example 5257 5258@noindent produces: 5259 5260@example 5261This marks the spot. 5262@dots{} 5263See [the spot], page 1. 5264@end example 5265 5266As you can see, the @code{@@anchor} command itself produces no output. 5267This example defines an anchor `x-spot' just before the word `spot'. 5268You can refer to it later with an @code{@@xref} or other cross-reference 5269command, as shown. @xref{Cross References}, for details on the 5270cross-reference commands. 5271 5272It is best to put @code{@@anchor} commands just before the position you 5273wish to refer to; that way, the reader's eye is led on to the correct 5274text when they jump to the anchor. You can put the @code{@@anchor} 5275command on a line by itself if that helps readability of the source. 5276Spaces are always ignored after @code{@@anchor}. 5277 5278Anchor names and node names may not conflict. Anchors and nodes are 5279given similar treatment in some ways; for example, the @code{goto-node} 5280command in standalone Info takes either an anchor name or a node name as 5281an argument. (@xref{goto-node,,,info-stnd,GNU Info}.) 5282 5283 5284@node Menus 5285@chapter Menus 5286@cindex Menus 5287@findex menu 5288 5289@dfn{Menus} contain pointers to subordinate nodes. In online output, 5290you use menus to go to such nodes. Menus have no effect in printed 5291manuals and do not appear in them. 5292 5293A node with a menu should not contain much text. If you find yourself 5294writing a lot of before a menu, we generally recommend moving most of 5295the text into a new subnode---all but a paragraph or two. Otherwise, 5296a reader with a terminal that displays only a few lines may miss the 5297menu and its associated text. As a practical matter, it is best to 5298locate a menu within 20 or so lines of the beginning of the node. 5299 5300@menu 5301* Menu Location:: Menus go at the ends of short nodes. 5302* Writing a Menu:: What is a menu? 5303* Menu Parts:: A menu entry has three parts. 5304* Less Cluttered Menu Entry:: Two part menu entry. 5305* Menu Example:: Two and three part menu entries. 5306* Other Info Files:: How to refer to a different Info file. 5307@end menu 5308 5309 5310@node Menu Location 5311@section Menu Location 5312@cindex Menu location 5313@cindex Location of menus 5314 5315A menu must be located at the end of a node, without any regular text 5316or additional commands between the @code{@@end menu} and the beginning 5317of the next node. (As a consequence, there may be at most one menu in 5318a node.) 5319 5320@cindex Info format, and menus 5321This is actually a useful restriction, since a reader who uses the 5322menu could easily miss any such text. Technically, it is necessary 5323because in Info format, there is no marker for the end of a menu, so 5324Info-reading programs would have no way to know when the menu ends and 5325normal text resumes. 5326 5327@cindex Hierarchical documents, and menus 5328Technically, menus can carry you to any node, regardless of the 5329structure of the document; even to nodes in a different Info file. 5330However, we do not recommend ever making use of this, because the 5331@command{makeinfo} implicit pointer creation feature (@pxref{makeinfo 5332Pointer Creation}) and GNU Emacs Texinfo mode updating commands work 5333only to create menus of subordinate nodes in a hierarchically 5334structured document. Instead, use cross references to refer to 5335arbitrary nodes. 5336 5337In the past, we recommended using a @samp{@@heading} command within an 5338@code{@@ifinfo} conditional instead of the normal sectioning commands 5339after a very short node with a menu. This had the advantage of making 5340the printed output look better, because there was no very short text 5341between two headings on the page. But aside from not working with 5342@command{makeinfo}'s implicit pointer creation, it also makes the XML 5343output incorrect, since it does not reflect the true document 5344structure. So, unfortunately we can no longer recommend this. 5345 5346 5347@node Writing a Menu 5348@section Writing a Menu 5349@cindex Writing a menu 5350@cindex Menu writing 5351 5352A menu consists of an @code{@@menu} command on a line by itself 5353followed by menu entry lines or menu comment lines and then by an 5354@code{@@end menu} command on a line by itself. 5355 5356A menu looks like this: 5357 5358@example 5359@group 5360@@menu 5361Larger Units of Text 5362 5363* Files:: All about handling files. 5364* Multiples: Buffers. Multiple buffers; editing 5365 several files at once. 5366@@end menu 5367@end group 5368@end example 5369 5370In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu 5371entry}. (Note the space after the asterisk.) A line that does not 5372start with an @w{@samp{* }} may also appear in a menu. Such a line is 5373not a menu entry but is a menu comment line that appears in the Info 5374file. In the example above, the line @samp{Larger Units of Text} is a 5375menu comment line; the two lines starting with @w{@samp{* }} are menu 5376@cindex Spaces, in menus 5377entries. Space characters in a menu are preserved as-is; this allows 5378you to format the menu as you wish. 5379 5380 5381@node Menu Parts 5382@section The Parts of a Menu 5383@cindex Parts of a menu 5384@cindex Menu parts 5385@cindex @code{@@menu} parts 5386 5387A menu entry has three parts, only the second of which is required: 5388 5389@enumerate 5390@item 5391The menu entry name (optional). 5392 5393@item 5394The name of the node (required). 5395 5396@item 5397A description of the item (optional). 5398@end enumerate 5399 5400The template for a menu entry looks like this:@refill 5401 5402@example 5403* @var{menu-entry-name}: @var{node-name}. @var{description} 5404@end example 5405 5406Follow the menu entry name with a single colon and follow the node name 5407with tab, comma, period, or newline.@refill 5408 5409In Info, a user selects a node with the @kbd{m} (@code{Info-menu}) 5410command. The menu entry name is what the user types after the @kbd{m} 5411command.@refill 5412 5413The third part of a menu entry is a descriptive phrase or sentence. 5414Menu entry names and node names are often short; the description 5415explains to the reader what the node is about. A useful description 5416complements the node name rather than repeats it. The description, 5417which is optional, can spread over two or more lines; if it does, some 5418authors prefer to indent the second line while others prefer to align it 5419with the first (and all others). It's up to you. 5420 5421 5422@node Less Cluttered Menu Entry 5423@comment node-name, next, previous, up 5424@section Less Cluttered Menu Entry 5425@cindex Two part menu entry 5426@cindex Double-colon menu entries 5427@cindex Menu entries with two colons 5428@cindex Less cluttered menu entry 5429@cindex Uncluttered menu entry 5430 5431When the menu entry name and node name are the same, you can write 5432the name immediately after the asterisk and space at the beginning of 5433the line and follow the name with two colons.@refill 5434 5435@need 800 5436For example, write 5437 5438@example 5439* Name:: @var{description} 5440@end example 5441 5442@need 800 5443@noindent 5444instead of 5445 5446@example 5447* Name: Name. @var{description} 5448@end example 5449 5450You should use the node name for the menu entry name whenever possible, 5451since it reduces visual clutter in the menu.@refill 5452 5453@node Menu Example 5454@comment node-name, next, previous, up 5455@section A Menu Example 5456@cindex Menu example 5457@cindex Example menu 5458 5459A menu looks like this in Texinfo:@refill 5460 5461@example 5462@group 5463@@menu 5464* menu entry name: Node name. A short description. 5465* Node name:: This form is preferred. 5466@@end menu 5467@end group 5468@end example 5469 5470@need 800 5471@noindent 5472This produces: 5473 5474@example 5475@group 5476* menu: 5477 5478* menu entry name: Node name. A short description. 5479* Node name:: This form is preferred. 5480@end group 5481@end example 5482 5483@need 700 5484Here is an example as you might see it in a Texinfo file:@refill 5485 5486@example 5487@group 5488@@menu 5489Larger Units of Text 5490 5491* Files:: All about handling files. 5492* Multiples: Buffers. Multiple buffers; editing 5493 several files at once. 5494@@end menu 5495@end group 5496@end example 5497 5498@need 800 5499@noindent 5500This produces: 5501 5502@example 5503@group 5504* menu: 5505Larger Units of Text 5506 5507* Files:: All about handling files. 5508* Multiples: Buffers. Multiple buffers; editing 5509 several files at once. 5510@end group 5511@end example 5512 5513In this example, the menu has two entries. @samp{Files} is both a menu 5514entry name and the name of the node referred to by that name. 5515@samp{Multiples} is the menu entry name; it refers to the node named 5516@samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it 5517appears in the menu, but is not an entry.@refill 5518 5519Since no file name is specified with either @samp{Files} or 5520@samp{Buffers}, they must be the names of nodes in the same Info file 5521(@pxref{Other Info Files, , Referring to Other Info Files}).@refill 5522 5523@node Other Info Files 5524@comment node-name, next, previous, up 5525@section Referring to Other Info Files 5526@cindex Referring to other Info files 5527@cindex Nodes in other Info files 5528@cindex Other Info files' nodes 5529@cindex Going to other Info files' nodes 5530@cindex Info; other files' nodes 5531 5532You can create a menu entry that enables a reader in Info to go to a 5533node in another Info file by writing the file name in parentheses just 5534before the node name. In this case, you should use the three-part menu 5535entry format, which saves the reader from having to type the file 5536name.@refill 5537 5538@need 800 5539The format looks like this:@refill 5540 5541@example 5542@group 5543@@menu 5544* @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description} 5545* @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description} 5546@@end menu 5547@end group 5548@end example 5549 5550For example, to refer directly to the @samp{Outlining} and 5551@samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a 5552menu like this:@refill 5553 5554@example 5555@group 5556@@menu 5557* Outlining: (emacs)Outline Mode. The major mode for 5558 editing outlines. 5559* Rebinding: (emacs)Rebinding. How to redefine the 5560 meaning of a key. 5561@@end menu 5562@end group 5563@end example 5564 5565If you do not list the node name, but only name the file, then Info 5566presumes that you are referring to the `Top' node.@refill 5567 5568The @file{dir} file that contains the main menu for Info has menu 5569entries that list only file names. These take you directly to the `Top' 5570nodes of each Info document. (@xref{Installing an Info File}.) 5571 5572@need 700 5573For example: 5574 5575@example 5576@group 5577* Info: (info). Documentation browsing system. 5578* Emacs: (emacs). The extensible, self-documenting 5579 text editor. 5580@end group 5581@end example 5582 5583@noindent 5584(The @file{dir} top level directory for the Info system is an Info file, 5585not a Texinfo file, but a menu entry looks the same in both types of 5586file.)@refill 5587 5588The GNU Emacs Texinfo mode menu updating commands only work with nodes 5589within the current buffer, so you cannot use them to create menus that 5590refer to other files. You must write such menus by hand. 5591 5592 5593@node Cross References 5594@chapter Cross References 5595@cindex Making cross references 5596@cindex Cross references 5597@cindex References 5598 5599@dfn{Cross references} are used to refer the reader to other parts of the 5600same or different Texinfo files. In Texinfo, nodes and anchors are the 5601places to which cross references can refer. 5602 5603@menu 5604* References:: What cross references are for. 5605* Cross Reference Commands:: A summary of the different commands. 5606* Cross Reference Parts:: A cross reference has several parts. 5607* xref:: Begin a reference with `See' @dots{} 5608* Top Node Naming:: How to refer to the beginning of another file. 5609* ref:: A reference for the last part of a sentence. 5610* pxref:: How to write a parenthetical cross reference. 5611* inforef:: How to refer to an Info-only file. 5612* uref:: How to refer to a uniform resource locator. 5613@end menu 5614 5615@node References 5616@section What References Are For 5617 5618Often, but not always, a printed document should be designed so that 5619it can be read sequentially. People tire of flipping back and forth 5620to find information that should be presented to them as they need 5621it.@refill 5622 5623However, in any document, some information will be too detailed for 5624the current context, or incidental to it; use cross references to 5625provide access to such information. Also, an online help system or a 5626reference manual is not like a novel; few read such documents in 5627sequence from beginning to end. Instead, people look up what they 5628need. For this reason, such creations should contain many cross 5629references to help readers find other information that they may not 5630have read.@refill 5631 5632In a printed manual, a cross reference results in a page reference, 5633unless it is to another manual altogether, in which case the cross 5634reference names that manual.@refill 5635 5636In Info, a cross reference results in an entry that you can follow 5637using the Info @samp{f} command. (@inforef{Help-Xref, Following 5638cross-references, info}.) 5639 5640The various cross reference commands use nodes (or anchors, 5641@pxref{anchor,,@code{@@anchor}}) to define cross reference locations. 5642This is evident in Info, in which a cross reference takes you to the 5643specified location. @TeX{} also uses nodes to define cross reference 5644locations, but the action is less obvious. When @TeX{} generates a DVI 5645file, it records each node's page number and uses the page numbers in making 5646references. Thus, if you are writing a manual that will only be 5647printed, and will not be used online, you must nonetheless write 5648@code{@@node} lines to name the places to which you make cross 5649references.@refill 5650 5651@need 800 5652@node Cross Reference Commands 5653@comment node-name, next, previous, up 5654@section Different Cross Reference Commands 5655@cindex Different cross reference commands 5656 5657There are four different cross reference commands:@refill 5658 5659@table @code 5660@item @@xref 5661Used to start a sentence in the printed manual saying @w{`See @dots{}'} 5662or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}. 5663 5664@item @@ref 5665Used within or, more often, at the end of a sentence; same as 5666@code{@@xref} for Info; produces just the reference in the printed 5667manual without a preceding `See'.@refill 5668 5669@item @@pxref 5670Used within parentheses to make a reference that suits both an Info 5671file and a printed book. Starts with a lower case `see' within the 5672printed manual. (@samp{p} is for `parenthesis'.)@refill 5673 5674@item @@inforef 5675Used to make a reference to an Info file for which there is no printed 5676manual.@refill 5677@end table 5678 5679@noindent 5680(The @code{@@cite} command is used to make references to books and 5681manuals for which there is no corresponding Info file and, therefore, 5682no node to which to point. @xref{cite, , @code{@@cite}}.)@refill 5683 5684@node Cross Reference Parts 5685@comment node-name, next, previous, up 5686@section Parts of a Cross Reference 5687@cindex Cross reference parts 5688@cindex Parts of a cross reference 5689 5690A cross reference command requires only one argument, which is the 5691name of the node to which it refers. But a cross reference command 5692may contain up to four additional arguments. By using these 5693arguments, you can provide a cross reference name for Info, a topic 5694description or section title for the printed output, the name of a 5695different Info file, and the name of a different printed 5696manual.@refill 5697 5698Here is a simple cross reference example:@refill 5699 5700@example 5701@@xref@{Node name@}. 5702@end example 5703 5704@noindent 5705which produces 5706 5707@example 5708*Note Node name::. 5709@end example 5710 5711@noindent 5712and 5713 5714@quotation 5715See Section @var{nnn} [Node name], page @var{ppp}. 5716@end quotation 5717 5718@need 700 5719Here is an example of a full five-part cross reference:@refill 5720 5721@example 5722@group 5723@@xref@{Node name, Cross Reference Name, Particular Topic, 5724info-file-name, A Printed Manual@}, for details. 5725@end group 5726@end example 5727 5728@noindent 5729which produces 5730 5731@example 5732*Note Cross Reference Name: (info-file-name)Node name, 5733for details. 5734@end example 5735 5736@noindent 5737in Info and 5738 5739@quotation 5740See section ``Particular Topic'' in @i{A Printed Manual}, for details. 5741@end quotation 5742 5743@noindent 5744in a printed book. 5745 5746The five possible arguments for a cross reference are:@refill 5747 5748@enumerate 5749@item 5750The node or anchor name (required). This is the location to which the 5751cross reference takes you. In a printed document, the location of the 5752node provides the page reference only for references within the same 5753document.@refill 5754 5755@item 5756The cross reference name for the Info reference, if it is to be different 5757from the node name. If you include this argument, it becomes 5758the first part of the cross reference. It is usually omitted.@refill 5759 5760@item 5761A topic description or section name. Often, this is the title of the 5762section. This is used as the name of the reference in the printed 5763manual. If omitted, the node name is used.@refill 5764 5765@item 5766The name of the Info file in which the reference is located, if it is 5767different from the current file. You need not include any @samp{.info} 5768suffix on the file name, since Info readers try appending it 5769automatically. 5770 5771@item 5772The name of a printed manual from a different Texinfo file.@refill 5773@end enumerate 5774 5775The template for a full five argument cross reference looks like 5776this:@refill 5777 5778@example 5779@group 5780@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, 5781@var{info-file-name}, @var{printed-manual-title}@}. 5782@end group 5783@end example 5784 5785Cross references with one, two, three, four, and five arguments are 5786described separately following the description of @code{@@xref}.@refill 5787 5788Write a node name in a cross reference in exactly the same way as in 5789the @code{@@node} line, including the same capitalization; otherwise, the 5790formatters may not find the reference.@refill 5791 5792You can write cross reference commands within a paragraph, but note 5793how Info and @TeX{} format the output of each of the various commands: 5794write @code{@@xref} at the beginning of a sentence; write 5795@code{@@pxref} only within parentheses, and so on.@refill 5796 5797@node xref 5798@comment node-name, next, previous, up 5799@section @code{@@xref} 5800@findex xref 5801@cindex Cross references using @code{@@xref} 5802@cindex References using @code{@@xref} 5803 5804The @code{@@xref} command generates a cross reference for the 5805beginning of a sentence. The Info formatting commands convert it into 5806an Info cross reference, which the Info @samp{f} command can use to 5807bring you directly to another node. The @TeX{} typesetting commands 5808convert it into a page reference, or a reference to another book or 5809manual.@refill 5810 5811@menu 5812* Reference Syntax:: What a reference looks like and requires. 5813* One Argument:: @code{@@xref} with one argument. 5814* Two Arguments:: @code{@@xref} with two arguments. 5815* Three Arguments:: @code{@@xref} with three arguments. 5816* Four and Five Arguments:: @code{@@xref} with four and five arguments. 5817@end menu 5818 5819@node Reference Syntax 5820@subsection What a Reference Looks Like and Requires 5821 5822Most often, an Info cross reference looks like this:@refill 5823 5824@example 5825*Note @var{node-name}::. 5826@end example 5827 5828@noindent 5829or like this 5830 5831@example 5832*Note @var{cross-reference-name}: @var{node-name}. 5833@end example 5834 5835@noindent 5836In @TeX{}, a cross reference looks like this: 5837 5838@quotation 5839See Section @var{section-number} [@var{node-name}], page @var{page}. 5840@end quotation 5841 5842@noindent 5843or like this 5844 5845@quotation 5846See Section @var{section-number} [@var{title-or-topic}], page @var{page}. 5847@end quotation 5848 5849The @code{@@xref} command does not generate a period or comma to end 5850the cross reference in either the Info file or the printed output. 5851You must write that period or comma yourself; otherwise, Info will not 5852recognize the end of the reference. (The @code{@@pxref} command works 5853differently. @xref{pxref, , @code{@@pxref}}.)@refill 5854 5855@quotation Caution 5856A period or comma @strong{must} follow the closing 5857brace of an @code{@@xref}. It is required to terminate the cross 5858reference. This period or comma will appear in the output, both in 5859the Info file and in the printed manual.@refill 5860@end quotation 5861 5862@code{@@xref} must refer to an Info node by name. Use @code{@@node} 5863to define the node (@pxref{Writing a Node}).@refill 5864 5865@code{@@xref} is followed by several arguments inside braces, separated by 5866commas. Whitespace before and after these commas is ignored.@refill 5867 5868A cross reference requires only the name of a node; but it may contain 5869up to four additional arguments. Each of these variations produces a 5870cross reference that looks somewhat different.@refill 5871 5872@quotation Note 5873Commas separate arguments in a cross reference; 5874avoid including them in the title or other part lest the formatters 5875mistake them for separators.@refill 5876@end quotation 5877 5878@node One Argument 5879@subsection @code{@@xref} with One Argument 5880 5881The simplest form of @code{@@xref} takes one argument, the name of 5882another node in the same Info file. The Info formatters produce 5883output that the Info readers can use to jump to the reference; @TeX{} 5884produces output that specifies the page and section number for you.@refill 5885 5886@need 700 5887@noindent 5888For example, 5889 5890@example 5891@@xref@{Tropical Storms@}. 5892@end example 5893 5894@noindent 5895produces 5896 5897@example 5898*Note Tropical Storms::. 5899@end example 5900 5901@noindent 5902and 5903 5904@quotation 5905See Section 3.1 [Tropical Storms], page 24. 5906@end quotation 5907 5908@noindent 5909(Note that in the preceding example the closing brace is followed by a 5910period.)@refill 5911 5912You can write a clause after the cross reference, like this:@refill 5913 5914@example 5915@@xref@{Tropical Storms@}, for more info. 5916@end example 5917 5918@noindent 5919which produces 5920 5921@example 5922*Note Tropical Storms::, for more info. 5923@end example 5924 5925@noindent 5926and 5927 5928@quotation 5929See Section 3.1 [Tropical Storms], page 24, for more info. 5930@end quotation 5931 5932@noindent 5933(Note that in the preceding example the closing brace is followed by a 5934comma, and then by the clause, which is followed by a period.)@refill 5935 5936@node Two Arguments 5937@subsection @code{@@xref} with Two Arguments 5938 5939With two arguments, the second is used as the name of the Info cross 5940reference, while the first is still the name of the node to which the 5941cross reference points.@refill 5942 5943@need 750 5944@noindent 5945The template is like this: 5946 5947@example 5948@@xref@{@var{node-name}, @var{cross-reference-name}@}. 5949@end example 5950 5951@need 700 5952@noindent 5953For example, 5954 5955@example 5956@@xref@{Electrical Effects, Lightning@}. 5957@end example 5958 5959@noindent 5960produces: 5961 5962@example 5963*Note Lightning: Electrical Effects. 5964@end example 5965 5966@noindent 5967and 5968 5969@quotation 5970See Section 5.2 [Electrical Effects], page 57. 5971@end quotation 5972 5973@noindent 5974(Note that in the preceding example the closing brace is followed by a 5975period; and that the node name is printed, not the cross reference name.) 5976 5977You can write a clause after the cross reference, like this:@refill 5978 5979@example 5980@@xref@{Electrical Effects, Lightning@}, for more info. 5981@end example 5982 5983@noindent 5984which produces 5985@example 5986*Note Lightning: Electrical Effects, for more info. 5987@end example 5988 5989@noindent 5990and 5991 5992@quotation 5993See Section 5.2 [Electrical Effects], page 57, for more info. 5994@end quotation 5995 5996@noindent 5997(Note that in the preceding example the closing brace is followed by a 5998comma, and then by the clause, which is followed by a period.)@refill 5999 6000@node Three Arguments 6001@subsection @code{@@xref} with Three Arguments 6002 6003A third argument replaces the node name in the @TeX{} output. The third 6004argument should be the name of the section in the printed output, or 6005else state the topic discussed by that section. Often, you will want to 6006use initial upper case letters so it will be easier to read when the 6007reference is printed. Use a third argument when the node name is 6008unsuitable because of syntax or meaning.@refill 6009 6010Remember to avoid placing a comma within the title or topic section of 6011a cross reference, or within any other section. The formatters divide 6012cross references into arguments according to the commas; a comma 6013within a title or other section will divide it into two arguments. In 6014a reference, you need to write a title such as ``Clouds, Mist, and 6015Fog'' without the commas.@refill 6016 6017Also, remember to write a comma or period after the closing brace of an 6018@code{@@xref} to terminate the cross reference. In the following 6019examples, a clause follows a terminating comma.@refill 6020 6021 6022@need 750 6023@noindent 6024The template is like this: 6025 6026@example 6027@group 6028@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}. 6029@end group 6030@end example 6031 6032@need 700 6033@noindent 6034For example, 6035 6036@example 6037@group 6038@@xref@{Electrical Effects, Lightning, Thunder and Lightning@}, 6039for details. 6040@end group 6041@end example 6042 6043@noindent 6044produces 6045 6046@example 6047*Note Lightning: Electrical Effects, for details. 6048@end example 6049 6050@noindent 6051and 6052 6053@quotation 6054See Section 5.2 [Thunder and Lightning], page 57, for details. 6055@end quotation 6056 6057If a third argument is given and the second one is empty, then the 6058third argument serves both. (Note how two commas, side by side, mark 6059the empty second argument.)@refill 6060 6061@example 6062@group 6063@@xref@{Electrical Effects, , Thunder and Lightning@}, 6064for details. 6065@end group 6066@end example 6067 6068@noindent 6069produces 6070 6071@example 6072*Note Thunder and Lightning: Electrical Effects, for details. 6073@end example 6074 6075@noindent 6076and 6077 6078@quotation 6079See Section 5.2 [Thunder and Lightning], page 57, for details. 6080@end quotation 6081 6082As a practical matter, it is often best to write cross references with 6083just the first argument if the node name and the section title are the 6084same, and with the first and third arguments if the node name and title 6085are different.@refill 6086 6087Here are several examples from @cite{The GNU Awk User's Guide}:@refill 6088 6089@smallexample 6090@@xref@{Sample Program@}. 6091@@xref@{Glossary@}. 6092@@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}. 6093@@xref@{Close Output, , Closing Output Files and Pipes@}, 6094 for more information. 6095@@xref@{Regexp, , Regular Expressions as Patterns@}. 6096@end smallexample 6097 6098@node Four and Five Arguments 6099@subsection @code{@@xref} with Four and Five Arguments 6100 6101In a cross reference, a fourth argument specifies the name of another 6102Info file, different from the file in which the reference appears, and 6103a fifth argument specifies its title as a printed manual.@refill 6104 6105Remember that a comma or period must follow the closing brace of an 6106@code{@@xref} command to terminate the cross reference. In the 6107following examples, a clause follows a terminating comma.@refill 6108 6109@need 800 6110@noindent 6111The template is: 6112 6113@example 6114@group 6115@@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}, 6116@var{info-file-name}, @var{printed-manual-title}@}. 6117@end group 6118@end example 6119 6120@need 700 6121@noindent 6122For example, 6123 6124@example 6125@@xref@{Electrical Effects, Lightning, Thunder and Lightning, 6126weather, An Introduction to Meteorology@}, for details. 6127@end example 6128 6129@noindent 6130produces 6131 6132@example 6133*Note Lightning: (weather)Electrical Effects, for details. 6134@end example 6135 6136@noindent 6137The name of the Info file is enclosed in parentheses and precedes 6138the name of the node. 6139 6140@noindent 6141In a printed manual, the reference looks like this:@refill 6142 6143@quotation 6144See section ``Thunder and Lightning'' in @i{An Introduction to 6145Meteorology}, for details. 6146@end quotation 6147 6148@noindent 6149The title of the printed manual is typeset in italics; and the 6150reference lacks a page number since @TeX{} cannot know to which page a 6151reference refers when that reference is to another manual.@refill 6152 6153Often, you will leave out the second argument when you use the long 6154version of @code{@@xref}. In this case, the third argument, the topic 6155description, will be used as the cross reference name in Info.@refill 6156 6157@noindent 6158The template looks like this: 6159 6160@example 6161@@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name}, 6162@var{printed-manual-title}@}, for details. 6163@end example 6164 6165@noindent 6166which produces 6167 6168@example 6169*Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details. 6170@end example 6171 6172@noindent 6173and 6174 6175@quotation 6176See section @var{title-or-topic} in @var{printed-manual-title}, for details. 6177@end quotation 6178 6179@need 700 6180@noindent 6181For example, 6182 6183@example 6184@@xref@{Electrical Effects, , Thunder and Lightning, 6185weather, An Introduction to Meteorology@}, for details. 6186@end example 6187 6188@noindent 6189produces 6190 6191@example 6192@group 6193*Note Thunder and Lightning: (weather)Electrical Effects, 6194for details. 6195@end group 6196@end example 6197 6198@noindent 6199and 6200 6201@quotation 6202See section ``Thunder and Lightning'' in @i{An Introduction to 6203Meteorology}, for details. 6204@end quotation 6205 6206On rare occasions, you may want to refer to another Info file that 6207is within a single printed manual---when multiple Texinfo files are 6208incorporated into the same @TeX{} run but make separate Info files. 6209In this case, you need to specify only the fourth argument, and not 6210the fifth.@refill 6211 6212@node Top Node Naming 6213@section Naming a `Top' Node 6214@cindex Naming a `Top' Node in references 6215@cindex @samp{@r{Top}} node naming for references 6216 6217In a cross reference, you must always name a node. This means that in 6218order to refer to a whole manual, you must identify the `Top' node by 6219writing it as the first argument to the @code{@@xref} command. (This 6220is different from the way you write a menu entry; see @ref{Other Info 6221Files, , Referring to Other Info Files}.) At the same time, to 6222provide a meaningful section topic or title in the printed cross 6223reference (instead of the word `Top'), you must write an appropriate 6224entry for the third argument to the @code{@@xref} command. 6225@refill 6226 6227@noindent 6228Thus, to make a cross reference to @cite{The GNU Make Manual}, 6229write:@refill 6230 6231@example 6232@@xref@{Top, , Overview, make, The GNU Make Manual@}. 6233@end example 6234 6235@noindent 6236which produces 6237 6238@example 6239*Note Overview: (make)Top. 6240@end example 6241 6242@noindent 6243and 6244 6245@quotation 6246See section ``Overview'' in @i{The GNU Make Manual}. 6247@end quotation 6248 6249@noindent 6250In this example, @samp{Top} is the name of the first node, and 6251@samp{Overview} is the name of the first section of the manual. 6252 6253 6254@node ref 6255@section @code{@@ref} 6256@cindex Cross references using @code{@@ref} 6257@cindex References using @code{@@ref} 6258@findex ref 6259 6260@code{@@ref} is nearly the same as @code{@@xref} except that it does 6261not generate a `See' in the printed output, just the reference itself. 6262This makes it useful as the last part of a sentence. 6263 6264@noindent For example, 6265 6266@cindex Hurricanes 6267@example 6268For more information, see @@ref@{Hurricanes@}. 6269@end example 6270 6271@noindent produces (in Info): 6272 6273@example 6274For more information, see *Note Hurricanes::. 6275@end example 6276 6277@noindent and (in printed output): 6278 6279@quotation 6280For more information, see Section 8.2 [Hurricanes], page 123. 6281@end quotation 6282 6283The @code{@@ref} command sometimes tempts writers to express 6284themselves in a manner that is suitable for a printed manual but looks 6285awkward in the Info format. Bear in mind that your audience will be 6286using both the printed and the Info format. For example: 6287 6288@cindex Sea surges 6289@example 6290Sea surges are described in @@ref@{Hurricanes@}. 6291@end example 6292 6293@noindent looks ok in the printed output: 6294 6295@quotation 6296Sea surges are described in Section 6.7 [Hurricanes], page 72. 6297@end quotation 6298 6299@noindent but is awkward to read in Info: 6300 6301@example 6302Sea surges are described in *Note Hurricanes::. 6303@end example 6304 6305As a general rule, you should write a period or comma immediately 6306after an @code{@@ref} command with two or more arguments. 6307 6308If there is no such following punctuation, @command{makeinfo} will 6309generate a (grammatically incorrect) period in the Info output; 6310otherwise, the cross-reference would fail completely, due to the 6311current syntax of Info format. 6312 6313 6314@node pxref 6315@section @code{@@pxref} 6316@cindex Cross references using @code{@@pxref} 6317@cindex References using @code{@@pxref} 6318@findex pxref 6319 6320The parenthetical reference command, @code{@@pxref}, is nearly the 6321same as @code{@@xref}, but you use it @emph{only} inside parentheses 6322and you do @emph{not} type a comma or period (or anything else) after 6323the command's closing brace. The command differs from @code{@@xref} 6324in two ways: 6325 6326@enumerate 6327@item 6328@TeX{} typesets the reference for the printed manual with a lower case 6329`see' rather than an upper case `See'.@refill 6330 6331@item 6332The Info formatting commands automatically end the reference with a 6333closing colon or period.@refill 6334@end enumerate 6335 6336Because one type of formatting automatically inserts closing 6337punctuation and the other does not, you should use @code{@@pxref} 6338@emph{only} inside parentheses as part of another sentence. Also, you 6339yourself should not insert punctuation after the reference (or any 6340other text), as you do with @code{@@xref}. In the Info 6341output, such text would follow a period, which is grammatically wrong. 6342 6343@code{@@pxref} is designed so that the output looks right and works 6344right between parentheses both in printed output and in an Info file. 6345In a printed manual, a closing comma or period should not follow a 6346cross reference within parentheses; such punctuation is wrong. But in 6347an Info file, suitable closing punctuation must follow the cross 6348reference so Info can recognize its end. @code{@@pxref} spares you 6349the need to use complicated methods to put a terminator into one form 6350of the output and not the other.@refill 6351 6352@noindent 6353With one argument, a parenthetical cross reference looks like 6354this:@refill 6355 6356@cindex Flooding 6357@example 6358@dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{} 6359@end example 6360 6361@need 800 6362@noindent 6363which produces 6364 6365@example 6366@group 6367@dots{} storms cause flooding (*Note Hurricanes::) @dots{} 6368@end group 6369@end example 6370 6371@noindent 6372and 6373 6374@quotation 6375@dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{} 6376@end quotation 6377 6378With two arguments, a parenthetical cross reference has this 6379template:@refill 6380 6381@example 6382@dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{} 6383@end example 6384 6385@noindent 6386which produces 6387 6388@example 6389@dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{} 6390@end example 6391 6392@noindent 6393and 6394 6395@need 1500 6396@quotation 6397@dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{} 6398@end quotation 6399 6400@code{@@pxref} can be used with up to five arguments just like 6401@code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill 6402 6403@quotation Caution 6404Use @code{@@pxref} only as a parenthetical 6405reference. Do not try to use @code{@@pxref} as a clause in a sentence. 6406It will look bad in either the Info file, the printed output, or 6407both.@refill 6408@end quotation 6409 6410Parenthetical cross references look best at the ends of sentences. 6411Although they technically work in the middle of a sentence, that 6412location breaks up the flow of reading. 6413 6414 6415@node inforef 6416@section @code{@@inforef} 6417@cindex Cross references using @code{@@inforef} 6418@cindex References using @code{@@inforef} 6419@findex inforef 6420 6421@code{@@inforef} is used for making cross references to Info 6422documents---even from a printed manual. This might be because you 6423want to refer to conditional @code{@@ifinfo} text 6424(@pxref{Conditionals}), or because printed output is not available 6425(perhaps because there is no Texinfo source), among other 6426possibilities. 6427 6428The command takes either two or three arguments, in the following 6429order:@refill 6430 6431@enumerate 6432@item 6433The node name. 6434 6435@item 6436The cross reference name (optional). 6437 6438@item 6439The Info file name. 6440@end enumerate 6441 6442@noindent 6443Separate the arguments with commas, as with @code{@@xref}. Also, you 6444must terminate the reference with a comma or period after the 6445@samp{@}}, as you do with @code{@@xref}.@refill 6446 6447@noindent 6448The template is: 6449 6450@example 6451@@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@}, 6452@end example 6453 6454@need 800 6455@noindent 6456For example, 6457 6458@example 6459@group 6460@@inforef@{Advanced, Advanced Info commands, info@}, 6461for more information. 6462@end group 6463@end example 6464 6465@need 800 6466@noindent 6467produces (in Info): 6468 6469@example 6470@group 6471*Note Advanced Info commands: (info)Advanced, 6472for more information. 6473@end group 6474@end example 6475 6476@need 800 6477@noindent 6478and (in the printed output): 6479 6480@quotation 6481See Info file @file{info}, node @samp{Advanced}, for more information. 6482@end quotation 6483 6484(This particular example is not realistic, since the Info manual is 6485written in Texinfo, so all formats are available.) 6486 6487The converse of @code{@@inforef} is @code{@@cite}, which is used to 6488refer to printed works for which no Info form exists. @xref{cite, , 6489@code{@@cite}}. 6490 6491 6492@node uref 6493@section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}} 6494@findex uref 6495@cindex Uniform resource locator, referring to 6496@cindex URL, referring to 6497 6498@cindex @code{href}, producing HTML 6499@code{@@uref} produces a reference to a uniform resource locator (url). 6500It takes one mandatory argument, the url, and two optional arguments 6501which control the text that is displayed. In HTML output, @code{@@uref} 6502produces a link you can follow. 6503 6504@code{@@url} is a synonym for @code{@@uref}. Originally, @code{@@url} 6505had the meaning of @code{@@indicateurl} 6506(@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it 6507was misused the vast majority of the time. So we've changed the 6508definitions. 6509 6510The second argument, if specified, is the text to display (the default 6511is the url itself); in Info and DVI output, but not in HTML output, the 6512url is also output. 6513 6514@cindex Man page, reference to 6515The third argument, if specified, is the text to display, but in this 6516case the url is @emph{not} output in any format. This is useful when 6517the text is already sufficiently referential, as in a man page. If 6518the third argument is given, the second argument is ignored. 6519 6520If the url is long enough to cause problems with line breaking, you 6521may find it useful to insert @code{@@/} at places where a line break 6522would be acceptable (after @samp{/} characters, for instance). This 6523tells @TeX{} to allow (but not force) a line break at those places. 6524@xref{Line Breaks}. 6525 6526Here is an example of the simple one argument form, where the url is 6527both the target and the text of the link: 6528 6529@example 6530The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}. 6531@end example 6532 6533@noindent produces: 6534@display 6535The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}. 6536@end display 6537 6538 6539An example of the two-argument form: 6540@example 6541The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@} 6542holds programs and texts. 6543@end example 6544 6545@noindent produces: 6546@display 6547The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site} 6548holds programs and texts. 6549@end display 6550 6551@noindent that is, the Info output is this: 6552@example 6553The official GNU ftp site (ftp://ftp.gnu.org/gnu) 6554holds programs and texts. 6555@end example 6556 6557@noindent and the HTML output is this: 6558@example 6559The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a> 6560holds programs and texts. 6561@end example 6562 6563 6564An example of the three-argument form: 6565@example 6566The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{} 6567@end example 6568 6569@noindent produces: 6570@display 6571The @uref{/man.cgi/1/ls,,ls(1)} program @dots{} 6572@end display 6573 6574@noindent but with HTML: 6575@example 6576The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{} 6577@end example 6578 6579To merely indicate a url without creating a link people can follow, use 6580@code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}). 6581 6582Some people prefer to display url's in the unambiguous format: 6583 6584@display 6585<URL:http://@var{host}/@var{path}> 6586@end display 6587 6588@noindent 6589@cindex <URL: convention, not used 6590You can use this form in the input file if you wish. We feel it's not 6591necessary to include the @samp{<URL:} and @samp{>} in the output, 6592since any software that tries to detect url's in text already has to 6593detect them without the @samp{<URL:} to be useful. 6594 6595 6596@node Marking Text 6597@chapter Marking Words and Phrases 6598@cindex Paragraph, marking text within 6599@cindex Marking words and phrases 6600@cindex Words and phrases, marking them 6601@cindex Marking text within a paragraph 6602@cindex Text, marking up 6603 6604In Texinfo, you can mark words and phrases in a variety of ways. 6605The Texinfo formatters use this information to determine how to 6606highlight the text. 6607You can specify, for example, whether a word or phrase is a 6608defining occurrence, a metasyntactic variable, or a symbol used in a 6609program. Also, you can emphasize text, in several different ways. 6610 6611@menu 6612* Indicating:: How to indicate definitions, files, etc. 6613* Emphasis:: How to emphasize text. 6614@end menu 6615 6616 6617@node Indicating 6618@section Indicating Definitions, Commands, etc. 6619@cindex Highlighting text 6620@cindex Indicating commands, definitions, etc. 6621 6622Texinfo has commands for indicating just what kind of object a piece of 6623text refers to. For example, metasyntactic variables are marked by 6624@code{@@var}, and code by @code{@@code}. Since the pieces of text are 6625labelled by commands that tell what kind of object they are, it is easy 6626to change the way the Texinfo formatters prepare such text. (Texinfo is 6627an @emph{intentional} formatting language rather than a @emph{typesetting} 6628formatting language.)@refill 6629 6630For example, in a printed manual, 6631code is usually illustrated in a typewriter font; 6632@code{@@code} tells @TeX{} to typeset this text in this font. But it 6633would be easy to change the way @TeX{} highlights code to use another 6634font, and this change would not affect how keystroke examples are 6635highlighted. If straight typesetting commands were used in the body 6636of the file and you wanted to make a change, you would need to check 6637every single occurrence to make sure that you were changing code and 6638not something else that should not be changed.@refill 6639 6640@menu 6641* Useful Highlighting:: Highlighting provides useful information. 6642* code:: Indicating program code. 6643* kbd:: Showing keyboard input. 6644* key:: Specifying keys. 6645* samp:: Indicating a literal sequence of characters. 6646* verb:: Indicating a verbatim sequence of characters. 6647* var:: Indicating metasyntactic variables. 6648* env:: Indicating environment variables. 6649* file:: Indicating file names. 6650* command:: Indicating command names. 6651* option:: Indicating option names. 6652* dfn:: Specifying definitions. 6653* cite:: Referring to books not in the Info system. 6654* abbr:: Indicating abbreviations. 6655* acronym:: Indicating acronyms. 6656* indicateurl:: Indicating an example URL. 6657* email:: Indicating an electronic mail address. 6658@end menu 6659 6660 6661@node Useful Highlighting 6662@subsection Highlighting Commands are Useful 6663 6664The highlighting commands can be used to extract useful information 6665from the file, such as lists of functions or file names. It is 6666possible, for example, to write a program in Emacs Lisp (or a keyboard 6667macro) to insert an index entry after every paragraph that contains 6668words or phrases marked by a specified command. You could do this to 6669construct an index of functions if you had not already made the 6670entries.@refill 6671 6672The commands serve a variety of purposes:@refill 6673 6674@table @code 6675@item @@code@{@var{sample-code}@} 6676Indicate text that is a literal example of a piece of a program. 6677@xref{code,,@code{@@code}}. 6678 6679@item @@kbd@{@var{keyboard-characters}@} 6680Indicate keyboard input. 6681@xref{kbd,,@code{@@kbd}}. 6682 6683@item @@key@{@var{key-name}@} 6684Indicate the conventional name for a key on a keyboard. 6685@xref{key,,@code{@@key}}. 6686 6687@item @@samp@{@var{text}@} 6688Indicate text that is a literal example of a sequence of characters. 6689@xref{samp,,@code{@@samp}}. 6690 6691@item @@verb@{@var{text}@} 6692Write a verbatim sequence of characters. 6693@xref{verb,,@code{@@verb}}. 6694 6695@item @@var@{@var{metasyntactic-variable}@} 6696Indicate a metasyntactic variable. 6697@xref{var,,@code{@@var}}. 6698 6699@item @@env@{@var{environment-variable}@} 6700Indicate an environment variable. 6701@xref{env,,@code{@@kenv}}. 6702 6703@item @@file@{@var{file-name}@} 6704Indicate the name of a file. 6705@xref{file,,@code{@@file}}. 6706 6707@item @@command@{@var{command-name}@} 6708Indicate the name of a command. 6709@xref{command,,@code{@@command}}. 6710 6711@item @@option@{@var{option}@} 6712Indicate a command-line option. 6713@xref{option,,@code{@@option}}. 6714 6715@item @@dfn@{@var{term}@} 6716Indicate the introductory or defining use of a term. 6717@xref{dfn,,@code{@@dfn}}. 6718 6719@item @@cite@{@var{reference}@} 6720Indicate the name of a book. 6721@xref{cite,,@code{@@cite}}. 6722 6723@item @@abbr@{@var{abbreviation}@} 6724Indicate an abbreviation. 6725 6726@item @@acronym@{@var{acronym}@} 6727Indicate an acronym. 6728@xref{acronym,,@code{@@acronym}}. 6729 6730@item @@indicateurl@{@var{uniform-resource-locator}@} 6731Indicate an example (that is, nonfunctional) uniform resource locator. 6732@xref{indicateurl,,@code{@@indicateurl}}. (Use @code{@@url} 6733(@pxref{uref,,@code{@@url}}) for live url's.) 6734 6735@item @@email@{@var{email-address}[, @var{displayed-text}]@} 6736Indicate an electronic mail address. 6737@xref{email,,@code{@@email}}. 6738 6739@ignore 6740@item @@ctrl@{@var{ctrl-char}@} 6741Use for an @sc{ascii} control character.@refill 6742@end ignore 6743@end table 6744 6745 6746@node code 6747@subsection @code{@@code}@{@var{sample-code}@} 6748@findex code 6749 6750@cindex Syntactic tokens, indicating 6751Use the @code{@@code} command to indicate text that is a piece of a 6752program and which consists of entire syntactic tokens. Enclose the 6753text in braces. 6754 6755@cindex Expressions in a program, indicating 6756@cindex Keywords, indicating 6757@cindex Reserved words, indicating 6758Thus, you should use @code{@@code} for an expression in a program, for 6759the name of a variable or function used in a program, or for a 6760keyword in a programming language. 6761 6762Use @code{@@code} for command names in languages that resemble 6763programming languages, such as Texinfo. For example, @code{@@code} and 6764@code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and 6765@samp{@@code@{@@@@samp@}} in the Texinfo source, respectively. 6766 6767@cindex Case, not altering in @code{@@code} 6768It is incorrect to alter the case of a word inside an @code{@@code} 6769command when it appears at the beginning of a sentence. Most computer 6770languages are case sensitive. In C, for example, @code{Printf} is 6771different from the identifier @code{printf}, and most likely is a 6772misspelling of it. Even in languages which are not case sensitive, it 6773is confusing to a human reader to see identifiers spelled in different 6774ways. Pick one spelling and always use that. If you do not want to 6775start a sentence with a command name written all in lower case, you 6776should rearrange the sentence. 6777 6778In the printed manual, @code{@@code} causes @TeX{} to typeset the 6779argument in a typewriter face. In the Info file, it causes the Info 6780formatting commands to use single quotation marks around the text. 6781 6782@need 700 6783For example, 6784 6785@example 6786The function returns @@code@{nil@}. 6787@end example 6788 6789@noindent 6790produces this in the printed manual: 6791 6792@quotation 6793The function returns @code{nil}. 6794@end quotation 6795 6796@iftex 6797@noindent 6798and this in the Info file: 6799@example 6800The function returns `nil'. 6801@end example 6802@end iftex 6803 6804Here are some cases for which it is preferable not to use @code{@@code}: 6805 6806@itemize @bullet 6807@item 6808For shell command names such as @command{ls} (use @code{@@command}). 6809 6810@item 6811For shell options such as @samp{-c} when such options stand alone (use 6812@code{@@option}). 6813 6814@item 6815Also, an entire shell command often looks better if written using 6816@code{@@samp} rather than @code{@@code}. In this case, the rule is to 6817choose the more pleasing format. 6818 6819@item 6820For environment variable such as @env{TEXINPUTS} (use @code{@@env}). 6821 6822@item 6823For a string of characters shorter than a syntactic token. For example, 6824if you are writing about @samp{goto-ch}, which is just a part of the 6825name for the @code{goto-char} Emacs Lisp function, you should use 6826@code{@@samp}. 6827 6828@item 6829In general, when writing about the characters used in a token; for 6830example, do not use @code{@@code} when you are explaining what letters 6831or printable symbols can be used in the names of functions. (Use 6832@code{@@samp}.) Also, you should not use @code{@@code} to mark text 6833that is considered input to programs unless the input is written in a 6834language that is like a programming language. For example, you should 6835not use @code{@@code} for the keystroke commands of GNU Emacs (use 6836@code{@@kbd} instead) although you may use @code{@@code} for the names 6837of the Emacs Lisp functions that the keystroke commands invoke. 6838 6839@end itemize 6840 6841Since @code{@@command}, @code{@@option}, and @code{@@env} were 6842introduced relatively recently, it is acceptable to use @code{@@code} or 6843@code{@@samp} for command names, options, and environment variables. 6844The new commands allow you to express the markup more precisely, but 6845there is no real harm in using the older commands, and of course the 6846long-standing manuals do so. 6847 6848 6849@node kbd 6850@subsection @code{@@kbd}@{@var{keyboard-characters}@} 6851@findex kbd 6852@cindex Keyboard input 6853 6854Use the @code{@@kbd} command for characters of input to be typed by 6855users. For example, to refer to the characters @kbd{M-a}, write: 6856 6857@example 6858@@kbd@{M-a@} 6859@end example 6860 6861@noindent 6862and to refer to the characters @kbd{M-x shell}, write: 6863 6864@example 6865@@kbd@{M-x shell@} 6866@end example 6867 6868@cindex User input 6869@cindex Slanted typewriter font, for @code{@@kbd} 6870By default, the @code{@@kbd} command produces a different font 6871(slanted typewriter instead of normal typewriter) in the printed 6872manual, so users can distinguish the characters that they are supposed 6873to type from those that the computer outputs. 6874 6875In Info output, @code{@@kbd} is usually the same as @code{@@code}, 6876producing `quotes' around its argument. However, in typewriter-like 6877contexts such as the @code{@@example} environment (@pxref{example}) 6878and @code{@@code} command itself, the quotes are omitted, since Info 6879format cannot use distinguishing fonts. 6880 6881@findex kbdinputstyle 6882Since the usage of @code{@@kbd} varies from manual to manual, you can 6883control the font switching with the @code{@@kbdinputstyle} command. 6884This command has no effect on Info output. Write this command at the 6885beginning of a line with a single word as an argument, one of the 6886following: 6887 6888@vindex distinct@r{, value for @code{@@kbdinputstyle}} 6889@vindex example@r{, value for @code{@@kbdinputstyle}} 6890@vindex code@r{, value for @code{@@kbdinputstyle}} 6891@table @samp 6892@item code 6893Always use the same font for @code{@@kbd} as @code{@@code}. 6894@item example 6895Use the distinguishing font for @code{@@kbd} only in @code{@@example} 6896and similar environments. 6897@item distinct 6898(the default) Always use the distinguishing font for @code{@@kbd}. 6899@end table 6900 6901You can embed another @@-command inside the braces of an @code{@@kbd} 6902command. Here, for example, is the way to describe a command that 6903would be described more verbosely as ``press the @samp{r} key and then 6904press the @key{RETURN} key'': 6905 6906@example 6907@@kbd@{r @@key@{RET@}@} 6908@end example 6909 6910@noindent 6911This produces: @kbd{r @key{RET}}. (The present manual accepts the 6912default for @code{@@kbdinputstyle}.) 6913 6914You also use the @code{@@kbd} command if you are spelling out the letters 6915you type; for example: 6916 6917@example 6918To give the @@code@{logout@} command, 6919type the characters @@kbd@{l o g o u t @@key@{RET@}@}. 6920@end example 6921 6922@noindent 6923This produces: 6924 6925@quotation 6926To give the @code{logout} command, 6927type the characters @kbd{l o g o u t @key{RET}}. 6928@end quotation 6929 6930(Also, this example shows that you can add spaces for clarity. If you 6931explicitly want to mention a space character as one of the characters of 6932input, write @kbd{@@key@{SPC@}} for it.)@refill 6933 6934 6935@node key 6936@comment node-name, next, previous, up 6937@subsection @code{@@key}@{@var{key-name}@} 6938@findex key 6939 6940Use the @code{@@key} command for the conventional name for a key on a 6941keyboard, as in:@refill 6942 6943@example 6944@@key@{RET@} 6945@end example 6946 6947You can use the @code{@@key} command within the argument of an 6948@code{@@kbd} command when the sequence of characters to be typed 6949includes one or more keys that are described by name.@refill 6950 6951@need 700 6952For example, to produce @kbd{C-x @key{ESC}} you would type:@refill 6953 6954@example 6955@@kbd@{C-x @@key@{ESC@}@} 6956@end example 6957 6958Here is a list of the recommended names for keys: 6959@cindex Recommended names for keys 6960@cindex Keys, recommended names 6961@cindex Names recommended for keys 6962@cindex Abbreviations for keys 6963 6964@quotation 6965@table @t 6966@item SPC 6967Space 6968@item RET 6969Return 6970@item LFD 6971Linefeed (however, since most keyboards nowadays do not have a Linefeed key, 6972it might be better to call this character @kbd{C-j}. 6973@item TAB 6974Tab 6975@item BS 6976Backspace 6977@item ESC 6978Escape 6979@item DEL 6980Delete 6981@item SHIFT 6982Shift 6983@item CTRL 6984Control 6985@item META 6986Meta 6987@end table 6988@end quotation 6989 6990@cindex META key 6991There are subtleties to handling words like `meta' or `ctrl' that are 6992names of modifier keys. When mentioning a character in which the 6993modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command 6994alone; do not use the @code{@@key} command; but when you are referring 6995to the modifier key in isolation, use the @code{@@key} command. For 6996example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and 6997@samp{@@key@{META@}} to produce @key{META}. 6998 6999@c I don't think this is a good explanation. 7000@c I think it will puzzle readers more than it clarifies matters. -- rms. 7001@c In other words, use @code{@@kbd} for what you do, and use @code{@@key} 7002@c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to 7003@c the beginning of the sentence. The @code{@@key@{META@}} key is often in 7004@c the lower left of the keyboard.''@refill 7005 7006@node samp 7007@subsection @code{@@samp}@{@var{text}@} 7008@findex samp 7009 7010Use the @code{@@samp} command to indicate text that is a literal example 7011or `sample' of a sequence of characters in a file, string, pattern, etc. 7012Enclose the text in braces. The argument appears within single 7013quotation marks in both the Info file and the printed manual; in 7014addition, it is printed in a fixed-width font.@refill 7015 7016@example 7017To match @@samp@{foo@} at the end of the line, 7018use the regexp @@samp@{foo$@}. 7019@end example 7020 7021@noindent 7022produces 7023 7024@quotation 7025To match @samp{foo} at the end of the line, use the regexp 7026@samp{foo$}.@refill 7027@end quotation 7028 7029Any time you are referring to single characters, you should use 7030@code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate. 7031Also, you may use @code{@@samp} for entire statements in C and for entire 7032shell commands---in this case, @code{@@samp} often looks better than 7033@code{@@code}. Basically, @code{@@samp} is a catchall for whatever is 7034not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill 7035 7036Only include punctuation marks within braces if they are part of the 7037string you are specifying. Write punctuation marks outside the braces 7038if those punctuation marks are part of the English text that surrounds 7039the string. In the following sentence, for example, the commas and 7040period are outside of the braces:@refill 7041 7042@example 7043@group 7044In English, the vowels are @@samp@{a@}, @@samp@{e@}, 7045@@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes 7046@@samp@{y@}. 7047@end group 7048@end example 7049 7050@noindent 7051This produces: 7052 7053@quotation 7054In English, the vowels are @samp{a}, @samp{e}, 7055@samp{i}, @samp{o}, @samp{u}, and sometimes 7056@samp{y}. 7057@end quotation 7058 7059 7060@node verb 7061@subsection @code{@@verb}@{<char>@var{text}<char>@} 7062@findex verb 7063@cindex Verbatim in-line text 7064 7065@cindex Delimiter character, for verbatim 7066Use the @code{@@verb} command to print a verbatim sequence of 7067characters. 7068 7069Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using 7070any unique delimiter character. Enclose the verbatim text, including the 7071delimiters, in braces. Text is printed in a fixed-width font: 7072 7073@example 7074How many @@verb@{|@@|@}-escapes does one need to print this 7075@@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this? 7076@end example 7077 7078@noindent 7079produces 7080 7081@example 7082How many @verb{|@|}-escapes does one need to print this 7083@verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this? 7084@end example 7085 7086This is in contrast to @code{@@samp} (see the previous section), 7087@code{@@code}, and similar commands; in those cases, the argument is 7088normal Texinfo text, where the three characters @code{@@@{@}} are 7089special. With @code{@@verb}, nothing is special except the delimiter 7090character you choose. 7091 7092It is not reliable to use @code{@@verb} inside other Texinfo 7093constructs. In particular, it does not work to use @code{@@verb} in 7094anything related to cross-referencing, such as section titles or 7095figure captions. 7096 7097 7098@node var 7099@subsection @code{@@var}@{@var{metasyntactic-variable}@} 7100@findex var 7101 7102Use the @code{@@var} command to indicate metasyntactic variables. A 7103@dfn{metasyntactic variable} is something that stands for another piece of 7104text. For example, you should use a metasyntactic variable in the 7105documentation of a function to describe the arguments that are passed 7106to that function.@refill 7107 7108Do not use @code{@@var} for the names of particular variables in 7109programming languages. These are specific names from a program, so 7110@code{@@code} is correct for them (@pxref{code}). For example, the 7111Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic 7112variable; it is properly formatted using @code{@@code}. 7113 7114Do not use @code{@@var} for environment variables either; @code{@@env} 7115is correct for them (see the next section). 7116 7117The effect of @code{@@var} in the Info file is to change the case of the 7118argument to all upper case. In the printed manual and HTML output, the 7119argument is printed in slanted type. 7120 7121@need 700 7122For example, 7123 7124@example 7125To delete file @@var@{filename@}, 7126type @@samp@{rm @@var@{filename@}@}. 7127@end example 7128 7129@noindent 7130produces 7131 7132@quotation 7133To delete file @var{filename}, type @samp{rm @var{filename}}. 7134@end quotation 7135 7136@noindent 7137(Note that @code{@@var} may appear inside @code{@@code}, 7138@code{@@samp}, @code{@@file}, etc.)@refill 7139 7140Write a metasyntactic variable all in lower case without spaces, and 7141use hyphens to make it more readable. Thus, the Texinfo source for 7142the illustration of how to begin a Texinfo manual looks like 7143this:@refill 7144 7145@example 7146@group 7147\input texinfo 7148@@@@setfilename @@var@{info-file-name@} 7149@@@@settitle @@var@{name-of-manual@} 7150@end group 7151@end example 7152 7153@noindent 7154This produces: 7155 7156@example 7157@group 7158\input texinfo 7159@@setfilename @var{info-file-name} 7160@@settitle @var{name-of-manual} 7161@end group 7162@end example 7163 7164In some documentation styles, metasyntactic variables are shown with 7165angle brackets, for example:@refill 7166 7167@example 7168@dots{}, type rm <filename> 7169@end example 7170 7171@noindent 7172However, that is not the style that Texinfo uses. (You can, of 7173course, modify the sources to @file{texinfo.tex} and the Info formatting commands 7174to output the @code{<@dots{}>} format if you wish.)@refill 7175 7176 7177@node env 7178@subsection @code{@@env}@{@var{environment-variable}@} 7179@findex env 7180 7181Use the @code{@@env} command to indicate environment variables, as used 7182by many operating systems, including GNU. Do not use it for 7183metasyntactic variables; use @code{@@var} instead (see the previous 7184section). 7185 7186@code{@@env} is equivalent to @code{@@code} in its effects. 7187For example: 7188 7189@example 7190The @@env@{PATH@} environment variable @dots{} 7191@end example 7192@noindent produces 7193@quotation 7194The @env{PATH} environment variable @dots{} 7195@end quotation 7196 7197 7198@node file 7199@subsection @code{@@file}@{@var{file-name}@} 7200@findex file 7201 7202Use the @code{@@file} command to indicate text that is the name of a 7203file, buffer, or directory, or is the name of a node in Info. You can 7204also use the command for file name suffixes. Do not use @code{@@file} 7205for symbols in a programming language; use @code{@@code}. 7206 7207Currently, @code{@@file} is equivalent to @code{@@samp} in its effects. 7208For example,@refill 7209 7210@example 7211The @@file@{.el@} files are in 7212the @@file@{/usr/local/emacs/lisp@} directory. 7213@end example 7214 7215@noindent 7216produces 7217 7218@quotation 7219The @file{.el} files are in 7220the @file{/usr/local/emacs/lisp} directory. 7221@end quotation 7222 7223 7224@node command 7225@subsection @code{@@command}@{@var{command-name}@} 7226@findex command 7227@cindex Command names, indicating 7228@cindex Program names, indicating 7229 7230Use the @code{@@command} command to indicate command names, such as 7231@command{ls} or @command{cc}. 7232 7233@code{@@command} is equivalent to @code{@@code} in its effects. 7234For example: 7235 7236@example 7237The command @@command@{ls@} lists directory contents. 7238@end example 7239@noindent produces 7240@quotation 7241The command @command{ls} lists directory contents. 7242@end quotation 7243 7244You should write the name of a program in the ordinary text font, rather 7245than using @code{@@command}, if you regard it as a new English word, 7246such as `Emacs' or `Bison'. 7247 7248When writing an entire shell command invocation, as in @samp{ls -l}, 7249you should use either @code{@@samp} or @code{@@code} at your discretion. 7250 7251 7252@node option 7253@subsection @code{@@option}@{@var{option-name}@} 7254@findex option 7255 7256Use the @code{@@option} command to indicate a command-line option; for 7257example, @option{-l} or @option{--version} or 7258@option{--output=@var{filename}}. 7259 7260@code{@@option} is equivalent to @code{@@samp} in its effects. 7261For example: 7262 7263@example 7264The option @@option@{-l@} produces a long listing. 7265@end example 7266@noindent produces 7267@quotation 7268The option @option{-l} produces a long listing. 7269@end quotation 7270 7271In tables, putting options inside @code{@@code} produces a 7272more pleasing effect. 7273 7274@node dfn 7275@comment node-name, next, previous, up 7276@subsection @code{@@dfn}@{@var{term}@} 7277@findex dfn 7278 7279Use the @code{@@dfn} command to identify the introductory or defining 7280use of a technical term. Use the command only in passages whose 7281purpose is to introduce a term which will be used again or which the 7282reader ought to know. Mere passing mention of a term for the first 7283time does not deserve @code{@@dfn}. The command generates italics in 7284the printed manual, and double quotation marks in the Info file. For 7285example:@refill 7286 7287@example 7288Getting rid of a file is called @@dfn@{deleting@} it. 7289@end example 7290 7291@noindent 7292produces 7293 7294@quotation 7295Getting rid of a file is called @dfn{deleting} it. 7296@end quotation 7297 7298As a general rule, a sentence containing the defining occurrence of a 7299term should be a definition of the term. The sentence does not need 7300to say explicitly that it is a definition, but it should contain the 7301information of a definition---it should make the meaning clear. 7302 7303@node cite 7304@subsection @code{@@cite}@{@var{reference}@} 7305@findex cite 7306 7307Use the @code{@@cite} command for the name of a book that lacks a 7308companion Info file. The command produces italics in the printed 7309manual, and quotation marks in the Info file. 7310 7311If a book is written in Texinfo, it is better to use a cross reference 7312command since a reader can easily follow such a reference in Info. 7313@xref{xref, , @code{@@xref}}. 7314 7315 7316@ignore 7317@c node ctrl, , cite, Indicating 7318@comment node-name, next, previous, up 7319@c subsection @code{@@ctrl}@{@var{ctrl-char}@} 7320@findex ctrl 7321 7322The @code{@@ctrl} command is seldom used. It describes an @sc{ascii} 7323control character by inserting the actual character into the Info 7324file. 7325 7326Usually, in Texinfo, you talk what you type as keyboard entry by 7327describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for 7328@kbd{C-a}. Use @code{@@kbd} in this way when talking about a control 7329character that is typed on the keyboard by the user. When talking 7330about a control character appearing in a file or a string, do not use 7331@code{@@kbd} since the control character is not typed. Also, do not 7332use @samp{C-} but spell out @code{control-}, as in @samp{control-a}, 7333to make it easier for a reader to understand.@refill 7334 7335@code{@@ctrl} is an idea from the beginnings of Texinfo which may not 7336really fit in to the scheme of things. But there may be times when 7337you want to use the command. The pattern is 7338@code{@@ctrl@{@var{ch}@}}, where @var{ch} is an @sc{ascii} character 7339whose control-equivalent is wanted. For example, to specify 7340@samp{control-f}, you would enter@refill 7341 7342@example 7343@@ctrl@{f@} 7344@end example 7345 7346@noindent 7347produces 7348 7349@quotation 7350@ctrl{f} 7351@end quotation 7352 7353In the Info file, this generates the specified control character, output 7354literally into the file. This is done so a user can copy the specified 7355control character (along with whatever else he or she wants) into another 7356Emacs buffer and use it. Since the `control-h',`control-i', and 7357`control-j' characters are formatting characters, they should not be 7358indicated with @code{@@ctrl}.@refill 7359 7360In a printed manual, @code{@@ctrl} generates text to describe or 7361identify that control character: an uparrow followed by the character 7362@var{ch}.@refill 7363@end ignore 7364 7365 7366@node abbr 7367@subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@} 7368@findex abbr 7369 7370@cindex Abbreviations, tagging 7371You can use the @code{@@abbr} command for general abbreviations. The 7372abbreviation is given as the single argument in braces, as in 7373@samp{@@abbr@{Comput.@}}. As a matter of style, or for particular 7374abbreviations, you may prefer to omit periods, as in 7375@samp{@@abbr@{Mr@} Stallman}. 7376 7377@code{@@abbr} accepts an optional second argument, intended to be used 7378for the meaning of the abbreviation. 7379 7380If the abbreviation ends with a lowercase letter and a period, and is 7381not at the end of a sentence, and has no second argument, remember to 7382use the @code{@@.} command (@pxref{Not Ending a 7383Sentence}) to get the correct spacing. However, you do not have to 7384use @code{@@.} within the abbreviation itself; Texinfo automatically 7385assumes periods within the abbreivation do not end a sentence. 7386 7387@cindex <abbr> tag 7388In @TeX{} and in the Info output, the first argument is printed as-is; 7389if the second argument is present, it is printed in parentheses after 7390the abbreviation. In HTML and XML, the @code{<abbr>} tag is 7391used; in Docbook, the @code{<abbrev>} tag is used. For instance: 7392 7393@example 7394@@abbr@{Comput. J., Computer Journal@} 7395@end example 7396 7397@noindent produces: 7398 7399@display 7400@abbr{Comput. J., Computer Journal} 7401@end display 7402 7403For abbreviations consisting of all capital letters, you may prefer to 7404use the @code{@@acronym} command instead. See the next section for 7405more on the usage of these two commands. 7406 7407 7408@node acronym 7409@subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@} 7410@findex acronym 7411 7412@cindex NASA, as acronym 7413@cindex Acronyms, tagging 7414Use the @code{@@acronym} command for abbreviations written in all 7415capital letters, such as `@acronym{NASA}'. The abbreviation is given as 7416the single argument in braces, as in @samp{@@acronym@{NASA@}}. As 7417a matter of style, or for particular acronyms, you may prefer to 7418use periods, as in @samp{@@acronym@{N.A.S.A.@}}. 7419 7420@code{@@acronym} accepts an optional second argument, intended to be 7421used for the meaning of the acronym. 7422 7423If the acronym is at the end of a sentence, and if there is no second 7424argument, remember to use the @code{@@.} or similar command 7425(@pxref{Ending a Sentence}) to get the correct spacing. 7426 7427@cindex <acronym> tag 7428In @TeX{}, the acronym is printed in slightly smaller font. In the 7429Info output, the argument is printed as-is. In either format, if the 7430second argument is present, it is printed in parentheses after the 7431acronym. In HTML, Docbook, and XML, the @code{<acronym>} tag is 7432used. 7433 7434For instance (since GNU is a recursive acronym, we use 7435@code{@@acronym} recursively): 7436 7437@example 7438@@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@} 7439@end example 7440 7441@noindent produces: 7442 7443@display 7444@acronym{GNU, @acronym{GNU}'s Not Unix} 7445@end display 7446 7447In some circumstances, it is conventional to print family names in all 7448capitals. Don't use @code{@@acronym} for this, since a name is not an 7449acronym. Use @code{@@sc} instead (@pxref{Smallcaps}). 7450 7451@code{@@abbr} and @code{@@acronym} are closely related commands: they 7452both signal to the reader that a shortened form is being used, and 7453possibly give a meaning. When choosing whether to use these two 7454commands, please bear the following in mind. 7455 7456@itemize @minus 7457@item 7458In standard English usage, acronyms are a subset of abbreviations: 7459they include pronounceable words like `@acronym{NATO}', `radar', and 7460`snafu', and some sources also include syllable acronyms like 7461`Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable 7462initialisms like `@acronym{FBI}'. 7463 7464@item 7465In Texinfo, an acronym (but not an abbreviation) should consist only 7466of capital letters and periods, no lowercase. 7467 7468@item 7469In @TeX{}, an acronym (but not an abbreviation) is printed in a 7470slightly smaller font. 7471 7472@item 7473Some browsers place a dotted bottom border under abbreviations but not 7474acronyms. 7475 7476@item 7477It's not essential to use these commands for all abbreviations. Text 7478is perfectly readable without them, and for common abbreviations like 7479`etc.@:', we consider them to be overkill. 7480 7481@end itemize 7482 7483 7484@node indicateurl 7485@subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@} 7486@findex indicateurl 7487@cindex Uniform resource locator, indicating 7488@cindex URL, indicating 7489 7490Use the @code{@@indicateurl} command to indicate a uniform resource 7491locator on the World Wide Web. This is analogous to @code{@@file}, 7492@code{@@var}, etc., and is purely for markup purposes. It does not 7493produce a link you can follow in HTML output (use the @code{@@uref} 7494command for that, @pxref{uref,, @code{@@uref}}). It is useful for 7495url's which do not actually exist. For example: 7496 7497@example 7498For example, the url might be @@indicateurl@{http://example.org/path@}. 7499@end example 7500 7501@noindent which produces: 7502 7503@display 7504For example, the url might be @indicateurl{http://example.org/path}. 7505@end display 7506 7507 7508@node email 7509@subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@} 7510@findex email 7511 7512Use the @code{@@email} command to indicate an electronic mail address. 7513It takes one mandatory argument, the address, and one optional argument, the 7514text to display (the default is the address itself). 7515 7516@cindex Mailto link 7517In Info, the address is shown in angle brackets, preceded by the text 7518to display if any. In @TeX{}, the angle brackets are omitted. In 7519HTML output, @code{@@email} produces a @samp{mailto} link that usually 7520brings up a mail composition window. For example: 7521 7522@example 7523Send bug reports to @@email@{bug-texinfo@@@@gnu.org@}, 7524suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}. 7525@end example 7526@noindent produces 7527@display 7528Send bug reports to @email{bug-texinfo@@gnu.org}, 7529suggestions to the @email{bug-texinfo@@gnu.org, same place}. 7530@end display 7531 7532 7533@node Emphasis 7534@comment node-name, next, previous, up 7535@section Emphasizing Text 7536@cindex Emphasizing text 7537 7538Usually, Texinfo changes the font to mark words in the text according to 7539what category the words belong to; an example is the @code{@@code} command. 7540Most often, this is the best way to mark words. 7541However, sometimes you will want to emphasize text without indicating a 7542category. Texinfo has two commands to do this. Also, Texinfo has 7543several commands that specify the font in which @TeX{} will typeset 7544text. These commands have no effect on Info and only one of them, 7545the @code{@@r} command, has any regular use.@refill 7546 7547@menu 7548* emph & strong:: How to emphasize text in Texinfo. 7549* Smallcaps:: How to use the small caps font. 7550* Fonts:: Various font commands for printed output. 7551@end menu 7552 7553@node emph & strong 7554@subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@} 7555@cindex Emphasizing text, font for 7556@findex emph 7557@findex strong 7558 7559The @code{@@emph} and @code{@@strong} commands are for emphasis; 7560@code{@@strong} is stronger. In printed output, @code{@@emph} produces 7561@emph{italics} and @code{@@strong} produces @strong{bold}. 7562 7563For example, 7564 7565@example 7566@group 7567@@strong@{Caution:@} @@samp@{rm * .[^.]*@} 7568removes @@emph@{all@} files in the directory. 7569@end group 7570@end example 7571 7572@noindent 7573produces the following in printed output and HTML: 7574 7575@quotation 7576@strong{Caution}: @samp{rm * .[^.]*} 7577removes @emph{all} files in the directory. 7578@end quotation 7579 7580@noindent 7581and the following in Info: 7582 7583@example 7584*Caution:* `rm * .[^.]*' removes _all_ 7585files in the directory. 7586@end example 7587 7588The @code{@@strong} command is seldom used except to mark what is, in 7589effect, a typographical element, such as the word `Caution' in the 7590preceding example. 7591 7592In the Info output, @code{@@emph} surrounds the text with underscores 7593(@samp{_}), and @code{@@strong} puts asterisks around the text. 7594 7595@quotation Caution 7596Do not use @code{@@strong} with the word @samp{Note}; Info will 7597mistake the combination for a cross reference. (It's usually 7598redundant, anyway.) Use a phrase such as @strong{Please notice} or 7599@strong{Caution} instead, or the optional argument to 7600@code{@@quotation}---@samp{Note} is allowable there. 7601@end quotation 7602 7603 7604@node Smallcaps 7605@subsection @code{@@sc}@{@var{text}@}: The Small Caps Font 7606@cindex Small caps font 7607@findex sc @r{(small caps font)} 7608 7609Use the @samp{@@sc} command to set text in @sc{a small caps font} 7610(where possible). Write the text you want to be in small caps between 7611braces in lower case, like this: 7612 7613@example 7614Richard @@sc@{Stallman@} founded @@acronym@{GNU@}. 7615@end example 7616 7617@noindent 7618This produces: 7619 7620@display 7621Richard @sc{Stallman} founded @acronym{GNU}. 7622@end display 7623 7624As shown here, we recommend using @code{@@acronym} for actual 7625acronyms (@pxref{acronym}), and reserving @code{@@sc} for special 7626cases where you want small caps. The output is not the same 7627(@code{@@acronym} prints in a smaller text font, not the small caps 7628font), but more importantly it describes the actual text more 7629accurately. 7630 7631Family names are one case where small capitals are sometimes desirable, 7632also as shown here. 7633 7634@cindex <small> tag 7635@TeX{} typesets any uppercase letters between the braces of an 7636@code{@@sc} command in full-size capitals; only lowercase letters are 7637printed in the small caps font. In the Info output, the argument to 7638@code{@@sc} is printed in all upper case. In HTML, the argument is 7639uppercased and the output marked with the @code{<small>} tag to reduce 7640the font size. 7641 7642Since it's redundant to mark all-uppercase text with @code{@@sc}, 7643@command{makeinfo} warns about such usage. 7644 7645We recommend using regular mixed case wherever possible. 7646 7647 7648@node Fonts 7649@subsection Fonts for Printing, Not Info 7650@cindex Fonts for printing, not Info 7651 7652Texinfo provides a number of font commands that specify font changes 7653in the printed manual and (where possible) in the HTML output, but 7654have no effect in the Info file. All the commands apply to an 7655argument that follows, surrounded by braces. 7656 7657@table @code 7658@item @@b 7659@findex b @r{(bold font)} 7660@cindex Bold font 7661selects @b{bold} face; 7662 7663@item @@i 7664@findex i @r{(italic font)} 7665@cindex Italic font 7666selects an @i{italic} font; 7667 7668@item @@r 7669@findex r @r{(roman font)} 7670@cindex Roman font 7671@cindex Default font 7672selects a @r{roman} font, which is the usual font in which text is 7673printed. It may or may not be seriffed. 7674 7675@item @@sansserif 7676@findex sansserif @r{(sans serif font)} 7677@cindex Sans serif font 7678selects a @sansserif{sans serif} font; 7679 7680@item @@slanted 7681@findex slanted @r{(slanted font)} 7682@cindex Slanted font 7683@cindex Oblique font 7684rselects a @slanted{slanted} font; 7685 7686@item @@t 7687@findex t @r{(typewriter font)} 7688@cindex Monospace font 7689@cindex Fixed-width font 7690@cindex Typewriter font 7691selects the @t{fixed-width}, typewriter-style font used by @code{@@code}; 7692 7693@end table 7694 7695(The commands with longer names were invented much later than the 7696others, when it did not seem desirable to use very short names for 7697such an infrequently needed feature.) 7698 7699@cindex <lineannotation> Docbook tag 7700Only the @code{@@r} command has much use: in example-like 7701environments, you can use the @code{@@r} command to write comments in 7702the standard roman font instead of the fixed-width font. This looks 7703better in printed output, and produces a @code{<lineannotation>} tag 7704in Docbook output. 7705 7706For example, 7707 7708@example 7709@group 7710@@lisp 7711(+ 2 2) ; @@r@{Add two plus two.@} 7712@@end lisp 7713@end group 7714@end example 7715 7716@noindent 7717produces 7718 7719@lisp 7720(+ 2 2) ; @r{Add two plus two.} 7721@end lisp 7722 7723In general, you should avoid using the other font commands. Some of 7724them are only useful when documenting functionality with specific font 7725effects, such as in \TeX\ and related packages. 7726 7727 7728@node Quotations and Examples 7729@chapter Quotations and Examples 7730 7731Quotations and examples are blocks of text consisting of one or more 7732whole paragraphs that are set off from the bulk of the text and 7733treated differently. They are usually indented in the output. 7734 7735@findex end 7736In Texinfo, you always begin a quotation or example by writing an 7737@@-command at the beginning of a line by itself, and end it by writing 7738an @code{@@end} command that is also at the beginning of a line by 7739itself. For instance, you begin an example by writing @code{@@example} 7740by itself at the beginning of a line and end the example by writing 7741@code{@@end example} on a line by itself, at the beginning of that 7742line, and with only one space between the @code{@@end} and the 7743@code{example}. 7744 7745@menu 7746* Block Enclosing Commands:: Different constructs for different purposes. 7747* quotation:: Writing a quotation. 7748* example:: Writing an example in a fixed-width font. 7749* verbatim:: Writing a verbatim example. 7750* verbatiminclude:: Including a file verbatim. 7751* lisp:: Illustrating Lisp code. 7752* small:: Examples in a smaller font. 7753* display:: Writing an example in the current font. 7754* format:: Writing an example without narrowed margins. 7755* exdent:: Undo indentation on a line. 7756* flushleft & flushright:: Pushing text flush left or flush right. 7757* noindent:: Preventing paragraph indentation. 7758* indent:: Forcing paragraph indentation. 7759* cartouche:: Drawing rounded rectangles around examples. 7760@end menu 7761 7762 7763@node Block Enclosing Commands 7764@section Block Enclosing Commands 7765 7766Here are commands for quotations and examples, explained further in the 7767following sections: 7768 7769@table @code 7770@item @@quotation 7771Indicate text that is quoted. The text is filled, indented (from both 7772margins), and printed in a roman font by default. 7773 7774@item @@example 7775Illustrate code, commands, and the like. The text is printed 7776in a fixed-width font, and indented but not filled. 7777 7778@item @@verbatim 7779Mark a piece of text that is to be printed verbatim; no character 7780substitutions are made and all commands are ignored, until the next 7781@code{@@end verbatim}. The text is printed in a fixed-width font, 7782and not indented or filled. Extra spaces and blank lines are 7783significant, and tabs are expanded. 7784 7785@item @@smallexample 7786Same as @code{@@example}, except that in @TeX{} this command typesets 7787text in a smaller font. 7788 7789@item @@lisp 7790Like @code{@@example}, but specifically for illustrating Lisp code. The 7791text is printed in a fixed-width font, and indented but not filled. 7792 7793@item @@smalllisp 7794Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}. 7795 7796@item @@display 7797Display illustrative text. The text is indented but not filled, and 7798no font is selected (so, by default, the font is roman).@refill 7799 7800@item @@smalldisplay 7801Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}. 7802 7803@item @@format 7804Like @code{@@display} (the text is not filled and no font is selected), 7805but the text is not indented. 7806 7807@item @@smallformat 7808Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}. 7809@end table 7810 7811The @code{@@exdent} command is used within the above constructs to 7812undo the indentation of a line. 7813 7814The @code{@@flushleft} and @code{@@flushright} commands are used to line 7815up the left or right margins of unfilled text.@refill 7816 7817The @code{@@noindent} command may be used after one of the above 7818constructs to prevent the following text from being indented as a new 7819paragraph. 7820 7821You can use the @code{@@cartouche} environment around one of the above 7822constructs to highlight the example or quotation by drawing a box with 7823rounded corners around it. @xref{cartouche, , Drawing Cartouches Around 7824Examples}. 7825 7826 7827@node quotation 7828@section @code{@@quotation}: Block quotations 7829@cindex Quotations 7830@findex quotation 7831 7832The text of a quotation is processed normally (regular font, text is 7833filled) except that: 7834 7835@itemize @bullet 7836@item 7837the margins are closer to the center of the page, so the whole of the 7838quotation is indented; 7839 7840@item 7841and the first lines of paragraphs are indented no more than other lines. 7842 7843@end itemize 7844 7845@quotation 7846This is an example of text written between an @code{@@quotation} 7847command and an @code{@@end quotation} command. An @code{@@quotation} 7848command is most often used to indicate text that is excerpted from 7849another (real or hypothetical) printed work. 7850@end quotation 7851 7852Write an @code{@@quotation} command as text on a line by itself. This 7853line will disappear from the output. Mark the end of the quotation 7854with a line beginning with and containing only @code{@@end quotation}. 7855The @code{@@end quotation} line will likewise disappear from the 7856output. 7857 7858@code{@@quotation} takes one optional argument, given on the remainder 7859of the line. This text, if present, is included at the beginning of 7860the quotation in bold or otherwise emphasized, and followed with a 7861@samp{:}. For example: 7862 7863@example 7864@@quotation Note 7865This is 7866a foo. 7867@@end quotation 7868@end example 7869 7870@noindent 7871produces 7872 7873@quotation Note 7874This is 7875a foo. 7876@end quotation 7877 7878If the @code{@@quotation} argument is exactly one of these words: 7879 7880@example 7881Caution Important Note Tip Warning 7882@end example 7883 7884@cindex <note> Docbook tag 7885@cindex <blockquote> HTML tag 7886@noindent then the Docbook output uses corresponding special tags 7887(@code{<note>}, etc.) instead of the default @code{<blockquote>}. 7888HTML output always uses @code{<blockquote>}. 7889 7890 7891@node example 7892@section @code{@@example}: Example Text 7893@cindex Examples, formatting them 7894@cindex Formatting examples 7895@findex example 7896 7897The @code{@@example} environment is used to indicate an example that 7898is not part of the running text, such as computer input or output. 7899Write an @code{@@example} command at the beginning of a line by 7900itself. Mark the end of the example with an @code{@@end example} 7901command, also written at the beginning of a line by itself. 7902 7903An @code{@@example} environment has the following characteristics: 7904 7905@itemize 7906@item Each line in the input file is a line in the output; that is, 7907the source text is not filled as it normally is. 7908@item Extra spaces and blank lines are significant. 7909@item The output is indented. 7910@item The output uses a fixed-width font. 7911@item Texinfo commands @emph{are} expanded; if you want the output to 7912be the input verbatim, use the @code{@@verbatim} environment instead 7913(@pxref{verbatim,,@code{@@verbatim}}). 7914@end itemize 7915 7916For example, 7917 7918@example 7919@@example 7920cp foo @@var@{dest1@}; \ 7921 cp foo @@var@{dest2@} 7922@@end example 7923@end example 7924 7925@noindent 7926produces 7927 7928@example 7929cp foo @var{dest1}; \ 7930 cp foo @var{dest2} 7931@end example 7932 7933The lines containing @code{@@example} and @code{@@end example} will 7934disappear from the output. To make the output look good, you should 7935put a blank line before the @code{@@example} and another blank line 7936after the @code{@@end example}. Blank lines inside the beginning 7937@code{@@example} and the ending @code{@@end example}, on the other 7938hand, do appear in the output. 7939 7940@quotation Caution 7941Do not use tabs in the lines of an example! (Or anywhere else in 7942Texinfo, except in verbatim environments.) @TeX{} treats tabs as 7943single spaces, and that is not what they look like. In Emacs, you can 7944use @kbd{M-x untabify} to convert tabs in a region to multiple spaces. 7945@end quotation 7946 7947Examples are often, logically speaking, ``in the middle'' of a 7948paragraph, and the text that continues afterwards should not be 7949indented, as in the example above. The @code{@@noindent} command 7950prevents a piece of text from being indented as if it were a new 7951paragraph (@pxref{noindent,,@code{@@noindent}}. 7952 7953If you want to embed code fragments within sentences, instead of 7954displaying them, use the @code{@@code} command or its relatives 7955(@pxref{code,,@code{@@code}}). 7956 7957If you wish to write a ``comment'' on a line of an example in the 7958normal roman font, you can use the @code{@@r} command (@pxref{Fonts}). 7959 7960 7961@node verbatim 7962@section @code{@@verbatim}: Literal Text 7963@findex verbatim 7964@cindex Verbatim environment 7965 7966Use the @code{@@verbatim} environment for printing of text that may 7967contain special characters or commands that should not be interpreted, 7968such as computer input or output (@code{@@example} interprets its text 7969as regular Texinfo commands). This is especially useful for including 7970automatically generated output in a Texinfo manual. Here is an example; 7971the output you see is just the same as the input, with a line 7972@code{@@verbatim} before and a line @code{@@end verbatim} after. 7973 7974@verbatim 7975This is an example of text written in a @verbatim 7976block. No character substitutions are made. All commands 7977are ignored, until `<at>end verbatim'. 7978 7979In the printed manual, the text is typeset in a 7980fixed-width font, and not indented or filled. All 7981spaces and blank lines are significant, including tabs. 7982@end verbatim 7983 7984Write a @code{@@verbatim} command at the beginning of a line by itself. 7985This line will disappear from the output. Mark the end of the verbatim 7986block with a @code{@@end verbatim} command, also written at the 7987beginning of a line by itself. The @code{@@end verbatim} will also 7988disappear from the output. 7989 7990For example: 7991@c oops, got to trick this a bit: can't use @end verbatim inside @verbatim 7992 7993@example 7994@exdent @t{@@verbatim} 7995@exdent @t{@{} 7996@exdent @key{TAB}@t{@@command with strange characters: @@'e} 7997@exdent @t{expand@key{TAB}me} 7998@exdent @t{@}} 7999@exdent @t{@@end verbatim} 8000@end example 8001 8002@noindent 8003produces 8004 8005@verbatim 8006{ 8007 @command with strange characters: @'e 8008expand me 8009} 8010@end verbatim 8011 8012Since the lines containing @code{@@verbatim} and @code{@@end verbatim} 8013produce no output, typically you should put a blank line before the 8014@code{@@verbatim} and another blank line after the @code{@@end 8015verbatim}. Blank lines between the beginning @code{@@verbatim} and 8016the ending @code{@@end verbatim} will appear in the output. 8017 8018It is not reliable to use @code{@@verbatim} inside other Texinfo constructs. 8019 8020 8021@node verbatiminclude 8022@section @code{@@verbatiminclude} @var{file}: Include a File Verbatim 8023@cindex Verbatim, include file 8024@cindex Including a file verbatim 8025@findex verbatiminclude 8026 8027You can include the exact contents of a file in the document with the 8028@code{@@verbatiminclude} command: 8029 8030@example 8031@@verbatiminclude @var{filename} 8032@end example 8033 8034The contents of @var{filename} is printed in a verbatim environment 8035(@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed 8036exactly as it is, with all special characters and white space 8037retained. No indentation is added; if you want indentation, enclose 8038the @code{@@verbatiminclude} within @code{@@example} 8039(@pxref{example,,@code{@@example}}). 8040 8041The name of the file is taken literally, with a single exception: 8042@code{@@value@{@var{var}@}} references are expanded. This makes it 8043possible to reliably include files in other directories in a 8044distribution, for instance: 8045 8046@example 8047@@include @@value@{top_srcdir@}/NEWS 8048@end example 8049 8050@noindent (You still have to get @code{top_srcdir} defined in the 8051first place.) 8052 8053 8054@node lisp 8055@section @code{@@lisp}: Marking a Lisp Example 8056@findex lisp 8057@cindex Lisp example 8058 8059The @code{@@lisp} command is used for Lisp code. It is synonymous 8060with the @code{@@example} command. 8061 8062@lisp 8063This is an example of text written between an 8064@code{@@lisp} command and an @code{@@end lisp} command. 8065@end lisp 8066 8067Use @code{@@lisp} instead of @code{@@example} to preserve information 8068regarding the nature of the example. This is useful, for example, if 8069you write a function that evaluates only and all the Lisp code in a 8070Texinfo file. Then you can use the Texinfo file as a Lisp 8071library.@footnote{It would be straightforward to extend Texinfo to work 8072in a similar fashion for C, Fortran, or other languages.} 8073 8074Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by 8075itself. 8076 8077 8078@node small 8079@section @code{@@small@dots{}} Block Commands 8080@cindex Small examples 8081@cindex Examples in smaller fonts 8082@cindex Lisp examples in smaller fonts 8083@findex smalldisplay 8084@findex smallexample 8085@findex smallformat 8086@findex smalllisp 8087 8088In addition to the regular @code{@@example} and @code{@@lisp} commands, 8089Texinfo has ``small'' example-style commands. These are 8090@code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and 8091@code{@@smalllisp}. 8092 8093In Info, the @code{@@small@dots{}} commands are equivalent to their 8094non-small companion commands. 8095 8096In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in 8097a smaller font than the non-small example commands. Consequently, 8098many examples containing long lines fit on a page without needing to 8099be shortened. 8100 8101Mark the end of an @code{@@small@dots{}} block with a corresponding 8102@code{@@end small@dots{}}. For example, pair @code{@@smallexample} with 8103@code{@@end smallexample}. 8104 8105Here is an example of the font used by the @code{@@small@dots{}} 8106commands (in Info, the output will be the same as usual): 8107 8108@smallexample 8109@dots{} to make sure that you have the freedom to 8110distribute copies of free software (and charge for 8111this service if you wish), that you receive source 8112code or can get it if you want it, that you can 8113change the software or use pieces of it in new free 8114programs; and that you know you can do these things. 8115@end smallexample 8116 8117The @code{@@small@dots{}} commands make it easier to prepare manuals 8118without forcing you to edit examples by hand to fit them onto narrower 8119pages. 8120 8121As a general rule, a printed document looks much better if you use 8122only one of (for instance) @code{@@example} or @code{@@smallexample} 8123consistently within a chapter. 8124 8125 8126@node display 8127@section @code{@@display} and @code{@@smalldisplay} 8128@cindex Display formatting 8129@findex display 8130 8131The @code{@@display} command begins a kind of example, where each line 8132of input produces a line of output, and the output is indented. It is 8133thus like the @code{@@example} command except that, in a printed 8134manual, @code{@@display} does not select the fixed-width font. In 8135fact, it does not specify the font at all, so that the text appears in 8136the same font it would have appeared in without the @code{@@display} 8137command. 8138 8139@display 8140This is an example of text written between an @code{@@display} command 8141and an @code{@@end display} command. The @code{@@display} command 8142indents the text, but does not fill it. 8143@end display 8144 8145@findex smalldisplay 8146Texinfo also provides a command @code{@@smalldisplay}, which is like 8147@code{@@display} but uses a smaller font in @code{@@smallbook} format. 8148@xref{small}. 8149 8150The @code{@@table} command (@pxref{table}) does not work inside 8151@code{@@display}. Since @code{@@display} is line-oriented, it doesn't 8152make sense to use them together. If you want to indent a table, try 8153@code{@@quotation} (@pxref{quotation}). 8154 8155 8156@node format 8157@section @code{@@format} and @code{@@smallformat} 8158@findex format 8159 8160The @code{@@format} command is similar to @code{@@example} except 8161that, in the printed manual, @code{@@format} does not select the 8162fixed-width font and does not narrow the margins.@refill 8163 8164@format 8165This is an example of text written between an @code{@@format} command 8166and an @code{@@end format} command. As you can see 8167from this example, 8168the @code{@@format} command does not fill the text. 8169@end format 8170 8171@findex smallformat 8172Texinfo also provides a command @code{@@smallformat}, which is like 8173@code{@@format} but uses a smaller font in @code{@@smallbook} format. 8174@xref{small}. 8175 8176 8177 8178@node exdent 8179@section @code{@@exdent}: Undoing a Line's Indentation 8180@cindex Indentation undoing 8181@findex exdent 8182 8183The @code{@@exdent} command removes any indentation a line might have. 8184The command is written at the beginning of a line and applies only to 8185the text that follows the command that is on the same line. Do not use 8186braces around the text. In a printed manual, the text on an 8187@code{@@exdent} line is printed in the roman font.@refill 8188 8189@code{@@exdent} is usually used within examples. Thus,@refill 8190 8191@example 8192@group 8193@@example 8194This line follows an @@@@example command. 8195@@exdent This line is exdented. 8196This line follows the exdented line. 8197The @@@@end example comes on the next line. 8198@@end group 8199@end group 8200@end example 8201 8202@noindent 8203produces 8204 8205@example 8206@group 8207This line follows an @@example command. 8208@exdent This line is exdented. 8209This line follows the exdented line. 8210The @@end example comes on the next line. 8211@end group 8212@end example 8213 8214In practice, the @code{@@exdent} command is rarely used. 8215Usually, you un-indent text by ending the example and 8216returning the page to its normal width.@refill 8217 8218 8219@node flushleft & flushright 8220@section @code{@@flushleft} and @code{@@flushright} 8221@findex flushleft 8222@findex flushright 8223@cindex Ragged right 8224@cindex Ragged left 8225 8226The @code{@@flushleft} and @code{@@flushright} commands line up the 8227ends of lines on the left and right margins of a page, 8228but do not fill the text. The commands are written on lines of their 8229own, without braces. The @code{@@flushleft} and @code{@@flushright} 8230commands are ended by @code{@@end flushleft} and @code{@@end 8231flushright} commands on lines of their own.@refill 8232 8233@need 1500 8234For example, 8235 8236@example 8237@group 8238@@flushleft 8239This text is 8240written flushleft. 8241@@end flushleft 8242@end group 8243@end example 8244 8245@noindent 8246produces 8247 8248@quotation 8249@flushleft 8250This text is 8251written flushleft. 8252@end flushleft 8253@end quotation 8254 8255 8256@code{@@flushright} produces the type of indentation often used in the 8257return address of letters. For example, 8258 8259@example 8260@group 8261@@flushright 8262Here is an example of text written 8263flushright. The @@code@{@@flushright@} command 8264right justifies every line but leaves the 8265left end ragged. 8266@@end flushright 8267@end group 8268@end example 8269 8270@noindent 8271produces 8272 8273@flushright 8274Here is an example of text written 8275flushright. The @code{@@flushright} command 8276right justifies every line but leaves the 8277left end ragged. 8278@end flushright 8279 8280 8281@node noindent 8282@section @code{@@noindent}: Omitting Indentation 8283@cindex Omitting indentation 8284@cindex Suppressing indentation 8285@cindex Indentation, omitting 8286@findex noindent 8287 8288An example or other inclusion can break a paragraph into segments. 8289Ordinarily, the formatters indent text that follows an example as a new 8290paragraph. You can prevent this on a case-by-case basis by writing 8291@code{@@noindent} at the beginning of a line, preceding the continuation 8292text. You can also disable indentation for all paragraphs globally with 8293@code{@@paragraphindent} (@pxref{paragraphindent, Paragraph Indenting}). 8294 8295It is best to write @code{@@noindent} on a line by itself, since in most 8296environments, spaces following the command will not be ignored. It's ok 8297to use it at the beginning of a line, with text following, outside of 8298any environment. 8299 8300@need 1500 8301For example: 8302 8303@example 8304@group 8305@@example 8306This is an example 8307@@end example 8308 8309@@noindent 8310This line is not indented. As you can see, the 8311beginning of the line is fully flush left with the line 8312that follows after it. (This whole example is between 8313@@code@{@@@@display@} and @@code@{@@@@end display@}.) 8314@end group 8315@end example 8316 8317@noindent produces: 8318 8319@display 8320 8321@example 8322This is an example 8323@end example 8324 8325@noindent 8326This line is not indented. As you can see, the 8327beginning of the line is fully flush left with the line 8328that follows after it. (This whole example is between 8329@code{@@display} and @code{@@end display}.) 8330 8331@end display 8332 8333To adjust the number of blank lines properly in the Info file output, 8334remember that the line containing @code{@@noindent} does not generate a 8335blank line, and neither does the @code{@@end example} line. 8336 8337In the Texinfo source file for this manual, each line that says 8338`produces' is preceded by @code{@@noindent}. 8339 8340Do not put braces after an @code{@@noindent} command; they are not 8341necessary, since @code{@@noindent} is a command used outside of 8342paragraphs (@pxref{Command Syntax}). 8343 8344 8345@node indent 8346@section @code{@@indent}: Forcing Indentation 8347@cindex Forcing indentation 8348@cindex Inserting indentation 8349@cindex Indentation, forcing 8350@findex indent 8351 8352@indent 8353To complement the @code{@@noindent} command (see the previous 8354section), Texinfo provides the @code{@@indent} command that forces a 8355paragraph to be indented. This paragraph, for instance, is indented 8356using an @code{@@indent} command. The first paragraph of a section is 8357the most likely place to use @code{@@indent}, to override the normal 8358behavior of no indentation there (@pxref{paragraphindent}). 8359 8360It is best to write @code{@@indent} on a line by itself, since in most 8361environments, spaces following the command will not be ignored. The 8362@code{@@indent} line will not generate a blank line in the Info output 8363within an environment. 8364 8365However, it is ok to use it at the beginning of a line, with text 8366following, outside of any environment. 8367 8368Do not put braces after an @code{@@indent} command; they are not 8369necessary, since @code{@@indent} is a command used outside of 8370paragraphs (@pxref{Command Syntax}). 8371 8372 8373@node cartouche 8374@section @code{@@cartouche}: Rounded Rectangles Around Examples 8375@findex cartouche 8376@cindex Box with rounded corners 8377@cindex Rounded rectangles, around examples 8378 8379In a printed manual, the @code{@@cartouche} command draws a box with 8380rounded corners around its contents. In HTML, a normal rectangle is 8381drawn (that's the best HTML can do). @code{@@cartouche} has no effect 8382in Info output. 8383 8384You can use this command to further highlight an example or quotation. 8385For instance, you could write a manual in which one type of example is 8386surrounded by a cartouche for emphasis. 8387 8388For example, 8389 8390@example 8391@@cartouche 8392@@example 8393% pwd 8394/usr/local/share/emacs 8395@@end example 8396@@end cartouche 8397@end example 8398 8399@noindent 8400surrounds the two-line example with a box with rounded corners, in the 8401printed manual. 8402 8403The output from the example looks like this (if you're reading this in 8404Info, you'll see the @code{@@cartouche} had no effect): 8405 8406@cartouche 8407@example 8408% pwd 8409/usr/local/info 8410@end example 8411@end cartouche 8412 8413For proper output in HTML, it's necessary to put the 8414@code{@@cartouche} around the @code{@@example}, and not the other way 8415around. This limitation of @command{makeinfo} may be removed one day. 8416 8417@code{@@cartouche} also implies @code{@@group} (@pxref{group}). 8418 8419@node Lists and Tables 8420@chapter Lists and Tables 8421@cindex Making lists and tables 8422@cindex Lists and tables, making 8423@cindex Tables and lists, making 8424 8425Texinfo has several ways of making lists and tables. Lists can be 8426bulleted or numbered; two-column tables can highlight the items in 8427the first column; multi-column tables are also supported. 8428 8429@menu 8430* Introducing Lists:: Texinfo formats lists for you. 8431* itemize:: How to construct a simple list. 8432* enumerate:: How to construct a numbered list. 8433* Two-column Tables:: How to construct a two-column table. 8434* Multi-column Tables:: How to construct generalized tables. 8435@end menu 8436 8437@node Introducing Lists 8438@section Introducing Lists 8439 8440Texinfo automatically indents the text in lists or tables, and numbers 8441an enumerated list. This last feature is useful if you modify the 8442list, since you do not need to renumber it yourself.@refill 8443 8444Numbered lists and tables begin with the appropriate @@-command at the 8445beginning of a line, and end with the corresponding @code{@@end} 8446command on a line by itself. The table and itemized-list commands 8447also require that you write formatting information on the same line as 8448the beginning @@-command.@refill 8449 8450Begin an enumerated list, for example, with an @code{@@enumerate} 8451command and end the list with an @code{@@end enumerate} command. 8452Begin an itemized list with an @code{@@itemize} command, followed on 8453the same line by a formatting command such as @code{@@bullet}, and end 8454the list with an @code{@@end itemize} command.@refill 8455@findex end 8456 8457Precede each element of a list with an @code{@@item} or @code{@@itemx} 8458command.@refill 8459 8460@sp 1 8461@noindent 8462Here is an itemized list of the different kinds of table and lists:@refill 8463 8464@itemize @bullet 8465@item 8466Itemized lists with and without bullets. 8467 8468@item 8469Enumerated lists, using numbers or letters. 8470 8471@item 8472Two-column tables with highlighting. 8473@end itemize 8474 8475@sp 1 8476@noindent 8477Here is an enumerated list with the same items:@refill 8478 8479@enumerate 8480@item 8481Itemized lists with and without bullets. 8482 8483@item 8484Enumerated lists, using numbers or letters. 8485 8486@item 8487Two-column tables with highlighting. 8488@end enumerate 8489 8490@sp 1 8491@noindent 8492And here is a two-column table with the same items and their 8493@w{@@-commands}:@refill 8494 8495@table @code 8496@item @@itemize 8497Itemized lists with and without bullets. 8498 8499@item @@enumerate 8500Enumerated lists, using numbers or letters. 8501 8502@item @@table 8503@itemx @@ftable 8504@itemx @@vtable 8505Two-column tables, optionally with indexing. 8506@end table 8507 8508 8509@node itemize 8510@section @code{@@itemize}: Making an Itemized List 8511@cindex Itemization 8512@findex itemize 8513 8514The @code{@@itemize} command produces sequences of indented 8515paragraphs, with a bullet or other mark inside the left margin 8516at the beginning of each paragraph for which such a mark is desired.@refill 8517 8518@cindex @code{@@w}, for blank items 8519Begin an itemized list by writing @code{@@itemize} at the beginning of 8520a line. Follow the command, on the same line, with a character or a 8521Texinfo command that generates a mark. Usually, you will write 8522@code{@@bullet} after @code{@@itemize}, but you can use 8523@code{@@minus}, or any command or character that results in a single 8524character in the Info file. If you don't want any mark at all, use 8525@code{@@w}. (When you write the mark command such as 8526@code{@@bullet} after an @code{@@itemize} command, you may omit the 8527@samp{@{@}}.) If you don't specify a mark command, the default is 8528@code{@@bullet}. 8529 8530Write the text of the indented paragraphs themselves after the 8531@code{@@itemize}, up to another line that says @code{@@end 8532itemize}.@refill 8533 8534@findex item 8535At the beginning of each paragraph for which a mark in the margin is 8536desired, write a line that starts with @code{@@item}. It is ok to 8537have text following the @code{@@item}. 8538 8539Usually, you should put a blank line before an @code{@@item}. This 8540puts a blank line in the Info file. (@TeX{} inserts the proper 8541interline whitespace in either case.) Except when the entries are 8542very brief, these blank lines make the list look better.@refill 8543 8544Here is an example of the use of @code{@@itemize}, followed by the 8545output it produces. @code{@@bullet} produces an @samp{*} in Info and a 8546round dot in @TeX{}. 8547 8548@example 8549@group 8550@@itemize @@bullet 8551@@item 8552Some text for foo. 8553 8554@@item 8555Some text 8556for bar. 8557@@end itemize 8558@end group 8559@end example 8560 8561@noindent 8562This produces: 8563 8564@quotation 8565@itemize @bullet 8566@item 8567Some text for foo. 8568 8569@item 8570Some text 8571for bar. 8572@end itemize 8573@end quotation 8574 8575Itemized lists may be embedded within other itemized lists. Here is a 8576list marked with dashes embedded in a list marked with bullets:@refill 8577 8578@example 8579@group 8580@@itemize @@bullet 8581@@item 8582First item. 8583 8584@@itemize @@minus 8585@@item 8586Inner item. 8587 8588@@item 8589Second inner item. 8590@@end itemize 8591 8592@@item 8593Second outer item. 8594@@end itemize 8595@end group 8596@end example 8597 8598@noindent 8599This produces: 8600 8601@quotation 8602@itemize @bullet 8603@item 8604First item. 8605 8606@itemize @minus 8607@item 8608Inner item. 8609 8610@item 8611Second inner item. 8612@end itemize 8613 8614@item 8615Second outer item. 8616@end itemize 8617@end quotation 8618 8619 8620@node enumerate 8621@section @code{@@enumerate}: Making a Numbered or Lettered List 8622@cindex Enumeration 8623@findex enumerate 8624 8625@code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,, 8626@code{@@itemize}}), except that the labels on the items are 8627successive integers or letters instead of bullets. 8628 8629Write the @code{@@enumerate} command at the beginning of a line. The 8630command does not require an argument, but accepts either a number or a 8631letter as an option. Without an argument, @code{@@enumerate} starts the 8632list with the number @samp{1}. With a numeric argument, such as 8633@samp{3}, the command starts the list with that number. With an upper 8634or lower case letter, such as @samp{a} or @samp{A}, the command starts 8635the list with that letter. 8636 8637Write the text of the enumerated list in the same way as an itemized 8638list: write a line starting with @code{@@item} at the beginning of 8639each paragraph that you want enumerated. It is ok to have text 8640following the @code{@@item}. 8641 8642You should put a blank line between entries in the list. 8643This generally makes it easier to read the Info file. 8644 8645@need 1500 8646Here is an example of @code{@@enumerate} without an argument: 8647 8648@example 8649@group 8650@@enumerate 8651@@item 8652Underlying causes. 8653 8654@@item 8655Proximate causes. 8656@@end enumerate 8657@end group 8658@end example 8659 8660@noindent 8661This produces: 8662 8663@enumerate 8664@item 8665Underlying causes. 8666 8667@item 8668Proximate causes. 8669@end enumerate 8670@sp 1 8671Here is an example with an argument of @kbd{3}:@refill 8672@sp 1 8673@example 8674@group 8675@@enumerate 3 8676@@item 8677Predisposing causes. 8678 8679@@item 8680Precipitating causes. 8681 8682@@item 8683Perpetuating causes. 8684@@end enumerate 8685@end group 8686@end example 8687 8688@noindent 8689This produces: 8690 8691@enumerate 3 8692@item 8693Predisposing causes. 8694 8695@item 8696Precipitating causes. 8697 8698@item 8699Perpetuating causes. 8700@end enumerate 8701@sp 1 8702Here is a brief summary of the alternatives. The summary is constructed 8703using @code{@@enumerate} with an argument of @kbd{a}.@refill 8704@sp 1 8705@enumerate a 8706@item 8707@code{@@enumerate} 8708 8709Without an argument, produce a numbered list, starting with the number 87101.@refill 8711 8712@item 8713@code{@@enumerate @var{positive-integer}} 8714 8715With a (positive) numeric argument, start a numbered list with that 8716number. You can use this to continue a list that you interrupted with 8717other text.@refill 8718 8719@item 8720@code{@@enumerate @var{upper-case-letter}} 8721 8722With an upper case letter as argument, start a list 8723in which each item is marked 8724by a letter, beginning with that upper case letter.@refill 8725 8726@item 8727@code{@@enumerate @var{lower-case-letter}} 8728 8729With a lower case letter as argument, start a list 8730in which each item is marked by 8731a letter, beginning with that lower case letter.@refill 8732@end enumerate 8733 8734You can also nest enumerated lists, as in an outline.@refill 8735 8736@node Two-column Tables 8737@section Making a Two-column Table 8738@cindex Tables, making two-column 8739@findex table 8740 8741@code{@@table} is similar to @code{@@itemize} (@pxref{itemize,, 8742@code{@@itemize}}), but allows you to specify a name or heading line for 8743each item. The @code{@@table} command is used to produce two-column 8744tables, and is especially useful for glossaries, explanatory 8745exhibits, and command-line option summaries. 8746 8747@menu 8748* table:: How to construct a two-column table. 8749* ftable vtable:: Automatic indexing for two-column tables. 8750* itemx:: How to put more entries in the first column. 8751@end menu 8752 8753@node table 8754@subsection Using the @code{@@table} Command 8755 8756@cindex Definition lists, typesetting 8757Use the @code{@@table} command to produce two-column tables. It is 8758usually listed for ``definition lists'' of various sorts, where you 8759have a list of terms and a brief text with each one. 8760 8761Write the @code{@@table} command at the beginning of a line, after a 8762blank line, and follow it on the same line with an argument that is a 8763Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp}, 8764@code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}). 8765 8766This command will be applied to the text that goes into the first 8767column of each item and thus determines how it will be highlighted. 8768For example, @code{@@table @@code} will cause the text in the first 8769column to be output as if it @code{@@code} command. 8770 8771@findex asis 8772You may also use the @code{@@asis} command as an argument to 8773@code{@@table}. @code{@@asis} is a command that does nothing; if you 8774use this command after @code{@@table}, the first column entries are 8775output without added highlighting (``as is''). 8776 8777The @code{@@table} command works with other commands besides those 8778explicitly mentioned here. However, you can only use commands that 8779normally take arguments in braces. (In this case, however, you use 8780the command name without an argument, because the subsequent 8781@code{@@item}'s will supply the argument.) 8782 8783@findex item 8784Begin each table entry with an @code{@@item} command at the beginning 8785of a line. Write the first column text on the same line as the 8786@code{@@item} command. Write the second column text on the line 8787following the @code{@@item} line and on subsequent lines. (You do not 8788need to type anything for an empty second column entry.) You may 8789write as many lines of supporting text as you wish, even several 8790paragraphs. But only the text on the same line as the @code{@@item} 8791will be placed in the first column (including any footnotes). 8792 8793Normally, you should put a blank line before an @code{@@item} line. 8794This puts a blank line in the Info file. Except when the entries are 8795very brief, a blank line looks better. 8796 8797End the table with a line consisting of @code{@@end table}, followed 8798by a blank line. @TeX{} will always start a new paragraph after the 8799table, so the blank line is needed for the Info output to be analogous. 8800 8801@need 1500 8802The following table, for example, highlights the text in the first 8803column with an @code{@@samp} command: 8804 8805@example 8806@group 8807@@table @@samp 8808@@item foo 8809This is the text for 8810@@samp@{foo@}. 8811 8812@@item bar 8813Text for @@samp@{bar@}. 8814@@end table 8815@end group 8816@end example 8817 8818@noindent 8819This produces: 8820 8821@table @samp 8822@item foo 8823This is the text for 8824@samp{foo}. 8825@item bar 8826Text for @samp{bar}. 8827@end table 8828 8829If you want to list two or more named items with a single block of 8830text, use the @code{@@itemx} command. (@xref{itemx,,@code{@@itemx}}.) 8831 8832 8833@node ftable vtable 8834@subsection @code{@@ftable} and @code{@@vtable} 8835@cindex Tables with indexes 8836@cindex Indexing table entries automatically 8837@findex ftable 8838@findex vtable 8839 8840The @code{@@ftable} and @code{@@vtable} commands are the same as the 8841@code{@@table} command except that @code{@@ftable} automatically enters 8842each of the items in the first column of the table into the index of 8843functions and @code{@@vtable} automatically enters each of the items in 8844the first column of the table into the index of variables. This 8845simplifies the task of creating indices. Only the items on the same 8846line as the @code{@@item} commands are indexed, and they are indexed in 8847exactly the form that they appear on that line. @xref{Indices}, 8848for more information about indices.@refill 8849 8850Begin a two-column table using @code{@@ftable} or @code{@@vtable} by 8851writing the @@-command at the beginning of a line, followed on the same 8852line by an argument that is a Texinfo command such as @code{@@code}, 8853exactly as you would for an @code{@@table} command; and end the table 8854with an @code{@@end ftable} or @code{@@end vtable} command on a line by 8855itself. 8856 8857See the example for @code{@@table} in the previous section. 8858 8859@node itemx 8860@subsection @code{@@itemx} 8861@cindex Two named items for @code{@@table} 8862@findex itemx 8863 8864Use the @code{@@itemx} command inside a table when you have two or more 8865first column entries for the same item, each of which should appear on a 8866line of its own. 8867 8868Use @code{@@item} for the first entry, and @code{@@itemx} for all 8869subsequent entries; @code{@@itemx} must always follow an @code{@@item} 8870command, with no blank line intervening. 8871 8872The @code{@@itemx} command works exactly like @code{@@item} except 8873that it does not generate extra vertical space above the first column 8874text. If you have multiple consecutive @code{@@itemx} commands, do 8875not insert any blank lines between them. 8876 8877For example, 8878 8879@example 8880@group 8881@@table @@code 8882@@item upcase 8883@@itemx downcase 8884These two functions accept a character or a string as 8885argument, and return the corresponding upper case (lower 8886case) character or string. 8887@@end table 8888@end group 8889@end example 8890 8891@noindent 8892This produces: 8893 8894@table @code 8895@item upcase 8896@itemx downcase 8897These two functions accept a character or a string as 8898argument, and return the corresponding upper case (lower 8899case) character or string.@refill 8900@end table 8901 8902@noindent 8903(Note also that this example illustrates multi-line supporting text in 8904a two-column table.)@refill 8905 8906 8907@node Multi-column Tables 8908@section @code{@@multitable}: Multi-column Tables 8909@cindex Tables, making multi-column 8910@findex multitable 8911 8912@code{@@multitable} allows you to construct tables with any number of 8913columns, with each column having any width you like. 8914 8915You define the column widths on the @code{@@multitable} line itself, and 8916write each row of the actual table following an @code{@@item} command, 8917with columns separated by an @code{@@tab} command. Finally, @code{@@end 8918multitable} completes the table. Details in the sections below. 8919 8920@menu 8921* Multitable Column Widths:: Defining multitable column widths. 8922* Multitable Rows:: Defining multitable rows, with examples. 8923@end menu 8924 8925@node Multitable Column Widths 8926@subsection Multitable Column Widths 8927@cindex Multitable column widths 8928@cindex Column widths, defining for multitables 8929@cindex Widths, defining multitable column 8930 8931You can define the column widths for a multitable in two ways: as 8932fractions of the line length; or with a prototype row. Mixing the two 8933methods is not supported. In either case, the widths are defined 8934entirely on the same line as the @code{@@multitable} command. 8935 8936@enumerate 8937@item 8938@findex columnfractions 8939@cindex Line length, column widths as fraction of 8940To specify column widths as fractions of the line length, write 8941@code{@@columnfractions} and the decimal numbers (presumably less than 89421; a leading zero is allowed and ignored) after the 8943@code{@@multitable} command, as in: 8944 8945@example 8946@@multitable @@columnfractions .33 .33 .33 8947@end example 8948 8949The fractions need not add up exactly to 1.0, as these do not. This 8950allows you to produce tables that do not need the full line length. 8951 8952@item 8953@cindex Prototype row, column widths defined by 8954To specify a prototype row, write the longest entry for each column 8955enclosed in braces after the @code{@@multitable} command. For example: 8956 8957@example 8958@@multitable @{some text for column one@} @{for column two@} 8959@end example 8960 8961@noindent 8962The first column will then have the width of the typeset `some text for 8963column one', and the second column the width of `for column two'. 8964 8965The prototype entries need not appear in the table itself. 8966 8967Although we used simple text in this example, the prototype entries can 8968contain Texinfo commands; markup commands such as @code{@@code} are 8969particularly likely to be useful. 8970 8971@end enumerate 8972 8973 8974@node Multitable Rows 8975@subsection Multitable Rows 8976@cindex Multitable rows 8977@cindex Rows, of a multitable 8978 8979@findex item 8980@findex tab 8981After the @code{@@multitable} command defining the column widths (see 8982the previous section), you begin each row in the body of a multitable 8983with @code{@@item}, and separate the column entries with @code{@@tab}. 8984Line breaks are not special within the table body, and you may break 8985input lines in your source file as necessary. 8986 8987@findex headitem 8988@cindex Heading row, in table 8989@cindex <thead> HTML tag 8990You can also use @code{@@headitem} instead of @code{@@item} to produce 8991a @dfn{heading row}. The @TeX{} output for such a row is in bold, and 8992the HTML, XML, and Docbook output uses the @code{<thead>} tag. 8993 8994Here is a complete example of a multi-column table (the text is from 8995@cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows, 8996emacs, The GNU Emacs Manual}): 8997 8998@example 8999@@multitable @@columnfractions .15 .45 .4 9000@@headitem Key @@tab Command @@tab Description 9001@@item C-x 2 9002@@tab @@code@{split-window-vertically@} 9003@@tab Split the selected window into two windows, 9004with one above the other. 9005@@item C-x 3 9006@@tab @@code@{split-window-horizontally@} 9007@@tab Split the selected window into two windows 9008positioned side by side. 9009@@item C-Mouse-2 9010@@tab 9011@@tab In the mode line or scroll bar of a window, 9012split that window. 9013@@end multitable 9014@end example 9015 9016@noindent produces: 9017 9018@multitable @columnfractions .15 .45 .4 9019@headitem Key @tab Command @tab Description 9020@item C-x 2 9021@tab @code{split-window-vertically} 9022@tab Split the selected window into two windows, 9023with one above the other. 9024@item C-x 3 9025@tab @code{split-window-horizontally} 9026@tab Split the selected window into two windows 9027positioned side by side. 9028@item C-Mouse-2 9029@tab 9030@tab In the mode line or scroll bar of a window, 9031split that window. 9032@end multitable 9033 9034 9035@node Special Displays 9036@chapter Special Displays 9037@cindex Special displays 9038 9039The commands in this chapter allow you to write text that is specially 9040displayed (output format permitting), outside of the normal document 9041flow. 9042 9043One set of such commands is for creating ``floats'', that is, figures, 9044tables, and the like, set off from the main text, possibly numbered, 9045captioned, and/or referred to from elsewhere in the document. Images 9046are often included in these displays. 9047 9048Another group of commands is for creating footnotes in Texinfo. 9049 9050@menu 9051* Floats:: Figures, tables, and the like. 9052* Images:: Including graphics and images. 9053* Footnotes:: Writing footnotes. 9054@end menu 9055 9056 9057@node Floats 9058@section Floats 9059@cindex Floats, in general 9060 9061A @dfn{float} is a display which is set off from the main text. It is 9062typically labelled as being a ``Figure'', ``Table'', ``Example'', or 9063some similar type. 9064 9065@cindex Floating, not yet implemented 9066A float is so-named because, in principle, it can be moved to the 9067bottom or top of the current page, or to a following page, in the 9068printed output. (Floating does not make sense in other output 9069formats.) In the present version of Texinfo, however, this floating 9070is unfortunately not yet implemented. Instead, the floating material 9071is simply output at the current location, more or less as if it were 9072an @code{@@group} (@pxref{group,,@code{@@group}}). 9073 9074@menu 9075* float:: Producing floating material. 9076* caption shortcaption:: Specifying descriptions for floats. 9077* listoffloats:: A table of contents for floats. 9078@end menu 9079 9080 9081@node float 9082@subsection @code{@@float} [@var{type}][,@var{label}]: Floating material 9083@findex float 9084@cindex Float environment 9085 9086To produce floating material, enclose the material you want to be 9087displayed separate between @code{@@float} and @code{@@end float} 9088commands, on lines by themselves. 9089 9090Floating material uses @code{@@image} to display an already-existing 9091graphic (@pxref{Images}), or @code{@@multitable} to display a table 9092(@pxref{Multi-column Tables}). However, the contents of the float can 9093be anything. Here's an example with simple text: 9094 9095@example 9096@@float Figure,fig:ex1 9097This is an example float. 9098@@end float 9099@end example 9100 9101@noindent And the output: 9102 9103@float Figure,fig:ex1 9104This is an example float. 9105@end float 9106 9107As shown in the example, @code{@@float} takes two arguments (separated 9108by a comma), @var{type} and @var{label}. Both are optional. 9109 9110@table @var 9111@item type 9112Specifies the sort of float this is; typically a word such as 9113``Figure'', ``Table'', etc. If not given, and @var{label} is, any 9114cross-referencing will simply use a bare number. 9115 9116@item label 9117Specifies a cross-reference label for this float. If given, this 9118float is automatically given a number, and will appear in any 9119@code{@@listofloats} output (@pxref{listoffloats}). Cross-references 9120to @var{label} are allowed. 9121 9122@cindex Floats, making unnumbered 9123@cindex Unnumbered float, creating 9124On the other hand, if @var{label} is not given, then the float will 9125not be numbered and consequently will not appear in the 9126@code{@@listoffloats} output or be cross-referenceable. 9127@end table 9128 9129@noindent Normally, you specify both @var{type} and @var{label}, to get a 9130labeled and numbered float. 9131 9132@cindex Floats, numbering of 9133@cindex Numbering of floats 9134In Texinfo, all floats are numbered the same way: with the chapter 9135number (or appendix letter), a period, and the float number, which 9136simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each 9137float type is counted independently. 9138 9139Floats within an @code{@@unnumbered} are numbered, or outside of any 9140chapter, are simply numbered consecutively from 1. 9141 9142These numbering conventions are not, at present, changeable. 9143 9144 9145@node caption shortcaption 9146@subsection @code{@@caption} & @code{@@shortcaption} 9147@findex caption 9148@findex shortcaption 9149@cindex Captions, for floats 9150@cindex Short captions, for lists of floats 9151 9152You may write an @code{@@caption} anywhere within a @code{@@float} 9153environment, to define a caption for the float. It is not allowed in 9154any other context. @code{@@caption} takes a single argument, enclosed 9155in braces. Here's an example: 9156 9157@example 9158@@float 9159An example float, with caption. 9160@@caption@{Caption for example float.@} 9161@@end float 9162@end example 9163 9164@noindent The output is: 9165 9166@float 9167An example float, with caption. 9168@caption{Caption for example float.} 9169@end float 9170 9171@code{@@caption} can appear anywhere within the float; it is not 9172processed until the @code{@@end float}. The caption text is usually a 9173sentence or two, but may consist of several paragraphs if necessary. 9174 9175In the output, the caption always appears below the float; this is not 9176currently changeable. It is preceded by the float type and/or number, 9177as specified to the @code{@@float} command (see the previous section). 9178 9179The @code{@@shortcaption} command likewise may be used only within 9180@code{@@float}, and takes a single argument in braces. The short 9181caption text is used instead of the caption text in a list of floats 9182(see the next section). Thus, you can write a long caption for the 9183main document, and a short title to appear in the list of floats. For 9184example: 9185 9186@example 9187@@float 9188... as above ... 9189@@shortcaption@{Text for list of floats.@} 9190@@end float 9191@end example 9192 9193The text for @code{@@caption} and @code{@@shortcaption} may not 9194contain comments (@code{@@c}), verbatim text (@code{@@verb}), 9195environments such as @code{@@example}, or other complex constructs. 9196 9197 9198@node listoffloats 9199@subsection @code{@@listoffloats}: Tables of contents for floats 9200@findex listoffloats 9201@cindex List of floats 9202@cindex Floats, list of 9203@cindex Table of contents, for floats 9204 9205You can write a @code{@@listoffloats} command to generate a list of 9206floats for a given float type (@pxref{float}), analogous to the 9207document's overall table of contents. Typically, it is written in its 9208own @code{@@unnumbered} node to provide a heading and structure, 9209rather like @code{@@printindex} (@pxref{Printing Indices & Menus}). 9210 9211@code{@@listoffloats} takes one optional argument, the float type. 9212Here's an example: 9213 9214@example 9215@@node List of Figures 9216@@unnumbered List of Figures 9217@@listoffloats Figure 9218@end example 9219 9220@noindent And the output from @code{@@listoffloats}: 9221 9222@display 9223@listoffloats Figure 9224@end display 9225 9226Without any argument, @code{@@listoffloats} generates a list of 9227floats for which no float type was specified, i.e., no first argument 9228to the @code{@@float} command (@pxref{float}). 9229 9230Each line in the list of floats contains the float type (if any), 9231the float number, and the caption, if any---the @code{@@shortcaption} 9232argument, if it was specified, else the @code{@@caption} argument. 9233In Info, the result is a menu where each float can be selected. In 9234HTML, each line is a link to the float. In printed output, the page 9235number is included. 9236 9237Unnumbered floats (those without cross-reference labels) are omitted 9238from the list of floats. 9239 9240 9241@node Images 9242@section Inserting Images 9243 9244@cindex Images, inserting 9245@cindex Pictures, inserting 9246@findex image 9247 9248You can insert an image given in an external file with the 9249@code{@@image} command. Although images can be used anywhere, 9250including the middle of a paragraph, we describe them in this chapter 9251since they are most often part of a displayed figure or example. 9252 9253@menu 9254* Image Syntax:: 9255* Image Scaling:: 9256@end menu 9257 9258 9259@node Image Syntax 9260@subsection Image Syntax 9261 9262Here is the basic synopsis of the @code{@@image} command: 9263 9264@example 9265@@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@} 9266@end example 9267 9268@cindex Formats for images 9269@cindex Image formats 9270The @var{filename} argument is mandatory, and must not have an 9271extension, because the different processors support different formats: 9272 9273@itemize @bullet 9274@item 9275@TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript 9276format). 9277@item 9278@pindex pdftex@r{, and images} 9279PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format). 9280@item 9281@code{makeinfo} includes @file{@var{filename}.txt} verbatim for 9282Info output (more or less as if it was an @code{@@example}). 9283@item 9284@code{makeinfo} uses the optional fifth argument @var{extension} to 9285@code{@@image} for the filename extension, if it is specified. For example: 9286 9287@pindex XPM image format 9288@example 9289@@image@{foo,,,,.xpm@} 9290@end example 9291 9292@noindent 9293will cause @code{makeinfo} to look for @file{foo.xpm} before any others. 9294 9295@end itemize 9296 9297The @var{width} and @var{height} arguments are described in the next 9298section. 9299 9300For @TeX{} output, if an image is the first thing in a paragraph, for 9301example if you want two images side-by-side, you must precede it with 9302@code{@@noindent} (@pxref{noindent,,@code{@@noindent}}). Otherwise it 9303will be displayed on a line by itself. If you want it centered, 9304use @code{@@center} (@pxref{titlefont center sp,,@code{@@titlefont 9305@@center @@sp}}). 9306 9307@cindex Alt attribute for images 9308@cindex Images, alternate text for 9309When producing html, @code{makeinfo} sets the @dfn{alt attribute} for 9310inline images to the optional @var{alttext} (fourth) argument to 9311@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses 9312the full file name of the image being displayed. If you want an empty 9313@code{alt} string, use @code{@@-}. The @var{alttext} is taken as 9314Texinfo text, so special characters such as @samp{"} and @samp{<} and 9315@samp{&} are escaped in the HTML and XML output. 9316 9317@cindex GIF images, unsupported due to patents 9318@cindex PNG image format 9319@cindex JPG image format 9320If you do not supply the optional @var{extension} (fifth) argument, 9321@code{makeinfo} first tries @file{@var{filename}.png}; if that does 9322not exist, it tries @file{@var{filename}.jpg}. If that does not exist 9323either, it complains. (We cannot support GIF format directly due to 9324software patents.) 9325 9326In Info output, @code{makeinfo} writes a reference to the binary image 9327file (trying @var{filename} suffixed with @file{@var{extension}}, 9328@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order) 9329if one exists. It also literally includes the @file{.txt} file if one 9330exists. This way, Info readers which can display images (such as the 9331Emacs Info browser, running under X) can do so, whereas Info readers 9332which can only use text (such as the standalone Info reader) can 9333display the textual version. 9334 9335The implementation of this is to put the following construct into the 9336Info output: 9337 9338@example 9339^@@^H[image src="@var{binaryfile}" text="@var{txtfile}" 9340 alt="@var{alttext} ... ^@@^H] 9341@end example 9342 9343@noindent where @samp{^@@} and @samp{^H} stand for the actual null and 9344backspace control characters. If one of the files is not present, the 9345corresponding argument is omitted. 9346 9347The reason for mentioning this here is that older Info browsers (this 9348feature was introduced in Texinfo version 4.6) will display the above 9349literally, which, although not pretty, should not be harmful. 9350 9351 9352@node Image Scaling 9353@subsection Image Scaling 9354 9355@cindex Images, scaling 9356@cindex Scaling images 9357@cindex Width of images 9358@cindex Height of images 9359@cindex Aspect ratio of images 9360@cindex Distorting images 9361The optional @var{width} and @var{height} arguments to the 9362@code{@@image} command (see the previous section) specify the size to 9363scale the image to. They are ignored for Info output. If neither is 9364specified, the image is presented in its natural size (given in the 9365file); if only one is specified, the other is scaled proportionately; 9366and if both are specified, both are respected, thus possibly distorting 9367the original image by changing its aspect ratio. 9368 9369@cindex Dimensions and image sizes 9370The @var{width} and @var{height} may be specified using any valid @TeX{} 9371dimension, namely: 9372 9373@table @asis 9374@item pt 9375@cindex Points (dimension) 9376point (72.27pt = 1in) 9377@item pc 9378@cindex Picas 9379pica (1pc = 12pt) 9380@item bp 9381@cindex Big points 9382big point (72bp = 1in) 9383@item in 9384@cindex Inches 9385inch 9386@item cm 9387@cindex Centimeters 9388centimeter (2.54cm = 1in) 9389@item mm 9390@cindex Millimeters 9391millimeter (10mm = 1cm) 9392@item dd 9393@cindex Did@^ot points 9394did@^ot point (1157dd = 1238pt) 9395@item cc 9396@cindex Ciceros 9397cicero (1cc = 12dd) 9398@item sp 9399@cindex Scaled points 9400scaled point (65536sp = 1pt) 9401@end table 9402 9403@pindex ridt.eps 9404For example, the following will scale a file @file{ridt.eps} to one 9405inch vertically, with the width scaled proportionately: 9406 9407@example 9408@@image@{ridt,,1in@} 9409@end example 9410 9411@pindex epsf.tex 9412For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be 9413installed somewhere that @TeX{} can find it. (The standard location is 9414@file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a 9415root of your @TeX{} directory tree.) This file is included in the 9416Texinfo distribution and is also available from 9417@uref{ftp://tug.org/tex/epsf.tex}, among other places. 9418 9419@code{@@image} can be used within a line as well as for displayed 9420figures. Therefore, if you intend it to be displayed, be sure to leave 9421a blank line before the command, or the output will run into the 9422preceding text. 9423 9424Image scaling is presently implemented only in @TeX{}, not in HTML or 9425any other sort of output. 9426 9427 9428@node Footnotes 9429@section Footnotes 9430@cindex Footnotes 9431@findex footnote 9432 9433A @dfn{footnote} is for a reference that documents or elucidates the 9434primary text.@footnote{A footnote should complement or expand upon 9435the primary text, but a reader should not need to read a footnote to 9436understand the primary text. For a thorough discussion of footnotes, 9437see @cite{The Chicago Manual of Style}, which is published by the 9438University of Chicago Press.} Footnotes are distracting; use them 9439sparingly, if at all. Standard bibliographical references are better 9440placed in a bibliography at the end of a document than in footnotes 9441throughout. 9442 9443@menu 9444* Footnote Commands:: How to write a footnote in Texinfo. 9445* Footnote Styles:: Controlling how footnotes appear in Info. 9446@end menu 9447 9448 9449@node Footnote Commands 9450@subsection Footnote Commands 9451 9452In Texinfo, footnotes are created with the @code{@@footnote} command. 9453This command is followed immediately by a left brace, then by the text 9454of the footnote, and then by a terminating right brace. Footnotes may 9455be of any length (they will be broken across pages if necessary), but 9456are usually short. The template is: 9457 9458@example 9459ordinary text@@footnote@{@var{text of footnote}@} 9460@end example 9461 9462As shown here, the @code{@@footnote} command should come right after the 9463text being footnoted, with no intervening space; otherwise, the footnote 9464marker might end up starting a line. 9465 9466For example, this clause is followed by a sample footnote@footnote{Here 9467is the sample footnote.}; in the Texinfo source, it looks like 9468this: 9469 9470@example 9471@dots{}a sample footnote@@footnote@{Here is the sample 9472footnote.@}; in the Texinfo source@dots{} 9473@end example 9474 9475As you can see, the source includes two punctuation marks next to each 9476other; in this case, @samp{.@};} is the sequence. This is normal (the 9477first ends the footnote and the second belongs to the sentence being 9478footnoted), so don't worry that it looks odd. 9479 9480In a printed manual or book, the reference mark for a footnote is a 9481small, superscripted number; the text of the footnote appears at the 9482bottom of the page, below a horizontal line. 9483 9484In Info, the reference mark for a footnote is a pair of parentheses 9485with the footnote number between them, like this: @samp{(1)}. The 9486reference mark is followed by a cross-reference link to the footnote's 9487text. 9488 9489In the HTML output, footnote references are marked with a small, 9490superscripted number which is rendered as a hypertext link to the 9491footnote text. 9492 9493By the way, footnotes in the argument of an @code{@@item} command for a 9494@code{@@table} must be on the same line as the @code{@@item} 9495(as usual). @xref{Two-column Tables}. 9496 9497 9498@node Footnote Styles 9499@subsection Footnote Styles 9500 9501Info has two footnote styles, which determine where the text of the 9502footnote is located: 9503 9504@itemize @bullet 9505@cindex @samp{@r{End}} node footnote style 9506@item 9507In the `End' node style, all the footnotes for a single node 9508are placed at the end of that node. The footnotes are separated from 9509the rest of the node by a line of dashes with the word 9510@samp{Footnotes} within it. Each footnote begins with an 9511@samp{(@var{n})} reference mark. 9512 9513@need 700 9514@noindent 9515Here is an example of a single footnote in the end of node style:@refill 9516 9517@example 9518@group 9519--------- Footnotes --------- 9520 9521(1) Here is a sample footnote. 9522@end group 9523@end example 9524 9525@cindex @samp{@r{Separate}} footnote style 9526@item 9527In the `Separate' node style, all the footnotes for a single 9528node are placed in an automatically constructed node of 9529their own. In this style, a ``footnote reference'' follows 9530each @samp{(@var{n})} reference mark in the body of the 9531node. The footnote reference is actually a cross reference 9532which you use to reach the footnote node. 9533 9534The name of the node with the footnotes is constructed 9535by appending @w{@samp{-Footnotes}} to the name of the node 9536that contains the footnotes. (Consequently, the footnotes' 9537node for the @file{Footnotes} node is 9538@w{@file{Footnotes-Footnotes}}!) The footnotes' node has an 9539`Up' node pointer that leads back to its parent node. 9540 9541@noindent 9542Here is how the first footnote in this manual looks after being 9543formatted for Info in the separate node style: 9544 9545@smallexample 9546@group 9547File: texinfo.info Node: Overview-Footnotes, Up: Overview 9548 9549(1) The first syllable of "Texinfo" is pronounced like "speck", not 9550"hex". @dots{} 9551@end group 9552@end smallexample 9553@end itemize 9554 9555Unless your document has long and important footnotes (as in, say, 9556Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end} 9557style, as it is simpler for readers to follow. 9558 9559@findex footnotestyle 9560Use the @code{@@footnotestyle} command to specify an Info file's 9561footnote style. Write this command at the beginning of a line followed 9562by an argument, either @samp{end} for the end node style or 9563@samp{separate} for the separate node style. 9564 9565@need 700 9566For example, 9567 9568@example 9569@@footnotestyle end 9570@end example 9571@noindent 9572or 9573@example 9574@@footnotestyle separate 9575@end example 9576 9577Write an @code{@@footnotestyle} command before or shortly after the 9578end-of-header line at the beginning of a Texinfo file. (If you 9579include the @code{@@footnotestyle} command between the start-of-header 9580and end-of-header lines, the region formatting commands will format 9581footnotes as specified.)@refill 9582 9583If you do not specify a footnote style, the formatting commands use 9584their default style. Currently, @code{texinfo-format-buffer} and 9585@code{texinfo-format-region} use the `separate' style and 9586@code{makeinfo} uses the `end' style. 9587 9588 9589@node Indices 9590@chapter Indices 9591@cindex Indices 9592 9593Using Texinfo, you can generate indices without having to sort and 9594collate entries manually. In an index, the entries are listed in 9595alphabetical order, together with information on how to find the 9596discussion of each entry. In a printed manual, this information 9597consists of page numbers. In an Info file, this information is a menu 9598entry leading to the first node referenced. 9599 9600Texinfo provides several predefined kinds of index: an index 9601for functions, an index for variables, an index for concepts, and so 9602on. You can combine indices or use them for other than their 9603canonical purpose. Lastly, you can define your own new indices. 9604 9605@xref{Printing Indices & Menus}, for information on how to print 9606indices. 9607 9608@menu 9609* Index Entries:: Choose different words for index entries. 9610* Predefined Indices:: Use different indices for different kinds 9611 of entries. 9612* Indexing Commands:: How to make an index entry. 9613* Combining Indices:: How to combine indices. 9614* New Indices:: How to define your own indices. 9615@end menu 9616 9617 9618@node Index Entries 9619@section Making Index Entries 9620@cindex Index entries, making 9621@cindex Entries, making index 9622 9623When you are making index entries, it is good practice to think of the 9624different ways people may look for something. Different people 9625@emph{do not} think of the same words when they look something up. A 9626helpful index will have items indexed under all the different words 9627that people may use. For example, one reader may think it obvious that 9628the two-letter names for indices should be listed under ``Indices, 9629two-letter names'', since the word ``Index'' is the general concept. 9630But another reader may remember the specific concept of two-letter 9631names and search for the entry listed as ``Two letter names for 9632indices''. A good index will have both entries and will help both 9633readers.@refill 9634 9635Like typesetting, the construction of an index is a highly skilled, 9636professional art, the subtleties of which are not appreciated until you 9637need to do it yourself.@refill 9638 9639@xref{Printing Indices & Menus}, for information about printing an index 9640at the end of a book or creating an index menu in an Info file.@refill 9641 9642 9643@node Predefined Indices 9644@section Predefined Indices 9645 9646Texinfo provides six predefined indices. Here are their nominal 9647meanings, abbreviations, and the corresponding index entry commands: 9648 9649@table @samp 9650@item cp 9651@cindex @code{cp} (concept) index 9652(@code{@@cindex}) concept index, for general concepts. 9653@item fn 9654@cindex @code{fn} (function) index 9655(@code{@@findex}) function index, for function and function-like 9656names (such as entry points of libraries). 9657@item ky 9658@cindex @code{ky} (keystroke) index 9659(@code{@@kindex}) keystroke index, for keyboard commands. 9660@item pg 9661@cindex @code{pg} (program) index 9662(@code{@@pindex}) program index, for names of programs. 9663@item tp 9664@cindex @code{tp} (data type) index 9665(@code{@@tindex}) data type index, for type names (such as structures 9666defined in header files). 9667@item vr 9668@cindex @code{vr} (variable) index 9669(@code{@@vindex}) variable index, for variable names (such as global 9670variables of libraries). 9671@end table 9672 9673@noindent 9674Not every manual needs all of these, and most manuals use only two or 9675three at most. The present manual, for example, has two indices: a 9676concept index and an @@-command index (that is actually the function 9677index but is called a command index in the chapter heading). 9678 9679You are not required to use the predefined indices strictly for their 9680canonical purposes. For example, suppose you wish to index some C 9681preprocessor macros. You could put them in the function index along 9682with actual functions, just by writing @code{@@findex} commands for 9683them; then, when you print the ``Function Index'' as an unnumbered 9684chapter, you could give it the title `Function and Macro Index' and 9685all will be consistent for the reader. 9686 9687On the other hand, it is best not to stray too far from the meaning of 9688the predefined indices. Otherwise, in the event that your text is 9689combined with other text from other manuals, the index entries will 9690not match up. Instead, define your own new index (@pxref{New 9691Indices}). 9692 9693We recommend having a single index in the final document whenever 9694possible, however many source indices you use, since then readers have 9695only one place to look. Two or more source indices can be combined 9696into one output index using the @code{@@synindex} or 9697@code{@@syncodeindex} commands (@pxref{Combining Indices}). 9698 9699 9700@node Indexing Commands 9701@section Defining the Entries of an Index 9702@cindex Defining indexing entries 9703@cindex Index entries 9704@cindex Entries for an index 9705@cindex Specifying index entries 9706@cindex Creating index entries 9707 9708The data to make an index come from many individual indexing commands 9709scattered throughout the Texinfo source file. Each command says to add 9710one entry to a particular index; after formatting, the index will give 9711the current page number or node name as the reference.@refill 9712 9713An index entry consists of an indexing command at the beginning of a 9714line followed, on the rest of the line, by the entry.@refill 9715 9716For example, this section begins with the following five entries for 9717the concept index:@refill 9718 9719@example 9720@@cindex Defining indexing entries 9721@@cindex Index entries, defining 9722@@cindex Entries for an index 9723@@cindex Specifying index entries 9724@@cindex Creating index entries 9725@end example 9726 9727Each predefined index has its own indexing command---@code{@@cindex} 9728for the concept index, @code{@@findex} for the function index, and so 9729on, as listed in the previous section. 9730 9731@cindex Writing index entries 9732@cindex Index entry writing 9733Concept index entries consist of text. The best way to write an index 9734is to choose entries that are terse yet clear. If you can do this, 9735the index often looks better if the entries are not capitalized, but 9736written just as they would appear in the middle of a sentence. 9737(Capitalize proper names and acronyms that always call for upper case 9738letters.) This is the case convention we use in most GNU manuals' 9739indices. 9740 9741If you don't see how to make an entry terse yet clear, make it longer 9742and clear---not terse and confusing. If many of the entries are several 9743words long, the index may look better if you use a different convention: 9744to capitalize the first word of each entry. But do not capitalize a 9745case-sensitive name such as a C or Lisp function name or a shell 9746command; that would be a spelling error. 9747 9748Whichever case convention you use, please use it consistently! 9749 9750Entries in indices other than the concept index are symbol names in 9751programming languages, or program names; these names are usually 9752case-sensitive, so use upper and lower case as required for them. 9753 9754@cindex Index font types 9755By default, entries for a concept index are printed in a small roman 9756font and entries for the other indices are printed in a small 9757@code{@@code} font. You may change the way part of an entry is 9758printed with the usual Texinfo commands, such as @code{@@file} for 9759file names (@pxref{Marking Text}), and @code{@@r} for the normal roman 9760font (@pxref{Fonts}). 9761 9762@quotation Caution 9763Do not use a colon in an index entry. In Info, a colon separates the 9764menu entry name from the node name, so a colon in the entry itself 9765confuses Info. @xref{Menu Parts}, for more information about the 9766structure of a menu entry. 9767@end quotation 9768 9769 9770@node Combining Indices 9771@section Combining Indices 9772@cindex Combining indices 9773@cindex Indices, combining them 9774 9775Sometimes you will want to combine two disparate indices such as 9776functions and concepts, perhaps because you have few enough entries 9777that a separate index would look silly. 9778 9779You could put functions into the concept index by writing 9780@code{@@cindex} commands for them instead of @code{@@findex} commands, 9781and produce a consistent manual by printing the concept index with the 9782title `Function and Concept Index' and not printing the `Function 9783Index' at all; but this is not a robust procedure. It works only if 9784your document is never included as part of another document that is 9785designed to have a separate function index; if your document were to 9786be included with such a document, the functions from your document and 9787those from the other would not end up together. Also, to make your 9788function names appear in the right font in the concept index, you 9789would need to enclose every one of them between the braces of 9790@code{@@code}. 9791 9792@menu 9793* syncodeindex:: How to merge two indices, using @code{@@code} 9794 font for the merged-from index. 9795* synindex:: How to merge two indices, using the 9796 default font of the merged-to index. 9797@end menu 9798 9799@node syncodeindex 9800@subsection @code{@@syncodeindex} 9801@findex syncodeindex 9802 9803When you want to combine functions and concepts into one index, you 9804should index the functions with @code{@@findex} and index the concepts 9805with @code{@@cindex}, and use the @code{@@syncodeindex} command to 9806redirect the function index entries into the concept index.@refill 9807 9808The @code{@@syncodeindex} command takes two arguments; they are the name 9809of the index to redirect, and the name of the index to redirect it to. 9810The template looks like this:@refill 9811 9812@example 9813@@syncodeindex @var{from} @var{to} 9814@end example 9815 9816@cindex Predefined names for indices 9817@cindex Two letter names for indices 9818@cindex Indices, two letter names 9819@cindex Names for indices 9820For this purpose, the indices are given two-letter names:@refill 9821 9822@table @samp 9823@item cp 9824concept index 9825@item fn 9826function index 9827@item vr 9828variable index 9829@item ky 9830key index 9831@item pg 9832program index 9833@item tp 9834data type index 9835@end table 9836 9837Write an @code{@@syncodeindex} command before or shortly after the 9838end-of-header line at the beginning of a Texinfo file. For example, 9839to merge a function index with a concept index, write the 9840following:@refill 9841 9842@example 9843@@syncodeindex fn cp 9844@end example 9845 9846@noindent 9847This will cause all entries designated for the function index to merge 9848in with the concept index instead.@refill 9849 9850To merge both a variables index and a function index into a concept 9851index, write the following:@refill 9852 9853@example 9854@group 9855@@syncodeindex vr cp 9856@@syncodeindex fn cp 9857@end group 9858@end example 9859 9860@cindex Fonts for indices 9861The @code{@@syncodeindex} command puts all the entries from the `from' 9862index (the redirected index) into the @code{@@code} font, overriding 9863whatever default font is used by the index to which the entries are 9864now directed. This way, if you direct function names from a function 9865index into a concept index, all the function names are printed in the 9866@code{@@code} font as you would expect.@refill 9867 9868@node synindex 9869@subsection @code{@@synindex} 9870@findex synindex 9871 9872The @code{@@synindex} command is nearly the same as the 9873@code{@@syncodeindex} command, except that it does not put the 9874`from' index entries into the @code{@@code} font; rather it puts 9875them in the roman font. Thus, you use @code{@@synindex} when you 9876merge a concept index into a function index.@refill 9877 9878@xref{Printing Indices & Menus}, for information about printing an index 9879at the end of a book or creating an index menu in an Info file.@refill 9880 9881 9882@node New Indices 9883@section Defining New Indices 9884@cindex Defining new indices 9885@cindex Indices, defining new 9886@cindex New index defining 9887@findex defindex 9888@findex defcodeindex 9889 9890In addition to the predefined indices, you may use the 9891@code{@@defindex} and @code{@@defcodeindex} commands to define new 9892indices. These commands create new indexing @@-commands with which 9893you mark index entries. The @code{@@defindex} command is used like 9894this: 9895 9896@example 9897@@defindex @var{name} 9898@end example 9899 9900The name of an index should be a two letter word, such as @samp{au}. 9901For example: 9902 9903@example 9904@@defindex au 9905@end example 9906 9907This defines a new index, called the @samp{au} index. At the same 9908time, it creates a new indexing command, @code{@@auindex}, that you 9909can use to make index entries. Use this new indexing command just as 9910you would use a predefined indexing command. 9911 9912For example, here is a section heading followed by a concept index 9913entry and two @samp{au} index entries. 9914 9915@example 9916@@section Cognitive Semantics 9917@@cindex kinesthetic image schemas 9918@@auindex Johnson, Mark 9919@@auindex Lakoff, George 9920@end example 9921 9922@noindent 9923(Evidently, @samp{au} serves here as an abbreviation for ``author''.) 9924 9925In general, Texinfo constructs the new indexing command by 9926concatenating the name of the index with @samp{index}; thus, defining 9927an @samp{xy} index leads to the automatic creation of an 9928@code{@@xyindex} command. 9929 9930Use the @code{@@printindex} command to print the index, as you do with 9931the predefined indices. For example: 9932 9933@example 9934@group 9935@@node Author Index 9936@@unnumbered Author Index 9937 9938@@printindex au 9939@end group 9940@end example 9941 9942The @code{@@defcodeindex} is like the @code{@@defindex} command, 9943except that, in the printed output, it prints entries in an 9944@code{@@code} font by default instead of a roman font. 9945 9946You should define new indices before the end-of-header line of a 9947Texinfo file, and (of course) before any @code{@@synindex} or 9948@code{@@syncodeindex} commands (@pxref{Texinfo File Header}). 9949 9950 9951@node Insertions 9952@chapter Special Insertions 9953@cindex Inserting special characters and symbols 9954@cindex Special insertions 9955 9956Texinfo provides several commands for inserting characters that have 9957special meaning in Texinfo, such as braces, and for other graphic 9958elements that do not correspond to simple characters you can type. 9959 9960@iftex 9961These are: 9962 9963@itemize @bullet 9964@item @samp{@@} and braces and commas. 9965@item Whitespace within and around a sentence. 9966@item Accents. 9967@item Dots and bullets. 9968@item The @TeX{} logo and the copyright symbol. 9969@item The pounds currency symbol. 9970@item The minus sign. 9971@item Mathematical expressions. 9972@item Glyphs for evaluation, macros, errors, etc. 9973@item Footnotes. 9974@item Images. 9975@end itemize 9976@end iftex 9977 9978@menu 9979* Atsign Braces Comma:: Inserting @@ and @{@} and ,. 9980* Inserting Space:: How to insert the right amount of space 9981 within a sentence. 9982* Inserting Accents:: How to insert accents and special characters. 9983* Dots Bullets:: How to insert dots and bullets. 9984* TeX and copyright:: How to insert the @TeX{} logo 9985 and the copyright symbol. 9986* euro:: How to insert the Euro currency symbol. 9987* pounds:: How to insert the pounds currency symbol. 9988* minus:: How to insert a minus sign. 9989* math:: How to format a mathematical expression. 9990* Glyphs:: How to indicate results of evaluation, 9991 expansion of macros, errors, etc. 9992@end menu 9993 9994 9995@node Atsign Braces Comma 9996@section Inserting @@ and @{@} and @comma{} 9997@cindex Special characters, inserting 9998@cindex Commands to insert special characters 9999 10000@samp{@@} and curly braces are special characters in Texinfo. To insert 10001these characters so they appear in text, you must put an @samp{@@} in 10002front of these characters to prevent Texinfo from misinterpreting 10003them. 10004 10005The comma `,' is a special character only in one uncommon context: 10006it separates arguments to commands that take multiple arguments. 10007 10008@menu 10009* Inserting an Atsign:: 10010* Inserting Braces:: 10011* Inserting a Comma:: 10012@end menu 10013 10014 10015@node Inserting an Atsign 10016@subsection Inserting `@@' with @code{@@@@} 10017@findex @@ @r{(literal @samp{@@})} 10018@cindex Inserting @@ @r{(literal @samp{@@})} 10019 10020@code{@@@@} stands for a single @samp{@@} in either printed or Info 10021output. 10022 10023Do not put braces after an @code{@@@@} command. 10024 10025 10026@node Inserting Braces 10027@subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}} 10028@cindex Braces, inserting 10029@findex @{ @r{(literal @samp{@{})} 10030@findex @} @r{(literal @samp{@}})} 10031 10032@code{@@@{} stands for a single @samp{@{} in either printed or Info 10033output. 10034 10035@code{@@@}} stands for a single @samp{@}} in either printed or Info 10036output. 10037 10038Do not put braces after either an @code{@@@{} or an @code{@@@}} 10039command.ppp 10040 10041 10042@node Inserting a Comma 10043@subsection Inserting `,' with @code{@@comma@{@}} 10044@cindex Commas, inserting 10045@findex comma 10046 10047Ordinarily, a comma `,' is a normal character that can be simply typed 10048in your input where you need it. 10049 10050However, Texinfo uses the comma as a special character in one uncommon 10051context: some commands, such as @code{@@acronym} (@pxref{acronym}) and 10052@code{@@xref} (@pxref{Cross References}), as well as user-defined 10053macros (@pxref{Defining Macros}), can take more than one argument. In 10054these cases, the comma character is used to separate arguments. 10055 10056Since a comma chacter would confuse Texinfo's parsing for these 10057commands, you must use the command @samp{@comma{}} instead if you want 10058to have an actual comma in the output. Here are some examples: 10059 10060@example 10061@@acronym@{ABC, A Bizarre @@comma@{@}@} 10062@@xref@{Comma,, The @@comma@{@} symbol@} 10063@@mymac@{One argument@@comma@{@} containing a comma@} 10064@end example 10065 10066Although @comma{} can be used anywhere, there is no need for it 10067anywhere except in this unusual case. 10068 10069 10070@node Inserting Space 10071@section Inserting Space 10072 10073@cindex Inserting space 10074@cindex Spacing, inserting 10075The following sections describe commands that control spacing of various 10076kinds within and after sentences. 10077 10078@menu 10079* Not Ending a Sentence:: Sometimes a . doesn't end a sentence. 10080* Ending a Sentence:: Sometimes it does. 10081* Multiple Spaces:: Inserting multiple spaces. 10082* dmn:: How to format a dimension. 10083@end menu 10084 10085 10086@node Not Ending a Sentence 10087@subsection Not Ending a Sentence 10088 10089@cindex Not ending a sentence 10090@cindex Sentence non-ending punctuation 10091@cindex Periods, inserting 10092Depending on whether a period or exclamation point or question mark is 10093inside or at the end of a sentence, less or more space is inserted after 10094a period in a typeset manual. Since it is not always possible 10095to determine when a period ends a sentence and when it is used 10096in an abbreviation, special commands are needed in some circumstances. 10097Usually, Texinfo can guess how to handle periods, so you do not need to 10098use the special commands; you just enter a period as you would if you 10099were using a typewriter, which means you put two spaces after the 10100period, question mark, or exclamation mark that ends a sentence. 10101 10102@findex <colon> @r{(suppress end-of-sentence space)} 10103Use the @code{@@:}@: command after a period, question mark, 10104exclamation mark, or colon that should not be followed by extra space. 10105For example, use @code{@@:}@: after periods that end abbreviations 10106which are not at the ends of sentences. 10107 10108For example, 10109 10110@example 10111The s.o.p.@@: has three parts @dots{} 10112The s.o.p. has three parts @dots{} 10113@end example 10114 10115@noindent 10116@ifnottex 10117produces 10118@end ifnottex 10119@iftex 10120produces the following. If you look carefully at this printed output, 10121you will see a little extraneous space after @samp{s.o.p.} in the second 10122line. 10123@end iftex 10124 10125@quotation 10126The s.o.p.@: has three parts @dots{}@* 10127The s.o.p. has three parts @dots{} 10128@end quotation 10129 10130@noindent 10131(Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating 10132Procedure''.) 10133 10134@code{@@:} has no effect on the Info and HTML output. In Docbook and 10135XML, the previous punctuation character (.?!:) is output as an entity 10136instead of as the normal character: @samp{. ? ! 10137:}. This gives further processors a chance to notice and not 10138add the usual extra space. 10139 10140Do not put braces after @code{@@:} (or any non-alphabetic command). 10141 10142 10143@node Ending a Sentence 10144@subsection Ending a Sentence 10145 10146@cindex Ending a Sentence 10147@cindex Sentence ending punctuation 10148 10149@findex . @r{(end of sentence)} 10150@findex ! @r{(end of sentence)} 10151@findex ? @r{(end of sentence)} 10152Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an 10153exclamation point, and @code{@@?}@: instead of a question mark at the end 10154of a sentence that ends with a capital letter. Otherwise, @TeX{} 10155will think the letter is an abbreviation and will not insert the correct 10156end-of-sentence spacing. Here is an example: 10157 10158@example 10159Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@. 10160Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. 10161@end example 10162 10163@noindent 10164@ifnottex 10165produces 10166@end ifnottex 10167@iftex 10168produces the following. If you look carefully at this printed output, 10169you will see a little more whitespace after the @samp{W} in the first 10170line. 10171@end iftex 10172 10173@quotation 10174Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@* 10175Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. 10176@end quotation 10177 10178In the Info file output, @code{@@.}@: is equivalent to a simple 10179@samp{.}; likewise for @code{@@!}@: and @code{@@?}@:. 10180 10181The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to 10182work well with the Emacs sentence motion commands (@pxref{Sentences,,, 10183emacs, The GNU Emacs Manual}). 10184 10185Do not put braces after any of these commands. 10186 10187 10188@node Multiple Spaces 10189@subsection Multiple Spaces 10190 10191@cindex Multiple spaces 10192@cindex Whitespace, inserting 10193@cindex Space, inserting horizontal 10194@findex <space> 10195@findex <tab> 10196@findex <newline> 10197 10198Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab, 10199and newline) into a single space. Info output, on the other hand, 10200preserves whitespace as you type it, except for changing a newline into 10201a space; this is why it is important to put two spaces at the end of 10202sentences in Texinfo documents. 10203 10204Occasionally, you may want to actually insert several consecutive 10205spaces, either for purposes of example (what your program does with 10206multiple spaces as input), or merely for purposes of appearance in 10207headings or lists. Texinfo supports three commands: 10208@code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of 10209which insert a single space into the output. (Here, 10210@code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a 10211space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab 10212character and end-of-line, i.e., when @samp{@@} is the last character on 10213a line.) 10214 10215For example, 10216@example 10217Spacey@@ @@ @@ @@ 10218example. 10219@end example 10220 10221@noindent produces 10222 10223@example 10224Spacey@ @ @ @ 10225example. 10226@end example 10227 10228Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by 10229@code{@@multitable} (@pxref{Multi-column Tables}). 10230 10231Do not follow any of these commands with braces. 10232 10233To produce a non-breakable space, see @ref{tie, @code{@@tie}}. 10234 10235 10236@node dmn 10237@subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension 10238@cindex Thin space between number, dimension 10239@cindex Dimension formatting 10240@cindex Format a dimension 10241@findex dmn 10242 10243At times, you may want to write @samp{12@dmn{pt}} or 10244@samp{8.5@dmn{in}} with little or no space between the number and the 10245abbreviation for the dimension. You can use the @code{@@dmn} command 10246to do this. On seeing the command, @TeX{} inserts just enough space 10247for proper typesetting; the Info formatting commands insert no space 10248at all, since the Info file does not require it. 10249 10250To use the @code{@@dmn} command, write the number and then follow it 10251immediately, with no intervening space, by @code{@@dmn}, and then by 10252the dimension within braces. For example, 10253 10254@example 10255A4 paper is 8.27@@dmn@{in@} wide. 10256@end example 10257 10258@noindent 10259produces 10260 10261@quotation 10262A4 paper is 8.27@dmn{in} wide. 10263@end quotation 10264 10265Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}} 10266or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file. 10267In these cases, however, the formatters may insert a line break between 10268the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if 10269you write a period after an abbreviation within a sentence, you should 10270write @samp{@@:} after the period to prevent @TeX{} from inserting extra 10271whitespace, as shown here. @xref{Not Ending a Sentence}. 10272 10273 10274@node Inserting Accents 10275@section Inserting Accents 10276 10277@cindex Inserting accents 10278@cindex Accents, inserting 10279@cindex Floating accents, inserting 10280 10281Here is a table with the commands Texinfo provides for inserting 10282floating accents. The commands with non-alphabetic names do not take 10283braces around their argument (which is taken to be the next character). 10284(Exception: @code{@@,} @emph{does} take braces around its argument.) 10285This is so as to make the source as convenient to type and read as 10286possible, since accented characters are very common in some languages. 10287 10288To get the true accented characters output in Info, and not just the 10289ASCII transliterations, you can use the @option{--enable-encoding} 10290option to @command{makeinfo} (@pxref{makeinfo options}). 10291 10292@findex " @r{(umlaut accent)} 10293@cindex Umlaut accent 10294@findex ' @r{(umlaut accent)} 10295@cindex Acute accent 10296@findex = @r{(macron accent)} 10297@cindex Macron accent 10298@findex ^ @r{(circumflex accent)} 10299@cindex Circumflex accent 10300@findex ` @r{(grave accent)} 10301@cindex Grave accent 10302@findex ~ @r{(tilde accent)} 10303@cindex Tilde accent 10304@findex , @r{(cedilla accent)} 10305@cindex Cedilla accent 10306@findex dotaccent 10307@cindex Dot accent 10308@findex H @r{(Hungarian umlaut accent)} 10309@cindex Hungarian umlaut accent 10310@findex ringaccent 10311@cindex Ring accent 10312@findex tieaccent 10313@cindex Tie-after accent 10314@findex u @r{(breve accent)} 10315@cindex Breve accent 10316@findex ubaraccent 10317@cindex Underbar accent 10318@findex udotaccent 10319@cindex Underdot accent 10320@findex v @r{(check accent)} 10321@cindex Hacek accent 10322@cindex Check accent 10323@cindex Caron accent 10324@multitable {@@questiondown@{@}} {Output} {hacek/check/caron accent} 10325@item Command @tab Output @tab What 10326@item @t{@@"o} @tab @"o @tab umlaut accent 10327@item @t{@@'o} @tab @'o @tab acute accent 10328@item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent 10329@item @t{@@=o} @tab @=o @tab macron/overbar accent 10330@item @t{@@^o} @tab @^o @tab circumflex accent 10331@item @t{@@`o} @tab @`o @tab grave accent 10332@item @t{@@~o} @tab @~o @tab tilde accent 10333@item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent 10334@item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut 10335@item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent 10336@item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent 10337@item @t{@@u@{o@}} @tab @u{o} @tab breve accent 10338@item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent 10339@item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent 10340@item @t{@@v@{o@}} @tab @v{o} @tab hacek/check/caron accent 10341@end multitable 10342 10343This table lists the Texinfo commands for inserting other characters 10344commonly used in languages other than English. 10345 10346@findex questiondown 10347@cindex @questiondown{} 10348@findex exclamdown 10349@cindex @exclamdown{} 10350@findex aa 10351@cindex @aa{} 10352@findex AA 10353@cindex @AA{} 10354@findex ae 10355@cindex @ae{} 10356@findex AE 10357@cindex @AE{} 10358@findex dotless 10359@cindex @dotless{i} (dotless i) 10360@cindex @dotless{j} (dotless j) 10361@cindex Dotless i, j 10362@findex l 10363@cindex @l{} 10364@findex L 10365@cindex @L{} 10366@findex o 10367@cindex @o{} 10368@findex O 10369@cindex @O{} 10370@findex oe 10371@cindex @oe{} 10372@findex OE 10373@cindex @OE{} 10374@cindex Romance ordinals 10375@cindex Ordinals, Romance 10376@cindex Feminine ordinal 10377@findex ordf 10378@cindex @ordf{} 10379@cindex Masculine ordinal 10380@findex ordm 10381@cindex @ordm{} 10382@findex ss 10383@cindex @ss{} 10384@cindex Es-zet 10385@cindex Sharp S 10386@cindex German S 10387@multitable {x@@questiondown@{@}} {oe OE} {es-zet or sharp S} 10388@item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down ! 10389@item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ? 10390@item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle 10391@item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures 10392@item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i 10393@item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j 10394@item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l 10395@item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash 10396@item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures 10397@item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals 10398@item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S 10399@end multitable 10400 10401 10402@node Dots Bullets 10403@section Inserting Ellipsis and Bullets 10404@cindex Dots, inserting 10405@cindex Bullets, inserting 10406@cindex Ellipsis, inserting 10407@cindex Inserting ellipsis 10408@cindex Inserting dots 10409@cindex Special typesetting commands 10410@cindex Typesetting commands for dots, etc. 10411 10412An @dfn{ellipsis} (a line of dots) is not typeset as a string of 10413periods, so a special command is used for ellipsis in Texinfo. The 10414@code{@@bullet} command is special, too. Each of these commands is 10415followed by a pair of braces, @samp{@{@}}, without any whitespace 10416between the name of the command and the braces. (You need to use braces 10417with these commands because you can use them next to other text; without 10418the braces, the formatters would be confused. @xref{Command Syntax, , 10419@@-Command Syntax}, for further information.)@refill 10420 10421@menu 10422* dots:: How to insert dots @dots{} 10423* bullet:: How to insert a bullet. 10424@end menu 10425 10426 10427@node dots 10428@subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{}) 10429@findex dots 10430@findex enddots 10431@cindex Inserting dots 10432@cindex Dots, inserting 10433 10434Use the @code{@@dots@{@}} command to generate an ellipsis, which is 10435three dots in a row, appropriately spaced @dots{} like so. Do 10436not simply write three periods in the input file; that would work for 10437the Info file output, but would produce the wrong amount of space 10438between the periods in the printed manual. 10439 10440Similarly, the @code{@@enddots@{@}} command generates an 10441end-of-sentence ellipsis, which has different spacing afterwards, 10442@enddots{} Look closely to see the difference. 10443 10444@iftex 10445Here is an ellipsis: @dots{} 10446Here are three periods in a row: ... 10447 10448In printed output, the three periods in a row are closer together than 10449the dots in the ellipsis. 10450@end iftex 10451 10452 10453@node bullet 10454@subsection @code{@@bullet}@{@} (@bullet{}) 10455@findex bullet 10456 10457Use the @code{@@bullet@{@}} command to generate a large round dot, or 10458the closest possible thing to one. In Info, an asterisk is used.@refill 10459 10460Here is a bullet: @bullet{} 10461 10462When you use @code{@@bullet} in @code{@@itemize}, you do not need to 10463type the braces, because @code{@@itemize} supplies them. 10464(@xref{itemize, , @code{@@itemize}}.)@refill 10465 10466 10467@node TeX and copyright 10468@section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{} 10469 10470The logo `@TeX{}' is typeset in a special fashion and it needs an 10471@@-command. The copyright and registered symbols, `@copyright{}' and 10472`@registeredsymbol{}', is also special. Each of these commands is 10473followed by a pair of braces, @samp{@{@}}, without any whitespace 10474between the name of the command and the braces. 10475 10476@menu 10477* tex:: The @TeX{} logos. 10478* copyright symbol:: The copyright symbol (c in a circle). 10479* registered symbol:: The registered symbol (R in a circle). 10480@end menu 10481 10482 10483@node tex 10484@subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{}) 10485@findex TeX 10486@findex LaTeX 10487 10488Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed 10489manual, this is a special logo that is different from three ordinary 10490letters. In Info, it just looks like @samp{TeX}. 10491 10492Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}', 10493which is even more special in printed manuals (and different from the 10494incorrect @code{La@@TeX@{@}}. In Info, the result is just 10495@samp{LaTeX}. (@LaTeX{} is another macro package built on top of 10496@TeX{}, very loosely analogous to Texinfo in that it emphasizes 10497logical structure, but much (much) larger.) 10498 10499The spelling of these commands are unusual among Texinfo commands in 10500that they use both uppercase and lowercase letters. 10501 10502 10503@node copyright symbol 10504@subsection @code{@@copyright@{@}} (@copyright{}) 10505@findex copyright 10506 10507Use the @code{@@copyright@{@}} command to generate the copyright 10508symbol, `@copyright{}'. Where possible, this is a @samp{c} 10509inside a circle; in Info, this is @samp{(C)}. 10510 10511 10512@node registered symbol 10513@subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{}) 10514@findex registeredsymbol 10515 10516Use the @code{@@registeredsymbol@{@}} command to generate the 10517registered symbol, `@registeredsymbol{}'. Where possible, this is an 10518@samp{R} inside a circle; in Info, this is @samp{(R)}. 10519 10520 10521@node euro 10522@section @code{@@euro}@{@} (@euro{}): Euro currency symbol 10523@findex euro 10524 10525Use the @code{@@euro@{@}} command to generate `@euro{}'. Where 10526possible, this is the symbol for the Euro currency, invented as part 10527of the European economic unification relatively recently. In plain 10528Info, it is the word @samp{Euro }. (The space is included in the text 10529transliteration since typically there would be no space after the 10530symbol, so it would be inappropriate to have a space in the source document.) 10531 10532Texinfo cannot magically synthesize support for the Euro symbol where 10533the underlying system (fonts, software, whatever) does not support 10534it. Therefore, in many cases it is preferable to use the word 10535``Euro''. (In banking circles, the abbreviation for the Euro is EUR.) 10536 10537@cindex ISO 8859-15 10538@cindex Latin 9 10539In order to get the Euro symbol in encoded Info output, for example, 10540it is necessary to specify @code{@@documentencoding ISO-8859-15}. 10541(@xref{documentencoding,,@code{@@documentencoding}}.) The Euro symbol 10542is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more 10543widely-used and supported ISO 8859-1 (Latin@tie{}1). 10544 10545 10546@node pounds 10547@section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling 10548@findex pounds 10549 10550Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where 10551possible, this is the symbol for the currency pounds sterling. In 10552Info, it is a @samp{#}. 10553 10554 10555@node minus 10556@section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign 10557@findex minus 10558 10559@cindex Em dash, compared to minus sign 10560@cindex Hyphen, compared to minus 10561Use the @code{@@minus@{@}} command to generate a minus sign. In a 10562fixed-width font, this is a single hyphen, but in a proportional font, 10563the symbol is the customary length for a minus sign---a little longer 10564than a hyphen, shorter than an em-dash: 10565 10566@display 10567@samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}}, 10568 10569`-' is a hyphen generated with the character @samp{-}, 10570 10571`---' is an em-dash for text. 10572@end display 10573 10574@noindent 10575In the fixed-width font used by Info, @code{@@minus@{@}} is the same 10576as a hyphen. 10577 10578You should not use @code{@@minus@{@}} inside @code{@@code} or 10579@code{@@example} because the width distinction is not made in the 10580fixed-width font they use. 10581 10582When you use @code{@@minus} to specify the mark beginning each entry in 10583an itemized list, you do not need to type the braces 10584(@pxref{itemize, , @code{@@itemize}}). 10585 10586 10587@node math 10588@section @code{@@math}: Inserting Mathematical Expressions 10589@findex math 10590@cindex Mathematical expressions 10591@cindex Formulas, mathematical 10592 10593You can write a short mathematical expression with the @code{@@math} 10594command. Write the mathematical expression between braces, like this: 10595 10596@example 10597@@math@{(a + b)(a + b) = a^2 + 2ab + b^2@} 10598@end example 10599 10600@iftex 10601@noindent This produces the following in @TeX{}: 10602 10603@display 10604@math{(a + b)(a + b) = a^2 + 2ab + b^2} 10605@end display 10606 10607@noindent and the following in other formats: 10608@end iftex 10609@ifnottex 10610@noindent This produces the following in Info and HTML: 10611@end ifnottex 10612 10613@example 10614(a + b)(a + b) = a^2 + 2ab + b^2 10615@end example 10616 10617Thus, the @code{@@math} command has no effect on the Info and HTML 10618output; @command{makeinfo} just reproduces the input, it does not try 10619to interpret the mathematics in any way. 10620 10621@code{@@math} implies @code{@@tex}. This not only makes it possible to 10622write superscripts and subscripts (as in the above example), but also 10623allows you to use any of the plain @TeX{} math control sequences. It's 10624conventional to use @samp{\} instead of @samp{@@} for these commands. 10625As in: 10626@example 10627@@math@{\sin 2\pi \equiv \cos 3\pi@} 10628@end example 10629 10630@iftex 10631@noindent which looks like this in @TeX{}: 10632@display 10633@math{\sin 2\pi \equiv \cos 3\pi} 10634@end display 10635 10636@noindent and 10637@end iftex 10638@noindent which looks like the input in Info and HTML: 10639@example 10640\sin 2\pi \equiv \cos 3\pi 10641@end example 10642 10643@findex \ @r{(literal \ in @code{@@math})} 10644Since @samp{\} is an escape character inside @code{@@math}, you can use 10645@code{@@\} to get a literal backslash (@code{\\} will work in @TeX{}, 10646but you'll get the literal @samp{\\} in Info). @code{@@\} is not 10647defined outside of @code{@@math}, since a @samp{\} ordinarily produces a 10648literal @samp{\}. 10649 10650 10651@cindex Displayed equations 10652@cindex Equations, displayed 10653For displayed equations, you must at present use @TeX{} directly 10654(@pxref{Raw Formatter Commands}). 10655 10656 10657@node Glyphs 10658@section Glyphs for Examples 10659@cindex Glyphs 10660@cindex Examples, glyphs for 10661 10662In Texinfo, code is often illustrated in examples that are delimited 10663by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and 10664@code{@@end lisp}. In such examples, you can indicate the results of 10665evaluation or an expansion using @samp{@result{}} or 10666@samp{@expansion{}}. Likewise, there are commands to insert glyphs 10667to indicate 10668printed output, error messages, equivalence of expressions, and the 10669location of point.@refill 10670 10671The glyph-insertion commands do not need to be used within an example, but 10672most often they are. Every glyph-insertion command is followed by a pair of 10673left- and right-hand braces.@refill 10674 10675@menu 10676* Glyphs Summary:: 10677* result:: How to show the result of expression. 10678* expansion:: How to indicate an expansion. 10679* Print Glyph:: How to indicate printed output. 10680* Error Glyph:: How to indicate an error message. 10681* Equivalence:: How to indicate equivalence. 10682* Point Glyph:: How to indicate the location of point. 10683@end menu 10684 10685 10686@node Glyphs Summary 10687@subsection Glyphs Summary 10688 10689Here are the different glyph commands:@refill 10690 10691@table @asis 10692@item @result{} 10693@code{@@result@{@}} points to the result of an expression.@refill 10694 10695@item @expansion{} 10696@code{@@expansion@{@}} shows the results of a macro expansion.@refill 10697 10698@item @print{} 10699@code{@@print@{@}} indicates printed output.@refill 10700 10701@item @error{} 10702@code{@@error@{@}} indicates that the following text is an error 10703message.@refill 10704 10705@item @equiv{} 10706@code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill 10707 10708@item @point{} 10709@code{@@point@{@}} shows the location of point.@refill 10710@end table 10711 10712@menu 10713* result:: 10714* expansion:: 10715* Print Glyph:: 10716* Error Glyph:: 10717* Equivalence:: 10718* Point Glyph:: 10719@end menu 10720 10721 10722@node result 10723@subsection @code{@@result@{@}} (@result{}): Indicating Evaluation 10724@cindex Result of an expression 10725@cindex Indicating evaluation 10726@cindex Evaluation glyph 10727@cindex Value of an expression, indicating 10728@findex result 10729 10730Use the @code{@@result@{@}} command to indicate the result of 10731evaluating an expression.@refill 10732 10733@iftex 10734The @code{@@result@{@}} command is displayed as @samp{@result{}} in 10735the printed output and as @samp{=>} in other formats. 10736@end iftex 10737@ifnottex 10738The @code{@@result@{@}} command is displayed as @samp{@result{}} in 10739Info and HTML and as a true double stemmed arrow in the printed output. 10740@end ifnottex 10741 10742Thus, the following, 10743 10744@lisp 10745(cdr '(1 2 3)) 10746 @result{} (2 3) 10747@end lisp 10748 10749@noindent 10750may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''. 10751 10752 10753@node expansion 10754@subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion 10755@cindex Expansion, indicating 10756@cindex Macro expansion, indicating 10757@findex expansion 10758 10759When an expression is a macro call, it expands into a new expression. 10760You can indicate the result of the expansion with the 10761@code{@@expansion@{@}} command.@refill 10762 10763@iftex 10764The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} 10765in the printed output. and as @samp{==>} in other formats. 10766@end iftex 10767@ifnottex 10768The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}} 10769in Info and HTML, and as a long arrow with a flat base in the printed 10770output. 10771@end ifnottex 10772 10773@need 700 10774For example, the following 10775 10776@example 10777@group 10778@@lisp 10779(third '(a b c)) 10780 @@expansion@{@} (car (cdr (cdr '(a b c)))) 10781 @@result@{@} c 10782@@end lisp 10783@end group 10784@end example 10785 10786@noindent 10787produces 10788 10789@lisp 10790@group 10791(third '(a b c)) 10792 @expansion{} (car (cdr (cdr '(a b c)))) 10793 @result{} c 10794@end group 10795@end lisp 10796 10797@noindent 10798which may be read as: 10799 10800@quotation 10801@code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))}; 10802the result of evaluating the expression is @code{c}. 10803@end quotation 10804 10805@noindent 10806Often, as in this case, an example looks better if the 10807@code{@@expansion@{@}} and @code{@@result@{@}} commands are indented. 10808 10809 10810@node Print Glyph 10811@subsection @code{@@print@{@}} (@print{}): Indicating Printed Output 10812@cindex Printed output, indicating 10813@findex print 10814 10815Sometimes an expression will print output during its execution. You 10816can indicate the printed output with the @code{@@print@{@}} command.@refill 10817 10818@iftex 10819The @code{@@print@{@}} command is displayed as @samp{-|} in Info and 10820HTML and as @samp{@print{}} in the printed output. 10821@end iftex 10822@ifnottex 10823The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info 10824and HTML and (similarly) as a horizontal dash butting against a 10825vertical bar in the printed output. 10826@end ifnottex 10827 10828In the following example, the printed text is indicated with 10829@samp{@print{}}, and the value of the expression follows on the 10830last line. 10831 10832@lisp 10833@group 10834(progn (print 'foo) (print 'bar)) 10835 @print{} foo 10836 @print{} bar 10837 @result{} bar 10838@end group 10839@end lisp 10840 10841@noindent 10842In a Texinfo source file, this example is written as follows: 10843 10844@lisp 10845@group 10846@@lisp 10847(progn (print 'foo) (print 'bar)) 10848 @@print@{@} foo 10849 @@print@{@} bar 10850 @@result@{@} bar 10851@@end lisp 10852@end group 10853@end lisp 10854 10855 10856@node Error Glyph 10857@subsection @code{@@error@{@}} (@error{}): Indicating an Error Message 10858@cindex Error message, indicating 10859@findex error 10860 10861A piece of code may cause an error when you evaluate it. You can 10862designate the error message with the @code{@@error@{@}} command.@refill 10863 10864@iftex 10865The @code{@@error@{@}} command is displayed as @samp{error-->} in Info 10866and HTML and as @samp{@error{}} in the printed output. 10867@end iftex 10868@ifnottex 10869The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info 10870and HTML and as the word `error' in a box in the printed output. 10871@end ifnottex 10872 10873@need 700 10874Thus, 10875 10876@example 10877@@lisp 10878(+ 23 'x) 10879@@error@{@} Wrong type argument: integer-or-marker-p, x 10880@@end lisp 10881@end example 10882 10883@noindent 10884produces 10885 10886@lisp 10887(+ 23 'x) 10888@error{} Wrong type argument: integer-or-marker-p, x 10889@end lisp 10890 10891@noindent 10892This indicates that the following error message is printed 10893when you evaluate the expression: 10894 10895@lisp 10896Wrong type argument: integer-or-marker-p, x 10897@end lisp 10898 10899@samp{@error{}} itself is not part of the error message. 10900 10901 10902@node Equivalence 10903@subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence 10904@cindex Equivalence, indicating 10905@findex equiv 10906 10907Sometimes two expressions produce identical results. You can indicate the 10908exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill 10909 10910@iftex 10911The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and 10912HTML and as @samp{@equiv{}} in the printed output. 10913@end iftex 10914@ifnottex 10915The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info 10916and HTML and as a standard mathematical equivalence sign (three 10917parallel horizontal lines) in the printed output. 10918@end ifnottex 10919 10920Thus, 10921 10922@example 10923@@lisp 10924(make-sparse-keymap) @@equiv@{@} (list 'keymap) 10925@@end lisp 10926@end example 10927 10928@noindent 10929produces 10930 10931@lisp 10932(make-sparse-keymap) @equiv{} (list 'keymap) 10933@end lisp 10934 10935@noindent 10936This indicates that evaluating @code{(make-sparse-keymap)} produces 10937identical results to evaluating @code{(list 'keymap)}. 10938 10939 10940@node Point Glyph 10941@subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer 10942@cindex Point, indicating in a buffer 10943@findex point 10944 10945Sometimes you need to show an example of text in an Emacs buffer. In 10946such examples, the convention is to include the entire contents of the 10947buffer in question between two lines of dashes containing the buffer 10948name.@refill 10949 10950You can use the @samp{@@point@{@}} command to show the location of point 10951in the text in the buffer. (The symbol for point, of course, is not 10952part of the text in the buffer; it indicates the place @emph{between} 10953two characters where point is located.)@refill 10954 10955@iftex 10956The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and 10957HTML and as @samp{@point{}} in the printed output. 10958@end iftex 10959@ifnottex 10960The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info 10961and HTML and as a small five pointed star in the printed 10962output. 10963@end ifnottex 10964 10965The following example shows the contents of buffer @file{foo} before 10966and after evaluating a Lisp command to insert the word @code{changed}.@refill 10967 10968@example 10969@group 10970---------- Buffer: foo ---------- 10971This is the @point{}contents of foo. 10972---------- Buffer: foo ---------- 10973 10974@end group 10975@end example 10976 10977@example 10978@group 10979(insert "changed ") 10980 @result{} nil 10981---------- Buffer: foo ---------- 10982This is the changed @point{}contents of foo. 10983---------- Buffer: foo ---------- 10984 10985@end group 10986@end example 10987 10988In a Texinfo source file, the example is written like this:@refill 10989 10990@example 10991@@example 10992---------- Buffer: foo ---------- 10993This is the @@point@{@}contents of foo. 10994---------- Buffer: foo ---------- 10995 10996(insert "changed ") 10997 @@result@{@} nil 10998---------- Buffer: foo ---------- 10999This is the changed @@point@{@}contents of foo. 11000---------- Buffer: foo ---------- 11001@@end example 11002@end example 11003 11004 11005@node Breaks 11006@chapter Forcing and Preventing Breaks 11007@cindex Forcing line and page breaks 11008@cindex Making line and page breaks 11009@cindex Preventing line and page breaks 11010 11011@cindex Line breaks 11012Usually, a Texinfo file is processed both by @TeX{} and by one of the 11013Info formatting commands. Line, paragraph, or page breaks sometimes 11014occur in the `wrong' place in one or other form of output. You must 11015ensure that text looks right both in the printed manual and in the 11016Info file. 11017 11018@cindex White space, excessive 11019@cindex Page breaks 11020For example, in a printed manual, page breaks may occur awkwardly in 11021the middle of an example; to prevent this, you can hold text together 11022using a grouping command that keeps the text from being split across 11023two pages. Conversely, you may want to force a page break where none 11024would occur normally. Fortunately, problems like these do not often 11025arise. When they do, use the break, break prevention, or pagination 11026commands. 11027 11028@menu 11029* Break Commands:: Summary of break-related commands. 11030* Line Breaks:: Forcing line breaks. 11031* - and hyphenation:: Helping @TeX{} with hyphenation points. 11032* w:: Preventing unwanted line breaks in text. 11033* tie:: Inserting an unbreakable but varying space. 11034* sp:: Inserting blank lines. 11035* page:: Forcing the start of a new page. 11036* group:: Preventing unwanted page breaks. 11037* need:: Another way to prevent unwanted page breaks. 11038@end menu 11039 11040 11041@node Break Commands 11042@section Break Commands 11043 11044The break commands create or allow line and paragraph breaks: 11045 11046@table @code 11047@item @@* 11048Force a line break. 11049 11050@item @@sp @var{n} 11051Skip @var{n} blank lines. 11052 11053@item @@- 11054Insert a discretionary hyphen. 11055 11056@item @@hyphenation@{@var{hy-phen-a-ted words}@} 11057Define hyphen points in @var{hy-phen-a-ted words}. 11058@end table 11059 11060These commands hold text together on a single line: 11061 11062@table @code 11063@item @@w@{@var{text}@} 11064Prevent @var{text} from being split and hyphenated across two lines. 11065@item @@tie@{@} 11066Insert a normal interword space at which a line break may not occur. 11067@end table 11068@iftex 11069@sp 1 11070@end iftex 11071 11072The pagination commands apply only to printed output, since Info 11073files do not have pages. 11074 11075@table @code 11076@item @@page 11077Start a new page in the printed manual. 11078 11079@item @@group 11080Hold text together that must appear on one printed page. 11081 11082@item @@need @var{mils} 11083Start a new printed page if not enough space on this one. 11084@end table 11085 11086 11087@node Line Breaks 11088@section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks 11089@findex * @r{(force line break)} 11090@findex / @r{(allow line break)} 11091@cindex Line breaks 11092@cindex Breaks in a line 11093@cindex Force line break 11094@cindex Allow line break 11095 11096The @code{@@*} command forces a line break in both the printed manual and 11097in Info. The @code{@@/} command allows a line break (printed manual only). 11098 11099Here is an example with @code{@@*}: 11100 11101@example 11102This line @@* is broken @@*in two places. 11103@end example 11104 11105@noindent produces 11106 11107@example 11108@group 11109This line 11110is broken 11111in two places. 11112@end group 11113@end example 11114 11115The @code{@@/} command can be useful within a url 11116(@pxref{uref,,@code{@@uref}}), which tend to be long and are otherwise 11117unbreakable. For example: 11118 11119@example 11120The official Texinfo home page is on the GNU web site: 11121@@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}. 11122@end example 11123 11124@noindent produces 11125 11126@display 11127The official Texinfo home page is on the GNU web site: 11128@uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. 11129@end display 11130 11131@noindent Without the @code{@@/} commands, @TeX{} would have nowhere to 11132break the line. @code{@@/} has no effect in the online output. 11133 11134 11135@node - and hyphenation 11136@section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate 11137 11138@findex - @r{(discretionary hyphen)} 11139@findex hyphenation 11140@cindex Hyphenation, helping @TeX{} do 11141@cindex Fine-tuning, and hyphenation 11142 11143Although @TeX{}'s hyphenation algorithm is generally pretty good, it 11144does miss useful hyphenation points from time to time. (Or, far more 11145rarely, insert an incorrect hyphenation.) So, for documents with an 11146unusual vocabulary or when fine-tuning for a printed edition, you may 11147wish to help @TeX{} out. Texinfo supports two commands for this: 11148 11149@table @code 11150@item @@- 11151Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does 11152not have to) hyphenate. This is especially useful when you notice an 11153overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull 11154hboxes}). @TeX{} will not insert any hyphenation points itself into a 11155word containing @code{@@-}. 11156 11157@item @@hyphenation@{@var{hy-phen-a-ted words}@} 11158Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you 11159put a @samp{-} at each hyphenation point. For example: 11160@example 11161@@hyphenation@{man-u-script man-u-scripts@} 11162@end example 11163@noindent @TeX{} only uses the specified hyphenation points when the 11164words match exactly, so give all necessary variants. 11165@end table 11166 11167Info output is not hyphenated, so these commands have no effect there. 11168 11169 11170@node w 11171@section @code{@@w}@{@var{text}@}: Prevent Line Breaks 11172@findex w @r{(prevent line break)} 11173@cindex Line breaks, preventing 11174 11175@code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks 11176within @var{text}, for both @TeX{} and @command{makeinfo}. 11177 11178@cindex Non-breakable space, fixed 11179@cindex Unbreakable space, fixed 11180Thus, you can use @code{@@w} to produce a non-breakable space, fixed at 11181the width of a normal interword space: 11182 11183@example 11184@@w@{ @} @@w@{ @} @@w@{ @} indentation. 11185@end example 11186 11187@noindent produces: 11188 11189@display 11190@w{ } @w{ } @w{ } indentation. 11191@end display 11192 11193The space from @code{@@w@{@w{ }@}}, as well as being non-breakable, 11194also will not stretch or shrink. Sometimes that is what you want, for 11195instance if you're doing indenting manual. However, usually you want 11196a normal interword space that does stretch and shrink (in the printed 11197output); see the @code{@@tie} command in the next section. 11198 11199@cindex Hyphenation, preventing 11200You can also use the @code{@@w} command to prevent @TeX{} from 11201automatically hyphenating a long name or phrase that happens to fall 11202near the end of a line. @command{makeinfo} does not ever hyphenate 11203words. 11204 11205@cindex Keyword expansion, preventing 11206@cindex Version control keywords, preventing expansion of 11207@cindex $Id expansion, preventing 11208You can also use @code{@@w} to avoid unwanted keyword expansion in 11209source control systems. For example, to literally write @t{@w{$}Id$} 11210in your document, use @code{@@w@{$@}Id$}. 11211 11212 11213@node tie 11214@section @code{@@tie@{@}}: Inserting an Unbreakable Space 11215@findex tie @r{(unbreakable interword space)} 11216@cindex Tied space 11217@cindex Non-breakable space, variable 11218@cindex Unbreakable space, variable 11219 11220The @code{@@tie@{@}} command produces a normal interword space at which 11221a line break may not occur. Always write it with following (empty) 11222braces, as usual for commands used within a paragraph. Here's an 11223example: 11224 11225@example 11226@@TeX@{@} was written by Donald E.@@tie@{@}Knuth. 11227@end example 11228 11229@noindent produces: 11230 11231@display 11232@TeX{} was written by Donald E.@tie{}Knuth. 11233@end display 11234 11235There are two important differences between @code{@@tie@{@}} and 11236@code{@@w@{@w{ }@}}: 11237 11238@itemize 11239@item 11240The space produced by @code{@@tie@{@}} will stretch and shrink slightly 11241along with the normal interword spaces in the paragraph; the space 11242produced by @code{@@w@{@w{ }@}} will not vary. 11243 11244@item 11245@code{@@tie@{@}} allows hyphenation of the surrounding words, while 11246@code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical 11247reasons, namely that it produces an @samp{\hbox}). 11248 11249@end itemize 11250 11251 11252@node sp 11253@section @code{@@sp} @var{n}: Insert Blank Lines 11254@findex sp @r{(line spacing)} 11255@cindex Space, inserting vertical 11256@cindex Blank lines 11257@cindex Line spacing 11258 11259A line beginning with and containing only @code{@@sp @var{n}} 11260generates @var{n} blank lines of space in both the printed manual and 11261the Info file. @code{@@sp} also forces a paragraph break. For 11262example, 11263 11264@example 11265@@sp 2 11266@end example 11267 11268@noindent 11269generates two blank lines. 11270 11271The @code{@@sp} command is most often used in the title page.@refill 11272 11273@ignore 11274@c node br, page, sp, Breaks 11275@comment node-name, next, previous, up 11276@c section @code{@@br}: Generate Paragraph Breaks 11277@findex br @r{(paragraph breaks)} 11278@cindex Paragraph breaks 11279@cindex Breaks in a paragraph 11280 11281The @code{@@br} command forces a paragraph break. It inserts a blank 11282line. You can use the command within or at the end of a line. If 11283used within a line, the @code{@@br@{@}} command must be followed by 11284left and right braces (as shown here) to mark the end of the 11285command.@refill 11286 11287@need 700 11288For example, 11289 11290@example 11291@group 11292This line @@br@{@}contains and is ended by paragraph breaks@@br 11293and is followed by another line. 11294@end group 11295@end example 11296 11297@noindent 11298produces 11299 11300@example 11301@group 11302This line 11303 11304contains and is ended by paragraph breaks 11305 11306and is followed by another line. 11307@end group 11308@end example 11309 11310The @code{@@br} command is seldom used. 11311@end ignore 11312 11313 11314@node page 11315@section @code{@@page}: Start a New Page 11316@cindex Page breaks 11317@findex page 11318 11319A line containing only @code{@@page} starts a new page in a printed 11320manual. The command has no effect on Info files since they are not 11321paginated. An @code{@@page} command is often used in the @code{@@titlepage} 11322section of a Texinfo file to start the copyright page. 11323 11324 11325@node group 11326@comment node-name, next, previous, up 11327@section @code{@@group}: Prevent Page Breaks 11328@cindex Group (hold text together vertically) 11329@cindex Holding text together vertically 11330@cindex Vertically holding text together 11331@findex group 11332 11333The @code{@@group} command (on a line by itself) is used inside an 11334@code{@@example} or similar construct to begin an unsplittable vertical 11335group, which will appear entirely on one page in the printed output. 11336The group is terminated by a line containing only @code{@@end group}. 11337These two lines produce no output of their own, and in the Info file 11338output they have no effect at all.@refill 11339 11340@c Once said that these environments 11341@c turn off vertical spacing between ``paragraphs''. 11342@c Also, quotation used to work, but doesn't in texinfo-2.72 11343Although @code{@@group} would make sense conceptually in a wide 11344variety of contexts, its current implementation works reliably only 11345within @code{@@example} and variants, and within @code{@@display}, 11346@code{@@format}, @code{@@flushleft} and @code{@@flushright}. 11347@xref{Quotations and Examples}. (What all these commands have in 11348common is that each line of input produces a line of output.) In 11349other contexts, @code{@@group} can cause anomalous vertical 11350spacing.@refill 11351 11352@need 750 11353This formatting requirement means that you should write: 11354 11355@example 11356@group 11357@@example 11358@@group 11359@dots{} 11360@@end group 11361@@end example 11362@end group 11363@end example 11364 11365@noindent 11366with the @code{@@group} and @code{@@end group} commands inside the 11367@code{@@example} and @code{@@end example} commands. 11368 11369The @code{@@group} command is most often used to hold an example 11370together on one page. In this Texinfo manual, more than 100 examples 11371contain text that is enclosed between @code{@@group} and @code{@@end 11372group}. 11373 11374If you forget to end a group, you may get strange and unfathomable 11375error messages when you run @TeX{}. This is because @TeX{} keeps 11376trying to put the rest of the Texinfo file onto the one page and does 11377not start to generate error messages until it has processed 11378considerable text. It is a good rule of thumb to look for a missing 11379@code{@@end group} if you get incomprehensible error messages in 11380@TeX{}.@refill 11381 11382@node need 11383@comment node-name, next, previous, up 11384@section @code{@@need @var{mils}}: Prevent Page Breaks 11385@cindex Need space at page bottom 11386@findex need 11387 11388A line containing only @code{@@need @var{n}} starts 11389a new page in a printed manual if fewer than @var{n} mils (thousandths 11390of an inch) remain on the current page. Do not use 11391braces around the argument @var{n}. The @code{@@need} command has no 11392effect on Info files since they are not paginated.@refill 11393 11394@need 800 11395This paragraph is preceded by an @code{@@need} command that tells 11396@TeX{} to start a new page if fewer than 800 mils (eight-tenths 11397inch) remain on the page. It looks like this:@refill 11398 11399@example 11400@group 11401@@need 800 11402This paragraph is preceded by @dots{} 11403@end group 11404@end example 11405 11406The @code{@@need} command is useful for preventing orphans (single 11407lines at the bottoms of printed pages).@refill 11408 11409 11410@node Definition Commands 11411@chapter Definition Commands 11412@cindex Definition commands 11413 11414The @code{@@deffn} command and the other @dfn{definition commands} 11415enable you to describe functions, variables, macros, commands, user 11416options, special forms and other such artifacts in a uniform 11417format.@refill 11418 11419In the Info file, a definition causes the entity 11420category---`Function', `Variable', or whatever---to appear at the 11421beginning of the first line of the definition, followed by the 11422entity's name and arguments. In the printed manual, the command 11423causes @TeX{} to print the entity's name and its arguments on the left 11424margin and print the category next to the right margin. In both 11425output formats, the body of the definition is indented. Also, the 11426name of the entity is entered into the appropriate index: 11427@code{@@deffn} enters the name into the index of functions, 11428@code{@@defvr} enters it into the index of variables, and so 11429on (@pxref{Predefined Indices}). 11430 11431A manual need not and should not contain more than one definition for 11432a given name. An appendix containing a summary should use 11433@code{@@table} rather than the definition commands.@refill 11434 11435@menu 11436* Def Cmd Template:: Writing descriptions using definition commands. 11437* Def Cmd Continuation Lines:: Continuing the heading over source lines. 11438* Optional Arguments:: Handling optional and repeated arguments. 11439* deffnx:: Group two or more `first' lines. 11440* Def Cmds in Detail:: Reference for all the definition commands. 11441* Def Cmd Conventions:: Conventions for writing definitions. 11442* Sample Function Definition:: An example. 11443@end menu 11444 11445 11446@node Def Cmd Template 11447@section The Template for a Definition 11448@cindex Definition template 11449@cindex Template for a definition 11450 11451The @code{@@deffn} command is used for definitions of entities that 11452resemble functions. To write a definition using the @code{@@deffn} 11453command, write the @code{@@deffn} command at the beginning of a line 11454and follow it on the same line by the category of the entity, the name 11455of the entity itself, and its arguments (if any). Then write the body 11456of the definition on succeeding lines. (You may embed examples in the 11457body.) Finally, end the definition with an @code{@@end deffn} command 11458written on a line of its own. 11459 11460The other definition commands follow the same format: a line with the 11461@code{@@def@dots{}} command and whatever arguments are appropriate for 11462that command; the body of the definition; and a corresponding 11463@code{@@end} line. 11464 11465The template for a definition looks like this: 11466 11467@example 11468@group 11469@@deffn @var{category} @var{name} @var{arguments}@dots{} 11470@var{body-of-definition} 11471@@end deffn 11472@end group 11473@end example 11474 11475@need 700 11476@noindent 11477For example, 11478 11479@example 11480@group 11481@@deffn Command forward-word count 11482This command moves point forward @@var@{count@} words 11483(or backward if @@var@{count@} is negative). @dots{} 11484@@end deffn 11485@end group 11486@end example 11487 11488@noindent 11489produces 11490 11491@quotation 11492@deffn Command forward-word count 11493This function moves point forward @var{count} words 11494(or backward if @var{count} is negative). @dots{} 11495@end deffn 11496@end quotation 11497 11498Capitalize the category name like a title. If the name of the 11499category contains spaces, as in the phrase `Interactive Command', 11500enclose it in braces. For example: 11501 11502@example 11503@group 11504@@deffn @{Interactive Command@} isearch-forward 11505@dots{} 11506@@end deffn 11507@end group 11508@end example 11509 11510@noindent 11511Otherwise, the second word will be mistaken for the name of the 11512entity. As a general rule, when any of the arguments in the heading 11513line @emph{except} the last one are more than one word, you need to 11514enclose them in braces. 11515 11516Some of the definition commands are more general than others. The 11517@code{@@deffn} command, for example, is the general definition command 11518for functions and the like---for entities that may take arguments. 11519When you use this command, you specify the category to which the 11520entity belongs. Three predefined, specialized variations 11521(@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the 11522category for you: ``Function'', ``Macro'', and ``Special Form'' 11523respectively. (In Lisp, a special form is an entity much like a 11524function.) Similarly, the general @code{@@defvr} command is 11525accompanied by several specialized variations for describing 11526particular kinds of variables. 11527 11528@xref{Sample Function Definition}, for a detailed example of a 11529function definition, including the use of @code{@@example} inside the 11530definition. 11531 11532@cindex Macros in definition commands 11533Unfortunately, due to implementation difficulties, macros are not expanded 11534in @code{@@deffn} and all the other definition commands. 11535 11536 11537@node Def Cmd Continuation Lines 11538@section Definition Command Continuation Lines 11539@cindex Continuation lines in definition commands 11540@cindex Definition command headings, continuing 11541@cindex @samp{@@} as continuation in definition commands 11542 11543The heading line of a definition command can get very long. 11544Therefore, Texinfo has a special syntax allowing them to be continued 11545over multiple lines of the source file: a lone @samp{@@} at the end of 11546each line to be continued. Here's an example: 11547 11548@example 11549@@defun fn-name @@ 11550 arg1 arg2 arg3 11551This is the basic continued defun. 11552@@end defun 11553@end example 11554 11555@noindent produces: 11556 11557@defun fn-name @ 11558 arg1 arg2 arg3 11559This is the basic continued defun. 11560@end defun 11561 11562@noindent 11563As you can see, the continued lines are combined, as if they had been 11564typed on one source line. 11565 11566Although this example only shows a one-line continuation, 11567continuations may extend over any number of lines; simply put an 11568@code{@@} at the end of each line to be continued. 11569 11570The @code{@@} character does not have to be the last character on the 11571physical line: whitespace is allowed (and ignored) afterwards. 11572 11573@cindex Whitespace, collapsed around continuations 11574@cindex Collapsing whitespace around continuations 11575In general, any number of spaces or tabs around the @code{@@} 11576continuation character, both on the line with the @code{@@} and on the 11577continued line, are collapsed into a single space. There is one 11578exception: the Texinfo processors will not fully collapse whitespace 11579around a continuation inside braces. For example: 11580 11581@example 11582@@deffn @{Category @@ 11583 Name@} @dots{} 11584@end example 11585 11586@noindent The output (not shown) has excess space between `Category' 11587and `Name'. In this case, simply elide any unwanted whitespace in 11588your input, or put the continuation @code{@@} outside braces. 11589 11590@code{@@} does not (currently) function as a continuation character in 11591@emph{any} other context. Ordinarily, @samp{@@} followed by a 11592whitespace character (space, tab, newline) produces a normal interword 11593space (@pxref{Multiple Spaces}). 11594 11595 11596@node Optional Arguments 11597@section Optional and Repeated Arguments 11598@cindex Optional and repeated arguments 11599@cindex Repeated and optional arguments 11600@cindex Arguments, repeated and optional 11601@cindex Syntax, optional & repeated arguments 11602@cindex Meta-syntactic chars for arguments 11603 11604Some entities take optional or repeated arguments, which may be 11605specified by a distinctive glyph that uses square brackets and 11606ellipses. For @w{example}, a special form often breaks its argument list 11607into separate arguments in more complicated ways than a 11608straightforward function. 11609 11610@c This is consistent with Emacs Lisp Reference manual 11611An argument enclosed within square brackets is optional. 11612Thus, [@var{optional-arg}] means that @var{optional-arg} is optional. 11613An argument followed by an ellipsis is optional 11614and may be repeated more than once. 11615@c This is consistent with Emacs Lisp Reference manual 11616Thus, @var{repeated-args}@samp{@dots{}} stands for zero or more 11617arguments. Parentheses are used when several arguments are grouped 11618into additional levels of list structure in Lisp. 11619 11620Here is the @code{@@defspec} line of an example of an imaginary 11621special form: 11622 11623@quotation 11624@defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} 11625@end defspec 11626@tex 11627\vskip \parskip 11628@end tex 11629@end quotation 11630 11631@noindent 11632In this example, the arguments @var{from} and @var{to} are optional, 11633but must both be present or both absent. If they are present, 11634@var{inc} may optionally be specified as well. These arguments are 11635grouped with the argument @var{var} into a list, to distinguish them 11636from @var{body}, which includes all remaining elements of the 11637form.@refill 11638 11639In a Texinfo source file, this @code{@@defspec} line is written like 11640this (except it would not be split over two lines, as it is in this 11641example).@refill 11642 11643@example 11644@group 11645@@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@} 11646 [@@var@{inc@}]]) @@var@{body@}@@dots@{@} 11647@end group 11648@end example 11649 11650@noindent 11651The function is listed in the Command and Variable Index under 11652@samp{foobar}.@refill 11653 11654 11655@node deffnx 11656@section Two or More `First' Lines 11657@cindex Two `First' Lines for @code{@@deffn} 11658@cindex Grouping two definitions together 11659@cindex Definitions grouped together 11660@findex deffnx 11661 11662To create two or more `first' or header lines for a definition, follow 11663the first @code{@@deffn} line by a line beginning with @code{@@deffnx}. 11664The @code{@@deffnx} command works exactly like @code{@@deffn} 11665except that it does not generate extra vertical white space between it 11666and the preceding line.@refill 11667 11668@need 1000 11669For example, 11670 11671@example 11672@group 11673@@deffn @{Interactive Command@} isearch-forward 11674@@deffnx @{Interactive Command@} isearch-backward 11675These two search commands are similar except @dots{} 11676@@end deffn 11677@end group 11678@end example 11679 11680@noindent 11681produces 11682 11683@deffn {Interactive Command} isearch-forward 11684@deffnx {Interactive Command} isearch-backward 11685These two search commands are similar except @dots{} 11686@end deffn 11687 11688Each definition command has an `x' form: @code{@@defunx}, 11689@code{@@defvrx}, @code{@@deftypefunx}, etc. 11690 11691The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}). 11692 11693 11694@node Def Cmds in Detail 11695@section The Definition Commands 11696 11697Texinfo provides more than a dozen definition commands, all of which 11698are described in this section.@refill 11699 11700The definition commands automatically enter the name of the entity in 11701the appropriate index: for example, @code{@@deffn}, @code{@@defun}, 11702and @code{@@defmac} enter function names in the index of functions; 11703@code{@@defvr} and @code{@@defvar} enter variable names in the index 11704of variables.@refill 11705 11706Although the examples that follow mostly illustrate Lisp, the commands 11707can be used for other programming languages.@refill 11708 11709@menu 11710* Functions Commands:: Commands for functions and similar entities. 11711* Variables Commands:: Commands for variables and similar entities. 11712* Typed Functions:: Commands for functions in typed languages. 11713* Typed Variables:: Commands for variables in typed languages. 11714* Data Types:: The definition command for data types. 11715* Abstract Objects:: Commands for object-oriented programming. 11716@end menu 11717 11718@node Functions Commands 11719@subsection Functions and Similar Entities 11720 11721This section describes the commands for describing functions and similar 11722entities:@refill 11723 11724@table @code 11725@findex deffn 11726@item @@deffn @var{category} @var{name} @var{arguments}@dots{} 11727The @code{@@deffn} command is the general definition command for 11728functions, interactive commands, and similar entities that may take 11729arguments. You must choose a term to describe the category of entity 11730being defined; for example, ``Function'' could be used if the entity is 11731a function. The @code{@@deffn} command is written at the beginning of a 11732line and is followed on the same line by the category of entity being 11733described, the name of this particular entity, and its arguments, if 11734any. Terminate the definition with @code{@@end deffn} on a line of its 11735own.@refill 11736 11737@need 750 11738For example, here is a definition: 11739 11740@example 11741@group 11742@@deffn Command forward-char nchars 11743Move point forward @@var@{nchars@} characters. 11744@@end deffn 11745@end group 11746@end example 11747 11748@noindent 11749This shows a rather terse definition for a ``command'' named 11750@code{forward-char} with one argument, @var{nchars}. 11751 11752@code{@@deffn} and prints argument names such as @var{nchars} in slanted 11753type in the printed output, because we think of these names as 11754metasyntactic variables---they stand for the actual argument values. 11755Within the text of the description, however, write an argument name 11756explicitly with @code{@@var} to refer to the value of the argument. 11757In the example above, we used @samp{@@var@{nchars@}} in this way. 11758 11759In the unusual case when an argument name contains @samp{--}, or 11760another character sequence which is treated specially 11761(@pxref{Conventions}), use @code{@@var} around the argument. This 11762causes the name to be printed in slanted typewriter, instead of the 11763regular slanted font, exactly as input. 11764@c except for ?` and !`, but we won't explain that. 11765 11766The template for @code{@@deffn} is: 11767 11768@example 11769@group 11770@@deffn @var{category} @var{name} @var{arguments}@dots{} 11771@var{body-of-definition} 11772@@end deffn 11773@end group 11774@end example 11775 11776@findex defun 11777@item @@defun @var{name} @var{arguments}@dots{} 11778The @code{@@defun} command is the definition command for functions. 11779@code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}. 11780Terminate the definition with @code{@@end defun} on a line of its own. 11781Thus, the template is: 11782 11783@example 11784@group 11785@@defun @var{function-name} @var{arguments}@dots{} 11786@var{body-of-definition} 11787@@end defun 11788@end group 11789@end example 11790 11791@findex defmac 11792@item @@defmac @var{name} @var{arguments}@dots{} 11793The @code{@@defmac} command is the definition command for macros. 11794@code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and 11795works like @code{@@defun}. 11796 11797@findex defspec 11798@item @@defspec @var{name} @var{arguments}@dots{} 11799The @code{@@defspec} command is the definition command for special 11800forms. (In Lisp, a special form is an entity much like a function, 11801@pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.) 11802@code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@} 11803@dots{}} and works like @code{@@defun}. 11804@end table 11805 11806All these commands create entries in the index of functions. 11807 11808 11809@node Variables Commands 11810@subsection Variables and Similar Entities 11811 11812Here are the commands for defining variables and similar 11813entities:@refill 11814 11815@table @code 11816@findex defvr 11817@item @@defvr @var{category} @var{name} 11818The @code{@@defvr} command is a general definition command for 11819something like a variable---an entity that records a value. You must 11820choose a term to describe the category of entity being defined; for 11821example, ``Variable'' could be used if the entity is a variable. 11822Write the @code{@@defvr} command at the beginning of a line and 11823follow it on the same line by the category of the entity and the 11824name of the entity. 11825 11826Capitalize the category name like a title. If the name of the category 11827contains spaces, as in the name ``User Option'', enclose it in braces. 11828Otherwise, the second word will be mistaken for the name of the entity. 11829For example, 11830 11831@example 11832@group 11833@@defvr @{User Option@} fill-column 11834This buffer-local variable specifies 11835the maximum width of filled lines. 11836@dots{} 11837@@end defvr 11838@end group 11839@end example 11840 11841Terminate the definition with @code{@@end defvr} on a line of its 11842own.@refill 11843 11844The template is: 11845 11846@example 11847@group 11848@@defvr @var{category} @var{name} 11849@var{body-of-definition} 11850@@end defvr 11851@end group 11852@end example 11853 11854@code{@@defvr} creates an entry in the index of variables for @var{name}. 11855 11856@findex defvar 11857@item @@defvar @var{name} 11858The @code{@@defvar} command is the definition command for variables. 11859@code{@@defvar} is equivalent to @samp{@@defvr Variable 11860@dots{}}.@refill 11861 11862@need 750 11863For example: 11864 11865@example 11866@group 11867@@defvar kill-ring 11868@dots{} 11869@@end defvar 11870@end group 11871@end example 11872 11873The template is: 11874 11875@example 11876@group 11877@@defvar @var{name} 11878@var{body-of-definition} 11879@@end defvar 11880@end group 11881@end example 11882 11883@code{@@defvar} creates an entry in the index of variables for 11884@var{name}.@refill 11885 11886@findex defopt 11887@item @@defopt @var{name} 11888@cindex User options, marking 11889The @code{@@defopt} command is the definition command for @dfn{user 11890options}, i.e., variables intended for users to change according to 11891taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs 11892Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User 11893Option@} @dots{}} and works like @code{@@defvar}. It creates an entry 11894in the index of variables. 11895@end table 11896 11897 11898@node Typed Functions 11899@subsection Functions in Typed Languages 11900 11901The @code{@@deftypefn} command and its variations are for describing 11902functions in languages in which you must declare types of variables and 11903functions, such as C and C++. 11904 11905@table @code 11906@findex deftypefn 11907@item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{} 11908The @code{@@deftypefn} command is the general definition command for 11909functions and similar entities that may take arguments and that are 11910typed. The @code{@@deftypefn} command is written at the beginning of 11911a line and is followed on the same line by the category of entity 11912being described, the type of the returned value, the name of this 11913particular entity, and its arguments, if any.@refill 11914 11915@need 800 11916@noindent 11917For example, 11918 11919@example 11920@group 11921@@deftypefn @{Library Function@} int foobar 11922 (int @@var@{foo@}, float @@var@{bar@}) 11923@dots{} 11924@@end deftypefn 11925@end group 11926@end example 11927 11928@need 1000 11929@noindent 11930(where the text before the ``@dots{}'', shown above as two lines, would 11931actually be a single line in a real Texinfo file) produces the following 11932in Info: 11933 11934@smallexample 11935@group 11936-- Library Function: int foobar (int FOO, float BAR) 11937@dots{} 11938@end group 11939@end smallexample 11940@iftex 11941 11942In a printed manual, it produces: 11943 11944@quotation 11945@deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) 11946@dots{} 11947@end deftypefn 11948@end quotation 11949@end iftex 11950 11951This means that @code{foobar} is a ``library function'' that returns an 11952@code{int}, and its arguments are @var{foo} (an @code{int}) and 11953@var{bar} (a @code{float}).@refill 11954 11955Since in typed languages, the actual names of the arguments are 11956typically scattered among data type names and keywords, Texinfo cannot 11957find them without help. You can either (a)@tie{}write everything 11958as straight text, and it will be printed in slanted type; (b)@tie{}use 11959@code{@@var} for the variable names, which will uppercase the 11960variable names in Info and use the slanted typewriter font in printed 11961output; (c)@tie{}use @code{@@var} for the variable names and 11962@code{@@code} for the type names and keywords, which will be dutifully 11963obeyed. 11964 11965The template for @code{@@deftypefn} is:@refill 11966 11967@example 11968@group 11969@@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{} 11970@var{body-of-description} 11971@@end deftypefn 11972@end group 11973@end example 11974 11975@noindent 11976Note that if the @var{category} or @var{data type} is more than one 11977word then it must be enclosed in braces to make it a single argument.@refill 11978 11979If you are describing a procedure in a language that has packages, 11980such as Ada, you might consider using @code{@@deftypefn} in a manner 11981somewhat contrary to the convention described in the preceding 11982paragraphs. For example: 11983 11984@example 11985@group 11986@@deftypefn stacks private push @@ 11987 (@@var@{s@}:in out stack; @@ 11988 @@var@{n@}:in integer) 11989@dots{} 11990@@end deftypefn 11991@end group 11992@end example 11993 11994@noindent 11995(The @code{@@deftypefn} arguments are shown using continuations 11996(@pxref{Def Cmd Continuation Lines}), but could be on a single line in 11997a real Texinfo file.) 11998 11999In this instance, the procedure is classified as belonging to the 12000package @code{stacks} rather than classified as a `procedure' and its 12001data type is described as @code{private}. (The name of the procedure 12002is @code{push}, and its arguments are @var{s} and @var{n}.)@refill 12003 12004@code{@@deftypefn} creates an entry in the index of functions for 12005@var{name}. 12006 12007@item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{} 12008@findex deftypefun 12009The @code{@@deftypefun} command is the specialized definition command 12010for functions in typed languages. The command is equivalent to 12011@samp{@@deftypefn Function @dots{}}. The template is: 12012 12013@example 12014@group 12015@@deftypefun @var{type} @var{name} @var{arguments}@dots{} 12016@var{body-of-description} 12017@@end deftypefun 12018@end group 12019@end example 12020 12021@code{@@deftypefun} creates an entry in the index of functions for 12022@var{name}. 12023 12024@end table 12025 12026 12027@node Typed Variables 12028@subsection Variables in Typed Languages 12029 12030Variables in typed languages are handled in a manner similar to 12031functions in typed languages. @xref{Typed Functions}. The general 12032definition command @code{@@deftypevr} corresponds to 12033@code{@@deftypefn} and the specialized definition command 12034@code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill 12035 12036@table @code 12037@findex deftypevr 12038@item @@deftypevr @var{category} @var{data-type} @var{name} 12039The @code{@@deftypevr} command is the general definition command for 12040something like a variable in a typed language---an entity that records 12041a value. You must choose a term to describe the category of the 12042entity being defined; for example, ``Variable'' could be used if the 12043entity is a variable.@refill 12044 12045The @code{@@deftypevr} command is written at the beginning of a line 12046and is followed on the same line by the category of the entity 12047being described, the data type, and the name of this particular 12048entity.@refill 12049 12050@need 800 12051@noindent 12052For example: 12053 12054@example 12055@group 12056@@deftypevr @{Global Flag@} int enable 12057@dots{} 12058@@end deftypevr 12059@end group 12060@end example 12061 12062@noindent 12063produces the following in Info: 12064 12065@example 12066@group 12067-- Global Flag: int enable 12068@dots{} 12069@end group 12070@end example 12071@iftex 12072 12073@noindent 12074and the following in a printed manual: 12075 12076@quotation 12077@deftypevr {Global Flag} int enable 12078@dots{} 12079@end deftypevr 12080@end quotation 12081@end iftex 12082 12083@need 800 12084The template is: 12085 12086@example 12087@@deftypevr @var{category} @var{data-type} @var{name} 12088@var{body-of-description} 12089@@end deftypevr 12090@end example 12091 12092@findex deftypevar 12093@item @@deftypevar @var{data-type} @var{name} 12094The @code{@@deftypevar} command is the specialized definition command 12095for variables in typed languages. @code{@@deftypevar} is equivalent 12096to @samp{@@deftypevr Variable @dots{}}. The template is: 12097 12098@example 12099@group 12100@@deftypevar @var{data-type} @var{name} 12101@var{body-of-description} 12102@@end deftypevar 12103@end group 12104@end example 12105@end table 12106 12107These commands create entries in the index of variables. 12108 12109@node Data Types 12110@subsection Data Types 12111 12112Here is the command for data types:@refill 12113 12114@table @code 12115@findex deftp 12116@item @@deftp @var{category} @var{name} @var{attributes}@dots{} 12117The @code{@@deftp} command is the generic definition command for data 12118types. The command is written at the beginning of a line and is 12119followed on the same line by the category, by the name of the type 12120(which is a word like @code{int} or @code{float}), and then by names of 12121attributes of objects of that type. Thus, you could use this command 12122for describing @code{int} or @code{float}, in which case you could use 12123@code{data type} as the category. (A data type is a category of 12124certain objects for purposes of deciding which operations can be 12125performed on them.)@refill 12126 12127In Lisp, for example, @dfn{pair} names a particular data 12128type, and an object of that type has two slots called the 12129@sc{car} and the @sc{cdr}. Here is how you would write the first line 12130of a definition of @code{pair}.@refill 12131 12132@example 12133@group 12134@@deftp @{Data type@} pair car cdr 12135@dots{} 12136@@end deftp 12137@end group 12138@end example 12139 12140@need 950 12141The template is: 12142 12143@example 12144@group 12145@@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} 12146@var{body-of-definition} 12147@@end deftp 12148@end group 12149@end example 12150 12151@code{@@deftp} creates an entry in the index of data types. 12152@end table 12153 12154 12155@node Abstract Objects 12156@subsection Object-Oriented Programming 12157 12158@cindex Object-oriented programming 12159 12160Here are the commands for formatting descriptions about abstract 12161objects, such as are used in object-oriented programming. A class is 12162a defined type of abstract object. An instance of a class is a 12163particular object that has the type of the class. An instance 12164variable is a variable that belongs to the class but for which each 12165instance has its own value. 12166 12167@menu 12168* Variables: Object-Oriented Variables. 12169* Methods: Object-Oriented Methods. 12170@end menu 12171 12172 12173@node Object-Oriented Variables 12174@subsubsection Object-Oriented Variables 12175 12176@cindex Variables, object-oriented 12177 12178These commands allow you to define different sorts of variables in 12179object-oriented programming languages. 12180 12181@table @code 12182@item @@defcv @var{category} @var{class} @var{name} 12183@findex defcv 12184The @code{@@defcv} command is the general definition command for 12185variables associated with classes in object-oriented programming. The 12186@code{@@defcv} command is followed by three arguments: the category of 12187thing being defined, the class to which it belongs, and its 12188name. For instance: 12189 12190@example 12191@group 12192@@defcv @{Class Option@} Window border-pattern 12193@dots{} 12194@@end defcv 12195@end group 12196@end example 12197 12198@noindent produces: 12199@defcv {Class Option} Window border-pattern 12200@dots{} 12201@end defcv 12202 12203@code{@@defcv} creates an entry in the index of variables. 12204 12205@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} 12206@findex deftypecv 12207The @code{@@deftypecv} command is the definition command for typed 12208class variables in object-oriented programming. It is analogous to 12209@code{@@defcv} with the addition of the @var{data-type} parameter to 12210specify the type of the instance variable. Ordinarily, the data type 12211is a programming language construct that should be marked with 12212@code{@@code}. For instance: 12213 12214@example 12215@group 12216@@deftypecv @{Class Option@} Window @@code@{int@} border-pattern 12217@dots{} 12218@@end deftypecv 12219@end group 12220@end example 12221 12222@noindent produces: 12223 12224@deftypecv {Class Option} Window @code{int} border-pattern 12225@dots{} 12226@end deftypecv 12227 12228@code{@@deftypecv} creates an entry in the index of variables. 12229 12230@item @@defivar @var{class} @var{name} 12231@findex defivar 12232The @code{@@defivar} command is the definition command for instance 12233variables in object-oriented programming. @code{@@defivar} is 12234equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For 12235instance: 12236 12237@example 12238@group 12239@@defivar Window border-pattern 12240@dots{} 12241@@end defivar 12242@end group 12243@end example 12244 12245@noindent produces: 12246 12247@defivar Window border-pattern 12248@dots{} 12249@end defivar 12250 12251@code{@@defivar} creates an entry in the index of variables. 12252 12253@item @@deftypeivar @var{class} @var{data-type} @var{name} 12254@findex deftypeivar 12255The @code{@@deftypeivar} command is the definition command for typed 12256instance variables in object-oriented programming. It is analogous to 12257@code{@@defivar} with the addition of the @var{data-type} parameter to 12258specify the type of the instance variable. Ordinarily, the data type 12259is a programming language construct that should be marked with 12260@code{@@code}. For instance: 12261 12262@example 12263@group 12264@@deftypeivar Window @@code@{int@} border-pattern 12265@dots{} 12266@@end deftypeivar 12267@end group 12268@end example 12269 12270@noindent produces: 12271 12272@deftypeivar Window @code{int} border-pattern 12273@dots{} 12274@end deftypeivar 12275 12276@code{@@deftypeivar} creates an entry in the index of variables. 12277 12278@end table 12279 12280@node Object-Oriented Methods 12281@subsubsection Object-Oriented Methods 12282 12283@cindex Methods, object-oriented 12284 12285These commands allow you to define different sorts of function-like 12286entities resembling methods in object-oriented programming languages. 12287These entities take arguments, as functions do, but are associated with 12288particular classes of objects. 12289 12290@table @code 12291 12292@findex defop 12293@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} 12294The @code{@@defop} command is the general definition command for these 12295method-like entities. 12296 12297For example, some systems have constructs called @dfn{wrappers} that 12298are associated with classes as methods are, but that act more like 12299macros than like functions. You could use @code{@@defop Wrapper} to 12300describe one of these.@refill 12301 12302Sometimes it is useful to distinguish methods and @dfn{operations}. 12303You can think of an operation as the specification for a method. 12304Thus, a window system might specify that all window classes have a 12305method named @code{expose}; we would say that this window system 12306defines an @code{expose} operation on windows in general. Typically, 12307the operation has a name and also specifies the pattern of arguments; 12308all methods that implement the operation must accept the same 12309arguments, since applications that use the operation do so without 12310knowing which method will implement it.@refill 12311 12312Often it makes more sense to document operations than methods. For 12313example, window application developers need to know about the 12314@code{expose} operation, but need not be concerned with whether a 12315given class of windows has its own method to implement this operation. 12316To describe this operation, you would write:@refill 12317 12318@example 12319@@defop Operation windows expose 12320@end example 12321 12322The @code{@@defop} command is written at the beginning of a line and 12323is followed on the same line by the overall name of the category of 12324operation, the name of the class of the operation, the name of the 12325operation, and its arguments, if any.@refill 12326 12327The template is: 12328@example 12329@group 12330@@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} 12331@var{body-of-definition} 12332@@end defop 12333@end group 12334@end example 12335 12336@code{@@defop} creates an entry, such as `@code{expose} on 12337@code{windows}', in the index of functions.@refill 12338 12339@findex deftypeop 12340@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} 12341The @code{@@deftypeop} command is the definition command for typed 12342operations in object-oriented programming. It is similar to 12343@code{@@defop} with the addition of the @var{data-type} parameter to 12344specify the return type of the method. @code{@@deftypeop} creates an 12345entry in the index of functions. 12346 12347@item @@defmethod @var{class} @var{name} @var{arguments}@dots{} 12348@findex defmethod 12349The @code{@@defmethod} command is the definition command for methods 12350in object-oriented programming. A method is a kind of function that 12351implements an operation for a particular class of objects and its 12352subclasses. 12353@ignore 12354@c ADR: Who cares?!? 12355@c KB: Oh, I don't know, I think this info is crucial! 12356In the Lisp Machine, methods actually were functions, but 12357they were usually defined with @code{defmethod}. 12358@end ignore 12359 12360@code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}. 12361The command is written at the beginning of a line and is followed by 12362the name of the class of the method, the name of the method, and its 12363arguments, if any.@refill 12364 12365@noindent 12366For example: 12367@example 12368@group 12369@@defmethod @code{bar-class} bar-method argument 12370@dots{} 12371@@end defmethod 12372@end group 12373@end example 12374 12375@noindent 12376illustrates the definition for a method called @code{bar-method} of 12377the class @code{bar-class}. The method takes an argument. 12378 12379@code{@@defmethod} creates an entry in the index of functions. 12380 12381@item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{} 12382@findex defmethod 12383The @code{@@deftypemethod} command is the definition command for methods 12384in object-oriented typed languages, such as C++ and Java. It is similar 12385to the @code{@@defmethod} command with the addition of the 12386@var{data-type} parameter to specify the return type of the method. 12387@code{@@deftypemethod} creates an entry in the index of functions. 12388 12389@end table 12390 12391 12392@node Def Cmd Conventions 12393@section Conventions for Writing Definitions 12394@cindex Definition conventions 12395@cindex Conventions for writing definitions 12396 12397When you write a definition using @code{@@deffn}, @code{@@defun}, or 12398one of the other definition commands, please take care to use 12399arguments that indicate the meaning, as with the @var{count} argument 12400to the @code{forward-word} function. Also, if the name of an argument 12401contains the name of a type, such as @var{integer}, take care that the 12402argument actually is of that type.@refill 12403 12404 12405@node Sample Function Definition 12406@section A Sample Function Definition 12407@cindex Function definitions 12408@cindex Command definitions 12409@cindex Macro definitions 12410@cindex Sample function definition 12411 12412A function definition uses the @code{@@defun} and @code{@@end defun} 12413commands. The name of the function follows immediately after the 12414@code{@@defun} command and it is followed, on the same line, by the 12415parameter list.@refill 12416 12417Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs 12418Lisp Reference Manual}. 12419 12420@quotation 12421@defun apply function &rest arguments 12422@code{apply} calls @var{function} with @var{arguments}, just 12423like @code{funcall} but with one difference: the last of 12424@var{arguments} is a list of arguments to give to 12425@var{function}, rather than a single argument. We also say 12426that this list is @dfn{appended} to the other arguments. 12427 12428@code{apply} returns the result of calling @var{function}. 12429As with @code{funcall}, @var{function} must either be a Lisp 12430function or a primitive function; special forms and macros 12431do not make sense in @code{apply}. 12432 12433@example 12434(setq f 'list) 12435 @result{} list 12436(apply f 'x 'y 'z) 12437@error{} Wrong type argument: listp, z 12438(apply '+ 1 2 '(3 4)) 12439 @result{} 10 12440(apply '+ '(1 2 3 4)) 12441 @result{} 10 12442 12443(apply 'append '((a b c) nil (x y z) nil)) 12444 @result{} (a b c x y z) 12445@end example 12446 12447An interesting example of using @code{apply} is found in the description 12448of @code{mapcar}.@refill 12449@end defun 12450@end quotation 12451 12452@need 1200 12453In the Texinfo source file, this example looks like this: 12454 12455@example 12456@group 12457@@defun apply function &rest arguments 12458@@code@{apply@} calls @@var@{function@} with 12459@@var@{arguments@}, just like @@code@{funcall@} but with one 12460difference: the last of @@var@{arguments@} is a list of 12461arguments to give to @@var@{function@}, rather than a single 12462argument. We also say that this list is @@dfn@{appended@} 12463to the other arguments. 12464@end group 12465 12466@group 12467@@code@{apply@} returns the result of calling 12468@@var@{function@}. As with @@code@{funcall@}, 12469@@var@{function@} must either be a Lisp function or a 12470primitive function; special forms and macros do not make 12471sense in @@code@{apply@}. 12472@end group 12473 12474@group 12475@@example 12476(setq f 'list) 12477 @@result@{@} list 12478(apply f 'x 'y 'z) 12479@@error@{@} Wrong type argument: listp, z 12480(apply '+ 1 2 '(3 4)) 12481 @@result@{@} 10 12482(apply '+ '(1 2 3 4)) 12483 @@result@{@} 10 12484 12485(apply 'append '((a b c) nil (x y z) nil)) 12486 @@result@{@} (a b c x y z) 12487@@end example 12488@end group 12489 12490@group 12491An interesting example of using @@code@{apply@} is found 12492in the description of @@code@{mapcar@}. 12493@@end defun 12494@end group 12495@end example 12496 12497@noindent 12498In this manual, this function is listed in the Command and Variable 12499Index under @code{apply}.@refill 12500 12501Ordinary variables and user options are described using a format like 12502that for functions except that variables do not take arguments. 12503 12504 12505@node Conditionals 12506@chapter Conditionally Visible Text 12507@cindex Conditionally visible text 12508@cindex Text, conditionally visible 12509@cindex Visibility of conditional text 12510@cindex If text conditionally visible 12511 12512The @dfn{conditional commands} allow you to use different text for 12513different output formats, or for general conditions that you define. 12514For example, you can use them to specify different text for the 12515printed manual and the Info output. 12516 12517The conditional commands comprise the following categories. 12518 12519@itemize @bullet 12520@item 12521Commands specific to an output format (Info, @TeX{}, HTML, @dots{}). 12522 12523@item 12524Commands specific to any output format @emph{other} than a given 12525one (not Info, not @TeX{}, @dots{}). 12526 12527@item 12528`Raw' formatter text for any output format, passed straight 12529through with no interpretation of @@-commands. 12530 12531@item 12532Format-independent variable substitutions, and testing if a variable 12533is set or clear. 12534 12535@end itemize 12536 12537@menu 12538* Conditional Commands:: Text for a given format. 12539* Conditional Not Commands:: Text for any format other than a given one. 12540* Raw Formatter Commands:: Using raw formatter commands. 12541* set clear value:: Variable tests and substitutions. 12542* Conditional Nesting:: Using conditionals inside conditionals. 12543@end menu 12544 12545 12546@node Conditional Commands 12547@section Conditional Commands 12548 12549Texinfo has an @code{@@if@var{format}} environment for each output 12550format, to allow conditional inclusion of text for a particular output 12551format. 12552 12553@findex ifinfo 12554@code{@@ifinfo} begins segments of text that should be ignored by 12555@TeX{} when it typesets the printed manual, and by @command{makeinfo} 12556when not producing Info output. The segment of text appears only in 12557the Info file and, for historical compatibility, the plain text 12558output. 12559 12560@findex ifdocbook 12561@findex ifhtml 12562@findex ifplaintext 12563@findex iftex 12564@findex ifxml 12565The environments for the other formats are analogous: 12566 12567@table @code 12568@item @@ifdocbook @dots{} @@end ifdocbook 12569Text to appear only in the Docbook output. 12570 12571@item @@ifhtml @dots{} @@end ifhtml 12572Text to appear only in the HTML output. 12573 12574@item @@ifplaintext @dots{} @@end ifplaintext 12575Text to appear only in the plain text output. 12576 12577@item @@iftex @dots{} @@end iftex 12578Text to appear only in the printed manual. 12579 12580@item @@ifxml @dots{} @@end ifxml 12581Text to appear only in the XML output. 12582@end table 12583 12584The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear 12585on lines by themselves in your source file. 12586 12587Here is an example showing all these conditionals: 12588 12589@example 12590@@iftex 12591This text will appear only in the printed manual. 12592@@end iftex 12593@@ifinfo 12594However, this text will appear only in Info and plain text. 12595@@end ifinfo 12596@@ifhtml 12597And this text will only appear in HTML. 12598@@end ifhtml 12599@@ifplaintext 12600Whereas this text will only appear in plain text. 12601@@end ifplaintext 12602@@ifxml 12603Notwithstanding that this will only appear in XML. 12604@@end ifxml 12605@@ifdocbook 12606Nevertheless, this will only appear in Docbook. 12607@@end ifdocbook 12608@end example 12609 12610@noindent 12611The preceding example produces the following line: 12612 12613@iftex 12614This text will appear only in the printed manual. 12615@end iftex 12616@ifinfo 12617However, this text will appear only in Info and plain text. 12618@end ifinfo 12619@ifhtml 12620And this text will only appear in HTML. 12621@end ifhtml 12622@ifplaintext 12623Whereas this text will only appear in plain text. 12624@end ifplaintext 12625@ifxml 12626Notwithstanding that this will only appear in XML. 12627@end ifxml 12628@ifdocbook 12629Nevertheless, this will only appear in Docbook. 12630@end ifdocbook 12631 12632@noindent 12633Notice that you only see one of the input lines, depending on which 12634version of the manual you are reading. 12635 12636 12637@node Conditional Not Commands 12638@section Conditional Not Commands 12639@findex ifnotdocbook 12640@findex ifnothtml 12641@findex ifnotinfo 12642@findex ifnotplaintext 12643@findex ifnottex 12644@findex ifnotxml 12645 12646You can specify text to be included in any output format @emph{other} 12647than a given one with the @code{@@ifnot@dots{}} environments: 12648 12649@example 12650@@ifnotdocbook @dots{} @@end ifnotdocbook 12651@@ifnothtml @dots{} @@end ifnothtml 12652@@ifnotinfo @dots{} @@end ifnotinfo 12653@@ifnotplaintext @dots{} @@end ifnotplaintext 12654@@ifnottex @dots{} @@end ifnottex 12655@@ifnotxml @dots{} @@end ifnotxml 12656@end example 12657 12658@noindent 12659The @code{@@ifnot@dots{}} command and the @code{@@end} command must 12660appear on lines by themselves in your actual source file. 12661 12662If the output file is being made in the given format, the 12663region is @emph{ignored}. Otherwise, it is included. 12664 12665There is one exception (for historical compatibility): 12666@code{@@ifnotinfo} text is omitted for both Info and plain text 12667output, not just Info. To specify text which appears only in Info and 12668not in plain text, use @code{@@ifnotplaintext}, like this: 12669 12670@example 12671@@ifinfo 12672@@ifnotplaintext 12673This will be in Info, but not plain text. 12674@@end ifnotplaintext 12675@@end ifinfo 12676@end example 12677 12678The regions delimited by these commands are ordinary Texinfo source as 12679with @code{@@iftex}, not raw formatter source as with @code{@@tex} 12680(@pxref{Raw Formatter Commands}). 12681 12682 12683@node Raw Formatter Commands 12684@section Raw Formatter Commands 12685@cindex Raw formatter commands 12686@cindex @TeX{} commands, using ordinary 12687@cindex Ordinary @TeX{} commands, using 12688@cindex Commands using raw @TeX{} 12689@cindex Docbook, including raw 12690@cindex HTML, including raw 12691@cindex XML, including raw 12692@cindex Plain @TeX{} 12693 12694Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, 12695you can embed some raw @TeX{} commands. The Texinfo processors will 12696ignore such a region unless @TeX{} output is being produced. You can 12697write the @TeX{} commands as you would write them in a normal @TeX{} 12698file, except that you must replace the @samp{\} used by @TeX{} with an 12699@samp{@@}. For example, in the @code{@@titlepage} section of a 12700Texinfo file, you can use the @TeX{} command @code{@@vskip} to format 12701the copyright page. (The @code{@@titlepage} command causes Info to 12702ignore the region automatically, as it does with the @code{@@iftex} 12703command.) 12704 12705However, most features of plain @TeX{} will not work within 12706@code{@@iftex}, as they are overridden by Texinfo features. The 12707purpose of @code{@@iftex} is to provide conditional processing for the 12708Texinfo source, not provide access to underlying formatting features. 12709 12710@findex tex 12711You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{} 12712commands, by delineating a region with the @code{@@tex} and @code{@@end 12713tex} commands. All plain @TeX{} commands and category codes are 12714restored within an @code{@@tex} region. The sole exception is that the 12715@code{@@} character still introduces a command, so that @code{@@end tex} 12716can be recognized properly. As with @code{@@iftex}, Texinfo 12717processors will ignore such a region unless @TeX{} output is being produced. 12718 12719@findex \gdef @r{within @code{@@tex}} 12720In complex cases, you may wish to define new @TeX{} macros within 12721@code{@@tex}. You must use @code{\gdef} to do this, not @code{\def}, 12722because @code{@@tex} regions are processed in a @TeX{} group. 12723 12724@cindex Mathematical expressions 12725As an example, here is a mathematical expression written in plain @TeX{}: 12726 12727@example 12728@@tex 12729$$ \chi^2 = \sum_@{i=1@}^N 12730 \left (y_i - (a + b x_i) 12731 \over \sigma_i\right)^2 $$ 12732@@end tex 12733@end example 12734 12735@noindent 12736The output of this example will appear only in a printed manual. If 12737you are reading this in Info, you will not see the equation that appears 12738in the printed manual. 12739@iftex 12740In a printed manual, the above expression looks like 12741this: 12742@end iftex 12743 12744@tex 12745$$ \chi^2 = \sum_{i=1}^N 12746 \left(y_i - (a + b x_i) 12747 \over \sigma_i\right)^2 $$ 12748@end tex 12749 12750@findex ifhtml 12751@findex html 12752Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit 12753a region to be included in HTML output only, and @code{@@html @dots{} 12754@@end html} for a region of raw HTML. 12755 12756@findex ifxml 12757@findex xml 12758Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit 12759a region to be included in XML output only, and @code{@@xml @dots{} 12760@@end xml} for a region of raw XML. 12761 12762@findex ifdocbook 12763@findex docbook 12764Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook} 12765to delimit a region to be included in Docbook output only, and 12766@code{@@docbook @dots{} @@end docbook} for a region of raw Docbook. 12767 12768In all cases, the exception to the raw processing is that @code{@@} is 12769still an escape character, so the @code{@@end} command can be 12770recognized. 12771 12772 12773@node set clear value 12774@section @code{@@set}, @code{@@clear}, and @code{@@value} 12775 12776You can direct the Texinfo formatting commands to format or ignore parts 12777of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset}, 12778and @code{@@ifclear} commands. 12779 12780Here are brief descriptions of these commands, see the following 12781sections for more details: 12782 12783@table @code 12784@item @@set @var{flag} [@var{value}] 12785Set the variable @var{flag}, to the optional @var{value} if specifed. 12786 12787@item @@clear @var{flag} 12788Undefine the variable @var{flag}, whether or not it was previously defined. 12789 12790@item @@ifset @var{flag} 12791If @var{flag} is set, text through the next @code{@@end ifset} command 12792is formatted. If @var{flag} is clear, text through the following 12793@code{@@end ifset} command is ignored. 12794 12795@item @@ifclear @var{flag} 12796If @var{flag} is set, text through the next @code{@@end ifclear} command 12797is ignored. If @var{flag} is clear, text through the following 12798@code{@@end ifclear} command is formatted. 12799@end table 12800 12801@menu 12802* set value:: Expand a flag variable to a string. 12803* ifset ifclear:: Format a region if a flag is set. 12804* value Example:: An easy way to update edition information. 12805@end menu 12806 12807 12808@node set value 12809@subsection @code{@@set} and @code{@@value} 12810@findex value 12811 12812You use the @code{@@set} command to specify a value for a flag, which 12813is later expanded by the @code{@@value} command. 12814 12815A @dfn{flag} (aka @dfn{variable}) is an identifier. It is best to use 12816only letters and numerals in a flag name, not @samp{-} or 12817@samp{_}---they will work in some contexts, but not all, due to 12818limitations in @TeX{}. 12819 12820The value is the remainder of the input line, and can contain anything. 12821 12822Write the @code{@@set} command like this: 12823 12824@example 12825@@set foo This is a string. 12826@end example 12827 12828@noindent 12829This sets the value of the flag @code{foo} to ``This is a string.''. 12830 12831The Texinfo formatters then replace an @code{@@value@{@var{flag}@}} 12832command with the string to which @var{flag} is set. Thus, when 12833@code{foo} is set as shown above, the Texinfo formatters convert this: 12834 12835@example 12836@group 12837@@value@{foo@} 12838@exdent @r{to this:} 12839This is a string. 12840@end group 12841@end example 12842 12843You can write an @code{@@value} command within a paragraph; but you 12844must write an @code{@@set} command on a line of its own. 12845 12846If you write the @code{@@set} command like this: 12847 12848@example 12849@@set foo 12850@end example 12851 12852@noindent 12853without specifying a string, the value of @code{foo} is the empty string. 12854 12855If you clear a previously set flag with @code{@@clear @var{flag}}, a 12856subsequent @code{@@value@{flag@}} command will report an error. 12857 12858For example, if you set @code{foo} as follows: 12859 12860@example 12861@@set howmuch very, very, very 12862@end example 12863 12864@noindent 12865then the formatters transform 12866 12867@example 12868@group 12869It is a @@value@{howmuch@} wet day. 12870@exdent @r{into} 12871It is a very, very, very wet day. 12872@end group 12873@end example 12874 12875If you write 12876 12877@example 12878@@clear howmuch 12879@end example 12880 12881@noindent 12882then the formatters transform 12883 12884@example 12885@group 12886It is a @@value@{howmuch@} wet day. 12887@exdent @r{into} 12888It is a @{No value for "howmuch"@} wet day. 12889@end group 12890@end example 12891 12892 12893@node ifset ifclear 12894@subsection @code{@@ifset} and @code{@@ifclear} 12895 12896@findex ifset 12897When a @var{flag} is set, the Texinfo formatting commands format text 12898between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end 12899ifset} commands. When the @var{flag} is cleared, the Texinfo formatting 12900commands do @emph{not} format the text. @code{@@ifclear} operates 12901analogously. 12902 12903Write the conditionally formatted text between @code{@@ifset @var{flag}} 12904and @code{@@end ifset} commands, like this: 12905 12906@example 12907@group 12908@@ifset @var{flag} 12909@var{conditional-text} 12910@@end ifset 12911@end group 12912@end example 12913 12914For example, you can create one document that has two variants, such as 12915a manual for a `large' and `small' model: 12916 12917@cindex Shrubbery 12918@example 12919You can use this machine to dig up shrubs 12920without hurting them. 12921 12922@@set large 12923 12924@@ifset large 12925It can also dig up fully grown trees. 12926@@end ifset 12927 12928Remember to replant promptly @dots{} 12929@end example 12930 12931@noindent 12932In the example, the formatting commands will format the text between 12933@code{@@ifset large} and @code{@@end ifset} because the @code{large} 12934flag is set. 12935 12936When @var{flag} is cleared, the Texinfo formatting commands do 12937@emph{not} format the text between @code{@@ifset @var{flag}} and 12938@code{@@end ifset}; that text is ignored and does not appear in either 12939printed or Info output. 12940 12941For example, if you clear the flag of the preceding example by writing 12942an @code{@@clear large} command after the @code{@@set large} command 12943(but before the conditional text), then the Texinfo formatting commands 12944ignore the text between the @code{@@ifset large} and @code{@@end ifset} 12945commands. In the formatted output, that text does not appear; in both 12946printed and Info output, you see only the lines that say, ``You can use 12947this machine to dig up shrubs without hurting them. Remember to replant 12948promptly @dots{}''. 12949 12950@findex ifclear 12951If a flag is cleared with an @code{@@clear @var{flag}} command, then 12952the formatting commands format text between subsequent pairs of 12953@code{@@ifclear} and @code{@@end ifclear} commands. But if the flag 12954is set with @code{@@set @var{flag}}, then the formatting commands do 12955@emph{not} format text between an @code{@@ifclear} and an @code{@@end 12956ifclear} command; rather, they ignore that text. An @code{@@ifclear} 12957command looks like this: 12958 12959@example 12960@@ifclear @var{flag} 12961@end example 12962 12963 12964@node value Example 12965@subsection @code{@@value} Example 12966 12967You can use the @code{@@value} command to minimize the number of 12968places you need to change when you record an update to a manual. 12969@xref{GNU Sample Texts}, for the full text of an example of using this 12970to work with Automake distributions. 12971 12972This example is adapted from @ref{Top,, Overview, make, The GNU Make 12973Manual}. 12974 12975@enumerate 12976@item 12977Set the flags: 12978 12979@example 12980@group 12981@@set EDITION 0.35 Beta 12982@@set VERSION 3.63 Beta 12983@@set UPDATED 14 August 1992 12984@@set UPDATE-MONTH August 1992 12985@end group 12986@end example 12987 12988@item 12989Write text for the @code{@@copying} section (@pxref{copying}): 12990 12991@example 12992@group 12993@@copying 12994This is Edition @@value@{EDITION@}, 12995last updated @@value@{UPDATED@}, 12996of @@cite@{The GNU Make Manual@}, 12997for @@code@{make@}, version @@value@{VERSION@}. 12998 12999Copyright @dots{} 13000 13001Permission is granted @dots{} 13002@@end copying 13003@end group 13004@end example 13005 13006@item 13007Write text for the title page, for people reading the printed manual: 13008 13009@example 13010@group 13011@@titlepage 13012@@title GNU Make 13013@@subtitle A Program for Directing Recompilation 13014@@subtitle Edition @@value@{EDITION@}, @dots{} 13015@@subtitle @@value@{UPDATE-MONTH@} 13016@@page 13017@@insertcopying 13018@dots{} 13019@@end titlepage 13020@end group 13021@end example 13022 13023@noindent 13024(On a printed cover, a date listing the month and the year looks less 13025fussy than a date listing the day as well as the month and year.) 13026 13027@item 13028Write text for the Top node, for people reading the Info file: 13029 13030@example 13031@group 13032@@ifnottex 13033@@node Top 13034@@top Make 13035 13036@@insertcopying 13037@dots{} 13038@@end ifnottex 13039@end group 13040@end example 13041 13042After you format the manual, the @code{@@value} constructs have been 13043expanded, so the output contains text like this: 13044 13045@example 13046@group 13047This is Edition 0.35 Beta, last updated 14 August 1992, 13048of `The GNU Make Manual', for `make', Version 3.63 Beta. 13049@end group 13050@end example 13051@end enumerate 13052 13053When you update the manual, you change only the values of the flags; you 13054do not need to edit the three sections. 13055 13056 13057@node Conditional Nesting 13058@section Conditional Nesting 13059@cindex Conditionals, nested 13060@cindex Nesting conditionals 13061 13062Conditionals can be nested; however, the details are a little tricky. 13063The difficulty comes with failing conditionals, such as 13064@code{@@ifhtml} when HTML is not being produced, where the included 13065text is to be ignored. However, it is not to be @emph{completely} 13066ignored, since it is useful to have one @code{@@ifset} inside another, 13067for example---that is a way to include text only if two conditions are 13068met. Here's an example: 13069 13070@example 13071@@ifset somevar 13072@@ifset anothervar 13073Both somevar and anothervar are set. 13074@@end ifset 13075@@ifclear anothervar 13076Somevar is set, anothervar is not. 13077@@end ifclear 13078@@end ifset 13079@end example 13080 13081Technically, Texinfo requires that for a failing conditional, the 13082ignored text must be properly nested with respect to that failing 13083conditional. Unfortunately, it's not always feasible to check that 13084@emph{all} conditionals are properly nested, because then the 13085processors could have to fully interpret the ignored text, which 13086defeats the purpose of the command. Here's an example illustrating 13087these rules: 13088 13089@example 13090@@ifset a 13091@@ifset b 13092@@ifclear ok - ok, ignored 13093@@end junky - ok, ignored 13094@@end ifset 13095@@c WRONG - missing @@end ifset. 13096@end example 13097 13098Finally, as mentioned above, all conditional commands must be on lines 13099by themselves, with no text (even spaces) before or after. Otherwise, 13100the processors cannot reliably determine which commands to consider 13101for nesting purposes. 13102 13103 13104@node Internationalization 13105@chapter Internationalization 13106 13107@cindex Internationalization 13108Texinfo has some support for writing in languages other than English, 13109although this area still needs considerable work. 13110 13111For a list of the various accented and special characters Texinfo 13112supports, see @ref{Inserting Accents}. 13113 13114@menu 13115* documentlanguage:: Declaring the current language. 13116* documentencoding:: Declaring the input encoding. 13117@end menu 13118 13119 13120@node documentlanguage 13121@section @code{@@documentlanguage @var{cc}}: Set the Document Language 13122 13123@findex documentlanguage 13124@cindex Language, declaring 13125@cindex Document language, declaring 13126 13127The @code{@@documentlanguage} command declares the current document 13128language. Write it on a line by itself, with a two-letter ISO-639 13129language code following (list is included below). If you have a 13130multilingual document, the intent is to be able to use this command 13131multiple times, to declare each language change. If the command is not 13132used at all, the default is @code{en} for English. 13133 13134@cindex @file{txi-@var{cc}.tex} 13135At present, this command is ignored in Info and HTML output. For 13136@TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it 13137exists). Such a file appropriately redefines the various English words 13138used in @TeX{} output, such as `Chapter', `See', and so on. 13139 13140@cindex Hyphenation patterns, language-dependent 13141It would be good if this command also changed @TeX{}'s ideas of the 13142current hyphenation patterns (via the @TeX{} primitive 13143@code{\language}), but this is unfortunately not currently implemented. 13144 13145@cindex ISO 639 codes 13146@cindex Language codes 13147Hereare the valid language codes, from ISO-639. 13148 13149@multitable @columnfractions .07 .26 .07 .26 .07 .26 13150@item 13151@code{aa} @tab Afar @tab 13152@code{ab} @tab Abkhazian @tab 13153@code{af} @tab Afrikaans 13154@item 13155@code{am} @tab Amharic @tab 13156@code{ar} @tab Arabic @tab 13157@code{as} @tab Assamese 13158@item 13159@code{ay} @tab Aymara @tab 13160@code{az} @tab Azerbaijani @tab 13161@code{ba} @tab Bashkir 13162@item 13163@code{be} @tab Byelorussian @tab 13164@code{bg} @tab Bulgarian @tab 13165@code{bh} @tab Bihari 13166@item 13167@code{bi} @tab Bislama @tab 13168@code{bn} @tab Bengali; Bangla @tab 13169@code{bo} @tab Tibetan 13170@item 13171@code{br} @tab Breton @tab 13172@code{ca} @tab Catalan @tab 13173@code{co} @tab Corsican 13174@item 13175@code{cs} @tab Czech @tab 13176@code{cy} @tab Welsh @tab 13177@code{da} @tab Danish 13178@item 13179@code{de} @tab German @tab 13180@code{dz} @tab Bhutani @tab 13181@code{el} @tab Greek 13182@item 13183@code{en} @tab English @tab 13184@code{eo} @tab Esperanto @tab 13185@code{es} @tab Spanish 13186@item 13187@code{et} @tab Estonian @tab 13188@code{eu} @tab Basque @tab 13189@code{fa} @tab Persian 13190@item 13191@code{fi} @tab Finnish @tab 13192@code{fj} @tab Fiji @tab 13193@code{fo} @tab Faroese 13194@item 13195@code{fr} @tab French @tab 13196@code{fy} @tab Frisian @tab 13197@code{ga} @tab Irish 13198@item 13199@code{gd} @tab Scots Gaelic @tab 13200@code{gl} @tab Galician @tab 13201@code{gn} @tab Guarani 13202@item 13203@code{gu} @tab Gujarati @tab 13204@code{ha} @tab Hausa @tab 13205@code{he} @tab Hebrew 13206@item 13207@code{hi} @tab Hindi @tab 13208@code{hr} @tab Croatian @tab 13209@code{hu} @tab Hungarian 13210@item 13211@code{hy} @tab Armenian @tab 13212@code{ia} @tab Interlingua @tab 13213@code{id} @tab Indonesian 13214@item 13215@code{ie} @tab Interlingue @tab 13216@code{ik} @tab Inupiak @tab 13217@code{is} @tab Icelandic 13218@item 13219@code{it} @tab Italian @tab 13220@code{iu} @tab Inuktitut @tab 13221@code{ja} @tab Japanese 13222@item 13223@code{jw} @tab Javanese @tab 13224@code{ka} @tab Georgian @tab 13225@code{kk} @tab Kazakh 13226@item 13227@code{kl} @tab Greenlandic @tab 13228@code{km} @tab Cambodian @tab 13229@code{kn} @tab Kannada 13230@item 13231@code{ks} @tab Kashmiri @tab 13232@code{ko} @tab Korean @tab 13233@code{ku} @tab Kurdish 13234@item 13235@code{ky} @tab Kirghiz @tab 13236@code{la} @tab Latin @tab 13237@code{ln} @tab Lingala 13238@item 13239@code{lt} @tab Lithuanian @tab 13240@code{lo} @tab Laothian @tab 13241@code{lv} @tab Latvian, Lettish 13242@item 13243@code{mg} @tab Malagasy @tab 13244@code{mi} @tab Maori @tab 13245@code{mk} @tab Macedonian 13246@item 13247@code{ml} @tab Malayalam @tab 13248@code{mn} @tab Mongolian @tab 13249@code{mo} @tab Moldavian 13250@item 13251@code{mr} @tab Marathi @tab 13252@code{ms} @tab Malay @tab 13253@code{mt} @tab Maltese 13254@item 13255@code{my} @tab Burmese @tab 13256@code{na} @tab Nauru @tab 13257@code{ne} @tab Nepali 13258@item 13259@code{nl} @tab Dutch @tab 13260@code{no} @tab Norwegian @tab 13261@code{oc} @tab Occitan 13262@item 13263@code{om} @tab (Afan) Oromo @tab 13264@code{or} @tab Oriya @tab 13265@code{pa} @tab Punjabi 13266@item 13267@code{pl} @tab Polish @tab 13268@code{ps} @tab Pashto, Pushto @tab 13269@code{pt} @tab Portuguese 13270@item 13271@code{qu} @tab Quechua @tab 13272@code{rm} @tab Rhaeto-Romance @tab 13273@code{rn} @tab Kirundi 13274@item 13275@code{ro} @tab Romanian @tab 13276@code{ru} @tab Russian @tab 13277@code{rw} @tab Kinyarwanda 13278@item 13279@code{sa} @tab Sanskrit @tab 13280@code{sd} @tab Sindhi @tab 13281@code{sg} @tab Sangro 13282@item 13283@code{sh} @tab Serbo-Croatian @tab 13284@code{si} @tab Sinhalese @tab 13285@code{sk} @tab Slovak 13286@item 13287@code{sl} @tab Slovenian @tab 13288@code{sm} @tab Samoan @tab 13289@code{sn} @tab Shona 13290@item 13291@code{so} @tab Somali @tab 13292@code{sq} @tab Albanian @tab 13293@code{sr} @tab Serbian 13294@item 13295@code{ss} @tab Siswati @tab 13296@code{st} @tab Sesotho @tab 13297@code{su} @tab Sundanese 13298@item 13299@code{sv} @tab Swedish @tab 13300@code{sw} @tab Swahili @tab 13301@code{ta} @tab Tamil 13302@item 13303@code{te} @tab Telugu @tab 13304@code{tg} @tab Tajik @tab 13305@code{th} @tab Thai 13306@item 13307@code{ti} @tab Tigrinya @tab 13308@code{tk} @tab Turkmen @tab 13309@code{tl} @tab Tagalog 13310@item 13311@code{tn} @tab Setswana @tab 13312@code{to} @tab Tonga @tab 13313@code{tr} @tab Turkish 13314@item 13315@code{ts} @tab Tsonga @tab 13316@code{tt} @tab Tatar @tab 13317@code{tw} @tab Twi 13318@item 13319@code{ug} @tab Uighur @tab 13320@code{uk} @tab Ukrainian @tab 13321@code{ur} @tab Urdu 13322@item 13323@code{uz} @tab Uzbek @tab 13324@code{vi} @tab Vietnamese @tab 13325@code{vo} @tab Volapuk 13326@item 13327@code{wo} @tab Wolof @tab 13328@code{xh} @tab Xhosa @tab 13329@code{yi} @tab Yiddish 13330@item 13331@code{yo} @tab Yoruba @tab 13332@code{za} @tab Zhuang @tab 13333@code{zh} @tab Chinese 13334@item 13335@code{zu} @tab Zulu 13336@end multitable 13337 13338 13339@node documentencoding 13340@section @code{@@documentencoding @var{enc}}: Set Input Encoding 13341 13342@findex documentencoding 13343@cindex Encoding, declaring 13344@cindex Input encoding, declaring 13345@cindex Character set, declaring 13346@cindex Document input encoding 13347 13348The @code{@@documentencoding} command declares the input document 13349encoding. Write it on a line by itself, with a valid encoding 13350specification following. 13351 13352At present, Texinfo supports only these encodings: 13353 13354@table @code 13355@item US-ASCII 13356This has no particular effect, but it's included for completeness. 13357 13358@itemx ISO-8859-1 13359@itemx ISO-8859-15 13360@item ISO-8859-2 13361These specify the standard encodings for Western European (the first 13362two) and Eastern European languages (the third), respectively. ISO 133638859-15 replaces some little-used characters from 8859-1 (e.g., 13364precomposed fractions) with more commonly needed ones, such as the 13365Euro symbol. 13366 13367A full description of the encodings is beyond our scope here; 13368one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}. 13369@end table 13370 13371Specifying an encoding @var{enc} has the following effects: 13372 13373@opindex --enable-encoding 13374@cindex Local Variables: section, for encoding 13375@cindex Info output, and encoding 13376In Info output, if the option @option{--enable-encoding} is given 13377to @command{makeinfo}, a so-called `Local Variables' section 13378(@pxref{File Variables,,,emacs,The GNU Emacs Manual}) is output 13379including @var{enc}. This allows Info readers to set the encoding 13380appropriately. 13381 13382@example 13383Local Variables: 13384coding: @var{enc} 13385End: 13386@end example 13387 13388@cindex HTML output, and encodings 13389@cindex @code{http-equiv}, and charset specification 13390@cindex @code{<meta>} HTML tag, and charset specification 13391In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>} 13392section of the HTML, that specifies @var{enc}. Web servers and 13393browsers cooperate to use this information so the correct encoding is 13394used to display the page, if supported by the system. 13395 13396@example 13397<meta http-equiv="Content-Type" content="text/html; 13398 charset=@var{enc}"> 13399@end example 13400 13401In all other cases, it is recognized but ignored. 13402 13403 13404@node Defining New Texinfo Commands 13405@chapter Defining New Texinfo Commands 13406@cindex Macros 13407@cindex Defining new Texinfo commands 13408@cindex New Texinfo commands, defining 13409@cindex Texinfo commands, defining new 13410@cindex User-defined Texinfo commands 13411 13412Texinfo provides several ways to define new commands: 13413 13414@itemize @bullet 13415@item 13416A Texinfo @dfn{macro} allows you to define a new Texinfo command as any 13417sequence of text and/or existing commands (including other macros). The 13418macro can have any number of @dfn{parameters}---text you supply each 13419time you use the macro. 13420 13421Incidentally, these macros have nothing to do with the @code{@@defmac} 13422command, which is for documenting macros in the subject of the manual 13423(@pxref{Def Cmd Template}). 13424 13425@item 13426@samp{@@alias} is a convenient way to define a new name for an existing 13427command. 13428 13429@item 13430@samp{@@definfoenclose} allows you to define new commands with 13431customized output in the Info file. 13432 13433@end itemize 13434 13435@menu 13436* Defining Macros:: Defining and undefining new commands. 13437* Invoking Macros:: Using a macro, once you've defined it. 13438* Macro Details:: Limitations of Texinfo macros. 13439* alias:: Command aliases. 13440* definfoenclose:: Customized highlighting. 13441@end menu 13442 13443 13444@node Defining Macros 13445@section Defining Macros 13446@cindex Defining macros 13447@cindex Macro definitions 13448 13449@findex macro 13450You use the Texinfo @code{@@macro} command to define a macro, like this: 13451 13452@example 13453@@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@} 13454@var{text} @dots{} \@var{param1}\ @dots{} 13455@@end macro 13456@end example 13457 13458The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to 13459arguments supplied when the macro is subsequently used in the document 13460(described in the next section). 13461 13462@cindex Macro names, valid characters in 13463@cindex Names of macros, valid characters of 13464For a macro to work consistently with @TeX{}, @var{macroname} must 13465consist entirely of letters: no digits, hyphens, underscores, or other 13466special characters. So, we recommend using only letters. However, 13467@command{makeinfo} will accept anything except @samp{@{@}_^=}; 13468@samp{_} and @samp{^} are excluded so that macros can be called in 13469@code{@@math} mode without a following space 13470(@pxref{math,,@code{@@math}}). 13471 13472If a macro needs no parameters, you can define it either with an empty 13473list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro 13474foo}). 13475 13476@cindex Body of a macro 13477@cindex Mutually recursive macros 13478@cindex Recursion, mutual 13479The definition or @dfn{body} of the macro can contain most Texinfo 13480commands, including previously-defined macros. Not-yet-defined macro 13481invocations are not allowed; thus, it is not possible to have mutually 13482recursive Texinfo macros. Also, a macro definition that defines another 13483macro does not work in @TeX{} due to limitations in the design of 13484@code{@@macro}. 13485 13486@cindex Parameters to macros 13487In the macro body, instances of a parameter name surrounded by 13488backslashes, as in @samp{\@var{param1}\} in the example above, are 13489replaced by the corresponding argument from the macro invocation. You 13490can use parameter names any number of times in the body, including zero. 13491 13492@cindex Backslash in macros 13493To get a single @samp{\} in the macro expansion, use @samp{\\}. Any 13494other use of @samp{\} in the body yields a warning. 13495 13496@cindex Spaces in macros 13497@cindex Whitespace in macros 13498The newlines after the @code{@@macro} line and before the @code{@@end 13499macro} line are ignored, that is, not included in the macro body. All 13500other whitespace is treated according to the usual Texinfo rules. 13501 13502@cindex Recursive macro invocations 13503@findex rmacro 13504To allow a macro to be used recursively, that is, in an argument to a 13505call to itself, you must define it with @samp{@@rmacro}, like this: 13506 13507@example 13508@@rmacro rmac @{arg@} 13509a\arg\b 13510@@end rmacro 13511@dots{} 13512@@rmac@{1@@rmac@{text@}2@} 13513@end example 13514 13515This produces the output `a1atextb2b'. With @samp{@@macro} instead of 13516@samp{@@rmacro}, an error message is given. 13517 13518@findex unmacro 13519@cindex Macros, undefining 13520@cindex Undefining macros 13521You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}. 13522It is not an error to undefine a macro that is already undefined. 13523For example: 13524 13525@example 13526@@unmacro foo 13527@end example 13528 13529 13530@node Invoking Macros 13531@section Invoking Macros 13532@cindex Invoking macros 13533@cindex Expanding macros 13534@cindex Running macros 13535@cindex Macro invocation 13536 13537After a macro is defined (see the previous section), you can use 13538(@dfn{invoke}) it in your document like this: 13539 13540@example 13541@@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@} 13542@end example 13543 13544@noindent and the result will be just as if you typed the body of 13545@var{macroname} at that spot. For example: 13546 13547@example 13548@@macro foo @{p, q@} 13549Together: \p\ & \q\. 13550@@end macro 13551@@foo@{a, b@} 13552@end example 13553 13554@noindent produces: 13555 13556@display 13557Together: a & b. 13558@end display 13559 13560@cindex Backslash, and macros 13561Thus, the arguments and parameters are separated by commas and delimited 13562by braces; any whitespace after (but not before) a comma is ignored. 13563The braces are required in the invocation (but not the definition), even 13564when the macro takes no arguments, consistent with all other Texinfo 13565commands. For example: 13566 13567@example 13568@@macro argless @{@} 13569No arguments here. 13570@@end macro 13571@@argless@{@} 13572@end example 13573 13574@noindent produces: 13575 13576@display 13577No arguments here. 13578@end display 13579 13580@cindex Comma, in macro arguments 13581@cindex Braces, in macro arguments 13582To insert a comma, brace, or backslash in an argument, prepend a 13583backslash, as in 13584 13585@example 13586@@@var{macname} @{\\\@{\@}\,@} 13587@end example 13588 13589@noindent 13590which will pass the (almost certainly error-producing) argument 13591@samp{\@{@},} to @var{macname}. However, commas in parameters, even 13592if escaped by a backslash, might cause trouble in @TeX{}. 13593 13594If the macro is defined to take a single argument, and is invoked 13595without any braces, the entire rest of the line after the macro name is 13596supplied as the argument. For example: 13597 13598@example 13599@@macro bar @{p@} 13600Twice: \p\ & \p\. 13601@@end macro 13602@@bar aah 13603@end example 13604 13605@noindent produces: 13606 13607@c Sorry for cheating, but let's not require macros to process the manual. 13608@display 13609Twice: aah & aah. 13610@end display 13611 13612If the macro is defined to take a single argument, and is invoked with 13613braces, the braced text is passed as the argument, regardless of 13614commas. For example: 13615 13616@example 13617@@macro bar @{p@} 13618Twice: \p\ & \p\. 13619@@end macro 13620@@bar@{a,b@} 13621@end example 13622 13623@noindent produces: 13624 13625@display 13626Twice: a,b & a,b. 13627@end display 13628 13629 13630@node Macro Details 13631@section Macro Details and Caveats 13632@cindex Macro details 13633@cindex Details of macro usage 13634@cindex Caveats for macro usage 13635 13636Due to unavoidable limitations, certain macro-related constructs cause 13637problems with @TeX{}. If you get macro-related errors when producing 13638the printed version of a manual, try expanding the macros with 13639@command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E} 13640option (@pxref{Format with texi2dvi}). 13641 13642@itemize @bullet 13643@item 13644As mentioned earlier, macro names must consist entirely of letters. 13645 13646@item 13647It is not advisable to redefine any @TeX{} primitive, plain, or 13648Texinfo command name as a macro. Unfortunately this is a very large 13649set of names, and the possible resulting errors are unpredictable. 13650 13651@item 13652All macros are expanded inside at least one @TeX{} group. This means 13653that @code{@@set} and other such commands have no effect inside a 13654macro. 13655 13656@item 13657Commas in macro arguments, even if escaped by a backslash, don't 13658always work. 13659 13660@item 13661Macro arguments cannot cross lines. 13662 13663@item 13664It is (usually) best to avoid comments inside macro definitions, but 13665see the next item. 13666 13667@item 13668Macros containing a command which must be on a line by itself, such as 13669a conditional, cannot be invoked in the middle of a line. In general, 13670the interaction of newlines in the macro definitions and invocations 13671depends on the precise commands and context. You may be able to work 13672around some problems with judicious use of @code{@@c}. Suppose you 13673define a macro that is always intended to be used on a line by itself: 13674 13675@example 13676@@macro linemac 13677@@cindex whatever 13678@@c 13679@@end macro 13680... 13681foo 13682@@linemac 13683bar 13684@end example 13685 13686Without the @code{@@c}, there will be an unwanted blank line between 13687the @samp{@@cindex whatever} and the @samp{bar} (one newline comes 13688from the macro definition, one from after the invocation), causing a 13689paragraph break. 13690 13691On the other hand, you wouldn't want the @code{@@c} if the macro was 13692sometimes invoked in the middle of a line (the text after the 13693invocation would be treated as a comment). 13694 13695@item 13696In general, you can't arbitrarily substitute a macro call for Texinfo 13697command arguments, even when the text is the same. It might work with 13698some commands, it fails with others. Best not to do it at all. For 13699instance, this fails: 13700 13701@example 13702@@macro offmacro 13703off 13704@@end macro 13705@@headings @@offmacro 13706@end example 13707 13708@noindent 13709You would expect this to be equivalent to @code{@@headings off}, but 13710for @TeX{}nical reasons, it fails with a mysterious error message 13711(@code{Paragraph ended before @@headings was complete}). 13712 13713@item 13714Macros cannot define macros in the natural way. To do this, you must 13715use conditionals and raw @TeX{}. For example: 13716 13717@example 13718@@ifnottex 13719@@macro ctor @{name, arg@} 13720@@macro \name\ 13721something involving \arg\ somehow 13722@@end macro 13723@@end macro 13724@@end ifnottex 13725@@tex 13726\gdef\ctor#1@{\ctorx#1,@} 13727\gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@} 13728@@end tex 13729@end example 13730 13731@end itemize 13732 13733The @command{makeinfo} implementation also has limitations: 13734 13735@itemize 13736@item 13737@code{@@verbatim} and macros do not mix; for instance, you can't start 13738a verbatim block inside a macro and end it outside. 13739(@xref{verbatim}.) Starting any environment inside a macro and ending 13740it outside may or may not work, for that matter. 13741 13742@item 13743Macros that completely define macros are ok, but it's not possible to 13744have incorrectly nested macro definitions. That is, @code{@@macro} 13745and @code{@@end macro} (likewise for @code{@@rmacro}) must be 13746correctly paired. For example, you cannot start a macro definition 13747within a macro, and then end the nested definition outside the macro. 13748 13749@item 13750@code{@@rmacro} is a kludge. 13751 13752@end itemize 13753 13754One more limitation is common to both implementations: white space is 13755ignored at the beginnings of lines. 13756 13757Future major revisions of Texinfo may ease some of these limitations 13758(by introducing a new macro syntax). 13759 13760 13761@node alias 13762@section @samp{@@alias @var{new}=@var{existing}} 13763@cindex Aliases, command 13764@cindex Command aliases 13765@findex alias 13766 13767The @samp{@@alias} command defines a new command to be just like an 13768existing one. This is useful for defining additional markup names, thus 13769preserving semantic information in the input even though the output 13770result may be the same. 13771 13772Write the @samp{@@alias} command on a line by itself, followed by the 13773new command name, an equals sign, and the existing command name. 13774Whitespace around the equals sign is ignored. Thus: 13775@example 13776@@alias @var{new} = @var{existing} 13777@end example 13778 13779For example, if your document contains citations for both books and 13780some other media (movies, for example), you might like to define a 13781macro @code{@@moviecite@{@}} that does the same thing as an ordinary 13782@code{@@cite@{@}} but conveys the extra semantic information as well. 13783You'd do this as follows: 13784 13785@example 13786@@alias moviecite = cite 13787@end example 13788 13789Macros do not always have the same effect as aliases, due to vagaries 13790of argument parsing. Also, aliases are much simpler to define than 13791macros. So the command is not redundant. (It was also heavily used 13792in the Jargon File!) 13793 13794Aliases must not be recursive, directly or indirectly. 13795 13796It is not advisable to redefine any @TeX{} primitive, plain, or 13797Texinfo command name as an alias. Unfortunately this is a very large 13798set of names, and the possible resulting errors are completely random. 13799 13800 13801@node definfoenclose 13802@section @samp{definfoenclose}: Customized Highlighting 13803@cindex Highlighting, customized 13804@cindex Customized highlighting 13805@findex definfoenclose 13806 13807A @code{@@definfoenclose} command may be used to define a highlighting 13808command for Info, but not for @TeX{}. A command defined using 13809@code{@@definfoenclose} marks text by enclosing it in strings that 13810precede and follow the text. You can use this to get closer control of 13811your Info output. 13812 13813Presumably, if you define a command with @code{@@definfoenclose} for Info, 13814you will create a corresponding command for @TeX{}, either in 13815@file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in 13816your document. 13817 13818Write a @code{@@definfoenclose} command on a line and follow it with 13819three arguments separated by commas. The first argument to 13820@code{@@definfoenclose} is the @@-command name (without the @code{@@}); 13821the second argument is the Info start delimiter string; and the third 13822argument is the Info end delimiter string. The latter two arguments 13823enclose the highlighted text in the Info file. A delimiter string may 13824contain spaces. Neither the start nor end delimiter is required. If 13825you do not want a start delimiter but do want an end delimiter, you must 13826follow the command name with two commas in a row; otherwise, the Info 13827formatting commands will naturally misinterpret the end delimiter string 13828you intended as the start delimiter string. 13829 13830If you do a @code{@@definfoenclose} on the name of a pre-defined macro 13831(such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the 13832enclosure definition will override the built-in definition. 13833 13834An enclosure command defined this way takes one argument in braces; this 13835is intended for new markup commands (@pxref{Marking Text}). 13836 13837@findex phoo 13838For example, you can write: 13839 13840@example 13841@@definfoenclose phoo,//,\\ 13842@end example 13843 13844@noindent 13845near the beginning of a Texinfo file to define @code{@@phoo} as an Info 13846formatting command that inserts `//' before and `\\' after the argument 13847to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you 13848want `//bar\\' highlighted in Info. 13849 13850Also, for @TeX{} formatting, you could write 13851 13852@example 13853@@iftex 13854@@global@@let@@phoo=@@i 13855@@end iftex 13856@end example 13857 13858@noindent 13859to define @code{@@phoo} as a command that causes @TeX{} to typeset the 13860argument to @code{@@phoo} in italics. 13861 13862Each definition applies to its own formatter: one for @TeX{}, the other 13863for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The 13864@code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but 13865the raw @TeX{} commands do need to be in @samp{@@iftex}. 13866 13867@findex headword 13868Here is another example: write 13869 13870@example 13871@@definfoenclose headword, , : 13872@end example 13873 13874@noindent 13875near the beginning of the file, to define @code{@@headword} as an Info 13876formatting command that inserts nothing before and a colon after the 13877argument to @code{@@headword}. 13878 13879@samp{@@definfoenclose} definitions must not be recursive, directly or 13880indirectly. 13881 13882 13883@node Hardcopy 13884@chapter Formatting and Printing Hardcopy 13885@cindex Format and print hardcopy 13886@cindex Printing hardcopy 13887@cindex Hardcopy, printing it 13888@cindex Making a printed manual 13889@cindex Sorting indices 13890@cindex Indices, sorting 13891@cindex @TeX{} index sorting 13892@pindex texindex 13893 13894There are three major shell commands for making a printed manual from a 13895Texinfo file: one for converting the Texinfo file into a file that will be 13896printed, a second for sorting indices, and a third for printing the 13897formatted document. When you use the shell commands, you can either 13898work directly in the operating system shell or work within a shell 13899inside GNU Emacs. 13900 13901If you are using GNU Emacs, you can use commands provided by Texinfo 13902mode instead of shell commands. In addition to the three commands to 13903format a file, sort the indices, and print the result, Texinfo mode 13904offers key bindings for commands to recenter the output buffer, show the 13905print queue, and delete a job from the print queue. 13906 13907@menu 13908* Use TeX:: Use @TeX{} to format for hardcopy. 13909* Format with tex/texindex:: How to format with explicit shell commands. 13910* Format with texi2dvi:: A simpler way to format. 13911* Print with lpr:: How to print. 13912* Within Emacs:: How to format and print from an Emacs shell. 13913* Texinfo Mode Printing:: How to format and print in Texinfo mode. 13914* Compile-Command:: How to print using Emacs's compile command. 13915* Requirements Summary:: @TeX{} formatting requirements summary. 13916* Preparing for TeX:: What to do before you use @TeX{}. 13917* Overfull hboxes:: What are and what to do with overfull hboxes. 13918* smallbook:: How to print small format books and manuals. 13919* A4 Paper:: How to print on A4 or A5 paper. 13920* pagesizes:: How to print with customized page sizes. 13921* Cropmarks and Magnification:: How to print marks to indicate the size 13922 of pages and how to print scaled up output. 13923* PDF Output:: Portable Document Format output. 13924* Obtaining TeX:: How to Obtain @TeX{}. 13925@end menu 13926 13927@node Use TeX 13928@section Use @TeX{} 13929 13930The typesetting program called @TeX{} is used for formatting a Texinfo 13931file. @TeX{} is a very powerful typesetting program and, if used correctly, 13932does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain 13933@TeX{}}, for information on how to obtain @TeX{}.) 13934 13935The standalone @code{makeinfo} program and Emacs functions 13936@code{texinfo-format-region} and @code{texinfo-format-buffer} commands 13937read the very same @@-commands in the Texinfo file as does @TeX{}, but 13938process them differently to make an Info file (@pxref{Creating an Info 13939File}). 13940 13941 13942@node Format with tex/texindex 13943@section Format with @code{tex} and @code{texindex} 13944@cindex Shell formatting with @code{tex} and @code{texindex} 13945@cindex Formatting with @code{tex} and @code{texindex} 13946@cindex DVI file 13947 13948You can format the Texinfo file with the shell command @code{tex} 13949followed by the name of the Texinfo file. For example: 13950 13951@example 13952tex foo.texi 13953@end example 13954 13955@noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary 13956files containing information for indices, cross references, etc. The 13957DVI file (for @dfn{DeVice Independent} file) can be printed on virtually 13958any device (see the following sections). 13959 13960@pindex texindex 13961The @code{tex} formatting command itself does not sort the indices; it 13962writes an output file of unsorted index data. To generate a printed 13963index after running the @command{tex} command, you first need a sorted 13964index to work from. The @command{texindex} command sorts indices. 13965(The source file @file{texindex.c} comes as part of the standard 13966Texinfo distribution, among other places.) (@command{texi2dvi} runs 13967@command{tex} and @command{texindex} as necessary.) 13968 13969@cindex Names of index files 13970@cindex Index file names 13971The @code{tex} formatting command outputs unsorted index files under 13972names that obey a standard convention: the name of your main input file 13973with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c, 13974Web2c}) extension removed, followed by the two letter names of indices. 13975For example, the raw index output files for the input file 13976@file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn}, 13977@file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the 13978arguments to give to @code{texindex}. 13979 13980@need 1000 13981@cindex Wildcards 13982@cindex Globbing 13983Instead of specifying all the unsorted index file names explicitly, you 13984can use @samp{??} as shell wildcards and give the command in this 13985form: 13986 13987@example 13988texindex foo.?? 13989@end example 13990 13991@noindent 13992This command will run @code{texindex} on all the unsorted index files, 13993including any that you have defined yourself using @code{@@defindex} 13994or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??} 13995even if there are similarly named files with two letter extensions 13996that are not index files, such as @samp{foo.el}. The @code{texindex} 13997command reports but otherwise ignores such files.) 13998 13999For each file specified, @code{texindex} generates a sorted index file 14000whose name is made by appending @samp{s} to the input file name. The 14001@code{@@printindex} command looks for a file with that name 14002(@pxref{Printing Indices & Menus}). @code{texindex} does not alter the 14003raw index output file. 14004 14005After you have sorted the indices, you need to rerun @code{tex} on the 14006Texinfo file. This regenerates the DVI file, this time with 14007up-to-date index entries. 14008 14009Finally, you may need to run @code{tex} one more time, to get the page 14010numbers in the cross-references correct. 14011 14012To summarize, this is a five step process: 14013 14014@enumerate 14015@item 14016Run @code{tex} on your Texinfo file. This generates a DVI file (with 14017undefined cross-references and no indices), and the raw index files 14018(with two letter extensions). 14019 14020@item 14021Run @code{texindex} on the raw index files. This creates the 14022corresponding sorted index files (with three letter extensions). 14023 14024@item 14025Run @code{tex} again on your Texinfo file. This regenerates the DVI 14026file, this time with indices and defined cross-references, but with page 14027numbers for the cross-references from last time, generally incorrect. 14028 14029@item 14030Sort the indices again, with @code{texindex}. 14031 14032@item 14033Run @code{tex} one last time. This time the correct page numbers are 14034written for the cross-references. 14035@end enumerate 14036 14037@pindex texi2dvi 14038Alternatively, it's a one-step process: run @code{texi2dvi} 14039(@pxref{Format with texi2dvi}). 14040 14041You need not run @code{texindex} each time after you run @code{tex}. If 14042you do not, on the next run, the @code{tex} formatting command will use 14043whatever sorted index files happen to exist from the previous use of 14044@code{texindex}. This is usually ok while you are debugging. 14045 14046@cindex Auxiliary files, avoiding 14047@findex novalidate 14048@cindex Pointer validation, suppressing 14049@cindex Chapters, formatting one at a time 14050Sometimes you may wish to print a document while you know it is 14051incomplete, or to print just one chapter of a document. In that case, 14052the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives 14053when cross-references are not satisfied are just nuisances. You can 14054avoid them with the @code{@@novalidate} command, which you must give 14055@emph{before} the @code{@@setfilename} command 14056(@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of 14057your file would look approximately like this: 14058 14059@example 14060\input texinfo 14061@@novalidate 14062@@setfilename myfile.info 14063@dots{} 14064@end example 14065 14066@noindent @code{@@novalidate} also turns off validation in 14067@code{makeinfo}, just like its @code{--no-validate} option 14068(@pxref{Pointer Validation}). 14069 14070 14071@node Format with texi2dvi 14072@section Format with @code{texi2dvi} 14073@pindex texi2dvi @r{(shell script)} 14074 14075The @code{texi2dvi} command automatically runs both @TeX{} and 14076@command{texindex} as many times as necessary to produce a DVI file 14077with sorted indices and all cross-references resolved. It is 14078therefore simpler than manually executing the 14079@code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence 14080described in the previous section. 14081 14082To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where 14083@samp{prompt$ } is your shell prompt): 14084 14085@example 14086prompt$ @kbd{texi2dvi foo.texi} 14087@end example 14088 14089As shown in this example, the input filenames to @code{texi2dvi} must 14090include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under 14091MS-DOS and perhaps in other circumstances, you may need to run @samp{sh 14092texi2dvi foo.texi} instead of relying on the operating system to invoke 14093the shell on the @samp{texi2dvi} script. 14094 14095Perhaps the most useful option to @code{texi2dvi} is 14096@samp{--command=@var{cmd}}. This inserts @var{cmd} on a line by itself 14097after the @code{@@setfilename} in a temporary copy of the input file 14098before running @TeX{}. With this, you can specify different printing 14099formats, such as @code{@@smallbook} (@pxref{smallbook}), 14100@code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes} 14101(@pxref{pagesizes}), without actually changing the document source. 14102(You can also do this on a site-wide basis with @file{texinfo.cnf}; 14103@pxref{Preparing for TeX,,Preparing for @TeX{}}). 14104 14105With the @option{--pdf} option, @command{texi2dvi} produces PDF output 14106instead of DVI (@pxref{PDF Output}), by running @command{pdftex} 14107instead of @command{tex}. Alternatively, the command 14108@command{texi2pdf} is an abbreviation for running @samp{texi2dvi --pdf}. 14109 14110@cindex @LaTeX{}, processing with @command{texi2dvi} 14111@command{texi2dvi} can also be used to process @LaTeX{} files; simply 14112run @samp{texi2dvi filename.ext}. 14113 14114@command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if 14115they are available; these extended versions of @TeX{} are not 14116required, and the DVI (or PDF) output is identical, but they simplify 14117the @TeX{} programming in some cases, and provide additional tracing 14118information when debugging @file{texinfo.tex}. 14119 14120For a list of other options, run @samp{texi2dvi --help}. 14121 14122 14123@node Print with lpr 14124@section Shell Print Using @code{lpr -d} 14125@pindex lpr @r{(DVI print command)} 14126 14127The precise command to print a DVI file depends on your system 14128installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr 14129-d foo.dvi}. 14130 14131For example, the following commands will (perhaps) suffice to sort the 14132indices, format, and print the @cite{Bison Manual}: 14133 14134@example 14135@group 14136tex bison.texinfo 14137texindex bison.?? 14138tex bison.texinfo 14139lpr -d bison.dvi 14140@end group 14141@end example 14142 14143@noindent 14144(Remember that the shell commands may be different at your site; but 14145these are commonly used versions.) 14146 14147Using the @code{texi2dvi} shell script (see the previous section): 14148 14149@example 14150@group 14151texi2dvi bison.texinfo 14152lpr -d bison.dvi 14153# or perhaps dvips bison.dvi -o 14154@end group 14155@end example 14156 14157@cindex Shell printing, on MS-DOS/MS-Windows 14158@cindex Printing DVI files, on MS-DOS/MS-Windows 14159@pindex lpr@r{-d, replacements on MS-DOS/MS-Windows} 14160@code{lpr} is a standard program on Unix systems, but it is usually 14161absent on MS-DOS/MS-Windows. Some network packages come with a 14162program named @code{lpr}, but these are usually limited to sending files 14163to a print server over the network, and generally don't support the 14164@samp{-d} option. If you are unfortunate enough to work on one of these 14165systems, you have several alternative ways of printing DVI files: 14166 14167@itemize @bullet{} 14168@item Find and install a Unix-like @code{lpr} program, or its clone. 14169If you can do that, you will be able to print DVI files just like 14170described above. 14171 14172@item Send the DVI files to a network printer queue for DVI files. 14173Some network printers have special queues for printing DVI files. You 14174should be able to set up your network software to send files to that 14175queue. In some cases, the version of @code{lpr} which comes with your 14176network software will have a special option to send a file to specific 14177queues, like this: 14178 14179@example 14180lpr -Qdvi -hprint.server.domain bison.dvi 14181@end example 14182 14183@item Convert the DVI file to a Postscript or PCL file and send it to your 14184local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man 14185pages for @code{dvilj}, for detailed description of these tools. Once 14186the DVI file is converted to the format your local printer understands 14187directly, just send it to the appropriate port, usually @samp{PRN}. 14188@end itemize 14189 14190 14191@node Within Emacs 14192@section From an Emacs Shell 14193@cindex Print, format from Emacs shell 14194@cindex Format, print from Emacs shell 14195@cindex Shell, format, print from 14196@cindex Emacs shell, format, print from 14197@cindex GNU Emacs shell, format, print from 14198 14199You can give formatting and printing commands from a shell within GNU 14200Emacs. To create a shell within Emacs, type @kbd{M-x shell}. In this 14201shell, you can format and print the document. @xref{Hardcopy, , Format 14202and Print Hardcopy}, for details. 14203 14204You can switch to and from the shell buffer while @code{tex} is 14205running and do other editing. If you are formatting a long document 14206on a slow machine, this can be very convenient.@refill 14207 14208You can also use @code{texi2dvi} from an Emacs shell. For example, 14209here is how to use @code{texi2dvi} to format and print @cite{Using and 14210Porting GNU CC} from a shell within Emacs: 14211 14212@example 14213@group 14214texi2dvi gcc.texinfo 14215lpr -d gcc.dvi 14216@end group 14217@end example 14218 14219See the next section for more information about formatting 14220and printing in Texinfo mode. 14221 14222 14223@node Texinfo Mode Printing 14224@section Formatting and Printing in Texinfo Mode 14225@cindex Region printing in Texinfo mode 14226@cindex Format and print in Texinfo mode 14227@cindex Print and format in Texinfo mode 14228 14229Texinfo mode provides several predefined key commands for @TeX{} 14230formatting and printing. These include commands for sorting indices, 14231looking at the printer queue, killing the formatting job, and 14232recentering the display of the buffer in which the operations 14233occur.@refill 14234 14235@table @kbd 14236@item C-c C-t C-b 14237@itemx M-x texinfo-tex-buffer 14238Run @code{texi2dvi} on the current buffer.@refill 14239 14240@item C-c C-t C-r 14241@itemx M-x texinfo-tex-region 14242Run @TeX{} on the current region.@refill 14243 14244@item C-c C-t C-i 14245@itemx M-x texinfo-texindex 14246Sort the indices of a Texinfo file formatted with 14247@code{texinfo-tex-region}.@refill 14248 14249@item C-c C-t C-p 14250@itemx M-x texinfo-tex-print 14251Print a DVI file that was made with @code{texinfo-tex-region} or 14252@code{texinfo-tex-buffer}.@refill 14253 14254@item C-c C-t C-q 14255@itemx M-x tex-show-print-queue 14256Show the print queue.@refill 14257 14258@item C-c C-t C-d 14259@itemx M-x texinfo-delete-from-print-queue 14260Delete a job from the print queue; you will be prompted for the job 14261number shown by a preceding @kbd{C-c C-t C-q} command 14262(@code{texinfo-show-tex-print-queue}).@refill 14263 14264@item C-c C-t C-k 14265@itemx M-x tex-kill-job 14266Kill the currently running @TeX{} job started by either 14267@code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other 14268process running in the Texinfo shell buffer.@refill 14269 14270@item C-c C-t C-x 14271@itemx M-x texinfo-quit-job 14272Quit a @TeX{} formatting job that has stopped because of an error by 14273sending an @key{x} to it. When you do this, @TeX{} preserves a record 14274of what it did in a @file{.log} file.@refill 14275 14276@item C-c C-t C-l 14277@itemx M-x tex-recenter-output-buffer 14278Redisplay the shell buffer in which the @TeX{} printing and formatting 14279commands are run to show its most recent output.@refill 14280@end table 14281 14282@need 1000 14283Thus, the usual sequence of commands for formatting a buffer is as 14284follows (with comments to the right):@refill 14285 14286@example 14287@group 14288C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.} 14289C-c C-t C-p @r{Print the DVI file.} 14290C-c C-t C-q @r{Display the printer queue.} 14291@end group 14292@end example 14293 14294The Texinfo mode @TeX{} formatting commands start a subshell in Emacs 14295called the @file{*tex-shell*}. The @code{texinfo-tex-command}, 14296@code{texinfo-texindex-command}, and @code{tex-dvi-print-command} 14297commands are all run in this shell. 14298 14299You can watch the commands operate in the @samp{*tex-shell*} buffer, 14300and you can switch to and from and use the @samp{*tex-shell*} buffer 14301as you would any other shell buffer.@refill 14302 14303@need 1500 14304The formatting and print commands depend on the values of several variables. 14305The default values are:@refill 14306 14307@example 14308@group 14309 @r{Variable} @r{Default value} 14310 14311texinfo-texi2dvi-command "texi2dvi" 14312texinfo-tex-command "tex" 14313texinfo-texindex-command "texindex" 14314texinfo-delete-from-print-queue-command "lprm" 14315texinfo-tex-trailer "@@bye" 14316tex-start-of-header "%**start" 14317tex-end-of-header "%**end" 14318tex-dvi-print-command "lpr -d" 14319tex-show-queue-command "lpq" 14320@end group 14321@end example 14322 14323You can change the values of these variables with the @kbd{M-x 14324set-variable} command (@pxref{Examining, , Examining and Setting 14325Variables, emacs, The GNU Emacs Manual}), or with your @file{.emacs} 14326initialization file (@pxref{Init File, , , emacs, The GNU Emacs 14327Manual}). 14328 14329@cindex Customize Emacs package (@t{Development/Docs/Texinfo}) 14330Beginning with version 20, GNU Emacs offers a user-friendly interface, 14331called @dfn{Customize}, for changing values of user-definable variables. 14332@xref{Easy Customization, , Easy Customization Interface, emacs, The GNU 14333Emacs Manual}, for more details about this. The Texinfo variables can 14334be found in the @samp{Development/Docs/Texinfo} group, once you invoke 14335the @kbd{M-x customize} command. 14336 14337 14338@node Compile-Command 14339@section Using the Local Variables List 14340@cindex Local variables 14341@cindex Compile command for formatting 14342@cindex Format with the compile command 14343 14344Yet another way to apply the @TeX{} formatting command to a Texinfo file 14345is to put that command in a @dfn{local variables list} at the end of the 14346Texinfo file. You can then specify the @code{tex} or @code{texi2dvi} 14347commands as a @code{compile-command} and have Emacs run it by typing 14348@kbd{M-x compile}. This creates a special shell called the 14349@file{*compilation*} buffer in which Emacs runs the compile command. 14350For example, at the end of the @file{gdb.texinfo} file, after the 14351@code{@@bye}, you could put the following:@refill 14352 14353@example 14354@group 14355Local Variables: 14356compile-command: "texi2dvi gdb.texinfo" 14357End: 14358@end group 14359@end example 14360 14361@noindent 14362This technique is most often used by programmers who also compile programs 14363this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill 14364 14365 14366@node Requirements Summary 14367@section @TeX{} Formatting Requirements Summary 14368@cindex Requirements for formatting 14369@cindex Minimal requirements for formatting 14370@cindex Formatting requirements 14371 14372Every Texinfo file that is to be input to @TeX{} must begin with a 14373@code{\input} command and must contain an @code{@@setfilename} command: 14374 14375@example 14376\input texinfo 14377@@setfilename @var{arg-not-used-by-@TeX{}} 14378@end example 14379 14380@noindent 14381The first command instructs @TeX{} to load the macros it needs to 14382process a Texinfo file and the second command opens auxiliary files. 14383 14384Every Texinfo file must end with a line that terminates @TeX{}'s 14385processing and forces out unfinished pages: 14386 14387@example 14388@@bye 14389@end example 14390 14391Strictly speaking, these lines are all a Texinfo file needs to be 14392processed successfully by @TeX{}. 14393 14394Usually, however, the beginning includes an @code{@@settitle} command to 14395define the title of the printed manual, an @code{@@setchapternewpage} 14396command, a title page, a copyright page, and permissions. Besides an 14397@code{@@bye}, the end of a file usually includes indices and a table of 14398contents. (And of course most manuals contain a body of text as well.) 14399 14400For more information, see: 14401 14402@itemize @bullet 14403@item @ref{settitle, , @code{@@settitle}}. 14404@item @ref{setchapternewpage, , @code{@@setchapternewpage}}. 14405@item @ref{Headings, ,Page Headings}. 14406@item @ref{Titlepage & Copyright Page}. 14407@item @ref{Printing Indices & Menus}. 14408@item @ref{Contents}. 14409@end itemize 14410 14411 14412@node Preparing for TeX 14413@section Preparing for @TeX{} 14414@cindex Preparing for @TeX{} 14415@cindex @TeX{} input initialization 14416@cindex @b{.profile} initialization file 14417@cindex @b{.cshrc} initialization file 14418@cindex Initialization file for @TeX{} input 14419 14420@TeX{} needs to know where to find the @file{texinfo.tex} file that the 14421@samp{\input texinfo} command on the first line reads. The 14422@file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is 14423included in all standard GNU distributions. The latest version is 14424always available from the Texinfo source repository: 14425@smalldisplay 14426@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD} 14427@end smalldisplay 14428 14429@pindex texinfo.tex@r{, installing} 14430 14431Usually, the installer has put the @file{texinfo.tex} file in the 14432default directory that contains @TeX{} macros when GNU Texinfo, Emacs or 14433other GNU software is installed. In this case, @TeX{} will find the 14434file and you do not need to do anything special. If this has not been 14435done, you can put @file{texinfo.tex} in the current directory when you 14436run @TeX{}, and @TeX{} will find it there. 14437 14438@pindex epsf.tex@r{, installing} 14439Also, you should install @file{epsf.tex}, if it is not already installed 14440from another distribution. More details are at the end of the description 14441of the @code{@@image} command (@pxref{Images}). 14442 14443@pindex pdfcolor.tex@r{, installing} 14444Likewise for @file{pdfcolor.tex}, if it is not already installed and you 14445use pdftex. 14446 14447@pindex texinfo.cnf @r{installation} 14448@cindex Customizing of @TeX{} for Texinfo 14449@cindex Site-wide Texinfo configuration file 14450Optionally, you may create an additional @file{texinfo.cnf}, and install 14451it as well. This file is read by @TeX{} when the @code{@@setfilename} 14452command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any 14453commands you like there, according to local site-wide conventions. They 14454will be read by @TeX{} when processing any Texinfo document. For 14455example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper} 14456(@pxref{A4 Paper}), then all Texinfo documents will be processed with 14457that page size in effect. If you have nothing to put in 14458@file{texinfo.cnf}, you do not need to create it. 14459 14460@cindex Environment variable @code{TEXINPUTS} 14461@vindex TEXINPUTS 14462If neither of the above locations for these system files suffice for 14463you, you can specify the directories explicitly. For 14464@file{texinfo.tex}, you can do this by writing the complete path for the 14465file after the @code{\input} command. Another way, that works for both 14466@file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{} 14467might read), is to set the @code{TEXINPUTS} environment variable in your 14468@file{.cshrc} or @file{.profile} file. 14469 14470Which you use of @file{.cshrc} or @file{.profile} depends on 14471whether you use a Bourne shell-compatible (@code{sh}, @code{bash}, 14472@code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh}) 14473command interpreter. The latter read the @file{.cshrc} file for 14474initialization information, and the former read @file{.profile}. 14475 14476In a @file{.cshrc} file, you could use the following @code{csh} command 14477sequence: 14478 14479@example 14480setenv TEXINPUTS .:/home/me/mylib: 14481@end example 14482 14483@need 1000 14484In a @file{.profile} file, you could use the following @code{sh} command 14485sequence: 14486 14487@example 14488@group 14489TEXINPUTS=.:/home/me/mylib: 14490export TEXINPUTS 14491@end group 14492@end example 14493 14494On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use 14495of the @samp{;} character, instead of @samp{:}, as directory separator 14496on these systems.}: 14497 14498@example 14499@group 14500set TEXINPUTS=.;d:/home/me/mylib;c: 14501@end group 14502@end example 14503 14504@noindent 14505It is customary for DOS/Windows users to put such commands in the 14506@file{autoexec.bat} file, or in the Windows Registry. 14507 14508@noindent 14509These settings would cause @TeX{} to look for @file{\input} file first 14510in the current directory, indicated by the @samp{.}, then in a 14511hypothetical user @samp{me}'s @file{mylib} directory, and finally in 14512the system directories. (A leading, trailing, or doubled @samp{:} 14513indicates searching the system directories at that point.) 14514 14515@cindex Dumping a .fmt file 14516@cindex Format file, dumping 14517Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,, 14518web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The 14519disadvantage is that then updating @file{texinfo.tex} requires 14520redumping.) You can do this by running this command, assuming 14521@file{epsf.tex} is findable by @TeX{}: 14522 14523@example 14524initex texinfo @@dump 14525@end example 14526 14527(@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to 14528wherever your @code{.fmt} files are found; typically, this will be in the 14529subdirectory @file{web2c} of your @TeX{} installation. 14530 14531 14532@node Overfull hboxes 14533@section Overfull ``hboxes'' 14534@cindex Overfull @samp{hboxes} 14535@cindex @samp{hboxes}, overfull 14536@cindex Final output 14537 14538@TeX{} is sometimes unable to typeset a line without extending it into 14539the right margin. This can occur when @TeX{} comes upon what it 14540interprets as a long word that it cannot hyphenate, such as an 14541electronic mail network address or a very long title. When this 14542happens, @TeX{} prints an error message like this: 14543 14544@example 14545Overfull @@hbox (20.76302pt too wide) 14546@end example 14547 14548@findex hbox 14549@noindent 14550(In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''. 14551@samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.) 14552 14553@TeX{} also provides the line number in the Texinfo source file and 14554the text of the offending line, which is marked at all the places that 14555@TeX{} considered hyphenation. 14556@xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting}, 14557for more information about typesetting errors. 14558 14559If the Texinfo file has an overfull hbox, you can rewrite the sentence 14560so the overfull hbox does not occur, or you can decide to leave it. A 14561small excursion into the right margin often does not matter and may not 14562even be noticeable. 14563 14564If you have many overfull boxes and/or an antipathy to rewriting, you 14565can coerce @TeX{} into greatly increasing the allowable interword 14566spacing, thus (if you're lucky) avoiding many of the bad line breaks, 14567like this: 14568 14569@findex \emergencystretch 14570@example 14571@@tex 14572\global\emergencystretch = .9\hsize 14573@@end tex 14574@end example 14575 14576@noindent 14577(You should adjust the fraction as needed.) This huge value for 14578@code{\emergencystretch} cannot be the default, since then the typeset 14579output would generally be of noticeably lower quality; the default 14580is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension 14581containing the current line width. 14582 14583@cindex Black rectangle in hardcopy 14584@cindex Rectangle, black in hardcopy 14585@cindex Box, ugly black in hardcopy 14586@cindex Ugly black rectangles in hardcopy 14587For what overfull boxes you have, however, @TeX{} will print a large, 14588ugly, black rectangle beside the line that contains the overfull hbox 14589unless told otherwise. This is so you will notice the location of the 14590problem if you are correcting a draft. 14591 14592@findex finalout 14593To prevent such a monstrosity from marring your final printout, write 14594the following in the beginning of the Texinfo file on a line of its own, 14595before the @code{@@titlepage} command: 14596 14597@example 14598@@finalout 14599@end example 14600 14601 14602@node smallbook 14603@section Printing ``Small'' Books 14604@findex smallbook 14605@cindex Small book size 14606@cindex Book, printing small 14607@cindex Page sizes for books 14608@cindex Size of printed book 14609 14610By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch 14611format. However, you can direct @TeX{} to typeset a document in a 7 by 146129.25 inch format that is suitable for bound books by inserting the 14613following command on a line by itself at the beginning of the Texinfo 14614file, before the title page:@refill 14615 14616@example 14617@@smallbook 14618@end example 14619 14620@noindent 14621(Since many books are about 7 by 9.25 inches, this command might better 14622have been called the @code{@@regularbooksize} command, but it came to be 14623called the @code{@@smallbook} command by comparison to the 8.5 by 11 14624inch format.) 14625 14626If you write the @code{@@smallbook} command between the 14627start-of-header and end-of-header lines, the Texinfo mode @TeX{} 14628region formatting command, @code{texinfo-tex-region}, will format the 14629region in ``small'' book size (@pxref{Start of Header}).@refill 14630 14631@xref{small}, for information about 14632commands that make it easier to produce examples for a smaller manual. 14633 14634@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for 14635@TeX{}}, for other ways to format with @code{@@smallbook} that do not 14636require changing the source file. 14637 14638 14639@node A4 Paper 14640@section Printing on A4 Paper 14641@cindex A4 paper, printing on 14642@cindex A5 paper, printing on 14643@cindex Paper size, A4 14644@cindex European A4 paper 14645@findex afourpaper 14646 14647You can tell @TeX{} to format a document for printing on European size 14648A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper}) 14649command. Write the command on a line by itself near the beginning of 14650the Texinfo file, before the title page. For example, this is how you 14651would write the header for this manual: 14652 14653@example 14654@group 14655\input texinfo @@c -*-texinfo-*- 14656@@c %**start of header 14657@@setfilename texinfo 14658@@settitle Texinfo 14659@@afourpaper 14660@@c %**end of header 14661@end group 14662@end example 14663 14664@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for 14665@TeX{}}, for other ways to format for different paper sizes that do not 14666require changing the source file. 14667 14668@findex afourlatex 14669@findex afourwide 14670You may or may not prefer the formatting that results from the command 14671@code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in 14672wide format. 14673 14674@node pagesizes 14675@section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes 14676@findex pagesizes 14677@cindex Custom page sizes 14678@cindex Page sizes, customized 14679@cindex Text width and height 14680@cindex Width of text area 14681@cindex Height of text area 14682@cindex Depth of text area 14683 14684You can explicitly specify the height and (optionally) width of the main 14685text area on the page with the @code{@@pagesizes} command. Write this 14686on a line by itself near the beginning of the Texinfo file, before the 14687title page. The height comes first, then the width if desired, 14688separated by a comma. Examples: 14689 14690@example 14691@@pagesizes 200mm,150mm @c for b5 paper 14692@end example 14693@noindent and 14694@example 14695@@pagesizes 11.5in @c for legal paper 14696@end example 14697 14698@cindex B5 paper, printing on 14699@cindex Legal paper, printing on 14700This would be reasonable for printing on B5-size paper. To emphasize, 14701this command specifies the size of the @emph{text area}, not the size of 14702the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by 147038.5@dmn{in} for legal). 14704 14705@cindex Margins on page, not controllable 14706To make more elaborate changes, such as changing any of the page 14707margins, you must define a new command in @file{texinfo.tex} (or 14708@file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}). 14709 14710@xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for 14711@TeX{}}, for other ways to specify @code{@@pagesizes} that do not 14712require changing the source file. 14713 14714@code{@@pagesizes} is ignored by @code{makeinfo}. 14715 14716 14717@node Cropmarks and Magnification 14718@section Cropmarks and Magnification 14719@findex cropmarks 14720@cindex Cropmarks for printing 14721@cindex Printing cropmarks 14722You can (attempt to) direct @TeX{} to print cropmarks at the corners of 14723pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks} 14724command on a line by itself between @code{@@iftex} and @code{@@end 14725iftex} lines near the beginning of the Texinfo file, before the title 14726page, like this:@refill 14727 14728@example 14729@group 14730@@iftex 14731@@cropmarks 14732@@end iftex 14733@end group 14734@end example 14735 14736This command is mainly for printers that typeset several pages on one 14737sheet of film; but you can attempt to use it to mark the corners of a 14738book set to 7 by 9.25 inches with the @code{@@smallbook} command. 14739(Printers will not produce cropmarks for regular sized output that is 14740printed on regular sized paper.) Since different printing machines work 14741in different ways, you should explore the use of this command with a 14742spirit of adventure. You may have to redefine the command in 14743@file{texinfo.tex}. 14744 14745@findex \mag @r{(raw @TeX{} magnification)} 14746@cindex Magnified printing 14747@cindex Larger or smaller pages 14748You can attempt to direct @TeX{} to typeset pages larger or smaller than 14749usual with the @code{\mag} @TeX{} command. Everything that is typeset 14750is scaled proportionally larger or smaller. (@code{\mag} stands for 14751``magnification''.) This is @emph{not} a Texinfo @@-command, but is a 14752plain @TeX{} command that is prefixed with a backslash. You have to 14753write this command between @code{@@tex} and @code{@@end tex} 14754(@pxref{Raw Formatter Commands}). 14755 14756Follow the @code{\mag} command with an @samp{=} and then a number that 14757is 1000 times the magnification you desire. For example, to print pages 14758at 1.2 normal size, write the following near the beginning of the 14759Texinfo file, before the title page: 14760 14761@example 14762@group 14763@@tex 14764\mag=1200 14765@@end tex 14766@end group 14767@end example 14768 14769With some printing technologies, you can print normal-sized copies that 14770look better than usual by giving a larger-than-normal master to your 14771print shop. They do the reduction, thus effectively increasing the 14772resolution. 14773 14774Depending on your system, DVI files prepared with a 14775nonstandard-@code{\mag} may not print or may print only with certain 14776magnifications. Be prepared to experiment. 14777 14778 14779@node PDF Output 14780@section PDF Output 14781@cindex PDF output 14782 14783@pindex pdftex 14784The simplest way to generate PDF output from Texinfo source is to run 14785the convenience script @command{texi2pdf}; this simply executes the 14786@command{texi2dvi} script with the @option{--pdf} option 14787(@pxref{Format with texi2dvi}). If for some reason you want to 14788process by hand, simply run the @command{pdftex} program instead of 14789plain @command{tex}. That is, run @samp{pdftex foo.texi} instead of 14790@samp{tex foo.texi}. 14791 14792@dfn{PDF} stands for `Portable Document Format'. It was invented by 14793Adobe Systems some years ago for document interchange, based on their 14794PostScript language. Related links: 14795 14796@itemize 14797@item 14798GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF 14799reader}. (It can also preview PostScript documents.) 14800 14801@item 14802A freely available standalone @uref{http://www.foolabs.com/xpdf/, 14803PDF reader} for the X window system. 14804 14805@item 14806@uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}. 14807 14808@end itemize 14809 14810At present, Texinfo does not provide 14811@samp{@@ifpdf} or @samp{@@pdf} commands as for the other output 14812formats, since PDF documents contain many internal links that would be 14813hard or impossible to get right at the Texinfo source level. 14814 14815PDF files require special software to be displayed, unlike the plain 14816ASCII formats (Info, HTML) that Texinfo supports. They also tend to 14817be much larger than the DVI files output by @TeX{} by default. 14818Nevertheless, a PDF file does define an actual typeset document in a 14819self-contained file, so it has its place. 14820 14821 14822@node Obtaining TeX 14823@section How to Obtain @TeX{} 14824@cindex Obtaining @TeX{} 14825@cindex @TeX{}, how to obtain 14826 14827@c !!! Here is information about obtaining TeX. Update it whenever. 14828@c !!! Also consider updating TeX.README on ftp.gnu.org. 14829@c Updated by RJC on 1 March 1995, conversation with MacKay. 14830@c Updated by kb@cs.umb.edu on 29 July 1996. 14831@c Updated by kb@cs.umb.edu on 25 April 1997. 14832@c Updated by kb@cs.umb.edu on 27 February 1998. 14833@TeX{} is freely redistributable. You can obtain @TeX{} for Unix 14834systems via anonymous ftp or on physical media. The core material 14835consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}). 14836 14837Instructions for retrieval by anonymous ftp and information on other 14838available distributions: 14839@uref{http://tug.org/unixtex.ftp}. 14840 14841The Free Software Foundation provides a core distribution on its Source 14842Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: 14843 14844@display 14845@group 14846Free Software Foundation, Inc. 1484759 Temple Place Suite 330 14848Boston, MA @ @ 02111-1307 14849USA 14850Telephone: @w{+1-617-542-5942} 14851Fax: (including Japan) @w{+1-617-542-2652} 14852Free Dial Fax (in Japan): 14853@w{ } @w{ } @w{ } 0031-13-2473 (KDD) 14854@w{ } @w{ } @w{ } 0066-3382-0158 (IDC) 14855Electronic mail: @code{gnu@@gnu.org} 14856@end group 14857@end display 14858 14859Many other @TeX{} distributions are available; see 14860@uref{http://tug.org/}. 14861 14862 14863@node Creating and Installing Info Files 14864@chapter Creating and Installing Info Files 14865 14866This chapter describes how to create and install Info files. @xref{Info 14867Files}, for general information about the file format itself. 14868 14869@menu 14870* Creating an Info File:: 14871* Installing an Info File:: 14872@end menu 14873 14874 14875@node Creating an Info File 14876@section Creating an Info File 14877@cindex Creating an Info file 14878@cindex Info, creating an online file 14879@cindex Formatting a file for Info 14880 14881@code{makeinfo} is a program that converts a Texinfo file into an Info 14882file, HTML file, or plain text. @code{texinfo-format-region} and 14883@code{texinfo-format-buffer} are GNU Emacs functions that convert 14884Texinfo to Info. 14885 14886For information on installing the Info file in the Info system, 14887@pxref{Installing an Info File}. 14888 14889@menu 14890* makeinfo advantages:: @code{makeinfo} provides better error checking. 14891* Invoking makeinfo:: How to run @code{makeinfo} from a shell. 14892* makeinfo options:: Specify fill-column and other options. 14893* Pointer Validation:: How to check that pointers point somewhere. 14894* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. 14895* texinfo-format commands:: Two Info formatting commands written 14896 in Emacs Lisp are an alternative 14897 to @code{makeinfo}. 14898* Batch Formatting:: How to format for Info in Emacs Batch mode. 14899* Tag and Split Files:: How tagged and split files help Info 14900 to run better. 14901@end menu 14902 14903 14904@node makeinfo advantages 14905@subsection @code{makeinfo} Preferred 14906 14907The @code{makeinfo} utility creates an Info file from a Texinfo source 14908file more quickly than either of the Emacs formatting commands and 14909provides better error messages. We recommend it. @code{makeinfo} is a 14910C program that is independent of Emacs. You do not need to run Emacs to 14911use @code{makeinfo}, which means you can use @code{makeinfo} on machines 14912that are too small to run Emacs. You can run @code{makeinfo} in any one 14913of three ways: from an operating system shell, from a shell inside 14914Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b} 14915command in Texinfo mode in Emacs. 14916 14917The @code{texinfo-format-region} and the @code{texinfo-format-buffer} 14918commands are useful if you cannot run @code{makeinfo}. Also, in some 14919circumstances, they format short regions or buffers more quickly than 14920@code{makeinfo}. 14921 14922 14923@node Invoking makeinfo 14924@subsection Running @code{makeinfo} from a Shell 14925@pindex makeinfo 14926 14927To create an Info file from a Texinfo file, invoke @command{makeinfo} 14928followed by the name of the Texinfo file. Thus, to create the Info 14929file for Bison, type the following to the shell: 14930 14931@example 14932makeinfo bison.texinfo 14933@end example 14934 14935(You can run a shell inside Emacs by typing @kbd{M-x shell}.) 14936 14937@command{makeinfo} has many options to control its actions and output; 14938see the next section. 14939 14940 14941@node makeinfo options 14942@subsection Options for @code{makeinfo} 14943@cindex @code{makeinfo} options 14944@cindex Options for @code{makeinfo} 14945 14946The @command{makeinfo} program accepts many options. Perhaps the most 14947commonly needed are those that change the output format. By default, 14948@command{makeinfo} outputs Info files. 14949 14950Each command line option is a word preceded by @samp{--} or a letter 14951preceded by @samp{-}. You can use abbreviations for the long option 14952names as long as they are unique. 14953 14954For example, you could use the following shell command to create an Info 14955file for @file{bison.texinfo} in which each line is filled to only 68 14956columns: 14957 14958@example 14959makeinfo --fill-column=68 bison.texinfo 14960@end example 14961 14962You can write two or more options in sequence, like this:@refill 14963 14964@example 14965makeinfo --no-split --fill-column=70 @dots{} 14966@end example 14967 14968@noindent 14969This would keep the Info file together as one possibly very long 14970file and would also set the fill column to 70. 14971 14972The options are: 14973 14974@table @code 14975 14976@item -D @var{var} 14977@opindex -D @var{var} 14978Cause the variable @var{var} to be defined. This is equivalent to 14979@code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}). 14980 14981@item --commands-in-node-names 14982@opindex --commands-in-node-names 14983Allow @code{@@}-commands in node names. This is not recommended, as it 14984can probably never be implemented in @TeX{}. It also makes 14985@code{makeinfo} much slower. Also, this option is ignored when 14986@samp{--no-validate} is used. @xref{Pointer Validation}, for more 14987details. 14988 14989@item --css-include=@var{file} 14990@opindex --css-include 14991Include the contents of @var{file}, which should contain cascading 14992style sheets specifications, in the @samp{<style>} block of the HTML 14993output. @xref{HTML CSS}. If @var{file} is @samp{-}, read standard 14994input. 14995 14996@item --docbook 14997@opindex --docbook 14998Generate Docbook output rather than Info. 14999 15000@item --enable-encoding 15001@opindex --enable-encoding 15002Output accented and special characters in Info or plain text output 15003based on @samp{@@documentencoding}. 15004@xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting Accents}. 15005 15006@item --error-limit=@var{limit} 15007@itemx -e @var{limit} 15008@opindex --error-limit=@var{limit} 15009@opindex -e @var{limit} 15010Set the maximum number of errors that @code{makeinfo} will report 15011before exiting (on the assumption that continuing would be useless); 15012default 100. 15013 15014@item --fill-column=@var{width} 15015@itemx -f @var{width} 15016@opindex --fill-column=@var{width} 15017@opindex -f @var{width} 15018Specify the maximum number of columns in a line; this is the right-hand 15019edge of a line. Paragraphs that are filled will be filled to this 15020width. (Filling is the process of breaking up and connecting lines so 15021that lines are the same length as or shorter than the number specified 15022as the fill column. Lines are broken between words.) The default value 15023is 72. Ignored with @samp{--html}. 15024 15025@item --footnote-style=@var{style} 15026@itemx -s @var{style} 15027@opindex --footnote-style=@var{style} 15028@opindex -s @var{style} 15029Set the footnote style to @var{style}, either @samp{end} for the end 15030node style (the default) or @samp{separate} for the separate node style. 15031The value set by this option overrides the value set in a Texinfo file 15032by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the 15033footnote style is @samp{separate}, @code{makeinfo} makes a new node 15034containing the footnotes found in the current node. When the footnote 15035style is @samp{end}, @code{makeinfo} places the footnote references at 15036the end of the current node. Ignored with @samp{--html}. 15037 15038@item --force 15039@itemx -F 15040@opindex --force 15041@opindex -F 15042Ordinarily, if the input file has errors, the output files are not 15043created. With this option, they are preserved. 15044 15045@item --help 15046@itemx -h 15047@opindex --help 15048@opindex -h 15049Print a usage message listing all available options, then exit successfully. 15050 15051@item --html 15052@opindex --html 15053Generate HTML output rather than Info. @xref{Generating HTML}. By 15054default, the HTML output is split into one output file per Texinfo 15055source node, and the split output is written into a subdirectory with 15056the name of the top-level info file. 15057 15058@item -I @var{dir} 15059@opindex -I @var{dir} 15060Append @var{dir} to the directory search list for finding files that 15061are included using the @code{@@include} command. By default, 15062@code{makeinfo} searches only the current directory. If @var{dir} is 15063not given, the current directory @file{.} is appended. Note that 15064@var{dir} can actually be a list of several directories separated by the 15065usual path separator character (@samp{:} on Unix, @samp{;} on 15066MS-DOS/MS-Windows). 15067 15068@item --ifdocbook 15069@opindex --ifdocbook 15070@itemx --ifhtml 15071@opindex --ifhtml 15072@itemx --ifinfo 15073@opindex --ifinfo 15074@itemx --ifplaintext 15075@opindex --ifplaintext 15076@itemx --iftex 15077@opindex --iftex 15078@itemx --ifxml 15079@opindex --ifxml 15080For the specified format, process @samp{@@if@var{format}} and 15081@samp{@@@var{format}} commands even if not generating the given output 15082format. For instance, if @option{--iftex} is specified, then 15083@samp{@@iftex} and @samp{@@tex} blocks will be read. 15084 15085@item --macro-expand=@var{file} 15086@itemx -E @var{file} 15087@opindex --macro-expand=@var{file} 15088@opindex -E @var{file} 15089Output the Texinfo source with all the macros expanded to the named 15090file. Normally, the results of macro expansion are used internally by 15091@code{makeinfo} and then discarded. This option is used by 15092@command{texi2dvi}. 15093 15094@item --no-headers 15095@item --plaintext 15096@opindex --no-headers 15097@opindex --plaintext 15098@cindex Plain text output 15099@cindex ASCII text output 15100@cindex Generating plain text files 15101@cindex @file{INSTALL} file, generating 15102@cindex Node separators, omitting 15103@cindex Menus, omitting 15104Do not include menus or node separator lines in the output, and 15105implicitly @option{--enable-encoding} (see above). This results in a 15106simple plain text file that you can (for example) send in email 15107without complications, or include in a distribution (as in an 15108@file{INSTALL} file). 15109 15110@cindex Navigation links, omitting 15111For HTML output, likewise omit menus. And if @samp{--no-split} is also 15112specified, do not include a navigation links at the top of each node 15113(these are never included in the default case of split output). 15114@xref{Generating HTML}. 15115 15116In both cases, ignore @code{@@setfilename} and write to standard 15117output by default---can be overridden with @option{-o}. 15118 15119@item --no-ifdocbook 15120@opindex --no-ifdocbook 15121@itemx --no-ifhtml 15122@opindex --no-ifhtml 15123@itemx --no-ifinfo 15124@opindex --no-ifinfo 15125@itemx --no-ifplaintext 15126@opindex --no-ifplaintext 15127@itemx --no-iftex 15128@opindex --no-iftex 15129@itemx --no-ifxml 15130@opindex --no-ifxml 15131Do not process @samp{@@if@var{format}} and @samp{@@@var{format}} 15132commands, and do process @samp{@@ifnot@var{format}}, even if 15133generating the given format. For instance, if @option{--no-ifhtml} is 15134specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be 15135read, and @samp{@@ifnothtml} blocks will be. 15136 15137@item --no-number-footnotes 15138@opindex --no-number-footnotes 15139Suppress automatic footnote numbering. By default, @code{makeinfo} 15140numbers each footnote sequentially in a single node, resetting the 15141current footnote number to 1 at the start of each node. 15142 15143@item --no-number-sections 15144@opindex --no-number-sections 15145Do not output chapter, section, and appendix numbers. 15146You need to specify this if your manual is not hierarchically-structured. 15147 15148@item --no-split 15149@opindex --no-split 15150@cindex Splitting of output files 15151@cindex Output file splitting 15152Suppress the splitting stage of @code{makeinfo}. By default, large 15153output files (where the size is greater than 70k bytes) are split into 15154smaller subfiles. For Info output, each one is approximately 50k bytes. 15155For HTML output, each file contains one node (@pxref{Generating HTML}). 15156 15157@item --no-pointer-validate 15158@itemx --no-validate 15159@opindex --no-pointer-validate 15160@opindex --no-validate 15161@cindex Pointer validation, suppressing 15162Suppress the pointer-validation phase of @code{makeinfo}---a dangerous 15163thing to do. This can also be done with the @code{@@novalidate} 15164command (@pxref{Use TeX,,Use @TeX{}}). Normally, after a Texinfo file 15165is processed, some consistency checks are made to ensure that cross 15166references can be resolved, etc. @xref{Pointer Validation}. 15167 15168@item --no-warn 15169@opindex --no-warn 15170Suppress warning messages (but @emph{not} error messages). 15171 15172@item --number-sections 15173@opindex --number-sections 15174Output chapter, section, and appendix numbers as in printed manuals. 15175This is the default. It works only with hierarchically-structured 15176manuals. 15177 15178@item --output=@var{file} 15179@itemx -o @var{file} 15180@opindex --output=@var{file} 15181@opindex -o @var{file} 15182Specify that the output should be directed to @var{file} and not to the 15183file name specified in the @code{@@setfilename} command found in the 15184Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output 15185goes to standard output and @samp{--no-split} is implied. For split 15186HTML output, @var{file} is the name for the directory into which all 15187HTML nodes are written (@pxref{Generating HTML}). 15188 15189@item -P @var{dir} 15190@opindex -P @var{dir} 15191Prepend @var{dir} to the directory search list for @code{@@include}. 15192If @var{dir} is not given, the current directory @file{.} is prepended. 15193See @samp{-I} for more details. 15194 15195@item --paragraph-indent=@var{indent} 15196@itemx -p @var{indent} 15197@opindex --paragraph-indent=@var{indent} 15198@opindex -p @var{indent} 15199Set the paragraph indentation style to @var{indent}. The value set by 15200this option overrides the value set in a Texinfo file by an 15201@code{@@paragraphindent} command (@pxref{paragraphindent}). The value 15202of @var{indent} is interpreted as follows: 15203 15204@table @asis 15205@item @samp{asis} 15206Preserve any existing indentation at the starts of paragraphs. 15207 15208@item @samp{0} or @samp{none} 15209Delete any existing indentation. 15210 15211@item @var{num} 15212Indent each paragraph by @var{num} spaces. 15213@end table 15214 15215@item --reference-limit=@var{limit} 15216@itemx -r @var{limit} 15217@opindex --reference-limit=@var{limit} 15218@opindex -r @var{limit} 15219Set the value of the number of references to a node that 15220@code{makeinfo} will make without reporting a warning. If a node has more 15221than this number of references in it, @code{makeinfo} will make the 15222references but also report a warning. The default is 1000. 15223 15224@item --split-size=@var{num} 15225@opindex --split-size=@var{num} 15226Keep Info files to at most @var{num} characters; default is 300,000. 15227 15228@item -U @var{var} 15229Cause @var{var} to be undefined. This is equivalent to 15230@code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}). 15231 15232@item --verbose 15233@opindex --verbose 15234Cause @code{makeinfo} to display messages saying what it is doing. 15235Normally, @code{makeinfo} only outputs messages if there are errors or 15236warnings. 15237 15238@item --version 15239@itemx -V 15240@opindex --version 15241@opindex -V 15242Print the version number, then exit successfully. 15243 15244@item --xml 15245@opindex --xml 15246Generate XML output rather than Info. 15247 15248@end table 15249 15250@vindex TEXINFO_OUTPUT_FORMAT 15251@cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT} 15252@command{makeinfo} also reads the environment variable 15253@env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not 15254overridden by a command line option. The possible values are: 15255 15256@example 15257docbook html info plaintext xml 15258@end example 15259 15260If not set, Info output is the default. 15261 15262 15263@node Pointer Validation 15264@subsection Pointer Validation 15265@cindex Pointer validation with @code{makeinfo} 15266@cindex Validation of pointers 15267 15268If you do not suppress pointer validation with the @samp{--no-validate} 15269option or the @code{@@novalidate} command in the source file (@pxref{Use 15270TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final 15271Info file. Mostly, this means ensuring that nodes you have referenced 15272really exist. Here is a complete list of what is checked: 15273 15274@enumerate 15275@item 15276If a `Next', `Previous', or `Up' node reference is a reference to a 15277node in the current file and is not an external reference such as to 15278@file{(dir)}, then the referenced node must exist.@refill 15279 15280@item 15281In every node, if the `Previous' node is different from the `Up' node, 15282then the node pointed to by the `Previous' field must have a `Next' 15283field which points back to this node.@refill 15284 15285@item 15286Every node except the `Top' node must have an `Up' pointer.@refill 15287 15288@item 15289The node referenced by an `Up' pointer must itself reference the current 15290node through a menu item, unless the node referenced by `Up' 15291has the form `(@var{file})'. 15292 15293@item 15294If the `Next' reference of a node is not the same as the `Next' reference 15295of the `Up' reference, then the node referenced by the `Next' pointer 15296must have a `Previous' pointer that points back to the current node. 15297This rule allows the last node in a section to point to the first node 15298of the next chapter.@refill 15299 15300@item 15301Every node except `Top' should be referenced by at least one other node, 15302either via the `Previous' or `Next' links, or via a menu or a 15303cross-reference.@refill 15304@end enumerate 15305 15306@cindex @@-commands in @@node, limited support 15307Some Texinfo documents might fail during the validation phase because 15308they use commands like @code{@@value} and @code{@@definfoenclose} in 15309node definitions and cross-references inconsistently. (Your best bet 15310is to avoid using @@-commands in node names.) Consider the 15311following example: 15312 15313@example 15314@group 15315@@set nodename Node 1 15316 15317@@node @@value@{nodename@}, Node 2, Top, Top 15318 15319This is node 1. 15320 15321@@node Node 2, , Node 1, Top 15322 15323This is node 2. 15324@end group 15325@end example 15326 15327@noindent 15328Here, the node ``Node 1'' was referenced both verbatim and through 15329@code{@@value}. 15330 15331By default, @code{makeinfo} fails such cases, because node names are not 15332fully expanded until they are written to the output file. You should 15333always try to reference nodes consistently; e.g., in the above example, 15334the second @code{@@node} line should have also used @code{@@value}. 15335However, if, for some reason, you @emph{must} reference node names 15336inconsistently, and @code{makeinfo} fails to validate the file, you can 15337use the @samp{--commands-in-node-names} option to force @code{makeinfo} 15338to perform the expensive expansion of all node names it finds in the 15339document. This might considerably slow down the program, though; 15340twofold increase in conversion time was measured for large documents 15341such as the Jargon file. 15342 15343@cindex @@value in @@node lines 15344The support for @code{@@}-commands in @code{@@node} directives is not 15345general enough to be freely used. For example, if the example above 15346redefined @code{nodename} somewhere in the document, @code{makeinfo} 15347will fail to convert it, even if invoked with the 15348@samp{--commands-in-node-names} option. 15349 15350@samp{--commands-in-node-names} has no effect if the @samp{--no-validate} 15351option is given. 15352 15353 15354@node makeinfo in Emacs 15355@subsection Running @code{makeinfo} Within Emacs 15356@cindex Running @code{makeinfo} in Emacs 15357@cindex @code{makeinfo} inside Emacs 15358@cindex Shell, running @code{makeinfo} in 15359 15360You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the 15361@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In 15362Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c 15363C-m C-b} by default.@refill 15364 15365@table @kbd 15366@item C-c C-m C-r 15367@itemx M-x makeinfo-region 15368Format the current region for Info.@refill 15369@findex makeinfo-region 15370 15371@item C-c C-m C-b 15372@itemx M-x makeinfo-buffer 15373Format the current buffer for Info.@refill 15374@findex makeinfo-buffer 15375@end table 15376 15377When you invoke @code{makeinfo-region} the output goes to a temporary 15378buffer. When you invoke @code{makeinfo-buffer} output goes to the 15379file set with @code{@@setfilename} (@pxref{setfilename}). 15380 15381The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands 15382run the @code{makeinfo} program in a temporary shell buffer. If 15383@code{makeinfo} finds any errors, Emacs displays the error messages in 15384the temporary buffer.@refill 15385 15386@cindex Errors, parsing 15387@cindex Parsing errors 15388@findex next-error 15389You can parse the error messages by typing @kbd{C-x `} 15390(@code{next-error}). This causes Emacs to go to and position the 15391cursor on the line in the Texinfo source that @code{makeinfo} thinks 15392caused the error. @xref{Compilation, , Running @code{make} or 15393Compilers Generally, emacs, The GNU Emacs Manual}, for more 15394information about using the @code{next-error} command.@refill 15395 15396In addition, you can kill the shell in which the @code{makeinfo} 15397command is running or make the shell buffer display its most recent 15398output.@refill 15399 15400@table @kbd 15401@item C-c C-m C-k 15402@itemx M-x makeinfo-kill-job 15403@findex makeinfo-kill-job 15404Kill the current running @code{makeinfo} job 15405(from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill 15406 15407@item C-c C-m C-l 15408@itemx M-x makeinfo-recenter-output-buffer 15409@findex makeinfo-recenter-output-buffer 15410Redisplay the @code{makeinfo} shell buffer to display its most recent 15411output.@refill 15412@end table 15413 15414@noindent 15415(Note that the parallel commands for killing and recentering a @TeX{} 15416job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode 15417Printing}.)@refill 15418 15419You can specify options for @code{makeinfo} by setting the 15420@code{makeinfo-options} variable with either the @kbd{M-x 15421customize} or the @kbd{M-x set-variable} command, or by setting the 15422variable in your @file{.emacs} initialization file. 15423 15424For example, you could write the following in your @file{.emacs} file:@refill 15425 15426@example 15427@group 15428(setq makeinfo-options 15429 "--paragraph-indent=0 --no-split 15430 --fill-column=70 --verbose") 15431@end group 15432@end example 15433 15434@noindent 15435@c If you write these three cross references using xref, you see 15436@c three references to the same named manual, which looks strange. 15437@iftex 15438For more information, see @ref{makeinfo options, , Options for 15439@code{makeinfo}}, as well as ``Easy Customization Interface,'' ``Examining 15440and Setting Variables,'' and ``Init File'' in @cite{The GNU Emacs 15441Manual}. 15442@end iftex 15443@ifnottex 15444For more information, see@* 15445@ref{Easy Customization, , Easy Customization Interface, emacs, The GNU Emacs Manual},@* 15446@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@* 15447@ref{Init File, , , emacs, The GNU Emacs Manual}, and@* 15448@ref{makeinfo options, , Options for @code{makeinfo}}. 15449@end ifnottex 15450 15451@node texinfo-format commands 15452@subsection The @code{texinfo-format@dots{}} Commands 15453 15454In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo 15455file with the @code{texinfo-format-region} command. This formats the 15456current region and displays the formatted text in a temporary buffer 15457called @samp{*Info Region*}.@refill 15458 15459Similarly, you can format a buffer with the 15460@code{texinfo-format-buffer} command. This command creates a new 15461buffer and generates the Info file in it. Typing @kbd{C-x C-s} will 15462save the Info file under the name specified by the 15463@code{@@setfilename} line which must be near the beginning of the 15464Texinfo file.@refill 15465 15466@table @kbd 15467@item C-c C-e C-r 15468@itemx @code{texinfo-format-region} 15469@findex texinfo-format-region 15470Format the current region for Info. 15471 15472@item C-c C-e C-b 15473@itemx @code{texinfo-format-buffer} 15474@findex texinfo-format-buffer 15475Format the current buffer for Info. 15476@end table 15477 15478The @code{texinfo-format-region} and @code{texinfo-format-buffer} 15479commands provide you with some error checking, and other functions can 15480provide you with further help in finding formatting errors. These 15481procedures are described in an appendix; see @ref{Catching Mistakes}. 15482However, the @code{makeinfo} program is often faster and 15483provides better error checking (@pxref{makeinfo in Emacs}).@refill 15484 15485@node Batch Formatting 15486@comment node-name, next, previous, up 15487@subsection Batch Formatting 15488@cindex Batch formatting for Info 15489@cindex Info batch formatting 15490 15491You can format Texinfo files for Info using @code{batch-texinfo-format} 15492and Emacs Batch mode. You can run Emacs in Batch mode from any shell, 15493including a shell inside of Emacs. (@xref{Command Arguments,,, 15494emacs, The GNU Emacs Manual}.) 15495 15496Here is a shell command to format all the files that end in 15497@file{.texinfo} in the current directory: 15498 15499@example 15500emacs -batch -funcall batch-texinfo-format *.texinfo 15501@end example 15502 15503@noindent 15504Emacs processes all the files listed on the command line, even if an 15505error occurs while attempting to format some of them.@refill 15506 15507Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown; 15508it is not interactive. It kills the Batch mode Emacs on completion.@refill 15509 15510@code{batch-texinfo-format} is convenient if you lack @code{makeinfo} 15511and want to format several Texinfo files at once. When you use Batch 15512mode, you create a new Emacs process. This frees your current Emacs, so 15513you can continue working in it. (When you run 15514@code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot 15515use that Emacs for anything else until the command finishes.)@refill 15516 15517@node Tag and Split Files 15518@comment node-name, next, previous, up 15519@subsection Tag Files and Split Files 15520@cindex Making a tag table automatically 15521@cindex Tag table, making automatically 15522 15523If a Texinfo file has more than 30,000 bytes, 15524@code{texinfo-format-buffer} automatically creates a tag table 15525for its Info file; @code{makeinfo} always creates a tag table. With 15526a @dfn{tag table}, Info can jump to new nodes more quickly than it can 15527otherwise.@refill 15528 15529@cindex Indirect subfiles 15530In addition, if the Texinfo file contains more than about 300,000 15531bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the 15532large Info file into shorter @dfn{indirect} subfiles of about 300,000 15533bytes each. Big files are split into smaller files so that Emacs does 15534not need to make a large buffer to hold the whole of a large Info 15535file; instead, Emacs allocates just enough memory for the small, split-off 15536file that is needed at the time. This way, Emacs avoids wasting 15537memory when you run Info. (Before splitting was implemented, Info 15538files were always kept short and @dfn{include files} were designed as 15539a way to create a single, large printed manual out of the smaller Info 15540files. @xref{Include Files}, for more information. Include files are 15541still used for very large documents, such as @cite{The Emacs Lisp 15542Reference Manual}, in which each chapter is a separate file.)@refill 15543 15544When a file is split, Info itself makes use of a shortened version of 15545the original file that contains just the tag table and references to 15546the files that were split off. The split-off files are called 15547@dfn{indirect} files.@refill 15548 15549The split-off files have names that are created by appending @w{@samp{-1}}, 15550@w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the 15551@code{@@setfilename} command. The shortened version of the original file 15552continues to have the name specified by @code{@@setfilename}.@refill 15553 15554At one stage in writing this document, for example, the Info file was saved 15555as the file @file{test-texinfo} and that file looked like this:@refill 15556 15557@example 15558@group 15559Info file: test-texinfo, -*-Text-*- 15560produced by texinfo-format-buffer 15561from file: new-texinfo-manual.texinfo 15562 15563^_ 15564Indirect: 15565test-texinfo-1: 102 15566test-texinfo-2: 50422 15567@end group 15568@group 15569test-texinfo-3: 101300 15570^_^L 15571Tag table: 15572(Indirect) 15573Node: overview^?104 15574Node: info file^?1271 15575@end group 15576@group 15577Node: printed manual^?4853 15578Node: conventions^?6855 15579@dots{} 15580@end group 15581@end example 15582 15583@noindent 15584(But @file{test-texinfo} had far more nodes than are shown here.) Each of 15585the split-off, indirect files, @file{test-texinfo-1}, 15586@file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file 15587after the line that says @samp{Indirect:}. The tag table is listed after 15588the line that says @samp{Tag table:}. @refill 15589 15590In the list of indirect files, the number following the file name 15591records the cumulative number of bytes in the preceding indirect files, 15592not counting the file list itself, the tag table, or the permissions 15593text in each file. In the tag table, the number following the node name 15594records the location of the beginning of the node, in bytes from the 15595beginning of the (unsplit) output. 15596 15597If you are using @code{texinfo-format-buffer} to create Info files, 15598you may want to run the @code{Info-validate} command. (The 15599@code{makeinfo} command does such a good job on its own, you do not 15600need @code{Info-validate}.) However, you cannot run the @kbd{M-x 15601Info-validate} node-checking command on indirect files. For 15602information on how to prevent files from being split and how to 15603validate the structure of the nodes, see @ref{Using Info-validate}. 15604 15605 15606@node Installing an Info File 15607@section Installing an Info File 15608@cindex Installing an Info file 15609@cindex Info file installation 15610@cindex @file{dir} directory for Info installation 15611 15612Info files are usually kept in the @file{info} directory. You can read 15613Info files using the standalone Info program or the Info reader built 15614into Emacs. (@inforef{Top, info, info}, for an introduction to Info.) 15615 15616@menu 15617* Directory File:: The top level menu for all Info files. 15618* New Info File:: Listing a new Info file. 15619* Other Info Directories:: How to specify Info files that are 15620 located in other directories. 15621* Installing Dir Entries:: How to specify what menu entry to add 15622 to the Info directory. 15623* Invoking install-info:: @code{install-info} options. 15624@end menu 15625 15626 15627@node Directory File 15628@subsection The Directory File @file{dir} 15629 15630For Info to work, the @file{info} directory must contain a file that 15631serves as a top level directory for the Info system. By convention, 15632this file is called @file{dir}. (You can find the location of this file 15633within Emacs by typing @kbd{C-h i} to enter Info and then typing 15634@kbd{C-x C-f} to see the pathname to the @file{info} directory.) 15635 15636The @file{dir} file is itself an Info file. It contains the top level 15637menu for all the Info files in the system. The menu looks like 15638this:@refill 15639 15640@example 15641@group 15642* Menu: 15643* Info: (info). Documentation browsing system. 15644* Emacs: (emacs). The extensible, self-documenting 15645 text editor. 15646* Texinfo: (texinfo). With one source file, make 15647 either a printed manual using 15648 @@TeX@{@} or an Info file. 15649@dots{} 15650@end group 15651@end example 15652 15653Each of these menu entries points to the `Top' node of the Info file 15654that is named in parentheses. (The menu entry does not need to 15655specify the `Top' node, since Info goes to the `Top' node if no node 15656name is mentioned. @xref{Other Info Files, , Nodes in Other Info 15657Files}.)@refill 15658 15659Thus, the @samp{Info} entry points to the `Top' node of the 15660@file{info} file and the @samp{Emacs} entry points to the `Top' node 15661of the @file{emacs} file.@refill 15662 15663In each of the Info files, the `Up' pointer of the `Top' node refers 15664back to the @code{dir} file. For example, the line for the `Top' 15665node of the Emacs manual looks like this in Info:@refill 15666 15667@example 15668File: emacs Node: Top, Up: (DIR), Next: Distrib 15669@end example 15670 15671@noindent 15672In this case, the @file{dir} file name is written in upper case 15673letters---it can be written in either upper or lower case. This is not 15674true in general, it is a special case for @file{dir}. 15675 15676 15677@node New Info File 15678@subsection Listing a New Info File 15679@cindex Adding a new Info file 15680@cindex Listing a new Info file 15681@cindex New Info file, listing it in @file{dir} file 15682@cindex Info file, listing a new 15683@cindex @file{dir} file listing 15684 15685To add a new Info file to your system, you must write a menu entry to 15686add to the menu in the @file{dir} file in the @file{info} directory. 15687For example, if you were adding documentation for GDB, you would write 15688the following new entry:@refill 15689 15690@example 15691* GDB: (gdb). The source-level C debugger. 15692@end example 15693 15694@noindent 15695The first part of the menu entry is the menu entry name, followed by a 15696colon. The second part is the name of the Info file, in parentheses, 15697followed by a period. The third part is the description. 15698 15699The name of an Info file often has a @file{.info} extension. Thus, the 15700Info file for GDB might be called either @file{gdb} or @file{gdb.info}. 15701The Info reader programs automatically try the file name both with and 15702without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will 15703try the @file{.inf} extension as well.}; so it is better to avoid 15704clutter and not to write @samp{.info} explicitly in the menu entry. For 15705example, the GDB menu entry should use just @samp{gdb} for the file 15706name, not @samp{gdb.info}. 15707 15708 15709@node Other Info Directories 15710@subsection Info Files in Other Directories 15711@cindex Installing Info in another directory 15712@cindex Info installed in another directory 15713@cindex Another Info directory 15714@cindex @file{dir} files and Info directories 15715 15716If an Info file is not in the @file{info} directory, there are three 15717ways to specify its location:@refill 15718 15719@enumerate 15720@item 15721Write the pathname in the @file{dir} file as the second part of the menu. 15722 15723@item 15724If you are using Emacs, list the name of the file in a second @file{dir} 15725file, in its directory; and then add the name of that directory to the 15726@code{Info-directory-list} variable in your personal or site 15727initialization file. 15728 15729This variable tells Emacs where to look for @file{dir} files (the files 15730must be named @file{dir}). Emacs merges the files named @file{dir} from 15731each of the listed directories. (In Emacs version 18, you can set the 15732@code{Info-directory} variable to the name of only one 15733directory.)@refill 15734 15735@item 15736Specify the Info directory name in the @code{INFOPATH} environment 15737variable in your @file{.profile} or @file{.cshrc} initialization file. 15738(Only you and others who set this environment variable will be able to 15739find Info files whose location is specified this way.) 15740@end enumerate 15741 15742For example, to reach a test file in the @file{/home/bob/info} 15743directory, you could add an entry like this to the menu in the 15744standard @file{dir} file:@refill 15745 15746@example 15747* Test: (/home/bob/info/info-test). Bob's own test file. 15748@end example 15749 15750@noindent 15751In this case, the absolute file name of the @file{info-test} file is 15752written as the second part of the menu entry.@refill 15753 15754Alternatively, you could write the following in your @file{.emacs} file: 15755 15756@vindex Info-directory-list 15757@example 15758@group 15759(require 'info) 15760(setq Info-directory-list 15761 (cons (expand-file-name "/home/bob/info") 15762 Info-directory-list)) 15763@end group 15764@end example 15765 15766This tells Emacs to merge the system @file{dir} file with the @file{dir} 15767file in @file{/home/bob/info}. Thus, Info will list the 15768@file{/home/bob/info/info-test} file as a menu entry in the 15769@file{/home/bob/info/dir} file. Emacs does the merging only when 15770@kbd{M-x info} is first run, so if you want to set 15771@code{Info-directory-list} in an Emacs session where you've already run 15772@code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs 15773to recompose the @file{dir} file. 15774 15775@vindex INFOPATH 15776@cindex Environment variable @code{INFOPATH} 15777Finally, you can tell Info where to look by setting the @code{INFOPATH} 15778environment variable in your shell startup file, such as @file{.cshrc}, 15779@file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible 15780shell such as @code{sh} or @code{bash} for your shell command 15781interpreter, you set the @code{INFOPATH} environment variable in the 15782@file{.profile} initialization file; but if you use @code{csh} or 15783@code{tcsh}, you set the variable in the @file{.cshrc} initialization 15784file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in 15785your @file{autoexec.bat} file or in the Registry. Each type of shell 15786uses a different syntax. 15787 15788@itemize @bullet 15789@item 15790In a @file{.cshrc} file, you could set the @code{INFOPATH} 15791variable as follows:@refill 15792 15793@smallexample 15794setenv INFOPATH .:~/info:/usr/local/emacs/info 15795@end smallexample 15796 15797@item 15798In a @file{.profile} file, you would achieve the same effect by 15799writing:@refill 15800 15801@smallexample 15802INFOPATH=.:$HOME/info:/usr/local/emacs/info 15803export INFOPATH 15804@end smallexample 15805 15806@item 15807@pindex autoexec.bat 15808In a @file{autoexec.bat} file, you write this command@footnote{Note the 15809use of @samp{;} as the directory separator, and a different syntax for 15810using values of other environment variables.}: 15811 15812@smallexample 15813set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info 15814@end smallexample 15815@end itemize 15816 15817@noindent 15818The @samp{.} indicates the current directory as usual. Emacs uses the 15819@code{INFOPATH} environment variable to initialize the value of Emacs's 15820own @code{Info-directory-list} variable. The stand-alone Info reader 15821merges any files named @file{dir} in any directory listed in the 15822@env{INFOPATH} variable into a single menu presented to you in the node 15823called @samp{(dir)Top}. 15824 15825@cindex Colon, last in @env{INFOPATH} 15826However you set @env{INFOPATH}, if its last character is a 15827colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this 15828is replaced by the default (compiled-in) path. This gives you a way to 15829augment the default path with new directories without having to list all 15830the standard places. For example (using @code{sh} syntax): 15831 15832@example 15833INFOPATH=/local/info: 15834export INFOPATH 15835@end example 15836 15837@noindent 15838will search @file{/local/info} first, then the standard directories. 15839Leading or doubled colons are not treated specially. 15840 15841@cindex @file{dir} file, creating your own 15842When you create your own @file{dir} file for use with 15843@code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by 15844copying an existing @file{dir} file and replace all the text after the 15845@samp{* Menu:} with your desired entries. That way, the punctuation and 15846special CTRL-_ characters that Info needs will be present. 15847 15848 15849@node Installing Dir Entries 15850@subsection Installing Info Directory Files 15851 15852When you install an Info file onto your system, you can use the program 15853@code{install-info} to update the Info directory file @file{dir}. 15854Normally the makefile for the package runs @code{install-info}, just 15855after copying the Info file into its proper installed location. 15856 15857@findex dircategory 15858@findex direntry 15859In order for the Info file to work with @code{install-info}, you include 15860the commands @code{@@dircategory} and 15861@code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source 15862file. Use @code{@@direntry} to specify the menu entries to add to the 15863Info directory file, and use @code{@@dircategory} to specify which part 15864of the Info directory to put it in. Here is how these commands are used 15865in this manual: 15866 15867@smallexample 15868@@dircategory Texinfo documentation system 15869@@direntry 15870* Texinfo: (texinfo). The GNU documentation format. 15871* install-info: (texinfo)Invoking install-info. @dots{} 15872@dots{} 15873@@end direntry 15874@end smallexample 15875 15876Here's what this produces in the Info file: 15877 15878@smallexample 15879INFO-DIR-SECTION Texinfo documentation system 15880START-INFO-DIR-ENTRY 15881* Texinfo: (texinfo). The GNU documentation format. 15882* install-info: (texinfo)Invoking install-info. @dots{} 15883@dots{} 15884END-INFO-DIR-ENTRY 15885@end smallexample 15886 15887@noindent 15888The @code{install-info} program sees these lines in the Info file, and 15889that is how it knows what to do. 15890 15891Always use the @code{@@direntry} and @code{@@dircategory} commands near 15892the beginning of the Texinfo input, before the first @code{@@node} 15893command. If you use them later on in the input, @code{install-info} 15894will not notice them. 15895 15896If you use @code{@@dircategory} more than once in the Texinfo source, 15897each usage specifies the `current' category; any subsequent 15898@code{@@direntry} commands will add to that category. 15899 15900@cindex Free Software Directory 15901@cindex Dir categories, choosing 15902@cindex Categories, choosing 15903When choosing a category name for the @code{@@dircategory} command, we 15904recommend consulting the @uref{http://www.gnu.org/directory, 15905Free Software Directory}. If your program is not listed there, 15906or listed incorrectly or incompletely, please report the situation to 15907the directory maintainers (@email{bug-directory@@gnu.org}) so that the 15908category names can be kept in sync. 15909 15910Here are a few examples (see the @file{util/dir-example} file in the 15911Texinfo distribution for large sample @code{dir} file): 15912 15913@display 15914Emacs 15915Localization 15916Printing 15917Software development 15918Software libraries 15919Text creation and manipulation 15920@end display 15921 15922@cindex Invoking nodes, including in dir file 15923Each `Invoking' node for every program installed should have a 15924corresponding @code{@@direntry}. This lets users easily find the 15925documentation for the different programs they can run, as with the 15926traditional @command{man} system. 15927 15928 15929@node Invoking install-info 15930@subsection Invoking @command{install-info} 15931@pindex install-info 15932 15933@code{install-info} inserts menu entries from an Info file into the 15934top-level @file{dir} file in the Info system (see the previous sections 15935for an explanation of how the @file{dir} file works). It's most often 15936run as part of software installation, or when constructing a @file{dir} file 15937for all manuals on a system. Synopsis: 15938 15939@example 15940install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]] 15941@end example 15942 15943If @var{info-file} or @var{dir-file} are not specified, the options 15944(described below) that define them must be. There are no compile-time 15945defaults, and standard input is never used. @code{install-info} can 15946read only one Info file and write only one @file{dir} file per invocation. 15947 15948@cindex @file{dir}, created by @code{install-info} 15949If @var{dir-file} (however specified) does not exist, 15950@code{install-info} creates it if possible (with no entries). 15951 15952@cindex Compressed files, reading 15953@cindex Dir files, compressed 15954If any input file is compressed with @code{gzip} (@pxref{Invoking 15955gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it 15956for reading. And if @var{dir-file} is compressed, @code{install-info} 15957also automatically leaves it compressed after writing any changes. 15958If @var{dir-file} itself does not exist, @code{install-info} tries to 15959open @file{@var{dir-file}.gz}. 15960 15961Options: 15962 15963@table @code 15964@item --delete 15965@opindex --delete 15966Delete the entries in @var{info-file} from @var{dir-file}. The file 15967name in the entry in @var{dir-file} must be @var{info-file} (except for 15968an optional @samp{.info} in either one). Don't insert any new entries. 15969 15970@item --dir-file=@var{name} 15971@itemx -d @var{name} 15972@opindex --dir-file=@var{name} 15973@opindex -d @var{name} 15974Specify file name of the Info directory file. This is equivalent to 15975using the @var{dir-file} argument. 15976 15977@item --entry=@var{text} 15978@itemx -e @var{text} 15979@opindex --entry=@var{text} 15980@opindex -e @var{text} 15981Insert @var{text} as an Info directory entry; @var{text} should have the 15982form of an Info menu item line plus zero or more extra lines starting 15983with whitespace. If you specify more than one entry, they are all 15984added. If you don't specify any entries, they are determined from 15985information in the Info file itself. 15986 15987@item --help 15988@itemx -h 15989@opindex --help 15990@opindex -h 15991Display a usage message listing basic usage and all available options, 15992then exit successfully. 15993 15994@item --info-file=@var{file} 15995@itemx -i @var{file} 15996@opindex --info-file=@var{file} 15997@opindex -i @var{file} 15998Specify Info file to install in the directory. 15999Equivalent to using the @var{info-file} argument. 16000 16001@item --info-dir=@var{dir} 16002@itemx -D @var{dir} 16003@opindex --info-dir=@var{dir} 16004@opindex -D @var{dir} 16005Specify the directory where the directory file @file{dir} resides. 16006Equivalent to @samp{--dir-file=@var{dir}/dir}. 16007 16008@item --item=@var{text} 16009@opindex --item=@var{text} 16010Same as @samp{--entry=@var{text}}. An Info directory entry is actually 16011a menu item. 16012 16013@item --quiet 16014@opindex --quiet 16015Suppress warnings. 16016 16017@item --remove 16018@itemx -r 16019@opindex --remove 16020@opindex -r 16021Same as @samp{--delete}. 16022 16023@item --section=@var{sec} 16024@itemx -s @var{sec} 16025@opindex --section=@var{sec} 16026@opindex -s @var{sec} 16027Put this file's entries in section @var{sec} of the directory. If you 16028specify more than one section, all the entries are added in each of the 16029sections. If you don't specify any sections, they are determined from 16030information in the Info file itself. 16031 16032@item --version 16033@itemx -V 16034@opindex --version 16035@opindex -V 16036@cindex Version number, for install-info 16037Display version information and exit successfully. 16038 16039@end table 16040 16041 16042@node Generating HTML 16043@chapter Generating HTML 16044@cindex HTML output 16045 16046@command{makeinfo} generates Info output by default, but given the 16047@option{--html} option, it will generate HTML, for web browsers and 16048other programs. This chapter gives some details on such HTML output. 16049 16050 16051@command{makeinfo} can also write in XML and Docbook format, but we do 16052not as yet describe these further. @xref{Output Formats}, for a brief 16053overview of all the output formats. 16054 16055@menu 16056* HTML Translation:: Details of the HTML output. 16057* HTML Splitting:: How HTML output is split. 16058* HTML CSS:: Influencing HTML output with Cascading Style Sheets. 16059* HTML Xref:: Cross-references in HTML output. 16060@end menu 16061 16062 16063@node HTML Translation 16064@section HTML Translation 16065 16066@command{makeinfo} will include segments of Texinfo source between 16067@code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not 16068any of the other conditionals, by default). Source between 16069@code{@@html} and @code{@@end html} is passed without change to the 16070output (i.e., suppressing the normal escaping of input @samp{<}, 16071@samp{>} and @samp{&} characters which have special significance in 16072HTML). @xref{Conditional Commands}. 16073 16074@opindex --footnote-style@r{, ignored in HTML output} 16075The @option{--footnote-style} option is currently ignored for HTML output; 16076footnotes are always linked to the end of the output file. 16077 16078@cindex Navigation bar, in HTML output 16079By default, a navigation bar is inserted at the start of each node, 16080analogous to Info output. The @samp{--no-headers} option suppresses 16081this if used with @samp{--no-split}. Header @code{<link>} elements in 16082split output can support info-like navigation with browsers like Lynx 16083and @w{Emacs W3} which implement this HTML@tie{}1.0 feature. 16084 16085@cindex HTML output, browser compatibility of 16086The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866). 16087One exception is that HTML@tie{}3.2 tables are generated from the 16088@code{@@multitable} command, but tagged to degrade as well as possible 16089in browsers without table support. The HTML@tie{}4 @samp{lang} 16090attribute on the @samp{<html>} attribute is also used. (Please report 16091output from an error-free run of @code{makeinfo} which has browser 16092portability problems as a bug.) 16093 16094 16095@node HTML Splitting 16096@section HTML Splitting 16097@cindex Split HTML output 16098@cindex HTML output, split 16099 16100When splitting output (which is the default), @command{makeinfo} 16101writes HTML output into (generally) one output file per Texinfo source 16102@code{@@node}. 16103 16104The output file name is the node name with special characters replaced 16105by @samp{-}'s, so it can work as a filename. In the unusual case of 16106two different nodes having the same name after this treatment, they 16107are written consecutively to the same file, with HTML anchors so each 16108can be referred to separately. If @command{makeinfo} is run on a 16109system which does not distinguish case in filenames, nodes which are 16110the same except for case will also be folded into the same output 16111file. 16112 16113When splitting, the HTML output files are written into a subdirectory, 16114with the name chosen as follows: 16115@enumerate 16116@item 16117@command{makeinfo} first tries the subdirectory with the base name 16118from @code{@@setfilename} (that is, any extension is removed). For 16119example, HTML output for @code{@@setfilename gcc.info} would be 16120written into a subdirectory named @samp{gcc}. 16121 16122@item 16123If that directory cannot be created for any reason, then 16124@command{makeinfo} tries appending @samp{.html} to the directory name. 16125For example, output for @code{@@setfilename texinfo} would be written 16126to @samp{texinfo.html}. 16127 16128@item 16129If the @samp{@var{name}.html} directory can't be 16130created either, @code{makeinfo} gives up. 16131 16132@end enumerate 16133 16134@noindent In any case, the top-level output file within the directory 16135is always named @samp{index.html}. 16136 16137Monolithic output (@code{--no-split}) is named according to 16138@code{@@setfilename} (with any @samp{.info} extension is replaced with 16139@samp{.html}) or @code{--output} (the argument is used literally). 16140 16141 16142@node HTML CSS 16143@section HTML CSS 16144@cindex HTML, and CSS 16145@cindex CSS, and HTML output 16146@cindex Cascading Style Sheets, and HTML output 16147 16148Cascading Style Sheets (CSS for short) is an Internet standard for 16149influencing the display of HTML documents: see 16150@uref{http://www.w3.org/Style/CSS/}. 16151 16152By default, @command{makeinfo} includes a few simple CSS commands to 16153better implement the appearance of some of the environments. Here 16154are two of them, as an example: 16155 16156@example 16157pre.display @{ font-family:inherit @} 16158pre.smalldisplay @{ font-family:inherit; font-size:smaller @} 16159@end example 16160 16161A full explanation of CSS is (far) beyond this manual; please see the 16162reference above. In brief, however, this specification tells the web 16163browser to use a `smaller' font size for @code{@@smalldisplay} text, 16164and to use the `inherited' font (generally a regular roman typeface) 16165for both @code{@@smalldisplay} and @code{@@display}. By default, the 16166HTML @samp{<pre>} command uses a monospaced font. 16167 16168You can influence the CSS in the HTML output with the 16169@option{--css-include=@var{file}} option to @command{makeinfo}. This 16170includes the contents @var{file} in the HTML output, as you might 16171expect. However, the details are somewhat tricky, as described in the 16172following, to provide maximum flexibility. 16173 16174@cindex @@import specifications, in CSS files 16175The CSS file may begin with so-called @samp{@@import} directives, 16176which link to external CSS specifications for browsers to use when 16177interpreting the document. Again, a full description is beyond our 16178scope here, but we'll describe how they work syntactically, so we can 16179explain how @command{makeinfo} handles them. 16180 16181@cindex Comments, in CSS files 16182There can be more than one @samp{@@import}, but they have to come 16183first in the file, with only whitespace and comments interspersed, no 16184normal definitions. (Technical exception: an @samp{@@charset} 16185directive may precede the @samp{@@import}'s. This does not alter 16186@command{makeinfo}'s behavior, it just copies the @samp{@@charset} if 16187present.) Comments in CSS files are delimited by @samp{/* ... */}, as 16188in C. An @samp{@@import} directive must be in one of these two forms: 16189 16190@example 16191@@import url(http://example.org/foo.css); 16192@@import "http://example.net/bar.css"; 16193@end example 16194 16195As far as @command{makeinfo} is concerned, the crucial characters are 16196the @samp{@@} at the beginning and the semicolon terminating the 16197directive. When reading the CSS file, it simply copies any such 16198@samp{@@}-directive into the output, as follows: 16199 16200@itemize 16201@item If @var{file} contains only normal CSS declarations, it is 16202included after @command{makeinfo}'s default CSS, thus overriding it. 16203 16204@item If @var{file} begins with @samp{@@import} specifications (see 16205below), then the @samp{import}'s are included first (they have to come 16206first, according to the standard), and then @command{makeinfo}'s 16207default CSS is included. If you need to override @command{makeinfo}'s 16208defaults from an @samp{@@import}, you can do so with the @samp{!@: 16209important} CSS construct, as in: 16210@example 16211pre.smallexample @{ font-size: inherit ! important @} 16212@end example 16213 16214@item If @var{file} contains both @samp{@@import} and inline CSS 16215specifications, the @samp{@@import}'s are included first, then 16216@command{makeinfo}'s defaults, and lastly the inline CSS from 16217@var{file}. 16218 16219@item Any @@-directive other than @samp{@@import} and @samp{@@charset} 16220is treated as a CSS declaration, meaning @command{makeinfo} includes 16221its default CSS and then the rest of the file. 16222 16223@end itemize 16224 16225If the CSS file is malformed or erroneous, @command{makeinfo}'s output 16226is unspecified. @command{makeinfo} does not try to interpret the 16227meaning of the CSS file in any way; it just looks for the special 16228@samp{@@} and @samp{;} characters and blindly copies the text into the 16229output. Comments in the CSS file may or may not be included in the 16230output. 16231 16232 16233@node HTML Xref 16234@section HTML Cross-references 16235@cindex HTML cross-references 16236@cindex Cross-references, in HTML output 16237 16238Cross-references between Texinfo manuals in HTML format amount, in the 16239end, to a standard HTML @code{<a>} link, but the details are 16240unfortunately complex. This section describes the algorithm used in 16241detail, so that Texinfo can cooperate with other programs, such as 16242@command{texi2html}, by writing mutually compatible HTML files. 16243 16244This algorithm may or may not be used for links @emph{within} HTML 16245output for a Texinfo file. Since no issues of compatibility arise in 16246such cases, we do not need to specify this. 16247 16248We try to support references to such ``external'' manuals in both 16249monolithic and split forms. A @dfn{monolithic} (mono) manual is 16250entirely contained in one file, and a @dfn{split} manual has a file 16251for each node. (@xref{HTML Splitting}.) 16252 16253@cindex Dumas, Patrice 16254Acknowledgement: this algorithm was primarily devised by Patrice Dumas 16255in 2003--04. 16256 16257@menu 16258* Link Basics: HTML Xref Link Basics. 16259* Node Expansion: HTML Xref Node Name Expansion. 16260* Command Expansion: HTML Xref Command Expansion. 16261* 8-bit Expansion: HTML Xref 8-bit Character Expansion. 16262* Mismatch: HTML Xref Mismatch. 16263@end menu 16264 16265 16266@node HTML Xref Link Basics 16267@subsection HTML Cross-reference Link Basics 16268@cindex HTML cross-reference link basics 16269 16270For our purposes, an HTML link consists of four components: a host 16271name, a directory part, a file part, and a target part. We 16272always assume the @code{http} protocol. For example: 16273 16274@example 16275http://@var{host}/@var{dir}/@var{file}.html#@var{target} 16276@end example 16277 16278The information to construct a link comes from the node name and 16279manual name in the cross-reference command in the Texinfo source 16280(@pxref{Cross References}), and from @dfn{external information}, which 16281is currently simply hardwired. In the future, it may come from an 16282external data file. 16283 16284We now consider each part in turn. 16285 16286The @var{host} is hardwired to be the local host. This could either 16287be the literal string @samp{localhost}, or, according to the rules for 16288HTML links, the @samp{http://localhost/} could be omitted entirely. 16289 16290The @var{dir} and @var{file} parts are more complicated, and depend on 16291the relative split/mono nature of both the manual being processed and 16292the manual that the cross-reference refers to. The underlying idea is 16293that there is one directory for Texinfo manuals in HTML, and each 16294manual is either available as a monolithic file @file{manual.html}, or a 16295split subdirectory @file{manual/*.html}. Here are the cases: 16296 16297@itemize @bullet 16298@item 16299If the present manual is split, and the referent manual is also split, 16300the directory is @samp{../@var{referent/}} and the file is the 16301expanded node name (described later). 16302 16303@item 16304If the present manual is split, and the referent manual is mono, the 16305directory is @samp{../} and the file is @file{@var{referent}.html}. 16306 16307@item 16308If the present manual is mono, and the referent manual is split, the 16309directory is @file{@var{referent}/} and the file is the expanded node 16310name. 16311 16312@item 16313If the present manual is mono, and the referent manual is also mono, 16314the directory is @file{./} (or just the empty string), and the file is 16315@file{@var{referent}.html}. 16316 16317@end itemize 16318 16319One exception: the algorithm for node name expansion prefixes the 16320string @samp{g_t} when the node name begins with a non-letter. This 16321kludge (due to XHTML rules) is not necessary for filenames, and is 16322therefore omitted. 16323 16324Any directory part in the filename argument of the source 16325cross-reference command is ignored. Thus, @code{@@xref@{,,,../foo@}} 16326and @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name. 16327This is because any such attempted hardwiring of the directory is very 16328unlikely to be useful for both Info and HTML output. 16329 16330Finally, the @var{target} part is always the expanded node name. 16331 16332Whether the present manual is split or mono is determined by user 16333option; @command{makeinfo} defaults to split, with the 16334@option{--no-split} option overriding this. 16335 16336Whether the referent manual is split or mono is another bit of the 16337external information. For now, @command{makeinfo} simply assumes the 16338referent manual is the same as the present manual. 16339 16340There can be a mismatch between the format of the referent manual that 16341the generating software assumes, and the format it's actually present 16342in. @xref{HTML Xref Mismatch}. 16343 16344 16345@node HTML Xref Node Name Expansion 16346@subsection HTML Cross-reference Node Name Expansion 16347@cindex HTML cross-reference node name expansion 16348@cindex node name expansion, in HTML cross-references 16349@cindex expansion, of node names in HTML cross-references 16350 16351As mentioned in the previous section, the key part of the HTML 16352cross-reference algorithm is the conversion of node names in the 16353Texinfo source into strings suitable for XHTML identifiers and 16354filenames. The restrictions are similar for each: plain ASCII 16355letters, numbers, and the @samp{-} and @samp{_} characters are all 16356that can be used. (Although HTML anchors can contain most characters, 16357XHTML is more restrictive.) 16358 16359Cross-references in Texinfo can actually refer either to nodes or 16360anchors (@pxref{anchor}), but anchors are treated identically to nodes 16361in this context, so we'll continue to say ``node'' names for 16362simplicity. 16363 16364(@@-commands and 8-bit characters are not presently handled by 16365@command{makeinfo} for HTML cross-references. See the next section.) 16366 16367A special exception: the Top node (@pxref{The Top Node}) is always 16368mapped to the file @file{index.html}, to match web server software. 16369However, the HTML @emph{target} is @samp{Top}. Thus (in the split case): 16370 16371@example 16372@@xref@{Top, Introduction,, emacs, The GNU Emacs Manual@}. 16373@result{} <a href="emacs/index.html#Top"> 16374@end example 16375 16376@enumerate 16377@item 16378The standard ASCII letters (a-z and A-Z) are not modified. All other 16379characters are changed as specified below. 16380 16381@item 16382The standard ASCII numbers (0-9) are not modified except when a number 16383is the first character of the node name. In that case, see below. 16384 16385@item 16386Multiple consecutive space, tab and newline characters are transformed 16387into just one space. (It's not possible to have newlines in node 16388names with the current implementation, but we specify it anyway, just 16389in case.) 16390 16391@item 16392Leading and trailing spaces are removed. 16393 16394@item 16395After the above has been applied, each remaining space character is 16396converted into a @samp{-} character. 16397 16398@item 16399Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}}, 16400where @var{xx} is the ASCII character code in (lowercase) hexadecimal. 16401This includes @samp{_}, which is mapped to @samp{_005f}. 16402 16403@item 16404If the node name does not begin with a letter, the literal string 16405@samp{g_t} is prefixed to the result. (Due to the rules above, that 16406string can never occur otherwise; it is an arbitrary choice, standing 16407for ``GNU Texinfo''.) This is necessary because XHTML requires that 16408identifiers begin with a letter. 16409 16410@end enumerate 16411 16412For example: 16413 16414@example 16415@@node A node --- with _'% 16416@result{} A-node-_002d_002d_002d-with-_005f_0027_0025 16417@end example 16418 16419Notice in particular: 16420 16421@itemize @bullet 16422@item @samp{_} @result{} @samp{_005f} 16423@item @samp{-} @result{} @samp{_002d} 16424@item @samp{A node} @result{} @samp{A-node} 16425@end itemize 16426 16427On case-folding computer systems, nodes differing only by case will be 16428mapped to the same file. 16429 16430In particular, as mentioned above, Top always maps to the file 16431@file{index.html}. Thus, on a case-folding system, Top and a node 16432named `Index' will both be written to @file{index.html}. 16433 16434Fortunately, the targets serve to distinguish these cases, since HTML 16435target names are always case-sensitive, independent of operating 16436system. 16437 16438 16439@node HTML Xref Command Expansion 16440@subsection HTML Cross-reference Command Expansion 16441@cindex HTML cross-reference command expansion 16442 16443In standard Texinfo, node names may not contain @@-commands. 16444@command{makeinfo} has an option @option{--commands-in-node-names} 16445which partially supports it (@pxref{Invoking makeinfo}), but it is not 16446robust and not recommended. 16447 16448Thus, @command{makeinfo} also does not fully implement this part of 16449the HTML cross-reference algorithm, but it is documented here for the 16450sake of completeness. 16451 16452First, comments are removed. 16453 16454Next, any @code{@@value} commands (@pxref{set value}) and macro invocations 16455(@pxref{Invoking Macros}) are fully expanded. 16456 16457Then, for the following commands, the command name and braces are removed, 16458the text of the argument is recursively transformed: 16459@example 16460@@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless 16461@@emph @@env @@file @@indicateurl @@kbd @@key 16462@@samp @@sc @@slanted @@strong @@t @@var @@w 16463@end example 16464 16465@noindent For @code{@@sc}, any letters are capitalized. 16466 16467The following commands are replaced by constant text, as shown. If 16468any of these commands have non-empty arguments, as in 16469@code{@@TeX@{bad@}}, it is an error, and the result is unspecified. 16470`(space)' means a space character, `(nothing)' means the empty string, 16471etc. The notation `U+@var{xxxx}' means Unicode code point @var{xxxx}. 16472There are further transformations of many of these expansions for the 16473final file or target name, such as space characters to @samp{-}, etc., 16474according to the other rules. 16475 16476@multitable @columnfractions .3 .5 16477@item @code{@@(newline)} @tab (space) 16478@item @code{@@(space)} @tab (space) 16479@item @code{@@(tab)} @tab (space) 16480@item @code{@@!} @tab @samp{!} 16481@item @code{@@*} @tab (space) 16482@item @code{@@-} @tab (nothing) 16483@item @code{@@.} @tab @samp{.} 16484@item @code{@@:} @tab (nothing) 16485@item @code{@@?} @tab @samp{?} 16486@item @code{@@@@} @tab @samp{@@} 16487@item @code{@@@{} @tab @samp{@{} 16488@item @code{@@@}} @tab @samp{@}} 16489@item @code{@@LaTeX} @tab @samp{LaTeX} 16490@item @code{@@TeX} @tab @samp{TeX} 16491@item @code{@@bullet} @tab U+2022 16492@item @code{@@comma} @tab @samp{,} 16493@item @code{@@copyright} @tab U+00A9 16494@item @code{@@dots} @tab U+2026 16495@item @code{@@enddots} @tab @samp{...} 16496@item @code{@@equiv} @tab U+2261 16497@item @code{@@error} @tab @samp{error-->} 16498@item @code{@@euro} @tab U+20AC 16499@item @code{@@exclamdown} @tab U+00A1 16500@item @code{@@expansion} @tab U+2192 16501@item @code{@@minus} @tab U+2212 16502@item @code{@@ordf} @tab U+00AA 16503@item @code{@@ordm} @tab U+00BA 16504@item @code{@@point} @tab U+2217 16505@item @code{@@pounds} @tab U+00A3 16506@item @code{@@print} @tab @samp{-|} 16507@item @code{@@questiondown} @tab U+00BF 16508@item @code{@@registeredsymbol} @tab U+00AE 16509@item @code{@@result} @tab U+21D2 16510@item @code{@@tie} @tab (space) 16511@end multitable 16512 16513An @code{@@acronym} or @code{@@abbr} command is replaced by the first 16514argument, followed by the second argument in parentheses, if present. 16515@xref{acronym}. 16516 16517An @code{@@email} command is replaced by the @var{text} argument if 16518present, else the address. @xref{email}. 16519 16520An @code{@@image} command is replaced by the filename (first) 16521argument. @xref{Images}. 16522 16523A @code{@@verb} command is replaced by its transformed argument. 16524@xref{verb}. 16525 16526Any other command is an error, and the result is unspecified. 16527 16528 16529@node HTML Xref 8-bit Character Expansion 16530@subsection HTML Cross-reference 8-bit Character Expansion 16531@cindex HTML cross-reference 8-bit character expansion 16532@cindex 8-bit characters, in HTML cross-references 16533@cindex Expansion of 8-bit characters in HTML cross-references 16534 16535Usually, characters other than plain 7-bit ASCII are transformed into 16536the corresponding Unicode code point(s) in Normalization Form C, which 16537uses precomposed characters where available. (This is the 16538normalization form recommended by the W3C and other bodies.) This 16539holds when that code point is 0xffff or less, as it almost always is. 16540 16541These will then be further transformed by the rules above into the 16542string @samp{_@var{xxxx}}, where @var{xxxx} is the code point in hex. 16543 16544For example, combining this rule and the previous section: 16545 16546@example 16547@@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@} 16548@result{} A-TeX-B_0306-_2605_002e_002e_002e 16549@end example 16550 16551Notice: 1)@tie{}@code{@@enddots} expands to three periods which in 16552turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B' 16553with a breve accent, which does not exist as a pre-accented Unicode 16554character, therefore expands to @samp{B_0306} (B with combining 16555breve). 16556 16557When the Unicode code point is above 0xffff, the transformation is 16558@samp{__@var{xxxxxx}}, that is, two leading underscores followed by 16559six hex digits. Since Unicode has declared that their highest code 16560point is 0x10ffff, this is sufficient. (We felt it was better to 16561define this extra escape than to always use six hex digits, since the 16562first two would nearly always be zeros.) 16563 16564For the definition of Unicode Normalization Form C, see Unicode report 16565UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many related 16566documents and implementations are available elsewhere on the web. 16567 16568 16569@node HTML Xref Mismatch 16570@subsection HTML Cross-reference Mismatch 16571@cindex HTML cross-reference mismatch 16572@cindex Mismatched HTML cross-reference source and target 16573 16574As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating 16575software has to guess whether a given manual being cross-referenced is 16576available in split or monolithic form---and, inevitably, it might 16577guess wrong. However, it is possible when the referent manual itself 16578is generated, it is possible to handle at least some mismatches. 16579 16580In the case where we assume the referent is split, but it is actually 16581available in mono, the only recourse would be to generate a 16582@file{manual/} subdirectory full of HTML files which redirect back to 16583the monolithic @file{manual.html}. Since this is essentially the same 16584as a split manual in the first place, it's not very appealing. 16585 16586On the other hand, in the case where we assume the referent is mono, 16587but it is actually available in split, it is possible to use 16588JavaScript to redirect from the putatively monolithic 16589@file{manual.html} to the different @file{manual/node.html} files. 16590Here's an example: 16591 16592@example 16593function redirect() @{ 16594 switch (location.hash) @{ 16595 case "#Node1": 16596 location.replace("manual/Node1.html#Node1"); break; 16597 case "#Node2" : 16598 location.replace("manual/Node2.html#Node2"); break; 16599 @dots{} 16600 default:; 16601 @} 16602@} 16603@end example 16604 16605Then, in the @code{<body>} tag of @file{manual.html}: 16606 16607@example 16608<body onLoad="redirect();"> 16609@end example 16610 16611Once again, this is something the software which generated the 16612@emph{referent} manual has to do in advance, it's not something the 16613software generating the actual cross-reference in the present manual 16614can control. 16615 16616Ultimately, we hope to allow for an external configuration file to 16617control which manuals are available from where, and how. 16618 16619 16620@ignore 16621-- not yet -- 16622 16623external information 16624-------------------- 16625 16626The information for the reference is searched in the file 16627`htmlxref.cnf' present in the following directories: 16628<srcdir>/.texinfo/, ~/.texinfo/, SYSCONFDIR/texinfo/, 16629DATADIR/texinfo/ 16630The first match should be used. 16631 16632The file is line-oriented, with the following format: 16633 <manualname> <whitespace> <keyword> <whitespace> <urlprefix> 16634with <keyword> being "mono" or "split". Thus 16635texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/ 16636texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html 16637 16638If the keyword is 'split', that is the target is split, the urlprefix gives 16639the directory and host name. 16640If the keyword is 'mono', that is the target is mono, the urlprefix gives 16641directory, host and file name. 16642 16643'#' followed by a space begins comments. '#' followed by another character 16644cannot begin comments as there are # in urls. 16645 16646@end ignore 16647 16648 16649@node Command List 16650@appendix @@-Command List 16651@cindex Alphabetical @@-command list 16652@cindex List of @@-commands 16653@cindex @@-command list 16654@cindex Reference to @@-commands 16655 16656Here is an alphabetical list of the @@-commands in Texinfo. Square 16657brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis, 16658@samp{@dots{}}, indicates repeated text. 16659 16660More specifics on the general syntax of different @@-commands are 16661given in the section below. 16662 16663@menu 16664* Command Syntax:: General syntax for varieties of @@-commands. 16665@end menu 16666 16667@sp 1 16668@table @code 16669@item @@@var{whitespace} 16670An @code{@@} followed by a space, tab, or newline produces a normal, 16671stretchable, interword space. @xref{Multiple Spaces}. 16672 16673@item @@! 16674Generate an exclamation point that really does end a sentence (usually 16675after an end-of-sentence capital letter). @xref{Ending a Sentence}. 16676 16677@item @@" 16678@itemx @@' 16679Generate an umlaut or acute accent, respectively, over the next 16680character, as in @"o and @'o. @xref{Inserting Accents}. 16681 16682@item @@* 16683Force a line break. @xref{Line Breaks}. 16684 16685@item @@,@{@var{c}@} 16686Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting 16687Accents}. 16688 16689@item @@- 16690Insert a discretionary hyphenation point. @xref{- and hyphenation}. 16691 16692@item @@. 16693Produce a period that really does end a sentence (usually after an 16694end-of-sentence capital letter). @xref{Ending a Sentence}. 16695 16696@item @@/ 16697Produces no output, but allows a line break. @xref{Line Breaks}. 16698 16699@item @@: 16700Indicate to @TeX{} that an immediately preceding period, question 16701mark, exclamation mark, or colon does not end a sentence. Prevent 16702@TeX{} from inserting extra whitespace as it does at the end of a 16703sentence. The command has no effect on the Info file output. 16704@xref{Not Ending a Sentence}. 16705 16706@item @@= 16707Generate a macron (bar) accent over the next character, as in @=o. 16708@xref{Inserting Accents}. 16709 16710@item @@? 16711Generate a question mark that really does end a sentence (usually after 16712an end-of-sentence capital letter). @xref{Ending a Sentence}. 16713 16714@item @@@@ 16715Stands for an at sign, @samp{@@}. 16716@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. 16717 16718@item @@\ 16719Stands for a backslash (@samp{\}) inside @code{@@math}. 16720@xref{math,,@code{math}}. 16721 16722@item @@^ 16723@itemx @@` 16724Generate a circumflex (hat) or grave accent, respectively, over the next 16725character, as in @^o and @`e. 16726@xref{Inserting Accents}. 16727 16728@item @@@{ 16729Stands for a left brace, @samp{@{}. 16730@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. 16731 16732@item @@@} 16733Stands for a right-hand brace, @samp{@}}.@* 16734@xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}. 16735 16736@item @@~ 16737Generate a tilde accent over the next character, as in @~N. 16738@xref{Inserting Accents}. 16739 16740@item @@AA@{@} 16741@itemx @@aa@{@} 16742Generate the uppercase and lowercase Scandinavian A-ring letters, 16743respectively: @AA{}, @aa{}. @xref{Inserting Accents}. 16744 16745@item @@abbr@{@var{abbreviation}@} 16746Tag @var{abbreviation} as an abbreviation, such as `Comput.'. 16747@xref{abbr,, @code{abbr}}. 16748 16749@item @@acronym@{@var{acronym}@} 16750Tag @var{acronym} as an acronym, such as `NASA'. 16751@xref{acronym,, @code{acronym}}. 16752 16753@item @@AE@{@} 16754@itemx @@ae@{@} 16755Generate the uppercase and lowercase AE ligatures, respectively: 16756@AE{}, @ae{}. @xref{Inserting Accents}. 16757 16758@itemx @@afivepaper 16759Change page dimensions for the A5 paper size. @xref{A4 Paper}. 16760 16761@item @@afourlatex 16762@itemx @@afourpaper 16763@itemx @@afourwide 16764Change page dimensions for the A4 paper size. @xref{A4 Paper}. 16765 16766@item @@alias @var{new}=@var{existing} 16767Make the command @samp{@@@var{new}} an alias for the existing command 16768@samp{@@@var{existing}}. @xref{alias}. 16769 16770@item @@anchor@{@var{name}@} 16771Define @var{name} as the current location for use as a cross-reference 16772target. @xref{anchor,, @code{@@anchor}}. 16773 16774@item @@appendix @var{title} 16775Begin an appendix. The title appears in the table 16776of contents of a printed manual. In Info, the title is 16777underlined with asterisks. @xref{unnumbered & appendix, , The 16778@code{@@unnumbered} and @code{@@appendix} Commands}.@refill 16779 16780@item @@appendixsec @var{title} 16781@itemx @@appendixsection @var{title} 16782Begin an appendix section within an appendix. The section title appears 16783in the table of contents of a printed manual. In Info, the title is 16784underlined with equal signs. @code{@@appendixsection} is a longer 16785spelling of the @code{@@appendixsec} command. @xref{unnumberedsec 16786appendixsec heading, , Section Commands}.@refill 16787 16788@item @@appendixsubsec @var{title} 16789Begin an appendix subsection within an appendix. The title appears 16790in the table of contents of a printed manual. In Info, the title is 16791underlined with hyphens. @xref{unnumberedsubsec appendixsubsec 16792subheading, , Subsection Commands}.@refill 16793 16794@item @@appendixsubsubsec @var{title} 16795Begin an appendix subsubsection within an appendix subsection. The 16796title appears in the table of contents of a printed manual. In Info, 16797the title is underlined with periods. @xref{subsubsection,, The 16798`subsub' Commands}.@refill 16799 16800@item @@asis 16801Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to 16802print the table's first column without highlighting (``as is''). 16803@xref{Two-column Tables, , Making a Two-column Table}.@refill 16804 16805@item @@author @var{author} 16806Typeset @var{author} flushleft and underline it. @xref{title 16807subtitle author, , The @code{@@title} and @code{@@author} 16808Commands}.@refill 16809 16810@item @@b@{@var{text}@} 16811Print @var{text} in @b{bold} font. No effect in Info. @xref{Fonts}.@refill 16812 16813@ignore 16814@item @@br 16815Force a paragraph break. If used within a line, follow @code{@@br} 16816with braces. @xref{br, , @code{@@br}}.@refill 16817@end ignore 16818 16819@item @@bullet@{@} 16820Generate a large round dot, or the closest possible 16821thing to one. @xref{bullet, , @code{@@bullet}}.@refill 16822 16823@item @@bye 16824Stop formatting a file. The formatters do not see the contents of a 16825file following an @code{@@bye} command. @xref{Ending a File}.@refill 16826 16827@item @@c @var{comment} 16828Begin a comment in Texinfo. The rest of the line does not appear in 16829either the Info file or the printed manual. A synonym for 16830@code{@@comment}. @xref{Comments}. 16831 16832@item @@caption 16833Define the full caption for a @code{@@float}. @xref{caption shortcaption}. 16834 16835@item @@cartouche 16836Highlight an example or quotation by drawing a box with rounded 16837corners around it. Pair with @code{@@end cartouche}. No effect in 16838Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill 16839 16840@item @@center @var{line-of-text} 16841Center the line of text following the command. 16842@xref{titlefont center sp, , @code{@@center}}.@refill 16843 16844@item @@centerchap @var{line-of-text} 16845Like @code{@@chapter}, but centers the chapter title. @xref{chapter,, 16846@code{@@chapter}}. 16847 16848@item @@chapheading @var{title} 16849Print a chapter-like heading in the text, but not in the table of 16850contents of a printed manual. In Info, the title is underlined with 16851asterisks. @xref{majorheading & chapheading, , @code{@@majorheading} 16852and @code{@@chapheading}}.@refill 16853 16854@item @@chapter @var{title} 16855Begin a chapter. The chapter title appears in the table of 16856contents of a printed manual. In Info, the title is underlined with 16857asterisks. @xref{chapter, , @code{@@chapter}}.@refill 16858 16859@item @@cindex @var{entry} 16860Add @var{entry} to the index of concepts. @xref{Index Entries, , 16861Defining the Entries of an Index}.@refill 16862 16863@item @@cite@{@var{reference}@} 16864Highlight the name of a book or other reference that lacks a 16865companion Info file. @xref{cite, , @code{@@cite}}.@refill 16866 16867@item @@clear @var{flag} 16868Unset @var{flag}, preventing the Texinfo formatting commands from 16869formatting text between subsequent pairs of @code{@@ifset @var{flag}} 16870and @code{@@end ifset} commands, and preventing 16871@code{@@value@{@var{flag}@}} from expanding to the value to which 16872@var{flag} is set. 16873@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 16874 16875@item @@code@{@var{sample-code}@} 16876Highlight text that is an expression, a syntactically complete token 16877of a program, or a program name. @xref{code, , @code{@@code}}.@refill 16878 16879@item @@comma@{@} 16880Insert a comma `,' character; only needed when a literal comma would 16881be taken as an argument separator. @xref{Inserting a Comma}. 16882 16883@item @@command@{@var{command-name}@} 16884Indicate a command name, such as @command{ls}. 16885@xref{command,, @code{@@command}}. 16886 16887@item @@comment @var{comment} 16888Begin a comment in Texinfo. The rest of the line does not appear in 16889either the Info file or the printed manual. A synonym for @code{@@c}. 16890@xref{Comments}. 16891 16892@item @@contents 16893Print a complete table of contents. Has no effect in Info, which uses 16894menus instead. @xref{Contents, , Generating a Table of 16895Contents}.@refill 16896 16897@item @@copyright@{@} 16898Generate the copyright symbol @copyright{}. @xref{copyright symbol,, 16899@code{@@copyright@{@}}}. 16900 16901@ignore 16902@item @@ctrl@{@var{ctrl-char}@} 16903Describe an @sc{ascii} control character. Insert actual control character 16904into Info file. @xref{ctrl, , @code{@@ctrl}}.@refill 16905@end ignore 16906 16907@item @@defcodeindex @var{index-name} 16908Define a new index and its indexing command. Print entries in an 16909@code{@@code} font. @xref{New Indices, , Defining New 16910Indices}.@refill 16911 16912@item @@defcv @var{category} @var{class} @var{name} 16913@itemx @@defcvx @var{category} @var{class} @var{name} 16914Format a description for a variable associated with a class in 16915object-oriented programming. Takes three arguments: the category of 16916thing being defined, the class to which it belongs, and its name. 16917@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. 16918 16919@item @@deffn @var{category} @var{name} @var{arguments}@dots{} 16920@itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{} 16921Format a description for a function, interactive command, or similar 16922entity that may take arguments. @code{@@deffn} takes as arguments the 16923category of entity being described, the name of this particular 16924entity, and its arguments, if any. @xref{Definition Commands}.@refill 16925 16926@item @@defindex @var{index-name} 16927Define a new index and its indexing command. Print entries in a roman 16928font. @xref{New Indices, , Defining New Indices}.@refill 16929 16930@item @@definfoenclose @var{newcmd}, @var{before}, @var{after}, 16931Create new @@-command @var{newcmd} for Info that marks text by enclosing 16932it in strings that precede and follow the text. @xref{definfoenclose}. 16933 16934@item @@defivar @var{class} @var{instance-variable-name} 16935@itemx @@defivarx @var{class} @var{instance-variable-name} 16936This command formats a description for an instance variable in 16937object-oriented programming. The command is equivalent to @samp{@@defcv 16938@{Instance Variable@} @dots{}}. @xref{Definition Commands}, and 16939@ref{deffnx,, Def Cmds in Detail}. 16940 16941@item @@defmac @var{macroname} @var{arguments}@dots{} 16942@itemx @@defmacx @var{macroname} @var{arguments}@dots{} 16943Format a description for a macro. The command is equivalent to 16944@samp{@@deffn Macro @dots{}}. @xref{Definition Commands}, and 16945@ref{deffnx,, Def Cmds in Detail}. 16946 16947@item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{} 16948@itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{} 16949Format a description for a method in object-oriented programming. The 16950command is equivalent to @samp{@@defop Method @dots{}}. Takes as 16951arguments the name of the class of the method, the name of the 16952method, and its arguments, if any. @xref{Definition Commands}, and 16953@ref{deffnx,, Def Cmds in Detail}. 16954 16955@item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{} 16956@itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{} 16957Format a description for an operation in object-oriented programming. 16958@code{@@defop} takes as arguments the overall name of the category of 16959operation, the name of the class of the operation, the name of the 16960operation, and its arguments, if any. @xref{Definition 16961Commands}, and @ref{Abstract Objects}. 16962 16963@item @@defopt @var{option-name} 16964@itemx @@defoptx @var{option-name} 16965Format a description for a user option. The command is equivalent to 16966@samp{@@defvr @{User Option@} @dots{}}. @xref{Definition Commands}, and 16967@ref{deffnx,, Def Cmds in Detail}. 16968 16969@item @@defspec @var{special-form-name} @var{arguments}@dots{} 16970@itemx @@defspecx @var{special-form-name} @var{arguments}@dots{} 16971Format a description for a special form. The command is equivalent to 16972@samp{@@deffn @{Special Form@} @dots{}}. @xref{Definition Commands}, 16973and @ref{deffnx,, Def Cmds in Detail}. 16974 16975@item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{} 16976@itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{} 16977Format a description for a data type. @code{@@deftp} takes as arguments 16978the category, the name of the type (which is a word like @samp{int} or 16979@samp{float}), and then the names of attributes of objects of that type. 16980@xref{Definition Commands}, and @ref{Data Types}. 16981 16982@item @@deftypecv @var{category} @var{class} @var{data-type} @var{name} 16983@itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name} 16984Format a description for a typed class variable in object-oriented programming. 16985@xref{Definition Commands}, and @ref{Abstract Objects}. 16986 16987@item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} 16988@itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{} 16989Format a description for a function or similar entity that may take 16990arguments and that is typed. @code{@@deftypefn} takes as arguments the 16991classification of entity being described, the type, the name of the 16992entity, and its arguments, if any. @xref{Definition Commands}, and 16993@ref{deffnx,, Def Cmds in Detail}. 16994 16995@item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{} 16996@itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{} 16997Format a description for a function in a typed language. 16998The command is equivalent to @samp{@@deftypefn Function @dots{}}. 16999@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. 17000 17001@item @@deftypeivar @var{class} @var{data-type} @var{variable-name} 17002@itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name} 17003Format a description for a typed instance variable in object-oriented 17004programming. @xref{Definition Commands}, and @ref{Abstract Objects}. 17005 17006@item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} 17007@itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{} 17008Format a description for a typed method in object-oriented programming. 17009@xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}. 17010 17011@item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} 17012@itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{} 17013Format a description for a typed operation in object-oriented programming. 17014@xref{Definition Commands}, and @ref{Abstract Objects}. 17015 17016@item @@deftypevar @var{data-type} @var{variable-name} 17017@itemx @@deftypevarx @var{data-type} @var{variable-name} 17018Format a description for a variable in a typed language. The command is 17019equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition 17020Commands}, and @ref{deffnx,, Def Cmds in Detail}. 17021 17022@item @@deftypevr @var{classification} @var{data-type} @var{name} 17023@itemx @@deftypevrx @var{classification} @var{data-type} @var{name} 17024Format a description for something like a variable in a typed 17025language---an entity that records a value. Takes as arguments the 17026classification of entity being described, the type, and the name of the 17027entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in 17028Detail}. 17029 17030@item @@defun @var{function-name} @var{arguments}@dots{} 17031@itemx @@defunx @var{function-name} @var{arguments}@dots{} 17032Format a description for functions. The command is equivalent to 17033@samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and 17034@ref{deffnx,, Def Cmds in Detail}. 17035 17036@item @@defvar @var{variable-name} 17037@itemx @@defvarx @var{variable-name} 17038Format a description for variables. The command is equivalent to 17039@samp{@@defvr Variable @dots{}}. @xref{Definition Commands}, and 17040@ref{deffnx,, Def Cmds in Detail}. 17041 17042@item @@defvr @var{category} @var{name} 17043@itemx @@defvrx @var{category} @var{name} 17044Format a description for any kind of variable. @code{@@defvr} takes 17045as arguments the category of the entity and the name of the entity. 17046@xref{Definition Commands}, 17047and @ref{deffnx,, Def Cmds in Detail}. 17048 17049@item @@detailmenu 17050Avoid @code{makeinfo} confusion stemming from the detailed node listing 17051in a master menu. @xref{Master Menu Parts}. 17052 17053@item @@dfn@{@var{term}@} 17054Highlight the introductory or defining use of a term. 17055@xref{dfn, , @code{@@dfn}}.@refill 17056 17057@item @@dircategory @var{dirpart} 17058Specify a part of the Info directory menu where this file's entry should 17059go. @xref{Installing Dir Entries}. 17060 17061@item @@direntry 17062Begin the Info directory menu entry for this file. Pair with 17063@code{@@end direntry}. @xref{Installing Dir Entries}. 17064 17065@item @@display 17066Begin a kind of example. Like @code{@@example} (indent text, do not 17067fill), but do not select a new font. Pair with @code{@@end display}. 17068@xref{display, , @code{@@display}}. 17069 17070@item @@dmn@{@var{dimension}@} 17071Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a 17072thin space before @var{dimension}. No effect in Info. 17073@xref{dmn, , @code{@@dmn}}. 17074 17075@item @@docbook 17076Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw 17077Formatter Commands}. 17078 17079@item @@documentdescription 17080Set the document description text, included in the HTML output. Pair 17081with @code{@@end documentdescription}. @xref{documentdescription,, 17082@code{@@documentdescription}}. 17083 17084@item @@documentencoding @var{enc} 17085Declare the input encoding to be @var{enc}. 17086@xref{documentencoding,, @code{@@documentencoding}}. 17087 17088@item @@documentlanguage @var{CC} 17089Declare the document language as the two-character ISO-639 abbreviation 17090@var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}. 17091 17092@item @@dotaccent@{@var{c}@} 17093Generate a dot accent over the character @var{c}, as in @dotaccent{o}. 17094@xref{Inserting Accents}. 17095 17096@item @@dots@{@} 17097Insert an ellipsis: @samp{@dots{}}. 17098@xref{dots, , @code{@@dots}}.@refill 17099 17100@item @@email@{@var{address}[, @var{displayed-text}]@} 17101Indicate an electronic mail address. 17102@xref{email, , @code{@@email}}. 17103 17104@item @@emph@{@var{text}@} 17105Highlight @var{text}; text is displayed in @emph{italics} in printed 17106output, and surrounded by asterisks in Info. @xref{Emphasis, , 17107Emphasizing Text}. 17108 17109@item @@end @var{environment} 17110Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting 17111Commands,,@@-commands}. 17112 17113@item @@env@{@var{environment-variable}@} 17114Indicate an environment variable name, such as @env{PATH}. 17115@xref{env,, @code{@@env}}. 17116 17117@item @@enddots@{@} 17118Generate an end-of-sentence of ellipsis, like this @enddots{} 17119@xref{dots,,@code{@@dots@{@}}}. 17120 17121@item @@enumerate [@var{number-or-letter}] 17122Begin a numbered list, using @code{@@item} for each entry. 17123Optionally, start list with @var{number-or-letter}. Pair with 17124@code{@@end enumerate}. @xref{enumerate, , 17125@code{@@enumerate}}.@refill 17126 17127@item @@equiv@{@} 17128Indicate to the reader the exact equivalence of two forms with a 17129glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill 17130 17131@item @@euro@{@} 17132Generate the Euro currency sign. 17133@xref{euro,,@code{@@euro@{@}}}. 17134 17135@item @@error@{@} 17136Indicate to the reader with a glyph that the following text is 17137an error message: @samp{@error{}}. @xref{Error Glyph}.@refill 17138 17139@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 17140@itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 17141Specify page footings resp.@: headings for even-numbered (left-hand) 17142pages. @xref{Custom Headings, , 17143How to Make Your Own Headings}.@refill 17144 17145@item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 17146@itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 17147Specify page footings resp.@: headings for every page. Not relevant to 17148Info. @xref{Custom Headings, , How to Make Your Own Headings}.@refill 17149 17150@item @@example 17151Begin an example. Indent text, do not fill, and select fixed-width font. 17152Pair with @code{@@end example}. @xref{example, , 17153@code{@@example}}.@refill 17154 17155@item @@exampleindent @var{indent} 17156Indent example-like environments by @var{indent} number of spaces 17157(perhaps 0). @xref{exampleindent,, Paragraph Indenting}. 17158 17159@item @@exclamdown@{@} 17160Produce an upside-down exclamation point. @xref{Inserting Accents}. 17161 17162@item @@exdent @var{line-of-text} 17163Remove any indentation a line might have. @xref{exdent, , 17164Undoing the Indentation of a Line}.@refill 17165 17166@item @@expansion@{@} 17167Indicate the result of a macro expansion to the reader with a special 17168glyph: @samp{@expansion{}}. 17169@xref{expansion, , @expansion{} Indicating an Expansion}.@refill 17170 17171@item @@file@{@var{filename}@} 17172Highlight the name of a file, buffer, node, or directory. @xref{file, , 17173@code{@@file}}.@refill 17174 17175@item @@finalout 17176Prevent @TeX{} from printing large black warning rectangles beside 17177over-wide lines. @xref{Overfull hboxes}.@refill 17178 17179@item @@findex @var{entry} 17180Add @var{entry} to the index of functions. @xref{Index Entries, , 17181Defining the Entries of an Index}.@refill 17182 17183@item @@float 17184Environment to define floating material. Pair with @code{@@end float}. 17185@xref{Floats}. 17186 17187@item @@flushleft 17188@itemx @@flushright 17189Left justify every line but leave the right end ragged. 17190Leave font as is. Pair with @code{@@end flushleft}. 17191@code{@@flushright} analogous. 17192@xref{flushleft & flushright, , @code{@@flushleft} and 17193@code{@@flushright}}.@refill 17194 17195@item @@footnote@{@var{text-of-footnote}@} 17196Enter a footnote. Footnote text is printed at the bottom of the page 17197by @TeX{}; Info may format in either `End' node or `Separate' node style. 17198@xref{Footnotes}.@refill 17199 17200@item @@footnotestyle @var{style} 17201Specify an Info file's footnote style, either @samp{end} for the end 17202node style or @samp{separate} for the separate node style. 17203@xref{Footnotes}.@refill 17204 17205@item @@format 17206Begin a kind of example. Like @code{@@display}, but do not narrow the 17207margins. Pair with @code{@@end format}. @xref{example,, 17208@code{@@example}}. 17209 17210@item @@ftable @var{formatting-command} 17211Begin a two-column table, using @code{@@item} for each entry. 17212Automatically enter each of the items in the first column into the 17213index of functions. Pair with @code{@@end ftable}. The same as 17214@code{@@table}, except for indexing. @xref{ftable vtable, , 17215@code{@@ftable} and @code{@@vtable}}.@refill 17216 17217@item @@group 17218Hold text together that must appear on one printed page. Pair with 17219@code{@@end group}. Not relevant to Info. @xref{group, , 17220@code{@@group}}.@refill 17221 17222@item @@H@{@var{c}@} 17223Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}. 17224 17225@item @@heading @var{title} 17226Print an unnumbered section-like heading in the text, but not in the 17227table of contents of a printed manual. In Info, the title is 17228underlined with equal signs. @xref{unnumberedsec appendixsec heading, 17229, Section Commands}.@refill 17230 17231@item @@headings @var{on-off-single-double} 17232Turn page headings on or off, and/or specify single-sided or double-sided 17233page headings for printing. @xref{headings on off, , The 17234@code{@@headings} Command}. 17235 17236@item @@html 17237Enter HTML completely. Pair with @code{@@end html}. @xref{Raw 17238Formatter Commands}. 17239 17240@item @@hyphenation@{@var{hy-phen-a-ted words}@} 17241Explicitly define hyphenation points. @xref{- and hyphenation,, 17242@code{@@-} and @code{@@hyphenation}}. 17243 17244@item @@i@{@var{text}@} 17245Print @var{text} in @i{italic} font. No effect in Info. @xref{Fonts}. 17246 17247@item @@ifclear @var{flag} 17248If @var{flag} is cleared, the Texinfo formatting commands format text 17249between @code{@@ifclear @var{flag}} and the following @code{@@end 17250ifclear} command. 17251@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 17252 17253@item @@ifdocbook 17254@itemx @@ifhtml 17255@itemx @@ifinfo 17256Begin text that will appear only in the given output format. 17257@code{@@ifinfo} output appears in both Info and (for historical 17258compatibility) plain text output. Pair with @code{@@end ifdocbook} 17259resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}. 17260@xref{Conditionals}. 17261 17262@item @@ifnotdocbook 17263@itemx @@ifnothtml 17264@itemx @@ifnotinfo 17265@itemx @@ifnotplaintext 17266@itemx @@ifnottex 17267@itemx @@ifnotxml 17268Begin a stretch of text that will be ignored in one output format but 17269not the others. The text appears in the formats not specified: 17270@code{@@ifnothtml} text is omitted from html output, etc. The exception 17271is @code{@@ifnotinfo} text, which is omitted from plain text output as 17272well as Info output. Pair with the corresponding @code{@@end 17273ifnot@var{format}}. @xref{Conditionals}. 17274 17275@item @@ifplaintext 17276Begin text that will appear only in the plain text output. 17277Pair with @code{@@end ifplaintext}. @xref{Conditionals}. 17278 17279@item @@ifset @var{flag} 17280If @var{flag} is set, the Texinfo formatting commands format text 17281between @code{@@ifset @var{flag}} and the following @code{@@end ifset} 17282command. 17283@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 17284 17285@item @@iftex 17286Begin text that will not appear in the Info file or other output, but 17287will be processed only by @TeX{}. Pair with @code{@@end iftex}. 17288@xref{Conditionals, , Conditionally Visible Text}.@refill 17289 17290@item @@ifxml 17291Begin text that will appear only in the XML output. Pair with 17292@code{@@end ifxml}. @xref{Conditionals}. 17293 17294@item @@ignore 17295Begin text that will not appear in any output. Pair with @code{@@end 17296ignore}. @xref{Comments, , Comments and Ignored Text}. 17297 17298@item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@} 17299Include graphics image in external @var{filename} scaled to the given 17300@var{width} and/or @var{height}, using @var{alt} text and looking for 17301@samp{@var{filename}.@var{ext}} in HTML. @xref{Images}. 17302 17303@item @@include @var{filename} 17304Incorporate the contents of the file @var{filename} into the Info file 17305or printed document. @xref{Include Files}.@refill 17306 17307@item @@indicateurl@{@var{indicateurl}@} 17308Indicate text that is a uniform resource locator for the World Wide 17309Web. @xref{indicateurl, , @code{@@indicateurl}}. 17310 17311@item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@} 17312Make a cross reference to an Info file for which there is no printed 17313manual. @xref{inforef, , Cross references using 17314@code{@@inforef}}.@refill 17315 17316@item \input @var{macro-definitions-file} 17317Use the specified macro definitions file. This command is used only 17318in the first line of a Texinfo file to cause @TeX{} to make use of the 17319@file{texinfo} macro definitions file. The backslash in @code{\input} 17320is used instead of an @code{@@} because @TeX{} does not 17321recognize @code{@@} until after it has read the definitions file. 17322@xref{Texinfo File Header}. 17323 17324@item @@item 17325Indicate the beginning of a marked paragraph for @code{@@itemize} and 17326@code{@@enumerate}; indicate the beginning of the text of a first column 17327entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}. 17328@xref{Lists and Tables}.@refill 17329 17330@item @@itemize @var{mark-generating-character-or-command} 17331Produce a sequence of indented paragraphs, with a mark inside the left 17332margin at the beginning of each paragraph. Pair with @code{@@end 17333itemize}. @xref{itemize, , @code{@@itemize}}.@refill 17334 17335@item @@itemx 17336Like @code{@@item} but do not generate extra vertical space above the 17337item text. @xref{itemx, , @code{@@itemx}}.@refill 17338 17339@item @@kbd@{@var{keyboard-characters}@} 17340Indicate text that is characters of input to be typed by 17341users. @xref{kbd, , @code{@@kbd}}.@refill 17342 17343@item @@kbdinputstyle @var{style} 17344Specify when @code{@@kbd} should use a font distinct from @code{@@code}. 17345@xref{kbd, , @code{@@kbd}}.@refill 17346 17347@item @@key@{@var{key-name}@} 17348Indicate a name for a key on a keyboard. 17349@xref{key, , @code{@@key}}.@refill 17350 17351@item @@kindex @var{entry} 17352Add @var{entry} to the index of keys. 17353@xref{Index Entries, , Defining the Entries of an Index}.@refill 17354 17355@item @@L@{@} 17356@itemx @@l@{@} 17357Generate the uppercase and lowercase Polish suppressed-L letters, 17358respectively: @L{}, @l{}. 17359 17360@item @@LaTeX@{@} 17361Insert the logo @LaTeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. 17362 17363@item @@lisp 17364Begin an example of Lisp code. Indent text, do not fill, and select 17365fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}. 17366 17367@item @@listoffloats 17368Produce a table-of-contents-like listing of @code{@@float}s. 17369@xref{listoffloats}. 17370 17371@item @@lowersections 17372Change subsequent chapters to sections, sections to subsections, and so 17373on. @xref{Raise/lower sections, , @code{@@raisesections} and 17374@code{@@lowersections}}.@refill 17375 17376@item @@macro @var{macroname} @{@var{params}@} 17377Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}. 17378Only supported by @code{makeinfo} and @code{texi2dvi}. @xref{Defining 17379Macros}. 17380 17381@item @@majorheading @var{title} 17382Print a chapter-like heading in the text, but not in the table of 17383contents of a printed manual. Generate more vertical whitespace before 17384the heading than the @code{@@chapheading} command. @xref{majorheading & 17385chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill 17386 17387@item @@math@{@var{mathematical-expression}@} 17388Format a mathematical expression. 17389@xref{math, , @code{@@math}: Inserting Mathematical Expressions}. 17390 17391@item @@menu 17392Mark the beginning of a menu of nodes in Info. No effect in a printed 17393manual. Pair with @code{@@end menu}. @xref{Menus}.@refill 17394 17395@item @@minus@{@} 17396Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.@refill 17397 17398@item @@multitable @var{column-width-spec} 17399Begin a multi-column table. Pair with @code{@@end multitable}. 17400@xref{Multitable Column Widths}. 17401 17402@item @@need @var{n} 17403Start a new page in a printed manual if fewer than @var{n} mils 17404(thousandths of an inch) remain on the current page. @xref{need, , 17405@code{@@need}}.@refill 17406 17407@item @@node @var{name}, @var{next}, @var{previous}, @var{up} 17408Define the beginning of a new node in Info, and serve as a locator for 17409references for @TeX{}. @xref{node, , @code{@@node}}.@refill 17410 17411@item @@noindent 17412Prevent text from being indented as if it were a new paragraph. 17413@xref{noindent, , @code{@@noindent}}.@refill 17414 17415@item @@novalidate 17416Suppress validation of node references, omit creation of auxiliary files 17417with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer Validation}. 17418 17419@item @@O@{@} 17420@itemx @@o@{@} 17421Generate the uppercase and lowercase O-with-slash letters, respectively: 17422@O{}, @o{}. 17423 17424@item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 17425@itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}] 17426Specify page footings resp.@: headings for odd-numbered (right-hand) 17427pages. @xref{Custom Headings, , 17428How to Make Your Own Headings}.@refill 17429 17430@item @@OE@{@} 17431@itemx @@oe@{@} 17432Generate the uppercase and lowercase OE ligatures, respectively: 17433@OE{}, @oe{}. @xref{Inserting Accents}. 17434 17435@item @@option@{@var{option-name}@} 17436Indicate a command-line option, such as @option{-l} or @option{--help}. 17437@xref{option,, @code{@@option}}. 17438 17439@item @@page 17440Start a new page in a printed manual. No effect in Info. 17441@xref{page, , @code{@@page}}.@refill 17442 17443@item @@pagesizes [@var{width}][, @var{height}] 17444Change page dimensions. @xref{pagesizes}. 17445 17446@item @@paragraphindent @var{indent} 17447Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve 17448source file indentation if @var{indent} is @code{asis}. 17449@xref{paragraphindent,, Paragraph Indenting}. 17450 17451@item @@pindex @var{entry} 17452Add @var{entry} to the index of programs. @xref{Index Entries, , Defining 17453the Entries of an Index}.@refill 17454 17455@item @@point@{@} 17456Indicate the position of point in a buffer to the reader with a 17457glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating 17458Point in a Buffer}.@refill 17459 17460@item @@pounds@{@} 17461Generate the pounds sterling currency sign. 17462@xref{pounds,,@code{@@pounds@{@}}}. 17463 17464@item @@print@{@} 17465Indicate printed output to the reader with a glyph: 17466@samp{@print{}}. @xref{Print Glyph}.@refill 17467 17468@item @@printindex @var{index-name} 17469Print an alphabetized two-column index in a printed manual or generate 17470an alphabetized menu of index entries for Info. @xref{Printing 17471Indices & Menus}.@refill 17472 17473@item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} 17474Make a reference that starts with a lower case `see' in a printed 17475manual. Use within parentheses only. Do not follow command with a 17476punctuation mark---the Info formatting commands automatically insert 17477terminating punctuation as needed. Only the first argument is mandatory. 17478@xref{pxref, , @code{@@pxref}}.@refill 17479 17480@item @@questiondown@{@} 17481Generate an upside-down question mark. @xref{Inserting Accents}. 17482 17483@item @@quotation 17484Narrow the margins to indicate text that is quoted from another real 17485or imaginary work. Takes optional argument of prefix text. Pair with 17486@code{@@end quotation}. @xref{quotation, , 17487@code{@@quotation}}.@refill 17488 17489@item @@r@{@var{text}@} 17490Print @var{text} in @r{roman} font. No effect in Info. 17491@xref{Fonts}.@refill 17492 17493@item @@raisesections 17494Change subsequent sections to chapters, subsections to sections, and so 17495on. @xref{Raise/lower sections, , @code{@@raisesections} and 17496@code{@@lowersections}}.@refill 17497 17498@item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} 17499Make a reference. In a printed manual, the reference does not start 17500with a `See'. Follow command with a punctuation mark. Only the first 17501argument is mandatory. @xref{ref, , @code{@@ref}}.@refill 17502 17503@item @@refill 17504This command used to refill and indent the paragraph after all the 17505other processing has been done. It is no longer needed, since all 17506formatters now automatically refill as needed, but you may still see 17507it in the source to some manuals, as it does no harm. 17508 17509@item @@registeredsymbol@{@} 17510Generate the legal symbol @registeredsymbol{}. @xref{registered 17511symbol,, @code{@@registeredsymbol@{@}}}. 17512 17513@item @@result@{@} 17514Indicate the result of an expression to the reader with a special 17515glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill 17516 17517@item @@ringaccent@{@var{c}@} 17518Generate a ring accent over the next character, as in @ringaccent{o}. 17519@xref{Inserting Accents}. 17520 17521@item @@samp@{@var{text}@} 17522Highlight @var{text} that is a literal example of a sequence of 17523characters. Used for single characters, for statements, and often for 17524entire shell commands. @xref{samp, , @code{@@samp}}.@refill 17525 17526@item @@sansserif@{@var{text}@} 17527Print @var{text} in a @sansserif{sans serif} font if possible. No 17528effect in Info. @xref{Fonts}. 17529 17530@item @@sc@{@var{text}@} 17531Set @var{text} in a printed output in @sc{the small caps font} and 17532set text in the Info file in uppercase letters. 17533@xref{Smallcaps}.@refill 17534 17535@item @@section @var{title} 17536Begin a section within a chapter. In a printed manual, the section 17537title is numbered and appears in the table of contents. In Info, the 17538title is underlined with equal signs. @xref{section, , 17539@code{@@section}}.@refill 17540 17541@item @@set @var{flag} [@var{string}] 17542Make @var{flag} active, causing the Texinfo formatting commands to 17543format text between subsequent pairs of @code{@@ifset @var{flag}} and 17544@code{@@end ifset} commands. Optionally, set value of @var{flag} to 17545@var{string}. 17546@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}. 17547 17548@item @@setchapternewpage @var{on-off-odd} 17549Specify whether chapters start on new pages, and if so, whether on 17550odd-numbered (right-hand) new pages. @xref{setchapternewpage, , 17551@code{@@setchapternewpage}}. 17552 17553@item @@setcontentsaftertitlepage 17554Put the table of contents after the @samp{@@end titlepage} even if the 17555@code{@@contents} command is not there. @xref{Contents}. 17556 17557@item @@setfilename @var{info-file-name} 17558Provide a name to be used by the Info file. This command is essential 17559for @TeX{} formatting as well, even though it produces no output. 17560@xref{setfilename, , @code{@@setfilename}}. 17561 17562@item @@setshortcontentsaftertitlepage 17563Place the short table of contents after the @samp{@@end titlepage} 17564command even if the @code{@@shortcontents} command is not there. 17565@xref{Contents}. 17566 17567@item @@settitle @var{title} 17568Provide a title for page headers in a printed manual, and the default 17569document description for HTML @samp{<head>}. 17570@xref{settitle, , @code{@@settitle}}.@refill 17571 17572@item @@shortcaption 17573Define the short caption for a @code{@@float}. @xref{caption shortcaption}. 17574 17575@item @@shortcontents 17576Print a short table of contents. Not relevant to Info, which uses 17577menus rather than tables of contents. A synonym for 17578@code{@@summarycontents}. @xref{Contents, , Generating a Table of 17579Contents}.@refill 17580 17581@item @@shorttitlepage @var{title} 17582Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}. 17583 17584@item @@slanted@{@var{text}@} 17585Print @var{text} in a @slanted{slanted} font if possible. No effect 17586in Info. @xref{Fonts}. 17587 17588@item @@smallbook 17589Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format 17590rather than the regular 8.5 by 11 inch format. @xref{smallbook, , 17591Printing Small Books}. Also, see @ref{small}. 17592 17593@item @@smalldisplay 17594Begin a kind of example. Like @code{@@smallexample} (narrow margins, no 17595filling), but do not select the fixed-width font. Pair with @code{@@end 17596smalldisplay}. @xref{small}. 17597 17598@item @@smallexample 17599Indent text to indicate an example. Do not fill, select fixed-width 17600font, narrow the margins. In printed manuals, print text in a smaller 17601font than with @code{@@example}. Pair with @code{@@end smallexample}. 17602@xref{small}. 17603 17604@item @@smallformat 17605Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow 17606the margins. Pair with @code{@@end smallformat}. @xref{small}. 17607 17608@item @@smalllisp 17609Begin an example of Lisp code. Same as @code{@@smallexample}. Pair 17610with @code{@@end smalllisp}. @xref{small}. 17611 17612@item @@sp @var{n} 17613Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill 17614 17615@item @@ss@{@} 17616Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}. 17617 17618@item @@strong @{@var{text}@} 17619Emphasize @var{text} by typesetting it in a @strong{bold} font for the 17620printed manual and by surrounding it with asterisks for Info. 17621@xref{emph & strong, , Emphasizing Text}.@refill 17622 17623@item @@subheading @var{title} 17624Print an unnumbered subsection-like heading in the text, but not in 17625the table of contents of a printed manual. In Info, the title is 17626underlined with hyphens. @xref{unnumberedsubsec appendixsubsec 17627subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec} 17628@code{@@subheading}}.@refill 17629 17630@item @@subsection @var{title} 17631Begin a subsection within a section. In a printed manual, the 17632subsection title is numbered and appears in the table of contents. In 17633Info, the title is underlined with hyphens. @xref{subsection, , 17634@code{@@subsection}}.@refill 17635 17636@item @@subsubheading @var{title} 17637Print an unnumbered subsubsection-like heading in the text, but not in 17638the table of contents of a printed manual. In Info, the title is 17639underlined with periods. @xref{subsubsection, , The `subsub' 17640Commands}.@refill 17641 17642@item @@subsubsection @var{title} 17643Begin a subsubsection within a subsection. In a printed manual, 17644the subsubsection title is numbered and appears in the table of 17645contents. In Info, the title is underlined with periods. 17646@xref{subsubsection, , The `subsub' Commands}.@refill 17647 17648@item @@subtitle @var{title} 17649In a printed manual, set a subtitle in a normal sized font flush to 17650the right-hand side of the page. Not relevant to Info, which does not 17651have title pages. @xref{title subtitle author, , @code{@@title} 17652@code{@@subtitle} and @code{@@author} Commands}.@refill 17653 17654@item @@summarycontents 17655Print a short table of contents. Not relevant to Info, which uses 17656menus rather than tables of contents. A synonym for 17657@code{@@shortcontents}. @xref{Contents, , Generating a Table of 17658Contents}.@refill 17659 17660@item @@syncodeindex @var{from-index} @var{into-index} 17661Merge the index named in the first argument into the index named in 17662the second argument, printing the entries from the first index in 17663@code{@@code} font. @xref{Combining Indices}.@refill 17664 17665@item @@synindex @var{from-index} @var{into-index} 17666Merge the index named in the first argument into the index named in 17667the second argument. Do not change the font of @var{from-index} 17668entries. @xref{Combining Indices}.@refill 17669 17670@item @@t@{@var{text}@} 17671Print @var{text} in a @t{fixed-width}, typewriter-like font. 17672No effect in Info. @xref{Fonts}.@refill 17673 17674@item @@tab 17675Separate columns in a multitable. @xref{Multitable Rows}. 17676 17677@item @@table @var{formatting-command} 17678Begin a two-column table, using @code{@@item} for each entry. Write 17679each first column entry on the same line as @code{@@item}. First 17680column entries are printed in the font resulting from 17681@var{formatting-command}. Pair with @code{@@end table}. 17682@xref{Two-column Tables, , Making a Two-column Table}. 17683Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, 17684and @ref{itemx, , @code{@@itemx}}.@refill 17685 17686@item @@TeX@{@} 17687Insert the logo @TeX{}. @xref{tex, , @TeX{} and @LaTeX{}}. 17688 17689@item @@tex 17690Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw 17691Formatter Commands}. 17692 17693@item @@thischapter 17694@itemx @@thischaptername 17695@itemx @@thisfile 17696@itemx @@thispage 17697@itemx @@thistitle 17698Only allowed in a heading or footing. Stands for the number and name of 17699the current chapter (in the format `Chapter 1: Title'), the chapter name 17700only, the filename, the current page number, and the title of the 17701document, respectively. @xref{Custom Headings, , How to Make Your Own 17702Headings}.@refill 17703 17704@item @@tie@{@} 17705Generate a normal interword space at which a line break is not allowed. 17706@xref{tie,, @code{@@tie@{@}}}. 17707 17708@item @@tieaccent@{@var{cc}@} 17709Generate a tie-after accent over the next two characters @var{cc}, as in 17710`@tieaccent{oo}'. @xref{Inserting Accents}. 17711 17712@item @@tindex @var{entry} 17713Add @var{entry} to the index of data types. @xref{Index Entries, , 17714Defining the Entries of an Index}.@refill 17715 17716@item @@title @var{title} 17717In a printed manual, set a title flush to the left-hand side of the 17718page in a larger than normal font and underline it with a black rule. 17719Not relevant to Info, which does not have title pages. @xref{title 17720subtitle author, , The @code{@@title} @code{@@subtitle} and 17721@code{@@author} Commands}.@refill 17722 17723@item @@titlefont@{@var{text}@} 17724In a printed manual, print @var{text} in a larger than normal font. 17725Not relevant to Info, which does not have title pages. 17726@xref{titlefont center sp, , The @code{@@titlefont} @code{@@center} 17727and @code{@@sp} Commands}.@refill 17728 17729@item @@titlepage 17730Indicate to Texinfo the beginning of the title page. Write command on 17731a line of its own. Pair with @code{@@end titlepage}. Nothing between 17732@code{@@titlepage} and @code{@@end titlepage} appears in Info. 17733@xref{titlepage, , @code{@@titlepage}}.@refill 17734 17735@item @@today@{@} 17736Insert the current date, in `1 Jan 1900' style. @xref{Custom 17737Headings, , How to Make Your Own Headings}.@refill 17738 17739@item @@top @var{title} 17740In a Texinfo file to be formatted with @code{makeinfo}, identify the 17741topmost @code{@@node} in the file, which must be written on the line 17742immediately preceding the @code{@@top} command. Used for 17743@code{makeinfo}'s node pointer insertion feature. The title is 17744underlined with asterisks. Both the @code{@@node} line and the @code{@@top} 17745line normally should be enclosed by @code{@@ifnottex} and @code{@@end 17746ifnottex}. In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top} 17747command is merely a synonym for @code{@@unnumbered}. @xref{makeinfo 17748Pointer Creation, , Creating Pointers with @code{makeinfo}}. 17749 17750@item @@u@{@var{c}@} 17751@itemx @@ubaraccent@{@var{c}@} 17752@itemx @@udotaccent@{@var{c}@} 17753Generate a breve, underbar, or underdot accent, respectively, over or 17754under the character @var{c}, as in @u{o}, @ubaraccent{o}, 17755@udotaccent{o}. @xref{Inserting Accents}. 17756 17757@item @@unnumbered @var{title} 17758In a printed manual, begin a chapter that appears without chapter 17759numbers of any kind. The title appears in the table of contents of a 17760printed manual. In Info, the title is underlined with asterisks. 17761@xref{unnumbered & appendix, , @code{@@unnumbered} and 17762@code{@@appendix}}.@refill 17763 17764@item @@unnumberedsec @var{title} 17765In a printed manual, begin a section that appears without section 17766numbers of any kind. The title appears in the table of contents of a 17767printed manual. In Info, the title is underlined with equal signs. 17768@xref{unnumberedsec appendixsec heading, , Section Commands}.@refill 17769 17770@item @@unnumberedsubsec @var{title} 17771In a printed manual, begin an unnumbered subsection within a 17772chapter. The title appears in the table of contents of a printed 17773manual. In Info, the title is underlined with hyphens. 17774@xref{unnumberedsubsec appendixsubsec subheading, , 17775@code{@@unnumberedsubsec} @code{@@appendixsubsec} 17776@code{@@subheading}}.@refill 17777 17778@item @@unnumberedsubsubsec @var{title} 17779In a printed manual, begin an unnumbered subsubsection within a 17780chapter. The title appears in the table of contents of a printed 17781manual. In Info, the title is underlined with periods. 17782@xref{subsubsection, , The `subsub' Commands}.@refill 17783 17784@item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@} 17785@itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@} 17786Define a cross reference to an external uniform resource locator for the 17787World Wide Web. @xref{uref, , @code{@@uref}}. 17788 17789@item @@v@{@var{c}@} 17790Generate check accent over the character @var{c}, as in @v{o}. 17791@xref{Inserting Accents}. 17792 17793@item @@value@{@var{flag}@} 17794Replace @var{flag} with the value to which it is set by @code{@@set 17795@var{flag}}. 17796@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 17797 17798@item @@var@{@var{metasyntactic-variable}@} 17799Highlight a metasyntactic variable, which is something that stands for 17800another piece of text. @xref{var, , Indicating Metasyntactic 17801Variables}.@refill 17802 17803@item @@verb@{@var{delim} @var{literal} @var{delim}@} 17804Output @var{literal}, delimited by the single character @var{delim}, 17805exactly as is (in the fixed-width font), including any whitespace or 17806Texinfo special characters. @xref{verb,,@code{verb}}. 17807 17808@item @@verbatim 17809Output the text of the environment exactly as is (in the fixed-width 17810font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}. 17811 17812@item @@verbatiminclude @var{filename} 17813Output the contents of @var{filename} exactly as is (in the fixed-width font). 17814@xref{verbatiminclude,,@code{verbatiminclude}}. 17815 17816@item @@vindex @var{entry} 17817Add @var{entry} to the index of variables. @xref{Index Entries, , 17818Defining the Entries of an Index}.@refill 17819 17820@item @@vskip @var{amount} 17821In a printed manual, insert whitespace so as to push text on the 17822remainder of the page towards the bottom of the page. Used in 17823formatting the copyright page with the argument @samp{0pt plus 178241filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used 17825only in contexts ignored for Info. @xref{Copyright}. 17826 17827@item @@vtable @var{formatting-command} 17828Begin a two-column table, using @code{@@item} for each entry. 17829Automatically enter each of the items in the first column into the 17830index of variables. Pair with @code{@@end vtable}. The same as 17831@code{@@table}, except for indexing. @xref{ftable vtable, , 17832@code{@@ftable} and @code{@@vtable}}.@refill 17833 17834@item @@w@{@var{text}@} 17835Prevent @var{text} from being split across two lines. 17836@xref{w, , @code{@@w}}.@refill 17837 17838@item @@xml 17839Enter XML completely. Pair with @code{@@end xml}. @xref{Raw 17840Formatter Commands}. 17841 17842@item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@} 17843Make a reference that starts with `See' in a printed manual. Follow 17844command with a punctuation mark. Only the first argument is 17845mandatory. @xref{xref, , @code{@@xref}}.@refill 17846@end table 17847 17848 17849@node Command Syntax 17850@section @@-Command Syntax 17851@cindex @@-command syntax 17852@cindex Syntax, of @@-commands 17853@cindex Command syntax 17854 17855The character @samp{@@} is used to start special Texinfo commands. 17856(It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo 17857has four types of @@-command:@refill 17858 17859@table @asis 17860@item 1. Non-alphabetic commands. 17861These commands consist of an @@ followed by a punctuation mark or other 17862character that is not part of the alphabet. Non-alphabetic commands are 17863almost always part of the text within a paragraph, and never take any 17864argument. The two characters (@@ and the other one) are complete in 17865themselves; none is followed by braces. The non-alphabetic commands 17866are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}}, 17867@code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and 17868@code{@@@}}.@refill 17869 17870@item 2. Alphabetic commands that do not require arguments. 17871These commands start with @@ followed by a word followed by left- and 17872right-hand braces. These commands insert special symbols in the 17873document; they do not require arguments. For example, 17874@code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}} 17875@result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}', 17876and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill 17877 17878@item 3. Alphabetic commands that require arguments within braces. 17879These commands start with @@ followed by a letter or a word, followed by an 17880argument within braces. For example, the command @code{@@dfn} indicates 17881the introductory or defining use of a term; it is used as follows: @samp{In 17882Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill 17883 17884@item 4. Alphabetic commands that occupy an entire line. 17885These commands occupy an entire line. The line starts with @@, 17886followed by the name of the command (a word); for example, @code{@@center} 17887or @code{@@cindex}. If no argument is needed, the word is followed by 17888the end of the line. If there is an argument, it is separated from 17889the command name by a space. Braces are not used.@refill 17890@end table 17891 17892@cindex Braces and argument syntax 17893Thus, the alphabetic commands fall into classes that have 17894different argument syntaxes. You cannot tell to which class a command 17895belongs by the appearance of its name, but you can tell by the 17896command's meaning: if the command stands for a glyph, it is in 17897class 2 and does not require an argument; if it makes sense to use the 17898command together with other text as part of a paragraph, the command 17899is in class 3 and must be followed by an argument in braces; 17900otherwise, it is in class 4 and uses the rest of the line as its 17901argument.@refill 17902 17903The purpose of having a different syntax for commands of classes 3 and 179044 is to make Texinfo files easier to read, and also to help the GNU 17905Emacs paragraph and filling commands work properly. There is only one 17906exception to this rule: the command @code{@@refill}, which is always 17907used at the end of a paragraph immediately following the final period 17908or other punctuation character. @code{@@refill} takes no argument and 17909does @emph{not} require braces. @code{@@refill} never confuses the 17910Emacs paragraph commands because it cannot appear at the beginning of 17911a line. It is also no longer needed, since all formatters now refill 17912paragraphs automatically. 17913 17914 17915@node Tips 17916@appendix Tips and Hints 17917 17918Here are some tips for writing Texinfo documentation:@refill 17919 17920@cindex Tips 17921@cindex Usage tips 17922@cindex Hints 17923@itemize @bullet 17924@item 17925Write in the present tense, not in the past or the future. 17926 17927@item 17928Write actively! For example, write ``We recommend that @dots{}'' rather 17929than ``It is recommended that @dots{}''. 17930 17931@item 17932Use 70 or 72 as your fill column. Longer lines are hard to read. 17933 17934@item 17935Include a copyright notice and copying permissions. 17936@end itemize 17937 17938@subsubheading Index, Index, Index! 17939 17940Write many index entries, in different ways. 17941Readers like indices; they are helpful and convenient. 17942 17943Although it is easiest to write index entries as you write the body of 17944the text, some people prefer to write entries afterwards. In either 17945case, write an entry before the paragraph to which it applies. This 17946way, an index entry points to the first page of a paragraph that is 17947split across pages. 17948 17949Here are more hints we have found valuable: 17950 17951@itemize @bullet 17952@item 17953Write each index entry differently, so each entry refers to a different 17954place in the document. 17955 17956@item 17957Write index entries only where a topic is discussed significantly. For 17958example, it is not useful to index ``debugging information'' in a 17959chapter on reporting bugs. Someone who wants to know about debugging 17960information will certainly not find it in that chapter. 17961 17962@item 17963Consistently capitalize the first word of every concept index entry, 17964or else consistently use lower case. Terse entries often call for 17965lower case; longer entries for capitalization. Whichever case 17966convention you use, please use one or the other consistently! Mixing 17967the two styles looks bad. 17968 17969@item 17970Always capitalize or use upper case for those words in an index for 17971which this is proper, such as names of countries or acronyms. Always 17972use the appropriate case for case-sensitive names, such as those in C or 17973Lisp. 17974 17975@item 17976Write the indexing commands that refer to a whole section immediately 17977after the section command, and write the indexing commands that refer to 17978a paragraph before that paragraph. 17979 17980In the example that follows, a blank line comes after the index 17981entry for ``Leaping'': 17982 17983@example 17984@group 17985@@section The Dog and the Fox 17986@@cindex Jumping, in general 17987@@cindex Leaping 17988 17989@@cindex Dog, lazy, jumped over 17990@@cindex Lazy dog jumped over 17991@@cindex Fox, jumps over dog 17992@@cindex Quick fox jumps over dog 17993The quick brown fox jumps over the lazy dog. 17994@end group 17995@end example 17996 17997@noindent 17998(Note that the example shows entries for the same concept that are 17999written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so 18000readers can look up the concept in different ways.) 18001@end itemize 18002 18003@subsubheading Blank Lines 18004 18005@itemize @bullet 18006@item 18007Insert a blank line between a sectioning command and the first following 18008sentence or paragraph, or between the indexing commands associated with 18009the sectioning command and the first following sentence or paragraph, as 18010shown in the tip on indexing. Otherwise, a formatter may fold title and 18011paragraph together. 18012 18013@item 18014Always insert a blank line before an @code{@@table} command and after an 18015@code{@@end table} command; but never insert a blank line after an 18016@code{@@table} command or before an @code{@@end table} command. 18017 18018@need 1000 18019For example, 18020 18021@example 18022@group 18023Types of fox: 18024 18025@@table @@samp 18026@@item Quick 18027Jump over lazy dogs. 18028@end group 18029 18030@group 18031@@item Brown 18032Also jump over lazy dogs. 18033@@end table 18034 18035@end group 18036@group 18037@@noindent 18038On the other hand, @dots{} 18039@end group 18040@end example 18041 18042Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end 18043itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the 18044same way. 18045@end itemize 18046 18047@subsubheading Complete Phrases 18048 18049Complete phrases are easier to read than @dots{} 18050 18051@itemize @bullet 18052@item 18053Write entries in an itemized list as complete sentences; or at least, as 18054complete phrases. Incomplete expressions @dots{} awkward @dots{} like 18055this. 18056 18057@item 18058Write the prefatory sentence or phrase for a multi-item list or table as 18059a complete expression. Do not write ``You can set:''; instead, write 18060``You can set these variables:''. The former expression sounds cut off. 18061@end itemize 18062 18063@subsubheading Editions, Dates and Versions 18064 18065Include edition numbers, version numbers, and dates in the 18066@code{@@copying} text (for people reading the Texinfo file, and for the 18067legal copyright in the output files). Then use @code{@@insertcopying} 18068in the @code{@@titlepage} section (for people reading the printed 18069output) and the Top node (for people reading the online output). 18070 18071It is easiest to do this using @code{@@set} and @code{@@value}. 18072@xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}. 18073 18074 18075@subsubheading Definition Commands 18076 18077Definition commands are @code{@@deffn}, @code{@@defun}, 18078@code{@@defmac}, and the like, and enable you to write descriptions in 18079a uniform format.@refill 18080 18081@itemize @bullet 18082@item 18083Write just one definition command for each entity you define with a 18084definition command. The automatic indexing feature creates an index 18085entry that leads the reader to the definition. 18086 18087@item 18088Use @code{@@table} @dots{} @code{@@end table} in an appendix that 18089contains a summary of functions, not @code{@@deffn} or other definition 18090commands. 18091@end itemize 18092 18093@subsubheading Capitalization 18094 18095@itemize @bullet 18096@item 18097Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or 18098@samp{i} in upper case. 18099 18100@item 18101Capitalize ``Info''; it is a name. 18102 18103@item 18104Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase 18105@samp{T} and @samp{X}. This command causes the formatters to 18106typeset the name according to the wishes of Donald Knuth, who wrote 18107@TeX{}. 18108@end itemize 18109 18110@subsubheading Spaces 18111 18112Do not use spaces to format a Texinfo file, except inside of 18113@code{@@example} @dots{} @code{@@end example} and other literal 18114environments and commands. 18115 18116@need 700 18117For example, @TeX{} fills the following: 18118 18119@example 18120@group 18121 @@kbd@{C-x v@} 18122 @@kbd@{M-x vc-next-action@} 18123 Perform the next logical operation 18124 on the version-controlled file 18125 corresponding to the current buffer. 18126@end group 18127@end example 18128 18129@need 950 18130@noindent 18131so it looks like this: 18132 18133@iftex 18134@quotation 18135 @kbd{C-x v} 18136 @kbd{M-x vc-next-action} 18137 Perform the next logical operation on the version-controlled file 18138 corresponding to the current buffer. 18139@end quotation 18140@end iftex 18141@ifnottex 18142@quotation 18143`C-x v' `M-x vc-next-action' Perform the next logical operation on the 18144version-controlled file corresponding to the current buffer. 18145@end quotation 18146@end ifnottex 18147 18148@noindent 18149In this case, the text should be formatted with 18150@code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table. 18151 18152 18153@subsubheading @@code, @@samp, @@var, and @samp{---} 18154 18155@itemize @bullet 18156@item 18157Use @code{@@code} around Lisp symbols, including command names. 18158For example, 18159 18160@example 18161The main function is @@code@{vc-next-action@}, @dots{} 18162@end example 18163 18164@item 18165Avoid putting letters such as @samp{s} immediately after an 18166@samp{@@code}. Such letters look bad. 18167 18168@item 18169Use @code{@@var} around meta-variables. Do not write angle brackets 18170around them. 18171 18172@item 18173Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{} 18174typesets these as a long dash and the Info formatters reduce three 18175hyphens to two. 18176@end itemize 18177 18178@subsubheading Periods Outside of Quotes 18179 18180Place periods and other punctuation marks @emph{outside} of quotations, 18181unless the punctuation is part of the quotation. This practice goes 18182against publishing conventions in the United States, but enables the 18183reader to distinguish between the contents of the quotation and the 18184whole passage. 18185 18186For example, you should write the following sentence with the period 18187outside the end quotation marks: 18188 18189@example 18190Evidently, @samp{au} is an abbreviation for ``author''. 18191@end example 18192 18193@noindent 18194since @samp{au} does @emph{not} serve as an abbreviation for 18195@samp{author.} (with a period following the word). 18196 18197@subsubheading Introducing New Terms 18198 18199@itemize @bullet 18200@item 18201Introduce new terms so that a reader who does not know them can 18202understand them from context; or write a definition for the term. 18203 18204For example, in the following, the terms ``check in'', ``register'' and 18205``delta'' are all appearing for the first time; the example sentence should be 18206rewritten so they are understandable. 18207 18208@quotation 18209The major function assists you in checking in a file to your 18210version control system and registering successive sets of changes to 18211it as deltas. 18212@end quotation 18213 18214@item 18215Use the @code{@@dfn} command around a word being introduced, to indicate 18216that the reader should not expect to know the meaning already, and 18217should expect to learn the meaning from this passage. 18218@end itemize 18219 18220@subsubheading @@pxref 18221 18222@c !!! maybe include this in the tips on pxref 18223@ignore 18224By the way, it is okay to use pxref with something else in front of 18225it within the parens, as long as the pxref is followed by the close 18226paren, and the material inside the parens is not part of a larger 18227sentence. Also, you can use xref inside parens as part of a complete 18228sentence so long as you terminate the cross reference with punctuation. 18229@end ignore 18230Absolutely never use @code{@@pxref} except in the special context for 18231which it is designed: inside parentheses, with the closing parenthesis 18232following immediately after the closing brace. One formatter 18233automatically inserts closing punctuation and the other does not. This 18234means that the output looks right both in printed output and in an Info 18235file, but only when the command is used inside parentheses. 18236 18237@subsubheading Invoking from a Shell 18238 18239You can invoke programs such as Emacs, GCC, and @code{gawk} from a 18240shell. The documentation for each program should contain a section that 18241describes this. Unfortunately, if the node names and titles for these 18242sections are all different, they are difficult for users to find. 18243 18244So, there is a convention to name such sections with a phrase beginning 18245with the word `Invoking', as in `Invoking Emacs'; this way, users can 18246find the section easily. 18247 18248 18249@subsubheading ANSI C Syntax 18250 18251When you use @code{@@example} to describe a C function's calling 18252conventions, use the ANSI C syntax, like this:@refill 18253 18254@example 18255void dld_init (char *@@var@{path@}); 18256@end example 18257 18258@noindent 18259And in the subsequent discussion, refer to the argument values by 18260writing the same argument names, again highlighted with 18261@code{@@var}.@refill 18262 18263@need 800 18264Avoid the obsolete style that looks like this:@refill 18265 18266@example 18267#include <dld.h> 18268 18269dld_init (path) 18270char *path; 18271@end example 18272 18273Also, it is best to avoid writing @code{#include} above the 18274declaration just to indicate that the function is declared in a 18275header file. The practice may give the misimpression that the 18276@code{#include} belongs near the declaration of the function. Either 18277state explicitly which header file holds the declaration or, better 18278yet, name the header file used for a group of functions at the 18279beginning of the section that describes the functions.@refill 18280 18281@subsubheading Bad Examples 18282 18283Here are several examples of bad writing to avoid: 18284 18285In this example, say, `` @dots{} you must @code{@@dfn}@{check 18286in@} the new version.'' That flows better. 18287 18288@quotation 18289When you are done editing the file, you must perform a 18290@code{@@dfn}@{check in@}. 18291@end quotation 18292 18293In the following example, say, ``@dots{} makes a unified interface such as VC 18294mode possible.'' 18295 18296@quotation 18297SCCS, RCS and other version-control systems all perform similar 18298functions in broadly similar ways (it is this resemblance which makes 18299a unified control mode like this possible). 18300@end quotation 18301 18302And in this example, you should specify what `it' refers to: 18303 18304@quotation 18305If you are working with other people, it assists in coordinating 18306everyone's changes so they do not step on each other. 18307@end quotation 18308 18309@subsubheading And Finally @dots{} 18310 18311@itemize @bullet 18312@item 18313Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last 18314sound in the name `Bach'. But pronounce Texinfo as in `speck': 18315``teckinfo''. 18316 18317@item 18318Write notes for yourself at the very end of a Texinfo file after the 18319@code{@@bye}. None of the formatters process text after the 18320@code{@@bye}; it is as if the text were within @code{@@ignore} @dots{} 18321@code{@@end ignore}. 18322@end itemize 18323 18324 18325@node Sample Texinfo Files 18326@appendix Sample Texinfo Files 18327@cindex Sample Texinfo files 18328 18329The first example is from the first chapter (@pxref{Short Sample}), 18330given here in its entirety, without commentary. The second 18331includes the full texts to be used in GNU manuals. 18332 18333@menu 18334* Short Sample Texinfo File:: 18335* GNU Sample Texts:: 18336* Verbatim Copying License:: 18337* All-permissive Copying License:: 18338@end menu 18339 18340 18341@node Short Sample Texinfo File 18342@section Short Sample 18343@cindex Sample Texinfo file, no comments 18344 18345Here is a complete, short sample Texinfo file, without any commentary. 18346You can see this file, with comments, in the first chapter. @xref{Short 18347Sample}. 18348 18349In a nutshell: The @command{makeinfo} program transforms a Texinfo 18350source file such as this into an Info file or HTML; and @TeX{} typesets 18351it for a printed manual. 18352 18353 18354@sp 1 18355@example 18356\input texinfo @@c -*-texinfo-*- 18357@@c %**start of header 18358@@setfilename sample.info 18359@@settitle Sample Manual 1.0 18360@@c %**end of header 18361 18362@@copying 18363This is a short example of a complete Texinfo file. 18364 18365Copyright (C) 2004 Free Software Foundation, Inc. 18366@@end copying 18367 18368@@titlepage 18369@@title Sample Title 18370@@page 18371@@vskip 0pt plus 1filll 18372@@insertcopying 18373@@end titlepage 18374 18375@@c Output the table of the contents at the beginning. 18376@@contents 18377 18378@@ifnottex 18379@@node Top 18380@@top GNU Sample 18381 18382@@insertcopying 18383@@end ifnottex 18384 18385@@menu 18386* First Chapter:: The first chapter is the 18387 only chapter in this sample. 18388* Index:: Complete index. 18389@@end menu 18390 18391 18392@@node First Chapter 18393@@chapter First Chapter 18394 18395@@cindex chapter, first 18396 18397This is the first chapter. 18398@@cindex index entry, another 18399 18400Here is a numbered list. 18401 18402@@enumerate 18403@@item 18404This is the first item. 18405 18406@@item 18407This is the second item. 18408@@end enumerate 18409 18410 18411@@node Index 18412@@unnumbered Index 18413 18414@@printindex cp 18415 18416@@bye 18417@end example 18418 18419 18420@node GNU Sample Texts 18421@section GNU Sample Texts 18422 18423@cindex GNU sample texts 18424@cindex Sample texts, GNU 18425@cindex Full texts, GNU 18426 18427Following is a sample Texinfo document with the full texts that should 18428be used in GNU manuals. 18429 18430As well as the legal texts, it also serves as a practical example of how 18431many elements in a GNU system can affect the manual. If you're not 18432familiar with all these different elements, don't worry. They're not 18433required and a perfectly good manual can be written without them. 18434They're included here nonetheless because many manuals do (or could) 18435benefit from them. 18436 18437@xref{Short Sample}, for a minimal example of a Texinfo file. 18438@xref{Beginning a File}, for a full explanation of that minimal 18439example. 18440 18441Here are some notes on the example: 18442 18443@itemize @bullet 18444@item 18445@cindex $Id 18446@cindex CVS $Id 18447@cindex RCS $Id 18448@cindex Documentation identification 18449@cindex Identification of documentation 18450The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs, 18451Concurrent Versions System}) or RCS (see rcsintro(1)) version control 18452systems, which expand it into a string such as: 18453@example 18454$Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $ 18455@end example 18456(This is useful in all sources that use version control, not just manuals.) 18457You may wish to include the @samp{$Id:} comment in the @code{@@copying} 18458text, if you want a completely unambiguous reference to the 18459documentation version. 18460 18461If you want to literally write @t{@w{$}Id$}, use @code{@@w}: 18462@code{@@w@{$@}Id$}. 18463 18464@item 18465@pindex automake@r{, and version info} 18466@vindex UPDATED @r{Automake variable} 18467@vindex VERSION @r{Automake variable} 18468@pindex time-stamp.el 18469The @file{version.texi} in the @code{@@include} command is maintained 18470automatically by Automake (@pxref{Top,, Introduction, automake, GNU 18471Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used 18472elsewhere. If your distribution doesn't use Automake, but you do use 18473Emacs, you may find the time-stamp.el package helpful (@pxref{Time 18474Stamps,,,emacs,The GNU Emacs Manual}). 18475 18476@item 18477The @code{@@syncodeindex} command reflects the recommendation to use 18478only one index where possible, to make it easier for readers to look up 18479index entries. 18480 18481@item 18482The @code{@@dircategory} is for constructing the Info directory. 18483@xref{Installing Dir Entries}, which includes a variety of recommended 18484category names. 18485 18486@item 18487The `Invoking' node is a GNU standard to help users find the basic 18488information about command-line usage of a given program. @xref{Manual 18489Structure Details,,,standards, GNU Coding Standards}. 18490 18491@item 18492@cindex GNU Free Documentation License, including entire 18493@cindex Free Documentation License, including entire 18494It is best to include the entire GNU Free Documentation License in a GNU 18495manual, unless the manual is only a few pages long. Of course this 18496sample is even shorter than that, but it includes the FDL anyway in 18497order to show one conventional way to do so. The @file{fdl.texi} file 18498is available on the GNU machines and in the Texinfo and other GNU 18499source distributions. 18500 18501The FDL provides for omitting itself under certain conditions, but in 18502that case the sample texts given here have to be modified. @xref{GNU 18503Free Documentation License}. 18504 18505@item 18506If your manual has invariant sections (again, see the license itself for 18507details), then don't forget to change the text here accordingly. 18508 18509@item 18510For documents that express your personal views, feelings or experiences, 18511it is more appropriate to use a license permitting only verbatim 18512copying, rather than the FDL. @xref{Verbatim Copying License}. 18513 18514@end itemize 18515 18516Here is the sample document: 18517 18518@verbatim 18519\input texinfo @c -*-texinfo-*- 18520@comment $Id: texinfo.txi,v 1.128 2004/12/29 15:06:41 karl Exp $ 18521@comment %**start of header 18522@setfilename sample.info 18523@include version.texi 18524@settitle GNU Sample @value{VERSION} 18525@syncodeindex pg cp 18526@comment %**end of header 18527@copying 18528This manual is for GNU Sample 18529(version @value{VERSION}, @value{UPDATED}), 18530which is an example in the Texinfo documentation. 18531 18532Copyright @copyright{} 2004 Free Software Foundation, Inc. 18533 18534@quotation 18535Permission is granted to copy, distribute and/or modify this document 18536under the terms of the GNU Free Documentation License, Version 1.1 or 18537any later version published by the Free Software Foundation; with no 18538Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' 18539and with the Back-Cover Texts as in (a) below. A copy of the 18540license is included in the section entitled ``GNU Free Documentation 18541License.'' 18542 18543(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 18544this GNU Manual, like GNU software. Copies published by the Free 18545Software Foundation raise funds for GNU development.'' 18546@end quotation 18547@end copying 18548 18549@dircategory Texinfo documentation system 18550@direntry 18551* sample: (sample)Invoking sample. 18552@end direntry 18553 18554@titlepage 18555@title GNU Sample 18556@subtitle for version @value{VERSION}, @value{UPDATED} 18557@author A.U. Thor (@email{bug-texinfo@@gnu.org}) 18558@page 18559@vskip 0pt plus 1filll 18560@insertcopying 18561@end titlepage 18562 18563@contents 18564 18565@ifnottex 18566@node Top 18567@top GNU Sample 18568 18569@insertcopying 18570@end ifnottex 18571 18572@menu 18573* Invoking sample:: 18574* Copying This Manual:: 18575* Index:: 18576@end menu 18577 18578 18579@node Invoking sample 18580@chapter Invoking sample 18581 18582@pindex sample 18583@cindex invoking @command{sample} 18584 18585This is a sample manual. There is no sample program to 18586invoke, but if there was, you could see its basic usage 18587and command line options here. 18588 18589 18590@node Copying This Manual 18591@appendix Copying This Manual 18592 18593@menu 18594* GNU Free Documentation License:: License for copying this manual. 18595@end menu 18596 18597@include fdl.texi 18598 18599 18600@node Index 18601@unnumbered Index 18602 18603@printindex cp 18604 18605@bye 18606@end verbatim 18607 18608 18609@node Verbatim Copying License 18610@section Verbatim Copying License 18611 18612@cindex Verbatim copying license 18613@cindex License for verbatim copying 18614 18615For software manuals and other documentation, it is important to use a 18616license permitting free redistribution and updating, so that when a free 18617program is changed, the documentation can be updated as well. 18618 18619On the other hand, for documents that express your personal views, 18620feelings or experiences, it is more appropriate to use a license 18621permitting only verbatim copying. 18622 18623Here is sample text for such a license permitting verbatim copying only. 18624This is just the license text itself. For a complete sample document, 18625see the previous sections. 18626 18627@verbatim 18628@copying 18629This document is a sample for allowing verbatim copying only. 18630 18631Copyright @copyright{} 2004 Free Software Foundation, Inc. 18632 18633@quotation 18634Permission is granted to make and distribute verbatim copies 18635of this entire document without royalty provided the 18636copyright notice and this permission notice are preserved. 18637@end quotation 18638@end copying 18639@end verbatim 18640 18641 18642@node All-permissive Copying License 18643@section All-permissive Copying License 18644 18645@cindex All-permissive copying license 18646@cindex License for all-permissive copying 18647 18648For software manuals and other documentation, it is important to use a 18649license permitting free redistribution and updating, so that when a free 18650program is changed, the documentation can be updated as well. 18651 18652On the other hand, for small supporting files, short manuals (under 300 18653lines long) and rough documentation (README files, INSTALL files, etc.), 18654the full FDL would be overkill. They can use a simple all-permissive 18655license. 18656 18657Here is sample text for such an all-permissive license. This is just 18658the license text itself. For a complete sample document, see the 18659previous sections. 18660 18661@example 18662Copyright @copyright{} 2004 Free Software Foundation, Inc. 18663 18664Copying and distribution of this file, with or without modification, 18665are permitted in any medium without royalty provided the copyright 18666notice and this notice are preserved. 18667@end example 18668 18669 18670@node Include Files 18671@appendix Include Files 18672@cindex Include files 18673 18674When @TeX{} or an Info formatting command sees an @code{@@include} 18675command in a Texinfo file, it processes the contents of the file named 18676by the command and incorporates them into the DVI or Info file being 18677created. Index entries from the included file are incorporated into 18678the indices of the output file. 18679 18680Include files let you keep a single large document as a collection of 18681conveniently small parts. 18682 18683@menu 18684* Using Include Files:: How to use the @code{@@include} command. 18685* texinfo-multiple-files-update:: How to create and update nodes and 18686 menus when using included files. 18687* Include Files Requirements:: @code{texinfo-multiple-files-update} needs. 18688* Sample Include File:: A sample outer file with included files 18689 within it; and a sample included file. 18690* Include Files Evolution:: How use of the @code{@@include} command 18691 has changed over time. 18692@end menu 18693 18694@node Using Include Files 18695@section How to Use Include Files 18696@findex include 18697 18698To include another file within a Texinfo file, write the 18699@code{@@include} command at the beginning of a line and follow it on 18700the same line by the name of a file to be included. For example: 18701 18702@example 18703@@include buffers.texi 18704@end example 18705 18706The name of the file is taken literally, with a single exception: 18707@code{@@value@{@var{var}@}} references are expanded. This makes it 18708possible to reliably include files in other directories in a 18709distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for 18710an example. 18711 18712An included file should simply be a segment of text that you expect to 18713be included as is into the overall or @dfn{outer} Texinfo file; it 18714should not contain the standard beginning and end parts of a Texinfo 18715file. In particular, you should not start an included file with a 18716line saying @samp{\input texinfo}; if you do, that phrase is inserted 18717into the output file as is. Likewise, you should not end an included 18718file with an @code{@@bye} command; nothing after @code{@@bye} is 18719formatted. 18720 18721In the past, you were required to write an @code{@@setfilename} line at the 18722beginning of an included file, but no longer. Now, it does not matter 18723whether you write such a line. If an @code{@@setfilename} line exists 18724in an included file, it is ignored.@refill 18725 18726Conventionally, an included file begins with an @code{@@node} line that 18727is followed by an @code{@@chapter} line. Each included file is one 18728chapter. This makes it easy to use the regular node and menu creating 18729and updating commands to create the node pointers and menus within the 18730included file. However, the simple Emacs node and menu creating and 18731updating commands do not work with multiple Texinfo files. Thus you 18732cannot use these commands to fill in the `Next', `Previous', and `Up' 18733pointers of the @code{@@node} line that begins the included file. Also, 18734you cannot use the regular commands to create a master menu for the 18735whole file. Either you must insert the menus and the `Next', 18736`Previous', and `Up' pointers by hand, or you must use the GNU Emacs 18737Texinfo mode command, @code{texinfo-multiple-files-update}, that is 18738designed for @code{@@include} files.@refill 18739 18740When an included file does not have any node lines in it, the 18741multiple files update command does not try to create a menu entry 18742for it. Consequently, you can include any file, such as a 18743version or an update file without node lines, not just files that 18744are chapters. Small includable files like this are created by 18745Automake (@pxref{GNU Sample Texts}). 18746 18747 18748@node texinfo-multiple-files-update 18749@section @code{texinfo-multiple-files-update} 18750@findex texinfo-multiple-files-update 18751 18752GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update} 18753command. This command creates or updates `Next', `Previous', and `Up' 18754pointers of included files as well as those in the outer or overall 18755Texinfo file, and it creates or updates a main menu in the outer file. 18756Depending whether you call it with optional arguments, the command 18757updates only the pointers in the first @code{@@node} line of the 18758included files or all of them:@refill 18759 18760@table @kbd 18761@item M-x texinfo-multiple-files-update 18762Called without any arguments:@refill 18763 18764@itemize @minus 18765@item 18766Create or update the `Next', `Previous', and `Up' pointers of the 18767first @code{@@node} line in each file included in an outer or overall 18768Texinfo file.@refill 18769 18770@item 18771Create or update the `Top' level node pointers of the outer or 18772overall file.@refill 18773 18774@item 18775Create or update a main menu in the outer file.@refill 18776@end itemize 18777 18778@item C-u M-x texinfo-multiple-files-update 18779Called with @kbd{C-u} as a prefix argument: 18780 18781@itemize @minus{} 18782@item 18783Create or update pointers in the first @code{@@node} line in each 18784included file. 18785 18786@item 18787Create or update the `Top' level node pointers of the outer file. 18788 18789@item 18790Create and insert a master menu in the outer file. The master menu 18791is made from all the menus in all the included files.@refill 18792@end itemize 18793 18794@item C-u 8 M-x texinfo-multiple-files-update 18795Called with a numeric prefix argument, such as @kbd{C-u 8}: 18796 18797@itemize @minus 18798@item 18799Create or update @strong{all} the `Next', `Previous', and `Up' pointers 18800of all the included files.@refill 18801 18802@item 18803Create or update @strong{all} the menus of all the included 18804files.@refill 18805 18806@item 18807Create or update the `Top' level node pointers of the outer or 18808overall file.@refill 18809 18810@item 18811And then create a master menu in the outer file. This is similar to 18812invoking @code{texinfo-master-menu} with an argument when you are 18813working with just one file.@refill 18814@end itemize 18815@end table 18816 18817Note the use of the prefix argument in interactive use: with a regular 18818prefix argument, just @w{@kbd{C-u}}, the 18819@code{texinfo-multiple-files-update} command inserts a master menu; 18820with a numeric prefix argument, such as @kbd{C-u 8}, the command 18821updates @strong{every} pointer and menu in @strong{all} the files and then inserts a 18822master menu.@refill 18823 18824 18825@node Include Files Requirements 18826@section Include Files Requirements 18827@cindex Include files requirements 18828@cindex Requirements for include files 18829 18830If you plan to use the @code{texinfo-multiple-files-update} command, 18831the outer Texinfo file that lists included files within it should 18832contain nothing but the beginning and end parts of a Texinfo file, and 18833a number of @code{@@include} commands listing the included files. It 18834should not even include indices, which should be listed in an included 18835file of their own.@refill 18836 18837Moreover, each of the included files must contain exactly one highest 18838level node (conventionally, @code{@@chapter} or equivalent), 18839and this node must be the first node in the included file. 18840Furthermore, each of these highest level nodes in each included file 18841must be at the same hierarchical level in the file structure. 18842Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an 18843@code{@@unnumbered} node. Thus, normally, each included file contains 18844one, and only one, chapter or equivalent-level node.@refill 18845 18846The outer file should contain only @emph{one} node, the `Top' node. It 18847should @emph{not} contain any nodes besides the single `Top' node. The 18848@code{texinfo-multiple-files-update} command will not process 18849them.@refill 18850 18851 18852@node Sample Include File 18853@section Sample File with @code{@@include} 18854@cindex Sample @code{@@include} file 18855@cindex Include file sample 18856@cindex @code{@@include} file sample 18857 18858Here is an example of an outer Texinfo file with @code{@@include} files 18859within it before running @code{texinfo-multiple-files-update}, which 18860would insert a main or master menu: 18861 18862@example 18863@group 18864\input texinfo @@c -*-texinfo-*- 18865@c %**start of header 18866@@setfilename include-example.info 18867@@settitle Include Example 18868@c %**end of header 18869@end group 18870 18871... @xref{Sample Texinfo Files}, for 18872examples of the rest of the frontmatter ... 18873 18874@group 18875@@ifnottex 18876@@node Top 18877@@top Include Example 18878@@end ifnottex 18879@end group 18880 18881@group 18882@@include foo.texinfo 18883@@include bar.texinfo 18884@@include concept-index.texinfo 18885@@bye 18886@end group 18887@end example 18888 18889An included file, such as @file{foo.texinfo}, might look like this: 18890 18891@example 18892@group 18893@@node First 18894@@chapter First Chapter 18895 18896Contents of first chapter @dots{} 18897@end group 18898@end example 18899 18900The full contents of @file{concept-index.texinfo} might be as simple as this: 18901 18902@example 18903@group 18904@@node Concept Index 18905@@unnumbered Concept Index 18906 18907@@printindex cp 18908@end group 18909@end example 18910 18911The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference 18912Manual} is named @file{elisp.texi}. This outer file contains a master 18913menu with 417 entries and a list of 41 @code{@@include} 18914files. 18915 18916 18917@node Include Files Evolution 18918@section Evolution of Include Files 18919 18920When Info was first created, it was customary to create many small 18921Info files on one subject. Each Info file was formatted from its own 18922Texinfo source file. This custom meant that Emacs did not need to 18923make a large buffer to hold the whole of a large Info file when 18924someone wanted information; instead, Emacs allocated just enough 18925memory for the small Info file that contained the particular 18926information sought. This way, Emacs could avoid wasting memory.@refill 18927 18928References from one file to another were made by referring to the file 18929name as well as the node name. (@xref{Other Info Files, , Referring to 18930Other Info Files}. Also, see @ref{Four and Five Arguments, , 18931@code{@@xref} with Four and Five Arguments}.)@refill 18932 18933Include files were designed primarily as a way to create a single, 18934large printed manual out of several smaller Info files. In a printed 18935manual, all the references were within the same document, so @TeX{} 18936could automatically determine the references' page numbers. The Info 18937formatting commands used include files only for creating joint 18938indices; each of the individual Texinfo files had to be formatted for 18939Info individually. (Each, therefore, required its own 18940@code{@@setfilename} line.)@refill 18941 18942However, because large Info files are now split automatically, it is 18943no longer necessary to keep them small.@refill 18944 18945Nowadays, multiple Texinfo files are used mostly for large documents, 18946such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects 18947in which several different people write different sections of a 18948document simultaneously.@refill 18949 18950In addition, the Info formatting commands have been extended to work 18951with the @code{@@include} command so as to create a single large Info 18952file that is split into smaller files if necessary. This means that 18953you can write menus and cross references without naming the different 18954Texinfo files.@refill 18955 18956 18957@node Headings 18958@appendix Page Headings 18959@cindex Headings 18960@cindex Footings 18961@cindex Page numbering 18962@cindex Page headings 18963@cindex Formatting headings and footings 18964 18965Most printed manuals contain headings along the top of every page 18966except the title and copyright pages. Some manuals also contain 18967footings. (Headings and footings have no meaning to Info, which is 18968not paginated.)@refill 18969 18970@menu 18971* Headings Introduced:: Conventions for using page headings. 18972* Heading Format:: Standard page heading formats. 18973* Heading Choice:: How to specify the type of page heading. 18974* Custom Headings:: How to create your own headings and footings. 18975@end menu 18976 18977@node Headings Introduced 18978@section Headings Introduced 18979 18980Texinfo provides standard page heading formats for manuals that are 18981printed on one side of each sheet of paper and for manuals that are 18982printed on both sides of the paper. Typically, you will use these 18983formats, but you can specify your own format if you wish.@refill 18984 18985In addition, you can specify whether chapters should begin on a new 18986page, or merely continue the same page as the previous chapter; and if 18987chapters begin on new pages, you can specify whether they must be 18988odd-numbered pages.@refill 18989 18990By convention, a book is printed on both sides of each sheet of paper. 18991When you open a book, the right-hand page is odd-numbered, and 18992chapters begin on right-hand pages---a preceding left-hand page is 18993left blank if necessary. Reports, however, are often printed on just 18994one side of paper, and chapters begin on a fresh page immediately 18995following the end of the preceding chapter. In short or informal 18996reports, chapters often do not begin on a new page at all, but are 18997separated from the preceding text by a small amount of whitespace.@refill 18998 18999The @code{@@setchapternewpage} command controls whether chapters begin 19000on new pages, and whether one of the standard heading formats is used. 19001In addition, Texinfo has several heading and footing commands that you 19002can use to generate your own heading and footing formats.@refill 19003 19004In Texinfo, headings and footings are single lines at the tops and 19005bottoms of pages; you cannot create multiline headings or footings. 19006Each header or footer line is divided into three parts: a left part, a 19007middle part, and a right part. Any part, or a whole line, may be left 19008blank. Text for the left part of a header or footer line is set 19009flushleft; text for the middle part is centered; and, text for the 19010right part is set flushright.@refill 19011 19012@node Heading Format 19013@comment node-name, next, previous, up 19014@section Standard Heading Formats 19015 19016Texinfo provides two standard heading formats, one for manuals printed 19017on one side of each sheet of paper, and the other for manuals printed 19018on both sides of the paper. 19019 19020By default, nothing is specified for the footing of a Texinfo file, 19021so the footing remains blank.@refill 19022 19023The standard format for single-sided printing consists of a header 19024line in which the left-hand part contains the name of the chapter, the 19025central part is blank, and the right-hand part contains the page 19026number.@refill 19027 19028@need 950 19029A single-sided page looks like this: 19030 19031@example 19032@group 19033 _______________________ 19034 | | 19035 | chapter page number | 19036 | | 19037 | Start of text ... | 19038 | ... | 19039 | | 19040@end group 19041@end example 19042 19043The standard format for two-sided printing depends on whether the page 19044number is even or odd. By convention, even-numbered pages are on the 19045left- and odd-numbered pages are on the right. (@TeX{} will adjust the 19046widths of the left- and right-hand margins. Usually, widths are 19047correct, but during double-sided printing, it is wise to check that 19048pages will bind properly---sometimes a printer will produce output in 19049which the even-numbered pages have a larger right-hand margin than the 19050odd-numbered pages.)@refill 19051 19052In the standard double-sided format, the left part of the left-hand 19053(even-numbered) page contains the page number, the central part is 19054blank, and the right part contains the title (specified by the 19055@code{@@settitle} command). The left part of the right-hand 19056(odd-numbered) page contains the name of the chapter, the central part 19057is blank, and the right part contains the page number.@refill 19058 19059@need 750 19060Two pages, side by side as in an open book, look like this:@refill 19061 19062@example 19063@group 19064 _______________________ _______________________ 19065 | | | | 19066 | page number title | | chapter page number | 19067 | | | | 19068 | Start of text ... | | More text ... | 19069 | ... | | ... | 19070 | | | | 19071@end group 19072@end example 19073 19074@noindent 19075The chapter name is preceded by the word ``Chapter'', the chapter number 19076and a colon. This makes it easier to keep track of where you are in the 19077manual.@refill 19078 19079@node Heading Choice 19080@comment node-name, next, previous, up 19081@section Specifying the Type of Heading 19082 19083@TeX{} does not begin to generate page headings for a standard Texinfo 19084file until it reaches the @code{@@end titlepage} command. Thus, the 19085title and copyright pages are not numbered. The @code{@@end 19086titlepage} command causes @TeX{} to begin to generate page headings 19087according to a standard format specified by the 19088@code{@@setchapternewpage} command that precedes the 19089@code{@@titlepage} section.@refill 19090 19091@need 1000 19092There are four possibilities:@refill 19093 19094@table @asis 19095@item No @code{@@setchapternewpage} command 19096Cause @TeX{} to specify the single-sided heading format, with chapters 19097on new pages. This is the same as @code{@@setchapternewpage on}.@refill 19098 19099@item @code{@@setchapternewpage on} 19100Specify the single-sided heading format, with chapters on new pages.@refill 19101 19102@item @code{@@setchapternewpage off} 19103Cause @TeX{} to start a new chapter on the same page as the last page of 19104the preceding chapter, after skipping some vertical whitespace. Also 19105cause @TeX{} to typeset for single-sided printing. (You can override 19106the headers format with the @code{@@headings double} command; see 19107@ref{headings on off, , The @code{@@headings} Command}.)@refill 19108 19109@item @code{@@setchapternewpage odd} 19110Specify the double-sided heading format, with chapters on new pages.@refill 19111@end table 19112 19113@noindent 19114Texinfo lacks an @code{@@setchapternewpage even} command.@refill 19115 19116@node Custom Headings 19117@comment node-name, next, previous, up 19118@section How to Make Your Own Headings 19119 19120You can use the standard headings provided with Texinfo or specify 19121your own. By default, Texinfo has no footers, so if you specify them, 19122the available page size for the main text will be slightly reduced. 19123 19124Texinfo provides six commands for specifying headings and 19125footings: 19126@itemize @bullet 19127@item 19128@code{@@everyheading} @code{@@everyfooting} generate page headers and 19129footers that are the same for both even- and odd-numbered pages. 19130@item 19131@code{@@evenheading} and @code{@@evenfooting} command generate headers 19132and footers for even-numbered (left-hand) pages. 19133@item 19134@code{@@oddheading} and @code{@@oddfooting} generate headers and footers 19135for odd-numbered (right-hand) pages. 19136@end itemize 19137 19138Write custom heading specifications in the Texinfo file immediately 19139after the @code{@@end titlepage} command. 19140You must cancel the predefined heading commands with the 19141@code{@@headings off} command before defining your own 19142specifications.@refill 19143 19144@need 1000 19145Here is how to tell @TeX{} to place the chapter name at the left, the 19146page number in the center, and the date at the right of every header 19147for both even- and odd-numbered pages:@refill 19148 19149@example 19150@group 19151@@headings off 19152@@everyheading @@thischapter @@| @@thispage @@| @@today@{@} 19153@end group 19154@end example 19155 19156@noindent 19157You need to divide the left part from the central part and the central 19158part from the right part by inserting @samp{@@|} between parts. 19159Otherwise, the specification command will not be able to tell where 19160the text for one part ends and the next part begins.@refill 19161 19162Each part can contain text or @@-commands. The text 19163is printed as if the part were within an ordinary paragraph in the 19164body of the page. The @@-commands replace 19165themselves with the page number, date, chapter name, or 19166whatever.@refill 19167 19168@need 950 19169Here are the six heading and footing commands:@refill 19170 19171@findex everyheading 19172@findex everyfooting 19173@table @code 19174@item @@everyheading @var{left} @@| @var{center} @@| @var{right} 19175@itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right} 19176 19177The `every' commands specify the format for both even- and odd-numbered 19178pages. These commands are for documents that are printed on one side 19179of each sheet of paper, or for documents in which you want symmetrical 19180headers or footers.@refill 19181 19182@findex evenheading 19183@findex evenfooting 19184@findex oddheading 19185@findex oddfooting 19186@item @@evenheading @var{left} @@| @var{center} @@| @var{right} 19187@itemx @@oddheading @var{left} @@| @var{center} @@| @var{right} 19188@itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right} 19189@itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right} 19190 19191The `even' and `odd' commands specify the format for even-numbered 19192pages and odd-numbered pages. These commands are for books and 19193manuals that are printed on both sides of each sheet of paper. 19194@end table 19195 19196Use the @samp{@@this@dots{}} series of @@-commands to 19197provide the names of chapters 19198and sections and the page number. You can use the 19199@samp{@@this@dots{}} commands in the left, center, or right portions 19200of headers and footers, or anywhere else in a Texinfo file so long as 19201they are between @code{@@iftex} and @code{@@end iftex} commands.@refill 19202 19203@need 1000 19204Here are the @samp{@@this@dots{}} commands:@refill 19205 19206@table @code 19207@findex thispage 19208@item @@thispage 19209Expands to the current page number.@refill 19210@c !!! Karl Berry says that `thissection' can fail on page breaks. 19211@ignore 19212@item @@thissection 19213Expands to the name of the current section.@refill 19214@end ignore 19215 19216@findex thischaptername 19217@item @@thischaptername 19218Expands to the name of the current chapter.@refill 19219 19220@findex thischapter 19221@item @@thischapter 19222Expands to the number and name of the current 19223chapter, in the format `Chapter 1: Title'.@refill 19224 19225@findex thistitle 19226@item @@thistitle 19227Expands to the name of the document, as specified by the 19228@code{@@settitle} command.@refill 19229 19230@findex thisfile 19231@item @@thisfile 19232For @code{@@include} files only: expands to the name of the current 19233@code{@@include} file. If the current Texinfo source file is not an 19234@code{@@include} file, this command has no effect. This command does 19235@emph{not} provide the name of the current Texinfo source file unless 19236it is an @code{@@include} file. (@xref{Include Files}, for more 19237information about @code{@@include} files.)@refill 19238@end table 19239 19240@noindent 19241You can also use the @code{@@today@{@}} command, which expands to the 19242current date, in `1 Jan 1900' format.@refill 19243@findex today 19244 19245Other @@-commands and text are printed in a header or footer just as 19246if they were in the body of a page. It is useful to incorporate text, 19247particularly when you are writing drafts:@refill 19248 19249@example 19250@group 19251@@headings off 19252@@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter 19253@@everyfooting @@| @@| Version: 0.27: @@today@{@} 19254@end group 19255@end example 19256 19257Beware of overlong titles: they may overlap another part of the 19258header or footer and blot it out.@refill 19259 19260 19261@node Catching Mistakes 19262@appendix Formatting Mistakes 19263@cindex Structure, catching mistakes in 19264@cindex Nodes, catching mistakes 19265@cindex Catching mistakes 19266@cindex Correcting mistakes 19267@cindex Mistakes, catching 19268@cindex Problems, catching 19269@cindex Debugging the Texinfo structure 19270 19271Besides mistakes in the content of your documentation, there are two 19272kinds of mistake you can make with Texinfo: you can make mistakes with 19273@@-commands, and you can make mistakes with the structure of the nodes 19274and chapters. 19275 19276Emacs has two tools for catching the @@-command mistakes and two for 19277catching structuring mistakes.@refill 19278 19279For finding problems with @@-commands, you can run @TeX{} or a region 19280formatting command on the region that has a problem; indeed, you can 19281run these commands on each region as you write it.@refill 19282 19283For finding problems with the structure of nodes and chapters, you can use 19284@kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur} 19285command and you can use the @kbd{M-x Info-validate} command.@refill 19286 19287@menu 19288* makeinfo Preferred:: @code{makeinfo} finds errors. 19289* Debugging with Info:: How to catch errors with Info formatting. 19290* Debugging with TeX:: How to catch errors with @TeX{} formatting. 19291* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. 19292* Using occur:: How to list all lines containing a pattern. 19293* Running Info-Validate:: How to find badly referenced nodes. 19294@end menu 19295 19296 19297@node makeinfo Preferred 19298@section @code{makeinfo} Find Errors 19299 19300The @code{makeinfo} program does an excellent job of catching errors 19301and reporting them---far better than @code{texinfo-format-region} or 19302@code{texinfo-format-buffer}. In addition, the various functions for 19303automatically creating and updating node pointers and menus remove 19304many opportunities for human error.@refill 19305 19306If you can, use the updating commands to create and insert pointers 19307and menus. These prevent many errors. Then use @code{makeinfo} (or 19308its Texinfo mode manifestations, @code{makeinfo-region} and 19309@code{makeinfo-buffer}) to format your file and check for other 19310errors. This is the best way to work with Texinfo. But if you 19311cannot use @code{makeinfo}, or your problem is very puzzling, then you 19312may want to use the tools described in this appendix.@refill 19313 19314@node Debugging with Info 19315@comment node-name, next, previous, up 19316@section Catching Errors with Info Formatting 19317@cindex Catching errors with Info formatting 19318@cindex Debugging with Info formatting 19319 19320After you have written part of a Texinfo file, you can use the 19321@code{texinfo-format-region} or the @code{makeinfo-region} command to 19322see whether the region formats properly.@refill 19323 19324Most likely, however, you are reading this section because for some 19325reason you cannot use the @code{makeinfo-region} command; therefore, the 19326rest of this section presumes that you are using 19327@code{texinfo-format-region}.@refill 19328 19329If you have made a mistake with an @@-command, 19330@code{texinfo-format-region} will stop processing at or after the 19331error and display an error message. To see where in the buffer the 19332error occurred, switch to the @samp{*Info Region*} buffer; the cursor 19333will be in a position that is after the location of the error. Also, 19334the text will not be formatted after the place where the error 19335occurred (or more precisely, where it was detected).@refill 19336 19337For example, if you accidentally end a menu with the command @code{@@end 19338menus} with an `s' on the end, instead of with @code{@@end menu}, you 19339will see an error message that says:@refill 19340 19341@example 19342@@end menus is not handled by texinfo 19343@end example 19344 19345@noindent 19346The cursor will stop at the point in the buffer where the error 19347occurs, or not long after it. The buffer will look like this:@refill 19348 19349@example 19350@group 19351---------- Buffer: *Info Region* ---------- 19352* Menu: 19353 19354* Using texinfo-show-structure:: How to use 19355 `texinfo-show-structure' 19356 to catch mistakes. 19357* Running Info-Validate:: How to check for 19358 unreferenced nodes. 19359@@end menus 19360@point{} 19361---------- Buffer: *Info Region* ---------- 19362@end group 19363@end example 19364 19365The @code{texinfo-format-region} command sometimes provides slightly 19366odd error messages. For example, the following cross reference fails to format:@refill 19367 19368@example 19369(@@xref@{Catching Mistakes, for more info.) 19370@end example 19371 19372@noindent 19373In this case, @code{texinfo-format-region} detects the missing closing 19374brace but displays a message that says @samp{Unbalanced parentheses} 19375rather than @samp{Unbalanced braces}. This is because the formatting 19376command looks for mismatches between braces as if they were 19377parentheses.@refill 19378 19379Sometimes @code{texinfo-format-region} fails to detect mistakes. For 19380example, in the following, the closing brace is swapped with the 19381closing parenthesis:@refill 19382 19383@example 19384(@@xref@{Catching Mistakes), for more info.@} 19385@end example 19386 19387@noindent 19388Formatting produces: 19389@example 19390(*Note for more info.: Catching Mistakes) 19391@end example 19392 19393The only way for you to detect this error is to realize that the 19394reference should have looked like this:@refill 19395 19396@example 19397(*Note Catching Mistakes::, for more info.) 19398@end example 19399 19400Incidentally, if you are reading this node in Info and type @kbd{f 19401@key{RET}} (@code{Info-follow-reference}), you will generate an error 19402message that says: 19403 19404@example 19405No such node: "Catching Mistakes) The only way @dots{} 19406@end example 19407 19408@noindent 19409This is because Info perceives the example of the error as the first 19410cross reference in this node and if you type a @key{RET} immediately 19411after typing the Info @kbd{f} command, Info will attempt to go to the 19412referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info 19413will complete the node name of the correctly written example and take 19414you to the `Catching Mistakes' node. (If you try this, you can return 19415from the `Catching Mistakes' node by typing @kbd{l} 19416(@code{Info-last}).) 19417 19418@c !!! section on using Elisp debugger ignored. 19419@ignore 19420Sometimes @code{texinfo-format-region} will stop long after the 19421original error; this is because it does not discover the problem until 19422then. In this case, you will need to backtrack.@refill 19423 19424@c menu 19425@c * Using the Emacs Lisp Debugger:: How to use the Emacs Lisp debugger. 19426@c end menu 19427 19428@c node Using the Emacs Lisp Debugger 19429@c appendixsubsec Using the Emacs Lisp Debugger 19430@c index Using the Emacs Lisp debugger 19431@c index Emacs Lisp debugger 19432@c index Debugger, using the Emacs Lisp 19433 19434If an error is especially elusive, you can turn on the Emacs Lisp 19435debugger and look at the backtrace; this tells you where in the 19436@code{texinfo-format-region} function the problem occurred. You can 19437turn on the debugger with the command:@refill 19438 19439@example 19440M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET} 19441@end example 19442 19443@noindent 19444and turn it off with 19445 19446@example 19447M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET} 19448@end example 19449 19450Often, when you are using the debugger, it is easier to follow what is 19451going on if you use the Emacs Lisp files that are not byte-compiled. 19452The byte-compiled sources send octal numbers to the debugger that may 19453look mysterious. To use the uncompiled source files, load 19454@file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file} 19455command.@refill 19456 19457The debugger will not catch an error if @code{texinfo-format-region} 19458does not detect one. In the example shown above, 19459@code{texinfo-format-region} did not find the error when the whole 19460list was formatted, but only when part of the list was formatted. 19461When @code{texinfo-format-region} did not find an error, the debugger 19462did not find one either. @refill 19463 19464However, when @code{texinfo-format-region} did report an error, it 19465invoked the debugger. This is the backtrace it produced:@refill 19466 19467@example 19468---------- Buffer: *Backtrace* ---------- 19469Signalling: (search-failed "[@},]") 19470 re-search-forward("[@},]") 19471 (while ...) 19472 (let ...) 19473 texinfo-format-parse-args() 19474 (let ...) 19475 texinfo-format-xref() 19476 funcall(texinfo-format-xref) 19477 (if ...) 19478 (let ...) 19479 (if ...) 19480 (while ...) 19481 texinfo-format-scan() 19482 (save-excursion ...) 19483 (let ...) 19484 texinfo-format-region(103370 103631) 19485* call-interactively(texinfo-format-region) 19486---------- Buffer: *Backtrace* ---------- 19487@end example 19488 19489The backtrace is read from the bottom up. 19490@code{texinfo-format-region} was called interactively; and it, in 19491turn, called various functions, including @code{texinfo-format-scan}, 19492@code{texinfo-format-xref} and @code{texinfo-format-parse-args}. 19493Inside the function @code{texinfo-format-parse-args}, the function 19494@code{re-search-forward} was called; it was this function that could 19495not find the missing right-hand brace.@refill 19496 19497@xref{Lisp Debug, , Debugging Emacs Lisp, emacs, The GNU Emacs 19498Manual}, for more information.@refill 19499@end ignore 19500 19501@node Debugging with TeX 19502@comment node-name, next, previous, up 19503@section Catching Errors with @TeX{} Formatting 19504@cindex Catching errors with @TeX{} formatting 19505@cindex Debugging with @TeX{} formatting 19506 19507You can also catch mistakes when you format a file with @TeX{}.@refill 19508 19509Usually, you will want to do this after you have run 19510@code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on 19511the same file, because @code{texinfo-format-buffer} sometimes displays 19512error messages that make more sense than @TeX{}. (@xref{Debugging 19513with Info}, for more information.)@refill 19514 19515For example, @TeX{} was run on a Texinfo file, part of which is shown 19516here:@refill 19517 19518@example 19519---------- Buffer: texinfo.texi ---------- 19520name of the Texinfo file as an extension. The 19521@@samp@{??@} are `wildcards' that cause the shell to 19522substitute all the raw index files. (@@xref@{sorting 19523indices, for more information about sorting 19524indices.)@@refill 19525---------- Buffer: texinfo.texi ---------- 19526@end example 19527 19528@noindent 19529(The cross reference lacks a closing brace.) 19530@TeX{} produced the following output, after which it stopped:@refill 19531 19532@example 19533---------- Buffer: *tex-shell* ---------- 19534Runaway argument? 19535@{sorting indices, for more information about sorting 19536indices.) @@refill @@ETC. 19537! Paragraph ended before @@xref was complete. 19538<to be read again> 19539 @@par 19540l.27 19541 19542? 19543---------- Buffer: *tex-shell* ---------- 19544@end example 19545 19546In this case, @TeX{} produced an accurate and 19547understandable error message: 19548 19549@example 19550Paragraph ended before @@xref was complete. 19551@end example 19552 19553@noindent 19554@samp{@@par} is an internal @TeX{} command of no relevance to Texinfo. 19555@samp{l.27} means that @TeX{} detected the problem on line 27 of the 19556Texinfo file. The @samp{?} is the prompt @TeX{} uses in this 19557circumstance.@refill 19558 19559Unfortunately, @TeX{} is not always so helpful, and sometimes you must 19560truly be a Sherlock Holmes to discover what went wrong.@refill 19561 19562In any case, if you run into a problem like this, you can do one of three 19563things.@refill 19564 19565@enumerate 19566@item 19567You can tell @TeX{} to continue running and ignore just this error by 19568typing @key{RET} at the @samp{?} prompt.@refill 19569 19570@item 19571You can tell @TeX{} to continue running and to ignore all errors as best 19572it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill 19573 19574This is often the best thing to do. However, beware: the one error 19575may produce a cascade of additional error messages as its consequences 19576are felt through the rest of the file. To stop @TeX{} when it is 19577producing such an avalanche of error messages, type @kbd{C-c} (or 19578@kbd{C-c C-c}, if you are running a shell inside Emacs). 19579 19580@item 19581You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}} 19582at the @samp{?} prompt.@refill 19583@end enumerate 19584 19585If you are running @TeX{} inside Emacs, you need to switch to the shell 19586buffer and line at which @TeX{} offers the @samp{?} prompt. 19587 19588Sometimes @TeX{} will format a file without producing error messages even 19589though there is a problem. This usually occurs if a command is not ended 19590but @TeX{} is able to continue processing anyhow. For example, if you fail 19591to end an itemized list with the @code{@@end itemize} command, @TeX{} will 19592write a DVI file that you can print out. The only error message that 19593@TeX{} will give you is the somewhat mysterious comment that@refill 19594 19595@example 19596(@@end occurred inside a group at level 1) 19597@end example 19598 19599@noindent 19600However, if you print the DVI file, you will find that the text 19601of the file that follows the itemized list is entirely indented as if 19602it were part of the last item in the itemized list. The error message 19603is the way @TeX{} says that it expected to find an @code{@@end} 19604command somewhere in the file; but that it could not determine where 19605it was needed.@refill 19606 19607Another source of notoriously hard-to-find errors is a missing 19608@code{@@end group} command. If you ever are stumped by 19609incomprehensible errors, look for a missing @code{@@end group} command 19610first.@refill 19611 19612If the Texinfo file lacks header lines, 19613@TeX{} may stop in the 19614beginning of its run and display output that looks like the following. 19615The @samp{*} indicates that @TeX{} is waiting for input.@refill 19616 19617@example 19618This is TeX, Version 3.14159 (Web2c 7.0) 19619(test.texinfo [1]) 19620* 19621@end example 19622 19623@noindent 19624In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then 19625write the header lines in the Texinfo file and run the @TeX{} command 19626again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\} 19627instead of @samp{@@}; and in this circumstance, you are working 19628directly with @TeX{}, not with Texinfo.)@refill 19629 19630@node Using texinfo-show-structure 19631@comment node-name, next, previous, up 19632@section Using @code{texinfo-show-structure} 19633@cindex Showing the structure of a file 19634@findex texinfo-show-structure 19635 19636It is not always easy to keep track of the nodes, chapters, sections, and 19637subsections of a Texinfo file. This is especially true if you are revising 19638or adding to a Texinfo file that someone else has written.@refill 19639 19640In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure} 19641command lists all the lines that begin with the @@-commands that 19642specify the structure: @code{@@chapter}, @code{@@section}, 19643@code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}} 19644as prefix argument, if interactive), 19645the command also shows the @code{@@node} lines. The 19646@code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in 19647Texinfo mode, by default.@refill 19648 19649The lines are displayed in a buffer called the @samp{*Occur*} buffer, 19650indented by hierarchical level. For example, here is a part of what was 19651produced by running @code{texinfo-show-structure} on this manual:@refill 19652 19653@example 19654@group 19655Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\| 19656unnum\\|major\\|chapheading \\|heading \\|appendix\\)" 19657in buffer texinfo.texi. 19658@dots{} 196594177:@@chapter Nodes 196604198: @@heading Two Paths 196614231: @@section Node and Menu Illustration 196624337: @@section The @@code@{@@@@node@} Command 196634393: @@subheading Choosing Node and Pointer Names 196644417: @@subsection How to Write an @@code@{@@@@node@} Line 196654469: @@subsection @@code@{@@@@node@} Line Tips 19666@dots{} 19667@end group 19668@end example 19669 19670This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin 19671with the @code{@@section}, @code{@@subheading}, and @code{@@subsection} 19672commands respectively. If you move your cursor into the @samp{*Occur*} 19673window, you can position the cursor over one of the lines and use the 19674@kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to 19675the corresponding spot in the Texinfo file. @xref{Other Repeating 19676Search, , Using Occur, emacs, The GNU Emacs Manual}, for more 19677information about @code{occur-mode-goto-occurrence}.@refill 19678 19679The first line in the @samp{*Occur*} window describes the @dfn{regular 19680expression} specified by @var{texinfo-heading-pattern}. This regular 19681expression is the pattern that @code{texinfo-show-structure} looks for. 19682@xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual}, 19683for more information.@refill 19684 19685When you invoke the @code{texinfo-show-structure} command, Emacs will 19686display the structure of the whole buffer. If you want to see the 19687structure of just a part of the buffer, of one chapter, for example, 19688use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the 19689region. (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.) This is 19690how the example used above was generated. (To see the whole buffer 19691again, use @kbd{C-x n w} (@code{widen}).)@refill 19692 19693If you call @code{texinfo-show-structure} with a prefix argument by 19694typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with 19695@code{@@node} as well as the lines beginning with the @@-sign commands 19696for @code{@@chapter}, @code{@@section}, and the like.@refill 19697 19698You can remind yourself of the structure of a Texinfo file by looking at 19699the list in the @samp{*Occur*} window; and if you have mis-named a node 19700or left out a section, you can correct the mistake.@refill 19701 19702@node Using occur 19703@comment node-name, next, previous, up 19704@section Using @code{occur} 19705@cindex Occurrences, listing with @code{@@occur} 19706@findex occur 19707 19708Sometimes the @code{texinfo-show-structure} command produces too much 19709information. Perhaps you want to remind yourself of the overall structure 19710of a Texinfo file, and are overwhelmed by the detailed list produced by 19711@code{texinfo-show-structure}. In this case, you can use the @code{occur} 19712command directly. To do this, type@refill 19713 19714@example 19715@kbd{M-x occur} 19716@end example 19717 19718@noindent 19719and then, when prompted, type a @dfn{regexp}, a regular expression for 19720the pattern you want to match. (@xref{Regexps, , Regular Expressions, 19721emacs, The GNU Emacs Manual}.) The @code{occur} command works from 19722the current location of the cursor in the buffer to the end of the 19723buffer. If you want to run @code{occur} on the whole buffer, place 19724the cursor at the beginning of the buffer.@refill 19725 19726For example, to see all the lines that contain the word 19727@samp{@@chapter} in them, just type @samp{@@chapter}. This will 19728produce a list of the chapters. It will also list all the sentences 19729with @samp{@@chapter} in the middle of the line.@refill 19730 19731If you want to see only those lines that start with the word 19732@samp{@@chapter}, type @samp{^@@chapter} when prompted by 19733@code{occur}. If you want to see all the lines that end with a word 19734or phrase, end the last word with a @samp{$}; for example, 19735@samp{catching mistakes$}. This can be helpful when you want to see 19736all the nodes that are part of the same chapter or section and 19737therefore have the same `Up' pointer.@refill 19738 19739@xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual}, 19740for more information.@refill 19741 19742@node Running Info-Validate 19743@comment node-name, next, previous, up 19744@section Finding Badly Referenced Nodes 19745@findex Info-validate 19746@cindex Nodes, checking for badly referenced 19747@cindex Checking for badly referenced nodes 19748@cindex Looking for badly referenced nodes 19749@cindex Finding badly referenced nodes 19750@cindex Badly referenced nodes 19751 19752You can use the @code{Info-validate} command to check whether any of 19753the `Next', `Previous', `Up' or other node pointers fail to point to a 19754node. This command checks that every node pointer points to an 19755existing node. The @code{Info-validate} command works only on Info 19756files, not on Texinfo files.@refill 19757 19758The @code{makeinfo} program validates pointers automatically, so you 19759do not need to use the @code{Info-validate} command if you are using 19760@code{makeinfo}. You only may need to use @code{Info-validate} if you 19761are unable to run @code{makeinfo} and instead must create an Info file 19762using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or 19763if you write an Info file from scratch.@refill 19764 19765@menu 19766* Using Info-validate:: How to run @code{Info-validate}. 19767* Unsplit:: How to create an unsplit file. 19768* Tagifying:: How to tagify a file. 19769* Splitting:: How to split a file manually. 19770@end menu 19771 19772@node Using Info-validate 19773@subsection Running @code{Info-validate} 19774@cindex Running @code{Info-validate} 19775@cindex Info validating a large file 19776@cindex Validating a large file 19777 19778To use @code{Info-validate}, visit the Info file you wish to check and 19779type:@refill 19780 19781@example 19782M-x Info-validate 19783@end example 19784 19785@noindent 19786Note that the @code{Info-validate} command requires an upper case 19787`I'. You may also need to create a tag table before running 19788@code{Info-validate}. @xref{Tagifying}. 19789 19790If your file is valid, you will receive a message that says ``File appears 19791valid''. However, if you have a pointer that does not point to a node, 19792error messages will be displayed in a buffer called @samp{*problems in 19793info file*}.@refill 19794 19795For example, @code{Info-validate} was run on a test file that contained 19796only the first node of this manual. One of the messages said:@refill 19797 19798@example 19799In node "Overview", invalid Next: Texinfo Mode 19800@end example 19801 19802@noindent 19803This meant that the node called @samp{Overview} had a `Next' pointer that 19804did not point to anything (which was true in this case, since the test file 19805had only one node in it).@refill 19806 19807Now suppose we add a node named @samp{Texinfo Mode} to our test case 19808but we do not specify a `Previous' for this node. Then we will get 19809the following error message:@refill 19810 19811@example 19812In node "Texinfo Mode", should have Previous: Overview 19813@end example 19814 19815@noindent 19816This is because every `Next' pointer should be matched by a 19817`Previous' (in the node where the `Next' points) which points back.@refill 19818 19819@code{Info-validate} also checks that all menu entries and cross references 19820point to actual nodes.@refill 19821 19822@code{Info-validate} requires a tag table and does not work with files 19823that have been split. (The @code{texinfo-format-buffer} command 19824automatically splits large files.) In order to use @code{Info-validate} 19825on a large file, you must run @code{texinfo-format-buffer} with an 19826argument so that it does not split the Info file; and you must create a 19827tag table for the unsplit file. 19828 19829@node Unsplit 19830@comment node-name, next, previous, up 19831@subsection Creating an Unsplit File 19832@cindex Creating an unsplit file 19833@cindex Unsplit file creation 19834 19835You can run @code{Info-validate} only on a single Info file that has a 19836tag table. The command will not work on the indirect subfiles that 19837are generated when a master file is split. If you have a large file 19838(longer than 300,000 bytes or so), you need to run the 19839@code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such 19840a way that it does not create indirect subfiles. You will also need 19841to create a tag table for the Info file. After you have done this, 19842you can run @code{Info-validate} and look for badly referenced 19843nodes.@refill 19844 19845The first step is to create an unsplit Info file. To prevent 19846@code{texinfo-format-buffer} from splitting a Texinfo file into 19847smaller Info files, give a prefix to the @kbd{M-x 19848texinfo-format-buffer} command:@refill 19849 19850@example 19851C-u M-x texinfo-format-buffer 19852@end example 19853 19854@noindent 19855or else 19856 19857@example 19858C-u C-c C-e C-b 19859@end example 19860 19861@noindent 19862When you do this, Texinfo will not split the file and will not create 19863a tag table for it. @refill 19864@cindex Making a tag table manually 19865@cindex Tag table, making manually 19866 19867@node Tagifying 19868@subsection Tagifying a File 19869 19870After creating an unsplit Info file, you must create a tag table for 19871it. Visit the Info file you wish to tagify and type:@refill 19872 19873@example 19874M-x Info-tagify 19875@end example 19876 19877@noindent 19878(Note the upper case @samp{I} in @code{Info-tagify}.) This creates an 19879Info file with a tag table that you can validate.@refill 19880 19881The third step is to validate the Info file:@refill 19882 19883@example 19884M-x Info-validate 19885@end example 19886 19887@noindent 19888(Note the upper case @samp{I} in @code{Info-validate}.) 19889In brief, the steps are:@refill 19890 19891@example 19892@group 19893C-u M-x texinfo-format-buffer 19894M-x Info-tagify 19895M-x Info-validate 19896@end group 19897@end example 19898 19899After you have validated the node structure, you can rerun 19900@code{texinfo-format-buffer} in the normal way so it will construct a 19901tag table and split the file automatically, or you can make the tag 19902table and split the file manually.@refill 19903 19904@node Splitting 19905@comment node-name, next, previous, up 19906@subsection Splitting a File Manually 19907@cindex Splitting an Info file manually 19908@cindex Info file, splitting manually 19909 19910You should split a large file or else let the 19911@code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it 19912for you automatically. (Generally you will let one of the formatting 19913commands do this job for you. @xref{Creating an Info File}.)@refill 19914 19915The split-off files are called the indirect subfiles.@refill 19916 19917Info files are split to save memory. With smaller files, Emacs does not 19918have make such a large buffer to hold the information.@refill 19919 19920If an Info file has more than 30 nodes, you should also make a tag 19921table for it. @xref{Using Info-validate}, for information 19922about creating a tag table. (Again, tag tables are usually created 19923automatically by the formatting command; you only need to create a tag 19924table yourself if you are doing the job manually. Most likely, you 19925will do this for a large, unsplit file on which you have run 19926@code{Info-validate}.)@refill 19927 19928@c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51 19929@ignore 19930Before running @code{Info-split}, you need to load the @code{info} library 19931into Emacs by giving the command @kbd{M-x load-library @key{RET} info 19932@key{RET}}. 19933@end ignore 19934 19935Visit the Info file you wish to tagify and split and type the two 19936commands:@refill 19937 19938@example 19939M-x Info-tagify 19940M-x Info-split 19941@end example 19942 19943@noindent 19944(Note that the @samp{I} in @samp{Info} is upper case.)@refill 19945 19946When you use the @code{Info-split} command, the buffer is modified into a 19947(small) Info file which lists the indirect subfiles. This file should be 19948saved in place of the original visited file. The indirect subfiles are 19949written in the same directory the original file is in, with names generated 19950by appending @samp{-} and a number to the original file name.@refill 19951 19952The primary file still functions as an Info file, but it contains just 19953the tag table and a directory of subfiles.@refill 19954 19955 19956@ignore 19957The simple description in the command summary seems sufficient to me 19958these days, so ignore this appendix. --karl, 13mar04. 19959 19960@node Refilling Paragraphs 19961@appendix Refilling Paragraphs 19962@cindex Refilling paragraphs 19963@cindex Filling paragraphs 19964@cindex Paragraphs, filling 19965@findex refill 19966 19967The @code{@@refill} command refills and, optionally, indents the first 19968line of a paragraph.@footnote{Perhaps the command should have been 19969called the @code{@@refillandindent} command, but @code{@@refill} is 19970shorter and the name was chosen before indenting was possible.} The 19971@code{@@refill} command is no longer important, but we describe it here 19972because you once needed it. You will see it in many old Texinfo 19973files.@refill 19974 19975Without refilling, paragraphs containing long @@-constructs may look 19976bad after formatting because the formatter removes @@-commands and 19977shortens some lines more than others. In the past, neither the 19978@code{texinfo-format-region} command nor the 19979@code{texinfo-format-buffer} command refilled paragraphs 19980automatically. The @code{@@refill} command had to be written at the 19981end of every paragraph to cause these formatters to fill them. (Both 19982@TeX{} and @code{makeinfo} have always refilled paragraphs 19983automatically.) Now, all the Info formatters automatically fill and 19984indent those paragraphs that need to be filled and indented.@refill 19985 19986The @code{@@refill} command causes @code{texinfo-format-region} and 19987@code{texinfo-format-buffer} to refill a paragraph in the Info file 19988@emph{after} all the other processing has been done. For this reason, 19989you can not use @code{@@refill} with a paragraph containing either 19990@code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will 19991override those two commands.@refill 19992 19993The @code{texinfo-format-region} and @code{texinfo-format-buffer} 19994commands now automatically append @code{@@refill} to the end of each 19995paragraph that should be filled. They do not append @code{@@refill} to 19996the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}} 19997and therefore do not refill or indent them.@refill 19998 19999@end ignore 20000 20001 20002@c These are no longer ``new'', and the explanations 20003@c are all given elsewhere anyway, I think. --karl, 25apr97. 20004@c So ignore the entire appendix. 20005@ignore 20006@c node New Features, Command and Variable Index, Obtaining TeX, Top 20007@c appendix Second Edition Features 20008 20009@tex 20010% Widen the space for the first column so three control-character 20011% strings fit in the first column. Switched back to default .8in 20012% value at end of chapter. 20013\global\tableindent=1.0in 20014@end tex 20015 20016The second edition of the Texinfo manual describes more than 20 new 20017Texinfo mode commands and more than 50 previously undocumented Texinfo 20018@@-commands. This edition is more than twice the length of the first 20019edition.@refill 20020 20021Here is a brief description of the new commands.@refill 20022 20023@c menu 20024* New Texinfo Mode Commands:: The updating commands are especially useful. 20025* New Commands:: Many newly described @@-commands. 20026@c end menu 20027 20028@c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX 20029@c appendixsec New Texinfo Mode Commands 20030 20031Texinfo mode provides commands and features especially designed for 20032working with Texinfo files. More than 20 new commands have been 20033added, including commands for automatically creating and updating 20034both nodes and menus. This is a tedious task when done by hand.@refill 20035 20036The keybindings are intended to be somewhat mnemonic.@refill 20037 20038@c subheading Update all nodes and menus 20039 20040The @code{texinfo-master-menu} command is the primary command: 20041 20042@table @kbd 20043@item C-c C-u m 20044@itemx M-x texinfo-master-menu 20045Create or update a master menu. 20046With @kbd{C-u} as a prefix argument, 20047first create or update all nodes 20048and regular menus. 20049@end table 20050 20051@c subheading Update Pointers 20052 20053@noindent 20054Create or update `Next', `Previous', and `Up' node pointers.@refill 20055 20056@noindent 20057@xref{Updating Nodes and Menus}. 20058 20059@table @kbd 20060@item C-c C-u C-n 20061@itemx M-x texinfo-update-node 20062Update a node. 20063 20064@item C-c C-u C-e 20065@itemx M-x texinfo-every-node-update 20066Update every node in the buffer. 20067@end table 20068 20069@c subheading Update Menus 20070 20071@noindent 20072Create or update menus.@refill 20073 20074@noindent 20075@xref{Updating Nodes and Menus}. 20076 20077@table @kbd 20078@item C-c C-u C-m 20079@itemx M-x texinfo-make-menu 20080Make or update a menu. 20081 20082@item C-c C-u C-a 20083@itemx M-x texinfo-all-menus-update 20084Make or update all the menus in a buffer. 20085With @kbd{C-u} as a prefix argument, 20086first update all the nodes. 20087@end table 20088 20089@c subheading Insert Title as Description 20090 20091@noindent 20092Insert a node's chapter or section title in the space for the 20093description in a menu entry line; position point so you can edit the 20094insert. (This command works somewhat differently than the other 20095insertion commands, which insert only a predefined string.)@refill 20096 20097@noindent 20098@xref{Inserting, Inserting Frequently Used Commands}. 20099 20100@table @kbd 20101@item C-c C-c C-d 20102Insert title. 20103@end table 20104 20105@c subheading Format for Info 20106 20107@noindent 20108Provide keybindings both for the Info formatting commands that are 20109written in Emacs Lisp and for @code{makeinfo} that is written in 20110C.@refill 20111 20112@noindent 20113@xref{Info Formatting}. 20114 20115@noindent 20116Use the Emacs lisp @code{texinfo-format@dots{}} commands: 20117 20118@table @kbd 20119@item C-c C-e C-r 20120Format the region. 20121 20122@item C-c C-e C-b 20123Format the buffer. 20124@end table 20125 20126@noindent 20127Use @code{makeinfo}: 20128 20129@table @kbd 20130@item C-c C-m C-r 20131Format the region. 20132 20133@item C-c C-m C-b 20134Format the buffer. 20135 20136@item C-c C-m C-l 20137Recenter the @code{makeinfo} output buffer. 20138 20139@item C-c C-m C-k 20140Kill the @code{makeinfo} formatting job. 20141@end table 20142 20143@c subheading Typeset and Print 20144 20145@noindent 20146Typeset and print Texinfo documents from within Emacs. 20147 20148@noindent 20149@xref{Printing}. 20150 20151@table @kbd 20152@item C-c C-t C-b 20153Run @code{texi2dvi} on the buffer. 20154 20155@item C-c C-t C-r 20156Run @TeX{} on the region. 20157 20158@item C-c C-t C-i 20159Run @code{texindex}. 20160 20161@item C-c C-t C-p 20162Print the DVI file. 20163 20164@item C-c C-t C-q 20165Show the print queue. 20166 20167@item C-c C-t C-d 20168Delete a job from the print queue. 20169 20170@item C-c C-t C-k 20171Kill the current @TeX{} formatting job. 20172 20173@item C-c C-t C-x 20174Quit a currently stopped @TeX{} formatting job. 20175 20176@item C-c C-t C-l 20177Recenter the output buffer. 20178@end table 20179 20180@c subheading Other Updating Commands 20181 20182@noindent 20183The ``other updating commands'' do not have standard keybindings because 20184they are used less frequently.@refill 20185 20186@noindent 20187@xref{Other Updating Commands}. 20188 20189@table @kbd 20190@item M-x texinfo-insert-node-lines 20191Insert missing @code{@@node} lines using 20192section titles as node names. 20193 20194@item M-x texinfo-multiple-files-update 20195Update a multi-file document. 20196With a numeric prefix, such as @kbd{C-u 8}, 20197update @strong{every} pointer and 20198menu in @strong{all} the files and 20199then insert a master menu. 20200 20201@item M-x texinfo-indent-menu-description 20202Indent descriptions in menus. 20203 20204@item M-x texinfo-sequential-node-update 20205Insert node pointers in strict sequence. 20206@end table 20207 20208@c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX 20209@c appendix.sec New Texinfo @@-Commands 20210 20211The second edition of the Texinfo manual describes more than 50 20212commands that were not described in the first edition. A third or so 20213of these commands existed in Texinfo but were not documented in the 20214manual; the others are new. Here is a listing, with brief 20215descriptions of them:@refill 20216 20217@c subheading Indexing 20218 20219@noindent 20220Create your own index, and merge indices.@refill 20221 20222@noindent 20223@xref{Indices}. 20224 20225@table @kbd 20226@item @@defindex @var{index-name} 20227Define a new index and its indexing command. 20228See also the @code{@@defcodeindex} command. 20229 20230@c written verbosely to avoid overfull hbox 20231@item @@synindex @var{from-index} @var{into-index} 20232Merge the @var{from-index} index into the @var{into-index} index. 20233See also the @code{@@syncodeindex} command. 20234@end table 20235 20236@c subheading Definitions 20237 20238@noindent 20239Describe functions, variables, macros, 20240commands, user options, special forms, and other such artifacts in a 20241uniform format.@refill 20242 20243@noindent 20244@xref{Definition Commands}. 20245 20246@table @kbd 20247@item @@deffn @var{category} @var{name} @var{arguments}@dots{} 20248Format a description for functions, interactive 20249commands, and similar entities. 20250 20251@item @@defvr, @@defop, @dots{} 2025215 other related commands. 20253@end table 20254 20255@c subheading Glyphs 20256 20257@noindent 20258Indicate the results of evaluation, expansion, 20259printed output, an error message, equivalence of expressions, and the 20260location of point.@refill 20261 20262@noindent 20263@xref{Glyphs}. 20264 20265@table @kbd 20266@item @@equiv@{@} 20267@itemx @equiv{} 20268Equivalence: 20269 20270@item @@error@{@} 20271@itemx @error{} 20272Error message 20273 20274@item @@expansion@{@} 20275@itemx @expansion{} 20276Macro expansion 20277 20278@item @@point@{@} 20279@itemx @point{} 20280Position of point 20281 20282@item @@print@{@} 20283@itemx @print{} 20284Printed output 20285 20286@item @@result@{@} 20287@itemx @result{} 20288Result of an expression 20289@end table 20290 20291@c subheading Page Headings 20292 20293@noindent 20294Customize page headings. 20295 20296@noindent 20297@xref{Headings}. 20298 20299@table @kbd 20300@item @@headings @var{on-off-single-double} 20301Headings on or off, single, or double-sided. 20302 20303@item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}] 20304Footings for even-numbered (left-hand) pages. 20305 20306@item @@evenheading, @@everyheading, @@oddheading, @dots{} 20307Five other related commands. 20308 20309@item @@thischapter 20310Insert name of chapter and chapter number. 20311 20312@item @@thischaptername, @@thisfile, @@thistitle, @@thispage 20313Related commands. 20314@end table 20315 20316@c subheading Formatting 20317 20318@noindent 20319Format blocks of text. 20320 20321@noindent 20322@xref{Quotations and Examples}, and@* 20323@ref{Lists and Tables, , Making Lists and Tables}. 20324 20325@table @kbd 20326@item @@cartouche 20327Draw rounded box surrounding text (no effect in Info). 20328 20329@item @@enumerate @var{optional-arg} 20330Enumerate a list with letters or numbers. 20331 20332@item @@exdent @var{line-of-text} 20333Remove indentation. 20334 20335@item @@flushleft 20336Left justify. 20337 20338@item @@flushright 20339Right justify. 20340 20341@item @@format 20342Do not narrow nor change font. 20343 20344@item @@ftable @var{formatting-command} 20345@itemx @@vtable @var{formatting-command} 20346Two-column table with indexing. 20347 20348@item @@lisp 20349For an example of Lisp code. 20350 20351@item @@smallexample 20352@itemx @@smalllisp 20353Like @@table and @@lisp, but for (originally) @@smallbook. 20354@end table 20355 20356@c subheading Conditionals 20357 20358@noindent 20359Conditionally format text. 20360 20361@noindent 20362@xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill 20363 20364@table @kbd 20365@item @@set @var{flag} [@var{string}] 20366Set a flag. Optionally, set value 20367of @var{flag} to @var{string}. 20368 20369@item @@clear @var{flag} 20370Clear a flag. 20371 20372@item @@value@{@var{flag}@} 20373Replace with value to which @var{flag} is set. 20374 20375@item @@ifset @var{flag} 20376Format, if @var{flag} is set. 20377 20378@item @@ifclear @var{flag} 20379Ignore, if @var{flag} is set. 20380@end table 20381 20382@c subheading @@heading series for Titles 20383 20384@noindent 20385Produce unnumbered headings that do not appear in a table of contents. 20386 20387@noindent 20388@xref{Structuring}. 20389 20390@table @kbd 20391@item @@heading @var{title} 20392Unnumbered section-like heading not listed 20393in the table of contents of a printed manual. 20394 20395@item @@chapheading, @@majorheading, @@c subheading, @@subsubheading 20396Related commands. 20397@end table 20398 20399@need 1000 20400@c subheading Font commands 20401 20402@need 1000 20403@noindent 20404@xref{Smallcaps}, and @* 20405@ref{Fonts}. 20406 20407@table @kbd 20408@item @@r@{@var{text}@} 20409Print in roman font. 20410 20411@item @@sc@{@var{text}@} 20412Print in @sc{small caps} font. 20413@end table 20414 20415@c subheading Miscellaneous 20416 20417@noindent 20418See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@* 20419see @ref{Customized Highlighting},@* 20420see @ref{Overfull hboxes},@* 20421see @ref{Footnotes},@* 20422see @ref{dmn, , Format a Dimension},@* 20423see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@* 20424see @ref{math, , @code{@@math}: Inserting Mathematical Expressions}.@* 20425see @ref{minus, , Inserting a Minus Sign},@* 20426see @ref{paragraphindent, , Paragraph Indenting},@* 20427see @ref{Cross Reference Commands},@* 20428see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@* 20429see @ref{Custom Headings, , How to Make Your Own Headings}. 20430 20431@table @kbd 20432@item @@author @var{author} 20433Typeset author's name. 20434 20435@c @item @@definfoenclose @var{new-command}, @var{before}, @var{after}, 20436@c Define a highlighting command for Info. (Info only.) 20437 20438@item @@finalout 20439Produce cleaner printed output. 20440 20441@item @@footnotestyle @var{end-or-separate} 20442Specify footnote style. 20443 20444@item @@dmn@{@var{dimension}@} 20445Format a dimension. 20446 20447@item @@global@@let@var{new-cmd}=@var{existing-cmd} 20448Define a highlighting command for @TeX{}. (@TeX{} only.) 20449 20450@item @@lowersections 20451Reduce hierarchical level of sectioning commands. 20452 20453@item @@math@{@var{mathematical-expression}@} 20454Format a mathematical expression. 20455 20456@item @@minus@{@} 20457Generate a minus sign. 20458 20459@item @@paragraphindent @var{asis-or-number} 20460Specify paragraph indentation. 20461 20462@item @@raisesections 20463Raise hierarchical level of sectioning commands. 20464 20465@item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@} 20466Make a reference. In the printed manual, the 20467reference does not start with the word `see'. 20468 20469@item @@title @var{title} 20470Typeset @var{title} in the alternative 20471title page format. 20472 20473@item @@subtitle @var{subtitle} 20474Typeset @var{subtitle} in the alternative 20475title page format. 20476 20477@item @@today@{@} 20478Insert the current date. 20479@end table 20480@tex 20481% Switch width of first column of tables back to default value 20482\global\tableindent=.8in 20483@end tex 20484@end ignore 20485 20486 20487@node Copying This Manual 20488@appendix Copying This Manual 20489 20490@menu 20491* GNU Free Documentation License:: License for copying this manual. 20492@end menu 20493 20494@include fdl.texi 20495 20496 20497@node Command and Variable Index 20498@unnumbered Command and Variable Index 20499 20500This is an alphabetical list of all the @@-commands, assorted Emacs Lisp 20501functions, and several variables. To make the list easier to use, the 20502commands are listed without their preceding @samp{@@}.@refill 20503 20504@printindex fn 20505 20506 20507@node Concept Index 20508@unnumbered Concept Index 20509 20510@printindex cp 20511 20512 20513@bye 20514