texinfo.texi(,2) @c Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
texinfo.texi(,3) @c Ordinarily Texinfo files have the extension .texi.  But texinfo.texi
texinfo.texi(,4) @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
texinfo.texi(,5) 
texinfo.texi(,6) @c Everything between the start/end of header lines will be passed by
texinfo.texi(,7) @c Emacs's {texinfo,makeinfo}-format region commands.  See the `start of
texinfo.texi(,8) @c header' node for more info.
texinfo.texi(,9) @c %**start of header
texinfo.texi(,10) 
texinfo.texi(,11) @c makeinfo and texinfo.tex ignore all text before @setfilename.
texinfo.texi(,12) @c
texinfo.texi(,13) @c Ordinarily the setfilename argument ends with .info.  But
texinfo.texi(,14) @c texinfo.info-13 is too long for 14-character filesystems.
texinfo.texi(,15) @setfilename texinfo
texinfo.texi(,16) 
texinfo.texi(,17) @c Automake automatically updates version.texi to @set VERSION and
texinfo.texi(,18) @c @set UPDATED to appropriate values.
version.texi(,1) @set UPDATED 28 March 2002
version.texi(,2) @set UPDATED-MONTH March 2002
version.texi(,3) @set EDITION 4.2
version.texi(,4) @set VERSION 4.2
texinfo.texi(,20) @settitle GNU Texinfo 4.2
texinfo.texi(,21) 
texinfo.texi(,22) @c Define a new index for options.
texinfo.texi(,23) @defcodeindex op
texinfo.texi(,24) @c Put everything except function (command, in this case) names in one
texinfo.texi(,25) @c index (arbitrarily chosen to be the concept index).
texinfo.texi(,26) @syncodeindex op cp
texinfo.texi(,27) @syncodeindex vr cp
texinfo.texi(,28) @syncodeindex pg cp
texinfo.texi(,29) 
texinfo.texi(,30) @footnotestyle separate
texinfo.texi(,31) @paragraphindent 2
texinfo.texi(,32) @c finalout
texinfo.texi(,33) 
texinfo.texi(,34) @comment %**end of header
texinfo.texi(,35) 
texinfo.texi(,36) @copying
texinfo.texi(,37) This manual is for GNU Texinfo (version 4.2, 28 March 2002),
texinfo.texi(,38) a documentation system that can produce both online information and a
texinfo.texi(,39) printed manual from a single source.
texinfo.texi(,40) 
texinfo.texi(,41) Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99, 2000, 01, 02
texinfo.texi(,42) Free Software Foundation, Inc.
texinfo.texi(,43) 
texinfo.texi(,44) @quotation
texinfo.texi(,45) Permission is granted to copy, distribute and/or modify this document
texinfo.texi(,46) under the terms of the GNU Free Documentation License, Version 1.1 or
texinfo.texi(,47) any later version published by the Free Software Foundation; with no
texinfo.texi(,48) Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
texinfo.texi(,49) and with the Back-Cover Texts as in (a) below.  A copy of the license is
texinfo.texi(,50) included in the section entitled ``GNU Free Documentation License.''
texinfo.texi(,51) 
texinfo.texi(,52) (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
texinfo.texi(,53) this GNU Manual, like GNU software.  Copies published by the Free
texinfo.texi(,54) Software Foundation raise funds for GNU development.''
texinfo.texi(,55) @end quotation
texinfo.texi(,56) @end copying
texinfo.texi(,57) 
texinfo.texi(,58) @dircategory Texinfo documentation system
texinfo.texi(,66) 
texinfo.texi(,67) @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
texinfo.texi(,68) @c prefix arg).  This updates the node pointers, which texinfmt.el needs.
texinfo.texi(,69) 
texinfo.texi(,70) @c Set smallbook if printing in smallbook format so the example of the
texinfo.texi(,71) @c smallbook font is actually written using smallbook; in bigbook, a kludge
texinfo.texi(,72) @c is used for TeX output.  Do this through the -t option to texi2dvi,
texinfo.texi(,73) @c so this same source can be used for other paper sizes as well.
texinfo.texi(,74) @c smallbook
texinfo.texi(,75) @c set smallbook
texinfo.texi(,76) @c @@clear smallbook
texinfo.texi(,77) 
texinfo.texi(,78) @c If you like blank pages, add through texi2dvi -t.
texinfo.texi(,79) @c setchapternewpage odd
texinfo.texi(,80) 
texinfo.texi(,81) @c Currently undocumented command, 5 December 1993:
texinfo.texi(,82) @c nwnode          (Same as node, but no warnings; for `makeinfo'.)
texinfo.texi(,83) 
texinfo.texi(,84) 
texinfo.texi(,85) @shorttitlepage Texinfo
texinfo.texi(,86) 
texinfo.texi(,87) @titlepage
texinfo.texi(,88) @title Texinfo
texinfo.texi(,89) @subtitle The GNU Documentation Format
texinfo.texi(,90) @subtitle for Texinfo version 4.2, 28 March 2002
texinfo.texi(,91) 
texinfo.texi(,92) @author Robert J. Chassell
texinfo.texi(,93) @author Richard M. Stallman
texinfo.texi(,94) 
texinfo.texi(,95) @c Include the Distribution inside the titlepage so
texinfo.texi(,96) @c that headings are turned off.
texinfo.texi(,97) 
texinfo.texi(,98) @page
texinfo.texi(,99) @vskip 0pt plus 1filll
texinfo.texi(,100) @insertcopying
texinfo.texi(,101) 
texinfo.texi(,102) Published by the Free Software Foundation @*
texinfo.texi(,103) 59 Temple Place Suite 330 @*
texinfo.texi(,104) Boston, MA 02111-1307 @*
texinfo.texi(,105) USA @*
texinfo.texi(,106) ISBN 1-882114-67-1 @c for version 4.0, September 1999.
texinfo.texi(,107) @c ISBN 1-882114-65-5 is for version 3.12, March 1998.
texinfo.texi(,108) @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
texinfo.texi(,109) @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995
texinfo.texi(,110) 
texinfo.texi(,111) Cover art by Etienne Suvasa.
texinfo.texi(,112) @end titlepage
texinfo.texi(,113) 
texinfo.texi(,114) 
texinfo.texi(,115) @summarycontents
texinfo.texi(,116) @contents
texinfo.texi(,117) 
texinfo.texi(,118) 
texinfo.texi(,120) @node Top
texinfo.texi(,121) @top Texinfo
texinfo.texi(,122) 
texinfo.texi(,123) @insertcopying
texinfo.texi(,124) 
texinfo.texi(,125) The first part of this master menu lists the major nodes in this Info
texinfo.texi(,126) document, including the @@-command and concept indices.  The rest of
texinfo.texi(,127) the menu lists all the lower level nodes in the document.
texinfo.texi(,128) 
texinfo.texi(,130) 
texinfo.texi(,131) @menu
texinfo.texi(,132) * Copying Conditions::          Your rights.
texinfo.texi(,133) * Overview::                    Texinfo in brief.
texinfo.texi(,134) * Texinfo Mode::                How to use Texinfo mode.
texinfo.texi(,135) * Beginning a File::            What is at the beginning of a Texinfo file?
texinfo.texi(,136) * Ending a File::               What is at the end of a Texinfo file?
texinfo.texi(,137) * Structuring::                 How to create chapters, sections, subsections,
texinfo.texi(,138)                                   appendices, and other parts.
texinfo.texi(,139) * Nodes::                       How to write nodes.
texinfo.texi(,140) * Menus::                       How to write menus.
texinfo.texi(,141) * Cross References::            How to write cross references.
texinfo.texi(,142) * Marking Text::                How to mark words and phrases as code,
texinfo.texi(,143)                                   keyboard input, meta-syntactic
texinfo.texi(,144)                                   variables, and the like.
texinfo.texi(,145) * Quotations and Examples::     How to write quotations, examples, etc.
texinfo.texi(,146) * Lists and Tables::            How to write lists and tables.
texinfo.texi(,147) * Indices::                     How to create indices.
texinfo.texi(,148) * Insertions::                  How to insert @@-signs, braces, etc.
texinfo.texi(,149) * Breaks::                      How to force and prevent line and page breaks.
texinfo.texi(,150) * Definition Commands::         How to describe functions and the like
texinfo.texi(,151)                                   in a uniform manner.
texinfo.texi(,152) * Conditionals::                How to specify text for either @TeX{} or Info.
texinfo.texi(,153) * Internationalization::        
texinfo.texi(,154) * Defining New Texinfo Commands::  
texinfo.texi(,155) * Hardcopy::                    How to convert a Texinfo file to a file
texinfo.texi(,156)                                   for printing and how to print that file.
texinfo.texi(,157) * Creating and Installing Info Files::  
texinfo.texi(,158) * Command List::                All the Texinfo @@-commands.
texinfo.texi(,159) * Tips::                        Hints on how to write a Texinfo document.
texinfo.texi(,160) * Sample Texinfo Files::        Complete examples, including full texts.
texinfo.texi(,161) * Include Files::               How to incorporate other Texinfo files.
texinfo.texi(,162) * Headings::                    How to write page headings and footings.
texinfo.texi(,163) * Catching Mistakes::           How to find formatting mistakes.
texinfo.texi(,164) * Refilling Paragraphs::        All about paragraph refilling.
texinfo.texi(,165) * Command Syntax::              A description of @@-Command syntax.
texinfo.texi(,166) * Obtaining TeX::               How to Obtain @TeX{}.
texinfo.texi(,167) * Copying This Manual::         The GNU Free Documentation License.
texinfo.texi(,168) * Command and Variable Index::  A menu containing commands and variables.
texinfo.texi(,169) * Concept Index::               A menu covering many topics.
texinfo.texi(,170) 
texinfo.texi(,171) @detailmenu
texinfo.texi(,172)  --- The Detailed Node Listing ---
texinfo.texi(,173) 
texinfo.texi(,174) Overview of Texinfo
texinfo.texi(,175) 
texinfo.texi(,176) * Reporting Bugs::              Submitting effective bug reports.
texinfo.texi(,177) * Using Texinfo::               Create printed or online output.
texinfo.texi(,178) * Info Files::                  What is an Info file?
texinfo.texi(,179) * Printed Books::               Characteristics of a printed book or manual.
texinfo.texi(,180) * Formatting Commands::         @@-commands are used for formatting.
texinfo.texi(,181) * Conventions::                 General rules for writing a Texinfo file.
texinfo.texi(,182) * Comments::                    Writing comments and ignored text in general.
texinfo.texi(,183) * Minimum::                     What a Texinfo file must have.
texinfo.texi(,184) * Six Parts::                   Usually, a Texinfo file has six parts.
texinfo.texi(,185) * Short Sample::                A short sample Texinfo file.
texinfo.texi(,186) * History::                     Acknowledgements, contributors and genesis.
texinfo.texi(,187) 
texinfo.texi(,188) Using Texinfo Mode
texinfo.texi(,189) 
texinfo.texi(,190) * Texinfo Mode Overview::       How Texinfo mode can help you.
texinfo.texi(,191) * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
texinfo.texi(,192)                                   purpose editing features.
texinfo.texi(,193) * Inserting::                   How to insert frequently used @@-commands.
texinfo.texi(,194) * Showing the Structure::       How to show the structure of a file.
texinfo.texi(,195) * Updating Nodes and Menus::    How to update or create new nodes and menus.
texinfo.texi(,196) * Info Formatting::             How to format for Info.
texinfo.texi(,197) * Printing::                    How to format and print part or all of a file.
texinfo.texi(,198) * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
texinfo.texi(,199) 
texinfo.texi(,200) Updating Nodes and Menus
texinfo.texi(,201) 
texinfo.texi(,202) * Updating Commands::           Five major updating commands.
texinfo.texi(,203) * Updating Requirements::       How to structure a Texinfo file for
texinfo.texi(,204)                                   using the updating command.
texinfo.texi(,205) * Other Updating Commands::     How to indent descriptions, insert
texinfo.texi(,206)                                   missing nodes lines, and update
texinfo.texi(,207)                                   nodes in sequence.
texinfo.texi(,208) 
texinfo.texi(,209) Beginning a Texinfo File
texinfo.texi(,210) 
texinfo.texi(,211) * Sample Beginning::            A sample beginning for a Texinfo file.
texinfo.texi(,212) * Texinfo File Header::         
texinfo.texi(,213) * Document Permissions::        
texinfo.texi(,214) * Titlepage & Copyright Page::  Creating the title and copyright pages.
texinfo.texi(,215) * The Top Node::                Creating the `Top' node and master menu.
texinfo.texi(,216) * Global Document Commands::    
texinfo.texi(,217) * Software Copying Permissions::  Ensure that you and others continue to
texinfo.texi(,218)                                     have the right to use and share software.
texinfo.texi(,219) 
texinfo.texi(,220) Texinfo File Header
texinfo.texi(,221) 
texinfo.texi(,222) * First Line::                  The first line of a Texinfo file.
texinfo.texi(,223) * Start of Header::             Formatting a region requires this.
texinfo.texi(,224) * setfilename::                 Tell Info the name of the Info file.
texinfo.texi(,225) * settitle::                    Create a title for the printed work.
texinfo.texi(,226) * End of Header::               Formatting a region requires this.
texinfo.texi(,227) 
texinfo.texi(,228) Document Permissions
texinfo.texi(,229) 
texinfo.texi(,230) * copying::                     Declare the document's copying permissions.
texinfo.texi(,231) * insertcopying::               Where to insert the permissions.
texinfo.texi(,232) 
texinfo.texi(,233) Title and Copyright Pages
texinfo.texi(,234) 
texinfo.texi(,235) * titlepage::                   Create a title for the printed document.
texinfo.texi(,236) * titlefont center sp::         The @code{@@titlefont}, @code{@@center},
texinfo.texi(,237)                                   and @code{@@sp} commands.
texinfo.texi(,238) * title subtitle author::       The @code{@@title}, @code{@@subtitle},
texinfo.texi(,239)                                   and @code{@@author} commands.
texinfo.texi(,240) * Copyright::                   How to write the copyright notice and
texinfo.texi(,241)                                   include copying permissions.
texinfo.texi(,242) * end titlepage::               Turn on page headings after the title and
texinfo.texi(,243)                                   copyright pages.
texinfo.texi(,244) * headings on off::             An option for turning headings on and off
texinfo.texi(,245)                                   and double or single sided printing.
texinfo.texi(,246) 
texinfo.texi(,247) The `Top' Node and Master Menu
texinfo.texi(,248) 
texinfo.texi(,249) * Top Node Example::            
texinfo.texi(,250) * Master Menu Parts::           
texinfo.texi(,251) 
texinfo.texi(,252) Global Document Commands
texinfo.texi(,253) 
texinfo.texi(,254) * documentdescription::         Document summary for the HTML output.
texinfo.texi(,255) * setchapternewpage::           Start chapters on right-hand pages.
texinfo.texi(,256) * paragraphindent::             Specify paragraph indentation.
texinfo.texi(,257) * exampleindent::               Specify environment indentation.
texinfo.texi(,258) 
texinfo.texi(,259) Ending a Texinfo File
texinfo.texi(,260) 
texinfo.texi(,261) * Printing Indices & Menus::    How to print an index in hardcopy and
texinfo.texi(,262)                                   generate index menus in Info.
texinfo.texi(,263) * Contents::                    How to create a table of contents.
texinfo.texi(,264) * File End::                    How to mark the end of a file.
texinfo.texi(,265) 
texinfo.texi(,266) Chapter Structuring
texinfo.texi(,267) 
texinfo.texi(,268) * Tree Structuring::            A manual is like an upside down tree @dots{}
texinfo.texi(,269) * Structuring Command Types::   How to divide a manual into parts.
texinfo.texi(,270) * makeinfo top::                The @code{@@top} command, part of the `Top' node.
texinfo.texi(,271) * chapter::                     
texinfo.texi(,272) * unnumbered & appendix::       
texinfo.texi(,273) * majorheading & chapheading::  
texinfo.texi(,274) * section::                     
texinfo.texi(,275) * unnumberedsec appendixsec heading::  
texinfo.texi(,276) * subsection::                  
texinfo.texi(,277) * unnumberedsubsec appendixsubsec subheading::  
texinfo.texi(,278) * subsubsection::               Commands for the lowest level sections.
texinfo.texi(,279) * Raise/lower sections::        How to change commands' hierarchical level.
texinfo.texi(,280) 
texinfo.texi(,281) Nodes
texinfo.texi(,282) 
texinfo.texi(,283) * Two Paths::                   Different commands to structure
texinfo.texi(,284)                                   Info output and printed output.
texinfo.texi(,285) * Node Menu Illustration::      A diagram, and sample nodes and menus.
texinfo.texi(,286) * node::                        Creating nodes, in detail.
texinfo.texi(,287) * makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
texinfo.texi(,288) * anchor::                      Defining arbitrary cross-reference targets.
texinfo.texi(,289) 
texinfo.texi(,290) The @code{@@node} Command
texinfo.texi(,291) 
texinfo.texi(,292) * Node Names::                  How to choose node and pointer names.
texinfo.texi(,293) * Writing a Node::              How to write an @code{@@node} line.
texinfo.texi(,294) * Node Line Tips::              Keep names short.
texinfo.texi(,295) * Node Line Requirements::      Keep names unique, without @@-commands.
texinfo.texi(,296) * First Node::                  How to write a `Top' node.
texinfo.texi(,297) * makeinfo top command::        How to use the @code{@@top} command.
texinfo.texi(,298) 
texinfo.texi(,299) Menus
texinfo.texi(,300) 
texinfo.texi(,301) * Menu Location::               Put a menu in a short node.
texinfo.texi(,302) * Writing a Menu::              What is a menu?
texinfo.texi(,303) * Menu Parts::                  A menu entry has three parts.
texinfo.texi(,304) * Less Cluttered Menu Entry::   Two part menu entry.
texinfo.texi(,305) * Menu Example::                Two and three part menu entries.
texinfo.texi(,306) * Other Info Files::            How to refer to a different Info file.
texinfo.texi(,307) 
texinfo.texi(,308) Cross References
texinfo.texi(,309) 
texinfo.texi(,310) * References::                  What cross references are for.
texinfo.texi(,311) * Cross Reference Commands::    A summary of the different commands.
texinfo.texi(,312) * Cross Reference Parts::       A cross reference has several parts.
texinfo.texi(,313) * xref::                        Begin a reference with `See' @dots{}
texinfo.texi(,314) * Top Node Naming::             How to refer to the beginning of another file.
texinfo.texi(,315) * ref::                         A reference for the last part of a sentence.
texinfo.texi(,316) * pxref::                       How to write a parenthetical cross reference.
texinfo.texi(,317) * inforef::                     How to refer to an Info-only file.
texinfo.texi(,318) * uref::                        How to refer to a uniform resource locator.
texinfo.texi(,319) 
texinfo.texi(,320) @code{@@xref}
texinfo.texi(,321) 
texinfo.texi(,322) * Reference Syntax::            What a reference looks like and requires.
texinfo.texi(,323) * One Argument::                @code{@@xref} with one argument.
texinfo.texi(,324) * Two Arguments::               @code{@@xref} with two arguments.
texinfo.texi(,325) * Three Arguments::             @code{@@xref} with three arguments.
texinfo.texi(,326) * Four and Five Arguments::     @code{@@xref} with four and five arguments.
texinfo.texi(,327) 
texinfo.texi(,328) Marking Words and Phrases
texinfo.texi(,329) 
texinfo.texi(,330) * Indicating::                  How to indicate definitions, files, etc.
texinfo.texi(,331) * Emphasis::                    How to emphasize text.
texinfo.texi(,332) 
texinfo.texi(,333) Indicating Definitions, Commands, etc.
texinfo.texi(,334) 
texinfo.texi(,335) * Useful Highlighting::         Highlighting provides useful information.
texinfo.texi(,336) * code::                        Indicating program code.
texinfo.texi(,337) * kbd::                         Showing keyboard input.
texinfo.texi(,338) * key::                         Specifying keys.
texinfo.texi(,339) * samp::                        A literal sequence of characters.
texinfo.texi(,340) * verb::                        A verbatim sequence of characters.
texinfo.texi(,341) * var::                         Indicating metasyntactic variables.
texinfo.texi(,342) * env::                         Indicating environment variables.
texinfo.texi(,343) * file::                        Indicating file names.
texinfo.texi(,344) * command::                     Indicating command names.
texinfo.texi(,345) * option::                      Indicating option names.
texinfo.texi(,346) * dfn::                         Specifying definitions.
texinfo.texi(,347) * cite::                        Referring to books not in the  Info system.
texinfo.texi(,348) * acronym::                     Indicating acronyms.
texinfo.texi(,349) * url::                         Indicating a World Wide Web reference.
texinfo.texi(,350) * email::                       Indicating an electronic mail address.
texinfo.texi(,351) 
texinfo.texi(,352) Emphasizing Text
texinfo.texi(,353) 
texinfo.texi(,354) * emph & strong::               How to emphasize text in Texinfo.
texinfo.texi(,355) * Smallcaps::                   How to use the small caps font.
texinfo.texi(,356) * Fonts::                       Various font commands for printed output.
texinfo.texi(,357) 
texinfo.texi(,358) Quotations and Examples
texinfo.texi(,359) 
texinfo.texi(,360) * Block Enclosing Commands::    Different constructs for different purposes.
texinfo.texi(,361) * quotation::                   Writing a quotation.
texinfo.texi(,362) * example::                     Writing an example in a fixed-width font.
texinfo.texi(,363) * verbatim::                    Writing a verbatim example.
texinfo.texi(,364) * verbatiminclude::             Including a file verbatim.
texinfo.texi(,365) * lisp::                        Illustrating Lisp code.
texinfo.texi(,366) * small::                       Forms for @code{@@smallbook}.
texinfo.texi(,367) * display::                     Writing an example in the current font.
texinfo.texi(,368) * format::                      Writing an example without narrowed margins.
texinfo.texi(,369) * exdent::                      Undo indentation on a line.
texinfo.texi(,370) * flushleft & flushright::      Pushing text flush left or flush right.
texinfo.texi(,371) * noindent::                    Preventing paragraph indentation.
texinfo.texi(,372) * cartouche::                   Drawing rounded rectangles around examples.
texinfo.texi(,373) 
texinfo.texi(,374) Lists and Tables
texinfo.texi(,375) 
texinfo.texi(,376) * Introducing Lists::           Texinfo formats lists for you.
texinfo.texi(,377) * itemize::                     How to construct a simple list.
texinfo.texi(,378) * enumerate::                   How to construct a numbered list.
texinfo.texi(,379) * Two-column Tables::           How to construct a two-column table.
texinfo.texi(,380) * Multi-column Tables::         How to construct generalized tables.
texinfo.texi(,381) 
texinfo.texi(,382) Making a Two-column Table
texinfo.texi(,383) 
texinfo.texi(,384) * table::                       How to construct a two-column table.
texinfo.texi(,385) * ftable vtable::               Automatic indexing for two-column tables.
texinfo.texi(,386) * itemx::                       How to put more entries in the first column.
texinfo.texi(,387) 
texinfo.texi(,388) Multi-column Tables
texinfo.texi(,389) 
texinfo.texi(,390) * Multitable Column Widths::    Defining multitable column widths.
texinfo.texi(,391) * Multitable Rows::             Defining multitable rows, with examples.
texinfo.texi(,392) 
texinfo.texi(,393) Indices
texinfo.texi(,394) 
texinfo.texi(,395) * Index Entries::               Choose different words for index entries.
texinfo.texi(,396) * Predefined Indices::          Use different indices for different kinds
texinfo.texi(,397)                                   of entry.
texinfo.texi(,398) * Indexing Commands::           How to make an index entry.
texinfo.texi(,399) * Combining Indices::           How to combine indices.
texinfo.texi(,400) * New Indices::                 How to define your own indices.
texinfo.texi(,401) 
texinfo.texi(,402) Combining Indices
texinfo.texi(,403) 
texinfo.texi(,404) * syncodeindex::                How to merge two indices, using @code{@@code}
texinfo.texi(,405)                                   font for the merged-from index.
texinfo.texi(,406) * synindex::                    How to merge two indices, using the
texinfo.texi(,407)                                   default font of the merged-to index.
texinfo.texi(,408) 
texinfo.texi(,409) Special Insertions
texinfo.texi(,410) 
texinfo.texi(,411) * Braces Atsigns::              How to insert braces, @samp{@@}.
texinfo.texi(,412) * Inserting Space::             How to insert the right amount of space
texinfo.texi(,413)                                   within a sentence.
texinfo.texi(,414) * Inserting Accents::           How to insert accents and special characters.
texinfo.texi(,415) * Dots Bullets::                How to insert dots and bullets.
texinfo.texi(,416) * TeX and copyright::           How to insert the @TeX{} logo
texinfo.texi(,417)                                   and the copyright symbol.
texinfo.texi(,418) * pounds::                      How to insert the pounds currency symbol.
texinfo.texi(,419) * minus::                       How to insert a minus sign.
texinfo.texi(,420) * math::                        How to format a mathematical expression.
texinfo.texi(,421) * Glyphs::                      How to indicate results of evaluation,
texinfo.texi(,422)                                   expansion of macros, errors, etc.
texinfo.texi(,423) * Footnotes::                   How to include footnotes.
texinfo.texi(,424) * Images::                      How to include graphics.
texinfo.texi(,425) 
texinfo.texi(,426) Inserting @@ and Braces
texinfo.texi(,427) 
texinfo.texi(,428) * Inserting An Atsign::         How to insert @samp{@@}.
texinfo.texi(,429) * Inserting Braces::            How to insert @samp{@{} and @samp{@}}.
texinfo.texi(,430) 
texinfo.texi(,431) Inserting Space
texinfo.texi(,432) 
texinfo.texi(,433) * Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
texinfo.texi(,434) * Ending a Sentence::           Sometimes it does.
texinfo.texi(,435) * Multiple Spaces::             Inserting multiple spaces.
texinfo.texi(,436) * dmn::                         How to format a dimension.
texinfo.texi(,437) 
texinfo.texi(,438) Inserting Ellipsis and Bullets
texinfo.texi(,439) 
texinfo.texi(,440) * dots::                        How to insert dots @dots{}
texinfo.texi(,441) * bullet::                      How to insert a bullet.
texinfo.texi(,442) 
texinfo.texi(,443) Inserting @TeX{} and the Copyright Symbol
texinfo.texi(,444) 
texinfo.texi(,445) * tex::                         How to insert the @TeX{} logo.
texinfo.texi(,446) * copyright symbol::            How to use @code{@@copyright}@{@}.
texinfo.texi(,447) 
texinfo.texi(,448) Glyphs for Examples
texinfo.texi(,449) 
texinfo.texi(,450) * Glyphs Summary::              
texinfo.texi(,451) * result::                      How to show the result of expression.
texinfo.texi(,452) * expansion::                   How to indicate an expansion.
texinfo.texi(,453) * Print Glyph::                 How to indicate printed output.
texinfo.texi(,454) * Error Glyph::                 How to indicate an error message.
texinfo.texi(,455) * Equivalence::                 How to indicate equivalence.
texinfo.texi(,456) * Point Glyph::                 How to indicate the location of point.
texinfo.texi(,457) 
texinfo.texi(,458) Glyphs Summary
texinfo.texi(,459) 
texinfo.texi(,460) * result::
texinfo.texi(,461) * expansion::
texinfo.texi(,462) * Print Glyph::
texinfo.texi(,463) * Error Glyph::
texinfo.texi(,464) * Equivalence::
texinfo.texi(,465) * Point Glyph::
texinfo.texi(,466) 
texinfo.texi(,467) Footnotes
texinfo.texi(,468) 
texinfo.texi(,469) * Footnote Commands::           How to write a footnote in Texinfo.
texinfo.texi(,470) * Footnote Styles::             Controlling how footnotes appear in Info.
texinfo.texi(,471) 
texinfo.texi(,472) Making and Preventing Breaks
texinfo.texi(,473) 
texinfo.texi(,474) * Break Commands::              Cause and prevent splits.
texinfo.texi(,475) * Line Breaks::                 How to force a single line to use two lines.
texinfo.texi(,476) * - and hyphenation::           How to tell @TeX{} about hyphenation points.
texinfo.texi(,477) * w::                           How to prevent unwanted line breaks.
texinfo.texi(,478) * sp::                          How to insert blank lines.
texinfo.texi(,479) * page::                        How to force the start of a new page.
texinfo.texi(,480) * group::                       How to prevent unwanted page breaks.
texinfo.texi(,481) * need::                        Another way to prevent unwanted page breaks.
texinfo.texi(,482) 
texinfo.texi(,483) Definition Commands
texinfo.texi(,484) 
texinfo.texi(,485) * Def Cmd Template::            How to structure a description using a
texinfo.texi(,486)                                   definition command.
texinfo.texi(,487) * Optional Arguments::          How to handle optional and repeated arguments.
texinfo.texi(,488) * deffnx::                      How to group two or more `first' lines.
texinfo.texi(,489) * Def Cmds in Detail::          All the definition commands.
texinfo.texi(,490) * Def Cmd Conventions::         Conventions for writing definitions.
texinfo.texi(,491) * Sample Function Definition::  
texinfo.texi(,492) 
texinfo.texi(,493) The Definition Commands
texinfo.texi(,494) 
texinfo.texi(,495) * Functions Commands::          Commands for functions and similar entities.
texinfo.texi(,496) * Variables Commands::          Commands for variables and similar entities.
texinfo.texi(,497) * Typed Functions::             Commands for functions in typed languages.
texinfo.texi(,498) * Typed Variables::             Commands for variables in typed languages.
texinfo.texi(,499) * Abstract Objects::            Commands for object-oriented programming.
texinfo.texi(,500) * Data Types::                  The definition command for data types.
texinfo.texi(,501) 
texinfo.texi(,502) Conditionally Visible Text
texinfo.texi(,503) 
texinfo.texi(,504) * Conditional Commands::        Specifying text for HTML, Info, or @TeX{}.
texinfo.texi(,505) * Conditional Not Commands::    Specifying text for not HTML, Info, or @TeX{}.
texinfo.texi(,506) * Raw Formatter Commands::      Using raw @TeX{} or HTML commands.
texinfo.texi(,507) * set clear value::             Designating which text to format (for
texinfo.texi(,508)                                   all output formats); and how to set a
texinfo.texi(,509)                                   flag to a string that you can insert.
texinfo.texi(,510) 
texinfo.texi(,511) @code{@@set}, @code{@@clear}, and @code{@@value}
texinfo.texi(,512) 
texinfo.texi(,513) * set value::                   Expand a flag variable to a string.
texinfo.texi(,514) * ifset ifclear::               Format a region if a flag is set.
texinfo.texi(,515) * value Example::               An easy way to update edition information.
texinfo.texi(,516) 
texinfo.texi(,517) Internationalization
texinfo.texi(,518) 
texinfo.texi(,519) * documentlanguage::            Declaring the current language.
texinfo.texi(,520) * documentencoding::            Declaring the input encoding.
texinfo.texi(,521) 
texinfo.texi(,522) Defining New Texinfo Commands
texinfo.texi(,523) 
texinfo.texi(,524) * Defining Macros::             Defining and undefining new commands.
texinfo.texi(,525) * Invoking Macros::             Using a macro, once you've defined it.
texinfo.texi(,526) * Macro Details::               Beyond basic macro usage.
texinfo.texi(,527) * alias::                       Command aliases.
texinfo.texi(,528) * definfoenclose::              Customized highlighting.
texinfo.texi(,529) 
texinfo.texi(,530) Formatting and Printing Hardcopy
texinfo.texi(,531) 
texinfo.texi(,532) * Use TeX::                     Use @TeX{} to format for hardcopy.
texinfo.texi(,533) * Format with tex/texindex::    How to format with explicit shell commands.
texinfo.texi(,534) * Format with texi2dvi::        A simpler way to format.
texinfo.texi(,535) * Print with lpr::              How to print.
texinfo.texi(,536) * Within Emacs::                How to format and print from an Emacs shell.
texinfo.texi(,537) * Texinfo Mode Printing::       How to format and print in Texinfo mode.
texinfo.texi(,538) * Compile-Command::             How to print using Emacs's compile command.
texinfo.texi(,539) * Requirements Summary::        @TeX{} formatting requirements summary.
texinfo.texi(,540) * Preparing for TeX::           What to do before you use @TeX{}.
texinfo.texi(,541) * Overfull hboxes::             What are and what to do with overfull hboxes.
texinfo.texi(,542) * smallbook::                   How to print small format books and manuals.
texinfo.texi(,543) * A4 Paper::                    How to print on A4 or A5 paper.
texinfo.texi(,544) * pagesizes::                   How to print with customized page sizes.
texinfo.texi(,545) * Cropmarks and Magnification::  How to print marks to indicate the size
texinfo.texi(,546)                                 of pages and how to print scaled up output.
texinfo.texi(,547) * PDF Output::                  Portable Document Format output.
texinfo.texi(,548) 
texinfo.texi(,549) Creating and Installing Info Files
texinfo.texi(,550) 
texinfo.texi(,551) * Creating an Info File::       
texinfo.texi(,552) * Installing an Info File::     
texinfo.texi(,553) 
texinfo.texi(,554) Creating an Info File
texinfo.texi(,555) 
texinfo.texi(,556) * makeinfo advantages::         @code{makeinfo} provides better error checking.
texinfo.texi(,557) * Invoking makeinfo::           How to run @code{makeinfo} from a shell.
texinfo.texi(,558) * makeinfo options::            Specify fill-column and other options.
texinfo.texi(,559) * Pointer Validation::          How to check that pointers point somewhere.
texinfo.texi(,560) * makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
texinfo.texi(,561) * texinfo-format commands::     Two Info formatting commands written
texinfo.texi(,562)                                   in Emacs Lisp are an alternative
texinfo.texi(,563)                                   to @code{makeinfo}.
texinfo.texi(,564) * Batch Formatting::            How to format for Info in Emacs Batch mode.
texinfo.texi(,565) * Tag and Split Files::         How tagged and split files help Info
texinfo.texi(,566)                                   to run better.
texinfo.texi(,567) * makeinfo html::               Generating HTML output.
texinfo.texi(,568) 
texinfo.texi(,569) Installing an Info File
texinfo.texi(,570) 
texinfo.texi(,571) * Directory File::              The top level menu for all Info files.
texinfo.texi(,572) * New Info File::               Listing a new Info file.
texinfo.texi(,573) * Other Info Directories::      How to specify Info files that are
texinfo.texi(,574)                                   located in other directories.
texinfo.texi(,575) * Installing Dir Entries::      How to specify what menu entry to add
texinfo.texi(,576)                                   to the Info directory.
texinfo.texi(,577) * Invoking install-info::       @code{install-info} options.
texinfo.texi(,578) 
texinfo.texi(,579) Sample Texinfo Files
texinfo.texi(,580) 
texinfo.texi(,581) * Short Sample Texinfo File::   
texinfo.texi(,582) * GNU Sample Texts::            
texinfo.texi(,583) 
texinfo.texi(,584) Include Files
texinfo.texi(,585) 
texinfo.texi(,586) * Using Include Files::         How to use the @code{@@include} command.
texinfo.texi(,587) * texinfo-multiple-files-update::  How to create and update nodes and
texinfo.texi(,588)                                   menus when using included files.
texinfo.texi(,589) * Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
texinfo.texi(,590) * Sample Include File::         A sample outer file with included files
texinfo.texi(,591)                                   within it; and a sample included file.
texinfo.texi(,592) * Include Files Evolution::     How use of the @code{@@include} command
texinfo.texi(,593)                                   has changed over time.
texinfo.texi(,594) 
texinfo.texi(,595) Page Headings
texinfo.texi(,596) 
texinfo.texi(,597) * Headings Introduced::         Conventions for using page headings.
texinfo.texi(,598) * Heading Format::              Standard page heading formats.
texinfo.texi(,599) * Heading Choice::              How to specify the type of page heading.
texinfo.texi(,600) * Custom Headings::             How to create your own headings and footings.
texinfo.texi(,601) 
texinfo.texi(,602) Formatting Mistakes
texinfo.texi(,603) 
texinfo.texi(,604) * makeinfo Preferred::          @code{makeinfo} finds errors.
texinfo.texi(,605) * Debugging with Info::         How to catch errors with Info formatting.
texinfo.texi(,606) * Debugging with TeX::          How to catch errors with @TeX{} formatting.
texinfo.texi(,607) * Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
texinfo.texi(,608) * Using occur::                 How to list all lines containing a pattern.
texinfo.texi(,609) * Running Info-Validate::       How to find badly referenced nodes.
texinfo.texi(,610) 
texinfo.texi(,611) Finding Badly Referenced Nodes
texinfo.texi(,612) 
texinfo.texi(,613) * Using Info-validate::         How to run @code{Info-validate}.
texinfo.texi(,614) * Unsplit::                     How to create an unsplit file.
texinfo.texi(,615) * Tagifying::                   How to tagify a file.
texinfo.texi(,616) * Splitting::                   How to split a file manually.
texinfo.texi(,617) 
texinfo.texi(,618) Copying This Manual
texinfo.texi(,619) 
texinfo.texi(,620) * GNU Free Documentation License::  License for copying this manual.
texinfo.texi(,621) 
texinfo.texi(,622) @end detailmenu
texinfo.texi(,623) @end menu
texinfo.texi(,624) 
texinfo.texi(,625) @c Reward readers for getting to the end of the menu :).
texinfo.texi(,626) @c Contributed by Arnold Robbins.
texinfo.texi(,627) @quotation
texinfo.texi(,628) Documentation is like sex: when it is good, it is very, very good; and
texinfo.texi(,629) when it is bad, it is better than nothing.
texinfo.texi(,630) ---Dick Brandon
texinfo.texi(,631) @end quotation
texinfo.texi(,632) 
texinfo.texi(,633) 
texinfo.texi(,634) @node Copying Conditions
texinfo.texi(,635) @unnumbered Texinfo Copying Conditions
texinfo.texi(,636) @cindex Copying conditions
texinfo.texi(,637) @cindex Conditions for copying Texinfo
texinfo.texi(,638) 
texinfo.texi(,639) The programs currently being distributed that relate to Texinfo include
texinfo.texi(,640) @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
texinfo.texi(,641) These programs are @dfn{free}; this means that everyone is free to use
texinfo.texi(,642) them and free to redistribute them on a free basis.  The Texinfo-related
texinfo.texi(,643) programs are not in the public domain; they are copyrighted and there
texinfo.texi(,644) are restrictions on their distribution, but these restrictions are
texinfo.texi(,645) designed to permit everything that a good cooperating citizen would want
texinfo.texi(,646) to do.  What is not allowed is to try to prevent others from further
texinfo.texi(,647) sharing any version of these programs that they might get from you.
texinfo.texi(,648) 
texinfo.texi(,649) Specifically, we want to make sure that you have the right to give away
texinfo.texi(,650) copies of the programs that relate to Texinfo, that you receive source
texinfo.texi(,651) code or else can get it if you want it, that you can change these
texinfo.texi(,652) programs or use pieces of them in new free programs, and that you know
texinfo.texi(,653) you can do these things.
texinfo.texi(,654) 
texinfo.texi(,655) To make sure that everyone has such rights, we have to forbid you to
texinfo.texi(,656) deprive anyone else of these rights.  For example, if you distribute
texinfo.texi(,657) copies of the Texinfo related programs, you must give the recipients all
texinfo.texi(,658) the rights that you have.  You must make sure that they, too, receive or
texinfo.texi(,659) can get the source code.  And you must tell them their rights.
texinfo.texi(,660) 
texinfo.texi(,661) Also, for our own protection, we must make certain that everyone finds
texinfo.texi(,662) out that there is no warranty for the programs that relate to Texinfo.
texinfo.texi(,663) If these programs are modified by someone else and passed on, we want
texinfo.texi(,664) their recipients to know that what they have is not what we distributed,
texinfo.texi(,665) so that any problems introduced by others will not reflect on our
texinfo.texi(,666) reputation.
texinfo.texi(,667) 
texinfo.texi(,668) The precise conditions of the licenses for the programs currently being
texinfo.texi(,669) distributed that relate to Texinfo are found in the General Public
texinfo.texi(,670) Licenses that accompany them.  This manual specifically is covered by
texinfo.texi(,671) the GNU Free Documentation License (@pxref{GNU Free Documentation
texinfo.texi(,672) License}).
texinfo.texi(,673) 
texinfo.texi(,674) 
texinfo.texi(,675) @node Overview
texinfo.texi(,676) @chapter Overview of Texinfo
texinfo.texi(,677) @cindex Overview of Texinfo
texinfo.texi(,678) @cindex Texinfo overview
texinfo.texi(,679) 
texinfo.texi(,680) @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
texinfo.texi(,681) like ``speck'', not ``hex''.  This odd pronunciation is derived from,
texinfo.texi(,682) but is not the same as, the pronunciation of @TeX{}.  In the word
texinfo.texi(,683) @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
texinfo.texi(,684) the English letter ``ex''.  Pronounce @TeX{} as if the @samp{X} were the
texinfo.texi(,685) last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
texinfo.texi(,686) were a `k'.  Spell ``Texinfo'' with a capital ``T'' and the other
texinfo.texi(,687) letters in lower case.}  is a documentation system that uses a single
texinfo.texi(,688) source file to produce both online information and printed output.  This
texinfo.texi(,689) means that instead of writing two different documents, one for the
texinfo.texi(,690) online information and the other for a printed work, you need write only
texinfo.texi(,691) one document.  Therefore, when the work is revised, you need revise only
texinfo.texi(,692) that one document.
texinfo.texi(,693) 
texinfo.texi(,694) @menu
texinfo.texi(,695) * Reporting Bugs::              Submitting effective bug reports.
texinfo.texi(,696) * Using Texinfo::               Create printed or online output.
texinfo.texi(,697) * Info Files::                  What is an Info file?
texinfo.texi(,698) * Printed Books::               Characteristics of a printed book or manual.
texinfo.texi(,699) * Formatting Commands::         @@-commands are used for formatting.
texinfo.texi(,700) * Conventions::                 General rules for writing a Texinfo file.
texinfo.texi(,701) * Comments::                    Writing comments and ignored text in general.
texinfo.texi(,702) * Minimum::                     What a Texinfo file must have.
texinfo.texi(,703) * Six Parts::                   Usually, a Texinfo file has six parts.
texinfo.texi(,704) * Short Sample::                A short sample Texinfo file.
texinfo.texi(,705) * History::                     Acknowledgements, contributors and genesis.
texinfo.texi(,706) @end menu
texinfo.texi(,707) 
texinfo.texi(,708) 
texinfo.texi(,709) @node Reporting Bugs
texinfo.texi(,710) @section Reporting Bugs
texinfo.texi(,711) 
texinfo.texi(,712) @cindex Bugs, reporting
texinfo.texi(,713) @cindex Suggestions for Texinfo, making
texinfo.texi(,714) @cindex Reporting bugs
texinfo.texi(,715) We welcome bug reports and suggestions for any aspect of the Texinfo system,
texinfo.texi(,716) programs, documentation, installation, anything.  Please email them to
texinfo.texi(,717) @email{bug-texinfo@@gnu.org}.  You can get the latest version of Texinfo
texinfo.texi(,718) from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
texinfo.texi(,719) 
texinfo.texi(,720) @cindex Checklist for bug reports
texinfo.texi(,721) For bug reports, please include enough information for the maintainers
texinfo.texi(,722) to reproduce the problem.  Generally speaking, that means:
texinfo.texi(,723) 
texinfo.texi(,724) @itemize @bullet
texinfo.texi(,725) @item the version number of Texinfo and the program(s) or manual(s) involved.
texinfo.texi(,726) @item hardware and operating system names and versions.
texinfo.texi(,727) @item the contents of any input files necessary to reproduce the bug.
texinfo.texi(,728) @item a description of the problem and samples of any erroneous output.
texinfo.texi(,729) @item any unusual options you gave to @command{configure}.
texinfo.texi(,730) @item anything else that you think would be helpful.
texinfo.texi(,731) @end itemize
texinfo.texi(,732) 
texinfo.texi(,733) When in doubt whether something is needed or not, include it.  It's
texinfo.texi(,734) better to include too much than to leave out something important.
texinfo.texi(,735) 
texinfo.texi(,736) @cindex Patches, contributing
texinfo.texi(,737) Patches are most welcome; if possible, please make them with
texinfo.texi(,738) @samp{@w{diff -c}} (@pxref{Top,, Overview, diffutils, Comparing and
texinfo.texi(,739) Merging Files}) and include @file{ChangeLog} entries (@pxref{Change
texinfo.texi(,740) Log,,, emacs, The GNU Emacs Manual}).
texinfo.texi(,741) 
texinfo.texi(,742) When sending patches, if possible please do not encode or split them in
texinfo.texi(,743) any way; it's much easier to deal with one plain text message, however
texinfo.texi(,744) large, than many small ones.  @uref{ftp://ftp.gnu.org/gnu/sharutils/,
texinfo.texi(,745) GNU shar} is a convenient way of packaging multiple and/or binary files
texinfo.texi(,746) for email.
texinfo.texi(,747) 
texinfo.texi(,748) 
texinfo.texi(,749) @node Using Texinfo
texinfo.texi(,750) @section Using Texinfo
texinfo.texi(,751) 
texinfo.texi(,752) @cindex Using Texinfo in general
texinfo.texi(,753) @cindex Texinfo, introduction to
texinfo.texi(,754) @cindex Introduction to Texinfo
texinfo.texi(,755) 
texinfo.texi(,756) Using Texinfo, you can create a printed document with the normal
texinfo.texi(,757) features of a book, including chapters, sections, cross references, and
texinfo.texi(,758) indices.  From the same Texinfo source file, you can create a
texinfo.texi(,759) menu-driven, online Info file with nodes, menus, cross references, and
texinfo.texi(,760) indices.  You can also create from that same source file an HTML output
texinfo.texi(,761) file suitable for use with a web browser, or an XML file.  @cite{The GNU
texinfo.texi(,762) Emacs Manual} is a good example of a Texinfo file, as is this manual.
texinfo.texi(,763) 
texinfo.texi(,764) To make a printed document, you process a Texinfo source file with the
texinfo.texi(,765) @TeX{} typesetting program (but the Texinfo language is very different
texinfo.texi(,766) and much stricter than @TeX{}'s usual language, plain @TeX{}).  This
texinfo.texi(,767) creates a DVI file that you can typeset and print as a book or report
texinfo.texi(,768) (@pxref{Hardcopy}).
texinfo.texi(,769) 
texinfo.texi(,770) @pindex makeinfo
texinfo.texi(,771) To output an Info file, process your Texinfo source with the
texinfo.texi(,772) @code{makeinfo} utility or Emacs's @code{texinfo-format-buffer} command.
texinfo.texi(,773) You can install the result in your Info tree (@pxref{Installing an Info
texinfo.texi(,774) File}).
texinfo.texi(,775) 
texinfo.texi(,776) To output an HTML file, run @code{makeinfo --html} on your Texinfo
texinfo.texi(,777) source.  You can (for example) install the result on your web site.
texinfo.texi(,778) 
texinfo.texi(,779) @cindex Docbook, converting to Texinfo
texinfo.texi(,780) @cindex Conversion, from Docbook to Texinfo
texinfo.texi(,781) To output an XML file, run @code{makeinfo --xml} on your Texinfo source.
texinfo.texi(,782) To output DocBook (a particular form of XML), run @code{makeinfo
texinfo.texi(,783) --docbook}.  If you want to convert from Docbook @emph{to} Texinfo,
texinfo.texi(,784) please see @uref{http://docbook2X.sourceforge.net/}.
texinfo.texi(,785) 
texinfo.texi(,786) @cindex Output formats, supporting more
texinfo.texi(,787) @cindex SGML-tools output format
texinfo.texi(,788) If you are a programmer and would like to contribute to the GNU project
texinfo.texi(,789) by implementing additional output formats for Texinfo, that would be
texinfo.texi(,790) excellent.  But please do not write a separate translator texi2foo for
texinfo.texi(,791) your favorite format foo!  That is the hard way to do the job, and makes
texinfo.texi(,792) extra work in subsequent maintenance, since the Texinfo language is
texinfo.texi(,793) continually being enhanced and updated.  Instead, the best approach is
texinfo.texi(,794) modify @code{makeinfo} to generate the new format, as it does now for
texinfo.texi(,795) Info, plain text, HTML, XML, and DocBook.
texinfo.texi(,796) 
texinfo.texi(,797) @TeX{} works with virtually all printers; Info works with virtually all
texinfo.texi(,798) computer terminals; the HTML output works with virtually all web
texinfo.texi(,799) browsers.  Thus Texinfo can be used by almost any computer user.
texinfo.texi(,800) 
texinfo.texi(,801) @cindex Source file
texinfo.texi(,802) A Texinfo source file is a plain @sc{ascii} file containing text and
texinfo.texi(,803) @dfn{@@-commands} (words preceded by an @samp{@@}) that tell the
texinfo.texi(,804) typesetting and formatting programs what to do.  You may edit a Texinfo
texinfo.texi(,805) file with any text editor; but it is especially convenient to use GNU
texinfo.texi(,806) Emacs since that editor has a special mode, called Texinfo mode, that
texinfo.texi(,807) provides various Texinfo-related features.  (@xref{Texinfo Mode}.)
texinfo.texi(,808) 
texinfo.texi(,809) Before writing a Texinfo source file, you should learn about nodes,
texinfo.texi(,810) menus, cross references, and the rest, for example by reading this
texinfo.texi(,811) manual.
texinfo.texi(,812) 
texinfo.texi(,813) You can use Texinfo to create both online help and printed manuals;
texinfo.texi(,814) moreover, Texinfo is freely redistributable.  For these reasons, Texinfo
texinfo.texi(,815) is the official documentation format of the GNU project.  More
texinfo.texi(,816) information is available at the @uref{http://www.gnu.org/doc/, GNU
texinfo.texi(,817) documentation web page}.
texinfo.texi(,818) 
texinfo.texi(,819) @cindex Man page output, not supported
texinfo.texi(,820) From time to time, proposals are made to generate traditional Unix man
texinfo.texi(,821) pages from Texinfo source.  This is not likely to ever be supported,
texinfo.texi(,822) because man pages have a very strict conventional format.  Merely
texinfo.texi(,823) enhancing @command{makeinfo} to output troff format would be
texinfo.texi(,824) insufficient.  Generating a good man page therefore requires a
texinfo.texi(,825) completely different source than the typical Texinfo applications of
texinfo.texi(,826) writing a good user tutorial or a good reference manual.  This makes
texinfo.texi(,827) generating man pages incompatible with the Texinfo design goal of not
texinfo.texi(,828) having to document the same information in different ways for different
texinfo.texi(,829) output formats.  You might as well just write the man page directly.
texinfo.texi(,830) 
texinfo.texi(,831) @pindex help2man 
texinfo.texi(,832) @cindex O'Dea, Brendan
texinfo.texi(,833) Man pages still have their place, and if you wish to support them, the
texinfo.texi(,834) program @command{help2man} may be useful; it generates a traditional man
texinfo.texi(,835) page from the @samp{--help} output of a program.  In fact, this is
texinfo.texi(,836) currently used to generate man pages for the Texinfo programs
texinfo.texi(,837) themselves.  It is GNU software written by Brendan O'Dea, available from
texinfo.texi(,838) @uref{ftp://ftp.gnu.org/gnu/help2man/}.
texinfo.texi(,839) 
texinfo.texi(,840) 
texinfo.texi(,841) @node Info Files
texinfo.texi(,842) @section Info files
texinfo.texi(,843) @cindex Info files
texinfo.texi(,844) 
texinfo.texi(,845) An Info file is a Texinfo file formatted so that the Info documentation
texinfo.texi(,846) reading program can operate on it.  (@code{makeinfo}
texinfo.texi(,847) and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
texinfo.texi(,848) into an Info file.)
texinfo.texi(,849) 
texinfo.texi(,850) Info files are divided into pieces called @dfn{nodes}, each of which
texinfo.texi(,851) contains the discussion of one topic.  Each node has a name, and
texinfo.texi(,852) contains both text for the user to read and pointers to other nodes,
texinfo.texi(,853) which are identified by their names.  The Info program displays one node
texinfo.texi(,854) at a time, and provides commands with which the user can move to other
texinfo.texi(,855) related nodes.
texinfo.texi(,856) 
texinfo.texi(,858) @inforef{Top, info, info}, for more information about using Info.
texinfo.texi(,860) 
texinfo.texi(,861) Each node of an Info file may have any number of child nodes that
texinfo.texi(,862) describe subtopics of the node's topic.  The names of child
texinfo.texi(,863) nodes are listed in a @dfn{menu} within the parent node; this
texinfo.texi(,864) allows you to use certain Info commands to move to one of the child
texinfo.texi(,865) nodes.  Generally, an Info file is organized like a book.  If a node
texinfo.texi(,866) is at the logical level of a chapter, its child nodes are at the level
texinfo.texi(,867) of sections; likewise, the child nodes of sections are at the level
texinfo.texi(,868) of subsections.
texinfo.texi(,869) 
texinfo.texi(,870) All the children of any one parent are linked together in a
texinfo.texi(,871) bidirectional chain of `Next' and `Previous' pointers.  The `Next'
texinfo.texi(,872) pointer provides a link to the next section, and the `Previous' pointer
texinfo.texi(,873) provides a link to the previous section.  This means that all the nodes
texinfo.texi(,874) that are at the level of sections within a chapter are linked together.
texinfo.texi(,875) Normally the order in this chain is the same as the order of the
texinfo.texi(,876) children in the parent's menu.  Each child node records the parent node
texinfo.texi(,877) name as its `Up' pointer.  The last child has no `Next' pointer, and the
texinfo.texi(,878) first child has the parent both as its `Previous' and as its `Up'
texinfo.texi(,879) pointer.@footnote{In some documents, the first child has no `Previous'
texinfo.texi(,880) pointer.  Occasionally, the last child has the node name of the next
texinfo.texi(,881) following higher level node as its `Next' pointer.}
texinfo.texi(,882) 
texinfo.texi(,883) The book-like structuring of an Info file into nodes that correspond
texinfo.texi(,884) to chapters, sections, and the like is a matter of convention, not a
texinfo.texi(,885) requirement.  The `Up', `Previous', and `Next' pointers of a node can
texinfo.texi(,886) point to any other nodes, and a menu can contain any other nodes.
texinfo.texi(,887) Thus, the node structure can be any directed graph.  But it is usually
texinfo.texi(,888) more comprehensible to follow a structure that corresponds to the
texinfo.texi(,889) structure of chapters and sections in a printed book or report.@refill
texinfo.texi(,890) 
texinfo.texi(,891) In addition to menus and to `Next', `Previous', and `Up' pointers, Info
texinfo.texi(,892) provides pointers of another kind, called references, that can be
texinfo.texi(,893) sprinkled throughout the text.  This is usually the best way to
texinfo.texi(,894) represent links that do not fit a hierarchical structure.@refill
texinfo.texi(,895) 
texinfo.texi(,896) Usually, you will design a document so that its nodes match the
texinfo.texi(,897) structure of chapters and sections in the printed output.  But
texinfo.texi(,898) occasionally there are times when this is not right for the material
texinfo.texi(,899) being discussed.  Therefore, Texinfo uses separate commands to specify
texinfo.texi(,900) the node structure for the Info file and the section structure for the
texinfo.texi(,901) printed output.@refill
texinfo.texi(,902) 
texinfo.texi(,903) Generally, you enter an Info file through a node that by convention is
texinfo.texi(,904) named `Top'.  This node normally contains just a brief summary of the
texinfo.texi(,905) file's purpose, and a large menu through which the rest of the file is
texinfo.texi(,906) reached.  From this node, you can either traverse the file
texinfo.texi(,907) systematically by going from node to node, or you can go to a specific
texinfo.texi(,908) node listed in the main menu, or you can search the index menus and then
texinfo.texi(,909) go directly to the node that has the information you want.  Alternatively,
texinfo.texi(,910) with the standalone Info program, you can specify specific menu items on
texinfo.texi(,911) the command line (@pxref{Top,,, info, Info}).
texinfo.texi(,912) 
texinfo.texi(,913) If you want to read through an Info file in sequence, as if it were a
texinfo.texi(,914) printed manual, you can hit @key{SPC} repeatedly, or you get the whole
texinfo.texi(,915) file with the advanced Info command @kbd{g *}.  (@inforef{Expert,
texinfo.texi(,916) Advanced Info commands, info}.)@refill
texinfo.texi(,917) 
texinfo.texi(,918) @c !!! dir file may be located in one of many places:
texinfo.texi(,919) @c     /usr/local/emacs/info            mentioned in info.c DEFAULT_INFOPATH
texinfo.texi(,920) @c     /usr/local/lib/emacs/info        mentioned in info.c DEFAULT_INFOPATH
texinfo.texi(,921) @c     /usr/gnu/info                    mentioned in info.c DEFAULT_INFOPATH
texinfo.texi(,922) @c     /usr/local/info
texinfo.texi(,923) @c     /usr/local/lib/info
texinfo.texi(,924) The @file{dir} file in the @file{info} directory serves as the
texinfo.texi(,925) departure point for the whole Info system.  From it, you can reach the
texinfo.texi(,926) `Top' nodes of each of the documents in a complete Info system.@refill
texinfo.texi(,927) 
texinfo.texi(,928) @cindex URI syntax for Info
texinfo.texi(,929) If you wish to refer to an Info file in a URI, you can use the
texinfo.texi(,930) (unofficial) syntax exemplified in the following.  This works with
texinfo.texi(,931) Emacs/W3, for example:
texinfo.texi(,932) @example
texinfo.texi(,933) info:///usr/info/emacs#Dissociated%20Press
texinfo.texi(,934) info:emacs#Dissociated%20Press
texinfo.texi(,935) info://localhost/usr/info/emacs#Dissociated%20Press
texinfo.texi(,936) @end example
texinfo.texi(,937) 
texinfo.texi(,938) The @command{info} program itself does not follow URI's of any kind.
texinfo.texi(,939) 
texinfo.texi(,940) 
texinfo.texi(,941) @node Printed Books
texinfo.texi(,942) @section Printed Books
texinfo.texi(,943) @cindex Printed book and manual characteristics
texinfo.texi(,944) @cindex Manual characteristics, printed
texinfo.texi(,945) @cindex Book characteristics, printed
texinfo.texi(,946) @cindex Texinfo printed book characteristics
texinfo.texi(,947) @cindex Characteristics, printed books or manuals
texinfo.texi(,948) 
texinfo.texi(,949) @cindex Knuth, Donald
texinfo.texi(,950) A Texinfo file can be formatted and typeset as a printed book or manual.
texinfo.texi(,951) To do this, you need @TeX{}, a powerful, sophisticated typesetting
texinfo.texi(,952) program written by Donald Knuth.@footnote{You can also use the
texinfo.texi(,953) @pindex texi2roff@r{, unsupported software}
texinfo.texi(,954) @uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
texinfo.texi(,955) do not have @TeX{}; since Texinfo is designed for use with @TeX{},
texinfo.texi(,956) @code{texi2roff} is not described here.  @code{texi2roff} is not part of
texinfo.texi(,957) the standard GNU distribution and is not maintained or up-to-date with
texinfo.texi(,958) all the Texinfo features described in this manual.}
texinfo.texi(,959) 
texinfo.texi(,960) A Texinfo-based book is similar to any other typeset, printed work: it
texinfo.texi(,961) can have a title page, copyright page, table of contents, and preface,
texinfo.texi(,962) as well as chapters, numbered or unnumbered sections and subsections,
texinfo.texi(,963) page headers, cross references, footnotes, and indices.@refill
texinfo.texi(,964) 
texinfo.texi(,965) You can use Texinfo to write a book without ever having the intention
texinfo.texi(,966) of converting it into online information.  You can use Texinfo for
texinfo.texi(,967) writing a printed novel, and even to write a printed memo, although
texinfo.texi(,968) this latter application is not recommended since electronic mail is so
texinfo.texi(,969) much easier.@refill
texinfo.texi(,970) 
texinfo.texi(,971) @TeX{} is a general purpose typesetting program.  Texinfo provides a
texinfo.texi(,972) file @file{texinfo.tex} that contains information (definitions or
texinfo.texi(,973) @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
texinfo.texi(,974) (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
texinfo.texi(,975) to @TeX{} commands, which @TeX{} can then process to create the typeset
texinfo.texi(,976) document.)  @file{texinfo.tex} contains the specifications for printing
texinfo.texi(,977) a document.  You can get the latest version of @file{texinfo.tex} from
texinfo.texi(,978) @uref{ftp://ftp.gnu.org/gnu/texinfo.tex}.
texinfo.texi(,979) 
texinfo.texi(,980) In the United States, documents are most often printed on 8.5 inch by 11
texinfo.texi(,981) inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size.  But
texinfo.texi(,982) you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
texinfo.texi(,983) 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
texinfo.texi(,984) (@code{@@afourpaper}, @code{@@afivepaper}).  (@xref{smallbook, ,
texinfo.texi(,985) Printing ``Small'' Books}.  Also, see @ref{A4 Paper, ,Printing on A4
texinfo.texi(,986) Paper}.)
texinfo.texi(,987) 
texinfo.texi(,988) By changing the parameters in @file{texinfo.tex}, you can change the
texinfo.texi(,989) size of the printed document.  In addition, you can change the style in
texinfo.texi(,990) which the printed document is formatted; for example, you can change the
texinfo.texi(,991) sizes and fonts used, the amount of indentation for each paragraph, the
texinfo.texi(,992) degree to which words are hyphenated, and the like.  By changing the
texinfo.texi(,993) specifications, you can make a book look dignified, old and serious, or
texinfo.texi(,994) light-hearted, young and cheery.
texinfo.texi(,995) 
texinfo.texi(,996) @TeX{} is freely distributable.  It is written in a superset of Pascal
texinfo.texi(,997) called WEB and can be compiled either in Pascal or (by using a
texinfo.texi(,998) conversion program that comes with the @TeX{} distribution) in C.
texinfo.texi(,999) (@xref{TeX Mode, ,@TeX{} Mode, emacs, The GNU Emacs Manual}, for information
texinfo.texi(,1000) about @TeX{}.)@refill
texinfo.texi(,1001) 
texinfo.texi(,1002) @TeX{} is very powerful and has a great many features.  Because a
texinfo.texi(,1003) Texinfo file must be able to present information both on a
texinfo.texi(,1004) character-only terminal in Info form and in a typeset book, the
texinfo.texi(,1005) formatting commands that Texinfo supports are necessarily limited.
texinfo.texi(,1006) 
texinfo.texi(,1007) To get a copy of @TeX{}, see
texinfo.texi(,1008) @ref{Obtaining TeX, , How to Obtain @TeX{}}.
texinfo.texi(,1009) 
texinfo.texi(,1010) 
texinfo.texi(,1011) @node Formatting Commands
texinfo.texi(,1012) @section @@-commands
texinfo.texi(,1013) @cindex @@-commands
texinfo.texi(,1014) @cindex Formatting commands
texinfo.texi(,1015) 
texinfo.texi(,1016) In a Texinfo file, the commands that tell @TeX{} how to typeset the
texinfo.texi(,1017) printed manual and tell @code{makeinfo} and
texinfo.texi(,1018) @code{texinfo-format-buffer} how to create an Info file are preceded
texinfo.texi(,1019) by @samp{@@}; they are called @dfn{@@-commands}.  For example,
texinfo.texi(,1020) @code{@@node} is the command to indicate a node and @code{@@chapter}
texinfo.texi(,1021) is the command to indicate the start of a chapter.@refill
texinfo.texi(,1022) 
texinfo.texi(,1023) @quotation
texinfo.texi(,1024) @strong{Please note:} All the @@-commands, with the exception of the
texinfo.texi(,1025) @code{@@TeX@{@}} command, must be written entirely in lower case.
texinfo.texi(,1026) @end quotation
texinfo.texi(,1027) 
texinfo.texi(,1028) The Texinfo @@-commands are a strictly limited set of constructs.  The
texinfo.texi(,1029) strict limits make it possible for Texinfo files to be understood both
texinfo.texi(,1030) by @TeX{} and by the code that converts them into Info files.  You can
texinfo.texi(,1031) display Info files on any terminal that displays alphabetic and
texinfo.texi(,1032) numeric characters.  Similarly, you can print the output generated by
texinfo.texi(,1033) @TeX{} on a wide variety of printers.@refill
texinfo.texi(,1034) 
texinfo.texi(,1035) Depending on what they do or what arguments@footnote{The word
texinfo.texi(,1036) @dfn{argument} comes from the way it is used in mathematics and does not
texinfo.texi(,1037) refer to a dispute between two people; it refers to the information
texinfo.texi(,1038) presented to the command.  According to the @cite{Oxford English
texinfo.texi(,1039) Dictionary}, the word derives from the Latin for @dfn{to make clear,
texinfo.texi(,1040) prove}; thus it came to mean `the evidence offered as proof', which is
texinfo.texi(,1041) to say, `the information offered', which led to its mathematical
texinfo.texi(,1042) meaning.  In its other thread of derivation, the word came to mean `to
texinfo.texi(,1043) assert in a manner against which others may make counter assertions',
texinfo.texi(,1044) which led to the meaning of `argument' as a dispute.} they take, you
texinfo.texi(,1045) need to write @@-commands on lines of their own or as part of
texinfo.texi(,1046) sentences:
texinfo.texi(,1047) 
texinfo.texi(,1048) @itemize @bullet
texinfo.texi(,1049) @item
texinfo.texi(,1050) Write a command such as @code{@@noindent} at the beginning of a line as
texinfo.texi(,1051) the only text on the line.  (@code{@@noindent} prevents the beginning of
texinfo.texi(,1052) the next line from being indented as the beginning of a
texinfo.texi(,1053) paragraph.)@refill
texinfo.texi(,1054) 
texinfo.texi(,1055) @item
texinfo.texi(,1056) Write a command such as @code{@@chapter} at the beginning of a line
texinfo.texi(,1057) followed by the command's arguments, in this case the chapter title, on
texinfo.texi(,1058) the rest of the line.  (@code{@@chapter} creates chapter titles.)@refill
texinfo.texi(,1059) 
texinfo.texi(,1060) @item
texinfo.texi(,1061) Write a command such as @code{@@dots@{@}} wherever you wish but usually
texinfo.texi(,1062) within a sentence. (@code{@@dots@{@}} creates dots @dots{})@refill
texinfo.texi(,1063) 
texinfo.texi(,1064) @item
texinfo.texi(,1065) Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
texinfo.texi(,1066) wish (but usually within a sentence) with its argument,
texinfo.texi(,1067) @var{sample-code} in this example, between the braces.  (@code{@@code}
texinfo.texi(,1068) marks text as being code.)@refill
texinfo.texi(,1069) 
texinfo.texi(,1070) @item
texinfo.texi(,1071) Write a command such as @code{@@example} on a line of its own; write the
texinfo.texi(,1072) body-text on following lines; and write the matching @code{@@end}
texinfo.texi(,1073) command, @code{@@end example} in this case, at the on a line of its own
texinfo.texi(,1074) after the body-text. (@code{@@example} @dots{} @code{@@end example}
texinfo.texi(,1075) indents and typesets body-text as an example.)  It's usually ok to
texinfo.texi(,1076) indent environment commands like this, but in complicated and
texinfo.texi(,1077) hard-to-define circumstances the extra spaces cause extra space to
texinfo.texi(,1078) appear in the output, so beware.
texinfo.texi(,1079) @end itemize
texinfo.texi(,1080) 
texinfo.texi(,1081) @noindent
texinfo.texi(,1082) @cindex Braces, when to use
texinfo.texi(,1083) As a general rule, a command requires braces if it mingles among other
texinfo.texi(,1084) text; but it does not need braces if it starts a line of its own.  The
texinfo.texi(,1085) non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
texinfo.texi(,1086) they do not need braces.@refill
texinfo.texi(,1087) 
texinfo.texi(,1088) As you gain experience with Texinfo, you will rapidly learn how to
texinfo.texi(,1089) write the different commands: the different ways to write commands
texinfo.texi(,1090) make it easier to write and read Texinfo files than if all commands
texinfo.texi(,1091) followed exactly the same syntax.  (For details about @@-command
texinfo.texi(,1092) syntax, see @ref{Command Syntax, , @@-Command Syntax}.)@refill
texinfo.texi(,1093) 
texinfo.texi(,1094) 
texinfo.texi(,1095) @node Conventions
texinfo.texi(,1096) @section General Syntactic Conventions
texinfo.texi(,1097) @cindex General syntactic conventions
texinfo.texi(,1098) @cindex Syntactic conventions
texinfo.texi(,1099) @cindex Conventions, syntactic
texinfo.texi(,1100) 
texinfo.texi(,1101) This section describes the general conventions used in all Texinfo documents.
texinfo.texi(,1102) 
texinfo.texi(,1103) @itemize @bullet
texinfo.texi(,1104) @item
texinfo.texi(,1105) All printable @sc{ascii} characters except @samp{@@}, @samp{@{} and
texinfo.texi(,1106) @samp{@}} can appear in a Texinfo file and stand for themselves.
texinfo.texi(,1107) @samp{@@} is the escape character which introduces commands, while
texinfo.texi(,1108) @samp{@{} and @samp{@}} are used to surround arguments to certain
texinfo.texi(,1109) commands.  To put one of these special characters into the document, put
texinfo.texi(,1110) an @samp{@@} character in front of it, like this: @samp{@@@@},
texinfo.texi(,1111) @samp{@@@{}, and @samp{@@@}}.
texinfo.texi(,1112) 
texinfo.texi(,1113) @item
texinfo.texi(,1114) It is customary in @TeX{} to use doubled single-quote characters to
texinfo.texi(,1115) begin and end quotations: @w{@t{`@w{}`@dots{}'@w{}'}}.  This
texinfo.texi(,1116) convention should be followed in Texinfo files.  @TeX{} converts
texinfo.texi(,1117) two single quotes to left- and right-hand doubled
texinfo.texi(,1118) quotation marks, 
texinfo.texi(,1119) @c this comes out as "like this" in Info, of course, which is just confusing.
texinfo.texi(,1123) and Info converts doubled single-quote characters to @sc{ascii}
texinfo.texi(,1124) double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
texinfo.texi(,1125) 
texinfo.texi(,1126) @item
texinfo.texi(,1127) Use three hyphens in a row, @samp{---}, for a dash---like this.  In
texinfo.texi(,1128) @TeX{}, a single or double hyphen produces a printed dash that is
texinfo.texi(,1129) shorter than the usual typeset dash. Info reduces three hyphens to two
texinfo.texi(,1130) for display on the screen.
texinfo.texi(,1131) 
texinfo.texi(,1132) @item
texinfo.texi(,1133) To prevent a paragraph from being indented in the printed manual, put
texinfo.texi(,1134) the command @code{@@noindent} on a line by itself before the
texinfo.texi(,1135) paragraph.
texinfo.texi(,1136) 
texinfo.texi(,1137) @item
texinfo.texi(,1138) If you mark off a region of the Texinfo file with the @code{@@iftex}
texinfo.texi(,1139) and @w{@code{@@end iftex}} commands, that region will appear only in
texinfo.texi(,1140) the printed copy; in that region, you can use certain commands
texinfo.texi(,1141) borrowed from plain @TeX{} that you cannot use in Info.  Conversely,
texinfo.texi(,1142) text surrounded by @code{@@ifnottex} and @code{@@end ifnottex} will
texinfo.texi(,1143) appear in all output formats @emph{except} @TeX{}.
texinfo.texi(,1144) 
texinfo.texi(,1145) Each of the other output formats (@code{html}, @code{info},
texinfo.texi(,1146) @code{plaintext}) have an analogous pair of commands.  @xref{Conditionals}.
texinfo.texi(,1147) @end itemize
texinfo.texi(,1148) 
texinfo.texi(,1149) @cindex Tabs; don't use!
texinfo.texi(,1150) @quotation
texinfo.texi(,1151) @strong{Caution:} Do not use tab characters in a Texinfo file (except in
texinfo.texi(,1152) verbatim modes)!  @TeX{} uses variable-width fonts, which means that it
texinfo.texi(,1153) is impractical at best to define a tab to work in all circumstances.
texinfo.texi(,1154) Consequently, @TeX{} treats tabs like single spaces, and that is not
texinfo.texi(,1155) what they look like.  Furthermore, @code{makeinfo} does nothing special
texinfo.texi(,1156) with tabs, and thus a tab character in your input file may appear
texinfo.texi(,1157) differently in the output, for example, in indented text.
texinfo.texi(,1158) 
texinfo.texi(,1159) @noindent
texinfo.texi(,1160) To avoid this problem, Texinfo mode causes GNU Emacs to insert multiple
texinfo.texi(,1161) spaces when you press the @key{TAB} key.
texinfo.texi(,1162) 
texinfo.texi(,1163) @noindent
texinfo.texi(,1164) Also, you can run @code{untabify} in Emacs to convert tabs in a region
texinfo.texi(,1165) to multiple spaces.
texinfo.texi(,1166) @end quotation
texinfo.texi(,1167) 
texinfo.texi(,1168) 
texinfo.texi(,1169) @node Comments
texinfo.texi(,1170) @section Comments
texinfo.texi(,1171) 
texinfo.texi(,1172) @cindex Comments
texinfo.texi(,1173) @findex comment
texinfo.texi(,1174) @findex c @r{(comment)}
texinfo.texi(,1175) 
texinfo.texi(,1176) You can write comments in a Texinfo file that will not appear in
texinfo.texi(,1177) either the Info file or the printed manual by using the
texinfo.texi(,1178) @code{@@comment} command (which may be abbreviated to @code{@@c}).
texinfo.texi(,1179) Such comments are for the person who revises the Texinfo file.  All the
texinfo.texi(,1180) text on a line that follows either @code{@@comment} or @code{@@c} is a
texinfo.texi(,1181) comment; the rest of the line does not appear in either the Info file
texinfo.texi(,1182) or the printed manual.
texinfo.texi(,1183) 
texinfo.texi(,1184) Often, you can write the @code{@@comment} or @code{@@c} in the middle of
texinfo.texi(,1185) a line, and only the text that follows after the @code{@@comment} or
texinfo.texi(,1186) @code{@@c} command does not appear; but some commands, such as
texinfo.texi(,1187) @code{@@settitle} and @code{@@setfilename}, work on a whole line.  You
texinfo.texi(,1188) cannot use @code{@@comment} or @code{@@c} in a line beginning with such
texinfo.texi(,1189) a command.
texinfo.texi(,1190) 
texinfo.texi(,1191) @cindex Ignored text
texinfo.texi(,1192) @cindex Unprocessed text
texinfo.texi(,1193) @findex ignore
texinfo.texi(,1194) You can write long stretches of text that will not appear in either
texinfo.texi(,1195) the Info file or the printed manual by using the @code{@@ignore} and
texinfo.texi(,1196) @code{@@end ignore} commands.  Write each of these commands on a line
texinfo.texi(,1197) of its own, starting each command at the beginning of the line.  Text
texinfo.texi(,1198) between these two commands does not appear in the processed output.
texinfo.texi(,1199) You can use @code{@@ignore} and @code{@@end ignore} for writing
texinfo.texi(,1200) comments.
texinfo.texi(,1201) 
texinfo.texi(,1202) Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
texinfo.texi(,1203) @code{@@ifclear} conditions is ignored in the sense that it will not
texinfo.texi(,1204) contribute to the formatted output.  However, @TeX{} and makeinfo must
texinfo.texi(,1205) still parse the ignored text, in order to understand when to @emph{stop}
texinfo.texi(,1206) ignoring text from the source file; that means that you may still get
texinfo.texi(,1207) error messages if you have invalid Texinfo commands within ignored text.
texinfo.texi(,1208) 
texinfo.texi(,1209) 
texinfo.texi(,1210) @node Minimum
texinfo.texi(,1211) @section What a Texinfo File Must Have
texinfo.texi(,1212) @cindex Minimal Texinfo file (requirements)
texinfo.texi(,1213) @cindex Must have in Texinfo file
texinfo.texi(,1214) @cindex Required in Texinfo file
texinfo.texi(,1215) @cindex Texinfo file minimum
texinfo.texi(,1216) 
texinfo.texi(,1217) By convention, the namea of a Texinfo file ends with (in order of
texinfo.texi(,1218) preference) one of the extensions @file{.texinfo}, @file{.texi},
texinfo.texi(,1219) @file{.txi}, or @file{.tex}.  The longer extensions are preferred since
texinfo.texi(,1220) they describe more clearly to a human reader the nature of the file.
texinfo.texi(,1221) The shorter extensions are for operating systems that cannot handle long
texinfo.texi(,1222) file names.
texinfo.texi(,1223) 
texinfo.texi(,1224) In order to be made into a printed manual and an Info file, a Texinfo
texinfo.texi(,1225) file @strong{must} begin with lines like this:
texinfo.texi(,1226) 
texinfo.texi(,1227) @example
texinfo.texi(,1228) @group
texinfo.texi(,1229) \input texinfo
texinfo.texi(,1230) @@setfilename @var{info-file-name}
texinfo.texi(,1231) @@settitle @var{name-of-manual}
texinfo.texi(,1232) @end group
texinfo.texi(,1233) @end example
texinfo.texi(,1234) 
texinfo.texi(,1235) @noindent
texinfo.texi(,1236) The contents of the file follow this beginning, and then you
texinfo.texi(,1237) @strong{must} end a Texinfo file with a line like this:
texinfo.texi(,1238) 
texinfo.texi(,1239) @example
texinfo.texi(,1240) @@bye
texinfo.texi(,1241) @end example
texinfo.texi(,1242) 
texinfo.texi(,1243) @findex \input @r{(raw @TeX{} startup)}
texinfo.texi(,1244) @noindent
texinfo.texi(,1245) Here's an explanation:
texinfo.texi(,1246) 
texinfo.texi(,1247) @itemize @bullet
texinfo.texi(,1248) @item
texinfo.texi(,1249) The @samp{\input texinfo} line tells @TeX{} to use the
texinfo.texi(,1250) @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
texinfo.texi(,1251) @@-commands into @TeX{} typesetting commands.  (Note the use of the
texinfo.texi(,1252) backslash, @samp{\}; this is correct for @TeX{}.)
texinfo.texi(,1253) 
texinfo.texi(,1254) @item
texinfo.texi(,1255) The @code{@@setfilename} line provides a name for the Info file and
texinfo.texi(,1256) tells @TeX{} to open auxiliary files.  @strong{All text before
texinfo.texi(,1257) @code{@@setfilename} is ignored!}
texinfo.texi(,1258) 
texinfo.texi(,1259) @item
texinfo.texi(,1260) The @code{@@settitle} line specifies a title for the page headers (or
texinfo.texi(,1261) footers) of the printed manual, and the default document description for
texinfo.texi(,1262) the @samp{<head>} in HTML format.  Strictly speaking, @code{@@settitle}
texinfo.texi(,1263) is optional---if you don't mind your document being titled `Untitled'.
texinfo.texi(,1264) 
texinfo.texi(,1265) @item
texinfo.texi(,1266) The @code{@@bye} line at the end of the file on a line of its own tells
texinfo.texi(,1267) the formatters that the file is ended and to stop formatting.
texinfo.texi(,1268) 
texinfo.texi(,1269) @end itemize
texinfo.texi(,1270) 
texinfo.texi(,1271) Typically, you will not use quite such a spare format, but will include
texinfo.texi(,1272) mode setting and start-of-header and end-of-header lines at the
texinfo.texi(,1273) beginning of a Texinfo file, like this:
texinfo.texi(,1274) 
texinfo.texi(,1275) @example
texinfo.texi(,1276) @group
texinfo.texi(,1277) \input texinfo   @@c -*-texinfo-*-
texinfo.texi(,1278) @@c %**start of header
texinfo.texi(,1279) @@setfilename @var{info-file-name}
texinfo.texi(,1280) @@settitle @var{name-of-manual}
texinfo.texi(,1281) @@c %**end of header
texinfo.texi(,1282) @end group
texinfo.texi(,1283) @end example
texinfo.texi(,1284) 
texinfo.texi(,1285) @noindent
texinfo.texi(,1286) In the first line, @samp{-*-texinfo-*-} causes Emacs to switch into
texinfo.texi(,1287) Texinfo mode when you edit the file.
texinfo.texi(,1288) 
texinfo.texi(,1289) The @code{@@c} lines which surround the @code{@@setfilename} and
texinfo.texi(,1290) @code{@@settitle} lines are optional, but you need them in order to
texinfo.texi(,1291) run @TeX{} or Info on just part of the file.  (@xref{Start of Header}.)
texinfo.texi(,1292) 
texinfo.texi(,1293) Furthermore, you will usually provide a Texinfo file with a title page,
texinfo.texi(,1294) indices, and the like, all of which are explained in this manual.  But
texinfo.texi(,1295) the minimum, which can be useful for short documents, is just the three
texinfo.texi(,1296) lines at the beginning and the one line at the end.
texinfo.texi(,1297) 
texinfo.texi(,1298) 
texinfo.texi(,1299) @node Six Parts
texinfo.texi(,1300) @section Six Parts of a Texinfo File
texinfo.texi(,1301) 
texinfo.texi(,1302) Generally, a Texinfo file contains more than the minimal beginning and
texinfo.texi(,1303) end described in the previous section---it usually contains the six
texinfo.texi(,1304) parts listed below.  These are described fully in the following sections.
texinfo.texi(,1305) 
texinfo.texi(,1306) @table @r
texinfo.texi(,1307) @item 1. Header
texinfo.texi(,1308) The @dfn{Header} names the file, tells @TeX{} which definitions file to
texinfo.texi(,1309) use, and other such housekeeping tasks.
texinfo.texi(,1310) 
texinfo.texi(,1311) @item 2. Summary and Copyright
texinfo.texi(,1312) The @dfn{Summary and Copyright} segment describes the document and
texinfo.texi(,1313) contains the copyright notice and copying permissions.  This is done
texinfo.texi(,1314) with the @code{@@copying} command.
texinfo.texi(,1315) 
texinfo.texi(,1316) @item 3. Title and Copyright
texinfo.texi(,1317) The @dfn{Title and Copyright} segment contains the title and copyright
texinfo.texi(,1318) pages for the printed manual.  The segment must be enclosed between
texinfo.texi(,1319) @code{@@titlepage} and @code{@@end titlepage} commands.  The title and
texinfo.texi(,1320) copyright page appear only in the printed manual.
texinfo.texi(,1321) 
texinfo.texi(,1322) @item 4. `Top' Node and Master Menu
texinfo.texi(,1323) The `Top' node starts off the online output; it does not appear in the
texinfo.texi(,1324) printed manual.  We recommend including the copying permissions here as
texinfo.texi(,1325) well as the segments above.  And it contains at least a top-level menu
texinfo.texi(,1326) listing the chapters, and possibly a @dfn{Master Menu} listing all the
texinfo.texi(,1327) nodes in the entire document.
texinfo.texi(,1328) 
texinfo.texi(,1329) @item 5. Body
texinfo.texi(,1330) The @dfn{Body} of the document is typically structured like a
texinfo.texi(,1331) traditional book or encyclopedia, but it may be free form.
texinfo.texi(,1332) 
texinfo.texi(,1333) @item 6. End
texinfo.texi(,1334) The @dfn{End} segment contains commands for printing indices and
texinfo.texi(,1335) generating the table of contents, and the @code{@@bye} command on a line
texinfo.texi(,1336) of its own.
texinfo.texi(,1337) @end table
texinfo.texi(,1338) 
texinfo.texi(,1339) 
texinfo.texi(,1340) @node Short Sample
texinfo.texi(,1341) @section A Short Sample Texinfo File
texinfo.texi(,1342) @cindex Sample Texinfo file, with comments
texinfo.texi(,1343) 
texinfo.texi(,1344) Here is a very short but complete Texinfo file, in the six conventional
texinfo.texi(,1345) parts enumerated in the previous section, so you can see how Texinfo
texinfo.texi(,1346) source appears in practice.  The first three parts of the file, from
texinfo.texi(,1347) @samp{\input texinfo} through to @samp{@@end titlepage}, look more
texinfo.texi(,1348) intimidating than they are: most of the material is standard
texinfo.texi(,1349) boilerplate; when writing a manual, you simply change the names as
texinfo.texi(,1350) appropriate.
texinfo.texi(,1351) 
texinfo.texi(,1352) @xref{Beginning a File}, for full documentation on the commands listed
texinfo.texi(,1353) here.  @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
texinfo.texi(,1354) 
texinfo.texi(,1355) In the following, the sample text is @emph{indented}; comments on it are
texinfo.texi(,1356) not.  The complete file, without interspersed comments, is shown in
texinfo.texi(,1357) @ref{Short Sample Texinfo File}.
texinfo.texi(,1358) 
texinfo.texi(,1359) @subheading Part 1: Header
texinfo.texi(,1360) 
texinfo.texi(,1361) @noindent
texinfo.texi(,1362) The header does not appear in either the Info file or the
texinfo.texi(,1363) printed output.  It sets various parameters, including the
texinfo.texi(,1364) name of the Info file and the title used in the header.
texinfo.texi(,1365) 
texinfo.texi(,1366) @example
texinfo.texi(,1367) @group
texinfo.texi(,1368) \input texinfo   @@c -*-texinfo-*-
texinfo.texi(,1369) @@c %**start of header
texinfo.texi(,1370) @@setfilename sample.info
texinfo.texi(,1371) @@settitle Sample Manual 1.0
texinfo.texi(,1372) @@c %**end of header
texinfo.texi(,1373) @end group
texinfo.texi(,1374) @end example
texinfo.texi(,1375) 
texinfo.texi(,1376) @subheading Part 2: Summary Description and Copyright
texinfo.texi(,1377) 
texinfo.texi(,1378) @noindent
texinfo.texi(,1379) A real manual includes more text here, according to the license under
texinfo.texi(,1380) which it is distributed.  @xref{GNU Sample Texts}.
texinfo.texi(,1381) 
texinfo.texi(,1382) @example
texinfo.texi(,1383) @group
texinfo.texi(,1384) @@copying
texinfo.texi(,1385) This is a short example of a complete Texinfo file, version 1.0.
texinfo.texi(,1386) 
texinfo.texi(,1387) Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
texinfo.texi(,1388) @@end copying
texinfo.texi(,1389) @end group
texinfo.texi(,1390) @end example
texinfo.texi(,1391) 
texinfo.texi(,1392) @subheading Part 3: Titlepage, Contents, Copyright
texinfo.texi(,1393) 
texinfo.texi(,1394) @noindent
texinfo.texi(,1395) The titlepage segment does not appear in the online output, only in the
texinfo.texi(,1396) printed manual.  We use the @code{@@insertcopying} command to
texinfo.texi(,1397) include the permission text from the previous section, instead of
texinfo.texi(,1398) writing it out again; it is output on the back of the title page.  The
texinfo.texi(,1399) @code{@@contents} command generates a table of contents.
texinfo.texi(,1400) 
texinfo.texi(,1401) @example
texinfo.texi(,1402) @group
texinfo.texi(,1403) @@titlepage
texinfo.texi(,1404) @@title Sample Title
texinfo.texi(,1405) @end group
texinfo.texi(,1406) 
texinfo.texi(,1407) @group
texinfo.texi(,1408) @@c The following two commands start the copyright page.
texinfo.texi(,1409) @@page
texinfo.texi(,1410) @@vskip 0pt plus 1filll
texinfo.texi(,1411) @@insertcopying
texinfo.texi(,1412) @@end titlepage
texinfo.texi(,1413) @end group
texinfo.texi(,1414) 
texinfo.texi(,1415) @@c Output the table of contents at the beginning.
texinfo.texi(,1416) @@contents
texinfo.texi(,1417) @end example
texinfo.texi(,1418) 
texinfo.texi(,1419) @subheading Part 4: `Top' Node and Master Menu
texinfo.texi(,1420) 
texinfo.texi(,1421) @noindent
texinfo.texi(,1422) The `Top' node contains the master menu for the Info file.  Since a
texinfo.texi(,1423) printed manual uses a table of contents rather than a menu, the master
texinfo.texi(,1424) menu appears only in online output.  We also include the copying text
texinfo.texi(,1425) again for the benefit of online readers.  And since the copying text
texinfo.texi(,1426) begins with a brief description of the manual, no other text is needed.
texinfo.texi(,1427) 
texinfo.texi(,1428) @example
texinfo.texi(,1429) @group
texinfo.texi(,1430) @@ifnottex
texinfo.texi(,1431) @@node Top
texinfo.texi(,1432) @@end ifnottex
texinfo.texi(,1433) @end group
texinfo.texi(,1434) @end example
texinfo.texi(,1435) 
texinfo.texi(,1436) @example
texinfo.texi(,1437) @group
texinfo.texi(,1438) @@insertcopying
texinfo.texi(,1439) 
texinfo.texi(,1440) @@menu
texinfo.texi(,1441) * First Chapter::    The first chapter is the
texinfo.texi(,1442)                        only chapter in this sample.
texinfo.texi(,1443) * Index::            Complete index.
texinfo.texi(,1444) @@end menu
texinfo.texi(,1445) @end group
texinfo.texi(,1446) @end example
texinfo.texi(,1447) 
texinfo.texi(,1448) 
texinfo.texi(,1449) @subheading Part 5: The Body of the Document
texinfo.texi(,1450) 
texinfo.texi(,1451) @noindent
texinfo.texi(,1452) The body segment contains all the text of the document, but not the
texinfo.texi(,1453) indices or table of contents.  This example illustrates a node and a
texinfo.texi(,1454) chapter containing an enumerated list.
texinfo.texi(,1455) 
texinfo.texi(,1456) @example
texinfo.texi(,1457) @group
texinfo.texi(,1458) @@node First Chapter
texinfo.texi(,1459) @@chapter First Chapter
texinfo.texi(,1460) 
texinfo.texi(,1461) @@cindex chapter, first
texinfo.texi(,1462) @end group
texinfo.texi(,1463) 
texinfo.texi(,1464) @group
texinfo.texi(,1465) This is the first chapter.
texinfo.texi(,1466) @@cindex index entry, another
texinfo.texi(,1467) @end group
texinfo.texi(,1468) 
texinfo.texi(,1469) @group
texinfo.texi(,1470) Here is a numbered list.
texinfo.texi(,1471) 
texinfo.texi(,1472) @@enumerate
texinfo.texi(,1473) @@item
texinfo.texi(,1474) This is the first item.
texinfo.texi(,1475) 
texinfo.texi(,1476) @@item
texinfo.texi(,1477) This is the second item.
texinfo.texi(,1478) @@end enumerate
texinfo.texi(,1479) @end group
texinfo.texi(,1480) @end example
texinfo.texi(,1481) 
texinfo.texi(,1482) 
texinfo.texi(,1483) @subheading Part 6: The End of the Document
texinfo.texi(,1484) 
texinfo.texi(,1485) @noindent
texinfo.texi(,1486) The end segment contains commands for generating an index in a node and
texinfo.texi(,1487) unnumbered chapter of its own, and the @code{@@bye} command that marks
texinfo.texi(,1488) the end of the document.
texinfo.texi(,1489) 
texinfo.texi(,1490) @example
texinfo.texi(,1491) @group
texinfo.texi(,1492) @@node Index
texinfo.texi(,1493) @@unnumbered Index
texinfo.texi(,1494) @end group
texinfo.texi(,1495) 
texinfo.texi(,1496) @group
texinfo.texi(,1497) @@printindex cp
texinfo.texi(,1498) 
texinfo.texi(,1499) @@bye
texinfo.texi(,1500) @end group
texinfo.texi(,1501) @end example
texinfo.texi(,1502) 
texinfo.texi(,1503) 
texinfo.texi(,1504) @subheading Some Results
texinfo.texi(,1505) 
texinfo.texi(,1506) Here is what the contents of the first chapter of the sample look like:
texinfo.texi(,1507) 
texinfo.texi(,1508) @sp 1
texinfo.texi(,1509) @need 700
texinfo.texi(,1510) @quotation
texinfo.texi(,1511) This is the first chapter.
texinfo.texi(,1512) 
texinfo.texi(,1513) Here is a numbered list.
texinfo.texi(,1514) 
texinfo.texi(,1515) @enumerate
texinfo.texi(,1516) @item
texinfo.texi(,1517) This is the first item.
texinfo.texi(,1518) 
texinfo.texi(,1519) @item
texinfo.texi(,1520) This is the second item.
texinfo.texi(,1521) @end enumerate
texinfo.texi(,1522) @end quotation
texinfo.texi(,1523) 
texinfo.texi(,1524) 
texinfo.texi(,1525) @node History
texinfo.texi(,1526) @section History
texinfo.texi(,1527) 
texinfo.texi(,1528) @cindex Stallman, Richard M.
texinfo.texi(,1529) @cindex Chassell, Robert J.
texinfo.texi(,1530) @cindex Fox, Brian
texinfo.texi(,1531) @cindex Berry, Karl
texinfo.texi(,1532) Richard M.@: Stallman invented the Texinfo format, wrote the initial
texinfo.texi(,1533) processors, and created Edition 1.0 of this manual.  @w{Robert J.@:}
texinfo.texi(,1534) Chassell greatly revised and extended the manual, starting with Edition
texinfo.texi(,1535) 1.1.  Brian Fox was responsible for the standalone Texinfo distribution
texinfo.texi(,1536) until version 3.8, and wrote the standalone @command{makeinfo} and
texinfo.texi(,1537) @command{info} programs.  Karl Berry has continued maintenance since
texinfo.texi(,1538) Texinfo 3.8 (manual edition 2.22).
texinfo.texi(,1539) 
texinfo.texi(,1540) @cindex Pinard, Fran@,{c}ois
texinfo.texi(,1541) @cindex Zuhn, David D.
texinfo.texi(,1542) @cindex Weisshaus, Melissa
texinfo.texi(,1543) @cindex Zaretskii, Eli
texinfo.texi(,1544) @cindex Schwab, Andreas
texinfo.texi(,1545) @cindex Weinberg, Zack
texinfo.texi(,1546) Our thanks go out to all who helped improve this work, particularly the
texinfo.texi(,1547) indefatigable Eli Zaretskii and Andreas Schwab, who have provided
texinfo.texi(,1548) patches beyond counting.  Fran@,{c}ois Pinard and @w{David D.@: Zuhn},
texinfo.texi(,1549) tirelessly recorded and reported mistakes and obscurities.  Zack
texinfo.texi(,1550) Weinberg did the impossible by implementing the macro syntax in
texinfo.texi(,1551) @file{texinfo.tex}.  Special thanks go to Melissa Weisshaus for her
texinfo.texi(,1552) frequent reviews of nearly similar editions.  Dozens of others have
texinfo.texi(,1553) contributed patches and suggestions, they are gratefully acknowledged in
texinfo.texi(,1554) the @file{ChangeLog} file.  Our mistakes are our own.
texinfo.texi(,1555) 
texinfo.texi(,1556) @cindex Scribe
texinfo.texi(,1557) @cindex Reid, Brian
texinfo.texi(,1558) @cindex History of Texinfo
texinfo.texi(,1559) @cindex Texinfo history
texinfo.texi(,1560) A bit of history: in the 1970's at CMU, Brian Reid developed a program
texinfo.texi(,1561) and format named Scribe to mark up documents for printing.  It used the
texinfo.texi(,1562) @code{@@} character to introduce commands, as Texinfo does.  Much more
texinfo.texi(,1563) consequentially, it strived to describe document contents rather than
texinfo.texi(,1564) formatting, an idea wholeheartedly adopted by Texinfo.
texinfo.texi(,1565) 
texinfo.texi(,1566) @cindex Bolio
texinfo.texi(,1567) @cindex Bo@TeX{}
texinfo.texi(,1568) Meanwhile, people at MIT developed another, not too dissimilar format
texinfo.texi(,1569) called Bolio.  This then was converted to using @TeX{} as its typesetting
texinfo.texi(,1570) language: Bo@TeX{}.  The earliest Bo@TeX{} version seems to have been
texinfo.texi(,1571) 0.02 on October 31, 1984.
texinfo.texi(,1572) 
texinfo.texi(,1573) Bo@TeX{} could only be used as a markup language for documents to be
texinfo.texi(,1574) printed, not for online documents.  Richard Stallman (RMS) worked on
texinfo.texi(,1575) both Bolio and Bo@TeX{}.  He also developed a nifty on-line help format
texinfo.texi(,1576) called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
texinfo.texi(,1577) mark up language for text that is intended to be read both online and
texinfo.texi(,1578) as printed hard copy.
texinfo.texi(,1579) 
texinfo.texi(,1580) 
texinfo.texi(,1581) @node Texinfo Mode
texinfo.texi(,1582) @chapter Using Texinfo Mode
texinfo.texi(,1583) @cindex Texinfo mode
texinfo.texi(,1584) @cindex Mode, using Texinfo
texinfo.texi(,1585) @cindex GNU Emacs
texinfo.texi(,1586) @cindex Emacs
texinfo.texi(,1587) 
texinfo.texi(,1588) You may edit a Texinfo file with any text editor you choose.  A Texinfo
texinfo.texi(,1589) file is no different from any other @sc{ascii} file.  However, GNU Emacs
texinfo.texi(,1590) comes with a special mode, called Texinfo mode, that provides Emacs
texinfo.texi(,1591) commands and tools to help ease your work.
texinfo.texi(,1592) 
texinfo.texi(,1593) This chapter describes features of GNU Emacs' Texinfo mode but not any
texinfo.texi(,1594) features of the Texinfo formatting language.  So if you are reading this
texinfo.texi(,1595) manual straight through from the beginning, you may want to skim through
texinfo.texi(,1596) this chapter briefly and come back to it after reading succeeding
texinfo.texi(,1597) chapters which describe the Texinfo formatting language in detail.
texinfo.texi(,1598) 
texinfo.texi(,1599) @menu
texinfo.texi(,1600) * Texinfo Mode Overview::       How Texinfo mode can help you.
texinfo.texi(,1601) * Emacs Editing::               Texinfo mode adds to GNU Emacs' general
texinfo.texi(,1602)                                   purpose editing features.
texinfo.texi(,1603) * Inserting::                   How to insert frequently used @@-commands.
texinfo.texi(,1604) * Showing the Structure::       How to show the structure of a file.
texinfo.texi(,1605) * Updating Nodes and Menus::    How to update or create new nodes and menus.
texinfo.texi(,1606) * Info Formatting::             How to format for Info.
texinfo.texi(,1607) * Printing::                    How to format and print part or all of a file.
texinfo.texi(,1608) * Texinfo Mode Summary::        Summary of all the Texinfo mode commands.
texinfo.texi(,1609) @end menu
texinfo.texi(,1610) 
texinfo.texi(,1611) @node Texinfo Mode Overview, Emacs Editing, Texinfo Mode, Texinfo Mode
texinfo.texi(,1613) @heading Texinfo Mode Overview
texinfo.texi(,1615) 
texinfo.texi(,1616) Texinfo mode provides special features for working with Texinfo
texinfo.texi(,1617) files.
texinfo.texi(,1618) You can:@refill
texinfo.texi(,1619) 
texinfo.texi(,1620) @itemize @bullet
texinfo.texi(,1621) @item
texinfo.texi(,1622) Insert frequently used @@-commands. @refill
texinfo.texi(,1623) 
texinfo.texi(,1624) @item
texinfo.texi(,1625) Automatically create @code{@@node} lines.
texinfo.texi(,1626) 
texinfo.texi(,1627) @item
texinfo.texi(,1628) Show the structure of a Texinfo source file.@refill
texinfo.texi(,1629) 
texinfo.texi(,1630) @item
texinfo.texi(,1631) Automatically create or update the `Next',
texinfo.texi(,1632) `Previous', and `Up' pointers of a node.
texinfo.texi(,1633) 
texinfo.texi(,1634) @item
texinfo.texi(,1635) Automatically create or update menus.@refill
texinfo.texi(,1636) 
texinfo.texi(,1637) @item
texinfo.texi(,1638) Automatically create a master menu.@refill
texinfo.texi(,1639) 
texinfo.texi(,1640) @item
texinfo.texi(,1641) Format a part or all of a file for Info.@refill
texinfo.texi(,1642) 
texinfo.texi(,1643) @item
texinfo.texi(,1644) Typeset and print part or all of a file.@refill
texinfo.texi(,1645) @end itemize
texinfo.texi(,1646) 
texinfo.texi(,1647) Perhaps the two most helpful features are those for inserting frequently
texinfo.texi(,1648) used @@-commands and for creating node pointers and menus.@refill
texinfo.texi(,1649) 
texinfo.texi(,1650) @node Emacs Editing, Inserting, Texinfo Mode Overview, Texinfo Mode
texinfo.texi(,1651) @section The Usual GNU Emacs Editing Commands
texinfo.texi(,1652) 
texinfo.texi(,1653) In most cases, the usual Text mode commands work the same in Texinfo
texinfo.texi(,1654) mode as they do in Text mode.  Texinfo mode adds new editing commands
texinfo.texi(,1655) and tools to GNU Emacs' general purpose editing features.  The major
texinfo.texi(,1656) difference concerns filling.  In Texinfo mode, the paragraph
texinfo.texi(,1657) separation variable and syntax table are redefined so that Texinfo
texinfo.texi(,1658) commands that should be on lines of their own are not inadvertently
texinfo.texi(,1659) included in paragraphs.  Thus, the @kbd{M-q} (@code{fill-paragraph})
texinfo.texi(,1660) command will refill a paragraph but not mix an indexing command on a
texinfo.texi(,1661) line adjacent to it into the paragraph.@refill
texinfo.texi(,1662) 
texinfo.texi(,1663) In addition, Texinfo mode sets the @code{page-delimiter} variable to
texinfo.texi(,1664) the value of @code{texinfo-chapter-level-regexp}; by default, this is
texinfo.texi(,1665) a regular expression matching the commands for chapters and their
texinfo.texi(,1666) equivalents, such as appendices.  With this value for the page
texinfo.texi(,1667) delimiter, you can jump from chapter title to chapter title with the
texinfo.texi(,1668) @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
texinfo.texi(,1669) (@code{backward-page}) commands and narrow to a chapter with the
texinfo.texi(,1670) @kbd{C-x p} (@code{narrow-to-page}) command.  (@xref{Pages, , ,emacs,
texinfo.texi(,1671) The GNU Emacs Manual}, for details about the page commands.)@refill
texinfo.texi(,1672) 
texinfo.texi(,1673) You may name a Texinfo file however you wish, but the convention is to
texinfo.texi(,1674) end a Texinfo file name with one of the extensions
texinfo.texi(,1675) @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}.  A longer
texinfo.texi(,1676) extension is preferred, since it is explicit, but a shorter extension
texinfo.texi(,1677) may be necessary for operating systems that limit the length of file
texinfo.texi(,1678) names.  GNU Emacs automatically enters Texinfo mode when you visit a
texinfo.texi(,1679) file with a @file{.texinfo}, @file{.texi} or @file{.txi}
texinfo.texi(,1680) extension.  Also, Emacs switches to Texinfo mode
texinfo.texi(,1681) when you visit a
texinfo.texi(,1682) file that has @samp{-*-texinfo-*-} in its first line.  If ever you are
texinfo.texi(,1683) in another mode and wish to switch to Texinfo mode, type @code{M-x
texinfo.texi(,1684) texinfo-mode}.@refill
texinfo.texi(,1685) 
texinfo.texi(,1686) Like all other Emacs features, you can customize or enhance Texinfo
texinfo.texi(,1687) mode as you wish.  In particular, the keybindings are very easy to
texinfo.texi(,1688) change.  The keybindings described here are the default or standard
texinfo.texi(,1689) ones.@refill
texinfo.texi(,1690) 
texinfo.texi(,1691) @node Inserting, Showing the Structure, Emacs Editing, Texinfo Mode
texinfo.texi(,1692) @comment  node-name,  next,  previous,  up
texinfo.texi(,1693) @section Inserting Frequently Used Commands
texinfo.texi(,1694) @cindex Inserting frequently used commands
texinfo.texi(,1695) @cindex Frequently used commands, inserting
texinfo.texi(,1696) @cindex Commands, inserting them
texinfo.texi(,1697) 
texinfo.texi(,1698) Texinfo mode provides commands to insert various frequently used
texinfo.texi(,1699) @@-commands into the buffer.  You can use these commands to save
texinfo.texi(,1700) keystrokes.@refill
texinfo.texi(,1701) 
texinfo.texi(,1702) The insert commands are invoked by typing @kbd{C-c} twice and then the
texinfo.texi(,1703) first letter of the @@-command:@refill
texinfo.texi(,1704) 
texinfo.texi(,1705) @table @kbd
texinfo.texi(,1706) @item  C-c C-c c
texinfo.texi(,1707) @itemx M-x texinfo-insert-@@code
texinfo.texi(,1708) @findex texinfo-insert-@@code
texinfo.texi(,1709) Insert @code{@@code@{@}} and put the
texinfo.texi(,1710) cursor between the braces.@refill
texinfo.texi(,1711) 
texinfo.texi(,1712) @item  C-c C-c d
texinfo.texi(,1713) @itemx M-x texinfo-insert-@@dfn
texinfo.texi(,1714) @findex texinfo-insert-@@dfn
texinfo.texi(,1715) Insert @code{@@dfn@{@}} and put the
texinfo.texi(,1716) cursor between the braces.@refill
texinfo.texi(,1717) 
texinfo.texi(,1718) @item  C-c C-c e
texinfo.texi(,1719) @itemx M-x texinfo-insert-@@end
texinfo.texi(,1720) @findex texinfo-insert-@@end
texinfo.texi(,1721) Insert @code{@@end} and attempt to insert the correct following word,
texinfo.texi(,1722) such as @samp{example} or @samp{table}.  (This command does not handle
texinfo.texi(,1723) nested lists correctly, but inserts the word appropriate to the
texinfo.texi(,1724) immediately preceding list.)@refill
texinfo.texi(,1725) 
texinfo.texi(,1726) @item  C-c C-c i
texinfo.texi(,1727) @itemx M-x texinfo-insert-@@item
texinfo.texi(,1728) @findex texinfo-insert-@@item
texinfo.texi(,1729) Insert @code{@@item} and put the
texinfo.texi(,1730) cursor at the beginning of the next line.@refill
texinfo.texi(,1731) 
texinfo.texi(,1732) @item  C-c C-c k
texinfo.texi(,1733) @itemx M-x texinfo-insert-@@kbd
texinfo.texi(,1734) @findex texinfo-insert-@@kbd
texinfo.texi(,1735) Insert @code{@@kbd@{@}} and put the
texinfo.texi(,1736) cursor between the braces.@refill
texinfo.texi(,1737) 
texinfo.texi(,1738) @item  C-c C-c n
texinfo.texi(,1739) @itemx M-x texinfo-insert-@@node
texinfo.texi(,1740) @findex texinfo-insert-@@node
texinfo.texi(,1741) Insert @code{@@node} and a comment line
texinfo.texi(,1742) listing the sequence for the `Next',
texinfo.texi(,1743) `Previous', and `Up' nodes.
texinfo.texi(,1744) Leave point after the @code{@@node}.@refill
texinfo.texi(,1745) 
texinfo.texi(,1746) @item  C-c C-c o
texinfo.texi(,1747) @itemx M-x texinfo-insert-@@noindent
texinfo.texi(,1748) @findex texinfo-insert-@@noindent
texinfo.texi(,1749) Insert @code{@@noindent} and put the
texinfo.texi(,1750) cursor at the beginning of the next line.@refill
texinfo.texi(,1751) 
texinfo.texi(,1752) @item  C-c C-c s
texinfo.texi(,1753) @itemx M-x texinfo-insert-@@samp
texinfo.texi(,1754) @findex texinfo-insert-@@samp
texinfo.texi(,1755) Insert @code{@@samp@{@}} and put the
texinfo.texi(,1756) cursor between the braces.@refill
texinfo.texi(,1757) 
texinfo.texi(,1758) @item  C-c C-c t
texinfo.texi(,1759) @itemx M-x texinfo-insert-@@table
texinfo.texi(,1760) @findex texinfo-insert-@@table
texinfo.texi(,1761) Insert @code{@@table} followed by a @key{SPC}
texinfo.texi(,1762) and leave the cursor after the @key{SPC}.@refill
texinfo.texi(,1763) 
texinfo.texi(,1764) @item  C-c C-c v
texinfo.texi(,1765) @itemx M-x texinfo-insert-@@var
texinfo.texi(,1766) @findex texinfo-insert-@@var
texinfo.texi(,1767) Insert @code{@@var@{@}} and put the
texinfo.texi(,1768) cursor between the braces.@refill
texinfo.texi(,1769) 
texinfo.texi(,1770) @item  C-c C-c x
texinfo.texi(,1771) @itemx M-x texinfo-insert-@@example
texinfo.texi(,1772) @findex texinfo-insert-@@example
texinfo.texi(,1773) Insert @code{@@example} and put the
texinfo.texi(,1774) cursor at the beginning of the next line.@refill
texinfo.texi(,1775) 
texinfo.texi(,1776) @c M-@{  was the binding for texinfo-insert-braces;
texinfo.texi(,1777) @c in Emacs 19, backward-paragraph will take this binding.
texinfo.texi(,1778) @item C-c C-c @{
texinfo.texi(,1779) @itemx M-x texinfo-insert-braces
texinfo.texi(,1780) @findex texinfo-insert-braces
texinfo.texi(,1781) Insert @code{@{@}} and put the cursor between the braces.@refill
texinfo.texi(,1782) 
texinfo.texi(,1783) @item C-c C-c @}
texinfo.texi(,1784) @itemx C-c C-c ]
texinfo.texi(,1785) @itemx M-x up-list
texinfo.texi(,1786) @findex up-list
texinfo.texi(,1787) Move from between a pair of braces forward past the closing brace.
texinfo.texi(,1788) Typing @kbd{C-c C-c ]} is easier than typing @kbd{C-c C-c @}}, which
texinfo.texi(,1789) is, however, more mnemonic; hence the two keybindings.  (Also, you can
texinfo.texi(,1790) move out from between braces by typing @kbd{C-f}.)@refill
texinfo.texi(,1791) @end table
texinfo.texi(,1792) 
texinfo.texi(,1793) To put a command such as @w{@code{@@code@{@dots{}@}}} around an
texinfo.texi(,1794) @emph{existing} word, position the cursor in front of the word and type
texinfo.texi(,1795) @kbd{C-u 1 C-c C-c c}.  This makes it easy to edit existing plain text.
texinfo.texi(,1796) The value of the prefix argument tells Emacs how many words following
texinfo.texi(,1797) point to include between braces---@samp{1} for one word, @samp{2} for
texinfo.texi(,1798) two words, and so on.  Use a negative argument to enclose the previous
texinfo.texi(,1799) word or words.  If you do not specify a prefix argument, Emacs inserts
texinfo.texi(,1800) the @@-command string and positions the cursor between the braces.  This
texinfo.texi(,1801) feature works only for those @@-commands that operate on a word or words
texinfo.texi(,1802) within one line, such as @code{@@kbd} and @code{@@var}.@refill
texinfo.texi(,1803) 
texinfo.texi(,1804) This set of insert commands was created after analyzing the frequency
texinfo.texi(,1805) with which different @@-commands are used in the @cite{GNU Emacs
texinfo.texi(,1806) Manual} and the @cite{GDB Manual}.  If you wish to add your own insert
texinfo.texi(,1807) commands, you can bind a keyboard macro to a key, use abbreviations,
texinfo.texi(,1808) or extend the code in @file{texinfo.el}.@refill
texinfo.texi(,1809) 
texinfo.texi(,1810) @findex texinfo-start-menu-description
texinfo.texi(,1811) @cindex Menu description, start
texinfo.texi(,1812) @cindex Description for menu, start
texinfo.texi(,1813) @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
texinfo.texi(,1814) command that works differently from the other insert commands.  It
texinfo.texi(,1815) inserts a node's section or chapter title in the space for the
texinfo.texi(,1816) description in a menu entry line.  (A menu entry has three parts, the
texinfo.texi(,1817) entry name, the node name, and the description.  Only the node name is
texinfo.texi(,1818) required, but a description helps explain what the node is about.
texinfo.texi(,1819) @xref{Menu Parts, , The Parts of a Menu}.)@refill
texinfo.texi(,1820) 
texinfo.texi(,1821) To use @code{texinfo-start-menu-description}, position point in a menu
texinfo.texi(,1822) entry line and type @kbd{C-c C-c C-d}.  The command looks for and copies
texinfo.texi(,1823) the title that goes with the node name, and inserts the title as a
texinfo.texi(,1824) description; it positions point at beginning of the inserted text so you
texinfo.texi(,1825) can edit it.  The function does not insert the title if the menu entry
texinfo.texi(,1826) line already contains a description.@refill
texinfo.texi(,1827) 
texinfo.texi(,1828) This command is only an aid to writing descriptions; it does not do the
texinfo.texi(,1829) whole job.  You must edit the inserted text since a title tends to use
texinfo.texi(,1830) the same words as a node name but a useful description uses different
texinfo.texi(,1831) words.@refill
texinfo.texi(,1832) 
texinfo.texi(,1833) @node Showing the Structure, Updating Nodes and Menus, Inserting, Texinfo Mode
texinfo.texi(,1834) @comment  node-name,  next,  previous,  up
texinfo.texi(,1835) @section Showing the Section Structure of a File
texinfo.texi(,1836) @cindex Showing the section structure of a file
texinfo.texi(,1837) @cindex Section structure of a file, showing it
texinfo.texi(,1838) @cindex Structure of a file, showing it
texinfo.texi(,1839) @cindex Outline of file structure, showing it
texinfo.texi(,1840) @cindex Contents-like outline of file structure
texinfo.texi(,1841) @cindex File section structure, showing it
texinfo.texi(,1842) @cindex Texinfo file section structure, showing it
texinfo.texi(,1843) 
texinfo.texi(,1844) You can show the section structure of a Texinfo file by using the
texinfo.texi(,1845) @kbd{C-c C-s} command (@code{texinfo-show-structure}).  This command
texinfo.texi(,1846) shows the section structure of a Texinfo file by listing the lines
texinfo.texi(,1847) that begin with the @@-commands for @code{@@chapter},
texinfo.texi(,1848) @code{@@section}, and the like.  It constructs what amounts
texinfo.texi(,1849) to a table of contents.  These lines are displayed in another buffer
texinfo.texi(,1850) called the @samp{*Occur*} buffer.  In that buffer, you can position
texinfo.texi(,1851) the cursor over one of the lines and use the @kbd{C-c C-c} command
texinfo.texi(,1852) (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
texinfo.texi(,1853) in the Texinfo file.@refill
texinfo.texi(,1854) 
texinfo.texi(,1855) @table @kbd
texinfo.texi(,1856) @item  C-c C-s
texinfo.texi(,1857) @itemx M-x texinfo-show-structure
texinfo.texi(,1858) @findex texinfo-show-structure
texinfo.texi(,1859) Show the @code{@@chapter}, @code{@@section}, and such lines of a
texinfo.texi(,1860) Texinfo file.@refill
texinfo.texi(,1861) 
texinfo.texi(,1862) @item  C-c C-c
texinfo.texi(,1863) @itemx M-x occur-mode-goto-occurrence
texinfo.texi(,1864) @findex occur-mode-goto-occurrence
texinfo.texi(,1865) Go to the line in the Texinfo file corresponding to the line under the
texinfo.texi(,1866) cursor in the @file{*Occur*} buffer.@refill
texinfo.texi(,1867) @end table
texinfo.texi(,1868) 
texinfo.texi(,1869) If you call @code{texinfo-show-structure} with a prefix argument by
texinfo.texi(,1870) typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
texinfo.texi(,1871) @@-commands for @code{@@chapter}, @code{@@section}, and the like, but
texinfo.texi(,1872) also the @code{@@node} lines.  You can use @code{texinfo-show-structure}
texinfo.texi(,1873) with a prefix argument to check whether the `Next', `Previous', and `Up'
texinfo.texi(,1874) pointers of an @code{@@node} line are correct.
texinfo.texi(,1875) 
texinfo.texi(,1876) Often, when you are working on a manual, you will be interested only
texinfo.texi(,1877) in the structure of the current chapter.  In this case, you can mark
texinfo.texi(,1878) off the region of the buffer that you are interested in by using the
texinfo.texi(,1879) @kbd{C-x n n} (@code{narrow-to-region}) command and
texinfo.texi(,1880) @code{texinfo-show-structure} will work on only that region.  To see
texinfo.texi(,1881) the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
texinfo.texi(,1882) (@xref{Narrowing, , , emacs, The GNU Emacs Manual}, for more
texinfo.texi(,1883) information about the narrowing commands.)@refill
texinfo.texi(,1884) 
texinfo.texi(,1885) @vindex page-delimiter
texinfo.texi(,1886) @cindex Page delimiter in Texinfo mode
texinfo.texi(,1887) In addition to providing the @code{texinfo-show-structure} command,
texinfo.texi(,1888) Texinfo mode sets the value of the page delimiter variable to match
texinfo.texi(,1889) the chapter-level @@-commands.  This enables you to use the @kbd{C-x
texinfo.texi(,1890) ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
texinfo.texi(,1891) commands to move forward and backward by chapter, and to use the
texinfo.texi(,1892) @kbd{C-x p} (@code{narrow-to-page}) command to narrow to a chapter.
texinfo.texi(,1893) @xref{Pages, , , emacs, The GNU Emacs Manual}, for more information
texinfo.texi(,1894) about the page commands.@refill
texinfo.texi(,1895) 
texinfo.texi(,1896) @node Updating Nodes and Menus, Info Formatting, Showing the Structure, Texinfo Mode
texinfo.texi(,1897) @comment  node-name,  next,  previous,  up
texinfo.texi(,1898) @section Updating Nodes and Menus
texinfo.texi(,1899) @cindex Updating nodes and menus
texinfo.texi(,1900) @cindex Create nodes, menus automatically
texinfo.texi(,1901) @cindex Insert nodes, menus automatically
texinfo.texi(,1902) @cindex Automatically insert nodes, menus
texinfo.texi(,1903) 
texinfo.texi(,1904) Texinfo mode provides commands for automatically creating or updating
texinfo.texi(,1905) menus and node pointers.  The commands are called ``update'' commands
texinfo.texi(,1906) because their most frequent use is for updating a Texinfo file after you
texinfo.texi(,1907) have worked on it; but you can use them to insert the `Next',
texinfo.texi(,1908) `Previous', and `Up' pointers into an @code{@@node} line that has none
texinfo.texi(,1909) and to create menus in a file that has none.
texinfo.texi(,1910) 
texinfo.texi(,1911) If you do not use the updating commands, you need to write menus and
texinfo.texi(,1912) node pointers by hand, which is a tedious task.@refill
texinfo.texi(,1913) 
texinfo.texi(,1914) @menu
texinfo.texi(,1915) * Updating Commands::           Five major updating commands.
texinfo.texi(,1916) * Updating Requirements::       How to structure a Texinfo file for
texinfo.texi(,1917)                                   using the updating command.
texinfo.texi(,1918) * Other Updating Commands::     How to indent descriptions, insert
texinfo.texi(,1919)                                   missing nodes lines, and update
texinfo.texi(,1920)                                   nodes in sequence.
texinfo.texi(,1921) @end menu
texinfo.texi(,1922) 
texinfo.texi(,1923) @node Updating Commands, Updating Requirements, Updating Nodes and Menus, Updating Nodes and Menus
texinfo.texi(,1925) @subheading The Updating Commands
texinfo.texi(,1927) 
texinfo.texi(,1928) You can use the updating commands to:@refill
texinfo.texi(,1929) 
texinfo.texi(,1930) @itemize @bullet
texinfo.texi(,1931) @item
texinfo.texi(,1932) insert or update the `Next', `Previous', and `Up' pointers of a
texinfo.texi(,1933) node,@refill
texinfo.texi(,1934) 
texinfo.texi(,1935) @item
texinfo.texi(,1936) insert or update the menu for a section, and@refill
texinfo.texi(,1937) 
texinfo.texi(,1938) @item
texinfo.texi(,1939) create a master menu for a Texinfo source file.@refill
texinfo.texi(,1940) @end itemize
texinfo.texi(,1941) 
texinfo.texi(,1942) You can also use the commands to update all the nodes and menus in a
texinfo.texi(,1943) region or in a whole Texinfo file.@refill
texinfo.texi(,1944) 
texinfo.texi(,1945) The updating commands work only with conventional Texinfo files, which
texinfo.texi(,1946) are structured hierarchically like books.  In such files, a structuring
texinfo.texi(,1947) command line must follow closely after each @code{@@node} line, except
texinfo.texi(,1948) for the `Top' @code{@@node} line.  (A @dfn{structuring command line} is
texinfo.texi(,1949) a line beginning with @code{@@chapter}, @code{@@section}, or other
texinfo.texi(,1950) similar command.)
texinfo.texi(,1951) 
texinfo.texi(,1952) You can write the structuring command line on the line that follows
texinfo.texi(,1953) immediately after an @code{@@node} line or else on the line that
texinfo.texi(,1954) follows after a single @code{@@comment} line or a single
texinfo.texi(,1955) @code{@@ifinfo} line.  You cannot interpose more than one line between
texinfo.texi(,1956) the @code{@@node} line and the structuring command line; and you may
texinfo.texi(,1957) interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
texinfo.texi(,1958) 
texinfo.texi(,1959) Commands which work on a whole buffer require that the `Top' node be
texinfo.texi(,1960) followed by a node with an @code{@@chapter} or equivalent-level command.
texinfo.texi(,1961) The menu updating commands will not create a main or master menu for a
texinfo.texi(,1962) Texinfo file that has only @code{@@chapter}-level nodes!  The menu
texinfo.texi(,1963) updating commands only create menus @emph{within} nodes for lower level
texinfo.texi(,1964) nodes.  To create a menu of chapters, you must provide a `Top'
texinfo.texi(,1965) node.
texinfo.texi(,1966) 
texinfo.texi(,1967) The menu updating commands remove menu entries that refer to other Info
texinfo.texi(,1968) files since they do not refer to nodes within the current buffer.  This
texinfo.texi(,1969) is a deficiency.  Rather than use menu entries, you can use cross
texinfo.texi(,1970) references to refer to other Info files.  None of the updating commands
texinfo.texi(,1971) affect cross references.@refill
texinfo.texi(,1972) 
texinfo.texi(,1973) Texinfo mode has five updating commands that are used most often: two
texinfo.texi(,1974) are for updating the node pointers or menu of a single node (or a
texinfo.texi(,1975) region); two are for updating every node pointer and menu in a file;
texinfo.texi(,1976) and one, the @code{texinfo-master-menu} command, is for creating a
texinfo.texi(,1977) master menu for a complete file, and optionally, for updating every
texinfo.texi(,1978) node and menu in the whole Texinfo file.@refill
texinfo.texi(,1979) 
texinfo.texi(,1980) The @code{texinfo-master-menu} command is the primary command:@refill
texinfo.texi(,1981) 
texinfo.texi(,1982) @table @kbd
texinfo.texi(,1983) @item C-c C-u m
texinfo.texi(,1984) @itemx M-x texinfo-master-menu
texinfo.texi(,1985) @findex texinfo-master-menu
texinfo.texi(,1986) Create or update a master menu that includes all the other menus
texinfo.texi(,1987) (incorporating the descriptions from pre-existing menus, if
texinfo.texi(,1988) any).@refill
texinfo.texi(,1989) 
texinfo.texi(,1990) With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
texinfo.texi(,1991) update all the nodes and all the regular menus in the buffer before
texinfo.texi(,1992) constructing the master menu.  (@xref{The Top Node, , The Top Node and
texinfo.texi(,1993) Master Menu}, for more about a master menu.)@refill
texinfo.texi(,1994) 
texinfo.texi(,1995) For @code{texinfo-master-menu} to work, the Texinfo file must have a
texinfo.texi(,1996) `Top' node and at least one subsequent node.@refill
texinfo.texi(,1997) 
texinfo.texi(,1998) After extensively editing a Texinfo file, you can type the following:
texinfo.texi(,1999) 
texinfo.texi(,2000) @example
texinfo.texi(,2001) C-u M-x texinfo-master-menu
texinfo.texi(,2002) @exdent or
texinfo.texi(,2003) C-u C-c C-u m
texinfo.texi(,2004) @end example
texinfo.texi(,2005) 
texinfo.texi(,2006) @noindent
texinfo.texi(,2007) This updates all the nodes and menus completely and all at once.@refill
texinfo.texi(,2008) @end table
texinfo.texi(,2009) 
texinfo.texi(,2010) The other major updating commands do smaller jobs and are designed for
texinfo.texi(,2011) the person who updates nodes and menus as he or she writes a Texinfo
texinfo.texi(,2012) file.@refill
texinfo.texi(,2013) 
texinfo.texi(,2014) @need 1000
texinfo.texi(,2015) The commands are:@refill
texinfo.texi(,2016) 
texinfo.texi(,2017) @table @kbd
texinfo.texi(,2018) @item C-c C-u C-n
texinfo.texi(,2019) @itemx M-x texinfo-update-node
texinfo.texi(,2020) @findex texinfo-update-node
texinfo.texi(,2021) Insert the `Next', `Previous', and `Up' pointers for the node that point is
texinfo.texi(,2022) within (i.e., for the @code{@@node} line preceding point).  If the
texinfo.texi(,2023) @code{@@node} line has pre-existing `Next', `Previous', or `Up'
texinfo.texi(,2024) pointers in it, the old pointers are removed and new ones inserted.
texinfo.texi(,2025) With an argument (prefix argument, @kbd{C-u}, if interactive), this command
texinfo.texi(,2026) updates all @code{@@node} lines in the region (which is the text
texinfo.texi(,2027) between point and mark).@refill
texinfo.texi(,2028) 
texinfo.texi(,2029) @item C-c C-u C-m
texinfo.texi(,2030) @itemx M-x texinfo-make-menu
texinfo.texi(,2031) @findex texinfo-make-menu
texinfo.texi(,2032) Create or update the menu in the node that point is within.
texinfo.texi(,2033) With an argument (@kbd{C-u} as prefix argument, if
texinfo.texi(,2034) interactive), the command makes or updates menus for the
texinfo.texi(,2035) nodes which are either within or a part of the
texinfo.texi(,2036) region.@refill
texinfo.texi(,2037) 
texinfo.texi(,2038) Whenever @code{texinfo-make-menu} updates an existing menu, the
texinfo.texi(,2039) descriptions from that menu are incorporated into the new menu.  This
texinfo.texi(,2040) is done by copying descriptions from the existing menu to the entries
texinfo.texi(,2041) in the new menu that have the same node names.  If the node names are
texinfo.texi(,2042) different, the descriptions are not copied to the new menu.@refill
texinfo.texi(,2043) 
texinfo.texi(,2044) @item C-c C-u C-e
texinfo.texi(,2045) @itemx M-x texinfo-every-node-update
texinfo.texi(,2046) @findex texinfo-every-node-update
texinfo.texi(,2047) Insert or update the `Next', `Previous', and `Up' pointers for every
texinfo.texi(,2048) node in the buffer.@refill
texinfo.texi(,2049) 
texinfo.texi(,2050) @item C-c C-u C-a
texinfo.texi(,2051) @itemx M-x texinfo-all-menus-update
texinfo.texi(,2052) @findex texinfo-all-menus-update
texinfo.texi(,2053) Create or update all the menus in the buffer.  With an argument
texinfo.texi(,2054) (@kbd{C-u} as prefix argument, if interactive), first insert
texinfo.texi(,2055) or update all the node
texinfo.texi(,2056) pointers before working on the menus.@refill
texinfo.texi(,2057) 
texinfo.texi(,2058) If a master menu exists, the @code{texinfo-all-menus-update} command
texinfo.texi(,2059) updates it; but the command does not create a new master menu if none
texinfo.texi(,2060) already exists.  (Use the @code{texinfo-master-menu} command for
texinfo.texi(,2061) that.)@refill
texinfo.texi(,2062) 
texinfo.texi(,2063) When working on a document that does not merit a master menu, you can
texinfo.texi(,2064) type the following:
texinfo.texi(,2065) 
texinfo.texi(,2066) @example
texinfo.texi(,2067) C-u C-c C-u C-a
texinfo.texi(,2068) @exdent or
texinfo.texi(,2069) C-u M-x texinfo-all-menus-update
texinfo.texi(,2070) @end example
texinfo.texi(,2071) 
texinfo.texi(,2072) @noindent
texinfo.texi(,2073) This updates all the nodes and menus.@refill
texinfo.texi(,2074) @end table
texinfo.texi(,2075) 
texinfo.texi(,2076) The @code{texinfo-column-for-description} variable specifies the
texinfo.texi(,2077) column to which menu descriptions are indented.  By default, the value
texinfo.texi(,2078) is 32 although it is often useful to reduce it to as low as 24.  You
texinfo.texi(,2079) can set the variable with the @kbd{M-x edit-options} command
texinfo.texi(,2080) (@pxref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs
texinfo.texi(,2081) Manual}) or with the @kbd{M-x set-variable} command (@pxref{Examining,
texinfo.texi(,2082) , Examining and Setting Variables, emacs, The GNU Emacs
texinfo.texi(,2083) Manual}).@refill
texinfo.texi(,2084) 
texinfo.texi(,2085) Also, the @code{texinfo-indent-menu-description} command may be used to
texinfo.texi(,2086) indent existing menu descriptions to a specified column.  Finally, if
texinfo.texi(,2087) you wish, you can use the @code{texinfo-insert-node-lines} command to
texinfo.texi(,2088) insert missing @code{@@node} lines into a file.  (@xref{Other Updating
texinfo.texi(,2089) Commands}, for more information.)@refill
texinfo.texi(,2090) 
texinfo.texi(,2091) @node Updating Requirements
texinfo.texi(,2092) @subsection Updating Requirements
texinfo.texi(,2093) @cindex Updating requirements
texinfo.texi(,2094) @cindex Requirements for updating commands
texinfo.texi(,2095) 
texinfo.texi(,2096) To use the updating commands, you must organize the Texinfo file
texinfo.texi(,2097) hierarchically with chapters, sections, subsections, and the like.
texinfo.texi(,2098) When you construct the hierarchy of the manual, do not `jump down'
texinfo.texi(,2099) more than one level at a time: you can follow the `Top' node with a
texinfo.texi(,2100) chapter, but not with a section; you can follow a chapter with a
texinfo.texi(,2101) section, but not with a subsection.  However, you may `jump up' any
texinfo.texi(,2102) number of levels at one time---for example, from a subsection to a
texinfo.texi(,2103) chapter.@refill
texinfo.texi(,2104) 
texinfo.texi(,2105) Each @code{@@node} line, with the exception of the line for the `Top'
texinfo.texi(,2106) node, must be followed by a line with a structuring command such as
texinfo.texi(,2107) @code{@@chapter}, @code{@@section}, or
texinfo.texi(,2108) @code{@@unnumberedsubsec}.@refill
texinfo.texi(,2109) 
texinfo.texi(,2110) Each @code{@@node} line/structuring-command line combination
texinfo.texi(,2111) must look either like this:
texinfo.texi(,2112) 
texinfo.texi(,2113) @example
texinfo.texi(,2114) @group
texinfo.texi(,2115) @@node     Comments,  Minimum, Conventions, Overview
texinfo.texi(,2116) @@comment  node-name, next,    previous,    up
texinfo.texi(,2117) @@section Comments
texinfo.texi(,2118) @end group
texinfo.texi(,2119) @end example
texinfo.texi(,2120) 
texinfo.texi(,2121) or like this (without the @code{@@comment} line):
texinfo.texi(,2122) 
texinfo.texi(,2123) @example
texinfo.texi(,2124) @group
texinfo.texi(,2125) @@node Comments, Minimum, Conventions, Overview
texinfo.texi(,2126) @@section Comments
texinfo.texi(,2127) @end group
texinfo.texi(,2128) @end example
texinfo.texi(,2129) 
texinfo.texi(,2130) or like this (without the explicit node pointers):
texinfo.texi(,2131) 
texinfo.texi(,2132) @example
texinfo.texi(,2133) @group
texinfo.texi(,2134) @@node Comments
texinfo.texi(,2135) @@section Comments
texinfo.texi(,2136) @end group
texinfo.texi(,2137) @end example
texinfo.texi(,2138) 
texinfo.texi(,2139) @noindent
texinfo.texi(,2140) In this example, `Comments' is the name of both the node and the
texinfo.texi(,2141) section.  The next node is called `Minimum' and the previous node is
texinfo.texi(,2142) called `Conventions'.  The `Comments' section is within the `Overview'
texinfo.texi(,2143) node, which is specified by the `Up' pointer.  (Instead of an
texinfo.texi(,2144) @code{@@comment} line, you may also write an @code{@@ifinfo} line.)
texinfo.texi(,2145) 
texinfo.texi(,2146) If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
texinfo.texi(,2147) and be the first node in the file.
texinfo.texi(,2148) 
texinfo.texi(,2149) The menu updating commands create a menu of sections within a chapter,
texinfo.texi(,2150) a menu of subsections within a section, and so on.  This means that
texinfo.texi(,2151) you must have a `Top' node if you want a menu of chapters.@refill
texinfo.texi(,2152) 
texinfo.texi(,2153) Incidentally, the @code{makeinfo} command will create an Info file for a
texinfo.texi(,2154) hierarchically organized Texinfo file that lacks `Next', `Previous' and
texinfo.texi(,2155) `Up' pointers.  Thus, if you can be sure that your Texinfo file will be
texinfo.texi(,2156) formatted with @code{makeinfo}, you have no need for the update node
texinfo.texi(,2157) commands.  (@xref{Creating an Info File}, for more information about
texinfo.texi(,2158) @code{makeinfo}.)  However, both @code{makeinfo} and the
texinfo.texi(,2159) @code{texinfo-format-@dots{}} commands require that you insert menus in
texinfo.texi(,2160) the file.
texinfo.texi(,2161) 
texinfo.texi(,2162) 
texinfo.texi(,2163) @node Other Updating Commands
texinfo.texi(,2164) @subsection Other Updating Commands
texinfo.texi(,2165) 
texinfo.texi(,2166) In addition to the five major updating commands, Texinfo mode
texinfo.texi(,2167) possesses several less frequently used updating commands:@refill
texinfo.texi(,2168) 
texinfo.texi(,2169) @table @kbd
texinfo.texi(,2170) @item M-x texinfo-insert-node-lines
texinfo.texi(,2171) @findex texinfo-insert-node-lines
texinfo.texi(,2172) Insert @code{@@node} lines before the @code{@@chapter},
texinfo.texi(,2173) @code{@@section}, and other sectioning commands wherever they are
texinfo.texi(,2174) missing throughout a region in a Texinfo file.@refill
texinfo.texi(,2175) 
texinfo.texi(,2176) With an argument (@kbd{C-u} as prefix argument, if interactive), the
texinfo.texi(,2177) @code{texinfo-insert-node-lines} command not only inserts
texinfo.texi(,2178) @code{@@node} lines but also inserts the chapter or section titles as
texinfo.texi(,2179) the names of the corresponding nodes.  In addition, it inserts the
texinfo.texi(,2180) titles as node names in pre-existing @code{@@node} lines that lack
texinfo.texi(,2181) names.  Since node names should be more concise than section or
texinfo.texi(,2182) chapter titles, you must manually edit node names so inserted.@refill
texinfo.texi(,2183) 
texinfo.texi(,2184) For example, the following marks a whole buffer as a region and inserts
texinfo.texi(,2185) @code{@@node} lines and titles throughout:@refill
texinfo.texi(,2186) 
texinfo.texi(,2187) @example
texinfo.texi(,2188) C-x h C-u M-x texinfo-insert-node-lines
texinfo.texi(,2189) @end example
texinfo.texi(,2190) 
texinfo.texi(,2191) This command inserts titles as node names in @code{@@node} lines; the
texinfo.texi(,2192) @code{texinfo-start-menu-description} command (@pxref{Inserting,
texinfo.texi(,2193) Inserting Frequently Used Commands}) inserts titles as descriptions in
texinfo.texi(,2194) menu entries, a different action.  However, in both cases, you need to
texinfo.texi(,2195) edit the inserted text.
texinfo.texi(,2196) 
texinfo.texi(,2197) @item M-x texinfo-multiple-files-update
texinfo.texi(,2198) @findex texinfo-multiple-files-update @r{(in brief)}
texinfo.texi(,2199) Update nodes and menus in a document built from several separate files.
texinfo.texi(,2200) With @kbd{C-u} as a prefix argument, create and insert a master menu in
texinfo.texi(,2201) the outer file.  With a numeric prefix argument, such as @kbd{C-u 2}, first
texinfo.texi(,2202) update all the menus and all the `Next', `Previous', and `Up' pointers
texinfo.texi(,2203) of all the included files before creating and inserting a master menu in
texinfo.texi(,2204) the outer file.  The @code{texinfo-multiple-files-update} command is
texinfo.texi(,2205) described in the appendix on @code{@@include} files.
texinfo.texi(,2207) @xref{texinfo-multiple-files-update}.@refill
texinfo.texi(,2213) 
texinfo.texi(,2214) @item M-x texinfo-indent-menu-description
texinfo.texi(,2215) @findex texinfo-indent-menu-description
texinfo.texi(,2216) Indent every description in the menu following point to the specified
texinfo.texi(,2217) column.  You can use this command to give yourself more space for
texinfo.texi(,2218) descriptions.  With an argument (@kbd{C-u} as prefix argument, if
texinfo.texi(,2219) interactive), the @code{texinfo-indent-menu-description} command indents
texinfo.texi(,2220) every description in every menu in the region.  However, this command
texinfo.texi(,2221) does not indent the second and subsequent lines of a multi-line
texinfo.texi(,2222) description.@refill
texinfo.texi(,2223) 
texinfo.texi(,2224) @item M-x texinfo-sequential-node-update
texinfo.texi(,2225) @findex texinfo-sequential-node-update
texinfo.texi(,2226) Insert the names of the nodes immediately following and preceding the
texinfo.texi(,2227) current node as the `Next' or `Previous' pointers regardless of those
texinfo.texi(,2228) nodes' hierarchical level.  This means that the `Next' node of a
texinfo.texi(,2229) subsection may well be the next chapter.  Sequentially ordered nodes are
texinfo.texi(,2230) useful for novels and other documents that you read through
texinfo.texi(,2231) sequentially.  (However, in Info, the @kbd{g *} command lets
texinfo.texi(,2232) you look through the file sequentially, so sequentially ordered nodes
texinfo.texi(,2233) are not strictly necessary.)  With an argument (prefix argument, if
texinfo.texi(,2234) interactive), the @code{texinfo-sequential-node-update} command
texinfo.texi(,2235) sequentially updates all the nodes in the region.@refill
texinfo.texi(,2236) @end table
texinfo.texi(,2237) 
texinfo.texi(,2238) @node Info Formatting, Printing, Updating Nodes and Menus, Texinfo Mode
texinfo.texi(,2239) @comment  node-name,  next,  previous,  up
texinfo.texi(,2240) @section Formatting for Info
texinfo.texi(,2241) @cindex Formatting for Info
texinfo.texi(,2242) @cindex Running an Info formatter
texinfo.texi(,2243) @cindex Info formatting
texinfo.texi(,2244) 
texinfo.texi(,2245) Texinfo mode provides several commands for formatting part or all of a
texinfo.texi(,2246) Texinfo file for Info.  Often, when you are writing a document, you
texinfo.texi(,2247) want to format only part of a file---that is, a region.@refill
texinfo.texi(,2248) 
texinfo.texi(,2249) You can use either the @code{texinfo-format-region} or the
texinfo.texi(,2250) @code{makeinfo-region} command to format a region:@refill
texinfo.texi(,2251) 
texinfo.texi(,2252) @table @kbd
texinfo.texi(,2253) @findex texinfo-format-region
texinfo.texi(,2254) @item  C-c C-e C-r
texinfo.texi(,2255) @itemx M-x texinfo-format-region
texinfo.texi(,2256) @itemx C-c C-m C-r
texinfo.texi(,2257) @itemx M-x makeinfo-region
texinfo.texi(,2258) Format the current region for Info.@refill
texinfo.texi(,2259) @end table
texinfo.texi(,2260) 
texinfo.texi(,2261) You can use either the @code{texinfo-format-buffer} or the
texinfo.texi(,2262) @code{makeinfo-buffer} command to format a whole buffer:@refill
texinfo.texi(,2263) 
texinfo.texi(,2264) @table @kbd
texinfo.texi(,2265) @findex texinfo-format-buffer
texinfo.texi(,2266) @item  C-c C-e C-b
texinfo.texi(,2267) @itemx M-x texinfo-format-buffer
texinfo.texi(,2268) @itemx C-c C-m C-b
texinfo.texi(,2269) @itemx M-x makeinfo-buffer
texinfo.texi(,2270) Format the current buffer for Info.@refill
texinfo.texi(,2271) @end table
texinfo.texi(,2272) 
texinfo.texi(,2273) @need 1000
texinfo.texi(,2274) For example, after writing a Texinfo file, you can type the following:
texinfo.texi(,2275) 
texinfo.texi(,2276) @example
texinfo.texi(,2277) C-u C-c C-u m
texinfo.texi(,2278) @exdent or
texinfo.texi(,2279) C-u M-x texinfo-master-menu
texinfo.texi(,2280) @end example
texinfo.texi(,2281) 
texinfo.texi(,2282) @noindent
texinfo.texi(,2283) This updates all the nodes and menus.  Then type the following to create
texinfo.texi(,2284) an Info file:
texinfo.texi(,2285) 
texinfo.texi(,2286) @example
texinfo.texi(,2287) C-c C-m C-b
texinfo.texi(,2288) @exdent or
texinfo.texi(,2289) M-x makeinfo-buffer
texinfo.texi(,2290) @end example
texinfo.texi(,2291) 
texinfo.texi(,2292) For @TeX{} or the Info formatting commands to work, the file @emph{must}
texinfo.texi(,2293) include a line that has @code{@@setfilename} in its header.
texinfo.texi(,2294) 
texinfo.texi(,2295) @xref{Creating an Info File}, for details about Info formatting.@refill
texinfo.texi(,2296) 
texinfo.texi(,2297) @node Printing, Texinfo Mode Summary, Info Formatting, Texinfo Mode
texinfo.texi(,2298) @comment node-name,  next,  previous,  up
texinfo.texi(,2299) @section Formatting and Printing
texinfo.texi(,2300) @cindex Formatting for printing
texinfo.texi(,2301) @cindex Printing a region or buffer
texinfo.texi(,2302) @cindex Region formatting and printing
texinfo.texi(,2303) @cindex Buffer formatting and printing
texinfo.texi(,2304) @cindex Part of file formatting and printing
texinfo.texi(,2305) 
texinfo.texi(,2306) Typesetting and printing a Texinfo file is a multi-step process in which
texinfo.texi(,2307) you first create a file for printing (called a DVI file), and then
texinfo.texi(,2308) print the file.  Optionally, you may also create indices.  To do this,
texinfo.texi(,2309) you must run the @code{texindex} command after first running the
texinfo.texi(,2310) @code{tex} typesetting command; and then you must run the @code{tex}
texinfo.texi(,2311) command again.  Or else run the @code{texi2dvi} command which
texinfo.texi(,2312) automatically creates indices as needed (@pxref{Format with texi2dvi}).
texinfo.texi(,2313) 
texinfo.texi(,2314) Often, when you are writing a document, you want to typeset and print
texinfo.texi(,2315) only part of a file to see what it will look like.  You can use the
texinfo.texi(,2316) @code{texinfo-tex-region} and related commands for this purpose.  Use
texinfo.texi(,2317) the @code{texinfo-tex-buffer} command to format all of a
texinfo.texi(,2318) buffer.@refill
texinfo.texi(,2319) 
texinfo.texi(,2320) @table @kbd
texinfo.texi(,2321) @item  C-c C-t C-b
texinfo.texi(,2322) @itemx M-x texinfo-tex-buffer
texinfo.texi(,2323) @findex texinfo-tex-buffer
texinfo.texi(,2324) Run @code{texi2dvi} on the buffer.  In addition to running @TeX{} on the
texinfo.texi(,2325) buffer, this command automatically creates or updates indices as
texinfo.texi(,2326) needed.@refill
texinfo.texi(,2327) 
texinfo.texi(,2328) @item  C-c C-t C-r
texinfo.texi(,2329) @itemx M-x texinfo-tex-region
texinfo.texi(,2330) @findex texinfo-tex-region
texinfo.texi(,2331) Run @TeX{} on the region.@refill
texinfo.texi(,2332) 
texinfo.texi(,2333) @item C-c C-t C-i
texinfo.texi(,2334) @itemx M-x texinfo-texindex
texinfo.texi(,2335) Run @code{texindex} to sort the indices of a Texinfo file formatted with
texinfo.texi(,2336) @code{texinfo-tex-region}.  The @code{texinfo-tex-region} command does
texinfo.texi(,2337) not run @code{texindex} automatically; it only runs the @code{tex}
texinfo.texi(,2338) typesetting command.  You must run the @code{texinfo-tex-region} command
texinfo.texi(,2339) a second time after sorting the raw index files with the @code{texindex}
texinfo.texi(,2340) command.  (Usually, you do not format an index when you format a region,
texinfo.texi(,2341) only when you format a buffer.  Now that the @code{texi2dvi} command
texinfo.texi(,2342) exists, there is little or no need for this command.)@refill
texinfo.texi(,2343) 
texinfo.texi(,2344) @item C-c C-t C-p
texinfo.texi(,2345) @itemx M-x texinfo-tex-print
texinfo.texi(,2346) @findex texinfo-tex-print
texinfo.texi(,2347) Print the file (or the part of the file) previously formatted with
texinfo.texi(,2348) @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
texinfo.texi(,2349) @end table
texinfo.texi(,2350) 
texinfo.texi(,2351) For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
texinfo.texi(,2352) file @emph{must} start with a @samp{\input texinfo} line and must
texinfo.texi(,2353) include an @code{@@settitle} line.  The file must end with @code{@@bye}
texinfo.texi(,2354) on a line by itself.  (When you use @code{texinfo-tex-region}, you must
texinfo.texi(,2355) surround the @code{@@settitle} line with start-of-header and
texinfo.texi(,2356) end-of-header lines.)@refill
texinfo.texi(,2357) 
texinfo.texi(,2358) @xref{Hardcopy}, for a description of the other @TeX{} related
texinfo.texi(,2359) commands, such as @code{tex-show-print-queue}.@refill
texinfo.texi(,2360) 
texinfo.texi(,2361) @node Texinfo Mode Summary,  , Printing, Texinfo Mode
texinfo.texi(,2362) @comment  node-name,  next,  previous,  up
texinfo.texi(,2363) @section Texinfo Mode Summary
texinfo.texi(,2364) 
texinfo.texi(,2365) In Texinfo mode, each set of commands has default keybindings that
texinfo.texi(,2366) begin with the same keys.  All the commands that are custom-created
texinfo.texi(,2367) for Texinfo mode begin with @kbd{C-c}.  The keys are somewhat
texinfo.texi(,2368) mnemonic.@refill
texinfo.texi(,2369) 
texinfo.texi(,2370) @subheading Insert Commands
texinfo.texi(,2371) 
texinfo.texi(,2372) The insert commands are invoked by typing @kbd{C-c} twice and then the
texinfo.texi(,2373) first letter of the @@-command to be inserted.  (It might make more
texinfo.texi(,2374) sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
texinfo.texi(,2375) @kbd{C-c C-c} is quick to type.)@refill
texinfo.texi(,2376) 
texinfo.texi(,2377) @example
texinfo.texi(,2378) C-c C-c c       @r{Insert} @samp{@@code}.
texinfo.texi(,2379) C-c C-c d       @r{Insert} @samp{@@dfn}.
texinfo.texi(,2380) C-c C-c e       @r{Insert} @samp{@@end}.
texinfo.texi(,2381) C-c C-c i       @r{Insert} @samp{@@item}.
texinfo.texi(,2382) C-c C-c n       @r{Insert} @samp{@@node}.
texinfo.texi(,2383) C-c C-c s       @r{Insert} @samp{@@samp}.
texinfo.texi(,2384) C-c C-c v       @r{Insert} @samp{@@var}.
texinfo.texi(,2385) C-c C-c @{       @r{Insert braces.}
texinfo.texi(,2386) C-c C-c ]
texinfo.texi(,2387) C-c C-c @}       @r{Move out of enclosing braces.}
texinfo.texi(,2388) 
texinfo.texi(,2389) @group
texinfo.texi(,2390) C-c C-c C-d     @r{Insert a node's section title}
texinfo.texi(,2391)                 @r{in the space for the description}
texinfo.texi(,2392)                 @r{in a menu entry line.}
texinfo.texi(,2393) @end group
texinfo.texi(,2394) @end example
texinfo.texi(,2395) 
texinfo.texi(,2396) @subheading Show Structure
texinfo.texi(,2397) 
texinfo.texi(,2398) The @code{texinfo-show-structure} command is often used within a
texinfo.texi(,2399) narrowed region.@refill
texinfo.texi(,2400) 
texinfo.texi(,2401) @example
texinfo.texi(,2402) C-c C-s         @r{List all the headings.}
texinfo.texi(,2403) @end example
texinfo.texi(,2404) 
texinfo.texi(,2405) @subheading The Master Update Command
texinfo.texi(,2406) 
texinfo.texi(,2407) The @code{texinfo-master-menu} command creates a master menu; and can
texinfo.texi(,2408) be used to update every node and menu in a file as well.@refill
texinfo.texi(,2409) 
texinfo.texi(,2410) @c Probably should use @tables in this section.
texinfo.texi(,2411) @example
texinfo.texi(,2412) @group
texinfo.texi(,2413) C-c C-u m
texinfo.texi(,2414) M-x texinfo-master-menu
texinfo.texi(,2415)                 @r{Create or update a master menu.}
texinfo.texi(,2416) @end group
texinfo.texi(,2417) 
texinfo.texi(,2418) @group
texinfo.texi(,2419) C-u C-c C-u m   @r{With @kbd{C-u} as a prefix argument, first}
texinfo.texi(,2420)                 @r{create or update all nodes and regular}
texinfo.texi(,2421)                 @r{menus, and then create a master menu.}
texinfo.texi(,2422) @end group
texinfo.texi(,2423) @end example
texinfo.texi(,2424) 
texinfo.texi(,2425) @subheading Update Pointers
texinfo.texi(,2426) 
texinfo.texi(,2427) The update pointer commands are invoked by typing @kbd{C-c C-u} and
texinfo.texi(,2428) then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
texinfo.texi(,2429) @code{texinfo-every-node-update}.@refill
texinfo.texi(,2430) 
texinfo.texi(,2431) @example
texinfo.texi(,2432) C-c C-u C-n     @r{Update a node.}
texinfo.texi(,2433) C-c C-u C-e     @r{Update every node in the buffer.}
texinfo.texi(,2434) @end example
texinfo.texi(,2435) 
texinfo.texi(,2436) @subheading Update Menus
texinfo.texi(,2437) 
texinfo.texi(,2438) Invoke the  update menu commands by typing @kbd{C-c C-u}
texinfo.texi(,2439) and then either @kbd{C-m} for @code{texinfo-make-menu} or
texinfo.texi(,2440) @kbd{C-a} for @code{texinfo-all-menus-update}.  To update
texinfo.texi(,2441) both nodes and menus at the same time, precede @kbd{C-c C-u
texinfo.texi(,2442) C-a} with @kbd{C-u}.@refill
texinfo.texi(,2443) 
texinfo.texi(,2444) @example
texinfo.texi(,2445) C-c C-u C-m     @r{Make or update a menu.}
texinfo.texi(,2446) 
texinfo.texi(,2447) @group
texinfo.texi(,2448) C-c C-u C-a     @r{Make or update all}
texinfo.texi(,2449)                 @r{menus in a buffer.}
texinfo.texi(,2450) @end group
texinfo.texi(,2451) 
texinfo.texi(,2452) @group
texinfo.texi(,2453) C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
texinfo.texi(,2454)                 @r{first create or update all nodes and}
texinfo.texi(,2455)                 @r{then create or update all menus.}
texinfo.texi(,2456) @end group
texinfo.texi(,2457) @end example
texinfo.texi(,2458) 
texinfo.texi(,2459) @subheading Format for Info
texinfo.texi(,2460) 
texinfo.texi(,2461) The Info formatting commands that are written in Emacs Lisp are
texinfo.texi(,2462) invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
texinfo.texi(,2463) or @kbd{C-b} for the whole buffer.@refill
texinfo.texi(,2464) 
texinfo.texi(,2465) The Info formatting commands that are written in C and based on the
texinfo.texi(,2466) @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
texinfo.texi(,2467) either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
texinfo.texi(,2468) 
texinfo.texi(,2469) @need 800
texinfo.texi(,2470) @noindent
texinfo.texi(,2471) Use the @code{texinfo-format@dots{}} commands:
texinfo.texi(,2472) 
texinfo.texi(,2473) @example
texinfo.texi(,2474) @group
texinfo.texi(,2475) C-c C-e C-r     @r{Format the region.}
texinfo.texi(,2476) C-c C-e C-b     @r{Format the buffer.}
texinfo.texi(,2477) @end group
texinfo.texi(,2478) @end example
texinfo.texi(,2479) 
texinfo.texi(,2480) @need 750
texinfo.texi(,2481) @noindent
texinfo.texi(,2482) Use @code{makeinfo}:
texinfo.texi(,2483) 
texinfo.texi(,2484) @example
texinfo.texi(,2485) C-c C-m C-r     @r{Format the region.}
texinfo.texi(,2486) C-c C-m C-b     @r{Format the buffer.}
texinfo.texi(,2487) C-c C-m C-l     @r{Recenter the @code{makeinfo} output buffer.}
texinfo.texi(,2488) C-c C-m C-k     @r{Kill the @code{makeinfo} formatting job.}
texinfo.texi(,2489) @end example
texinfo.texi(,2490) 
texinfo.texi(,2491) @subheading Typeset and Print
texinfo.texi(,2492) 
texinfo.texi(,2493) The @TeX{} typesetting and printing commands are invoked by typing
texinfo.texi(,2494) @kbd{C-c C-t} and then another control command: @kbd{C-r} for
texinfo.texi(,2495) @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
texinfo.texi(,2496) and so on.@refill
texinfo.texi(,2497) 
texinfo.texi(,2498) @example
texinfo.texi(,2499) C-c C-t C-r     @r{Run @TeX{} on the region.}
texinfo.texi(,2500) C-c C-t C-b     @r{Run} @code{texi2dvi} @r{on the buffer.}
texinfo.texi(,2501) C-c C-t C-i     @r{Run} @code{texindex}.
texinfo.texi(,2502) C-c C-t C-p     @r{Print the DVI file.}
texinfo.texi(,2503) C-c C-t C-q     @r{Show the print queue.}
texinfo.texi(,2504) C-c C-t C-d     @r{Delete a job from the print queue.}
texinfo.texi(,2505) C-c C-t C-k     @r{Kill the current @TeX{} formatting job.}
texinfo.texi(,2506) C-c C-t C-x     @r{Quit a currently stopped @TeX{} formatting job.}
texinfo.texi(,2507) C-c C-t C-l     @r{Recenter the output buffer.}
texinfo.texi(,2508) @end example
texinfo.texi(,2509) 
texinfo.texi(,2510) @subheading Other Updating Commands
texinfo.texi(,2511) 
texinfo.texi(,2512) The remaining updating commands do not have standard keybindings because
texinfo.texi(,2513) they are rarely used.
texinfo.texi(,2514) 
texinfo.texi(,2515) @example
texinfo.texi(,2516) @group
texinfo.texi(,2517) M-x texinfo-insert-node-lines
texinfo.texi(,2518)                 @r{Insert missing @code{@@node} lines in region.}
texinfo.texi(,2519)                 @r{With @kbd{C-u} as a prefix argument,}
texinfo.texi(,2520)                 @r{use section titles as node names.}
texinfo.texi(,2521) @end group
texinfo.texi(,2522) 
texinfo.texi(,2523) @group
texinfo.texi(,2524) M-x texinfo-multiple-files-update
texinfo.texi(,2525)                 @r{Update a multi-file document.}
texinfo.texi(,2526)                 @r{With @kbd{C-u 2} as a prefix argument,}
texinfo.texi(,2527)                 @r{create or update all nodes and menus}
texinfo.texi(,2528)                 @r{in all included files first.}
texinfo.texi(,2529) @end group
texinfo.texi(,2530) 
texinfo.texi(,2531) @group
texinfo.texi(,2532) M-x texinfo-indent-menu-description
texinfo.texi(,2533)                 @r{Indent descriptions.}
texinfo.texi(,2534) @end group
texinfo.texi(,2535) 
texinfo.texi(,2536) @group
texinfo.texi(,2537) M-x texinfo-sequential-node-update
texinfo.texi(,2538)                 @r{Insert node pointers in strict sequence.}
texinfo.texi(,2539) @end group
texinfo.texi(,2540) @end example
texinfo.texi(,2541) 
texinfo.texi(,2542) 
texinfo.texi(,2543) @node Beginning a File
texinfo.texi(,2544) @chapter Beginning a Texinfo File
texinfo.texi(,2545) @cindex Beginning a Texinfo file
texinfo.texi(,2546) @cindex Texinfo file beginning
texinfo.texi(,2547) @cindex File beginning
texinfo.texi(,2548) 
texinfo.texi(,2549) Certain pieces of information must be provided at the beginning of a
texinfo.texi(,2550) Texinfo file, such as the name for the output file(s), the title of the
texinfo.texi(,2551) document, and the Top node.
texinfo.texi(,2552) 
texinfo.texi(,2553) This chapter expands on the minimal complete Texinfo source file
texinfo.texi(,2554) previously given (@pxref{Six Parts}).
texinfo.texi(,2555) 
texinfo.texi(,2556) @menu
texinfo.texi(,2557) * Sample Beginning::            A sample beginning for a Texinfo file.
texinfo.texi(,2558) * Texinfo File Header::         The first lines.
texinfo.texi(,2559) * Document Permissions::        Ensuring your manual is free.
texinfo.texi(,2560) * Titlepage & Copyright Page::  Creating the title and copyright pages.
texinfo.texi(,2561) * The Top Node::                Creating the `Top' node and master menu.
texinfo.texi(,2562) * Global Document Commands::    Affecting formatting throughout.
texinfo.texi(,2563) * Software Copying Permissions::  Ensure that you and others continue to
texinfo.texi(,2564)                                     have the right to use and share software.
texinfo.texi(,2565) @end menu
texinfo.texi(,2566) 
texinfo.texi(,2567) 
texinfo.texi(,2568) @node Sample Beginning
texinfo.texi(,2569) @section Sample Texinfo File Beginning
texinfo.texi(,2570) 
texinfo.texi(,2571) @cindex Example beginning of Texinfo file 
texinfo.texi(,2572) 
texinfo.texi(,2573) The following sample shows what is needed.  The elements given here are
texinfo.texi(,2574) explained in more detail in the following sections.  Other commands are
texinfo.texi(,2575) often included at the beginning of Texinfo files, but the ones here are
texinfo.texi(,2576) the most critical.
texinfo.texi(,2577) 
texinfo.texi(,2578) @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
texinfo.texi(,2579) 
texinfo.texi(,2580) @example
texinfo.texi(,2581) \input texinfo   @@c -*-texinfo-*-
texinfo.texi(,2582) @@c %**start of header
texinfo.texi(,2583) @@setfilename @var{infoname}.info
texinfo.texi(,2584) @@settitle @var{name-of-manual} @var{version}
texinfo.texi(,2585) @@c %**end of header
texinfo.texi(,2586) 
texinfo.texi(,2587) @@copying
texinfo.texi(,2588) This manual is for @var{program}, version @var{version}.
texinfo.texi(,2589) 
texinfo.texi(,2590) Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
texinfo.texi(,2591) 
texinfo.texi(,2592) @group
texinfo.texi(,2593) @@quotation
texinfo.texi(,2594) Permission is granted to @dots{}
texinfo.texi(,2595) @@end quotation
texinfo.texi(,2596) @@end copying
texinfo.texi(,2597) @end group
texinfo.texi(,2598) 
texinfo.texi(,2599) @group
texinfo.texi(,2600) @@titlepage
texinfo.texi(,2601) @@title @var{name-of-manual-when-printed}
texinfo.texi(,2602) @@subtitle @var{subtitle-if-any}
texinfo.texi(,2603) @@subtitle @var{second-subtitle}
texinfo.texi(,2604) @@author @var{author}
texinfo.texi(,2605) @end group
texinfo.texi(,2606) 
texinfo.texi(,2607) @group
texinfo.texi(,2608) @@c  The following two commands
texinfo.texi(,2609) @@c  start the copyright page.
texinfo.texi(,2610) @@page
texinfo.texi(,2611) @@vskip 0pt plus 1filll
texinfo.texi(,2612) @@insertcopying
texinfo.texi(,2613) @end group
texinfo.texi(,2614) 
texinfo.texi(,2615) Published by @dots{}
texinfo.texi(,2616) @@end titlepage
texinfo.texi(,2617) 
texinfo.texi(,2618) @@c So the toc is printed in the right place.
texinfo.texi(,2619) @@contents
texinfo.texi(,2620) 
texinfo.texi(,2621) @@ifnottex
texinfo.texi(,2622) @@node Top
texinfo.texi(,2623) @@top @var{title}
texinfo.texi(,2624) 
texinfo.texi(,2625) @@insertcopying
texinfo.texi(,2626) @@end ifnottex
texinfo.texi(,2627) 
texinfo.texi(,2628) @group
texinfo.texi(,2629) @@menu
texinfo.texi(,2630) * First Chapter::    Getting started @dots{}
texinfo.texi(,2631) * Second Chapter::          @dots{}
texinfo.texi(,2632)   @dots{}
texinfo.texi(,2633) * Copying::          Your rights and freedoms.
texinfo.texi(,2634) @@end menu
texinfo.texi(,2635) @end group
texinfo.texi(,2636) 
texinfo.texi(,2637) @group
texinfo.texi(,2638) @@node First Chapter
texinfo.texi(,2639) @@chapter First Chapter
texinfo.texi(,2640) 
texinfo.texi(,2641) @@cindex first chapter
texinfo.texi(,2642) @@cindex chapter, first
texinfo.texi(,2643) @dots{}
texinfo.texi(,2644) @end group
texinfo.texi(,2645) @end example
texinfo.texi(,2646) 
texinfo.texi(,2647) 
texinfo.texi(,2648) @node Texinfo File Header
texinfo.texi(,2649) @section Texinfo File Header
texinfo.texi(,2650) @cindex Header for Texinfo files
texinfo.texi(,2651) @cindex Texinfo file header
texinfo.texi(,2652) 
texinfo.texi(,2653) Texinfo files start with at least three lines that provide Info and
texinfo.texi(,2654) @TeX{} with necessary information.  These are the @code{\input texinfo}
texinfo.texi(,2655) line, the @code{@@settitle} line, and the @code{@@setfilename} line.
texinfo.texi(,2656) 
texinfo.texi(,2657) Also, if you want to format just part of the Texinfo file, you must
texinfo.texi(,2658) write the @code{@@settitle} and @code{@@setfilename} lines between
texinfo.texi(,2659) start-of-header and end-of-header lines.  The start- and end-of-header
texinfo.texi(,2660) lines are optional, but they do no harm, so you might as well always
texinfo.texi(,2661) include them.
texinfo.texi(,2662) 
texinfo.texi(,2663) Any command that affects document formatting as a whole makes sense to
texinfo.texi(,2664) include in the header.  @code{@@synindex} (@pxref{synindex}), for
texinfo.texi(,2665) instance, is another command often included in the header.  @xref{GNU
texinfo.texi(,2666) Sample Texts}, for complete sample texts.
texinfo.texi(,2667) 
texinfo.texi(,2668) Thus, the beginning of a Texinfo file generally looks like this:
texinfo.texi(,2669) 
texinfo.texi(,2670) @example
texinfo.texi(,2671) @group
texinfo.texi(,2672) \input texinfo   @@c -*-texinfo-*-
texinfo.texi(,2673) @@c %**start of header
texinfo.texi(,2674) @@setfilename sample.info
texinfo.texi(,2675) @@settitle Sample Manual 1.0
texinfo.texi(,2676) @@c %**end of header
texinfo.texi(,2677) @end group
texinfo.texi(,2678) @end example
texinfo.texi(,2679) 
texinfo.texi(,2680) @menu
texinfo.texi(,2681) * First Line::                  The first line of a Texinfo file.
texinfo.texi(,2682) * Start of Header::             Formatting a region requires this.
texinfo.texi(,2683) * setfilename::                 Tell Info the name of the Info file.
texinfo.texi(,2684) * settitle::                    Create a title for the printed work.
texinfo.texi(,2685) * End of Header::               Formatting a region requires this.
texinfo.texi(,2686) @end menu
texinfo.texi(,2687) 
texinfo.texi(,2688) 
texinfo.texi(,2689) @node First Line
texinfo.texi(,2690) @subsection The First Line of a Texinfo File
texinfo.texi(,2691) @cindex First line of a Texinfo file
texinfo.texi(,2692) @cindex Beginning line of a Texinfo file
texinfo.texi(,2693) @cindex Header of a Texinfo file
texinfo.texi(,2694) 
texinfo.texi(,2695) Every Texinfo file that is to be the top-level input to @TeX{} must begin
texinfo.texi(,2696) with a line that looks like this:
texinfo.texi(,2697) 
texinfo.texi(,2698) @example
texinfo.texi(,2699) \input texinfo   @@c -*-texinfo-*-
texinfo.texi(,2700) @end example
texinfo.texi(,2701) 
texinfo.texi(,2702) @noindent
texinfo.texi(,2703) This line serves two functions:
texinfo.texi(,2704) 
texinfo.texi(,2705) @enumerate
texinfo.texi(,2706) @item
texinfo.texi(,2707) When the file is processed by @TeX{}, the @samp{\input texinfo} command
texinfo.texi(,2708) tells @TeX{} to load the macros needed for processing a Texinfo file.
texinfo.texi(,2709) These are in a file called @file{texinfo.tex}, which should have been
texinfo.texi(,2710) installed on your system along with either the @TeX{} or Texinfo
texinfo.texi(,2711) software.  @TeX{} uses the backslash, @samp{\}, to mark the beginning of
texinfo.texi(,2712) a command, exactly as Texinfo uses @samp{@@}.  The @file{texinfo.tex}
texinfo.texi(,2713) file causes the switch from @samp{\} to @samp{@@}; before the switch
texinfo.texi(,2714) occurs, @TeX{} requires @samp{\}, which is why it appears at the
texinfo.texi(,2715) beginning of the file.
texinfo.texi(,2716) 
texinfo.texi(,2717) @item
texinfo.texi(,2718) When the file is edited in GNU Emacs, the @samp{-*-texinfo-*-} mode
texinfo.texi(,2719) specification tells Emacs to use Texinfo mode.
texinfo.texi(,2720) @end enumerate
texinfo.texi(,2721) 
texinfo.texi(,2722) 
texinfo.texi(,2723) @node Start of Header
texinfo.texi(,2724) @subsection Start of Header
texinfo.texi(,2725) @cindex Start of header line
texinfo.texi(,2726) 
texinfo.texi(,2727) A start-of-header line is a Texinfo comment that looks like this:
texinfo.texi(,2728) 
texinfo.texi(,2729) @example
texinfo.texi(,2730) @@c %**start of header
texinfo.texi(,2731) @end example
texinfo.texi(,2732) 
texinfo.texi(,2733) Write the start-of-header line on the second line of a Texinfo file.
texinfo.texi(,2734) Follow the start-of-header line with @code{@@setfilename} and
texinfo.texi(,2735) @code{@@settitle} lines and, optionally, with other commands that
texinfo.texi(,2736) globally affect the document formatting, such as @code{@@synindex} or
texinfo.texi(,2737) @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
texinfo.texi(,2738) Header}).
texinfo.texi(,2739) 
texinfo.texi(,2740) The start- and end-of-header lines allow you to format only part of a
texinfo.texi(,2741) Texinfo file for Info or printing.  @xref{texinfo-format commands}.
texinfo.texi(,2742) 
texinfo.texi(,2743) The odd string of characters, @samp{%**}, is to ensure that no other
texinfo.texi(,2744) comment is accidentally taken for a start-of-header line.  You can
texinfo.texi(,2745) change it if you wish by setting the @code{tex-start-of-header} and/or
texinfo.texi(,2746) @code{tex-end-of-header} Emacs variables.  @xref{Texinfo Mode Printing}.
texinfo.texi(,2747) 
texinfo.texi(,2748) 
texinfo.texi(,2749) @node setfilename
texinfo.texi(,2750) @subsection @code{@@setfilename}: Set the output file name
texinfo.texi(,2751) @findex setfilename
texinfo.texi(,2752) @cindex Texinfo requires @code{@@setfilename}
texinfo.texi(,2753) 
texinfo.texi(,2754) In order to serve as the primary input file for either @code{makeinfo}
texinfo.texi(,2755) or @TeX{}, a Texinfo file must contain a line that looks like this:
texinfo.texi(,2756) 
texinfo.texi(,2757) @example
texinfo.texi(,2758) @@setfilename @var{info-file-name}
texinfo.texi(,2759) @end example
texinfo.texi(,2760) 
texinfo.texi(,2761) Write the @code{@@setfilename} command at the beginning of a line and
texinfo.texi(,2762) follow it on the same line by the Info file name.  Do not write anything
texinfo.texi(,2763) else on the line; anything on the line after the command is considered
texinfo.texi(,2764) part of the file name, including what would otherwise be a
texinfo.texi(,2765) comment.
texinfo.texi(,2766) 
texinfo.texi(,2767) @cindex Ignored before @code{@@setfilename}
texinfo.texi(,2768) @cindex @samp{\input} source line ignored
texinfo.texi(,2769) The Info formatting commands ignore everything written before the
texinfo.texi(,2770) @code{@@setfilename} line, which is why the very first line of
texinfo.texi(,2771) the file (the @code{\input} line) does not show up in the output.
texinfo.texi(,2772) 
texinfo.texi(,2773) The @code{@@setfilename} line specifies the name of the output file to
texinfo.texi(,2774) be generated.  This name must be different from the name of the Texinfo
texinfo.texi(,2775) file.  There are two conventions for choosing the name: you can either
texinfo.texi(,2776) remove the extension (such as @samp{.texi}) entirely from the input file
texinfo.texi(,2777) name, or, preferably, replace it with the @samp{.info} extension.
texinfo.texi(,2778) 
texinfo.texi(,2779) @cindex Length of file names
texinfo.texi(,2780) @cindex File name collision
texinfo.texi(,2781) @cindex Info file name, choosing
texinfo.texi(,2782) Although an explicit @samp{.info} extension is preferable, some
texinfo.texi(,2783) operating systems cannot handle long file names.  You can run into a
texinfo.texi(,2784) problem even when the file name you specify is itself short enough.
texinfo.texi(,2785) This occurs because the Info formatters split a long Info file into
texinfo.texi(,2786) short indirect subfiles, and name them by appending @samp{-1},
texinfo.texi(,2787) @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
texinfo.texi(,2788) file name.  (@xref{Tag and Split Files}.)  The subfile name
texinfo.texi(,2789) @file{texinfo.info-10}, for example, is too long for old systems with a
texinfo.texi(,2790) 14-character limit on filenames; so the Info file name for this document
texinfo.texi(,2791) is @file{texinfo} rather than @file{texinfo.info}.  When @code{makeinfo}
texinfo.texi(,2792) is running on operating systems such as MS-DOS which impose severe
texinfo.texi(,2793) limits on file names, it may remove some characters from the original
texinfo.texi(,2794) file name to leave enough space for the subfile suffix, thus producing
texinfo.texi(,2795) files named @file{texin-10}, @file{gcc.i12}, etc.
texinfo.texi(,2796) 
texinfo.texi(,2797) When producing HTML output, @code{makeinfo} will replace any extension
texinfo.texi(,2798) with @samp{html}, or add @samp{.html} if the given name has no
texinfo.texi(,2799) extension.
texinfo.texi(,2800) 
texinfo.texi(,2801) @pindex texinfo.cnf
texinfo.texi(,2802) The @code{@@setfilename} line produces no output when you typeset a
texinfo.texi(,2803) manual with @TeX{}, but it is nevertheless essential: it opens the
texinfo.texi(,2804) index, cross-reference, and other auxiliary files used by Texinfo, and
texinfo.texi(,2805) also reads @file{texinfo.cnf} if that file is present on your system
texinfo.texi(,2806) (@pxref{Preparing for TeX,, Preparing for @TeX{}}).
texinfo.texi(,2807) 
texinfo.texi(,2808) 
texinfo.texi(,2809) @node settitle
texinfo.texi(,2810) @subsection @code{@@settitle}: Set the document title
texinfo.texi(,2811) @findex settitle
texinfo.texi(,2812) 
texinfo.texi(,2813) In order to be made into a printed manual, a Texinfo file must contain
texinfo.texi(,2814) a line that looks like this:
texinfo.texi(,2815) 
texinfo.texi(,2816) @example
texinfo.texi(,2817) @@settitle @var{title}
texinfo.texi(,2818) @end example
texinfo.texi(,2819) 
texinfo.texi(,2820) Write the @code{@@settitle} command at the beginning of a line and
texinfo.texi(,2821) follow it on the same line by the title.  This tells @TeX{} the title to
texinfo.texi(,2822) use in a header or footer.  Do not write anything else on the line;
texinfo.texi(,2823) anything on the line after the command is considered part of the title,
texinfo.texi(,2824) including what would otherwise be a comment.
texinfo.texi(,2825) 
texinfo.texi(,2826) The @code{@@settitle} command should precede everything that generates
texinfo.texi(,2827) actual output in @TeX{}.
texinfo.texi(,2828) 
texinfo.texi(,2829) @cindex <title> HTML tag
texinfo.texi(,2830) In the HTML file produced by @command{makeinfo}, @var{title} also serves
texinfo.texi(,2831) as the document @samp{<title>} and the default document description in
texinfo.texi(,2832) the @samp{<head>} part; see @ref{documentdescription}, for how to change
texinfo.texi(,2833) that.
texinfo.texi(,2834) 
texinfo.texi(,2835) The title in the @code{@@settitle} command does not affect the title as
texinfo.texi(,2836) it appears on the title page.  Thus, the two do not need not match
texinfo.texi(,2837) exactly.  A practice we recommend is to include the version or edition
texinfo.texi(,2838) number of the manual in the @code{@@settitle} title; on the title page,
texinfo.texi(,2839) the version number generally appears as a @code{@@subtitle} so it would
texinfo.texi(,2840) be omitted from the @code{@@title}.  (@xref{titlepage}.)
texinfo.texi(,2841) 
texinfo.texi(,2842) Conventionally, when @TeX{} formats a Texinfo file for double-sided
texinfo.texi(,2843) output, the title is printed in the left-hand (even-numbered) page
texinfo.texi(,2844) headings and the current chapter title is printed in the right-hand
texinfo.texi(,2845) (odd-numbered) page headings.  (@TeX{} learns the title of each chapter
texinfo.texi(,2846) from each @code{@@chapter} command.)  By default, no page footer is
texinfo.texi(,2847) printed.
texinfo.texi(,2848) 
texinfo.texi(,2849) Even if you are printing in a single-sided style, @TeX{} looks for an
texinfo.texi(,2850) @code{@@settitle} command line, in case you include the manual title
texinfo.texi(,2851) in the heading.
texinfo.texi(,2852) 
texinfo.texi(,2853) @TeX{} prints page headings only for that text that comes after the
texinfo.texi(,2854) @code{@@end titlepage} command in the Texinfo file, or that comes
texinfo.texi(,2855) after an @code{@@headings} command that turns on headings.
texinfo.texi(,2856) (@xref{headings on off, , The @code{@@headings} Command}, for more
texinfo.texi(,2857) information.)
texinfo.texi(,2858) 
texinfo.texi(,2859) You may, if you wish, create your own, customized headings and footings.
texinfo.texi(,2860) @xref{Headings}, for a detailed discussion of this.
texinfo.texi(,2861) 
texinfo.texi(,2862) 
texinfo.texi(,2863) @node End of Header
texinfo.texi(,2864) @subsection End of Header
texinfo.texi(,2865) @cindex End of header line
texinfo.texi(,2866) 
texinfo.texi(,2867) Follow the header lines with an @w{end-of-header} line, which is a
texinfo.texi(,2868) Texinfo comment that looks like this:
texinfo.texi(,2869) 
texinfo.texi(,2870) @example
texinfo.texi(,2871) @@c %**end of header
texinfo.texi(,2872) @end example
texinfo.texi(,2873) 
texinfo.texi(,2874) @xref{Start of Header}.
texinfo.texi(,2875) 
texinfo.texi(,2876) 
texinfo.texi(,2877) @node Document Permissions
texinfo.texi(,2878) @section Document Permissions
texinfo.texi(,2879) @cindex Document Permissions
texinfo.texi(,2880) @cindex Copying Permissions
texinfo.texi(,2881) 
texinfo.texi(,2882) The copyright notice and copying permissions for a document need to
texinfo.texi(,2883) appear in several places in the various Texinfo output formats.
texinfo.texi(,2884) Therefore, Texinfo provides a command (@code{@@copying}) to declare
texinfo.texi(,2885) this text once, and another command (@code{@@insertcopying}) to
texinfo.texi(,2886) insert the text at appropriate points.
texinfo.texi(,2887) 
texinfo.texi(,2888) @menu
texinfo.texi(,2889) * copying::                 Declare the document's copying permissions.
texinfo.texi(,2890) * insertcopying::           Where to insert the permissions.
texinfo.texi(,2891) @end menu
texinfo.texi(,2892) 
texinfo.texi(,2893) 
texinfo.texi(,2894) @node copying
texinfo.texi(,2895) @subsection @code{@@copying}: Declare copying permissions
texinfo.texi(,2896) @findex copying
texinfo.texi(,2897) 
texinfo.texi(,2898) The @code{@@copying} command should be given very early in the document;
texinfo.texi(,2899) right after the header material (@pxref{Texinfo File Header}) is the
texinfo.texi(,2900) recommended location.  It conventionally consists of a sentence or two
texinfo.texi(,2901) about what the program is, the legal copyright line, and the copying
texinfo.texi(,2902) permissions.  Here is a skeletal example:
texinfo.texi(,2903) 
texinfo.texi(,2904) @example
texinfo.texi(,2905) @@copying
texinfo.texi(,2906) This manual is for @var{program} (version @var{version}),
texinfo.texi(,2907) which @dots{}
texinfo.texi(,2908) 
texinfo.texi(,2909) Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
texinfo.texi(,2910) 
texinfo.texi(,2911) @@quotation
texinfo.texi(,2912) Permission is granted to @dots{}
texinfo.texi(,2913) @@end quotation
texinfo.texi(,2914) @@end copying
texinfo.texi(,2915) @end example
texinfo.texi(,2916) 
texinfo.texi(,2917) The @code{@@quotation} has no legal significance; it's there to improve
texinfo.texi(,2918) readability in some contexts.
texinfo.texi(,2919) 
texinfo.texi(,2920) @xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
texinfo.texi(,2921) @xref{GNU Free Documentation License}, for the license itself under
texinfo.texi(,2922) which GNU and other free manuals are distributed.
texinfo.texi(,2923) 
texinfo.texi(,2924) The text of @code{@@copying} is output as a comment at the beginning of
texinfo.texi(,2925) Info, HTML, and XML output files.  It is @emph{not} output implicitly in
texinfo.texi(,2926) plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
texinfo.texi(,2927) emit the copying information.  See the next section for details.
texinfo.texi(,2928) 
texinfo.texi(,2929) @findex copyright
texinfo.texi(,2930) In output formats that support it (print and HTML), the
texinfo.texi(,2931) @code{@@copyright@{@}} command generates a @samp{c} inside a circle.  In
texinfo.texi(,2932) Info and plain text, it generates @samp{(C)}.  The copyright notice
texinfo.texi(,2933) itself has the following legally defined sequence:
texinfo.texi(,2934) 
texinfo.texi(,2935) @example
texinfo.texi(,2936) Copyright @copyright{} @var{years} @var{copyright-owner}.
texinfo.texi(,2937) @end example
texinfo.texi(,2938) 
texinfo.texi(,2939) @cindex Copyright word, always in English
texinfo.texi(,2940) The word `Copyright' must always be written in English, even if the
texinfo.texi(,2941) manual is otherwise in another language.  This is due to international
texinfo.texi(,2942) law.
texinfo.texi(,2943) 
texinfo.texi(,2944) @cindex Years, in copyright line
texinfo.texi(,2945) The list of years should include all years in which a version was
texinfo.texi(,2946) completed (even if it was released in a subsequent year).  Ranges are
texinfo.texi(,2947) not allowed, each year must be written out individually, separated by
texinfo.texi(,2948) commas.
texinfo.texi(,2949) 
texinfo.texi(,2950) @cindex Copyright owner for FSF works
texinfo.texi(,2951) The copyright owner (or owners) is whoever holds legal copyright on the
texinfo.texi(,2952) work.  In the case of works assigned to the FSF, the owner is `Free
texinfo.texi(,2953) Software Foundation, Inc.'.
texinfo.texi(,2954) 
texinfo.texi(,2955) @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
texinfo.texi(,2956) additional information.
texinfo.texi(,2957) 
texinfo.texi(,2958) 
texinfo.texi(,2959) @node insertcopying
texinfo.texi(,2960) @subsection @code{@@insertcopying}: Include permissions text
texinfo.texi(,2961) @findex insertcopying
texinfo.texi(,2962) @cindex Copying text, including
texinfo.texi(,2963) @cindex Permissions text, including
texinfo.texi(,2964) @cindex Including permissions text
texinfo.texi(,2965) 
texinfo.texi(,2966) The @code{@@insertcopying} command is simply written on a line by
texinfo.texi(,2967) itself, like this:
texinfo.texi(,2968) 
texinfo.texi(,2969) @example
texinfo.texi(,2970) @@insertcopying
texinfo.texi(,2971) @end example
texinfo.texi(,2972) 
texinfo.texi(,2973) It inserts the text previously defined by @code{@@copying}.  Legally, it
texinfo.texi(,2974) must be used on the copyright page in the printed manual
texinfo.texi(,2975) (@pxref{Copyright}).
texinfo.texi(,2976) 
texinfo.texi(,2977) Although it's not a legal requirement, we also strongly recommend using
texinfo.texi(,2978) @code{@@insertcopying} in the Top node of your manual (@pxref{The Top
texinfo.texi(,2979) Node}).  Here's why:
texinfo.texi(,2980) 
texinfo.texi(,2981) The @code{@@copying} command itself causes the permissions text to
texinfo.texi(,2982) appear in an Info file @emph{before} the first node.  The text is also
texinfo.texi(,2983) copied into the beginning of each split Info output file, as is legally
texinfo.texi(,2984) necessary.  This location implies a human reading the manual using Info
texinfo.texi(,2985) does @emph{not} see this text (except when using the advanced Info
texinfo.texi(,2986) command @kbd{g *}).  Therefore, an explicit @code{@@insertcopying}
texinfo.texi(,2987) in the Top node makes it apparent to readers that the manual is free.
texinfo.texi(,2988) 
texinfo.texi(,2989) Similarly, the @code{@@copying} text is automatically included at the
texinfo.texi(,2990) beginning of each HTML output file, as an HTML comment.  Again, this
texinfo.texi(,2991) text is not visible (unless the reader views the HTML source).  And
texinfo.texi(,2992) therefore again, the @code{@@insertcopying} in the Top node is valuable
texinfo.texi(,2993) because it makes the copying permissions visible and thus promotes
texinfo.texi(,2994) freedom.
texinfo.texi(,2995) 
texinfo.texi(,2996) The permissions text defined by @code{@@copying} also appears
texinfo.texi(,2997) automatically at the beginning of the XML output file.
texinfo.texi(,2998) 
texinfo.texi(,2999) 
texinfo.texi(,3000) @node Titlepage & Copyright Page
texinfo.texi(,3001) @section Title and Copyright Pages
texinfo.texi(,3002) 
texinfo.texi(,3003) In hard copy output, the manual's name and author are usually printed on
texinfo.texi(,3004) a title page.  Copyright information is usually printed on the back of
texinfo.texi(,3005) the title page.
texinfo.texi(,3006) 
texinfo.texi(,3007) The title and copyright pages appear in the printed manual, but not in
texinfo.texi(,3008) the Info file.  Because of this, it is possible to use several slightly
texinfo.texi(,3009) obscure @TeX{} typesetting commands that cannot be used in an Info file.
texinfo.texi(,3010) In addition, this part of the beginning of a Texinfo file contains the
texinfo.texi(,3011) text of the copying permissions that appears in the printed manual.
texinfo.texi(,3012) 
texinfo.texi(,3013) @cindex Title page, for plain text
texinfo.texi(,3014) @cindex Copyright page, for plain text
texinfo.texi(,3015) You may wish to include titlepage-like information for plain text
texinfo.texi(,3016) output.  Simply place any such leading material between
texinfo.texi(,3017) @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
texinfo.texi(,3018) includes this when writing plain text (@samp{--no-headers}), along with
texinfo.texi(,3019) an @code{@@insertcopying}.
texinfo.texi(,3020) 
texinfo.texi(,3021) @menu
texinfo.texi(,3022) * titlepage::                   Create a title for the printed document.
texinfo.texi(,3023) * titlefont center sp::         The @code{@@titlefont}, @code{@@center},
texinfo.texi(,3024)                                   and @code{@@sp} commands.
texinfo.texi(,3025) * title subtitle author::       The @code{@@title}, @code{@@subtitle},
texinfo.texi(,3026)                                   and @code{@@author} commands.
texinfo.texi(,3027) * Copyright::                   How to write the copyright notice and
texinfo.texi(,3028)                                   include copying permissions.
texinfo.texi(,3029) * end titlepage::               Turn on page headings after the title and
texinfo.texi(,3030)                                   copyright pages.
texinfo.texi(,3031) * headings on off::             An option for turning headings on and off
texinfo.texi(,3032)                                   and double or single sided printing.
texinfo.texi(,3033) @end menu
texinfo.texi(,3034) 
texinfo.texi(,3035) 
texinfo.texi(,3036) @node titlepage
texinfo.texi(,3037) @subsection @code{@@titlepage}
texinfo.texi(,3038) @cindex Title page
texinfo.texi(,3039) @findex titlepage
texinfo.texi(,3040) 
texinfo.texi(,3041) Start the material for the title page and following copyright page
texinfo.texi(,3042) with @code{@@titlepage} on a line by itself and end it with
texinfo.texi(,3043) @code{@@end titlepage} on a line by itself.
texinfo.texi(,3044) 
texinfo.texi(,3045) The @code{@@end titlepage} command starts a new page and turns on page
texinfo.texi(,3046) numbering.  (@xref{Headings, , Page Headings}, for details about how to
texinfo.texi(,3047) generate page headings.)  All the material that you want to appear on
texinfo.texi(,3048) unnumbered pages should be put between the @code{@@titlepage} and
texinfo.texi(,3049) @code{@@end titlepage} commands.  You can force the table of contents to
texinfo.texi(,3050) appear there with the @code{@@setcontentsaftertitlepage} command
texinfo.texi(,3051) (@pxref{Contents}).
texinfo.texi(,3052) 
texinfo.texi(,3053) @findex page@r{, within @code{@@titlepage}}
texinfo.texi(,3054) By using the @code{@@page} command you can force a page break within the
texinfo.texi(,3055) region delineated by the @code{@@titlepage} and @code{@@end titlepage}
texinfo.texi(,3056) commands and thereby create more than one unnumbered page.  This is how
texinfo.texi(,3057) the copyright page is produced.  (The @code{@@titlepage} command might
texinfo.texi(,3058) perhaps have been better named the @code{@@titleandadditionalpages}
texinfo.texi(,3059) command, but that would have been rather long!)
texinfo.texi(,3060) 
texinfo.texi(,3061) When you write a manual about a computer program, you should write the
texinfo.texi(,3062) version of the program to which the manual applies on the title page.
texinfo.texi(,3063) If the manual changes more frequently than the program or is independent
texinfo.texi(,3064) of it, you should also include an edition number@footnote{We have found
texinfo.texi(,3065) that it is helpful to refer to versions of independent manuals as
texinfo.texi(,3066) `editions' and versions of programs as `versions'; otherwise, we find we
texinfo.texi(,3067) are liable to confuse each other in conversation by referring to both
texinfo.texi(,3068) the documentation and the software with the same words.} for the manual.
texinfo.texi(,3069) This helps readers keep track of which manual is for which version of
texinfo.texi(,3070) the program.  (The `Top' node should also contain this information; see
texinfo.texi(,3071) @ref{The Top Node}.)
texinfo.texi(,3072) 
texinfo.texi(,3073) Texinfo provides two main methods for creating a title page.  One method
texinfo.texi(,3074) uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
texinfo.texi(,3075) to generate a title page in which the words on the page are
texinfo.texi(,3076) centered.
texinfo.texi(,3077) 
texinfo.texi(,3078) The second method uses the @code{@@title}, @code{@@subtitle}, and
texinfo.texi(,3079) @code{@@author} commands to create a title page with black rules under
texinfo.texi(,3080) the title and author lines and the subtitle text set flush to the
texinfo.texi(,3081) right hand side of the page.  With this method, you do not specify any
texinfo.texi(,3082) of the actual formatting of the title page.  You specify the text
texinfo.texi(,3083) you want, and Texinfo does the formatting.
texinfo.texi(,3084) 
texinfo.texi(,3085) You may use either method, or you may combine them; see the examples in
texinfo.texi(,3086) the sections below.
texinfo.texi(,3087) 
texinfo.texi(,3088) @findex shorttitlepage
texinfo.texi(,3089) @cindex Bastard title page
texinfo.texi(,3090) @cindex Title page, bastard
texinfo.texi(,3091) For extremely simple applications, and for the bastard title page in
texinfo.texi(,3092) traditional book front matter, Texinfo also provides a command
texinfo.texi(,3093) @code{@@shorttitlepage} which takes the rest of the line as the title.
texinfo.texi(,3094) The argument is typeset on a page by itself and followed by a blank
texinfo.texi(,3095) page.
texinfo.texi(,3096) 
texinfo.texi(,3097) 
texinfo.texi(,3098) @node titlefont center sp
texinfo.texi(,3099) @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
texinfo.texi(,3100) @findex titlefont
texinfo.texi(,3101) @findex center
texinfo.texi(,3102) @findex sp @r{(titlepage line spacing)}
texinfo.texi(,3103) 
texinfo.texi(,3104) You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
texinfo.texi(,3105) commands to create a title page for a printed document.  (This is the
texinfo.texi(,3106) first of the two methods for creating a title page in Texinfo.)
texinfo.texi(,3107) 
texinfo.texi(,3108) Use the @code{@@titlefont} command to select a large font suitable for
texinfo.texi(,3109) the title itself.  You can use @code{@@titlefont} more than once if you
texinfo.texi(,3110) have an especially long title.
texinfo.texi(,3111) 
texinfo.texi(,3112) @need 700
texinfo.texi(,3113) For example:
texinfo.texi(,3114) 
texinfo.texi(,3115) @example
texinfo.texi(,3116) @@titlefont@{Texinfo@}
texinfo.texi(,3117) @end example
texinfo.texi(,3118) 
texinfo.texi(,3119) Use the @code{@@center} command at the beginning of a line to center
texinfo.texi(,3120) the remaining text on that line.  Thus,
texinfo.texi(,3121) 
texinfo.texi(,3122) @example
texinfo.texi(,3123) @@center @@titlefont@{Texinfo@}
texinfo.texi(,3124) @end example
texinfo.texi(,3125) 
texinfo.texi(,3126) @noindent
texinfo.texi(,3127) centers the title, which in this example is ``Texinfo'' printed
texinfo.texi(,3128) in the title font.
texinfo.texi(,3129) 
texinfo.texi(,3130) Use the @code{@@sp} command to insert vertical space.  For example:
texinfo.texi(,3131) 
texinfo.texi(,3132) @example
texinfo.texi(,3133) @@sp 2
texinfo.texi(,3134) @end example
texinfo.texi(,3135) 
texinfo.texi(,3136) @noindent
texinfo.texi(,3137) This inserts two blank lines on the printed page.  (@xref{sp, ,
texinfo.texi(,3138) @code{@@sp}}, for more information about the @code{@@sp}
texinfo.texi(,3139) command.)
texinfo.texi(,3140) 
texinfo.texi(,3141) A template for this method looks like this:
texinfo.texi(,3142) 
texinfo.texi(,3143) @example
texinfo.texi(,3144) @group
texinfo.texi(,3145) @@titlepage
texinfo.texi(,3146) @@sp 10
texinfo.texi(,3147) @@center @@titlefont@{@var{name-of-manual-when-printed}@}
texinfo.texi(,3148) @@sp 2
texinfo.texi(,3149) @@center @var{subtitle-if-any}
texinfo.texi(,3150) @@sp 2
texinfo.texi(,3151) @@center @var{author}
texinfo.texi(,3152) @dots{}
texinfo.texi(,3153) @@end titlepage
texinfo.texi(,3154) @end group
texinfo.texi(,3155) @end example
texinfo.texi(,3156) 
texinfo.texi(,3157) The spacing of the example fits an 8.5 by 11 inch manual.
texinfo.texi(,3158) 
texinfo.texi(,3159) 
texinfo.texi(,3160) @node title subtitle author
texinfo.texi(,3161) @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
texinfo.texi(,3162) @findex title
texinfo.texi(,3163) @findex subtitle
texinfo.texi(,3164) @findex author
texinfo.texi(,3165) 
texinfo.texi(,3166) You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
texinfo.texi(,3167) commands to create a title page in which the vertical and horizontal
texinfo.texi(,3168) spacing is done for you automatically.  This contrasts with the method
texinfo.texi(,3169) described in the previous section, in which the @code{@@sp} command is
texinfo.texi(,3170) needed to adjust vertical spacing.
texinfo.texi(,3171) 
texinfo.texi(,3172) Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
texinfo.texi(,3173) commands at the beginning of a line followed by the title, subtitle,
texinfo.texi(,3174) or author.
texinfo.texi(,3175) 
texinfo.texi(,3176) The @code{@@title} command produces a line in which the title is set
texinfo.texi(,3177) flush to the left-hand side of the page in a larger than normal font.
texinfo.texi(,3178) The title is underlined with a black rule.  Only a single line is
texinfo.texi(,3179) allowed; the @code{@@*} command may not be used to break the title into
texinfo.texi(,3180) two lines.  To handle very long titles, you may find it profitable to
texinfo.texi(,3181) use both @code{@@title} and @code{@@titlefont}; see the final example in
texinfo.texi(,3182) this section.
texinfo.texi(,3183) 
texinfo.texi(,3184) The @code{@@subtitle} command sets subtitles in a normal-sized font
texinfo.texi(,3185) flush to the right-hand side of the page.
texinfo.texi(,3186) 
texinfo.texi(,3187) The @code{@@author} command sets the names of the author or authors in
texinfo.texi(,3188) a middle-sized font flush to the left-hand side of the page on a line
texinfo.texi(,3189) near the bottom of the title page.  The names are underlined with a
texinfo.texi(,3190) black rule that is thinner than the rule that underlines the title.
texinfo.texi(,3191) (The black rule only occurs if the @code{@@author} command line is
texinfo.texi(,3192) followed by an @code{@@page} command line.)
texinfo.texi(,3193) 
texinfo.texi(,3194) There are two ways to use the @code{@@author} command: you can write
texinfo.texi(,3195) the name or names on the remaining part of the line that starts with
texinfo.texi(,3196) an @code{@@author} command:
texinfo.texi(,3197) 
texinfo.texi(,3198) @example
texinfo.texi(,3199) @@author by Jane Smith and John Doe
texinfo.texi(,3200) @end example
texinfo.texi(,3201) 
texinfo.texi(,3202) @noindent
texinfo.texi(,3203) or you can write the names one above each other by using two (or more)
texinfo.texi(,3204) @code{@@author} commands:
texinfo.texi(,3205) 
texinfo.texi(,3206) @example
texinfo.texi(,3207) @group
texinfo.texi(,3208) @@author Jane Smith
texinfo.texi(,3209) @@author John Doe
texinfo.texi(,3210) @end group
texinfo.texi(,3211) @end example
texinfo.texi(,3212) 
texinfo.texi(,3213) @noindent
texinfo.texi(,3214) (Only the bottom name is underlined with a black rule.)
texinfo.texi(,3215) 
texinfo.texi(,3216) @need 950
texinfo.texi(,3217) A template for this method looks like this:
texinfo.texi(,3218) 
texinfo.texi(,3219) @example
texinfo.texi(,3220) @group
texinfo.texi(,3221) @@titlepage
texinfo.texi(,3222) @@title @var{name-of-manual-when-printed}
texinfo.texi(,3223) @@subtitle @var{subtitle-if-any}
texinfo.texi(,3224) @@subtitle @var{second-subtitle}
texinfo.texi(,3225) @@author @var{author}
texinfo.texi(,3226) @@page
texinfo.texi(,3227) @dots{}
texinfo.texi(,3228) @@end titlepage
texinfo.texi(,3229) @end group
texinfo.texi(,3230) @end example
texinfo.texi(,3231) 
texinfo.texi(,3232) You may also combine the @code{@@titlefont} method described in the
texinfo.texi(,3233) previous section and @code{@@title} method described in this one.  This
texinfo.texi(,3234) may be useful if you have a very long title.  Here is a real-life example:
texinfo.texi(,3235) 
texinfo.texi(,3236) @example
texinfo.texi(,3237) @group
texinfo.texi(,3238) @@titlepage
texinfo.texi(,3239) @@titlefont@{GNU Software@}
texinfo.texi(,3240) @@sp 1
texinfo.texi(,3241) @@title for MS-Windows and MS-DOS
texinfo.texi(,3242) @@subtitle Edition @@value@{e@} for Release @@value@{cde@}
texinfo.texi(,3243) @@author by Daniel Hagerty, Melissa Weisshaus
texinfo.texi(,3244) @@author and Eli Zaretskii
texinfo.texi(,3245) @end group
texinfo.texi(,3246) @end example
texinfo.texi(,3247) 
texinfo.texi(,3248) @noindent
texinfo.texi(,3249) (The use of @code{@@value} here is explained in @ref{value Example}.
texinfo.texi(,3250) 
texinfo.texi(,3251) 
texinfo.texi(,3252) @node Copyright
texinfo.texi(,3253) @subsection Copyright Page
texinfo.texi(,3254) @cindex Copyright page
texinfo.texi(,3255) @cindex Printed permissions
texinfo.texi(,3256) @cindex Permissions, printed
texinfo.texi(,3257) 
texinfo.texi(,3258) By international treaty, the copyright notice for a book must be either
texinfo.texi(,3259) on the title page or on the back of the title page.  When the copyright
texinfo.texi(,3260) notice is on the back of the title page, that page is customarily not
texinfo.texi(,3261) numbered.  Therefore, in Texinfo, the information on the copyright page
texinfo.texi(,3262) should be within @code{@@titlepage} and @code{@@end titlepage}
texinfo.texi(,3263) commands.
texinfo.texi(,3264) 
texinfo.texi(,3265) @findex vskip @r{@TeX{} vertical skip}
texinfo.texi(,3266) @findex filll @r{@TeX{} dimension}
texinfo.texi(,3267) Use the @code{@@page} command to cause a page break.  To push the
texinfo.texi(,3268) copyright notice and the other text on the copyright page towards the
texinfo.texi(,3269) bottom of the page, use the following incantantion after @code{@@page}:
texinfo.texi(,3270) 
texinfo.texi(,3271) @example
texinfo.texi(,3272) @@vskip 0pt plus 1filll
texinfo.texi(,3273) @end example
texinfo.texi(,3274) 
texinfo.texi(,3275) @noindent
texinfo.texi(,3276) This is a @TeX{} command that is not supported by the Info formatting
texinfo.texi(,3277) commands.  The @code{@@vskip} command inserts whitespace.  The @samp{0pt
texinfo.texi(,3278) plus 1filll} means to put in zero points of mandatory whitespace, and as
texinfo.texi(,3279) much optional whitespace as needed to push the following text to the
texinfo.texi(,3280) bottom of the page.  Note the use of three @samp{l}s in the word
texinfo.texi(,3281) @samp{filll}; this is correct.
texinfo.texi(,3282) 
texinfo.texi(,3283) To insert the copyright text itself, write @code{@@insertcopying}
texinfo.texi(,3284) next (@pxref{Document Permissions}):
texinfo.texi(,3285) 
texinfo.texi(,3286) @example
texinfo.texi(,3287) @@insertcopying
texinfo.texi(,3288) @end example
texinfo.texi(,3289) 
texinfo.texi(,3290) Follow the copying text by the publisher, ISBN numbers, cover art
texinfo.texi(,3291) credits, and other such information.
texinfo.texi(,3292) 
texinfo.texi(,3293) Here is an example putting all this together:
texinfo.texi(,3294) 
texinfo.texi(,3295) @example
texinfo.texi(,3296) @@titlepage
texinfo.texi(,3297) @dots{}
texinfo.texi(,3298) @@page
texinfo.texi(,3299) @@vskip 0pt plus 1filll
texinfo.texi(,3300) @@insertcopying
texinfo.texi(,3301) 
texinfo.texi(,3302) Published by @dots{}
texinfo.texi(,3303) 
texinfo.texi(,3304) Cover art by @dots{}
texinfo.texi(,3305) @@end titlepage
texinfo.texi(,3306) @end example
texinfo.texi(,3307) 
texinfo.texi(,3308) 
texinfo.texi(,3309) @node end titlepage
texinfo.texi(,3310) @subsection Heading Generation
texinfo.texi(,3311) @findex end titlepage
texinfo.texi(,3312) @cindex Headings, page, begin to appear
texinfo.texi(,3313) @cindex Titlepage end starts headings
texinfo.texi(,3314) @cindex End titlepage starts headings
texinfo.texi(,3315) 
texinfo.texi(,3316) The @code{@@end titlepage} command must be written on a line by itself.
texinfo.texi(,3317) It not only marks the end of the title and copyright pages, but also
texinfo.texi(,3318) causes @TeX{} to start generating page headings and page numbers.
texinfo.texi(,3319) 
texinfo.texi(,3320) To repeat what is said elsewhere,  Texinfo has two standard page heading
texinfo.texi(,3321) formats, one for documents which are printed on one side of each sheet of paper
texinfo.texi(,3322) (single-sided printing), and the other for documents which are printed on both
texinfo.texi(,3323) sides of each sheet (double-sided printing).
texinfo.texi(,3324) You can specify these formats in different ways:
texinfo.texi(,3325) 
texinfo.texi(,3326) @itemize @bullet
texinfo.texi(,3327) @item
texinfo.texi(,3328) The conventional way is to write an @code{@@setchapternewpage} command
texinfo.texi(,3329) before the title page commands, and then have the @code{@@end
texinfo.texi(,3330) titlepage} command start generating page headings in the manner desired.
texinfo.texi(,3331) (@xref{setchapternewpage}.)
texinfo.texi(,3332) 
texinfo.texi(,3333) @item
texinfo.texi(,3334) Alternatively, you can use the @code{@@headings} command to prevent page
texinfo.texi(,3335) headings from being generated or to start them for either single or
texinfo.texi(,3336) double-sided printing.  (Write an @code{@@headings} command immediately
texinfo.texi(,3337) after the @code{@@end titlepage} command.  @xref{headings on off, , The
texinfo.texi(,3338) @code{@@headings} Command}, for more information.)@refill
texinfo.texi(,3339) 
texinfo.texi(,3340) @item
texinfo.texi(,3341) Or, you may specify your own page heading and footing format.
texinfo.texi(,3342) @xref{Headings, , Page Headings}, for detailed
texinfo.texi(,3343) information about page headings and footings.
texinfo.texi(,3344) @end itemize
texinfo.texi(,3345) 
texinfo.texi(,3346) Most documents are formatted with the standard single-sided or
texinfo.texi(,3347) double-sided format, using @code{@@setchapternewpage odd} for
texinfo.texi(,3348) double-sided printing and no @code{@@setchapternewpage} command for
texinfo.texi(,3349) single-sided printing.
texinfo.texi(,3350) 
texinfo.texi(,3351) 
texinfo.texi(,3352) @node headings on off
texinfo.texi(,3353) @subsection The @code{@@headings} Command
texinfo.texi(,3354) @findex headings
texinfo.texi(,3355) 
texinfo.texi(,3356) The @code{@@headings} command is rarely used.  It specifies what kind of
texinfo.texi(,3357) page headings and footings to print on each page.  Usually, this is
texinfo.texi(,3358) controlled by the @code{@@setchapternewpage} command.  You need the
texinfo.texi(,3359) @code{@@headings} command only if the @code{@@setchapternewpage} command
texinfo.texi(,3360) does not do what you want, or if you want to turn off pre-defined page
texinfo.texi(,3361) headings prior to defining your own.  Write an @code{@@headings} command
texinfo.texi(,3362) immediately after the @code{@@end titlepage} command.@refill
texinfo.texi(,3363) 
texinfo.texi(,3364) You can use @code{@@headings} as follows:@refill
texinfo.texi(,3365) 
texinfo.texi(,3366) @table @code
texinfo.texi(,3367) @item @@headings off
texinfo.texi(,3368) Turn off printing of page headings.@refill
texinfo.texi(,3369) 
texinfo.texi(,3370) @item @@headings single
texinfo.texi(,3371) Turn on page headings appropriate for single-sided printing.
texinfo.texi(,3372) @refill
texinfo.texi(,3373) 
texinfo.texi(,3374) @item @@headings double
texinfo.texi(,3375) @itemx @@headings on
texinfo.texi(,3376) Turn on page headings appropriate for double-sided printing.  The two
texinfo.texi(,3377) commands, @code{@@headings on} and @code{@@headings double}, are
texinfo.texi(,3378) synonymous.@refill
texinfo.texi(,3379) 
texinfo.texi(,3380) @item @@headings singleafter
texinfo.texi(,3381) @itemx @@headings doubleafter
texinfo.texi(,3382) Turn on @code{single} or @code{double} headings, respectively, after the
texinfo.texi(,3383) current page is output.
texinfo.texi(,3384) 
texinfo.texi(,3385) @item @@headings on
texinfo.texi(,3386) Turn on page headings: @code{single} if @samp{@@setchapternewpage
texinfo.texi(,3387) on}, @code{double} otherwise.
texinfo.texi(,3388) @end table
texinfo.texi(,3389) 
texinfo.texi(,3390) For example, suppose you write @code{@@setchapternewpage off} before the
texinfo.texi(,3391) @code{@@titlepage} command to tell @TeX{} to start a new chapter on the
texinfo.texi(,3392) same page as the end of the last chapter.  This command also causes
texinfo.texi(,3393) @TeX{} to typeset page headers for single-sided printing.  To cause
texinfo.texi(,3394) @TeX{} to typeset for double sided printing, write @code{@@headings
texinfo.texi(,3395) double} after the @code{@@end titlepage} command.
texinfo.texi(,3396) 
texinfo.texi(,3397) You can stop @TeX{} from generating any page headings at all by
texinfo.texi(,3398) writing @code{@@headings off} on a line of its own immediately after the
texinfo.texi(,3399) line containing the @code{@@end titlepage} command, like this:@refill
texinfo.texi(,3400) 
texinfo.texi(,3401) @example
texinfo.texi(,3402) @@end titlepage
texinfo.texi(,3403) @@headings off
texinfo.texi(,3404) @end example
texinfo.texi(,3405) 
texinfo.texi(,3406) @noindent
texinfo.texi(,3407) The @code{@@headings off} command overrides the @code{@@end titlepage}
texinfo.texi(,3408) command, which would otherwise cause @TeX{} to print page
texinfo.texi(,3409) headings.@refill
texinfo.texi(,3410) 
texinfo.texi(,3411) You can also specify your own style of page heading and footing.
texinfo.texi(,3412) @xref{Headings, , Page Headings}, for more information.@refill
texinfo.texi(,3413) 
texinfo.texi(,3414) 
texinfo.texi(,3415) @node The Top Node
texinfo.texi(,3416) @section The `Top' Node and Master Menu
texinfo.texi(,3417) @cindex Top node
texinfo.texi(,3418) @cindex Node, `Top'
texinfo.texi(,3419) 
texinfo.texi(,3420) The `Top' node is the node in which a reader enters an Info manual.  As
texinfo.texi(,3421) such, it should begin with the @code{@@insertcopying} command
texinfo.texi(,3422) (@pxref{Document Permissions}) to provide a brief description of the
texinfo.texi(,3423) manual (including the version number) and copying permissions, and end
texinfo.texi(,3424) with a master menu for the whole manual.  Of course you should include
texinfo.texi(,3425) any other general information you feel a reader would find helpful.
texinfo.texi(,3426) 
texinfo.texi(,3427) @findex top
texinfo.texi(,3428) It is also conventional to write an @code{@@top} sectioning command line
texinfo.texi(,3429) containing the title of the document immediately after the @code{@@node
texinfo.texi(,3430) Top} line (@pxref{makeinfo top command, , The @code{@@top} Sectioning
texinfo.texi(,3431) Command}).
texinfo.texi(,3432) 
texinfo.texi(,3433) The contents of the `Top' node should appear only in the online output;
texinfo.texi(,3434) none of it should appear in printed output, so enclose it between
texinfo.texi(,3435) @code{@@ifnottex} and @code{@@end ifnottex} commands.  (@TeX{} does not
texinfo.texi(,3436) print either an @code{@@node} line or a menu; they appear only in Info;
texinfo.texi(,3437) strictly speaking, you are not required to enclose these parts between
texinfo.texi(,3438) @code{@@ifnottex} and @code{@@end ifnottext}, but it is simplest to do
texinfo.texi(,3439) so.  @xref{Conditionals, , Conditionally Visible Text}.)
texinfo.texi(,3440) 
texinfo.texi(,3441) @menu
texinfo.texi(,3442) * Top Node Example::            
texinfo.texi(,3443) * Master Menu Parts::           
texinfo.texi(,3444) @end menu
texinfo.texi(,3445) 
texinfo.texi(,3446) 
texinfo.texi(,3447) @node Top Node Example
texinfo.texi(,3448) @subsection Top Node Example
texinfo.texi(,3449) 
texinfo.texi(,3450) @cindex Top node example
texinfo.texi(,3451) 
texinfo.texi(,3452) Here is an example of a Top node.
texinfo.texi(,3453) 
texinfo.texi(,3454) @example
texinfo.texi(,3455) @group
texinfo.texi(,3456) @@ifnottex
texinfo.texi(,3457) @@node Top
texinfo.texi(,3458) @@top Sample Title
texinfo.texi(,3459) 
texinfo.texi(,3460) @@insertcopying
texinfo.texi(,3461) @end group
texinfo.texi(,3462) 
texinfo.texi(,3463) Additional general information.
texinfo.texi(,3464) 
texinfo.texi(,3465) @group
texinfo.texi(,3466) @@menu
texinfo.texi(,3467) * First Chapter::
texinfo.texi(,3468) * Second Chapter::
texinfo.texi(,3469) @dots{}
texinfo.texi(,3470) * Index::
texinfo.texi(,3471) @end group
texinfo.texi(,3472) @@end menu
texinfo.texi(,3473) @end example
texinfo.texi(,3474) 
texinfo.texi(,3475) 
texinfo.texi(,3476) @node Master Menu Parts
texinfo.texi(,3477) @subsection Parts of a Master Menu
texinfo.texi(,3478) @cindex Master menu
texinfo.texi(,3479) @cindex Menu, master
texinfo.texi(,3480) @cindex Parts of a master menu
texinfo.texi(,3481) 
texinfo.texi(,3482) A @dfn{master menu} is a detailed main menu listing all the nodes in a
texinfo.texi(,3483) file.
texinfo.texi(,3484) 
texinfo.texi(,3485) A master menu is enclosed in @code{@@menu} and @code{@@end menu}
texinfo.texi(,3486) commands and does not appear in the printed document.
texinfo.texi(,3487) 
texinfo.texi(,3488) Generally, a master menu is divided into parts.
texinfo.texi(,3489) 
texinfo.texi(,3490) @itemize @bullet
texinfo.texi(,3491) @item
texinfo.texi(,3492) The first part contains the major nodes in the Texinfo file: the nodes
texinfo.texi(,3493) for the chapters, chapter-like sections, and the appendices.
texinfo.texi(,3494) 
texinfo.texi(,3495) @item
texinfo.texi(,3496) The second part contains nodes for the indices.
texinfo.texi(,3497) 
texinfo.texi(,3498) @item
texinfo.texi(,3499) The third and subsequent parts contain a listing of the other, lower
texinfo.texi(,3500) level nodes, often ordered by chapter.  This way, rather than go
texinfo.texi(,3501) through an intermediary menu, an inquirer can go directly to a
texinfo.texi(,3502) particular node when searching for specific information.  These menu
texinfo.texi(,3503) items are not required; add them if you think they are a
texinfo.texi(,3504) convenience.  If you do use them, put @code{@@detailmenu} before the
texinfo.texi(,3505) first one, and @code{@@end detailmenu} after the last; otherwise,
texinfo.texi(,3506) @code{makeinfo} will get confused.
texinfo.texi(,3507) @end itemize
texinfo.texi(,3508) 
texinfo.texi(,3509) Each section in the menu can be introduced by a descriptive line.  So
texinfo.texi(,3510) long as the line does not begin with an asterisk, it will not be
texinfo.texi(,3511) treated as a menu entry.  (@xref{Writing a Menu}, for more
texinfo.texi(,3512) information.)
texinfo.texi(,3513) 
texinfo.texi(,3514) For example, the master menu for this manual looks like the following
texinfo.texi(,3515) (but has many more entries):
texinfo.texi(,3516) 
texinfo.texi(,3517) @example
texinfo.texi(,3518) @group
texinfo.texi(,3519) @@menu
texinfo.texi(,3520) * Copying Conditions::  Your rights.
texinfo.texi(,3521) * Overview::            Texinfo in brief.
texinfo.texi(,3522) @dots{}
texinfo.texi(,3523) @end group
texinfo.texi(,3524) @group
texinfo.texi(,3525) * Command and Variable Index::
texinfo.texi(,3526) * Concept Index::       
texinfo.texi(,3527) @end group
texinfo.texi(,3528) 
texinfo.texi(,3529) @group
texinfo.texi(,3530) @@detailmenu
texinfo.texi(,3531)  --- The Detailed Node Listing ---
texinfo.texi(,3532) 
texinfo.texi(,3533) Overview of Texinfo
texinfo.texi(,3534) 
texinfo.texi(,3535) * Reporting Bugs:: @dots{}
texinfo.texi(,3536) @dots{}
texinfo.texi(,3537) @end group
texinfo.texi(,3538) 
texinfo.texi(,3539) @group
texinfo.texi(,3540) Beginning a Texinfo File
texinfo.texi(,3541) 
texinfo.texi(,3542) * Sample Beginning:: @dots{}
texinfo.texi(,3543) @dots{}
texinfo.texi(,3544) @@end detailmenu
texinfo.texi(,3545) @@end menu
texinfo.texi(,3546) @end group
texinfo.texi(,3547) @end example
texinfo.texi(,3548) 
texinfo.texi(,3549) 
texinfo.texi(,3550) @node Global Document Commands
texinfo.texi(,3551) @section Global Document Commands
texinfo.texi(,3552) @cindex Global Document Commands
texinfo.texi(,3553) 
texinfo.texi(,3554) Besides the basic commands mentioned in the previous sections, here are
texinfo.texi(,3555) additional commands which affect the document as a whole.  They are
texinfo.texi(,3556) generally all given before the Top node, if they are given at all.
texinfo.texi(,3557) 
texinfo.texi(,3558) @menu
texinfo.texi(,3559) * documentdescription::         Document summary for the HTML output.
texinfo.texi(,3560) * setchapternewpage::           Start chapters on right-hand pages.
texinfo.texi(,3561) * paragraphindent::             Specify paragraph indentation.
texinfo.texi(,3562) * exampleindent::               Specify environment indentation.
texinfo.texi(,3563) @end menu
texinfo.texi(,3564) 
texinfo.texi(,3565) 
texinfo.texi(,3566) @node documentdescription
texinfo.texi(,3567) @subsection @code{@@documentdescription}: Summary text
texinfo.texi(,3568) @cindex Document description
texinfo.texi(,3569) @cindex Description of document
texinfo.texi(,3570) @cindex Summary of document
texinfo.texi(,3571) @cindex Abstract of document
texinfo.texi(,3572) @cindex <meta> HTML tag, and document description
texinfo.texi(,3573) @findex documentdescription
texinfo.texi(,3574) 
texinfo.texi(,3575) When producing HTML output for a document, @command{makeinfo} writes a
texinfo.texi(,3576) @samp{<meta>} element in the @samp{<head>} to give some idea of the
texinfo.texi(,3577) content of the document.  By default, this @dfn{description} is the title
texinfo.texi(,3578) of the document, taken from the @code{@@settitle} command
texinfo.texi(,3579) (@pxref{settitle}).  To change this, use the @code{@@documentdescription}
texinfo.texi(,3580) environment, as in:
texinfo.texi(,3581) 
texinfo.texi(,3582) @example
texinfo.texi(,3583) @@documentdescription
texinfo.texi(,3584) descriptive text.
texinfo.texi(,3585) @@end documentdescription
texinfo.texi(,3586) @end example
texinfo.texi(,3587) 
texinfo.texi(,3588) @noindent
texinfo.texi(,3589) This will produce the following output in the @samp{<head>} of the HTML:
texinfo.texi(,3590) 
texinfo.texi(,3591) @example
texinfo.texi(,3592) <meta name=description content="descriptive text.">
texinfo.texi(,3593) @end example
texinfo.texi(,3594) 
texinfo.texi(,3595) @code{@@documentdescription} must be specified before the first node of
texinfo.texi(,3596) the document.
texinfo.texi(,3597) 
texinfo.texi(,3598) 
texinfo.texi(,3599) @node setchapternewpage
texinfo.texi(,3600) @subsection @code{@@setchapternewpage}: 
texinfo.texi(,3601) @cindex Starting chapters
texinfo.texi(,3602) @cindex Pages, starting odd
texinfo.texi(,3603) @findex setchapternewpage
texinfo.texi(,3604) 
texinfo.texi(,3605) In an officially bound book, text is usually printed on both sides of
texinfo.texi(,3606) the paper, chapters start on right-hand pages, and right-hand pages have
texinfo.texi(,3607) odd numbers.  But in short reports, text often is printed only on one
texinfo.texi(,3608) side of the paper.  Also in short reports, chapters sometimes do not
texinfo.texi(,3609) start on new pages, but are printed on the same page as the end of the
texinfo.texi(,3610) preceding chapter, after a small amount of vertical whitespace.
texinfo.texi(,3611) 
texinfo.texi(,3612) You can use the @code{@@setchapternewpage} command with various
texinfo.texi(,3613) arguments to specify how @TeX{} should start chapters and whether it
texinfo.texi(,3614) should format headers for printing on one or both sides of the paper
texinfo.texi(,3615) (single-sided or double-sided printing).
texinfo.texi(,3616) 
texinfo.texi(,3617) Write the @code{@@setchapternewpage} command at the beginning of a
texinfo.texi(,3618) line followed by its argument.
texinfo.texi(,3619) 
texinfo.texi(,3620) For example, you would write the following to cause each chapter to
texinfo.texi(,3621) start on a fresh odd-numbered page:
texinfo.texi(,3622) 
texinfo.texi(,3623) @example
texinfo.texi(,3624) @@setchapternewpage odd
texinfo.texi(,3625) @end example
texinfo.texi(,3626) 
texinfo.texi(,3627) You can specify one of three alternatives with the
texinfo.texi(,3628) @code{@@setchapternewpage} command:
texinfo.texi(,3629) 
texinfo.texi(,3630) @table @asis
texinfo.texi(,3631) 
texinfo.texi(,3632) @item @code{@@setchapternewpage off}
texinfo.texi(,3633) Cause @TeX{} to typeset a new chapter on the same page as the last
texinfo.texi(,3634) chapter, after skipping some vertical whitespace.  Also, cause @TeX{} to
texinfo.texi(,3635) format page headers for single-sided printing.
texinfo.texi(,3636) 
texinfo.texi(,3637) @item @code{@@setchapternewpage on}
texinfo.texi(,3638) Cause @TeX{} to start new chapters on new pages and to format page
texinfo.texi(,3639) headers for single-sided printing.  This is the form most often used for
texinfo.texi(,3640) short reports or personal printing. This is the default.
texinfo.texi(,3641) 
texinfo.texi(,3642) @item @code{@@setchapternewpage odd}
texinfo.texi(,3643) Cause @TeX{} to start new chapters on new, odd-numbered pages
texinfo.texi(,3644) (right-handed pages) and to typeset for double-sided printing.  This is
texinfo.texi(,3645) the form most often used for books and manuals.
texinfo.texi(,3646) @end table
texinfo.texi(,3647) 
texinfo.texi(,3648) Texinfo does not have an @code{@@setchapternewpage even} command,
texinfo.texi(,3649) because there is no printing tradition of starting chapters or books on
texinfo.texi(,3650) an even-numbered page.
texinfo.texi(,3651) 
texinfo.texi(,3652) If you don't like the default headers that @code{@@setchapternewpage}
texinfo.texi(,3653) sets, you can explicit control them with the @code{@@headings} command.
texinfo.texi(,3654) @xref{headings on off, , The @code{@@headings} Command}.
texinfo.texi(,3655) 
texinfo.texi(,3656) At the beginning of a manual or book, pages are not numbered---for
texinfo.texi(,3657) example, the title and copyright pages of a book are not numbered.  By
texinfo.texi(,3658) convention, table of contents and frontmatter pages are numbered with
texinfo.texi(,3659) roman numerals and not in sequence with the rest of the document.
texinfo.texi(,3660) 
texinfo.texi(,3661) Since an Info file does not have pages, the @code{@@setchapternewpage}
texinfo.texi(,3662) command has no effect on it.
texinfo.texi(,3663) 
texinfo.texi(,3664) We recommend not including any @code{@@setchapternewpage} command in
texinfo.texi(,3665) your manual sources at all, since the desired output is not intrinsic to
texinfo.texi(,3666) the document.  For a particular hard copy run, if you don't want the
texinfo.texi(,3667) default option (no blank pages, same headers on all pages) use the
texinfo.texi(,3668) @option{--texinfo} option to @command{texi2dvi} to specify the output
texinfo.texi(,3669) you want.
texinfo.texi(,3670) 
texinfo.texi(,3671) 
texinfo.texi(,3672) @node paragraphindent
texinfo.texi(,3673) @subsection Paragraph Indenting
texinfo.texi(,3674) @cindex Indenting paragraphs, control of
texinfo.texi(,3675) @cindex Paragraph indentation control
texinfo.texi(,3676) @findex paragraphindent
texinfo.texi(,3677) 
texinfo.texi(,3678) The Texinfo processors may insert whitespace at the beginning of the
texinfo.texi(,3679) first line of each paragraph, thereby indenting that paragraph.  You can
texinfo.texi(,3680) use the @code{@@paragraphindent} command to specify this indentation.
texinfo.texi(,3681) Write an @code{@@paragraphindent} command at the beginning of a line
texinfo.texi(,3682) followed by either @samp{asis} or a number:
texinfo.texi(,3683) 
texinfo.texi(,3684) @example
texinfo.texi(,3685) @@paragraphindent @var{indent}
texinfo.texi(,3686) @end example
texinfo.texi(,3687) 
texinfo.texi(,3688) The indentation is according to the value of @var{indent}:
texinfo.texi(,3689) 
texinfo.texi(,3690) @table @asis
texinfo.texi(,3691) @item @code{asis}
texinfo.texi(,3692) Do not change the existing indentation (not implemented in @TeX{}).
texinfo.texi(,3693) 
texinfo.texi(,3694) @item @code{none}
texinfo.texi(,3695) @itemx 0
texinfo.texi(,3696) Omit all indentation.
texinfo.texi(,3697) 
texinfo.texi(,3698) @item @var{n}
texinfo.texi(,3699) Indent by @var{n} space characters in Info output, by @var{n} ems in
texinfo.texi(,3700) @TeX{}.
texinfo.texi(,3701) 
texinfo.texi(,3702) @end table
texinfo.texi(,3703) 
texinfo.texi(,3704) The default value of @var{indent} is 3.  @code{@@paragraphindent} is
texinfo.texi(,3705) ignored for HTML output.
texinfo.texi(,3706) 
texinfo.texi(,3707) It is best to write the @code{@@paragraphindent} command before the
texinfo.texi(,3708) end-of-header line at the beginning of a Texinfo file, so the region
texinfo.texi(,3709) formatting commands indent paragraphs as specified.  @xref{Start of
texinfo.texi(,3710) Header}.
texinfo.texi(,3711) 
texinfo.texi(,3712) A peculiarity of the @code{texinfo-format-buffer} and
texinfo.texi(,3713) @code{texinfo-format-region} commands is that they do not indent (nor
texinfo.texi(,3714) fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
texinfo.texi(,3715) @xref{Refilling Paragraphs}, for further information.
texinfo.texi(,3716) 
texinfo.texi(,3717) 
texinfo.texi(,3718) @node exampleindent
texinfo.texi(,3719) @subsection @code{@@exampleindent}: Environment Indenting
texinfo.texi(,3720) @cindex Indenting environments
texinfo.texi(,3721) @cindex Environment indentation
texinfo.texi(,3722) @cindex Example indentation
texinfo.texi(,3723) @findex exampleindent
texinfo.texi(,3724) 
texinfo.texi(,3725) The Texinfo processors indent each line of @code{@@example} and similar
texinfo.texi(,3726) environments.  You can use the @code{@@exampleindent} command to specify
texinfo.texi(,3727) this indentation.  Write an @code{@@exampleindent} command at the
texinfo.texi(,3728) beginning of a line followed by either @samp{asis} or a number:
texinfo.texi(,3729) 
texinfo.texi(,3730) @example
texinfo.texi(,3731) @@exampleindent @var{indent}
texinfo.texi(,3732) @end example
texinfo.texi(,3733) 
texinfo.texi(,3734) The indentation is according to the value of @var{indent}:
texinfo.texi(,3735) 
texinfo.texi(,3736) @table @asis
texinfo.texi(,3737) @item @code{asis}
texinfo.texi(,3738) Do not change the existing indentation (not implemented in @TeX{}).
texinfo.texi(,3739) 
texinfo.texi(,3740) @item 0
texinfo.texi(,3741) Omit all indentation.
texinfo.texi(,3742) 
texinfo.texi(,3743) @item @var{n}
texinfo.texi(,3744) Indent environments by @var{n} space characters in Info output, by
texinfo.texi(,3745) @var{n} ems in @TeX{}.
texinfo.texi(,3746) 
texinfo.texi(,3747) @end table
texinfo.texi(,3748) 
texinfo.texi(,3749) The default value of @var{indent} is 5.  @code{@@exampleindent} is
texinfo.texi(,3750) ignored for HTML output.
texinfo.texi(,3751) 
texinfo.texi(,3752) It is best to write the @code{@@exampleindent} command before the
texinfo.texi(,3753) end-of-header line at the beginning of a Texinfo file, so the region
texinfo.texi(,3754) formatting commands indent paragraphs as specified.  @xref{Start of
texinfo.texi(,3755) Header}.
texinfo.texi(,3756) 
texinfo.texi(,3757) 
texinfo.texi(,3758) @node Software Copying Permissions
texinfo.texi(,3759) @section Software Copying Permissions
texinfo.texi(,3760) @cindex Software copying permissions
texinfo.texi(,3761) @cindex Copying software
texinfo.texi(,3762) @cindex Distribution
texinfo.texi(,3763) @cindex License agreement
texinfo.texi(,3764) 
texinfo.texi(,3765) If the Texinfo file has a section containing the ``General Public
texinfo.texi(,3766) License'' and the distribution information and a warranty disclaimer for
texinfo.texi(,3767) the software that is documented, we recommend placing this right after
texinfo.texi(,3768) the `Top' node.  The General Public License is very important to Project
texinfo.texi(,3769) GNU software.  It ensures that you and others will continue to have a
texinfo.texi(,3770) right to use and share the software.
texinfo.texi(,3771) 
texinfo.texi(,3772) The copying and distribution information and the disclaimer are followed
texinfo.texi(,3773) by an introduction or else by the first chapter of the manual.
texinfo.texi(,3774) 
texinfo.texi(,3775) @cindex Introduction, as part of file
texinfo.texi(,3776) Although an introduction is not a required part of a Texinfo file, it
texinfo.texi(,3777) is very helpful.  Ideally, it should state clearly and concisely what
texinfo.texi(,3778) the file is about and who would be interested in reading it.  In
texinfo.texi(,3779) general, an introduction would follow the licensing and distribution
texinfo.texi(,3780) information, although sometimes people put it earlier in the document.
texinfo.texi(,3781) 
texinfo.texi(,3782) 
texinfo.texi(,3783) @node Ending a File
texinfo.texi(,3784) @chapter Ending a Texinfo File
texinfo.texi(,3785) @cindex Ending a Texinfo file
texinfo.texi(,3786) @cindex Texinfo file ending
texinfo.texi(,3787) @cindex File ending
texinfo.texi(,3788) @findex bye
texinfo.texi(,3789) 
texinfo.texi(,3790) The end of a Texinfo file should include commands to create indices and
texinfo.texi(,3791) (perhaps) to generate both the full and summary tables of contents.
texinfo.texi(,3792) Finally, it must include the @code{@@bye} command that marks the last
texinfo.texi(,3793) line to be processed.
texinfo.texi(,3794) 
texinfo.texi(,3795) @need 700
texinfo.texi(,3796) For example:
texinfo.texi(,3797) 
texinfo.texi(,3798) @example
texinfo.texi(,3799) @@node Index
texinfo.texi(,3800) @@unnumbered Index
texinfo.texi(,3801) 
texinfo.texi(,3802) @@printindex cp
texinfo.texi(,3803) 
texinfo.texi(,3804) @@shortcontents
texinfo.texi(,3805) @@contents
texinfo.texi(,3806) 
texinfo.texi(,3807) @@bye
texinfo.texi(,3808) @end example
texinfo.texi(,3809) 
texinfo.texi(,3810) @menu
texinfo.texi(,3811) * Printing Indices & Menus::    How to print an index in hardcopy and
texinfo.texi(,3812)                                   generate index menus in Info.
texinfo.texi(,3813) * Contents::                    How to create a table of contents.
texinfo.texi(,3814) * File End::                    How to mark the end of a file.
texinfo.texi(,3815) @end menu
texinfo.texi(,3816) 
texinfo.texi(,3817) 
texinfo.texi(,3818) @node Printing Indices & Menus
texinfo.texi(,3819) @section Printing Indices and Menus
texinfo.texi(,3820) @findex printindex
texinfo.texi(,3821) @cindex Printing an index
texinfo.texi(,3822) @cindex Indices, printing and menus
texinfo.texi(,3823) @cindex Generating menus with indices
texinfo.texi(,3824) @cindex Menus generated with indices
texinfo.texi(,3825) 
texinfo.texi(,3826) To print an index means to include it as part of a manual or Info file.
texinfo.texi(,3827) This does not happen automatically just because you use @code{@@cindex}
texinfo.texi(,3828) or other index-entry generating commands in the Texinfo file; those just
texinfo.texi(,3829) cause the raw data for the index to be accumulated.  To generate an
texinfo.texi(,3830) index, you must include the @code{@@printindex} command at the place in
texinfo.texi(,3831) the document where you want the index to appear.  Also, as part of the
texinfo.texi(,3832) process of creating a printed manual, you must run a program called
texinfo.texi(,3833) @code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
texinfo.texi(,3834) sorted index file.  The sorted index file is what is actually used to
texinfo.texi(,3835) print the index.
texinfo.texi(,3836) 
texinfo.texi(,3837) Texinfo offers six separate types of predefined index, each with a
texinfo.texi(,3838) two-letter abbreviation, as illustrated in the following table.
texinfo.texi(,3839) However, you may merge indices (@pxref{Combining Indices}) or define
texinfo.texi(,3840) your own indices (@pxref{New Indices}).
texinfo.texi(,3841) 
texinfo.texi(,3842) Here are the predefined indices, their abbreviations, and the
texinfo.texi(,3843) corresponding index entry commands:
texinfo.texi(,3844) 
texinfo.texi(,3845) @table @samp
texinfo.texi(,3846) @item cp
texinfo.texi(,3847) concept index (@code{@@cindex})
texinfo.texi(,3848) @item fn
texinfo.texi(,3849) function index (@code{@@findex})
texinfo.texi(,3850) @item vr
texinfo.texi(,3851) variable index (@code{@@index})
texinfo.texi(,3852) @item ky
texinfo.texi(,3853) key index (@code{@@kindex})
texinfo.texi(,3854) @item pg
texinfo.texi(,3855) program index (@code{@@pindex})
texinfo.texi(,3856) @item tp
texinfo.texi(,3857) data type index (@code{@@tindex})
texinfo.texi(,3858) @end table
texinfo.texi(,3859) 
texinfo.texi(,3860) The @code{@@printindex} command takes a two-letter index abbreviation,
texinfo.texi(,3861) reads the corresponding sorted index file and formats it appropriately
texinfo.texi(,3862) into an index.
texinfo.texi(,3863) 
texinfo.texi(,3864) The @code{@@printindex} command does not generate a chapter heading for
texinfo.texi(,3865) the index.  Consequently, you should precede the @code{@@printindex}
texinfo.texi(,3866) command with a suitable section or chapter command (usually
texinfo.texi(,3867) @code{@@appendix} or @code{@@unnumbered}) to supply the chapter heading
texinfo.texi(,3868) and put the index into the table of contents.  Precede the
texinfo.texi(,3869) @code{@@unnumbered} command with an @code{@@node} line.
texinfo.texi(,3870) 
texinfo.texi(,3871) For example:
texinfo.texi(,3872) 
texinfo.texi(,3873) @smallexample
texinfo.texi(,3874) @group
texinfo.texi(,3875) @@node Variable Index
texinfo.texi(,3876) @@unnumbered Variable Index
texinfo.texi(,3877) 
texinfo.texi(,3878) @@printindex vr
texinfo.texi(,3879) @end group
texinfo.texi(,3880) 
texinfo.texi(,3881) @group
texinfo.texi(,3882) @@node Concept Index
texinfo.texi(,3883) @@unnumbered Concept Index
texinfo.texi(,3884) 
texinfo.texi(,3885) @@printindex cp
texinfo.texi(,3886) @end group
texinfo.texi(,3887) @end smallexample
texinfo.texi(,3888) 
texinfo.texi(,3889) @noindent
texinfo.texi(,3890) 
texinfo.texi(,3891) We recommend placing the concept index last, since that makes it easiest
texinfo.texi(,3892) to find.  We also recommend having a single index whenever possible,
texinfo.texi(,3893) since then readers have only one place to look (@pxref{Combining Indices}).
texinfo.texi(,3894) 
texinfo.texi(,3895) 
texinfo.texi(,3896) @node Contents
texinfo.texi(,3897) @section Generating a Table of Contents
texinfo.texi(,3898) @cindex Table of contents
texinfo.texi(,3899) @cindex Contents, Table of
texinfo.texi(,3900) @cindex Short table of contents
texinfo.texi(,3901) @findex contents
texinfo.texi(,3902) @findex summarycontents
texinfo.texi(,3903) @findex shortcontents
texinfo.texi(,3904) 
texinfo.texi(,3905) The @code{@@chapter}, @code{@@section}, and other structuring commands
texinfo.texi(,3906) supply the information to make up a table of contents, but they do not
texinfo.texi(,3907) cause an actual table to appear in the manual.  To do this, you must use
texinfo.texi(,3908) the @code{@@contents} and/or @code{@@summarycontents} command(s).
texinfo.texi(,3909) 
texinfo.texi(,3910) @table @code
texinfo.texi(,3911) @item @@contents
texinfo.texi(,3912) Generate a table of contents in a printed manual, including all
texinfo.texi(,3913) chapters, sections, subsections, etc., as well as appendices and
texinfo.texi(,3914) unnumbered chapters.  Headings generated by the @code{@@heading}
texinfo.texi(,3915) series of commands do not appear in the table of contents.
texinfo.texi(,3916) 
texinfo.texi(,3917) @item @@shortcontents
texinfo.texi(,3918) @itemx @@summarycontents
texinfo.texi(,3919) (@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
texinfo.texi(,3920) 
texinfo.texi(,3921) Generate a short or summary table of contents that lists only the
texinfo.texi(,3922) chapters, appendices, and unnumbered chapters.  Sections, subsections
texinfo.texi(,3923) and subsubsections are omitted.  Only a long manual needs a short table
texinfo.texi(,3924) of contents in addition to the full table of contents.
texinfo.texi(,3925) 
texinfo.texi(,3926) @end table
texinfo.texi(,3927) 
texinfo.texi(,3928) Both contents commands should be written on a line by themselves.
texinfo.texi(,3929) The contents commands automatically generate a chapter-like heading at
texinfo.texi(,3930) the top of the first table of contents page, so don't include any
texinfo.texi(,3931) sectioning command such as @code{@@unnumbered} before them.
texinfo.texi(,3932) 
texinfo.texi(,3933) Since an Info file uses menus instead of tables of contents, the Info
texinfo.texi(,3934) formatting commands ignore the contents commands.  But the contents are
texinfo.texi(,3935) included in plain text output (generated by @code{makeinfo
texinfo.texi(,3936) --no-headers}), unless @code{makeinfo} is writing its output to standard
texinfo.texi(,3937) output.
texinfo.texi(,3938) 
texinfo.texi(,3939) When @code{makeinfo} writes a short table of contents while producing
texinfo.texi(,3940) html output, the links in the short table of contents point to
texinfo.texi(,3941) corresponding entries in the full table of contents rather than the text
texinfo.texi(,3942) of the document. The links in the full table of contents point to the
texinfo.texi(,3943) main text of the document.
texinfo.texi(,3944) 
texinfo.texi(,3945) The contents commands can be placed either at the very end of the file,
texinfo.texi(,3946) after any indices (see the previous section) and just before the
texinfo.texi(,3947) @code{@@bye} (see the next section), or near the beginning of the file,
texinfo.texi(,3948) after the @code{@@end titlepage} (@pxref{titlepage}).  The advantage to
texinfo.texi(,3949) the former is that then the contents output is always up to date,
texinfo.texi(,3950) because it reflects the processing just done.  The advantage to the
texinfo.texi(,3951) latter is that the contents are printed in the proper place, thus you do
texinfo.texi(,3952) not need to rearrange the DVI file with @command{dviselect} or shuffle
texinfo.texi(,3953) paper.
texinfo.texi(,3954) 
texinfo.texi(,3955) @findex setcontentsaftertitlepage
texinfo.texi(,3956) @findex setshortcontentsaftertitlepage
texinfo.texi(,3957) @cindex Contents, after title page
texinfo.texi(,3958) @cindex Table of contents, after title page
texinfo.texi(,3959) As an author, you can put the contents commands wherever you prefer.
texinfo.texi(,3960) But if you are a user simply printing a manual, you may wish to print
texinfo.texi(,3961) the contents after the title page even if the author put the contents
texinfo.texi(,3962) commands at the end of the document (as is the case in most existing
texinfo.texi(,3963) Texinfo documents, at this writing).  You can do this by specifying
texinfo.texi(,3964) @code{@@setcontentsaftertitlepage} and/or
texinfo.texi(,3965) @code{@@setshortcontentsaftertitlepage}.  The first prints only the main
texinfo.texi(,3966) contents after the @code{@@end titlepage}; the second prints both the
texinfo.texi(,3967) short contents and the main contents.  In either case, any subsequent
texinfo.texi(,3968) @code{@@contents} or @code{@@shortcontents} is ignored (unless no
texinfo.texi(,3969) @code{@@end titlepage} is ever encountered).
texinfo.texi(,3970) 
texinfo.texi(,3971) You need to include the @code{@@set@dots{}contentsaftertitlepage}
texinfo.texi(,3972) commands early in the document (just after @code{@@setfilename}, for
texinfo.texi(,3973) example).  We recommend using @command{texi2dvi} (@pxref{Format with
texinfo.texi(,3974) texi2dvi}) to specify this without altering the source file at all.  For
texinfo.texi(,3975) example:
texinfo.texi(,3976) @example
texinfo.texi(,3977) texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
texinfo.texi(,3978) @end example
texinfo.texi(,3979) 
texinfo.texi(,3980) 
texinfo.texi(,3981) @node File End
texinfo.texi(,3982) @section @code{@@bye} File Ending
texinfo.texi(,3983) @findex bye
texinfo.texi(,3984) 
texinfo.texi(,3985) An @code{@@bye} command terminates @TeX{} or Info formatting.  None of
texinfo.texi(,3986) the formatting commands reading anything following @code{@@bye}.  The
texinfo.texi(,3987) @code{@@bye} command should be on a line by itself.
texinfo.texi(,3988) 
texinfo.texi(,3989) If you wish, you may follow the @code{@@bye} line with notes. These
texinfo.texi(,3990) notes will not be formatted and will not appear in either Info or a
texinfo.texi(,3991) printed manual; it is as if text after @code{@@bye} were within
texinfo.texi(,3992) @code{@@ignore} @dots{} @code{@@end ignore}.  Also, you may follow the
texinfo.texi(,3993) @code{@@bye} line with a local variables list for Emacs.
texinfo.texi(,3994) @xref{Compile-Command, , Using Local Variables and the Compile Command},
texinfo.texi(,3995) for more information.
texinfo.texi(,3996) 
texinfo.texi(,3997) 
texinfo.texi(,3998) @node Structuring
texinfo.texi(,3999) @chapter Chapter Structuring
texinfo.texi(,4000) @cindex Chapter structuring
texinfo.texi(,4001) @cindex Structuring of chapters
texinfo.texi(,4002) 
texinfo.texi(,4003) The @dfn{chapter structuring} commands divide a document into a hierarchy of
texinfo.texi(,4004) chapters, sections, subsections, and subsubsections.  These commands
texinfo.texi(,4005) generate large headings; they also provide information for the table
texinfo.texi(,4006) of contents of a printed manual (@pxref{Contents, , Generating a Table
texinfo.texi(,4007) of Contents}).@refill
texinfo.texi(,4008) 
texinfo.texi(,4009) The chapter structuring commands do not create an Info node structure,
texinfo.texi(,4010) so normally you should put an @code{@@node} command immediately before
texinfo.texi(,4011) each chapter structuring command (@pxref{Nodes}).  The only time you
texinfo.texi(,4012) are likely to use the chapter structuring commands without using the
texinfo.texi(,4013) node structuring commands is if you are writing a document that
texinfo.texi(,4014) contains no cross references and will never be transformed into Info
texinfo.texi(,4015) format.@refill
texinfo.texi(,4016) 
texinfo.texi(,4017) It is unlikely that you will ever write a Texinfo file that is
texinfo.texi(,4018) intended only as an Info file and not as a printable document.  If you
texinfo.texi(,4019) do, you might still use chapter structuring commands to create a
texinfo.texi(,4020) heading at the top of each node---but you don't need to.@refill
texinfo.texi(,4021) 
texinfo.texi(,4022) @menu
texinfo.texi(,4023) * Tree Structuring::            A manual is like an upside down tree @dots{}
texinfo.texi(,4024) * Structuring Command Types::   How to divide a manual into parts.
texinfo.texi(,4025) * makeinfo top::                The @code{@@top} command, part of the `Top' node.
texinfo.texi(,4026) * chapter::                     
texinfo.texi(,4027) * unnumbered & appendix::       
texinfo.texi(,4028) * majorheading & chapheading::  
texinfo.texi(,4029) * section::                     
texinfo.texi(,4030) * unnumberedsec appendixsec heading::  
texinfo.texi(,4031) * subsection::                  
texinfo.texi(,4032) * unnumberedsubsec appendixsubsec subheading::  
texinfo.texi(,4033) * subsubsection::               Commands for the lowest level sections.
texinfo.texi(,4034) * Raise/lower sections::        How to change commands' hierarchical level.
texinfo.texi(,4035) @end menu
texinfo.texi(,4036) 
texinfo.texi(,4037) 
texinfo.texi(,4038) @node Tree Structuring
texinfo.texi(,4039) @section Tree Structure of Sections
texinfo.texi(,4040) @cindex Tree structuring
texinfo.texi(,4041) 
texinfo.texi(,4042) A Texinfo file is usually structured like a book with chapters,
texinfo.texi(,4043) sections, subsections, and the like.  This structure can be visualized
texinfo.texi(,4044) as a tree (or rather as an upside-down tree) with the root at the top
texinfo.texi(,4045) and the levels corresponding to chapters, sections, subsection, and
texinfo.texi(,4046) subsubsections.@refill
texinfo.texi(,4047) 
texinfo.texi(,4048) Here is a diagram that shows a Texinfo file with three chapters,
texinfo.texi(,4049) each of which has two sections.@refill
texinfo.texi(,4050) 
texinfo.texi(,4051) @example
texinfo.texi(,4052) @group
texinfo.texi(,4053)                           Top
texinfo.texi(,4054)                            |
texinfo.texi(,4055)          -------------------------------------
texinfo.texi(,4056)         |                  |                  |
texinfo.texi(,4057)      Chapter 1          Chapter 2          Chapter 3
texinfo.texi(,4058)         |                  |                  |
texinfo.texi(,4059)      --------           --------           --------
texinfo.texi(,4060)     |        |         |        |         |        |
texinfo.texi(,4061)  Section  Section   Section  Section   Section  Section
texinfo.texi(,4062)    1.1      1.2       2.1      2.2       3.1      3.2
texinfo.texi(,4063) 
texinfo.texi(,4064) @end group
texinfo.texi(,4065) @end example
texinfo.texi(,4066) 
texinfo.texi(,4067) In a Texinfo file that has this structure, the beginning of Chapter 2
texinfo.texi(,4068) looks like this:@refill
texinfo.texi(,4069) 
texinfo.texi(,4070) @example
texinfo.texi(,4071) @group
texinfo.texi(,4072) @@node    Chapter 2,  Chapter 3, Chapter 1, top
texinfo.texi(,4073) @@chapter Chapter 2
texinfo.texi(,4074) @end group
texinfo.texi(,4075) @end example
texinfo.texi(,4076) 
texinfo.texi(,4077) The chapter structuring commands are described in the sections that
texinfo.texi(,4078) follow; the @code{@@node} and @code{@@menu} commands are described in
texinfo.texi(,4079) following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
texinfo.texi(,4080) 
texinfo.texi(,4081) 
texinfo.texi(,4082) @node Structuring Command Types
texinfo.texi(,4083) @section Structuring Command Types
texinfo.texi(,4084) 
texinfo.texi(,4085) The chapter structuring commands fall into four groups or series, each
texinfo.texi(,4086) of which contains structuring commands corresponding to the
texinfo.texi(,4087) hierarchical levels of chapters, sections, subsections, and
texinfo.texi(,4088) subsubsections.@refill
texinfo.texi(,4089) 
texinfo.texi(,4090) The four groups are the @code{@@chapter} series, the
texinfo.texi(,4091) @code{@@unnumbered} series, the @code{@@appendix} series, and the
texinfo.texi(,4092) @code{@@heading} series.@refill
texinfo.texi(,4093) 
texinfo.texi(,4094) Each command produces titles that have a different appearance on the
texinfo.texi(,4095) printed page or Info file; only some of the commands produce
texinfo.texi(,4096) titles that are listed in the table of contents of a printed book or
texinfo.texi(,4097) manual.@refill
texinfo.texi(,4098) 
texinfo.texi(,4099) @itemize @bullet
texinfo.texi(,4100) @item
texinfo.texi(,4101) The @code{@@chapter} and @code{@@appendix} series of commands produce
texinfo.texi(,4102) numbered or lettered entries both in the body of a printed work and in
texinfo.texi(,4103) its table of contents.@refill
texinfo.texi(,4104) 
texinfo.texi(,4105) @item
texinfo.texi(,4106) The @code{@@unnumbered} series of commands produce unnumbered entries
texinfo.texi(,4107) both in the body of a printed work and in its table of contents.  The
texinfo.texi(,4108) @code{@@top} command, which has a special use, is a member of this
texinfo.texi(,4109) series (@pxref{makeinfo top, , @code{@@top}}).@refill
texinfo.texi(,4110) 
texinfo.texi(,4111) @item
texinfo.texi(,4112) The @code{@@heading} series of commands produce unnumbered headings
texinfo.texi(,4113) that do not appear in a table of contents.  The heading commands never
texinfo.texi(,4114) start a new page.@refill
texinfo.texi(,4115) 
texinfo.texi(,4116) @item
texinfo.texi(,4117) The @code{@@majorheading} command produces results similar to using
texinfo.texi(,4118) the @code{@@chapheading} command but generates a larger vertical
texinfo.texi(,4119) whitespace before the heading.@refill
texinfo.texi(,4120) 
texinfo.texi(,4121) @item
texinfo.texi(,4122) When an @code{@@setchapternewpage} command says to do so, the
texinfo.texi(,4123) @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
texinfo.texi(,4124) start new pages in the printed manual; the @code{@@heading} commands
texinfo.texi(,4125) do not.@refill
texinfo.texi(,4126) @end itemize
texinfo.texi(,4127) 
texinfo.texi(,4128) Here are the four groups of chapter structuring commands:
texinfo.texi(,4129) 
texinfo.texi(,4133) 
texinfo.texi(,4134) @multitable @columnfractions .19 .30 .29 .22
texinfo.texi(,4135) @item                        @tab                              @tab                       @tab No new page
texinfo.texi(,4136) @item @i{Numbered}           @tab @i{Unnumbered}               @tab @i{Lettered/numbered} @tab @i{Unnumbered}
texinfo.texi(,4137) @item In contents            @tab In contents                  @tab In contents           @tab Omitted from@*contents
texinfo.texi(,4138) @item                        @tab @code{@@top}                 @tab                       @tab @code{@@majorheading}
texinfo.texi(,4139) @item @code{@@chapter}       @tab @code{@@unnumbered}          @tab @code{@@appendix} @tab @code{@@chapheading}
texinfo.texi(,4140) @item @code{@@section}       @tab @code{@@unnumberedsec}       @tab @code{@@appendixsec} @tab @code{@@heading}
texinfo.texi(,4141) @item @code{@@subsection}    @tab @code{@@unnumberedsubsec}    @tab @code{@@appendixsubsec} @tab @code{@@subheading}
texinfo.texi(,4142) @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
texinfo.texi(,4143) @end multitable
texinfo.texi(,4147) 
texinfo.texi(,4148) 
texinfo.texi(,4149) @node makeinfo top
texinfo.texi(,4150) @section @code{@@top}
texinfo.texi(,4151) 
texinfo.texi(,4152) The @code{@@top} command is a special sectioning command that you use
texinfo.texi(,4153) only after an @samp{@@node Top} line at the beginning of a Texinfo file.
texinfo.texi(,4154) The @code{@@top} command tells the @code{makeinfo} formatter which node
texinfo.texi(,4155) is the `Top' node, so it can use it as the root of the node tree if your
texinfo.texi(,4156) manual uses implicit pointers.  It has the same typesetting effect as
texinfo.texi(,4157) @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
texinfo.texi(,4158) and @code{@@appendix}}).  For detailed information, see @ref{makeinfo
texinfo.texi(,4159) top command, , The @code{@@top} Command}.
texinfo.texi(,4160) 
texinfo.texi(,4161) The @code{@@top} node and its menu (if any) is conventionally wrapped in
texinfo.texi(,4162) an @code{@@ifnottex} conditional so that it will appear only in Info and
texinfo.texi(,4163) HTML output, not @TeX{}.
texinfo.texi(,4164) 
texinfo.texi(,4165) 
texinfo.texi(,4166) @node chapter, unnumbered & appendix, makeinfo top, Structuring
texinfo.texi(,4167) @comment  node-name,  next,  previous,  up
texinfo.texi(,4168) @section @code{@@chapter}
texinfo.texi(,4169) @findex chapter
texinfo.texi(,4170) 
texinfo.texi(,4171) @code{@@chapter} identifies a chapter in the document.  Write the
texinfo.texi(,4172) command at the beginning of a line and follow it on the same line by
texinfo.texi(,4173) the title of the chapter.@refill
texinfo.texi(,4174) 
texinfo.texi(,4175) For example, this chapter in this manual is entitled ``Chapter
texinfo.texi(,4176) Structuring''; the @code{@@chapter} line looks like this:@refill
texinfo.texi(,4177) 
texinfo.texi(,4178) @example
texinfo.texi(,4179) @@chapter Chapter Structuring
texinfo.texi(,4180) @end example
texinfo.texi(,4181) 
texinfo.texi(,4182) In @TeX{}, the @code{@@chapter} command creates a chapter in the
texinfo.texi(,4183) document, specifying the chapter title.  The chapter is numbered
texinfo.texi(,4184) automatically.@refill
texinfo.texi(,4185) 
texinfo.texi(,4186) In Info, the @code{@@chapter} command causes the title to appear on a
texinfo.texi(,4187) line by itself, with a line of asterisks inserted underneath.  Thus,
texinfo.texi(,4188) in Info, the above example produces the following output:@refill
texinfo.texi(,4189) 
texinfo.texi(,4190) @example
texinfo.texi(,4191) Chapter Structuring
texinfo.texi(,4192) *******************
texinfo.texi(,4193) @end example
texinfo.texi(,4194) 
texinfo.texi(,4195) @findex centerchap
texinfo.texi(,4196) Texinfo also provides a command @code{@@centerchap}, which is analogous
texinfo.texi(,4197) to @code{@@unnumbered}, but centers its argument in the printed output.
texinfo.texi(,4198) This kind of stylistic choice is not usually offered by Texinfo.
texinfo.texi(,4199) @c but the Hacker's Dictionary wanted it ...
texinfo.texi(,4200) 
texinfo.texi(,4201) 
texinfo.texi(,4202) @node unnumbered & appendix
texinfo.texi(,4203) @section @code{@@unnumbered} and @code{@@appendix}
texinfo.texi(,4204) @findex unnumbered
texinfo.texi(,4205) @findex appendix
texinfo.texi(,4206) 
texinfo.texi(,4207) Use the @code{@@unnumbered} command to create a chapter that appears
texinfo.texi(,4208) in a printed manual without chapter numbers of any kind.  Use the
texinfo.texi(,4209) @code{@@appendix} command to create an appendix in a printed manual
texinfo.texi(,4210) that is labelled by letter instead of by number.@refill
texinfo.texi(,4211) 
texinfo.texi(,4212) For Info file output, the @code{@@unnumbered} and @code{@@appendix}
texinfo.texi(,4213) commands are equivalent to @code{@@chapter}: the title is printed on a
texinfo.texi(,4214) line by itself with a line of asterisks underneath.  (@xref{chapter, ,
texinfo.texi(,4215) @code{@@chapter}}.)@refill
texinfo.texi(,4216) 
texinfo.texi(,4217) To create an appendix or an unnumbered chapter, write an
texinfo.texi(,4218) @code{@@appendix} or @code{@@unnumbered} command at the beginning of a
texinfo.texi(,4219) line and follow it on the same line by the title, as you would if you
texinfo.texi(,4220) were creating a chapter.@refill
texinfo.texi(,4221) 
texinfo.texi(,4222) 
texinfo.texi(,4223) @node majorheading & chapheading, section, unnumbered & appendix, Structuring
texinfo.texi(,4224) @section @code{@@majorheading}, @code{@@chapheading}
texinfo.texi(,4225) @findex majorheading
texinfo.texi(,4226) @findex chapheading
texinfo.texi(,4227) 
texinfo.texi(,4228) The @code{@@majorheading} and @code{@@chapheading} commands put
texinfo.texi(,4229) chapter-like headings in the body of a document.@refill
texinfo.texi(,4230) 
texinfo.texi(,4231) However, neither command causes @TeX{} to produce a numbered heading
texinfo.texi(,4232) or an entry in the table of contents; and neither command causes
texinfo.texi(,4233) @TeX{} to start a new page in a printed manual.@refill
texinfo.texi(,4234) 
texinfo.texi(,4235) In @TeX{}, an @code{@@majorheading} command generates a larger vertical
texinfo.texi(,4236) whitespace before the heading than an @code{@@chapheading} command but
texinfo.texi(,4237) is otherwise the same.@refill
texinfo.texi(,4238) 
texinfo.texi(,4239) In Info,
texinfo.texi(,4240) the @code{@@majorheading} and
texinfo.texi(,4241) @code{@@chapheading} commands are equivalent to
texinfo.texi(,4242) @code{@@chapter}: the title is printed on a line by itself with a line
texinfo.texi(,4243) of asterisks underneath.  (@xref{chapter, , @code{@@chapter}}.)@refill
texinfo.texi(,4244) 
texinfo.texi(,4245) @node section, unnumberedsec appendixsec heading, majorheading & chapheading, Structuring
texinfo.texi(,4246) @comment  node-name,  next,  previous,  up
texinfo.texi(,4247) @section @code{@@section}
texinfo.texi(,4248) @findex section
texinfo.texi(,4249) 
texinfo.texi(,4250) In a printed manual, an @code{@@section} command identifies a
texinfo.texi(,4251) numbered section within a chapter.  The section title appears in the
texinfo.texi(,4252) table of contents.  In Info, an @code{@@section} command provides a
texinfo.texi(,4253) title for a segment of text, underlined with @samp{=}.@refill
texinfo.texi(,4254) 
texinfo.texi(,4255) This section is headed with an @code{@@section} command and looks like
texinfo.texi(,4256) this in the Texinfo file:@refill
texinfo.texi(,4257) 
texinfo.texi(,4258) @example
texinfo.texi(,4259) @@section @@code@{@@@@section@}
texinfo.texi(,4260) @end example
texinfo.texi(,4261) 
texinfo.texi(,4262) To create a section, write the @code{@@section} command at the
texinfo.texi(,4263) beginning of a line and follow it on the same line by the section
texinfo.texi(,4264) title.@refill
texinfo.texi(,4265) 
texinfo.texi(,4266) Thus,
texinfo.texi(,4267) 
texinfo.texi(,4268) @example
texinfo.texi(,4269) @@section This is a section
texinfo.texi(,4270) @end example
texinfo.texi(,4271) 
texinfo.texi(,4272) @noindent
texinfo.texi(,4273) produces
texinfo.texi(,4274) 
texinfo.texi(,4275) @example
texinfo.texi(,4276) @group
texinfo.texi(,4277) This is a section
texinfo.texi(,4278) =================
texinfo.texi(,4279) @end group
texinfo.texi(,4280) @end example
texinfo.texi(,4281) 
texinfo.texi(,4282) @noindent
texinfo.texi(,4283) in Info.
texinfo.texi(,4284) 
texinfo.texi(,4285) @node unnumberedsec appendixsec heading, subsection, section, Structuring
texinfo.texi(,4286) @comment  node-name,  next,  previous,  up
texinfo.texi(,4287) @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
texinfo.texi(,4288) @findex unnumberedsec
texinfo.texi(,4289) @findex appendixsec
texinfo.texi(,4290) @findex heading
texinfo.texi(,4291) 
texinfo.texi(,4292) The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
texinfo.texi(,4293) commands are, respectively, the unnumbered, appendix-like, and
texinfo.texi(,4294) heading-like equivalents of the @code{@@section} command.
texinfo.texi(,4295) (@xref{section, , @code{@@section}}.)@refill
texinfo.texi(,4296) 
texinfo.texi(,4297) @table @code
texinfo.texi(,4298) @item @@unnumberedsec
texinfo.texi(,4299) The @code{@@unnumberedsec} command may be used within an
texinfo.texi(,4300) unnumbered chapter or within a regular chapter or appendix to
texinfo.texi(,4301) provide an unnumbered section.@refill
texinfo.texi(,4302) 
texinfo.texi(,4303) @item @@appendixsec
texinfo.texi(,4304) @itemx @@appendixsection
texinfo.texi(,4305) @code{@@appendixsection} is a longer spelling of the
texinfo.texi(,4306) @code{@@appendixsec} command; the two are synonymous.@refill
texinfo.texi(,4307) @findex appendixsection
texinfo.texi(,4308) 
texinfo.texi(,4309) Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
texinfo.texi(,4310) command is used only within appendices.@refill
texinfo.texi(,4311) 
texinfo.texi(,4312) @item @@heading
texinfo.texi(,4313) You may use the @code{@@heading} command anywhere you wish for a
texinfo.texi(,4314) section-style heading that will not appear in the table of contents.@refill
texinfo.texi(,4315) @end table
texinfo.texi(,4316) 
texinfo.texi(,4317) @node subsection, unnumberedsubsec appendixsubsec subheading, unnumberedsec appendixsec heading, Structuring
texinfo.texi(,4318) @comment  node-name,  next,  previous,  up
texinfo.texi(,4319) @section The @code{@@subsection} Command
texinfo.texi(,4320) @findex subsection
texinfo.texi(,4321) 
texinfo.texi(,4322) Subsections are to sections as sections are to chapters.
texinfo.texi(,4323) (@xref{section, , @code{@@section}}.)  In Info, subsection titles are
texinfo.texi(,4324) underlined with @samp{-}.  For example,@refill
texinfo.texi(,4325) 
texinfo.texi(,4326) @example
texinfo.texi(,4327) @@subsection This is a subsection
texinfo.texi(,4328) @end example
texinfo.texi(,4329) 
texinfo.texi(,4330) @noindent
texinfo.texi(,4331) produces
texinfo.texi(,4332) 
texinfo.texi(,4333) @example
texinfo.texi(,4334) @group
texinfo.texi(,4335) This is a subsection
texinfo.texi(,4336) --------------------
texinfo.texi(,4337) @end group
texinfo.texi(,4338) @end example
texinfo.texi(,4339) 
texinfo.texi(,4340) In a printed manual, subsections are listed in the table of contents
texinfo.texi(,4341) and are numbered three levels deep.@refill
texinfo.texi(,4342) 
texinfo.texi(,4343) @node unnumberedsubsec appendixsubsec subheading, subsubsection, subsection, Structuring
texinfo.texi(,4344) @comment  node-name,  next,  previous,  up
texinfo.texi(,4345) @section The @code{@@subsection}-like Commands
texinfo.texi(,4346) @cindex Subsection-like commands
texinfo.texi(,4347) @findex unnumberedsubsec
texinfo.texi(,4348) @findex appendixsubsec
texinfo.texi(,4349) @findex subheading
texinfo.texi(,4350) 
texinfo.texi(,4351) The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
texinfo.texi(,4352) @code{@@subheading} commands are, respectively, the unnumbered,
texinfo.texi(,4353) appendix-like, and heading-like equivalents of the @code{@@subsection}
texinfo.texi(,4354) command.  (@xref{subsection, , @code{@@subsection}}.)@refill
texinfo.texi(,4355) 
texinfo.texi(,4356) In Info, the @code{@@subsection}-like commands generate a title
texinfo.texi(,4357) underlined with hyphens.  In a printed manual, an @code{@@subheading}
texinfo.texi(,4358) command produces a heading like that of a subsection except that it is
texinfo.texi(,4359) not numbered and does not appear in the table of contents.  Similarly,
texinfo.texi(,4360) an @code{@@unnumberedsubsec} command produces an unnumbered heading like
texinfo.texi(,4361) that of a subsection and an @code{@@appendixsubsec} command produces a
texinfo.texi(,4362) subsection-like heading labelled with a letter and numbers; both of
texinfo.texi(,4363) these commands produce headings that appear in the table of
texinfo.texi(,4364) contents.@refill
texinfo.texi(,4365) 
texinfo.texi(,4366) @node subsubsection, Raise/lower sections, unnumberedsubsec appendixsubsec subheading, Structuring
texinfo.texi(,4367) @comment  node-name,  next,  previous,  up
texinfo.texi(,4368) @section The `subsub' Commands
texinfo.texi(,4369) @cindex Subsub commands
texinfo.texi(,4370) @findex subsubsection
texinfo.texi(,4371) @findex unnumberedsubsubsec
texinfo.texi(,4372) @findex appendixsubsubsec
texinfo.texi(,4373) @findex subsubheading
texinfo.texi(,4374) 
texinfo.texi(,4375) The fourth and lowest level sectioning commands in Texinfo are the
texinfo.texi(,4376) `subsub' commands.  They are:@refill
texinfo.texi(,4377) 
texinfo.texi(,4378) @table @code
texinfo.texi(,4379) @item @@subsubsection
texinfo.texi(,4380) Subsubsections are to subsections as subsections are to sections.
texinfo.texi(,4381) (@xref{subsection, , @code{@@subsection}}.)  In a printed manual,
texinfo.texi(,4382) subsubsection titles appear in the table of contents and are numbered
texinfo.texi(,4383) four levels deep.@refill
texinfo.texi(,4384) 
texinfo.texi(,4385) @item @@unnumberedsubsubsec
texinfo.texi(,4386) Unnumbered subsubsection titles appear in the table of contents of a
texinfo.texi(,4387) printed manual, but lack numbers.  Otherwise, unnumbered
texinfo.texi(,4388) subsubsections are the same as subsubsections.  In Info, unnumbered
texinfo.texi(,4389) subsubsections look exactly like ordinary subsubsections.@refill
texinfo.texi(,4390) 
texinfo.texi(,4391) @item @@appendixsubsubsec
texinfo.texi(,4392) Conventionally, appendix commands are used only for appendices and are
texinfo.texi(,4393) lettered and numbered appropriately in a printed manual.  They also
texinfo.texi(,4394) appear in the table of contents.  In Info, appendix subsubsections look
texinfo.texi(,4395) exactly like ordinary subsubsections.@refill
texinfo.texi(,4396) 
texinfo.texi(,4397) @item @@subsubheading
texinfo.texi(,4398) The @code{@@subsubheading} command may be used anywhere that you need
texinfo.texi(,4399) a small heading that will not appear in the table of contents.  In
texinfo.texi(,4400) Info, subsubheadings look exactly like ordinary subsubsection
texinfo.texi(,4401) headings.@refill
texinfo.texi(,4402) @end table
texinfo.texi(,4403) 
texinfo.texi(,4404) In Info,  `subsub' titles are underlined with periods.
texinfo.texi(,4405) For example,@refill
texinfo.texi(,4406) 
texinfo.texi(,4407) @example
texinfo.texi(,4408) @@subsubsection This is a subsubsection
texinfo.texi(,4409) @end example
texinfo.texi(,4410) 
texinfo.texi(,4411) @noindent
texinfo.texi(,4412) produces
texinfo.texi(,4413) 
texinfo.texi(,4414) @example
texinfo.texi(,4415) @group
texinfo.texi(,4416) This is a subsubsection
texinfo.texi(,4417) .......................
texinfo.texi(,4418) @end group
texinfo.texi(,4419) @end example
texinfo.texi(,4420) 
texinfo.texi(,4421) @node Raise/lower sections,  , subsubsection, Structuring
texinfo.texi(,4422) @comment  node-name,  next,  previous,  up
texinfo.texi(,4423) @section @code{@@raisesections} and @code{@@lowersections}
texinfo.texi(,4424) @findex raisesections
texinfo.texi(,4425) @findex lowersections
texinfo.texi(,4426) @cindex Raising and lowering sections
texinfo.texi(,4427) @cindex Sections, raising and lowering
texinfo.texi(,4428) 
texinfo.texi(,4429) The @code{@@raisesections} and @code{@@lowersections} commands raise and
texinfo.texi(,4430) lower the hierarchical level of chapters, sections, subsections and the
texinfo.texi(,4431) like.  The @code{@@raisesections} command changes sections to chapters,
texinfo.texi(,4432) subsections to sections, and so on.  The @code{@@lowersections} command
texinfo.texi(,4433) changes chapters to sections, sections to subsections, and so on.
texinfo.texi(,4434) 
texinfo.texi(,4435) @cindex Include files, and section levels
texinfo.texi(,4436) An @code{@@lowersections} command is useful if you wish to include text
texinfo.texi(,4437) that is written as an outer or standalone Texinfo file in another
texinfo.texi(,4438) Texinfo file as an inner, included file.  If you write the command at
texinfo.texi(,4439) the beginning of the file, all your @code{@@chapter} commands are
texinfo.texi(,4440) formatted as if they were @code{@@section} commands, all your
texinfo.texi(,4441) @code{@@section} command are formatted as if they were
texinfo.texi(,4442) @code{@@subsection} commands, and so on.
texinfo.texi(,4443) 
texinfo.texi(,4444) @need 1000
texinfo.texi(,4445) @code{@@raisesections} raises a command one level in the chapter
texinfo.texi(,4446) structuring hierarchy:@refill
texinfo.texi(,4447) 
texinfo.texi(,4448) @example
texinfo.texi(,4449) @group
texinfo.texi(,4450)   @r{Change}           @r{To}
texinfo.texi(,4451) 
texinfo.texi(,4452) @@subsection     @@section,
texinfo.texi(,4453) @@section        @@chapter,
texinfo.texi(,4454) @@heading        @@chapheading,
texinfo.texi(,4455)           @r{etc.}
texinfo.texi(,4456) @end group
texinfo.texi(,4457) @end example
texinfo.texi(,4458) 
texinfo.texi(,4459) @need 1000
texinfo.texi(,4460) @code{@@lowersections} lowers a command one level in the chapter
texinfo.texi(,4461) structuring hierarchy:@refill
texinfo.texi(,4462) 
texinfo.texi(,4463) @example
texinfo.texi(,4464) @group
texinfo.texi(,4465)   @r{Change}           @r{To}
texinfo.texi(,4466) 
texinfo.texi(,4467) @@chapter        @@section,
texinfo.texi(,4468) @@subsection     @@subsubsection,
texinfo.texi(,4469) @@heading        @@subheading,
texinfo.texi(,4470)           @r{etc.}
texinfo.texi(,4471) @end group
texinfo.texi(,4472) @end example
texinfo.texi(,4473) 
texinfo.texi(,4474) An @code{@@raisesections} or @code{@@lowersections} command changes only
texinfo.texi(,4475) those structuring commands that follow the command in the Texinfo file.
texinfo.texi(,4476) Write an @code{@@raisesections} or @code{@@lowersections} command on a
texinfo.texi(,4477) line of its own.
texinfo.texi(,4478) 
texinfo.texi(,4479) An @code{@@lowersections} command cancels an @code{@@raisesections}
texinfo.texi(,4480) command, and vice versa.  Typically, the commands are used like this:
texinfo.texi(,4481) 
texinfo.texi(,4482) @example
texinfo.texi(,4483) @@lowersections
texinfo.texi(,4484) @@include somefile.texi
texinfo.texi(,4485) @@raisesections
texinfo.texi(,4486) @end example
texinfo.texi(,4487) 
texinfo.texi(,4488) Without the @code{@@raisesections}, all the subsequent sections in your
texinfo.texi(,4489) document will be lowered.
texinfo.texi(,4490) 
texinfo.texi(,4491) Repeated use of the commands continue to raise or lower the hierarchical
texinfo.texi(,4492) level a step at a time.
texinfo.texi(,4493) 
texinfo.texi(,4494) An attempt to raise above `chapters' reproduces chapter commands; an
texinfo.texi(,4495) attempt to lower below `subsubsections' reproduces subsubsection
texinfo.texi(,4496) commands.
texinfo.texi(,4497) 
texinfo.texi(,4498) @node Nodes
texinfo.texi(,4499) @chapter Nodes
texinfo.texi(,4500) 
texinfo.texi(,4501) @dfn{Nodes} are the primary segments of a Texinfo file.  They do not
texinfo.texi(,4502) themselves impose a hierarchical or any other kind of structure on a file.
texinfo.texi(,4503) Nodes contain @dfn{node pointers} that name other nodes, and can contain
texinfo.texi(,4504) @dfn{menus} which are lists of nodes.  In Info, the movement commands
texinfo.texi(,4505) can carry you to a pointed-to node or to a node listed in a menu.  Node
texinfo.texi(,4506) pointers and menus provide structure for Info files just as chapters,
texinfo.texi(,4507) sections, subsections, and the like, provide structure for printed
texinfo.texi(,4508) books.@refill
texinfo.texi(,4509) 
texinfo.texi(,4510) @menu
texinfo.texi(,4511) * Two Paths::                   Different commands to structure
texinfo.texi(,4512)                                   Info output and printed output.
texinfo.texi(,4513) * Node Menu Illustration::      A diagram, and sample nodes and menus.
texinfo.texi(,4514) * node::                        Creating nodes, in detail.
texinfo.texi(,4515) * makeinfo Pointer Creation::   Letting makeinfo determine node pointers.
texinfo.texi(,4516) * anchor::                      Defining arbitrary cross-reference targets.
texinfo.texi(,4517) @end menu
texinfo.texi(,4518) 
texinfo.texi(,4519) 
texinfo.texi(,4520) @node Two Paths
texinfo.texi(,4521) @section Two Paths
texinfo.texi(,4522) 
texinfo.texi(,4523) The node and menu commands and the chapter structuring commands are
texinfo.texi(,4524) technically independent of each other:
texinfo.texi(,4525) 
texinfo.texi(,4526) @itemize @bullet
texinfo.texi(,4527) @item
texinfo.texi(,4528) In Info, node and menu commands provide structure.  The chapter
texinfo.texi(,4529) structuring commands generate headings with different kinds of
texinfo.texi(,4530) underlining---asterisks for chapters, hyphens for sections, and so on;
texinfo.texi(,4531) they do nothing else.@refill
texinfo.texi(,4532) 
texinfo.texi(,4533) @item
texinfo.texi(,4534) In @TeX{}, the chapter structuring commands generate chapter and section
texinfo.texi(,4535) numbers and tables of contents.  The node and menu commands provide
texinfo.texi(,4536) information for cross references; they do nothing else.@refill
texinfo.texi(,4537) @end itemize
texinfo.texi(,4538) 
texinfo.texi(,4539) You can use node pointers and menus to structure an Info file any way
texinfo.texi(,4540) you want; and you can write a Texinfo file so that its Info output has a
texinfo.texi(,4541) different structure than its printed output.  However, virtually all
texinfo.texi(,4542) Texinfo files are written such that the structure for the Info output
texinfo.texi(,4543) corresponds to the structure for the printed output.  It is neither
texinfo.texi(,4544) convenient nor understandable to the reader to do otherwise.@refill
texinfo.texi(,4545) 
texinfo.texi(,4546) Generally, printed output is structured in a tree-like hierarchy in
texinfo.texi(,4547) which the chapters are the major limbs from which the sections branch
texinfo.texi(,4548) out.  Similarly, node pointers and menus are organized to create a
texinfo.texi(,4549) matching structure in the Info output.@refill
texinfo.texi(,4550) 
texinfo.texi(,4551) 
texinfo.texi(,4552) @node Node Menu Illustration
texinfo.texi(,4553) @section Node and Menu Illustration
texinfo.texi(,4554) 
texinfo.texi(,4555) Here is a copy of the diagram shown earlier that illustrates a Texinfo
texinfo.texi(,4556) file with three chapters, each of which contains two sections.@refill
texinfo.texi(,4557) 
texinfo.texi(,4558) The ``root'' is at the top of the diagram and the ``leaves'' are at the
texinfo.texi(,4559) bottom.  This is how such a diagram is drawn conventionally; it
texinfo.texi(,4560) illustrates an upside-down tree.  For this reason, the root node is
texinfo.texi(,4561) called the `Top' node, and `Up' node pointers carry you closer to the
texinfo.texi(,4562) root.@refill
texinfo.texi(,4563) 
texinfo.texi(,4564) @example
texinfo.texi(,4565) @group
texinfo.texi(,4566)                           Top
texinfo.texi(,4567)                            |
texinfo.texi(,4568)          -------------------------------------
texinfo.texi(,4569)         |                  |                  |
texinfo.texi(,4570)      Chapter 1          Chapter 2          Chapter 3
texinfo.texi(,4571)         |                  |                  |
texinfo.texi(,4572)      --------           --------           --------
texinfo.texi(,4573)     |        |         |        |         |        |
texinfo.texi(,4574)  Section  Section   Section  Section   Section  Section
texinfo.texi(,4575)    1.1      1.2       2.1      2.2       3.1      3.2
texinfo.texi(,4576) @end group
texinfo.texi(,4577) @end example
texinfo.texi(,4578) 
texinfo.texi(,4579) The fully-written command to start Chapter 2 would be this:
texinfo.texi(,4580) 
texinfo.texi(,4581) @example
texinfo.texi(,4582) @group
texinfo.texi(,4583) @@node     Chapter 2,  Chapter 3, Chapter 1, Top
texinfo.texi(,4584) @@comment  node-name,  next,      previous,  up
texinfo.texi(,4585) @end group
texinfo.texi(,4586) @end example
texinfo.texi(,4587) 
texinfo.texi(,4588) @noindent
texinfo.texi(,4589) This @code{@@node} line says that the name of this node is ``Chapter
texinfo.texi(,4590) 2'', the name of the `Next' node is ``Chapter 3'', the name of the
texinfo.texi(,4591) `Previous' node is ``Chapter 1'', and the name of the `Up' node is
texinfo.texi(,4592) ``Top''.  You can omit writing out these node names if your document is
texinfo.texi(,4593) hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
texinfo.texi(,4594) pointer relationships still obtain.
texinfo.texi(,4595) 
texinfo.texi(,4596) @quotation
texinfo.texi(,4597) @strong{Please Note:} `Next' refers to the next node at the same
texinfo.texi(,4598) hierarchical level in the manual, not necessarily to the next node
texinfo.texi(,4599) within the Texinfo file.  In the Texinfo file, the subsequent node may
texinfo.texi(,4600) be at a lower level---a section-level node most often follows a
texinfo.texi(,4601) chapter-level node, for example.  `Next' and `Previous' refer to nodes
texinfo.texi(,4602) at the @emph{same} hierarchical level.  (The `Top' node contains the
texinfo.texi(,4603) exception to this rule.  Since the `Top' node is the only node at that
texinfo.texi(,4604) level, `Next' refers to the first following node, which is almost always
texinfo.texi(,4605) a chapter or chapter-level node.)@refill
texinfo.texi(,4606) @end quotation
texinfo.texi(,4607) 
texinfo.texi(,4608) To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
texinfo.texi(,4609) 2.  (@xref{Menus}.)  You would write the menu just
texinfo.texi(,4610) before the beginning of Section 2.1, like this:@refill
texinfo.texi(,4611) 
texinfo.texi(,4612) @example
texinfo.texi(,4613) @group
texinfo.texi(,4614)     @@menu
texinfo.texi(,4615)     * Sect. 2.1::    Description of this section.
texinfo.texi(,4616)     * Sect. 2.2::
texinfo.texi(,4617)     @@end menu
texinfo.texi(,4618) @end group
texinfo.texi(,4619) @end example
texinfo.texi(,4620) 
texinfo.texi(,4621) Write the node for Sect. 2.1 like this:@refill
texinfo.texi(,4622) 
texinfo.texi(,4623) @example
texinfo.texi(,4624) @group
texinfo.texi(,4625)     @@node     Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
texinfo.texi(,4626)     @@comment  node-name, next,      previous,  up
texinfo.texi(,4627) @end group
texinfo.texi(,4628) @end example
texinfo.texi(,4629) 
texinfo.texi(,4630) In Info format, the `Next' and `Previous' pointers of a node usually
texinfo.texi(,4631) lead to other nodes at the same level---from chapter to chapter or from
texinfo.texi(,4632) section to section (sometimes, as shown, the `Previous' pointer points
texinfo.texi(,4633) up); an `Up' pointer usually leads to a node at the level above (closer
texinfo.texi(,4634) to the `Top' node); and a `Menu' leads to nodes at a level below (closer
texinfo.texi(,4635) to `leaves').  (A cross reference can point to a node at any level;
texinfo.texi(,4636) see @ref{Cross References}.)@refill
texinfo.texi(,4637) 
texinfo.texi(,4638) Usually, an @code{@@node} command and a chapter structuring command are
texinfo.texi(,4639) used in sequence, along with indexing commands.  (You may follow the
texinfo.texi(,4640) @code{@@node} line with a comment line that reminds you which pointer is
texinfo.texi(,4641) which.)@refill
texinfo.texi(,4642) 
texinfo.texi(,4643) Here is the beginning of the chapter in this manual called ``Ending a
texinfo.texi(,4644) Texinfo File''.  This shows an @code{@@node} line followed by a comment
texinfo.texi(,4645) line, an @code{@@chapter} line, and then by indexing lines.@refill
texinfo.texi(,4646) 
texinfo.texi(,4647) @example
texinfo.texi(,4648) @group
texinfo.texi(,4649) @@node    Ending a File, Structuring, Beginning a File, Top
texinfo.texi(,4650) @@comment node-name,     next,        previous,         up
texinfo.texi(,4651) @@chapter Ending a Texinfo File
texinfo.texi(,4652) @@cindex Ending a Texinfo file
texinfo.texi(,4653) @@cindex Texinfo file ending
texinfo.texi(,4654) @@cindex File ending
texinfo.texi(,4655) @end group
texinfo.texi(,4656) @end example
texinfo.texi(,4657) 
texinfo.texi(,4658) 
texinfo.texi(,4659) @node node
texinfo.texi(,4660) @section The @code{@@node} Command
texinfo.texi(,4661) 
texinfo.texi(,4662) @cindex Node, defined
texinfo.texi(,4663) @findex node
texinfo.texi(,4664) 
texinfo.texi(,4665) A @dfn{node} is a segment of text that begins at an @code{@@node}
texinfo.texi(,4666) command and continues until the next @code{@@node} command.  The
texinfo.texi(,4667) definition of node is different from that for chapter or section.  A
texinfo.texi(,4668) chapter may contain sections and a section may contain subsections;
texinfo.texi(,4669) but a node cannot contain subnodes; the text of a node continues only
texinfo.texi(,4670) until the next @code{@@node} command in the file.  A node usually
texinfo.texi(,4671) contains only one chapter structuring command, the one that follows
texinfo.texi(,4672) the @code{@@node} line.  On the other hand, in printed output nodes
texinfo.texi(,4673) are used only for cross references, so a chapter or section may
texinfo.texi(,4674) contain any number of nodes.  Indeed, a chapter usually contains
texinfo.texi(,4675) several nodes, one for each section, subsection, and
texinfo.texi(,4676) subsubsection.@refill
texinfo.texi(,4677) 
texinfo.texi(,4678) To create a node, write an @code{@@node} command at the beginning of a
texinfo.texi(,4679) line, and follow it with up to four arguments, separated by commas, on
texinfo.texi(,4680) the rest of the same line.  The first argument is required; it is the
texinfo.texi(,4681) name of this node.  The subsequent arguments are the names of the
texinfo.texi(,4682) `Next', `Previous', and `Up' pointers, in that order, and may be omitted
texinfo.texi(,4683) if your Texinfo document is hierarchically organized (@pxref{makeinfo
texinfo.texi(,4684) Pointer Creation}).
texinfo.texi(,4685) 
texinfo.texi(,4686) You may insert spaces before each name if you wish; the spaces are
texinfo.texi(,4687) ignored.  You must write the name of the node and the names of the
texinfo.texi(,4688) `Next', `Previous', and `Up' pointers all on the same line.  Otherwise,
texinfo.texi(,4689) the formatters fail.  (@inforef{Top, info, info}, for more information
texinfo.texi(,4690) about nodes in Info.)
texinfo.texi(,4691) 
texinfo.texi(,4692) Usually, you write one of the chapter-structuring command lines
texinfo.texi(,4693) immediately after an @code{@@node} line---for example, an
texinfo.texi(,4694) @code{@@section} or @code{@@subsection} line.  (@xref{Structuring
texinfo.texi(,4695) Command Types}.)
texinfo.texi(,4696) 
texinfo.texi(,4697) @quotation
texinfo.texi(,4698) @strong{Please note:} The GNU Emacs Texinfo mode updating commands work
texinfo.texi(,4699) only with Texinfo files in which @code{@@node} lines are followed by chapter
texinfo.texi(,4700) structuring lines.  @xref{Updating Requirements}.@refill
texinfo.texi(,4701) @end quotation
texinfo.texi(,4702) 
texinfo.texi(,4703) @TeX{} uses @code{@@node} lines to identify the names to use for cross
texinfo.texi(,4704) references.  For this reason, you must write @code{@@node} lines in a
texinfo.texi(,4705) Texinfo file that you intend to format for printing, even if you do not
texinfo.texi(,4706) intend to format it for Info.  (Cross references, such as the one at the
texinfo.texi(,4707) end of this sentence, are made with @code{@@xref} and related commands;
texinfo.texi(,4708) see @ref{Cross References}.)@refill
texinfo.texi(,4709) 
texinfo.texi(,4710) @menu
texinfo.texi(,4711) * Node Names::                  How to choose node and pointer names.
texinfo.texi(,4712) * Writing a Node::              How to write an @code{@@node} line.
texinfo.texi(,4713) * Node Line Tips::              Keep names short.
texinfo.texi(,4714) * Node Line Requirements::      Keep names unique, without @@-commands.
texinfo.texi(,4715) * First Node::                  How to write a `Top' node.
texinfo.texi(,4716) * makeinfo top command::        How to use the @code{@@top} command.
texinfo.texi(,4717) @end menu
texinfo.texi(,4718) 
texinfo.texi(,4719) 
texinfo.texi(,4720) @node Node Names
texinfo.texi(,4721) @subsection Choosing Node and Pointer Names
texinfo.texi(,4722) 
texinfo.texi(,4723) @cindex Node names, choosing
texinfo.texi(,4724) The name of a node identifies the node.  The pointers enable
texinfo.texi(,4725) you to reach other nodes and consist of the names of those nodes.@refill
texinfo.texi(,4726) 
texinfo.texi(,4727) Normally, a node's `Up' pointer contains the name of the node whose menu
texinfo.texi(,4728) mentions that node.  The node's `Next' pointer contains the name of the
texinfo.texi(,4729) node that follows that node in that menu and its `Previous' pointer
texinfo.texi(,4730) contains the name of the node that precedes it in that menu.  When a
texinfo.texi(,4731) node's `Previous' node is the same as its `Up' node, both node pointers
texinfo.texi(,4732) name the same node.@refill
texinfo.texi(,4733) 
texinfo.texi(,4734) Usually, the first node of a Texinfo file is the `Top' node, and its
texinfo.texi(,4735) `Up' and `Previous' pointers point to the @file{dir} file, which
texinfo.texi(,4736) contains the main menu for all of Info.@refill
texinfo.texi(,4737) 
texinfo.texi(,4738) The `Top' node itself contains the main or master menu for the manual.
texinfo.texi(,4739) Also, it is helpful to include a brief description of the manual in the
texinfo.texi(,4740) `Top' node.  @xref{First Node}, for information on how to write the
texinfo.texi(,4741) first node of a Texinfo file.@refill
texinfo.texi(,4742) 
texinfo.texi(,4743) Even when you explicitly specify all pointers, that does not mean you
texinfo.texi(,4744) can write the nodes in the Texinfo source file in an arbitrary order!
texinfo.texi(,4745) Because @TeX{} processes the file sequentially, irrespective of node
texinfo.texi(,4746) pointers, you must write the nodes in the order you wish them to appear
texinfo.texi(,4747) in the printed output.
texinfo.texi(,4748) 
texinfo.texi(,4749) 
texinfo.texi(,4750) @node Writing a Node
texinfo.texi(,4751) @subsection How to Write an @code{@@node} Line
texinfo.texi(,4752) @cindex Writing an @code{@@node} line
texinfo.texi(,4753) @cindex @code{@@node} line writing
texinfo.texi(,4754) @cindex Node line writing
texinfo.texi(,4755) 
texinfo.texi(,4756) The easiest way to write an @code{@@node} line is to write @code{@@node}
texinfo.texi(,4757) at the beginning of a line and then the name of the node, like
texinfo.texi(,4758) this:@refill
texinfo.texi(,4759) 
texinfo.texi(,4760) @example
texinfo.texi(,4761) @@node @var{node-name}
texinfo.texi(,4762) @end example
texinfo.texi(,4763) 
texinfo.texi(,4764) If you are using GNU Emacs, you can use the update node commands
texinfo.texi(,4765) provided by Texinfo mode to insert the names of the pointers; or you
texinfo.texi(,4766) can leave the pointers out of the Texinfo file and let @code{makeinfo}
texinfo.texi(,4767) insert node pointers into the Info file it creates.  (@xref{Texinfo
texinfo.texi(,4768) Mode}, and @ref{makeinfo Pointer Creation}.)@refill
texinfo.texi(,4769) 
texinfo.texi(,4770) Alternatively, you can insert the `Next', `Previous', and `Up'
texinfo.texi(,4771) pointers yourself.  If you do this, you may find it helpful to use the
texinfo.texi(,4772) Texinfo mode keyboard command @kbd{C-c C-c n}.  This command inserts
texinfo.texi(,4773) @samp{@@node} and a comment line listing the names of the pointers in
texinfo.texi(,4774) their proper order.  The comment line helps you keep track of which
texinfo.texi(,4775) arguments are for which pointers.  This comment line is especially useful
texinfo.texi(,4776) if you are not familiar with Texinfo.@refill
texinfo.texi(,4777) 
texinfo.texi(,4778) The template for a fully-written-out node line with `Next', `Previous',
texinfo.texi(,4779) and `Up' pointers looks like this:@refill
texinfo.texi(,4780) 
texinfo.texi(,4781) @example
texinfo.texi(,4782) @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
texinfo.texi(,4783) @end example
texinfo.texi(,4784) 
texinfo.texi(,4785) If you wish, you can ignore @code{@@node} lines altogether in your first
texinfo.texi(,4786) draft and then use the @code{texinfo-insert-node-lines} command to
texinfo.texi(,4787) create @code{@@node} lines for you.  However, we do not recommend this
texinfo.texi(,4788) practice.  It is better to name the node itself at the same time that
texinfo.texi(,4789) you write a segment so you can easily make cross references.  A large
texinfo.texi(,4790) number of cross references are an especially important feature of a good
texinfo.texi(,4791) Info file.
texinfo.texi(,4792) 
texinfo.texi(,4793) After you have inserted an @code{@@node} line, you should immediately
texinfo.texi(,4794) write an @@-command for the chapter or section and insert its name.
texinfo.texi(,4795) Next (and this is important!), put in several index entries.  Usually,
texinfo.texi(,4796) you will find at least two and often as many as four or five ways of
texinfo.texi(,4797) referring to the node in the index.  Use them all.  This will make it
texinfo.texi(,4798) much easier for people to find the node.
texinfo.texi(,4799) 
texinfo.texi(,4800) 
texinfo.texi(,4801) @node Node Line Tips
texinfo.texi(,4802) @subsection @code{@@node} Line Tips
texinfo.texi(,4803) 
texinfo.texi(,4804) Here are three suggestions:
texinfo.texi(,4805) 
texinfo.texi(,4806) @itemize @bullet
texinfo.texi(,4807) @item
texinfo.texi(,4808) Try to pick node names that are informative but short.@refill
texinfo.texi(,4809) 
texinfo.texi(,4810) In the Info file, the file name, node name, and pointer names are all
texinfo.texi(,4811) inserted on one line, which may run into the right edge of the window.
texinfo.texi(,4812) (This does not cause a problem with Info, but is ugly.)@refill
texinfo.texi(,4813) 
texinfo.texi(,4814) @item
texinfo.texi(,4815) Try to pick node names that differ from each other near the beginnings
texinfo.texi(,4816) of their names.  This way, it is easy to use automatic name completion in
texinfo.texi(,4817) Info.@refill
texinfo.texi(,4818) 
texinfo.texi(,4819) @item
texinfo.texi(,4820) By convention, node names are capitalized just as they would be for
texinfo.texi(,4821) section or chapter titles---initial and significant words are
texinfo.texi(,4822) capitalized; others are not.@refill
texinfo.texi(,4823) @end itemize
texinfo.texi(,4824) 
texinfo.texi(,4825) 
texinfo.texi(,4826) @node Node Line Requirements, First Node, Node Line Tips, node
texinfo.texi(,4827) @subsection @code{@@node} Line Requirements
texinfo.texi(,4828) 
texinfo.texi(,4829) @cindex Node line requirements
texinfo.texi(,4830) @cindex Restrictions on node names
texinfo.texi(,4831) Here are several requirements for @code{@@node} lines:
texinfo.texi(,4832) 
texinfo.texi(,4833) @itemize @bullet
texinfo.texi(,4834) @cindex Unique nodename requirement
texinfo.texi(,4835) @cindex Node name must be unique
texinfo.texi(,4836) @item
texinfo.texi(,4837) All the node names for a single Info file must be unique.@refill
texinfo.texi(,4838) 
texinfo.texi(,4839) Duplicates confuse the Info movement commands.  This means, for
texinfo.texi(,4840) example, that if you end every chapter with a summary, you must name
texinfo.texi(,4841) each summary node differently.  You cannot just call each one
texinfo.texi(,4842) ``Summary''.  You may, however, duplicate the titles of chapters, sections,
texinfo.texi(,4843) and the like.  Thus you can end each chapter in a book with a section
texinfo.texi(,4844) called ``Summary'', so long as the node names for those sections are all
texinfo.texi(,4845) different.@refill
texinfo.texi(,4846) 
texinfo.texi(,4847) @item
texinfo.texi(,4848) A pointer name must be the name of a node.@refill
texinfo.texi(,4849) 
texinfo.texi(,4850) The node to which a pointer points may come before or after the
texinfo.texi(,4851) node containing the pointer.
texinfo.texi(,4852) 
texinfo.texi(,4853) @cindex @@-commands in nodename
texinfo.texi(,4854) @cindex Node name, should not contain @@-commands
texinfo.texi(,4855) @item
texinfo.texi(,4856) @w{@@-commands} used in node names generally confuse Info, so you
texinfo.texi(,4857) should avoid them.  This includes punctuation characters that are
texinfo.texi(,4858) escaped with a @samp{@@}, such as @code{@@} and @code{@{}.  For a few
texinfo.texi(,4859) rare cases when this is useful, Texinfo has limited support for using
texinfo.texi(,4860) @w{@@-commands} in node names; see @ref{Pointer Validation}.
texinfo.texi(,4861) 
texinfo.texi(,4862) @need 750
texinfo.texi(,4863) Thus, the beginning of the section called @code{@@chapter} looks like
texinfo.texi(,4864) this:@refill
texinfo.texi(,4865) 
texinfo.texi(,4866) @smallexample
texinfo.texi(,4867) @group
texinfo.texi(,4868) @@node  chapter, unnumbered & appendix, makeinfo top, Structuring
texinfo.texi(,4869) @@comment  node-name,  next,  previous,  up
texinfo.texi(,4870) @@section @@code@{@@@@chapter@}
texinfo.texi(,4871) @@findex chapter
texinfo.texi(,4872) @end group
texinfo.texi(,4873) @end smallexample
texinfo.texi(,4874) 
texinfo.texi(,4875) @item
texinfo.texi(,4876) @cindex Parentheses in nodename
texinfo.texi(,4877) You cannot use parentheses in node names, because a node name such as
texinfo.texi(,4878) @samp{(foo)bar} is interpreted by the Info readers as a node
texinfo.texi(,4879) @samp{bar} in an Info file @file{foo}.
texinfo.texi(,4880) 
texinfo.texi(,4881) @item
texinfo.texi(,4882) @cindex Apostrophe in nodename
texinfo.texi(,4883) @cindex Colon in nodename
texinfo.texi(,4884) @cindex Comma in nodename
texinfo.texi(,4885) @cindex Period in nodename
texinfo.texi(,4886) @cindex Characters, invalid in node name
texinfo.texi(,4887) @cindex Invalid characters in node names
texinfo.texi(,4888) Unfortunately, you cannot use periods, commas, colons or apostrophes
texinfo.texi(,4889) within a node name; these confuse @TeX{} or the Info formatters.
texinfo.texi(,4890) 
texinfo.texi(,4891) @need 700
texinfo.texi(,4892) For example, the following is a section title:
texinfo.texi(,4893) 
texinfo.texi(,4894) @smallexample
texinfo.texi(,4895) @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
texinfo.texi(,4896) @end smallexample
texinfo.texi(,4897) 
texinfo.texi(,4898) @noindent
texinfo.texi(,4899) The corresponding node name is:
texinfo.texi(,4900) 
texinfo.texi(,4901) @smallexample
texinfo.texi(,4902) unnumberedsec appendixsec heading
texinfo.texi(,4903) @end smallexample
texinfo.texi(,4904) 
texinfo.texi(,4905) @cindex Case in node name
texinfo.texi(,4906) @item
texinfo.texi(,4907) Case is significant.
texinfo.texi(,4908) @end itemize
texinfo.texi(,4909) 
texinfo.texi(,4910) 
texinfo.texi(,4911) @node First Node
texinfo.texi(,4912) @subsection The First Node
texinfo.texi(,4913) @cindex Top node is first
texinfo.texi(,4914) @cindex First node
texinfo.texi(,4915) 
texinfo.texi(,4916) The first node of a Texinfo file is the @dfn{Top} node, except in an
texinfo.texi(,4917) included file (@pxref{Include Files}).  The Top node should contain a
texinfo.texi(,4918) short summary, copying permissions, and a master menu.  @xref{The Top
texinfo.texi(,4919) Node}, for more information on the Top node contents and examples.
texinfo.texi(,4920) 
texinfo.texi(,4921) Here is a description of the node pointers to be used in the Top node:
texinfo.texi(,4922) 
texinfo.texi(,4923) @itemize @bullet
texinfo.texi(,4924) 
texinfo.texi(,4925) @item
texinfo.texi(,4926) @cindex Up node of Top node
texinfo.texi(,4927) @cindex (dir) as Up node of Top node
texinfo.texi(,4928) The Top node (which must be named @samp{top} or @samp{Top}) should have
texinfo.texi(,4929) as its `Up' node the name of a node in another file, where there is a
texinfo.texi(,4930) menu that leads to this file.  Specify the file name in parentheses.
texinfo.texi(,4931) 
texinfo.texi(,4932) Usually, all Info files are installed in the same Info directory tree;
texinfo.texi(,4933) in this case, use @samp{(dir)} as the parent of the Top node; this is
texinfo.texi(,4934) short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
texinfo.texi(,4935) file, which contains the main menu for the Info system as a whole. 
texinfo.texi(,4936) 
texinfo.texi(,4937) @item
texinfo.texi(,4938) @cindex Previous node of Top node
texinfo.texi(,4939) On the other hand, do not define the `Previous' node of the Top node to
texinfo.texi(,4940) be @samp{(dir)}, as it causes confusing behavior for users: if you are
texinfo.texi(,4941) in the Top node and hits @key{DEL} to go backwards, you wind up in the
texinfo.texi(,4942) middle of the some other entry in the @file{dir} file, which has nothing
texinfo.texi(,4943) to do with what you were reading.
texinfo.texi(,4944) 
texinfo.texi(,4945) @item
texinfo.texi(,4946) @cindex Next node of Top node
texinfo.texi(,4947) The `Next' node of the Top node should be the first chapter in your
texinfo.texi(,4948) document.
texinfo.texi(,4949) 
texinfo.texi(,4950) @end itemize
texinfo.texi(,4951) 
texinfo.texi(,4952) @xref{Installing an Info File}, for more information about installing
texinfo.texi(,4953) an Info file in the @file{info} directory.
texinfo.texi(,4954) 
texinfo.texi(,4955) For concreteness, here is an example with explicit pointers (which you
texinfo.texi(,4956) can maintain automatically with the texinfo mode commands):
texinfo.texi(,4957) 
texinfo.texi(,4958) Or you can leave the pointers off entirely and let the tools implicitly
texinfo.texi(,4959) define them.  This is recommended.  Thus:
texinfo.texi(,4960) 
texinfo.texi(,4961) @example
texinfo.texi(,4962) @@node Top
texinfo.texi(,4963) @end example
texinfo.texi(,4964) 
texinfo.texi(,4965) 
texinfo.texi(,4966) @node makeinfo top command
texinfo.texi(,4967) @subsection The @code{@@top} Sectioning Command
texinfo.texi(,4968) @findex top @r{(@@-command)}
texinfo.texi(,4969) 
texinfo.texi(,4970) A special sectioning command, @code{@@top} should be used with the
texinfo.texi(,4971) @code{@@node Top} line.  The @code{@@top} sectioning command tells
texinfo.texi(,4972) @code{makeinfo} that it marks the `Top' node in the file.  It provides
texinfo.texi(,4973) the information that @code{makeinfo} needs to insert node pointers
texinfo.texi(,4974) automatically.  Write the @code{@@top} command at the beginning of the
texinfo.texi(,4975) line immediately following the @code{@@node Top} line.  Write the title
texinfo.texi(,4976) on the remaining part of the same line as the @code{@@top} command.
texinfo.texi(,4977) 
texinfo.texi(,4978) In Info, the @code{@@top} sectioning command causes the title to appear
texinfo.texi(,4979) on a line by itself, with a line of asterisks inserted underneath, as
texinfo.texi(,4980) other sectioning commands do.
texinfo.texi(,4981) 
texinfo.texi(,4982) In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
texinfo.texi(,4983) sectioning command is merely a synonym for @code{@@unnumbered}.
texinfo.texi(,4984) Neither of these formatters require an @code{@@top} command, and do
texinfo.texi(,4985) nothing special with it.  You can use @code{@@chapter} or
texinfo.texi(,4986) @code{@@unnumbered} after the @code{@@node Top} line when you use
texinfo.texi(,4987) these formatters.  Also, you can use @code{@@chapter} or
texinfo.texi(,4988) @code{@@unnumbered} when you use the Texinfo updating commands to
texinfo.texi(,4989) create or update pointers and menus.
texinfo.texi(,4990) 
texinfo.texi(,4991) Thus, in practice, a Top node starts like this:
texinfo.texi(,4992) 
texinfo.texi(,4993) @example
texinfo.texi(,4994) @@node Top
texinfo.texi(,4995) @@top Your Manual Title
texinfo.texi(,4996) @end example
texinfo.texi(,4997) 
texinfo.texi(,4998) 
texinfo.texi(,4999) @node makeinfo Pointer Creation
texinfo.texi(,5000) @section Creating Pointers with @code{makeinfo}
texinfo.texi(,5001) @cindex Creating pointers with @code{makeinfo}
texinfo.texi(,5002) @cindex Pointer creation with @code{makeinfo}
texinfo.texi(,5003) @cindex Automatic pointer creation with @code{makeinfo}
texinfo.texi(,5004) 
texinfo.texi(,5005) The @code{makeinfo} program has a feature for automatically defining
texinfo.texi(,5006) node pointers for a hierarchically organized file.
texinfo.texi(,5007) 
texinfo.texi(,5008) When you take advantage of this feature, you do not need to write the
texinfo.texi(,5009) `Next', `Previous', and `Up' pointers after the name of a node.
texinfo.texi(,5010) However, you must write a sectioning command, such as @code{@@chapter}
texinfo.texi(,5011) or @code{@@section}, on the line immediately following each truncated
texinfo.texi(,5012) @code{@@node} line (except that comment lines may intervene).
texinfo.texi(,5013) 
texinfo.texi(,5014) In addition, you must follow the `Top' @code{@@node} line with a line
texinfo.texi(,5015) beginning with @code{@@top} to mark the `Top' node in the
texinfo.texi(,5016) file.  @xref{makeinfo top, , @code{@@top}}.
texinfo.texi(,5017) 
texinfo.texi(,5018) Finally, you must write the name of each node (except for the `Top'
texinfo.texi(,5019) node) in a menu that is one or more hierarchical levels above the
texinfo.texi(,5020) node's hierarchical level.
texinfo.texi(,5021) 
texinfo.texi(,5022) This node pointer insertion feature in @code{makeinfo} relieves you from
texinfo.texi(,5023) the need to update menus and pointers manually or with Texinfo mode
texinfo.texi(,5024) commands.  (@xref{Updating Nodes and Menus}.)
texinfo.texi(,5025) 
texinfo.texi(,5026) In most cases, you will want to take advantage of this feature and not
texinfo.texi(,5027) redundantly specify node pointers.  However, Texinfo documents are not
texinfo.texi(,5028) required to be organized hierarchically or in fact contain sectioning
texinfo.texi(,5029) commands at all.  For example, if you never intend the document to be
texinfo.texi(,5030) printed.  In those cases, you will need to explicitly specify the pointers.
texinfo.texi(,5031) 
texinfo.texi(,5032) 
texinfo.texi(,5033) @node anchor
texinfo.texi(,5034) @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
texinfo.texi(,5035) 
texinfo.texi(,5036) @findex anchor
texinfo.texi(,5037) @cindex Anchors
texinfo.texi(,5038) @cindex Cross-reference targets, arbitrary
texinfo.texi(,5039) @cindex Targets for cross-references, arbitrary
texinfo.texi(,5040) 
texinfo.texi(,5041) An @dfn{anchor} is a position in your document, labeled so that
texinfo.texi(,5042) cross-references can refer to it, just as they can to nodes.  You create
texinfo.texi(,5043) an anchor with the @code{@@anchor} command, and give the label as a
texinfo.texi(,5044) normal brace-delimited argument.  For example:
texinfo.texi(,5045) 
texinfo.texi(,5046) @example
texinfo.texi(,5047) This marks the @@anchor@{x-spot@}spot.
texinfo.texi(,5048) @dots{}
texinfo.texi(,5049) @@xref@{x-spot,,the spot@}.
texinfo.texi(,5050) @end example
texinfo.texi(,5051) 
texinfo.texi(,5052) @noindent produces:
texinfo.texi(,5053) 
texinfo.texi(,5054) @example
texinfo.texi(,5055) This marks the spot.
texinfo.texi(,5056) @dots{}
texinfo.texi(,5057) See [the spot], page 1.
texinfo.texi(,5058) @end example
texinfo.texi(,5059) 
texinfo.texi(,5060) As you can see, the @code{@@anchor} command itself produces no output.
texinfo.texi(,5061) This example defines an anchor `x-spot' just before the word `spot'.
texinfo.texi(,5062) You can refer to it later with an @code{@@xref} or other cross-reference
texinfo.texi(,5063) command, as shown.  @xref{Cross References}, for details on the
texinfo.texi(,5064) cross-reference commands.
texinfo.texi(,5065) 
texinfo.texi(,5066) It is best to put @code{@@anchor} commands just before the position you
texinfo.texi(,5067) wish to refer to; that way, the reader's eye is led on to the correct
texinfo.texi(,5068) text when they jump to the anchor.  You can put the @code{@@anchor}
texinfo.texi(,5069) command on a line by itself if that helps readability of the source.
texinfo.texi(,5070) Spaces are always ignored after @code{@@anchor}.
texinfo.texi(,5071) 
texinfo.texi(,5072) Anchor names and node names may not conflict.  Anchors and nodes are
texinfo.texi(,5073) given similar treatment in some ways; for example, the @code{goto-node}
texinfo.texi(,5074) command in standalone Info takes either an anchor name or a node name as
texinfo.texi(,5075) an argument.  (@xref{goto-node,,,info-stnd,GNU Info}.)
texinfo.texi(,5076) 
texinfo.texi(,5077) 
texinfo.texi(,5078) @node Menus
texinfo.texi(,5079) @chapter Menus
texinfo.texi(,5080) @cindex Menus
texinfo.texi(,5081) @findex menu
texinfo.texi(,5082) 
texinfo.texi(,5083) @dfn{Menus} contain pointers to subordinate nodes.@footnote{Menus can
texinfo.texi(,5084) carry you to any node, regardless of the hierarchical structure; even to
texinfo.texi(,5085) nodes in a different Info file.  However, the GNU Emacs Texinfo mode
texinfo.texi(,5086) updating commands work only to create menus of subordinate nodes.
texinfo.texi(,5087) Conventionally, cross references are used to refer to other nodes.} In
texinfo.texi(,5088) Info, you use menus to go to such nodes.  Menus have no effect in
texinfo.texi(,5089) printed manuals and do not appear in them.
texinfo.texi(,5090) 
texinfo.texi(,5091) By convention, a menu is put at the end of a node since a reader who
texinfo.texi(,5092) uses the menu may not see text that follows it.  Furthermore, a node
texinfo.texi(,5093) that has a menu should not contain much text. If you have a lot of text
texinfo.texi(,5094) and a menu, move most of the text into a new subnode---all but a few
texinfo.texi(,5095) lines.  Otherwise, a reader with a terminal that displays only a few
texinfo.texi(,5096) lines may miss the menu and its associated text.  As a practical matter,
texinfo.texi(,5097) you should locate a menu within 20 lines of the beginning of the
texinfo.texi(,5098) node.
texinfo.texi(,5099) 
texinfo.texi(,5100) @menu
texinfo.texi(,5101) * Menu Location::               Put a menu in a short node.
texinfo.texi(,5102) * Writing a Menu::              What is a menu?
texinfo.texi(,5103) * Menu Parts::                  A menu entry has three parts.
texinfo.texi(,5104) * Less Cluttered Menu Entry::   Two part menu entry.
texinfo.texi(,5105) * Menu Example::                Two and three part menu entries.
texinfo.texi(,5106) * Other Info Files::            How to refer to a different Info file.
texinfo.texi(,5107) @end menu
texinfo.texi(,5108) 
texinfo.texi(,5109) 
texinfo.texi(,5110) @node Menu Location, Writing a Menu, Menus, Menus
texinfo.texi(,5112) @heading Menus Need Short Nodes
texinfo.texi(,5114) @cindex Menu location
texinfo.texi(,5115) @cindex Location of menus
texinfo.texi(,5116) @cindex Nodes for menus are short
texinfo.texi(,5117) @cindex Short nodes for menus
texinfo.texi(,5118) 
texinfo.texi(,5119) The short text before a menu may look awkward in a printed manual.  To
texinfo.texi(,5120) avoid this, you can write a menu near the beginning of its node and
texinfo.texi(,5121) follow the menu by an @code{@@node} line, and then an @code{@@heading}
texinfo.texi(,5122) line located within @code{@@ifinfo} and @code{@@end ifinfo}.  This way,
texinfo.texi(,5123) the menu, @code{@@node} line, and title appear only in the Info file,
texinfo.texi(,5124) not the printed document.
texinfo.texi(,5125) 
texinfo.texi(,5126) For example, the preceding two paragraphs follow an Info-only menu,
texinfo.texi(,5127) @code{@@node} line, and heading, and look like this:
texinfo.texi(,5128) 
texinfo.texi(,5129) @example
texinfo.texi(,5130) @group
texinfo.texi(,5131) @@menu
texinfo.texi(,5132) * Menu Location::             Put a menu in a short node.
texinfo.texi(,5133) * Writing a Menu::            What is a menu?
texinfo.texi(,5134) * Menu Parts::                A menu entry has three parts.
texinfo.texi(,5135) * Less Cluttered Menu Entry:: Two part menu entry.
texinfo.texi(,5136) * Menu Example::              Two and three part entries.
texinfo.texi(,5137) * Other Info Files::          How to refer to a different
texinfo.texi(,5138)                                 Info file.
texinfo.texi(,5139) @@end menu
texinfo.texi(,5140) 
texinfo.texi(,5141) @@node Menu Location, Writing a Menu, , Menus
texinfo.texi(,5142) @@ifinfo
texinfo.texi(,5143) @@heading Menus Need Short Nodes
texinfo.texi(,5144) @@end ifinfo
texinfo.texi(,5145) @end group
texinfo.texi(,5146) @end example
texinfo.texi(,5147) 
texinfo.texi(,5148) The Texinfo file for this document contains a number of
texinfo.texi(,5149) examples of this procedure; one is at the beginning of this chapter.
texinfo.texi(,5150) 
texinfo.texi(,5151) 
texinfo.texi(,5152) @node Writing a Menu, Menu Parts, Menu Location, Menus
texinfo.texi(,5153) @section Writing a Menu
texinfo.texi(,5154) @cindex Writing a menu
texinfo.texi(,5155) @cindex Menu writing
texinfo.texi(,5156) 
texinfo.texi(,5157) A menu consists of an @code{@@menu} command on a line by
texinfo.texi(,5158) itself followed by menu entry lines or menu comment lines
texinfo.texi(,5159) and then by an @code{@@end menu} command on a line by
texinfo.texi(,5160) itself.@refill
texinfo.texi(,5161) 
texinfo.texi(,5162) A menu looks like this:@refill
texinfo.texi(,5163) 
texinfo.texi(,5164) @example
texinfo.texi(,5165) @group
texinfo.texi(,5166) @@menu
texinfo.texi(,5167) Larger Units of Text
texinfo.texi(,5168) 
texinfo.texi(,5169) * Files::                       All about handling files.
texinfo.texi(,5170) * Multiples: Buffers.           Multiple buffers; editing
texinfo.texi(,5171)                                   several files at once.
texinfo.texi(,5172) @@end menu
texinfo.texi(,5173) @end group
texinfo.texi(,5174) @end example
texinfo.texi(,5175) 
texinfo.texi(,5176) In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
texinfo.texi(,5177) entry}.  (Note the space after the asterisk.)  A line that does not
texinfo.texi(,5178) start with an @w{@samp{* }} may also appear in a menu.  Such a line is
texinfo.texi(,5179) not a menu entry but is a menu comment line that appears in the Info
texinfo.texi(,5180) file.  In the example above, the line @samp{Larger Units of Text} is a
texinfo.texi(,5181) menu comment line; the two lines starting with @w{@samp{* }} are menu
texinfo.texi(,5182) @cindex Spaces, in menus
texinfo.texi(,5183) entries.  Space characters in a menu are preserved as-is; this allows
texinfo.texi(,5184) you to format the menu as you wish.
texinfo.texi(,5185) 
texinfo.texi(,5186) 
texinfo.texi(,5187) @node Menu Parts, Less Cluttered Menu Entry, Writing a Menu, Menus
texinfo.texi(,5188) @section The Parts of a Menu
texinfo.texi(,5189) @cindex Parts of a menu
texinfo.texi(,5190) @cindex Menu parts
texinfo.texi(,5191) @cindex @code{@@menu} parts
texinfo.texi(,5192) 
texinfo.texi(,5193) A menu entry has three parts, only the second of which is required:
texinfo.texi(,5194) 
texinfo.texi(,5195) @enumerate
texinfo.texi(,5196) @item
texinfo.texi(,5197) The menu entry name (optional).
texinfo.texi(,5198) 
texinfo.texi(,5199) @item
texinfo.texi(,5200) The name of the node (required).
texinfo.texi(,5201) 
texinfo.texi(,5202) @item
texinfo.texi(,5203) A description of the item (optional).
texinfo.texi(,5204) @end enumerate
texinfo.texi(,5205) 
texinfo.texi(,5206) The template for a menu entry looks like this:@refill
texinfo.texi(,5207) 
texinfo.texi(,5208) @example
texinfo.texi(,5209) * @var{menu-entry-name}: @var{node-name}.   @var{description}
texinfo.texi(,5210) @end example
texinfo.texi(,5211) 
texinfo.texi(,5212) Follow the menu entry name with a single colon and follow the node name
texinfo.texi(,5213) with tab, comma, period, or newline.@refill
texinfo.texi(,5214) 
texinfo.texi(,5215) In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
texinfo.texi(,5216) command.  The menu entry name is what the user types after the @kbd{m}
texinfo.texi(,5217) command.@refill
texinfo.texi(,5218) 
texinfo.texi(,5219) The third part of a menu entry is a descriptive phrase or sentence.
texinfo.texi(,5220) Menu entry names and node names are often short; the description
texinfo.texi(,5221) explains to the reader what the node is about.  A useful description
texinfo.texi(,5222) complements the node name rather than repeats it.  The description,
texinfo.texi(,5223) which is optional, can spread over two or more lines; if it does, some
texinfo.texi(,5224) authors prefer to indent the second line while others prefer to align it
texinfo.texi(,5225) with the first (and all others).  It's up to you.
texinfo.texi(,5226) 
texinfo.texi(,5227) 
texinfo.texi(,5228) @node Less Cluttered Menu Entry, Menu Example, Menu Parts, Menus
texinfo.texi(,5229) @comment  node-name,  next,  previous,  up
texinfo.texi(,5230) @section Less Cluttered Menu Entry
texinfo.texi(,5231) @cindex Two part menu entry
texinfo.texi(,5232) @cindex Double-colon menu entries
texinfo.texi(,5233) @cindex Menu entries with two colons
texinfo.texi(,5234) @cindex Less cluttered menu entry
texinfo.texi(,5235) @cindex Uncluttered menu entry
texinfo.texi(,5236) 
texinfo.texi(,5237) When the menu entry name and node name are the same, you can write
texinfo.texi(,5238) the name immediately after the asterisk and space at the beginning of
texinfo.texi(,5239) the line and follow the name with two colons.@refill
texinfo.texi(,5240) 
texinfo.texi(,5241) @need 800
texinfo.texi(,5242) For example, write
texinfo.texi(,5243) 
texinfo.texi(,5244) @example
texinfo.texi(,5245) * Name::                                    @var{description}
texinfo.texi(,5246) @end example
texinfo.texi(,5247) 
texinfo.texi(,5248) @need 800
texinfo.texi(,5249) @noindent
texinfo.texi(,5250) instead of
texinfo.texi(,5251) 
texinfo.texi(,5252) @example
texinfo.texi(,5253) * Name: Name.                               @var{description}
texinfo.texi(,5254) @end example
texinfo.texi(,5255) 
texinfo.texi(,5256) You should use the node name for the menu entry name whenever possible,
texinfo.texi(,5257) since it reduces visual clutter in the menu.@refill
texinfo.texi(,5258) 
texinfo.texi(,5259) @node Menu Example, Other Info Files, Less Cluttered Menu Entry, Menus
texinfo.texi(,5260) @comment  node-name,  next,  previous,  up
texinfo.texi(,5261) @section A Menu Example
texinfo.texi(,5262) @cindex Menu example
texinfo.texi(,5263) @cindex Example menu
texinfo.texi(,5264) 
texinfo.texi(,5265) A menu looks like this in Texinfo:@refill
texinfo.texi(,5266) 
texinfo.texi(,5267) @example
texinfo.texi(,5268) @group
texinfo.texi(,5269) @@menu
texinfo.texi(,5270) * menu entry name: Node name.   A short description.
texinfo.texi(,5271) * Node name::                   This form is preferred.
texinfo.texi(,5272) @@end menu
texinfo.texi(,5273) @end group
texinfo.texi(,5274) @end example
texinfo.texi(,5275) 
texinfo.texi(,5276) @need 800
texinfo.texi(,5277) @noindent
texinfo.texi(,5278) This produces:
texinfo.texi(,5279) 
texinfo.texi(,5280) @example
texinfo.texi(,5281) @group
texinfo.texi(,5282) * menu:
texinfo.texi(,5283) 
texinfo.texi(,5284) * menu entry name: Node name.   A short description.
texinfo.texi(,5285) * Node name::                   This form is preferred.
texinfo.texi(,5286) @end group
texinfo.texi(,5287) @end example
texinfo.texi(,5288) 
texinfo.texi(,5289) @need 700
texinfo.texi(,5290) Here is an example as you might see it in a Texinfo file:@refill
texinfo.texi(,5291) 
texinfo.texi(,5292) @example
texinfo.texi(,5293) @group
texinfo.texi(,5294) @@menu
texinfo.texi(,5295) Larger Units of Text
texinfo.texi(,5296) 
texinfo.texi(,5297) * Files::                       All about handling files.
texinfo.texi(,5298) * Multiples: Buffers.           Multiple buffers; editing
texinfo.texi(,5299)                                   several files at once.
texinfo.texi(,5300) @@end menu
texinfo.texi(,5301) @end group
texinfo.texi(,5302) @end example
texinfo.texi(,5303) 
texinfo.texi(,5304) @need 800
texinfo.texi(,5305) @noindent
texinfo.texi(,5306) This produces:
texinfo.texi(,5307) 
texinfo.texi(,5308) @example
texinfo.texi(,5309) @group
texinfo.texi(,5310) * menu:
texinfo.texi(,5311) Larger Units of Text
texinfo.texi(,5312) 
texinfo.texi(,5313) * Files::                       All about handling files.
texinfo.texi(,5314) * Multiples: Buffers.           Multiple buffers; editing
texinfo.texi(,5315)                                   several files at once.
texinfo.texi(,5316) @end group
texinfo.texi(,5317) @end example
texinfo.texi(,5318) 
texinfo.texi(,5319) In this example, the menu has two entries.  @samp{Files} is both a menu
texinfo.texi(,5320) entry name and the name of the node referred to by that name.
texinfo.texi(,5321) @samp{Multiples} is the menu entry name; it refers to the node named
texinfo.texi(,5322) @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
texinfo.texi(,5323) appears in the menu, but is not an entry.@refill
texinfo.texi(,5324) 
texinfo.texi(,5325) Since no file name is specified with either @samp{Files} or
texinfo.texi(,5326) @samp{Buffers}, they must be the names of nodes in the same Info file
texinfo.texi(,5327) (@pxref{Other Info Files, , Referring to Other Info Files}).@refill
texinfo.texi(,5328) 
texinfo.texi(,5329) @node Other Info Files,  , Menu Example, Menus
texinfo.texi(,5330) @comment  node-name,  next,  previous,  up
texinfo.texi(,5331) @section Referring to Other Info Files
texinfo.texi(,5332) @cindex Referring to other Info files
texinfo.texi(,5333) @cindex Nodes in other Info files
texinfo.texi(,5334) @cindex Other Info files' nodes
texinfo.texi(,5335) @cindex Going to other Info files' nodes
texinfo.texi(,5336) @cindex Info; other files' nodes
texinfo.texi(,5337) 
texinfo.texi(,5338) You can create a menu entry that enables a reader in Info to go to a
texinfo.texi(,5339) node in another Info file by writing the file name in parentheses just
texinfo.texi(,5340) before the node name.  In this case, you should use the three-part menu
texinfo.texi(,5341) entry format, which saves the reader from having to type the file
texinfo.texi(,5342) name.@refill
texinfo.texi(,5343) 
texinfo.texi(,5344) @need 800
texinfo.texi(,5345) The format looks like this:@refill
texinfo.texi(,5346) 
texinfo.texi(,5347) @example
texinfo.texi(,5348) @group
texinfo.texi(,5349) @@menu
texinfo.texi(,5350) * @var{first-entry-name}:(@var{filename})@var{nodename}.     @var{description}
texinfo.texi(,5351) * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
texinfo.texi(,5352) @@end menu
texinfo.texi(,5353) @end group
texinfo.texi(,5354) @end example
texinfo.texi(,5355) 
texinfo.texi(,5356) For example, to refer directly to the @samp{Outlining} and
texinfo.texi(,5357) @samp{Rebinding} nodes in the @cite{Emacs Manual}, you would write a
texinfo.texi(,5358) menu like this:@refill
texinfo.texi(,5359) 
texinfo.texi(,5360) @example
texinfo.texi(,5361) @group
texinfo.texi(,5362) @@menu
texinfo.texi(,5363) * Outlining: (emacs)Outline Mode. The major mode for
texinfo.texi(,5364)                                   editing outlines.
texinfo.texi(,5365) * Rebinding: (emacs)Rebinding.    How to redefine the
texinfo.texi(,5366)                                   meaning of a key.
texinfo.texi(,5367) @@end menu
texinfo.texi(,5368) @end group
texinfo.texi(,5369) @end example
texinfo.texi(,5370) 
texinfo.texi(,5371) If you do not list the node name, but only name the file, then Info
texinfo.texi(,5372) presumes that you are referring to the `Top' node.@refill
texinfo.texi(,5373) 
texinfo.texi(,5374) The @file{dir} file that contains the main menu for Info has menu
texinfo.texi(,5375) entries that list only file names.  These take you directly to the `Top'
texinfo.texi(,5376) nodes of each Info document.  (@xref{Installing an Info File}.)
texinfo.texi(,5377) 
texinfo.texi(,5378) @need 700
texinfo.texi(,5379) For example:
texinfo.texi(,5380) 
texinfo.texi(,5381) @example
texinfo.texi(,5382) @group
texinfo.texi(,5383) * Info: (info).         Documentation browsing system.
texinfo.texi(,5384) * Emacs: (emacs).       The extensible, self-documenting
texinfo.texi(,5385)                         text editor.
texinfo.texi(,5386) @end group
texinfo.texi(,5387) @end example
texinfo.texi(,5388) 
texinfo.texi(,5389) @noindent
texinfo.texi(,5390) (The @file{dir} top level directory for the Info system is an Info file,
texinfo.texi(,5391) not a Texinfo file, but a menu entry looks the same in both types of
texinfo.texi(,5392) file.)@refill
texinfo.texi(,5393) 
texinfo.texi(,5394) The GNU Emacs Texinfo mode menu updating commands only work with nodes
texinfo.texi(,5395) within the current buffer, so you cannot use them to create menus that
texinfo.texi(,5396) refer to other files.  You must write such menus by hand.
texinfo.texi(,5397) 
texinfo.texi(,5398) 
texinfo.texi(,5399) @node Cross References
texinfo.texi(,5400) @chapter Cross References
texinfo.texi(,5401) @cindex Making cross references
texinfo.texi(,5402) @cindex Cross references
texinfo.texi(,5403) @cindex References
texinfo.texi(,5404) 
texinfo.texi(,5405) @dfn{Cross references} are used to refer the reader to other parts of the
texinfo.texi(,5406) same or different Texinfo files.  In Texinfo, nodes and anchors are the
texinfo.texi(,5407) places to which cross references can refer.
texinfo.texi(,5408) 
texinfo.texi(,5409) @menu
texinfo.texi(,5410) * References::                  What cross references are for.
texinfo.texi(,5411) * Cross Reference Commands::    A summary of the different commands.
texinfo.texi(,5412) * Cross Reference Parts::       A cross reference has several parts.
texinfo.texi(,5413) * xref::                        Begin a reference with `See' @dots{}
texinfo.texi(,5414) * Top Node Naming::             How to refer to the beginning of another file.
texinfo.texi(,5415) * ref::                         A reference for the last part of a sentence.
texinfo.texi(,5416) * pxref::                       How to write a parenthetical cross reference.
texinfo.texi(,5417) * inforef::                     How to refer to an Info-only file.
texinfo.texi(,5418) * uref::                        How to refer to a uniform resource locator.
texinfo.texi(,5419) @end menu
texinfo.texi(,5420) 
texinfo.texi(,5421) @node References, Cross Reference Commands, Cross References, Cross References
texinfo.texi(,5423) @heading What References Are For
texinfo.texi(,5425) 
texinfo.texi(,5426) Often, but not always, a printed document should be designed so that
texinfo.texi(,5427) it can be read sequentially.  People tire of flipping back and forth
texinfo.texi(,5428) to find information that should be presented to them as they need
texinfo.texi(,5429) it.@refill
texinfo.texi(,5430) 
texinfo.texi(,5431) However, in any document, some information will be too detailed for
texinfo.texi(,5432) the current context, or incidental to it; use cross references to
texinfo.texi(,5433) provide access to such information.  Also, an online help system or a
texinfo.texi(,5434) reference manual is not like a novel; few read such documents in
texinfo.texi(,5435) sequence from beginning to end.  Instead, people look up what they
texinfo.texi(,5436) need.  For this reason, such creations should contain many cross
texinfo.texi(,5437) references to help readers find other information that they may not
texinfo.texi(,5438) have read.@refill
texinfo.texi(,5439) 
texinfo.texi(,5440) In a printed manual, a cross reference results in a page reference,
texinfo.texi(,5441) unless it is to another manual altogether, in which case the cross
texinfo.texi(,5442) reference names that manual.@refill
texinfo.texi(,5443) 
texinfo.texi(,5444) In Info, a cross reference results in an entry that you can follow using
texinfo.texi(,5445) the Info @samp{f} command.  (@inforef{Help-Adv, Some advanced Info
texinfo.texi(,5446) commands, info}.)@refill
texinfo.texi(,5447) 
texinfo.texi(,5448) The various cross reference commands use nodes (or anchors,
texinfo.texi(,5449) @pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
texinfo.texi(,5450) This is evident in Info, in which a cross reference takes you to the
texinfo.texi(,5451) specified location.  @TeX{} also uses nodes to define cross reference
texinfo.texi(,5452) locations, but the action is less obvious.  When @TeX{} generates a DVI
texinfo.texi(,5453) file, it records each node's page number and uses the page numbers in making
texinfo.texi(,5454) references.  Thus, if you are writing a manual that will only be
texinfo.texi(,5455) printed, and will not be used online, you must nonetheless write
texinfo.texi(,5456) @code{@@node} lines to name the places to which you make cross
texinfo.texi(,5457) references.@refill
texinfo.texi(,5458) 
texinfo.texi(,5459) @need 800
texinfo.texi(,5460) @node Cross Reference Commands, Cross Reference Parts, References, Cross References
texinfo.texi(,5461) @comment  node-name,  next,  previous,  up
texinfo.texi(,5462) @section Different Cross Reference Commands
texinfo.texi(,5463) @cindex Different cross reference commands
texinfo.texi(,5464) 
texinfo.texi(,5465) There are four different cross reference commands:@refill
texinfo.texi(,5466) 
texinfo.texi(,5467) @table @code
texinfo.texi(,5468) @item @@xref
texinfo.texi(,5469) Used to start a sentence in the printed manual saying @w{`See @dots{}'}
texinfo.texi(,5470) or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
texinfo.texi(,5471) 
texinfo.texi(,5472) @item @@ref
texinfo.texi(,5473) Used within or, more often, at the end of a sentence; same as
texinfo.texi(,5474) @code{@@xref} for Info; produces just the reference in the printed
texinfo.texi(,5475) manual without a preceding `See'.@refill
texinfo.texi(,5476) 
texinfo.texi(,5477) @item @@pxref
texinfo.texi(,5478) Used within parentheses to make a reference that suits both an Info
texinfo.texi(,5479) file and a printed book.  Starts with a lower case `see' within the
texinfo.texi(,5480) printed manual. (@samp{p} is for `parenthesis'.)@refill
texinfo.texi(,5481) 
texinfo.texi(,5482) @item @@inforef
texinfo.texi(,5483) Used to make a reference to an Info file for which there is no printed
texinfo.texi(,5484) manual.@refill
texinfo.texi(,5485) @end table
texinfo.texi(,5486) 
texinfo.texi(,5487) @noindent
texinfo.texi(,5488) (The @code{@@cite} command is used to make references to books and
texinfo.texi(,5489) manuals for which there is no corresponding Info file and, therefore,
texinfo.texi(,5490) no node to which to point.   @xref{cite, , @code{@@cite}}.)@refill
texinfo.texi(,5491) 
texinfo.texi(,5492) @node Cross Reference Parts, xref, Cross Reference Commands, Cross References
texinfo.texi(,5493) @comment  node-name,  next,  previous,  up
texinfo.texi(,5494) @section Parts of a Cross Reference
texinfo.texi(,5495) @cindex Cross reference parts
texinfo.texi(,5496) @cindex Parts of a cross reference
texinfo.texi(,5497) 
texinfo.texi(,5498) A cross reference command requires only one argument, which is the
texinfo.texi(,5499) name of the node to which it refers.  But a cross reference command
texinfo.texi(,5500) may contain up to four additional arguments.  By using these
texinfo.texi(,5501) arguments, you can provide a cross reference name for Info, a topic
texinfo.texi(,5502) description or section title for the printed output, the name of a
texinfo.texi(,5503) different Info file, and the name of a different printed
texinfo.texi(,5504) manual.@refill
texinfo.texi(,5505) 
texinfo.texi(,5506) Here is a simple cross reference example:@refill
texinfo.texi(,5507) 
texinfo.texi(,5508) @example
texinfo.texi(,5509) @@xref@{Node name@}.
texinfo.texi(,5510) @end example
texinfo.texi(,5511) 
texinfo.texi(,5512) @noindent
texinfo.texi(,5513) which produces
texinfo.texi(,5514) 
texinfo.texi(,5515) @example
texinfo.texi(,5516) *Note Node name::.
texinfo.texi(,5517) @end example
texinfo.texi(,5518) 
texinfo.texi(,5519) @noindent
texinfo.texi(,5520) and
texinfo.texi(,5521) 
texinfo.texi(,5522) @quotation
texinfo.texi(,5523) See Section @var{nnn} [Node name], page @var{ppp}.
texinfo.texi(,5524) @end quotation
texinfo.texi(,5525) 
texinfo.texi(,5526) @need 700
texinfo.texi(,5527) Here is an example of a full five-part cross reference:@refill
texinfo.texi(,5528) 
texinfo.texi(,5529) @example
texinfo.texi(,5530) @group
texinfo.texi(,5531) @@xref@{Node name, Cross Reference Name, Particular Topic,
texinfo.texi(,5532) info-file-name, A Printed Manual@}, for details.
texinfo.texi(,5533) @end group
texinfo.texi(,5534) @end example
texinfo.texi(,5535) 
texinfo.texi(,5536) @noindent
texinfo.texi(,5537) which produces
texinfo.texi(,5538) 
texinfo.texi(,5539) @example
texinfo.texi(,5540) *Note Cross Reference Name: (info-file-name)Node name,
texinfo.texi(,5541) for details.
texinfo.texi(,5542) @end example
texinfo.texi(,5543) 
texinfo.texi(,5544) @noindent
texinfo.texi(,5545) in Info and
texinfo.texi(,5546) 
texinfo.texi(,5547) @quotation
texinfo.texi(,5548) See section ``Particular Topic'' in @i{A Printed Manual}, for details.
texinfo.texi(,5549) @end quotation
texinfo.texi(,5550) 
texinfo.texi(,5551) @noindent
texinfo.texi(,5552) in a printed book.
texinfo.texi(,5553) 
texinfo.texi(,5554) The five possible arguments for a cross reference are:@refill
texinfo.texi(,5555) 
texinfo.texi(,5556) @enumerate
texinfo.texi(,5557) @item
texinfo.texi(,5558) The node or anchor name (required).  This is the location to which the
texinfo.texi(,5559) cross reference takes you.  In a printed document, the location of the
texinfo.texi(,5560) node provides the page reference only for references within the same
texinfo.texi(,5561) document.@refill
texinfo.texi(,5562) 
texinfo.texi(,5563) @item
texinfo.texi(,5564) The cross reference name for the Info reference, if it is to be different
texinfo.texi(,5565) from the node name.  If you include this argument, it becomes
texinfo.texi(,5566) the first part of the cross reference.  It is usually omitted.@refill
texinfo.texi(,5567) 
texinfo.texi(,5568) @item
texinfo.texi(,5569) A topic description or section name.  Often, this is the title of the
texinfo.texi(,5570) section.  This is used as the name of the reference in the printed
texinfo.texi(,5571) manual.  If omitted, the node name is used.@refill
texinfo.texi(,5572) 
texinfo.texi(,5573) @item
texinfo.texi(,5574) The name of the Info file in which the reference is located, if it is
texinfo.texi(,5575) different from the current file.  You need not include any @samp{.info}
texinfo.texi(,5576) suffix on the file name, since Info readers try appending it
texinfo.texi(,5577) automatically.
texinfo.texi(,5578) 
texinfo.texi(,5579) @item
texinfo.texi(,5580) The name of a printed manual from a different Texinfo file.@refill
texinfo.texi(,5581) @end enumerate
texinfo.texi(,5582) 
texinfo.texi(,5583) The template for a full five argument cross reference looks like
texinfo.texi(,5584) this:@refill
texinfo.texi(,5585) 
texinfo.texi(,5586) @example
texinfo.texi(,5587) @group
texinfo.texi(,5588) @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
texinfo.texi(,5589) @var{info-file-name}, @var{printed-manual-title}@}.
texinfo.texi(,5590) @end group
texinfo.texi(,5591) @end example
texinfo.texi(,5592) 
texinfo.texi(,5593) Cross references with one, two, three, four, and five arguments are
texinfo.texi(,5594) described separately following the description of @code{@@xref}.@refill
texinfo.texi(,5595) 
texinfo.texi(,5596) Write a node name in a cross reference in exactly the same way as in
texinfo.texi(,5597) the @code{@@node} line, including the same capitalization; otherwise, the
texinfo.texi(,5598) formatters may not find the reference.@refill
texinfo.texi(,5599) 
texinfo.texi(,5600) You can write cross reference commands within a paragraph, but note
texinfo.texi(,5601) how Info and @TeX{} format the output of each of the various commands:
texinfo.texi(,5602) write @code{@@xref} at the beginning of a sentence; write
texinfo.texi(,5603) @code{@@pxref} only within parentheses, and so on.@refill
texinfo.texi(,5604) 
texinfo.texi(,5605) @node xref, Top Node Naming, Cross Reference Parts, Cross References
texinfo.texi(,5606) @comment  node-name,  next,  previous,  up
texinfo.texi(,5607) @section @code{@@xref}
texinfo.texi(,5608) @findex xref
texinfo.texi(,5609) @cindex Cross references using @code{@@xref}
texinfo.texi(,5610) @cindex References using @code{@@xref}
texinfo.texi(,5611) 
texinfo.texi(,5612) The @code{@@xref} command generates a cross reference for the
texinfo.texi(,5613) beginning of a sentence.  The Info formatting commands convert it into
texinfo.texi(,5614) an Info cross reference, which the Info @samp{f} command can use to
texinfo.texi(,5615) bring you directly to another node.  The @TeX{} typesetting commands
texinfo.texi(,5616) convert it into a page reference, or a reference to another book or
texinfo.texi(,5617) manual.@refill
texinfo.texi(,5618) 
texinfo.texi(,5619) @menu
texinfo.texi(,5620) * Reference Syntax::            What a reference looks like and requires.
texinfo.texi(,5621) * One Argument::                @code{@@xref} with one argument.
texinfo.texi(,5622) * Two Arguments::               @code{@@xref} with two arguments.
texinfo.texi(,5623) * Three Arguments::             @code{@@xref} with three arguments.
texinfo.texi(,5624) * Four and Five Arguments::     @code{@@xref} with four and five arguments.
texinfo.texi(,5625) @end menu
texinfo.texi(,5626) 
texinfo.texi(,5627) @node Reference Syntax, One Argument, xref, xref
texinfo.texi(,5629) @subheading What a Reference Looks Like and Requires
texinfo.texi(,5631) 
texinfo.texi(,5632) Most often, an Info cross reference looks like this:@refill
texinfo.texi(,5633) 
texinfo.texi(,5634) @example
texinfo.texi(,5635) *Note @var{node-name}::.
texinfo.texi(,5636) @end example
texinfo.texi(,5637) 
texinfo.texi(,5638) @noindent
texinfo.texi(,5639) or like this
texinfo.texi(,5640) 
texinfo.texi(,5641) @example
texinfo.texi(,5642) *Note @var{cross-reference-name}: @var{node-name}.
texinfo.texi(,5643) @end example
texinfo.texi(,5644) 
texinfo.texi(,5645) @noindent
texinfo.texi(,5646) In @TeX{}, a cross reference looks like this:
texinfo.texi(,5647) 
texinfo.texi(,5648) @quotation
texinfo.texi(,5649) See Section @var{section-number} [@var{node-name}], page @var{page}.
texinfo.texi(,5650) @end quotation
texinfo.texi(,5651) 
texinfo.texi(,5652) @noindent
texinfo.texi(,5653) or like this
texinfo.texi(,5654) 
texinfo.texi(,5655) @quotation
texinfo.texi(,5656) See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
texinfo.texi(,5657) @end quotation
texinfo.texi(,5658) 
texinfo.texi(,5659) The @code{@@xref} command does not generate a period or comma to end
texinfo.texi(,5660) the cross reference in either the Info file or the printed output.
texinfo.texi(,5661) You must write that period or comma yourself; otherwise, Info will not
texinfo.texi(,5662) recognize the end of the reference.  (The @code{@@pxref} command works
texinfo.texi(,5663) differently.  @xref{pxref, , @code{@@pxref}}.)@refill
texinfo.texi(,5664) 
texinfo.texi(,5665) @quotation
texinfo.texi(,5666) @strong{Please note:} A period or comma @strong{must} follow the closing
texinfo.texi(,5667) brace of an @code{@@xref}.  It is required to terminate the cross
texinfo.texi(,5668) reference.  This period or comma will appear in the output, both in
texinfo.texi(,5669) the Info file and in the printed manual.@refill
texinfo.texi(,5670) @end quotation
texinfo.texi(,5671) 
texinfo.texi(,5672) @code{@@xref} must refer to an Info node by name.  Use @code{@@node}
texinfo.texi(,5673) to define the node (@pxref{Writing a Node}).@refill
texinfo.texi(,5674) 
texinfo.texi(,5675) @code{@@xref} is followed by several arguments inside braces, separated by
texinfo.texi(,5676) commas.  Whitespace before and after these commas is ignored.@refill
texinfo.texi(,5677) 
texinfo.texi(,5678) A cross reference requires only the name of a node; but it may contain
texinfo.texi(,5679) up to four additional arguments.  Each of these variations produces a
texinfo.texi(,5680) cross reference that looks somewhat different.@refill
texinfo.texi(,5681) 
texinfo.texi(,5682) @quotation
texinfo.texi(,5683) @strong{Please note:} Commas separate arguments in a cross reference;
texinfo.texi(,5684) avoid including them in the title or other part lest the formatters
texinfo.texi(,5685) mistake them for separators.@refill
texinfo.texi(,5686) @end quotation
texinfo.texi(,5687) 
texinfo.texi(,5688) @node One Argument, Two Arguments, Reference Syntax, xref
texinfo.texi(,5689) @subsection @code{@@xref} with One Argument
texinfo.texi(,5690) 
texinfo.texi(,5691) The simplest form of @code{@@xref} takes one argument, the name of
texinfo.texi(,5692) another node in the same Info file.    The Info formatters produce
texinfo.texi(,5693) output that the Info readers can use to jump to the reference; @TeX{}
texinfo.texi(,5694) produces output that specifies the page and section number for you.@refill
texinfo.texi(,5695) 
texinfo.texi(,5696) @need 700
texinfo.texi(,5697) @noindent
texinfo.texi(,5698) For example,
texinfo.texi(,5699) 
texinfo.texi(,5700) @example
texinfo.texi(,5701) @@xref@{Tropical Storms@}.
texinfo.texi(,5702) @end example
texinfo.texi(,5703) 
texinfo.texi(,5704) @noindent
texinfo.texi(,5705) produces
texinfo.texi(,5706) 
texinfo.texi(,5707) @example
texinfo.texi(,5708) *Note Tropical Storms::.
texinfo.texi(,5709) @end example
texinfo.texi(,5710) 
texinfo.texi(,5711) @noindent
texinfo.texi(,5712) and
texinfo.texi(,5713) 
texinfo.texi(,5714) @quotation
texinfo.texi(,5715) See Section 3.1 [Tropical Storms], page 24.
texinfo.texi(,5716) @end quotation
texinfo.texi(,5717) 
texinfo.texi(,5718) @noindent
texinfo.texi(,5719) (Note that in the preceding example the closing brace is followed by a
texinfo.texi(,5720) period.)@refill
texinfo.texi(,5721) 
texinfo.texi(,5722) You can write a clause after the cross reference, like this:@refill
texinfo.texi(,5723) 
texinfo.texi(,5724) @example
texinfo.texi(,5725) @@xref@{Tropical Storms@}, for more info.
texinfo.texi(,5726) @end example
texinfo.texi(,5727) 
texinfo.texi(,5728) @noindent
texinfo.texi(,5729) which produces
texinfo.texi(,5730) 
texinfo.texi(,5731) @example
texinfo.texi(,5732) *Note Tropical Storms::, for more info.
texinfo.texi(,5733) @end example
texinfo.texi(,5734) 
texinfo.texi(,5735) @noindent
texinfo.texi(,5736) and
texinfo.texi(,5737) 
texinfo.texi(,5738) @quotation
texinfo.texi(,5739) See Section 3.1 [Tropical Storms], page 24, for more info.
texinfo.texi(,5740) @end quotation
texinfo.texi(,5741) 
texinfo.texi(,5742) @noindent
texinfo.texi(,5743) (Note that in the preceding example the closing brace is followed by a
texinfo.texi(,5744) comma, and then by the clause, which is followed by a period.)@refill
texinfo.texi(,5745) 
texinfo.texi(,5746) @node Two Arguments, Three Arguments, One Argument, xref
texinfo.texi(,5747) @subsection @code{@@xref} with Two Arguments
texinfo.texi(,5748) 
texinfo.texi(,5749) With two arguments, the second is used as the name of the Info cross
texinfo.texi(,5750) reference, while the first is still the name of the node to which the
texinfo.texi(,5751) cross reference points.@refill
texinfo.texi(,5752) 
texinfo.texi(,5753) @need 750
texinfo.texi(,5754) @noindent
texinfo.texi(,5755) The template is like this:
texinfo.texi(,5756) 
texinfo.texi(,5757) @example
texinfo.texi(,5758) @@xref@{@var{node-name}, @var{cross-reference-name}@}.
texinfo.texi(,5759) @end example
texinfo.texi(,5760) 
texinfo.texi(,5761) @need 700
texinfo.texi(,5762) @noindent
texinfo.texi(,5763) For example,
texinfo.texi(,5764) 
texinfo.texi(,5765) @example
texinfo.texi(,5766) @@xref@{Electrical Effects, Lightning@}.
texinfo.texi(,5767) @end example
texinfo.texi(,5768) 
texinfo.texi(,5769) @noindent
texinfo.texi(,5770) produces:
texinfo.texi(,5771) 
texinfo.texi(,5772) @example
texinfo.texi(,5773) *Note Lightning: Electrical Effects.
texinfo.texi(,5774) @end example
texinfo.texi(,5775) 
texinfo.texi(,5776) @noindent
texinfo.texi(,5777) and
texinfo.texi(,5778) 
texinfo.texi(,5779) @quotation
texinfo.texi(,5780) See Section 5.2 [Electrical Effects], page 57.
texinfo.texi(,5781) @end quotation
texinfo.texi(,5782) 
texinfo.texi(,5783) @noindent
texinfo.texi(,5784) (Note that in the preceding example the closing brace is followed by a
texinfo.texi(,5785) period; and that the node name is printed, not the cross reference name.)
texinfo.texi(,5786) 
texinfo.texi(,5787) You can write a clause after the cross reference, like this:@refill
texinfo.texi(,5788) 
texinfo.texi(,5789) @example
texinfo.texi(,5790) @@xref@{Electrical Effects, Lightning@}, for more info.
texinfo.texi(,5791) @end example
texinfo.texi(,5792) 
texinfo.texi(,5793) @noindent
texinfo.texi(,5794) which produces
texinfo.texi(,5795) @example
texinfo.texi(,5796) *Note Lightning: Electrical Effects, for more info.
texinfo.texi(,5797) @end example
texinfo.texi(,5798) 
texinfo.texi(,5799) @noindent
texinfo.texi(,5800) and
texinfo.texi(,5801) 
texinfo.texi(,5802) @quotation
texinfo.texi(,5803) See Section 5.2 [Electrical Effects], page 57, for more info.
texinfo.texi(,5804) @end quotation
texinfo.texi(,5805) 
texinfo.texi(,5806) @noindent
texinfo.texi(,5807) (Note that in the preceding example the closing brace is followed by a
texinfo.texi(,5808) comma, and then by the clause, which is followed by a period.)@refill
texinfo.texi(,5809) 
texinfo.texi(,5810) @node Three Arguments, Four and Five Arguments, Two Arguments, xref
texinfo.texi(,5811) @subsection @code{@@xref} with Three Arguments
texinfo.texi(,5812) 
texinfo.texi(,5813) A third argument replaces the node name in the @TeX{} output.  The third
texinfo.texi(,5814) argument should be the name of the section in the printed output, or
texinfo.texi(,5815) else state the topic discussed by that section.  Often, you will want to
texinfo.texi(,5816) use initial upper case letters so it will be easier to read when the
texinfo.texi(,5817) reference is printed.  Use a third argument when the node name is
texinfo.texi(,5818) unsuitable because of syntax or meaning.@refill
texinfo.texi(,5819) 
texinfo.texi(,5820) Remember to avoid placing a comma within the title or topic section of
texinfo.texi(,5821) a cross reference, or within any other section.  The formatters divide
texinfo.texi(,5822) cross references into arguments according to the commas; a comma
texinfo.texi(,5823) within a title or other section will divide it into two arguments.  In
texinfo.texi(,5824) a reference, you need to write a title such as ``Clouds, Mist, and
texinfo.texi(,5825) Fog'' without the commas.@refill
texinfo.texi(,5826) 
texinfo.texi(,5827) Also, remember to write a comma or period after the closing brace of an
texinfo.texi(,5828) @code{@@xref} to terminate the cross reference.  In the following
texinfo.texi(,5829) examples, a clause follows a terminating comma.@refill
texinfo.texi(,5830) 
texinfo.texi(,5831) 
texinfo.texi(,5832) @need 750
texinfo.texi(,5833) @noindent
texinfo.texi(,5834) The template is like this:
texinfo.texi(,5835) 
texinfo.texi(,5836) @example
texinfo.texi(,5837) @group
texinfo.texi(,5838) @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
texinfo.texi(,5839) @end group
texinfo.texi(,5840) @end example
texinfo.texi(,5841) 
texinfo.texi(,5842) @need 700
texinfo.texi(,5843) @noindent
texinfo.texi(,5844) For example,
texinfo.texi(,5845) 
texinfo.texi(,5846) @example
texinfo.texi(,5847) @group
texinfo.texi(,5848) @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
texinfo.texi(,5849) for details.
texinfo.texi(,5850) @end group
texinfo.texi(,5851) @end example
texinfo.texi(,5852) 
texinfo.texi(,5853) @noindent
texinfo.texi(,5854) produces
texinfo.texi(,5855) 
texinfo.texi(,5856) @example
texinfo.texi(,5857) *Note Lightning: Electrical Effects, for details.
texinfo.texi(,5858) @end example
texinfo.texi(,5859) 
texinfo.texi(,5860) @noindent
texinfo.texi(,5861) and
texinfo.texi(,5862) 
texinfo.texi(,5863) @quotation
texinfo.texi(,5864) See Section 5.2 [Thunder and Lightning], page 57, for details.
texinfo.texi(,5865) @end quotation
texinfo.texi(,5866) 
texinfo.texi(,5867) If a third argument is given and the second one is empty, then the
texinfo.texi(,5868) third argument serves both.  (Note how two commas, side by side, mark
texinfo.texi(,5869) the empty second argument.)@refill
texinfo.texi(,5870) 
texinfo.texi(,5871) @example
texinfo.texi(,5872) @group
texinfo.texi(,5873) @@xref@{Electrical Effects, , Thunder and Lightning@},
texinfo.texi(,5874) for details.
texinfo.texi(,5875) @end group
texinfo.texi(,5876) @end example
texinfo.texi(,5877) 
texinfo.texi(,5878) @noindent
texinfo.texi(,5879) produces
texinfo.texi(,5880) 
texinfo.texi(,5881) @example
texinfo.texi(,5882) *Note Thunder and Lightning: Electrical Effects, for details.
texinfo.texi(,5883) @end example
texinfo.texi(,5884) 
texinfo.texi(,5885) @noindent
texinfo.texi(,5886) and
texinfo.texi(,5887) 
texinfo.texi(,5888) @quotation
texinfo.texi(,5889) See Section 5.2 [Thunder and Lightning], page 57, for details.
texinfo.texi(,5890) @end quotation
texinfo.texi(,5891) 
texinfo.texi(,5892) As a practical matter, it is often best to write cross references with
texinfo.texi(,5893) just the first argument if the node name and the section title are the
texinfo.texi(,5894) same, and with the first and third arguments if the node name and title
texinfo.texi(,5895) are different.@refill
texinfo.texi(,5896) 
texinfo.texi(,5897) Here are several examples from @cite{The GNU Awk User's Guide}:@refill
texinfo.texi(,5898) 
texinfo.texi(,5899) @smallexample
texinfo.texi(,5900) @@xref@{Sample Program@}.
texinfo.texi(,5901) @@xref@{Glossary@}.
texinfo.texi(,5902) @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
texinfo.texi(,5903) @@xref@{Close Output, , Closing Output Files and Pipes@},
texinfo.texi(,5904)    for more information.
texinfo.texi(,5905) @@xref@{Regexp, , Regular Expressions as Patterns@}.
texinfo.texi(,5906) @end smallexample
texinfo.texi(,5907) 
texinfo.texi(,5908) @node Four and Five Arguments,  , Three Arguments, xref
texinfo.texi(,5909) @subsection @code{@@xref} with Four and Five Arguments
texinfo.texi(,5910) 
texinfo.texi(,5911) In a cross reference, a fourth argument specifies the name of another
texinfo.texi(,5912) Info file, different from the file in which the reference appears, and
texinfo.texi(,5913) a fifth argument specifies its title as a printed manual.@refill
texinfo.texi(,5914) 
texinfo.texi(,5915) Remember that a comma or period must follow the closing brace of an
texinfo.texi(,5916) @code{@@xref} command to terminate the cross reference.  In the
texinfo.texi(,5917) following examples, a clause follows a terminating comma.@refill
texinfo.texi(,5918) 
texinfo.texi(,5919) @need 800
texinfo.texi(,5920) @noindent
texinfo.texi(,5921) The template is:
texinfo.texi(,5922) 
texinfo.texi(,5923) @example
texinfo.texi(,5924) @group
texinfo.texi(,5925) @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
texinfo.texi(,5926) @var{info-file-name}, @var{printed-manual-title}@}.
texinfo.texi(,5927) @end group
texinfo.texi(,5928) @end example
texinfo.texi(,5929) 
texinfo.texi(,5930) @need 700
texinfo.texi(,5931) @noindent
texinfo.texi(,5932) For example,
texinfo.texi(,5933) 
texinfo.texi(,5934) @example
texinfo.texi(,5935) @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
texinfo.texi(,5936) weather, An Introduction to Meteorology@}, for details.
texinfo.texi(,5937) @end example
texinfo.texi(,5938) 
texinfo.texi(,5939) @noindent
texinfo.texi(,5940) produces
texinfo.texi(,5941) 
texinfo.texi(,5942) @example
texinfo.texi(,5943) *Note Lightning: (weather)Electrical Effects, for details.
texinfo.texi(,5944) @end example
texinfo.texi(,5945) 
texinfo.texi(,5946) @noindent
texinfo.texi(,5947) The name of the Info file is enclosed in parentheses and precedes
texinfo.texi(,5948) the name of the node.
texinfo.texi(,5949) 
texinfo.texi(,5950) @noindent
texinfo.texi(,5951) In a printed manual, the reference looks like this:@refill
texinfo.texi(,5952) 
texinfo.texi(,5953) @quotation
texinfo.texi(,5954) See section ``Thunder and Lightning'' in @i{An Introduction to
texinfo.texi(,5955) Meteorology}, for details.
texinfo.texi(,5956) @end quotation
texinfo.texi(,5957) 
texinfo.texi(,5958) @noindent
texinfo.texi(,5959) The title of the printed manual is typeset in italics; and the
texinfo.texi(,5960) reference lacks a page number since @TeX{} cannot know to which page a
texinfo.texi(,5961) reference refers when that reference is to another manual.@refill
texinfo.texi(,5962) 
texinfo.texi(,5963) Often, you will leave out the second argument when you use the long
texinfo.texi(,5964) version of @code{@@xref}.  In this case, the third argument, the topic
texinfo.texi(,5965) description, will be used as the cross reference name in Info.@refill
texinfo.texi(,5966) 
texinfo.texi(,5967) @noindent
texinfo.texi(,5968) The template looks like this:
texinfo.texi(,5969) 
texinfo.texi(,5970) @example
texinfo.texi(,5971) @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
texinfo.texi(,5972) @var{printed-manual-title}@}, for details.
texinfo.texi(,5973) @end example
texinfo.texi(,5974) 
texinfo.texi(,5975) @noindent
texinfo.texi(,5976) which produces
texinfo.texi(,5977) 
texinfo.texi(,5978) @example
texinfo.texi(,5979) *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
texinfo.texi(,5980) @end example
texinfo.texi(,5981) 
texinfo.texi(,5982) @noindent
texinfo.texi(,5983) and
texinfo.texi(,5984) 
texinfo.texi(,5985) @quotation
texinfo.texi(,5986) See section @var{title-or-topic} in @var{printed-manual-title}, for details.
texinfo.texi(,5987) @end quotation
texinfo.texi(,5988) 
texinfo.texi(,5989) @need 700
texinfo.texi(,5990) @noindent
texinfo.texi(,5991) For example,
texinfo.texi(,5992) 
texinfo.texi(,5993) @example
texinfo.texi(,5994) @@xref@{Electrical Effects, , Thunder and Lightning,
texinfo.texi(,5995) weather, An Introduction to Meteorology@}, for details.
texinfo.texi(,5996) @end example
texinfo.texi(,5997) 
texinfo.texi(,5998) @noindent
texinfo.texi(,5999) produces
texinfo.texi(,6000) 
texinfo.texi(,6001) @example
texinfo.texi(,6002) @group
texinfo.texi(,6003) *Note Thunder and Lightning: (weather)Electrical Effects,
texinfo.texi(,6004) for details.
texinfo.texi(,6005) @end group
texinfo.texi(,6006) @end example
texinfo.texi(,6007) 
texinfo.texi(,6008) @noindent
texinfo.texi(,6009) and
texinfo.texi(,6010) 
texinfo.texi(,6011) @quotation
texinfo.texi(,6012) See section ``Thunder and Lightning'' in @i{An Introduction to
texinfo.texi(,6013) Meteorology}, for details.
texinfo.texi(,6014) @end quotation
texinfo.texi(,6015) 
texinfo.texi(,6016) On rare occasions, you may want to refer to another Info file that
texinfo.texi(,6017) is within a single printed manual---when multiple Texinfo files are
texinfo.texi(,6018) incorporated into the same @TeX{} run but make separate Info files.
texinfo.texi(,6019) In this case, you need to specify only the fourth argument, and not
texinfo.texi(,6020) the fifth.@refill
texinfo.texi(,6021) 
texinfo.texi(,6022) @node Top Node Naming, ref, xref, Cross References
texinfo.texi(,6023) @section Naming a `Top' Node
texinfo.texi(,6024) @cindex Naming a `Top' Node in references
texinfo.texi(,6025) @cindex @samp{@r{Top}} node naming for references
texinfo.texi(,6026) 
texinfo.texi(,6027) In a cross reference, you must always name a node.  This means that in
texinfo.texi(,6028) order to refer to a whole manual, you must identify the `Top' node by
texinfo.texi(,6029) writing it as the first argument to the @code{@@xref} command.  (This
texinfo.texi(,6030) is different from the way you write a menu entry; see @ref{Other Info
texinfo.texi(,6031) Files, , Referring to Other Info Files}.)  At the same time, to
texinfo.texi(,6032) provide a meaningful section topic or title in the printed cross
texinfo.texi(,6033) reference (instead of the word `Top'), you must write an appropriate
texinfo.texi(,6034) entry for the third argument to the @code{@@xref} command.
texinfo.texi(,6035) @refill
texinfo.texi(,6036) 
texinfo.texi(,6037) @noindent
texinfo.texi(,6038) Thus, to make a cross reference to @cite{The GNU Make Manual},
texinfo.texi(,6039) write:@refill
texinfo.texi(,6040) 
texinfo.texi(,6041) @example
texinfo.texi(,6042) @@xref@{Top, , Overview, make, The GNU Make Manual@}.
texinfo.texi(,6043) @end example
texinfo.texi(,6044) 
texinfo.texi(,6045) @noindent
texinfo.texi(,6046) which produces
texinfo.texi(,6047) 
texinfo.texi(,6048) @example
texinfo.texi(,6049) *Note Overview: (make)Top.
texinfo.texi(,6050) @end example
texinfo.texi(,6051) 
texinfo.texi(,6052) @noindent
texinfo.texi(,6053) and
texinfo.texi(,6054) 
texinfo.texi(,6055) @quotation
texinfo.texi(,6056) See section ``Overview'' in @i{The GNU Make Manual}.
texinfo.texi(,6057) @end quotation
texinfo.texi(,6058) 
texinfo.texi(,6059) @noindent
texinfo.texi(,6060) In this example, @samp{Top} is the name of the first node, and
texinfo.texi(,6061) @samp{Overview} is the name of the first section of the manual.@refill
texinfo.texi(,6062) @node ref, pxref, Top Node Naming, Cross References
texinfo.texi(,6063) @comment  node-name,  next,  previous,  up
texinfo.texi(,6064) @section @code{@@ref}
texinfo.texi(,6065) @cindex Cross references using @code{@@ref}
texinfo.texi(,6066) @cindex References using @code{@@ref}
texinfo.texi(,6067) @findex ref
texinfo.texi(,6068) 
texinfo.texi(,6069) @code{@@ref} is nearly the same as @code{@@xref} except that it does
texinfo.texi(,6070) not generate a `See' in the printed output, just the reference itself.
texinfo.texi(,6071) This makes it useful as the last part of a sentence.@refill
texinfo.texi(,6072) 
texinfo.texi(,6073) @need 700
texinfo.texi(,6074) @noindent
texinfo.texi(,6075) For example,
texinfo.texi(,6076) 
texinfo.texi(,6077) @cindex Hurricanes
texinfo.texi(,6078) @example
texinfo.texi(,6079) For more information, see @@ref@{Hurricanes@}.
texinfo.texi(,6080) @end example
texinfo.texi(,6081) 
texinfo.texi(,6082) @noindent
texinfo.texi(,6083) produces
texinfo.texi(,6084) 
texinfo.texi(,6085) @example
texinfo.texi(,6086) For more information, see *Note Hurricanes::.
texinfo.texi(,6087) @end example
texinfo.texi(,6088) 
texinfo.texi(,6089) @noindent
texinfo.texi(,6090) and
texinfo.texi(,6091) 
texinfo.texi(,6092) @quotation
texinfo.texi(,6093) For more information, see Section 8.2 [Hurricanes], page 123.
texinfo.texi(,6094) @end quotation
texinfo.texi(,6095) 
texinfo.texi(,6096) The @code{@@ref} command sometimes leads writers to express themselves
texinfo.texi(,6097) in a manner that is suitable for a printed manual but looks awkward
texinfo.texi(,6098) in the Info format.  Bear in mind that your audience will be using
texinfo.texi(,6099) both the printed and the Info format.@refill
texinfo.texi(,6100) 
texinfo.texi(,6101) @need 800
texinfo.texi(,6102) @noindent
texinfo.texi(,6103) For example,
texinfo.texi(,6104) 
texinfo.texi(,6105) @cindex Sea surges
texinfo.texi(,6106) @example
texinfo.texi(,6107) @group
texinfo.texi(,6108) Sea surges are described in @@ref@{Hurricanes@}.
texinfo.texi(,6109) @end group
texinfo.texi(,6110) @end example
texinfo.texi(,6111) 
texinfo.texi(,6112) @need 800
texinfo.texi(,6113) @noindent
texinfo.texi(,6114) produces
texinfo.texi(,6115) 
texinfo.texi(,6116) @quotation
texinfo.texi(,6117) Sea surges are described in Section 6.7 [Hurricanes], page 72.
texinfo.texi(,6118) @end quotation
texinfo.texi(,6119) 
texinfo.texi(,6120) @need 800
texinfo.texi(,6121) @noindent
texinfo.texi(,6122) in a printed document, and the following in Info:
texinfo.texi(,6123) 
texinfo.texi(,6124) @example
texinfo.texi(,6125) Sea surges are described in *Note Hurricanes::.
texinfo.texi(,6126) @end example
texinfo.texi(,6127) 
texinfo.texi(,6128) @quotation
texinfo.texi(,6129) @strong{Caution:} You @emph{must} write a period, comma, or right
texinfo.texi(,6130) parenthesis immediately after an @code{@@ref} command with two or more
texinfo.texi(,6131) arguments.  Otherwise, Info will not find the end of the cross reference
texinfo.texi(,6132) entry and its attempt to follow the cross reference will fail.  As a
texinfo.texi(,6133) general rule, you should write a period or comma after every
texinfo.texi(,6134) @code{@@ref} command.  This looks best in both the printed and the Info
texinfo.texi(,6135) output.@refill
texinfo.texi(,6136) @end quotation
texinfo.texi(,6137) 
texinfo.texi(,6138) @node pxref, inforef, ref, Cross References
texinfo.texi(,6139) @comment  node-name,  next,  previous,  up
texinfo.texi(,6140) @section @code{@@pxref}
texinfo.texi(,6141) @cindex Cross references using @code{@@pxref}
texinfo.texi(,6142) @cindex References using @code{@@pxref}
texinfo.texi(,6143) @findex pxref
texinfo.texi(,6144) 
texinfo.texi(,6145) The parenthetical reference command, @code{@@pxref}, is nearly the
texinfo.texi(,6146) same as @code{@@xref}, but you use it @emph{only} inside parentheses
texinfo.texi(,6147) and you do @emph{not} type a comma or period after the command's
texinfo.texi(,6148) closing brace.  The command differs from @code{@@xref} in two
texinfo.texi(,6149) ways:@refill
texinfo.texi(,6150) 
texinfo.texi(,6151) @enumerate
texinfo.texi(,6152) @item
texinfo.texi(,6153) @TeX{} typesets the reference for the printed manual with a lower case
texinfo.texi(,6154) `see' rather than an upper case `See'.@refill
texinfo.texi(,6155) 
texinfo.texi(,6156) @item
texinfo.texi(,6157) The Info formatting commands automatically end the reference with a
texinfo.texi(,6158) closing colon or period.@refill
texinfo.texi(,6159) @end enumerate
texinfo.texi(,6160) 
texinfo.texi(,6161) Because one type of formatting automatically inserts closing
texinfo.texi(,6162) punctuation and the other does not, you should use @code{@@pxref}
texinfo.texi(,6163) @emph{only} inside parentheses as part of another sentence.  Also, you
texinfo.texi(,6164) yourself should not insert punctuation after the reference, as you do
texinfo.texi(,6165) with @code{@@xref}.@refill
texinfo.texi(,6166) 
texinfo.texi(,6167) @code{@@pxref} is designed so that the output looks right and works
texinfo.texi(,6168) right between parentheses both in printed output and in an Info file.
texinfo.texi(,6169) In a printed manual, a closing comma or period should not follow a
texinfo.texi(,6170) cross reference within parentheses; such punctuation is wrong.  But in
texinfo.texi(,6171) an Info file, suitable closing punctuation must follow the cross
texinfo.texi(,6172) reference so Info can recognize its end.  @code{@@pxref} spares you
texinfo.texi(,6173) the need to use complicated methods to put a terminator into one form
texinfo.texi(,6174) of the output and not the other.@refill
texinfo.texi(,6175) 
texinfo.texi(,6176) @noindent
texinfo.texi(,6177) With one argument, a parenthetical cross reference looks like
texinfo.texi(,6178) this:@refill
texinfo.texi(,6179) 
texinfo.texi(,6180) @cindex Flooding
texinfo.texi(,6181) @example
texinfo.texi(,6182) @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
texinfo.texi(,6183) @end example
texinfo.texi(,6184) 
texinfo.texi(,6185) @need 800
texinfo.texi(,6186) @noindent
texinfo.texi(,6187) which produces
texinfo.texi(,6188) 
texinfo.texi(,6189) @example
texinfo.texi(,6190) @group
texinfo.texi(,6191) @dots{} storms cause flooding (*Note Hurricanes::) @dots{}
texinfo.texi(,6192) @end group
texinfo.texi(,6193) @end example
texinfo.texi(,6194) 
texinfo.texi(,6195) @noindent
texinfo.texi(,6196) and
texinfo.texi(,6197) 
texinfo.texi(,6198) @quotation
texinfo.texi(,6199) @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
texinfo.texi(,6200) @end quotation
texinfo.texi(,6201) 
texinfo.texi(,6202) With two arguments, a parenthetical cross reference has this
texinfo.texi(,6203) template:@refill
texinfo.texi(,6204) 
texinfo.texi(,6205) @example
texinfo.texi(,6206) @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
texinfo.texi(,6207) @end example
texinfo.texi(,6208) 
texinfo.texi(,6209) @noindent
texinfo.texi(,6210) which produces
texinfo.texi(,6211) 
texinfo.texi(,6212) @example
texinfo.texi(,6213) @dots{} (*Note @var{cross-reference-name}: @var{node-name}.) @dots{}
texinfo.texi(,6214) @end example
texinfo.texi(,6215) 
texinfo.texi(,6216) @noindent
texinfo.texi(,6217) and
texinfo.texi(,6218) 
texinfo.texi(,6219) @need 1500
texinfo.texi(,6220) @quotation
texinfo.texi(,6221) @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
texinfo.texi(,6222) @end quotation
texinfo.texi(,6223) 
texinfo.texi(,6224) @code{@@pxref} can be used with up to five arguments just like
texinfo.texi(,6225) @code{@@xref} (@pxref{xref, , @code{@@xref}}).@refill
texinfo.texi(,6226) 
texinfo.texi(,6227) @quotation
texinfo.texi(,6228) @strong{Please note:} Use @code{@@pxref} only as a parenthetical
texinfo.texi(,6229) reference.  Do not try to use @code{@@pxref} as a clause in a sentence.
texinfo.texi(,6230) It will look bad in either the Info file, the printed output, or
texinfo.texi(,6231) both.@refill
texinfo.texi(,6232) 
texinfo.texi(,6233) Also, parenthetical cross references look best at the ends of sentences.
texinfo.texi(,6234) Although you may write them in the middle of a sentence, that location
texinfo.texi(,6235) breaks up the flow of text.@refill
texinfo.texi(,6236) @end quotation
texinfo.texi(,6237) 
texinfo.texi(,6238) @node inforef, uref, pxref, Cross References
texinfo.texi(,6239) @section @code{@@inforef}
texinfo.texi(,6240) @cindex Cross references using @code{@@inforef}
texinfo.texi(,6241) @cindex References using @code{@@inforef}
texinfo.texi(,6242) @findex inforef
texinfo.texi(,6243) 
texinfo.texi(,6244) @code{@@inforef} is used for cross references to Info files for which
texinfo.texi(,6245) there are no printed manuals.  Even in a printed manual,
texinfo.texi(,6246) @code{@@inforef} generates a reference directing the user to look in
texinfo.texi(,6247) an Info file.@refill
texinfo.texi(,6248) 
texinfo.texi(,6249) The command takes either two or three arguments, in the following
texinfo.texi(,6250) order:@refill
texinfo.texi(,6251) 
texinfo.texi(,6252) @enumerate
texinfo.texi(,6253) @item
texinfo.texi(,6254) The node name.
texinfo.texi(,6255) 
texinfo.texi(,6256) @item
texinfo.texi(,6257) The cross reference name (optional).
texinfo.texi(,6258) 
texinfo.texi(,6259) @item
texinfo.texi(,6260) The Info file name.
texinfo.texi(,6261) @end enumerate
texinfo.texi(,6262) 
texinfo.texi(,6263) @noindent
texinfo.texi(,6264) Separate the arguments with commas, as with @code{@@xref}.  Also, you
texinfo.texi(,6265) must terminate the reference with a comma or period after the
texinfo.texi(,6266) @samp{@}}, as you do with @code{@@xref}.@refill
texinfo.texi(,6267) 
texinfo.texi(,6268) @noindent
texinfo.texi(,6269) The template is:
texinfo.texi(,6270) 
texinfo.texi(,6271) @example
texinfo.texi(,6272) @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
texinfo.texi(,6273) @end example
texinfo.texi(,6274) 
texinfo.texi(,6275) @need 800
texinfo.texi(,6276) @noindent
texinfo.texi(,6277) Thus,
texinfo.texi(,6278) 
texinfo.texi(,6279) @example
texinfo.texi(,6280) @group
texinfo.texi(,6281) @@inforef@{Expert, Advanced Info commands, info@},
texinfo.texi(,6282) for more information.
texinfo.texi(,6283) @end group
texinfo.texi(,6284) @end example
texinfo.texi(,6285) 
texinfo.texi(,6286) @need 800
texinfo.texi(,6287) @noindent
texinfo.texi(,6288) produces
texinfo.texi(,6289) 
texinfo.texi(,6290) @example
texinfo.texi(,6291) @group
texinfo.texi(,6292) *Note Advanced Info commands: (info)Expert,
texinfo.texi(,6293) for more information.
texinfo.texi(,6294) @end group
texinfo.texi(,6295) @end example
texinfo.texi(,6296) 
texinfo.texi(,6297) @need 800
texinfo.texi(,6298) @noindent
texinfo.texi(,6299) and
texinfo.texi(,6300) 
texinfo.texi(,6301) @quotation
texinfo.texi(,6302) See Info file @file{info}, node @samp{Expert}, for more information.
texinfo.texi(,6303) @end quotation
texinfo.texi(,6304) 
texinfo.texi(,6305) @need 800
texinfo.texi(,6306) @noindent
texinfo.texi(,6307) Similarly,
texinfo.texi(,6308) 
texinfo.texi(,6309) @example
texinfo.texi(,6310) @group
texinfo.texi(,6311) @@inforef@{Expert, , info@}, for more information.
texinfo.texi(,6312) @end group
texinfo.texi(,6313) @end example
texinfo.texi(,6314) 
texinfo.texi(,6315) @need 800
texinfo.texi(,6316) @noindent
texinfo.texi(,6317) produces
texinfo.texi(,6318) 
texinfo.texi(,6319) @example
texinfo.texi(,6320) *Note (info)Expert::, for more information.
texinfo.texi(,6321) @end example
texinfo.texi(,6322) 
texinfo.texi(,6323) @need 800
texinfo.texi(,6324) @noindent
texinfo.texi(,6325) and
texinfo.texi(,6326) 
texinfo.texi(,6327) @quotation
texinfo.texi(,6328) See Info file @file{info}, node @samp{Expert}, for more information.
texinfo.texi(,6329) @end quotation
texinfo.texi(,6330) 
texinfo.texi(,6331) The converse of @code{@@inforef} is @code{@@cite}, which is used to
texinfo.texi(,6332) refer to printed works for which no Info form exists.  @xref{cite, ,
texinfo.texi(,6333) @code{@@cite}}.@refill
texinfo.texi(,6334) 
texinfo.texi(,6335) 
texinfo.texi(,6336) @node uref
texinfo.texi(,6337) @section @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
texinfo.texi(,6338) @findex uref
texinfo.texi(,6339) @cindex Uniform resource locator, referring to
texinfo.texi(,6340) @cindex URL, referring to
texinfo.texi(,6341) 
texinfo.texi(,6342) @cindex @code{href}, producing HTML
texinfo.texi(,6343) @code{@@uref} produces a reference to a uniform resource locator (url).
texinfo.texi(,6344) It takes one mandatory argument, the url, and two optional arguments
texinfo.texi(,6345) which control the text that is displayed.  In HTML output, @code{@@uref}
texinfo.texi(,6346) produces a link you can follow.
texinfo.texi(,6347) 
texinfo.texi(,6348) The second argument, if specified, is the text to display (the default
texinfo.texi(,6349) is the url itself); in Info and DVI output, but not in HTML output, the
texinfo.texi(,6350) url is also output.
texinfo.texi(,6351) 
texinfo.texi(,6352) @cindex Man page, reference to
texinfo.texi(,6353) The third argument, on the other hand, if specified is also the text to
texinfo.texi(,6354) display, but the url is @emph{not} output in any format.  This is useful
texinfo.texi(,6355) when the text is already sufficiently referential, as in a man page.  If
texinfo.texi(,6356) the third argument is given, the second argument is ignored.
texinfo.texi(,6357) 
texinfo.texi(,6358) The simple one argument form, where the url is both the target and the
texinfo.texi(,6359) text of the link:
texinfo.texi(,6360) 
texinfo.texi(,6361) @example
texinfo.texi(,6362) The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
texinfo.texi(,6363) @end example
texinfo.texi(,6364) 
texinfo.texi(,6365) @noindent produces:
texinfo.texi(,6366) @display
texinfo.texi(,6367) The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
texinfo.texi(,6368) @end display
texinfo.texi(,6369) 
texinfo.texi(,6370) 
texinfo.texi(,6371) An example of the two-argument form:
texinfo.texi(,6372) @example
texinfo.texi(,6373) The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
texinfo.texi(,6374) holds programs and texts.
texinfo.texi(,6375) @end example
texinfo.texi(,6376) 
texinfo.texi(,6377) @noindent produces:
texinfo.texi(,6378) @display
texinfo.texi(,6379) The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
texinfo.texi(,6380) holds programs and texts.
texinfo.texi(,6381) @end display
texinfo.texi(,6382) 
texinfo.texi(,6383) @noindent that is, the Info output is this:
texinfo.texi(,6384) @example
texinfo.texi(,6385) The official GNU ftp site (ftp://ftp.gnu.org/gnu)
texinfo.texi(,6386) holds programs and texts.
texinfo.texi(,6387) @end example
texinfo.texi(,6388) 
texinfo.texi(,6389) @noindent and the HTML output is this:
texinfo.texi(,6390) @example
texinfo.texi(,6391) The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
texinfo.texi(,6392) holds programs and texts.
texinfo.texi(,6393) @end example
texinfo.texi(,6394) 
texinfo.texi(,6395) 
texinfo.texi(,6396) An example of the three-argument form:
texinfo.texi(,6397) @example
texinfo.texi(,6398) The @@uref@{/man.cgi/1/ls,,ls(1)@} program @dots{}
texinfo.texi(,6399) @end example
texinfo.texi(,6400) 
texinfo.texi(,6401) @noindent produces:
texinfo.texi(,6402) @display
texinfo.texi(,6403) The @uref{/man.cgi/1/ls,,ls(1)} program @dots{}
texinfo.texi(,6404) @end display
texinfo.texi(,6405) 
texinfo.texi(,6406) @noindent but with HTML:
texinfo.texi(,6407) @example
texinfo.texi(,6408) The <a href="/man.cgi/1/ls">ls(1)</a> program @dots{}
texinfo.texi(,6409) @end example
texinfo.texi(,6410) 
texinfo.texi(,6411) To merely indicate a url without creating a link people can follow, use
texinfo.texi(,6412) @code{@@url} (@pxref{url, @code{@@url}}).
texinfo.texi(,6413) 
texinfo.texi(,6414) Some people prefer to display url's in the unambiguous format:
texinfo.texi(,6415) 
texinfo.texi(,6416) @display
texinfo.texi(,6417) <URL:http://@var{host}/@var{path}>
texinfo.texi(,6418) @end display
texinfo.texi(,6419) 
texinfo.texi(,6420) @noindent
texinfo.texi(,6421) @cindex <URL convention, not used
texinfo.texi(,6422) You can use this form in the input file if you wish.  We feel it's not
texinfo.texi(,6423) necessary to clutter up the output with the extra @samp{<URL:} and
texinfo.texi(,6424) @samp{>}, since any software that tries to detect url's in text already
texinfo.texi(,6425) has to detect them without the @samp{<URL:} to be useful.
texinfo.texi(,6426) 
texinfo.texi(,6427) 
texinfo.texi(,6428) @node Marking Text
texinfo.texi(,6429) @chapter Marking Words and Phrases
texinfo.texi(,6430) @cindex Paragraph, marking text within
texinfo.texi(,6431) @cindex Marking words and phrases
texinfo.texi(,6432) @cindex Words and phrases, marking them
texinfo.texi(,6433) @cindex Marking text within a paragraph
texinfo.texi(,6434) @cindex Text, marking up
texinfo.texi(,6435) 
texinfo.texi(,6436) In Texinfo, you can mark words and phrases in a variety of ways.
texinfo.texi(,6437) The Texinfo formatters use this information to determine how to
texinfo.texi(,6438) highlight the text.
texinfo.texi(,6439) You can specify, for example, whether a word or phrase is a
texinfo.texi(,6440) defining occurrence, a metasyntactic variable, or a symbol used in a
texinfo.texi(,6441) program.  Also, you can emphasize text, in several different ways.
texinfo.texi(,6442) 
texinfo.texi(,6443) @menu
texinfo.texi(,6444) * Indicating::                  How to indicate definitions, files, etc.
texinfo.texi(,6445) * Emphasis::                    How to emphasize text.
texinfo.texi(,6446) @end menu
texinfo.texi(,6447) 
texinfo.texi(,6448) 
texinfo.texi(,6449) @node Indicating, Emphasis, Marking Text, Marking Text
texinfo.texi(,6450) @section Indicating Definitions, Commands, etc.
texinfo.texi(,6451) @cindex Highlighting text
texinfo.texi(,6452) @cindex Indicating commands, definitions, etc.
texinfo.texi(,6453) 
texinfo.texi(,6454) Texinfo has commands for indicating just what kind of object a piece of
texinfo.texi(,6455) text refers to.  For example, metasyntactic variables are marked by
texinfo.texi(,6456) @code{@@var}, and code by @code{@@code}.  Since the pieces of text are
texinfo.texi(,6457) labelled by commands that tell what kind of object they are, it is easy
texinfo.texi(,6458) to change the way the Texinfo formatters prepare such text.  (Texinfo is
texinfo.texi(,6459) an @emph{intentional} formatting language rather than a @emph{typesetting}
texinfo.texi(,6460) formatting language.)@refill
texinfo.texi(,6461) 
texinfo.texi(,6462) For example, in a printed manual,
texinfo.texi(,6463) code is usually illustrated in a typewriter font;
texinfo.texi(,6464) @code{@@code} tells @TeX{} to typeset this text in this font.  But it
texinfo.texi(,6465) would be easy to change the way @TeX{} highlights code to use another
texinfo.texi(,6466) font, and this change would not affect how keystroke examples are
texinfo.texi(,6467) highlighted.  If straight typesetting commands were used in the body
texinfo.texi(,6468) of the file and you wanted to make a change, you would need to check
texinfo.texi(,6469) every single occurrence to make sure that you were changing code and
texinfo.texi(,6470) not something else that should not be changed.@refill
texinfo.texi(,6471) 
texinfo.texi(,6472) @menu
texinfo.texi(,6473) * Useful Highlighting::         Highlighting provides useful information.
texinfo.texi(,6474) * code::                        Indicating program code.
texinfo.texi(,6475) * kbd::                         Showing keyboard input.
texinfo.texi(,6476) * key::                         Specifying keys.
texinfo.texi(,6477) * samp::                        A literal sequence of characters.
texinfo.texi(,6478) * verb::                        A verbatim sequence of characters.
texinfo.texi(,6479) * var::                         Indicating metasyntactic variables.
texinfo.texi(,6480) * env::                         Indicating environment variables.
texinfo.texi(,6481) * file::                        Indicating file names.
texinfo.texi(,6482) * command::                     Indicating command names.
texinfo.texi(,6483) * option::                      Indicating option names.
texinfo.texi(,6484) * dfn::                         Specifying definitions.
texinfo.texi(,6485) * cite::                        Referring to books not in the  Info system.
texinfo.texi(,6486) * acronym::                     Indicating acronyms.
texinfo.texi(,6487) * url::                         Indicating a World Wide Web reference.
texinfo.texi(,6488) * email::                       Indicating an electronic mail address.
texinfo.texi(,6489) @end menu
texinfo.texi(,6490) 
texinfo.texi(,6491) 
texinfo.texi(,6492) @node Useful Highlighting, code, Indicating, Indicating
texinfo.texi(,6494) @subheading Highlighting Commands are Useful
texinfo.texi(,6496) 
texinfo.texi(,6497) The highlighting commands can be used to extract useful information
texinfo.texi(,6498) from the file, such as lists of functions or file names.  It is
texinfo.texi(,6499) possible, for example, to write a program in Emacs Lisp (or a keyboard
texinfo.texi(,6500) macro) to insert an index entry after every paragraph that contains
texinfo.texi(,6501) words or phrases marked by a specified command.  You could do this to
texinfo.texi(,6502) construct an index of functions if you had not already made the
texinfo.texi(,6503) entries.@refill
texinfo.texi(,6504) 
texinfo.texi(,6505) The commands serve a variety of purposes:@refill
texinfo.texi(,6506) 
texinfo.texi(,6507) @table @code
texinfo.texi(,6508) @item @@code@{@var{sample-code}@}
texinfo.texi(,6509) Indicate text that is a literal example of a piece of a program.@refill
texinfo.texi(,6510) 
texinfo.texi(,6511) @item @@kbd@{@var{keyboard-characters}@}
texinfo.texi(,6512) Indicate keyboard input.@refill
texinfo.texi(,6513) 
texinfo.texi(,6514) @item @@key@{@var{key-name}@}
texinfo.texi(,6515) Indicate the conventional name for a key on a keyboard.@refill
texinfo.texi(,6516) 
texinfo.texi(,6517) @item @@samp@{@var{text}@}
texinfo.texi(,6518) Indicate text that is a literal example of a sequence of characters.@refill
texinfo.texi(,6519) 
texinfo.texi(,6520) @item @@var@{@var{metasyntactic-variable}@}
texinfo.texi(,6521) Indicate a metasyntactic variable.@refill
texinfo.texi(,6522) 
texinfo.texi(,6523) @item @@env@{@var{environment-variable}@}
texinfo.texi(,6524) Indicate an environment variable.@refill
texinfo.texi(,6525) 
texinfo.texi(,6526) @item @@file@{@var{file-name}@}
texinfo.texi(,6527) Indicate the name of a file.@refill
texinfo.texi(,6528) 
texinfo.texi(,6529) @item @@command@{@var{command-name}@}
texinfo.texi(,6530) Indicate the name of a command.@refill
texinfo.texi(,6531) 
texinfo.texi(,6532) @item @@option@{@var{option}@}
texinfo.texi(,6533) Indicate a command-line option.@refill
texinfo.texi(,6534) 
texinfo.texi(,6535) @item @@dfn@{@var{term}@}
texinfo.texi(,6536) Indicate the introductory or defining use of a term.@refill
texinfo.texi(,6537) 
texinfo.texi(,6538) @item @@cite@{@var{reference}@}
texinfo.texi(,6539) Indicate the name of a book.@refill
texinfo.texi(,6540) 
texinfo.texi(,6541) @item @@acronym@{@var{acronym}@}
texinfo.texi(,6542) Indicate an acronym.@refill
texinfo.texi(,6543) 
texinfo.texi(,6544) @item @@url@{@var{uniform-resource-locator}@}
texinfo.texi(,6545) Indicate a uniform resource locator for the World Wide Web.
texinfo.texi(,6546) 
texinfo.texi(,6547) @item @@email@{@var{email-address}[, @var{displayed-text}]@}
texinfo.texi(,6548) Indicate an electronic mail address.
texinfo.texi(,6549) 
texinfo.texi(,6554) @end table
texinfo.texi(,6555) 
texinfo.texi(,6556) 
texinfo.texi(,6557) @node code
texinfo.texi(,6558) @subsection @code{@@code}@{@var{sample-code}@}
texinfo.texi(,6559) @findex code
texinfo.texi(,6560) 
texinfo.texi(,6561) @cindex Syntactic tokens, indicating
texinfo.texi(,6562) Use the @code{@@code} command to indicate text that is a piece of a
texinfo.texi(,6563) program and which consists of entire syntactic tokens.  Enclose the
texinfo.texi(,6564) text in braces.
texinfo.texi(,6565) 
texinfo.texi(,6566) @cindex Expressions in a program, indicating
texinfo.texi(,6567) @cindex Keywords, indicating
texinfo.texi(,6568) @cindex Reserved words, indicating
texinfo.texi(,6569) Thus, you should use @code{@@code} for an expression in a program, for
texinfo.texi(,6570) the name of a variable or function used in a program, or for a
texinfo.texi(,6571) keyword in a programming language.
texinfo.texi(,6572) 
texinfo.texi(,6573) Use @code{@@code} for command names in languages that resemble
texinfo.texi(,6574) programming languages, such as Texinfo.  For example, @code{@@code} and
texinfo.texi(,6575) @code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
texinfo.texi(,6576) @samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
texinfo.texi(,6577) 
texinfo.texi(,6578) @cindex Case, not altering in @code{@@code}
texinfo.texi(,6579) It is incorrect to alter the case of a word inside an @code{@@code}
texinfo.texi(,6580) command when it appears at the beginning of a sentence.  Most computer
texinfo.texi(,6581) languages are case sensitive.  In C, for example, @code{Printf} is
texinfo.texi(,6582) different from the identifier @code{printf}, and most likely is a
texinfo.texi(,6583) misspelling of it.  Even in languages which are not case sensitive, it
texinfo.texi(,6584) is confusing to a human reader to see identifiers spelled in different
texinfo.texi(,6585) ways.  Pick one spelling and always use that.  If you do not want to
texinfo.texi(,6586) start a sentence with a command name written all in lower case, you
texinfo.texi(,6587) should rearrange the sentence.
texinfo.texi(,6588) 
texinfo.texi(,6589) In the printed manual, @code{@@code} causes @TeX{} to typeset the
texinfo.texi(,6590) argument in a typewriter face.  In the Info file, it causes the Info
texinfo.texi(,6591) formatting commands to use single quotation marks around the text.
texinfo.texi(,6592) 
texinfo.texi(,6593) @need 700
texinfo.texi(,6594) For example,
texinfo.texi(,6595) 
texinfo.texi(,6596) @example
texinfo.texi(,6597) The function returns @@code@{nil@}.
texinfo.texi(,6598) @end example
texinfo.texi(,6599) 
texinfo.texi(,6600) @noindent
texinfo.texi(,6601) produces this in the printed manual:
texinfo.texi(,6602) 
texinfo.texi(,6603) @quotation
texinfo.texi(,6604) The function returns @code{nil}.
texinfo.texi(,6605) @end quotation
texinfo.texi(,6606) 
texinfo.texi(,6614) 
texinfo.texi(,6615) Here are some cases for which it is preferable not to use @code{@@code}:
texinfo.texi(,6616) 
texinfo.texi(,6617) @itemize @bullet
texinfo.texi(,6618) @item
texinfo.texi(,6619) For shell command names such as @command{ls} (use @code{@@command}).
texinfo.texi(,6620) 
texinfo.texi(,6621) @item
texinfo.texi(,6622) For shell options such as @samp{-c} when such options stand alone (use
texinfo.texi(,6623) @code{@@option}).
texinfo.texi(,6624) 
texinfo.texi(,6625) @item
texinfo.texi(,6626) Also, an entire shell command often looks better if written using
texinfo.texi(,6627) @code{@@samp} rather than @code{@@code}.  In this case, the rule is to
texinfo.texi(,6628) choose the more pleasing format.
texinfo.texi(,6629) 
texinfo.texi(,6630) @item
texinfo.texi(,6631) For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
texinfo.texi(,6632) 
texinfo.texi(,6633) @item
texinfo.texi(,6634) For a string of characters shorter than a syntactic token.  For example,
texinfo.texi(,6635) if you are writing about @samp{goto-ch}, which is just a part of the
texinfo.texi(,6636) name for the @code{goto-char} Emacs Lisp function, you should use
texinfo.texi(,6637) @code{@@samp}.
texinfo.texi(,6638) 
texinfo.texi(,6639) @item
texinfo.texi(,6640) In general, when writing about the characters used in a token; for
texinfo.texi(,6641) example, do not use @code{@@code} when you are explaining what letters
texinfo.texi(,6642) or printable symbols can be used in the names of functions.  (Use
texinfo.texi(,6643) @code{@@samp}.)  Also, you should not use @code{@@code} to mark text
texinfo.texi(,6644) that is considered input to programs unless the input is written in a
texinfo.texi(,6645) language that is like a programming language.  For example, you should
texinfo.texi(,6646) not use @code{@@code} for the keystroke commands of GNU Emacs (use
texinfo.texi(,6647) @code{@@kbd} instead) although you may use @code{@@code} for the names
texinfo.texi(,6648) of the Emacs Lisp functions that the keystroke commands invoke.
texinfo.texi(,6649) 
texinfo.texi(,6650) @end itemize
texinfo.texi(,6651) 
texinfo.texi(,6652) Since @code{@@command}, @code{@@option}, and @code{@@env} were
texinfo.texi(,6653) introduced relatively recently, it is acceptable to use @code{@@code} or
texinfo.texi(,6654) @code{@@samp} for command names, options, and environment variables.
texinfo.texi(,6655) The new commands allow you to express the markup more precisely, but
texinfo.texi(,6656) there is no real harm in using the older commands, and of course the
texinfo.texi(,6657) long-standing manuals do so.
texinfo.texi(,6658) 
texinfo.texi(,6659) 
texinfo.texi(,6660) @node kbd
texinfo.texi(,6661) @subsection @code{@@kbd}@{@var{keyboard-characters}@}
texinfo.texi(,6662) @findex kbd
texinfo.texi(,6663) @cindex Keyboard input
texinfo.texi(,6664) 
texinfo.texi(,6665) Use the @code{@@kbd} command for characters of input to be typed by
texinfo.texi(,6666) users.  For example, to refer to the characters @kbd{M-a},
texinfo.texi(,6667) write@refill
texinfo.texi(,6668) 
texinfo.texi(,6669) @example
texinfo.texi(,6670) @@kbd@{M-a@}
texinfo.texi(,6671) @end example
texinfo.texi(,6672) 
texinfo.texi(,6673) @noindent
texinfo.texi(,6674) and to refer to the characters @kbd{M-x shell}, write@refill
texinfo.texi(,6675) 
texinfo.texi(,6676) @example
texinfo.texi(,6677) @@kbd@{M-x shell@}
texinfo.texi(,6678) @end example
texinfo.texi(,6679) 
texinfo.texi(,6680) @cindex user input
texinfo.texi(,6681) @cindex slanted typewriter font, for @code{@@kbd}
texinfo.texi(,6682) The @code{@@kbd} command has the same effect as @code{@@code} in Info,
texinfo.texi(,6683) but by default produces a different font (slanted typewriter instead of
texinfo.texi(,6684) normal typewriter) in the printed manual, so users can distinguish the
texinfo.texi(,6685) characters they are supposed to type from those the computer outputs.
texinfo.texi(,6686) 
texinfo.texi(,6687) @findex kbdinputstyle
texinfo.texi(,6688) Since the usage of @code{@@kbd} varies from manual to manual, you can
texinfo.texi(,6689) control the font switching with the @code{@@kbdinputstyle} command.
texinfo.texi(,6690) This command has no effect on Info output.  Write this command at the
texinfo.texi(,6691) beginning of a line with a single word as an argument, one of the
texinfo.texi(,6692) following:
texinfo.texi(,6693) @vindex distinct@r{, arg to @@kbdinputstyle}
texinfo.texi(,6694) @vindex example@r{, arg to @@kbdinputstyle}
texinfo.texi(,6695) @vindex code@r{, arg to @@kbdinputstyle}
texinfo.texi(,6696) @table @samp
texinfo.texi(,6697) @item code
texinfo.texi(,6698) Always use the same font for @code{@@kbd} as @code{@@code}.
texinfo.texi(,6699) @item example
texinfo.texi(,6700) Use the distinguishing font for @code{@@kbd} only in @code{@@example}
texinfo.texi(,6701) and similar environments.
texinfo.texi(,6702) @item distinct
texinfo.texi(,6703) (the default) Always use the distinguishing font for @code{@@kbd}.
texinfo.texi(,6704) @end table
texinfo.texi(,6705) 
texinfo.texi(,6706) You can embed another @@-command inside the braces of an @code{@@kbd}
texinfo.texi(,6707) command.  Here, for example, is the way to describe a command that
texinfo.texi(,6708) would be described more verbosely as ``press an @samp{r} and then
texinfo.texi(,6709) press the @key{RET} key'':@refill
texinfo.texi(,6710) 
texinfo.texi(,6711) @example
texinfo.texi(,6712) @@kbd@{r @@key@{RET@}@}
texinfo.texi(,6713) @end example
texinfo.texi(,6714) 
texinfo.texi(,6715) @noindent
texinfo.texi(,6716) This produces: @kbd{r @key{RET}}
texinfo.texi(,6717) 
texinfo.texi(,6718) You also use the @code{@@kbd} command if you are spelling out the letters
texinfo.texi(,6719) you type; for example:@refill
texinfo.texi(,6720) 
texinfo.texi(,6721) @example
texinfo.texi(,6722) To give the @@code@{logout@} command,
texinfo.texi(,6723) type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
texinfo.texi(,6724) @end example
texinfo.texi(,6725) 
texinfo.texi(,6726) @noindent
texinfo.texi(,6727) This produces:
texinfo.texi(,6728) 
texinfo.texi(,6729) @quotation
texinfo.texi(,6730) To give the @code{logout} command,
texinfo.texi(,6731) type the characters @kbd{l o g o u t @key{RET}}.
texinfo.texi(,6732) @end quotation
texinfo.texi(,6733) 
texinfo.texi(,6734) (Also, this example shows that you can add spaces for clarity.  If you
texinfo.texi(,6735) really want to mention a space character as one of the characters of
texinfo.texi(,6736) input, write @kbd{@@key@{SPC@}} for it.)@refill
texinfo.texi(,6737) 
texinfo.texi(,6738) 
texinfo.texi(,6739) @node key, samp, kbd, Indicating
texinfo.texi(,6740) @comment  node-name,  next,  previous,  up
texinfo.texi(,6741) @subsection @code{@@key}@{@var{key-name}@}
texinfo.texi(,6742) @findex key
texinfo.texi(,6743) 
texinfo.texi(,6744) Use the @code{@@key} command for the conventional name for a key on a
texinfo.texi(,6745) keyboard, as in:@refill
texinfo.texi(,6746) 
texinfo.texi(,6747) @example
texinfo.texi(,6748) @@key@{RET@}
texinfo.texi(,6749) @end example
texinfo.texi(,6750) 
texinfo.texi(,6751) You can use the @code{@@key} command within the argument of an
texinfo.texi(,6752) @code{@@kbd} command when the sequence of characters to be typed
texinfo.texi(,6753) includes one or more keys that are described by name.@refill
texinfo.texi(,6754) 
texinfo.texi(,6755) @need 700
texinfo.texi(,6756) For example, to produce @kbd{C-x @key{ESC}} you would type:@refill
texinfo.texi(,6757) 
texinfo.texi(,6758) @example
texinfo.texi(,6759) @@kbd@{C-x @@key@{ESC@}@}
texinfo.texi(,6760) @end example
texinfo.texi(,6761) 
texinfo.texi(,6762) Here is a list of the recommended names for keys:
texinfo.texi(,6763) @cindex Recommended names for keys
texinfo.texi(,6764) @cindex Keys, recommended names
texinfo.texi(,6765) @cindex Names recommended for keys
texinfo.texi(,6766) @cindex Abbreviations for keys
texinfo.texi(,6767) 
texinfo.texi(,6768) @quotation
texinfo.texi(,6769) @table @t
texinfo.texi(,6770) @item SPC
texinfo.texi(,6771) Space
texinfo.texi(,6772) @item RET
texinfo.texi(,6773) Return
texinfo.texi(,6774) @item LFD
texinfo.texi(,6775) Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
texinfo.texi(,6776) it might be better to call this character @kbd{C-j}.
texinfo.texi(,6777) @item TAB
texinfo.texi(,6778) Tab
texinfo.texi(,6779) @item BS
texinfo.texi(,6780) Backspace
texinfo.texi(,6781) @item ESC
texinfo.texi(,6782) Escape
texinfo.texi(,6783) @item DEL
texinfo.texi(,6784) Delete
texinfo.texi(,6785) @item SHIFT
texinfo.texi(,6786) Shift
texinfo.texi(,6787) @item CTRL
texinfo.texi(,6788) Control
texinfo.texi(,6789) @item META
texinfo.texi(,6790) Meta
texinfo.texi(,6791) @end table
texinfo.texi(,6792) @end quotation
texinfo.texi(,6793) 
texinfo.texi(,6794) @cindex META key
texinfo.texi(,6795) There are subtleties to handling words like `meta' or `ctrl' that are
texinfo.texi(,6796) names of modifier keys.  When mentioning a character in which the
texinfo.texi(,6797) modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
texinfo.texi(,6798) alone; do not use the @code{@@key} command; but when you are referring
texinfo.texi(,6799) to the modifier key in isolation, use the @code{@@key} command.  For
texinfo.texi(,6800) example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
texinfo.texi(,6801) @samp{@@key@{META@}} to produce @key{META}.
texinfo.texi(,6802) 
texinfo.texi(,6803) @c I don't think this is a good explanation.
texinfo.texi(,6804) @c I think it will puzzle readers more than it clarifies matters.  -- rms.
texinfo.texi(,6805) @c In other words, use @code{@@kbd} for what you do, and use @code{@@key}
texinfo.texi(,6806) @c for what you talk about: ``Press @code{@@kbd@{M-a@}} to move point to
texinfo.texi(,6807) @c the beginning of the sentence.  The @code{@@key@{META@}} key is often in
texinfo.texi(,6808) @c the lower left of the keyboard.''@refill
texinfo.texi(,6809) 
texinfo.texi(,6810) @node samp
texinfo.texi(,6811) @subsection @code{@@samp}@{@var{text}@}
texinfo.texi(,6812) @findex samp
texinfo.texi(,6813) 
texinfo.texi(,6814) Use the @code{@@samp} command to indicate text that is a literal example
texinfo.texi(,6815) or `sample' of a sequence of characters in a file, string, pattern, etc.
texinfo.texi(,6816) Enclose the text in braces.  The argument appears within single
texinfo.texi(,6817) quotation marks in both the Info file and the printed manual; in
texinfo.texi(,6818) addition, it is printed in a fixed-width font.@refill
texinfo.texi(,6819) 
texinfo.texi(,6820) @example
texinfo.texi(,6821) To match @@samp@{foo@} at the end of the line,
texinfo.texi(,6822) use the regexp @@samp@{foo$@}.
texinfo.texi(,6823) @end example
texinfo.texi(,6824) 
texinfo.texi(,6825) @noindent
texinfo.texi(,6826) produces
texinfo.texi(,6827) 
texinfo.texi(,6828) @quotation
texinfo.texi(,6829) To match @samp{foo} at the end of the line, use the regexp
texinfo.texi(,6830) @samp{foo$}.@refill
texinfo.texi(,6831) @end quotation
texinfo.texi(,6832) 
texinfo.texi(,6833) Any time you are referring to single characters, you should use
texinfo.texi(,6834) @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
texinfo.texi(,6835) Also, you may use @code{@@samp} for entire statements in C and for entire
texinfo.texi(,6836) shell commands---in this case, @code{@@samp} often looks better than
texinfo.texi(,6837) @code{@@code}.  Basically, @code{@@samp} is a catchall for whatever is
texinfo.texi(,6838) not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
texinfo.texi(,6839) 
texinfo.texi(,6840) Only include punctuation marks within braces if they are part of the
texinfo.texi(,6841) string you are specifying.  Write punctuation marks outside the braces
texinfo.texi(,6842) if those punctuation marks are part of the English text that surrounds
texinfo.texi(,6843) the string.  In the following sentence, for example, the commas and
texinfo.texi(,6844) period are outside of the braces:@refill
texinfo.texi(,6845) 
texinfo.texi(,6846) @example
texinfo.texi(,6847) @group
texinfo.texi(,6848) In English, the vowels are @@samp@{a@}, @@samp@{e@},
texinfo.texi(,6849) @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
texinfo.texi(,6850) @@samp@{y@}.
texinfo.texi(,6851) @end group
texinfo.texi(,6852) @end example
texinfo.texi(,6853) 
texinfo.texi(,6854) @noindent
texinfo.texi(,6855) This produces:
texinfo.texi(,6856) 
texinfo.texi(,6857) @quotation
texinfo.texi(,6858) In English, the vowels are @samp{a}, @samp{e},
texinfo.texi(,6859) @samp{i}, @samp{o}, @samp{u},  and sometimes
texinfo.texi(,6860) @samp{y}.
texinfo.texi(,6861) @end quotation
texinfo.texi(,6862) 
texinfo.texi(,6863) 
texinfo.texi(,6864) @node verb
texinfo.texi(,6865) @subsection @code{@@verb}@{<char>@var{text}<char>@}
texinfo.texi(,6866) @findex verb
texinfo.texi(,6867) @cindex Verbatim in-line text
texinfo.texi(,6868) 
texinfo.texi(,6869) @cindex Delimiter character, for verbatim 
texinfo.texi(,6870) Use the @code{@@verb} command to print a verbatim sequence of
texinfo.texi(,6871) characters.
texinfo.texi(,6872) 
texinfo.texi(,6873) Like La@TeX{}'s @code{\verb} command, the verbatim text can be quoted using
texinfo.texi(,6874) any unique delimiter character.  Enclose the verbatim text, including the
texinfo.texi(,6875) delimiters, in braces.  Text is printed in a fixed-width font:
texinfo.texi(,6876) 
texinfo.texi(,6877) @example
texinfo.texi(,6878) How many @@verb@{|@@|@}-escapes does one need to print this
texinfo.texi(,6879) @@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
texinfo.texi(,6880) @end example
texinfo.texi(,6881) 
texinfo.texi(,6882) @noindent
texinfo.texi(,6883) produces
texinfo.texi(,6884) 
texinfo.texi(,6885) @example
texinfo.texi(,6886) How many @verb{|@ |}-escapes does one need to print this
texinfo.texi(,6887) @verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
texinfo.texi(,6888) @end example
texinfo.texi(,6889) 
texinfo.texi(,6890) This is in contrast to @code{@@samp} (see the previous
texinfo.texi(,6891) section), whose argument is normal Texinfo text, where the characters
texinfo.texi(,6892) @code{@@@{@}} are special; with @code{@@verb}, nothing is special except
texinfo.texi(,6893) the delimiter character you choose.
texinfo.texi(,6894) 
texinfo.texi(,6895) 
texinfo.texi(,6896) @node var
texinfo.texi(,6897) @subsection @code{@@var}@{@var{metasyntactic-variable}@}
texinfo.texi(,6898) @findex var
texinfo.texi(,6899) 
texinfo.texi(,6900) Use the @code{@@var} command to indicate metasyntactic variables.  A
texinfo.texi(,6901) @dfn{metasyntactic variable} is something that stands for another piece of
texinfo.texi(,6902) text.  For example, you should use a metasyntactic variable in the
texinfo.texi(,6903) documentation of a function to describe the arguments that are passed
texinfo.texi(,6904) to that function.@refill
texinfo.texi(,6905) 
texinfo.texi(,6906) Do not use @code{@@var} for the names of particular variables in
texinfo.texi(,6907) programming languages.  These are specific names from a program, so
texinfo.texi(,6908) @code{@@code} is correct for them (@pxref{code}).  For example, the
texinfo.texi(,6909) Emacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
texinfo.texi(,6910) variable; it is properly formatted using @code{@@code}.
texinfo.texi(,6911) 
texinfo.texi(,6912) Do not use @code{@@var} for environment variables either; @code{@@env}
texinfo.texi(,6913) is correct for them (see the next section).
texinfo.texi(,6914) 
texinfo.texi(,6915) The effect of @code{@@var} in the Info file is to change the case of the
texinfo.texi(,6916) argument to all upper case.  In the printed manual and HTML output, the
texinfo.texi(,6917) argument is printed in slanted type.  
texinfo.texi(,6918) 
texinfo.texi(,6919) @need 700
texinfo.texi(,6920) For example,
texinfo.texi(,6921) 
texinfo.texi(,6922) @example
texinfo.texi(,6923) To delete file @@var@{filename@},
texinfo.texi(,6924) type @@samp@{rm @@var@{filename@}@}.
texinfo.texi(,6925) @end example
texinfo.texi(,6926) 
texinfo.texi(,6927) @noindent
texinfo.texi(,6928) produces
texinfo.texi(,6929) 
texinfo.texi(,6930) @quotation
texinfo.texi(,6931) To delete file @var{filename}, type @samp{rm @var{filename}}.
texinfo.texi(,6932) @end quotation
texinfo.texi(,6933) 
texinfo.texi(,6934) @noindent
texinfo.texi(,6935) (Note that @code{@@var} may appear inside @code{@@code},
texinfo.texi(,6936) @code{@@samp}, @code{@@file}, etc.)@refill
texinfo.texi(,6937) 
texinfo.texi(,6938) Write a metasyntactic variable all in lower case without spaces, and
texinfo.texi(,6939) use hyphens to make it more readable.  Thus, the Texinfo source for
texinfo.texi(,6940) the illustration of how to begin a Texinfo manual looks like
texinfo.texi(,6941) this:@refill
texinfo.texi(,6942) 
texinfo.texi(,6943) @example
texinfo.texi(,6944) @group
texinfo.texi(,6945) \input texinfo
texinfo.texi(,6946) @@@@setfilename @@var@{info-file-name@}
texinfo.texi(,6947) @@@@settitle @@var@{name-of-manual@}
texinfo.texi(,6948) @end group
texinfo.texi(,6949) @end example
texinfo.texi(,6950) 
texinfo.texi(,6951) @noindent
texinfo.texi(,6952) This produces:
texinfo.texi(,6953) 
texinfo.texi(,6954) @example
texinfo.texi(,6955) @group
texinfo.texi(,6956) \input texinfo
texinfo.texi(,6957) @@setfilename @var{info-file-name}
texinfo.texi(,6958) @@settitle @var{name-of-manual}
texinfo.texi(,6959) @end group
texinfo.texi(,6960) @end example
texinfo.texi(,6961) 
texinfo.texi(,6962) In some documentation styles, metasyntactic variables are shown with
texinfo.texi(,6963) angle brackets, for example:@refill
texinfo.texi(,6964) 
texinfo.texi(,6965) @example
texinfo.texi(,6966) @dots{}, type rm <filename>
texinfo.texi(,6967) @end example
texinfo.texi(,6968) 
texinfo.texi(,6969) @noindent
texinfo.texi(,6970) However, that is not the style that Texinfo uses.  (You can, of
texinfo.texi(,6971) course, modify the sources to @file{texinfo.tex} and the Info formatting commands
texinfo.texi(,6972) to output the @code{<@dots{}>} format if you wish.)@refill
texinfo.texi(,6973) 
texinfo.texi(,6974) 
texinfo.texi(,6975) @node env
texinfo.texi(,6976) @subsection @code{@@env}@{@var{environment-variable}@}
texinfo.texi(,6977) @findex env
texinfo.texi(,6978) 
texinfo.texi(,6979) Use the @code{@@env} command to indicate environment variables, as used
texinfo.texi(,6980) by many operating systems, including GNU.  Do not use it for
texinfo.texi(,6981) metasyntactic variables; use @code{@@var} instead (see the previous
texinfo.texi(,6982) section).
texinfo.texi(,6983) 
texinfo.texi(,6984) @code{@@env} is equivalent to @code{@@code} in its effects.
texinfo.texi(,6985) For example:
texinfo.texi(,6986) 
texinfo.texi(,6987) @example
texinfo.texi(,6988) The @@env@{PATH@} environment variable @dots{}
texinfo.texi(,6989) @end example
texinfo.texi(,6990) @noindent produces
texinfo.texi(,6991) @quotation
texinfo.texi(,6992) The @env{PATH} environment variable @dots{}
texinfo.texi(,6993) @end quotation
texinfo.texi(,6994) 
texinfo.texi(,6995) 
texinfo.texi(,6996) @node file
texinfo.texi(,6997) @subsection @code{@@file}@{@var{file-name}@}
texinfo.texi(,6998) @findex file
texinfo.texi(,6999) 
texinfo.texi(,7000) Use the @code{@@file} command to indicate text that is the name of a
texinfo.texi(,7001) file, buffer, or directory, or is the name of a node in Info.  You can
texinfo.texi(,7002) also use the command for file name suffixes.  Do not use @code{@@file}
texinfo.texi(,7003) for symbols in a programming language; use @code{@@code}.
texinfo.texi(,7004) 
texinfo.texi(,7005) Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
texinfo.texi(,7006) For example,@refill
texinfo.texi(,7007) 
texinfo.texi(,7008) @example
texinfo.texi(,7009) The @@file@{.el@} files are in
texinfo.texi(,7010) the @@file@{/usr/local/emacs/lisp@} directory.
texinfo.texi(,7011) @end example
texinfo.texi(,7012) 
texinfo.texi(,7013) @noindent
texinfo.texi(,7014) produces
texinfo.texi(,7015) 
texinfo.texi(,7016) @quotation
texinfo.texi(,7017) The @file{.el} files are in
texinfo.texi(,7018) the @file{/usr/local/emacs/lisp} directory.
texinfo.texi(,7019) @end quotation
texinfo.texi(,7020) 
texinfo.texi(,7021) 
texinfo.texi(,7022) @node command
texinfo.texi(,7023) @subsection @code{@@command}@{@var{command-name}@}
texinfo.texi(,7024) @findex command
texinfo.texi(,7025) @cindex Command names, indicating
texinfo.texi(,7026) @cindex Program names, indicating
texinfo.texi(,7027) 
texinfo.texi(,7028) Use the @code{@@command} command to indicate command names, such as
texinfo.texi(,7029) @command{ls} or @command{cc}.
texinfo.texi(,7030) 
texinfo.texi(,7031) @code{@@command} is equivalent to @code{@@code} in its effects.
texinfo.texi(,7032) For example:
texinfo.texi(,7033) 
texinfo.texi(,7034) @example
texinfo.texi(,7035) The command @@command@{ls@} lists directory contents.
texinfo.texi(,7036) @end example
texinfo.texi(,7037) @noindent produces
texinfo.texi(,7038) @quotation
texinfo.texi(,7039) The command @command{ls} lists directory contents.
texinfo.texi(,7040) @end quotation
texinfo.texi(,7041) 
texinfo.texi(,7042) You should write the name of a program in the ordinary text font, rather
texinfo.texi(,7043) than using @code{@@command}, if you regard it as a new English word,
texinfo.texi(,7044) such as `Emacs' or `Bison'.
texinfo.texi(,7045) 
texinfo.texi(,7046) When writing an entire shell command invocation, as in @samp{ls -l},
texinfo.texi(,7047) you should use either @code{@@samp} or @code{@@code} at your discretion.
texinfo.texi(,7048) 
texinfo.texi(,7049) 
texinfo.texi(,7050) @node option
texinfo.texi(,7051) @subsection @code{@@option}@{@var{option-name}@}
texinfo.texi(,7052) @findex option
texinfo.texi(,7053) 
texinfo.texi(,7054) Use the @code{@@option} command to indicate a command-line option; for
texinfo.texi(,7055) example, @option{-l} or @option{--version} or
texinfo.texi(,7056) @option{--output=@var{filename}}.
texinfo.texi(,7057) 
texinfo.texi(,7058) @code{@@option} is equivalent to @code{@@samp} in its effects.
texinfo.texi(,7059) For example:
texinfo.texi(,7060) 
texinfo.texi(,7061) @example
texinfo.texi(,7062) The option @@option@{-l@} produces a long listing.
texinfo.texi(,7063) @end example
texinfo.texi(,7064) @noindent produces
texinfo.texi(,7065) @quotation
texinfo.texi(,7066) The option @option{-l} produces a long listing.
texinfo.texi(,7067) @end quotation
texinfo.texi(,7068) 
texinfo.texi(,7069) In tables, putting options inside @code{@@code} produces a
texinfo.texi(,7070) more pleasing effect.
texinfo.texi(,7071) 
texinfo.texi(,7072) @node dfn
texinfo.texi(,7073) @comment  node-name,  next,  previous,  up
texinfo.texi(,7074) @subsection @code{@@dfn}@{@var{term}@}
texinfo.texi(,7075) @findex dfn
texinfo.texi(,7076) 
texinfo.texi(,7077) Use the @code{@@dfn} command to identify the introductory or defining
texinfo.texi(,7078) use of a technical term.  Use the command only in passages whose
texinfo.texi(,7079) purpose is to introduce a term which will be used again or which the
texinfo.texi(,7080) reader ought to know.  Mere passing mention of a term for the first
texinfo.texi(,7081) time does not deserve @code{@@dfn}.  The command generates italics in
texinfo.texi(,7082) the printed manual, and double quotation marks in the Info file.  For
texinfo.texi(,7083) example:@refill
texinfo.texi(,7084) 
texinfo.texi(,7085) @example
texinfo.texi(,7086) Getting rid of a file is called @@dfn@{deleting@} it.
texinfo.texi(,7087) @end example
texinfo.texi(,7088) 
texinfo.texi(,7089) @noindent
texinfo.texi(,7090) produces
texinfo.texi(,7091) 
texinfo.texi(,7092) @quotation
texinfo.texi(,7093) Getting rid of a file is called @dfn{deleting} it.
texinfo.texi(,7094) @end quotation
texinfo.texi(,7095) 
texinfo.texi(,7096) As a general rule, a sentence containing the defining occurrence of a
texinfo.texi(,7097) term should be a definition of the term.  The sentence does not need
texinfo.texi(,7098) to say explicitly that it is a definition, but it should contain the
texinfo.texi(,7099) information of a definition---it should make the meaning clear.
texinfo.texi(,7100) 
texinfo.texi(,7101) @node cite
texinfo.texi(,7102) @subsection @code{@@cite}@{@var{reference}@}
texinfo.texi(,7103) @findex cite
texinfo.texi(,7104) 
texinfo.texi(,7105) Use the @code{@@cite} command for the name of a book that lacks a
texinfo.texi(,7106) companion Info file.  The command produces italics in the printed
texinfo.texi(,7107) manual, and quotation marks in the Info file.
texinfo.texi(,7108) 
texinfo.texi(,7109) If a book is written in Texinfo, it is better to use a cross reference
texinfo.texi(,7110) command since a reader can easily follow such a reference in Info.
texinfo.texi(,7111) @xref{xref, , @code{@@xref}}.
texinfo.texi(,7112) 
texinfo.texi(,7113) 
texinfo.texi(,7162) 
texinfo.texi(,7163) 
texinfo.texi(,7164) @node acronym
texinfo.texi(,7165) @subsection @code{@@acronym}@{@var{acronym}@}
texinfo.texi(,7166) @findex acronym
texinfo.texi(,7167) 
texinfo.texi(,7168) @cindex NASA, as acronym
texinfo.texi(,7169) @cindex F.B.I., as acronym
texinfo.texi(,7170) @cindex Abbreviations, tagging
texinfo.texi(,7171) @cindex Acronyms, tagging
texinfo.texi(,7172) Use the @code{@@acronym} command for abbreviations written in all
texinfo.texi(,7173) capital letters, such as `@acronym{NASA}'.  The abbreviation is given as
texinfo.texi(,7174) the single argument in braces, as in @samp{@@acronym@{NASA@}}.  As
texinfo.texi(,7175) a matter of style, or for particular abbreviations, you may prefer to
texinfo.texi(,7176) use periods, as in @samp{@@acronym@{F.B.I.@}}.
texinfo.texi(,7177) 
texinfo.texi(,7178) In @TeX{} and HTML, the argument is printed in a slightly smaller font
texinfo.texi(,7179) size.  In Info or plain text output, this command changes nothing.
texinfo.texi(,7180) 
texinfo.texi(,7181) 
texinfo.texi(,7182) @node url
texinfo.texi(,7183) @subsection @code{@@url}@{@var{uniform-resource-locator}@}
texinfo.texi(,7184) @findex url
texinfo.texi(,7185) @cindex Uniform resource locator, indicating
texinfo.texi(,7186) @cindex URL, indicating
texinfo.texi(,7187) 
texinfo.texi(,7188) Use the @code{@@url} command to indicate a uniform resource locator on
texinfo.texi(,7189) the World Wide Web.  This is analogous to @code{@@file}, @code{@@var},
texinfo.texi(,7190) etc., and is purely for markup purposes.  It does not produce a link you
texinfo.texi(,7191) can follow in HTML output (use the @code{@@uref} command for that,
texinfo.texi(,7192) @pxref{uref,, @code{@@uref}}).  It is useful for url's which do
texinfo.texi(,7193) not actually exist.  For example:
texinfo.texi(,7194) 
texinfo.texi(,7195) @c Two lines because one is too long for smallbook format.
texinfo.texi(,7196) @example
texinfo.texi(,7197) For example, the url might be @@url@{http://example.org/path@}.
texinfo.texi(,7198) @end example
texinfo.texi(,7199) 
texinfo.texi(,7200) @noindent which produces:
texinfo.texi(,7201) 
texinfo.texi(,7202) @display
texinfo.texi(,7203) For example, the url might be @url{http://example.org/path}.
texinfo.texi(,7204) @end display
texinfo.texi(,7205) 
texinfo.texi(,7206) 
texinfo.texi(,7207) @node email
texinfo.texi(,7208) @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
texinfo.texi(,7209) @findex email
texinfo.texi(,7210) 
texinfo.texi(,7211) Use the @code{@@email} command to indicate an electronic mail address.
texinfo.texi(,7212) It takes one mandatory argument, the address, and one optional argument, the
texinfo.texi(,7213) text to display (the default is the address itself).
texinfo.texi(,7214) 
texinfo.texi(,7215) @cindex mailto link
texinfo.texi(,7216) In Info and @TeX{}, the address is shown in angle brackets, preceded by
texinfo.texi(,7217) the text to display if any.  In HTML output, @code{@@email} produces a
texinfo.texi(,7218) @samp{mailto} link that usually brings up a mail composition window.
texinfo.texi(,7219) For example:
texinfo.texi(,7220) 
texinfo.texi(,7221) @example
texinfo.texi(,7222) Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
texinfo.texi(,7223) suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
texinfo.texi(,7224) @end example
texinfo.texi(,7225) @noindent produces
texinfo.texi(,7226) @display
texinfo.texi(,7227) Send bug reports to @email{bug-texinfo@@gnu.org},
texinfo.texi(,7228) suggestions to the @email{bug-texinfo@@gnu.org, same place}.
texinfo.texi(,7229) @end display
texinfo.texi(,7230) 
texinfo.texi(,7231) 
texinfo.texi(,7232) @node Emphasis
texinfo.texi(,7233) @comment node-name,  next,  previous,  up
texinfo.texi(,7234) @section Emphasizing Text
texinfo.texi(,7235) @cindex Emphasizing text
texinfo.texi(,7236) 
texinfo.texi(,7237) Usually, Texinfo changes the font to mark words in the text according to
texinfo.texi(,7238) what category the words belong to; an example is the @code{@@code} command.
texinfo.texi(,7239) Most often, this is the best way to mark words.
texinfo.texi(,7240) However, sometimes you will want to emphasize text without indicating a
texinfo.texi(,7241) category.  Texinfo has two commands to do this.  Also, Texinfo has
texinfo.texi(,7242) several commands that specify the font in which @TeX{} will typeset
texinfo.texi(,7243) text.  These commands have no effect on Info and only one of them,
texinfo.texi(,7244) the @code{@@r} command, has any regular use.@refill
texinfo.texi(,7245) 
texinfo.texi(,7246) @menu
texinfo.texi(,7247) * emph & strong::               How to emphasize text in Texinfo.
texinfo.texi(,7248) * Smallcaps::                   How to use the small caps font.
texinfo.texi(,7249) * Fonts::                       Various font commands for printed output.
texinfo.texi(,7250) @end menu
texinfo.texi(,7251) 
texinfo.texi(,7252) @node emph & strong
texinfo.texi(,7253) @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
texinfo.texi(,7254) @cindex Emphasizing text, font for
texinfo.texi(,7255) @findex emph
texinfo.texi(,7256) @findex strong
texinfo.texi(,7257) 
texinfo.texi(,7258) The @code{@@emph} and @code{@@strong} commands are for emphasis;
texinfo.texi(,7259) @code{@@strong} is stronger.  In printed output, @code{@@emph} produces
texinfo.texi(,7260) @emph{italics} and @code{@@strong} produces @strong{bold}.
texinfo.texi(,7261) 
texinfo.texi(,7262) @need 800
texinfo.texi(,7263) For example,
texinfo.texi(,7264) 
texinfo.texi(,7265) @example
texinfo.texi(,7266) @group
texinfo.texi(,7267) @@quotation
texinfo.texi(,7268) @@strong@{Caution:@} @@samp@{rm * .[^.]*@} removes @@emph@{all@}
texinfo.texi(,7269) files in the directory.
texinfo.texi(,7270) @@end quotation
texinfo.texi(,7271) @end group
texinfo.texi(,7272) @end example
texinfo.texi(,7273) 
texinfo.texi(,7287) @noindent
texinfo.texi(,7288) produces:
texinfo.texi(,7290) 
texinfo.texi(,7291) @example
texinfo.texi(,7292)      *Caution*: `rm * .[^.]*' removes _all_
texinfo.texi(,7293)      files in the directory.
texinfo.texi(,7294) @end example
texinfo.texi(,7295) 
texinfo.texi(,7296) The @code{@@strong} command is seldom used except to mark what is, in
texinfo.texi(,7297) effect, a typographical element, such as the word `Caution' in the
texinfo.texi(,7298) preceding example.
texinfo.texi(,7299) 
texinfo.texi(,7300) In the Info output, @code{@@emph} surrounds the text with underscores
texinfo.texi(,7301) (@samp{_}), and @code{@@strong} puts asterisks around the text.
texinfo.texi(,7302) 
texinfo.texi(,7303) @quotation
texinfo.texi(,7304) @strong{Caution:} Do not use @code{@@strong} with the word @samp{Note};
texinfo.texi(,7305) Info will mistake the combination for a cross reference.  Use a phrase
texinfo.texi(,7306) such as @strong{Please note} or @strong{Caution} instead.
texinfo.texi(,7307) @end quotation
texinfo.texi(,7308) 
texinfo.texi(,7309) 
texinfo.texi(,7310) @node Smallcaps
texinfo.texi(,7311) @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
texinfo.texi(,7312) @cindex Small caps font
texinfo.texi(,7313) @findex sc @r{(small caps font)}
texinfo.texi(,7314) 
texinfo.texi(,7315) Use the @samp{@@sc} command to set text in the printed and the HTML
texinfo.texi(,7316) output in @sc{a small caps font} and set text in the Info file in upper
texinfo.texi(,7317) case letters.  Write the text you want to be in small caps (where
texinfo.texi(,7318) possible) between braces in lower case, like this:
texinfo.texi(,7319) 
texinfo.texi(,7320) @example
texinfo.texi(,7321) The @@sc@{acm@} and @@sc@{ieee@} are technical societies.
texinfo.texi(,7322) @end example
texinfo.texi(,7323) 
texinfo.texi(,7324) @noindent
texinfo.texi(,7325) This produces:
texinfo.texi(,7326) 
texinfo.texi(,7327) @display
texinfo.texi(,7328) The @sc{acm} and @sc{ieee} are technical societies.
texinfo.texi(,7329) @end display
texinfo.texi(,7330) 
texinfo.texi(,7331) @TeX{} typesets the small caps font in a manner that prevents the
texinfo.texi(,7332) letters from `jumping out at you on the page'.  This makes small caps
texinfo.texi(,7333) text easier to read than text in all upper case---but it's usually
texinfo.texi(,7334) better to use regular mixed case anyway.  The Info formatting commands
texinfo.texi(,7335) set all small caps text in upper case.  In HTML, the text is upper-cased
texinfo.texi(,7336) and a smaller font is used to render it.
texinfo.texi(,7337) 
texinfo.texi(,7338) If the text between the braces of an @code{@@sc} command is uppercase,
texinfo.texi(,7339) @TeX{} typesets in FULL-SIZE CAPITALS.  Use full-size capitals
texinfo.texi(,7340) sparingly, if ever, and since it's redundant to mark all-uppercase text
texinfo.texi(,7341) with @code{@@sc}, @command{makeinfo} warns about such usage.
texinfo.texi(,7342) 
texinfo.texi(,7343) You may also use the small caps font for a jargon word such as
texinfo.texi(,7344) @sc{ato} (a @sc{nasa} word meaning `abort to orbit').
texinfo.texi(,7345) 
texinfo.texi(,7346) There are subtleties to using the small caps font with a jargon word
texinfo.texi(,7347) such as @sc{cdr}, a word used in Lisp programming.  In this case, you
texinfo.texi(,7348) should use the small caps font when the word refers to the second and
texinfo.texi(,7349) subsequent elements of a list (the @sc{cdr} of the list), but you
texinfo.texi(,7350) should use @samp{@@code} when the word refers to the Lisp function of
texinfo.texi(,7351) the same spelling.
texinfo.texi(,7352) 
texinfo.texi(,7353) 
texinfo.texi(,7354) @node Fonts
texinfo.texi(,7355) @subsection Fonts for Printing, Not Info
texinfo.texi(,7356) @cindex Fonts for printing, not for Info
texinfo.texi(,7357) @findex i @r{(italic font)}
texinfo.texi(,7358) @findex b @r{(bold font)}
texinfo.texi(,7359) @findex t @r{(typewriter font)}
texinfo.texi(,7360) @findex r @r{(Roman font)}
texinfo.texi(,7361) 
texinfo.texi(,7362) Texinfo provides four font commands that specify font changes in the
texinfo.texi(,7363) printed manual but have no effect in the Info file.  @code{@@i}
texinfo.texi(,7364) requests @i{italic} font (in some versions of @TeX{}, a slanted font
texinfo.texi(,7365) is used), @code{@@b} requests @b{bold} face, @code{@@t} requests the
texinfo.texi(,7366) @t{fixed-width}, typewriter-style font used by @code{@@code}, and @code{@@r} requests a
texinfo.texi(,7367) @r{roman} font, which is the usual font in which text is printed.  All
texinfo.texi(,7368) four commands apply to an argument that follows, surrounded by
texinfo.texi(,7369) braces.@refill
texinfo.texi(,7370) 
texinfo.texi(,7371) Only the @code{@@r} command has much use: in example programs, you
texinfo.texi(,7372) can use the @code{@@r} command to convert code comments from the
texinfo.texi(,7373) fixed-width font to a roman font.  This looks better in printed
texinfo.texi(,7374) output.@refill
texinfo.texi(,7375) 
texinfo.texi(,7376) @need 700
texinfo.texi(,7377) For example,
texinfo.texi(,7378) 
texinfo.texi(,7379) @example
texinfo.texi(,7380) @group
texinfo.texi(,7381) @@lisp
texinfo.texi(,7382) (+ 2 2)    ; @@r@{Add two plus two.@}
texinfo.texi(,7383) @@end lisp
texinfo.texi(,7384) @end group
texinfo.texi(,7385) @end example
texinfo.texi(,7386) 
texinfo.texi(,7387) @noindent
texinfo.texi(,7388) produces
texinfo.texi(,7389) 
texinfo.texi(,7390) @lisp
texinfo.texi(,7391) (+ 2 2)    ; @r{Add two plus two.}
texinfo.texi(,7392) @end lisp
texinfo.texi(,7393) 
texinfo.texi(,7394) If possible, you should avoid using the other three font commands.  If
texinfo.texi(,7395) you need to use one, it probably indicates a gap in the Texinfo
texinfo.texi(,7396) language.
texinfo.texi(,7397) 
texinfo.texi(,7398) 
texinfo.texi(,7399) @node Quotations and Examples
texinfo.texi(,7400) @chapter Quotations and Examples
texinfo.texi(,7401) 
texinfo.texi(,7402) Quotations and examples are blocks of text consisting of one or more
texinfo.texi(,7403) whole paragraphs that are set off from the bulk of the text and
texinfo.texi(,7404) treated differently.  They are usually indented.@refill
texinfo.texi(,7405) 
texinfo.texi(,7406) In Texinfo, you always begin a quotation or example by writing an
texinfo.texi(,7407) @@-command at the beginning of a line by itself, and end it by writing
texinfo.texi(,7408) an @code{@@end} command that is also at the beginning of a line by
texinfo.texi(,7409) itself.  For instance, you begin an example by writing @code{@@example}
texinfo.texi(,7410) by itself at the beginning of a line and end the example by writing
texinfo.texi(,7411) @code{@@end example} on a line by itself, at the beginning of that
texinfo.texi(,7412) line.
texinfo.texi(,7413) @findex end
texinfo.texi(,7414) 
texinfo.texi(,7415) @menu
texinfo.texi(,7416) * Block Enclosing Commands::    Different constructs for different purposes.
texinfo.texi(,7417) * quotation::                   Writing a quotation.
texinfo.texi(,7418) * example::                     Writing an example in a fixed-width font.
texinfo.texi(,7419) * verbatim::                    Writing a verbatim example.
texinfo.texi(,7420) * verbatiminclude::             Including a file verbatim.
texinfo.texi(,7421) * lisp::                        Illustrating Lisp code.
texinfo.texi(,7422) * small::                       Forms for @code{@@smallbook}.
texinfo.texi(,7423) * display::                     Writing an example in the current font.
texinfo.texi(,7424) * format::                      Writing an example without narrowed margins.
texinfo.texi(,7425) * exdent::                      Undo indentation on a line.
texinfo.texi(,7426) * flushleft & flushright::      Pushing text flush left or flush right.
texinfo.texi(,7427) * noindent::                    Preventing paragraph indentation.
texinfo.texi(,7428) * cartouche::                   Drawing rounded rectangles around examples.
texinfo.texi(,7429) @end menu
texinfo.texi(,7430) 
texinfo.texi(,7431) 
texinfo.texi(,7432) @node Block Enclosing Commands
texinfo.texi(,7433) @section Block Enclosing Commands
texinfo.texi(,7434) 
texinfo.texi(,7435) Here are commands for quotations and examples, explained further in the
texinfo.texi(,7436) following sections:
texinfo.texi(,7437) 
texinfo.texi(,7438) @table @code
texinfo.texi(,7439) @item @@quotation
texinfo.texi(,7440) Indicate text that is quoted. The text is filled, indented, and
texinfo.texi(,7441) printed in a roman font by default.
texinfo.texi(,7442) 
texinfo.texi(,7443) @item @@example
texinfo.texi(,7444) Illustrate code, commands, and the like. The text is printed
texinfo.texi(,7445) in a fixed-width font, and indented but not filled.
texinfo.texi(,7446) 
texinfo.texi(,7447) @item @@verbatim
texinfo.texi(,7448) Mark a piece of text that is to be printed verbatim; no character 
texinfo.texi(,7449) substitutions are made and all commands are ignored, until the next
texinfo.texi(,7450) @code{@@end verbatim}.  The text is printed in a fixed-width font, 
texinfo.texi(,7451) and not indented or filled.  Extra spaces and blank lines are 
texinfo.texi(,7452) significant, and tabs are expanded.
texinfo.texi(,7453) 
texinfo.texi(,7454) @item @@smallexample
texinfo.texi(,7455) Same as @code{@@example}, except that in @TeX{} this command typesets
texinfo.texi(,7456) text in a smaller font.
texinfo.texi(,7457) 
texinfo.texi(,7458) @item @@lisp
texinfo.texi(,7459) Like @code{@@example}, but specifically for illustrating Lisp code. The
texinfo.texi(,7460) text is printed in a fixed-width font, and indented but not filled.
texinfo.texi(,7461) 
texinfo.texi(,7462) @item @@smalllisp
texinfo.texi(,7463) Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
texinfo.texi(,7464) 
texinfo.texi(,7465) @item @@display
texinfo.texi(,7466) Display illustrative text.  The text is indented but not filled, and
texinfo.texi(,7467) no font is selected (so, by default, the font is roman).@refill
texinfo.texi(,7468) 
texinfo.texi(,7469) @item @@smalldisplay
texinfo.texi(,7470) Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
texinfo.texi(,7471) 
texinfo.texi(,7472) @item @@format
texinfo.texi(,7473) Like @code{@@display} (the text is not filled and no font is selected),
texinfo.texi(,7474) but the text is not indented.
texinfo.texi(,7475) 
texinfo.texi(,7476) @item @@smallformat
texinfo.texi(,7477) Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
texinfo.texi(,7478) @end table
texinfo.texi(,7479) 
texinfo.texi(,7480) The @code{@@exdent} command is used within the above constructs to
texinfo.texi(,7481) undo the indentation of a line.
texinfo.texi(,7482) 
texinfo.texi(,7483) The @code{@@flushleft} and @code{@@flushright} commands are used to line
texinfo.texi(,7484) up the left or right margins of unfilled text.@refill
texinfo.texi(,7485) 
texinfo.texi(,7486) The @code{@@noindent} command may be used after one of the above
texinfo.texi(,7487) constructs to prevent the following text from being indented as a new
texinfo.texi(,7488) paragraph.
texinfo.texi(,7489) 
texinfo.texi(,7490) You can use the @code{@@cartouche} command within one of the above
texinfo.texi(,7491) constructs to highlight the example or quotation by drawing a box with
texinfo.texi(,7492) rounded corners around it.  @xref{cartouche, , Drawing Cartouches Around
texinfo.texi(,7493) Examples}.
texinfo.texi(,7494) 
texinfo.texi(,7495) 
texinfo.texi(,7496) @node quotation
texinfo.texi(,7497) @section @code{@@quotation}
texinfo.texi(,7498) @cindex Quotations
texinfo.texi(,7499) @findex quotation
texinfo.texi(,7500) 
texinfo.texi(,7501) The text of a quotation is processed normally except that:
texinfo.texi(,7502) 
texinfo.texi(,7503) @itemize @bullet
texinfo.texi(,7504) @item
texinfo.texi(,7505) the margins are closer to the center of the page, so the whole of the
texinfo.texi(,7506) quotation is indented;@refill
texinfo.texi(,7507) 
texinfo.texi(,7508) @item
texinfo.texi(,7509) the first lines of paragraphs are indented no more than other
texinfo.texi(,7510) lines;@refill
texinfo.texi(,7511) 
texinfo.texi(,7512) @item
texinfo.texi(,7513) in the printed output, interparagraph spacing is reduced.@refill
texinfo.texi(,7514) @end itemize
texinfo.texi(,7515) 
texinfo.texi(,7516) @quotation
texinfo.texi(,7517) This is an example of text written between an @code{@@quotation}
texinfo.texi(,7518) command and an @code{@@end quotation} command.  An @code{@@quotation}
texinfo.texi(,7519) command is most often used to indicate text that is excerpted from
texinfo.texi(,7520) another (real or hypothetical) printed work.@refill
texinfo.texi(,7521) @end quotation
texinfo.texi(,7522) 
texinfo.texi(,7523) Write an @code{@@quotation} command as text on a line by itself.  This
texinfo.texi(,7524) line will disappear from the output.  Mark the end of the quotation
texinfo.texi(,7525) with a line beginning with and containing only @code{@@end quotation}.
texinfo.texi(,7526) The @code{@@end quotation} line will likewise disappear from the
texinfo.texi(,7527) output.  Thus, the following,@refill
texinfo.texi(,7528) 
texinfo.texi(,7529) @example
texinfo.texi(,7530) @@quotation
texinfo.texi(,7531) This is
texinfo.texi(,7532) a foo.
texinfo.texi(,7533) @@end quotation
texinfo.texi(,7534) @end example
texinfo.texi(,7535) 
texinfo.texi(,7536) @noindent
texinfo.texi(,7537) produces
texinfo.texi(,7538) 
texinfo.texi(,7539) @quotation
texinfo.texi(,7540) This is a foo.
texinfo.texi(,7541) @end quotation
texinfo.texi(,7542) 
texinfo.texi(,7543) 
texinfo.texi(,7544) @node example
texinfo.texi(,7545) @section @code{@@example}: Example Text
texinfo.texi(,7546) @cindex Examples, formatting them
texinfo.texi(,7547) @cindex Formatting examples
texinfo.texi(,7548) @findex example
texinfo.texi(,7549) 
texinfo.texi(,7550) The @code{@@example} command is used to indicate an example that is
texinfo.texi(,7551) not part of the running text, such as computer input or output.
texinfo.texi(,7552) 
texinfo.texi(,7553) @example
texinfo.texi(,7554) @group
texinfo.texi(,7555) This is an example of text written between an
texinfo.texi(,7556) @code{@@example} command
texinfo.texi(,7557) and an @code{@@end example} command.
texinfo.texi(,7558) The text is indented but not filled.
texinfo.texi(,7559) @end group
texinfo.texi(,7560) 
texinfo.texi(,7561) @group
texinfo.texi(,7562) In the printed manual, the text is typeset in a
texinfo.texi(,7563) fixed-width font, and extra spaces and blank lines are
texinfo.texi(,7564) significant.  In the Info file, an analogous result is
texinfo.texi(,7565) obtained by indenting each line with five spaces.
texinfo.texi(,7566) @end group
texinfo.texi(,7567) @end example
texinfo.texi(,7568) 
texinfo.texi(,7569) Write an @code{@@example} command at the beginning of a line by itself.
texinfo.texi(,7570) Mark the end of the example
texinfo.texi(,7571) with an @code{@@end example} command, also written at the beginning of a
texinfo.texi(,7572) line by itself.@refill
texinfo.texi(,7573) 
texinfo.texi(,7574) @need 700
texinfo.texi(,7575) For example,
texinfo.texi(,7576) 
texinfo.texi(,7577) @example
texinfo.texi(,7578) @@example
texinfo.texi(,7579) mv foo bar
texinfo.texi(,7580) @@end example
texinfo.texi(,7581) @end example
texinfo.texi(,7582) 
texinfo.texi(,7583) @noindent
texinfo.texi(,7584) produces
texinfo.texi(,7585) 
texinfo.texi(,7586) @example
texinfo.texi(,7587) mv foo bar
texinfo.texi(,7588) @end example
texinfo.texi(,7589) 
texinfo.texi(,7590) The lines containing @code{@@example} and @code{@@end example}
texinfo.texi(,7591) will disappear from the output.
texinfo.texi(,7592) To make the output look good,
texinfo.texi(,7593) you should put a blank line before the
texinfo.texi(,7594) @code{@@example} and another blank line after the @code{@@end example}.
texinfo.texi(,7595) Note that blank lines inside the beginning
texinfo.texi(,7596) @code{@@example} and the ending @code{@@end example} will appear in
texinfo.texi(,7597) the output.@refill
texinfo.texi(,7598) 
texinfo.texi(,7599) @quotation
texinfo.texi(,7600) @strong{Caution:} Do not use tabs in the lines of an example or anywhere
texinfo.texi(,7601) else in Texinfo (except in verbatim environments)!  The @TeX{}
texinfo.texi(,7602) implementation of Texinfo treats tabs as single spaces, and that is not
texinfo.texi(,7603) what they look like.  (If necessary, in Emacs, you can use @kbd{M-x
texinfo.texi(,7604) untabify} to convert tabs in a region to multiple spaces.)@refill
texinfo.texi(,7605) @end quotation
texinfo.texi(,7606) 
texinfo.texi(,7607) Examples are often, logically speaking, ``in the middle'' of a
texinfo.texi(,7608) paragraph, and the text that continues after an example should not be
texinfo.texi(,7609) indented.  The @code{@@noindent} command prevents a piece of text from
texinfo.texi(,7610) being indented as if it were a new paragraph.
texinfo.texi(,7612) (@xref{noindent}.)
texinfo.texi(,7614) 
texinfo.texi(,7615) (The @code{@@code} command is used for examples of code that are
texinfo.texi(,7616) embedded within sentences, not set off from preceding and following
texinfo.texi(,7617) text.  @xref{code, , @code{@@code}}.)
texinfo.texi(,7618) 
texinfo.texi(,7619) 
texinfo.texi(,7620) @node verbatim
texinfo.texi(,7621) @section @code{@@verbatim}: Literal Text
texinfo.texi(,7622) @findex verbatim
texinfo.texi(,7623) @cindex Verbatim environment
texinfo.texi(,7624) 
texinfo.texi(,7625) Use the @code{@@verbatim} environment for printing of text that may
texinfo.texi(,7626) contain special characters or commands that should not be interpreted,
texinfo.texi(,7627) such as computer input or output (@code{@@example} interprets its text
texinfo.texi(,7628) as regular Texinfo commands).  This is especially useful for including
texinfo.texi(,7629) automatically generated output in a Texinfo manual.  Here is an example;
texinfo.texi(,7630) the output you see is just the same as the input, with a line
texinfo.texi(,7631) @code{@@verbatim} before and a line @code{@@end verbatim} after.
texinfo.texi(,7632) 
texinfo.texi(,7633) @verbatim
texinfo.texi(,7634) This is an example of text written in a @verbatim
texinfo.texi(,7635) block.  No character substitutions are made.  All commands
texinfo.texi(,7636) are ignored, until `<at>end verbatim'.
texinfo.texi(,7637) 
texinfo.texi(,7638) In the printed manual, the text is typeset in a
texinfo.texi(,7639) fixed-width font, and not indented or filled.  All
texinfo.texi(,7640) spaces and blank lines are significant, including tabs.
texinfo.texi(,7641) @end verbatim
texinfo.texi(,7642) 
texinfo.texi(,7643) Write a @code{@@verbatim} command at the beginning of a line by itself.
texinfo.texi(,7644) This line will disappear from the output.  Mark the end of the verbatim
texinfo.texi(,7645) block with a @code{@@end verbatim} command, also written at the
texinfo.texi(,7646) beginning of a line by itself.  The @code{@@end verbatim} will also
texinfo.texi(,7647) disappear from the output.
texinfo.texi(,7648) 
texinfo.texi(,7649) For example:
texinfo.texi(,7650) @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
texinfo.texi(,7651) 
texinfo.texi(,7652) @example
texinfo.texi(,7653) @exdent @@verbatim
texinfo.texi(,7654) @exdent @{
texinfo.texi(,7655) @exdent <tab>@@command with strange characters: @@'e 
texinfo.texi(,7656) @exdent expand<tab>me
texinfo.texi(,7657) @exdent @}
texinfo.texi(,7658) @exdent @@end verbatim
texinfo.texi(,7659) @end example
texinfo.texi(,7660) 
texinfo.texi(,7661) @noindent
texinfo.texi(,7662) produces
texinfo.texi(,7663) 
texinfo.texi(,7664) @verbatim
texinfo.texi(,7665) {
texinfo.texi(,7666) 	@command with strange characters: @'e 
texinfo.texi(,7667) expand	me
texinfo.texi(,7668) }
texinfo.texi(,7669) @end verbatim
texinfo.texi(,7670) 
texinfo.texi(,7671) Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
texinfo.texi(,7672) produce no output, tyically you should put a blank line before the
texinfo.texi(,7673) @code{@@verbatim} and another blank line after the @code{@@end
texinfo.texi(,7674) verbatim}.  Blank lines between the beginning @code{@@verbatim} and the
texinfo.texi(,7675) ending @code{@@end verbatim} will appear in the output.
texinfo.texi(,7676) 
texinfo.texi(,7677) 
texinfo.texi(,7678) @node verbatiminclude
texinfo.texi(,7679) @section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
texinfo.texi(,7680) @cindex Verbatim, include file
texinfo.texi(,7681) @cindex Including a file verbatim
texinfo.texi(,7682) @findex verbatiminclude
texinfo.texi(,7683) 
texinfo.texi(,7684) You can include the exact contents of a file in the document with the
texinfo.texi(,7685) @code{@@verbatiminclude} command:
texinfo.texi(,7686) 
texinfo.texi(,7687) @example
texinfo.texi(,7688) @@verbatiminclude @var{filename}
texinfo.texi(,7689) @end example
texinfo.texi(,7690) 
texinfo.texi(,7691) The contents of @var{filename} is printed in a verbatim environment
texinfo.texi(,7692) (@pxref{verbatim,,@code{@@verbatim}}).  Generally, the file is printed
texinfo.texi(,7693) exactly as it is, with all special characters and white space retained.
texinfo.texi(,7694) 
texinfo.texi(,7695) 
texinfo.texi(,7696) @node lisp
texinfo.texi(,7697) @section @code{@@lisp}: Marking a Lisp Example
texinfo.texi(,7698) @findex lisp
texinfo.texi(,7699) @cindex Lisp example
texinfo.texi(,7700) 
texinfo.texi(,7701) The @code{@@lisp} command is used for Lisp code.  It is synonymous
texinfo.texi(,7702) with the @code{@@example} command.
texinfo.texi(,7703) 
texinfo.texi(,7704) @lisp
texinfo.texi(,7705) This is an example of text written between an
texinfo.texi(,7706) @code{@@lisp} command and an @code{@@end lisp} command.
texinfo.texi(,7707) @end lisp
texinfo.texi(,7708) 
texinfo.texi(,7709) Use @code{@@lisp} instead of @code{@@example} to preserve information
texinfo.texi(,7710) regarding the nature of the example.  This is useful, for example, if
texinfo.texi(,7711) you write a function that evaluates only and all the Lisp code in a
texinfo.texi(,7712) Texinfo file.  Then you can use the Texinfo file as a Lisp
texinfo.texi(,7713) library.@footnote{It would be straightforward to extend Texinfo to work
texinfo.texi(,7714) in a similar fashion for C, Fortran, or other languages.}
texinfo.texi(,7715) 
texinfo.texi(,7716) Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
texinfo.texi(,7717) itself.@refill
texinfo.texi(,7718) 
texinfo.texi(,7719) 
texinfo.texi(,7720) @node small
texinfo.texi(,7721) @section @code{@@small@dots{}} Block Commands
texinfo.texi(,7722) @cindex Small examples
texinfo.texi(,7723) @cindex Examples in smaller fonts
texinfo.texi(,7724) @cindex Lisp examples in smaller fonts
texinfo.texi(,7725) @findex smalldisplay
texinfo.texi(,7726) @findex smallexample
texinfo.texi(,7727) @findex smallformat
texinfo.texi(,7728) @findex smalllisp
texinfo.texi(,7729) 
texinfo.texi(,7730) In addition to the regular @code{@@example} and @code{@@lisp} commands,
texinfo.texi(,7731) Texinfo has ``small'' example-style commands.  These are
texinfo.texi(,7732) @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
texinfo.texi(,7733) @code{@@smalllisp}.
texinfo.texi(,7734) 
texinfo.texi(,7735) In @TeX{}, the @code{@@small@dots{}} commands typeset text in a smaller
texinfo.texi(,7736) font than the non-small example commands.  Consequently, many examples
texinfo.texi(,7737) containing long lines fit on a page without needing to be shortened.
texinfo.texi(,7738) 
texinfo.texi(,7739) In Info, the @code{@@small@dots{}} commands are equivalent to their
texinfo.texi(,7740) non-small companion commands.
texinfo.texi(,7741) 
texinfo.texi(,7742) Mark the end of an @code{@@small@dots{}} block with a corresponding
texinfo.texi(,7743) @code{@@end small@dots{}}.  For example, pair @code{@@smallexample} with
texinfo.texi(,7744) @code{@@end smallexample}.
texinfo.texi(,7745) 
texinfo.texi(,7776) @smallexample
texinfo.texi(,7777) This is an example of text written between @code{@@smallexample} and
texinfo.texi(,7778) @code{@@end smallexample}.  In Info this text appears in its normal size;
texinfo.texi(,7779) but in a 7 by 9.25 inch manual, this text appears in a smaller font.
texinfo.texi(,7780) @end smallexample
texinfo.texi(,7782) 
texinfo.texi(,7783) The @code{@@small@dots{}} commands make it easier to prepare manuals
texinfo.texi(,7784) without forcing you to edit examples by hand to fit them onto narrower
texinfo.texi(,7785) pages.
texinfo.texi(,7786) 
texinfo.texi(,7787) As a general rule, a printed document looks better if you use only one
texinfo.texi(,7788) of (for example) @code{@@example} or in @code{@@smallexample}
texinfo.texi(,7789) consistently within a chapter.  Only occasionally should you mix the two
texinfo.texi(,7790) formats.
texinfo.texi(,7791) 
texinfo.texi(,7792) @xref{smallbook, , Printing ``Small'' Books}, for more information
texinfo.texi(,7793) about the @code{@@smallbook} command.
texinfo.texi(,7794) 
texinfo.texi(,7795) 
texinfo.texi(,7796) @node display
texinfo.texi(,7797) @section @code{@@display} and @code{@@smalldisplay}
texinfo.texi(,7798) @cindex Display formatting
texinfo.texi(,7799) @findex display
texinfo.texi(,7800) 
texinfo.texi(,7801) The @code{@@display} command begins a kind of example.  It is like the
texinfo.texi(,7802) @code{@@example} command
texinfo.texi(,7803) except that, in
texinfo.texi(,7804) a printed manual, @code{@@display} does not select the fixed-width
texinfo.texi(,7805) font.  In fact, it does not specify the font at all, so that the text
texinfo.texi(,7806) appears in the same font it would have appeared in without the
texinfo.texi(,7807) @code{@@display} command.@refill
texinfo.texi(,7808) 
texinfo.texi(,7809) @display
texinfo.texi(,7810) This is an example of text written between an @code{@@display} command
texinfo.texi(,7811) and an @code{@@end display} command.  The @code{@@display} command
texinfo.texi(,7812) indents the text, but does not fill it.
texinfo.texi(,7813) @end display
texinfo.texi(,7814) 
texinfo.texi(,7815) @findex smalldisplay
texinfo.texi(,7816) Texinfo also provides a command @code{@@smalldisplay}, which is like
texinfo.texi(,7817) @code{@@display} but uses a smaller font in @code{@@smallbook} format.
texinfo.texi(,7818) @xref{small}.
texinfo.texi(,7819) 
texinfo.texi(,7820) 
texinfo.texi(,7821) @node format
texinfo.texi(,7822) @section @code{@@format} and @code{@@smallformat}
texinfo.texi(,7823) @findex format
texinfo.texi(,7824) 
texinfo.texi(,7825) The @code{@@format} command is similar to @code{@@example} except
texinfo.texi(,7826) that, in the printed manual, @code{@@format} does not select the
texinfo.texi(,7827) fixed-width font and does not narrow the margins.@refill
texinfo.texi(,7828) 
texinfo.texi(,7829) @format
texinfo.texi(,7830) This is an example of text written between an @code{@@format} command
texinfo.texi(,7831) and an @code{@@end format} command.  As you can see
texinfo.texi(,7832) from this example,
texinfo.texi(,7833) the @code{@@format} command does not fill the text.
texinfo.texi(,7834) @end format
texinfo.texi(,7835) 
texinfo.texi(,7836) @findex smallformat
texinfo.texi(,7837) Texinfo also provides a command @code{@@smallformat}, which is like
texinfo.texi(,7838) @code{@@format} but uses a smaller font in @code{@@smallbook} format.
texinfo.texi(,7839) @xref{small}.
texinfo.texi(,7840) 
texinfo.texi(,7841) 
texinfo.texi(,7842) 
texinfo.texi(,7843) @node exdent
texinfo.texi(,7844) @section @code{@@exdent}: Undoing a Line's Indentation
texinfo.texi(,7845) @cindex Indentation undoing
texinfo.texi(,7846) @findex exdent
texinfo.texi(,7847) 
texinfo.texi(,7848) The @code{@@exdent} command removes any indentation a line might have.
texinfo.texi(,7849) The command is written at the beginning of a line and applies only to
texinfo.texi(,7850) the text that follows the command that is on the same line.  Do not use
texinfo.texi(,7851) braces around the text.  In a printed manual, the text on an
texinfo.texi(,7852) @code{@@exdent} line is printed in the roman font.@refill
texinfo.texi(,7853) 
texinfo.texi(,7854) @code{@@exdent} is usually used within examples.  Thus,@refill
texinfo.texi(,7855) 
texinfo.texi(,7856) @example
texinfo.texi(,7857) @group
texinfo.texi(,7858) @@example
texinfo.texi(,7859) This line follows an @@@@example command.
texinfo.texi(,7860) @@exdent This line is exdented.
texinfo.texi(,7861) This line follows the exdented line.
texinfo.texi(,7862) The @@@@end example comes on the next line.
texinfo.texi(,7863) @@end group
texinfo.texi(,7864) @end group
texinfo.texi(,7865) @end example
texinfo.texi(,7866) 
texinfo.texi(,7867) @noindent
texinfo.texi(,7868) produces
texinfo.texi(,7869) 
texinfo.texi(,7870) @example
texinfo.texi(,7871) @group
texinfo.texi(,7872) This line follows an @@example command.
texinfo.texi(,7873) @exdent This line is exdented.
texinfo.texi(,7874) This line follows the exdented line.
texinfo.texi(,7875) The @@end example comes on the next line.
texinfo.texi(,7876) @end group
texinfo.texi(,7877) @end example
texinfo.texi(,7878) 
texinfo.texi(,7879) In practice, the @code{@@exdent} command is rarely used.
texinfo.texi(,7880) Usually, you un-indent text by ending the example and
texinfo.texi(,7881) returning the page to its normal width.@refill
texinfo.texi(,7882) 
texinfo.texi(,7883) 
texinfo.texi(,7884) @node flushleft & flushright
texinfo.texi(,7885) @section @code{@@flushleft} and @code{@@flushright}
texinfo.texi(,7886) @findex flushleft
texinfo.texi(,7887) @findex flushright
texinfo.texi(,7888) @cindex ragged right
texinfo.texi(,7889) @cindex ragged left
texinfo.texi(,7890) 
texinfo.texi(,7891) The @code{@@flushleft} and @code{@@flushright} commands line up the
texinfo.texi(,7892) ends of lines on the left and right margins of a page,
texinfo.texi(,7893) but do not fill the text.  The commands are written on lines of their
texinfo.texi(,7894) own, without braces.  The @code{@@flushleft} and @code{@@flushright}
texinfo.texi(,7895) commands are ended by @code{@@end flushleft} and @code{@@end
texinfo.texi(,7896) flushright} commands on lines of their own.@refill
texinfo.texi(,7897) 
texinfo.texi(,7898) @need 1500
texinfo.texi(,7899) For example,
texinfo.texi(,7900) 
texinfo.texi(,7901) @example
texinfo.texi(,7902) @group
texinfo.texi(,7903) @@flushleft
texinfo.texi(,7904) This text is
texinfo.texi(,7905) written flushleft.
texinfo.texi(,7906) @@end flushleft
texinfo.texi(,7907) @end group
texinfo.texi(,7908) @end example
texinfo.texi(,7909) 
texinfo.texi(,7910) @noindent
texinfo.texi(,7911) produces
texinfo.texi(,7912) 
texinfo.texi(,7913) @quotation
texinfo.texi(,7914) @flushleft
texinfo.texi(,7915) This text is
texinfo.texi(,7916) written flushleft.
texinfo.texi(,7917) @end flushleft
texinfo.texi(,7918) @end quotation
texinfo.texi(,7919) 
texinfo.texi(,7920) 
texinfo.texi(,7921) @code{@@flushright} produces the type of indentation often used in the
texinfo.texi(,7922) return address of letters.  For example,
texinfo.texi(,7923) 
texinfo.texi(,7924) @example
texinfo.texi(,7925) @group
texinfo.texi(,7926) @@flushright
texinfo.texi(,7927) Here is an example of text written
texinfo.texi(,7928) flushright.  The @@code@{@@flushright@} command
texinfo.texi(,7929) right justifies every line but leaves the
texinfo.texi(,7930) left end ragged.
texinfo.texi(,7931) @@end flushright
texinfo.texi(,7932) @end group
texinfo.texi(,7933) @end example
texinfo.texi(,7934) 
texinfo.texi(,7935) @noindent
texinfo.texi(,7936) produces
texinfo.texi(,7937) 
texinfo.texi(,7938) @flushright
texinfo.texi(,7939) Here is an example of text written
texinfo.texi(,7940) flushright.  The @code{@@flushright} command
texinfo.texi(,7941) right justifies every line but leaves the
texinfo.texi(,7942) left end ragged.
texinfo.texi(,7943) @end flushright
texinfo.texi(,7944) 
texinfo.texi(,7945) 
texinfo.texi(,7946) @node noindent
texinfo.texi(,7947) @section @code{@@noindent}: Omitting Indentation
texinfo.texi(,7948) @findex noindent
texinfo.texi(,7949) 
texinfo.texi(,7950) An example or other inclusion can break a paragraph into segments.
texinfo.texi(,7951) Ordinarily, the formatters indent text that follows an example as a new
texinfo.texi(,7952) paragraph.  However, you can prevent this by writing @code{@@noindent}
texinfo.texi(,7953) at the beginning of a line by itself preceding the continuation
texinfo.texi(,7954) text.@refill
texinfo.texi(,7955) 
texinfo.texi(,7956) @need 1500
texinfo.texi(,7957) For example:
texinfo.texi(,7958) 
texinfo.texi(,7959) @example
texinfo.texi(,7960) @group
texinfo.texi(,7961) @@example
texinfo.texi(,7962) This is an example
texinfo.texi(,7963) @@end example
texinfo.texi(,7964) 
texinfo.texi(,7965) @@noindent
texinfo.texi(,7966) This line is not indented.  As you can see, the
texinfo.texi(,7967) beginning of the line is fully flush left with the line
texinfo.texi(,7968) that follows after it.  (This whole example is between
texinfo.texi(,7969) @@code@{@@@@display@} and @@code@{@@@@end display@}.)
texinfo.texi(,7970) @end group
texinfo.texi(,7971) @end example
texinfo.texi(,7972) 
texinfo.texi(,7973) @noindent
texinfo.texi(,7974) produces
texinfo.texi(,7975) 
texinfo.texi(,7976) @display
texinfo.texi(,7977) @example
texinfo.texi(,7978) This is an example
texinfo.texi(,7979) @end example
texinfo.texi(,7984) 
texinfo.texi(,7985) @noindent
texinfo.texi(,7986) This line is not indented.  As you can see, the
texinfo.texi(,7987) beginning of the line is fully flush left with the line
texinfo.texi(,7988) that follows after it.  (This whole example is between
texinfo.texi(,7989) @code{@@display} and @code{@@end display}.)
texinfo.texi(,7990) @end display
texinfo.texi(,7991) 
texinfo.texi(,7992) To adjust the number of blank lines properly in the Info file output,
texinfo.texi(,7993) remember that the line containing @code{@@noindent} does not generate a
texinfo.texi(,7994) blank line, and neither does the @code{@@end example} line.@refill
texinfo.texi(,7995) 
texinfo.texi(,7996) In the Texinfo source file for this manual, each line that says
texinfo.texi(,7997) `produces' is preceded by a line containing @code{@@noindent}.@refill
texinfo.texi(,7998) 
texinfo.texi(,7999) Do not put braces after an @code{@@noindent} command; they are not
texinfo.texi(,8000) necessary, since @code{@@noindent} is a command used outside of
texinfo.texi(,8001) paragraphs (@pxref{Command Syntax}).@refill
texinfo.texi(,8002) 
texinfo.texi(,8003) 
texinfo.texi(,8004) @node cartouche
texinfo.texi(,8005) @section @code{@@cartouche}: Rounded Rectangles Around Examples
texinfo.texi(,8006) @findex cartouche
texinfo.texi(,8007) @cindex Box with rounded corners
texinfo.texi(,8008) @cindex Rounded rectangles, around examples
texinfo.texi(,8009) 
texinfo.texi(,8010) In a printed manual, the @code{@@cartouche} command draws a box with
texinfo.texi(,8011) rounded corners around its contents.  You can use this command to
texinfo.texi(,8012) further highlight an example or quotation.  For instance, you could
texinfo.texi(,8013) write a manual in which one type of example is surrounded by a cartouche
texinfo.texi(,8014) for emphasis.
texinfo.texi(,8015) 
texinfo.texi(,8016) @code{@@cartouche} affects only the printed manual; it has no effect in
texinfo.texi(,8017) other output files.
texinfo.texi(,8018) 
texinfo.texi(,8019) @need 1500
texinfo.texi(,8020) For example,
texinfo.texi(,8021) 
texinfo.texi(,8022) @example
texinfo.texi(,8023) @group
texinfo.texi(,8024) @@example
texinfo.texi(,8025) @@cartouche
texinfo.texi(,8026) % pwd
texinfo.texi(,8027) /usr/local/share/emacs
texinfo.texi(,8028) @@end cartouche
texinfo.texi(,8029) @@end example
texinfo.texi(,8030) @end group
texinfo.texi(,8031) @end example
texinfo.texi(,8032) 
texinfo.texi(,8033) @noindent
texinfo.texi(,8034) surrounds the two-line example with a box with rounded corners, in the
texinfo.texi(,8035) printed manual.
texinfo.texi(,8036) 
texinfo.texi(,8049) 
texinfo.texi(,8050) 
texinfo.texi(,8051) @node Lists and Tables
texinfo.texi(,8052) @chapter Lists and Tables
texinfo.texi(,8053) @cindex Making lists and tables
texinfo.texi(,8054) @cindex Lists and tables, making
texinfo.texi(,8055) @cindex Tables and lists, making
texinfo.texi(,8056) 
texinfo.texi(,8057) Texinfo has several ways of making lists and tables.  Lists can be
texinfo.texi(,8058) bulleted or numbered; two-column tables can highlight the items in
texinfo.texi(,8059) the first column; multi-column tables are also supported.
texinfo.texi(,8060) 
texinfo.texi(,8061) @menu
texinfo.texi(,8062) * Introducing Lists::           Texinfo formats lists for you.
texinfo.texi(,8063) * itemize::                     How to construct a simple list.
texinfo.texi(,8064) * enumerate::                   How to construct a numbered list.
texinfo.texi(,8065) * Two-column Tables::           How to construct a two-column table.
texinfo.texi(,8066) * Multi-column Tables::         How to construct generalized tables.
texinfo.texi(,8067) @end menu
texinfo.texi(,8068) 
texinfo.texi(,8069) @node Introducing Lists, itemize, Lists and Tables, Lists and Tables
texinfo.texi(,8071) @heading Introducing Lists
texinfo.texi(,8073) 
texinfo.texi(,8074) Texinfo automatically indents the text in lists or tables, and numbers
texinfo.texi(,8075) an enumerated list.  This last feature is useful if you modify the
texinfo.texi(,8076) list, since you do not need to renumber it yourself.@refill
texinfo.texi(,8077) 
texinfo.texi(,8078) Numbered lists and tables begin with the appropriate @@-command at the
texinfo.texi(,8079) beginning of a line, and end with the corresponding @code{@@end}
texinfo.texi(,8080) command on a line by itself.  The table and itemized-list commands
texinfo.texi(,8081) also require that you write formatting information on the same line as
texinfo.texi(,8082) the beginning @@-command.@refill
texinfo.texi(,8083) 
texinfo.texi(,8084) Begin an enumerated list, for example, with an @code{@@enumerate}
texinfo.texi(,8085) command and end the list with an @code{@@end enumerate} command.
texinfo.texi(,8086) Begin an itemized list with an @code{@@itemize} command, followed on
texinfo.texi(,8087) the same line by a formatting command such as @code{@@bullet}, and end
texinfo.texi(,8088) the list with an @code{@@end itemize} command.@refill
texinfo.texi(,8089) @findex end
texinfo.texi(,8090) 
texinfo.texi(,8091) Precede each element of a list with an @code{@@item} or @code{@@itemx}
texinfo.texi(,8092) command.@refill
texinfo.texi(,8093) 
texinfo.texi(,8094) @sp 1
texinfo.texi(,8095) @noindent
texinfo.texi(,8096) Here is an itemized list of the different kinds of table and lists:@refill
texinfo.texi(,8097) 
texinfo.texi(,8098) @itemize @bullet
texinfo.texi(,8099) @item
texinfo.texi(,8100) Itemized lists with and without bullets.
texinfo.texi(,8101) 
texinfo.texi(,8102) @item
texinfo.texi(,8103) Enumerated lists, using numbers or letters.
texinfo.texi(,8104) 
texinfo.texi(,8105) @item
texinfo.texi(,8106) Two-column tables with highlighting.
texinfo.texi(,8107) @end itemize
texinfo.texi(,8108) 
texinfo.texi(,8109) @sp 1
texinfo.texi(,8110) @noindent
texinfo.texi(,8111) Here is an enumerated list with the same items:@refill
texinfo.texi(,8112) 
texinfo.texi(,8113) @enumerate
texinfo.texi(,8114) @item
texinfo.texi(,8115) Itemized lists with and without bullets.
texinfo.texi(,8116) 
texinfo.texi(,8117) @item
texinfo.texi(,8118) Enumerated lists, using numbers or letters.
texinfo.texi(,8119) 
texinfo.texi(,8120) @item
texinfo.texi(,8121) Two-column tables with highlighting.
texinfo.texi(,8122) @end enumerate
texinfo.texi(,8123) 
texinfo.texi(,8124) @sp 1
texinfo.texi(,8125) @noindent
texinfo.texi(,8126) And here is a two-column table with the same items and their
texinfo.texi(,8127) @w{@@-commands}:@refill
texinfo.texi(,8128) 
texinfo.texi(,8129) @table @code
texinfo.texi(,8130) @item @@itemize
texinfo.texi(,8131) Itemized lists with and without bullets.
texinfo.texi(,8132) 
texinfo.texi(,8133) @item @@enumerate
texinfo.texi(,8134) Enumerated lists, using numbers or letters.
texinfo.texi(,8135) 
texinfo.texi(,8136) @item @@table
texinfo.texi(,8137) @itemx @@ftable
texinfo.texi(,8138) @itemx @@vtable
texinfo.texi(,8139) Two-column tables, optionally with indexing.
texinfo.texi(,8140) @end table
texinfo.texi(,8141) 
texinfo.texi(,8142) 
texinfo.texi(,8143) @node itemize
texinfo.texi(,8144) @section @code{@@itemize}: Making an Itemized List
texinfo.texi(,8145) @cindex Itemization
texinfo.texi(,8146) @findex itemize
texinfo.texi(,8147) 
texinfo.texi(,8148) The @code{@@itemize} command produces sequences of indented
texinfo.texi(,8149) paragraphs, with a bullet or other mark inside the left margin
texinfo.texi(,8150) at the beginning of each paragraph for which such a mark is desired.@refill
texinfo.texi(,8151) 
texinfo.texi(,8152) @cindex @code{@@w}, for blank items
texinfo.texi(,8153) Begin an itemized list by writing @code{@@itemize} at the beginning of
texinfo.texi(,8154) a line.  Follow the command, on the same line, with a character or a
texinfo.texi(,8155) Texinfo command that generates a mark.  Usually, you will write
texinfo.texi(,8156) @code{@@bullet} after @code{@@itemize}, but you can use
texinfo.texi(,8157) @code{@@minus}, or any command or character that results in a single
texinfo.texi(,8158) character in the Info file.  If you don't want any mark at all, use
texinfo.texi(,8159) @code{@@w}.  (When you write the mark command such as
texinfo.texi(,8160) @code{@@bullet} after an @code{@@itemize} command, you may omit the
texinfo.texi(,8161) @samp{@{@}}.)  If you don't specify a mark command, the default is
texinfo.texi(,8162) @code{@@bullet}.
texinfo.texi(,8163) 
texinfo.texi(,8164) Write the text of the indented paragraphs themselves after the
texinfo.texi(,8165) @code{@@itemize}, up to another line that says @code{@@end
texinfo.texi(,8166) itemize}.@refill
texinfo.texi(,8167) 
texinfo.texi(,8168) @findex item
texinfo.texi(,8169) Before each paragraph for which a mark in the margin is desired, write a
texinfo.texi(,8170) line that says just @code{@@item}.  It is ok to have text following the
texinfo.texi(,8171) @code{@@item}.
texinfo.texi(,8172) 
texinfo.texi(,8173) Usually, you should put a blank line before an @code{@@item}.  This
texinfo.texi(,8174) puts a blank line in the Info file. (@TeX{} inserts the proper
texinfo.texi(,8175) interline whitespace in either case.)  Except when the entries are
texinfo.texi(,8176) very brief, these blank lines make the list look better.@refill
texinfo.texi(,8177) 
texinfo.texi(,8178) Here is an example of the use of @code{@@itemize}, followed by the
texinfo.texi(,8179) output it produces.  @code{@@bullet} produces an @samp{*} in Info and a
texinfo.texi(,8180) round dot in @TeX{}.
texinfo.texi(,8181) 
texinfo.texi(,8182) @example
texinfo.texi(,8183) @group
texinfo.texi(,8184) @@itemize @@bullet
texinfo.texi(,8185) @@item
texinfo.texi(,8186) Some text for foo.
texinfo.texi(,8187) 
texinfo.texi(,8188) @@item
texinfo.texi(,8189) Some text
texinfo.texi(,8190) for bar.
texinfo.texi(,8191) @@end itemize
texinfo.texi(,8192) @end group
texinfo.texi(,8193) @end example
texinfo.texi(,8194) 
texinfo.texi(,8195) @noindent
texinfo.texi(,8196) This produces:
texinfo.texi(,8197) 
texinfo.texi(,8198) @quotation
texinfo.texi(,8199) @itemize @bullet
texinfo.texi(,8200) @item
texinfo.texi(,8201) Some text for foo.
texinfo.texi(,8202) 
texinfo.texi(,8203) @item
texinfo.texi(,8204) Some text
texinfo.texi(,8205) for bar.
texinfo.texi(,8206) @end itemize
texinfo.texi(,8207) @end quotation
texinfo.texi(,8208) 
texinfo.texi(,8209) Itemized lists may be embedded within other itemized lists.  Here is a
texinfo.texi(,8210) list marked with dashes embedded in a list marked with bullets:@refill
texinfo.texi(,8211) 
texinfo.texi(,8212) @example
texinfo.texi(,8213) @group
texinfo.texi(,8214) @@itemize @@bullet
texinfo.texi(,8215) @@item
texinfo.texi(,8216) First item.
texinfo.texi(,8217) 
texinfo.texi(,8218) @@itemize @@minus
texinfo.texi(,8219) @@item
texinfo.texi(,8220) Inner item.
texinfo.texi(,8221) 
texinfo.texi(,8222) @@item
texinfo.texi(,8223) Second inner item.
texinfo.texi(,8224) @@end itemize
texinfo.texi(,8225) 
texinfo.texi(,8226) @@item
texinfo.texi(,8227) Second outer item.
texinfo.texi(,8228) @@end itemize
texinfo.texi(,8229) @end group
texinfo.texi(,8230) @end example
texinfo.texi(,8231) 
texinfo.texi(,8232) @noindent
texinfo.texi(,8233) This produces:
texinfo.texi(,8234) 
texinfo.texi(,8235) @quotation
texinfo.texi(,8236) @itemize @bullet
texinfo.texi(,8237) @item
texinfo.texi(,8238) First item.
texinfo.texi(,8239) 
texinfo.texi(,8240) @itemize @minus
texinfo.texi(,8241) @item
texinfo.texi(,8242) Inner item.
texinfo.texi(,8243) 
texinfo.texi(,8244) @item
texinfo.texi(,8245) Second inner item.
texinfo.texi(,8246) @end itemize
texinfo.texi(,8247) 
texinfo.texi(,8248) @item
texinfo.texi(,8249) Second outer item.
texinfo.texi(,8250) @end itemize
texinfo.texi(,8251) @end quotation
texinfo.texi(,8252) 
texinfo.texi(,8253) 
texinfo.texi(,8254) @node enumerate
texinfo.texi(,8255) @section @code{@@enumerate}: Making a Numbered or Lettered List
texinfo.texi(,8256) @cindex Enumeration
texinfo.texi(,8257) @findex enumerate
texinfo.texi(,8258) 
texinfo.texi(,8259) @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
texinfo.texi(,8260) @code{@@itemize}}), except that the labels on the items are
texinfo.texi(,8261) successive integers or letters instead of bullets.
texinfo.texi(,8262) 
texinfo.texi(,8263) Write the @code{@@enumerate} command at the beginning of a line.  The
texinfo.texi(,8264) command does not require an argument, but accepts either a number or a
texinfo.texi(,8265) letter as an option.  Without an argument, @code{@@enumerate} starts the
texinfo.texi(,8266) list with the number @samp{1}.  With a numeric argument, such as
texinfo.texi(,8267) @samp{3}, the command starts the list with that number.  With an upper
texinfo.texi(,8268) or lower case letter, such as @samp{a} or @samp{A}, the command starts
texinfo.texi(,8269) the list with that letter.
texinfo.texi(,8270) 
texinfo.texi(,8271) Write the text of the enumerated list in the same way you write an
texinfo.texi(,8272) itemized list: put @code{@@item} on a line of its own before the start
texinfo.texi(,8273) of each paragraph that you want enumerated.  Do not write any other text
texinfo.texi(,8274) on the line beginning with @code{@@item}.
texinfo.texi(,8275) 
texinfo.texi(,8276) You should put a blank line between entries in the list.
texinfo.texi(,8277) This generally makes it easier to read the Info file.
texinfo.texi(,8278) 
texinfo.texi(,8279) @need 1500
texinfo.texi(,8280) Here is an example of @code{@@enumerate} without an argument:
texinfo.texi(,8281) 
texinfo.texi(,8282) @example
texinfo.texi(,8283) @group
texinfo.texi(,8284) @@enumerate
texinfo.texi(,8285) @@item
texinfo.texi(,8286) Underlying causes.
texinfo.texi(,8287) 
texinfo.texi(,8288) @@item
texinfo.texi(,8289) Proximate causes.
texinfo.texi(,8290) @@end enumerate
texinfo.texi(,8291) @end group
texinfo.texi(,8292) @end example
texinfo.texi(,8293) 
texinfo.texi(,8294) @noindent
texinfo.texi(,8295) This produces:
texinfo.texi(,8296) 
texinfo.texi(,8297) @enumerate
texinfo.texi(,8298) @item
texinfo.texi(,8299) Underlying causes.
texinfo.texi(,8300) 
texinfo.texi(,8301) @item
texinfo.texi(,8302) Proximate causes.
texinfo.texi(,8303) @end enumerate
texinfo.texi(,8304) @sp 1
texinfo.texi(,8305) Here is an example with an argument of @kbd{3}:@refill
texinfo.texi(,8306) @sp 1
texinfo.texi(,8307) @example
texinfo.texi(,8308) @group
texinfo.texi(,8309) @@enumerate 3
texinfo.texi(,8310) @@item
texinfo.texi(,8311) Predisposing causes.
texinfo.texi(,8312) 
texinfo.texi(,8313) @@item
texinfo.texi(,8314) Precipitating causes.
texinfo.texi(,8315) 
texinfo.texi(,8316) @@item
texinfo.texi(,8317) Perpetuating causes.
texinfo.texi(,8318) @@end enumerate
texinfo.texi(,8319) @end group
texinfo.texi(,8320) @end example
texinfo.texi(,8321) 
texinfo.texi(,8322) @noindent
texinfo.texi(,8323) This produces:
texinfo.texi(,8324) 
texinfo.texi(,8325) @enumerate 3
texinfo.texi(,8326) @item
texinfo.texi(,8327) Predisposing causes.
texinfo.texi(,8328) 
texinfo.texi(,8329) @item
texinfo.texi(,8330) Precipitating causes.
texinfo.texi(,8331) 
texinfo.texi(,8332) @item
texinfo.texi(,8333) Perpetuating causes.
texinfo.texi(,8334) @end enumerate
texinfo.texi(,8335) @sp 1
texinfo.texi(,8336) Here is a brief summary of the alternatives.  The summary is constructed
texinfo.texi(,8337) using @code{@@enumerate} with an argument of @kbd{a}.@refill
texinfo.texi(,8338) @sp 1
texinfo.texi(,8339) @enumerate a
texinfo.texi(,8340) @item
texinfo.texi(,8341) @code{@@enumerate}
texinfo.texi(,8342) 
texinfo.texi(,8343) Without an argument, produce a numbered list, starting with the number
texinfo.texi(,8344) 1.@refill
texinfo.texi(,8345) 
texinfo.texi(,8346) @item
texinfo.texi(,8347) @code{@@enumerate @var{positive-integer}}
texinfo.texi(,8348) 
texinfo.texi(,8349) With a (positive) numeric argument, start a numbered list with that
texinfo.texi(,8350) number.  You can use this to continue a list that you interrupted with
texinfo.texi(,8351) other text.@refill
texinfo.texi(,8352) 
texinfo.texi(,8353) @item
texinfo.texi(,8354) @code{@@enumerate @var{upper-case-letter}}
texinfo.texi(,8355) 
texinfo.texi(,8356) With an upper case letter as argument, start a list
texinfo.texi(,8357) in which each item is marked
texinfo.texi(,8358) by a letter, beginning with that upper case letter.@refill
texinfo.texi(,8359) 
texinfo.texi(,8360) @item
texinfo.texi(,8361) @code{@@enumerate @var{lower-case-letter}}
texinfo.texi(,8362) 
texinfo.texi(,8363) With a lower case letter as argument, start a list
texinfo.texi(,8364) in which each item is marked by
texinfo.texi(,8365) a letter, beginning with that lower case letter.@refill
texinfo.texi(,8366) @end enumerate
texinfo.texi(,8367) 
texinfo.texi(,8368) You can also nest enumerated lists, as in an outline.@refill
texinfo.texi(,8369) 
texinfo.texi(,8370) @node Two-column Tables, Multi-column Tables, enumerate, Lists and Tables
texinfo.texi(,8371) @section Making a Two-column Table
texinfo.texi(,8372) @cindex Tables, making two-column
texinfo.texi(,8373) @findex table
texinfo.texi(,8374) 
texinfo.texi(,8375) @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
texinfo.texi(,8376) @code{@@itemize}}), but allows you to specify a name or heading line for
texinfo.texi(,8377) each item.  The @code{@@table} command is used to produce two-column
texinfo.texi(,8378) tables, and is especially useful for glossaries, explanatory
texinfo.texi(,8379) exhibits, and command-line option summaries.
texinfo.texi(,8380) 
texinfo.texi(,8381) @menu
texinfo.texi(,8382) * table::                       How to construct a two-column table.
texinfo.texi(,8383) * ftable vtable::               Automatic indexing for two-column tables.
texinfo.texi(,8384) * itemx::                       How to put more entries in the first column.
texinfo.texi(,8385) @end menu
texinfo.texi(,8386) 
texinfo.texi(,8387) @node table, ftable vtable, Two-column Tables, Two-column Tables
texinfo.texi(,8389) @subheading Using the @code{@@table} Command
texinfo.texi(,8390) 
texinfo.texi(,8391) Use the @code{@@table} command to produce two-column tables.@refill
texinfo.texi(,8393) 
texinfo.texi(,8394) Write the @code{@@table} command at the beginning of a line and follow
texinfo.texi(,8395) it on the same line with an argument that is a Texinfo ``indicating''
texinfo.texi(,8396) command such as @code{@@code}, @code{@@samp}, @code{@@var}, or
texinfo.texi(,8397) @code{@@kbd} (@pxref{Indicating}).  Although these commands are usually
texinfo.texi(,8398) followed by arguments in braces, in this case you use the command name
texinfo.texi(,8399) without an argument because @code{@@item} will supply the argument.
texinfo.texi(,8400) This command will be applied to the text that goes into the first column
texinfo.texi(,8401) of each item and determines how it will be highlighted.  For example,
texinfo.texi(,8402) @code{@@code} will cause the text in the first column to be highlighted
texinfo.texi(,8403) with an @code{@@code} command.  (We recommend @code{@@code} for
texinfo.texi(,8404) @code{@@table}'s of command-line options.)
texinfo.texi(,8405) 
texinfo.texi(,8406) @findex asis
texinfo.texi(,8407) You may also choose to use the @code{@@asis} command as an argument to
texinfo.texi(,8408) @code{@@table}.  @code{@@asis} is a command that does nothing; if you
texinfo.texi(,8409) use this command after @code{@@table}, @TeX{} and the Info formatting
texinfo.texi(,8410) commands output the first column entries without added highlighting
texinfo.texi(,8411) (``as is'').@refill
texinfo.texi(,8412) 
texinfo.texi(,8413) (The @code{@@table} command may work with other commands besides those
texinfo.texi(,8414) listed here.  However, you can only use commands that normally take
texinfo.texi(,8415) arguments in braces.)@refill
texinfo.texi(,8416) 
texinfo.texi(,8417) @findex item
texinfo.texi(,8418) Begin each table entry with an @code{@@item} command at the beginning
texinfo.texi(,8419) of a line.  Write the first column text on the same line as the
texinfo.texi(,8420) @code{@@item} command.  Write the second column text on the line
texinfo.texi(,8421) following the @code{@@item} line and on subsequent lines.  (You do not
texinfo.texi(,8422) need to type anything for an empty second column entry.)  You may
texinfo.texi(,8423) write as many lines of supporting text as you wish, even several
texinfo.texi(,8424) paragraphs.  But only text on the same line as the @code{@@item} will
texinfo.texi(,8425) be placed in the first column, including any footnote.
texinfo.texi(,8426) 
texinfo.texi(,8427) Normally, you should put a blank line before an @code{@@item} line.
texinfo.texi(,8428) This puts a blank like in the Info file.  Except when the entries are
texinfo.texi(,8429) very brief, a blank line looks better.@refill
texinfo.texi(,8430) 
texinfo.texi(,8431) @need 1500
texinfo.texi(,8432) The following table, for example, highlights the text in the first
texinfo.texi(,8433) column with an @code{@@samp} command:@refill
texinfo.texi(,8434) 
texinfo.texi(,8435) @example
texinfo.texi(,8436) @group
texinfo.texi(,8437) @@table @@samp
texinfo.texi(,8438) @@item foo
texinfo.texi(,8439) This is the text for
texinfo.texi(,8440) @@samp@{foo@}.
texinfo.texi(,8441) 
texinfo.texi(,8442) @@item bar
texinfo.texi(,8443) Text for @@samp@{bar@}.
texinfo.texi(,8444) @@end table
texinfo.texi(,8445) @end group
texinfo.texi(,8446) @end example
texinfo.texi(,8447) 
texinfo.texi(,8448) @noindent
texinfo.texi(,8449) This produces:
texinfo.texi(,8450) 
texinfo.texi(,8451) @table @samp
texinfo.texi(,8452) @item foo
texinfo.texi(,8453) This is the text for
texinfo.texi(,8454) @samp{foo}.
texinfo.texi(,8455) @item bar
texinfo.texi(,8456) Text for @samp{bar}.
texinfo.texi(,8457) @end table
texinfo.texi(,8458) 
texinfo.texi(,8459) If you want to list two or more named items with a single block of
texinfo.texi(,8460) text, use the @code{@@itemx} command.  (@xref{itemx, ,
texinfo.texi(,8461) @code{@@itemx}}.)@refill
texinfo.texi(,8462) 
texinfo.texi(,8463) 
texinfo.texi(,8464) @node ftable vtable
texinfo.texi(,8465) @subsection @code{@@ftable} and @code{@@vtable}
texinfo.texi(,8466) @cindex Tables with indexes
texinfo.texi(,8467) @cindex Indexing table entries automatically
texinfo.texi(,8468) @findex ftable
texinfo.texi(,8469) @findex vtable
texinfo.texi(,8470) 
texinfo.texi(,8471) The @code{@@ftable} and @code{@@vtable} commands are the same as the
texinfo.texi(,8472) @code{@@table} command except that @code{@@ftable} automatically enters
texinfo.texi(,8473) each of the items in the first column of the table into the index of
texinfo.texi(,8474) functions and @code{@@vtable} automatically enters each of the items in
texinfo.texi(,8475) the first column of the table into the index of variables.  This
texinfo.texi(,8476) simplifies the task of creating indices.  Only the items on the same
texinfo.texi(,8477) line as the @code{@@item} commands are indexed, and they are indexed in
texinfo.texi(,8478) exactly the form that they appear on that line.  @xref{Indices},
texinfo.texi(,8479) for more information about indices.@refill
texinfo.texi(,8480) 
texinfo.texi(,8481) Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
texinfo.texi(,8482) writing the @@-command at the beginning of a line, followed on the same
texinfo.texi(,8483) line by an argument that is a Texinfo command such as @code{@@code},
texinfo.texi(,8484) exactly as you would for an @code{@@table} command; and end the table
texinfo.texi(,8485) with an @code{@@end ftable} or @code{@@end vtable} command on a line by
texinfo.texi(,8486) itself.
texinfo.texi(,8487) 
texinfo.texi(,8488) See the example for @code{@@table} in the previous section.
texinfo.texi(,8489) 
texinfo.texi(,8490) @node itemx
texinfo.texi(,8491) @subsection @code{@@itemx}
texinfo.texi(,8492) @cindex Two named items for @code{@@table}
texinfo.texi(,8493) @findex itemx
texinfo.texi(,8494) 
texinfo.texi(,8495) Use the @code{@@itemx} command inside a table when you have two or more
texinfo.texi(,8496) first column entries for the same item, each of which should appear on a
texinfo.texi(,8497) line of its own.  Use @code{@@itemx} for all but the first entry;
texinfo.texi(,8498) @code{@@itemx} should always follow an @code{@@item} command.  The
texinfo.texi(,8499) @code{@@itemx} command works exactly like @code{@@item} except that it
texinfo.texi(,8500) does not generate extra vertical space above the first column text.
texinfo.texi(,8501) 
texinfo.texi(,8502) For example,
texinfo.texi(,8503) 
texinfo.texi(,8504) @example
texinfo.texi(,8505) @group
texinfo.texi(,8506) @@table @@code
texinfo.texi(,8507) @@item upcase
texinfo.texi(,8508) @@itemx downcase
texinfo.texi(,8509) These two functions accept a character or a string as
texinfo.texi(,8510) argument, and return the corresponding upper case (lower
texinfo.texi(,8511) case) character or string.
texinfo.texi(,8512) @@end table
texinfo.texi(,8513) @end group
texinfo.texi(,8514) @end example
texinfo.texi(,8515) 
texinfo.texi(,8516) @noindent
texinfo.texi(,8517) This produces:
texinfo.texi(,8518) 
texinfo.texi(,8519) @table @code
texinfo.texi(,8520) @item upcase
texinfo.texi(,8521) @itemx downcase
texinfo.texi(,8522) These two functions accept a character or a string as
texinfo.texi(,8523) argument, and return the corresponding upper case (lower
texinfo.texi(,8524) case) character or string.@refill
texinfo.texi(,8525) @end table
texinfo.texi(,8526) 
texinfo.texi(,8527) @noindent
texinfo.texi(,8528) (Note also that this example illustrates multi-line supporting text in
texinfo.texi(,8529) a two-column table.)@refill
texinfo.texi(,8530) 
texinfo.texi(,8531) 
texinfo.texi(,8532) @node Multi-column Tables,  , Two-column Tables, Lists and Tables
texinfo.texi(,8533) @section Multi-column Tables
texinfo.texi(,8534) @cindex Tables, making multi-column
texinfo.texi(,8535) @findex multitable
texinfo.texi(,8536) 
texinfo.texi(,8537) @code{@@multitable} allows you to construct tables with any number of
texinfo.texi(,8538) columns, with each column having any width you like.
texinfo.texi(,8539) 
texinfo.texi(,8540) You define the column widths on the @code{@@multitable} line itself, and
texinfo.texi(,8541) write each row of the actual table following an @code{@@item} command,
texinfo.texi(,8542) with columns separated by an @code{@@tab} command.  Finally, @code{@@end
texinfo.texi(,8543) multitable} completes the table.  Details in the sections below.
texinfo.texi(,8544) 
texinfo.texi(,8545) @menu
texinfo.texi(,8546) * Multitable Column Widths::    Defining multitable column widths.
texinfo.texi(,8547) * Multitable Rows::             Defining multitable rows, with examples.
texinfo.texi(,8548) @end menu
texinfo.texi(,8549) 
texinfo.texi(,8550) @node Multitable Column Widths
texinfo.texi(,8551) @subsection Multitable Column Widths
texinfo.texi(,8552) @cindex Multitable column widths
texinfo.texi(,8553) @cindex Column widths, defining for multitables
texinfo.texi(,8554) @cindex Widths, defining multitable column
texinfo.texi(,8555) 
texinfo.texi(,8556) You can define the column widths for a multitable in two ways: as
texinfo.texi(,8557) fractions of the line length; or with a prototype row.  Mixing the two
texinfo.texi(,8558) methods is not supported.  In either case, the widths are defined
texinfo.texi(,8559) entirely on the same line as the @code{@@multitable} command.
texinfo.texi(,8560) 
texinfo.texi(,8561) @enumerate
texinfo.texi(,8562) @item
texinfo.texi(,8563) @findex columnfractions
texinfo.texi(,8564) @cindex Line length, column widths as fraction of
texinfo.texi(,8565) To specify column widths as fractions of the line length, write
texinfo.texi(,8566) @code{@@columnfractions} and the decimal numbers (presumably less than
texinfo.texi(,8567) 1) after the @code{@@multitable} command, as in:
texinfo.texi(,8568) 
texinfo.texi(,8569) @example
texinfo.texi(,8570) @@multitable @@columnfractions .33 .33 .33
texinfo.texi(,8571) @end example
texinfo.texi(,8572) 
texinfo.texi(,8573) @noindent The fractions need not add up exactly to 1.0, as these do
texinfo.texi(,8574) not.  This allows you to produce tables that do not need the full line
texinfo.texi(,8575) length.  You can use a leading zero if you wish.
texinfo.texi(,8576) 
texinfo.texi(,8577) @item
texinfo.texi(,8578) @cindex Prototype row, column widths defined by
texinfo.texi(,8579) To specify a prototype row, write the longest entry for each column
texinfo.texi(,8580) enclosed in braces after the @code{@@multitable} command.  For example:
texinfo.texi(,8581) 
texinfo.texi(,8582) @example
texinfo.texi(,8583) @@multitable @{some text for column one@} @{for column two@}
texinfo.texi(,8584) @end example
texinfo.texi(,8585) 
texinfo.texi(,8586) @noindent
texinfo.texi(,8587) The first column will then have the width of the typeset `some text for
texinfo.texi(,8588) column one', and the second column the width of `for column two'.
texinfo.texi(,8589) 
texinfo.texi(,8590) The prototype entries need not appear in the table itself.
texinfo.texi(,8591) 
texinfo.texi(,8592) Although we used simple text in this example, the prototype entries can
texinfo.texi(,8593) contain Texinfo commands; markup commands such as @code{@@code} are
texinfo.texi(,8594) particularly likely to be useful.
texinfo.texi(,8595) 
texinfo.texi(,8596) @end enumerate
texinfo.texi(,8597) 
texinfo.texi(,8598) 
texinfo.texi(,8599) @node Multitable Rows,  , Multitable Column Widths, Multi-column Tables
texinfo.texi(,8600) @subsection Multitable Rows
texinfo.texi(,8601) @cindex Multitable rows
texinfo.texi(,8602) @cindex Rows, of a multitable
texinfo.texi(,8603) 
texinfo.texi(,8604) @findex item
texinfo.texi(,8605) @findex tab
texinfo.texi(,8606) After the @code{@@multitable} command defining the column widths (see
texinfo.texi(,8607) the previous section), you begin each row in the body of a multitable
texinfo.texi(,8608) with @code{@@item}, and separate the column entries with @code{@@tab}.
texinfo.texi(,8609) Line breaks are not special within the table body, and you may break
texinfo.texi(,8610) input lines in your source file as necessary.
texinfo.texi(,8611) 
texinfo.texi(,8612) Here is a complete example of a multi-column table (the text is from
texinfo.texi(,8613) @cite{The GNU Emacs Manual}, @pxref{Split Window,, Splitting Windows,
texinfo.texi(,8614) emacs, The GNU Emacs Manual}):
texinfo.texi(,8615) 
texinfo.texi(,8616) @example
texinfo.texi(,8617) @@multitable @@columnfractions .15 .45 .4
texinfo.texi(,8618) @@item Key @@tab Command @@tab Description
texinfo.texi(,8619) @@item C-x 2
texinfo.texi(,8620) @@tab @@code@{split-window-vertically@}
texinfo.texi(,8621) @@tab Split the selected window into two windows,
texinfo.texi(,8622) with one above the other.
texinfo.texi(,8623) @@item C-x 3
texinfo.texi(,8624) @@tab @@code@{split-window-horizontally@}
texinfo.texi(,8625) @@tab Split the selected window into two windows
texinfo.texi(,8626) positioned side by side.
texinfo.texi(,8627) @@item C-Mouse-2
texinfo.texi(,8628) @@tab
texinfo.texi(,8629) @@tab In the mode line or scroll bar of a window,
texinfo.texi(,8630) split that window.
texinfo.texi(,8631) @@end multitable
texinfo.texi(,8632) @end example
texinfo.texi(,8633) 
texinfo.texi(,8634) @noindent produces:
texinfo.texi(,8635) 
texinfo.texi(,8636) @multitable @columnfractions .15 .45 .4
texinfo.texi(,8637) @item Key @tab Command @tab Description
texinfo.texi(,8638) @item C-x 2
texinfo.texi(,8639) @tab @code{split-window-vertically}
texinfo.texi(,8640) @tab Split the selected window into two windows,
texinfo.texi(,8641) with one above the other.
texinfo.texi(,8642) @item C-x 3
texinfo.texi(,8643) @tab @code{split-window-horizontally}
texinfo.texi(,8644) @tab Split the selected window into two windows
texinfo.texi(,8645) positioned side by side.
texinfo.texi(,8646) @item C-Mouse-2
texinfo.texi(,8647) @tab
texinfo.texi(,8648) @tab In the mode line or scroll bar of a window,
texinfo.texi(,8649) split that window.
texinfo.texi(,8650) @end multitable
texinfo.texi(,8651) 
texinfo.texi(,8652) 
texinfo.texi(,8653) @node Indices, Insertions, Lists and Tables, Top
texinfo.texi(,8654) @comment node-name,  next,  previous,  up
texinfo.texi(,8655) @chapter Indices
texinfo.texi(,8656) @cindex Indices
texinfo.texi(,8657) 
texinfo.texi(,8658) Using Texinfo, you can generate indices without having to sort and
texinfo.texi(,8659) collate entries manually.  In an index, the entries are listed in
texinfo.texi(,8660) alphabetical order, together with information on how to find the
texinfo.texi(,8661) discussion of each entry.  In a printed manual, this information
texinfo.texi(,8662) consists of page numbers.  In an Info file, this information is a menu
texinfo.texi(,8663) entry leading to the first node referenced.@refill
texinfo.texi(,8664) 
texinfo.texi(,8665) Texinfo provides several predefined kinds of index: an index
texinfo.texi(,8666) for functions, an index for variables, an index for concepts, and so
texinfo.texi(,8667) on.  You can combine indices or use them for other than their
texinfo.texi(,8668) canonical purpose.  If you wish, you can define your own indices.@refill
texinfo.texi(,8669) 
texinfo.texi(,8670) @menu
texinfo.texi(,8671) * Index Entries::               Choose different words for index entries.
texinfo.texi(,8672) * Predefined Indices::          Use different indices for different kinds
texinfo.texi(,8673)                                   of entry.
texinfo.texi(,8674) * Indexing Commands::           How to make an index entry.
texinfo.texi(,8675) * Combining Indices::           How to combine indices.
texinfo.texi(,8676) * New Indices::                 How to define your own indices.
texinfo.texi(,8677) @end menu
texinfo.texi(,8678) 
texinfo.texi(,8679) @node Index Entries, Predefined Indices, Indices, Indices
texinfo.texi(,8680) @comment  node-name,  next,  previous,  up
texinfo.texi(,8681) @section Making Index Entries
texinfo.texi(,8682) @cindex Index entries, making
texinfo.texi(,8683) @cindex Entries, making index
texinfo.texi(,8684) 
texinfo.texi(,8685) When you are making index entries, it is good practice to think of the
texinfo.texi(,8686) different ways people may look for something.  Different people
texinfo.texi(,8687) @emph{do not} think of the same words when they look something up.  A
texinfo.texi(,8688) helpful index will have items indexed under all the different words
texinfo.texi(,8689) that people may use.  For example, one reader may think it obvious that
texinfo.texi(,8690) the two-letter names for indices should be listed under ``Indices,
texinfo.texi(,8691) two-letter names'', since the word ``Index'' is the general concept.
texinfo.texi(,8692) But another reader may remember the specific concept of two-letter
texinfo.texi(,8693) names and search for the entry listed as ``Two letter names for
texinfo.texi(,8694) indices''.  A good index will have both entries and will help both
texinfo.texi(,8695) readers.@refill
texinfo.texi(,8696) 
texinfo.texi(,8697) Like typesetting, the construction of an index is a highly skilled,
texinfo.texi(,8698) professional art, the subtleties of which are not appreciated until you
texinfo.texi(,8699) need to do it yourself.@refill
texinfo.texi(,8700) 
texinfo.texi(,8701) @xref{Printing Indices & Menus}, for information about printing an index
texinfo.texi(,8702) at the end of a book or creating an index menu in an Info file.@refill
texinfo.texi(,8703) 
texinfo.texi(,8704) @node Predefined Indices, Indexing Commands, Index Entries, Indices
texinfo.texi(,8705) @comment  node-name,  next,  previous,  up
texinfo.texi(,8706) @section Predefined Indices
texinfo.texi(,8707) 
texinfo.texi(,8708) Texinfo provides six predefined indices:@refill
texinfo.texi(,8709) 
texinfo.texi(,8710) @itemize @bullet
texinfo.texi(,8711) @item
texinfo.texi(,8712) A @dfn{concept index} listing concepts that are discussed.@refill
texinfo.texi(,8713) 
texinfo.texi(,8714) @item
texinfo.texi(,8715) A @dfn{function index} listing functions (such as entry points of
texinfo.texi(,8716) libraries).@refill
texinfo.texi(,8717) 
texinfo.texi(,8718) @item
texinfo.texi(,8719) A @dfn{variables index} listing variables (such as global variables
texinfo.texi(,8720) of libraries).@refill
texinfo.texi(,8721) 
texinfo.texi(,8722) @item
texinfo.texi(,8723) A @dfn{keystroke index} listing keyboard commands.@refill
texinfo.texi(,8724) 
texinfo.texi(,8725) @item
texinfo.texi(,8726) A @dfn{program index} listing names of programs.@refill
texinfo.texi(,8727) 
texinfo.texi(,8728) @item
texinfo.texi(,8729) A @dfn{data type index} listing data types (such as structures defined in
texinfo.texi(,8730) header files).@refill
texinfo.texi(,8731) @end itemize
texinfo.texi(,8732) 
texinfo.texi(,8733) @noindent
texinfo.texi(,8734) Not every manual needs all of these, and most manuals use two or three
texinfo.texi(,8735) of them.  This manual has two indices: a
texinfo.texi(,8736) concept index and an @@-command index (that is actually the function
texinfo.texi(,8737) index but is called a command index in the chapter heading).  Two or
texinfo.texi(,8738) more indices can be combined into one using the @code{@@synindex} or
texinfo.texi(,8739) @code{@@syncodeindex} commands.  @xref{Combining Indices}.@refill
texinfo.texi(,8740) 
texinfo.texi(,8741) @node Indexing Commands, Combining Indices, Predefined Indices, Indices
texinfo.texi(,8742) @comment  node-name,  next,  previous,  up
texinfo.texi(,8743) @section Defining the Entries of an Index
texinfo.texi(,8744) @cindex Defining indexing entries
texinfo.texi(,8745) @cindex Index entries
texinfo.texi(,8746) @cindex Entries for an index
texinfo.texi(,8747) @cindex Specifying index entries
texinfo.texi(,8748) @cindex Creating index entries
texinfo.texi(,8749) 
texinfo.texi(,8750) The data to make an index come from many individual indexing commands
texinfo.texi(,8751) scattered throughout the Texinfo source file.  Each command says to add
texinfo.texi(,8752) one entry to a particular index; after formatting, the index will give
texinfo.texi(,8753) the current page number or node name as the reference.@refill
texinfo.texi(,8754) 
texinfo.texi(,8755) An index entry consists of an indexing command at the beginning of a
texinfo.texi(,8756) line followed, on the rest of the line, by the entry.@refill
texinfo.texi(,8757) 
texinfo.texi(,8758) For example, this section begins with the following five entries for
texinfo.texi(,8759) the concept index:@refill
texinfo.texi(,8760) 
texinfo.texi(,8761) @example
texinfo.texi(,8762) @@cindex Defining indexing entries
texinfo.texi(,8763) @@cindex Index entries
texinfo.texi(,8764) @@cindex Entries for an index
texinfo.texi(,8765) @@cindex Specifying index entries
texinfo.texi(,8766) @@cindex Creating index entries
texinfo.texi(,8767) @end example
texinfo.texi(,8768) 
texinfo.texi(,8769) Each predefined index has its own indexing command---@code{@@cindex}
texinfo.texi(,8770) for the concept index, @code{@@findex} for the function index, and so
texinfo.texi(,8771) on.@refill
texinfo.texi(,8772) 
texinfo.texi(,8773) @cindex Writing index entries
texinfo.texi(,8774) @cindex Index entry writing
texinfo.texi(,8775) Concept index entries consist of text.  The best way to write an index
texinfo.texi(,8776) is to choose entries that are terse yet clear.  If you can do this,
texinfo.texi(,8777) the index often looks better if the entries are not capitalized, but
texinfo.texi(,8778) written just as they would appear in the middle of a sentence.
texinfo.texi(,8779) (Capitalize proper names and acronyms that always call for upper case
texinfo.texi(,8780) letters.)  This is the case convention we use in most GNU manuals'
texinfo.texi(,8781) indices.
texinfo.texi(,8782) 
texinfo.texi(,8783) If you don't see how to make an entry terse yet clear, make it longer
texinfo.texi(,8784) and clear---not terse and confusing.  If many of the entries are several
texinfo.texi(,8785) words long, the index may look better if you use a different convention:
texinfo.texi(,8786) to capitalize the first word of each entry.  But do not capitalize a
texinfo.texi(,8787) case-sensitive name such as a C or Lisp function name or a shell
texinfo.texi(,8788) command; that would be a spelling error.
texinfo.texi(,8789) 
texinfo.texi(,8790) Whichever case convention you use, please use it consistently!
texinfo.texi(,8791) 
texinfo.texi(,8792) Entries in indices other than the concept index are symbol names in
texinfo.texi(,8793) programming languages, or program names; these names are usually
texinfo.texi(,8794) case-sensitive, so use upper and lower case as required for them.
texinfo.texi(,8795) 
texinfo.texi(,8796) By default, entries for a concept index are printed in a small roman
texinfo.texi(,8797) font and entries for the other indices are printed in a small
texinfo.texi(,8798) @code{@@code} font.  You may change the way part of an entry is
texinfo.texi(,8799) printed with the usual Texinfo commands, such as @code{@@file} for
texinfo.texi(,8800) file names and @code{@@emph} for emphasis (@pxref{Marking
texinfo.texi(,8801) Text}).@refill
texinfo.texi(,8802) @cindex Index font types
texinfo.texi(,8803) 
texinfo.texi(,8804) @cindex Predefined indexing commands
texinfo.texi(,8805) @cindex Indexing commands, predefined
texinfo.texi(,8806) The six indexing commands for predefined indices are:
texinfo.texi(,8807) 
texinfo.texi(,8808) @table @code
texinfo.texi(,8809) @item @@cindex @var{concept}
texinfo.texi(,8810) @findex cindex
texinfo.texi(,8811) Make an entry in the concept index for @var{concept}.@refill
texinfo.texi(,8812) 
texinfo.texi(,8813) @item @@findex @var{function}
texinfo.texi(,8814) @findex findex
texinfo.texi(,8815) Make an entry in the function index for @var{function}.@refill
texinfo.texi(,8816) 
texinfo.texi(,8817) @item @@vindex @var{variable}
texinfo.texi(,8818) @findex vindex
texinfo.texi(,8819) Make an entry in the variable index for @var{variable}.@refill
texinfo.texi(,8820) 
texinfo.texi(,8821) @item @@kindex @var{keystroke}
texinfo.texi(,8822) @findex kindex
texinfo.texi(,8823) Make an entry in the key index for @var{keystroke}.@refill
texinfo.texi(,8824) 
texinfo.texi(,8825) @item @@pindex @var{program}
texinfo.texi(,8826) @findex pindex
texinfo.texi(,8827) Make an entry in the program index for @var{program}.@refill
texinfo.texi(,8828) 
texinfo.texi(,8829) @item @@tindex @var{data type}
texinfo.texi(,8830) @findex tindex
texinfo.texi(,8831) Make an entry in the data type index for @var{data type}.@refill
texinfo.texi(,8832) @end table
texinfo.texi(,8833) 
texinfo.texi(,8834) @quotation
texinfo.texi(,8835) @strong{Caution:} Do not use a colon in an index entry.  In Info, a
texinfo.texi(,8836) colon separates the menu entry name from the node name, so a colon in
texinfo.texi(,8837) the entry itself confuses Info.  @xref{Menu Parts, , The Parts of a
texinfo.texi(,8838) Menu}, for more information about the structure of a menu entry.
texinfo.texi(,8839) @end quotation
texinfo.texi(,8840) 
texinfo.texi(,8841) You are not actually required to use the predefined indices for their
texinfo.texi(,8842) canonical purposes.  For example, suppose you wish to index some C
texinfo.texi(,8843) preprocessor macros.  You could put them in the function index along
texinfo.texi(,8844) with actual functions, just by writing @code{@@findex} commands for
texinfo.texi(,8845) them; then, when you print the ``Function Index'' as an unnumbered
texinfo.texi(,8846) chapter, you could give it the title `Function and Macro Index' and
texinfo.texi(,8847) all will be consistent for the reader.  Or you could put the macros in
texinfo.texi(,8848) with the data types by writing @code{@@tindex} commands for them, and
texinfo.texi(,8849) give that index a suitable title so the reader will understand.
texinfo.texi(,8850) (@xref{Printing Indices & Menus}.)@refill
texinfo.texi(,8851) 
texinfo.texi(,8852) @node Combining Indices, New Indices, Indexing Commands, Indices
texinfo.texi(,8853) @comment node-name,  next,  previous,  up
texinfo.texi(,8854) @section Combining Indices
texinfo.texi(,8855) @cindex Combining indices
texinfo.texi(,8856) @cindex Indices, combining them
texinfo.texi(,8857) 
texinfo.texi(,8858) Sometimes you will want to combine two disparate indices such as functions
texinfo.texi(,8859) and concepts, perhaps because you have few enough of one of them that
texinfo.texi(,8860) a separate index for them would look silly.@refill
texinfo.texi(,8861) 
texinfo.texi(,8862) You could put functions into the concept index by writing
texinfo.texi(,8863) @code{@@cindex} commands for them instead of @code{@@findex} commands,
texinfo.texi(,8864) and produce a consistent manual by printing the concept index with the
texinfo.texi(,8865) title `Function and Concept Index' and not printing the `Function
texinfo.texi(,8866) Index' at all; but this is not a robust procedure.  It works only if
texinfo.texi(,8867) your document is never included as part of another
texinfo.texi(,8868) document that is designed to have a separate function index; if your
texinfo.texi(,8869) document were to be included with such a document, the functions from
texinfo.texi(,8870) your document and those from the other would not end up together.
texinfo.texi(,8871) Also, to make your function names appear in the right font in the
texinfo.texi(,8872) concept index, you would need to enclose every one of them between
texinfo.texi(,8873) the braces of @code{@@code}.@refill
texinfo.texi(,8874) 
texinfo.texi(,8875) @menu
texinfo.texi(,8876) * syncodeindex::                How to merge two indices, using @code{@@code}
texinfo.texi(,8877)                                   font for the merged-from index.
texinfo.texi(,8878) * synindex::                    How to merge two indices, using the
texinfo.texi(,8879)                                   default font of the merged-to index.
texinfo.texi(,8880) @end menu
texinfo.texi(,8881) 
texinfo.texi(,8882) @node syncodeindex
texinfo.texi(,8883) @subsection @code{@@syncodeindex}
texinfo.texi(,8884) @findex syncodeindex
texinfo.texi(,8885) 
texinfo.texi(,8886) When you want to combine functions and concepts into one index, you
texinfo.texi(,8887) should index the functions with @code{@@findex} and index the concepts
texinfo.texi(,8888) with @code{@@cindex}, and use the @code{@@syncodeindex} command to
texinfo.texi(,8889) redirect the function index entries into the concept index.@refill
texinfo.texi(,8890) @findex syncodeindex
texinfo.texi(,8891) 
texinfo.texi(,8892) The @code{@@syncodeindex} command takes two arguments; they are the name
texinfo.texi(,8893) of the index to redirect, and the name of the index to redirect it to.
texinfo.texi(,8894) The template looks like this:@refill
texinfo.texi(,8895) 
texinfo.texi(,8896) @example
texinfo.texi(,8897) @@syncodeindex @var{from} @var{to}
texinfo.texi(,8898) @end example
texinfo.texi(,8899) 
texinfo.texi(,8900) @cindex Predefined names for indices
texinfo.texi(,8901) @cindex Two letter names for indices
texinfo.texi(,8902) @cindex Indices, two letter names
texinfo.texi(,8903) @cindex Names for indices
texinfo.texi(,8904) For this purpose, the indices are given two-letter names:@refill
texinfo.texi(,8905) 
texinfo.texi(,8906) @table @samp
texinfo.texi(,8907) @item cp
texinfo.texi(,8908) concept index
texinfo.texi(,8909) @item fn
texinfo.texi(,8910) function index
texinfo.texi(,8911) @item vr
texinfo.texi(,8912) variable index
texinfo.texi(,8913) @item ky
texinfo.texi(,8914) key index
texinfo.texi(,8915) @item pg
texinfo.texi(,8916) program index
texinfo.texi(,8917) @item tp
texinfo.texi(,8918) data type index
texinfo.texi(,8919) @end table
texinfo.texi(,8920) 
texinfo.texi(,8921) Write an @code{@@syncodeindex} command before or shortly after the
texinfo.texi(,8922) end-of-header line at the beginning of a Texinfo file.  For example,
texinfo.texi(,8923) to merge a function index with a concept index, write the
texinfo.texi(,8924) following:@refill
texinfo.texi(,8925) 
texinfo.texi(,8926) @example
texinfo.texi(,8927) @@syncodeindex fn cp
texinfo.texi(,8928) @end example
texinfo.texi(,8929) 
texinfo.texi(,8930) @noindent
texinfo.texi(,8931) This will cause all entries designated for the function index to merge
texinfo.texi(,8932) in with the concept index instead.@refill
texinfo.texi(,8933) 
texinfo.texi(,8934) To merge both a variables index and a function index into a concept
texinfo.texi(,8935) index, write the following:@refill
texinfo.texi(,8936) 
texinfo.texi(,8937) @example
texinfo.texi(,8938) @group
texinfo.texi(,8939) @@syncodeindex vr cp
texinfo.texi(,8940) @@syncodeindex fn cp
texinfo.texi(,8941) @end group
texinfo.texi(,8942) @end example
texinfo.texi(,8943) 
texinfo.texi(,8944) @cindex Fonts for indices
texinfo.texi(,8945) The @code{@@syncodeindex} command puts all the entries from the `from'
texinfo.texi(,8946) index (the redirected index) into the @code{@@code} font, overriding
texinfo.texi(,8947) whatever default font is used by the index to which the entries are
texinfo.texi(,8948) now directed.  This way, if you direct function names from a function
texinfo.texi(,8949) index into a concept index, all the function names are printed in the
texinfo.texi(,8950) @code{@@code} font as you would expect.@refill
texinfo.texi(,8951) 
texinfo.texi(,8952) @node synindex,  , syncodeindex, Combining Indices
texinfo.texi(,8953) @subsection @code{@@synindex}
texinfo.texi(,8954) @findex synindex
texinfo.texi(,8955) 
texinfo.texi(,8956) The @code{@@synindex} command is nearly the same as the
texinfo.texi(,8957) @code{@@syncodeindex} command, except that it does not put the
texinfo.texi(,8958) `from' index  entries into the @code{@@code} font; rather it puts
texinfo.texi(,8959) them in the roman font.  Thus, you use @code{@@synindex} when you
texinfo.texi(,8960) merge a concept index into a function index.@refill
texinfo.texi(,8961) 
texinfo.texi(,8962) @xref{Printing Indices & Menus}, for information about printing an index
texinfo.texi(,8963) at the end of a book or creating an index menu in an Info file.@refill
texinfo.texi(,8964) 
texinfo.texi(,8965) @node New Indices,  , Combining Indices, Indices
texinfo.texi(,8966) @section Defining New Indices
texinfo.texi(,8967) @cindex Defining new indices
texinfo.texi(,8968) @cindex Indices, defining new
texinfo.texi(,8969) @cindex New index defining
texinfo.texi(,8970) @findex defindex
texinfo.texi(,8971) @findex defcodeindex
texinfo.texi(,8972) 
texinfo.texi(,8973) In addition to the predefined indices, you may use the
texinfo.texi(,8974) @code{@@defindex} and @code{@@defcodeindex} commands to define new
texinfo.texi(,8975) indices.  These commands create new indexing @@-commands with which
texinfo.texi(,8976) you mark index entries.  The @code{@@defindex }command is used like
texinfo.texi(,8977) this:@refill
texinfo.texi(,8978) 
texinfo.texi(,8979) @example
texinfo.texi(,8980) @@defindex @var{name}
texinfo.texi(,8981) @end example
texinfo.texi(,8982) 
texinfo.texi(,8983) The name of an index should be a two letter word, such as @samp{au}.
texinfo.texi(,8984) For example:@refill
texinfo.texi(,8985) 
texinfo.texi(,8986) @example
texinfo.texi(,8987) @@defindex au
texinfo.texi(,8988) @end example
texinfo.texi(,8989) 
texinfo.texi(,8990) This defines a new index, called the @samp{au} index.  At the same
texinfo.texi(,8991) time, it creates a new indexing command, @code{@@auindex}, that you
texinfo.texi(,8992) can use to make index entries.  Use the new indexing command just as
texinfo.texi(,8993) you would use a predefined indexing command.@refill
texinfo.texi(,8994) 
texinfo.texi(,8995) For example, here is a section heading followed by a concept index
texinfo.texi(,8996) entry and two @samp{au} index entries.@refill
texinfo.texi(,8997) 
texinfo.texi(,8998) @example
texinfo.texi(,8999) @@section Cognitive Semantics
texinfo.texi(,9000) @@cindex kinesthetic image schemas
texinfo.texi(,9001) @@auindex Johnson, Mark
texinfo.texi(,9002) @@auindex Lakoff, George
texinfo.texi(,9003) @end example
texinfo.texi(,9004) 
texinfo.texi(,9005) @noindent
texinfo.texi(,9006) (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
texinfo.texi(,9007) Texinfo constructs the new indexing command by concatenating the name
texinfo.texi(,9008) of the index with @samp{index}; thus, defining an @samp{au} index
texinfo.texi(,9009) leads to the automatic creation of an @code{@@auindex} command.@refill
texinfo.texi(,9010) 
texinfo.texi(,9011) Use the @code{@@printindex} command to print the index, as you do with
texinfo.texi(,9012) the predefined indices.  For example:@refill
texinfo.texi(,9013) 
texinfo.texi(,9014) @example
texinfo.texi(,9015) @group
texinfo.texi(,9016) @@node Author Index, Subject Index, , Top
texinfo.texi(,9017) @@unnumbered Author Index
texinfo.texi(,9018) 
texinfo.texi(,9019) @@printindex au
texinfo.texi(,9020) @end group
texinfo.texi(,9021) @end example
texinfo.texi(,9022) 
texinfo.texi(,9023) The @code{@@defcodeindex} is like the @code{@@defindex} command, except
texinfo.texi(,9024) that, in the printed output, it prints entries in an @code{@@code} font
texinfo.texi(,9025) instead of a roman font.  Thus, it parallels the @code{@@findex} command
texinfo.texi(,9026) rather than the @code{@@cindex} command.@refill
texinfo.texi(,9027) 
texinfo.texi(,9028) You should define new indices within or right after the end-of-header
texinfo.texi(,9029) line of a Texinfo file, before any @code{@@synindex} or
texinfo.texi(,9030) @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
texinfo.texi(,9031) 
texinfo.texi(,9032) 
texinfo.texi(,9033) @node Insertions
texinfo.texi(,9034) @chapter Special Insertions
texinfo.texi(,9035) @cindex Inserting special characters and symbols
texinfo.texi(,9036) @cindex Special insertions
texinfo.texi(,9037) 
texinfo.texi(,9038) Texinfo provides several commands for inserting characters that have
texinfo.texi(,9039) special meaning in Texinfo, such as braces, and for other graphic
texinfo.texi(,9040) elements that do not correspond to simple characters you can type.
texinfo.texi(,9041) 
texinfo.texi(,9059) 
texinfo.texi(,9060) @menu
texinfo.texi(,9061) * Braces Atsigns::              How to insert braces, @samp{@@}.
texinfo.texi(,9062) * Inserting Space::             How to insert the right amount of space
texinfo.texi(,9063)                                   within a sentence.
texinfo.texi(,9064) * Inserting Accents::           How to insert accents and special characters.
texinfo.texi(,9065) * Dots Bullets::                How to insert dots and bullets.
texinfo.texi(,9066) * TeX and copyright::           How to insert the @TeX{} logo
texinfo.texi(,9067)                                   and the copyright symbol.
texinfo.texi(,9068) * pounds::                      How to insert the pounds currency symbol.
texinfo.texi(,9069) * minus::                       How to insert a minus sign.
texinfo.texi(,9070) * math::                        How to format a mathematical expression.
texinfo.texi(,9071) * Glyphs::                      How to indicate results of evaluation,
texinfo.texi(,9072)                                   expansion of macros, errors, etc.
texinfo.texi(,9073) * Footnotes::                   How to include footnotes.
texinfo.texi(,9074) * Images::                      How to include graphics.
texinfo.texi(,9075) @end menu
texinfo.texi(,9076) 
texinfo.texi(,9077) 
texinfo.texi(,9078) @node Braces Atsigns, Inserting Space, Insertions, Insertions
texinfo.texi(,9079) @section Inserting @@ and Braces
texinfo.texi(,9080) @cindex Inserting @@, braces
texinfo.texi(,9081) @cindex Braces, inserting
texinfo.texi(,9082) @cindex Special characters, commands to insert
texinfo.texi(,9083) @cindex Commands to insert special characters
texinfo.texi(,9084) 
texinfo.texi(,9085) @samp{@@} and curly braces are special characters in Texinfo.  To insert
texinfo.texi(,9086) these characters so they appear in text, you must put an @samp{@@} in
texinfo.texi(,9087) front of these characters to prevent Texinfo from misinterpreting
texinfo.texi(,9088) them.
texinfo.texi(,9089) 
texinfo.texi(,9090) Do not put braces after any of these commands; they are not
texinfo.texi(,9091) necessary.
texinfo.texi(,9092) 
texinfo.texi(,9093) @menu
texinfo.texi(,9094) * Inserting An Atsign::         How to insert @samp{@@}.
texinfo.texi(,9095) * Inserting Braces::            How to insert @samp{@{} and @samp{@}}.
texinfo.texi(,9096) @end menu
texinfo.texi(,9097) 
texinfo.texi(,9098) @node Inserting An Atsign, Inserting Braces, Braces Atsigns, Braces Atsigns
texinfo.texi(,9099) @subsection Inserting @samp{@@} with @@@@
texinfo.texi(,9100) @findex @@ @r{(literal @samp{@@})}
texinfo.texi(,9101) 
texinfo.texi(,9102) @code{@@@@} stands for a single @samp{@@} in either printed or Info
texinfo.texi(,9103) output.
texinfo.texi(,9104) 
texinfo.texi(,9105) Do not put braces after an @code{@@@@} command.
texinfo.texi(,9106) 
texinfo.texi(,9107) 
texinfo.texi(,9108) @node Inserting Braces
texinfo.texi(,9109) @subsection Inserting @samp{@{} and @samp{@}}with @@@{ and @@@}
texinfo.texi(,9110) @findex @{ @r{(literal @samp{@{})}
texinfo.texi(,9111) @findex @} @r{(literal @samp{@}})}
texinfo.texi(,9112) 
texinfo.texi(,9113) @code{@@@{} stands for a single @samp{@{} in either printed or Info
texinfo.texi(,9114) output.
texinfo.texi(,9115) 
texinfo.texi(,9116) @code{@@@}} stands for a single @samp{@}} in either printed or Info
texinfo.texi(,9117) output.
texinfo.texi(,9118) 
texinfo.texi(,9119) Do not put braces after either an @code{@@@{} or an @code{@@@}}
texinfo.texi(,9120) command.
texinfo.texi(,9121) 
texinfo.texi(,9122) 
texinfo.texi(,9123) @node Inserting Space
texinfo.texi(,9124) @section Inserting Space
texinfo.texi(,9125) 
texinfo.texi(,9126) @cindex Inserting space
texinfo.texi(,9127) @cindex Spacing, inserting
texinfo.texi(,9128) The following sections describe commands that control spacing of various
texinfo.texi(,9129) kinds within and after sentences.
texinfo.texi(,9130) 
texinfo.texi(,9131) @menu
texinfo.texi(,9132) * Not Ending a Sentence::       Sometimes a . doesn't end a sentence.
texinfo.texi(,9133) * Ending a Sentence::           Sometimes it does.
texinfo.texi(,9134) * Multiple Spaces::             Inserting multiple spaces.
texinfo.texi(,9135) * dmn::                         How to format a dimension.
texinfo.texi(,9136) @end menu
texinfo.texi(,9137) 
texinfo.texi(,9138) 
texinfo.texi(,9139) @node Not Ending a Sentence
texinfo.texi(,9140) @subsection Not Ending a Sentence
texinfo.texi(,9141) 
texinfo.texi(,9142) @cindex Not ending a sentence
texinfo.texi(,9143) @cindex Sentence non-ending punctuation
texinfo.texi(,9144) @cindex Periods, inserting
texinfo.texi(,9145) Depending on whether a period or exclamation point or question mark is
texinfo.texi(,9146) inside or at the end of a sentence, less or more space is inserted after
texinfo.texi(,9147) a period in a typeset manual.  Since it is not always possible
texinfo.texi(,9148) to determine when a period ends a sentence and when it is used
texinfo.texi(,9149) in an abbreviation, special commands are needed in some circumstances.
texinfo.texi(,9150) Usually, Texinfo can guess how to handle periods, so you do not need to
texinfo.texi(,9151) use the special commands; you just enter a period as you would if you
texinfo.texi(,9152) were using a typewriter, which means you put two spaces after the
texinfo.texi(,9153) period, question mark, or exclamation mark that ends a sentence.
texinfo.texi(,9154) 
texinfo.texi(,9155) @findex <colon> @r{(suppress widening)}
texinfo.texi(,9156) Use the @code{@@:}@: command after a period, question mark,
texinfo.texi(,9157) exclamation mark, or colon that should not be followed by extra space.
texinfo.texi(,9158) For example, use @code{@@:}@: after periods that end abbreviations
texinfo.texi(,9159) which are not at the ends of sentences.
texinfo.texi(,9160) 
texinfo.texi(,9161) For example,
texinfo.texi(,9162) 
texinfo.texi(,9163) @example
texinfo.texi(,9164) The s.o.p.@@: has three parts @dots{}
texinfo.texi(,9165) The s.o.p. has three parts @dots{}
texinfo.texi(,9166) @end example
texinfo.texi(,9167) 
texinfo.texi(,9168) @noindent
texinfo.texi(,9170) produces
texinfo.texi(,9177) 
texinfo.texi(,9178) @quotation
texinfo.texi(,9179) The s.o.p.@: has three parts @dots{}@*
texinfo.texi(,9180) The s.o.p. has three parts @dots{}
texinfo.texi(,9181) @end quotation
texinfo.texi(,9182) 
texinfo.texi(,9183) @noindent
texinfo.texi(,9184) (Incidentally, @samp{s.o.p.} is an abbreviation for ``Standard Operating
texinfo.texi(,9185) Procedure''.)
texinfo.texi(,9186) 
texinfo.texi(,9187) @code{@@:} has no effect on the Info output.  Do not put braces after
texinfo.texi(,9188) @code{@@:}.
texinfo.texi(,9189) 
texinfo.texi(,9190) 
texinfo.texi(,9191) @node Ending a Sentence, Multiple Spaces, Not Ending a Sentence, Inserting Space
texinfo.texi(,9192) @subsection Ending a Sentence
texinfo.texi(,9193) 
texinfo.texi(,9194) @cindex Ending a Sentence
texinfo.texi(,9195) @cindex Sentence ending punctuation
texinfo.texi(,9196) 
texinfo.texi(,9197) @findex .  @r{(end of sentence)}
texinfo.texi(,9198) @findex ! @r{(end of sentence)}
texinfo.texi(,9199) @findex ? @r{(end of sentence)}
texinfo.texi(,9200) Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
texinfo.texi(,9201) exclamation point, and @code{@@?}@: instead of a question mark at the end
texinfo.texi(,9202) of a sentence that ends with a single capital letter.  Otherwise, @TeX{}
texinfo.texi(,9203) will think the letter is an abbreviation and will not insert the correct
texinfo.texi(,9204) end-of-sentence spacing.  Here is an example:
texinfo.texi(,9205) 
texinfo.texi(,9206) @example
texinfo.texi(,9207) Give it to M.I.B. and to M.E.W@@.  Also, give it to R.J.C@@.
texinfo.texi(,9208) Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
texinfo.texi(,9209) @end example
texinfo.texi(,9210) 
texinfo.texi(,9211) @noindent
texinfo.texi(,9213) produces
texinfo.texi(,9220) 
texinfo.texi(,9221) @quotation
texinfo.texi(,9222) Give it to M.I.B. and to M.E.W@.  Also, give it to R.J.C@.@*
texinfo.texi(,9223) Give it to M.I.B. and to M.E.W.  Also, give it to R.J.C.
texinfo.texi(,9224) @end quotation
texinfo.texi(,9225) 
texinfo.texi(,9226) In the Info file output, @code{@@.}@: is equivalent to a simple
texinfo.texi(,9227) @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
texinfo.texi(,9228) 
texinfo.texi(,9229) The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
texinfo.texi(,9230) work well with the Emacs sentence motion commands (@pxref{Sentences,,,
texinfo.texi(,9231) emacs, The GNU Emacs Manual}).
texinfo.texi(,9232) 
texinfo.texi(,9233) Do not put braces after any of these commands.
texinfo.texi(,9234) 
texinfo.texi(,9235) 
texinfo.texi(,9236) @node Multiple Spaces, dmn, Ending a Sentence, Inserting Space
texinfo.texi(,9237) @subsection Multiple Spaces
texinfo.texi(,9238) 
texinfo.texi(,9239) @cindex Multiple spaces
texinfo.texi(,9240) @cindex Whitespace, inserting
texinfo.texi(,9241) @cindex Space, inserting horizontal
texinfo.texi(,9242) @findex (space)
texinfo.texi(,9243) @findex (tab)
texinfo.texi(,9244) @findex (newline)
texinfo.texi(,9245) 
texinfo.texi(,9246) Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
texinfo.texi(,9247) and newline) into a single space.  Info output, on the other hand,
texinfo.texi(,9248) preserves whitespace as you type it, except for changing a newline into
texinfo.texi(,9249) a space; this is why it is important to put two spaces at the end of
texinfo.texi(,9250) sentences in Texinfo documents.
texinfo.texi(,9251) 
texinfo.texi(,9252) Occasionally, you may want to actually insert several consecutive
texinfo.texi(,9253) spaces, either for purposes of example (what your program does with
texinfo.texi(,9254) multiple spaces as input), or merely for purposes of appearance in
texinfo.texi(,9255) headings or lists.  Texinfo supports three commands:
texinfo.texi(,9256) @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
texinfo.texi(,9257) which insert a single space into the output.  (Here,
texinfo.texi(,9258) @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
texinfo.texi(,9259) space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
texinfo.texi(,9260) character and end-of-line, i.e., when @samp{@@} is the last character on
texinfo.texi(,9261) a line.)
texinfo.texi(,9262) 
texinfo.texi(,9263) For example,
texinfo.texi(,9264) @example
texinfo.texi(,9265) Spacey@@ @@ @@ @@
texinfo.texi(,9266) example.
texinfo.texi(,9267) @end example
texinfo.texi(,9268) 
texinfo.texi(,9269) @noindent produces
texinfo.texi(,9270) 
texinfo.texi(,9271) @example
texinfo.texi(,9272) Spacey@ @ @ @
texinfo.texi(,9273) example.
texinfo.texi(,9274) @end example
texinfo.texi(,9275) 
texinfo.texi(,9276) Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
texinfo.texi(,9277) @code{@@multitable} (@pxref{Multi-column Tables}).
texinfo.texi(,9278) 
texinfo.texi(,9279) Do not follow any of these commands with braces.
texinfo.texi(,9280) 
texinfo.texi(,9281) To produce a non-breakable space, see @ref{w, non-breakable space}.
texinfo.texi(,9282) 
texinfo.texi(,9283) 
texinfo.texi(,9284) @node dmn
texinfo.texi(,9285) @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
texinfo.texi(,9286) @cindex Thin space between number, dimension
texinfo.texi(,9287) @cindex Dimension formatting
texinfo.texi(,9288) @cindex Format a dimension
texinfo.texi(,9289) @findex dmn
texinfo.texi(,9290) 
texinfo.texi(,9291) At times, you may want to write @samp{12@dmn{pt}} or
texinfo.texi(,9292) @samp{8.5@dmn{in}} with little or no space between the number and the
texinfo.texi(,9293) abbreviation for the dimension.  You can use the @code{@@dmn} command
texinfo.texi(,9294) to do this.  On seeing the command, @TeX{} inserts just enough space
texinfo.texi(,9295) for proper typesetting; the Info formatting commands insert no space
texinfo.texi(,9296) at all, since the Info file does not require it.
texinfo.texi(,9297) 
texinfo.texi(,9298) To use the @code{@@dmn} command, write the number and then follow it
texinfo.texi(,9299) immediately, with no intervening space, by @code{@@dmn}, and then by
texinfo.texi(,9300) the dimension within braces.  For example,
texinfo.texi(,9301) 
texinfo.texi(,9302) @example
texinfo.texi(,9303) A4 paper is 8.27@@dmn@{in@} wide.
texinfo.texi(,9304) @end example
texinfo.texi(,9305) 
texinfo.texi(,9306) @noindent
texinfo.texi(,9307) produces
texinfo.texi(,9308) 
texinfo.texi(,9309) @quotation
texinfo.texi(,9310) A4 paper is 8.27@dmn{in} wide.
texinfo.texi(,9311) @end quotation
texinfo.texi(,9312) 
texinfo.texi(,9313) Not everyone uses this style.  Some people prefer @w{@samp{8.27 in.@@:}}
texinfo.texi(,9314) or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
texinfo.texi(,9315) In these cases, however, the formatters may insert a line break between
texinfo.texi(,9316) the number and the dimension, so use @code{@@w} (@pxref{w}).  Also, if
texinfo.texi(,9317) you write a period after an abbreviation within a sentence, you should
texinfo.texi(,9318) write @samp{@@:} after the period to prevent @TeX{} from inserting extra
texinfo.texi(,9319) whitespace, as shown here.  @xref{Not Ending a Sentence}.
texinfo.texi(,9320) 
texinfo.texi(,9321) 
texinfo.texi(,9322) @node Inserting Accents
texinfo.texi(,9323) @section Inserting Accents
texinfo.texi(,9324) 
texinfo.texi(,9325) @cindex Inserting accents
texinfo.texi(,9326) @cindex Accents, inserting
texinfo.texi(,9327) @cindex Floating accents, inserting
texinfo.texi(,9328) 
texinfo.texi(,9329) Here is a table with the commands Texinfo provides for inserting
texinfo.texi(,9330) floating accents.  The commands with non-alphabetic names do not take
texinfo.texi(,9331) braces around their argument (which is taken to be the next character).
texinfo.texi(,9332) (Exception: @code{@@,} @emph{does} take braces around its argument.)
texinfo.texi(,9333) This is so as to make the source as convenient to type and read as
texinfo.texi(,9334) possible, since accented characters are very common in some languages.
texinfo.texi(,9335) 
texinfo.texi(,9336) @findex " @r{(umlaut accent)}
texinfo.texi(,9337) @cindex Umlaut accent
texinfo.texi(,9338) @findex ' @r{(umlaut accent)}
texinfo.texi(,9339) @cindex Acute accent
texinfo.texi(,9340) @findex = @r{(macron accent)}
texinfo.texi(,9341) @cindex Macron accent
texinfo.texi(,9342) @findex ^ @r{(circumflex accent)}
texinfo.texi(,9343) @cindex Circumflex accent
texinfo.texi(,9344) @findex ` @r{(grave accent)}
texinfo.texi(,9345) @cindex Grave accent
texinfo.texi(,9346) @findex ~ @r{(tilde accent)}
texinfo.texi(,9347) @cindex Tilde accent
texinfo.texi(,9348) @findex , @r{(cedilla accent)}
texinfo.texi(,9349) @cindex Cedilla accent
texinfo.texi(,9350) @findex dotaccent
texinfo.texi(,9351) @cindex Dot accent
texinfo.texi(,9352) @findex H @r{(Hungarian umlaut accent)}
texinfo.texi(,9353) @cindex Hungarian umlaut accent
texinfo.texi(,9354) @findex ringaccent
texinfo.texi(,9355) @cindex Ring accent
texinfo.texi(,9356) @findex tieaccent
texinfo.texi(,9357) @cindex Tie-after accent
texinfo.texi(,9358) @findex u @r{(breve accent)}
texinfo.texi(,9359) @cindex Breve accent
texinfo.texi(,9360) @findex ubaraccent
texinfo.texi(,9361) @cindex Underbar accent
texinfo.texi(,9362) @findex udotaccent
texinfo.texi(,9363) @cindex Underdot accent
texinfo.texi(,9364) @findex v @r{(check accent)}
texinfo.texi(,9365) @cindex Check accent
texinfo.texi(,9366) @multitable {@@questiondown@{@}} {Output} {macron/overbar accent}
texinfo.texi(,9367) @item Command               @tab Output         @tab What
texinfo.texi(,9368) @item @t{@@"o}              @tab @"o            @tab umlaut accent
texinfo.texi(,9369) @item @t{@@'o}              @tab @'o            @tab acute accent
texinfo.texi(,9370) @item @t{@@,@{c@}}          @tab @,{c}          @tab cedilla accent
texinfo.texi(,9371) @item @t{@@=o}              @tab @=o            @tab macron/overbar accent
texinfo.texi(,9372) @item @t{@@^o}              @tab @^o            @tab circumflex accent
texinfo.texi(,9373) @item @t{@@`o}              @tab @`o            @tab grave accent
texinfo.texi(,9374) @item @t{@@~o}              @tab @~o            @tab tilde accent
texinfo.texi(,9375) @item @t{@@dotaccent@{o@}}  @tab @dotaccent{o}  @tab overdot accent
texinfo.texi(,9376) @item @t{@@H@{o@}}          @tab @H{o}          @tab long Hungarian umlaut
texinfo.texi(,9377) @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
texinfo.texi(,9378) @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
texinfo.texi(,9379) @item @t{@@u@{o@}}          @tab @u{o}          @tab breve accent
texinfo.texi(,9380) @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
texinfo.texi(,9381) @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
texinfo.texi(,9382) @item @t{@@v@{o@}}          @tab @v{o}          @tab hacek or check accent
texinfo.texi(,9383) @end multitable
texinfo.texi(,9384) 
texinfo.texi(,9385) This table lists the Texinfo commands for inserting other characters
texinfo.texi(,9386) commonly used in languages other than English.
texinfo.texi(,9387) 
texinfo.texi(,9388) @findex questiondown
texinfo.texi(,9389) @cindex @questiondown{}
texinfo.texi(,9390) @findex exclamdown
texinfo.texi(,9391) @cindex @exclamdown{}
texinfo.texi(,9392) @findex aa
texinfo.texi(,9393) @cindex @aa{}
texinfo.texi(,9394) @findex AA
texinfo.texi(,9395) @cindex @AA{}
texinfo.texi(,9396) @findex ae
texinfo.texi(,9397) @cindex @ae{}
texinfo.texi(,9398) @findex AE
texinfo.texi(,9399) @cindex @AE{}
texinfo.texi(,9400) @findex dotless
texinfo.texi(,9401) @cindex @dotless{i}
texinfo.texi(,9402) @cindex @dotless{j}
texinfo.texi(,9403) @cindex Dotless i, j
texinfo.texi(,9404) @findex l
texinfo.texi(,9405) @cindex @l{}
texinfo.texi(,9406) @findex L
texinfo.texi(,9407) @cindex @L{}
texinfo.texi(,9408) @findex o
texinfo.texi(,9409) @cindex @o{}
texinfo.texi(,9410) @findex O
texinfo.texi(,9411) @cindex @O{}
texinfo.texi(,9412) @findex oe
texinfo.texi(,9413) @cindex @oe{}
texinfo.texi(,9414) @findex OE
texinfo.texi(,9415) @cindex @OE{}
texinfo.texi(,9416) @findex ss
texinfo.texi(,9417) @cindex @ss{}
texinfo.texi(,9418) @cindex Es-zet
texinfo.texi(,9419) @cindex Sharp S
texinfo.texi(,9420) @cindex German S
texinfo.texi(,9421) @multitable {x@@questiondown@{@}} {oe,OE} {es-zet or sharp S}
texinfo.texi(,9422) @item @t{@@exclamdown@{@}}   @tab @exclamdown{}   @tab upside-down !
texinfo.texi(,9423) @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
texinfo.texi(,9424) @item @t{@@aa@{@},@@AA@{@}}  @tab @aa{},@AA{}     @tab a,A with circle
texinfo.texi(,9425) @item @t{@@ae@{@},@@AE@{@}}  @tab @ae{},@AE{}     @tab ae,AE ligatures
texinfo.texi(,9426) @item @t{@@dotless@{i@}}     @tab @dotless{i}     @tab dotless i
texinfo.texi(,9427) @item @t{@@dotless@{j@}}     @tab @dotless{j}     @tab dotless j
texinfo.texi(,9428) @item @t{@@l@{@},@@L@{@}}    @tab @l{},@L{}       @tab suppressed-L,l
texinfo.texi(,9429) @item @t{@@o@{@},@@O@{@}}    @tab @o{},@O{}       @tab O,o with slash
texinfo.texi(,9430) @item @t{@@oe@{@},@@OE@{@}}  @tab @oe{},@OE{}     @tab oe,OE ligatures
texinfo.texi(,9431) @item @t{@@ss@{@}}           @tab @ss{}           @tab es-zet or sharp S
texinfo.texi(,9432) @end multitable
texinfo.texi(,9433) 
texinfo.texi(,9434) 
texinfo.texi(,9435) @node Dots Bullets
texinfo.texi(,9436) @section Inserting Ellipsis and Bullets
texinfo.texi(,9437) @cindex Dots, inserting
texinfo.texi(,9438) @cindex Bullets, inserting
texinfo.texi(,9439) @cindex Ellipsis, inserting
texinfo.texi(,9440) @cindex Inserting ellipsis
texinfo.texi(,9441) @cindex Inserting dots
texinfo.texi(,9442) @cindex Special typesetting commands
texinfo.texi(,9443) @cindex Typesetting commands for dots, etc.
texinfo.texi(,9444) 
texinfo.texi(,9445) An @dfn{ellipsis} (a line of dots) is not typeset as a string of
texinfo.texi(,9446) periods, so a special command is used for ellipsis in Texinfo.  The
texinfo.texi(,9447) @code{@@bullet} command is special, too.  Each of these commands is
texinfo.texi(,9448) followed by a pair of braces, @samp{@{@}}, without any whitespace
texinfo.texi(,9449) between the name of the command and the braces.  (You need to use braces
texinfo.texi(,9450) with these commands because you can use them next to other text; without
texinfo.texi(,9451) the braces, the formatters would be confused.  @xref{Command Syntax, ,
texinfo.texi(,9452) @@-Command Syntax}, for further information.)@refill
texinfo.texi(,9453) 
texinfo.texi(,9454) @menu
texinfo.texi(,9455) * dots::                        How to insert dots @dots{}
texinfo.texi(,9456) * bullet::                      How to insert a bullet.
texinfo.texi(,9457) @end menu
texinfo.texi(,9458) 
texinfo.texi(,9459) 
texinfo.texi(,9460) @node dots
texinfo.texi(,9461) @subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
texinfo.texi(,9462) @findex dots
texinfo.texi(,9463) @findex enddots
texinfo.texi(,9464) @cindex Inserting dots
texinfo.texi(,9465) @cindex Dots, inserting
texinfo.texi(,9466) 
texinfo.texi(,9467) Use the @code{@@dots@{@}} command to generate an ellipsis, which is
texinfo.texi(,9468) three dots in a row, appropriately spaced, like this: `@dots{}'.  Do
texinfo.texi(,9469) not simply write three periods in the input file; that would work for
texinfo.texi(,9470) the Info file output, but would produce the wrong amount of space
texinfo.texi(,9471) between the periods in the printed manual.
texinfo.texi(,9472) 
texinfo.texi(,9473) Similarly, the @code{@@enddots@{@}} command generates an
texinfo.texi(,9474) end-of-sentence ellipsis (four dots) @enddots{}
texinfo.texi(,9475) 
texinfo.texi(,9483) 
texinfo.texi(,9484) 
texinfo.texi(,9485) @node bullet
texinfo.texi(,9486) @subsection @code{@@bullet}@{@} (@bullet{})
texinfo.texi(,9487) @findex bullet
texinfo.texi(,9488) 
texinfo.texi(,9489) Use the @code{@@bullet@{@}} command to generate a large round dot, or
texinfo.texi(,9490) the closest possible thing to one.  In Info, an asterisk is used.@refill
texinfo.texi(,9491) 
texinfo.texi(,9492) Here is a bullet: @bullet{}
texinfo.texi(,9493) 
texinfo.texi(,9494) When you use @code{@@bullet} in @code{@@itemize}, you do not need to
texinfo.texi(,9495) type the braces, because @code{@@itemize} supplies them.
texinfo.texi(,9496) (@xref{itemize, , @code{@@itemize}}.)@refill
texinfo.texi(,9497) 
texinfo.texi(,9498) 
texinfo.texi(,9499) @node TeX and copyright, pounds, Dots Bullets, Insertions
texinfo.texi(,9500) @section Inserting @TeX{} and the Copyright Symbol
texinfo.texi(,9501) 
texinfo.texi(,9502) The logo `@TeX{}' is typeset in a special fashion and it needs an
texinfo.texi(,9503) @@-command.  The copyright symbol, `@copyright{}', is also special.
texinfo.texi(,9504) Each of these commands is followed by a pair of braces, @samp{@{@}},
texinfo.texi(,9505) without any whitespace between the name of the command and the
texinfo.texi(,9506) braces.@refill
texinfo.texi(,9507) 
texinfo.texi(,9508) @menu
texinfo.texi(,9509) * tex::                         How to insert the @TeX{} logo.
texinfo.texi(,9510) * copyright symbol::            How to use @code{@@copyright}@{@}.
texinfo.texi(,9511) @end menu
texinfo.texi(,9512) 
texinfo.texi(,9513) 
texinfo.texi(,9514) @node tex
texinfo.texi(,9515) @subsection @code{@@TeX}@{@} (@TeX{})
texinfo.texi(,9516) @findex tex (command)
texinfo.texi(,9517) 
texinfo.texi(,9518) Use the @code{@@TeX@{@}} command to generate `@TeX{}'.  In a printed
texinfo.texi(,9519) manual, this is a special logo that is different from three ordinary
texinfo.texi(,9520) letters.  In Info, it just looks like @samp{TeX}.  The
texinfo.texi(,9521) @code{@@TeX@{@}} command is unique among Texinfo commands in that the
texinfo.texi(,9522) @samp{T} and the @samp{X} are in upper case.@refill
texinfo.texi(,9523) 
texinfo.texi(,9524) 
texinfo.texi(,9525) @node copyright symbol
texinfo.texi(,9526) @subsection @code{@@copyright}@{@} (@copyright{})
texinfo.texi(,9527) @findex copyright
texinfo.texi(,9528) 
texinfo.texi(,9529) Use the @code{@@copyright@{@}} command to generate `@copyright{}'.  In
texinfo.texi(,9530) a printed manual, this is a @samp{c} inside a circle, and in Info,
texinfo.texi(,9531) this is @samp{(C)}.@refill
texinfo.texi(,9532) 
texinfo.texi(,9533) 
texinfo.texi(,9534) @node pounds, minus, TeX and copyright, Insertions
texinfo.texi(,9535) @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
texinfo.texi(,9536) @findex pounds
texinfo.texi(,9537) 
texinfo.texi(,9538) Use the @code{@@pounds@{@}} command to generate `@pounds{}'.  In a
texinfo.texi(,9539) printed manual, this is the symbol for the currency pounds sterling.
texinfo.texi(,9540) In Info, it is a @samp{#}.  Other currency symbols are unfortunately not
texinfo.texi(,9541) available.
texinfo.texi(,9542) 
texinfo.texi(,9543) 
texinfo.texi(,9544) @node minus, math, pounds, Insertions
texinfo.texi(,9545) @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
texinfo.texi(,9546) @findex minus
texinfo.texi(,9547) 
texinfo.texi(,9548) @cindex em-dash
texinfo.texi(,9549) @cindex hyphen
texinfo.texi(,9550) Use the @code{@@minus@{@}} command to generate a minus sign.  In a
texinfo.texi(,9551) fixed-width font, this is a single hyphen, but in a proportional font,
texinfo.texi(,9552) the symbol is the customary length for a minus sign---a little longer
texinfo.texi(,9553) than a hyphen, shorter than an em-dash:
texinfo.texi(,9554) 
texinfo.texi(,9555) @display
texinfo.texi(,9556) @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
texinfo.texi(,9557) 
texinfo.texi(,9558) `-' is a hyphen generated with the character @samp{-},
texinfo.texi(,9559) 
texinfo.texi(,9560) `---' is an em-dash for text.
texinfo.texi(,9561) @end display
texinfo.texi(,9562) 
texinfo.texi(,9563) @noindent
texinfo.texi(,9564) In the fixed-width font used by Info, @code{@@minus@{@}} is the same
texinfo.texi(,9565) as a hyphen.
texinfo.texi(,9566) 
texinfo.texi(,9567) You should not use @code{@@minus@{@}} inside @code{@@code} or
texinfo.texi(,9568) @code{@@example} because the width distinction is not made in the
texinfo.texi(,9569) fixed-width font they use.
texinfo.texi(,9570) 
texinfo.texi(,9571) When you use @code{@@minus} to specify the mark beginning each entry in
texinfo.texi(,9572) an itemized list, you do not need to type the braces
texinfo.texi(,9573) (@pxref{itemize, , @code{@@itemize}}.)
texinfo.texi(,9574) 
texinfo.texi(,9575) 
texinfo.texi(,9576) @node math
texinfo.texi(,9577) @section @code{@@math}: Inserting Mathematical Expressions
texinfo.texi(,9578) @findex math
texinfo.texi(,9579) @cindex Mathematical expressions
texinfo.texi(,9580) @cindex Formulas, mathematical
texinfo.texi(,9581) 
texinfo.texi(,9582) You can write a short mathematical expression with the @code{@@math}
texinfo.texi(,9583) command.  Write the mathematical expression between braces, like this:
texinfo.texi(,9584) 
texinfo.texi(,9585) @example
texinfo.texi(,9586) @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
texinfo.texi(,9587) @end example
texinfo.texi(,9588) 
texinfo.texi(,9599) @noindent This produces the following in Info:
texinfo.texi(,9601) 
texinfo.texi(,9602) @example
texinfo.texi(,9603) (a + b)(a + b) = a^2 + 2ab + b^2
texinfo.texi(,9604) @end example
texinfo.texi(,9605) 
texinfo.texi(,9606) Thus, the @code{@@math} command has no effect on the Info output.
texinfo.texi(,9607) 
texinfo.texi(,9608) @code{@@math} implies @code{@@tex}.  This not only makes it possible to
texinfo.texi(,9609) write superscripts and subscripts (as in the above example), but also
texinfo.texi(,9610) allows you to use any of the plain @TeX{} math control sequences.  It's
texinfo.texi(,9611) conventional to use @samp{\} instead of @samp{@@} for these commands.
texinfo.texi(,9612) As in:
texinfo.texi(,9613) @example
texinfo.texi(,9614) @@math@{\sin 2\pi \equiv \cos 3\pi@}
texinfo.texi(,9615) @end example
texinfo.texi(,9616) 
texinfo.texi(,9625) @noindent which looks like the input in Info and HTML:
texinfo.texi(,9626) @example
texinfo.texi(,9627) \sin 2\pi \equiv \cos 3\pi
texinfo.texi(,9628) @end example
texinfo.texi(,9629) 
texinfo.texi(,9630) @findex \ @r{(literal \ in @code{@@math})}
texinfo.texi(,9631) Since @samp{\} is an escape character inside @code{@@math}, you can use
texinfo.texi(,9632) @code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
texinfo.texi(,9633) but you'll get the literal @samp{\\} in Info).  @code{@@\} is not
texinfo.texi(,9634) defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
texinfo.texi(,9635) literal @samp{\}.
texinfo.texi(,9636) 
texinfo.texi(,9637) 
texinfo.texi(,9638) @cindex Displayed equations
texinfo.texi(,9639) @cindex Equations, displayed
texinfo.texi(,9640) For displayed equations, you must at present use @TeX{} directly
texinfo.texi(,9641) (@pxref{Raw Formatter Commands}).  
texinfo.texi(,9642) 
texinfo.texi(,9643) 
texinfo.texi(,9644) @node Glyphs
texinfo.texi(,9645) @section Glyphs for Examples
texinfo.texi(,9646) @cindex Glyphs
texinfo.texi(,9647) @cindex Examples, glyphs for
texinfo.texi(,9648) 
texinfo.texi(,9649) In Texinfo, code is often illustrated in examples that are delimited
texinfo.texi(,9650) by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
texinfo.texi(,9651) @code{@@end lisp}.  In such examples, you can indicate the results of
texinfo.texi(,9652) evaluation or an expansion using @samp{@result{}} or
texinfo.texi(,9653) @samp{@expansion{}}.  Likewise, there are commands to insert glyphs
texinfo.texi(,9654) to indicate
texinfo.texi(,9655) printed output, error messages, equivalence of expressions, and the
texinfo.texi(,9656) location of point.@refill
texinfo.texi(,9657) 
texinfo.texi(,9658) The glyph-insertion commands do not need to be used within an example, but
texinfo.texi(,9659) most often they are.  Every  glyph-insertion command is followed by a pair of
texinfo.texi(,9660) left- and right-hand braces.@refill
texinfo.texi(,9661) 
texinfo.texi(,9662) @menu
texinfo.texi(,9663) * Glyphs Summary::              
texinfo.texi(,9664) * result::                      How to show the result of expression.
texinfo.texi(,9665) * expansion::                   How to indicate an expansion.
texinfo.texi(,9666) * Print Glyph::                 How to indicate printed output.
texinfo.texi(,9667) * Error Glyph::                 How to indicate an error message.
texinfo.texi(,9668) * Equivalence::                 How to indicate equivalence.
texinfo.texi(,9669) * Point Glyph::                 How to indicate the location of point.
texinfo.texi(,9670) @end menu
texinfo.texi(,9671) 
texinfo.texi(,9672) 
texinfo.texi(,9673) @node Glyphs Summary
texinfo.texi(,9674) @subsection Glyphs Summary
texinfo.texi(,9675) 
texinfo.texi(,9676) Here are the different glyph commands:@refill
texinfo.texi(,9677) 
texinfo.texi(,9678) @table @asis
texinfo.texi(,9679) @item @result{}
texinfo.texi(,9680) @code{@@result@{@}} points to the result of an expression.@refill
texinfo.texi(,9681) 
texinfo.texi(,9682) @item @expansion{}
texinfo.texi(,9683) @code{@@expansion@{@}} shows the results of a macro expansion.@refill
texinfo.texi(,9684) 
texinfo.texi(,9685) @item @print{}
texinfo.texi(,9686) @code{@@print@{@}} indicates printed output.@refill
texinfo.texi(,9687) 
texinfo.texi(,9688) @item @error{}
texinfo.texi(,9689) @code{@@error@{@}} indicates that the following text is an error
texinfo.texi(,9690) message.@refill
texinfo.texi(,9691) 
texinfo.texi(,9692) @item @equiv{}
texinfo.texi(,9693) @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
texinfo.texi(,9694) 
texinfo.texi(,9695) @item @point{}
texinfo.texi(,9696) @code{@@point@{@}} shows the location of point.@refill
texinfo.texi(,9697) @end table
texinfo.texi(,9698) 
texinfo.texi(,9699) @menu
texinfo.texi(,9700) * result::
texinfo.texi(,9701) * expansion::
texinfo.texi(,9702) * Print Glyph::
texinfo.texi(,9703) * Error Glyph::
texinfo.texi(,9704) * Equivalence::
texinfo.texi(,9705) * Point Glyph::
texinfo.texi(,9706) @end menu
texinfo.texi(,9707) 
texinfo.texi(,9708) 
texinfo.texi(,9709) @node result
texinfo.texi(,9710) @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
texinfo.texi(,9711) @cindex Result of an expression
texinfo.texi(,9712) @cindex Indicating evaluation
texinfo.texi(,9713) @cindex Evaluation glyph
texinfo.texi(,9714) @cindex Value of an expression, indicating
texinfo.texi(,9715) @findex result
texinfo.texi(,9716) 
texinfo.texi(,9717) Use the @code{@@result@{@}} command to indicate the result of
texinfo.texi(,9718) evaluating an expression.@refill
texinfo.texi(,9719) 
texinfo.texi(,9725) The @code{@@result@{@}} command is displayed as @samp{@result{}} in Info
texinfo.texi(,9726) and as a double stemmed arrow in the printed output.@refill
texinfo.texi(,9728) 
texinfo.texi(,9729) Thus, the following,
texinfo.texi(,9730) 
texinfo.texi(,9731) @lisp
texinfo.texi(,9732) (cdr '(1 2 3))
texinfo.texi(,9733)      @result{} (2 3)
texinfo.texi(,9734) @end lisp
texinfo.texi(,9735) 
texinfo.texi(,9736) @noindent
texinfo.texi(,9737) may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
texinfo.texi(,9738) 
texinfo.texi(,9739) 
texinfo.texi(,9740) @node expansion, Print Glyph, result, Glyphs
texinfo.texi(,9741) @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
texinfo.texi(,9742) @cindex Expansion, indicating it
texinfo.texi(,9743) @findex expansion
texinfo.texi(,9744) 
texinfo.texi(,9745) When an expression is a macro call, it expands into a new expression.
texinfo.texi(,9746) You can indicate the result of the expansion with the
texinfo.texi(,9747) @code{@@expansion@{@}} command.@refill
texinfo.texi(,9748) 
texinfo.texi(,9754) The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
texinfo.texi(,9755) in Info and as a long arrow with a flat base in the printed output.@refill
texinfo.texi(,9757) 
texinfo.texi(,9758) @need 700
texinfo.texi(,9759) For example, the following
texinfo.texi(,9760) 
texinfo.texi(,9761) @example
texinfo.texi(,9762) @group
texinfo.texi(,9763) @@lisp
texinfo.texi(,9764) (third '(a b c))
texinfo.texi(,9765)      @@expansion@{@} (car (cdr (cdr '(a b c))))
texinfo.texi(,9766)      @@result@{@} c
texinfo.texi(,9767) @@end lisp
texinfo.texi(,9768) @end group
texinfo.texi(,9769) @end example
texinfo.texi(,9770) 
texinfo.texi(,9771) @noindent
texinfo.texi(,9772) produces
texinfo.texi(,9773) 
texinfo.texi(,9774) @lisp
texinfo.texi(,9775) @group
texinfo.texi(,9776) (third '(a b c))
texinfo.texi(,9777)      @expansion{} (car (cdr (cdr '(a b c))))
texinfo.texi(,9778)      @result{} c
texinfo.texi(,9779) @end group
texinfo.texi(,9780) @end lisp
texinfo.texi(,9781) 
texinfo.texi(,9782) @noindent
texinfo.texi(,9783) which may be read as:
texinfo.texi(,9784) 
texinfo.texi(,9785) @quotation
texinfo.texi(,9786) @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
texinfo.texi(,9787) the result of evaluating the expression is @code{c}.
texinfo.texi(,9788) @end quotation
texinfo.texi(,9789) 
texinfo.texi(,9790) @noindent
texinfo.texi(,9791) Often, as in this case, an example looks better if the
texinfo.texi(,9792) @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented
texinfo.texi(,9793) five spaces.@refill
texinfo.texi(,9794) 
texinfo.texi(,9795) 
texinfo.texi(,9796) @node Print Glyph, Error Glyph, expansion, Glyphs
texinfo.texi(,9797) @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
texinfo.texi(,9798) @cindex Printed output, indicating it
texinfo.texi(,9799) @findex print
texinfo.texi(,9800) 
texinfo.texi(,9801) Sometimes an expression will print output during its execution.  You
texinfo.texi(,9802) can indicate the printed output with the @code{@@print@{@}} command.@refill
texinfo.texi(,9803) 
texinfo.texi(,9809) The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
texinfo.texi(,9810) and similarly, as a horizontal dash butting against a vertical bar, in
texinfo.texi(,9811) the printed output.@refill
texinfo.texi(,9813) 
texinfo.texi(,9814) In the following example, the printed text is indicated with
texinfo.texi(,9815) @samp{@print{}}, and the value of the expression follows on the
texinfo.texi(,9816) last line.@refill
texinfo.texi(,9817) 
texinfo.texi(,9818) @lisp
texinfo.texi(,9819) @group
texinfo.texi(,9820) (progn (print 'foo) (print 'bar))
texinfo.texi(,9821)      @print{} foo
texinfo.texi(,9822)      @print{} bar
texinfo.texi(,9823)      @result{} bar
texinfo.texi(,9824) @end group
texinfo.texi(,9825) @end lisp
texinfo.texi(,9826) 
texinfo.texi(,9827) @noindent
texinfo.texi(,9828) In a Texinfo source file, this example is written as follows:
texinfo.texi(,9829) 
texinfo.texi(,9830) @lisp
texinfo.texi(,9831) @group
texinfo.texi(,9832) @@lisp
texinfo.texi(,9833) (progn (print 'foo) (print 'bar))
texinfo.texi(,9834)      @@print@{@} foo
texinfo.texi(,9835)      @@print@{@} bar
texinfo.texi(,9836)      @@result@{@} bar
texinfo.texi(,9837) @@end lisp
texinfo.texi(,9838) @end group
texinfo.texi(,9839) @end lisp
texinfo.texi(,9840) 
texinfo.texi(,9841) 
texinfo.texi(,9842) @node Error Glyph, Equivalence, Print Glyph, Glyphs
texinfo.texi(,9843) @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
texinfo.texi(,9844) @cindex Error message, indicating it
texinfo.texi(,9845) @findex error
texinfo.texi(,9846) 
texinfo.texi(,9847) A piece of code may cause an error when you evaluate it.  You can
texinfo.texi(,9848) designate the error message with the @code{@@error@{@}} command.@refill
texinfo.texi(,9849) 
texinfo.texi(,9855) The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
texinfo.texi(,9856) and as the word `error' in a box in the printed output.@refill
texinfo.texi(,9858) 
texinfo.texi(,9859) @need 700
texinfo.texi(,9860) Thus,
texinfo.texi(,9861) 
texinfo.texi(,9862) @example
texinfo.texi(,9863) @@lisp
texinfo.texi(,9864) (+ 23 'x)
texinfo.texi(,9865) @@error@{@} Wrong type argument: integer-or-marker-p, x
texinfo.texi(,9866) @@end lisp
texinfo.texi(,9867) @end example
texinfo.texi(,9868) 
texinfo.texi(,9869) @noindent
texinfo.texi(,9870) produces
texinfo.texi(,9871) 
texinfo.texi(,9872) @lisp
texinfo.texi(,9873) (+ 23 'x)
texinfo.texi(,9874) @error{} Wrong type argument: integer-or-marker-p, x
texinfo.texi(,9875) @end lisp
texinfo.texi(,9876) 
texinfo.texi(,9877) @noindent
texinfo.texi(,9878) This indicates that the following error message is printed
texinfo.texi(,9879) when you evaluate the expression:
texinfo.texi(,9880) 
texinfo.texi(,9881) @lisp
texinfo.texi(,9882) Wrong type argument: integer-or-marker-p, x
texinfo.texi(,9883) @end lisp
texinfo.texi(,9884) 
texinfo.texi(,9885) @samp{@error{}} itself is not part of the error message.
texinfo.texi(,9886) 
texinfo.texi(,9887) 
texinfo.texi(,9888) @node Equivalence, Point Glyph, Error Glyph, Glyphs
texinfo.texi(,9889) @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
texinfo.texi(,9890) @cindex Equivalence, indicating it
texinfo.texi(,9891) @findex equiv
texinfo.texi(,9892) 
texinfo.texi(,9893) Sometimes two expressions produce identical results.  You can indicate the
texinfo.texi(,9894) exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
texinfo.texi(,9895) 
texinfo.texi(,9901) The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
texinfo.texi(,9902) and as a three parallel horizontal lines in the printed output.@refill
texinfo.texi(,9904) 
texinfo.texi(,9905) Thus,
texinfo.texi(,9906) 
texinfo.texi(,9907) @example
texinfo.texi(,9908) @@lisp
texinfo.texi(,9909) (make-sparse-keymap) @@equiv@{@} (list 'keymap)
texinfo.texi(,9910) @@end lisp
texinfo.texi(,9911) @end example
texinfo.texi(,9912) 
texinfo.texi(,9913) @noindent
texinfo.texi(,9914) produces
texinfo.texi(,9915) 
texinfo.texi(,9916) @lisp
texinfo.texi(,9917) (make-sparse-keymap) @equiv{} (list 'keymap)
texinfo.texi(,9918) @end lisp
texinfo.texi(,9919) 
texinfo.texi(,9920) @noindent
texinfo.texi(,9921) This indicates that evaluating @code{(make-sparse-keymap)} produces
texinfo.texi(,9922) identical results to evaluating @code{(list 'keymap)}.
texinfo.texi(,9923) 
texinfo.texi(,9924) 
texinfo.texi(,9925) @node Point Glyph
texinfo.texi(,9926) @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
texinfo.texi(,9927) @cindex Point, indicating in a buffer
texinfo.texi(,9928) @findex point
texinfo.texi(,9929) 
texinfo.texi(,9930) Sometimes you need to show an example of text in an Emacs buffer.  In
texinfo.texi(,9931) such examples, the convention is to include the entire contents of the
texinfo.texi(,9932) buffer in question between two lines of dashes containing the buffer
texinfo.texi(,9933) name.@refill
texinfo.texi(,9934) 
texinfo.texi(,9935) You can use the @samp{@@point@{@}} command to show the location of point
texinfo.texi(,9936) in the text in the buffer.  (The symbol for point, of course, is not
texinfo.texi(,9937) part of the text in the buffer; it indicates the place @emph{between}
texinfo.texi(,9938) two characters where point is located.)@refill
texinfo.texi(,9939) 
texinfo.texi(,9945) The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
texinfo.texi(,9946) and as a small five pointed star in the printed output.@refill
texinfo.texi(,9948) 
texinfo.texi(,9949) The following example shows the contents of buffer @file{foo} before
texinfo.texi(,9950) and after evaluating a Lisp command to insert the word @code{changed}.@refill
texinfo.texi(,9951) 
texinfo.texi(,9952) @example
texinfo.texi(,9953) @group
texinfo.texi(,9954) ---------- Buffer: foo ----------
texinfo.texi(,9955) This is the @point{}contents of foo.
texinfo.texi(,9956) ---------- Buffer: foo ----------
texinfo.texi(,9957) 
texinfo.texi(,9958) @end group
texinfo.texi(,9959) @end example
texinfo.texi(,9960) 
texinfo.texi(,9961) @example
texinfo.texi(,9962) @group
texinfo.texi(,9963) (insert "changed ")
texinfo.texi(,9964)      @result{} nil
texinfo.texi(,9965) ---------- Buffer: foo ----------
texinfo.texi(,9966) This is the changed @point{}contents of foo.
texinfo.texi(,9967) ---------- Buffer: foo ----------
texinfo.texi(,9968) 
texinfo.texi(,9969) @end group
texinfo.texi(,9970) @end example
texinfo.texi(,9971) 
texinfo.texi(,9972) In a Texinfo source file, the example is written like this:@refill
texinfo.texi(,9973) 
texinfo.texi(,9974) @example
texinfo.texi(,9975) @@example
texinfo.texi(,9976) ---------- Buffer: foo ----------
texinfo.texi(,9977) This is the @@point@{@}contents of foo.
texinfo.texi(,9978) ---------- Buffer: foo ----------
texinfo.texi(,9979) 
texinfo.texi(,9980) (insert "changed ")
texinfo.texi(,9981)      @@result@{@} nil
texinfo.texi(,9982) ---------- Buffer: foo ----------
texinfo.texi(,9983) This is the changed @@point@{@}contents of foo.
texinfo.texi(,9984) ---------- Buffer: foo ----------
texinfo.texi(,9985) @@end example
texinfo.texi(,9986) @end example
texinfo.texi(,9987) 
texinfo.texi(,9988) 
texinfo.texi(,9989) @node Footnotes
texinfo.texi(,9990) @section Footnotes
texinfo.texi(,9991) @cindex Footnotes
texinfo.texi(,9992) @findex footnote
texinfo.texi(,9993) 
texinfo.texi(,9994) A @dfn{footnote} is for a reference that documents or elucidates the
texinfo.texi(,9995) primary text.@footnote{A footnote should complement or expand upon
texinfo.texi(,9996) the primary text, but a reader should not need to read a footnote to
texinfo.texi(,9997) understand the primary text.  For a thorough discussion of footnotes,
texinfo.texi(,9998) see @cite{The Chicago Manual of Style}, which is published by the
texinfo.texi(,9999) University of Chicago Press.}
texinfo.texi(,10000) 
texinfo.texi(,10001) @menu
texinfo.texi(,10002) * Footnote Commands::           How to write a footnote in Texinfo.
texinfo.texi(,10003) * Footnote Styles::             Controlling how footnotes appear in Info.
texinfo.texi(,10004) @end menu
texinfo.texi(,10005) 
texinfo.texi(,10006) 
texinfo.texi(,10007) @node Footnote Commands
texinfo.texi(,10008) @subsection Footnote Commands
texinfo.texi(,10009) 
texinfo.texi(,10010) In Texinfo, footnotes are created with the @code{@@footnote} command.
texinfo.texi(,10011) This command is followed immediately by a left brace, then by the text
texinfo.texi(,10012) of the footnote, and then by a terminating right brace.  Footnotes may
texinfo.texi(,10013) be of any length (they will be broken across pages if necessary), but
texinfo.texi(,10014) are usually short.  The template is:
texinfo.texi(,10015) 
texinfo.texi(,10016) @example
texinfo.texi(,10017) ordinary text@@footnote@{@var{text of footnote}@}
texinfo.texi(,10018) @end example
texinfo.texi(,10019) 
texinfo.texi(,10020) As shown here, the @code{@@footnote} command should come right after the
texinfo.texi(,10021) text being footnoted, with no intervening space; otherwise, the footnote
texinfo.texi(,10022) marker might end up starting a line.
texinfo.texi(,10023) 
texinfo.texi(,10024) For example, this clause is followed by a sample footnote@footnote{Here
texinfo.texi(,10025) is the sample footnote.}; in the Texinfo source, it looks like
texinfo.texi(,10026) this:
texinfo.texi(,10027) 
texinfo.texi(,10028) @example
texinfo.texi(,10029) @dots{}a sample footnote@@footnote@{Here is the sample
texinfo.texi(,10030) footnote.@}; in the Texinfo source@dots{}
texinfo.texi(,10031) @end example
texinfo.texi(,10032) 
texinfo.texi(,10033) As you can see, the source includes two punctuation marks next to each
texinfo.texi(,10034) other; in this case, @samp{.@};} is the sequence.  This is normal (the
texinfo.texi(,10035) first ends the footnote and the second belongs to the sentence being
texinfo.texi(,10036) footnoted), so don't worry that it looks odd.
texinfo.texi(,10037) 
texinfo.texi(,10038) In a printed manual or book, the reference mark for a footnote is a
texinfo.texi(,10039) small, superscripted number; the text of the footnote appears at the
texinfo.texi(,10040) bottom of the page, below a horizontal line.
texinfo.texi(,10041) 
texinfo.texi(,10042) In Info, the reference mark for a footnote is a pair of parentheses
texinfo.texi(,10043) with the footnote number between them, like this: @samp{(1)}.  The
texinfo.texi(,10044) reference mark is followed by a cross-reference link to the footnote's
texinfo.texi(,10045) text.
texinfo.texi(,10046) 
texinfo.texi(,10047) In the HTML output, footnote references are marked with a small,
texinfo.texi(,10048) superscripted number which is rendered as a hypertext link to the
texinfo.texi(,10049) footnote text.
texinfo.texi(,10050) 
texinfo.texi(,10051) By the way, footnotes in the argument of an @code{@@item} command for a
texinfo.texi(,10052) @code{@@table} must be on the same line as the @code{@@item}
texinfo.texi(,10053) (as usual).  @xref{Two-column Tables}.
texinfo.texi(,10054) 
texinfo.texi(,10055) 
texinfo.texi(,10056) @node Footnote Styles
texinfo.texi(,10057) @subsection Footnote Styles
texinfo.texi(,10058) 
texinfo.texi(,10059) Info has two footnote styles, which determine where the text of the
texinfo.texi(,10060) footnote is located:@refill
texinfo.texi(,10061) 
texinfo.texi(,10062) @itemize @bullet
texinfo.texi(,10063) @cindex @samp{@r{End}} node footnote style
texinfo.texi(,10064) @item
texinfo.texi(,10065) In the `End' node style, all the footnotes for a single node
texinfo.texi(,10066) are placed at the end of that node.  The footnotes are separated from
texinfo.texi(,10067) the rest of the node by a line of dashes with the word
texinfo.texi(,10068) @samp{Footnotes} within it.  Each footnote begins with an
texinfo.texi(,10069) @samp{(@var{n})} reference mark.@refill
texinfo.texi(,10070) 
texinfo.texi(,10071) @need 700
texinfo.texi(,10072) @noindent
texinfo.texi(,10073) Here is an example of a single footnote in the end of node style:@refill
texinfo.texi(,10074) 
texinfo.texi(,10075) @example
texinfo.texi(,10076) @group
texinfo.texi(,10077)  --------- Footnotes ---------
texinfo.texi(,10078) 
texinfo.texi(,10079) (1)  Here is a sample footnote.
texinfo.texi(,10080) @end group
texinfo.texi(,10081) @end example
texinfo.texi(,10082) 
texinfo.texi(,10083) @cindex @samp{@r{Separate}} footnote style
texinfo.texi(,10084) @item
texinfo.texi(,10085) In the `Separate' node style, all the footnotes for a single
texinfo.texi(,10086) node are placed in an automatically constructed node of
texinfo.texi(,10087) their own.  In this style, a ``footnote reference'' follows
texinfo.texi(,10088) each @samp{(@var{n})} reference mark in the body of the
texinfo.texi(,10089) node.  The footnote reference is actually a cross reference
texinfo.texi(,10090) which you use to reach the footnote node.@refill
texinfo.texi(,10091) 
texinfo.texi(,10092) The name of the node with the footnotes is constructed
texinfo.texi(,10093) by appending @w{@samp{-Footnotes}} to the name of the node
texinfo.texi(,10094) that contains the footnotes. (Consequently, the footnotes'
texinfo.texi(,10095) node for the @file{Footnotes} node is
texinfo.texi(,10096) @w{@file{Footnotes-Footnotes}}!)  The footnotes' node has an
texinfo.texi(,10097) `Up' node pointer that leads back to its parent node.@refill
texinfo.texi(,10098) 
texinfo.texi(,10099) @noindent
texinfo.texi(,10100) Here is how the first footnote in this manual looks after being
texinfo.texi(,10101) formatted for Info in the separate node style:@refill
texinfo.texi(,10102) 
texinfo.texi(,10103) @smallexample
texinfo.texi(,10104) @group
texinfo.texi(,10105) File: texinfo.info  Node: Overview-Footnotes, Up: Overview
texinfo.texi(,10106) 
texinfo.texi(,10107) (1) The first syllable of "Texinfo" is pronounced like "speck", not
texinfo.texi(,10108) "hex". @dots{}
texinfo.texi(,10109) @end group
texinfo.texi(,10110) @end smallexample
texinfo.texi(,10111) @end itemize
texinfo.texi(,10112) 
texinfo.texi(,10113) A Texinfo file may be formatted into an Info file with either footnote
texinfo.texi(,10114) style.@refill
texinfo.texi(,10115) 
texinfo.texi(,10116) @findex footnotestyle
texinfo.texi(,10117) Use the @code{@@footnotestyle} command to specify an Info file's
texinfo.texi(,10118) footnote style.  Write this command at the beginning of a line followed
texinfo.texi(,10119) by an argument, either @samp{end} for the end node style or
texinfo.texi(,10120) @samp{separate} for the separate node style.
texinfo.texi(,10121) 
texinfo.texi(,10122) @need 700
texinfo.texi(,10123) For example,
texinfo.texi(,10124) 
texinfo.texi(,10125) @example
texinfo.texi(,10126) @@footnotestyle end
texinfo.texi(,10127) @end example
texinfo.texi(,10128) @noindent
texinfo.texi(,10129) or
texinfo.texi(,10130) @example
texinfo.texi(,10131) @@footnotestyle separate
texinfo.texi(,10132) @end example
texinfo.texi(,10133) 
texinfo.texi(,10134) Write an @code{@@footnotestyle} command before or shortly after the
texinfo.texi(,10135) end-of-header line at the beginning of a Texinfo file.  (If you
texinfo.texi(,10136) include the @code{@@footnotestyle} command between the start-of-header
texinfo.texi(,10137) and end-of-header lines, the region formatting commands will format
texinfo.texi(,10138) footnotes as specified.)@refill
texinfo.texi(,10139) 
texinfo.texi(,10140) If you do not specify a footnote style, the formatting commands use
texinfo.texi(,10141) their default style.  Currently, @code{texinfo-format-buffer} and
texinfo.texi(,10142) @code{texinfo-format-region} use the `separate' style and
texinfo.texi(,10143) @code{makeinfo} uses the `end' style.@refill
texinfo.texi(,10144) 
texinfo.texi(,10145) @c !!! note: makeinfo's --footnote-style option overrides footnotestyle
texinfo.texi(,10181) This chapter contains two footnotes.@refill
texinfo.texi(,10183) 
texinfo.texi(,10184) 
texinfo.texi(,10185) @c this should be described with figures when we have them
texinfo.texi(,10186) @c perhaps in the quotation/example chapter.
texinfo.texi(,10187) @node Images
texinfo.texi(,10188) @section Inserting Images
texinfo.texi(,10189) 
texinfo.texi(,10190) @cindex Images, inserting
texinfo.texi(,10191) @cindex Pictures, inserting
texinfo.texi(,10192) @findex image
texinfo.texi(,10193) 
texinfo.texi(,10194) You can insert an image given in an external file with the
texinfo.texi(,10195) @code{@@image} command:
texinfo.texi(,10196) 
texinfo.texi(,10197) @example
texinfo.texi(,10198) @@image@{@var{filename}, @r{[}@var{width}@r{]}, @r{[}@var{height}@r{]}, @r{[}@var{alttext}@r{]}, @r{[}@var{extension}@r{]}@}
texinfo.texi(,10199) @end example
texinfo.texi(,10200) 
texinfo.texi(,10201) @cindex Formats for images
texinfo.texi(,10202) @cindex Image formats
texinfo.texi(,10203) The @var{filename} argument is mandatory, and must not have an
texinfo.texi(,10204) extension, because the different processors support different formats:
texinfo.texi(,10205) @itemize @bullet
texinfo.texi(,10206) @item
texinfo.texi(,10207) @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
texinfo.texi(,10208) format).
texinfo.texi(,10209) @item
texinfo.texi(,10210) @pindex pdftex@r{, and images}
texinfo.texi(,10211) PDF@TeX{} reads @file{@var{filename}.pdf} (Adobe's Portable Document Format).
texinfo.texi(,10212) @item
texinfo.texi(,10213) @code{makeinfo} uses @file{@var{filename}.txt} verbatim for
texinfo.texi(,10214) Info output (more or less as if it was an @code{@@example}).
texinfo.texi(,10215) @item
texinfo.texi(,10216) @code{makeinfo}
texinfo.texi(,10217) uses the optional fifth argument to @code{@@image} for the extension if
texinfo.texi(,10218) you supply it.  For example:
texinfo.texi(,10219) 
texinfo.texi(,10220) @pindex XPM image format
texinfo.texi(,10221) @example
texinfo.texi(,10222) @@image@{foo,,,,xpm@}
texinfo.texi(,10223) @end example
texinfo.texi(,10224) 
texinfo.texi(,10225) @noindent
texinfo.texi(,10226) will cause @samp{makeinfo --html} to try @file{foo.xpm}.
texinfo.texi(,10227) 
texinfo.texi(,10228) @cindex GIF, unsupported due to patents
texinfo.texi(,10229) @cindex PNG image format
texinfo.texi(,10230) @cindex JPG image format
texinfo.texi(,10231) If you do not supply the optional fifth argument, @samp{makeinfo
texinfo.texi(,10232) ---html} first tries @file{@var{filename}.png}; if that does not exist,
texinfo.texi(,10233) it tries @file{@var{filename}.jpg}.  If that does not exist either, it
texinfo.texi(,10234) complains.  (We cannot support GIF format directly due to software
texinfo.texi(,10235) patents.)
texinfo.texi(,10236) @end itemize
texinfo.texi(,10237) 
texinfo.texi(,10238) @cindex Width of images
texinfo.texi(,10239) @cindex Height of images
texinfo.texi(,10240) @cindex Aspect ratio of images
texinfo.texi(,10241) @cindex Distorting images
texinfo.texi(,10242) The optional @var{width} and @var{height} arguments specify the size to
texinfo.texi(,10243) scale the image to (they are ignored for Info output).  If neither is
texinfo.texi(,10244) specified, the image is presented in its natural size (given in the
texinfo.texi(,10245) file); if only one is specified, the other is scaled proportionately;
texinfo.texi(,10246) and if both are specified, both are respected, thus possibly distorting
texinfo.texi(,10247) the original image by changing its aspect ratio.
texinfo.texi(,10248) 
texinfo.texi(,10249) @cindex Dimensions and image sizes
texinfo.texi(,10250) The @var{width} and @var{height} may be specified using any valid @TeX{}
texinfo.texi(,10251) dimension, namely:
texinfo.texi(,10252) 
texinfo.texi(,10253) @table @asis
texinfo.texi(,10254) @item pt
texinfo.texi(,10255) @cindex Points (dimension)
texinfo.texi(,10256) point (72.27pt = 1in)
texinfo.texi(,10257) @item pc
texinfo.texi(,10258) @cindex Picas
texinfo.texi(,10259) pica (1pc = 12pt)
texinfo.texi(,10260) @item bp
texinfo.texi(,10261) @cindex Big points
texinfo.texi(,10262) big point (72bp = 1in)
texinfo.texi(,10263) @item in
texinfo.texi(,10264) @cindex Inches
texinfo.texi(,10265) inch
texinfo.texi(,10266) @item cm
texinfo.texi(,10267) @cindex Centimeters
texinfo.texi(,10268) centimeter (2.54cm = 1in)
texinfo.texi(,10269) @item mm
texinfo.texi(,10270) @cindex Millimeters
texinfo.texi(,10271) millimeter (10mm = 1cm)
texinfo.texi(,10272) @item dd
texinfo.texi(,10273) @cindex Did@^ot points
texinfo.texi(,10274) did@^ot point (1157dd = 1238pt)
texinfo.texi(,10275) @item cc
texinfo.texi(,10276) @cindex Ciceros
texinfo.texi(,10277) cicero (1cc = 12dd)
texinfo.texi(,10278) @item sp
texinfo.texi(,10279) @cindex Scaled points
texinfo.texi(,10280) scaled point (65536sp = 1pt)
texinfo.texi(,10281) @end table
texinfo.texi(,10282) 
texinfo.texi(,10283) @pindex ridt.eps
texinfo.texi(,10284) For example, the following will scale a file @file{ridt.eps} to one
texinfo.texi(,10285) inch vertically, with the width scaled proportionately:
texinfo.texi(,10286) 
texinfo.texi(,10287) @example
texinfo.texi(,10288) @@image@{ridt,,1in@}
texinfo.texi(,10289) @end example
texinfo.texi(,10290) 
texinfo.texi(,10291) @pindex epsf.tex
texinfo.texi(,10292) For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
texinfo.texi(,10293) installed somewhere that @TeX{} can find it.  (The standard location is
texinfo.texi(,10294) @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
texinfo.texi(,10295) root of your @TeX{} directory tree.)  This file is included in the
texinfo.texi(,10296) Texinfo distribution and is also available from
texinfo.texi(,10297) @uref{ftp://tug.org/tex/epsf.tex}, among other places.
texinfo.texi(,10298) 
texinfo.texi(,10299) @code{@@image} can be used within a line as well as for displayed
texinfo.texi(,10300) figures.  Therefore, if you intend it to be displayed, be sure to leave
texinfo.texi(,10301) a blank line before the command, or the output will run into the
texinfo.texi(,10302) preceding text.
texinfo.texi(,10303) 
texinfo.texi(,10304) @cindex alt attribute for images
texinfo.texi(,10305) @cindex alternate text for images
texinfo.texi(,10306) When producing html, @code{makeinfo} sets the @dfn{alt attribute} for
texinfo.texi(,10307) inline images to the optional fourth argument to @code{@@image}, if
texinfo.texi(,10308) supplied.  If not supplied, @code{makeinfo} uses the full file name of
texinfo.texi(,10309) the image being displayed.
texinfo.texi(,10310) 
texinfo.texi(,10311) 
texinfo.texi(,10312) @node Breaks
texinfo.texi(,10313) @chapter Making and Preventing Breaks
texinfo.texi(,10314) @cindex Making line and page breaks
texinfo.texi(,10315) @cindex Preventing line and page breaks
texinfo.texi(,10316) 
texinfo.texi(,10317) @cindex Line breaks
texinfo.texi(,10318) Usually, a Texinfo file is processed both by @TeX{} and by one of the
texinfo.texi(,10319) Info formatting commands.  Line, paragraph, or page breaks sometimes
texinfo.texi(,10320) occur in the `wrong' place in one or other form of output.  You must
texinfo.texi(,10321) ensure that text looks right both in the printed manual and in the
texinfo.texi(,10322) Info file.
texinfo.texi(,10323) 
texinfo.texi(,10324) @cindex White space, excessive
texinfo.texi(,10325) @cindex Page breaks
texinfo.texi(,10326) For example, in a printed manual, page breaks may occur awkwardly in
texinfo.texi(,10327) the middle of an example; to prevent this, you can hold text together
texinfo.texi(,10328) using a grouping command that keeps the text from being split across
texinfo.texi(,10329) two pages.  Conversely, you may want to force a page break where none
texinfo.texi(,10330) would occur normally.  Fortunately, problems like these do not often
texinfo.texi(,10331) arise.  When they do, use the break, break prevention, or pagination
texinfo.texi(,10332) commands.
texinfo.texi(,10333) 
texinfo.texi(,10334) @menu
texinfo.texi(,10335) * Break Commands::              Cause and prevent splits.
texinfo.texi(,10336) * Line Breaks::                 How to force a single line to use two lines.
texinfo.texi(,10337) * - and hyphenation::           How to tell @TeX{} about hyphenation points.
texinfo.texi(,10338) * w::                           How to prevent unwanted line breaks.
texinfo.texi(,10339) * sp::                          How to insert blank lines.
texinfo.texi(,10340) * page::                        How to force the start of a new page.
texinfo.texi(,10341) * group::                       How to prevent unwanted page breaks.
texinfo.texi(,10342) * need::                        Another way to prevent unwanted page breaks.
texinfo.texi(,10343) @end menu
texinfo.texi(,10344) 
texinfo.texi(,10345) 
texinfo.texi(,10346) @node Break Commands, Line Breaks, Breaks, Breaks
texinfo.texi(,10348) @heading Break Commands
texinfo.texi(,10350) 
texinfo.texi(,10351) The break commands create or allow line and paragraph breaks:@refill
texinfo.texi(,10352) 
texinfo.texi(,10353) @table @code
texinfo.texi(,10354) @item @@*
texinfo.texi(,10355) Force a line break.
texinfo.texi(,10356) 
texinfo.texi(,10357) @item @@sp @var{n}
texinfo.texi(,10358) Skip @var{n} blank lines.@refill
texinfo.texi(,10359) 
texinfo.texi(,10360) @item @@-
texinfo.texi(,10361) Insert a discretionary hyphen.
texinfo.texi(,10362) 
texinfo.texi(,10363) @item @@hyphenation@{@var{hy-phen-a-ted words}@}
texinfo.texi(,10364) Define hyphen points in @var{hy-phen-a-ted words}.
texinfo.texi(,10365) @end table
texinfo.texi(,10366) 
texinfo.texi(,10367) The line-break-prevention command holds text together all on one
texinfo.texi(,10368) line:@refill
texinfo.texi(,10369) 
texinfo.texi(,10370) @table @code
texinfo.texi(,10371) @item @@w@{@var{text}@}
texinfo.texi(,10372) Prevent @var{text} from being split and hyphenated across two lines.@refill
texinfo.texi(,10373) @end table
texinfo.texi(,10377) 
texinfo.texi(,10378) The pagination commands apply only to printed output, since Info
texinfo.texi(,10379) files do not have pages.@refill
texinfo.texi(,10380) 
texinfo.texi(,10381) @table @code
texinfo.texi(,10382) @item @@page
texinfo.texi(,10383) Start a new page in the printed manual.@refill
texinfo.texi(,10384) 
texinfo.texi(,10385) @item @@group
texinfo.texi(,10386) Hold text together that must appear on one printed page.@refill
texinfo.texi(,10387) 
texinfo.texi(,10388) @item @@need @var{mils}
texinfo.texi(,10389) Start a new printed page if not enough space on this one.@refill
texinfo.texi(,10390) @end table
texinfo.texi(,10391) 
texinfo.texi(,10392) @node Line Breaks
texinfo.texi(,10393) @section @code{@@*}: Generate Line Breaks
texinfo.texi(,10394) @findex * @r{(force line break)}
texinfo.texi(,10395) @cindex Line breaks
texinfo.texi(,10396) @cindex Breaks in a line
texinfo.texi(,10397) 
texinfo.texi(,10398) The @code{@@*} command forces a line break in both the printed manual and
texinfo.texi(,10399) in Info.@refill
texinfo.texi(,10400) 
texinfo.texi(,10401) @need 700
texinfo.texi(,10402) For example,
texinfo.texi(,10403) 
texinfo.texi(,10404) @example
texinfo.texi(,10405) This line @@* is broken @@*in two places.
texinfo.texi(,10406) @end example
texinfo.texi(,10407) 
texinfo.texi(,10408) @noindent
texinfo.texi(,10409) produces
texinfo.texi(,10410) 
texinfo.texi(,10411) @example
texinfo.texi(,10412) @group
texinfo.texi(,10413) This line
texinfo.texi(,10414)  is broken
texinfo.texi(,10415) in two places.
texinfo.texi(,10416) @end group
texinfo.texi(,10417) @end example
texinfo.texi(,10418) 
texinfo.texi(,10419) @noindent
texinfo.texi(,10420) (Note that the space after the first @code{@@*} command is faithfully
texinfo.texi(,10421) carried down to the next line.)@refill
texinfo.texi(,10422) 
texinfo.texi(,10423) @need 800
texinfo.texi(,10424) The @code{@@*} command is often used in a file's copyright page:@refill
texinfo.texi(,10425) 
texinfo.texi(,10426) @example
texinfo.texi(,10427) @group
texinfo.texi(,10428) This is edition 2.0 of the Texinfo documentation,@@*
texinfo.texi(,10429) and is for @dots{}
texinfo.texi(,10430) @end group
texinfo.texi(,10431) @end example
texinfo.texi(,10432) 
texinfo.texi(,10433) @noindent
texinfo.texi(,10434) In this case, the @code{@@*} command keeps @TeX{} from stretching the
texinfo.texi(,10435) line across the whole page in an ugly manner.@refill
texinfo.texi(,10436) 
texinfo.texi(,10437) @quotation
texinfo.texi(,10438) @strong{Please note:} Do not write braces after an @code{@@*} command;
texinfo.texi(,10439) they are not needed.@refill
texinfo.texi(,10440) 
texinfo.texi(,10441) Do not write an @code{@@refill} command at the end of a paragraph
texinfo.texi(,10442) containing an @code{@@*} command; it will cause the paragraph to be
texinfo.texi(,10443) refilled after the line break occurs, negating the effect of the line
texinfo.texi(,10444) break.@refill
texinfo.texi(,10445) @end quotation
texinfo.texi(,10446) 
texinfo.texi(,10447) 
texinfo.texi(,10448) @node - and hyphenation
texinfo.texi(,10449) @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} hyphenate
texinfo.texi(,10450) 
texinfo.texi(,10451) @findex - @r{(discretionary hyphen)}
texinfo.texi(,10452) @findex hyphenation
texinfo.texi(,10453) @cindex Hyphenation, helping @TeX{} do
texinfo.texi(,10454) @cindex Fine-tuning, and hyphenation
texinfo.texi(,10455) 
texinfo.texi(,10456) Although @TeX{}'s hyphenation algorithm is generally pretty good, it
texinfo.texi(,10457) does miss useful hyphenation points from time to time.  (Or, far more
texinfo.texi(,10458) rarely, insert an incorrect hyphenation.)  So, for documents with an
texinfo.texi(,10459) unusual vocabulary or when fine-tuning for a printed edition, you may
texinfo.texi(,10460) wish to help @TeX{} out.  Texinfo supports two commands for this:
texinfo.texi(,10461) 
texinfo.texi(,10462) @table @code
texinfo.texi(,10463) @item @@-
texinfo.texi(,10464) Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
texinfo.texi(,10465) not have to) hyphenate.  This is especially useful when you notice an
texinfo.texi(,10466) overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
texinfo.texi(,10467) hboxes}).  @TeX{} will not insert any hyphenation points itself into a
texinfo.texi(,10468) word containing @code{@@-}.
texinfo.texi(,10469) 
texinfo.texi(,10470) @item @@hyphenation@{@var{hy-phen-a-ted words}@}
texinfo.texi(,10471) Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}.  As shown, you
texinfo.texi(,10472) put a @samp{-} at each hyphenation point.  For example:
texinfo.texi(,10473) @example
texinfo.texi(,10474) @@hyphenation@{man-u-script man-u-scripts@}
texinfo.texi(,10475) @end example
texinfo.texi(,10476) @noindent @TeX{} only uses the specified hyphenation points when the
texinfo.texi(,10477) words match exactly, so give all necessary variants.
texinfo.texi(,10478) @end table
texinfo.texi(,10479) 
texinfo.texi(,10480) Info output is not hyphenated, so these commands have no effect there.
texinfo.texi(,10481) 
texinfo.texi(,10482) @node w
texinfo.texi(,10483) @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
texinfo.texi(,10484) @findex w @r{(prevent line break)}
texinfo.texi(,10485) @cindex Line breaks, preventing
texinfo.texi(,10486) @cindex Hyphenation, preventing
texinfo.texi(,10487) 
texinfo.texi(,10488) @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
texinfo.texi(,10489) within @var{text}.@refill
texinfo.texi(,10490) 
texinfo.texi(,10491) You can use the @code{@@w} command to prevent @TeX{} from automatically
texinfo.texi(,10492) hyphenating a long name or phrase that happens to fall near the end of a
texinfo.texi(,10493) line.  For example:
texinfo.texi(,10494) 
texinfo.texi(,10495) @example
texinfo.texi(,10496) You can copy GNU software from @@w@{@@samp@{ftp.gnu.org@}@}.
texinfo.texi(,10497) @end example
texinfo.texi(,10498) 
texinfo.texi(,10499) @noindent
texinfo.texi(,10500) produces
texinfo.texi(,10501) 
texinfo.texi(,10502) @quotation
texinfo.texi(,10503) You can copy GNU software from @w{@samp{ftp.gnu.org}}.
texinfo.texi(,10504) @end quotation
texinfo.texi(,10505) 
texinfo.texi(,10506) @cindex Non-breakable space
texinfo.texi(,10507) @cindex Unbreakable space
texinfo.texi(,10508) @cindex Tied space
texinfo.texi(,10509) You can also use @code{@@w} to produce a non-breakable space:
texinfo.texi(,10510) 
texinfo.texi(,10511) @example
texinfo.texi(,10512) None of the formatters will break at this@@w@{ @}space.
texinfo.texi(,10513) @end example
texinfo.texi(,10514) 
texinfo.texi(,10515) 
texinfo.texi(,10516) @node sp
texinfo.texi(,10517) @section @code{@@sp} @var{n}: Insert Blank Lines
texinfo.texi(,10518) @findex sp @r{(line spacing)}
texinfo.texi(,10519) @cindex Space, inserting vertical
texinfo.texi(,10520) @cindex Blank lines
texinfo.texi(,10521) @cindex Line spacing
texinfo.texi(,10522) 
texinfo.texi(,10523) A line beginning with and containing only @code{@@sp @var{n}}
texinfo.texi(,10524) generates @var{n} blank lines of space in both the printed manual and
texinfo.texi(,10525) the Info file.  @code{@@sp} also forces a paragraph break.  For
texinfo.texi(,10526) example,
texinfo.texi(,10527) 
texinfo.texi(,10528) @example
texinfo.texi(,10529) @@sp 2
texinfo.texi(,10530) @end example
texinfo.texi(,10531) 
texinfo.texi(,10532) @noindent
texinfo.texi(,10533) generates two blank lines.
texinfo.texi(,10534) 
texinfo.texi(,10535) The @code{@@sp} command is most often used in the title page.@refill
texinfo.texi(,10536) 
texinfo.texi(,10576) 
texinfo.texi(,10577) 
texinfo.texi(,10578) @node page
texinfo.texi(,10579) @section @code{@@page}: Start a New Page
texinfo.texi(,10580) @cindex Page breaks
texinfo.texi(,10581) @findex page
texinfo.texi(,10582) 
texinfo.texi(,10583) A line containing only @code{@@page} starts a new page in a printed
texinfo.texi(,10584) manual.  The command has no effect on Info files since they are not
texinfo.texi(,10585) paginated.  An @code{@@page} command is often used in the @code{@@titlepage}
texinfo.texi(,10586) section of a Texinfo file to start the copyright page.
texinfo.texi(,10587) 
texinfo.texi(,10588) 
texinfo.texi(,10589) @node group, need, page, Breaks
texinfo.texi(,10590) @comment  node-name,  next,  previous,  up
texinfo.texi(,10591) @section @code{@@group}: Prevent Page Breaks
texinfo.texi(,10592) @cindex Group (hold text together vertically)
texinfo.texi(,10593) @cindex Holding text together vertically
texinfo.texi(,10594) @cindex Vertically holding text together
texinfo.texi(,10595) @findex group
texinfo.texi(,10596) 
texinfo.texi(,10597) The @code{@@group} command (on a line by itself) is used inside an
texinfo.texi(,10598) @code{@@example} or similar construct to begin an unsplittable vertical
texinfo.texi(,10599) group, which will appear entirely on one page in the printed output.
texinfo.texi(,10600) The group is terminated by a line containing only @code{@@end group}.
texinfo.texi(,10601) These two lines produce no output of their own, and in the Info file
texinfo.texi(,10602) output they have no effect at all.@refill
texinfo.texi(,10603) 
texinfo.texi(,10604) @c Once said that these environments
texinfo.texi(,10605) @c turn off vertical spacing between ``paragraphs''.
texinfo.texi(,10606) @c Also, quotation used to work, but doesn't in texinfo-2.72
texinfo.texi(,10607) Although @code{@@group} would make sense conceptually in a wide
texinfo.texi(,10608) variety of contexts, its current implementation works reliably only
texinfo.texi(,10609) within @code{@@example} and variants, and within @code{@@display},
texinfo.texi(,10610) @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
texinfo.texi(,10611) @xref{Quotations and Examples}.  (What all these commands have in
texinfo.texi(,10612) common is that each line of input produces a line of output.)  In
texinfo.texi(,10613) other contexts, @code{@@group} can cause anomalous vertical
texinfo.texi(,10614) spacing.@refill
texinfo.texi(,10615) 
texinfo.texi(,10616) @need 750
texinfo.texi(,10617) This formatting requirement means that you should write:
texinfo.texi(,10618) 
texinfo.texi(,10619) @example
texinfo.texi(,10620) @group
texinfo.texi(,10621) @@example
texinfo.texi(,10622) @@group
texinfo.texi(,10623) @dots{}
texinfo.texi(,10624) @@end group
texinfo.texi(,10625) @@end example
texinfo.texi(,10626) @end group
texinfo.texi(,10627) @end example
texinfo.texi(,10628) 
texinfo.texi(,10629) @noindent
texinfo.texi(,10630) with the @code{@@group} and @code{@@end group} commands inside the
texinfo.texi(,10631) @code{@@example} and @code{@@end example} commands.
texinfo.texi(,10632) 
texinfo.texi(,10633) The @code{@@group} command is most often used to hold an example
texinfo.texi(,10634) together on one page.  In this Texinfo manual, more than 100 examples
texinfo.texi(,10635) contain text that is enclosed between @code{@@group} and @code{@@end
texinfo.texi(,10636) group}.
texinfo.texi(,10637) 
texinfo.texi(,10638) If you forget to end a group, you may get strange and unfathomable
texinfo.texi(,10639) error messages when you run @TeX{}.  This is because @TeX{} keeps
texinfo.texi(,10640) trying to put the rest of the Texinfo file onto the one page and does
texinfo.texi(,10641) not start to generate error messages until it has processed
texinfo.texi(,10642) considerable text.  It is a good rule of thumb to look for a missing
texinfo.texi(,10643) @code{@@end group} if you get incomprehensible error messages in
texinfo.texi(,10644) @TeX{}.@refill
texinfo.texi(,10645) 
texinfo.texi(,10646) @node need,  , group, Breaks
texinfo.texi(,10647) @comment  node-name,  next,  previous,  up
texinfo.texi(,10648) @section @code{@@need @var{mils}}: Prevent Page Breaks
texinfo.texi(,10649) @cindex Need space at page bottom
texinfo.texi(,10650) @findex need
texinfo.texi(,10651) 
texinfo.texi(,10652) A line containing only @code{@@need @var{n}} starts
texinfo.texi(,10653) a new page in a printed manual if fewer than @var{n} mils (thousandths
texinfo.texi(,10654) of an inch) remain on the current page.  Do not use
texinfo.texi(,10655) braces around the argument @var{n}.  The @code{@@need} command has no
texinfo.texi(,10656) effect on Info files since they are not paginated.@refill
texinfo.texi(,10657) 
texinfo.texi(,10658) @need 800
texinfo.texi(,10659) This paragraph is preceded by an @code{@@need} command that tells
texinfo.texi(,10660) @TeX{} to start a new page if fewer than 800 mils (eight-tenths
texinfo.texi(,10661) inch) remain on the page.  It looks like this:@refill
texinfo.texi(,10662) 
texinfo.texi(,10663) @example
texinfo.texi(,10664) @group
texinfo.texi(,10665) @@need 800
texinfo.texi(,10666) This paragraph is preceded by @dots{}
texinfo.texi(,10667) @end group
texinfo.texi(,10668) @end example
texinfo.texi(,10669) 
texinfo.texi(,10670) The @code{@@need} command is useful for preventing orphans (single
texinfo.texi(,10671) lines at the bottoms of printed pages).@refill
texinfo.texi(,10672) 
texinfo.texi(,10673) 
texinfo.texi(,10674) @node Definition Commands
texinfo.texi(,10675) @chapter Definition Commands
texinfo.texi(,10676) @cindex Definition commands
texinfo.texi(,10677) 
texinfo.texi(,10678) The @code{@@deffn} command and the other @dfn{definition commands}
texinfo.texi(,10679) enable you to describe functions, variables, macros, commands, user
texinfo.texi(,10680) options, special forms and other such artifacts in a uniform
texinfo.texi(,10681) format.@refill
texinfo.texi(,10682) 
texinfo.texi(,10683) In the Info file, a definition causes the entity
texinfo.texi(,10684) category---`Function', `Variable', or whatever---to appear at the
texinfo.texi(,10685) beginning of the first line of the definition, followed by the
texinfo.texi(,10686) entity's name and arguments.  In the printed manual, the command
texinfo.texi(,10687) causes @TeX{} to print the entity's name and its arguments on the left
texinfo.texi(,10688) margin and print the category next to the right margin.  In both
texinfo.texi(,10689) output formats, the body of the definition is indented.  Also, the
texinfo.texi(,10690) name of the entity is entered into the appropriate index:
texinfo.texi(,10691) @code{@@deffn} enters the name into the index of functions,
texinfo.texi(,10692) @code{@@defvr} enters it into the index of variables, and so
texinfo.texi(,10693) on.@refill
texinfo.texi(,10694) 
texinfo.texi(,10695) A manual need not and should not contain more than one definition for
texinfo.texi(,10696) a given name.  An appendix containing a summary should use
texinfo.texi(,10697) @code{@@table} rather than the definition commands.@refill
texinfo.texi(,10698) 
texinfo.texi(,10699) @menu
texinfo.texi(,10700) * Def Cmd Template::            How to structure a description using a
texinfo.texi(,10701)                                   definition command.
texinfo.texi(,10702) * Optional Arguments::          How to handle optional and repeated arguments.
texinfo.texi(,10703) * deffnx::                      How to group two or more `first' lines.
texinfo.texi(,10704) * Def Cmds in Detail::          All the definition commands.
texinfo.texi(,10705) * Def Cmd Conventions::         Conventions for writing definitions.
texinfo.texi(,10706) * Sample Function Definition::  
texinfo.texi(,10707) @end menu
texinfo.texi(,10708) 
texinfo.texi(,10709) @node Def Cmd Template, Optional Arguments, Definition Commands, Definition Commands
texinfo.texi(,10710) @section The Template for a Definition
texinfo.texi(,10711) @cindex Definition template
texinfo.texi(,10712) @cindex Template for a definition
texinfo.texi(,10713) 
texinfo.texi(,10714) The @code{@@deffn} command is used for definitions of entities that
texinfo.texi(,10715) resemble functions.  To write a definition using the @code{@@deffn}
texinfo.texi(,10716) command, write the @code{@@deffn} command at the beginning of a line
texinfo.texi(,10717) and follow it on the same line by the category of the entity, the name
texinfo.texi(,10718) of the entity itself, and its arguments (if any).  Then write the body
texinfo.texi(,10719) of the definition on succeeding lines.  (You may embed examples in the
texinfo.texi(,10720) body.)  Finally, end the definition with an @code{@@end deffn} command
texinfo.texi(,10721) written on a line of its own.  (The other definition commands follow
texinfo.texi(,10722) the same format.)@refill
texinfo.texi(,10723) 
texinfo.texi(,10724) The template for a definition looks like this:
texinfo.texi(,10725) 
texinfo.texi(,10726) @example
texinfo.texi(,10727) @group
texinfo.texi(,10728) @@deffn @var{category} @var{name} @var{arguments}@dots{}
texinfo.texi(,10729) @var{body-of-definition}
texinfo.texi(,10730) @@end deffn
texinfo.texi(,10731) @end group
texinfo.texi(,10732) @end example
texinfo.texi(,10733) 
texinfo.texi(,10734) @need 700
texinfo.texi(,10735) @noindent
texinfo.texi(,10736) For example,
texinfo.texi(,10737) 
texinfo.texi(,10738) @example
texinfo.texi(,10739) @group
texinfo.texi(,10740) @@deffn Command forward-word count
texinfo.texi(,10741) This command moves point forward @@var@{count@} words
texinfo.texi(,10742) (or backward if @@var@{count@} is negative). @dots{}
texinfo.texi(,10743) @@end deffn
texinfo.texi(,10744) @end group
texinfo.texi(,10745) @end example
texinfo.texi(,10746) 
texinfo.texi(,10747) @noindent
texinfo.texi(,10748) produces
texinfo.texi(,10749) 
texinfo.texi(,10750) @quotation
texinfo.texi(,10751) @deffn Command forward-word count
texinfo.texi(,10752) This function moves point forward @var{count} words
texinfo.texi(,10753) (or backward if @var{count} is negative). @dots{}
texinfo.texi(,10754) @end deffn
texinfo.texi(,10755) @end quotation
texinfo.texi(,10756) 
texinfo.texi(,10757) Capitalize the category name like a title.  If the name of the
texinfo.texi(,10758) category contains spaces, as in the phrase `Interactive Command',
texinfo.texi(,10759) write braces around it.  For example:@refill
texinfo.texi(,10760) 
texinfo.texi(,10761) @example
texinfo.texi(,10762) @group
texinfo.texi(,10763) @@deffn @{Interactive Command@} isearch-forward
texinfo.texi(,10764) @dots{}
texinfo.texi(,10765) @@end deffn
texinfo.texi(,10766) @end group
texinfo.texi(,10767) @end example
texinfo.texi(,10768) 
texinfo.texi(,10769) @noindent
texinfo.texi(,10770) Otherwise, the second word will be mistaken for the name of the
texinfo.texi(,10771) entity.@refill
texinfo.texi(,10772) 
texinfo.texi(,10773) Some of the definition commands are more general than others.  The
texinfo.texi(,10774) @code{@@deffn} command, for example, is the general definition command
texinfo.texi(,10775) for functions and the like---for entities that may take arguments.  When
texinfo.texi(,10776) you use this command, you specify the category to which the entity
texinfo.texi(,10777) belongs.  The @code{@@deffn} command possesses three predefined,
texinfo.texi(,10778) specialized variations, @code{@@defun}, @code{@@defmac}, and
texinfo.texi(,10779) @code{@@defspec}, that specify the category for you: ``Function'',
texinfo.texi(,10780) ``Macro'', and ``Special Form'' respectively.  (In Lisp, a special form
texinfo.texi(,10781) is an entity much like a function.)  The @code{@@defvr} command also is
texinfo.texi(,10782) accompanied by several predefined, specialized variations for describing
texinfo.texi(,10783) particular kinds of variables.@refill
texinfo.texi(,10784) 
texinfo.texi(,10785) The template for a specialized definition, such as @code{@@defun}, is
texinfo.texi(,10786) similar to the template for a generalized definition, except that you
texinfo.texi(,10787) do not need to specify the category:@refill
texinfo.texi(,10788) 
texinfo.texi(,10789) @example
texinfo.texi(,10790) @group
texinfo.texi(,10791) @@defun @var{name} @var{arguments}@dots{}
texinfo.texi(,10792) @var{body-of-definition}
texinfo.texi(,10793) @@end defun
texinfo.texi(,10794) @end group
texinfo.texi(,10795) @end example
texinfo.texi(,10796) 
texinfo.texi(,10797) @noindent
texinfo.texi(,10798) Thus,
texinfo.texi(,10799) 
texinfo.texi(,10800) @example
texinfo.texi(,10801) @group
texinfo.texi(,10802) @@defun buffer-end flag
texinfo.texi(,10803) This function returns @@code@{(point-min)@} if @@var@{flag@}
texinfo.texi(,10804) is less than 1, @@code@{(point-max)@} otherwise.
texinfo.texi(,10805) @dots{}
texinfo.texi(,10806) @@end defun
texinfo.texi(,10807) @end group
texinfo.texi(,10808) @end example
texinfo.texi(,10809) 
texinfo.texi(,10810) @noindent
texinfo.texi(,10811) produces
texinfo.texi(,10812) 
texinfo.texi(,10813) @quotation
texinfo.texi(,10814) @defun buffer-end flag
texinfo.texi(,10815) This function returns @code{(point-min)} if @var{flag} is less than 1,
texinfo.texi(,10816) @code{(point-max)} otherwise.  @dots{}
texinfo.texi(,10817) @end defun
texinfo.texi(,10818) @end quotation
texinfo.texi(,10819) 
texinfo.texi(,10820) @noindent
texinfo.texi(,10821) @xref{Sample Function Definition, Sample Function Definition, A Sample
texinfo.texi(,10822) Function Definition}, for a more detailed example of a function
texinfo.texi(,10823) definition, including the use of @code{@@example} inside the
texinfo.texi(,10824) definition.@refill
texinfo.texi(,10825) 
texinfo.texi(,10826) The other specialized commands work like @code{@@defun}.@refill
texinfo.texi(,10827) 
texinfo.texi(,10828) @cindex Macros in definition commands
texinfo.texi(,10829) Note that, due to implementation difficulties, macros are not expanded
texinfo.texi(,10830) in @code{@@deffn} and all the other definition commands.
texinfo.texi(,10831) 
texinfo.texi(,10832) @node Optional Arguments, deffnx, Def Cmd Template, Definition Commands
texinfo.texi(,10833) @section Optional and Repeated Arguments
texinfo.texi(,10834) @cindex Optional and repeated arguments
texinfo.texi(,10835) @cindex Repeated and optional arguments
texinfo.texi(,10836) @cindex Arguments, repeated and optional
texinfo.texi(,10837) @cindex Syntax, optional & repeated arguments
texinfo.texi(,10838) @cindex Meta-syntactic chars for arguments
texinfo.texi(,10839) 
texinfo.texi(,10840) Some entities take optional or repeated arguments, which may be
texinfo.texi(,10841) specified by a distinctive glyph that uses square brackets and
texinfo.texi(,10842) ellipses.  For @w{example}, a special form often breaks its argument list
texinfo.texi(,10843) into separate arguments in more complicated ways than a
texinfo.texi(,10844) straightforward function.@refill
texinfo.texi(,10845) 
texinfo.texi(,10858) @c The following looks better in Info (no `r', `samp' and `code'):
texinfo.texi(,10860) An argument enclosed within square brackets is optional.
texinfo.texi(,10861) Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
texinfo.texi(,10862) An argument followed by an ellipsis is optional
texinfo.texi(,10863) and may be repeated more than once.
texinfo.texi(,10864) @c This is consistent with Emacs Lisp Reference manual
texinfo.texi(,10865) Thus, @var{repeated-args}@dots{} stands for zero or more arguments.
texinfo.texi(,10866) Parentheses are used when several arguments are grouped
texinfo.texi(,10867) into additional levels of list structure in Lisp.
texinfo.texi(,10869) 
texinfo.texi(,10870) Here is the @code{@@defspec} line of an example of an imaginary
texinfo.texi(,10871) special form:@refill
texinfo.texi(,10872) 
texinfo.texi(,10873) @quotation
texinfo.texi(,10874) @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
texinfo.texi(,10875) @end defspec
texinfo.texi(,10879) @end quotation
texinfo.texi(,10880) 
texinfo.texi(,10881) @noindent
texinfo.texi(,10882) In this example, the arguments @var{from} and @var{to} are optional,
texinfo.texi(,10883) but must both be present or both absent.  If they are present,
texinfo.texi(,10884) @var{inc} may optionally be specified as well.  These arguments are
texinfo.texi(,10885) grouped with the argument @var{var} into a list, to distinguish them
texinfo.texi(,10886) from @var{body}, which includes all remaining elements of the
texinfo.texi(,10887) form.@refill
texinfo.texi(,10888) 
texinfo.texi(,10889) In a Texinfo source file, this @code{@@defspec} line is written like
texinfo.texi(,10890) this (except it would not be split over two lines, as it is in this
texinfo.texi(,10891) example).@refill
texinfo.texi(,10892) 
texinfo.texi(,10893) @example
texinfo.texi(,10894) @group
texinfo.texi(,10895) @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
texinfo.texi(,10896)      [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
texinfo.texi(,10897) @end group
texinfo.texi(,10898) @end example
texinfo.texi(,10899) 
texinfo.texi(,10900) @noindent
texinfo.texi(,10901) The function is listed in the Command and Variable Index under
texinfo.texi(,10902) @samp{foobar}.@refill
texinfo.texi(,10903) 
texinfo.texi(,10904) @node deffnx, Def Cmds in Detail, Optional Arguments, Definition Commands
texinfo.texi(,10905) @section Two or More `First' Lines
texinfo.texi(,10906) @cindex Two `First' Lines for @code{@@deffn}
texinfo.texi(,10907) @cindex Grouping two definitions together
texinfo.texi(,10908) @cindex Definitions grouped together
texinfo.texi(,10909) @findex deffnx
texinfo.texi(,10910) 
texinfo.texi(,10911) To create two or more `first' or header lines for a definition, follow
texinfo.texi(,10912) the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
texinfo.texi(,10913) The @code{@@deffnx} command works exactly like @code{@@deffn}
texinfo.texi(,10914) except that it does not generate extra vertical white space between it
texinfo.texi(,10915) and the preceding line.@refill
texinfo.texi(,10916) 
texinfo.texi(,10917) @need 1000
texinfo.texi(,10918) For example,
texinfo.texi(,10919) 
texinfo.texi(,10920) @example
texinfo.texi(,10921) @group
texinfo.texi(,10922) @@deffn @{Interactive Command@} isearch-forward
texinfo.texi(,10923) @@deffnx @{Interactive Command@} isearch-backward
texinfo.texi(,10924) These two search commands are similar except @dots{}
texinfo.texi(,10925) @@end deffn
texinfo.texi(,10926) @end group
texinfo.texi(,10927) @end example
texinfo.texi(,10928) 
texinfo.texi(,10929) @noindent
texinfo.texi(,10930) produces
texinfo.texi(,10931) 
texinfo.texi(,10932) @deffn {Interactive Command} isearch-forward
texinfo.texi(,10933) @deffnx {Interactive Command} isearch-backward
texinfo.texi(,10934) These two search commands are similar except @dots{}
texinfo.texi(,10935) @end deffn
texinfo.texi(,10936) 
texinfo.texi(,10937) Each definition command has an `x' form: @code{@@defunx},
texinfo.texi(,10938) @code{@@defvrx}, @code{@@deftypefunx}, etc.
texinfo.texi(,10939) 
texinfo.texi(,10940) The `x' forms work just like @code{@@itemx}; see @ref{itemx, , @code{@@itemx}}.
texinfo.texi(,10941) 
texinfo.texi(,10942) @node Def Cmds in Detail, Def Cmd Conventions, deffnx, Definition Commands
texinfo.texi(,10943) @section The Definition Commands
texinfo.texi(,10944) 
texinfo.texi(,10945) Texinfo provides more than a dozen definition commands, all of which
texinfo.texi(,10946) are described in this section.@refill
texinfo.texi(,10947) 
texinfo.texi(,10948) The definition commands automatically enter the name of the entity in
texinfo.texi(,10949) the appropriate index: for example, @code{@@deffn}, @code{@@defun},
texinfo.texi(,10950) and @code{@@defmac} enter function names in the index of functions;
texinfo.texi(,10951) @code{@@defvr} and @code{@@defvar} enter variable names in the index
texinfo.texi(,10952) of variables.@refill
texinfo.texi(,10953) 
texinfo.texi(,10954) Although the examples that follow mostly illustrate Lisp, the commands
texinfo.texi(,10955) can be used for other programming languages.@refill
texinfo.texi(,10956) 
texinfo.texi(,10957) @menu
texinfo.texi(,10958) * Functions Commands::          Commands for functions and similar entities.
texinfo.texi(,10959) * Variables Commands::          Commands for variables and similar entities.
texinfo.texi(,10960) * Typed Functions::             Commands for functions in typed languages.
texinfo.texi(,10961) * Typed Variables::             Commands for variables in typed languages.
texinfo.texi(,10962) * Abstract Objects::            Commands for object-oriented programming.
texinfo.texi(,10963) * Data Types::                  The definition command for data types.
texinfo.texi(,10964) @end menu
texinfo.texi(,10965) 
texinfo.texi(,10966) @node Functions Commands, Variables Commands, Def Cmds in Detail, Def Cmds in Detail
texinfo.texi(,10967) @subsection Functions and Similar Entities
texinfo.texi(,10968) 
texinfo.texi(,10969) This section describes the commands for describing functions and similar
texinfo.texi(,10970) entities:@refill
texinfo.texi(,10971) 
texinfo.texi(,10972) @table @code
texinfo.texi(,10973) @findex deffn
texinfo.texi(,10974) @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
texinfo.texi(,10975) The @code{@@deffn} command is the general definition command for
texinfo.texi(,10976) functions, interactive commands, and similar entities that may take
texinfo.texi(,10977) arguments.  You must choose a term to describe the category of entity
texinfo.texi(,10978) being defined; for example, ``Function'' could be used if the entity is
texinfo.texi(,10979) a function.  The @code{@@deffn} command is written at the beginning of a
texinfo.texi(,10980) line and is followed on the same line by the category of entity being
texinfo.texi(,10981) described, the name of this particular entity, and its arguments, if
texinfo.texi(,10982) any.  Terminate the definition with @code{@@end deffn} on a line of its
texinfo.texi(,10983) own.@refill
texinfo.texi(,10984) 
texinfo.texi(,10985) @need 750
texinfo.texi(,10986) For example, here is a definition:
texinfo.texi(,10987) 
texinfo.texi(,10988) @example
texinfo.texi(,10989) @group
texinfo.texi(,10990) @@deffn Command forward-char nchars
texinfo.texi(,10991) Move point forward @@var@{nchars@} characters.
texinfo.texi(,10992) @@end deffn
texinfo.texi(,10993) @end group
texinfo.texi(,10994) @end example
texinfo.texi(,10995) 
texinfo.texi(,10996) @noindent
texinfo.texi(,10997) This shows a rather terse definition for a ``command'' named
texinfo.texi(,10998) @code{forward-char} with one argument, @var{nchars}.
texinfo.texi(,10999) 
texinfo.texi(,11000) @code{@@deffn} prints argument names such as @var{nchars} in italics or
texinfo.texi(,11001) upper case, as if @code{@@var} had been used, because we think of these
texinfo.texi(,11002) names as metasyntactic variables---they stand for the actual argument
texinfo.texi(,11003) values.  Within the text of the description, write an argument name
texinfo.texi(,11004) explicitly with @code{@@var} to refer to the value of the argument.  In
texinfo.texi(,11005) the example above, we used @samp{@@var@{nchars@}} in this way.
texinfo.texi(,11006) 
texinfo.texi(,11007) The template for @code{@@deffn} is:
texinfo.texi(,11008) 
texinfo.texi(,11009) @example
texinfo.texi(,11010) @group
texinfo.texi(,11011) @@deffn @var{category} @var{name} @var{arguments}@dots{}
texinfo.texi(,11012) @var{body-of-definition}
texinfo.texi(,11013) @@end deffn
texinfo.texi(,11014) @end group
texinfo.texi(,11015) @end example
texinfo.texi(,11016) 
texinfo.texi(,11017) @findex defun
texinfo.texi(,11018) @item @@defun @var{name} @var{arguments}@dots{}
texinfo.texi(,11019) The @code{@@defun} command is the definition command for functions.
texinfo.texi(,11020) @code{@@defun} is equivalent to @samp{@@deffn Function
texinfo.texi(,11021) @dots{}}.@refill
texinfo.texi(,11022) 
texinfo.texi(,11023) @need 800
texinfo.texi(,11024) @noindent
texinfo.texi(,11025) For example,
texinfo.texi(,11026) 
texinfo.texi(,11027) @example
texinfo.texi(,11028) @group
texinfo.texi(,11029) @@defun set symbol new-value
texinfo.texi(,11030) Change the value of the symbol @@var@{symbol@}
texinfo.texi(,11031) to @@var@{new-value@}.
texinfo.texi(,11032) @@end defun
texinfo.texi(,11033) @end group
texinfo.texi(,11034) @end example
texinfo.texi(,11035) 
texinfo.texi(,11036) @noindent
texinfo.texi(,11037) shows a rather terse definition for a function @code{set} whose
texinfo.texi(,11038) arguments are @var{symbol} and @var{new-value}.  The argument names on
texinfo.texi(,11039) the @code{@@defun} line automatically appear in italics or upper case as
texinfo.texi(,11040) if they were enclosed in @code{@@var}.  Terminate the definition with
texinfo.texi(,11041) @code{@@end defun} on a line of its own.@refill
texinfo.texi(,11042) 
texinfo.texi(,11043) The template is:
texinfo.texi(,11044) 
texinfo.texi(,11045) @example
texinfo.texi(,11046) @group
texinfo.texi(,11047) @@defun @var{function-name} @var{arguments}@dots{}
texinfo.texi(,11048) @var{body-of-definition}
texinfo.texi(,11049) @@end defun
texinfo.texi(,11050) @end group
texinfo.texi(,11051) @end example
texinfo.texi(,11052) 
texinfo.texi(,11053) @code{@@defun} creates an entry in the index of functions.
texinfo.texi(,11054) 
texinfo.texi(,11055) @findex defmac
texinfo.texi(,11056) @item @@defmac @var{name} @var{arguments}@dots{}
texinfo.texi(,11057) The @code{@@defmac} command is the definition command for macros.
texinfo.texi(,11058) @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
texinfo.texi(,11059) works like @code{@@defun}.@refill
texinfo.texi(,11060) 
texinfo.texi(,11061) @findex defspec
texinfo.texi(,11062) @item @@defspec @var{name} @var{arguments}@dots{}
texinfo.texi(,11063) The @code{@@defspec} command is the definition command for special
texinfo.texi(,11064) forms.  (In Lisp, a special form is an entity much like a function,
texinfo.texi(,11065) @pxref{Special Forms,,, elisp, GNU Emacs Lisp Reference Manual}.)
texinfo.texi(,11066) @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
texinfo.texi(,11067) @dots{}} and works like @code{@@defun}.@refill
texinfo.texi(,11068) @end table
texinfo.texi(,11069) 
texinfo.texi(,11070) @node Variables Commands, Typed Functions, Functions Commands, Def Cmds in Detail
texinfo.texi(,11071) @subsection Variables and Similar Entities
texinfo.texi(,11072) 
texinfo.texi(,11073) Here are the commands for defining variables and similar
texinfo.texi(,11074) entities:@refill
texinfo.texi(,11075) 
texinfo.texi(,11076) @table @code
texinfo.texi(,11077) @findex defvr
texinfo.texi(,11078) @item @@defvr @var{category} @var{name}
texinfo.texi(,11079) The @code{@@defvr} command is a general definition command for
texinfo.texi(,11080) something like a variable---an entity that records a value.  You must
texinfo.texi(,11081) choose a term to describe the category of entity being defined; for
texinfo.texi(,11082) example, ``Variable'' could be used if the entity is a variable.
texinfo.texi(,11083) Write the @code{@@defvr} command at the beginning of a line and
texinfo.texi(,11084) follow it on the same line by the category of the entity and the
texinfo.texi(,11085) name of the entity.
texinfo.texi(,11086) 
texinfo.texi(,11087) Capitalize the category name like a title.  If the name of the category
texinfo.texi(,11088) contains spaces, as in the name ``User Option'', enclose it in braces.
texinfo.texi(,11089) Otherwise, the second word will be mistaken for the name of the entity.
texinfo.texi(,11090) For example,
texinfo.texi(,11091) 
texinfo.texi(,11092) @example
texinfo.texi(,11093) @group
texinfo.texi(,11094) @@defvr @{User Option@} fill-column
texinfo.texi(,11095) This buffer-local variable specifies
texinfo.texi(,11096) the maximum width of filled lines.
texinfo.texi(,11097) @dots{}
texinfo.texi(,11098) @@end defvr
texinfo.texi(,11099) @end group
texinfo.texi(,11100) @end example
texinfo.texi(,11101) 
texinfo.texi(,11102) Terminate the definition with @code{@@end defvr} on a line of its
texinfo.texi(,11103) own.@refill
texinfo.texi(,11104) 
texinfo.texi(,11105) The template is:
texinfo.texi(,11106) 
texinfo.texi(,11107) @example
texinfo.texi(,11108) @group
texinfo.texi(,11109) @@defvr @var{category} @var{name}
texinfo.texi(,11110) @var{body-of-definition}
texinfo.texi(,11111) @@end defvr
texinfo.texi(,11112) @end group
texinfo.texi(,11113) @end example
texinfo.texi(,11114) 
texinfo.texi(,11115) @code{@@defvr} creates an entry in the index of variables for @var{name}.
texinfo.texi(,11116) 
texinfo.texi(,11117) @findex defvar
texinfo.texi(,11118) @item @@defvar @var{name}
texinfo.texi(,11119) The @code{@@defvar} command is the definition command for variables.
texinfo.texi(,11120) @code{@@defvar} is equivalent to @samp{@@defvr Variable
texinfo.texi(,11121) @dots{}}.@refill
texinfo.texi(,11122) 
texinfo.texi(,11123) @need 750
texinfo.texi(,11124) For example:
texinfo.texi(,11125) 
texinfo.texi(,11126) @example
texinfo.texi(,11127) @group
texinfo.texi(,11128) @@defvar kill-ring
texinfo.texi(,11129) @dots{}
texinfo.texi(,11130) @@end defvar
texinfo.texi(,11131) @end group
texinfo.texi(,11132) @end example
texinfo.texi(,11133) 
texinfo.texi(,11134) The template is:
texinfo.texi(,11135) 
texinfo.texi(,11136) @example
texinfo.texi(,11137) @group
texinfo.texi(,11138) @@defvar @var{name}
texinfo.texi(,11139) @var{body-of-definition}
texinfo.texi(,11140) @@end defvar
texinfo.texi(,11141) @end group
texinfo.texi(,11142) @end example
texinfo.texi(,11143) 
texinfo.texi(,11144) @code{@@defvar} creates an entry in the index of variables for
texinfo.texi(,11145) @var{name}.@refill
texinfo.texi(,11146) 
texinfo.texi(,11147) @findex defopt
texinfo.texi(,11148) @item @@defopt @var{name}
texinfo.texi(,11149) @cindex User options, marking
texinfo.texi(,11150) The @code{@@defopt} command is the definition command for @dfn{user
texinfo.texi(,11151) options}, i.e., variables intended for users to change according to
texinfo.texi(,11152) taste; Emacs has many such (@pxref{Variables,,, emacs, The GNU Emacs
texinfo.texi(,11153) Manual}).  @code{@@defopt} is equivalent to @samp{@@defvr @{User
texinfo.texi(,11154) Option@} @dots{}} and works like @code{@@defvar}.@refill
texinfo.texi(,11155) @end table
texinfo.texi(,11156) 
texinfo.texi(,11157) 
texinfo.texi(,11158) @node Typed Functions, Typed Variables, Variables Commands, Def Cmds in Detail
texinfo.texi(,11159) @subsection Functions in Typed Languages
texinfo.texi(,11160) 
texinfo.texi(,11161) The @code{@@deftypefn} command and its variations are for describing
texinfo.texi(,11162) functions in languages in which you must declare types of variables and
texinfo.texi(,11163) functions, such as C and C++.
texinfo.texi(,11164) 
texinfo.texi(,11165) @table @code
texinfo.texi(,11166) @findex deftypefn
texinfo.texi(,11167) @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,11168) The @code{@@deftypefn} command is the general definition command for
texinfo.texi(,11169) functions and similar entities that may take arguments and that are
texinfo.texi(,11170) typed.  The @code{@@deftypefn} command is written at the beginning of
texinfo.texi(,11171) a line and is followed on the same line by the category of entity
texinfo.texi(,11172) being described, the type of the returned value, the name of this
texinfo.texi(,11173) particular entity, and its arguments, if any.@refill
texinfo.texi(,11174) 
texinfo.texi(,11175) @need 800
texinfo.texi(,11176) @noindent
texinfo.texi(,11177) For example,
texinfo.texi(,11178) 
texinfo.texi(,11179) @example
texinfo.texi(,11180) @group
texinfo.texi(,11181) @@deftypefn @{Library Function@} int foobar
texinfo.texi(,11182)    (int @@var@{foo@}, float @@var@{bar@})
texinfo.texi(,11183) @dots{}
texinfo.texi(,11184) @@end deftypefn
texinfo.texi(,11185) @end group
texinfo.texi(,11186) @end example
texinfo.texi(,11187) 
texinfo.texi(,11188) @need 1000
texinfo.texi(,11189) @noindent
texinfo.texi(,11190) (where the text before the ``@dots{}'', shown above as two lines, would
texinfo.texi(,11191) actually be a single line in a real Texinfo file) produces the following
texinfo.texi(,11192) in Info:
texinfo.texi(,11193) 
texinfo.texi(,11194) @smallexample
texinfo.texi(,11195) @group
texinfo.texi(,11196) -- Library Function: int foobar (int FOO, float BAR)
texinfo.texi(,11197) @dots{}
texinfo.texi(,11198) @end group
texinfo.texi(,11199) @end smallexample
texinfo.texi(,11210) 
texinfo.texi(,11211) This means that @code{foobar} is a ``library function'' that returns an
texinfo.texi(,11212) @code{int}, and its arguments are @var{foo} (an @code{int}) and
texinfo.texi(,11213) @var{bar} (a @code{float}).@refill
texinfo.texi(,11214) 
texinfo.texi(,11215) The argument names that you write in @code{@@deftypefn} are not subject
texinfo.texi(,11216) to an implicit @code{@@var}---since the actual names of the arguments in
texinfo.texi(,11217) @code{@@deftypefn} are typically scattered among data type names and
texinfo.texi(,11218) keywords, Texinfo cannot find them without help.  Instead, you must write
texinfo.texi(,11219) @code{@@var} explicitly around the argument names.  In the example
texinfo.texi(,11220) above, the argument names are @samp{foo} and @samp{bar}.@refill
texinfo.texi(,11221) 
texinfo.texi(,11222) The template for @code{@@deftypefn} is:@refill
texinfo.texi(,11223) 
texinfo.texi(,11224) @example
texinfo.texi(,11225) @group
texinfo.texi(,11226) @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
texinfo.texi(,11227) @var{body-of-description}
texinfo.texi(,11228) @@end deftypefn
texinfo.texi(,11229) @end group
texinfo.texi(,11230) @end example
texinfo.texi(,11231) 
texinfo.texi(,11232) @noindent
texinfo.texi(,11233) Note that if the @var{category} or @var{data type} is more than one
texinfo.texi(,11234) word then it must be enclosed in braces to make it a single argument.@refill
texinfo.texi(,11235) 
texinfo.texi(,11236) If you are describing a procedure in a language that has packages,
texinfo.texi(,11237) such as Ada, you might consider using @code{@@deftypefn} in a manner
texinfo.texi(,11238) somewhat contrary to the convention described in the preceding
texinfo.texi(,11239) paragraphs.@refill
texinfo.texi(,11240) 
texinfo.texi(,11241) @need 800
texinfo.texi(,11242) @noindent
texinfo.texi(,11243) For example:
texinfo.texi(,11244) 
texinfo.texi(,11245) @example
texinfo.texi(,11246) @group
texinfo.texi(,11247) @@deftypefn stacks private push
texinfo.texi(,11248)         (@@var@{s@}:in out stack;
texinfo.texi(,11249)         @@var@{n@}:in integer)
texinfo.texi(,11250) @dots{}
texinfo.texi(,11251) @@end deftypefn
texinfo.texi(,11252) @end group
texinfo.texi(,11253) @end example
texinfo.texi(,11254) 
texinfo.texi(,11255) @noindent
texinfo.texi(,11256) (The @code{@@deftypefn} arguments are shown split into three lines, but
texinfo.texi(,11257) would be a single line in a real Texinfo file.)
texinfo.texi(,11258) 
texinfo.texi(,11259) In this instance, the procedure is classified as belonging to the
texinfo.texi(,11260) package @code{stacks} rather than classified as a `procedure' and its
texinfo.texi(,11261) data type is described as @code{private}.  (The name of the procedure
texinfo.texi(,11262) is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
texinfo.texi(,11263) 
texinfo.texi(,11264) @code{@@deftypefn} creates an entry in the index of functions for
texinfo.texi(,11265) @var{name}.@refill
texinfo.texi(,11266) 
texinfo.texi(,11267) @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,11268) @findex deftypefun
texinfo.texi(,11269) The @code{@@deftypefun} command is the specialized definition command
texinfo.texi(,11270) for functions in typed languages.  The command is equivalent to
texinfo.texi(,11271) @samp{@@deftypefn Function @dots{}}.@refill
texinfo.texi(,11272) 
texinfo.texi(,11273) @need 800
texinfo.texi(,11274) @noindent
texinfo.texi(,11275) Thus,
texinfo.texi(,11276) 
texinfo.texi(,11277) @smallexample
texinfo.texi(,11278) @group
texinfo.texi(,11279) @@deftypefun int foobar (int @@var@{foo@}, float @@var@{bar@})
texinfo.texi(,11280) @dots{}
texinfo.texi(,11281) @@end deftypefun
texinfo.texi(,11282) @end group
texinfo.texi(,11283) @end smallexample
texinfo.texi(,11284) 
texinfo.texi(,11285) @noindent
texinfo.texi(,11286) produces the following in Info:
texinfo.texi(,11287) 
texinfo.texi(,11288) @example
texinfo.texi(,11289) @group
texinfo.texi(,11290) -- Function: int foobar (int FOO, float BAR)
texinfo.texi(,11291) @dots{}
texinfo.texi(,11292) @end group
texinfo.texi(,11293) @end example
texinfo.texi(,11306) 
texinfo.texi(,11307) @need 800
texinfo.texi(,11308) The template is:
texinfo.texi(,11309) 
texinfo.texi(,11310) @example
texinfo.texi(,11311) @group
texinfo.texi(,11312) @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
texinfo.texi(,11313) @var{body-of-description}
texinfo.texi(,11314) @@end deftypefun
texinfo.texi(,11315) @end group
texinfo.texi(,11316) @end example
texinfo.texi(,11317) 
texinfo.texi(,11318) @code{@@deftypefun} creates an entry in the index of functions for
texinfo.texi(,11319) @var{name}.@refill
texinfo.texi(,11320) 
texinfo.texi(,11321) @end table
texinfo.texi(,11322) 
texinfo.texi(,11323) 
texinfo.texi(,11324) @node Typed Variables, Abstract Objects, Typed Functions, Def Cmds in Detail
texinfo.texi(,11325) @subsection Variables in Typed Languages
texinfo.texi(,11326) 
texinfo.texi(,11327) Variables in typed languages are handled in a manner similar to
texinfo.texi(,11328) functions in typed languages.  @xref{Typed Functions}.  The general
texinfo.texi(,11329) definition command @code{@@deftypevr} corresponds to
texinfo.texi(,11330) @code{@@deftypefn} and the specialized definition command
texinfo.texi(,11331) @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
texinfo.texi(,11332) 
texinfo.texi(,11333) @table @code
texinfo.texi(,11334) @findex deftypevr
texinfo.texi(,11335) @item @@deftypevr @var{category} @var{data-type} @var{name}
texinfo.texi(,11336) The @code{@@deftypevr} command is the general definition command for
texinfo.texi(,11337) something like a variable in a typed language---an entity that records
texinfo.texi(,11338) a value.  You must choose a term to describe the category of the
texinfo.texi(,11339) entity being defined; for example, ``Variable'' could be used if the
texinfo.texi(,11340) entity is a variable.@refill
texinfo.texi(,11341) 
texinfo.texi(,11342) The @code{@@deftypevr} command is written at the beginning of a line
texinfo.texi(,11343) and is followed on the same line by the category of the entity
texinfo.texi(,11344) being described, the data type, and the name of this particular
texinfo.texi(,11345) entity.@refill
texinfo.texi(,11346) 
texinfo.texi(,11347) @need 800
texinfo.texi(,11348) @noindent
texinfo.texi(,11349) For example:
texinfo.texi(,11350) 
texinfo.texi(,11351) @example
texinfo.texi(,11352) @group
texinfo.texi(,11353) @@deftypevr @{Global Flag@} int enable
texinfo.texi(,11354) @dots{}
texinfo.texi(,11355) @@end deftypevr
texinfo.texi(,11356) @end group
texinfo.texi(,11357) @end example
texinfo.texi(,11358) 
texinfo.texi(,11359) @noindent
texinfo.texi(,11360) produces the following in Info:
texinfo.texi(,11361) 
texinfo.texi(,11362) @example
texinfo.texi(,11363) @group
texinfo.texi(,11364) -- Global Flag: int enable
texinfo.texi(,11365) @dots{}
texinfo.texi(,11366) @end group
texinfo.texi(,11367) @end example
texinfo.texi(,11379) 
texinfo.texi(,11380) @need 800
texinfo.texi(,11381) The template is:
texinfo.texi(,11382) 
texinfo.texi(,11383) @example
texinfo.texi(,11384) @@deftypevr @var{category} @var{data-type} @var{name}
texinfo.texi(,11385) @var{body-of-description}
texinfo.texi(,11386) @@end deftypevr
texinfo.texi(,11387) @end example
texinfo.texi(,11388) 
texinfo.texi(,11389) @code{@@deftypevr} creates an entry in the index of variables for
texinfo.texi(,11390) @var{name}.@refill
texinfo.texi(,11391) 
texinfo.texi(,11392) @findex deftypevar
texinfo.texi(,11393) @item @@deftypevar @var{data-type} @var{name}
texinfo.texi(,11394) The @code{@@deftypevar} command is the specialized definition command
texinfo.texi(,11395) for variables in typed languages.  @code{@@deftypevar} is equivalent
texinfo.texi(,11396) to @samp{@@deftypevr Variable @dots{}}.@refill
texinfo.texi(,11397) 
texinfo.texi(,11398) @need 800
texinfo.texi(,11399) @noindent
texinfo.texi(,11400) For example:
texinfo.texi(,11401) 
texinfo.texi(,11402) @example
texinfo.texi(,11403) @group
texinfo.texi(,11404) @@deftypevar int fubar
texinfo.texi(,11405) @dots{}
texinfo.texi(,11406) @@end deftypevar
texinfo.texi(,11407) @end group
texinfo.texi(,11408) @end example
texinfo.texi(,11409) 
texinfo.texi(,11410) @noindent
texinfo.texi(,11411) produces the following in Info:
texinfo.texi(,11412) 
texinfo.texi(,11413) @example
texinfo.texi(,11414) @group
texinfo.texi(,11415) -- Variable: int fubar
texinfo.texi(,11416) @dots{}
texinfo.texi(,11417) @end group
texinfo.texi(,11418) @end example
texinfo.texi(,11431) 
texinfo.texi(,11432) @need 800
texinfo.texi(,11433) @noindent
texinfo.texi(,11434) The template is:
texinfo.texi(,11435) 
texinfo.texi(,11436) @example
texinfo.texi(,11437) @group
texinfo.texi(,11438) @@deftypevar @var{data-type} @var{name}
texinfo.texi(,11439) @var{body-of-description}
texinfo.texi(,11440) @@end deftypevar
texinfo.texi(,11441) @end group
texinfo.texi(,11442) @end example
texinfo.texi(,11443) 
texinfo.texi(,11444) @code{@@deftypevar} creates an entry in the index of variables for
texinfo.texi(,11445) @var{name}.@refill
texinfo.texi(,11446) @end table
texinfo.texi(,11447) 
texinfo.texi(,11448) @node Abstract Objects
texinfo.texi(,11449) @subsection Object-Oriented Programming
texinfo.texi(,11450) 
texinfo.texi(,11451) Here are the commands for formatting descriptions about abstract
texinfo.texi(,11452) objects, such as are used in object-oriented programming.  A class is
texinfo.texi(,11453) a defined type of abstract object.  An instance of a class is a
texinfo.texi(,11454) particular object that has the type of the class.  An instance
texinfo.texi(,11455) variable is a variable that belongs to the class but for which each
texinfo.texi(,11456) instance has its own value.@refill
texinfo.texi(,11457) 
texinfo.texi(,11458) In a definition, if the name of a class is truly a name defined in the
texinfo.texi(,11459) programming system for a class, then you should write an @code{@@code}
texinfo.texi(,11460) around it.  Otherwise, it is printed in the usual text font.@refill
texinfo.texi(,11461) 
texinfo.texi(,11462) @table @code
texinfo.texi(,11463) @findex defcv
texinfo.texi(,11464) @item @@defcv @var{category} @var{class} @var{name}
texinfo.texi(,11465) The @code{@@defcv} command is the general definition command for
texinfo.texi(,11466) variables associated with classes in object-oriented programming.  The
texinfo.texi(,11467) @code{@@defcv} command is followed by three arguments: the category of
texinfo.texi(,11468) thing being defined, the class to which it belongs, and its
texinfo.texi(,11469) name.  Thus,@refill
texinfo.texi(,11470) 
texinfo.texi(,11471) @example
texinfo.texi(,11472) @group
texinfo.texi(,11473) @@defcv @{Class Option@} Window border-pattern
texinfo.texi(,11474) @dots{}
texinfo.texi(,11475) @@end defcv
texinfo.texi(,11476) @end group
texinfo.texi(,11477) @end example
texinfo.texi(,11478) 
texinfo.texi(,11479) @noindent
texinfo.texi(,11480) illustrates how you would write the first line of a definition of the
texinfo.texi(,11481) @code{border-pattern} class option of the class @code{Window}.@refill
texinfo.texi(,11482) 
texinfo.texi(,11483) The template is:
texinfo.texi(,11484) @example
texinfo.texi(,11485) @group
texinfo.texi(,11486) @@defcv @var{category} @var{class} @var{name}
texinfo.texi(,11487) @dots{}
texinfo.texi(,11488) @@end defcv
texinfo.texi(,11489) @end group
texinfo.texi(,11490) @end example
texinfo.texi(,11491) 
texinfo.texi(,11492) @code{@@defcv} creates an entry in the index of variables.
texinfo.texi(,11493) 
texinfo.texi(,11494) @findex defivar
texinfo.texi(,11495) @item @@defivar @var{class} @var{name}
texinfo.texi(,11496) The @code{@@defivar} command is the definition command for instance
texinfo.texi(,11497) variables in object-oriented programming.  @code{@@defivar} is
texinfo.texi(,11498) equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}@refill
texinfo.texi(,11499) 
texinfo.texi(,11500) The template is:
texinfo.texi(,11501) @example
texinfo.texi(,11502) @group
texinfo.texi(,11503) @@defivar @var{class} @var{instance-variable-name}
texinfo.texi(,11504) @var{body-of-definition}
texinfo.texi(,11505) @@end defivar
texinfo.texi(,11506) @end group
texinfo.texi(,11507) @end example
texinfo.texi(,11508) 
texinfo.texi(,11509) @code{@@defivar} creates an entry in the index of variables.
texinfo.texi(,11510) 
texinfo.texi(,11511) @findex deftypeivar
texinfo.texi(,11512) @item @@deftypeivar @var{class} @var{data-type} @var{name}
texinfo.texi(,11513) The @code{@@deftypeivar} command is the definition command for typed
texinfo.texi(,11514) instance variables in object-oriented programming.  It is similar to
texinfo.texi(,11515) @code{@@defivar} with the addition of the @var{data-type} parameter to
texinfo.texi(,11516) specify the type of the instance variable.  @code{@@deftypeivar} creates an
texinfo.texi(,11517) entry in the index of variables.
texinfo.texi(,11518) 
texinfo.texi(,11519) @findex defop
texinfo.texi(,11520) @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
texinfo.texi(,11521) The @code{@@defop} command is the general definition command for
texinfo.texi(,11522) entities that may resemble methods in object-oriented programming.
texinfo.texi(,11523) These entities take arguments, as functions do, but are associated with
texinfo.texi(,11524) particular classes of objects.@refill
texinfo.texi(,11525) 
texinfo.texi(,11526) For example, some systems have constructs called @dfn{wrappers} that
texinfo.texi(,11527) are associated with classes as methods are, but that act more like
texinfo.texi(,11528) macros than like functions.  You could use @code{@@defop Wrapper} to
texinfo.texi(,11529) describe one of these.@refill
texinfo.texi(,11530) 
texinfo.texi(,11531) Sometimes it is useful to distinguish methods and @dfn{operations}.
texinfo.texi(,11532) You can think of an operation as the specification for a method.
texinfo.texi(,11533) Thus, a window system might specify that all window classes have a
texinfo.texi(,11534) method named @code{expose}; we would say that this window system
texinfo.texi(,11535) defines an @code{expose} operation on windows in general.  Typically,
texinfo.texi(,11536) the operation has a name and also specifies the pattern of arguments;
texinfo.texi(,11537) all methods that implement the operation must accept the same
texinfo.texi(,11538) arguments, since applications that use the operation do so without
texinfo.texi(,11539) knowing which method will implement it.@refill
texinfo.texi(,11540) 
texinfo.texi(,11541) Often it makes more sense to document operations than methods.  For
texinfo.texi(,11542) example, window application developers need to know about the
texinfo.texi(,11543) @code{expose} operation, but need not be concerned with whether a
texinfo.texi(,11544) given class of windows has its own method to implement this operation.
texinfo.texi(,11545) To describe this operation, you would write:@refill
texinfo.texi(,11546) 
texinfo.texi(,11547) @example
texinfo.texi(,11548) @@defop Operation windows expose
texinfo.texi(,11549) @end example
texinfo.texi(,11550) 
texinfo.texi(,11551) The @code{@@defop} command is written at the beginning of a line and
texinfo.texi(,11552) is followed on the same line by the overall name of the category of
texinfo.texi(,11553) operation, the name of the class of the operation, the name of the
texinfo.texi(,11554) operation, and its arguments, if any.@refill
texinfo.texi(,11555) 
texinfo.texi(,11556) The template is:
texinfo.texi(,11557) @example
texinfo.texi(,11558) @group
texinfo.texi(,11559) @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
texinfo.texi(,11560) @var{body-of-definition}
texinfo.texi(,11561) @@end defop
texinfo.texi(,11562) @end group
texinfo.texi(,11563) @end example
texinfo.texi(,11564) 
texinfo.texi(,11565) @code{@@defop} creates an entry, such as `@code{expose} on
texinfo.texi(,11566) @code{windows}', in the index of functions.@refill
texinfo.texi(,11567) 
texinfo.texi(,11568) @findex deftypeop
texinfo.texi(,11569) @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,11570) The @code{@@deftypeop} command is the definition command for typed
texinfo.texi(,11571) operations in object-oriented programming.  It is similar to
texinfo.texi(,11572) @code{@@defop} with the addition of the @var{data-type} parameter to
texinfo.texi(,11573) specify the return type of the method.  @code{@@deftypeop} creates an
texinfo.texi(,11574) entry in the index of functions.
texinfo.texi(,11575) 
texinfo.texi(,11576) @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
texinfo.texi(,11577) @findex defmethod
texinfo.texi(,11578) The @code{@@defmethod} command is the definition command for methods
texinfo.texi(,11579) in object-oriented programming.  A method is a kind of function that
texinfo.texi(,11580) implements an operation for a particular class of objects and its
texinfo.texi(,11581) subclasses.
texinfo.texi(,11588) 
texinfo.texi(,11589) @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
texinfo.texi(,11590) The command is written at the beginning of a line and is followed by
texinfo.texi(,11591) the name of the class of the method, the name of the method, and its
texinfo.texi(,11592) arguments, if any.@refill
texinfo.texi(,11593) 
texinfo.texi(,11594) @noindent
texinfo.texi(,11595) For example:
texinfo.texi(,11596) @example
texinfo.texi(,11597) @group
texinfo.texi(,11598) @@defmethod @code{bar-class} bar-method argument
texinfo.texi(,11599) @dots{}
texinfo.texi(,11600) @@end defmethod
texinfo.texi(,11601) @end group
texinfo.texi(,11602) @end example
texinfo.texi(,11603) 
texinfo.texi(,11604) @noindent
texinfo.texi(,11605) illustrates the definition for a method called @code{bar-method} of
texinfo.texi(,11606) the class @code{bar-class}.  The method takes an argument.@refill
texinfo.texi(,11607) 
texinfo.texi(,11608) The template is:
texinfo.texi(,11609) 
texinfo.texi(,11610) @example
texinfo.texi(,11611) @group
texinfo.texi(,11612) @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
texinfo.texi(,11613) @var{body-of-definition}
texinfo.texi(,11614) @@end defmethod
texinfo.texi(,11615) @end group
texinfo.texi(,11616) @end example
texinfo.texi(,11617) 
texinfo.texi(,11618) @code{@@defmethod} creates an entry, such as `@code{bar-method} on
texinfo.texi(,11619) @code{bar-class}', in the index of functions.@refill
texinfo.texi(,11620) 
texinfo.texi(,11621) 
texinfo.texi(,11622) @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,11623) @findex defmethod
texinfo.texi(,11624) The @code{@@deftypemethod} command is the definition command for methods
texinfo.texi(,11625) in object-oriented typed languages, such as C++ and Java.  It is similar
texinfo.texi(,11626) to the @code{@@defmethod} command with the addition of the
texinfo.texi(,11627) @var{data-type} parameter to specify the return type of the method.
texinfo.texi(,11628) 
texinfo.texi(,11629) @end table
texinfo.texi(,11630) 
texinfo.texi(,11631) 
texinfo.texi(,11632) @node Data Types
texinfo.texi(,11633) @subsection Data Types
texinfo.texi(,11634) 
texinfo.texi(,11635) Here is the command for data types:@refill
texinfo.texi(,11636) 
texinfo.texi(,11637) @table @code
texinfo.texi(,11638) @findex deftp
texinfo.texi(,11639) @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
texinfo.texi(,11640) The @code{@@deftp} command is the generic definition command for data
texinfo.texi(,11641) types.  The command is written at the beginning of a line and is
texinfo.texi(,11642) followed on the same line by the category, by the name of the type
texinfo.texi(,11643) (which is a word like @code{int} or @code{float}), and then by names of
texinfo.texi(,11644) attributes of objects of that type.  Thus, you could use this command
texinfo.texi(,11645) for describing @code{int} or @code{float}, in which case you could use
texinfo.texi(,11646) @code{data type} as the category.  (A data type is a category of
texinfo.texi(,11647) certain objects for purposes of deciding which operations can be
texinfo.texi(,11648) performed on them.)@refill
texinfo.texi(,11649) 
texinfo.texi(,11650) In Lisp, for example,  @dfn{pair} names a particular data
texinfo.texi(,11651) type, and an object of that type has two slots called the
texinfo.texi(,11652) @sc{car} and the @sc{cdr}.  Here is how you would write the first line
texinfo.texi(,11653) of a definition of @code{pair}.@refill
texinfo.texi(,11654) 
texinfo.texi(,11655) @example
texinfo.texi(,11656) @group
texinfo.texi(,11657) @@deftp @{Data type@} pair car cdr
texinfo.texi(,11658) @dots{}
texinfo.texi(,11659) @@end deftp
texinfo.texi(,11660) @end group
texinfo.texi(,11661) @end example
texinfo.texi(,11662) 
texinfo.texi(,11663) @need 950
texinfo.texi(,11664) The template is:
texinfo.texi(,11665) 
texinfo.texi(,11666) @example
texinfo.texi(,11667) @group
texinfo.texi(,11668) @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
texinfo.texi(,11669) @var{body-of-definition}
texinfo.texi(,11670) @@end deftp
texinfo.texi(,11671) @end group
texinfo.texi(,11672) @end example
texinfo.texi(,11673) 
texinfo.texi(,11674) @code{@@deftp} creates an entry in the index of data types.
texinfo.texi(,11675) @end table
texinfo.texi(,11676) 
texinfo.texi(,11677) @node Def Cmd Conventions, Sample Function Definition, Def Cmds in Detail, Definition Commands
texinfo.texi(,11678) @section Conventions for Writing Definitions
texinfo.texi(,11679) @cindex Definition conventions
texinfo.texi(,11680) @cindex Conventions for writing definitions
texinfo.texi(,11681) 
texinfo.texi(,11682) When you write a definition using @code{@@deffn}, @code{@@defun}, or
texinfo.texi(,11683) one of the other definition commands, please take care to use
texinfo.texi(,11684) arguments that indicate the meaning, as with the @var{count} argument
texinfo.texi(,11685) to the @code{forward-word} function.  Also, if the name of an argument
texinfo.texi(,11686) contains the name of a type, such as @var{integer}, take care that the
texinfo.texi(,11687) argument actually is of that type.@refill
texinfo.texi(,11688) 
texinfo.texi(,11689) @node Sample Function Definition,  , Def Cmd Conventions, Definition Commands
texinfo.texi(,11690) @section A Sample Function Definition
texinfo.texi(,11691) @cindex Function definitions
texinfo.texi(,11692) @cindex Command definitions
texinfo.texi(,11693) @cindex Macro definitions
texinfo.texi(,11694) @cindex Sample function definition
texinfo.texi(,11695) 
texinfo.texi(,11696) A function definition uses the @code{@@defun} and @code{@@end defun}
texinfo.texi(,11697) commands.  The name of the function follows immediately after the
texinfo.texi(,11698) @code{@@defun} command and it is followed, on the same line, by the
texinfo.texi(,11699) parameter list.@refill
texinfo.texi(,11700) 
texinfo.texi(,11701) Here is a definition from @ref{Calling Functions,,, elisp, The GNU Emacs
texinfo.texi(,11702) Lisp Reference Manual}.
texinfo.texi(,11703) 
texinfo.texi(,11704) @quotation
texinfo.texi(,11705) @defun apply function &rest arguments
texinfo.texi(,11706) @code{apply} calls @var{function} with @var{arguments}, just
texinfo.texi(,11707) like @code{funcall} but with one difference: the last of
texinfo.texi(,11708) @var{arguments} is a list of arguments to give to
texinfo.texi(,11709) @var{function}, rather than a single argument.  We also say
texinfo.texi(,11710) that this list is @dfn{appended} to the other arguments.
texinfo.texi(,11711) 
texinfo.texi(,11712) @code{apply} returns the result of calling @var{function}.
texinfo.texi(,11713) As with @code{funcall}, @var{function} must either be a Lisp
texinfo.texi(,11714) function or a primitive function; special forms and macros
texinfo.texi(,11715) do not make sense in @code{apply}.
texinfo.texi(,11716) 
texinfo.texi(,11717) @example
texinfo.texi(,11718) (setq f 'list)
texinfo.texi(,11719)      @result{} list
texinfo.texi(,11720) (apply f 'x 'y 'z)
texinfo.texi(,11721) @error{} Wrong type argument: listp, z
texinfo.texi(,11722) (apply '+ 1 2 '(3 4))
texinfo.texi(,11723)      @result{} 10
texinfo.texi(,11724) (apply '+ '(1 2 3 4))
texinfo.texi(,11725)      @result{} 10
texinfo.texi(,11726) 
texinfo.texi(,11727) (apply 'append '((a b c) nil (x y z) nil))
texinfo.texi(,11728)      @result{} (a b c x y z)
texinfo.texi(,11729) @end example
texinfo.texi(,11730) 
texinfo.texi(,11731) An interesting example of using @code{apply} is found in the description
texinfo.texi(,11732) of @code{mapcar}.@refill
texinfo.texi(,11733) @end defun
texinfo.texi(,11734) @end quotation
texinfo.texi(,11735) 
texinfo.texi(,11736) @need 1200
texinfo.texi(,11737) In the Texinfo source file, this example looks like this:
texinfo.texi(,11738) 
texinfo.texi(,11739) @example
texinfo.texi(,11740) @group
texinfo.texi(,11741) @@defun apply function &rest arguments
texinfo.texi(,11742) @@code@{apply@} calls @@var@{function@} with
texinfo.texi(,11743) @@var@{arguments@}, just like @@code@{funcall@} but with one
texinfo.texi(,11744) difference: the last of @@var@{arguments@} is a list of
texinfo.texi(,11745) arguments to give to @@var@{function@}, rather than a single
texinfo.texi(,11746) argument.  We also say that this list is @@dfn@{appended@}
texinfo.texi(,11747) to the other arguments.
texinfo.texi(,11748) @end group
texinfo.texi(,11749) 
texinfo.texi(,11750) @group
texinfo.texi(,11751) @@code@{apply@} returns the result of calling
texinfo.texi(,11752) @@var@{function@}.  As with @@code@{funcall@},
texinfo.texi(,11753) @@var@{function@} must either be a Lisp function or a
texinfo.texi(,11754) primitive function; special forms and macros do not make
texinfo.texi(,11755) sense in @@code@{apply@}.
texinfo.texi(,11756) @end group
texinfo.texi(,11757) 
texinfo.texi(,11758) @group
texinfo.texi(,11759) @@example
texinfo.texi(,11760) (setq f 'list)
texinfo.texi(,11761)      @@result@{@} list
texinfo.texi(,11762) (apply f 'x 'y 'z)
texinfo.texi(,11763) @@error@{@} Wrong type argument: listp, z
texinfo.texi(,11764) (apply '+ 1 2 '(3 4))
texinfo.texi(,11765)      @@result@{@} 10
texinfo.texi(,11766) (apply '+ '(1 2 3 4))
texinfo.texi(,11767)      @@result@{@} 10
texinfo.texi(,11768) 
texinfo.texi(,11769) (apply 'append '((a b c) nil (x y z) nil))
texinfo.texi(,11770)      @@result@{@} (a b c x y z)
texinfo.texi(,11771) @@end example
texinfo.texi(,11772) @end group
texinfo.texi(,11773) 
texinfo.texi(,11774) @group
texinfo.texi(,11775) An interesting example of using @@code@{apply@} is found
texinfo.texi(,11776) in the description of @@code@{mapcar@}.
texinfo.texi(,11777) @@end defun
texinfo.texi(,11778) @end group
texinfo.texi(,11779) @end example
texinfo.texi(,11780) 
texinfo.texi(,11781) @noindent
texinfo.texi(,11782) In this manual, this function is listed in the Command and Variable
texinfo.texi(,11783) Index under @code{apply}.@refill
texinfo.texi(,11784) 
texinfo.texi(,11785) Ordinary variables and user options are described using a format like
texinfo.texi(,11786) that for functions except that variables do not take arguments.
texinfo.texi(,11787) 
texinfo.texi(,11788) 
texinfo.texi(,11789) @node Conditionals
texinfo.texi(,11790) @chapter Conditionally Visible Text
texinfo.texi(,11791) @cindex Conditionally visible text
texinfo.texi(,11792) @cindex Text, conditionally visible
texinfo.texi(,11793) @cindex Visibility of conditional text
texinfo.texi(,11794) @cindex If text conditionally visible
texinfo.texi(,11795) 
texinfo.texi(,11796) Sometimes it is good to use different text for different output formats.
texinfo.texi(,11797) For example, you can use the @dfn{conditional commands} to specify
texinfo.texi(,11798) different text for the printed manual and the Info output.
texinfo.texi(,11799) 
texinfo.texi(,11800) Conditional commands may not be nested.
texinfo.texi(,11801) 
texinfo.texi(,11802) The conditional commands comprise the following categories.
texinfo.texi(,11803) 
texinfo.texi(,11804) @itemize @bullet
texinfo.texi(,11805) @item Commands for HTML, Info, or @TeX{}.
texinfo.texi(,11806) @item Commands for not HTML, Info, or @TeX{}.
texinfo.texi(,11807) @item Raw @TeX{} or HTML commands.
texinfo.texi(,11808) @item
texinfo.texi(,11809) Substituting text for all formats, and testing if a flag is set or clear.
texinfo.texi(,11810) @end itemize
texinfo.texi(,11811) 
texinfo.texi(,11812) @menu
texinfo.texi(,11813) * Conditional Commands::        Specifying text for HTML, Info, or @TeX{}.
texinfo.texi(,11814) * Conditional Not Commands::    Specifying text for not HTML, Info, or @TeX{}.
texinfo.texi(,11815) * Raw Formatter Commands::      Using raw @TeX{} or HTML commands.
texinfo.texi(,11816) * set clear value::             Designating which text to format (for
texinfo.texi(,11817)                                   all output formats); and how to set a
texinfo.texi(,11818)                                   flag to a string that you can insert.
texinfo.texi(,11819) @end menu
texinfo.texi(,11820) 
texinfo.texi(,11821) 
texinfo.texi(,11822) @node Conditional Commands
texinfo.texi(,11823) @section Conditional Commands
texinfo.texi(,11824) 
texinfo.texi(,11825) Texinfo has a pair of commands for each output format, to allow
texinfo.texi(,11826) conditional inclusion of text for a particular output format.
texinfo.texi(,11827) 
texinfo.texi(,11828) @findex ifinfo
texinfo.texi(,11829) @code{@@ifinfo} begins segments of text that should be ignored by @TeX{}
texinfo.texi(,11830) when it typesets the printed manual.  The segment of text appears only
texinfo.texi(,11831) in the Info file and (for historical compatibility) the plain text
texinfo.texi(,11832) output.  The @code{@@ifinfo} command should appear on a line by itself;
texinfo.texi(,11833) end the Info-only text with a line containing @code{@@end ifinfo} by
texinfo.texi(,11834) itself.
texinfo.texi(,11835) 
texinfo.texi(,11836) @findex iftex
texinfo.texi(,11837) @findex ifhtml
texinfo.texi(,11838) @findex ifplaintext
texinfo.texi(,11839) The @code{@@iftex} and @code{@@end iftex} commands are analogous to the
texinfo.texi(,11840) @code{@@ifinfo} and @code{@@end ifinfo} commands; they specify text that
texinfo.texi(,11841) will appear in the printed manual but not in the Info file.  Likewise
texinfo.texi(,11842) for @code{@@ifhtml} and @code{@@end ifhtml}, which specify text to
texinfo.texi(,11843) appear only in HTML output.  And for @code{@@ifplaintext} and
texinfo.texi(,11844) @code{@@end ifplaintext}, which specify text to appear only in plain
texinfo.texi(,11845) text output.
texinfo.texi(,11846) 
texinfo.texi(,11847) For example,
texinfo.texi(,11848) 
texinfo.texi(,11849) @example
texinfo.texi(,11850) @@iftex
texinfo.texi(,11851) This text will appear only in the printed manual.
texinfo.texi(,11852) @@end iftex
texinfo.texi(,11853) @@ifinfo
texinfo.texi(,11854) However, this text will appear only in Info (or plain text).
texinfo.texi(,11855) @@end ifinfo
texinfo.texi(,11856) @@ifhtml
texinfo.texi(,11857) And this text will only appear in HTML.
texinfo.texi(,11858) @@end ifhtml
texinfo.texi(,11859) @@ifplaintext
texinfo.texi(,11860) Whereas this text will only appear in plain text.
texinfo.texi(,11861) @@end ifplaintext
texinfo.texi(,11862) @end example
texinfo.texi(,11863) 
texinfo.texi(,11864) @noindent
texinfo.texi(,11865) The preceding example produces the following line:
texinfo.texi(,11870) However, this text will appear only in Info (or plain text).
texinfo.texi(,11873) And this text will only appear in HTML.
texinfo.texi(,11878) 
texinfo.texi(,11879) @noindent
texinfo.texi(,11880) Notice that you only see one of the input lines, depending on which
texinfo.texi(,11881) version of the manual you are reading.
texinfo.texi(,11882) 
texinfo.texi(,11883) 
texinfo.texi(,11884) @node Conditional Not Commands
texinfo.texi(,11885) @section Conditional Not Commands
texinfo.texi(,11886) @findex ifnothtml
texinfo.texi(,11887) @findex ifnotinfo
texinfo.texi(,11888) @findex ifnotplaintext
texinfo.texi(,11889) @findex ifnottex
texinfo.texi(,11890) 
texinfo.texi(,11891) You can specify text to be included in any output format @emph{other}
texinfo.texi(,11892) than some given one with the @code{@@ifnot@dots{}} commands:
texinfo.texi(,11893) @example
texinfo.texi(,11894) @@ifnothtml @dots{} @@end ifnothtml
texinfo.texi(,11895) @@ifnotinfo @dots{} @@end ifnotinfo
texinfo.texi(,11896) @@ifnotplaintext @dots{} @@end ifnotplaintext
texinfo.texi(,11897) @@ifnottex @dots{} @@end ifnottex
texinfo.texi(,11898) @end example
texinfo.texi(,11899) @noindent
texinfo.texi(,11900) (The @code{@@ifnot@dots{}} command and the @code{@@end} command must
texinfo.texi(,11901) appear on lines by themselves in your actual source file.)
texinfo.texi(,11902) 
texinfo.texi(,11903) If the output file is @emph{not} being made for the given format, the
texinfo.texi(,11904) region is included.  Otherwise, it is ignored.
texinfo.texi(,11905) 
texinfo.texi(,11906) With one exception (for historical compatibility): @code{@@ifnotinfo}
texinfo.texi(,11907) text is omitted for both Info and plain text output, not just Info.  To
texinfo.texi(,11908) specify text which appears only in Info and not in plain text, use
texinfo.texi(,11909) @code{@@ifnotplaintext}, like this:
texinfo.texi(,11910) @example
texinfo.texi(,11913) This will be in Info, but not plain text.
texinfo.texi(,11916) @end example
texinfo.texi(,11917) 
texinfo.texi(,11918) The regions delimited by these commands are ordinary Texinfo source as
texinfo.texi(,11919) with @code{@@iftex}, not raw formatter source as with @code{@@tex}
texinfo.texi(,11920) (@pxref{Raw Formatter Commands}).
texinfo.texi(,11921) 
texinfo.texi(,11922) 
texinfo.texi(,11923) @node Raw Formatter Commands
texinfo.texi(,11924) @section Raw Formatter Commands
texinfo.texi(,11925) @cindex @TeX{} commands, using ordinary
texinfo.texi(,11926) @cindex HTML commands, using ordinary
texinfo.texi(,11927) @cindex Raw formatter commands
texinfo.texi(,11928) @cindex Ordinary @TeX{} commands, using
texinfo.texi(,11929) @cindex Ordinary HTML commands, using
texinfo.texi(,11930) @cindex Commands using raw @TeX{}
texinfo.texi(,11931) @cindex Commands using raw HTML
texinfo.texi(,11932) @cindex plain @TeX{}
texinfo.texi(,11933) 
texinfo.texi(,11934) Inside a region delineated by @code{@@iftex} and @code{@@end iftex}, you
texinfo.texi(,11935) can embed some raw @TeX{} commands.  Info will ignore these commands
texinfo.texi(,11936) since they are only in that part of the file which is seen by @TeX{}.
texinfo.texi(,11937) You can write the @TeX{} commands as you would write them in a normal
texinfo.texi(,11938) @TeX{} file, except that you must replace the @samp{\} used by @TeX{}
texinfo.texi(,11939) with an @samp{@@}.  For example, in the @code{@@titlepage} section of a
texinfo.texi(,11940) Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
texinfo.texi(,11941) the copyright page.  (The @code{@@titlepage} command causes Info to
texinfo.texi(,11942) ignore the region automatically, as it does with the @code{@@iftex}
texinfo.texi(,11943) command.)
texinfo.texi(,11944) 
texinfo.texi(,11945) However, many features of plain @TeX{} will not work, as they are
texinfo.texi(,11946) overridden by Texinfo features.
texinfo.texi(,11947) 
texinfo.texi(,11948) @findex tex
texinfo.texi(,11949) You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
texinfo.texi(,11950) commands, by delineating a region with the @code{@@tex} and @code{@@end
texinfo.texi(,11951) tex} commands.  (The @code{@@tex} command also causes Info to ignore the
texinfo.texi(,11952) region, like the @code{@@iftex} command.)  The sole exception is that the
texinfo.texi(,11953) @code{@@} character still introduces a command, so that @code{@@end tex}
texinfo.texi(,11954) can be recognized properly.
texinfo.texi(,11955) 
texinfo.texi(,11956) @cindex Mathematical expressions
texinfo.texi(,11957) For example, here is a mathematical expression written in
texinfo.texi(,11958) plain @TeX{}:
texinfo.texi(,11959) 
texinfo.texi(,11960) @example
texinfo.texi(,11961) @@tex
texinfo.texi(,11962) $$ \chi^2 = \sum_@{i=1@}^N
texinfo.texi(,11963)           \left (y_i - (a + b x_i)
texinfo.texi(,11964)           \over \sigma_i\right)^2 $$
texinfo.texi(,11965) @@end tex
texinfo.texi(,11966) @end example
texinfo.texi(,11967) 
texinfo.texi(,11968) @noindent
texinfo.texi(,11969) The output of this example will appear only in a printed manual.  If
texinfo.texi(,11970) you are reading this in Info, you will not see the equation that appears
texinfo.texi(,11971) in the printed manual.
texinfo.texi(,11976) 
texinfo.texi(,11982) 
texinfo.texi(,11983) @findex ifhtml
texinfo.texi(,11984) @findex html
texinfo.texi(,11985) Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
texinfo.texi(,11986) a region to be included in HTML output only, and @code{@@html @dots{}
texinfo.texi(,11987) @@end html} for a region of raw HTML (again, except that @code{@@} is
texinfo.texi(,11988) still the escape character, so the @code{@@end} command can be
texinfo.texi(,11989) recognized.)
texinfo.texi(,11990) 
texinfo.texi(,11991) 
texinfo.texi(,11992) @node set clear value
texinfo.texi(,11993) @section @code{@@set}, @code{@@clear}, and @code{@@value}
texinfo.texi(,11994) 
texinfo.texi(,11995) You can direct the Texinfo formatting commands to format or ignore parts
texinfo.texi(,11996) of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
texinfo.texi(,11997) and @code{@@ifclear} commands.@refill
texinfo.texi(,11998) 
texinfo.texi(,11999) Brief descriptions:
texinfo.texi(,12000) 
texinfo.texi(,12001) @table @code
texinfo.texi(,12002) @item @@set @var{flag} [@var{value}]
texinfo.texi(,12003) Set the variable @var{flag}, to the optional @var{value} if specifed.
texinfo.texi(,12004) 
texinfo.texi(,12005) @item @@clear @var{flag}
texinfo.texi(,12006) Undefine the variable @var{flag}, whether or not it was previously defined.
texinfo.texi(,12007) 
texinfo.texi(,12008) @item @@ifset @var{flag}
texinfo.texi(,12009) If @var{flag} is set, text through the next @code{@@end ifset} command
texinfo.texi(,12010) is formatted.  If @var{flag} is clear, text through the following
texinfo.texi(,12011) @code{@@end ifset} command is ignored.
texinfo.texi(,12012) 
texinfo.texi(,12013) @item @@ifclear @var{flag}
texinfo.texi(,12014) If @var{flag} is set, text through the next @code{@@end ifclear} command
texinfo.texi(,12015) is ignored.  If @var{flag} is clear, text through the following
texinfo.texi(,12016) @code{@@end ifclear} command is formatted.
texinfo.texi(,12017) @end table
texinfo.texi(,12018) 
texinfo.texi(,12019) @menu
texinfo.texi(,12020) * set value::                   Expand a flag variable to a string.
texinfo.texi(,12021) * ifset ifclear::               Format a region if a flag is set.
texinfo.texi(,12022) * value Example::               An easy way to update edition information.
texinfo.texi(,12023) @end menu
texinfo.texi(,12024) 
texinfo.texi(,12025) 
texinfo.texi(,12026) @node set value
texinfo.texi(,12027) @subsection @code{@@set} and @code{@@value}
texinfo.texi(,12028) @findex value
texinfo.texi(,12029) 
texinfo.texi(,12030) You use the @code{@@set} command to specify a value for a flag, which is
texinfo.texi(,12031) later expanded by the @code{@@value} command.
texinfo.texi(,12032) 
texinfo.texi(,12033) A @dfn{flag} is an identifier.  In general, it is best to use only
texinfo.texi(,12034) letters and numerals in a flag name, not @samp{-} or @samp{_}---they
texinfo.texi(,12035) will work in some contexts, but not all, due to limitations in @TeX{}.
texinfo.texi(,12036) 
texinfo.texi(,12037) The value is the remainder of the input line, and can contain anything.
texinfo.texi(,12038) 
texinfo.texi(,12039) Write the @code{@@set} command like this:
texinfo.texi(,12040) 
texinfo.texi(,12041) @example
texinfo.texi(,12042) @@set foo This is a string.
texinfo.texi(,12043) @end example
texinfo.texi(,12044) 
texinfo.texi(,12045) @noindent
texinfo.texi(,12046) This sets the value of the flag @code{foo} to ``This is a string.''.
texinfo.texi(,12047) 
texinfo.texi(,12048) The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
texinfo.texi(,12049) command with the string to which @var{flag} is set.  Thus, when
texinfo.texi(,12050) @code{foo} is set as shown above, the Texinfo formatters convert this:
texinfo.texi(,12051) 
texinfo.texi(,12052) @example
texinfo.texi(,12053) @group
texinfo.texi(,12054) @@value@{foo@}
texinfo.texi(,12055) @exdent @r{to this:}
texinfo.texi(,12056) This is a string.
texinfo.texi(,12057) @end group
texinfo.texi(,12058) @end example
texinfo.texi(,12059) 
texinfo.texi(,12060) You can write an @code{@@value} command within a paragraph; but you
texinfo.texi(,12061) must write an @code{@@set} command on a line of its own.
texinfo.texi(,12062) 
texinfo.texi(,12063) If you write the @code{@@set} command like this:
texinfo.texi(,12064) 
texinfo.texi(,12065) @example
texinfo.texi(,12066) @@set foo
texinfo.texi(,12067) @end example
texinfo.texi(,12068) 
texinfo.texi(,12069) @noindent
texinfo.texi(,12070) without specifying a string, the value of @code{foo} is the empty string.
texinfo.texi(,12071) 
texinfo.texi(,12072) If you clear a previously set flag with @code{@@clear @var{flag}}, a
texinfo.texi(,12073) subsequent @code{@@value@{flag@}} command will report an error.
texinfo.texi(,12074) 
texinfo.texi(,12075) For example, if you set @code{foo} as follows:@refill
texinfo.texi(,12076) 
texinfo.texi(,12077) @example
texinfo.texi(,12078) @@set how-much very, very, very
texinfo.texi(,12079) @end example
texinfo.texi(,12080) 
texinfo.texi(,12081) @noindent
texinfo.texi(,12082) then the formatters transform
texinfo.texi(,12083) 
texinfo.texi(,12084) @example
texinfo.texi(,12085) @group
texinfo.texi(,12086) It is a @@value@{how-much@} wet day.
texinfo.texi(,12087) @exdent @r{into}
texinfo.texi(,12088) It is a very, very, very wet day.
texinfo.texi(,12089) @end group
texinfo.texi(,12090) @end example
texinfo.texi(,12091) 
texinfo.texi(,12092) If you write
texinfo.texi(,12093) 
texinfo.texi(,12094) @example
texinfo.texi(,12095) @@clear how-much
texinfo.texi(,12096) @end example
texinfo.texi(,12097) 
texinfo.texi(,12098) @noindent
texinfo.texi(,12099) then the formatters transform
texinfo.texi(,12100) 
texinfo.texi(,12101) @example
texinfo.texi(,12102) @group
texinfo.texi(,12103) It is a @@value@{how-much@} wet day.
texinfo.texi(,12104) @exdent @r{into}
texinfo.texi(,12105) It is a @{No value for "how-much"@} wet day.
texinfo.texi(,12106) @end group
texinfo.texi(,12107) @end example
texinfo.texi(,12108) 
texinfo.texi(,12109) 
texinfo.texi(,12110) @node ifset ifclear
texinfo.texi(,12111) @subsection @code{@@ifset} and @code{@@ifclear}
texinfo.texi(,12112) 
texinfo.texi(,12113) @findex ifset
texinfo.texi(,12114) When a @var{flag} is set, the Texinfo formatting commands format text
texinfo.texi(,12115) between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
texinfo.texi(,12116) ifset} commands.  When the @var{flag} is cleared, the Texinfo formatting
texinfo.texi(,12117) commands do @emph{not} format the text.  @code{@@ifclear} operates
texinfo.texi(,12118) analogously.
texinfo.texi(,12119) 
texinfo.texi(,12120) Write the conditionally formatted text between @code{@@ifset @var{flag}}
texinfo.texi(,12121) and @code{@@end ifset} commands, like this:
texinfo.texi(,12122) 
texinfo.texi(,12123) @example
texinfo.texi(,12124) @group
texinfo.texi(,12125) @@ifset @var{flag}
texinfo.texi(,12126) @var{conditional-text}
texinfo.texi(,12127) @@end ifset
texinfo.texi(,12128) @end group
texinfo.texi(,12129) @end example
texinfo.texi(,12130) 
texinfo.texi(,12131) For example, you can create one document that has two variants, such as
texinfo.texi(,12132) a manual for a `large' and `small' model:
texinfo.texi(,12133) 
texinfo.texi(,12134) @cindex shrubbery
texinfo.texi(,12135) @example
texinfo.texi(,12136) You can use this machine to dig up shrubs
texinfo.texi(,12137) without hurting them.
texinfo.texi(,12138) 
texinfo.texi(,12139) @@set large
texinfo.texi(,12140) 
texinfo.texi(,12141) @@ifset large
texinfo.texi(,12142) It can also dig up fully grown trees.
texinfo.texi(,12143) @@end ifset
texinfo.texi(,12144) 
texinfo.texi(,12145) Remember to replant promptly @dots{}
texinfo.texi(,12146) @end example
texinfo.texi(,12147) 
texinfo.texi(,12148) @noindent
texinfo.texi(,12149) In the example, the formatting commands will format the text between
texinfo.texi(,12150) @code{@@ifset large} and @code{@@end ifset} because the @code{large}
texinfo.texi(,12151) flag is set.
texinfo.texi(,12152) 
texinfo.texi(,12153) When @var{flag} is cleared, the Texinfo formatting commands do
texinfo.texi(,12154) @emph{not} format the text between @code{@@ifset @var{flag}} and
texinfo.texi(,12155) @code{@@end ifset}; that text is ignored and does not appear in either
texinfo.texi(,12156) printed or Info output.
texinfo.texi(,12157) 
texinfo.texi(,12158) For example, if you clear the flag of the preceding example by writing
texinfo.texi(,12159) an @code{@@clear large} command after the @code{@@set large} command
texinfo.texi(,12160) (but before the conditional text), then the Texinfo formatting commands
texinfo.texi(,12161) ignore the text between the @code{@@ifset large} and @code{@@end ifset}
texinfo.texi(,12162) commands.  In the formatted output, that text does not appear; in both
texinfo.texi(,12163) printed and Info output, you see only the lines that say, ``You can use
texinfo.texi(,12164) this machine to dig up shrubs without hurting them.  Remember to replant
texinfo.texi(,12165) promptly @dots{}''.
texinfo.texi(,12166) 
texinfo.texi(,12167) @findex ifclear
texinfo.texi(,12168) If a flag is cleared with an @code{@@clear @var{flag}} command, then
texinfo.texi(,12169) the formatting commands format text between subsequent pairs of
texinfo.texi(,12170) @code{@@ifclear} and @code{@@end ifclear} commands.  But if the flag
texinfo.texi(,12171) is set with @code{@@set @var{flag}}, then the formatting commands do
texinfo.texi(,12172) @emph{not} format text between an @code{@@ifclear} and an @code{@@end
texinfo.texi(,12173) ifclear} command; rather, they ignore that text.  An @code{@@ifclear}
texinfo.texi(,12174) command looks like this:
texinfo.texi(,12175) 
texinfo.texi(,12176) @example
texinfo.texi(,12177) @@ifclear @var{flag}
texinfo.texi(,12178) @end example
texinfo.texi(,12179) 
texinfo.texi(,12180) 
texinfo.texi(,12181) @node value Example
texinfo.texi(,12182) @subsection @code{@@value} Example
texinfo.texi(,12183) 
texinfo.texi(,12184) You can use the @code{@@value} command to minimize the number of places
texinfo.texi(,12185) you need to change when you record an update to a manual.  @xref{GNU
texinfo.texi(,12186) Sample Texts}, for an example of this same principle can work with
texinfo.texi(,12187) Automake distributions, and full texts.
texinfo.texi(,12188) 
texinfo.texi(,12189) Here is an example adapted from @ref{Top,, Overview, make, The GNU Make
texinfo.texi(,12190) Manual}):
texinfo.texi(,12191) 
texinfo.texi(,12192) @enumerate
texinfo.texi(,12193) @item
texinfo.texi(,12194) Set the flags:
texinfo.texi(,12195) 
texinfo.texi(,12196) @example
texinfo.texi(,12197) @group
texinfo.texi(,12198) @@set EDITION 0.35 Beta
texinfo.texi(,12199) @@set VERSION 3.63 Beta
texinfo.texi(,12200) @@set UPDATED 14 August 1992
texinfo.texi(,12201) @@set UPDATE-MONTH August 1992
texinfo.texi(,12202) @end group
texinfo.texi(,12203) @end example
texinfo.texi(,12204) 
texinfo.texi(,12205) @item
texinfo.texi(,12206) Write text for the @code{@@copying} section (@pxref{copying}):
texinfo.texi(,12207) 
texinfo.texi(,12208) @example
texinfo.texi(,12209) @group
texinfo.texi(,12210) @@copying
texinfo.texi(,12211) This is Edition @@value@{EDITION@},
texinfo.texi(,12212) last updated @@value@{UPDATED@},
texinfo.texi(,12213) of @@cite@{The GNU Make Manual@},
texinfo.texi(,12214) for @@code@{make@}, version @@value@{VERSION@}.
texinfo.texi(,12215) 
texinfo.texi(,12216) Copyright @dots{}
texinfo.texi(,12217) 
texinfo.texi(,12218) Permission is granted @dots{}
texinfo.texi(,12219) @@end copying
texinfo.texi(,12220) @end group
texinfo.texi(,12221) @end example
texinfo.texi(,12222) 
texinfo.texi(,12223) @item
texinfo.texi(,12224) Write text for the title page, for people reading the printed manual:
texinfo.texi(,12225) 
texinfo.texi(,12226) @example
texinfo.texi(,12227) @group
texinfo.texi(,12228) @@titlepage
texinfo.texi(,12229) @@title GNU Make
texinfo.texi(,12230) @@subtitle A Program for Directing Recompilation
texinfo.texi(,12231) @@subtitle Edition @@value@{EDITION@}, @dots{}
texinfo.texi(,12232) @@subtitle @@value@{UPDATE-MONTH@}
texinfo.texi(,12233) @@page
texinfo.texi(,12234) @@insertcopying
texinfo.texi(,12235) @dots{}
texinfo.texi(,12236) @@end titlepage
texinfo.texi(,12237) @end group
texinfo.texi(,12238) @end example
texinfo.texi(,12239) 
texinfo.texi(,12240) @noindent
texinfo.texi(,12241) (On a printed cover, a date listing the month and the year looks less
texinfo.texi(,12242) fussy than a date listing the day as well as the month and year.)
texinfo.texi(,12243) 
texinfo.texi(,12244) @item
texinfo.texi(,12245) Write text for the Top node, for people reading the Info file:
texinfo.texi(,12246) 
texinfo.texi(,12247) @example
texinfo.texi(,12248) @group
texinfo.texi(,12249) @@ifnottex
texinfo.texi(,12250) @@node Top
texinfo.texi(,12251) @@top Make
texinfo.texi(,12252) 
texinfo.texi(,12253) @@insertcopying
texinfo.texi(,12254) @dots{}
texinfo.texi(,12255) @@end ifnottex
texinfo.texi(,12256) @end group
texinfo.texi(,12257) @end example
texinfo.texi(,12258) 
texinfo.texi(,12259) After you format the manual, the @code{@@value} constructs have been
texinfo.texi(,12260) expanded, so the output contains text like this:
texinfo.texi(,12261) 
texinfo.texi(,12262) @example
texinfo.texi(,12263) @group
texinfo.texi(,12264) This is Edition 0.35 Beta, last updated 14 August 1992,
texinfo.texi(,12265) of `The GNU Make Manual', for `make', Version 3.63 Beta.
texinfo.texi(,12266) @end group
texinfo.texi(,12267) @end example
texinfo.texi(,12268) @end enumerate
texinfo.texi(,12269) 
texinfo.texi(,12270) When you update the manual, you change only the values of the flags; you
texinfo.texi(,12271) do not need to edit the three sections.
texinfo.texi(,12272) 
texinfo.texi(,12273) 
texinfo.texi(,12274) @node Internationalization
texinfo.texi(,12275) @chapter Internationalization
texinfo.texi(,12276) 
texinfo.texi(,12277) @cindex Internationalization
texinfo.texi(,12278) Texinfo has some support for writing in languages other than English,
texinfo.texi(,12279) although this area still needs considerable work.
texinfo.texi(,12280) 
texinfo.texi(,12281) For a list of the various accented and special characters Texinfo
texinfo.texi(,12282) supports, see @ref{Inserting Accents}.
texinfo.texi(,12283) 
texinfo.texi(,12284) @menu
texinfo.texi(,12285) * documentlanguage::            Declaring the current language.
texinfo.texi(,12286) * documentencoding::            Declaring the input encoding.
texinfo.texi(,12287) @end menu
texinfo.texi(,12288) 
texinfo.texi(,12289) 
texinfo.texi(,12290) @node documentlanguage
texinfo.texi(,12291) @section @code{@@documentlanguage @var{cc}}: Set the Document Language
texinfo.texi(,12292) 
texinfo.texi(,12293) @findex documentlanguage
texinfo.texi(,12294) @cindex Language, declaring
texinfo.texi(,12295) @cindex Document language, declaring
texinfo.texi(,12296) 
texinfo.texi(,12297) The @code{@@documentlanguage} command declares the current document
texinfo.texi(,12298) language.  Write it on a line by itself, with a two-letter ISO-639
texinfo.texi(,12299) language code following (list is included below).  If you have a
texinfo.texi(,12300) multilingual document, the intent is to be able to use this command
texinfo.texi(,12301) multiple times, to declare each language change.  If the command is not
texinfo.texi(,12302) used at all, the default is @code{en} for English.
texinfo.texi(,12303) 
texinfo.texi(,12304) @cindex @file{txi-@var{cc}.tex}
texinfo.texi(,12305) At present, this command is ignored in Info and HTML output.  For
texinfo.texi(,12306) @TeX{}, it causes the file @file{txi-@var{cc}.tex} to be read (if it
texinfo.texi(,12307) exists).  Such a file appropriately redefines the various English words
texinfo.texi(,12308) used in @TeX{} output, such as `Chapter', `See', and so on.
texinfo.texi(,12309) 
texinfo.texi(,12310) @cindex Hyphenation patterns, language-dependent
texinfo.texi(,12311) It would be good if this command also changed @TeX{}'s ideas of the
texinfo.texi(,12312) current hyphenation patterns (via the @TeX{} primitive
texinfo.texi(,12313) @code{\language}), but this is unfortunately not currently implemented.
texinfo.texi(,12314) 
texinfo.texi(,12315) @cindex ISO 639 codes
texinfo.texi(,12316) @cindex Language codes
texinfo.texi(,12317) Hereare the valid language codes, from ISO-639.
texinfo.texi(,12318) 
texinfo.texi(,12319) @multitable @columnfractions .07 .26 .07 .26 .07 .26
texinfo.texi(,12320) @item
texinfo.texi(,12321) @code{aa} @tab Afar @tab
texinfo.texi(,12322) @code{ab} @tab Abkhazian @tab
texinfo.texi(,12323) @code{af} @tab Afrikaans
texinfo.texi(,12324) @item
texinfo.texi(,12325) @code{am} @tab Amharic @tab
texinfo.texi(,12326) @code{ar} @tab Arabic @tab
texinfo.texi(,12327) @code{as} @tab Assamese
texinfo.texi(,12328) @item
texinfo.texi(,12329) @code{ay} @tab Aymara @tab
texinfo.texi(,12330) @code{az} @tab Azerbaijani @tab
texinfo.texi(,12331) @code{ba} @tab Bashkir
texinfo.texi(,12332) @item
texinfo.texi(,12333) @code{be} @tab Byelorussian @tab
texinfo.texi(,12334) @code{bg} @tab Bulgarian @tab
texinfo.texi(,12335) @code{bh} @tab Bihari
texinfo.texi(,12336) @item
texinfo.texi(,12337) @code{bi} @tab Bislama @tab
texinfo.texi(,12338) @code{bn} @tab Bengali; Bangla @tab
texinfo.texi(,12339) @code{bo} @tab Tibetan
texinfo.texi(,12340) @item
texinfo.texi(,12341) @code{br} @tab Breton @tab
texinfo.texi(,12342) @code{ca} @tab Catalan @tab
texinfo.texi(,12343) @code{co} @tab Corsican
texinfo.texi(,12344) @item
texinfo.texi(,12345) @code{cs} @tab Czech @tab
texinfo.texi(,12346) @code{cy} @tab Welsh @tab
texinfo.texi(,12347) @code{da} @tab Danish
texinfo.texi(,12348) @item
texinfo.texi(,12349) @code{de} @tab German @tab
texinfo.texi(,12350) @code{dz} @tab Bhutani @tab
texinfo.texi(,12351) @code{el} @tab Greek
texinfo.texi(,12352) @item
texinfo.texi(,12353) @code{en} @tab English @tab
texinfo.texi(,12354) @code{eo} @tab Esperanto @tab
texinfo.texi(,12355) @code{es} @tab Spanish
texinfo.texi(,12356) @item
texinfo.texi(,12357) @code{et} @tab Estonian @tab
texinfo.texi(,12358) @code{eu} @tab Basque @tab
texinfo.texi(,12359) @code{fa} @tab Persian
texinfo.texi(,12360) @item
texinfo.texi(,12361) @code{fi} @tab Finnish @tab
texinfo.texi(,12362) @code{fj} @tab Fiji @tab
texinfo.texi(,12363) @code{fo} @tab Faroese
texinfo.texi(,12364) @item
texinfo.texi(,12365) @code{fr} @tab French @tab
texinfo.texi(,12366) @code{fy} @tab Frisian @tab
texinfo.texi(,12367) @code{ga} @tab Irish
texinfo.texi(,12368) @item
texinfo.texi(,12369) @code{gd} @tab Scots Gaelic @tab
texinfo.texi(,12370) @code{gl} @tab Galician @tab
texinfo.texi(,12371) @code{gn} @tab Guarani
texinfo.texi(,12372) @item
texinfo.texi(,12373) @code{gu} @tab Gujarati @tab
texinfo.texi(,12374) @code{ha} @tab Hausa @tab
texinfo.texi(,12375) @code{he} @tab Hebrew
texinfo.texi(,12376) @item
texinfo.texi(,12377) @code{hi} @tab Hindi @tab
texinfo.texi(,12378) @code{hr} @tab Croatian @tab
texinfo.texi(,12379) @code{hu} @tab Hungarian
texinfo.texi(,12380) @item
texinfo.texi(,12381) @code{hy} @tab Armenian @tab
texinfo.texi(,12382) @code{ia} @tab Interlingua @tab
texinfo.texi(,12383) @code{id} @tab Indonesian
texinfo.texi(,12384) @item
texinfo.texi(,12385) @code{ie} @tab Interlingue @tab
texinfo.texi(,12386) @code{ik} @tab Inupiak @tab
texinfo.texi(,12387) @code{is} @tab Icelandic
texinfo.texi(,12388) @item
texinfo.texi(,12389) @code{it} @tab Italian @tab
texinfo.texi(,12390) @code{iu} @tab Inuktitut @tab
texinfo.texi(,12391) @code{ja} @tab Japanese
texinfo.texi(,12392) @item
texinfo.texi(,12393) @code{jw} @tab Javanese @tab
texinfo.texi(,12394) @code{ka} @tab Georgian @tab
texinfo.texi(,12395) @code{kk} @tab Kazakh
texinfo.texi(,12396) @item
texinfo.texi(,12397) @code{kl} @tab Greenlandic @tab
texinfo.texi(,12398) @code{km} @tab Cambodian @tab
texinfo.texi(,12399) @code{kn} @tab Kannada
texinfo.texi(,12400) @item
texinfo.texi(,12401) @code{ks} @tab Kashmiri @tab
texinfo.texi(,12402) @code{ko} @tab Korean @tab
texinfo.texi(,12403) @code{ku} @tab Kurdish
texinfo.texi(,12404) @item
texinfo.texi(,12405) @code{ky} @tab Kirghiz @tab
texinfo.texi(,12406) @code{la} @tab Latin @tab
texinfo.texi(,12407) @code{ln} @tab Lingala
texinfo.texi(,12408) @item
texinfo.texi(,12409) @code{lt} @tab Lithuanian @tab
texinfo.texi(,12410) @code{lo} @tab Laothian @tab
texinfo.texi(,12411) @code{lv} @tab Latvian, Lettish
texinfo.texi(,12412) @item
texinfo.texi(,12413) @code{mg} @tab Malagasy @tab
texinfo.texi(,12414) @code{mi} @tab Maori @tab
texinfo.texi(,12415) @code{mk} @tab Macedonian
texinfo.texi(,12416) @item
texinfo.texi(,12417) @code{ml} @tab Malayalam @tab
texinfo.texi(,12418) @code{mn} @tab Mongolian @tab
texinfo.texi(,12419) @code{mo} @tab Moldavian
texinfo.texi(,12420) @item
texinfo.texi(,12421) @code{mr} @tab Marathi @tab
texinfo.texi(,12422) @code{ms} @tab Malay @tab
texinfo.texi(,12423) @code{mt} @tab Maltese
texinfo.texi(,12424) @item
texinfo.texi(,12425) @code{my} @tab Burmese @tab
texinfo.texi(,12426) @code{na} @tab Nauru @tab
texinfo.texi(,12427) @code{ne} @tab Nepali
texinfo.texi(,12428) @item
texinfo.texi(,12429) @code{nl} @tab Dutch @tab
texinfo.texi(,12430) @code{no} @tab Norwegian @tab
texinfo.texi(,12431) @code{oc} @tab Occitan
texinfo.texi(,12432) @item
texinfo.texi(,12433) @code{om} @tab (Afan) Oromo @tab
texinfo.texi(,12434) @code{or} @tab Oriya @tab
texinfo.texi(,12435) @code{pa} @tab Punjabi
texinfo.texi(,12436) @item
texinfo.texi(,12437) @code{pl} @tab Polish @tab
texinfo.texi(,12438) @code{ps} @tab Pashto, Pushto @tab
texinfo.texi(,12439) @code{pt} @tab Portuguese
texinfo.texi(,12440) @item
texinfo.texi(,12441) @code{qu} @tab Quechua @tab
texinfo.texi(,12442) @code{rm} @tab Rhaeto-Romance @tab
texinfo.texi(,12443) @code{rn} @tab Kirundi
texinfo.texi(,12444) @item
texinfo.texi(,12445) @code{ro} @tab Romanian @tab
texinfo.texi(,12446) @code{ru} @tab Russian @tab
texinfo.texi(,12447) @code{rw} @tab Kinyarwanda
texinfo.texi(,12448) @item
texinfo.texi(,12449) @code{sa} @tab Sanskrit @tab
texinfo.texi(,12450) @code{sd} @tab Sindhi @tab
texinfo.texi(,12451) @code{sg} @tab Sangro
texinfo.texi(,12452) @item
texinfo.texi(,12453) @code{sh} @tab Serbo-Croatian @tab
texinfo.texi(,12454) @code{si} @tab Sinhalese @tab
texinfo.texi(,12455) @code{sk} @tab Slovak
texinfo.texi(,12456) @item
texinfo.texi(,12457) @code{sl} @tab Slovenian @tab
texinfo.texi(,12458) @code{sm} @tab Samoan @tab
texinfo.texi(,12459) @code{sn} @tab Shona
texinfo.texi(,12460) @item
texinfo.texi(,12461) @code{so} @tab Somali @tab
texinfo.texi(,12462) @code{sq} @tab Albanian @tab
texinfo.texi(,12463) @code{sr} @tab Serbian
texinfo.texi(,12464) @item
texinfo.texi(,12465) @code{ss} @tab Siswati @tab
texinfo.texi(,12466) @code{st} @tab Sesotho @tab
texinfo.texi(,12467) @code{su} @tab Sundanese
texinfo.texi(,12468) @item
texinfo.texi(,12469) @code{sv} @tab Swedish @tab
texinfo.texi(,12470) @code{sw} @tab Swahili @tab
texinfo.texi(,12471) @code{ta} @tab Tamil
texinfo.texi(,12472) @item
texinfo.texi(,12473) @code{te} @tab Telugu @tab
texinfo.texi(,12474) @code{tg} @tab Tajik @tab
texinfo.texi(,12475) @code{th} @tab Thai
texinfo.texi(,12476) @item
texinfo.texi(,12477) @code{ti} @tab Tigrinya @tab
texinfo.texi(,12478) @code{tk} @tab Turkmen @tab
texinfo.texi(,12479) @code{tl} @tab Tagalog
texinfo.texi(,12480) @item
texinfo.texi(,12481) @code{tn} @tab Setswana @tab
texinfo.texi(,12482) @code{to} @tab Tonga @tab
texinfo.texi(,12483) @code{tr} @tab Turkish
texinfo.texi(,12484) @item
texinfo.texi(,12485) @code{ts} @tab Tsonga @tab
texinfo.texi(,12486) @code{tt} @tab Tatar @tab
texinfo.texi(,12487) @code{tw} @tab Twi
texinfo.texi(,12488) @item
texinfo.texi(,12489) @code{ug} @tab Uighur @tab
texinfo.texi(,12490) @code{uk} @tab Ukrainian @tab
texinfo.texi(,12491) @code{ur} @tab Urdu
texinfo.texi(,12492) @item
texinfo.texi(,12493) @code{uz} @tab Uzbek @tab
texinfo.texi(,12494) @code{vi} @tab Vietnamese @tab
texinfo.texi(,12495) @code{vo} @tab Volapuk
texinfo.texi(,12496) @item
texinfo.texi(,12497) @code{wo} @tab Wolof @tab
texinfo.texi(,12498) @code{xh} @tab Xhosa @tab
texinfo.texi(,12499) @code{yi} @tab Yiddish
texinfo.texi(,12500) @item
texinfo.texi(,12501) @code{yo} @tab Yoruba @tab
texinfo.texi(,12502) @code{za} @tab Zhuang @tab
texinfo.texi(,12503) @code{zh} @tab Chinese
texinfo.texi(,12504) @item
texinfo.texi(,12505) @code{zu} @tab Zulu
texinfo.texi(,12506) @end multitable
texinfo.texi(,12507) 
texinfo.texi(,12508) 
texinfo.texi(,12509) @node documentencoding
texinfo.texi(,12510) @section @code{@@documentencoding @var{enc}}: Set Input Encoding
texinfo.texi(,12511) 
texinfo.texi(,12512) @findex documentencoding
texinfo.texi(,12513) @cindex Encoding, declaring
texinfo.texi(,12514) @cindex Input encoding, declaring
texinfo.texi(,12515) @cindex Document input encoding
texinfo.texi(,12516) 
texinfo.texi(,12517) The @code{@@documentencoding} command declares the input document
texinfo.texi(,12518) encoding.  Write it on a line by itself, with a valid encoding
texinfo.texi(,12519) specification following, such as @samp{ISO-8859-1}.
texinfo.texi(,12520) 
texinfo.texi(,12521) @cindex http-equiv, and charset
texinfo.texi(,12522) @cindex meta HTML tag, and charset
texinfo.texi(,12523) At present, this is used only in HTML output from @code{makeinfo}.  If a
texinfo.texi(,12524) document encoding @var{enc} is specified, it is used in a
texinfo.texi(,12525) @samp{<meta>} tag included in the @samp{<head>} of the output:
texinfo.texi(,12526) 
texinfo.texi(,12527) @example
texinfo.texi(,12528) <meta http-equiv="Content-Type" content="text/html;
texinfo.texi(,12529)       charset=@var{enc}">
texinfo.texi(,12530) @end example
texinfo.texi(,12531) 
texinfo.texi(,12532) 
texinfo.texi(,12533) @node Defining New Texinfo Commands
texinfo.texi(,12534) @chapter Defining New Texinfo Commands
texinfo.texi(,12535) @cindex Macros
texinfo.texi(,12536) @cindex Defining new Texinfo commands
texinfo.texi(,12537) @cindex New Texinfo commands, defining
texinfo.texi(,12538) @cindex Texinfo commands, defining new
texinfo.texi(,12539) @cindex User-defined Texinfo commands
texinfo.texi(,12540) 
texinfo.texi(,12541) Texinfo provides several ways to define new commands:
texinfo.texi(,12542) 
texinfo.texi(,12543) @itemize @bullet
texinfo.texi(,12544) @item
texinfo.texi(,12545) A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
texinfo.texi(,12546) sequence of text and/or existing commands (including other macros).  The
texinfo.texi(,12547) macro can have any number of @dfn{parameters}---text you supply each
texinfo.texi(,12548) time you use the macro.
texinfo.texi(,12549) 
texinfo.texi(,12550) Incidentally, these macros have nothing to do with the @code{@@defmac}
texinfo.texi(,12551) command, which is for documenting macros in the subject of the manual
texinfo.texi(,12552) (@pxref{Def Cmd Template}).
texinfo.texi(,12553) 
texinfo.texi(,12554) @item
texinfo.texi(,12555) @samp{@@alias} is a convenient way to define a new name for an existing
texinfo.texi(,12556) command.
texinfo.texi(,12557) 
texinfo.texi(,12558) @item
texinfo.texi(,12559) @samp{@@definfoenclose} allows you to define new commands with
texinfo.texi(,12560) customized output in the Info file.
texinfo.texi(,12561) 
texinfo.texi(,12562) @end itemize
texinfo.texi(,12563) 
texinfo.texi(,12564) @menu
texinfo.texi(,12565) * Defining Macros::             Defining and undefining new commands.
texinfo.texi(,12566) * Invoking Macros::             Using a macro, once you've defined it.
texinfo.texi(,12567) * Macro Details::               Beyond basic macro usage.
texinfo.texi(,12568) * alias::                       Command aliases.
texinfo.texi(,12569) * definfoenclose::              Customized highlighting.
texinfo.texi(,12570) @end menu
texinfo.texi(,12571) 
texinfo.texi(,12572) 
texinfo.texi(,12573) @node Defining Macros
texinfo.texi(,12574) @section Defining Macros
texinfo.texi(,12575) @cindex Defining macros
texinfo.texi(,12576) @cindex Macro definitions
texinfo.texi(,12577) 
texinfo.texi(,12578) @findex macro
texinfo.texi(,12579) You use the Texinfo @code{@@macro} command to define a macro, like this:
texinfo.texi(,12580) 
texinfo.texi(,12581) @example
texinfo.texi(,12582) @@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
texinfo.texi(,12583) @var{text} @dots{} \@var{param1}\ @dots{}
texinfo.texi(,12584) @@end macro
texinfo.texi(,12585) @end example
texinfo.texi(,12586) 
texinfo.texi(,12587) The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
texinfo.texi(,12588) arguments supplied when the macro is subsequently used in the document
texinfo.texi(,12589) (described in the next section).
texinfo.texi(,12590) 
texinfo.texi(,12591) For a macro to work with @TeX{}, @var{macroname} must consist entirely
texinfo.texi(,12592) of letters: no digits, hyphens, underscores, or other special characters.
texinfo.texi(,12593) 
texinfo.texi(,12594) If a macro needs no parameters, you can define it either with an empty
texinfo.texi(,12595) list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
texinfo.texi(,12596) foo}).
texinfo.texi(,12597) 
texinfo.texi(,12598) @cindex Body of a macro
texinfo.texi(,12599) @cindex Mutually recursive macros
texinfo.texi(,12600) @cindex Recursion, mutual
texinfo.texi(,12601) The definition or @dfn{body} of the macro can contain most Texinfo
texinfo.texi(,12602) commands, including previously-defined macros.  Not-yet-defined macro
texinfo.texi(,12603) invocations are not allowed; thus, it is not possible to have mutually
texinfo.texi(,12604) recursive Texinfo macros.  Also, a macro definition that defines another
texinfo.texi(,12605) macro does not work in @TeX{} due to limitations in the design of
texinfo.texi(,12606) @code{@@macro}.
texinfo.texi(,12607) 
texinfo.texi(,12608) @cindex Parameters to macros
texinfo.texi(,12609) In the macro body, instances of a parameter name surrounded by
texinfo.texi(,12610) backslashes, as in @samp{\@var{param1}\} in the example above, are
texinfo.texi(,12611) replaced by the corresponding argument from the macro invocation.  You
texinfo.texi(,12612) can use parameter names any number of times in the body, including zero.
texinfo.texi(,12613) 
texinfo.texi(,12614) @cindex Backslash in macros
texinfo.texi(,12615) To get a single @samp{\} in the macro expansion, use @samp{\\}.  Any
texinfo.texi(,12616) other use of @samp{\} in the body yields a warning.
texinfo.texi(,12617) 
texinfo.texi(,12618) @cindex Spaces in macros
texinfo.texi(,12619) @cindex Whitespace in macros
texinfo.texi(,12620) The newlines after the @code{@@macro} line and before the @code{@@end
texinfo.texi(,12621) macro} line are ignored, that is, not included in the macro body.  All
texinfo.texi(,12622) other whitespace is treated according to the usual Texinfo rules.
texinfo.texi(,12623) 
texinfo.texi(,12624) @cindex Recursive macro invocations
texinfo.texi(,12625) @findex rmacro
texinfo.texi(,12626) To allow a macro to be used recursively, that is, in an argument to a
texinfo.texi(,12627) call to itself, you must define it with @samp{@@rmacro}, like this:
texinfo.texi(,12628) 
texinfo.texi(,12629) @example
texinfo.texi(,12630) @@rmacro rmac @{arg@}
texinfo.texi(,12631) a\arg\b
texinfo.texi(,12632) @@end rmacro
texinfo.texi(,12633) @dots{}
texinfo.texi(,12634) @@rmac@{1@@rmac@{text@}2@}
texinfo.texi(,12635) @end example
texinfo.texi(,12636) 
texinfo.texi(,12637) This produces the output `a1atextb2b'.  With @samp{@@macro} instead of
texinfo.texi(,12638) @samp{@@rmacro}, an error message is given.
texinfo.texi(,12639) 
texinfo.texi(,12640) @findex unmacro
texinfo.texi(,12641) @cindex Macros, undefining
texinfo.texi(,12642) @cindex Undefining macros
texinfo.texi(,12643) You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
texinfo.texi(,12644) It is not an error to undefine a macro that is already undefined.
texinfo.texi(,12645) For example:
texinfo.texi(,12646) 
texinfo.texi(,12647) @example
texinfo.texi(,12648) @@unmacro foo
texinfo.texi(,12649) @end example
texinfo.texi(,12650) 
texinfo.texi(,12651) 
texinfo.texi(,12652) @node Invoking Macros
texinfo.texi(,12653) @section Invoking Macros
texinfo.texi(,12654) @cindex Invoking macros
texinfo.texi(,12655) @cindex Expanding macros
texinfo.texi(,12656) @cindex Running macros
texinfo.texi(,12657) @cindex Macro invocation
texinfo.texi(,12658) 
texinfo.texi(,12659) After a macro is defined (see the previous section), you can use
texinfo.texi(,12660) (@dfn{invoke}) it in your document like this:
texinfo.texi(,12661) 
texinfo.texi(,12662) @example
texinfo.texi(,12663) @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
texinfo.texi(,12664) @end example
texinfo.texi(,12665) 
texinfo.texi(,12666) @noindent and the result will be just as if you typed the body of
texinfo.texi(,12667) @var{macroname} at that spot.  For example:
texinfo.texi(,12668) 
texinfo.texi(,12669) @example
texinfo.texi(,12670) @@macro foo @{p, q@}
texinfo.texi(,12671) Together: \p\ & \q\.
texinfo.texi(,12672) @@end macro
texinfo.texi(,12673) @@foo@{a, b@}
texinfo.texi(,12674) @end example
texinfo.texi(,12675) 
texinfo.texi(,12676) @noindent produces:
texinfo.texi(,12677) 
texinfo.texi(,12678) @display
texinfo.texi(,12679) Together: a & b.
texinfo.texi(,12680) @end display
texinfo.texi(,12681) 
texinfo.texi(,12682) @cindex Backslash, and macros
texinfo.texi(,12683) Thus, the arguments and parameters are separated by commas and delimited
texinfo.texi(,12684) by braces; any whitespace after (but not before) a comma is ignored.
texinfo.texi(,12685) The braces are required in the invocation (but not the definition), even
texinfo.texi(,12686) when the macro takes no arguments, consistent with all other Texinfo
texinfo.texi(,12687) commands.  For example:
texinfo.texi(,12688) 
texinfo.texi(,12689) @example
texinfo.texi(,12690) @@macro argless @{@}
texinfo.texi(,12691) No arguments here.
texinfo.texi(,12692) @@end macro
texinfo.texi(,12693) @@argless@{@}
texinfo.texi(,12694) @end example
texinfo.texi(,12695) 
texinfo.texi(,12696) @noindent produces:
texinfo.texi(,12697) 
texinfo.texi(,12698) @display
texinfo.texi(,12699) No arguments here.
texinfo.texi(,12700) @end display
texinfo.texi(,12701) 
texinfo.texi(,12702) @cindex Comma, in macro arguments
texinfo.texi(,12703) @cindex Braces, in macro arguments
texinfo.texi(,12704) To insert a comma, brace, or backslash in an argument, prepend a
texinfo.texi(,12705) backslash, as in
texinfo.texi(,12706) 
texinfo.texi(,12707) @example
texinfo.texi(,12708) @@@var{macname} @{\\\@{\@}\,@}
texinfo.texi(,12709) @end example
texinfo.texi(,12710) 
texinfo.texi(,12711) @noindent
texinfo.texi(,12712) which will pass the (almost certainly error-producing) argument
texinfo.texi(,12713) @samp{\@{@},} to @var{macname}.  However, commas in parameters, even
texinfo.texi(,12714) if escaped by a backslash, might cause trouble in @TeX{}.
texinfo.texi(,12715) 
texinfo.texi(,12716) If the macro is defined to take a single argument, and is invoked
texinfo.texi(,12717) without any braces, the entire rest of the line after the macro name is
texinfo.texi(,12718) supplied as the argument.  For example:
texinfo.texi(,12719) 
texinfo.texi(,12720) @example
texinfo.texi(,12721) @@macro bar @{p@}
texinfo.texi(,12722) Twice: \p\ & \p\.
texinfo.texi(,12723) @@end macro
texinfo.texi(,12724) @@bar aah
texinfo.texi(,12725) @end example
texinfo.texi(,12726) 
texinfo.texi(,12727) @noindent produces:
texinfo.texi(,12728) 
texinfo.texi(,12729) @c Sorry for cheating, but let's not require macros to process the manual.
texinfo.texi(,12730) @display
texinfo.texi(,12731) Twice: aah & aah.
texinfo.texi(,12732) @end display
texinfo.texi(,12733) 
texinfo.texi(,12734) If the macro is defined to take a single argument, and is invoked with
texinfo.texi(,12735) braces, the braced text is passed as the argument, regardless of
texinfo.texi(,12736) commas.  For example:
texinfo.texi(,12737) 
texinfo.texi(,12738) @example
texinfo.texi(,12739) @@macro bar @{p@}
texinfo.texi(,12740) Twice: \p\ & \p\.
texinfo.texi(,12741) @@end macro
texinfo.texi(,12742) @@bar@{a,b@}
texinfo.texi(,12743) @end example
texinfo.texi(,12744) 
texinfo.texi(,12745) @noindent produces:
texinfo.texi(,12746) 
texinfo.texi(,12747) @display
texinfo.texi(,12748) Twice: a,b & a,b.
texinfo.texi(,12749) @end display
texinfo.texi(,12750) 
texinfo.texi(,12751) 
texinfo.texi(,12752) @node Macro Details
texinfo.texi(,12753) @section Macro Details
texinfo.texi(,12754) @cindex Macro details
texinfo.texi(,12755) @cindex Details of macro usage
texinfo.texi(,12756) 
texinfo.texi(,12757) Due to unavoidable disparities in the @TeX{} and @command{makeinfo}
texinfo.texi(,12758) implementations, Texinfo macros have the following limitations.
texinfo.texi(,12759) 
texinfo.texi(,12760) @itemize @bullet
texinfo.texi(,12761) @item
texinfo.texi(,12762) All macros are expanded inside at least one @TeX{} group.  This means
texinfo.texi(,12763) that @code{@@set} and other such commands will have no effect inside a
texinfo.texi(,12764) macro.
texinfo.texi(,12765) 
texinfo.texi(,12766) @item
texinfo.texi(,12767) Macros containing a command which must be on a line by itself, such as a
texinfo.texi(,12768) conditional, cannot be invoked in the middle of a line.
texinfo.texi(,12769) 
texinfo.texi(,12770) @item
texinfo.texi(,12771) Commas in macro arguments, even if escaped by a backslash, don't
texinfo.texi(,12772) always work.
texinfo.texi(,12773) 
texinfo.texi(,12774) @item
texinfo.texi(,12775) The @TeX{} implementation cannot construct macros that define macros in
texinfo.texi(,12776) the natural way.  To do this, you must use conditionals and raw @TeX{}.
texinfo.texi(,12777) For example:
texinfo.texi(,12778) 
texinfo.texi(,12779) @example
texinfo.texi(,12780) @@ifnottex
texinfo.texi(,12781) @@macro ctor @{name, arg@}
texinfo.texi(,12782) @@macro \name\
texinfo.texi(,12783) something involving \arg\ somehow
texinfo.texi(,12784) @@end macro
texinfo.texi(,12785) @@end macro
texinfo.texi(,12786) @@end ifnottex
texinfo.texi(,12787) @@tex
texinfo.texi(,12788) \gdef\ctor#1@{\ctorx#1,@}
texinfo.texi(,12789) \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
texinfo.texi(,12790) @@end tex
texinfo.texi(,12791) @end example
texinfo.texi(,12792) 
texinfo.texi(,12793) @item
texinfo.texi(,12794) It is best to avoid comments inside macro definitions.
texinfo.texi(,12795) 
texinfo.texi(,12796) @end itemize
texinfo.texi(,12797) 
texinfo.texi(,12798) If some macro feature causes errors when producing the printed version
texinfo.texi(,12799) of a manual, try expanding the macros with @command{makeinfo} by
texinfo.texi(,12800) invoking @command{texi2dvi} with the @samp{-e} option; see @ref{Format
texinfo.texi(,12801) with texi2dvi}.
texinfo.texi(,12802) 
texinfo.texi(,12803) @node alias
texinfo.texi(,12804) @section @samp{@@alias @var{new}=@var{existing}}
texinfo.texi(,12805) @cindex Aliases, command
texinfo.texi(,12806) @cindex Command aliases
texinfo.texi(,12807) @findex alias
texinfo.texi(,12808) 
texinfo.texi(,12809) The @samp{@@alias} command defines a new command to be just like an
texinfo.texi(,12810) existing one.  This is useful for defining additional markup names, thus
texinfo.texi(,12811) preserving semantic information in the input even though the output
texinfo.texi(,12812) result may be the same.
texinfo.texi(,12813) 
texinfo.texi(,12814) Write the @samp{@@alias} command on a line by itself, followed by the
texinfo.texi(,12815) new command name, an equals sign, and the existing command name.
texinfo.texi(,12816) Whitespace around the equals sign is ignored.  Thus:
texinfo.texi(,12817) @example
texinfo.texi(,12818) @@alias @var{new} = @var{existing}
texinfo.texi(,12819) @end example
texinfo.texi(,12820) 
texinfo.texi(,12821) For example, if your document contains citations for both books and
texinfo.texi(,12822) some other media (movies, for example), you might like to define a
texinfo.texi(,12823) macro @code{@@moviecite@{@}} that does the same thing as an ordinary
texinfo.texi(,12824) @code{@@cite@{@}} but conveys the extra semantic information as well.
texinfo.texi(,12825) You'd do this as follows:
texinfo.texi(,12826) 
texinfo.texi(,12827) @example
texinfo.texi(,12828) @@alias moviecite = cite
texinfo.texi(,12829) @end example
texinfo.texi(,12830) 
texinfo.texi(,12831) Macros do not always have the same effect due to vagaries of argument
texinfo.texi(,12832) parsing.  Also, aliases are much simpler to define than macros.  So the
texinfo.texi(,12833) command is not redundant.  (It was also heavily used in the Jargon File!)
texinfo.texi(,12834) 
texinfo.texi(,12835) Aliases must not be recursive, directly or indirectly.
texinfo.texi(,12836) 
texinfo.texi(,12837) @node definfoenclose
texinfo.texi(,12838) @section @samp{definfoenclose}: Customized Highlighting
texinfo.texi(,12839) @cindex Highlighting, customized
texinfo.texi(,12840) @cindex Customized highlighting
texinfo.texi(,12841) @findex definfoenclose
texinfo.texi(,12842) 
texinfo.texi(,12843) A @code{@@definfoenclose} command may be used to define a highlighting
texinfo.texi(,12844) command for Info, but not for @TeX{}.  A command defined using
texinfo.texi(,12845) @code{@@definfoenclose} marks text by enclosing it in strings that
texinfo.texi(,12846) precede and follow the text.  You can use this to get closer control of
texinfo.texi(,12847) your Info output.
texinfo.texi(,12848)  
texinfo.texi(,12849) Presumably, if you define a command with @code{@@definfoenclose} for Info,
texinfo.texi(,12850) you will create a corresponding command for @TeX{}, either in
texinfo.texi(,12851) @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
texinfo.texi(,12852) your document.
texinfo.texi(,12853) 
texinfo.texi(,12854) Write a @code{@@definfoenclose} command on a line and follow it with
texinfo.texi(,12855) three arguments separated by commas.  The first argument to
texinfo.texi(,12856) @code{@@definfoenclose} is the @@-command name (without the @code{@@});
texinfo.texi(,12857) the second argument is the Info start delimiter string; and the third
texinfo.texi(,12858) argument is the Info end delimiter string.  The latter two arguments
texinfo.texi(,12859) enclose the highlighted text in the Info file.  A delimiter string may
texinfo.texi(,12860) contain spaces.  Neither the start nor end delimiter is required.  If
texinfo.texi(,12861) you do not want a start delimiter but do want an end delimiter, you must
texinfo.texi(,12862) follow the command name with two commas in a row; otherwise, the Info
texinfo.texi(,12863) formatting commands will naturally misinterpret the end delimiter string
texinfo.texi(,12864) you intended as the start delimiter string.
texinfo.texi(,12865) 
texinfo.texi(,12866) If you do a @code{@@definfoenclose} on the name of a pre-defined macro
texinfo.texi(,12867) (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
texinfo.texi(,12868) enclosure definition will override the built-in definition.
texinfo.texi(,12869)  
texinfo.texi(,12870) An enclosure command defined this way takes one argument in braces; this
texinfo.texi(,12871) is intended for new markup commands (@pxref{Marking Text}).
texinfo.texi(,12872) 
texinfo.texi(,12873) @findex phoo
texinfo.texi(,12874) For example, you can write:
texinfo.texi(,12875) 
texinfo.texi(,12876) @example
texinfo.texi(,12877) @@definfoenclose phoo,//,\\
texinfo.texi(,12878) @end example
texinfo.texi(,12879) 
texinfo.texi(,12880) @noindent
texinfo.texi(,12881) near the beginning of a Texinfo file to define @code{@@phoo} as an Info
texinfo.texi(,12882) formatting command that inserts `//' before and `\\' after the argument
texinfo.texi(,12883) to @code{@@phoo}.  You can then write @code{@@phoo@{bar@}} wherever you
texinfo.texi(,12884) want `//bar\\' highlighted in Info.
texinfo.texi(,12885) 
texinfo.texi(,12886) Also, for @TeX{} formatting, you could write 
texinfo.texi(,12887) 
texinfo.texi(,12888) @example
texinfo.texi(,12889) @@iftex
texinfo.texi(,12890) @@global@@let@@phoo=@@i
texinfo.texi(,12891) @@end iftex
texinfo.texi(,12892) @end example
texinfo.texi(,12893) 
texinfo.texi(,12894) @noindent
texinfo.texi(,12895) to define @code{@@phoo} as a command that causes @TeX{} to typeset the
texinfo.texi(,12896) argument to @code{@@phoo} in italics.
texinfo.texi(,12897) 
texinfo.texi(,12898) Each definition applies to its own formatter: one for @TeX{}, the other
texinfo.texi(,12899) for @code{texinfo-format-buffer} or @code{texinfo-format-region}.  The
texinfo.texi(,12900) @code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
texinfo.texi(,12901) the raw @TeX{} commands do need to be in @samp{@@iftex}.
texinfo.texi(,12902) 
texinfo.texi(,12903) @findex headword
texinfo.texi(,12904) Here is another example: write
texinfo.texi(,12905) 
texinfo.texi(,12906) @example
texinfo.texi(,12907) @@definfoenclose headword, , :
texinfo.texi(,12908) @end example
texinfo.texi(,12909) 
texinfo.texi(,12910) @noindent
texinfo.texi(,12911) near the beginning of the file, to define @code{@@headword} as an Info
texinfo.texi(,12912) formatting command that inserts nothing before and a colon after the
texinfo.texi(,12913) argument to @code{@@headword}.
texinfo.texi(,12914) 
texinfo.texi(,12915) @samp{@@definfoenclose} definitions must not be recursive, directly or
texinfo.texi(,12916) indirectly.
texinfo.texi(,12917) 
texinfo.texi(,12918) 
texinfo.texi(,12919) @node Hardcopy
texinfo.texi(,12920) @chapter Formatting and Printing Hardcopy
texinfo.texi(,12921) @cindex Format and print hardcopy
texinfo.texi(,12922) @cindex Printing hardcopy
texinfo.texi(,12923) @cindex Hardcopy, printing it
texinfo.texi(,12924) @cindex Making a printed manual
texinfo.texi(,12925) @cindex Sorting indices
texinfo.texi(,12926) @cindex Indices, sorting
texinfo.texi(,12927) @cindex @TeX{} index sorting
texinfo.texi(,12928) @pindex texindex
texinfo.texi(,12929) 
texinfo.texi(,12930) There are three major shell commands for making a printed manual from a
texinfo.texi(,12931) Texinfo file: one for converting the Texinfo file into a file that will be
texinfo.texi(,12932) printed, a second for sorting indices, and a third for printing the
texinfo.texi(,12933) formatted document.  When you use the shell commands, you can either
texinfo.texi(,12934) work directly in the operating system shell or work within a shell
texinfo.texi(,12935) inside GNU Emacs.
texinfo.texi(,12936) 
texinfo.texi(,12937) If you are using GNU Emacs, you can use commands provided by Texinfo
texinfo.texi(,12938) mode instead of shell commands.  In addition to the three commands to
texinfo.texi(,12939) format a file, sort the indices, and print the result, Texinfo mode
texinfo.texi(,12940) offers key bindings for commands to recenter the output buffer, show the
texinfo.texi(,12941) print queue, and delete a job from the print queue.
texinfo.texi(,12942) 
texinfo.texi(,12943) @menu
texinfo.texi(,12944) * Use TeX::                     Use @TeX{} to format for hardcopy.
texinfo.texi(,12945) * Format with tex/texindex::    How to format with explicit shell commands.
texinfo.texi(,12946) * Format with texi2dvi::        A simpler way to format.
texinfo.texi(,12947) * Print with lpr::              How to print.
texinfo.texi(,12948) * Within Emacs::                How to format and print from an Emacs shell.
texinfo.texi(,12949) * Texinfo Mode Printing::       How to format and print in Texinfo mode.
texinfo.texi(,12950) * Compile-Command::             How to print using Emacs's compile command.
texinfo.texi(,12951) * Requirements Summary::        @TeX{} formatting requirements summary.
texinfo.texi(,12952) * Preparing for TeX::           What to do before you use @TeX{}.
texinfo.texi(,12953) * Overfull hboxes::             What are and what to do with overfull hboxes.
texinfo.texi(,12954) * smallbook::                   How to print small format books and manuals.
texinfo.texi(,12955) * A4 Paper::                    How to print on A4 or A5 paper.
texinfo.texi(,12956) * pagesizes::                   How to print with customized page sizes.
texinfo.texi(,12957) * Cropmarks and Magnification::  How to print marks to indicate the size
texinfo.texi(,12958)                                 of pages and how to print scaled up output.
texinfo.texi(,12959) * PDF Output::                  Portable Document Format output.
texinfo.texi(,12960) @end menu
texinfo.texi(,12961) 
texinfo.texi(,12962) @node Use TeX
texinfo.texi(,12963) @section Use @TeX{}
texinfo.texi(,12964) 
texinfo.texi(,12965) The typesetting program called @TeX{} is used for formatting a Texinfo
texinfo.texi(,12966) file.  @TeX{} is a very powerful typesetting program and, if used correctly,
texinfo.texi(,12967) does an exceptionally good job.  (@xref{Obtaining TeX, , How to Obtain
texinfo.texi(,12968) @TeX{}}, for information on how to obtain @TeX{}.)
texinfo.texi(,12969) 
texinfo.texi(,12970) The standalone @code{makeinfo} program and Emacs functions
texinfo.texi(,12971) @code{texinfo-format-region} and @code{texinfo-format-buffer} commands
texinfo.texi(,12972) read the very same @@-commands in the Texinfo file as does @TeX{}, but
texinfo.texi(,12973) process them differently to make an Info file (@pxref{Creating an Info
texinfo.texi(,12974) File}).
texinfo.texi(,12975) 
texinfo.texi(,12976) 
texinfo.texi(,12977) @node Format with tex/texindex
texinfo.texi(,12978) @section Format with @code{tex} and @code{texindex}
texinfo.texi(,12979) @cindex Shell formatting with @code{tex} and @code{texindex}
texinfo.texi(,12980) @cindex Formatting with @code{tex} and @code{texindex}
texinfo.texi(,12981) @cindex DVI file
texinfo.texi(,12982) 
texinfo.texi(,12983) Format the Texinfo file with the shell command @code{tex} followed by
texinfo.texi(,12984) the name of the Texinfo file.  For example:
texinfo.texi(,12985) 
texinfo.texi(,12986) @example
texinfo.texi(,12987) tex foo.texi
texinfo.texi(,12988) @end example
texinfo.texi(,12989) 
texinfo.texi(,12990) @noindent @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
texinfo.texi(,12991) files containing information for indices, cross references, etc.  The
texinfo.texi(,12992) DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
texinfo.texi(,12993) any device (see the following sections).
texinfo.texi(,12994) 
texinfo.texi(,12995) @pindex texindex
texinfo.texi(,12996) The @code{tex} formatting command itself does not sort the indices; it
texinfo.texi(,12997) writes an output file of unsorted index data.  (The @code{texi2dvi}
texinfo.texi(,12998) command automatically generates indices; @pxref{Format with texi2dvi,,
texinfo.texi(,12999) Format with @code{texi2dvi}}.)  To generate a printed index after
texinfo.texi(,13000) running the @code{tex} command, you first need a sorted index to work
texinfo.texi(,13001) from.  The @code{texindex} command sorts indices.  (The source file
texinfo.texi(,13002) @file{texindex.c} comes as part of the standard Texinfo distribution,
texinfo.texi(,13003) among other places.)@refill
texinfo.texi(,13004) 
texinfo.texi(,13005) @cindex Names of index files
texinfo.texi(,13006) @cindex Index file names
texinfo.texi(,13007) The @code{tex} formatting command outputs unsorted index files under
texinfo.texi(,13008) names that obey a standard convention: the name of your main input file
texinfo.texi(,13009) with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
texinfo.texi(,13010) Web2c}) extension removed, followed by the two letter names of indices.
texinfo.texi(,13011) For example, the raw index output files for the input file
texinfo.texi(,13012) @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
texinfo.texi(,13013) @file{foo.tp}, @file{foo.pg} and @file{foo.ky}.  Those are exactly the
texinfo.texi(,13014) arguments to give to @code{texindex}.
texinfo.texi(,13015) 
texinfo.texi(,13016) @need 1000
texinfo.texi(,13017) @cindex Wildcards
texinfo.texi(,13018) @cindex Globbing
texinfo.texi(,13019) Instead of specifying all the unsorted index file names explicitly, you
texinfo.texi(,13020) can use @samp{??} as shell wildcards and give the command in this
texinfo.texi(,13021) form:
texinfo.texi(,13022) 
texinfo.texi(,13023) @example
texinfo.texi(,13024) texindex foo.??
texinfo.texi(,13025) @end example
texinfo.texi(,13026) 
texinfo.texi(,13027) @noindent
texinfo.texi(,13028) This command will run @code{texindex} on all the unsorted index files,
texinfo.texi(,13029) including any that you have defined yourself using @code{@@defindex}
texinfo.texi(,13030) or @code{@@defcodeindex}.  (You may execute @samp{texindex foo.??}
texinfo.texi(,13031) even if there are similarly named files with two letter extensions
texinfo.texi(,13032) that are not index files, such as @samp{foo.el}.  The @code{texindex}
texinfo.texi(,13033) command reports but otherwise ignores such files.)
texinfo.texi(,13034) 
texinfo.texi(,13035) For each file specified, @code{texindex} generates a sorted index file
texinfo.texi(,13036) whose name is made by appending @samp{s} to the input file name.  The
texinfo.texi(,13037) @code{@@printindex} command looks for a file with that name
texinfo.texi(,13038) (@pxref{Printing Indices & Menus}).  @code{texindex} does not alter the
texinfo.texi(,13039) raw index output file.
texinfo.texi(,13040) 
texinfo.texi(,13041) After you have sorted the indices, you need to rerun the @code{tex}
texinfo.texi(,13042) formatting command on the Texinfo file.  This regenerates the DVI file,
texinfo.texi(,13043) this time with up-to-date index entries.
texinfo.texi(,13044) 
texinfo.texi(,13045) Finally, you may need to run @code{tex} one more time, to get the page
texinfo.texi(,13046) numbers in the cross-references correct.
texinfo.texi(,13047) 
texinfo.texi(,13048) To summarize, this is a five step process:
texinfo.texi(,13049) 
texinfo.texi(,13050) @enumerate
texinfo.texi(,13051) @item
texinfo.texi(,13052) Run @code{tex} on your Texinfo file.  This generates a DVI file (with
texinfo.texi(,13053) undefined cross-references and no indices), and the raw index files
texinfo.texi(,13054) (with two letter extensions).
texinfo.texi(,13055) 
texinfo.texi(,13056) @item
texinfo.texi(,13057) Run @code{texindex} on the raw index files.  This creates the
texinfo.texi(,13058) corresponding sorted index files (with three letter extensions).
texinfo.texi(,13059) 
texinfo.texi(,13060) @item
texinfo.texi(,13061) Run @code{tex} again on your Texinfo file.  This regenerates the DVI
texinfo.texi(,13062) file, this time with indices and defined cross-references, but with page
texinfo.texi(,13063) numbers for the cross-references from last time, generally incorrect.
texinfo.texi(,13064) 
texinfo.texi(,13065) @item
texinfo.texi(,13066) Sort the indices again, with @code{texindex}.
texinfo.texi(,13067) 
texinfo.texi(,13068) @item
texinfo.texi(,13069) Run @code{tex} one last time.  This time the correct page numbers are
texinfo.texi(,13070) written for the cross-references.
texinfo.texi(,13071) @end enumerate
texinfo.texi(,13072) 
texinfo.texi(,13073) @pindex texi2dvi
texinfo.texi(,13074) Alternatively, it's a one-step process: run @code{texi2dvi}
texinfo.texi(,13075) (@pxref{Format with texi2dvi}).
texinfo.texi(,13076) 
texinfo.texi(,13077) You need not run @code{texindex} each time after you run @code{tex}.  If
texinfo.texi(,13078) you do not, on the next run, the @code{tex} formatting command will use
texinfo.texi(,13079) whatever sorted index files happen to exist from the previous use of
texinfo.texi(,13080) @code{texindex}.  This is usually ok while you are debugging.
texinfo.texi(,13081) 
texinfo.texi(,13082) @cindex Auxiliary files, avoiding
texinfo.texi(,13083) @findex novalidate
texinfo.texi(,13084) @cindex Pointer validation, suppressing
texinfo.texi(,13085) @cindex Chapters, formatting one at a time
texinfo.texi(,13086) Sometimes you may wish to print a document while you know it is
texinfo.texi(,13087) incomplete, or to print just one chapter of a document.  In that case,
texinfo.texi(,13088) the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
texinfo.texi(,13089) when cross-references are not satisfied are just nuisances.  You can
texinfo.texi(,13090) avoid them with the @code{@@novalidate} command, which you must give
texinfo.texi(,13091) @emph{before} the @code{@@setfilename} command
texinfo.texi(,13092) (@pxref{setfilename,,@code{@@setfilename}}).  Thus, the beginning of
texinfo.texi(,13093) your file would look approximately like this:
texinfo.texi(,13094) 
texinfo.texi(,13095) @example
texinfo.texi(,13096) \input texinfo
texinfo.texi(,13097) @@novalidate
texinfo.texi(,13098) @@setfilename myfile.info
texinfo.texi(,13099) @dots{}
texinfo.texi(,13100) @end example
texinfo.texi(,13101) 
texinfo.texi(,13102) @noindent @code{@@novalidate} also turns off validation in
texinfo.texi(,13103) @code{makeinfo}, just like its @code{--no-validate} option
texinfo.texi(,13104) (@pxref{Pointer Validation}).
texinfo.texi(,13105) 
texinfo.texi(,13106) 
texinfo.texi(,13107) @node Format with texi2dvi
texinfo.texi(,13108) @section Format with @code{texi2dvi}
texinfo.texi(,13109) @pindex texi2dvi @r{(shell script)}
texinfo.texi(,13110) 
texinfo.texi(,13111) The @code{texi2dvi} command automatically runs both @code{tex} and
texinfo.texi(,13112) @code{texindex} as many times as necessary to produce a DVI file with
texinfo.texi(,13113) sorted indices and all cross-references resolved.  It simplifies the
texinfo.texi(,13114) @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
texinfo.texi(,13115) described in the previous section.
texinfo.texi(,13116) 
texinfo.texi(,13117) To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
texinfo.texi(,13118) @samp{prompt$ } is your shell prompt):
texinfo.texi(,13119) 
texinfo.texi(,13120) @example
texinfo.texi(,13121) prompt$ @kbd{texi2dvi foo.texi}
texinfo.texi(,13122) @end example
texinfo.texi(,13123) 
texinfo.texi(,13124) As shown in this example, the input filenames to @code{texi2dvi} must
texinfo.texi(,13125) include any extension (@samp{.texi}, @samp{.texinfo}, etc.).  Under
texinfo.texi(,13126) MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
texinfo.texi(,13127) texi2dvi foo.texi} instead of relying on the operating system to invoke
texinfo.texi(,13128) the shell on the @samp{texi2dvi} script.
texinfo.texi(,13129) 
texinfo.texi(,13130) Perhaps the most useful option to @code{texi2dvi} is
texinfo.texi(,13131) @samp{--texinfo=@var{cmd}}.  This inserts @var{cmd} on a line by itself
texinfo.texi(,13132) after the @code{@@setfilename} in a temporary copy of the input file
texinfo.texi(,13133) before running @TeX{}.  With this, you can specify different printing
texinfo.texi(,13134) formats, such as @code{@@smallbook} (@pxref{smallbook}),
texinfo.texi(,13135) @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
texinfo.texi(,13136) (@pxref{pagesizes}), without actually changing the document source.
texinfo.texi(,13137) (You can also do this on a site-wide basis with @file{texinfo.cnf};
texinfo.texi(,13138) @pxref{Preparing for TeX,,Preparing for @TeX{}}).
texinfo.texi(,13139) 
texinfo.texi(,13140) For a list of other options, run @samp{texi2dvi --help}.
texinfo.texi(,13141) 
texinfo.texi(,13142) 
texinfo.texi(,13143) @node Print with lpr
texinfo.texi(,13144) @section Shell Print Using @code{lpr -d}
texinfo.texi(,13145) @pindex lpr @r{(DVI print command)}
texinfo.texi(,13146) 
texinfo.texi(,13147) The precise command to print a DVI file depends on your system
texinfo.texi(,13148) installation.  Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
texinfo.texi(,13149) -d foo.dvi}.  
texinfo.texi(,13150) 
texinfo.texi(,13151) For example, the following commands will (perhaps) suffice to sort the
texinfo.texi(,13152) indices, format, and print the @cite{Bison Manual}:
texinfo.texi(,13153) 
texinfo.texi(,13154) @example
texinfo.texi(,13155) @group
texinfo.texi(,13156) tex bison.texinfo
texinfo.texi(,13157) texindex bison.??
texinfo.texi(,13158) tex bison.texinfo
texinfo.texi(,13159) lpr -d bison.dvi
texinfo.texi(,13160) @end group
texinfo.texi(,13161) @end example
texinfo.texi(,13162) 
texinfo.texi(,13163) @noindent
texinfo.texi(,13164) (Remember that the shell commands may be different at your site; but
texinfo.texi(,13165) these are commonly used versions.)
texinfo.texi(,13166) 
texinfo.texi(,13167) Using the @code{texi2dvi} shell script (see the previous section):
texinfo.texi(,13168) 
texinfo.texi(,13169) @example
texinfo.texi(,13170) @group
texinfo.texi(,13171) texi2dvi bison.texinfo
texinfo.texi(,13172) lpr -d bison.dvi
texinfo.texi(,13173) # or perhaps dvips bison.dvi -o
texinfo.texi(,13174) @end group
texinfo.texi(,13175) @end example
texinfo.texi(,13176) 
texinfo.texi(,13177) @cindex Shell printing, on MS-DOS/MS-Windows
texinfo.texi(,13178) @cindex Printing DVI files, on MS-DOS/MS-Windows
texinfo.texi(,13179) @pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
texinfo.texi(,13180) @code{lpr} is a standard program on Unix systems, but it is usually
texinfo.texi(,13181) absent on MS-DOS/MS-Windows.  Some network packages come with a
texinfo.texi(,13182) program named @code{lpr}, but these are usually limited to sending files
texinfo.texi(,13183) to a print server over the network, and generally don't support the
texinfo.texi(,13184) @samp{-d} option.  If you are unfortunate enough to work on one of these
texinfo.texi(,13185) systems, you have several alternative ways of printing DVI files:
texinfo.texi(,13186) 
texinfo.texi(,13187) @itemize @bullet{}
texinfo.texi(,13188) @item Find and install a Unix-like @code{lpr} program, or its clone.
texinfo.texi(,13189) If you can do that, you will be able to print DVI files just like
texinfo.texi(,13190) described above.
texinfo.texi(,13191) 
texinfo.texi(,13192) @item Send the DVI files to a network printer queue for DVI files.
texinfo.texi(,13193) Some network printers have special queues for printing DVI files.  You
texinfo.texi(,13194) should be able to set up your network software to send files to that
texinfo.texi(,13195) queue.  In some cases, the version of @code{lpr} which comes with your
texinfo.texi(,13196) network software will have a special option to send a file to specific
texinfo.texi(,13197) queues, like this:
texinfo.texi(,13198) 
texinfo.texi(,13199) @example
texinfo.texi(,13200) lpr -Qdvi -hprint.server.domain bison.dvi
texinfo.texi(,13201) @end example
texinfo.texi(,13202) 
texinfo.texi(,13203) @item Convert the DVI file to a Postscript or PCL file and send it to your
texinfo.texi(,13204) local printer.  @xref{dvips invocation,,, dvips, Dvips}, and the man
texinfo.texi(,13205) pages for @code{dvilj}, for detailed description of these tools.  Once
texinfo.texi(,13206) the DVI file is converted to the format your local printer understands
texinfo.texi(,13207) directly, just send it to the appropriate port, usually @samp{PRN}.
texinfo.texi(,13208) @end itemize
texinfo.texi(,13209) 
texinfo.texi(,13210) 
texinfo.texi(,13211) @node Within Emacs
texinfo.texi(,13212) @section From an Emacs Shell
texinfo.texi(,13213) @cindex Print, format from Emacs shell
texinfo.texi(,13214) @cindex Format, print from Emacs shell
texinfo.texi(,13215) @cindex Shell, format, print from
texinfo.texi(,13216) @cindex Emacs shell, format, print from
texinfo.texi(,13217) @cindex GNU Emacs shell, format, print from
texinfo.texi(,13218) 
texinfo.texi(,13219) You can give formatting and printing commands from a shell within GNU
texinfo.texi(,13220) Emacs.  To create a shell within Emacs, type @kbd{M-x shell}.  In this
texinfo.texi(,13221) shell, you can format and print the document.  @xref{Hardcopy, , Format
texinfo.texi(,13222) and Print Hardcopy}, for details.
texinfo.texi(,13223) 
texinfo.texi(,13224) You can switch to and from the shell buffer while @code{tex} is
texinfo.texi(,13225) running and do other editing.  If you are formatting a long document
texinfo.texi(,13226) on a slow machine, this can be very convenient.@refill
texinfo.texi(,13227) 
texinfo.texi(,13228) You can also use @code{texi2dvi} from an Emacs shell.  For example,
texinfo.texi(,13229) here is how to use @code{texi2dvi} to format and print @cite{Using and
texinfo.texi(,13230) Porting GNU CC} from a shell within Emacs:
texinfo.texi(,13231) 
texinfo.texi(,13232) @example
texinfo.texi(,13233) @group
texinfo.texi(,13234) texi2dvi gcc.texinfo
texinfo.texi(,13235) lpr -d gcc.dvi
texinfo.texi(,13236) @end group
texinfo.texi(,13237) @end example
texinfo.texi(,13239) 
texinfo.texi(,13240) @xref{Texinfo Mode Printing}, for more information about formatting
texinfo.texi(,13241) and printing in Texinfo mode.@refill
texinfo.texi(,13243) 
texinfo.texi(,13244) 
texinfo.texi(,13245) @node Texinfo Mode Printing, Compile-Command, Within Emacs, Hardcopy
texinfo.texi(,13246) @section Formatting and Printing in Texinfo Mode
texinfo.texi(,13247) @cindex Region printing in Texinfo mode
texinfo.texi(,13248) @cindex Format and print in Texinfo mode
texinfo.texi(,13249) @cindex Print and format in Texinfo mode
texinfo.texi(,13250) 
texinfo.texi(,13251) Texinfo mode provides several predefined key commands for @TeX{}
texinfo.texi(,13252) formatting and printing.  These include commands for sorting indices,
texinfo.texi(,13253) looking at the printer queue, killing the formatting job, and
texinfo.texi(,13254) recentering the display of the buffer in which the operations
texinfo.texi(,13255) occur.@refill
texinfo.texi(,13256) 
texinfo.texi(,13257) @table @kbd
texinfo.texi(,13258) @item C-c C-t C-b
texinfo.texi(,13259) @itemx M-x texinfo-tex-buffer
texinfo.texi(,13260) Run @code{texi2dvi} on the current buffer.@refill
texinfo.texi(,13261) 
texinfo.texi(,13262) @item C-c C-t C-r
texinfo.texi(,13263) @itemx M-x texinfo-tex-region
texinfo.texi(,13264) Run @TeX{} on the current region.@refill
texinfo.texi(,13265) 
texinfo.texi(,13266) @item C-c C-t C-i
texinfo.texi(,13267) @itemx M-x texinfo-texindex
texinfo.texi(,13268) Sort the indices of a Texinfo file formatted with
texinfo.texi(,13269) @code{texinfo-tex-region}.@refill
texinfo.texi(,13270) 
texinfo.texi(,13271) @item C-c C-t C-p
texinfo.texi(,13272) @itemx M-x texinfo-tex-print
texinfo.texi(,13273) Print a DVI file that was made with @code{texinfo-tex-region} or
texinfo.texi(,13274) @code{texinfo-tex-buffer}.@refill
texinfo.texi(,13275) 
texinfo.texi(,13276) @item C-c C-t C-q
texinfo.texi(,13277) @itemx M-x tex-show-print-queue
texinfo.texi(,13278) Show the print queue.@refill
texinfo.texi(,13279) 
texinfo.texi(,13280) @item C-c C-t C-d
texinfo.texi(,13281) @itemx M-x texinfo-delete-from-print-queue
texinfo.texi(,13282) Delete a job from the print queue; you will be prompted for the job
texinfo.texi(,13283) number shown by a preceding @kbd{C-c C-t C-q} command
texinfo.texi(,13284) (@code{texinfo-show-tex-print-queue}).@refill
texinfo.texi(,13285) 
texinfo.texi(,13286) @item C-c C-t C-k
texinfo.texi(,13287) @itemx M-x tex-kill-job
texinfo.texi(,13288) Kill the currently running @TeX{} job started by either
texinfo.texi(,13289) @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
texinfo.texi(,13290) process running in the Texinfo shell buffer.@refill
texinfo.texi(,13291) 
texinfo.texi(,13292) @item C-c C-t C-x
texinfo.texi(,13293) @itemx M-x texinfo-quit-job
texinfo.texi(,13294) Quit a @TeX{} formatting job that has stopped because of an error by
texinfo.texi(,13295) sending an @key{x} to it.  When you do this, @TeX{} preserves a record
texinfo.texi(,13296) of what it did in a @file{.log} file.@refill
texinfo.texi(,13297) 
texinfo.texi(,13298) @item C-c C-t C-l
texinfo.texi(,13299) @itemx M-x tex-recenter-output-buffer
texinfo.texi(,13300) Redisplay the shell buffer in which the @TeX{} printing and formatting
texinfo.texi(,13301) commands are run to show its most recent output.@refill
texinfo.texi(,13302) @end table
texinfo.texi(,13303) 
texinfo.texi(,13304) @need 1000
texinfo.texi(,13305) Thus, the usual sequence of commands for formatting a buffer is as
texinfo.texi(,13306) follows (with comments to the right):@refill
texinfo.texi(,13307) 
texinfo.texi(,13308) @example
texinfo.texi(,13309) @group
texinfo.texi(,13310) C-c C-t C-b             @r{Run @code{texi2dvi} on the buffer.}
texinfo.texi(,13311) C-c C-t C-p             @r{Print the DVI file.}
texinfo.texi(,13312) C-c C-t C-q             @r{Display the printer queue.}
texinfo.texi(,13313) @end group
texinfo.texi(,13314) @end example
texinfo.texi(,13315) 
texinfo.texi(,13316) The Texinfo mode @TeX{} formatting commands start a subshell in Emacs
texinfo.texi(,13317) called the @file{*tex-shell*}.  The @code{texinfo-tex-command},
texinfo.texi(,13318) @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
texinfo.texi(,13319) commands are all run in this shell.
texinfo.texi(,13320) 
texinfo.texi(,13321) You can watch the commands operate in the @samp{*tex-shell*} buffer,
texinfo.texi(,13322) and you can switch to and from and use the @samp{*tex-shell*} buffer
texinfo.texi(,13323) as you would any other shell buffer.@refill
texinfo.texi(,13324) 
texinfo.texi(,13325) @need 1500
texinfo.texi(,13326) The formatting and print commands depend on the values of several variables.
texinfo.texi(,13327) The default values are:@refill
texinfo.texi(,13328) 
texinfo.texi(,13329) @example
texinfo.texi(,13330) @group
texinfo.texi(,13331)      @r{Variable}                              @r{Default value}
texinfo.texi(,13332) 
texinfo.texi(,13333) texinfo-texi2dvi-command                  "texi2dvi"
texinfo.texi(,13334) texinfo-tex-command                       "tex"
texinfo.texi(,13335) texinfo-texindex-command                  "texindex"
texinfo.texi(,13336) texinfo-delete-from-print-queue-command   "lprm"
texinfo.texi(,13337) texinfo-tex-trailer                       "@@bye"
texinfo.texi(,13338) tex-start-of-header                       "%**start"
texinfo.texi(,13339) tex-end-of-header                         "%**end"
texinfo.texi(,13340) tex-dvi-print-command                     "lpr -d"
texinfo.texi(,13341) tex-show-queue-command                    "lpq"
texinfo.texi(,13342) @end group
texinfo.texi(,13343) @end example
texinfo.texi(,13344) 
texinfo.texi(,13345) You can change the values of these variables with the @kbd{M-x
texinfo.texi(,13346) edit-options} command (@pxref{Edit Options, , Editing Variable Values,
texinfo.texi(,13347) emacs, The GNU Emacs Manual}), with the @kbd{M-x set-variable} command
texinfo.texi(,13348) (@pxref{Examining, , Examining and Setting Variables, emacs, The GNU
texinfo.texi(,13349) Emacs Manual}), or with your @file{.emacs} initialization file
texinfo.texi(,13350) (@pxref{Init File, , , emacs, The GNU Emacs Manual}).@refill
texinfo.texi(,13351) 
texinfo.texi(,13352) @cindex Customize Emacs package (@t{Development/Docs/Texinfo})
texinfo.texi(,13353) Beginning with version 20, GNU Emacs offers a user-friendly interface,
texinfo.texi(,13354) called @dfn{Customize}, for changing values of user-definable variables.
texinfo.texi(,13355) @xref{Easy Customization, , Easy Customization Interface, emacs, The GNU
texinfo.texi(,13356) Emacs Manual}, for more details about this.  The Texinfo variables can
texinfo.texi(,13357) be found in the @samp{Development/Docs/Texinfo} group, once you invoke
texinfo.texi(,13358) the @kbd{M-x customize} command.
texinfo.texi(,13359) 
texinfo.texi(,13360) 
texinfo.texi(,13361) @node Compile-Command
texinfo.texi(,13362) @section Using the Local Variables List
texinfo.texi(,13363) @cindex Local variables
texinfo.texi(,13364) @cindex Compile command for formatting
texinfo.texi(,13365) @cindex Format with the compile command
texinfo.texi(,13366) 
texinfo.texi(,13367) Yet another way to apply the @TeX{} formatting command to a Texinfo file
texinfo.texi(,13368) is to put that command in a @dfn{local variables list} at the end of the
texinfo.texi(,13369) Texinfo file.  You can then specify the @code{tex} or @code{texi2dvi}
texinfo.texi(,13370) commands as a @code{compile-command} and have Emacs run it by typing
texinfo.texi(,13371) @kbd{M-x compile}.  This creates a special shell called the
texinfo.texi(,13372) @file{*compilation*} buffer in which Emacs runs the compile command.
texinfo.texi(,13373) For example, at the end of the @file{gdb.texinfo} file, after the
texinfo.texi(,13374) @code{@@bye}, you could put the following:@refill
texinfo.texi(,13375) 
texinfo.texi(,13376) @example
texinfo.texi(,13377) @group
texinfo.texi(,13378) Local Variables:
texinfo.texi(,13379) compile-command: "texi2dvi gdb.texinfo"
texinfo.texi(,13380) End:
texinfo.texi(,13381) @end group
texinfo.texi(,13382) @end example
texinfo.texi(,13383) 
texinfo.texi(,13384) @noindent
texinfo.texi(,13385) This technique is most often used by programmers who also compile programs
texinfo.texi(,13386) this way; see @ref{Compilation, , , emacs, The GNU Emacs Manual}.@refill
texinfo.texi(,13387) 
texinfo.texi(,13388) 
texinfo.texi(,13389) @node Requirements Summary
texinfo.texi(,13390) @section @TeX{} Formatting Requirements Summary
texinfo.texi(,13391) @cindex Requirements for formatting
texinfo.texi(,13392) @cindex Minimal requirements for formatting
texinfo.texi(,13393) @cindex Formatting requirements
texinfo.texi(,13394) 
texinfo.texi(,13395) Every Texinfo file that is to be input to @TeX{} must begin with a
texinfo.texi(,13396) @code{\input} command and must contain an @code{@@setfilename} command:
texinfo.texi(,13397) 
texinfo.texi(,13398) @example
texinfo.texi(,13399) \input texinfo
texinfo.texi(,13400) @@setfilename @var{arg-not-used-by-@TeX{}}
texinfo.texi(,13401) @end example
texinfo.texi(,13402) 
texinfo.texi(,13403) @noindent
texinfo.texi(,13404) The first command instructs @TeX{} to load the macros it needs to
texinfo.texi(,13405) process a Texinfo file and the second command opens auxiliary files.
texinfo.texi(,13406) 
texinfo.texi(,13407) Every Texinfo file must end with a line that terminates @TeX{}'s
texinfo.texi(,13408) processing and forces out unfinished pages:
texinfo.texi(,13409) 
texinfo.texi(,13410) @example
texinfo.texi(,13411) @@bye
texinfo.texi(,13412) @end example
texinfo.texi(,13413) 
texinfo.texi(,13414) Strictly speaking, these lines are all a Texinfo file needs to be
texinfo.texi(,13415) processed successfully by @TeX{}.
texinfo.texi(,13416) 
texinfo.texi(,13417) Usually, however, the beginning includes an @code{@@settitle} command to
texinfo.texi(,13418) define the title of the printed manual, an @code{@@setchapternewpage}
texinfo.texi(,13419) command, a title page, a copyright page, and permissions.  Besides an
texinfo.texi(,13420) @code{@@bye}, the end of a file usually includes indices and a table of
texinfo.texi(,13421) contents.  (And of course most manuals contain a body of text as well.)
texinfo.texi(,13422) 
texinfo.texi(,13423) For more information, see:
texinfo.texi(,13424) @itemize @bullet
texinfo.texi(,13425) @item @ref{settitle, , @code{@@settitle}}
texinfo.texi(,13426) @item @ref{setchapternewpage, , @code{@@setchapternewpage}}
texinfo.texi(,13427) @item @ref{Headings, ,Page Headings}
texinfo.texi(,13428) @item @ref{Titlepage & Copyright Page}
texinfo.texi(,13429) @item @ref{Printing Indices & Menus}
texinfo.texi(,13430) @item @ref{Contents}
texinfo.texi(,13431) @end itemize
texinfo.texi(,13432) 
texinfo.texi(,13433) 
texinfo.texi(,13434) @node Preparing for TeX
texinfo.texi(,13435) @section Preparing for @TeX{}
texinfo.texi(,13436) @cindex Preparing for @TeX{}
texinfo.texi(,13437) @cindex @TeX{} input initialization
texinfo.texi(,13438) @cindex @code{TEXINPUTS} environment variable
texinfo.texi(,13439) @vindex TEXINPUTS
texinfo.texi(,13440) @cindex @b{.profile} initialization file
texinfo.texi(,13441) @cindex @b{.cshrc} initialization file
texinfo.texi(,13442) @cindex Initialization file for @TeX{} input
texinfo.texi(,13443) 
texinfo.texi(,13444) @TeX{} needs to know where to find the @file{texinfo.tex} file that the
texinfo.texi(,13445) @samp{\input texinfo} command on the first line reads.  The
texinfo.texi(,13446) @file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
texinfo.texi(,13447) included in all standard GNU distributions.
texinfo.texi(,13448) 
texinfo.texi(,13449) @pindex texinfo.tex@r{, installing}
texinfo.texi(,13450) 
texinfo.texi(,13451) Usually, the installer has put the @file{texinfo.tex} file in the
texinfo.texi(,13452) default directory that contains @TeX{} macros when GNU Texinfo, Emacs or
texinfo.texi(,13453) other GNU software is installed.  In this case, @TeX{} will find the
texinfo.texi(,13454) file and you do not need to do anything special.  If this has not been
texinfo.texi(,13455) done, you can put @file{texinfo.tex} in the current directory when you
texinfo.texi(,13456) run @TeX{}, and @TeX{} will find it there.
texinfo.texi(,13457) 
texinfo.texi(,13458) @pindex epsf.tex@r{, installing}
texinfo.texi(,13459) Also, you should install @file{epsf.tex}, if it is not already installed
texinfo.texi(,13460) from another distribution.  More details are at the end of the description
texinfo.texi(,13461) of the @code{@@image} command (@pxref{Images}).
texinfo.texi(,13462) 
texinfo.texi(,13463) @pindex pdfcolor.tex@r{, installing}
texinfo.texi(,13464) Likewise for @file{pdfcolor.tex}, if it is not already installed and you
texinfo.texi(,13465) use pdftex.
texinfo.texi(,13466) 
texinfo.texi(,13467) @pindex texinfo.cnf @r{installation}
texinfo.texi(,13468) @cindex Customizing of @TeX{} for Texinfo
texinfo.texi(,13469) @cindex Site-wide Texinfo configuration file
texinfo.texi(,13470) Optionally, you may create an additional @file{texinfo.cnf}, and install
texinfo.texi(,13471) it as well.  This file is read by @TeX{} when the @code{@@setfilename}
texinfo.texi(,13472) command is executed (@pxref{setfilename,, @code{@@setfilename}}).  You can put any
texinfo.texi(,13473) commands you like there, according to local site-wide conventions.  They
texinfo.texi(,13474) will be read by @TeX{} when processing any Texinfo document.  For
texinfo.texi(,13475) example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
texinfo.texi(,13476) (@pxref{A4 Paper}), then all Texinfo documents will be processed with
texinfo.texi(,13477) that page size in effect.  If you have nothing to put in
texinfo.texi(,13478) @file{texinfo.cnf}, you do not need to create it.
texinfo.texi(,13479) 
texinfo.texi(,13480) @vindex TEXINPUTS
texinfo.texi(,13481) If neither of the above locations for these system files suffice for
texinfo.texi(,13482) you, you can specify the directories explicitly.  For
texinfo.texi(,13483) @file{texinfo.tex}, you can do this by writing the complete path for the
texinfo.texi(,13484) file after the @code{\input} command.  Another way, that works for both
texinfo.texi(,13485) @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
texinfo.texi(,13486) might read), is to set the @code{TEXINPUTS} environment variable in your
texinfo.texi(,13487) @file{.cshrc} or @file{.profile} file.
texinfo.texi(,13488) 
texinfo.texi(,13489) Which you use of @file{.cshrc} or @file{.profile} depends on
texinfo.texi(,13490) whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
texinfo.texi(,13491) @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
texinfo.texi(,13492) command interpreter.  The latter read the @file{.cshrc} file for
texinfo.texi(,13493) initialization information, and the former read @file{.profile}.
texinfo.texi(,13494) 
texinfo.texi(,13495) In a @file{.cshrc} file, you could use the following @code{csh} command
texinfo.texi(,13496) sequence:
texinfo.texi(,13497) 
texinfo.texi(,13498) @example
texinfo.texi(,13499) setenv TEXINPUTS .:/home/me/mylib:/usr/lib/tex/macros
texinfo.texi(,13500) @end example
texinfo.texi(,13501) 
texinfo.texi(,13502) @need 1000
texinfo.texi(,13503) In a @file{.profile} file, you could use the following @code{sh} command
texinfo.texi(,13504) sequence:
texinfo.texi(,13505) 
texinfo.texi(,13506) @example
texinfo.texi(,13507) @group
texinfo.texi(,13508) TEXINPUTS=.:/home/me/mylib:/usr/lib/tex/macros
texinfo.texi(,13509) export TEXINPUTS
texinfo.texi(,13510) @end group
texinfo.texi(,13511) @end example
texinfo.texi(,13512) 
texinfo.texi(,13513) On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
texinfo.texi(,13514) of the @samp{;} character, instead of @samp{:}, as directory separator
texinfo.texi(,13515) on these systems.}:
texinfo.texi(,13516) 
texinfo.texi(,13517) @example
texinfo.texi(,13518) @group
texinfo.texi(,13519) set TEXINPUTS=.;d:/home/me/mylib;c:/usr/lib/tex/macros
texinfo.texi(,13520) @end group
texinfo.texi(,13521) @end example
texinfo.texi(,13522) 
texinfo.texi(,13523) @noindent
texinfo.texi(,13524) It is customary for DOS/Windows users to put such commands in the
texinfo.texi(,13525) @file{autoexec.bat} file, or in the Windows Registry.@refill
texinfo.texi(,13526) 
texinfo.texi(,13527) @noindent
texinfo.texi(,13528) These settings would cause @TeX{} to look for @file{\input} file first
texinfo.texi(,13529) in the current directory, indicated by the @samp{.}, then in a
texinfo.texi(,13530) hypothetical user's @file{me/mylib} directory, and finally in a system
texinfo.texi(,13531) directory @file{/usr/lib/tex/macros}.
texinfo.texi(,13532) 
texinfo.texi(,13533) @cindex Dumping a .fmt file
texinfo.texi(,13534) @cindex Format file, dumping
texinfo.texi(,13535) Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
texinfo.texi(,13536) web2c, Web2c}) so that @TeX{} can load Texinfo faster.  (The
texinfo.texi(,13537) disadvantage is that then updating @file{texinfo.tex} requires
texinfo.texi(,13538) redumping.)  You can do this by running this command, assuming
texinfo.texi(,13539) @file{epsf.tex} is findable by @TeX{}:
texinfo.texi(,13540) 
texinfo.texi(,13541) @example
texinfo.texi(,13542) initex texinfo @@dump
texinfo.texi(,13543) @end example
texinfo.texi(,13544) 
texinfo.texi(,13545) (@code{dump} is a @TeX{} primitive.)  Then, move @file{texinfo.fmt} to
texinfo.texi(,13546) wherever your @code{.fmt} files are found; typically, this will be in the
texinfo.texi(,13547) subdirectory @file{web2c} of your @TeX{} installation.
texinfo.texi(,13548) 
texinfo.texi(,13549) 
texinfo.texi(,13550) @node Overfull hboxes
texinfo.texi(,13551) @section Overfull ``hboxes''
texinfo.texi(,13552) @cindex Overfull @samp{hboxes}
texinfo.texi(,13553) @cindex @samp{hboxes}, overfull
texinfo.texi(,13554) @cindex Final output
texinfo.texi(,13555) 
texinfo.texi(,13556) @TeX{} is sometimes unable to typeset a line without extending it into
texinfo.texi(,13557) the right margin.  This can occur when @TeX{} comes upon what it
texinfo.texi(,13558) interprets as a long word that it cannot hyphenate, such as an
texinfo.texi(,13559) electronic mail network address or a very long title.  When this
texinfo.texi(,13560) happens, @TeX{} prints an error message like this:
texinfo.texi(,13561) 
texinfo.texi(,13562) @example
texinfo.texi(,13563) Overfull @@hbox (20.76302pt too wide)
texinfo.texi(,13564) @end example
texinfo.texi(,13565) 
texinfo.texi(,13566) @findex hbox
texinfo.texi(,13567) @noindent
texinfo.texi(,13568) (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
texinfo.texi(,13569) @samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
texinfo.texi(,13570) 
texinfo.texi(,13571) @TeX{} also provides the line number in the Texinfo source file and
texinfo.texi(,13572) the text of the offending line, which is marked at all the places that
texinfo.texi(,13573) @TeX{} considered hyphenation.
texinfo.texi(,13574) @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
texinfo.texi(,13575) for more information about typesetting errors.
texinfo.texi(,13576) 
texinfo.texi(,13577) If the Texinfo file has an overfull hbox, you can rewrite the sentence
texinfo.texi(,13578) so the overfull hbox does not occur, or you can decide to leave it.  A
texinfo.texi(,13579) small excursion into the right margin often does not matter and may not
texinfo.texi(,13580) even be noticeable.
texinfo.texi(,13581) 
texinfo.texi(,13582) If you have many overfull boxes and/or an antipathy to rewriting, you
texinfo.texi(,13583) can coerce @TeX{} into greatly increasing the allowable interword
texinfo.texi(,13584) spacing, thus (if you're lucky) avoiding many of the bad line breaks,
texinfo.texi(,13585) like this:
texinfo.texi(,13586) 
texinfo.texi(,13587) @findex \emergencystretch
texinfo.texi(,13588) @example
texinfo.texi(,13589) @@tex
texinfo.texi(,13590) \global\emergencystretch = .9\hsize
texinfo.texi(,13591) @@end tex
texinfo.texi(,13592) @end example
texinfo.texi(,13593) 
texinfo.texi(,13594) @noindent
texinfo.texi(,13595) (You should adjust the fraction as needed.)  This huge value for
texinfo.texi(,13596) @code{\emergencystretch} cannot be the default, since then the typeset
texinfo.texi(,13597) output would generally be of noticeably lower quality; the default
texinfo.texi(,13598) is @samp{.15\hsize}.  @code{\hsize} is the @TeX{} dimension
texinfo.texi(,13599) containing the current line width.
texinfo.texi(,13600) 
texinfo.texi(,13601) @cindex Black rectangle in hardcopy
texinfo.texi(,13602) @cindex Rectangle, black in hardcopy
texinfo.texi(,13603) @cindex Box, ugly black in hardcopy
texinfo.texi(,13604) @cindex Ugly black rectangles in hardcopy
texinfo.texi(,13605) For what overfull boxes you have, however, @TeX{} will print a large,
texinfo.texi(,13606) ugly, black rectangle beside the line that contains the overfull hbox
texinfo.texi(,13607) unless told otherwise.  This is so you will notice the location of the
texinfo.texi(,13608) problem if you are correcting a draft.
texinfo.texi(,13609) 
texinfo.texi(,13610) @findex finalout
texinfo.texi(,13611) To prevent such a monstrosity from marring your final printout, write
texinfo.texi(,13612) the following in the beginning of the Texinfo file on a line of its own,
texinfo.texi(,13613) before the @code{@@titlepage} command:
texinfo.texi(,13614) 
texinfo.texi(,13615) @example
texinfo.texi(,13616) @@finalout
texinfo.texi(,13617) @end example
texinfo.texi(,13618) 
texinfo.texi(,13619) 
texinfo.texi(,13620) @node smallbook
texinfo.texi(,13621) @section Printing ``Small'' Books
texinfo.texi(,13622) @findex smallbook
texinfo.texi(,13623) @cindex Small book size
texinfo.texi(,13624) @cindex Book, printing small
texinfo.texi(,13625) @cindex Page sizes for books
texinfo.texi(,13626) @cindex Size of printed book
texinfo.texi(,13627) 
texinfo.texi(,13628) By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
texinfo.texi(,13629) format.  However, you can direct @TeX{} to typeset a document in a 7 by
texinfo.texi(,13630) 9.25 inch format that is suitable for bound books by inserting the
texinfo.texi(,13631) following command on a line by itself at the beginning of the Texinfo
texinfo.texi(,13632) file, before the title page:@refill
texinfo.texi(,13633) 
texinfo.texi(,13634) @example
texinfo.texi(,13635) @@smallbook
texinfo.texi(,13636) @end example
texinfo.texi(,13637) 
texinfo.texi(,13638) @noindent
texinfo.texi(,13639) (Since many books are about 7 by 9.25 inches, this command might better
texinfo.texi(,13640) have been called the @code{@@regularbooksize} command, but it came to be
texinfo.texi(,13641) called the @code{@@smallbook} command by comparison to the 8.5 by 11 inch format.)
texinfo.texi(,13642) 
texinfo.texi(,13643) If you write the @code{@@smallbook} command between the
texinfo.texi(,13644) start-of-header and end-of-header lines, the Texinfo mode @TeX{}
texinfo.texi(,13645) region formatting command, @code{texinfo-tex-region}, will format the
texinfo.texi(,13646) region in ``small'' book size (@pxref{Start of Header}).@refill
texinfo.texi(,13647) 
texinfo.texi(,13648) @xref{small}, for information about
texinfo.texi(,13649) commands that make it easier to produce examples for a smaller manual.
texinfo.texi(,13650) 
texinfo.texi(,13651) @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
texinfo.texi(,13652) @TeX{}}, for other ways to format with @code{@@smallbook} that do not
texinfo.texi(,13653) require changing the source file.
texinfo.texi(,13654) 
texinfo.texi(,13655) 
texinfo.texi(,13656) @node A4 Paper
texinfo.texi(,13657) @section Printing on A4 Paper
texinfo.texi(,13658) @cindex A4 paper, printing on
texinfo.texi(,13659) @cindex A5 paper, printing on
texinfo.texi(,13660) @cindex Paper size, A4
texinfo.texi(,13661) @cindex European A4 paper
texinfo.texi(,13662) @findex afourpaper
texinfo.texi(,13663) 
texinfo.texi(,13664) You can tell @TeX{} to format a document for printing on European size
texinfo.texi(,13665) A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
texinfo.texi(,13666) command.  Write the command on a line by itself near the beginning of
texinfo.texi(,13667) the Texinfo file, before the title page.  For example, this is how you
texinfo.texi(,13668) would write the header for this manual:
texinfo.texi(,13669) 
texinfo.texi(,13670) @example
texinfo.texi(,13671) @group
texinfo.texi(,13672) \input texinfo    @@c -*-texinfo-*-
texinfo.texi(,13673) @@c %**start of header
texinfo.texi(,13674) @@setfilename texinfo
texinfo.texi(,13675) @@settitle Texinfo
texinfo.texi(,13676) @@afourpaper
texinfo.texi(,13677) @@c %**end of header
texinfo.texi(,13678) @end group
texinfo.texi(,13679) @end example
texinfo.texi(,13680) 
texinfo.texi(,13681) @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
texinfo.texi(,13682) @TeX{}}, for other ways to format for different paper sizes that do not
texinfo.texi(,13683) require changing the source file.
texinfo.texi(,13684) 
texinfo.texi(,13685) @findex afourlatex
texinfo.texi(,13686) @findex afourwide
texinfo.texi(,13687) You may or may not prefer the formatting that results from the command
texinfo.texi(,13688) @code{@@afourlatex}.  There's also @code{@@afourwide} for A4 paper in
texinfo.texi(,13689) wide format.
texinfo.texi(,13690) 
texinfo.texi(,13691) @node pagesizes
texinfo.texi(,13692) @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom page sizes
texinfo.texi(,13693) @findex pagesizes
texinfo.texi(,13694) @cindex Custom page sizes
texinfo.texi(,13695) @cindex Page sizes, customized
texinfo.texi(,13696) @cindex Text width and height
texinfo.texi(,13697) @cindex Width of text area
texinfo.texi(,13698) @cindex Height of text area
texinfo.texi(,13699) @cindex Depth of text area
texinfo.texi(,13700) 
texinfo.texi(,13701) You can explicitly specify the height and (optionally) width of the main
texinfo.texi(,13702) text area on the page with the @code{@@pagesizes} command.  Write this
texinfo.texi(,13703) on a line by itself near the beginning of the Texinfo file, before the
texinfo.texi(,13704) title page.  The height comes first, then the width if desired,
texinfo.texi(,13705) separated by a comma.  Examples:
texinfo.texi(,13706) 
texinfo.texi(,13707) @example
texinfo.texi(,13708) @@pagesizes 200mm,150mm  @c for b5 paper
texinfo.texi(,13709) @end example
texinfo.texi(,13710) @noindent and
texinfo.texi(,13711) @example
texinfo.texi(,13712) @@pagesizes 11.5in      @c for legal paper
texinfo.texi(,13713) @end example
texinfo.texi(,13714) 
texinfo.texi(,13715) @cindex B5 paper, printing on
texinfo.texi(,13716) @cindex Legal paper, printing on
texinfo.texi(,13717) This would be reasonable for printing on B5-size paper.  To emphasize,
texinfo.texi(,13718) this command specifies the size of the @emph{text area}, not the size of
texinfo.texi(,13719) the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
texinfo.texi(,13720) 8.5@dmn{in} for legal).
texinfo.texi(,13721) 
texinfo.texi(,13722) @cindex Margins on page, not controllable
texinfo.texi(,13723) To make more elaborate changes, such as changing any of the page
texinfo.texi(,13724) margins, you must define a new command in @file{texinfo.tex} (or
texinfo.texi(,13725) @file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
texinfo.texi(,13726) 
texinfo.texi(,13727) @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
texinfo.texi(,13728) @TeX{}}, for other ways to specify @code{@@pagesizes} that do not
texinfo.texi(,13729) require changing the source file.
texinfo.texi(,13730) 
texinfo.texi(,13731) @code{@@pagesizes} is ignored by @code{makeinfo}.
texinfo.texi(,13732) 
texinfo.texi(,13733) 
texinfo.texi(,13734) @node Cropmarks and Magnification
texinfo.texi(,13735) @section Cropmarks and Magnification
texinfo.texi(,13736) @findex cropmarks
texinfo.texi(,13737) @cindex Cropmarks for printing
texinfo.texi(,13738) @cindex Printing cropmarks
texinfo.texi(,13739) You can (attempt to) direct @TeX{} to print cropmarks at the corners of
texinfo.texi(,13740) pages with the @code{@@cropmarks} command.  Write the @code{@@cropmarks}
texinfo.texi(,13741) command on a line by itself between @code{@@iftex} and @code{@@end
texinfo.texi(,13742) iftex} lines near the beginning of the Texinfo file, before the title
texinfo.texi(,13743) page, like this:@refill
texinfo.texi(,13744) 
texinfo.texi(,13745) @example
texinfo.texi(,13746) @group
texinfo.texi(,13747) @@iftex
texinfo.texi(,13748) @@cropmarks
texinfo.texi(,13749) @@end iftex
texinfo.texi(,13750) @end group
texinfo.texi(,13751) @end example
texinfo.texi(,13752) 
texinfo.texi(,13753) This command is mainly for printers that typeset several pages on one
texinfo.texi(,13754) sheet of film; but you can attempt to use it to mark the corners of a
texinfo.texi(,13755) book set to 7 by 9.25 inches with the @code{@@smallbook} command.
texinfo.texi(,13756) (Printers will not produce cropmarks for regular sized output that is
texinfo.texi(,13757) printed on regular sized paper.)  Since different printing machines work
texinfo.texi(,13758) in different ways, you should explore the use of this command with a
texinfo.texi(,13759) spirit of adventure.  You may have to redefine the command in
texinfo.texi(,13760) @file{texinfo.tex}.
texinfo.texi(,13761) 
texinfo.texi(,13762) @findex \mag @r{(raw @TeX{} magnification)}
texinfo.texi(,13763) @cindex Magnified printing
texinfo.texi(,13764) @cindex Larger or smaller pages
texinfo.texi(,13765) You can attempt to direct @TeX{} to typeset pages larger or smaller than
texinfo.texi(,13766) usual with the @code{\mag} @TeX{} command.  Everything that is typeset
texinfo.texi(,13767) is scaled proportionally larger or smaller.  (@code{\mag} stands for
texinfo.texi(,13768) ``magnification''.)  This is @emph{not} a Texinfo @@-command, but is a
texinfo.texi(,13769) plain @TeX{} command that is prefixed with a backslash.  You have to
texinfo.texi(,13770) write this command between @code{@@tex} and @code{@@end tex}
texinfo.texi(,13771) (@pxref{Raw Formatter Commands}).
texinfo.texi(,13772) 
texinfo.texi(,13773) Follow the @code{\mag} command with an @samp{=} and then a number that
texinfo.texi(,13774) is 1000 times the magnification you desire.  For example, to print pages
texinfo.texi(,13775) at 1.2 normal size, write the following near the beginning of the
texinfo.texi(,13776) Texinfo file, before the title page:
texinfo.texi(,13777) 
texinfo.texi(,13778) @example
texinfo.texi(,13779) @group
texinfo.texi(,13780) @@tex
texinfo.texi(,13781) \mag=1200
texinfo.texi(,13782) @@end tex
texinfo.texi(,13783) @end group
texinfo.texi(,13784) @end example
texinfo.texi(,13785) 
texinfo.texi(,13786) With some printing technologies, you can print normal-sized copies that
texinfo.texi(,13787) look better than usual by giving a larger-than-normal master to your
texinfo.texi(,13788) print shop.  They do the reduction, thus effectively increasing the
texinfo.texi(,13789) resolution.
texinfo.texi(,13790) 
texinfo.texi(,13791) Depending on your system, DVI files prepared with a
texinfo.texi(,13792) nonstandard-@code{\mag} may not print or may print only with certain
texinfo.texi(,13793) magnifications.  Be prepared to experiment.
texinfo.texi(,13794) 
texinfo.texi(,13795) 
texinfo.texi(,13796) @node PDF Output
texinfo.texi(,13797) @section PDF Output
texinfo.texi(,13798) @cindex PDF output
texinfo.texi(,13799) 
texinfo.texi(,13800) @pindex pdftex
texinfo.texi(,13801) You can generate a PDF output file from Texinfo source by using the
texinfo.texi(,13802) @command{pdftex} program to process your file instead of plain
texinfo.texi(,13803) @command{tex}.  Just run @samp{pdftex foo.texi} instead of @samp{tex
texinfo.texi(,13804) foo.texi}, or give the @samp{--pdf} option to @command{texi2dvi}.
texinfo.texi(,13805) 
texinfo.texi(,13806) @dfn{PDF} stands for `Portable Document Format'. It was invented by
texinfo.texi(,13807) Adobe Systems some years ago for document interchange, based on their
texinfo.texi(,13808) PostScript language.  A @uref{http://www.foolabs.com/xpdf/, PDF reader}
texinfo.texi(,13809) for the X window system is freely available, as is the
texinfo.texi(,13810) @uref{http://partners.adobe.com/asn/developer/technotes/, definition of
texinfo.texi(,13811) the file format}.  Since PDF is a binary format, there are no
texinfo.texi(,13812) @samp{@@ifpdf} or @samp{@@pdf} commands as with the other output
texinfo.texi(,13813) formats.
texinfo.texi(,13814) 
texinfo.texi(,13815) Despite the `portable' in the name, PDF files are nowhere near as
texinfo.texi(,13816) portable in practice as the plain ASCII formats (Info, HTML) that
texinfo.texi(,13817) Texinfo supports (DVI portability is arguable).  They also tend to be
texinfo.texi(,13818) much larger and do not support the bitmap fonts used by @TeX{} (by
texinfo.texi(,13819) default) very well.  Nevertheless, a PDF file does preserve an actual
texinfo.texi(,13820) printed document on a screen as faithfully as possible, so it has its place.
texinfo.texi(,13821) 
texinfo.texi(,13822) PDF support in Texinfo is fairly rudimentary.
texinfo.texi(,13823) 
texinfo.texi(,13824) 
texinfo.texi(,13825) @node Creating and Installing Info Files
texinfo.texi(,13826) @chapter Creating and Installing Info Files
texinfo.texi(,13827) 
texinfo.texi(,13828) This chapter describes how to create and install Info files.  @xref{Info
texinfo.texi(,13829) Files}, for general information about the file format itself.
texinfo.texi(,13830) 
texinfo.texi(,13831) @menu
texinfo.texi(,13832) * Creating an Info File::       
texinfo.texi(,13833) * Installing an Info File::     
texinfo.texi(,13834) @end menu
texinfo.texi(,13835) 
texinfo.texi(,13836) 
texinfo.texi(,13837) @node Creating an Info File
texinfo.texi(,13838) @section Creating an Info File
texinfo.texi(,13839) @cindex Creating an Info file
texinfo.texi(,13840) @cindex Info, creating an online file
texinfo.texi(,13841) @cindex Formatting a file for Info
texinfo.texi(,13842) 
texinfo.texi(,13843) @code{makeinfo} is a program that converts a Texinfo file into an Info
texinfo.texi(,13844) file, HTML file, or plain text.  @code{texinfo-format-region} and
texinfo.texi(,13845) @code{texinfo-format-buffer} are GNU Emacs functions that convert
texinfo.texi(,13846) Texinfo to Info.
texinfo.texi(,13847) 
texinfo.texi(,13848) For information on installing the Info file in the Info system,
texinfo.texi(,13849) @pxref{Installing an Info File}.
texinfo.texi(,13850) 
texinfo.texi(,13851) @menu
texinfo.texi(,13852) * makeinfo advantages::         @code{makeinfo} provides better error checking.
texinfo.texi(,13853) * Invoking makeinfo::           How to run @code{makeinfo} from a shell.
texinfo.texi(,13854) * makeinfo options::            Specify fill-column and other options.
texinfo.texi(,13855) * Pointer Validation::          How to check that pointers point somewhere.
texinfo.texi(,13856) * makeinfo in Emacs::           How to run @code{makeinfo} from Emacs.
texinfo.texi(,13857) * texinfo-format commands::     Two Info formatting commands written
texinfo.texi(,13858)                                   in Emacs Lisp are an alternative
texinfo.texi(,13859)                                   to @code{makeinfo}.
texinfo.texi(,13860) * Batch Formatting::            How to format for Info in Emacs Batch mode.
texinfo.texi(,13861) * Tag and Split Files::         How tagged and split files help Info
texinfo.texi(,13862)                                   to run better.
texinfo.texi(,13863) * makeinfo html::               Generating HTML output.
texinfo.texi(,13864) @end menu
texinfo.texi(,13865) 
texinfo.texi(,13866) 
texinfo.texi(,13867) @node makeinfo advantages
texinfo.texi(,13868) @subsection @code{makeinfo} Preferred
texinfo.texi(,13869) 
texinfo.texi(,13870) The @code{makeinfo} utility creates an Info file from a Texinfo source
texinfo.texi(,13871) file more quickly than either of the Emacs formatting commands and
texinfo.texi(,13872) provides better error messages.  We recommend it.  @code{makeinfo} is a
texinfo.texi(,13873) C program that is independent of Emacs.  You do not need to run Emacs to
texinfo.texi(,13874) use @code{makeinfo}, which means you can use @code{makeinfo} on machines
texinfo.texi(,13875) that are too small to run Emacs.  You can run @code{makeinfo} in any one
texinfo.texi(,13876) of three ways: from an operating system shell, from a shell inside
texinfo.texi(,13877) Emacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
texinfo.texi(,13878) command in Texinfo mode in Emacs.
texinfo.texi(,13879) @refill
texinfo.texi(,13880) 
texinfo.texi(,13881) The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
texinfo.texi(,13882) commands are useful if you cannot run @code{makeinfo}.  Also, in some
texinfo.texi(,13883) circumstances, they format short regions or buffers more quickly than
texinfo.texi(,13884) @code{makeinfo}.@refill
texinfo.texi(,13885) 
texinfo.texi(,13886) @node Invoking makeinfo
texinfo.texi(,13887) @subsection Running @code{makeinfo} from a Shell
texinfo.texi(,13888) 
texinfo.texi(,13889) To create an Info file from a Texinfo file, type @code{makeinfo}
texinfo.texi(,13890) followed by the name of the Texinfo file.  Thus, to create the Info
texinfo.texi(,13891) file for Bison, type the following to the shell:
texinfo.texi(,13892) 
texinfo.texi(,13893) @example
texinfo.texi(,13894) makeinfo bison.texinfo
texinfo.texi(,13895) @end example
texinfo.texi(,13896) 
texinfo.texi(,13897) (You can run a shell inside Emacs by typing @kbd{M-x shell}.)@refill
texinfo.texi(,13898) 
texinfo.texi(,13900) Sometimes you will want to specify options.  For example, if you wish
texinfo.texi(,13901) to discover which version of @code{makeinfo} you are using,
texinfo.texi(,13902) type:@refill
texinfo.texi(,13903) 
texinfo.texi(,13904) @example
texinfo.texi(,13905) makeinfo --version
texinfo.texi(,13906) @end example
texinfo.texi(,13907) 
texinfo.texi(,13908) @xref{makeinfo options}, for more information.
texinfo.texi(,13910) 
texinfo.texi(,13911) 
texinfo.texi(,13912) @node makeinfo options
texinfo.texi(,13913) @subsection Options for @code{makeinfo}
texinfo.texi(,13914) @cindex @code{makeinfo} options
texinfo.texi(,13915) @cindex Options for @code{makeinfo}
texinfo.texi(,13916) 
texinfo.texi(,13917) The @code{makeinfo} command takes a number of options.  Most often,
texinfo.texi(,13918) options are used to set the value of the fill column and specify the
texinfo.texi(,13919) footnote style.  Each command line option is a word preceded by
texinfo.texi(,13920) @samp{--} or a letter preceded by @samp{-}.  You can use abbreviations
texinfo.texi(,13921) for the long option names as long as they are unique.@refill
texinfo.texi(,13922) 
texinfo.texi(,13923) For example, you could use the following shell command to create an Info
texinfo.texi(,13924) file for @file{bison.texinfo} in which each line is filled to only 68
texinfo.texi(,13925) columns:@refill
texinfo.texi(,13926) 
texinfo.texi(,13927) @example
texinfo.texi(,13928) makeinfo --fill-column=68 bison.texinfo
texinfo.texi(,13929) @end example
texinfo.texi(,13930) 
texinfo.texi(,13931) You can write two or more options in sequence, like this:@refill
texinfo.texi(,13932) 
texinfo.texi(,13933) @example
texinfo.texi(,13934) makeinfo --no-split --fill-column=70 @dots{}
texinfo.texi(,13935) @end example
texinfo.texi(,13936) 
texinfo.texi(,13937) @noindent
texinfo.texi(,13938) This would keep the Info file together as one possibly very long
texinfo.texi(,13939) file and would also set the fill column to 70.@refill
texinfo.texi(,13940) 
texinfo.texi(,13941) The options are:
texinfo.texi(,13942) 
texinfo.texi(,13943) @table @code
texinfo.texi(,13944) 
texinfo.texi(,13945) @item -D @var{var}
texinfo.texi(,13946) @opindex -D @var{var}
texinfo.texi(,13947) Cause the variable @var{var} to be defined.  This is equivalent to
texinfo.texi(,13948) @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
texinfo.texi(,13949) 
texinfo.texi(,13950) @item --commands-in-node-names
texinfo.texi(,13951) @opindex --commands-in-node-names
texinfo.texi(,13952) Allow @code{@@}-commands in node names.  This is not recommended, as it
texinfo.texi(,13953) can probably never be implemented in @TeX{}.  It also makes
texinfo.texi(,13954) @code{makeinfo} much slower.  Also, this option is ignored when
texinfo.texi(,13955) @samp{--no-validate} is used.  @xref{Pointer Validation}, for more
texinfo.texi(,13956) details.
texinfo.texi(,13957) 
texinfo.texi(,13958) @item --docbook
texinfo.texi(,13959) @opindex --docbook
texinfo.texi(,13960) Generate DocBook output rather than Info.  
texinfo.texi(,13961) 
texinfo.texi(,13962) @item --error-limit=@var{limit}
texinfo.texi(,13963) @itemx -e @var{limit}
texinfo.texi(,13964) @opindex --error-limit=@var{limit}
texinfo.texi(,13965) @opindex -e @var{limit}
texinfo.texi(,13966) Set the maximum number of errors that @code{makeinfo} will report
texinfo.texi(,13967) before exiting (on the assumption that continuing would be useless);
texinfo.texi(,13968) default 100.
texinfo.texi(,13969) 
texinfo.texi(,13970) @item --fill-column=@var{width}
texinfo.texi(,13971) @itemx -f @var{width}
texinfo.texi(,13972) @opindex --fill-column=@var{width}
texinfo.texi(,13973) @opindex -f @var{width}
texinfo.texi(,13974) Specify the maximum number of columns in a line; this is the right-hand
texinfo.texi(,13975) edge of a line.  Paragraphs that are filled will be filled to this
texinfo.texi(,13976) width.  (Filling is the process of breaking up and connecting lines so
texinfo.texi(,13977) that lines are the same length as or shorter than the number specified
texinfo.texi(,13978) as the fill column.  Lines are broken between words.) The default value
texinfo.texi(,13979) is 72.  Ignored with @samp{--html}.
texinfo.texi(,13980) 
texinfo.texi(,13981) @item --footnote-style=@var{style}
texinfo.texi(,13982) @itemx -s @var{style}
texinfo.texi(,13983) @opindex --footnote-style=@var{style}
texinfo.texi(,13984) @opindex -s @var{style}
texinfo.texi(,13985) Set the footnote style to @var{style}, either @samp{end} for the end
texinfo.texi(,13986) node style (the default) or @samp{separate} for the separate node style.
texinfo.texi(,13987) The value set by this option overrides the value set in a Texinfo file
texinfo.texi(,13988) by an @code{@@footnotestyle} command (@pxref{Footnotes}).  When the
texinfo.texi(,13989) footnote style is @samp{separate}, @code{makeinfo} makes a new node
texinfo.texi(,13990) containing the footnotes found in the current node.  When the footnote
texinfo.texi(,13991) style is @samp{end}, @code{makeinfo} places the footnote references at
texinfo.texi(,13992) the end of the current node.  Ignored with @samp{--html}.
texinfo.texi(,13993) 
texinfo.texi(,13994) @item --force
texinfo.texi(,13995) @itemx -F
texinfo.texi(,13996) @opindex --force
texinfo.texi(,13997) @opindex -F
texinfo.texi(,13998) Ordinarily, if the input file has errors, the output files are not
texinfo.texi(,13999) created.  With this option, they are preserved.
texinfo.texi(,14000) 
texinfo.texi(,14001) @item --help
texinfo.texi(,14002) @itemx -h
texinfo.texi(,14003) @opindex --help
texinfo.texi(,14004) @opindex -h
texinfo.texi(,14005) Print a usage message listing all available options, then exit successfully.
texinfo.texi(,14006) 
texinfo.texi(,14007) @item --html
texinfo.texi(,14008) @opindex --html
texinfo.texi(,14009) Generate HTML output rather than Info.  @xref{makeinfo html}.  By
texinfo.texi(,14010) default, the HTML output is split into one output file per source node,
texinfo.texi(,14011) and the split output is written into a subdirectory with the name of the
texinfo.texi(,14012) top-level info file.
texinfo.texi(,14013) 
texinfo.texi(,14014) @item -I @var{dir}
texinfo.texi(,14015) @opindex -I @var{dir}
texinfo.texi(,14016) Append @var{dir} to the directory search list for finding files that
texinfo.texi(,14017) are included using the @code{@@include} command.  By default,
texinfo.texi(,14018) @code{makeinfo} searches only the current directory.  If @var{dir} is
texinfo.texi(,14019) not given, the current directory @file{.} is appended.  Note that
texinfo.texi(,14020) @var{dir} can actually be a list of several directories separated by the
texinfo.texi(,14021) usual path separator character (@samp{:} on Unix, @samp{;} on
texinfo.texi(,14022) MS-DOS/MS-Windows).
texinfo.texi(,14023) 
texinfo.texi(,14024) @item --macro-expand=@var{file}
texinfo.texi(,14025) @itemx -E @var{file}
texinfo.texi(,14026) Output the Texinfo source with all the macros expanded to the named
texinfo.texi(,14027) file.  Normally, the results of macro expansion are used internally by
texinfo.texi(,14028) @code{makeinfo} and then discarded.  This option is used by
texinfo.texi(,14029) @command{texi2dvi} if you are using an old version of @file{texinfo.tex}
texinfo.texi(,14030) that does not support @code{@@macro}.
texinfo.texi(,14031) 
texinfo.texi(,14032) @item --no-headers
texinfo.texi(,14033) @opindex --no-headers
texinfo.texi(,14034) @cindex Plain text output
texinfo.texi(,14035) @cindex ASCII text output
texinfo.texi(,14036) @cindex Generating plain text files
texinfo.texi(,14037) @cindex @file{INSTALL} file, generating
texinfo.texi(,14038) @cindex Node separators, omitting
texinfo.texi(,14039) @cindex Menus, omitting
texinfo.texi(,14040) For Info output, do not include menus or node separator lines in the
texinfo.texi(,14041) output.  This results in a simple plain text file that you can (for
texinfo.texi(,14042) example) send in email without complications, or include in a
texinfo.texi(,14043) distribution (as in an @file{INSTALL} file).
texinfo.texi(,14044) 
texinfo.texi(,14045) @cindex Navigation links, omitting
texinfo.texi(,14046) For HTML output, likewise omit menus.  And if @samp{--no-split} is also
texinfo.texi(,14047) specified, do not include a navigation links at the top of each node
texinfo.texi(,14048) (these are never included in the default case of split output).
texinfo.texi(,14049) @xref{makeinfo html}.
texinfo.texi(,14050) 
texinfo.texi(,14051) In both cases, write to standard output by default (can still be
texinfo.texi(,14052) overridden by @option{-o}).
texinfo.texi(,14053) 
texinfo.texi(,14054) @item --no-split
texinfo.texi(,14055) @opindex --no-split
texinfo.texi(,14056) @cindex Splitting of output files
texinfo.texi(,14057) @cindex Output file splitting
texinfo.texi(,14058) Suppress the splitting stage of @code{makeinfo}.  By default, large
texinfo.texi(,14059) output files (where the size is greater than 70k bytes) are split into
texinfo.texi(,14060) smaller subfiles.  For Info output, each one is approximately 50k bytes.
texinfo.texi(,14061) For HTML output, each file contains one node (@pxref{makeinfo html}).
texinfo.texi(,14062) 
texinfo.texi(,14063) @item --no-pointer-validate
texinfo.texi(,14064) @itemx --no-validate
texinfo.texi(,14065) @opindex --no-pointer-validate
texinfo.texi(,14066) @opindex --no-validate
texinfo.texi(,14067) @cindex Pointer validation, suppressing
texinfo.texi(,14068) Suppress the pointer-validation phase of @code{makeinfo}.  This can also
texinfo.texi(,14069) be done with the @code{@@novalidate} command (@pxref{Use TeX,,Use
texinfo.texi(,14070) @TeX{}}).  Normally, after a Texinfo file is processed, some consistency
texinfo.texi(,14071) checks are made to ensure that cross references can be resolved, etc.
texinfo.texi(,14072) @xref{Pointer Validation}.
texinfo.texi(,14073) 
texinfo.texi(,14074) @item --no-warn
texinfo.texi(,14075) @opindex --no-warn
texinfo.texi(,14076) Suppress warning messages (but @emph{not} error messages).  You might
texinfo.texi(,14077) want this if the file you are creating has examples of Texinfo cross
texinfo.texi(,14078) references within it, and the nodes that are referenced do not actually
texinfo.texi(,14079) exist.
texinfo.texi(,14080) 
texinfo.texi(,14081) @item --number-sections
texinfo.texi(,14082) @opindex --number-sections
texinfo.texi(,14083) Output chapter, section, and appendix numbers as in printed manuals.
texinfo.texi(,14084) 
texinfo.texi(,14085) @item --no-number-footnotes
texinfo.texi(,14086) @opindex --no-number-footnotes
texinfo.texi(,14087) Suppress automatic footnote numbering.  By default, @code{makeinfo}
texinfo.texi(,14088) numbers each footnote sequentially in a single node, resetting the
texinfo.texi(,14089) current footnote number to 1 at the start of each node.
texinfo.texi(,14090) 
texinfo.texi(,14091) @item --output=@var{file}
texinfo.texi(,14092) @itemx -o @var{file}
texinfo.texi(,14093) @opindex --output=@var{file}
texinfo.texi(,14094) @opindex -o @var{file}
texinfo.texi(,14095) Specify that the output should be directed to @var{file} and not to the
texinfo.texi(,14096) file name specified in the @code{@@setfilename} command found in the
texinfo.texi(,14097) Texinfo source (@pxref{setfilename}).  If @var{file} is @samp{-}, output
texinfo.texi(,14098) goes to standard output and @samp{--no-split} is implied.  For split
texinfo.texi(,14099) HTML output, @var{file} is the name for the directory into which all
texinfo.texi(,14100) HTML nodes are written (@pxref{makeinfo html}).
texinfo.texi(,14101) 
texinfo.texi(,14102) @item -P @var{dir}
texinfo.texi(,14103) @opindex -P @var{dir}
texinfo.texi(,14104) Prepend @var{dir} to the directory search list for @code{@@include}.
texinfo.texi(,14105) If @var{dir} is not given, the current directory @file{.} is prepended.
texinfo.texi(,14106) See @samp{-I} for more details.
texinfo.texi(,14107) 
texinfo.texi(,14108) @item --paragraph-indent=@var{indent}
texinfo.texi(,14109) @itemx -p @var{indent}
texinfo.texi(,14110) @opindex --paragraph-indent=@var{indent}
texinfo.texi(,14111) @opindex -p @var{indent}
texinfo.texi(,14112) Set the paragraph indentation style to @var{indent}.  The value set by
texinfo.texi(,14113) this option overrides the value set in a Texinfo file by an
texinfo.texi(,14114) @code{@@paragraphindent} command (@pxref{paragraphindent}).  The value
texinfo.texi(,14115) of @var{indent} is interpreted as follows:
texinfo.texi(,14116) 
texinfo.texi(,14117) @table @asis
texinfo.texi(,14118) @item @samp{asis}
texinfo.texi(,14119) Preserve any existing indentation at the starts of paragraphs.
texinfo.texi(,14120) 
texinfo.texi(,14121) @item @samp{0} or @samp{none}
texinfo.texi(,14122) Delete any existing indentation.
texinfo.texi(,14123) 
texinfo.texi(,14124) @item @var{num}
texinfo.texi(,14125) Indent each paragraph by @var{num} spaces.
texinfo.texi(,14126) @end table
texinfo.texi(,14127) 
texinfo.texi(,14128) @item --reference-limit=@var{limit}
texinfo.texi(,14129) @itemx -r @var{limit}
texinfo.texi(,14130) @opindex --reference-limit=@var{limit}
texinfo.texi(,14131) @opindex -r @var{limit}
texinfo.texi(,14132) Set the value of the number of references to a node that
texinfo.texi(,14133) @code{makeinfo} will make without reporting a warning.  If a node has more
texinfo.texi(,14134) than this number of references in it, @code{makeinfo} will make the
texinfo.texi(,14135) references but also report a warning.  The default is 1000.
texinfo.texi(,14136) 
texinfo.texi(,14137) @item -U @var{var}
texinfo.texi(,14138) Cause @var{var} to be undefined.  This is equivalent to
texinfo.texi(,14139) @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
texinfo.texi(,14140) 
texinfo.texi(,14141) @item --verbose
texinfo.texi(,14142) @opindex --verbose
texinfo.texi(,14143) Cause @code{makeinfo} to display messages saying what it is doing.
texinfo.texi(,14144) Normally, @code{makeinfo} only outputs messages if there are errors or
texinfo.texi(,14145) warnings.
texinfo.texi(,14146) 
texinfo.texi(,14147) @item --version
texinfo.texi(,14148) @itemx -V
texinfo.texi(,14149) @opindex --version
texinfo.texi(,14150) @opindex -V
texinfo.texi(,14151) Print the version number, then exit successfully.
texinfo.texi(,14152) 
texinfo.texi(,14153) @item --xml
texinfo.texi(,14154) @opindex --xml
texinfo.texi(,14155) Generate XML output rather than Info.  
texinfo.texi(,14156) 
texinfo.texi(,14157) @end table
texinfo.texi(,14158) 
texinfo.texi(,14159) 
texinfo.texi(,14160) @node Pointer Validation
texinfo.texi(,14161) @subsection Pointer Validation
texinfo.texi(,14162) @cindex Pointer validation with @code{makeinfo}
texinfo.texi(,14163) @cindex Validation of pointers
texinfo.texi(,14164) 
texinfo.texi(,14165) If you do not suppress pointer validation with the @samp{--no-validate}
texinfo.texi(,14166) option or the @code{@@novalidate} command in the source file (@pxref{Use
texinfo.texi(,14167) TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
texinfo.texi(,14168) Info file.  Mostly, this means ensuring that nodes you have referenced
texinfo.texi(,14169) really exist.  Here is a complete list of what is checked:
texinfo.texi(,14170) 
texinfo.texi(,14171) @enumerate
texinfo.texi(,14172) @item
texinfo.texi(,14173) If a `Next', `Previous', or `Up' node reference is a reference to a
texinfo.texi(,14174) node in the current file and is not an external reference such as to
texinfo.texi(,14175) @file{(dir)}, then the referenced node must exist.@refill
texinfo.texi(,14176) 
texinfo.texi(,14177) @item
texinfo.texi(,14178) In every node, if the `Previous' node is different from the `Up' node,
texinfo.texi(,14179) then the node pointed to by the `Previous' field must have a `Next'
texinfo.texi(,14180) field which points back to this node.@refill
texinfo.texi(,14181) 
texinfo.texi(,14182) @item
texinfo.texi(,14183) Every node except the `Top' node must have an `Up' pointer.@refill
texinfo.texi(,14184) 
texinfo.texi(,14185) @item
texinfo.texi(,14186) The node referenced by an `Up' pointer must itself reference the current
texinfo.texi(,14187) node through a menu item, unless the node referenced by `Up'
texinfo.texi(,14188) has the form `(@var{file})'.
texinfo.texi(,14189) 
texinfo.texi(,14190) @item
texinfo.texi(,14191) If the `Next' reference of a node is not the same as the `Next' reference
texinfo.texi(,14192) of the `Up' reference, then the node referenced by the `Next' pointer
texinfo.texi(,14193) must have a `Previous' pointer that points back to the current node.
texinfo.texi(,14194) This rule allows the last node in a section to point to the first node
texinfo.texi(,14195) of the next chapter.@refill
texinfo.texi(,14196) 
texinfo.texi(,14197) @item
texinfo.texi(,14198) Every node except `Top' should be referenced by at least one other node,
texinfo.texi(,14199) either via the `Previous' or `Next' links, or via a menu or a
texinfo.texi(,14200) cross-reference.@refill
texinfo.texi(,14201) @end enumerate
texinfo.texi(,14202) 
texinfo.texi(,14203) @cindex @@-commands in @@node, limited support
texinfo.texi(,14204) Some Texinfo documents might fail during the validation phase because
texinfo.texi(,14205) they use commands like @code{@@value} and @code{@@definfoenclose} in
texinfo.texi(,14206) node definitions and cross-references inconsistently.  Consider the
texinfo.texi(,14207) following example:
texinfo.texi(,14208) 
texinfo.texi(,14209) @example
texinfo.texi(,14210) @group
texinfo.texi(,14211) @@set nodename Node 1
texinfo.texi(,14212) 
texinfo.texi(,14213) @@node @@value@{nodename@}, Node 2, Top, Top
texinfo.texi(,14214) 
texinfo.texi(,14215) This is node 1.
texinfo.texi(,14216) 
texinfo.texi(,14217) @@node Node 2, , Node 1, Top
texinfo.texi(,14218) 
texinfo.texi(,14219) This is node 2.
texinfo.texi(,14220) @end group
texinfo.texi(,14221) @end example
texinfo.texi(,14222) 
texinfo.texi(,14223) @noindent
texinfo.texi(,14224) Here, the node ``Node 1'' was referenced both verbatim and through
texinfo.texi(,14225) @code{@@value}.
texinfo.texi(,14226) 
texinfo.texi(,14227) By default, @code{makeinfo} fails such cases, because node names are not
texinfo.texi(,14228) fully expanded until they are written to the output file.  You should
texinfo.texi(,14229) always try to reference nodes consistently; e.g., in the above example,
texinfo.texi(,14230) the second @code{@@node} line should have also used @code{@@value}.
texinfo.texi(,14231) However, if, for some reason, you @emph{must} reference node names
texinfo.texi(,14232) inconsistently, and @code{makeinfo} fails to validate the file, you can
texinfo.texi(,14233) use the @samp{--commands-in-node-names} option to force @code{makeinfo}
texinfo.texi(,14234) to perform the expensive expansion of all node names it finds in the
texinfo.texi(,14235) document.  This might considerably slow down the program, though;
texinfo.texi(,14236) twofold increase in conversion time was measured for large documents
texinfo.texi(,14237) such as the Jargon file.
texinfo.texi(,14238) 
texinfo.texi(,14239) @cindex @@value in @@node lines
texinfo.texi(,14240) The support for @code{@@}-commands in @code{@@node} directives is not
texinfo.texi(,14241) general enough to be freely used.  For example, if the example above
texinfo.texi(,14242) redefined @code{nodename} somewhere in the document, @code{makeinfo}
texinfo.texi(,14243) will fail to convert it, even if invoked with the
texinfo.texi(,14244) @samp{--commands-in-node-names} option.
texinfo.texi(,14245) 
texinfo.texi(,14246) @samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
texinfo.texi(,14247) option is given.
texinfo.texi(,14248) 
texinfo.texi(,14249) 
texinfo.texi(,14250) @node makeinfo in Emacs
texinfo.texi(,14251) @subsection Running @code{makeinfo} inside Emacs
texinfo.texi(,14252) @cindex Running @code{makeinfo} in Emacs
texinfo.texi(,14253) @cindex @code{makeinfo} inside Emacs
texinfo.texi(,14254) @cindex Shell, running @code{makeinfo} in
texinfo.texi(,14255) 
texinfo.texi(,14256) You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
texinfo.texi(,14257) @code{makeinfo-region} or the @code{makeinfo-buffer} commands.  In
texinfo.texi(,14258) Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
texinfo.texi(,14259) C-m C-b} by default.@refill
texinfo.texi(,14260) 
texinfo.texi(,14261) @table @kbd
texinfo.texi(,14262) @item C-c C-m C-r
texinfo.texi(,14263) @itemx M-x makeinfo-region
texinfo.texi(,14264) Format the current region for Info.@refill
texinfo.texi(,14265) @findex makeinfo-region
texinfo.texi(,14266) 
texinfo.texi(,14267) @item C-c C-m C-b
texinfo.texi(,14268) @itemx M-x makeinfo-buffer
texinfo.texi(,14269) Format the current buffer for Info.@refill
texinfo.texi(,14270) @findex makeinfo-buffer
texinfo.texi(,14271) @end table
texinfo.texi(,14272) 
texinfo.texi(,14273) When you invoke either @code{makeinfo-region} or
texinfo.texi(,14274) @code{makeinfo-buffer}, Emacs prompts for a file name, offering the
texinfo.texi(,14275) name of the visited file as the default.  You can edit the default
texinfo.texi(,14276) file name in the minibuffer if you wish, before pressing @key{RET} to
texinfo.texi(,14277) start the @code{makeinfo} process.@refill
texinfo.texi(,14278) 
texinfo.texi(,14279) The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
texinfo.texi(,14280) run the @code{makeinfo} program in a temporary shell buffer.  If
texinfo.texi(,14281) @code{makeinfo} finds any errors, Emacs displays the error messages in
texinfo.texi(,14282) the temporary buffer.@refill
texinfo.texi(,14283) 
texinfo.texi(,14284) @cindex Errors, parsing
texinfo.texi(,14285) @cindex Parsing errors
texinfo.texi(,14286) @findex next-error
texinfo.texi(,14287) You can parse the error messages by typing @kbd{C-x `}
texinfo.texi(,14288) (@code{next-error}).  This causes Emacs to go to and position the
texinfo.texi(,14289) cursor on the line in the Texinfo source that @code{makeinfo} thinks
texinfo.texi(,14290) caused the error.  @xref{Compilation, , Running @code{make} or
texinfo.texi(,14291) Compilers Generally, emacs, The GNU Emacs Manual}, for more
texinfo.texi(,14292) information about using the @code{next-error} command.@refill
texinfo.texi(,14293) 
texinfo.texi(,14294) In addition, you can kill the shell in which the @code{makeinfo}
texinfo.texi(,14295) command is running or make the shell buffer display its most recent
texinfo.texi(,14296) output.@refill
texinfo.texi(,14297) 
texinfo.texi(,14298) @table @kbd
texinfo.texi(,14299) @item C-c C-m C-k
texinfo.texi(,14300) @itemx M-x makeinfo-kill-job
texinfo.texi(,14301) @findex makeinfo-kill-job
texinfo.texi(,14302) Kill the current running @code{makeinfo} job
texinfo.texi(,14303) (from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
texinfo.texi(,14304) 
texinfo.texi(,14305) @item C-c C-m C-l
texinfo.texi(,14306) @itemx M-x makeinfo-recenter-output-buffer
texinfo.texi(,14307) @findex makeinfo-recenter-output-buffer
texinfo.texi(,14308) Redisplay the @code{makeinfo} shell buffer to display its most recent
texinfo.texi(,14309) output.@refill
texinfo.texi(,14310) @end table
texinfo.texi(,14311) 
texinfo.texi(,14312) @noindent
texinfo.texi(,14313) (Note that the parallel commands for killing and recentering a @TeX{}
texinfo.texi(,14314) job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}.  @xref{Texinfo Mode
texinfo.texi(,14315) Printing}.)@refill
texinfo.texi(,14316) 
texinfo.texi(,14317) You can specify options for @code{makeinfo} by setting the
texinfo.texi(,14318) @code{makeinfo-options} variable with either the @kbd{M-x
texinfo.texi(,14319) edit-options} or the @kbd{M-x set-variable} command, or by setting the
texinfo.texi(,14320) variable in your @file{.emacs} initialization file.@refill
texinfo.texi(,14321) 
texinfo.texi(,14322) For example, you could write the following in your @file{.emacs} file:@refill
texinfo.texi(,14323) 
texinfo.texi(,14324) @example
texinfo.texi(,14325) @group
texinfo.texi(,14326) (setq makeinfo-options
texinfo.texi(,14327)       "--paragraph-indent=0 --no-split
texinfo.texi(,14328)        --fill-column=70 --verbose")
texinfo.texi(,14329) @end group
texinfo.texi(,14330) @end example
texinfo.texi(,14331) 
texinfo.texi(,14332) @c If you write these three cross references using xref, you see
texinfo.texi(,14333) @c three references to the same named manual, which looks strange.
texinfo.texi(,14340) @noindent
texinfo.texi(,14342) For more information, see@*
texinfo.texi(,14343) @ref{Edit Options, , Editing Variable Values, emacs, The GNU Emacs Manual},@*
texinfo.texi(,14344) @ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs Manual},@*
texinfo.texi(,14345) @ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
texinfo.texi(,14346) @ref{makeinfo options, , Options for @code{makeinfo}}.
texinfo.texi(,14348) 
texinfo.texi(,14349) @node texinfo-format commands
texinfo.texi(,14350) @comment  node-name,  next,  previous,  up
texinfo.texi(,14351) @subsection The @code{texinfo-format@dots{}} Commands
texinfo.texi(,14352) @findex texinfo-format-region
texinfo.texi(,14353) @findex texinfo-format-buffer
texinfo.texi(,14354) 
texinfo.texi(,14355) In GNU Emacs in Texinfo mode, you can format part or all of a Texinfo
texinfo.texi(,14356) file with the @code{texinfo-format-region} command.  This formats the
texinfo.texi(,14357) current region and displays the formatted text in a temporary buffer
texinfo.texi(,14358) called @samp{*Info Region*}.@refill
texinfo.texi(,14359) 
texinfo.texi(,14360) Similarly, you can format a buffer with the
texinfo.texi(,14361) @code{texinfo-format-buffer} command.  This command creates a new
texinfo.texi(,14362) buffer and generates the Info file in it.  Typing @kbd{C-x C-s} will
texinfo.texi(,14363) save the Info file under the name specified by the
texinfo.texi(,14364) @code{@@setfilename} line which must be near the beginning of the
texinfo.texi(,14365) Texinfo file.@refill
texinfo.texi(,14366) 
texinfo.texi(,14367) @table @kbd
texinfo.texi(,14368) @item C-c C-e C-r
texinfo.texi(,14369) @itemx @code{texinfo-format-region}
texinfo.texi(,14370) Format the current region for Info.
texinfo.texi(,14371) @findex texinfo-format-region
texinfo.texi(,14372) 
texinfo.texi(,14373) @item C-c C-e C-b
texinfo.texi(,14374) @itemx @code{texinfo-format-buffer}
texinfo.texi(,14375) Format the current buffer for Info.
texinfo.texi(,14376) @findex texinfo-format-buffer
texinfo.texi(,14377) @end table
texinfo.texi(,14378) 
texinfo.texi(,14379) The @code{texinfo-format-region} and @code{texinfo-format-buffer}
texinfo.texi(,14380) commands provide you with some error checking, and other functions can
texinfo.texi(,14381) provide you with further help in finding formatting errors.  These
texinfo.texi(,14382) procedures are described in an appendix; see @ref{Catching Mistakes}.
texinfo.texi(,14383) However, the @code{makeinfo} program is often faster and
texinfo.texi(,14384) provides better error checking (@pxref{makeinfo in Emacs}).@refill
texinfo.texi(,14385) 
texinfo.texi(,14386) @node Batch Formatting
texinfo.texi(,14387) @comment  node-name,  next,  previous,  up
texinfo.texi(,14388) @subsection Batch Formatting
texinfo.texi(,14389) @cindex Batch formatting for Info
texinfo.texi(,14390) @cindex Info batch formatting
texinfo.texi(,14391) 
texinfo.texi(,14392) You can format Texinfo files for Info using @code{batch-texinfo-format}
texinfo.texi(,14393) and Emacs Batch mode.  You can run Emacs in Batch mode from any shell,
texinfo.texi(,14394) including a shell inside of Emacs.  (@xref{Command Switches, , Command
texinfo.texi(,14395) Line Switches and Arguments, emacs, The GNU Emacs Manual}.)@refill
texinfo.texi(,14396) 
texinfo.texi(,14397) Here is a shell command to format all the files that end in
texinfo.texi(,14398) @file{.texinfo} in the current directory:
texinfo.texi(,14399) 
texinfo.texi(,14400) @example
texinfo.texi(,14401) emacs -batch -funcall batch-texinfo-format *.texinfo
texinfo.texi(,14402) @end example
texinfo.texi(,14403) 
texinfo.texi(,14404) @noindent
texinfo.texi(,14405) Emacs processes all the files listed on the command line, even if an
texinfo.texi(,14406) error occurs while attempting to format some of them.@refill
texinfo.texi(,14407) 
texinfo.texi(,14408) Run @code{batch-texinfo-format} only with Emacs in Batch mode as shown;
texinfo.texi(,14409) it is not interactive.  It kills the Batch mode Emacs on completion.@refill
texinfo.texi(,14410) 
texinfo.texi(,14411) @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
texinfo.texi(,14412) and want to format several Texinfo files at once.  When you use Batch
texinfo.texi(,14413) mode, you create a new Emacs process.  This frees your current Emacs, so
texinfo.texi(,14414) you can continue working in it.  (When you run
texinfo.texi(,14415) @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
texinfo.texi(,14416) use that Emacs for anything else until the command finishes.)@refill
texinfo.texi(,14417) 
texinfo.texi(,14418) @node Tag and Split Files
texinfo.texi(,14419) @comment  node-name,  next,  previous,  up
texinfo.texi(,14420) @subsection Tag Files and Split Files
texinfo.texi(,14421) @cindex Making a tag table automatically
texinfo.texi(,14422) @cindex Tag table, making automatically
texinfo.texi(,14423) 
texinfo.texi(,14424) If a Texinfo file has more than 30,000 bytes,
texinfo.texi(,14425) @code{texinfo-format-buffer} automatically creates a tag table
texinfo.texi(,14426) for its Info file;  @code{makeinfo} always creates a tag table.  With
texinfo.texi(,14427) a @dfn{tag table}, Info can jump to new nodes more quickly than it can
texinfo.texi(,14428) otherwise.@refill
texinfo.texi(,14429) 
texinfo.texi(,14430) @cindex Indirect subfiles
texinfo.texi(,14431) In addition, if the Texinfo file contains more than about 70,000
texinfo.texi(,14432) bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
texinfo.texi(,14433) large Info file into shorter @dfn{indirect} subfiles of about 50,000
texinfo.texi(,14434) bytes each.  Big files are split into smaller files so that Emacs does
texinfo.texi(,14435) not need to make a large buffer to hold the whole of a large Info
texinfo.texi(,14436) file; instead, Emacs allocates just enough memory for the small, split-off
texinfo.texi(,14437) file that is needed at the time.  This way, Emacs avoids wasting
texinfo.texi(,14438) memory when you run Info.  (Before splitting was implemented, Info
texinfo.texi(,14439) files were always kept short and @dfn{include files} were designed as
texinfo.texi(,14440) a way to create a single, large printed manual out of the smaller Info
texinfo.texi(,14441) files.  @xref{Include Files}, for more information.  Include files are
texinfo.texi(,14442) still used for very large documents, such as @cite{The Emacs Lisp
texinfo.texi(,14443) Reference Manual}, in which each chapter is a separate file.)@refill
texinfo.texi(,14444) 
texinfo.texi(,14445) When a file is split, Info itself makes use of a shortened version of
texinfo.texi(,14446) the original file that contains just the tag table and references to
texinfo.texi(,14447) the files that were split off.  The split-off files are called
texinfo.texi(,14448) @dfn{indirect} files.@refill
texinfo.texi(,14449) 
texinfo.texi(,14450) The split-off files have names that are created by appending @w{@samp{-1}},
texinfo.texi(,14451) @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
texinfo.texi(,14452) @code{@@setfilename} command.  The shortened version of the original file
texinfo.texi(,14453) continues to have the name specified by @code{@@setfilename}.@refill
texinfo.texi(,14454) 
texinfo.texi(,14455) At one stage in writing this document, for example, the Info file was saved
texinfo.texi(,14456) as the file @file{test-texinfo} and that file looked like this:@refill
texinfo.texi(,14457) 
texinfo.texi(,14458) @example
texinfo.texi(,14459) @group
texinfo.texi(,14460) Info file: test-texinfo,    -*-Text-*-
texinfo.texi(,14461) produced by texinfo-format-buffer
texinfo.texi(,14462) from file: new-texinfo-manual.texinfo
texinfo.texi(,14463) 
texinfo.texi(,14464) ^_
texinfo.texi(,14465) Indirect:
texinfo.texi(,14466) test-texinfo-1: 102
texinfo.texi(,14467) test-texinfo-2: 50422
texinfo.texi(,14468) @end group
texinfo.texi(,14469) @group
texinfo.texi(,14470) test-texinfo-3: 101300
texinfo.texi(,14471) ^_^L
texinfo.texi(,14472) Tag table:
texinfo.texi(,14473) (Indirect)
texinfo.texi(,14474) Node: overview^?104
texinfo.texi(,14475) Node: info file^?1271
texinfo.texi(,14476) @end group
texinfo.texi(,14477) @group
texinfo.texi(,14478) Node: printed manual^?4853
texinfo.texi(,14479) Node: conventions^?6855
texinfo.texi(,14480) @dots{}
texinfo.texi(,14481) @end group
texinfo.texi(,14482) @end example
texinfo.texi(,14483) 
texinfo.texi(,14484) @noindent
texinfo.texi(,14485) (But @file{test-texinfo} had far more nodes than are shown here.)  Each of
texinfo.texi(,14486) the split-off, indirect files, @file{test-texinfo-1},
texinfo.texi(,14487) @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
texinfo.texi(,14488) after the line that says @samp{Indirect:}.  The tag table is listed after
texinfo.texi(,14489) the line that says @samp{Tag table:}. @refill
texinfo.texi(,14490) 
texinfo.texi(,14491) In the list of indirect files, the number following the file name
texinfo.texi(,14492) records the cumulative number of bytes in the preceding indirect files,
texinfo.texi(,14493) not counting the file list itself, the tag table, or the permissions
texinfo.texi(,14494) text in each file.  In the tag table, the number following the node name
texinfo.texi(,14495) records the location of the beginning of the node, in bytes from the
texinfo.texi(,14496) beginning of the (unsplit) output.
texinfo.texi(,14497) 
texinfo.texi(,14498) If you are using @code{texinfo-format-buffer} to create Info files,
texinfo.texi(,14499) you may want to run the @code{Info-validate} command.  (The
texinfo.texi(,14500) @code{makeinfo} command does such a good job on its own, you do not
texinfo.texi(,14501) need @code{Info-validate}.)  However, you cannot run the @kbd{M-x
texinfo.texi(,14502) Info-validate} node-checking command on indirect files.  For
texinfo.texi(,14503) information on how to prevent files from being split and how to
texinfo.texi(,14504) validate the structure of the nodes, see @ref{Using
texinfo.texi(,14505) Info-validate}.@refill
texinfo.texi(,14506) 
texinfo.texi(,14507) 
texinfo.texi(,14508) @node makeinfo html
texinfo.texi(,14509) @subsection Generating HTML
texinfo.texi(,14510) @cindex HTML
texinfo.texi(,14511) 
texinfo.texi(,14512) Besides generating output in the Info format, you can use the
texinfo.texi(,14513) @samp{--html} option to generate output in HTML format, for installation
texinfo.texi(,14514) on a web site (for example).  By default, the HTML output is split at
texinfo.texi(,14515) node level.
texinfo.texi(,14516) 
texinfo.texi(,14517) When splitting, the HTML output files are written into a subdirectory.
texinfo.texi(,14518) The subdirectory is named according to the name from
texinfo.texi(,14519) @code{@@setfilename} with any extension removed; for example, HTML
texinfo.texi(,14520) output for @code{@@setfilename emacs.info} would be written into a
texinfo.texi(,14521) subdirectory named @samp{emacs}.  If that directory cannot be created
texinfo.texi(,14522) for any reason, then @samp{.html} is appended to the directory name, as
texinfo.texi(,14523) in @samp{emacs.html} (this is necessary because sometimes the info file
texinfo.texi(,14524) is named without an extension, e.g., @samp{texinfo}).  If the
texinfo.texi(,14525) @samp{@var{name}.html} directory can't be created either,
texinfo.texi(,14526) @code{makeinfo} gives up.  In any case, the top-level output file within
texinfo.texi(,14527) the directory is always named @samp{index.html}.
texinfo.texi(,14528) 
texinfo.texi(,14529) Monolithic output (@code{--no-split}) is named according to
texinfo.texi(,14530) @code{@@setfilename} or @code{--outfile}.  Cross-document node
texinfo.texi(,14531) references are not supported in monolithic HTML.
texinfo.texi(,14532) 
texinfo.texi(,14533) Texinfo input marked up with the @code{@@ifhtml} command will produce
texinfo.texi(,14534) output only with the @samp{--html} option supplied.  Input marked up
texinfo.texi(,14535) with the @code{@@html} is passed literally to the output (suppressing
texinfo.texi(,14536) the normal escaping of input @samp{<}, @samp{>} and @samp{&} characters
texinfo.texi(,14537) which have special significance in HTML).
texinfo.texi(,14538) 
texinfo.texi(,14539) The @samp{--footnote-style} option is currently ignored for HTML output;
texinfo.texi(,14540) footnotes are linked to the end of the output file.
texinfo.texi(,14541) 
texinfo.texi(,14542) The HTML generated is mostly standard (i.e., HTML 2.0, RFC-1866).  The
texinfo.texi(,14543) exception is that HTML 3.2 tables are generated from the
texinfo.texi(,14544) @code{@@multitable} command, but tagged to degrade as well as possible
texinfo.texi(,14545) in browsers without table support.  The HTML 4 @samp{lang} attribute on
texinfo.texi(,14546) the @samp{<html>} attribute is also used.  Please report output from an
texinfo.texi(,14547) error-free run of @code{makeinfo} which has browser portability problems
texinfo.texi(,14548) as a bug.
texinfo.texi(,14549) 
texinfo.texi(,14550) Navigation bars are inserted at the start of nodes, similarly to Info
texinfo.texi(,14551) output.  The @samp{--no-headers} option will suppress this if used with
texinfo.texi(,14552) @samp{--no-split}.  Header @code{<link>} elements in split output can
texinfo.texi(,14553) support info-like navigation with browsers like Lynx and @w{Emacs W3}
texinfo.texi(,14554) which implement this @w{HTML 1.0} feature.  @samp{@@xref} commands to
texinfo.texi(,14555) other documents are generated assuming the other document is available
texinfo.texi(,14556) in split HTML form, and installed in the same HTML documentation tree,
texinfo.texi(,14557) at @file{../<info-document>/}.
texinfo.texi(,14558) 
texinfo.texi(,14559) 
texinfo.texi(,14560) @node Installing an Info File
texinfo.texi(,14561) @section Installing an Info File
texinfo.texi(,14562) @cindex Installing an Info file
texinfo.texi(,14563) @cindex Info file installation
texinfo.texi(,14564) @cindex @file{dir} directory for Info installation
texinfo.texi(,14565) 
texinfo.texi(,14566) Info files are usually kept in the @file{info} directory.  You can read
texinfo.texi(,14567) Info files using the standalone Info program or the Info reader built
texinfo.texi(,14568) into Emacs.  (@inforef{Top, info, info}, for an introduction to Info.)
texinfo.texi(,14569) 
texinfo.texi(,14570) @menu
texinfo.texi(,14571) * Directory File::              The top level menu for all Info files.
texinfo.texi(,14572) * New Info File::               Listing a new Info file.
texinfo.texi(,14573) * Other Info Directories::      How to specify Info files that are
texinfo.texi(,14574)                                   located in other directories.
texinfo.texi(,14575) * Installing Dir Entries::      How to specify what menu entry to add
texinfo.texi(,14576)                                   to the Info directory.
texinfo.texi(,14577) * Invoking install-info::       @code{install-info} options.
texinfo.texi(,14578) @end menu
texinfo.texi(,14579) 
texinfo.texi(,14580) 
texinfo.texi(,14581) @node Directory File
texinfo.texi(,14582) @subsection The Directory File @file{dir}
texinfo.texi(,14583) 
texinfo.texi(,14584) For Info to work, the @file{info} directory must contain a file that
texinfo.texi(,14585) serves as a top level directory for the Info system.  By convention,
texinfo.texi(,14586) this file is called @file{dir}.  (You can find the location of this file
texinfo.texi(,14587) within Emacs by typing @kbd{C-h i} to enter Info and then typing
texinfo.texi(,14588) @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
texinfo.texi(,14589) 
texinfo.texi(,14590) The @file{dir} file is itself an Info file.  It contains the top level
texinfo.texi(,14591) menu for all the Info files in the system.  The menu looks like
texinfo.texi(,14592) this:@refill
texinfo.texi(,14593) 
texinfo.texi(,14594) @example
texinfo.texi(,14595) @group
texinfo.texi(,14596) * Menu:
texinfo.texi(,14597) * Info:    (info).     Documentation browsing system.
texinfo.texi(,14598) * Emacs:   (emacs).    The extensible, self-documenting
texinfo.texi(,14599)                        text editor.
texinfo.texi(,14600) * Texinfo: (texinfo).  With one source file, make
texinfo.texi(,14601)                        either a printed manual using
texinfo.texi(,14602)                        @@TeX@{@} or an Info file.
texinfo.texi(,14603) @dots{}
texinfo.texi(,14604) @end group
texinfo.texi(,14605) @end example
texinfo.texi(,14606) 
texinfo.texi(,14607) Each of these menu entries points to the `Top' node of the Info file
texinfo.texi(,14608) that is named in parentheses.  (The menu entry does not need to
texinfo.texi(,14609) specify the `Top' node, since Info goes to the `Top' node if no node
texinfo.texi(,14610) name is mentioned.  @xref{Other Info Files, , Nodes in Other Info
texinfo.texi(,14611) Files}.)@refill
texinfo.texi(,14612) 
texinfo.texi(,14613) Thus, the @samp{Info} entry points to the `Top' node of the
texinfo.texi(,14614) @file{info} file and the @samp{Emacs} entry points to the `Top' node
texinfo.texi(,14615) of the @file{emacs} file.@refill
texinfo.texi(,14616) 
texinfo.texi(,14617) In each of the Info files, the `Up' pointer of the `Top' node refers
texinfo.texi(,14618) back to the @code{dir} file.  For example, the line for the `Top'
texinfo.texi(,14619) node of the Emacs manual looks like this in Info:@refill
texinfo.texi(,14620) 
texinfo.texi(,14621) @example
texinfo.texi(,14622) File: emacs  Node: Top, Up: (DIR), Next: Distrib
texinfo.texi(,14623) @end example
texinfo.texi(,14624) 
texinfo.texi(,14625) @noindent
texinfo.texi(,14626) In this case, the @file{dir} file name is written in upper case
texinfo.texi(,14627) letters---it can be written in either upper or lower case.  This is not
texinfo.texi(,14628) true in general, it is a special case for @file{dir}.
texinfo.texi(,14629) 
texinfo.texi(,14630) 
texinfo.texi(,14631) @node New Info File
texinfo.texi(,14632) @subsection Listing a New Info File
texinfo.texi(,14633) @cindex Adding a new Info file
texinfo.texi(,14634) @cindex Listing a new Info file
texinfo.texi(,14635) @cindex New Info file, listing it in @file{dir} file
texinfo.texi(,14636) @cindex Info file, listing a new
texinfo.texi(,14637) @cindex @file{dir} file listing
texinfo.texi(,14638) 
texinfo.texi(,14639) To add a new Info file to your system, you must write a menu entry to
texinfo.texi(,14640) add to the menu in the @file{dir} file in the @file{info} directory.
texinfo.texi(,14641) For example, if you were adding documentation for GDB, you would write
texinfo.texi(,14642) the following new entry:@refill
texinfo.texi(,14643) 
texinfo.texi(,14644) @example
texinfo.texi(,14645) * GDB: (gdb).           The source-level C debugger.
texinfo.texi(,14646) @end example
texinfo.texi(,14647) 
texinfo.texi(,14648) @noindent
texinfo.texi(,14649) The first part of the menu entry is the menu entry name, followed by a
texinfo.texi(,14650) colon.  The second part is the name of the Info file, in parentheses,
texinfo.texi(,14651) followed by a period.  The third part is the description.
texinfo.texi(,14652) 
texinfo.texi(,14653) The name of an Info file often has a @file{.info} extension.  Thus, the
texinfo.texi(,14654) Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
texinfo.texi(,14655) The Info reader programs automatically try the file name both with and
texinfo.texi(,14656) without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
texinfo.texi(,14657) try the @file{.inf} extension as well.}; so it is better to avoid
texinfo.texi(,14658) clutter and not to write @samp{.info} explicitly in the menu entry.  For
texinfo.texi(,14659) example, the GDB menu entry should use just @samp{gdb} for the file
texinfo.texi(,14660) name, not @samp{gdb.info}.
texinfo.texi(,14661) 
texinfo.texi(,14662) 
texinfo.texi(,14663) @node Other Info Directories
texinfo.texi(,14664) @subsection Info Files in Other Directories
texinfo.texi(,14665) @cindex Installing Info in another directory
texinfo.texi(,14666) @cindex Info installed in another directory
texinfo.texi(,14667) @cindex Another Info directory
texinfo.texi(,14668) @cindex @file{dir} files and Info directories
texinfo.texi(,14669) 
texinfo.texi(,14670) If an Info file is not in the @file{info} directory, there are three
texinfo.texi(,14671) ways to specify its location:@refill
texinfo.texi(,14672) 
texinfo.texi(,14673) @enumerate
texinfo.texi(,14674) @item
texinfo.texi(,14675) Write the pathname in the @file{dir} file as the second part of the menu.
texinfo.texi(,14676) 
texinfo.texi(,14677) @item
texinfo.texi(,14678) If you are using Emacs, list the name of the file in a second @file{dir}
texinfo.texi(,14679) file, in its directory; and then add the name of that directory to the
texinfo.texi(,14680) @code{Info-directory-list} variable in your personal or site
texinfo.texi(,14681) initialization file.
texinfo.texi(,14682) 
texinfo.texi(,14683) This variable tells Emacs where to look for @file{dir} files (the files
texinfo.texi(,14684) must be named @file{dir}).  Emacs merges the files named @file{dir} from
texinfo.texi(,14685) each of the listed directories.  (In Emacs version 18, you can set the
texinfo.texi(,14686) @code{Info-directory} variable to the name of only one
texinfo.texi(,14687) directory.)@refill
texinfo.texi(,14688) 
texinfo.texi(,14689) @item
texinfo.texi(,14690) Specify the Info directory name in the @code{INFOPATH} environment
texinfo.texi(,14691) variable in your @file{.profile} or @file{.cshrc} initialization file.
texinfo.texi(,14692) (Only you and others who set this environment variable will be able to
texinfo.texi(,14693) find Info files whose location is specified this way.)
texinfo.texi(,14694) @end enumerate
texinfo.texi(,14695) 
texinfo.texi(,14696) For example, to reach a test file in the @file{/home/bob/info}
texinfo.texi(,14697) directory, you could add an entry like this to the menu in the
texinfo.texi(,14698) standard @file{dir} file:@refill
texinfo.texi(,14699) 
texinfo.texi(,14700) @example
texinfo.texi(,14701) * Test: (/home/bob/info/info-test).  Bob's own test file.
texinfo.texi(,14702) @end example
texinfo.texi(,14703) 
texinfo.texi(,14704) @noindent
texinfo.texi(,14705) In this case, the absolute file name of the @file{info-test} file is
texinfo.texi(,14706) written as the second part of the menu entry.@refill
texinfo.texi(,14707) 
texinfo.texi(,14708) Alternatively, you could write the following in your @file{.emacs} file:
texinfo.texi(,14709) 
texinfo.texi(,14710) @vindex Info-directory-list
texinfo.texi(,14711) @example
texinfo.texi(,14712) @group
texinfo.texi(,14713) (require 'info)
texinfo.texi(,14714) (setq Info-directory-list
texinfo.texi(,14715)   (cons (expand-file-name "/home/bob/info")
texinfo.texi(,14716)         Info-directory-list))
texinfo.texi(,14717) @end group
texinfo.texi(,14718) @end example
texinfo.texi(,14719) 
texinfo.texi(,14720) This tells Emacs to merge the system @file{dir} file with the @file{dir}
texinfo.texi(,14721) file in @file{/home/bob/info}.  Thus, Info will list the
texinfo.texi(,14722) @file{/home/bob/info/info-test} file as a menu entry in the
texinfo.texi(,14723) @file{/home/bob/info/dir} file.  Emacs does the merging only when
texinfo.texi(,14724) @kbd{M-x info} is first run, so if you want to set
texinfo.texi(,14725) @code{Info-directory-list} in an Emacs session where you've already run
texinfo.texi(,14726) @code{info}, you must @code{(setq Info-dir-contents nil)} to force Emacs
texinfo.texi(,14727) to recompose the @file{dir} file.
texinfo.texi(,14728) 
texinfo.texi(,14729) @vindex INFOPATH
texinfo.texi(,14730) Finally, you can tell Info where to look by setting the @code{INFOPATH}
texinfo.texi(,14731) environment variable in your shell startup file, such as @file{.cshrc},
texinfo.texi(,14732) @file{.profile} or @file{autoexec.bat}.  If you use a Bourne-compatible
texinfo.texi(,14733) shell such as @code{sh} or @code{bash} for your shell command
texinfo.texi(,14734) interpreter, you set the @code{INFOPATH} environment variable in the
texinfo.texi(,14735) @file{.profile} initialization file; but if you use @code{csh} or
texinfo.texi(,14736) @code{tcsh}, you set the variable in the @file{.cshrc} initialization
texinfo.texi(,14737) file.  On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
texinfo.texi(,14738) your @file{autoexec.bat} file or in the Registry.  Each type of shell
texinfo.texi(,14739) uses a different syntax.
texinfo.texi(,14740) 
texinfo.texi(,14741) @itemize @bullet
texinfo.texi(,14742) @item
texinfo.texi(,14743) In a @file{.cshrc} file, you could set the @code{INFOPATH}
texinfo.texi(,14744) variable as follows:@refill
texinfo.texi(,14745) 
texinfo.texi(,14746) @smallexample
texinfo.texi(,14747) setenv INFOPATH .:~/info:/usr/local/emacs/info
texinfo.texi(,14748) @end smallexample
texinfo.texi(,14749) 
texinfo.texi(,14750) @item
texinfo.texi(,14751) In a @file{.profile} file, you would achieve the same effect by
texinfo.texi(,14752) writing:@refill
texinfo.texi(,14753) 
texinfo.texi(,14754) @smallexample
texinfo.texi(,14755) INFOPATH=.:$HOME/info:/usr/local/emacs/info
texinfo.texi(,14756) export INFOPATH
texinfo.texi(,14757) @end smallexample
texinfo.texi(,14758) 
texinfo.texi(,14759) @item
texinfo.texi(,14760) @pindex autoexec.bat
texinfo.texi(,14761) In a @file{autoexec.bat} file, you write this command@footnote{Note the
texinfo.texi(,14762) use of @samp{;} as the directory separator, and a different syntax for
texinfo.texi(,14763) using values of other environment variables.}:
texinfo.texi(,14764) 
texinfo.texi(,14765) @smallexample
texinfo.texi(,14766) set INFOPATH=.;%HOME%/info;c:/usr/local/emacs/info
texinfo.texi(,14767) @end smallexample
texinfo.texi(,14768) @end itemize
texinfo.texi(,14769) 
texinfo.texi(,14770) @noindent
texinfo.texi(,14771) The @samp{.} indicates the current directory as usual.  Emacs uses the
texinfo.texi(,14772) @code{INFOPATH} environment variable to initialize the value of Emacs's
texinfo.texi(,14773) own @code{Info-directory-list} variable.  The stand-alone Info reader
texinfo.texi(,14774) merges any files named @file{dir} in any directory listed in the
texinfo.texi(,14775) @env{INFOPATH} variable into a single menu presented to you in the node
texinfo.texi(,14776) called @samp{(dir)Top}.
texinfo.texi(,14777) 
texinfo.texi(,14778) @cindex colon, last in @env{INFOPATH}
texinfo.texi(,14779) However you set @env{INFOPATH}, if its last character is a
texinfo.texi(,14780) colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
texinfo.texi(,14781) is replaced by the default (compiled-in) path.  This gives you a way to
texinfo.texi(,14782) augment the default path with new directories without having to list all
texinfo.texi(,14783) the standard places.  For example (using @code{sh} syntax):
texinfo.texi(,14784) 
texinfo.texi(,14785) @example
texinfo.texi(,14786) INFOPATH=/local/info:
texinfo.texi(,14787) export INFOPATH
texinfo.texi(,14788) @end example
texinfo.texi(,14789) 
texinfo.texi(,14790) @noindent
texinfo.texi(,14791) will search @file{/local/info} first, then the standard directories.
texinfo.texi(,14792) Leading or doubled colons are not treated specially.
texinfo.texi(,14793) 
texinfo.texi(,14794) @cindex @file{dir} file, creating your own
texinfo.texi(,14795) When you create your own @file{dir} file for use with
texinfo.texi(,14796) @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
texinfo.texi(,14797) copying an existing @file{dir} file and replace all the text after the
texinfo.texi(,14798) @samp{* Menu:} with your desired entries.  That way, the punctuation and
texinfo.texi(,14799) special CTRL-_ characters that Info needs will be present.
texinfo.texi(,14800) 
texinfo.texi(,14801) 
texinfo.texi(,14802) @node Installing Dir Entries
texinfo.texi(,14803) @subsection Installing Info Directory Files
texinfo.texi(,14804) 
texinfo.texi(,14805) When you install an Info file onto your system, you can use the program
texinfo.texi(,14806) @code{install-info} to update the Info directory file @file{dir}.
texinfo.texi(,14807) Normally the makefile for the package runs @code{install-info}, just
texinfo.texi(,14808) after copying the Info file into its proper installed location.
texinfo.texi(,14809) 
texinfo.texi(,14810) @findex dircategory
texinfo.texi(,14811) @findex direntry
texinfo.texi(,14812) In order for the Info file to work with @code{install-info}, you include
texinfo.texi(,14813) the commands @code{@@dircategory} and
texinfo.texi(,14814) @code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
texinfo.texi(,14815) file.  Use @code{@@direntry} to specify the menu entries to add to the
texinfo.texi(,14816) Info directory file, and use @code{@@dircategory} to specify which part
texinfo.texi(,14817) of the Info directory to put it in.  Here is how these commands are used
texinfo.texi(,14818) in this manual:
texinfo.texi(,14819) 
texinfo.texi(,14820) @smallexample
texinfo.texi(,14821) @@dircategory Texinfo documentation system
texinfo.texi(,14822) @@direntry
texinfo.texi(,14823) * Texinfo: (texinfo).           The GNU documentation format.
texinfo.texi(,14824) * install-info: (texinfo)Invoking install-info. @dots{}
texinfo.texi(,14825) @dots{}
texinfo.texi(,14826) @@end direntry
texinfo.texi(,14827) @end smallexample
texinfo.texi(,14828) 
texinfo.texi(,14829) Here's what this produces in the Info file:
texinfo.texi(,14830) 
texinfo.texi(,14831) @smallexample
texinfo.texi(,14832) INFO-DIR-SECTION Texinfo documentation system
texinfo.texi(,14833) START-INFO-DIR-ENTRY
texinfo.texi(,14834) * Texinfo: (texinfo).           The GNU documentation format.
texinfo.texi(,14835) * install-info: (texinfo)Invoking install-info. @dots{}
texinfo.texi(,14836) @dots{}
texinfo.texi(,14837) END-INFO-DIR-ENTRY
texinfo.texi(,14838) @end smallexample
texinfo.texi(,14839) 
texinfo.texi(,14840) @noindent
texinfo.texi(,14841) The @code{install-info} program sees these lines in the Info file, and
texinfo.texi(,14842) that is how it knows what to do.
texinfo.texi(,14843) 
texinfo.texi(,14844) Always use the @code{@@direntry} and @code{@@dircategory} commands near
texinfo.texi(,14845) the beginning of the Texinfo input, before the first @code{@@node}
texinfo.texi(,14846) command.  If you use them later on in the input, @code{install-info}
texinfo.texi(,14847) will not notice them.
texinfo.texi(,14848) 
texinfo.texi(,14849) If you use @code{@@dircategory} more than once in the Texinfo source,
texinfo.texi(,14850) each usage specifies the `current' category; any subsequent
texinfo.texi(,14851) @code{@@direntry} commands will add to that category.  
texinfo.texi(,14852) 
texinfo.texi(,14853) Here are some recommended @code{@@dircategory} categories:
texinfo.texi(,14854) 
texinfo.texi(,14855) @display
texinfo.texi(,14856) GNU packages
texinfo.texi(,14857) GNU programming tools
texinfo.texi(,14858) GNU programming documentation
texinfo.texi(,14859) GNU Emacs Lisp
texinfo.texi(,14860) GNU libraries
texinfo.texi(,14861) TeX
texinfo.texi(,14862) Individual utilities
texinfo.texi(,14863) @end display
texinfo.texi(,14864) 
texinfo.texi(,14865) The idea is to include the `Invoking' node for every program installed
texinfo.texi(,14866) by a package under `Individual utilities', and an entry for the manual
texinfo.texi(,14867) as a whole in the appropriate other category.
texinfo.texi(,14868) 
texinfo.texi(,14869) 
texinfo.texi(,14870) @node Invoking install-info
texinfo.texi(,14871) @subsection Invoking install-info
texinfo.texi(,14872) 
texinfo.texi(,14873) @pindex install-info
texinfo.texi(,14874) 
texinfo.texi(,14875) @code{install-info} inserts menu entries from an Info file into the
texinfo.texi(,14876) top-level @file{dir} file in the Info system (see the previous sections
texinfo.texi(,14877) for an explanation of how the @file{dir} file works).  It's most often
texinfo.texi(,14878) run as part of software installation, or when constructing a @file{dir} file
texinfo.texi(,14879) for all manuals on a system.  Synopsis:
texinfo.texi(,14880) 
texinfo.texi(,14881) @example
texinfo.texi(,14882) install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
texinfo.texi(,14883) @end example
texinfo.texi(,14884) 
texinfo.texi(,14885) If @var{info-file} or @var{dir-file} are not specified, the options
texinfo.texi(,14886) (described below) that define them must be.  There are no compile-time
texinfo.texi(,14887) defaults, and standard input is never used.  @code{install-info} can
texinfo.texi(,14888) read only one Info file and write only one @file{dir} file per invocation.
texinfo.texi(,14889) 
texinfo.texi(,14890) @cindex @file{dir}, created by @code{install-info}
texinfo.texi(,14891) If @var{dir-file} (however specified) does not exist,
texinfo.texi(,14892) @code{install-info} creates it if possible (with no entries).
texinfo.texi(,14893) 
texinfo.texi(,14894) @cindex Compressed files, reading
texinfo.texi(,14895) @cindex Dir files, compressed
texinfo.texi(,14896) If any input file is compressed with @code{gzip} (@pxref{Invoking
texinfo.texi(,14897) gzip,,,gzip, Gzip}), @code{install-info} automatically uncompresses it
texinfo.texi(,14898) for reading.  And if @var{dir-file} is compressed, @code{install-info}
texinfo.texi(,14899) also automatically leaves it compressed after writing any changes.
texinfo.texi(,14900) If @var{dir-file} itself does not exist, @code{install-info} tries to
texinfo.texi(,14901) open @file{@var{dir-file}.gz}.
texinfo.texi(,14902) 
texinfo.texi(,14903) Options:
texinfo.texi(,14904) 
texinfo.texi(,14905) @table @code
texinfo.texi(,14906) @item --delete
texinfo.texi(,14907) @opindex --delete
texinfo.texi(,14908) Delete the entries in @var{info-file} from @var{dir-file}.  The file
texinfo.texi(,14909) name in the entry in @var{dir-file} must be @var{info-file} (except for
texinfo.texi(,14910) an optional @samp{.info} in either one).  Don't insert any new entries.
texinfo.texi(,14911) 
texinfo.texi(,14912) @item --dir-file=@var{name}
texinfo.texi(,14913) @itemx -d @var{name}
texinfo.texi(,14914) @opindex --dir-file=@var{name}
texinfo.texi(,14915) @opindex -d @var{name}
texinfo.texi(,14916) Specify file name of the Info directory file.  This is equivalent to
texinfo.texi(,14917) using the @var{dir-file} argument.
texinfo.texi(,14918) 
texinfo.texi(,14919) @item --entry=@var{text}
texinfo.texi(,14920) @itemx -e @var{text}
texinfo.texi(,14921) @opindex --entry=@var{text}
texinfo.texi(,14922) @opindex -e @var{text}
texinfo.texi(,14923) Insert @var{text} as an Info directory entry; @var{text} should have the
texinfo.texi(,14924) form of an Info menu item line plus zero or more extra lines starting
texinfo.texi(,14925) with whitespace.  If you specify more than one entry, they are all
texinfo.texi(,14926) added.  If you don't specify any entries, they are determined from
texinfo.texi(,14927) information in the Info file itself.
texinfo.texi(,14928) 
texinfo.texi(,14929) @item --help
texinfo.texi(,14930) @itemx -h
texinfo.texi(,14931) @opindex --help
texinfo.texi(,14932) @opindex -h
texinfo.texi(,14933) Display a usage message listing basic usage and all available options,
texinfo.texi(,14934) then exit successfully.
texinfo.texi(,14935) 
texinfo.texi(,14936) @item --info-file=@var{file}
texinfo.texi(,14937) @itemx -i @var{file}
texinfo.texi(,14938) @opindex --info-file=@var{file}
texinfo.texi(,14939) @opindex -i @var{file}
texinfo.texi(,14940) Specify Info file to install in the directory.
texinfo.texi(,14941) Equivalent to using the @var{info-file} argument.
texinfo.texi(,14942) 
texinfo.texi(,14943) @item --info-dir=@var{dir}
texinfo.texi(,14944) @itemx -D @var{dir}
texinfo.texi(,14945) @opindex --info-dir=@var{dir}
texinfo.texi(,14946) @opindex -D @var{dir}
texinfo.texi(,14947) Specify the directory where @file{dir} resides.
texinfo.texi(,14948) Equivalent to @samp{--dir-file=@var{dir}/dir}.
texinfo.texi(,14949) 
texinfo.texi(,14950) @item --item=@var{text}
texinfo.texi(,14951) @opindex --item=@var{text}
texinfo.texi(,14952) Same as @samp{--entry=@var{text}}.  An Info directory entry is actually
texinfo.texi(,14953) a menu item.
texinfo.texi(,14954) 
texinfo.texi(,14955) @item --quiet
texinfo.texi(,14956) @opindex --quiet
texinfo.texi(,14957) Suppress warnings.
texinfo.texi(,14958) 
texinfo.texi(,14959) @item --remove
texinfo.texi(,14960) @itemx -r
texinfo.texi(,14961) @opindex --remove
texinfo.texi(,14962) @opindex -r
texinfo.texi(,14963) Same as @samp{--delete}.
texinfo.texi(,14964) 
texinfo.texi(,14965) @item --section=@var{sec}
texinfo.texi(,14966) @itemx -s @var{sec}
texinfo.texi(,14967) @opindex --section=@var{sec}
texinfo.texi(,14968) @opindex -s @var{sec}
texinfo.texi(,14969) Put this file's entries in section @var{sec} of the directory.  If you
texinfo.texi(,14970) specify more than one section, all the entries are added in each of the
texinfo.texi(,14971) sections.  If you don't specify any sections, they are determined from
texinfo.texi(,14972) information in the Info file itself.
texinfo.texi(,14973) 
texinfo.texi(,14974) @item --version
texinfo.texi(,14975) @itemx -V
texinfo.texi(,14976) @opindex --version
texinfo.texi(,14977) @opindex -V
texinfo.texi(,14978) @cindex version number, finding
texinfo.texi(,14979) Display version information and exit successfully.
texinfo.texi(,14980) 
texinfo.texi(,14981) @end table
texinfo.texi(,14982) 
texinfo.texi(,14983) 
texinfo.texi(,14984) @node Command List
texinfo.texi(,14985) @appendix @@-Command List
texinfo.texi(,14986) @cindex Alphabetical @@-command list
texinfo.texi(,14987) @cindex List of  @@-commands
texinfo.texi(,14988) @cindex @@-command list
texinfo.texi(,14989) @cindex Reference to @@-commands
texinfo.texi(,14990) 
texinfo.texi(,14991) Here is an alphabetical list of the @@-commands in Texinfo.  Square
texinfo.texi(,14992) brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
texinfo.texi(,14993) @samp{@dots{}}, indicates repeated text.
texinfo.texi(,14994) 
texinfo.texi(,14995) @sp 1
texinfo.texi(,14996) @table @code
texinfo.texi(,14997) @item @@@var{whitespace}
texinfo.texi(,14998) An @code{@@} followed by a space, tab, or newline produces a normal,
texinfo.texi(,14999) stretchable, interword space.  @xref{Multiple Spaces}.
texinfo.texi(,15000) 
texinfo.texi(,15001) @item @@!
texinfo.texi(,15002) Generate an exclamation point that really does end a sentence (usually
texinfo.texi(,15003) after an end-of-sentence capital letter).  @xref{Ending a Sentence}.
texinfo.texi(,15004) 
texinfo.texi(,15005) @item @@"
texinfo.texi(,15006) @itemx @@'
texinfo.texi(,15007) Generate an umlaut or acute accent, respectively, over the next
texinfo.texi(,15008) character, as in @"o and @'o.  @xref{Inserting Accents}.
texinfo.texi(,15009) 
texinfo.texi(,15010) @item @@*
texinfo.texi(,15011) Force a line break. Do not end a paragraph that uses @code{@@*} with
texinfo.texi(,15012) an @code{@@refill} command.  @xref{Line Breaks}.
texinfo.texi(,15013) 
texinfo.texi(,15014) @item @@,@{@var{c}@}
texinfo.texi(,15015) Generate a cedilla accent under @var{c}, as in @,{c}.  @xref{Inserting
texinfo.texi(,15016) Accents}.
texinfo.texi(,15017) 
texinfo.texi(,15018) @item @@-
texinfo.texi(,15019) Insert a discretionary hyphenation point.  @xref{- and hyphenation}.
texinfo.texi(,15020) 
texinfo.texi(,15021) @item @@.
texinfo.texi(,15022) Produce a period that really does end a sentence (usually after an
texinfo.texi(,15023) end-of-sentence capital letter).  @xref{Ending a Sentence}.
texinfo.texi(,15024) 
texinfo.texi(,15025) @item @@:
texinfo.texi(,15026) Indicate to @TeX{} that an immediately preceding period, question
texinfo.texi(,15027) mark, exclamation mark, or colon does not end a sentence.  Prevent
texinfo.texi(,15028) @TeX{} from inserting extra whitespace as it does at the end of a
texinfo.texi(,15029) sentence.  The command has no effect on the Info file output.
texinfo.texi(,15030) @xref{Not Ending a Sentence}.
texinfo.texi(,15031) 
texinfo.texi(,15032) @item @@=
texinfo.texi(,15033) Generate a macron (bar) accent over the next character, as in @=o.
texinfo.texi(,15034) @xref{Inserting Accents}.
texinfo.texi(,15035) 
texinfo.texi(,15036) @item @@?
texinfo.texi(,15037) Generate a question mark that really does end a sentence (usually after
texinfo.texi(,15038) an end-of-sentence capital letter).  @xref{Ending a Sentence}.
texinfo.texi(,15039) 
texinfo.texi(,15040) @item @@@@
texinfo.texi(,15041) Stands for an at sign, @samp{@@}.
texinfo.texi(,15042) @xref{Braces Atsigns, , Inserting @@ and braces}.
texinfo.texi(,15043) 
texinfo.texi(,15044) @item @@\
texinfo.texi(,15045) Stands for a backslash (@samp{\}) inside @code{@@math}.
texinfo.texi(,15046) @xref{math,,@code{math}}.
texinfo.texi(,15047) 
texinfo.texi(,15048) @item @@^
texinfo.texi(,15049) @itemx @@`
texinfo.texi(,15050) Generate a circumflex (hat) or grave accent, respectively, over the next
texinfo.texi(,15051) character, as in @^o and @`e.
texinfo.texi(,15052) @xref{Inserting Accents}.
texinfo.texi(,15053) 
texinfo.texi(,15054) @item @@@{
texinfo.texi(,15055) Stands for a left brace, @samp{@{}.
texinfo.texi(,15056) @xref{Braces Atsigns, , Inserting @@ and braces}.
texinfo.texi(,15057) 
texinfo.texi(,15058) @item @@@}
texinfo.texi(,15059) Stands for a right-hand brace, @samp{@}}.@*
texinfo.texi(,15060) @xref{Braces Atsigns, , Inserting @@ and braces}.
texinfo.texi(,15061) 
texinfo.texi(,15062) @item @@~
texinfo.texi(,15063) Generate a tilde accent over the next character, as in @~N.
texinfo.texi(,15064) @xref{Inserting Accents}.
texinfo.texi(,15065) 
texinfo.texi(,15066) @item @@AA@{@}
texinfo.texi(,15067) @itemx @@aa@{@}
texinfo.texi(,15068) Generate the uppercase and lowercase Scandinavian A-ring letters,
texinfo.texi(,15069) respectively: @AA{}, @aa{}.  @xref{Inserting Accents}.
texinfo.texi(,15070) 
texinfo.texi(,15071) @item @@acronym@{@var{abbrev}@}
texinfo.texi(,15072) Tag @var{abbrev} as an acronym, that is, an abbreviation written in all
texinfo.texi(,15073) capital letters, such as `NASA'.  @xref{acronym,, @code{acronym}}.
texinfo.texi(,15074) 
texinfo.texi(,15075) @item @@AE@{@}
texinfo.texi(,15076) @itemx @@ae@{@}
texinfo.texi(,15077) Generate the uppercase and lowercase AE ligatures, respectively:
texinfo.texi(,15078) @AE{}, @ae{}.  @xref{Inserting Accents}.
texinfo.texi(,15079) 
texinfo.texi(,15080) @itemx @@afivepaper
texinfo.texi(,15081) Change page dimensions for the A5 paper size.  @xref{A4 Paper}.
texinfo.texi(,15082) 
texinfo.texi(,15083) @item @@afourlatex
texinfo.texi(,15084) @itemx @@afourpaper
texinfo.texi(,15085) @itemx @@afourwide
texinfo.texi(,15086) Change page dimensions for the A4 paper size.  @xref{A4 Paper}.
texinfo.texi(,15087) 
texinfo.texi(,15088) @item @@alias @var{new}=@var{existing}
texinfo.texi(,15089) Make the command @samp{@@@var{new}} an alias for the existing command
texinfo.texi(,15090) @samp{@@@var{existing}}.  @xref{alias}.
texinfo.texi(,15091) 
texinfo.texi(,15092) @item @@anchor@{@var{name}@}
texinfo.texi(,15093) Define @var{name} as the current location for use as a cross-reference
texinfo.texi(,15094) target.  @xref{anchor,, @code{@@anchor}}.
texinfo.texi(,15095) 
texinfo.texi(,15096) @item @@appendix @var{title}
texinfo.texi(,15097) Begin an appendix.  The title appears in the table
texinfo.texi(,15098) of contents of a printed manual.  In Info, the title is
texinfo.texi(,15099) underlined with asterisks.  @xref{unnumbered & appendix, , The
texinfo.texi(,15100) @code{@@unnumbered} and @code{@@appendix} Commands}.@refill
texinfo.texi(,15101) 
texinfo.texi(,15102) @item @@appendixsec @var{title}
texinfo.texi(,15103) @itemx @@appendixsection @var{title}
texinfo.texi(,15104) Begin an appendix section within an appendix.  The section title appears
texinfo.texi(,15105) in the table of contents of a printed manual.  In Info, the title is
texinfo.texi(,15106) underlined with equal signs.  @code{@@appendixsection} is a longer
texinfo.texi(,15107) spelling of the @code{@@appendixsec} command.  @xref{unnumberedsec
texinfo.texi(,15108) appendixsec heading, , Section Commands}.@refill
texinfo.texi(,15109) 
texinfo.texi(,15110) @item @@appendixsubsec @var{title}
texinfo.texi(,15111) Begin an appendix subsection within an appendix.  The title appears
texinfo.texi(,15112) in the table of contents of a printed manual.  In Info, the title is
texinfo.texi(,15113) underlined with hyphens.  @xref{unnumberedsubsec appendixsubsec
texinfo.texi(,15114) subheading, , Subsection Commands}.@refill
texinfo.texi(,15115) 
texinfo.texi(,15116) @item @@appendixsubsubsec @var{title}
texinfo.texi(,15117) Begin an appendix subsubsection within an appendix subsection.  The
texinfo.texi(,15118) title appears in the table of contents of a printed manual.  In Info,
texinfo.texi(,15119) the title is underlined with periods.  @xref{subsubsection,, The
texinfo.texi(,15120) `subsub' Commands}.@refill
texinfo.texi(,15121) 
texinfo.texi(,15122) @item @@asis
texinfo.texi(,15123) Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
texinfo.texi(,15124) print the table's first column without highlighting (``as is'').
texinfo.texi(,15125) @xref{Two-column Tables, , Making a Two-column Table}.@refill
texinfo.texi(,15126) 
texinfo.texi(,15127) @item @@author @var{author}
texinfo.texi(,15128) Typeset @var{author} flushleft and underline it.  @xref{title
texinfo.texi(,15129) subtitle author, , The @code{@@title} and @code{@@author}
texinfo.texi(,15130) Commands}.@refill
texinfo.texi(,15131) 
texinfo.texi(,15132) @item @@b@{@var{text}@}
texinfo.texi(,15133) Print @var{text} in @b{bold} font.  No effect in Info.  @xref{Fonts}.@refill
texinfo.texi(,15134) 
texinfo.texi(,15140) 
texinfo.texi(,15141) @item @@bullet@{@}
texinfo.texi(,15142) Generate a large round dot, or the closest possible
texinfo.texi(,15143) thing to one.  @xref{bullet, , @code{@@bullet}}.@refill
texinfo.texi(,15144) 
texinfo.texi(,15145) @item @@bye
texinfo.texi(,15146) Stop formatting a file.  The formatters do not see the contents of a
texinfo.texi(,15147) file following an @code{@@bye} command.  @xref{Ending a File}.@refill
texinfo.texi(,15148) 
texinfo.texi(,15149) @item @@c @var{comment}
texinfo.texi(,15150) Begin a comment in Texinfo.  The rest of the line does not appear in
texinfo.texi(,15151) either the Info file or the printed manual.  A synonym for
texinfo.texi(,15152) @code{@@comment}.  @xref{Comments, , Comments}.@refill
texinfo.texi(,15153) 
texinfo.texi(,15154) @item @@cartouche
texinfo.texi(,15155) Highlight an example or quotation by drawing a box with rounded
texinfo.texi(,15156) corners around it.  Pair with @code{@@end cartouche}.  No effect in
texinfo.texi(,15157) Info.  @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
texinfo.texi(,15158) 
texinfo.texi(,15159) @item @@center @var{line-of-text}
texinfo.texi(,15160) Center the line of text following the command.
texinfo.texi(,15161) @xref{titlefont center sp, , @code{@@center}}.@refill
texinfo.texi(,15162) 
texinfo.texi(,15163) @item @@centerchap @var{line-of-text}
texinfo.texi(,15164) Like @code{@@chapter}, but centers the chapter title.  @xref{chapter,,
texinfo.texi(,15165) @code{@@chapter}}.
texinfo.texi(,15166) 
texinfo.texi(,15167) @item @@chapheading @var{title}
texinfo.texi(,15168) Print a chapter-like heading in the text, but not in the table of
texinfo.texi(,15169) contents of a printed manual.  In Info, the title is underlined with
texinfo.texi(,15170) asterisks.  @xref{majorheading & chapheading, , @code{@@majorheading}
texinfo.texi(,15171) and @code{@@chapheading}}.@refill
texinfo.texi(,15172) 
texinfo.texi(,15173) @item @@chapter @var{title}
texinfo.texi(,15174) Begin a chapter.  The chapter title appears in the table of
texinfo.texi(,15175) contents of a printed manual.  In Info, the title is underlined with
texinfo.texi(,15176) asterisks.  @xref{chapter, , @code{@@chapter}}.@refill
texinfo.texi(,15177) 
texinfo.texi(,15178) @item @@cindex @var{entry}
texinfo.texi(,15179) Add @var{entry} to the index of concepts.  @xref{Index Entries, ,
texinfo.texi(,15180) Defining the Entries of an Index}.@refill
texinfo.texi(,15181) 
texinfo.texi(,15182) @item @@cite@{@var{reference}@}
texinfo.texi(,15183) Highlight the name of a book or other reference that lacks a
texinfo.texi(,15184) companion Info file.  @xref{cite, , @code{@@cite}}.@refill
texinfo.texi(,15185) 
texinfo.texi(,15186) @item @@clear @var{flag}
texinfo.texi(,15187) Unset @var{flag}, preventing the Texinfo formatting commands from
texinfo.texi(,15188) formatting text between subsequent pairs of @code{@@ifset @var{flag}}
texinfo.texi(,15189) and @code{@@end ifset} commands, and preventing
texinfo.texi(,15190) @code{@@value@{@var{flag}@}} from expanding to the value to which
texinfo.texi(,15191) @var{flag} is set.
texinfo.texi(,15192) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
texinfo.texi(,15193) 
texinfo.texi(,15194) @item @@code@{@var{sample-code}@}
texinfo.texi(,15195) Highlight text that is an expression, a syntactically complete token
texinfo.texi(,15196) of a program, or a program name.  @xref{code, , @code{@@code}}.@refill
texinfo.texi(,15197) 
texinfo.texi(,15198) @item @@command@{@var{command-name}@}
texinfo.texi(,15199) Indicate a command name, such as @command{ls}.
texinfo.texi(,15200) @xref{command,, @code{@@command}}.
texinfo.texi(,15201) 
texinfo.texi(,15202) @item @@comment @var{comment}
texinfo.texi(,15203) Begin a comment in Texinfo.  The rest of the line does not appear in
texinfo.texi(,15204) either the Info file or the printed manual.  A synonym for @code{@@c}.
texinfo.texi(,15205) @xref{Comments}.
texinfo.texi(,15206) 
texinfo.texi(,15207) @item @@contents
texinfo.texi(,15208) Print a complete table of contents.  Has no effect in Info, which uses
texinfo.texi(,15209) menus instead.  @xref{Contents, , Generating a Table of
texinfo.texi(,15210) Contents}.@refill
texinfo.texi(,15211) 
texinfo.texi(,15212) @item @@copyright@{@}
texinfo.texi(,15213) Generate a copyright symbol.  @xref{copyright symbol, ,
texinfo.texi(,15214) @code{@@copyright}}.@refill
texinfo.texi(,15215) 
texinfo.texi(,15221) 
texinfo.texi(,15222) @item @@defcodeindex @var{index-name}
texinfo.texi(,15223) Define a new index and its indexing command.  Print entries in an
texinfo.texi(,15224) @code{@@code} font.  @xref{New Indices, , Defining New
texinfo.texi(,15225) Indices}.@refill
texinfo.texi(,15226) 
texinfo.texi(,15227) @item @@defcv @var{category} @var{class} @var{name}
texinfo.texi(,15228) @itemx @@defcvx @var{category} @var{class} @var{name}
texinfo.texi(,15229) Format a description for a variable associated with a class in
texinfo.texi(,15230) object-oriented programming.  Takes three arguments: the category of
texinfo.texi(,15231) thing being defined, the class to which it belongs, and its name.
texinfo.texi(,15232) @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15233) 
texinfo.texi(,15234) @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
texinfo.texi(,15235) @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
texinfo.texi(,15236) Format a description for a function, interactive command, or similar
texinfo.texi(,15237) entity that may take arguments.  @code{@@deffn} takes as arguments the
texinfo.texi(,15238) category of entity being described, the name of this particular
texinfo.texi(,15239) entity, and its arguments, if any.  @xref{Definition Commands}.@refill
texinfo.texi(,15240) 
texinfo.texi(,15241) @item @@defindex @var{index-name}
texinfo.texi(,15242) Define a new index and its indexing command.  Print entries in a roman
texinfo.texi(,15243) font.  @xref{New Indices, , Defining New Indices}.@refill
texinfo.texi(,15244) 
texinfo.texi(,15245) @item @@definfoenclose @var{newcmd}, @var{before}, @var{after},
texinfo.texi(,15246) Create new @@-command @var{newcmd} for Info that marks text by enclosing
texinfo.texi(,15247) it in strings that precede and follow the text.  @xref{definfoenclose}.
texinfo.texi(,15248) 
texinfo.texi(,15249) @item @@defivar @var{class} @var{instance-variable-name}
texinfo.texi(,15250) @itemx @@defivarx @var{class} @var{instance-variable-name}
texinfo.texi(,15251) This command formats a description for an instance variable in
texinfo.texi(,15252) object-oriented programming.  The command is equivalent to @samp{@@defcv
texinfo.texi(,15253) @{Instance Variable@} @dots{}}.  @xref{Definition Commands}, and
texinfo.texi(,15254) @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15255) 
texinfo.texi(,15256) @item @@defmac @var{macroname} @var{arguments}@dots{}
texinfo.texi(,15257) @itemx @@defmacx @var{macroname} @var{arguments}@dots{}
texinfo.texi(,15258) Format a description for a macro.  The command is equivalent to
texinfo.texi(,15259) @samp{@@deffn Macro @dots{}}.  @xref{Definition Commands}, and
texinfo.texi(,15260) @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15261) 
texinfo.texi(,15262) @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
texinfo.texi(,15263) @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
texinfo.texi(,15264) Format a description for a method in object-oriented programming.  The
texinfo.texi(,15265) command is equivalent to @samp{@@defop Method @dots{}}.  Takes as
texinfo.texi(,15266) arguments the name of the class of the method, the name of the
texinfo.texi(,15267) method, and its arguments, if any.  @xref{Definition Commands}, and
texinfo.texi(,15268) @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15269) 
texinfo.texi(,15270) @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
texinfo.texi(,15271) @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
texinfo.texi(,15272) Format a description for an operation in object-oriented programming.
texinfo.texi(,15273) @code{@@defop} takes as arguments the overall name of the category of
texinfo.texi(,15274) operation, the name of the class of the operation, the name of the
texinfo.texi(,15275) operation, and its arguments, if any.  @xref{Definition
texinfo.texi(,15276) Commands}, and @ref{Abstract Objects}.
texinfo.texi(,15277) 
texinfo.texi(,15278) @item @@defopt @var{option-name}
texinfo.texi(,15279) @itemx @@defoptx @var{option-name}
texinfo.texi(,15280) Format a description for a user option.  The command is equivalent to
texinfo.texi(,15281) @samp{@@defvr @{User Option@} @dots{}}.  @xref{Definition Commands}, and
texinfo.texi(,15282) @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15283) 
texinfo.texi(,15284) @item @@defspec @var{special-form-name} @var{arguments}@dots{}
texinfo.texi(,15285) @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
texinfo.texi(,15286) Format a description for a special form.  The command is equivalent to
texinfo.texi(,15287) @samp{@@deffn @{Special Form@} @dots{}}.  @xref{Definition Commands},
texinfo.texi(,15288) and @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15289) 
texinfo.texi(,15290) @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
texinfo.texi(,15291) @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
texinfo.texi(,15292) Format a description for a data type.  @code{@@deftp} takes as arguments
texinfo.texi(,15293) the category, the name of the type (which is a word like @samp{int} or
texinfo.texi(,15294) @samp{float}), and then the names of attributes of objects of that type.
texinfo.texi(,15295) @xref{Definition Commands}, and @ref{Data Types}.
texinfo.texi(,15296) 
texinfo.texi(,15297) @item @@deftypefn @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,15298) @itemx @@deftypefnx @var{classification} @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,15299) Format a description for a function or similar entity that may take
texinfo.texi(,15300) arguments and that is typed.  @code{@@deftypefn} takes as arguments the
texinfo.texi(,15301) classification of entity being described, the type, the name of the
texinfo.texi(,15302) entity, and its arguments, if any.  @xref{Definition Commands}, and
texinfo.texi(,15303) @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15304) 
texinfo.texi(,15305) @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
texinfo.texi(,15306) @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
texinfo.texi(,15307) Format a description for a function in a typed language.
texinfo.texi(,15308) The command is equivalent to @samp{@@deftypefn Function @dots{}}.
texinfo.texi(,15309) @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15310) 
texinfo.texi(,15311) @item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
texinfo.texi(,15312) @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
texinfo.texi(,15313) Format a description for a typed instance variable in object-oriented
texinfo.texi(,15314) programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
texinfo.texi(,15315) 
texinfo.texi(,15316) @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
texinfo.texi(,15317) @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
texinfo.texi(,15318) Format a description for a typed method in object-oriented programming.
texinfo.texi(,15319) @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15320) 
texinfo.texi(,15321) @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,15322) @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
texinfo.texi(,15323) Format a description for a typed operation in object-oriented programming.
texinfo.texi(,15324) @xref{Definition Commands}, and @ref{Abstract Objects}.
texinfo.texi(,15325) 
texinfo.texi(,15326) @item @@deftypevar @var{data-type} @var{variable-name}
texinfo.texi(,15327) @itemx @@deftypevarx @var{data-type} @var{variable-name}
texinfo.texi(,15328) Format a description for a variable in a typed language.  The command is
texinfo.texi(,15329) equivalent to @samp{@@deftypevr Variable @dots{}}.  @xref{Definition
texinfo.texi(,15330) Commands}, and @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15331) 
texinfo.texi(,15332) @item @@deftypevr @var{classification} @var{data-type} @var{name}
texinfo.texi(,15333) @itemx @@deftypevrx @var{classification} @var{data-type} @var{name}
texinfo.texi(,15334) Format a description for something like a variable in a typed
texinfo.texi(,15335) language---an entity that records a value.  Takes as arguments the
texinfo.texi(,15336) classification of entity being described, the type, and the name of the
texinfo.texi(,15337) entity.  @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
texinfo.texi(,15338) Detail}.
texinfo.texi(,15339) 
texinfo.texi(,15340) @item @@defun @var{function-name} @var{arguments}@dots{}
texinfo.texi(,15341) @itemx @@defunx @var{function-name} @var{arguments}@dots{}
texinfo.texi(,15342) Format a description for functions.  The command is equivalent to
texinfo.texi(,15343) @samp{@@deffn Function @dots{}}.  @xref{Definition Commands}, and
texinfo.texi(,15344) @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15345) 
texinfo.texi(,15346) @item @@defvar @var{variable-name}
texinfo.texi(,15347) @itemx @@defvarx @var{variable-name}
texinfo.texi(,15348) Format a description for variables.  The command is equivalent to
texinfo.texi(,15349) @samp{@@defvr Variable @dots{}}.  @xref{Definition Commands}, and
texinfo.texi(,15350) @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15351) 
texinfo.texi(,15352) @item @@defvr @var{category} @var{name}
texinfo.texi(,15353) @itemx @@defvrx @var{category} @var{name}
texinfo.texi(,15354) Format a description for any kind of variable.  @code{@@defvr} takes
texinfo.texi(,15355) as arguments the category of the entity and the name of the entity.
texinfo.texi(,15356) @xref{Definition Commands},
texinfo.texi(,15357) and @ref{deffnx,, Def Cmds in Detail}.
texinfo.texi(,15358) 
texinfo.texi(,15359) @item @@detailmenu
texinfo.texi(,15360) Avoid @code{makeinfo} confusion stemming from the detailed node listing
texinfo.texi(,15361) in a master menu.  @xref{Master Menu Parts}.
texinfo.texi(,15362) 
texinfo.texi(,15363) @item @@dfn@{@var{term}@}
texinfo.texi(,15364) Highlight the introductory or defining use of a term.
texinfo.texi(,15365) @xref{dfn, , @code{@@dfn}}.@refill
texinfo.texi(,15366) 
texinfo.texi(,15367) @item @@dircategory @var{dirpart}
texinfo.texi(,15368) Specify a part of the Info directory menu where this file's entry should
texinfo.texi(,15369) go.  @xref{Installing Dir Entries}.
texinfo.texi(,15370) 
texinfo.texi(,15371) @item @@direntry
texinfo.texi(,15372) Begin the Info directory menu entry for this file.  Pair with
texinfo.texi(,15373) @code{@@end direntry}.  @xref{Installing Dir Entries}.
texinfo.texi(,15374) 
texinfo.texi(,15375) @item @@display
texinfo.texi(,15376) Begin a kind of example.  Like @code{@@example} (indent text, do not
texinfo.texi(,15377) fill), but do not select a new font.  Pair with @code{@@end display}.
texinfo.texi(,15378) @xref{display, , @code{@@display}}.
texinfo.texi(,15379) 
texinfo.texi(,15380) @item @@dmn@{@var{dimension}@}
texinfo.texi(,15381) Format a unit of measure, as in 12@dmn{pt}.  Causes @TeX{} to insert a
texinfo.texi(,15382) thin space before @var{dimension}.  No effect in Info.
texinfo.texi(,15383) @xref{dmn, , @code{@@dmn}}.
texinfo.texi(,15384) 
texinfo.texi(,15385) @item @@documentdescription
texinfo.texi(,15386) Set the document description text, included in the HTML output.  Pair
texinfo.texi(,15387) with @code{@@end documentdescription}.  @xref{documentdescription,,
texinfo.texi(,15388) @code{@@documentdescription}}.
texinfo.texi(,15389) 
texinfo.texi(,15390) @item @@documentencoding @var{enc}
texinfo.texi(,15391) Declare the input encoding to be @var{enc}.
texinfo.texi(,15392) @xref{documentencoding,, @code{@@documentencoding}}.
texinfo.texi(,15393) 
texinfo.texi(,15394) @item @@documentlanguage @var{CC}
texinfo.texi(,15395) Declare the document language as the two-character ISO-639 abbreviation
texinfo.texi(,15396) @var{CC}.  @xref{documentlanguage,, @code{@@documentlanguage}}.
texinfo.texi(,15397) 
texinfo.texi(,15398) @item @@dotaccent@{@var{c}@}
texinfo.texi(,15399) Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
texinfo.texi(,15400) @xref{Inserting Accents}.
texinfo.texi(,15401) 
texinfo.texi(,15402) @item @@dots@{@}
texinfo.texi(,15403) Insert an ellipsis: @samp{@dots{}}.
texinfo.texi(,15404) @xref{dots, , @code{@@dots}}.@refill
texinfo.texi(,15405) 
texinfo.texi(,15406) @item @@email@{@var{address}[, @var{displayed-text}]@}
texinfo.texi(,15407) Indicate an electronic mail address.
texinfo.texi(,15408) @xref{email, , @code{@@email}}.
texinfo.texi(,15409) 
texinfo.texi(,15410) @item @@emph@{@var{text}@}
texinfo.texi(,15411) Highlight @var{text}; text is displayed in @emph{italics} in printed
texinfo.texi(,15412) output, and surrounded by asterisks in Info.  @xref{Emphasis, ,
texinfo.texi(,15413) Emphasizing Text}.
texinfo.texi(,15414) 
texinfo.texi(,15415) @item @@end @var{environment}
texinfo.texi(,15416) Ends @var{environment}, as in @samp{@@end example}.  @xref{Formatting
texinfo.texi(,15417) Commands,,@@-commands}.
texinfo.texi(,15418) 
texinfo.texi(,15419) @item @@env@{@var{environment-variable}@}
texinfo.texi(,15420) Indicate an environment variable name, such as @env{PATH}.
texinfo.texi(,15421) @xref{env,, @code{@@env}}.
texinfo.texi(,15422) 
texinfo.texi(,15423) @item @@enddots@{@}
texinfo.texi(,15424) Generate an end-of-sentence of ellipsis, like this @enddots{}
texinfo.texi(,15425) @xref{dots,,@code{@@dots@{@}}}.
texinfo.texi(,15426) 
texinfo.texi(,15427) @item @@enumerate [@var{number-or-letter}]
texinfo.texi(,15428) Begin a numbered list, using @code{@@item} for each entry.
texinfo.texi(,15429) Optionally, start list with @var{number-or-letter}.  Pair with
texinfo.texi(,15430) @code{@@end enumerate}.  @xref{enumerate, ,
texinfo.texi(,15431) @code{@@enumerate}}.@refill
texinfo.texi(,15432) 
texinfo.texi(,15433) @item @@equiv@{@}
texinfo.texi(,15434) Indicate to the reader the exact equivalence of two forms with a
texinfo.texi(,15435) glyph: @samp{@equiv{}}.  @xref{Equivalence}.@refill
texinfo.texi(,15436) 
texinfo.texi(,15437) @item @@error@{@}
texinfo.texi(,15438) Indicate to the reader with a glyph that the following text is
texinfo.texi(,15439) an error message: @samp{@error{}}.  @xref{Error Glyph}.@refill
texinfo.texi(,15440) 
texinfo.texi(,15441) @item  @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
texinfo.texi(,15442) @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
texinfo.texi(,15443) Specify page footings resp.@: headings for even-numbered (left-hand)
texinfo.texi(,15444) pages.  @xref{Custom Headings, ,
texinfo.texi(,15445) How to Make Your Own Headings}.@refill
texinfo.texi(,15446) 
texinfo.texi(,15447) @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
texinfo.texi(,15448) @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
texinfo.texi(,15449) Specify page footings resp.@: headings for every page.  Not relevant to
texinfo.texi(,15450) Info.  @xref{Custom Headings, , How to Make Your Own Headings}.@refill
texinfo.texi(,15451) 
texinfo.texi(,15452) @item @@example
texinfo.texi(,15453) Begin an example.  Indent text, do not fill, and select fixed-width font.
texinfo.texi(,15454) Pair with @code{@@end example}.  @xref{example, ,
texinfo.texi(,15455) @code{@@example}}.@refill
texinfo.texi(,15456) 
texinfo.texi(,15457) @item @@exampleindent @var{indent}
texinfo.texi(,15458) Indent example-like environments by @var{indent} number of spaces
texinfo.texi(,15459) (perhaps 0).  @xref{exampleindent,, Paragraph Indenting}.
texinfo.texi(,15460) 
texinfo.texi(,15461) @item @@exclamdown@{@}
texinfo.texi(,15462) Produce an upside-down exclamation point.  @xref{Inserting Accents}.
texinfo.texi(,15463) 
texinfo.texi(,15464) @item @@exdent @var{line-of-text}
texinfo.texi(,15465) Remove any indentation a line might have.  @xref{exdent, ,
texinfo.texi(,15466) Undoing the Indentation of a Line}.@refill
texinfo.texi(,15467) 
texinfo.texi(,15468) @item @@expansion@{@}
texinfo.texi(,15469) Indicate the result of a macro expansion to the reader with a special
texinfo.texi(,15470) glyph: @samp{@expansion{}}.
texinfo.texi(,15471) @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
texinfo.texi(,15472) 
texinfo.texi(,15473) @item @@file@{@var{filename}@}
texinfo.texi(,15474) Highlight the name of a file, buffer, node, or directory.  @xref{file, ,
texinfo.texi(,15475) @code{@@file}}.@refill
texinfo.texi(,15476) 
texinfo.texi(,15477) @item @@finalout
texinfo.texi(,15478) Prevent @TeX{} from printing large black warning rectangles beside
texinfo.texi(,15479) over-wide lines.  @xref{Overfull hboxes}.@refill
texinfo.texi(,15480) 
texinfo.texi(,15481) @item @@findex @var{entry}
texinfo.texi(,15482) Add @var{entry} to the index of functions.  @xref{Index Entries, ,
texinfo.texi(,15483) Defining the Entries of an Index}.@refill
texinfo.texi(,15484) 
texinfo.texi(,15485) @item @@flushleft
texinfo.texi(,15486) @itemx @@flushright
texinfo.texi(,15487) Left justify every line but leave the right end ragged.
texinfo.texi(,15488) Leave font as is.  Pair with @code{@@end flushleft}.
texinfo.texi(,15489) @code{@@flushright} analogous.
texinfo.texi(,15490) @xref{flushleft & flushright, , @code{@@flushleft} and
texinfo.texi(,15491) @code{@@flushright}}.@refill
texinfo.texi(,15492) 
texinfo.texi(,15493) @item @@footnote@{@var{text-of-footnote}@}
texinfo.texi(,15494) Enter a footnote.  Footnote text is printed at the bottom of the page
texinfo.texi(,15495) by @TeX{}; Info may format in either `End' node or `Separate' node style.
texinfo.texi(,15496) @xref{Footnotes}.@refill
texinfo.texi(,15497) 
texinfo.texi(,15498) @item @@footnotestyle @var{style}
texinfo.texi(,15499) Specify an Info file's footnote style, either @samp{end} for the end
texinfo.texi(,15500) node style or @samp{separate} for the separate node style.
texinfo.texi(,15501) @xref{Footnotes}.@refill
texinfo.texi(,15502) 
texinfo.texi(,15503) @item @@format
texinfo.texi(,15504) Begin a kind of example.  Like @code{@@display}, but do not narrow the
texinfo.texi(,15505) margins.  Pair with @code{@@end format}.  @xref{example,,
texinfo.texi(,15506) @code{@@example}}.
texinfo.texi(,15507) 
texinfo.texi(,15508) @item @@ftable @var{formatting-command}
texinfo.texi(,15509) Begin a two-column table, using @code{@@item} for each entry.
texinfo.texi(,15510) Automatically enter each of the items in the first column into the
texinfo.texi(,15511) index of functions.  Pair with @code{@@end ftable}.  The same as
texinfo.texi(,15512) @code{@@table}, except for indexing.  @xref{ftable vtable, ,
texinfo.texi(,15513) @code{@@ftable} and @code{@@vtable}}.@refill
texinfo.texi(,15514) 
texinfo.texi(,15515) @item @@group
texinfo.texi(,15516) Hold text together that must appear on one printed page.  Pair with
texinfo.texi(,15517) @code{@@end group}.  Not relevant to Info.  @xref{group, ,
texinfo.texi(,15518) @code{@@group}}.@refill
texinfo.texi(,15519) 
texinfo.texi(,15520) @item @@H@{@var{c}@}
texinfo.texi(,15521) Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
texinfo.texi(,15522) 
texinfo.texi(,15523) @item @@heading @var{title}
texinfo.texi(,15524) Print an unnumbered section-like heading in the text, but not in the
texinfo.texi(,15525) table of contents of a printed manual.  In Info, the title is
texinfo.texi(,15526) underlined with equal signs.  @xref{unnumberedsec appendixsec heading,
texinfo.texi(,15527) , Section Commands}.@refill
texinfo.texi(,15528) 
texinfo.texi(,15529) @item @@headings @var{on-off-single-double}
texinfo.texi(,15530) Turn page headings on or off, and/or specify single-sided or double-sided
texinfo.texi(,15531) page headings for printing.  @xref{headings on off, , The
texinfo.texi(,15532) @code{@@headings} Command}.
texinfo.texi(,15533) 
texinfo.texi(,15534) @item @@html
texinfo.texi(,15535) Enter HTML completely.  Pair with @code{@@end html}.  @xref{Raw
texinfo.texi(,15536) Formatter Commands}.
texinfo.texi(,15537) 
texinfo.texi(,15538) @item @@hyphenation@{@var{hy-phen-a-ted words}@}
texinfo.texi(,15539) Explicitly define hyphenation points.  @xref{- and hyphenation,,
texinfo.texi(,15540) @code{@@-} and @code{@@hyphenation}}.
texinfo.texi(,15541) 
texinfo.texi(,15542) @item @@i@{@var{text}@}
texinfo.texi(,15543) Print @var{text} in @i{italic} font.  No effect in Info.  @xref{Fonts}.
texinfo.texi(,15544) 
texinfo.texi(,15545) @item @@ifclear @var{flag}
texinfo.texi(,15546) If @var{flag} is cleared, the Texinfo formatting commands format text
texinfo.texi(,15547) between @code{@@ifclear @var{flag}} and the following @code{@@end
texinfo.texi(,15548) ifclear} command.
texinfo.texi(,15549) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
texinfo.texi(,15550) 
texinfo.texi(,15551) @item @@ifhtml
texinfo.texi(,15552) @itemx @@ifinfo
texinfo.texi(,15553) Begin a stretch of text that will be ignored by @TeX{} when it typesets
texinfo.texi(,15554) the printed manual.  @code{@@ifhtml} text appears only in the HTML
texinfo.texi(,15555) output.  @code{@@ifinfo} output appears in both Info and (for historical
texinfo.texi(,15556) compatibility) plain text output .  Pair with @code{@@end ifhtml}
texinfo.texi(,15557) resp.@: @code{@@end ifinfo}.  @xref{Conditionals}.
texinfo.texi(,15558) 
texinfo.texi(,15559) @item @@ifnothtml
texinfo.texi(,15560) @itemx @@ifnotinfo
texinfo.texi(,15561) @itemx @@ifnotplaintext
texinfo.texi(,15562) @itemx @@ifnottex
texinfo.texi(,15563) Begin a stretch of text that will be ignored in one output format but
texinfo.texi(,15564) not the others.  The text appears in the formats not specified:
texinfo.texi(,15565) @code{@@ifnothtml} text is omitted from html output, etc.  The exception
texinfo.texi(,15566) is @code{@@ifnotinfo} text, which is omitted from plain text output as
texinfo.texi(,15567) well as Info output.  Pair with @code{@@end ifnothtml} resp.@:
texinfo.texi(,15568) @code{@@end ifnotinfo} resp.@: @code{@@end ifnotplaintext} resp.@:
texinfo.texi(,15569) @code{@@end ifnottex}.  @xref{Conditionals}.
texinfo.texi(,15570) 
texinfo.texi(,15571) @item @@ifplaintext
texinfo.texi(,15572) Begin a stretch of text that appears only in the plain text output.
texinfo.texi(,15573) Pair with @code{@@end ifplaintext}.  @xref{Conditionals}.
texinfo.texi(,15574) 
texinfo.texi(,15575) @item @@ifset @var{flag}
texinfo.texi(,15576) If @var{flag} is set, the Texinfo formatting commands format text
texinfo.texi(,15577) between @code{@@ifset @var{flag}} and the following @code{@@end ifset}
texinfo.texi(,15578) command.
texinfo.texi(,15579) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
texinfo.texi(,15580) 
texinfo.texi(,15581) @item @@iftex
texinfo.texi(,15582) Begin a stretch of text that will not appear in the Info file, but
texinfo.texi(,15583) will be processed only by @TeX{}.  Pair with @code{@@end iftex}.
texinfo.texi(,15584) @xref{Conditionals, , Conditionally Visible Text}.@refill
texinfo.texi(,15585) 
texinfo.texi(,15586) @item @@ignore
texinfo.texi(,15587) Begin a stretch of text that will not appear in either the Info file
texinfo.texi(,15588) or the printed output.  Pair with @code{@@end ignore}.
texinfo.texi(,15589) @xref{Comments, , Comments and Ignored Text}.@refill
texinfo.texi(,15590) 
texinfo.texi(,15591) @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
texinfo.texi(,15592) Include graphics image in external @var{filename} scaled to the given
texinfo.texi(,15593) @var{width} and/or @var{height}, using @var{alt} text and looking for
texinfo.texi(,15594) @samp{@var{filename}.@var{ext}} in HTML.  @xref{Images}.
texinfo.texi(,15595) 
texinfo.texi(,15596) @item @@include @var{filename}
texinfo.texi(,15597) Incorporate the contents of the file @var{filename} into the Info file
texinfo.texi(,15598) or printed document.  @xref{Include Files}.@refill
texinfo.texi(,15599) 
texinfo.texi(,15600) @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
texinfo.texi(,15601) Make a cross reference to an Info file for which there is no printed
texinfo.texi(,15602) manual.  @xref{inforef, , Cross references using
texinfo.texi(,15603) @code{@@inforef}}.@refill
texinfo.texi(,15604) 
texinfo.texi(,15605) @item \input @var{macro-definitions-file}
texinfo.texi(,15606) Use the specified macro definitions file.  This command is used only
texinfo.texi(,15607) in the first line of a Texinfo file to cause @TeX{} to make use of the
texinfo.texi(,15608) @file{texinfo} macro definitions file.  The backslash in @code{\input}
texinfo.texi(,15609) is used instead of an @code{@@} because @TeX{} does not
texinfo.texi(,15610) recognize @code{@@} until after it has read the definitions file.
texinfo.texi(,15611) @xref{Texinfo File Header}.
texinfo.texi(,15612) 
texinfo.texi(,15613) @item @@item
texinfo.texi(,15614) Indicate the beginning of a marked paragraph for @code{@@itemize} and
texinfo.texi(,15615) @code{@@enumerate}; indicate the beginning of the text of a first column
texinfo.texi(,15616) entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
texinfo.texi(,15617) @xref{Lists and Tables}.@refill
texinfo.texi(,15618) 
texinfo.texi(,15619) @item @@itemize  @var{mark-generating-character-or-command}
texinfo.texi(,15620) Produce a sequence of indented paragraphs, with a mark inside the left
texinfo.texi(,15621) margin at the beginning of each paragraph.  Pair with @code{@@end
texinfo.texi(,15622) itemize}.  @xref{itemize, , @code{@@itemize}}.@refill
texinfo.texi(,15623) 
texinfo.texi(,15624) @item @@itemx
texinfo.texi(,15625) Like @code{@@item} but do not generate extra vertical space above the
texinfo.texi(,15626) item text.  @xref{itemx, , @code{@@itemx}}.@refill
texinfo.texi(,15627) 
texinfo.texi(,15628) @item @@kbd@{@var{keyboard-characters}@}
texinfo.texi(,15629) Indicate text that is characters of input to be typed by
texinfo.texi(,15630) users.  @xref{kbd, , @code{@@kbd}}.@refill
texinfo.texi(,15631) 
texinfo.texi(,15632) @item @@kbdinputstyle @var{style}
texinfo.texi(,15633) Specify when @code{@@kbd} should use a font distinct from @code{@@code}.
texinfo.texi(,15634) @xref{kbd, , @code{@@kbd}}.@refill
texinfo.texi(,15635) 
texinfo.texi(,15636) @item @@key@{@var{key-name}@}
texinfo.texi(,15637) Indicate a name for a key on a keyboard.
texinfo.texi(,15638) @xref{key, , @code{@@key}}.@refill
texinfo.texi(,15639) 
texinfo.texi(,15640) @item @@kindex @var{entry}
texinfo.texi(,15641) Add @var{entry} to the index of keys.
texinfo.texi(,15642) @xref{Index Entries, , Defining the Entries of an Index}.@refill
texinfo.texi(,15643) 
texinfo.texi(,15644) @item @@L@{@}
texinfo.texi(,15645) @itemx @@l@{@}
texinfo.texi(,15646) Generate the uppercase and lowercase Polish suppressed-L letters,
texinfo.texi(,15647) respectively: @L{}, @l{}.
texinfo.texi(,15648) 
texinfo.texi(,15649) @c Possibly this can be tossed now that we have macros.  --karl, 16sep96.
texinfo.texi(,15650) @c Yes, let's toss it, it's pretty weird.  --karl, 15jun97.
texinfo.texi(,15651) @c @item @@global@@let@var{new-command}=@var{existing-command}
texinfo.texi(,15652) @c Equate a new highlighting command with an existing one.  Only for
texinfo.texi(,15653) @c @TeX{}.  Write definition inside of @code{@@iftex} @dots{} @code{@@end
texinfo.texi(,15654) @c iftex}.  @xref{Customized Highlighting}.@refill
texinfo.texi(,15655) 
texinfo.texi(,15656) @item @@lisp
texinfo.texi(,15657) Begin an example of Lisp code.  Indent text, do not fill, and select
texinfo.texi(,15658) fixed-width font.  Pair with @code{@@end lisp}.  @xref{lisp, , @code{@@lisp}}.
texinfo.texi(,15659) 
texinfo.texi(,15660) @item @@lowersections
texinfo.texi(,15661) Change subsequent chapters to sections, sections to subsections, and so
texinfo.texi(,15662) on. @xref{Raise/lower sections, , @code{@@raisesections} and
texinfo.texi(,15663) @code{@@lowersections}}.@refill
texinfo.texi(,15664) 
texinfo.texi(,15665) @item @@macro @var{macroname} @{@var{params}@}
texinfo.texi(,15666) Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
texinfo.texi(,15667) Only supported by @code{makeinfo} and @code{texi2dvi}.  @xref{Defining
texinfo.texi(,15668) Macros}.
texinfo.texi(,15669) 
texinfo.texi(,15670) @item @@majorheading @var{title}
texinfo.texi(,15671) Print a chapter-like heading in the text, but not in the table of
texinfo.texi(,15672) contents of a printed manual.  Generate more vertical whitespace before
texinfo.texi(,15673) the heading than the @code{@@chapheading} command.  In Info, the chapter
texinfo.texi(,15674) heading line is underlined with asterisks.  @xref{majorheading &
texinfo.texi(,15675) chapheading, , @code{@@majorheading} and @code{@@chapheading}}.@refill
texinfo.texi(,15676) 
texinfo.texi(,15677) @item @@math@{@var{mathematical-expression}@}
texinfo.texi(,15678) Format a mathematical expression.
texinfo.texi(,15679) @xref{math, , @code{@@math}: Inserting Mathematical Expressions}.
texinfo.texi(,15680) 
texinfo.texi(,15681) @item @@menu
texinfo.texi(,15682) Mark the beginning of a menu of nodes in Info.  No effect in a printed
texinfo.texi(,15683) manual.  Pair with @code{@@end menu}.  @xref{Menus}.@refill
texinfo.texi(,15684) 
texinfo.texi(,15685) @item @@minus@{@}
texinfo.texi(,15686) Generate a minus sign, `@minus{}'.  @xref{minus, , @code{@@minus}}.@refill
texinfo.texi(,15687) 
texinfo.texi(,15688) @item @@multitable @var{column-width-spec}
texinfo.texi(,15689) Begin a multi-column table.  Pair with @code{@@end multitable}.
texinfo.texi(,15690) @xref{Multitable Column Widths}.
texinfo.texi(,15691) 
texinfo.texi(,15692) @item @@need @var{n}
texinfo.texi(,15693) Start a new page in a printed manual if fewer than @var{n} mils
texinfo.texi(,15694) (thousandths of an inch) remain on the current page.  @xref{need, ,
texinfo.texi(,15695) @code{@@need}}.@refill
texinfo.texi(,15696) 
texinfo.texi(,15697) @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
texinfo.texi(,15698) Define the beginning of a new node in Info, and serve as a locator for
texinfo.texi(,15699) references for @TeX{}.  @xref{node, , @code{@@node}}.@refill
texinfo.texi(,15700) 
texinfo.texi(,15701) @item @@noindent
texinfo.texi(,15702) Prevent text from being indented as if it were a new paragraph.
texinfo.texi(,15703) @xref{noindent, , @code{@@noindent}}.@refill
texinfo.texi(,15704) 
texinfo.texi(,15705) @item @@novalidate
texinfo.texi(,15706) Suppress validation of node references, omit creation of auxiliary files
texinfo.texi(,15707) with @TeX{}.  Use before @code{@@setfilename}.  @xref{Pointer Validation}.
texinfo.texi(,15708) 
texinfo.texi(,15709) @item @@O@{@}
texinfo.texi(,15710) @itemx @@o@{@}
texinfo.texi(,15711) Generate the uppercase and lowercase O-with-slash letters, respectively:
texinfo.texi(,15712) @O{}, @o{}.
texinfo.texi(,15713) 
texinfo.texi(,15714) @item  @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
texinfo.texi(,15715) @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
texinfo.texi(,15716) Specify page footings resp.@: headings for odd-numbered (right-hand)
texinfo.texi(,15717) pages.  @xref{Custom Headings, ,
texinfo.texi(,15718) How to Make Your Own Headings}.@refill
texinfo.texi(,15719) 
texinfo.texi(,15720) @item @@OE@{@}
texinfo.texi(,15721) @itemx @@oe@{@}
texinfo.texi(,15722) Generate the uppercase and lowercase OE ligatures, respectively:
texinfo.texi(,15723) @OE{}, @oe{}.  @xref{Inserting Accents}.
texinfo.texi(,15724) 
texinfo.texi(,15725) @item @@option@{@var{option-name}@}
texinfo.texi(,15726) Indicate a command-line option, such as @option{-l} or @option{--help}.
texinfo.texi(,15727) @xref{option,, @code{@@option}}.
texinfo.texi(,15728) 
texinfo.texi(,15729) @item @@page
texinfo.texi(,15730) Start a new page in a printed manual.  No effect in Info.
texinfo.texi(,15731) @xref{page, , @code{@@page}}.@refill
texinfo.texi(,15732) 
texinfo.texi(,15733) @item @@pagesizes [@var{width}][, @var{height}]
texinfo.texi(,15734) Change page dimensions.  @xref{pagesizes}.
texinfo.texi(,15735) 
texinfo.texi(,15736) @item @@paragraphindent @var{indent}
texinfo.texi(,15737) Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
texinfo.texi(,15738) source file indentation if @var{indent} is @code{asis}.
texinfo.texi(,15739) @xref{paragraphindent,, Paragraph Indenting}.
texinfo.texi(,15740) 
texinfo.texi(,15741) @item @@pindex @var{entry}
texinfo.texi(,15742) Add @var{entry} to the index of programs.  @xref{Index Entries, , Defining
texinfo.texi(,15743) the Entries of an Index}.@refill
texinfo.texi(,15744) 
texinfo.texi(,15745) @item @@point@{@}
texinfo.texi(,15746) Indicate the position of point in a buffer to the reader with a
texinfo.texi(,15747) glyph: @samp{@point{}}.  @xref{Point Glyph, , Indicating
texinfo.texi(,15748) Point in a Buffer}.@refill
texinfo.texi(,15749) 
texinfo.texi(,15750) @item @@pounds@{@}
texinfo.texi(,15751) Generate the pounds sterling currency sign.
texinfo.texi(,15752) @xref{pounds,,@code{@@pounds@{@}}}.
texinfo.texi(,15753) 
texinfo.texi(,15754) @item @@print@{@}
texinfo.texi(,15755) Indicate printed output to the reader with a glyph:
texinfo.texi(,15756) @samp{@print{}}.  @xref{Print Glyph}.@refill
texinfo.texi(,15757) 
texinfo.texi(,15758) @item @@printindex @var{index-name}
texinfo.texi(,15759) Print an alphabetized two-column index in a printed manual or generate
texinfo.texi(,15760) an alphabetized menu of index entries for Info.  @xref{Printing
texinfo.texi(,15761) Indices & Menus}.@refill
texinfo.texi(,15762) 
texinfo.texi(,15763) @item @@pxref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
texinfo.texi(,15764) Make a reference that starts with a lower case `see' in a printed
texinfo.texi(,15765) manual.  Use within parentheses only.  Do not follow command with a
texinfo.texi(,15766) punctuation mark---the Info formatting commands automatically insert
texinfo.texi(,15767) terminating punctuation as needed.  Only the first argument is mandatory.
texinfo.texi(,15768) @xref{pxref, , @code{@@pxref}}.@refill
texinfo.texi(,15769) 
texinfo.texi(,15770) @item @@questiondown@{@}
texinfo.texi(,15771) Generate an upside-down question mark.  @xref{Inserting Accents}.
texinfo.texi(,15772) 
texinfo.texi(,15773) @item @@quotation
texinfo.texi(,15774) Narrow the margins to indicate text that is quoted from another real
texinfo.texi(,15775) or imaginary work.  Write command on a line of its own.  Pair with
texinfo.texi(,15776) @code{@@end quotation}.  @xref{quotation, ,
texinfo.texi(,15777) @code{@@quotation}}.@refill
texinfo.texi(,15778) 
texinfo.texi(,15779) @item @@r@{@var{text}@}
texinfo.texi(,15780) Print @var{text} in @r{roman} font.  No effect in Info.
texinfo.texi(,15781) @xref{Fonts}.@refill
texinfo.texi(,15782) 
texinfo.texi(,15783) @item @@raisesections
texinfo.texi(,15784) Change subsequent sections to chapters, subsections to sections, and so
texinfo.texi(,15785) on.  @xref{Raise/lower sections, , @code{@@raisesections} and
texinfo.texi(,15786) @code{@@lowersections}}.@refill
texinfo.texi(,15787) 
texinfo.texi(,15788) @item @@ref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
texinfo.texi(,15789) Make a reference.  In a printed manual, the reference does not start
texinfo.texi(,15790) with a `See'.  Follow command with a punctuation mark.  Only the first
texinfo.texi(,15791) argument is mandatory.  @xref{ref, , @code{@@ref}}.@refill
texinfo.texi(,15792) 
texinfo.texi(,15793) @item @@refill
texinfo.texi(,15794) In Info, refill and indent the paragraph after all the other processing
texinfo.texi(,15795) has been done.  No effect on @TeX{}, which always refills.  This command
texinfo.texi(,15796) is no longer needed, since all formatters now automatically refill.
texinfo.texi(,15797) @xref{Refilling Paragraphs}.@refill
texinfo.texi(,15798) 
texinfo.texi(,15799) @item @@result@{@}
texinfo.texi(,15800) Indicate the result of an expression to the reader with a special
texinfo.texi(,15801) glyph: @samp{@result{}}.  @xref{result, , @code{@@result}}.@refill
texinfo.texi(,15802) 
texinfo.texi(,15803) @item @@ringaccent@{@var{c}@}
texinfo.texi(,15804) Generate a ring accent over the next character, as in @ringaccent{o}.
texinfo.texi(,15805) @xref{Inserting Accents}.
texinfo.texi(,15806) 
texinfo.texi(,15807) @item @@samp@{@var{text}@}
texinfo.texi(,15808) Highlight @var{text} that is a literal example of a sequence of
texinfo.texi(,15809) characters.  Used for single characters, for statements, and often for
texinfo.texi(,15810) entire shell commands.  @xref{samp, , @code{@@samp}}.@refill
texinfo.texi(,15811) 
texinfo.texi(,15812) @item @@sc@{@var{text}@}
texinfo.texi(,15813) Set @var{text} in a printed output in @sc{the small caps font} and
texinfo.texi(,15814) set text in the Info file in uppercase letters.
texinfo.texi(,15815) @xref{Smallcaps}.@refill
texinfo.texi(,15816) 
texinfo.texi(,15817) @item @@section @var{title}
texinfo.texi(,15818) Begin a section within a chapter.  In a printed manual, the section
texinfo.texi(,15819) title is numbered and appears in the table of contents.  In Info, the
texinfo.texi(,15820) title is underlined with equal signs.  @xref{section, ,
texinfo.texi(,15821) @code{@@section}}.@refill
texinfo.texi(,15822) 
texinfo.texi(,15823) @item @@set @var{flag} [@var{string}]
texinfo.texi(,15824) Make @var{flag} active, causing the Texinfo formatting commands to
texinfo.texi(,15825) format text between subsequent pairs of @code{@@ifset @var{flag}} and
texinfo.texi(,15826) @code{@@end ifset} commands.  Optionally, set value of @var{flag} to
texinfo.texi(,15827) @var{string}.
texinfo.texi(,15828) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.
texinfo.texi(,15829) 
texinfo.texi(,15830) @item @@setchapternewpage @var{on-off-odd}
texinfo.texi(,15831) Specify whether chapters start on new pages, and if so, whether on
texinfo.texi(,15832) odd-numbered (right-hand) new pages.  @xref{setchapternewpage, ,
texinfo.texi(,15833) @code{@@setchapternewpage}}.
texinfo.texi(,15834) 
texinfo.texi(,15835) @item @@setcontentsaftertitlepage
texinfo.texi(,15836) Put the table of contents after the @samp{@@end titlepage} even if the
texinfo.texi(,15837) @code{@@contents} command is not there.  @xref{Contents}.
texinfo.texi(,15838) 
texinfo.texi(,15839) @item @@setfilename @var{info-file-name}
texinfo.texi(,15840) Provide a name to be used by the Info file.  This command is essential
texinfo.texi(,15841) for @TeX{} formatting as well, even though it produces no output.
texinfo.texi(,15842) @xref{setfilename, , @code{@@setfilename}}.
texinfo.texi(,15843) 
texinfo.texi(,15844) @item @@setshortcontentsaftertitlepage
texinfo.texi(,15845) Place the short table of contents after the @samp{@@end titlepage}
texinfo.texi(,15846) command even if the @code{@@shortcontents} command is not there.
texinfo.texi(,15847) @xref{Contents}.
texinfo.texi(,15848) 
texinfo.texi(,15849) @item @@settitle @var{title}
texinfo.texi(,15850) Provide a title for page headers in a printed manual, and the default
texinfo.texi(,15851) document description for HTML @samp{<head>}.
texinfo.texi(,15852) @xref{settitle, , @code{@@settitle}}.@refill
texinfo.texi(,15853) 
texinfo.texi(,15854) @item @@shortcontents
texinfo.texi(,15855) Print a short table of contents.  Not relevant to Info, which uses
texinfo.texi(,15856) menus rather than tables of contents.  A synonym for
texinfo.texi(,15857) @code{@@summarycontents}.  @xref{Contents, , Generating a Table of
texinfo.texi(,15858) Contents}.@refill
texinfo.texi(,15859) 
texinfo.texi(,15860) @item @@shorttitlepage @var{title}
texinfo.texi(,15861) Generate a minimal title page.  @xref{titlepage,,@code{@@titlepage}}.
texinfo.texi(,15862) 
texinfo.texi(,15863) @item @@smallbook
texinfo.texi(,15864) Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
texinfo.texi(,15865) rather than the regular 8.5 by 11 inch format.  @xref{smallbook, ,
texinfo.texi(,15866) Printing Small Books}.  Also, see @ref{small}.
texinfo.texi(,15867) 
texinfo.texi(,15868) @item @@smalldisplay
texinfo.texi(,15869) Begin a kind of example.  Like @code{@@smallexample} (narrow margins, no
texinfo.texi(,15870) filling), but do not select the fixed-width font.  Pair with @code{@@end
texinfo.texi(,15871) smalldisplay}.  @xref{small}.
texinfo.texi(,15872) 
texinfo.texi(,15873) @item @@smallexample
texinfo.texi(,15874) Indent text to indicate an example.  Do not fill, select fixed-width
texinfo.texi(,15875) font, narrow the margins.  In printed manuals, print text in a smaller
texinfo.texi(,15876) font than with @code{@@example}.  Pair with @code{@@end smallexample}.
texinfo.texi(,15877) @xref{small}.
texinfo.texi(,15878) 
texinfo.texi(,15879) @item @@smallformat
texinfo.texi(,15880) Begin a kind of example.  Like @code{@@smalldisplay}, but do not narrow
texinfo.texi(,15881) the margins.  Pair with @code{@@end smallformat}.  @xref{small}.
texinfo.texi(,15882) 
texinfo.texi(,15883) @item @@smalllisp
texinfo.texi(,15884) Begin an example of Lisp code.  Same as @code{@@smallexample}.  Pair
texinfo.texi(,15885) with @code{@@end smalllisp}.  @xref{small}.
texinfo.texi(,15886) 
texinfo.texi(,15887) @item @@sp @var{n}
texinfo.texi(,15888) Skip @var{n} blank lines.  @xref{sp, , @code{@@sp}}.@refill
texinfo.texi(,15889) 
texinfo.texi(,15890) @item @@ss@{@}
texinfo.texi(,15891) Generate the German sharp-S es-zet letter, @ss{}.  @xref{Inserting Accents}.
texinfo.texi(,15892) 
texinfo.texi(,15893) @item @@strong @{@var{text}@}
texinfo.texi(,15894) Emphasize @var{text} by typesetting it in a @strong{bold} font for the
texinfo.texi(,15895) printed manual and by surrounding it with asterisks for Info.
texinfo.texi(,15896) @xref{emph & strong, , Emphasizing Text}.@refill
texinfo.texi(,15897) 
texinfo.texi(,15898) @item @@subheading @var{title}
texinfo.texi(,15899) Print an unnumbered subsection-like heading in the text, but not in
texinfo.texi(,15900) the table of contents of a printed manual.  In Info, the title is
texinfo.texi(,15901) underlined with hyphens.  @xref{unnumberedsubsec appendixsubsec
texinfo.texi(,15902) subheading, , @code{@@unnumberedsubsec} @code{@@appendixsubsec}
texinfo.texi(,15903) @code{@@subheading}}.@refill
texinfo.texi(,15904) 
texinfo.texi(,15905) @item @@subsection @var{title}
texinfo.texi(,15906) Begin a subsection within a section.  In a printed manual, the
texinfo.texi(,15907) subsection title is numbered and appears in the table of contents.  In
texinfo.texi(,15908) Info, the title is underlined with hyphens.  @xref{subsection, ,
texinfo.texi(,15909) @code{@@subsection}}.@refill
texinfo.texi(,15910) 
texinfo.texi(,15911) @item @@subsubheading @var{title}
texinfo.texi(,15912) Print an unnumbered subsubsection-like heading in the text, but not in
texinfo.texi(,15913) the table of contents of a printed manual.  In Info, the title is
texinfo.texi(,15914) underlined with periods.  @xref{subsubsection, , The `subsub'
texinfo.texi(,15915) Commands}.@refill
texinfo.texi(,15916) 
texinfo.texi(,15917) @item @@subsubsection @var{title}
texinfo.texi(,15918) Begin a subsubsection within a subsection.  In a printed manual,
texinfo.texi(,15919) the subsubsection title is numbered and appears in the table of
texinfo.texi(,15920) contents.  In Info, the title is underlined with periods.
texinfo.texi(,15921) @xref{subsubsection, , The `subsub' Commands}.@refill
texinfo.texi(,15922) 
texinfo.texi(,15923) @item @@subtitle @var{title}
texinfo.texi(,15924) In a printed manual, set a subtitle in a normal sized font flush to
texinfo.texi(,15925) the right-hand side of the page.  Not relevant to Info, which does not
texinfo.texi(,15926) have title pages.  @xref{title subtitle author, , @code{@@title}
texinfo.texi(,15927) @code{@@subtitle} and @code{@@author} Commands}.@refill
texinfo.texi(,15928) 
texinfo.texi(,15929) @item @@summarycontents
texinfo.texi(,15930) Print a short table of contents.  Not relevant to Info, which uses
texinfo.texi(,15931) menus rather than tables of contents.  A synonym for
texinfo.texi(,15932) @code{@@shortcontents}.  @xref{Contents, , Generating a Table of
texinfo.texi(,15933) Contents}.@refill
texinfo.texi(,15934) 
texinfo.texi(,15935) @item @@syncodeindex @var{from-index} @var{into-index}
texinfo.texi(,15936) Merge the index named in the first argument into the index named in
texinfo.texi(,15937) the second argument, printing the entries from the first index in
texinfo.texi(,15938) @code{@@code} font.  @xref{Combining Indices}.@refill
texinfo.texi(,15939) 
texinfo.texi(,15940) @item @@synindex @var{from-index} @var{into-index}
texinfo.texi(,15941) Merge the index named in the first argument into the index named in
texinfo.texi(,15942) the second argument.  Do not change the font of @var{from-index}
texinfo.texi(,15943) entries.  @xref{Combining Indices}.@refill
texinfo.texi(,15944) 
texinfo.texi(,15945) @item @@t@{@var{text}@}
texinfo.texi(,15946) Print @var{text} in a @t{fixed-width}, typewriter-like font.
texinfo.texi(,15947) No effect in Info.  @xref{Fonts}.@refill
texinfo.texi(,15948) 
texinfo.texi(,15949) @item @@tab
texinfo.texi(,15950) Separate columns in a multitable.  @xref{Multitable Rows}.
texinfo.texi(,15951) 
texinfo.texi(,15952) @item @@table @var{formatting-command}
texinfo.texi(,15953) Begin a two-column table, using @code{@@item} for each entry.  Write
texinfo.texi(,15954) each first column entry on the same line as @code{@@item}.  First
texinfo.texi(,15955) column entries are printed in the font resulting from
texinfo.texi(,15956) @var{formatting-command}.  Pair with @code{@@end table}.
texinfo.texi(,15957) @xref{Two-column Tables, , Making a Two-column Table}.
texinfo.texi(,15958) Also see @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}},
texinfo.texi(,15959) and @ref{itemx, , @code{@@itemx}}.@refill
texinfo.texi(,15960) 
texinfo.texi(,15961) @item @@TeX@{@}
texinfo.texi(,15962) Insert the logo @TeX{}.  @xref{TeX and copyright, , Inserting @TeX{}
texinfo.texi(,15963) and @copyright{}}.@refill
texinfo.texi(,15964) 
texinfo.texi(,15965) @item @@tex
texinfo.texi(,15966) Enter @TeX{} completely.  Pair with @code{@@end tex}.  @xref{Raw
texinfo.texi(,15967) Formatter Commands}.
texinfo.texi(,15968) 
texinfo.texi(,15969) @item @@thischapter
texinfo.texi(,15970) @itemx @@thischaptername
texinfo.texi(,15971) @itemx @@thisfile
texinfo.texi(,15972) @itemx @@thispage
texinfo.texi(,15973) @itemx @@thistitle
texinfo.texi(,15974) Only allowed in a heading or footing.  Stands for the number and name of
texinfo.texi(,15975) the current chapter (in the format `Chapter 1: Title'), the chapter name
texinfo.texi(,15976) only, the filename, the current page number, and the title of the
texinfo.texi(,15977) document, respectively.  @xref{Custom Headings, , How to Make Your Own
texinfo.texi(,15978) Headings}.@refill
texinfo.texi(,15979) 
texinfo.texi(,15980) @item @@tieaccent@{@var{cc}@}
texinfo.texi(,15981) Generate a tie-after accent over the next two characters @var{cc}, as in
texinfo.texi(,15982) `@tieaccent{oo}'.  @xref{Inserting Accents}.
texinfo.texi(,15983) 
texinfo.texi(,15984) @item @@tindex @var{entry}
texinfo.texi(,15985) Add @var{entry} to the index of data types.  @xref{Index Entries, ,
texinfo.texi(,15986) Defining the Entries of an Index}.@refill
texinfo.texi(,15987) 
texinfo.texi(,15988) @item @@title @var{title}
texinfo.texi(,15989) In a printed manual, set a title flush to the left-hand side of the
texinfo.texi(,15990) page in a larger than normal font and underline it with a black rule.
texinfo.texi(,15991) Not relevant to Info, which does not have title pages.  @xref{title
texinfo.texi(,15992) subtitle author, , The @code{@@title} @code{@@subtitle} and
texinfo.texi(,15993) @code{@@author} Commands}.@refill
texinfo.texi(,15994) 
texinfo.texi(,15995) @item @@titlefont@{@var{text}@}
texinfo.texi(,15996) In a printed manual, print @var{text} in a larger than normal font.
texinfo.texi(,15997) Not relevant to Info, which does not have title pages.
texinfo.texi(,15998) @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
texinfo.texi(,15999) and @code{@@sp} Commands}.@refill
texinfo.texi(,16000) 
texinfo.texi(,16001) @item @@titlepage
texinfo.texi(,16002) Indicate to Texinfo the beginning of the title page.  Write command on
texinfo.texi(,16003) a line of its own.  Pair with @code{@@end titlepage}.  Nothing between
texinfo.texi(,16004) @code{@@titlepage} and @code{@@end titlepage} appears in Info.
texinfo.texi(,16005) @xref{titlepage, , @code{@@titlepage}}.@refill
texinfo.texi(,16006) 
texinfo.texi(,16007) @item @@today@{@}
texinfo.texi(,16008) Insert the current date, in `1 Jan 1900' style.  @xref{Custom
texinfo.texi(,16009) Headings, , How to Make Your Own Headings}.@refill
texinfo.texi(,16010) 
texinfo.texi(,16011) @item @@top @var{title}
texinfo.texi(,16012) In a Texinfo file to be formatted with @code{makeinfo}, identify the
texinfo.texi(,16013) topmost @code{@@node} in the file, which must be written on the line
texinfo.texi(,16014) immediately preceding the @code{@@top} command.  Used for
texinfo.texi(,16015) @code{makeinfo}'s node pointer insertion feature.  The title is
texinfo.texi(,16016) underlined with asterisks.  Both the @code{@@node} line and the @code{@@top}
texinfo.texi(,16017) line normally should be enclosed by @code{@@ifnottex} and @code{@@end
texinfo.texi(,16018) ifnottex}.  In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
texinfo.texi(,16019) command is merely a synonym for @code{@@unnumbered}.  @xref{makeinfo
texinfo.texi(,16020) Pointer Creation, , Creating Pointers with @code{makeinfo}}.
texinfo.texi(,16021) 
texinfo.texi(,16022) @item @@u@{@var{c}@}
texinfo.texi(,16023) @itemx @@ubaraccent@{@var{c}@}
texinfo.texi(,16024) @itemx @@udotaccent@{@var{c}@}
texinfo.texi(,16025) Generate a breve, underbar, or underdot accent, respectively, over or
texinfo.texi(,16026) under the character @var{c}, as in @u{o}, @ubaraccent{o},
texinfo.texi(,16027) @udotaccent{o}.  @xref{Inserting Accents}.
texinfo.texi(,16028) 
texinfo.texi(,16029) @item @@unnumbered @var{title}
texinfo.texi(,16030) In a printed manual, begin a chapter that appears without chapter
texinfo.texi(,16031) numbers of any kind.  The title appears in the table of contents of a
texinfo.texi(,16032) printed manual.  In Info, the title is underlined with asterisks.
texinfo.texi(,16033) @xref{unnumbered & appendix, , @code{@@unnumbered} and
texinfo.texi(,16034) @code{@@appendix}}.@refill
texinfo.texi(,16035) 
texinfo.texi(,16036) @item @@unnumberedsec @var{title}
texinfo.texi(,16037) In a printed manual, begin a section that appears without section
texinfo.texi(,16038) numbers of any kind.  The title appears in the table of contents of a
texinfo.texi(,16039) printed manual.  In Info, the title is underlined with equal signs.
texinfo.texi(,16040) @xref{unnumberedsec appendixsec heading, , Section Commands}.@refill
texinfo.texi(,16041) 
texinfo.texi(,16042) @item @@unnumberedsubsec @var{title}
texinfo.texi(,16043) In a printed manual, begin an unnumbered subsection within a
texinfo.texi(,16044) chapter.  The title appears in the table of contents of a printed
texinfo.texi(,16045) manual.  In Info, the title is underlined with hyphens.
texinfo.texi(,16046) @xref{unnumberedsubsec appendixsubsec subheading, ,
texinfo.texi(,16047) @code{@@unnumberedsubsec} @code{@@appendixsubsec}
texinfo.texi(,16048) @code{@@subheading}}.@refill
texinfo.texi(,16049) 
texinfo.texi(,16050) @item @@unnumberedsubsubsec @var{title}
texinfo.texi(,16051) In a printed manual, begin an unnumbered subsubsection within a
texinfo.texi(,16052) chapter.  The title appears in the table of contents of a printed
texinfo.texi(,16053) manual.  In Info, the title is underlined with periods.
texinfo.texi(,16054) @xref{subsubsection, , The `subsub' Commands}.@refill
texinfo.texi(,16055) 
texinfo.texi(,16056) @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
texinfo.texi(,16057) Define a cross reference to an external uniform resource locator for the
texinfo.texi(,16058) World Wide Web.  @xref{uref, , @code{@@uref}}.@refill
texinfo.texi(,16059) 
texinfo.texi(,16060) @item @@url@{@var{url}@}
texinfo.texi(,16061) Indicate text that is a uniform resource locator for the World Wide
texinfo.texi(,16062) Web.  @xref{url, , @code{@@url}}.@refill
texinfo.texi(,16063) 
texinfo.texi(,16064) @item @@v@{@var{c}@}
texinfo.texi(,16065) Generate check accent over the character @var{c}, as in @v{o}.
texinfo.texi(,16066) @xref{Inserting Accents}.
texinfo.texi(,16067) 
texinfo.texi(,16068) @item @@value@{@var{flag}@}
texinfo.texi(,16069) Replace @var{flag} with the value to which it is set by @code{@@set
texinfo.texi(,16070) @var{flag}}.
texinfo.texi(,16071) @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
texinfo.texi(,16072) 
texinfo.texi(,16073) @item @@var@{@var{metasyntactic-variable}@}
texinfo.texi(,16074) Highlight a metasyntactic variable, which is something that stands for
texinfo.texi(,16075) another piece of text.  @xref{var, , Indicating Metasyntactic
texinfo.texi(,16076) Variables}.@refill
texinfo.texi(,16077) 
texinfo.texi(,16078) @item @@verb@{@var{delim} @var{literal} @var{delim}@}
texinfo.texi(,16079) Output @var{literal}, delimited by the single character @var{delim},
texinfo.texi(,16080) exactly as is (in the fixed-width font), including any whitespace or
texinfo.texi(,16081) Texinfo special characters.  @xref{verb,,@code{verb}}.
texinfo.texi(,16082) 
texinfo.texi(,16083) @item @@verbatim
texinfo.texi(,16084) Output the text of the environment exactly as is (in the fixed-width
texinfo.texi(,16085) font).  Pair with @code{@@end verbatim}.  @xref{verbatim,,@code{verbatim}}.
texinfo.texi(,16086) 
texinfo.texi(,16087) @item @@verbatiminclude @var{filename}
texinfo.texi(,16088) Output the contents of @var{filename} exactly as is (in the fixed-width font).
texinfo.texi(,16089) @xref{verbatiminclude,,@code{verbatiminclude}}.
texinfo.texi(,16090) 
texinfo.texi(,16091) @item @@vindex @var{entry}
texinfo.texi(,16092) Add @var{entry} to the index of variables.  @xref{Index Entries, ,
texinfo.texi(,16093) Defining the Entries of an Index}.@refill
texinfo.texi(,16094) 
texinfo.texi(,16095) @item @@vskip @var{amount}
texinfo.texi(,16096) In a printed manual, insert whitespace so as to push text on the
texinfo.texi(,16097) remainder of the page towards the bottom of the page.  Used in
texinfo.texi(,16098) formatting the copyright page with the argument @samp{0pt plus
texinfo.texi(,16099) 1filll}.  (Note spelling of @samp{filll}.)  @code{@@vskip} may be used
texinfo.texi(,16100) only in contexts ignored for Info.  @xref{Copyright}.
texinfo.texi(,16101) 
texinfo.texi(,16102) @item @@vtable @var{formatting-command}
texinfo.texi(,16103) Begin a two-column table, using @code{@@item} for each entry.
texinfo.texi(,16104) Automatically enter each of the items in the first column into the
texinfo.texi(,16105) index of variables.  Pair with @code{@@end vtable}.  The same as
texinfo.texi(,16106) @code{@@table}, except for indexing.  @xref{ftable vtable, ,
texinfo.texi(,16107) @code{@@ftable} and @code{@@vtable}}.@refill
texinfo.texi(,16108) 
texinfo.texi(,16109) @item @@w@{@var{text}@}
texinfo.texi(,16110) Prevent @var{text} from being split across two lines.  Do not end a
texinfo.texi(,16111) paragraph that uses @code{@@w} with an @code{@@refill} command.
texinfo.texi(,16112) @xref{w, , @code{@@w}}.@refill
texinfo.texi(,16113) 
texinfo.texi(,16114) @item @@xref@{@var{node-name}, [@var{entry}], [@var{topic-or-title}], [@var{info-file}], [@var{manual}]@}
texinfo.texi(,16115) Make a reference that starts with `See' in a printed manual.  Follow
texinfo.texi(,16116) command with a punctuation mark.  Only the first argument is
texinfo.texi(,16117) mandatory.  @xref{xref, , @code{@@xref}}.@refill
texinfo.texi(,16118) @end table
texinfo.texi(,16119) 
texinfo.texi(,16120) 
texinfo.texi(,16121) @node Tips
texinfo.texi(,16122) @appendix Tips and Hints
texinfo.texi(,16123) 
texinfo.texi(,16124) Here are some tips for writing Texinfo documentation:@refill
texinfo.texi(,16125) 
texinfo.texi(,16126) @cindex Tips
texinfo.texi(,16127) @cindex Usage tips
texinfo.texi(,16128) @cindex Hints
texinfo.texi(,16129) @itemize @bullet
texinfo.texi(,16130) @item
texinfo.texi(,16131) Write in the present tense, not in the past or the future.
texinfo.texi(,16132) 
texinfo.texi(,16133) @item
texinfo.texi(,16134) Write actively!  For example, write ``We recommend that @dots{}'' rather
texinfo.texi(,16135) than ``It is recommended that @dots{}''.
texinfo.texi(,16136) 
texinfo.texi(,16137) @item
texinfo.texi(,16138) Use 70 or 72 as your fill column.  Longer lines are hard to read.
texinfo.texi(,16139) 
texinfo.texi(,16140) @item
texinfo.texi(,16141) Include a copyright notice and copying permissions.
texinfo.texi(,16142) @end itemize
texinfo.texi(,16143) 
texinfo.texi(,16144) @subsubheading Index, Index, Index!
texinfo.texi(,16145) 
texinfo.texi(,16146) Write many index entries, in different ways.
texinfo.texi(,16147) Readers like indices; they are helpful and convenient.
texinfo.texi(,16148) 
texinfo.texi(,16149) Although it is easiest to write index entries as you write the body of
texinfo.texi(,16150) the text, some people prefer to write entries afterwards.  In either
texinfo.texi(,16151) case, write an entry before the paragraph to which it applies.  This
texinfo.texi(,16152) way, an index entry points to the first page of a paragraph that is
texinfo.texi(,16153) split across pages.
texinfo.texi(,16154) 
texinfo.texi(,16155) Here are more hints we have found valuable:
texinfo.texi(,16156) 
texinfo.texi(,16157) @itemize @bullet
texinfo.texi(,16158) @item
texinfo.texi(,16159) Write each index entry differently, so each entry refers to a different
texinfo.texi(,16160) place in the document.
texinfo.texi(,16161) 
texinfo.texi(,16162) @item
texinfo.texi(,16163) Write index entries only where a topic is discussed significantly.  For
texinfo.texi(,16164) example, it is not useful to index ``debugging information'' in a
texinfo.texi(,16165) chapter on reporting bugs.  Someone who wants to know about debugging
texinfo.texi(,16166) information will certainly not find it in that chapter.
texinfo.texi(,16167) 
texinfo.texi(,16168) @item
texinfo.texi(,16169) Consistently capitalize the first word of every concept index entry,
texinfo.texi(,16170) or else consistently use lower case.  Terse entries often call for
texinfo.texi(,16171) lower case; longer entries for capitalization.  Whichever case
texinfo.texi(,16172) convention you use, please use one or the other consistently!  Mixing
texinfo.texi(,16173) the two styles looks bad.
texinfo.texi(,16174) 
texinfo.texi(,16175) @item
texinfo.texi(,16176) Always capitalize or use upper case for those words in an index for
texinfo.texi(,16177) which this is proper, such as names of countries or acronyms.  Always
texinfo.texi(,16178) use the appropriate case for case-sensitive names, such as those in C or
texinfo.texi(,16179) Lisp.
texinfo.texi(,16180) 
texinfo.texi(,16181) @item
texinfo.texi(,16182) Write the indexing commands that refer to a whole section immediately
texinfo.texi(,16183) after the section command, and write the indexing commands that refer to
texinfo.texi(,16184) a paragraph before that paragraph.
texinfo.texi(,16185) 
texinfo.texi(,16186) In the example that follows, a blank line comes after the index
texinfo.texi(,16187) entry for ``Leaping'':
texinfo.texi(,16188) 
texinfo.texi(,16189) @example
texinfo.texi(,16190) @group
texinfo.texi(,16191) @@section The Dog and the Fox
texinfo.texi(,16192) @@cindex Jumping, in general
texinfo.texi(,16193) @@cindex Leaping
texinfo.texi(,16194) 
texinfo.texi(,16195) @@cindex Dog, lazy, jumped over
texinfo.texi(,16196) @@cindex Lazy dog jumped over
texinfo.texi(,16197) @@cindex Fox, jumps over dog
texinfo.texi(,16198) @@cindex Quick fox jumps over dog
texinfo.texi(,16199) The quick brown fox jumps over the lazy dog.
texinfo.texi(,16200) @end group
texinfo.texi(,16201) @end example
texinfo.texi(,16202) 
texinfo.texi(,16203) @noindent
texinfo.texi(,16204) (Note that the example shows entries for the same concept that are
texinfo.texi(,16205) written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
texinfo.texi(,16206) readers can look up the concept in different ways.)
texinfo.texi(,16207) @end itemize
texinfo.texi(,16208) 
texinfo.texi(,16209) @subsubheading Blank Lines
texinfo.texi(,16210) 
texinfo.texi(,16211) @itemize @bullet
texinfo.texi(,16212) @item
texinfo.texi(,16213) Insert a blank line between a sectioning command and the first following
texinfo.texi(,16214) sentence or paragraph, or between the indexing commands associated with
texinfo.texi(,16215) the sectioning command and the first following sentence or paragraph, as
texinfo.texi(,16216) shown in the tip on indexing.  Otherwise, a formatter may fold title and
texinfo.texi(,16217) paragraph together.
texinfo.texi(,16218) 
texinfo.texi(,16219) @item
texinfo.texi(,16220) Always insert a blank line before an @code{@@table} command and after an
texinfo.texi(,16221) @code{@@end table} command; but never insert a blank line after an
texinfo.texi(,16222) @code{@@table} command or before an @code{@@end table} command.
texinfo.texi(,16223) 
texinfo.texi(,16224) @need 1000
texinfo.texi(,16225) For example,
texinfo.texi(,16226) 
texinfo.texi(,16227) @example
texinfo.texi(,16228) @group
texinfo.texi(,16229) Types of fox:
texinfo.texi(,16230) 
texinfo.texi(,16231) @@table @@samp
texinfo.texi(,16232) @@item Quick
texinfo.texi(,16233) Jump over lazy dogs.
texinfo.texi(,16234) @end group
texinfo.texi(,16235) 
texinfo.texi(,16236) @group
texinfo.texi(,16237) @@item Brown
texinfo.texi(,16238) Also jump over lazy dogs.
texinfo.texi(,16239) @@end table
texinfo.texi(,16240) 
texinfo.texi(,16241) @end group
texinfo.texi(,16242) @group
texinfo.texi(,16243) @@noindent
texinfo.texi(,16244) On the other hand, @dots{}
texinfo.texi(,16245) @end group
texinfo.texi(,16246) @end example
texinfo.texi(,16247) 
texinfo.texi(,16248) Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
texinfo.texi(,16249) itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
texinfo.texi(,16250) same way.
texinfo.texi(,16251) @end itemize
texinfo.texi(,16252) 
texinfo.texi(,16253) @subsubheading Complete Phrases
texinfo.texi(,16254) 
texinfo.texi(,16255) Complete phrases are easier to read than @dots{}
texinfo.texi(,16256) 
texinfo.texi(,16257) @itemize @bullet
texinfo.texi(,16258) @item
texinfo.texi(,16259) Write entries in an itemized list as complete sentences; or at least, as
texinfo.texi(,16260) complete phrases.  Incomplete expressions @dots{} awkward @dots{} like
texinfo.texi(,16261) this.
texinfo.texi(,16262) 
texinfo.texi(,16263) @item
texinfo.texi(,16264) Write the prefatory sentence or phrase for a multi-item list or table as
texinfo.texi(,16265) a complete expression.  Do not write ``You can set:''; instead, write
texinfo.texi(,16266) ``You can set these variables:''.  The former expression sounds cut off.
texinfo.texi(,16267) @end itemize
texinfo.texi(,16268) 
texinfo.texi(,16269) @subsubheading Editions, Dates and Versions
texinfo.texi(,16270) 
texinfo.texi(,16271) Include edition numbers, version numbers, and dates in the
texinfo.texi(,16272) @code{@@copying} text (for people reading the Texinfo file, and for the
texinfo.texi(,16273) legal copyright in the output files).  Then use @code{@@insertcopying}
texinfo.texi(,16274) in the @code{@@titlepage} section (for people reading the printed
texinfo.texi(,16275) output) and the Top node (for people reading the online output).
texinfo.texi(,16276) 
texinfo.texi(,16277) It is easiest to do this using @code{@@set} and @code{@@value}.
texinfo.texi(,16278) @xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
texinfo.texi(,16279) 
texinfo.texi(,16280) 
texinfo.texi(,16281) @subsubheading Definition Commands
texinfo.texi(,16282) 
texinfo.texi(,16283) Definition commands are @code{@@deffn}, @code{@@defun},
texinfo.texi(,16284) @code{@@defmac}, and the like, and enable you to write descriptions in
texinfo.texi(,16285) a uniform format.@refill
texinfo.texi(,16286) 
texinfo.texi(,16287) @itemize @bullet
texinfo.texi(,16288) @item
texinfo.texi(,16289) Write just one definition command for each entity you define with a
texinfo.texi(,16290) definition command.  The automatic indexing feature creates an index
texinfo.texi(,16291) entry that leads the reader to the definition.
texinfo.texi(,16292) 
texinfo.texi(,16293) @item
texinfo.texi(,16294) Use @code{@@table} @dots{} @code{@@end table} in an appendix that
texinfo.texi(,16295) contains a summary of functions, not @code{@@deffn} or other definition
texinfo.texi(,16296) commands.
texinfo.texi(,16297) @end itemize
texinfo.texi(,16298) 
texinfo.texi(,16299) @subsubheading Capitalization
texinfo.texi(,16300) 
texinfo.texi(,16301) @itemize @bullet
texinfo.texi(,16302) @item
texinfo.texi(,16303) Capitalize ``Texinfo''; it is a name.  Do not write the @samp{x} or
texinfo.texi(,16304) @samp{i} in upper case.
texinfo.texi(,16305) 
texinfo.texi(,16306) @item
texinfo.texi(,16307) Capitalize ``Info''; it is a name.
texinfo.texi(,16308) 
texinfo.texi(,16309) @item
texinfo.texi(,16310) Write @TeX{} using the @code{@@TeX@{@}} command.  Note the uppercase
texinfo.texi(,16311) @samp{T} and @samp{X}.  This command causes the formatters to
texinfo.texi(,16312) typeset the name according to the wishes of Donald Knuth, who wrote
texinfo.texi(,16313) @TeX{}.
texinfo.texi(,16314) @end itemize
texinfo.texi(,16315) 
texinfo.texi(,16316) @subsubheading Spaces
texinfo.texi(,16317) 
texinfo.texi(,16318) Do not use spaces to format a Texinfo file, except inside of
texinfo.texi(,16319) @code{@@example} @dots{} @code{@@end example} and similar commands.
texinfo.texi(,16320) 
texinfo.texi(,16321) @need 700
texinfo.texi(,16322) For example, @TeX{} fills the following:
texinfo.texi(,16323) 
texinfo.texi(,16324) @example
texinfo.texi(,16325) @group
texinfo.texi(,16326)     @@kbd@{C-x v@}
texinfo.texi(,16327)     @@kbd@{M-x vc-next-action@}
texinfo.texi(,16328)        Perform the next logical operation
texinfo.texi(,16329)        on the version-controlled file
texinfo.texi(,16330)        corresponding to the current buffer.
texinfo.texi(,16331) @end group
texinfo.texi(,16332) @end example
texinfo.texi(,16333) 
texinfo.texi(,16334) @need 950
texinfo.texi(,16335) @noindent
texinfo.texi(,16336) so it looks like this:
texinfo.texi(,16337) 
texinfo.texi(,16347) @quotation
texinfo.texi(,16348) `C-x v' `M-x vc-next-action' Perform the next logical operation on the
texinfo.texi(,16349) version-controlled file corresponding to the current buffer.
texinfo.texi(,16350) @end quotation
texinfo.texi(,16352) 
texinfo.texi(,16353) @noindent
texinfo.texi(,16354) In this case, the text should be formatted with
texinfo.texi(,16355) @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
texinfo.texi(,16356) 
texinfo.texi(,16357) @subsubheading @@code, @@samp, @@var, and @samp{---}
texinfo.texi(,16358) 
texinfo.texi(,16359) @itemize @bullet
texinfo.texi(,16360) @item
texinfo.texi(,16361) Use @code{@@code} around Lisp symbols, including command names.
texinfo.texi(,16362) For example,
texinfo.texi(,16363) 
texinfo.texi(,16364) @example
texinfo.texi(,16365) The main function is @@code@{vc-next-action@}, @dots{}
texinfo.texi(,16366) @end example
texinfo.texi(,16367) 
texinfo.texi(,16368) @item
texinfo.texi(,16369) Avoid putting letters such as @samp{s} immediately after an
texinfo.texi(,16370) @samp{@@code}.  Such letters look bad.
texinfo.texi(,16371) 
texinfo.texi(,16372) @item
texinfo.texi(,16373) Use @code{@@var} around meta-variables.  Do not write angle brackets
texinfo.texi(,16374) around them.
texinfo.texi(,16375) 
texinfo.texi(,16376) @item
texinfo.texi(,16377) Use three hyphens in a row, @samp{---}, to indicate a long dash.  @TeX{}
texinfo.texi(,16378) typesets these as a long dash and the Info formatters reduce three
texinfo.texi(,16379) hyphens to two.
texinfo.texi(,16380) @end itemize
texinfo.texi(,16381) 
texinfo.texi(,16382) @subsubheading Periods Outside of Quotes
texinfo.texi(,16383) 
texinfo.texi(,16384) Place periods and other punctuation marks @emph{outside} of quotations,
texinfo.texi(,16385) unless the punctuation is part of the quotation.  This practice goes
texinfo.texi(,16386) against publishing conventions in the United States, but enables the
texinfo.texi(,16387) reader to distinguish between the contents of the quotation and the
texinfo.texi(,16388) whole passage.
texinfo.texi(,16389) 
texinfo.texi(,16390) For example, you should write the following sentence with the period
texinfo.texi(,16391) outside the end quotation marks:
texinfo.texi(,16392) 
texinfo.texi(,16393) @example
texinfo.texi(,16394) Evidently, @samp{au} is an abbreviation for ``author''.
texinfo.texi(,16395) @end example
texinfo.texi(,16396) 
texinfo.texi(,16397) @noindent
texinfo.texi(,16398) since @samp{au} does @emph{not} serve as an  abbreviation for
texinfo.texi(,16399) @samp{author.} (with a period following the word).
texinfo.texi(,16400) 
texinfo.texi(,16401) @subsubheading Introducing New Terms
texinfo.texi(,16402) 
texinfo.texi(,16403) @itemize @bullet
texinfo.texi(,16404) @item
texinfo.texi(,16405) Introduce new terms so that a reader who does not know them can
texinfo.texi(,16406) understand them from context; or write a definition for the term.
texinfo.texi(,16407) 
texinfo.texi(,16408) For example, in the following, the terms ``check in'', ``register'' and
texinfo.texi(,16409) ``delta'' are all appearing for the first time; the example sentence should be
texinfo.texi(,16410) rewritten so they are understandable.
texinfo.texi(,16411) 
texinfo.texi(,16412) @quotation
texinfo.texi(,16413) The major function assists you in checking in a file to your
texinfo.texi(,16414) version control system and registering successive sets of changes to
texinfo.texi(,16415) it as deltas.
texinfo.texi(,16416) @end quotation
texinfo.texi(,16417) 
texinfo.texi(,16418) @item
texinfo.texi(,16419) Use the @code{@@dfn} command around a word being introduced, to indicate
texinfo.texi(,16420) that the reader should not expect to know the meaning already, and
texinfo.texi(,16421) should expect to learn the meaning from this passage.
texinfo.texi(,16422) @end itemize
texinfo.texi(,16423) 
texinfo.texi(,16424) @subsubheading @@pxref
texinfo.texi(,16425) 
texinfo.texi(,16426) @c !!! maybe include this in the tips on pxref
texinfo.texi(,16434) Absolutely never use @code{@@pxref} except in the special context for
texinfo.texi(,16435) which it is designed: inside parentheses, with the closing parenthesis
texinfo.texi(,16436) following immediately after the closing brace.  One formatter
texinfo.texi(,16437) automatically inserts closing punctuation and the other does not.  This
texinfo.texi(,16438) means that the output looks right both in printed output and in an Info
texinfo.texi(,16439) file, but only when the command is used inside parentheses.
texinfo.texi(,16440) 
texinfo.texi(,16441) @subsubheading Invoking from a Shell
texinfo.texi(,16442) 
texinfo.texi(,16443) You can invoke programs such as Emacs, GCC, and @code{gawk} from a
texinfo.texi(,16444) shell.  The documentation for each program should contain a section that
texinfo.texi(,16445) describes this.  Unfortunately, if the node names and titles for these
texinfo.texi(,16446) sections are all different, they are difficult for users to find.
texinfo.texi(,16447) 
texinfo.texi(,16448) So, there is a convention to name such sections with a phrase beginning
texinfo.texi(,16449) with the word `Invoking', as in `Invoking Emacs'; this way, users can
texinfo.texi(,16450) find the section easily.
texinfo.texi(,16451) 
texinfo.texi(,16452) 
texinfo.texi(,16453) @subsubheading ANSI C Syntax
texinfo.texi(,16454) 
texinfo.texi(,16455) When you use @code{@@example} to describe a C function's calling
texinfo.texi(,16456) conventions, use the ANSI C syntax, like this:@refill
texinfo.texi(,16457) 
texinfo.texi(,16458) @example
texinfo.texi(,16459) void dld_init (char *@@var@{path@});
texinfo.texi(,16460) @end example
texinfo.texi(,16461) 
texinfo.texi(,16462) @noindent
texinfo.texi(,16463) And in the subsequent discussion, refer to the argument values by
texinfo.texi(,16464) writing the same argument names, again highlighted with
texinfo.texi(,16465) @code{@@var}.@refill
texinfo.texi(,16466) 
texinfo.texi(,16467) @need 800
texinfo.texi(,16468) Avoid the obsolete style that looks like this:@refill
texinfo.texi(,16469) 
texinfo.texi(,16470) @example
texinfo.texi(,16471) #include <dld.h>
texinfo.texi(,16472) 
texinfo.texi(,16473) dld_init (path)
texinfo.texi(,16474) char *path;
texinfo.texi(,16475) @end example
texinfo.texi(,16476) 
texinfo.texi(,16477) Also, it is best to avoid writing @code{#include} above the
texinfo.texi(,16478) declaration just to indicate that the function is declared in a
texinfo.texi(,16479) header file.  The practice may give the misimpression that the
texinfo.texi(,16480) @code{#include} belongs near the declaration of the function.  Either
texinfo.texi(,16481) state explicitly which header file holds the declaration or, better
texinfo.texi(,16482) yet, name the header file used for a group of functions at the
texinfo.texi(,16483) beginning of the section that describes the functions.@refill
texinfo.texi(,16484) 
texinfo.texi(,16485) @subsubheading Bad Examples
texinfo.texi(,16486) 
texinfo.texi(,16487) Here are several examples of bad writing to avoid:
texinfo.texi(,16488) 
texinfo.texi(,16489) In this example, say, `` @dots{} you must @code{@@dfn}@{check
texinfo.texi(,16490) in@} the new version.''  That flows better.
texinfo.texi(,16491) 
texinfo.texi(,16492) @quotation
texinfo.texi(,16493) When you are done editing the file, you must perform a
texinfo.texi(,16494) @code{@@dfn}@{check in@}.
texinfo.texi(,16495) @end quotation
texinfo.texi(,16496) 
texinfo.texi(,16497) In the following example, say, ``@dots{} makes a unified interface such as VC
texinfo.texi(,16498) mode possible.''
texinfo.texi(,16499) 
texinfo.texi(,16500) @quotation
texinfo.texi(,16501) SCCS, RCS and other version-control systems all perform similar
texinfo.texi(,16502) functions in broadly similar ways (it is this resemblance which makes
texinfo.texi(,16503) a unified control mode like this possible).
texinfo.texi(,16504) @end quotation
texinfo.texi(,16505) 
texinfo.texi(,16506) And in this example, you should specify what `it' refers to:
texinfo.texi(,16507) 
texinfo.texi(,16508) @quotation
texinfo.texi(,16509) If you are working with other people, it assists in coordinating
texinfo.texi(,16510) everyone's changes so they do not step on each other.
texinfo.texi(,16511) @end quotation
texinfo.texi(,16512) 
texinfo.texi(,16513) @subsubheading And Finally @dots{}
texinfo.texi(,16514) 
texinfo.texi(,16515) @itemize @bullet
texinfo.texi(,16516) @item
texinfo.texi(,16517) Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
texinfo.texi(,16518) sound in the name `Bach'.  But pronounce Texinfo as in `speck':
texinfo.texi(,16519) ``teckinfo''.
texinfo.texi(,16520) 
texinfo.texi(,16521) @item
texinfo.texi(,16522) Write notes for yourself at the very end of a Texinfo file after the
texinfo.texi(,16523) @code{@@bye}.  None of the formatters process text after the
texinfo.texi(,16524) @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
texinfo.texi(,16525) @code{@@end ignore}.
texinfo.texi(,16526) @end itemize
texinfo.texi(,16527) 
texinfo.texi(,16528) 
texinfo.texi(,16529) @node Sample Texinfo Files
texinfo.texi(,16530) @appendix Sample Texinfo Files
texinfo.texi(,16531) @cindex Sample Texinfo files
texinfo.texi(,16532) 
texinfo.texi(,16533) The first example is from the first chapter (@pxref{Short Sample}),
texinfo.texi(,16534) given here in its entirety, without commentary.  The second sample
texinfo.texi(,16535) includes the full texts to be used in GNU manuals.
texinfo.texi(,16536) 
texinfo.texi(,16537) @menu
texinfo.texi(,16538) * Short Sample Texinfo File::   
texinfo.texi(,16539) * GNU Sample Texts::            
texinfo.texi(,16540) @end menu
texinfo.texi(,16541) 
texinfo.texi(,16542) 
texinfo.texi(,16543) @node Short Sample Texinfo File
texinfo.texi(,16544) @section Short Sample
texinfo.texi(,16545) @cindex Sample Texinfo file, no comments
texinfo.texi(,16546) 
texinfo.texi(,16547) Here is a complete, short sample Texinfo file, without any commentary.
texinfo.texi(,16548) You can see this file, with comments, in the first chapter.  @xref{Short
texinfo.texi(,16549) Sample}.
texinfo.texi(,16550) 
texinfo.texi(,16551) In a nutshell: The @command{makeinfo} program transforms a Texinfo
texinfo.texi(,16552) source file such as this into an Info file or HTML; and @TeX{} typesets
texinfo.texi(,16553) it for a printed manual.
texinfo.texi(,16554) 
texinfo.texi(,16555) 
texinfo.texi(,16556) @sp 1
texinfo.texi(,16557) @example
texinfo.texi(,16558) \input texinfo   @@c -*-texinfo-*-
texinfo.texi(,16559) @@c %**start of header
texinfo.texi(,16560) @@setfilename sample.info
texinfo.texi(,16561) @@settitle Sample Manual 1.0
texinfo.texi(,16562) @@c %**end of header
texinfo.texi(,16563) 
texinfo.texi(,16564) @@copying
texinfo.texi(,16565) This is a short example of a complete Texinfo file.
texinfo.texi(,16566) 
texinfo.texi(,16567) Copyright (C) 2002 Free Software Foundation, Inc.
texinfo.texi(,16568) @@end copying
texinfo.texi(,16569) 
texinfo.texi(,16570) @@titlepage
texinfo.texi(,16571) @@title Sample Title
texinfo.texi(,16572) @@page
texinfo.texi(,16573) @@vskip 0pt plus 1filll
texinfo.texi(,16574) @@insertcopying
texinfo.texi(,16575) @@end titlepage
texinfo.texi(,16576) 
texinfo.texi(,16577) @@c Output the table of the contents at the beginning.
texinfo.texi(,16578) @@contents
texinfo.texi(,16579) 
texinfo.texi(,16580) @@ifnottex
texinfo.texi(,16581) @@node Top
texinfo.texi(,16582) 
texinfo.texi(,16583) @@insertcopying
texinfo.texi(,16584) @@end ifnottex
texinfo.texi(,16585) 
texinfo.texi(,16586) @@menu
texinfo.texi(,16587) * First Chapter::    The first chapter is the
texinfo.texi(,16588)                        only chapter in this sample.
texinfo.texi(,16589) * Index::            Complete index.
texinfo.texi(,16590) @@end menu
texinfo.texi(,16591) 
texinfo.texi(,16592) 
texinfo.texi(,16593) @@node First Chapter
texinfo.texi(,16594) @@chapter First Chapter
texinfo.texi(,16595) 
texinfo.texi(,16596) @@cindex chapter, first
texinfo.texi(,16597) 
texinfo.texi(,16598) This is the first chapter.
texinfo.texi(,16599) @@cindex index entry, another
texinfo.texi(,16600) 
texinfo.texi(,16601) Here is a numbered list.
texinfo.texi(,16602) 
texinfo.texi(,16603) @@enumerate
texinfo.texi(,16604) @@item
texinfo.texi(,16605) This is the first item.
texinfo.texi(,16606) 
texinfo.texi(,16607) @@item
texinfo.texi(,16608) This is the second item.
texinfo.texi(,16609) @@end enumerate
texinfo.texi(,16610) 
texinfo.texi(,16611) 
texinfo.texi(,16612) @@node Index
texinfo.texi(,16613) @@unnumbered Index
texinfo.texi(,16614) 
texinfo.texi(,16615) @@printindex cp
texinfo.texi(,16616) 
texinfo.texi(,16617) @@bye
texinfo.texi(,16618) @end example
texinfo.texi(,16619) 
texinfo.texi(,16620) 
texinfo.texi(,16621) @node GNU Sample Texts
texinfo.texi(,16622) @section GNU Sample Texts
texinfo.texi(,16623) 
texinfo.texi(,16624) @cindex GNU sample texts
texinfo.texi(,16625) @cindex Sample texts, GNU
texinfo.texi(,16626) @cindex Full texts, GNU
texinfo.texi(,16627) 
texinfo.texi(,16628) Here is a sample Texinfo document with the full texts that should be
texinfo.texi(,16629) used in GNU manuals.
texinfo.texi(,16630) 
texinfo.texi(,16631) As well as the legal texts, it also serves as a practical example of how
texinfo.texi(,16632) many elements in a GNU system can affect the manual.  If you're not
texinfo.texi(,16633) familiar with all these different elements, don't worry.  They're not
texinfo.texi(,16634) required and a perfectly good manual can be written without them.
texinfo.texi(,16635) They're included here nonetheless because many manuals do (or could)
texinfo.texi(,16636) benefit from them.
texinfo.texi(,16637) 
texinfo.texi(,16638) @xref{Short Sample}, for a minimal example of a Texinfo file.
texinfo.texi(,16639) @xref{Beginning a File}, for a full explanation of that minimal
texinfo.texi(,16640) example.
texinfo.texi(,16641) 
texinfo.texi(,16642) Here are some notes on the example:
texinfo.texi(,16643) 
texinfo.texi(,16644) @itemize @bullet
texinfo.texi(,16645) @item
texinfo.texi(,16646) @cindex $ @c Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $ comment
texinfo.texi(,16647) @cindex CVS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in Texinfo
texinfo.texi(,16648) @cindex RCS Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $, in Texinfo
texinfo.texi(,16649) The @samp{Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $} comment is for CVS (@pxref{Top,, Overview, cvs,
texinfo.texi(,16650) Concurrent Versions System}) or RCS (see rcsintro(1)) version control
texinfo.texi(,16651) systems, which expand it into a string such as:
texinfo.texi(,16652) @example
texinfo.texi(,16653) Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
texinfo.texi(,16654) @end example
texinfo.texi(,16655) (This is useful in all sources that use version control, not just manuals.)
texinfo.texi(,16656) 
texinfo.texi(,16657) @item
texinfo.texi(,16658) @pindex automake@r{, and version info}
texinfo.texi(,16659) The @file{version.texi} in the @code{@@include} command is maintained
texinfo.texi(,16660) automatically by Automake (@pxref{Top,, Introduction, automake, GNU
texinfo.texi(,16661) Automake}).  It sets the @samp{VERSION} and @samp{UPDATED} values used
texinfo.texi(,16662) elsewhere.  If your distribution doesn't use Automake, you can mimic
texinfo.texi(,16663) these or equivalent settings.
texinfo.texi(,16664) 
texinfo.texi(,16665) @item
texinfo.texi(,16666) The @code{@@syncodeindex} command reflects the recommendation to use only
texinfo.texi(,16667) one index if at all possible, to make it easier for readers.
texinfo.texi(,16668) 
texinfo.texi(,16669) @item
texinfo.texi(,16670) The @code{@@dircategory} is for constructing the Info directory.
texinfo.texi(,16671) @xref{Installing Dir Entries}, which includes a variety of recommended
texinfo.texi(,16672) category names.
texinfo.texi(,16673) 
texinfo.texi(,16674) @item
texinfo.texi(,16675) The `Invoking' node is a GNU standard to help users find the basic
texinfo.texi(,16676) information about command-line usage of a given program.  @xref{Manual
texinfo.texi(,16677) Structure Details,,,standards, GNU Coding Standards}.
texinfo.texi(,16678) 
texinfo.texi(,16679) @item
texinfo.texi(,16680) It is best to include the entire GNU Free Documentation License in a GNU
texinfo.texi(,16681) manual, unless the manual is only a few pages long.  Of course this
texinfo.texi(,16682) sample is even shorter than that, but it includes the FDL anyway in
texinfo.texi(,16683) order to show one conventional way of doing so.  The @file{fdl.texi}
texinfo.texi(,16684) file is available on the GNU machines (and in the Texinfo and other GNU
texinfo.texi(,16685) distributions).
texinfo.texi(,16686) 
texinfo.texi(,16687) The FDL provides for omitting itself under certain conditions, but in
texinfo.texi(,16688) that case the sample texts given here have to be modified.  @xref{GNU
texinfo.texi(,16689) Free Documentation License}.
texinfo.texi(,16690) 
texinfo.texi(,16691) @item
texinfo.texi(,16692) If your manual has invariant sections (again, see the license itself for
texinfo.texi(,16693) details), then don't forget to include them.
texinfo.texi(,16694) @end itemize
texinfo.texi(,16695) 
texinfo.texi(,16696) Here is the sample document:
texinfo.texi(,16697) 
texinfo.texi(,16698) @c We do the first part of this with @example instead of @verbatim
texinfo.texi(,16699) @c because the literal @setfilename and @include confuse Automake.  Argh.
texinfo.texi(,16700) @example
texinfo.texi(,16701) \input texinfo    @@c -*-texinfo-*-
texinfo.texi(,16702) @@comment Id: texinfo.txi,v 1.2 2003/02/24 18:17:06 pertusus Exp $
texinfo.texi(,16703) @@comment %**start of header
texinfo.texi(,16704) @@setfilename sample.info
texinfo.texi(,16705) @@include version.texi
texinfo.texi(,16706) @@settitle GNU Sample @@value@{VERSION@}
texinfo.texi(,16707) @@syncodeindex pg cp
texinfo.texi(,16708) @@comment %**end of header
texinfo.texi(,16709) @@copying
texinfo.texi(,16710) This manual is for GNU Sample
texinfo.texi(,16711) (version @@value@{VERSION@}, @@value@{UPDATED@}),
texinfo.texi(,16712) which is an example in the Texinfo documentation.
texinfo.texi(,16713) 
texinfo.texi(,16714) Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
texinfo.texi(,16715) 
texinfo.texi(,16716) @@quotation
texinfo.texi(,16717) Permission is granted to copy, distribute and/or modify this document
texinfo.texi(,16718) under the terms of the GNU Free Documentation License, Version 1.1 or
texinfo.texi(,16719) any later version published by the Free Software Foundation; with no
texinfo.texi(,16720) Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
texinfo.texi(,16721) and with the Back-Cover Texts as in (a) below.  A copy of the
texinfo.texi(,16722) license is included in the section entitled ``GNU Free Documentation
texinfo.texi(,16723) License.''
texinfo.texi(,16724) 
texinfo.texi(,16725) (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
texinfo.texi(,16726) this GNU Manual, like GNU software.  Copies published by the Free
texinfo.texi(,16727) Software Foundation raise funds for GNU development.''
texinfo.texi(,16728) @@end quotation
texinfo.texi(,16729) @@end copying
texinfo.texi(,16730) 
texinfo.texi(,16731) @@dircategory Texinfo documentation system
texinfo.texi(,16732) @@direntry
texinfo.texi(,16733) * sample: (sample)Invoking sample.    
texinfo.texi(,16734) @@end direntry
texinfo.texi(,16735) 
texinfo.texi(,16736) @@titlepage
texinfo.texi(,16737) @@title GNU Sample
texinfo.texi(,16738) @@subtitle for version @@value@{VERSION@}, @@value@{UPDATED@}
texinfo.texi(,16739) @@author A.U. Thor (@@email@{bug-texinfo@@@@gnu.org@})
texinfo.texi(,16740) @@page
texinfo.texi(,16741) @@vskip 0pt plus 1filll
texinfo.texi(,16742) @@insertcopying
texinfo.texi(,16743) @@end titlepage
texinfo.texi(,16744) 
texinfo.texi(,16745) @@contents
texinfo.texi(,16746) 
texinfo.texi(,16747) @@ifnottex
texinfo.texi(,16748) @@node Top
texinfo.texi(,16749) @@top GNU Sample
texinfo.texi(,16750) 
texinfo.texi(,16751) @@insertcopying
texinfo.texi(,16752) @@end ifnottex
texinfo.texi(,16753) 
texinfo.texi(,16754) @@menu
texinfo.texi(,16755) * Invoking sample::
texinfo.texi(,16756) * Copying This Manual::
texinfo.texi(,16757) * Index::
texinfo.texi(,16758) @@end menu
texinfo.texi(,16759) 
texinfo.texi(,16760) 
texinfo.texi(,16761) @@node Invoking sample
texinfo.texi(,16762) @@chapter Invoking sample
texinfo.texi(,16763) 
texinfo.texi(,16764) @@pindex sample
texinfo.texi(,16765) @@cindex invoking @@command@{sample@}
texinfo.texi(,16766) 
texinfo.texi(,16767) This is a sample manual.  There is no sample program to
texinfo.texi(,16768) invoke, but if there was, you could see its basic usage
texinfo.texi(,16769) and command line options here.
texinfo.texi(,16770) 
texinfo.texi(,16771) 
texinfo.texi(,16772) @@node Copying This Manual
texinfo.texi(,16773) @@appendix Copying This Manual
texinfo.texi(,16774) 
texinfo.texi(,16775) @@menu
texinfo.texi(,16776) * GNU Free Documentation License::  License for copying this manual.
texinfo.texi(,16777) @@end menu
texinfo.texi(,16778) 
texinfo.texi(,16779) @@include fdl.texi
texinfo.texi(,16780) 
texinfo.texi(,16781) 
texinfo.texi(,16782) @@node Index
texinfo.texi(,16783) @@unnumbered Index
texinfo.texi(,16784) 
texinfo.texi(,16785) @@printindex cp
texinfo.texi(,16786) 
texinfo.texi(,16787) @@bye
texinfo.texi(,16788) @end example
texinfo.texi(,16789) 
texinfo.texi(,16790) 
texinfo.texi(,16791) @node Include Files
texinfo.texi(,16792) @appendix Include Files
texinfo.texi(,16793) @cindex Include files
texinfo.texi(,16794) 
texinfo.texi(,16795) When @TeX{} or an Info formatting command sees an @code{@@include}
texinfo.texi(,16796) command in a Texinfo file, it processes the contents of the file named
texinfo.texi(,16797) by the command and incorporates them into the DVI or Info file being
texinfo.texi(,16798) created.  Index entries from the included file are incorporated into
texinfo.texi(,16799) the indices of the output file.
texinfo.texi(,16800) 
texinfo.texi(,16801) Include files let you keep a single large document as a collection of
texinfo.texi(,16802) conveniently small parts.
texinfo.texi(,16803) 
texinfo.texi(,16804) @menu
texinfo.texi(,16805) * Using Include Files::         How to use the @code{@@include} command.
texinfo.texi(,16806) * texinfo-multiple-files-update::  How to create and update nodes and
texinfo.texi(,16807)                                   menus when using included files.
texinfo.texi(,16808) * Include File Requirements::   What @code{texinfo-multiple-files-update} expects.
texinfo.texi(,16809) * Sample Include File::         A sample outer file with included files
texinfo.texi(,16810)                                   within it; and a sample included file.
texinfo.texi(,16811) * Include Files Evolution::     How use of the @code{@@include} command
texinfo.texi(,16812)                                   has changed over time.
texinfo.texi(,16813) @end menu
texinfo.texi(,16814) 
texinfo.texi(,16815) @node Using Include Files, texinfo-multiple-files-update, Include Files, Include Files
texinfo.texi(,16816) @section How to Use Include Files
texinfo.texi(,16817) @findex include
texinfo.texi(,16818) 
texinfo.texi(,16819) To include another file within a Texinfo file, write the
texinfo.texi(,16820) @code{@@include} command at the beginning of a line and follow it on
texinfo.texi(,16821) the same line by the name of a file to be included.  For
texinfo.texi(,16822) example:@refill
texinfo.texi(,16823) 
texinfo.texi(,16824) @example
texinfo.texi(,16825) @@include buffers.texi
texinfo.texi(,16826) @end example
texinfo.texi(,16827) 
texinfo.texi(,16828) An included file should simply be a segment of text that you expect to
texinfo.texi(,16829) be included as is into the overall or @dfn{outer} Texinfo file; it
texinfo.texi(,16830) should not contain the standard beginning and end parts of a Texinfo
texinfo.texi(,16831) file.  In particular, you should not start an included file with a
texinfo.texi(,16832) line saying @samp{\input texinfo}; if you do, that phrase is inserted
texinfo.texi(,16833) into the output file as is.  Likewise, you should not end an included
texinfo.texi(,16834) file with an @code{@@bye} command; nothing after @code{@@bye} is
texinfo.texi(,16835) formatted.@refill
texinfo.texi(,16836) 
texinfo.texi(,16837) In the past, you were required to write an @code{@@setfilename} line at the
texinfo.texi(,16838) beginning of an included file, but no longer.  Now, it does not matter
texinfo.texi(,16839) whether you write such a line.  If an @code{@@setfilename} line exists
texinfo.texi(,16840) in an included file, it is ignored.@refill
texinfo.texi(,16841) 
texinfo.texi(,16842) Conventionally, an included file begins with an @code{@@node} line that
texinfo.texi(,16843) is followed by an @code{@@chapter} line.  Each included file is one
texinfo.texi(,16844) chapter.  This makes it easy to use the regular node and menu creating
texinfo.texi(,16845) and updating commands to create the node pointers and menus within the
texinfo.texi(,16846) included file.  However, the simple Emacs node and menu creating and
texinfo.texi(,16847) updating commands do not work with multiple Texinfo files.  Thus you
texinfo.texi(,16848) cannot use these commands to fill in the `Next', `Previous', and `Up'
texinfo.texi(,16849) pointers of the @code{@@node} line that begins the included file.  Also,
texinfo.texi(,16850) you cannot use the regular commands to create a master menu for the
texinfo.texi(,16851) whole file.  Either you must insert the menus and the `Next',
texinfo.texi(,16852) `Previous', and `Up' pointers by hand, or you must use the GNU Emacs
texinfo.texi(,16853) Texinfo mode command, @code{texinfo-multiple-files-update}, that is
texinfo.texi(,16854) designed for @code{@@include} files.@refill
texinfo.texi(,16855) 
texinfo.texi(,16856) @node texinfo-multiple-files-update, Include File Requirements, Using Include Files, Include Files
texinfo.texi(,16857) @section @code{texinfo-multiple-files-update}
texinfo.texi(,16858) @findex texinfo-multiple-files-update
texinfo.texi(,16859) 
texinfo.texi(,16860) GNU Emacs Texinfo mode provides the @code{texinfo-multiple-files-update}
texinfo.texi(,16861) command.  This command creates or updates `Next', `Previous', and `Up'
texinfo.texi(,16862) pointers of included files as well as those in the outer or overall
texinfo.texi(,16863) Texinfo file, and it creates or updates a main menu in the outer file.
texinfo.texi(,16864) Depending whether you call it with optional arguments, the command
texinfo.texi(,16865) updates only the pointers in the first @code{@@node} line of the
texinfo.texi(,16866) included files or all of them:@refill
texinfo.texi(,16867) 
texinfo.texi(,16868) @table @kbd
texinfo.texi(,16869) @item M-x texinfo-multiple-files-update
texinfo.texi(,16870) Called without any arguments:@refill
texinfo.texi(,16871) 
texinfo.texi(,16872) @itemize @minus
texinfo.texi(,16873) @item
texinfo.texi(,16874) Create or update the `Next', `Previous', and `Up' pointers of the
texinfo.texi(,16875) first @code{@@node} line in each file included in an outer or overall
texinfo.texi(,16876) Texinfo file.@refill
texinfo.texi(,16877) 
texinfo.texi(,16878) @item
texinfo.texi(,16879) Create or update the `Top' level node pointers of the outer or
texinfo.texi(,16880) overall file.@refill
texinfo.texi(,16881) 
texinfo.texi(,16882) @item
texinfo.texi(,16883) Create or update a main menu in the outer file.@refill
texinfo.texi(,16884) @end itemize
texinfo.texi(,16885) 
texinfo.texi(,16886) @item C-u M-x texinfo-multiple-files-update
texinfo.texi(,16887) Called with @kbd{C-u} as a prefix argument:
texinfo.texi(,16888) 
texinfo.texi(,16889) @itemize @minus{}
texinfo.texi(,16890) @item
texinfo.texi(,16891) Create or update pointers in the first @code{@@node} line in each
texinfo.texi(,16892) included file.
texinfo.texi(,16893) 
texinfo.texi(,16894) @item
texinfo.texi(,16895) Create or update the `Top' level node pointers of the outer file.
texinfo.texi(,16896) 
texinfo.texi(,16897) @item
texinfo.texi(,16898) Create and insert a master menu in the outer file.  The master menu
texinfo.texi(,16899) is made from all the menus in all the included files.@refill
texinfo.texi(,16900) @end itemize
texinfo.texi(,16901) 
texinfo.texi(,16902) @item C-u 8 M-x texinfo-multiple-files-update
texinfo.texi(,16903) Called with a numeric prefix argument, such as @kbd{C-u 8}:
texinfo.texi(,16904) 
texinfo.texi(,16905) @itemize @minus
texinfo.texi(,16906) @item
texinfo.texi(,16907) Create or update @strong{all} the `Next', `Previous', and `Up' pointers
texinfo.texi(,16908) of all the included files.@refill
texinfo.texi(,16909) 
texinfo.texi(,16910) @item
texinfo.texi(,16911) Create or update @strong{all} the menus of all the included
texinfo.texi(,16912) files.@refill
texinfo.texi(,16913) 
texinfo.texi(,16914) @item
texinfo.texi(,16915) Create or update the `Top' level node pointers of the outer or
texinfo.texi(,16916) overall file.@refill
texinfo.texi(,16917) 
texinfo.texi(,16918) @item
texinfo.texi(,16919) And then create a master menu in the outer file.  This is similar to
texinfo.texi(,16920) invoking @code{texinfo-master-menu} with an argument when you are
texinfo.texi(,16921) working with just one file.@refill
texinfo.texi(,16922) @end itemize
texinfo.texi(,16923) @end table
texinfo.texi(,16924) 
texinfo.texi(,16925) Note the use of the prefix argument in interactive use: with a regular
texinfo.texi(,16926) prefix argument, just @w{@kbd{C-u}}, the
texinfo.texi(,16927) @code{texinfo-multiple-files-update} command inserts a master menu;
texinfo.texi(,16928) with a numeric prefix argument, such as @kbd{C-u 8}, the command
texinfo.texi(,16929) updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
texinfo.texi(,16930) master menu.@refill
texinfo.texi(,16931) 
texinfo.texi(,16932) 
texinfo.texi(,16933) @node Include File Requirements
texinfo.texi(,16934) @section Include File Requirements
texinfo.texi(,16935) @cindex Include file requirements
texinfo.texi(,16936) @cindex Requirements for include files
texinfo.texi(,16937) 
texinfo.texi(,16938) If you plan to use the @code{texinfo-multiple-files-update} command,
texinfo.texi(,16939) the outer Texinfo file that lists included files within it should
texinfo.texi(,16940) contain nothing but the beginning and end parts of a Texinfo file, and
texinfo.texi(,16941) a number of @code{@@include} commands listing the included files.  It
texinfo.texi(,16942) should not even include indices, which should be listed in an included
texinfo.texi(,16943) file of their own.@refill
texinfo.texi(,16944) 
texinfo.texi(,16945) Moreover, each of the included files must contain exactly one highest
texinfo.texi(,16946) level node (conventionally, @code{@@chapter} or equivalent),
texinfo.texi(,16947) and this node must be the first node in the included file.
texinfo.texi(,16948) Furthermore, each of these highest level nodes in each included file
texinfo.texi(,16949) must be at the same hierarchical level in the file structure.
texinfo.texi(,16950) Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
texinfo.texi(,16951) @code{@@unnumbered} node.  Thus, normally, each included file contains
texinfo.texi(,16952) one, and only one, chapter or equivalent-level node.@refill
texinfo.texi(,16953) 
texinfo.texi(,16954) The outer file should contain only @emph{one} node, the `Top' node.  It
texinfo.texi(,16955) should @emph{not} contain any nodes besides the single `Top' node.  The
texinfo.texi(,16956) @code{texinfo-multiple-files-update} command will not process
texinfo.texi(,16957) them.@refill
texinfo.texi(,16958) 
texinfo.texi(,16959) @node Sample Include File, Include Files Evolution, Include File Requirements, Include Files
texinfo.texi(,16960) @section Sample File with @code{@@include}
texinfo.texi(,16961) @cindex Sample @code{@@include} file
texinfo.texi(,16962) @cindex Include file sample
texinfo.texi(,16963) @cindex @code{@@include} file sample
texinfo.texi(,16964) 
texinfo.texi(,16965) Here is an example of a complete outer Texinfo file with @code{@@include} files
texinfo.texi(,16966) within it before running @code{texinfo-multiple-files-update}, which
texinfo.texi(,16967) would insert a main or master menu:@refill
texinfo.texi(,16968) 
texinfo.texi(,16969) @example
texinfo.texi(,16970) @group
texinfo.texi(,16971) \input texinfo @@c -*-texinfo-*-
texinfo.texi(,16972) @c %**start of header
texinfo.texi(,16973) @@setfilename  include-example.info
texinfo.texi(,16974) @@settitle Include Example
texinfo.texi(,16975) @c %**end of header
texinfo.texi(,16976) @end group
texinfo.texi(,16977) 
texinfo.texi(,16978) @group
texinfo.texi(,16979) @@setchapternewpage odd
texinfo.texi(,16980) @@titlepage
texinfo.texi(,16981) @@sp 12
texinfo.texi(,16982) @@center @@titlefont@{Include Example@}
texinfo.texi(,16983) @@sp 2
texinfo.texi(,16984) @@center by Whom Ever
texinfo.texi(,16985) @end group
texinfo.texi(,16986) 
texinfo.texi(,16987) @group
texinfo.texi(,16988) @@page
texinfo.texi(,16989) @@vskip 0pt plus 1filll
texinfo.texi(,16990) Copyright @@copyright@{@} 2002 Free Software Foundation, Inc.
texinfo.texi(,16991) @@end titlepage
texinfo.texi(,16992) @end group
texinfo.texi(,16993) 
texinfo.texi(,16994) @group
texinfo.texi(,16995) @@ifinfo
texinfo.texi(,16996) @@node Top, First, , (dir)
texinfo.texi(,16997) @@top Master Menu
texinfo.texi(,16998) @@end ifinfo
texinfo.texi(,16999) @end group
texinfo.texi(,17000) 
texinfo.texi(,17001) @group
texinfo.texi(,17002) @@include foo.texinfo
texinfo.texi(,17003) @@include bar.texinfo
texinfo.texi(,17004) @@include concept-index.texinfo
texinfo.texi(,17005) @end group
texinfo.texi(,17006) 
texinfo.texi(,17007) @group
texinfo.texi(,17008) @@summarycontents
texinfo.texi(,17009) @@contents
texinfo.texi(,17010) 
texinfo.texi(,17011) @@bye
texinfo.texi(,17012) @end group
texinfo.texi(,17013) @end example
texinfo.texi(,17014) 
texinfo.texi(,17015) An included file, such as @file{foo.texinfo}, might look like this:
texinfo.texi(,17016) 
texinfo.texi(,17017) @example
texinfo.texi(,17018) @group
texinfo.texi(,17019) @@node First, Second, , Top
texinfo.texi(,17020) @@chapter First Chapter
texinfo.texi(,17021) 
texinfo.texi(,17022) Contents of first chapter @dots{}
texinfo.texi(,17023) @end group
texinfo.texi(,17024) @end example
texinfo.texi(,17025) 
texinfo.texi(,17026) The full contents of @file{concept-index.texinfo} might be as simple as this:
texinfo.texi(,17027) 
texinfo.texi(,17028) @example
texinfo.texi(,17029) @group
texinfo.texi(,17030) @@node Concept Index
texinfo.texi(,17031) @@unnumbered Concept Index
texinfo.texi(,17032) 
texinfo.texi(,17033) @@printindex cp
texinfo.texi(,17034) @end group
texinfo.texi(,17035) @end example
texinfo.texi(,17036) 
texinfo.texi(,17037) The outer Texinfo source file for @cite{The GNU Emacs Lisp Reference
texinfo.texi(,17038) Manual} is named @file{elisp.texi}.  This outer file contains a master
texinfo.texi(,17039) menu with 417 entries and a list of 41 @code{@@include}
texinfo.texi(,17040) files.@refill
texinfo.texi(,17041) 
texinfo.texi(,17042) 
texinfo.texi(,17043) @node Include Files Evolution
texinfo.texi(,17044) @section Evolution of Include Files
texinfo.texi(,17045) 
texinfo.texi(,17046) When Info was first created, it was customary to create many small
texinfo.texi(,17047) Info files on one subject.  Each Info file was formatted from its own
texinfo.texi(,17048) Texinfo source file.  This custom meant that Emacs did not need to
texinfo.texi(,17049) make a large buffer to hold the whole of a large Info file when
texinfo.texi(,17050) someone wanted information; instead, Emacs allocated just enough
texinfo.texi(,17051) memory for the small Info file that contained the particular
texinfo.texi(,17052) information sought.  This way, Emacs could avoid wasting memory.@refill
texinfo.texi(,17053) 
texinfo.texi(,17054) References from one file to another were made by referring to the file
texinfo.texi(,17055) name as well as the node name. (@xref{Other Info Files, , Referring to
texinfo.texi(,17056) Other Info Files}.  Also, see @ref{Four and Five Arguments, ,
texinfo.texi(,17057) @code{@@xref} with Four and Five Arguments}.)@refill
texinfo.texi(,17058) 
texinfo.texi(,17059) Include files were designed primarily as a way to create a single,
texinfo.texi(,17060) large printed manual out of several smaller Info files.  In a printed
texinfo.texi(,17061) manual, all the references were within the same document, so @TeX{}
texinfo.texi(,17062) could automatically determine the references' page numbers.  The Info
texinfo.texi(,17063) formatting commands used include files only for creating joint
texinfo.texi(,17064) indices; each of the individual Texinfo files had to be formatted for
texinfo.texi(,17065) Info individually.  (Each, therefore, required its own
texinfo.texi(,17066) @code{@@setfilename} line.)@refill
texinfo.texi(,17067) 
texinfo.texi(,17068) However, because large Info files are now split automatically, it is
texinfo.texi(,17069) no longer necessary to keep them small.@refill
texinfo.texi(,17070) 
texinfo.texi(,17071) Nowadays, multiple Texinfo files are used mostly for large documents,
texinfo.texi(,17072) such as @cite{The GNU Emacs Lisp Reference Manual}, and for projects
texinfo.texi(,17073) in which several different people write different sections of a
texinfo.texi(,17074) document simultaneously.@refill
texinfo.texi(,17075) 
texinfo.texi(,17076) In addition, the Info formatting commands have been extended to work
texinfo.texi(,17077) with the @code{@@include} command so as to create a single large Info
texinfo.texi(,17078) file that is split into smaller files if necessary.  This means that
texinfo.texi(,17079) you can write menus and cross references without naming the different
texinfo.texi(,17080) Texinfo files.@refill
texinfo.texi(,17081) 
texinfo.texi(,17082) 
texinfo.texi(,17083) @node Headings
texinfo.texi(,17084) @appendix Page Headings
texinfo.texi(,17085) @cindex Headings
texinfo.texi(,17086) @cindex Footings
texinfo.texi(,17087) @cindex Page numbering
texinfo.texi(,17088) @cindex Page headings
texinfo.texi(,17089) @cindex Formatting headings and footings
texinfo.texi(,17090) 
texinfo.texi(,17091) Most printed manuals contain headings along the top of every page
texinfo.texi(,17092) except the title and copyright pages.  Some manuals also contain
texinfo.texi(,17093) footings.  (Headings and footings have no meaning to Info, which is
texinfo.texi(,17094) not paginated.)@refill
texinfo.texi(,17095) 
texinfo.texi(,17096) @menu
texinfo.texi(,17097) * Headings Introduced::         Conventions for using page headings.
texinfo.texi(,17098) * Heading Format::              Standard page heading formats.
texinfo.texi(,17099) * Heading Choice::              How to specify the type of page heading.
texinfo.texi(,17100) * Custom Headings::             How to create your own headings and footings.
texinfo.texi(,17101) @end menu
texinfo.texi(,17102) 
texinfo.texi(,17103) @node Headings Introduced, Heading Format, Headings, Headings
texinfo.texi(,17105) @heading Headings Introduced
texinfo.texi(,17107) 
texinfo.texi(,17108) Texinfo provides standard page heading formats for manuals that are
texinfo.texi(,17109) printed on one side of each sheet of paper and for manuals that are
texinfo.texi(,17110) printed on both sides of the paper.  Typically, you will use these
texinfo.texi(,17111) formats, but you can specify your own format if you wish.@refill
texinfo.texi(,17112) 
texinfo.texi(,17113) In addition, you can specify whether chapters should begin on a new
texinfo.texi(,17114) page, or merely continue the same page as the previous chapter; and if
texinfo.texi(,17115) chapters begin on new pages, you can specify whether they must be
texinfo.texi(,17116) odd-numbered pages.@refill
texinfo.texi(,17117) 
texinfo.texi(,17118) By convention, a book is printed on both sides of each sheet of paper.
texinfo.texi(,17119) When you open a book, the right-hand page is odd-numbered, and
texinfo.texi(,17120) chapters begin on right-hand pages---a preceding left-hand page is
texinfo.texi(,17121) left blank if necessary.  Reports, however, are often printed on just
texinfo.texi(,17122) one side of paper, and chapters begin on a fresh page immediately
texinfo.texi(,17123) following the end of the preceding chapter.  In short or informal
texinfo.texi(,17124) reports, chapters often do not begin on a new page at all, but are
texinfo.texi(,17125) separated from the preceding text by a small amount of whitespace.@refill
texinfo.texi(,17126) 
texinfo.texi(,17127) The @code{@@setchapternewpage} command controls whether chapters begin
texinfo.texi(,17128) on new pages, and whether one of the standard heading formats is used.
texinfo.texi(,17129) In addition, Texinfo has several heading and footing commands that you
texinfo.texi(,17130) can use to generate your own heading and footing formats.@refill
texinfo.texi(,17131) 
texinfo.texi(,17132) In Texinfo, headings and footings are single lines at the tops and
texinfo.texi(,17133) bottoms of pages; you cannot create multiline headings or footings.
texinfo.texi(,17134) Each header or footer line is divided into three parts: a left part, a
texinfo.texi(,17135) middle part, and a right part.  Any part, or a whole line, may be left
texinfo.texi(,17136) blank.  Text for the left part of a header or footer line is set
texinfo.texi(,17137) flushleft; text for the middle part is centered; and, text for the
texinfo.texi(,17138) right part is set flushright.@refill
texinfo.texi(,17139) 
texinfo.texi(,17140) @node Heading Format, Heading Choice, Headings Introduced, Headings
texinfo.texi(,17141) @comment  node-name,  next,  previous,  up
texinfo.texi(,17142) @section Standard Heading Formats
texinfo.texi(,17143) 
texinfo.texi(,17144) Texinfo provides two standard heading formats, one for manuals printed
texinfo.texi(,17145) on one side of each sheet of paper, and the other for manuals printed
texinfo.texi(,17146) on both sides of the paper.
texinfo.texi(,17147) 
texinfo.texi(,17148) By default, nothing is specified for the footing of a Texinfo file,
texinfo.texi(,17149) so the footing remains blank.@refill
texinfo.texi(,17150) 
texinfo.texi(,17151) The standard format for single-sided printing consists of a header
texinfo.texi(,17152) line in which the left-hand part contains the name of the chapter, the
texinfo.texi(,17153) central part is blank, and the right-hand part contains the page
texinfo.texi(,17154) number.@refill
texinfo.texi(,17155) 
texinfo.texi(,17156) @need 950
texinfo.texi(,17157) A single-sided page looks like this:
texinfo.texi(,17158) 
texinfo.texi(,17159) @example
texinfo.texi(,17160) @group
texinfo.texi(,17161)    _______________________
texinfo.texi(,17162)   |                       |
texinfo.texi(,17163)   | chapter   page number |
texinfo.texi(,17164)   |                       |
texinfo.texi(,17165)   | Start of text ...     |
texinfo.texi(,17166)   | ...                   |
texinfo.texi(,17167)   |                       |
texinfo.texi(,17168) 
texinfo.texi(,17169) @end group
texinfo.texi(,17170) @end example
texinfo.texi(,17171) 
texinfo.texi(,17172) The standard format for two-sided printing depends on whether the page
texinfo.texi(,17173) number is even or odd.  By convention, even-numbered pages are on the
texinfo.texi(,17174) left- and odd-numbered pages are on the right.  (@TeX{} will adjust the
texinfo.texi(,17175) widths of the left- and right-hand margins.  Usually, widths are
texinfo.texi(,17176) correct, but during double-sided printing, it is wise to check that
texinfo.texi(,17177) pages will bind properly---sometimes a printer will produce output in
texinfo.texi(,17178) which the even-numbered pages have a larger right-hand margin than the
texinfo.texi(,17179) odd-numbered pages.)@refill
texinfo.texi(,17180) 
texinfo.texi(,17181) In the standard double-sided format, the left part of the left-hand
texinfo.texi(,17182) (even-numbered) page contains the page number, the central part is
texinfo.texi(,17183) blank, and the right part contains the title (specified by the
texinfo.texi(,17184) @code{@@settitle} command).  The left part of the right-hand
texinfo.texi(,17185) (odd-numbered) page contains the name of the chapter, the central part
texinfo.texi(,17186) is blank, and the right part contains the page number.@refill
texinfo.texi(,17187) 
texinfo.texi(,17188) @need 750
texinfo.texi(,17189) Two pages, side by side as in an open book, look like this:@refill
texinfo.texi(,17190) 
texinfo.texi(,17191) @example
texinfo.texi(,17192) @group
texinfo.texi(,17193)    _______________________     _______________________
texinfo.texi(,17194)   |                       |   |                       |
texinfo.texi(,17195)   | page number     title |   | chapter   page number |
texinfo.texi(,17196)   |                       |   |                       |
texinfo.texi(,17197)   | Start of text ...     |   | More  text ...        |
texinfo.texi(,17198)   | ...                   |   | ...                   |
texinfo.texi(,17199)   |                       |   |                       |
texinfo.texi(,17200) 
texinfo.texi(,17201) @end group
texinfo.texi(,17202) @end example
texinfo.texi(,17203) 
texinfo.texi(,17204) @noindent
texinfo.texi(,17205) The chapter name is preceded by the word ``Chapter'', the chapter number
texinfo.texi(,17206) and a colon.  This makes it easier to keep track of where you are in the
texinfo.texi(,17207) manual.@refill
texinfo.texi(,17208) 
texinfo.texi(,17209) @node Heading Choice, Custom Headings, Heading Format, Headings
texinfo.texi(,17210) @comment  node-name,  next,  previous,  up
texinfo.texi(,17211) @section Specifying the Type of Heading
texinfo.texi(,17212) 
texinfo.texi(,17213) @TeX{} does not begin to generate page headings for a standard Texinfo
texinfo.texi(,17214) file until it reaches the @code{@@end titlepage} command.  Thus, the
texinfo.texi(,17215) title and copyright pages are not numbered.  The @code{@@end
texinfo.texi(,17216) titlepage} command causes @TeX{} to begin to generate page headings
texinfo.texi(,17217) according to a standard format specified by the
texinfo.texi(,17218) @code{@@setchapternewpage} command that precedes the
texinfo.texi(,17219) @code{@@titlepage} section.@refill
texinfo.texi(,17220) 
texinfo.texi(,17221) @need 1000
texinfo.texi(,17222) There are four possibilities:@refill
texinfo.texi(,17223) 
texinfo.texi(,17224) @table @asis
texinfo.texi(,17225) @item No @code{@@setchapternewpage} command
texinfo.texi(,17226) Cause @TeX{} to specify the single-sided heading format, with chapters
texinfo.texi(,17227) on new pages. This is the same as @code{@@setchapternewpage on}.@refill
texinfo.texi(,17228) 
texinfo.texi(,17229) @item @code{@@setchapternewpage on}
texinfo.texi(,17230) Specify the single-sided heading format, with chapters on new pages.@refill
texinfo.texi(,17231) 
texinfo.texi(,17232) @item @code{@@setchapternewpage off}
texinfo.texi(,17233) Cause @TeX{} to start a new chapter on the same page as the last page of
texinfo.texi(,17234) the preceding chapter, after skipping some vertical whitespace.  Also
texinfo.texi(,17235) cause @TeX{} to typeset for single-sided printing.  (You can override
texinfo.texi(,17236) the headers format with the @code{@@headings double} command; see
texinfo.texi(,17237) @ref{headings on off, , The @code{@@headings} Command}.)@refill
texinfo.texi(,17238) 
texinfo.texi(,17239) @item @code{@@setchapternewpage odd}
texinfo.texi(,17240) Specify the double-sided heading format, with chapters on new pages.@refill
texinfo.texi(,17241) @end table
texinfo.texi(,17242) 
texinfo.texi(,17243) @noindent
texinfo.texi(,17244) Texinfo lacks an @code{@@setchapternewpage even} command.@refill
texinfo.texi(,17245) 
texinfo.texi(,17246) @node Custom Headings,  , Heading Choice, Headings
texinfo.texi(,17247) @comment  node-name,  next,  previous,  up
texinfo.texi(,17248) @section How to Make Your Own Headings
texinfo.texi(,17249) 
texinfo.texi(,17250) You can use the standard headings provided with Texinfo or specify
texinfo.texi(,17251) your own.  By default, Texinfo has no footers, so if you specify them,
texinfo.texi(,17252) the available page size for the main text will be slightly reduced.
texinfo.texi(,17253) 
texinfo.texi(,17254) Texinfo provides six commands for specifying headings and
texinfo.texi(,17255) footings:
texinfo.texi(,17256) @itemize @bullet
texinfo.texi(,17257) @item
texinfo.texi(,17258) @code{@@everyheading} @code{@@everyfooting} generate page headers and
texinfo.texi(,17259) footers that are the same for both even- and odd-numbered pages.
texinfo.texi(,17260) @item
texinfo.texi(,17261) @code{@@evenheading} and @code{@@evenfooting} command generate headers
texinfo.texi(,17262) and footers for even-numbered (left-hand) pages.
texinfo.texi(,17263) @item
texinfo.texi(,17264) @code{@@oddheading} and @code{@@oddfooting} generate headers and footers
texinfo.texi(,17265) for odd-numbered (right-hand) pages.
texinfo.texi(,17266) @end itemize
texinfo.texi(,17267) 
texinfo.texi(,17268) Write custom heading specifications in the Texinfo file immediately
texinfo.texi(,17269) after the @code{@@end titlepage} command.
texinfo.texi(,17270) You must cancel the predefined heading commands with the
texinfo.texi(,17271) @code{@@headings off} command before defining your own
texinfo.texi(,17272) specifications.@refill
texinfo.texi(,17273) 
texinfo.texi(,17274) @need 1000
texinfo.texi(,17275) Here is how to tell @TeX{} to place the chapter name at the left, the
texinfo.texi(,17276) page number in the center, and the date at the right of every header
texinfo.texi(,17277) for both even- and odd-numbered pages:@refill
texinfo.texi(,17278) 
texinfo.texi(,17279) @example
texinfo.texi(,17280) @group
texinfo.texi(,17281) @@headings off
texinfo.texi(,17282) @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
texinfo.texi(,17283) @end group
texinfo.texi(,17284) @end example
texinfo.texi(,17285) 
texinfo.texi(,17286) @noindent
texinfo.texi(,17287) You need to divide the left part from the central part and the central
texinfo.texi(,17288) part from the right part by inserting @samp{@@|} between parts.
texinfo.texi(,17289) Otherwise, the specification command will not be able to tell where
texinfo.texi(,17290) the text for one part ends and the next part begins.@refill
texinfo.texi(,17291) 
texinfo.texi(,17292) Each part can contain text or @@-commands.  The text
texinfo.texi(,17293) is printed as if the part were within an ordinary paragraph in the
texinfo.texi(,17294) body of the page.  The @@-commands replace
texinfo.texi(,17295) themselves with the page number, date, chapter name, or
texinfo.texi(,17296) whatever.@refill
texinfo.texi(,17297) 
texinfo.texi(,17298) @need 950
texinfo.texi(,17299) Here are the six heading and footing commands:@refill
texinfo.texi(,17300) 
texinfo.texi(,17301) @findex everyheading
texinfo.texi(,17302) @findex everyfooting
texinfo.texi(,17303) @table @code
texinfo.texi(,17304) @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
texinfo.texi(,17305) @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
texinfo.texi(,17306) 
texinfo.texi(,17307) The `every' commands specify the format for both even- and odd-numbered
texinfo.texi(,17308) pages.  These commands are for documents that are printed on one side
texinfo.texi(,17309) of each sheet of paper, or for documents in which you want symmetrical
texinfo.texi(,17310) headers or footers.@refill
texinfo.texi(,17311) 
texinfo.texi(,17312) @findex evenheading
texinfo.texi(,17313) @findex evenfooting
texinfo.texi(,17314) @findex oddheading
texinfo.texi(,17315) @findex oddfooting
texinfo.texi(,17316) @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
texinfo.texi(,17317) @itemx @@oddheading  @var{left} @@| @var{center} @@| @var{right}
texinfo.texi(,17318) 
texinfo.texi(,17319) @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
texinfo.texi(,17320) @itemx @@oddfooting  @var{left} @@| @var{center} @@| @var{right}
texinfo.texi(,17321) 
texinfo.texi(,17322) The `even' and `odd' commands specify the format for even-numbered
texinfo.texi(,17323) pages and odd-numbered pages.  These commands are for books and
texinfo.texi(,17324) manuals that are printed on both sides of each sheet of paper.
texinfo.texi(,17325) @end table
texinfo.texi(,17326) 
texinfo.texi(,17327) Use the @samp{@@this@dots{}} series of @@-commands to
texinfo.texi(,17328) provide the names of chapters
texinfo.texi(,17329) and sections and the page number.  You can use the
texinfo.texi(,17330) @samp{@@this@dots{}} commands in the left, center, or right portions
texinfo.texi(,17331) of headers and footers, or anywhere else in a Texinfo file so long as
texinfo.texi(,17332) they are between @code{@@iftex} and @code{@@end iftex} commands.@refill
texinfo.texi(,17333) 
texinfo.texi(,17334) @need 1000
texinfo.texi(,17335) Here are the @samp{@@this@dots{}} commands:@refill
texinfo.texi(,17336) 
texinfo.texi(,17337) @table @code
texinfo.texi(,17338) @findex thispage
texinfo.texi(,17339) @item @@thispage
texinfo.texi(,17340) Expands to the current page number.@refill
texinfo.texi(,17341) @c !!! Karl Berry says that `thissection' can fail on page breaks.
texinfo.texi(,17346) 
texinfo.texi(,17347) @findex thischaptername
texinfo.texi(,17348) @item @@thischaptername
texinfo.texi(,17349) Expands to the name of the current chapter.@refill
texinfo.texi(,17350) 
texinfo.texi(,17351) @findex thischapter
texinfo.texi(,17352) @item @@thischapter
texinfo.texi(,17353) Expands to the number and name of the current
texinfo.texi(,17354) chapter, in the format `Chapter 1: Title'.@refill
texinfo.texi(,17355) 
texinfo.texi(,17356) @findex thistitle
texinfo.texi(,17357) @item @@thistitle
texinfo.texi(,17358) Expands to the name of the document, as specified by the
texinfo.texi(,17359) @code{@@settitle} command.@refill
texinfo.texi(,17360) 
texinfo.texi(,17361) @findex thisfile
texinfo.texi(,17362) @item @@thisfile
texinfo.texi(,17363) For @code{@@include} files only: expands to the name of the current
texinfo.texi(,17364) @code{@@include} file.  If the current Texinfo source file is not an
texinfo.texi(,17365) @code{@@include} file, this command has no effect.  This command does
texinfo.texi(,17366) @emph{not} provide the name of the current Texinfo source file unless
texinfo.texi(,17367) it is an @code{@@include} file.  (@xref{Include Files}, for more
texinfo.texi(,17368) information about @code{@@include} files.)@refill
texinfo.texi(,17369) @end table
texinfo.texi(,17370) 
texinfo.texi(,17371) @noindent
texinfo.texi(,17372) You can also use the @code{@@today@{@}} command, which expands to the
texinfo.texi(,17373) current date, in `1 Jan 1900' format.@refill
texinfo.texi(,17374) @findex today
texinfo.texi(,17375) 
texinfo.texi(,17376) Other @@-commands and text are printed in a header or footer just as
texinfo.texi(,17377) if they were in the body of a page.  It is useful to incorporate text,
texinfo.texi(,17378) particularly when you are writing drafts:@refill
texinfo.texi(,17379) 
texinfo.texi(,17380) @example
texinfo.texi(,17381) @group
texinfo.texi(,17382) @@headings off
texinfo.texi(,17383) @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
texinfo.texi(,17384) @@everyfooting @@| @@| Version: 0.27: @@today@{@}
texinfo.texi(,17385) @end group
texinfo.texi(,17386) @end example
texinfo.texi(,17387) 
texinfo.texi(,17388) Beware of overlong titles: they may overlap another part of the
texinfo.texi(,17389) header or footer and blot it out.@refill
texinfo.texi(,17390) 
texinfo.texi(,17391) 
texinfo.texi(,17392) @node Catching Mistakes
texinfo.texi(,17393) @appendix Formatting Mistakes
texinfo.texi(,17394) @cindex Structure, catching mistakes in
texinfo.texi(,17395) @cindex Nodes, catching mistakes
texinfo.texi(,17396) @cindex Catching mistakes
texinfo.texi(,17397) @cindex Correcting mistakes
texinfo.texi(,17398) @cindex Mistakes, catching
texinfo.texi(,17399) @cindex Problems, catching
texinfo.texi(,17400) @cindex Debugging the Texinfo structure
texinfo.texi(,17401) 
texinfo.texi(,17402) Besides mistakes in the content of your documentation, there are two
texinfo.texi(,17403) kinds of mistake you can make with Texinfo: you can make mistakes with
texinfo.texi(,17404) @@-commands, and you can make mistakes with the structure of the nodes
texinfo.texi(,17405) and chapters.
texinfo.texi(,17406) 
texinfo.texi(,17407) Emacs has two tools for catching the @@-command mistakes and two for
texinfo.texi(,17408) catching structuring mistakes.@refill
texinfo.texi(,17409) 
texinfo.texi(,17410) For finding problems with @@-commands, you can run @TeX{} or a region
texinfo.texi(,17411) formatting command on the region that has a problem; indeed, you can
texinfo.texi(,17412) run these commands on each region as you write it.@refill
texinfo.texi(,17413) 
texinfo.texi(,17414) For finding problems with the structure of nodes and chapters, you can use
texinfo.texi(,17415) @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
texinfo.texi(,17416) command and you can use the @kbd{M-x Info-validate} command.@refill
texinfo.texi(,17417) 
texinfo.texi(,17418) @menu
texinfo.texi(,17419) * makeinfo Preferred::          @code{makeinfo} finds errors.
texinfo.texi(,17420) * Debugging with Info::         How to catch errors with Info formatting.
texinfo.texi(,17421) * Debugging with TeX::          How to catch errors with @TeX{} formatting.
texinfo.texi(,17422) * Using texinfo-show-structure::  How to use @code{texinfo-show-structure}.
texinfo.texi(,17423) * Using occur::                 How to list all lines containing a pattern.
texinfo.texi(,17424) * Running Info-Validate::       How to find badly referenced nodes.
texinfo.texi(,17425) @end menu
texinfo.texi(,17426) 
texinfo.texi(,17427) @node makeinfo Preferred, Debugging with Info, Catching Mistakes, Catching Mistakes
texinfo.texi(,17429) @heading @code{makeinfo} Find Errors
texinfo.texi(,17431) 
texinfo.texi(,17432) The @code{makeinfo} program does an excellent job of catching errors
texinfo.texi(,17433) and reporting them---far better than @code{texinfo-format-region} or
texinfo.texi(,17434) @code{texinfo-format-buffer}.  In addition, the various functions for
texinfo.texi(,17435) automatically creating and updating node pointers and menus remove
texinfo.texi(,17436) many opportunities for human error.@refill
texinfo.texi(,17437) 
texinfo.texi(,17438) If you can, use the updating commands to create and insert pointers
texinfo.texi(,17439) and menus.  These prevent many errors.  Then use @code{makeinfo} (or
texinfo.texi(,17440) its Texinfo mode manifestations, @code{makeinfo-region} and
texinfo.texi(,17441) @code{makeinfo-buffer}) to format your file and check for other
texinfo.texi(,17442) errors.  This is the best way to work with Texinfo.  But if you
texinfo.texi(,17443) cannot use @code{makeinfo}, or your problem is very puzzling, then you
texinfo.texi(,17444) may want to use the tools described in this appendix.@refill
texinfo.texi(,17445) 
texinfo.texi(,17446) @node Debugging with Info, Debugging with TeX, makeinfo Preferred, Catching Mistakes
texinfo.texi(,17447) @comment  node-name,  next,  previous,  up
texinfo.texi(,17448) @section Catching Errors with Info Formatting
texinfo.texi(,17449) @cindex Catching errors with Info formatting
texinfo.texi(,17450) @cindex Debugging with Info formatting
texinfo.texi(,17451) 
texinfo.texi(,17452) After you have written part of a Texinfo file, you can use the
texinfo.texi(,17453) @code{texinfo-format-region} or the @code{makeinfo-region} command to
texinfo.texi(,17454) see whether the region formats properly.@refill
texinfo.texi(,17455) 
texinfo.texi(,17456) Most likely, however, you are reading this section because for some
texinfo.texi(,17457) reason you cannot use the @code{makeinfo-region} command; therefore, the
texinfo.texi(,17458) rest of this section presumes that you are using
texinfo.texi(,17459) @code{texinfo-format-region}.@refill
texinfo.texi(,17460) 
texinfo.texi(,17461) If you have made a mistake with an @@-command,
texinfo.texi(,17462) @code{texinfo-format-region} will stop processing at or after the
texinfo.texi(,17463) error and display an error message.  To see where in the buffer the
texinfo.texi(,17464) error occurred, switch to the @samp{*Info Region*} buffer; the cursor
texinfo.texi(,17465) will be in a position that is after the location of the error.  Also,
texinfo.texi(,17466) the text will not be formatted after the place where the error
texinfo.texi(,17467) occurred (or more precisely, where it was detected).@refill
texinfo.texi(,17468) 
texinfo.texi(,17469) For example, if you accidentally end a menu with the command @code{@@end
texinfo.texi(,17470) menus} with an `s' on the end, instead of with @code{@@end menu}, you
texinfo.texi(,17471) will see an error message that says:@refill
texinfo.texi(,17472) 
texinfo.texi(,17473) @example
texinfo.texi(,17474) @@end menus is not handled by texinfo
texinfo.texi(,17475) @end example
texinfo.texi(,17476) 
texinfo.texi(,17477) @noindent
texinfo.texi(,17478) The cursor will stop at the point in the buffer where the error
texinfo.texi(,17479) occurs, or not long after it.  The buffer will look like this:@refill
texinfo.texi(,17480) 
texinfo.texi(,17481) @example
texinfo.texi(,17482) @group
texinfo.texi(,17483) ---------- Buffer: *Info Region* ----------
texinfo.texi(,17484) * Menu:
texinfo.texi(,17485) 
texinfo.texi(,17486) * Using texinfo-show-structure::  How to use
texinfo.texi(,17487)                                   `texinfo-show-structure'
texinfo.texi(,17488)                                   to catch mistakes.
texinfo.texi(,17489) * Running Info-Validate::         How to check for
texinfo.texi(,17490)                                   unreferenced nodes.
texinfo.texi(,17491) @@end menus
texinfo.texi(,17492) @point{}
texinfo.texi(,17493) ---------- Buffer: *Info Region* ----------
texinfo.texi(,17494) @end group
texinfo.texi(,17495) @end example
texinfo.texi(,17496) 
texinfo.texi(,17497) The @code{texinfo-format-region} command sometimes provides slightly
texinfo.texi(,17498) odd error messages.  For example, the following cross reference fails to format:@refill
texinfo.texi(,17499) 
texinfo.texi(,17500) @example
texinfo.texi(,17501) (@@xref@{Catching Mistakes, for more info.)
texinfo.texi(,17502) @end example
texinfo.texi(,17503) 
texinfo.texi(,17504) @noindent
texinfo.texi(,17505) In this case, @code{texinfo-format-region} detects the missing closing
texinfo.texi(,17506) brace but displays a message that says @samp{Unbalanced parentheses}
texinfo.texi(,17507) rather than @samp{Unbalanced braces}.  This is because the formatting
texinfo.texi(,17508) command looks for mismatches between braces as if they were
texinfo.texi(,17509) parentheses.@refill
texinfo.texi(,17510) 
texinfo.texi(,17511) Sometimes @code{texinfo-format-region} fails to detect mistakes.  For
texinfo.texi(,17512) example, in the following, the closing brace is swapped with the
texinfo.texi(,17513) closing parenthesis:@refill
texinfo.texi(,17514) 
texinfo.texi(,17515) @example
texinfo.texi(,17516) (@@xref@{Catching Mistakes), for more info.@}
texinfo.texi(,17517) @end example
texinfo.texi(,17518) 
texinfo.texi(,17519) @noindent
texinfo.texi(,17520) Formatting produces:
texinfo.texi(,17521) @example
texinfo.texi(,17522) (*Note for more info.: Catching Mistakes)
texinfo.texi(,17523) @end example
texinfo.texi(,17524) 
texinfo.texi(,17525) The only way for you to detect this error is to realize that the
texinfo.texi(,17526) reference should have looked like this:@refill
texinfo.texi(,17527) 
texinfo.texi(,17528) @example
texinfo.texi(,17529) (*Note Catching Mistakes::, for more info.)
texinfo.texi(,17530) @end example
texinfo.texi(,17531) 
texinfo.texi(,17532) Incidentally, if you are reading this node in Info and type @kbd{f
texinfo.texi(,17533) @key{RET}} (@code{Info-follow-reference}), you will generate an error
texinfo.texi(,17534) message that says:
texinfo.texi(,17535) 
texinfo.texi(,17536) @example
texinfo.texi(,17537) No such node: "Catching Mistakes) The only way @dots{}
texinfo.texi(,17538) @end example
texinfo.texi(,17539) 
texinfo.texi(,17540) @noindent
texinfo.texi(,17541) This is because Info perceives the example of the error as the first
texinfo.texi(,17542) cross reference in this node and if you type a @key{RET} immediately
texinfo.texi(,17543) after typing the Info @kbd{f} command, Info will attempt to go to the
texinfo.texi(,17544) referenced node.  If you type @kbd{f catch @key{TAB} @key{RET}}, Info
texinfo.texi(,17545) will complete the node name of the correctly written example and take
texinfo.texi(,17546) you to the `Catching Mistakes' node.  (If you try this, you can return
texinfo.texi(,17547) from the `Catching Mistakes' node by typing @kbd{l}
texinfo.texi(,17548) (@code{Info-last}).)
texinfo.texi(,17549) 
texinfo.texi(,17550) @c !!! section on using Elisp debugger ignored.
texinfo.texi(,17632) 
texinfo.texi(,17633) @node Debugging with TeX, Using texinfo-show-structure, Debugging with Info, Catching Mistakes
texinfo.texi(,17634) @comment  node-name,  next,  previous,  up
texinfo.texi(,17635) @section Catching Errors with @TeX{} Formatting
texinfo.texi(,17636) @cindex Catching errors with @TeX{} formatting
texinfo.texi(,17637) @cindex Debugging with @TeX{} formatting
texinfo.texi(,17638) 
texinfo.texi(,17639) You can also catch mistakes when you format a file with @TeX{}.@refill
texinfo.texi(,17640) 
texinfo.texi(,17641) Usually, you will want to do this after you have run
texinfo.texi(,17642) @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
texinfo.texi(,17643) the same file, because @code{texinfo-format-buffer} sometimes displays
texinfo.texi(,17644) error messages that make more sense than @TeX{}.  (@xref{Debugging
texinfo.texi(,17645) with Info}, for more information.)@refill
texinfo.texi(,17646) 
texinfo.texi(,17647) For example, @TeX{} was run on a Texinfo file, part of which is shown
texinfo.texi(,17648) here:@refill
texinfo.texi(,17649) 
texinfo.texi(,17650) @example
texinfo.texi(,17651) ---------- Buffer: texinfo.texi ----------
texinfo.texi(,17652) name of the Texinfo file as an extension.  The
texinfo.texi(,17653) @@samp@{??@} are `wildcards' that cause the shell to
texinfo.texi(,17654) substitute all the raw index files.  (@@xref@{sorting
texinfo.texi(,17655) indices, for more information about sorting
texinfo.texi(,17656) indices.)@@refill
texinfo.texi(,17657) ---------- Buffer: texinfo.texi ----------
texinfo.texi(,17658) @end example
texinfo.texi(,17659) 
texinfo.texi(,17660) @noindent
texinfo.texi(,17661) (The cross reference lacks a closing brace.)
texinfo.texi(,17662) @TeX{} produced the following output, after which it stopped:@refill
texinfo.texi(,17663) 
texinfo.texi(,17664) @example
texinfo.texi(,17665) ---------- Buffer: *tex-shell* ----------
texinfo.texi(,17666) Runaway argument?
texinfo.texi(,17667) @{sorting indices, for more information about sorting
texinfo.texi(,17668) indices.) @@refill @@ETC.
texinfo.texi(,17669) ! Paragraph ended before @@xref was complete.
texinfo.texi(,17670) <to be read again>
texinfo.texi(,17671)                    @@par
texinfo.texi(,17672) l.27
texinfo.texi(,17673) 
texinfo.texi(,17674) ?
texinfo.texi(,17675) ---------- Buffer: *tex-shell* ----------
texinfo.texi(,17676) @end example
texinfo.texi(,17677) 
texinfo.texi(,17678) In this case, @TeX{} produced an accurate and
texinfo.texi(,17679) understandable error message:
texinfo.texi(,17680) 
texinfo.texi(,17681) @example
texinfo.texi(,17682) Paragraph ended before @@xref was complete.
texinfo.texi(,17683) @end example
texinfo.texi(,17684) 
texinfo.texi(,17685) @noindent
texinfo.texi(,17686) @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
texinfo.texi(,17687) @samp{l.27} means that @TeX{} detected the problem on line 27 of the
texinfo.texi(,17688) Texinfo file.  The @samp{?} is the prompt @TeX{} uses in this
texinfo.texi(,17689) circumstance.@refill
texinfo.texi(,17690) 
texinfo.texi(,17691) Unfortunately, @TeX{} is not always so helpful, and sometimes you must
texinfo.texi(,17692) truly be a Sherlock Holmes to discover what went wrong.@refill
texinfo.texi(,17693) 
texinfo.texi(,17694) In any case, if you run into a problem like this, you can do one of three
texinfo.texi(,17695) things.@refill
texinfo.texi(,17696) 
texinfo.texi(,17697) @enumerate
texinfo.texi(,17698) @item
texinfo.texi(,17699) You can tell @TeX{} to continue running and ignore just this error by
texinfo.texi(,17700) typing @key{RET} at the @samp{?} prompt.@refill
texinfo.texi(,17701) 
texinfo.texi(,17702) @item
texinfo.texi(,17703) You can tell @TeX{} to continue running and to ignore all errors as best
texinfo.texi(,17704) it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
texinfo.texi(,17705) 
texinfo.texi(,17706) This is often the best thing to do.  However, beware: the one error
texinfo.texi(,17707) may produce a cascade of additional error messages as its consequences
texinfo.texi(,17708) are felt through the rest of the file.  To stop @TeX{} when it is
texinfo.texi(,17709) producing such an avalanche of error messages, type @kbd{C-c} (or
texinfo.texi(,17710) @kbd{C-c C-c}, if you are running a shell inside Emacs).
texinfo.texi(,17711) 
texinfo.texi(,17712) @item
texinfo.texi(,17713) You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
texinfo.texi(,17714) at the @samp{?} prompt.@refill
texinfo.texi(,17715) @end enumerate
texinfo.texi(,17716) 
texinfo.texi(,17717) If you are running @TeX{} inside Emacs, you need to switch to the shell
texinfo.texi(,17718) buffer and line at which @TeX{} offers the @samp{?} prompt.
texinfo.texi(,17719) 
texinfo.texi(,17720) Sometimes @TeX{} will format a file without producing error messages even
texinfo.texi(,17721) though there is a problem.  This usually occurs if a command is not ended
texinfo.texi(,17722) but @TeX{} is able to continue processing anyhow.  For example, if you fail
texinfo.texi(,17723) to end an itemized list with the @code{@@end itemize} command, @TeX{} will
texinfo.texi(,17724) write a DVI file that you can print out.  The only error message that
texinfo.texi(,17725) @TeX{} will give you is the somewhat mysterious comment that@refill
texinfo.texi(,17726) 
texinfo.texi(,17727) @example
texinfo.texi(,17728) (@@end occurred inside a group at level 1)
texinfo.texi(,17729) @end example
texinfo.texi(,17730) 
texinfo.texi(,17731) @noindent
texinfo.texi(,17732) However, if you print the DVI file, you will find that the text
texinfo.texi(,17733) of the file that follows the itemized list is entirely indented as if
texinfo.texi(,17734) it were part of the last item in the itemized list.  The error message
texinfo.texi(,17735) is the way @TeX{} says that it expected to find an @code{@@end}
texinfo.texi(,17736) command somewhere in the file; but that it could not determine where
texinfo.texi(,17737) it was needed.@refill
texinfo.texi(,17738) 
texinfo.texi(,17739) Another source of notoriously hard-to-find errors is a missing
texinfo.texi(,17740) @code{@@end group} command.  If you ever are stumped by
texinfo.texi(,17741) incomprehensible errors, look for a missing @code{@@end group} command
texinfo.texi(,17742) first.@refill
texinfo.texi(,17743) 
texinfo.texi(,17744) If the Texinfo file lacks header lines,
texinfo.texi(,17745) @TeX{} may stop in the
texinfo.texi(,17746) beginning of its run and display output that looks like the following.
texinfo.texi(,17747) The @samp{*} indicates that @TeX{} is waiting for input.@refill
texinfo.texi(,17748) 
texinfo.texi(,17749) @example
texinfo.texi(,17750) This is TeX, Version 3.14159 (Web2c 7.0)
texinfo.texi(,17751) (test.texinfo [1])
texinfo.texi(,17752) *
texinfo.texi(,17753) @end example
texinfo.texi(,17754) 
texinfo.texi(,17755) @noindent
texinfo.texi(,17756) In this case, simply type @kbd{\end @key{RET}} after the asterisk.  Then
texinfo.texi(,17757) write the header lines in the Texinfo file and run the @TeX{} command
texinfo.texi(,17758) again. (Note the use of the backslash, @samp{\}.  @TeX{} uses @samp{\}
texinfo.texi(,17759) instead of @samp{@@}; and in this circumstance, you are working
texinfo.texi(,17760) directly with @TeX{}, not with Texinfo.)@refill
texinfo.texi(,17761) 
texinfo.texi(,17762) @node Using texinfo-show-structure, Using occur, Debugging with TeX, Catching Mistakes
texinfo.texi(,17763) @comment  node-name,  next,  previous,  up
texinfo.texi(,17764) @section Using @code{texinfo-show-structure}
texinfo.texi(,17765) @cindex Showing the structure of a file
texinfo.texi(,17766) @findex texinfo-show-structure
texinfo.texi(,17767) 
texinfo.texi(,17768) It is not always easy to keep track of the nodes, chapters, sections, and
texinfo.texi(,17769) subsections of a Texinfo file.  This is especially true if you are revising
texinfo.texi(,17770) or adding to a Texinfo file that someone else has written.@refill
texinfo.texi(,17771) 
texinfo.texi(,17772) In GNU Emacs, in Texinfo mode, the @code{texinfo-show-structure}
texinfo.texi(,17773) command lists all the lines that begin with the @@-commands that
texinfo.texi(,17774) specify the structure: @code{@@chapter}, @code{@@section},
texinfo.texi(,17775) @code{@@appendix}, and so on.  With an argument (@w{@kbd{C-u}}
texinfo.texi(,17776) as prefix argument, if interactive),
texinfo.texi(,17777) the command also shows the @code{@@node} lines.  The
texinfo.texi(,17778) @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
texinfo.texi(,17779) Texinfo mode, by default.@refill
texinfo.texi(,17780) 
texinfo.texi(,17781) The lines are displayed in a buffer called the @samp{*Occur*} buffer,
texinfo.texi(,17782) indented by hierarchical level.  For example, here is a part of what was
texinfo.texi(,17783) produced by running @code{texinfo-show-structure} on this manual:@refill
texinfo.texi(,17784) 
texinfo.texi(,17785) @example
texinfo.texi(,17786) @group
texinfo.texi(,17787)  Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
texinfo.texi(,17788)  unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
texinfo.texi(,17789)  in buffer texinfo.texi.
texinfo.texi(,17790)  @dots{}
texinfo.texi(,17791)  4177:@@chapter Nodes
texinfo.texi(,17792)  4198:    @@heading Two Paths
texinfo.texi(,17793)  4231:    @@section Node and Menu Illustration
texinfo.texi(,17794)  4337:    @@section The @@code@{@@@@node@} Command
texinfo.texi(,17795)  4393:        @@subheading Choosing Node and Pointer Names
texinfo.texi(,17796)  4417:        @@subsection How to Write an @@code@{@@@@node@} Line
texinfo.texi(,17797)  4469:        @@subsection @@code@{@@@@node@} Line Tips
texinfo.texi(,17798)  @dots{}
texinfo.texi(,17799) @end group
texinfo.texi(,17800) @end example
texinfo.texi(,17801) 
texinfo.texi(,17802) This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
texinfo.texi(,17803) with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
texinfo.texi(,17804) commands respectively.  If you move your cursor into the @samp{*Occur*}
texinfo.texi(,17805) window, you can position the cursor over one of the lines and use the
texinfo.texi(,17806) @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
texinfo.texi(,17807) the corresponding spot in the Texinfo file.  @xref{Other Repeating
texinfo.texi(,17808) Search, , Using Occur, emacs, The GNU Emacs Manual}, for more
texinfo.texi(,17809) information about @code{occur-mode-goto-occurrence}.@refill
texinfo.texi(,17810) 
texinfo.texi(,17811) The first line in the @samp{*Occur*} window describes the @dfn{regular
texinfo.texi(,17812) expression} specified by @var{texinfo-heading-pattern}.  This regular
texinfo.texi(,17813) expression is the pattern that @code{texinfo-show-structure} looks for.
texinfo.texi(,17814) @xref{Regexps, , Using Regular Expressions, emacs, The GNU Emacs Manual},
texinfo.texi(,17815) for more information.@refill
texinfo.texi(,17816) 
texinfo.texi(,17817) When you invoke the @code{texinfo-show-structure} command, Emacs will
texinfo.texi(,17818) display the structure of the whole buffer.  If you want to see the
texinfo.texi(,17819) structure of just a part of the buffer, of one chapter, for example,
texinfo.texi(,17820) use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
texinfo.texi(,17821) region.  (@xref{Narrowing, , , emacs, The GNU Emacs Manual}.)  This is
texinfo.texi(,17822) how the example used above was generated.  (To see the whole buffer
texinfo.texi(,17823) again, use @kbd{C-x n w} (@code{widen}).)@refill
texinfo.texi(,17824) 
texinfo.texi(,17825) If you call @code{texinfo-show-structure} with a prefix argument by
texinfo.texi(,17826) typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
texinfo.texi(,17827) @code{@@node} as well as the lines beginning with the @@-sign commands
texinfo.texi(,17828) for @code{@@chapter}, @code{@@section}, and the like.@refill
texinfo.texi(,17829) 
texinfo.texi(,17830) You can remind yourself of the structure of a Texinfo file by looking at
texinfo.texi(,17831) the list in the @samp{*Occur*} window; and if you have mis-named a node
texinfo.texi(,17832) or left out a section, you can correct the mistake.@refill
texinfo.texi(,17833) 
texinfo.texi(,17834) @node Using occur, Running Info-Validate, Using texinfo-show-structure, Catching Mistakes
texinfo.texi(,17835) @comment  node-name,  next,  previous,  up
texinfo.texi(,17836) @section Using @code{occur}
texinfo.texi(,17837) @cindex Occurrences, listing with @code{@@occur}
texinfo.texi(,17838) @findex occur
texinfo.texi(,17839) 
texinfo.texi(,17840) Sometimes the @code{texinfo-show-structure} command produces too much
texinfo.texi(,17841) information.  Perhaps you want to remind yourself of the overall structure
texinfo.texi(,17842) of a Texinfo file, and are overwhelmed by the detailed list produced by
texinfo.texi(,17843) @code{texinfo-show-structure}.  In this case, you can use the @code{occur}
texinfo.texi(,17844) command directly.  To do this, type@refill
texinfo.texi(,17845) 
texinfo.texi(,17846) @example
texinfo.texi(,17847) @kbd{M-x occur}
texinfo.texi(,17848) @end example
texinfo.texi(,17849) 
texinfo.texi(,17850) @noindent
texinfo.texi(,17851) and then, when prompted, type a @dfn{regexp}, a regular expression for
texinfo.texi(,17852) the pattern you want to match.  (@xref{Regexps, , Regular Expressions,
texinfo.texi(,17853) emacs, The GNU Emacs Manual}.)  The @code{occur} command works from
texinfo.texi(,17854) the current location of the cursor in the buffer to the end of the
texinfo.texi(,17855) buffer.  If you want to run @code{occur} on the whole buffer, place
texinfo.texi(,17856) the cursor at the beginning of the buffer.@refill
texinfo.texi(,17857) 
texinfo.texi(,17858) For example, to see all the lines that contain the word
texinfo.texi(,17859) @samp{@@chapter} in them, just type @samp{@@chapter}.  This will
texinfo.texi(,17860) produce a list of the chapters.  It will also list all the sentences
texinfo.texi(,17861) with @samp{@@chapter} in the middle of the line.@refill
texinfo.texi(,17862) 
texinfo.texi(,17863) If you want to see only those lines that start with the word
texinfo.texi(,17864) @samp{@@chapter}, type @samp{^@@chapter} when prompted by
texinfo.texi(,17865) @code{occur}.  If you want to see all the lines that end with a word
texinfo.texi(,17866) or phrase, end the last word with a @samp{$}; for example,
texinfo.texi(,17867) @samp{catching mistakes$}.  This can be helpful when you want to see
texinfo.texi(,17868) all the nodes that are part of the same chapter or section and
texinfo.texi(,17869) therefore have the same `Up' pointer.@refill
texinfo.texi(,17870) 
texinfo.texi(,17871) @xref{Other Repeating Search, , Using Occur, emacs , The GNU Emacs Manual},
texinfo.texi(,17872) for more information.@refill
texinfo.texi(,17873) 
texinfo.texi(,17874) @node Running Info-Validate,  , Using occur, Catching Mistakes
texinfo.texi(,17875) @comment  node-name,  next,  previous,  up
texinfo.texi(,17876) @section Finding Badly Referenced Nodes
texinfo.texi(,17877) @findex Info-validate
texinfo.texi(,17878) @cindex Nodes, checking for badly referenced
texinfo.texi(,17879) @cindex Checking for badly referenced nodes
texinfo.texi(,17880) @cindex Looking for badly referenced nodes
texinfo.texi(,17881) @cindex Finding badly referenced nodes
texinfo.texi(,17882) @cindex Badly referenced nodes
texinfo.texi(,17883) 
texinfo.texi(,17884) You can use the @code{Info-validate} command to check whether any of
texinfo.texi(,17885) the `Next', `Previous', `Up' or other node pointers fail to point to a
texinfo.texi(,17886) node.  This command checks that every node pointer points to an
texinfo.texi(,17887) existing node.  The @code{Info-validate} command works only on Info
texinfo.texi(,17888) files, not on Texinfo files.@refill
texinfo.texi(,17889) 
texinfo.texi(,17890) The @code{makeinfo} program validates pointers automatically, so you
texinfo.texi(,17891) do not need to use the @code{Info-validate} command if you are using
texinfo.texi(,17892) @code{makeinfo}.  You only may need to use @code{Info-validate} if you
texinfo.texi(,17893) are unable to run @code{makeinfo} and instead must create an Info file
texinfo.texi(,17894) using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
texinfo.texi(,17895) if you write an Info file from scratch.@refill
texinfo.texi(,17896) 
texinfo.texi(,17897) @menu
texinfo.texi(,17898) * Using Info-validate::         How to run @code{Info-validate}.
texinfo.texi(,17899) * Unsplit::                     How to create an unsplit file.
texinfo.texi(,17900) * Tagifying::                   How to tagify a file.
texinfo.texi(,17901) * Splitting::                   How to split a file manually.
texinfo.texi(,17902) @end menu
texinfo.texi(,17903) 
texinfo.texi(,17904) @node Using Info-validate, Unsplit, Running Info-Validate, Running Info-Validate
texinfo.texi(,17905) @subsection Running @code{Info-validate}
texinfo.texi(,17906) @cindex Running @code{Info-validate}
texinfo.texi(,17907) @cindex Info validating a large file
texinfo.texi(,17908) @cindex Validating a large file
texinfo.texi(,17909) 
texinfo.texi(,17910) To use @code{Info-validate}, visit the Info file you wish to check and
texinfo.texi(,17911) type:@refill
texinfo.texi(,17912) 
texinfo.texi(,17913) @example
texinfo.texi(,17914) M-x Info-validate
texinfo.texi(,17915) @end example
texinfo.texi(,17916) 
texinfo.texi(,17917) @noindent
texinfo.texi(,17918) Note that the @code{Info-validate} command requires an upper case
texinfo.texi(,17919) `I'.  You may also need to create a tag table before running
texinfo.texi(,17920) @code{Info-validate}.  @xref{Tagifying}.
texinfo.texi(,17921) 
texinfo.texi(,17922) If your file is valid, you will receive a message that says ``File appears
texinfo.texi(,17923) valid''.  However, if you have a pointer that does not point to a node,
texinfo.texi(,17924) error messages will be displayed in a buffer called @samp{*problems in
texinfo.texi(,17925) info file*}.@refill
texinfo.texi(,17926) 
texinfo.texi(,17927) For example, @code{Info-validate} was run on a test file that contained
texinfo.texi(,17928) only the first node of this manual.  One of the messages said:@refill
texinfo.texi(,17929) 
texinfo.texi(,17930) @example
texinfo.texi(,17931) In node "Overview", invalid Next: Texinfo Mode
texinfo.texi(,17932) @end example
texinfo.texi(,17933) 
texinfo.texi(,17934) @noindent
texinfo.texi(,17935) This meant that the node called @samp{Overview} had a `Next' pointer that
texinfo.texi(,17936) did not point to anything (which was true in this case, since the test file
texinfo.texi(,17937) had only one node in it).@refill
texinfo.texi(,17938) 
texinfo.texi(,17939) Now suppose we add a node named @samp{Texinfo Mode} to our test case
texinfo.texi(,17940) but we do not specify a `Previous' for this node.  Then we will get
texinfo.texi(,17941) the following error message:@refill
texinfo.texi(,17942) 
texinfo.texi(,17943) @example
texinfo.texi(,17944) In node "Texinfo Mode", should have Previous: Overview
texinfo.texi(,17945) @end example
texinfo.texi(,17946) 
texinfo.texi(,17947) @noindent
texinfo.texi(,17948) This is because every `Next' pointer should be matched by a
texinfo.texi(,17949) `Previous' (in the node where the `Next' points) which points back.@refill
texinfo.texi(,17950) 
texinfo.texi(,17951) @code{Info-validate} also checks that all menu entries and cross references
texinfo.texi(,17952) point to actual nodes.@refill
texinfo.texi(,17953) 
texinfo.texi(,17954) @code{Info-validate} requires a tag table and does not work with files
texinfo.texi(,17955) that have been split.  (The @code{texinfo-format-buffer} command
texinfo.texi(,17956) automatically splits large files.)  In order to use @code{Info-validate}
texinfo.texi(,17957) on a large file, you must run @code{texinfo-format-buffer} with an
texinfo.texi(,17958) argument so that it does not split the Info file; and you must create a
texinfo.texi(,17959) tag table for the unsplit file.
texinfo.texi(,17960) 
texinfo.texi(,17961) @node Unsplit, Tagifying, Using Info-validate, Running Info-Validate
texinfo.texi(,17962) @comment  node-name,  next,  previous,  up
texinfo.texi(,17963) @subsection Creating an Unsplit File
texinfo.texi(,17964) @cindex Creating an unsplit file
texinfo.texi(,17965) @cindex Unsplit file creation
texinfo.texi(,17966) 
texinfo.texi(,17967) You can run @code{Info-validate} only on a single Info file that has a
texinfo.texi(,17968) tag table.  The command will not work on the indirect subfiles that
texinfo.texi(,17969) are generated when a master file is split.  If you have a large file
texinfo.texi(,17970) (longer than 70,000 bytes or so), you need to run the
texinfo.texi(,17971) @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
texinfo.texi(,17972) a way that it does not create indirect subfiles.  You will also need
texinfo.texi(,17973) to create a tag table for the Info file.  After you have done this,
texinfo.texi(,17974) you can run @code{Info-validate} and look for badly referenced
texinfo.texi(,17975) nodes.@refill
texinfo.texi(,17976) 
texinfo.texi(,17977) The first step is to create an unsplit Info file.  To prevent
texinfo.texi(,17978) @code{texinfo-format-buffer} from splitting a Texinfo file into
texinfo.texi(,17979) smaller Info files, give a prefix to the @kbd{M-x
texinfo.texi(,17980) texinfo-format-buffer} command:@refill
texinfo.texi(,17981) 
texinfo.texi(,17982) @example
texinfo.texi(,17983) C-u M-x texinfo-format-buffer
texinfo.texi(,17984) @end example
texinfo.texi(,17985) 
texinfo.texi(,17986) @noindent
texinfo.texi(,17987) or else
texinfo.texi(,17988) 
texinfo.texi(,17989) @example
texinfo.texi(,17990) C-u C-c C-e C-b
texinfo.texi(,17991) @end example
texinfo.texi(,17992) 
texinfo.texi(,17993) @noindent
texinfo.texi(,17994) When you do this, Texinfo will not split the file and will not create
texinfo.texi(,17995) a tag table for it. @refill
texinfo.texi(,17996) @cindex Making a tag table manually
texinfo.texi(,17997) @cindex Tag table, making manually
texinfo.texi(,17998) 
texinfo.texi(,17999) @node Tagifying, Splitting, Unsplit, Running Info-Validate
texinfo.texi(,18000) @subsection Tagifying a File
texinfo.texi(,18001) 
texinfo.texi(,18002) After creating an unsplit Info file, you must create a tag table for
texinfo.texi(,18003) it.  Visit the Info file you wish to tagify and type:@refill
texinfo.texi(,18004) 
texinfo.texi(,18005) @example
texinfo.texi(,18006) M-x Info-tagify
texinfo.texi(,18007) @end example
texinfo.texi(,18008) 
texinfo.texi(,18009) @noindent
texinfo.texi(,18010) (Note the upper case @samp{I} in @code{Info-tagify}.)  This creates an
texinfo.texi(,18011) Info file with a tag table that you can validate.@refill
texinfo.texi(,18012) 
texinfo.texi(,18013) The third step is to validate the Info file:@refill
texinfo.texi(,18014) 
texinfo.texi(,18015) @example
texinfo.texi(,18016) M-x Info-validate
texinfo.texi(,18017) @end example
texinfo.texi(,18018) 
texinfo.texi(,18019) @noindent
texinfo.texi(,18020) (Note the upper case @samp{I} in @code{Info-validate}.)
texinfo.texi(,18021) In brief, the steps are:@refill
texinfo.texi(,18022) 
texinfo.texi(,18023) @example
texinfo.texi(,18024) @group
texinfo.texi(,18025) C-u M-x texinfo-format-buffer
texinfo.texi(,18026) M-x Info-tagify
texinfo.texi(,18027) M-x Info-validate
texinfo.texi(,18028) @end group
texinfo.texi(,18029) @end example
texinfo.texi(,18030) 
texinfo.texi(,18031) After you have validated the node structure, you can rerun
texinfo.texi(,18032) @code{texinfo-format-buffer} in the normal way so it will construct a
texinfo.texi(,18033) tag table and split the file automatically, or you can make the tag
texinfo.texi(,18034) table and split the file manually.@refill
texinfo.texi(,18035) 
texinfo.texi(,18036) @node Splitting,  , Tagifying, Running Info-Validate
texinfo.texi(,18037) @comment  node-name,  next,  previous,  up
texinfo.texi(,18038) @subsection Splitting a File Manually
texinfo.texi(,18039) @cindex Splitting an Info file manually
texinfo.texi(,18040) @cindex Info file, splitting manually
texinfo.texi(,18041) 
texinfo.texi(,18042) You should split a large file or else let the
texinfo.texi(,18043) @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
texinfo.texi(,18044) for you automatically.  (Generally you will let one of the formatting
texinfo.texi(,18045) commands do this job for you.  @xref{Creating an Info File}.)@refill
texinfo.texi(,18046) 
texinfo.texi(,18047) The split-off files are called the indirect subfiles.@refill
texinfo.texi(,18048) 
texinfo.texi(,18049) Info files are split to save memory.  With smaller files, Emacs does not
texinfo.texi(,18050) have make such a large buffer to hold the information.@refill
texinfo.texi(,18051) 
texinfo.texi(,18052) If an Info file has more than 30 nodes, you should also make a tag
texinfo.texi(,18053) table for it. @xref{Using Info-validate}, for information
texinfo.texi(,18054) about creating a tag table.  (Again, tag tables are usually created
texinfo.texi(,18055) automatically by the formatting command; you only need to create a tag
texinfo.texi(,18056) table yourself if you are doing the job manually.  Most likely, you
texinfo.texi(,18057) will do this for a large, unsplit file on which you have run
texinfo.texi(,18058) @code{Info-validate}.)@refill
texinfo.texi(,18059) 
texinfo.texi(,18060) @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
texinfo.texi(,18066) 
texinfo.texi(,18067) Visit the Info file you wish to tagify and split and type the two
texinfo.texi(,18068) commands:@refill
texinfo.texi(,18069) 
texinfo.texi(,18070) @example
texinfo.texi(,18071) M-x Info-tagify
texinfo.texi(,18072) M-x Info-split
texinfo.texi(,18073) @end example
texinfo.texi(,18074) 
texinfo.texi(,18075) @noindent
texinfo.texi(,18076) (Note that the @samp{I} in @samp{Info} is upper case.)@refill
texinfo.texi(,18077) 
texinfo.texi(,18078) When you use the @code{Info-split} command, the buffer is modified into a
texinfo.texi(,18079) (small) Info file which lists the indirect subfiles.  This file should be
texinfo.texi(,18080) saved in place of the original visited file.  The indirect subfiles are
texinfo.texi(,18081) written in the same directory the original file is in, with names generated
texinfo.texi(,18082) by appending @samp{-} and a number to the original file name.@refill
texinfo.texi(,18083) 
texinfo.texi(,18084) The primary file still functions as an Info file, but it contains just
texinfo.texi(,18085) the tag table and a directory of subfiles.@refill
texinfo.texi(,18086) 
texinfo.texi(,18087) 
texinfo.texi(,18088) @node Refilling Paragraphs
texinfo.texi(,18089) @appendix Refilling Paragraphs
texinfo.texi(,18090) @cindex Refilling paragraphs
texinfo.texi(,18091) @cindex Filling paragraphs
texinfo.texi(,18092) @cindex Paragraphs, filling
texinfo.texi(,18093) @findex refill
texinfo.texi(,18094) 
texinfo.texi(,18095) The @code{@@refill} command refills and, optionally, indents the first
texinfo.texi(,18096) line of a paragraph.@footnote{Perhaps the command should have been
texinfo.texi(,18097) called the @code{@@refillandindent} command, but @code{@@refill} is
texinfo.texi(,18098) shorter and the name was chosen before indenting was possible.} The
texinfo.texi(,18099) @code{@@refill} command is no longer important, but we describe it here
texinfo.texi(,18100) because you once needed it.  You will see it in many old Texinfo
texinfo.texi(,18101) files.@refill
texinfo.texi(,18102) 
texinfo.texi(,18103) Without refilling, paragraphs containing long @@-constructs may look
texinfo.texi(,18104) bad after formatting because the formatter removes @@-commands and
texinfo.texi(,18105) shortens some lines more than others.  In the past, neither the
texinfo.texi(,18106) @code{texinfo-format-region} command nor the
texinfo.texi(,18107) @code{texinfo-format-buffer} command refilled paragraphs
texinfo.texi(,18108) automatically.  The @code{@@refill} command had to be written at the
texinfo.texi(,18109) end of every paragraph to cause these formatters to fill them.  (Both
texinfo.texi(,18110) @TeX{} and @code{makeinfo} have always refilled paragraphs
texinfo.texi(,18111) automatically.)  Now, all the Info formatters automatically fill and
texinfo.texi(,18112) indent those paragraphs that need to be filled and indented.@refill
texinfo.texi(,18113) 
texinfo.texi(,18114) The @code{@@refill} command causes @code{texinfo-format-region} and
texinfo.texi(,18115) @code{texinfo-format-buffer} to refill a paragraph in the Info file
texinfo.texi(,18116) @emph{after} all the other processing has been done.  For this reason,
texinfo.texi(,18117) you can not use @code{@@refill} with a paragraph containing either
texinfo.texi(,18118) @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
texinfo.texi(,18119) override those two commands.@refill
texinfo.texi(,18120) 
texinfo.texi(,18121) The @code{texinfo-format-region} and @code{texinfo-format-buffer}
texinfo.texi(,18122) commands now automatically append @code{@@refill} to the end of each
texinfo.texi(,18123) paragraph that should be filled.  They do not append @code{@@refill} to
texinfo.texi(,18124) the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
texinfo.texi(,18125) and therefore do not refill or indent them.@refill
texinfo.texi(,18126) 
texinfo.texi(,18127) 
texinfo.texi(,18128) @node Command Syntax
texinfo.texi(,18129) @appendix @@-Command Syntax
texinfo.texi(,18130) @cindex @@-command syntax
texinfo.texi(,18131) @cindex Syntax, of @@-commands
texinfo.texi(,18132) @cindex Command syntax
texinfo.texi(,18133) 
texinfo.texi(,18134) The character @samp{@@} is used to start special Texinfo commands.
texinfo.texi(,18135) (It has the same meaning that @samp{\} has in plain @TeX{}.)  Texinfo
texinfo.texi(,18136) has four types of @@-command:@refill
texinfo.texi(,18137) 
texinfo.texi(,18138) @table @asis
texinfo.texi(,18139) @item 1. Non-alphabetic commands.
texinfo.texi(,18140) These commands consist of an @@ followed by a punctuation mark or other
texinfo.texi(,18141) character that is not part of the alphabet.  Non-alphabetic commands are
texinfo.texi(,18142) almost always part of the text within a paragraph, and never take any
texinfo.texi(,18143) argument.  The two characters (@@ and the other one) are complete in
texinfo.texi(,18144) themselves; none is followed by braces.  The non-alphabetic commands
texinfo.texi(,18145) are: @code{@@.}, @code{@@:}, @code{@@*}, @code{@@@kbd{SPACE}},
texinfo.texi(,18146) @code{@@@kbd{TAB}}, @code{@@@kbd{NL}}, @code{@@@@}, @code{@@@{}, and
texinfo.texi(,18147) @code{@@@}}.@refill
texinfo.texi(,18148) 
texinfo.texi(,18149) @item 2. Alphabetic commands that do not require arguments.
texinfo.texi(,18150) These commands start with @@ followed by a word followed by left- and
texinfo.texi(,18151) right-hand braces.  These commands insert special symbols in the
texinfo.texi(,18152) document; they do not require arguments.  For example,
texinfo.texi(,18153) @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
texinfo.texi(,18154) @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
texinfo.texi(,18155) and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
texinfo.texi(,18156) 
texinfo.texi(,18157) @item 3. Alphabetic commands that require arguments within braces.
texinfo.texi(,18158) These commands start with @@ followed by a letter or a word, followed by an
texinfo.texi(,18159) argument within braces.  For example, the command @code{@@dfn} indicates
texinfo.texi(,18160) the introductory or defining use of a term; it is used as follows: @samp{In
texinfo.texi(,18161) Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
texinfo.texi(,18162) 
texinfo.texi(,18163) @item 4. Alphabetic commands that occupy an entire line.
texinfo.texi(,18164) These commands occupy an entire line.  The line starts with @@,
texinfo.texi(,18165) followed by the name of the command (a word); for example, @code{@@center}
texinfo.texi(,18166) or @code{@@cindex}.  If no argument is needed, the word is followed by
texinfo.texi(,18167) the end of the line.  If there is an argument, it is separated from
texinfo.texi(,18168) the command name by a space.  Braces are not used.@refill
texinfo.texi(,18169) @end table
texinfo.texi(,18170) 
texinfo.texi(,18171) @cindex Braces and argument syntax
texinfo.texi(,18172) Thus, the alphabetic commands fall into classes that have
texinfo.texi(,18173) different argument syntaxes.  You cannot tell to which class a command
texinfo.texi(,18174) belongs by the appearance of its name, but you can tell by the
texinfo.texi(,18175) command's meaning: if the command stands for a glyph, it is in
texinfo.texi(,18176) class 2 and does not require an argument; if it makes sense to use the
texinfo.texi(,18177) command together with other text as part of a paragraph, the command
texinfo.texi(,18178) is in class 3 and must be followed by an argument in braces;
texinfo.texi(,18179) otherwise, it is in class 4 and uses the rest of the line as its
texinfo.texi(,18180) argument.@refill
texinfo.texi(,18181) 
texinfo.texi(,18182) The purpose of having a different syntax for commands of classes 3 and
texinfo.texi(,18183) 4 is to make Texinfo files easier to read, and also to help the GNU
texinfo.texi(,18184) Emacs paragraph and filling commands work properly.  There is only one
texinfo.texi(,18185) exception to this rule: the command @code{@@refill}, which is always
texinfo.texi(,18186) used at the end of a paragraph immediately following the final period
texinfo.texi(,18187) or other punctuation character.  @code{@@refill} takes no argument and
texinfo.texi(,18188) does @emph{not} require braces.  @code{@@refill} never confuses the
texinfo.texi(,18189) Emacs paragraph commands because it cannot appear at the beginning of
texinfo.texi(,18190) a line.@refill
texinfo.texi(,18191) 
texinfo.texi(,18192) 
texinfo.texi(,18193) @node Obtaining TeX
texinfo.texi(,18194) @appendix How to Obtain @TeX{}
texinfo.texi(,18195) @cindex Obtaining @TeX{}
texinfo.texi(,18196) @cindex @TeX{}, how to obtain
texinfo.texi(,18197) 
texinfo.texi(,18198) @c !!! Here is information about obtaining TeX.  Update it whenever.
texinfo.texi(,18199) @c !!! Also consider updating TeX.README on ftp.gnu.org.
texinfo.texi(,18200) @c     Updated by RJC on 1 March 1995, conversation with MacKay.
texinfo.texi(,18201) @c     Updated by kb@cs.umb.edu on 29 July 1996.
texinfo.texi(,18202) @c     Updated by kb@cs.umb.edu on 25 April 1997.
texinfo.texi(,18203) @c     Updated by kb@cs.umb.edu on 27 February 1998.
texinfo.texi(,18204) @TeX{} is freely redistributable.  You can obtain @TeX{} for Unix
texinfo.texi(,18205) systems via anonymous ftp or on physical media.  The core material
texinfo.texi(,18206) consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
texinfo.texi(,18207) 
texinfo.texi(,18208) Instructions for retrieval by anonymous ftp and information on other
texinfo.texi(,18209) available distributions:
texinfo.texi(,18210) @example
texinfo.texi(,18211) @uref{ftp://tug.org/tex/unixtex.ftp}
texinfo.texi(,18212) @uref{http://tug.org/unixtex.ftp}
texinfo.texi(,18213) @end example
texinfo.texi(,18214) 
texinfo.texi(,18215) The Free Software Foundation provides a core distribution on its Source
texinfo.texi(,18216) Code CD-ROM suitable for printing Texinfo manuals.  To order it, contact:
texinfo.texi(,18217) 
texinfo.texi(,18218) @display
texinfo.texi(,18219) @group
texinfo.texi(,18220) Free Software Foundation, Inc.
texinfo.texi(,18221) 59 Temple Place Suite 330
texinfo.texi(,18222) Boston, MA @ @ 02111-1307
texinfo.texi(,18223) USA
texinfo.texi(,18224) Telephone: @w{+1-617-542-5942}
texinfo.texi(,18225) Fax: (including Japan) @w{+1-617-542-2652}
texinfo.texi(,18226) Free Dial Fax (in Japan):
texinfo.texi(,18227) @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
texinfo.texi(,18228) @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
texinfo.texi(,18229) Electronic mail: @code{gnu@@gnu.org}
texinfo.texi(,18230) @end group
texinfo.texi(,18231) @end display
texinfo.texi(,18232) 
texinfo.texi(,18233) Many other @TeX{} distributions are available; see
texinfo.texi(,18234) @uref{http://tug.org/}.
texinfo.texi(,18235) 
texinfo.texi(,18236) 
texinfo.texi(,18237) @c These are no longer ``new'', and the explanations
texinfo.texi(,18238) @c are all given elsewhere anyway, I think.  --karl, 25apr97.
texinfo.texi(,18239) @c So ignore the entire appendix.
texinfo.texi(,18726) 
texinfo.texi(,18727) 
texinfo.texi(,18728) @node Copying This Manual
texinfo.texi(,18729) @appendix Copying This Manual
texinfo.texi(,18730) 
texinfo.texi(,18731) @menu
texinfo.texi(,18732) * GNU Free Documentation License::  License for copying this manual.
texinfo.texi(,18733) @end menu
texinfo.texi(,18734) 
fdl.texi(,1) 
fdl.texi(,2) @node GNU Free Documentation License
fdl.texi(,3) @appendixsec GNU Free Documentation License
fdl.texi(,4) 
fdl.texi(,5) @cindex FDL, GNU Free Documentation License
fdl.texi(,6) @center Version 1.1, March 2000
fdl.texi(,7) 
fdl.texi(,8) @display
fdl.texi(,9) Copyright @copyright{} 2000 Free Software Foundation, Inc.
fdl.texi(,10) 59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
fdl.texi(,11) 
fdl.texi(,12) Everyone is permitted to copy and distribute verbatim copies
fdl.texi(,13) of this license document, but changing it is not allowed.
fdl.texi(,14) @end display
fdl.texi(,15) 
fdl.texi(,16) @enumerate 0
fdl.texi(,17) @item
fdl.texi(,18) PREAMBLE
fdl.texi(,19) 
fdl.texi(,20) The purpose of this License is to make a manual, textbook, or other
fdl.texi(,21) written document @dfn{free} in the sense of freedom: to assure everyone
fdl.texi(,22) the effective freedom to copy and redistribute it, with or without
fdl.texi(,23) modifying it, either commercially or noncommercially.  Secondarily,
fdl.texi(,24) this License preserves for the author and publisher a way to get
fdl.texi(,25) credit for their work, while not being considered responsible for
fdl.texi(,26) modifications made by others.
fdl.texi(,27) 
fdl.texi(,28) This License is a kind of ``copyleft'', which means that derivative
fdl.texi(,29) works of the document must themselves be free in the same sense.  It
fdl.texi(,30) complements the GNU General Public License, which is a copyleft
fdl.texi(,31) license designed for free software.
fdl.texi(,32) 
fdl.texi(,33) We have designed this License in order to use it for manuals for free
fdl.texi(,34) software, because free software needs free documentation: a free
fdl.texi(,35) program should come with manuals providing the same freedoms that the
fdl.texi(,36) software does.  But this License is not limited to software manuals;
fdl.texi(,37) it can be used for any textual work, regardless of subject matter or
fdl.texi(,38) whether it is published as a printed book.  We recommend this License
fdl.texi(,39) principally for works whose purpose is instruction or reference.
fdl.texi(,40) 
fdl.texi(,41) @item
fdl.texi(,42) APPLICABILITY AND DEFINITIONS
fdl.texi(,43) 
fdl.texi(,44) This License applies to any manual or other work that contains a
fdl.texi(,45) notice placed by the copyright holder saying it can be distributed
fdl.texi(,46) under the terms of this License.  The ``Document'', below, refers to any
fdl.texi(,47) such manual or work.  Any member of the public is a licensee, and is
fdl.texi(,48) addressed as ``you''.
fdl.texi(,49) 
fdl.texi(,50) A ``Modified Version'' of the Document means any work containing the
fdl.texi(,51) Document or a portion of it, either copied verbatim, or with
fdl.texi(,52) modifications and/or translated into another language.
fdl.texi(,53) 
fdl.texi(,54) A ``Secondary Section'' is a named appendix or a front-matter section of
fdl.texi(,55) the Document that deals exclusively with the relationship of the
fdl.texi(,56) publishers or authors of the Document to the Document's overall subject
fdl.texi(,57) (or to related matters) and contains nothing that could fall directly
fdl.texi(,58) within that overall subject.  (For example, if the Document is in part a
fdl.texi(,59) textbook of mathematics, a Secondary Section may not explain any
fdl.texi(,60) mathematics.)  The relationship could be a matter of historical
fdl.texi(,61) connection with the subject or with related matters, or of legal,
fdl.texi(,62) commercial, philosophical, ethical or political position regarding
fdl.texi(,63) them.
fdl.texi(,64) 
fdl.texi(,65) The ``Invariant Sections'' are certain Secondary Sections whose titles
fdl.texi(,66) are designated, as being those of Invariant Sections, in the notice
fdl.texi(,67) that says that the Document is released under this License.
fdl.texi(,68) 
fdl.texi(,69) The ``Cover Texts'' are certain short passages of text that are listed,
fdl.texi(,70) as Front-Cover Texts or Back-Cover Texts, in the notice that says that
fdl.texi(,71) the Document is released under this License.
fdl.texi(,72) 
fdl.texi(,73) A ``Transparent'' copy of the Document means a machine-readable copy,
fdl.texi(,74) represented in a format whose specification is available to the
fdl.texi(,75) general public, whose contents can be viewed and edited directly and
fdl.texi(,76) straightforwardly with generic text editors or (for images composed of
fdl.texi(,77) pixels) generic paint programs or (for drawings) some widely available
fdl.texi(,78) drawing editor, and that is suitable for input to text formatters or
fdl.texi(,79) for automatic translation to a variety of formats suitable for input
fdl.texi(,80) to text formatters.  A copy made in an otherwise Transparent file
fdl.texi(,81) format whose markup has been designed to thwart or discourage
fdl.texi(,82) subsequent modification by readers is not Transparent.  A copy that is
fdl.texi(,83) not ``Transparent'' is called ``Opaque''.
fdl.texi(,84) 
fdl.texi(,85) Examples of suitable formats for Transparent copies include plain
fdl.texi(,86) @sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
fdl.texi(,87) @acronym{SGML} or @acronym{XML} using a publicly available
fdl.texi(,88) @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
fdl.texi(,89) for human modification.  Opaque formats include PostScript,
fdl.texi(,90) @acronym{PDF}, proprietary formats that can be read and edited only by
fdl.texi(,91) proprietary word processors, @acronym{SGML} or @acronym{XML} for which
fdl.texi(,92) the @acronym{DTD} and/or processing tools are not generally available,
fdl.texi(,93) and the machine-generated @acronym{HTML} produced by some word
fdl.texi(,94) processors for output purposes only.
fdl.texi(,95) 
fdl.texi(,96) The ``Title Page'' means, for a printed book, the title page itself,
fdl.texi(,97) plus such following pages as are needed to hold, legibly, the material
fdl.texi(,98) this License requires to appear in the title page.  For works in
fdl.texi(,99) formats which do not have any title page as such, ``Title Page'' means
fdl.texi(,100) the text near the most prominent appearance of the work's title,
fdl.texi(,101) preceding the beginning of the body of the text.
fdl.texi(,102) 
fdl.texi(,103) @item
fdl.texi(,104) VERBATIM COPYING
fdl.texi(,105) 
fdl.texi(,106) You may copy and distribute the Document in any medium, either
fdl.texi(,107) commercially or noncommercially, provided that this License, the
fdl.texi(,108) copyright notices, and the license notice saying this License applies
fdl.texi(,109) to the Document are reproduced in all copies, and that you add no other
fdl.texi(,110) conditions whatsoever to those of this License.  You may not use
fdl.texi(,111) technical measures to obstruct or control the reading or further
fdl.texi(,112) copying of the copies you make or distribute.  However, you may accept
fdl.texi(,113) compensation in exchange for copies.  If you distribute a large enough
fdl.texi(,114) number of copies you must also follow the conditions in section 3.
fdl.texi(,115) 
fdl.texi(,116) You may also lend copies, under the same conditions stated above, and
fdl.texi(,117) you may publicly display copies.
fdl.texi(,118) 
fdl.texi(,119) @item
fdl.texi(,120) COPYING IN QUANTITY
fdl.texi(,121) 
fdl.texi(,122) If you publish printed copies of the Document numbering more than 100,
fdl.texi(,123) and the Document's license notice requires Cover Texts, you must enclose
fdl.texi(,124) the copies in covers that carry, clearly and legibly, all these Cover
fdl.texi(,125) Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
fdl.texi(,126) the back cover.  Both covers must also clearly and legibly identify
fdl.texi(,127) you as the publisher of these copies.  The front cover must present
fdl.texi(,128) the full title with all words of the title equally prominent and
fdl.texi(,129) visible.  You may add other material on the covers in addition.
fdl.texi(,130) Copying with changes limited to the covers, as long as they preserve
fdl.texi(,131) the title of the Document and satisfy these conditions, can be treated
fdl.texi(,132) as verbatim copying in other respects.
fdl.texi(,133) 
fdl.texi(,134) If the required texts for either cover are too voluminous to fit
fdl.texi(,135) legibly, you should put the first ones listed (as many as fit
fdl.texi(,136) reasonably) on the actual cover, and continue the rest onto adjacent
fdl.texi(,137) pages.
fdl.texi(,138) 
fdl.texi(,139) If you publish or distribute Opaque copies of the Document numbering
fdl.texi(,140) more than 100, you must either include a machine-readable Transparent
fdl.texi(,141) copy along with each Opaque copy, or state in or with each Opaque copy
fdl.texi(,142) a publicly-accessible computer-network location containing a complete
fdl.texi(,143) Transparent copy of the Document, free of added material, which the
fdl.texi(,144) general network-using public has access to download anonymously at no
fdl.texi(,145) charge using public-standard network protocols.  If you use the latter
fdl.texi(,146) option, you must take reasonably prudent steps, when you begin
fdl.texi(,147) distribution of Opaque copies in quantity, to ensure that this
fdl.texi(,148) Transparent copy will remain thus accessible at the stated location
fdl.texi(,149) until at least one year after the last time you distribute an Opaque
fdl.texi(,150) copy (directly or through your agents or retailers) of that edition to
fdl.texi(,151) the public.
fdl.texi(,152) 
fdl.texi(,153) It is requested, but not required, that you contact the authors of the
fdl.texi(,154) Document well before redistributing any large number of copies, to give
fdl.texi(,155) them a chance to provide you with an updated version of the Document.
fdl.texi(,156) 
fdl.texi(,157) @item
fdl.texi(,158) MODIFICATIONS
fdl.texi(,159) 
fdl.texi(,160) You may copy and distribute a Modified Version of the Document under
fdl.texi(,161) the conditions of sections 2 and 3 above, provided that you release
fdl.texi(,162) the Modified Version under precisely this License, with the Modified
fdl.texi(,163) Version filling the role of the Document, thus licensing distribution
fdl.texi(,164) and modification of the Modified Version to whoever possesses a copy
fdl.texi(,165) of it.  In addition, you must do these things in the Modified Version:
fdl.texi(,166) 
fdl.texi(,167) @enumerate A
fdl.texi(,168) @item
fdl.texi(,169) Use in the Title Page (and on the covers, if any) a title distinct
fdl.texi(,170) from that of the Document, and from those of previous versions
fdl.texi(,171) (which should, if there were any, be listed in the History section
fdl.texi(,172) of the Document).  You may use the same title as a previous version
fdl.texi(,173) if the original publisher of that version gives permission.
fdl.texi(,174) 
fdl.texi(,175) @item
fdl.texi(,176) List on the Title Page, as authors, one or more persons or entities
fdl.texi(,177) responsible for authorship of the modifications in the Modified
fdl.texi(,178) Version, together with at least five of the principal authors of the
fdl.texi(,179) Document (all of its principal authors, if it has less than five).
fdl.texi(,180) 
fdl.texi(,181) @item
fdl.texi(,182) State on the Title page the name of the publisher of the
fdl.texi(,183) Modified Version, as the publisher.
fdl.texi(,184) 
fdl.texi(,185) @item
fdl.texi(,186) Preserve all the copyright notices of the Document.
fdl.texi(,187) 
fdl.texi(,188) @item
fdl.texi(,189) Add an appropriate copyright notice for your modifications
fdl.texi(,190) adjacent to the other copyright notices.
fdl.texi(,191) 
fdl.texi(,192) @item
fdl.texi(,193) Include, immediately after the copyright notices, a license notice
fdl.texi(,194) giving the public permission to use the Modified Version under the
fdl.texi(,195) terms of this License, in the form shown in the Addendum below.
fdl.texi(,196) 
fdl.texi(,197) @item
fdl.texi(,198) Preserve in that license notice the full lists of Invariant Sections
fdl.texi(,199) and required Cover Texts given in the Document's license notice.
fdl.texi(,200) 
fdl.texi(,201) @item
fdl.texi(,202) Include an unaltered copy of this License.
fdl.texi(,203) 
fdl.texi(,204) @item
fdl.texi(,205) Preserve the section entitled ``History'', and its title, and add to
fdl.texi(,206) it an item stating at least the title, year, new authors, and
fdl.texi(,207) publisher of the Modified Version as given on the Title Page.  If
fdl.texi(,208) there is no section entitled ``History'' in the Document, create one
fdl.texi(,209) stating the title, year, authors, and publisher of the Document as
fdl.texi(,210) given on its Title Page, then add an item describing the Modified
fdl.texi(,211) Version as stated in the previous sentence.
fdl.texi(,212) 
fdl.texi(,213) @item
fdl.texi(,214) Preserve the network location, if any, given in the Document for
fdl.texi(,215) public access to a Transparent copy of the Document, and likewise
fdl.texi(,216) the network locations given in the Document for previous versions
fdl.texi(,217) it was based on.  These may be placed in the ``History'' section.
fdl.texi(,218) You may omit a network location for a work that was published at
fdl.texi(,219) least four years before the Document itself, or if the original
fdl.texi(,220) publisher of the version it refers to gives permission.
fdl.texi(,221) 
fdl.texi(,222) @item
fdl.texi(,223) In any section entitled ``Acknowledgments'' or ``Dedications'',
fdl.texi(,224) preserve the section's title, and preserve in the section all the
fdl.texi(,225) substance and tone of each of the contributor acknowledgments
fdl.texi(,226) and/or dedications given therein.
fdl.texi(,227) 
fdl.texi(,228) @item
fdl.texi(,229) Preserve all the Invariant Sections of the Document,
fdl.texi(,230) unaltered in their text and in their titles.  Section numbers
fdl.texi(,231) or the equivalent are not considered part of the section titles.
fdl.texi(,232) 
fdl.texi(,233) @item
fdl.texi(,234) Delete any section entitled ``Endorsements''.  Such a section
fdl.texi(,235) may not be included in the Modified Version.
fdl.texi(,236) 
fdl.texi(,237) @item
fdl.texi(,238) Do not retitle any existing section as ``Endorsements''
fdl.texi(,239) or to conflict in title with any Invariant Section.
fdl.texi(,240) @end enumerate
fdl.texi(,241) 
fdl.texi(,242) If the Modified Version includes new front-matter sections or
fdl.texi(,243) appendices that qualify as Secondary Sections and contain no material
fdl.texi(,244) copied from the Document, you may at your option designate some or all
fdl.texi(,245) of these sections as invariant.  To do this, add their titles to the
fdl.texi(,246) list of Invariant Sections in the Modified Version's license notice.
fdl.texi(,247) These titles must be distinct from any other section titles.
fdl.texi(,248) 
fdl.texi(,249) You may add a section entitled ``Endorsements'', provided it contains
fdl.texi(,250) nothing but endorsements of your Modified Version by various
fdl.texi(,251) parties---for example, statements of peer review or that the text has
fdl.texi(,252) been approved by an organization as the authoritative definition of a
fdl.texi(,253) standard.
fdl.texi(,254) 
fdl.texi(,255) You may add a passage of up to five words as a Front-Cover Text, and a
fdl.texi(,256) passage of up to 25 words as a Back-Cover Text, to the end of the list
fdl.texi(,257) of Cover Texts in the Modified Version.  Only one passage of
fdl.texi(,258) Front-Cover Text and one of Back-Cover Text may be added by (or
fdl.texi(,259) through arrangements made by) any one entity.  If the Document already
fdl.texi(,260) includes a cover text for the same cover, previously added by you or
fdl.texi(,261) by arrangement made by the same entity you are acting on behalf of,
fdl.texi(,262) you may not add another; but you may replace the old one, on explicit
fdl.texi(,263) permission from the previous publisher that added the old one.
fdl.texi(,264) 
fdl.texi(,265) The author(s) and publisher(s) of the Document do not by this License
fdl.texi(,266) give permission to use their names for publicity for or to assert or
fdl.texi(,267) imply endorsement of any Modified Version.
fdl.texi(,268) 
fdl.texi(,269) @item
fdl.texi(,270) COMBINING DOCUMENTS
fdl.texi(,271) 
fdl.texi(,272) You may combine the Document with other documents released under this
fdl.texi(,273) License, under the terms defined in section 4 above for modified
fdl.texi(,274) versions, provided that you include in the combination all of the
fdl.texi(,275) Invariant Sections of all of the original documents, unmodified, and
fdl.texi(,276) list them all as Invariant Sections of your combined work in its
fdl.texi(,277) license notice.
fdl.texi(,278) 
fdl.texi(,279) The combined work need only contain one copy of this License, and
fdl.texi(,280) multiple identical Invariant Sections may be replaced with a single
fdl.texi(,281) copy.  If there are multiple Invariant Sections with the same name but
fdl.texi(,282) different contents, make the title of each such section unique by
fdl.texi(,283) adding at the end of it, in parentheses, the name of the original
fdl.texi(,284) author or publisher of that section if known, or else a unique number.
fdl.texi(,285) Make the same adjustment to the section titles in the list of
fdl.texi(,286) Invariant Sections in the license notice of the combined work.
fdl.texi(,287) 
fdl.texi(,288) In the combination, you must combine any sections entitled ``History''
fdl.texi(,289) in the various original documents, forming one section entitled
fdl.texi(,290) ``History''; likewise combine any sections entitled ``Acknowledgments'',
fdl.texi(,291) and any sections entitled ``Dedications''.  You must delete all sections
fdl.texi(,292) entitled ``Endorsements.''
fdl.texi(,293) 
fdl.texi(,294) @item
fdl.texi(,295) COLLECTIONS OF DOCUMENTS
fdl.texi(,296) 
fdl.texi(,297) You may make a collection consisting of the Document and other documents
fdl.texi(,298) released under this License, and replace the individual copies of this
fdl.texi(,299) License in the various documents with a single copy that is included in
fdl.texi(,300) the collection, provided that you follow the rules of this License for
fdl.texi(,301) verbatim copying of each of the documents in all other respects.
fdl.texi(,302) 
fdl.texi(,303) You may extract a single document from such a collection, and distribute
fdl.texi(,304) it individually under this License, provided you insert a copy of this
fdl.texi(,305) License into the extracted document, and follow this License in all
fdl.texi(,306) other respects regarding verbatim copying of that document.
fdl.texi(,307) 
fdl.texi(,308) @item
fdl.texi(,309) AGGREGATION WITH INDEPENDENT WORKS
fdl.texi(,310) 
fdl.texi(,311) A compilation of the Document or its derivatives with other separate
fdl.texi(,312) and independent documents or works, in or on a volume of a storage or
fdl.texi(,313) distribution medium, does not as a whole count as a Modified Version
fdl.texi(,314) of the Document, provided no compilation copyright is claimed for the
fdl.texi(,315) compilation.  Such a compilation is called an ``aggregate'', and this
fdl.texi(,316) License does not apply to the other self-contained works thus compiled
fdl.texi(,317) with the Document, on account of their being thus compiled, if they
fdl.texi(,318) are not themselves derivative works of the Document.
fdl.texi(,319) 
fdl.texi(,320) If the Cover Text requirement of section 3 is applicable to these
fdl.texi(,321) copies of the Document, then if the Document is less than one quarter
fdl.texi(,322) of the entire aggregate, the Document's Cover Texts may be placed on
fdl.texi(,323) covers that surround only the Document within the aggregate.
fdl.texi(,324) Otherwise they must appear on covers around the whole aggregate.
fdl.texi(,325) 
fdl.texi(,326) @item
fdl.texi(,327) TRANSLATION
fdl.texi(,328) 
fdl.texi(,329) Translation is considered a kind of modification, so you may
fdl.texi(,330) distribute translations of the Document under the terms of section 4.
fdl.texi(,331) Replacing Invariant Sections with translations requires special
fdl.texi(,332) permission from their copyright holders, but you may include
fdl.texi(,333) translations of some or all Invariant Sections in addition to the
fdl.texi(,334) original versions of these Invariant Sections.  You may include a
fdl.texi(,335) translation of this License provided that you also include the
fdl.texi(,336) original English version of this License.  In case of a disagreement
fdl.texi(,337) between the translation and the original English version of this
fdl.texi(,338) License, the original English version will prevail.
fdl.texi(,339) 
fdl.texi(,340) @item
fdl.texi(,341) TERMINATION
fdl.texi(,342) 
fdl.texi(,343) You may not copy, modify, sublicense, or distribute the Document except
fdl.texi(,344) as expressly provided for under this License.  Any other attempt to
fdl.texi(,345) copy, modify, sublicense or distribute the Document is void, and will
fdl.texi(,346) automatically terminate your rights under this License.  However,
fdl.texi(,347) parties who have received copies, or rights, from you under this
fdl.texi(,348) License will not have their licenses terminated so long as such
fdl.texi(,349) parties remain in full compliance.
fdl.texi(,350) 
fdl.texi(,351) @item
fdl.texi(,352) FUTURE REVISIONS OF THIS LICENSE
fdl.texi(,353) 
fdl.texi(,354) The Free Software Foundation may publish new, revised versions
fdl.texi(,355) of the GNU Free Documentation License from time to time.  Such new
fdl.texi(,356) versions will be similar in spirit to the present version, but may
fdl.texi(,357) differ in detail to address new problems or concerns.  See
fdl.texi(,358) @uref{http://www.gnu.org/copyleft/}.
fdl.texi(,359) 
fdl.texi(,360) Each version of the License is given a distinguishing version number.
fdl.texi(,361) If the Document specifies that a particular numbered version of this
fdl.texi(,362) License ``or any later version'' applies to it, you have the option of
fdl.texi(,363) following the terms and conditions either of that specified version or
fdl.texi(,364) of any later version that has been published (not as a draft) by the
fdl.texi(,365) Free Software Foundation.  If the Document does not specify a version
fdl.texi(,366) number of this License, you may choose any version ever published (not
fdl.texi(,367) as a draft) by the Free Software Foundation.
fdl.texi(,368) @end enumerate
fdl.texi(,369) 
fdl.texi(,370) @page
fdl.texi(,371) @appendixsubsec ADDENDUM: How to use this License for your documents
fdl.texi(,372) 
fdl.texi(,373) To use this License in a document you have written, include a copy of
fdl.texi(,374) the License in the document and put the following copyright and
fdl.texi(,375) license notices just after the title page:
fdl.texi(,376) 
fdl.texi(,377) @smallexample
fdl.texi(,378) @group
fdl.texi(,379)   Copyright (C)  @var{year}  @var{your name}.
fdl.texi(,380)   Permission is granted to copy, distribute and/or modify this document
fdl.texi(,381)   under the terms of the GNU Free Documentation License, Version 1.1
fdl.texi(,382)   or any later version published by the Free Software Foundation;
fdl.texi(,383)   with the Invariant Sections being @var{list their titles}, with the
fdl.texi(,384)   Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
fdl.texi(,385)   A copy of the license is included in the section entitled ``GNU
fdl.texi(,386)   Free Documentation License''.
fdl.texi(,387) @end group
fdl.texi(,388) @end smallexample
fdl.texi(,389) 
fdl.texi(,390) If you have no Invariant Sections, write ``with no Invariant Sections''
fdl.texi(,391) instead of saying which ones are invariant.  If you have no
fdl.texi(,392) Front-Cover Texts, write ``no Front-Cover Texts'' instead of
fdl.texi(,393) ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
fdl.texi(,394) 
fdl.texi(,395) If your document contains nontrivial examples of program code, we
fdl.texi(,396) recommend releasing these examples in parallel under your choice of
fdl.texi(,397) free software license, such as the GNU General Public License,
fdl.texi(,398) to permit their use in free software.
fdl.texi(,399) 
fdl.texi(,400) @c Local Variables:
fdl.texi(,401) @c ispell-local-pdict: "ispell-dict"
fdl.texi(,402) @c End:
fdl.texi(,403) 
texinfo.texi(,18736) 
texinfo.texi(,18737) 
texinfo.texi(,18738) @node Command and Variable Index
texinfo.texi(,18739) @unnumbered Command and Variable Index
texinfo.texi(,18740) 
texinfo.texi(,18741) This is an alphabetical list of all the @@-commands, assorted Emacs Lisp
texinfo.texi(,18742) functions, and several variables.  To make the list easier to use, the
texinfo.texi(,18743) commands are listed without their preceding @samp{@@}.@refill
texinfo.texi(,18744) 
texinfo.texi(,18745) @printindex fn
texinfo.texi(,18746) 
texinfo.texi(,18747) 
texinfo.texi(,18748) @node Concept Index
texinfo.texi(,18749) @unnumbered Concept Index
texinfo.texi(,18750) 
texinfo.texi(,18751) @printindex cp
texinfo.texi(,18752) 
texinfo.texi(,18753) 
texinfo.texi(,18754) @bye
